G3N Common Contract

Appearance

Comments & Inbox ​

Status: INTERIM (AS-BUILT partial; implemented in ICS/SCM/PCM/CRM/PPM/Influencer/Accounting with org-wide search; standardization ongoing). Current services may support comments where documented.

Comments and threads (business rules) ​

  • Every org-scoped record supports comments, replies (threads), and attachments.
  • Comments include a caption and body; attachments are treated as part of the body.
  • Any member can read and add comments; only the author can edit.
  • Edits preserve revision history with actor and timestamp.
  • Comments are searchable org-wide by default, with filters (record type, user, date range, hashtag).
  • Org-wide full-text search uses a dedicated search plane (not the operational data store); results are best-effort and remain org-scoped. Search plane is currently parked; endpoints return 501 when not configured (see PLAYBOOK.md section 3 for re-enablement).
  • Prototype search endpoints:
    • POST /ics/search/comments (filters: q, services, target_type, target_id, user_guid, status, hashtag, date range)
    • POST /ics/search/inbox (filters: q, services, team_guid or org_wide, status, state, record_type, record_id, priority, date range)
  • Hashtags and user/team references are supported.
  • Retention is policy-driven; comments linked to financial or compliance records must be retained at least 24 months.

Attachment handling (canonical) ​

  • Attachments are stored in MRS containers and referenced by record_id.
  • Comments store attachment metadata (filename, content_type, size_bytes, checksum/etag).
  • Download flow: if inline_ok=true and size is small, the attachment may be returned inline; otherwise a presigned URL is returned.
  • Attachments follow retention rules and may be scrubbed/expired; when deleted, comment responses omit download URLs and include a deletion timestamp.

See https://doc.g3nretailstack.com/mrs/surfaces/ for upload/download mechanics.

Service exceptions and alignment (interim) ​

  • Standard: comments are editable with revision history.
  • PVM (current behavior): comments are create-only and immutable. This is a documented exception until migration.
  • Migration path: PVM will adopt the standard editable model with revision history. Migration expectations:
    • Existing comments map to revision=0 with original author/timestamp.
    • Edits become revision entries linked to the original comment id.
    • UI/SDKs should surface revision history and preserve the original content for audit.
    • During migration, clients should model edits as a new comment referencing the original.

Inbox notifications (business rules) ​

  • Team-based notifications are visible to all members of the team.
  • Status: inbox or archived.
  • State: pending, completed, or deferred.
  • Rules:
    • pending is allowed only in inbox.
    • archived requires completed, or deferred first.
  • Any team member can update state/status within the rules.
  • Notifications include act_by date/time and priority (low|medium|high|show_stopper).
  • Notifications support the same comment/thread model as records.
  • Inbox records follow operational retention baselines (24 months minimum) unless policy extends.

Cross-service inbox ​

  • ICS/SCM/PCM/CRM/PPM/Influencer/Accounting emit inbox notifications to a shared search plane.
  • Search endpoints:
    • POST /ics/search/inbox (org-scoped, with filters by service, team, status/state, priority, date range).
  • Anti-enumeration applies: non-associated callers receive 404 not-found.

Auditability ​

  • All comment and inbox actions emit events for audit and billing attribution.