G3N Common Contract

Appearance

Changelog ​

Documentation changes, newest first. Each entry references the build or commit that introduced the change.

Round 5 — RTV Bucket Selection, DDB Centralization & Drift Fixes (2026-04-14) ​

Added ​

  • RTV stock bucket selection: from_bucket field on PCM RtvLine and ICS adjustment/create for bucket-targeted deductions (available, damaged, quarantine, consignment, reserved, committed, in_transit). PCM→ICS cross-service integration on rtv/receive (best-effort).
  • DDB entity_type centralization: shared packages/ddb-fields constants + 19 per-service fields.ts files. ~1000 raw entity_type string literals replaced with compile-safe ENTITY.* references across 195+ handler files.
  • entity_type expansion: added to UAS (7 types), USM (4), OPS (5), MRS (4), OFM orgCreate (3) records.

Fixed ​

  • ICS updated_at dual-write: backward-compatible migration from last_updated to updated_at. All stock position writes now set both fields. Reads prefer updated_at with last_updated fallback.
  • USM _utc timestamp suffix: dual-write migration. expires_at/doomed_at/archive_due_at now written alongside legacy _utc names. auth-direct reads prefer canonical names with _utc fallback.
  • ICS dual-write completeness: fixed 2 missed handlers (bulkImport, transfer) that wrote last_updated without updated_at.
  • Test lane promotion: ics.adjustment-from-bucket and pcm.rtv-from-bucket tests added to required-core lane.

Round 4 — Contract Enforcement, Audit Remediation & Consistency (2026-03-29 → 2026-04-12) ​

Added ​

  • AJV request validation across 17/20 services — strict contract enforcement with schema-level request body validation.
  • POS fraud detection patterns in SCM (customer fraud assessment, transaction velocity checks).
  • Recalculate endpoints: POST /pcm/po/status/recalculate, POST /scm/special-order/recalculate, POST /scm/layaway/recalculate, POST /crm/loyalty/recalculate, POST /crm/loyalty/preview.
  • UCP + UTL test expansion: 212 new tests across 13 files (UCP ratio 4.8:1 → 1.04:1, UTL 3.1:1 → 1.57:1).
  • CORS origin allowlist: dynamic origin validation in Lambda (replaces Allow-Origin: *).
  • React ErrorBoundary in webapp (App root + InventoryApp).
  • Policies & Limits page (/common/policies.html): hardcoded limits and configurable policies reference.
  • VisualGrid playbooks page added to VitePress nav.

Fixed ​

  • OPS vacuum MRS bug: vacuumOrgWorker now iterates 256 hex buckets for MRS (gsi1Strategy=bucketed_256). Previously silently missed ALL MRS records.
  • UCP checkoutComplete: ConditionExpression guard on final transition to 'completed' (prevents concurrent completion race).
  • RECAP drift in 5 services: PPM route count, RBS route count + OFM dependency, SCM ICS dependency, IPM auth claim, MRS GSI_TAG clarification.
  • CONTINUITY.md: 6 stale data points corrected (commit hash, test counts, publish tuple, deploy count, verification commands).
  • ROADMAP.md: Phases 1-3 marked DONE.

Changed ​

  • Core test lane: 168 → 189 suites (21 test files promoted from repo lane). 2705 → 2985 assertions.
  • SCM CDK: PVM_INTERNAL_SECRET env var wired for per-receiver secret model.

Round 3 — Documentation Quality Overhaul ​

Commit: (current session)

Added ​

  • Event Catalog (/common/event-catalog.html): browsable reference of all events emitted across 16 services, generated from internal-docs/event-schemas/*.schema.json.
  • Pagination Walkthrough in /common/pagination-filtering.html: curl page-by-page demo, Node.js and Python drain-all-pages helpers using PVM /division as example.
  • Service abbreviation legend in /common/glossary.html: 16-row table mapping abbreviations to full service names.
  • Service subtitles: each service index.md now shows an italic abbreviation line (e.g., ICS — Inventory Control Service).
  • Auth placement callouts: ::: warning on headers-identity.md and minimum-viable-flow.md; ::: danger on USM and UTL surfaces pages highlighting body-auth exceptions.
  • Mermaid entity diagrams in /common/domain-models.html: service dependency flow (graph TD) + 4 ER diagrams (Product, Sales, Inventory, Procurement) sourced from OpenAPI component schemas.
  • Changelog page (this page) with nav/sidebar links.
  • Scalar API Explorer per service: interactive OpenAPI explorer at /<service>/explorer.html.
  • Operator guidance in MVF: warning callout at step 3 about org-verification gate, aws lambda invoke command, OFM surfaces link.

Fixed ​

  • Python SDK syntax: replaced print() with dict literal argument with an f-string in sdk-snippets.md and minimum-viable-flow-python.py.

Changed ​

  • Response samples in calls.md: generate-calls-docs.mjs now derives response data from OpenAPI response schemas instead of showing "data": { "note": "See Envelope" }. All 16 calls.md files regenerated.
  • Pagefind indexing: generated calls.md pages now include data-pagefind-meta attributes for service name and endpoint type.

Round 2 — Code-vs-Docs Gap Remediation ​

Commits: fcd66fb4, 2c51f3fe

Changed ​

  • Remediated 38 code-vs-docs and MCP gaps across all services.
  • Remaining round 2 gaps (steps 3a-3m, 4k-4l) resolved.

Round 1 — Aggressive Test Expansion ​

Commit: aa7286b4

Added ​

  • 24 new test suites with 318 tests across 8 services.
  • Full handler and event FSM coverage for ICS, SCM, PCM, PPM, CRM, Influencer, Accounting, and RBS.

Initial Documentation Build ​

Added ​

  • 16 service doc sites with index, surfaces, calls, state-machines, and MCP protocol pages.
  • Common doc site with integration guides, schemas, error tags, and contract references.
  • Story and QA doc sites.
  • Automated build pipeline (scripts/build-docs-dist.js) with symmetry validation and link checking.