--- id: CAP-COM-FUL-020 title: Import Commerce history and reconcile source records feature: FEAT-COM-FUL-05 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-INV-026 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: [] purpose: >- Implementation staff load prepared migration records and verify their resulting identities. outcomes: - >- Imported Commerce history supplies the migrating workspace's opening records. - Source identities support reconciliation with original historical records. concepts: - CON-COM-FUL-005 - CON-COM-FUL-001 actors: - ACT-COM-009 surfaces: - api - job preconditions: [] postconditions: [] permissions: - key: commerce.inventory.bulk where_checked: api scope: tenant - key: commerce.inventory.update where_checked: api scope: tenant rules: - id: BR-CAP-COM-FUL-020-01 proved_by: [] statement: >- Migration serves twelve collections with eleven job operations each: stores, ordering profiles, orders, promotions, redemptions, categories, listings, merchandise option sets, merchandise, warehouses, locations and stock items. kind: policy enforced_at: - api must_prove: false provenance: test source: >- services-commerce:modules/data-operations/tests/unit/operations/data-operations.spec.js#serves the twelve object types of the migration origin: none - id: BR-CAP-COM-FUL-020-02 proved_by: [ATS-COM-FUL-020-01, TST-COM-FUL-003, TST-COM-FUL-013, TST-COM-FUL-014] statement: >- Submission accepts up to 500 prepared records in validate or apply mode with insert, upsert or update semantics, rejects patch selections, and requires a source key or identity per record and a source system for keyed records. kind: validation enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/unit/api/data-jobs-schemas.spec.js#refuses a selection with a patch: no Commerce operation changes records in place by id origin: none - id: BR-CAP-COM-FUL-020-03 proved_by: [ATS-COM-FUL-020-01, TST-COM-FUL-003, TST-COM-FUL-013, TST-COM-FUL-014] statement: >- Data jobs require collection bulk authority and recheck record-write authority, rejecting read-only job callers and portal members. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#refuses a principal holding the read key alone on every data-job route of the collection, 403 permission_missing origin: none - id: BR-CAP-COM-FUL-020-04 proved_by: [ATS-COM-FUL-020-02, TST-COM-FUL-003, TST-COM-FUL-004] statement: >- Repeating an identical submission under its idempotency key returns the existing job marked reused. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers a second submission of the same body under the same Idempotency-Key with the same job, reused origin: none - id: BR-CAP-COM-FUL-020-05 proved_by: [ATS-COM-FUL-020-02, TST-COM-FUL-003, TST-COM-FUL-004] statement: >- Validation records impact without writes, and apply rejects an absent or mismatched validation-impact digest. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#refuses an apply that echoes a digest other than the validation recorded, impact_digest_mismatch origin: none - id: BR-CAP-COM-FUL-020-06 proved_by: [ATS-COM-FUL-020-03, TST-COM-FUL-004] statement: >- Bulk-key holders can inspect all jobs in their collection and other callers only their own, while cross-collection job reads and mismatched collection submissions are rejected. kind: permission enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#lists only the jobs a caller submitted themselves when they lack the collection’s bulk key origin: none - id: BR-CAP-COM-FUL-020-07 proved_by: [ATS-COM-FUL-020-04, TST-COM-FUL-003, TST-COM-FUL-004] statement: >- Initial import requires an implementation workspace in loading state, where job routes remain available and ordinary routes are closed. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#is refused for a tenant that is live origin: none - id: BR-CAP-COM-FUL-020-08 proved_by: [ATS-COM-FUL-020-05, TST-COM-FUL-011] statement: >- Batch execution reloads the submitter's permissions, fails the job if authority was revoked, avoids duplicate application on redelivery and dead-letters unreadable messages. kind: permission enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/queue/data-job-worker.integration.spec.js#acknowledges the message as access_revoked and fails the job whole with that code, nothing left on the queue origin: none - id: BR-CAP-COM-FUL-020-09 proved_by: [ATS-COM-FUL-020-06, TST-COM-FUL-005, TST-COM-FUL-015] statement: >- Missing references defer records with the dependency field identified, typed failures retain their code, duplicate errors disclose constraint names rather than colliding values, and dropped connections are transient. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/unit/operations/error-classification.spec.js#blocks an item whose reference nobody has loaded, on the engine’s dependency_missing, at the field that names it origin: none - id: BR-CAP-COM-FUL-020-10 proved_by: [ATS-COM-FUL-020-07, TST-COM-FUL-003, TST-COM-FUL-006] statement: >- Readback accepts up to 100 source keys, returns imported shapes and missing-key lists and excludes records from other workspaces. kind: permission enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers the key missing before the apply, and the store as its load carried it once the job is applied and run origin: none - id: BR-CAP-COM-FUL-020-11 proved_by: [ATS-COM-FUL-002-15, ATS-COM-FUL-004-13, ATS-COM-FUL-020-08, ATS-COM-FUL-020-11, TST-COM-FUL-009] statement: >- Migrated orders preserve original numbers, arrive accepted, billed and marked migrated, create completed or blocked item-line obligations and defer unresolved invoice linking for a later same-key relink. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/operations/order-import.integration.spec.js#creates one obligation per item line in its final state: completed and open for the fulfilled line, blocked for the other origin: >- D-C-04 (build decision, not a product ruling): services-commerce:docs/migrations/data-operations/README.md - id: BR-CAP-COM-FUL-020-12 proved_by: [ATS-COM-FUL-016-08, ATS-COM-FUL-017-12, ATS-COM-FUL-020-09, ATS-COM-FUL-020-10, TST-COM-FUL-007] statement: >- Migrated stock opening uses count-correction and damage ledger entries instead of direct balance writes, rejecting repeat keys and inactive destinations. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/operations/inventory-import.integration.spec.js#opens the mug’s item through the ledger: a count correction of twelve and a damage of two, so the trigger holds ten available origin: none - id: BR-CAP-COM-FUL-020-13 proved_by: [] statement: >- Pause, resume, cancellation and retry take effect between batches, and cancellation preserves and reports already committed records. kind: lifecycle enforced_at: - api - service must_prove: false provenance: observed source: >- services-commerce:modules/data-operations/aws/api/data-operations.routes.ts:dataJobRoutesOf origin: none scenarios: - id: SC-CAP-COM-FUL-020-01 given: A prepared store import has passed validation. when: Apply its recorded impact digest and execute the queued batch. then: >- The created store is available through its original source key in imported shape. provenance: test source: >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers the key missing before the apply, and the store as its load carried it once the job is applied and run edge_cases: - id: SC-CAP-COM-FUL-020-02 given: A listing references a product not yet imported. when: Execute its import batch. then: The item waits on the identified missing dependency without being written. provenance: test source: >- services-commerce:modules/data-operations/tests/integration/services/operations/catalog-import.integration.spec.js#blocks a listing whose product nothing has loaded as dependency_missing, naming the product source key, and writes nothing constraints: [] depends_on: [] related: - CAP-COM-FUL-017 journeys: - JNY-COM-FUL-006 open_questions: - OQ-COM-FUL-003 evidence: - repository: services-commerce sources: - >- services-commerce:modules/data-operations/tests/unit/operations/data-operations.spec.js#serves the twelve object types of the migration - >- services-commerce:modules/data-operations/tests/unit/api/data-jobs-schemas.spec.js#refuses a selection with a patch: no Commerce operation changes records in place by id - >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#refuses a principal holding the read key alone on every data-job route of the collection, 403 permission_missing - >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers a second submission of the same body under the same Idempotency-Key with the same job, reused - >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#refuses an apply that echoes a digest other than the validation recorded, impact_digest_mismatch - >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#lists only the jobs a caller submitted themselves when they lack the collection’s bulk key - >- services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#is refused for a tenant that is live - >- services-commerce:modules/data-operations/tests/integration/services/queue/data-job-worker.integration.spec.js#acknowledges the message as access_revoked and fails the job whole with that code, nothing left on the queue - >- services-commerce:modules/data-operations/tests/unit/operations/error-classification.spec.js#blocks an item whose reference nobody has loaded, on the engine’s dependency_missing, at the field that names it - >- services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers the key missing before the apply, and the store as its load carried it once the job is applied and run - >- services-commerce:modules/data-operations/tests/integration/services/operations/order-import.integration.spec.js#creates one obligation per item line in its final state: completed and open for the fulfilled line, blocked for the other - >- services-commerce:modules/data-operations/tests/integration/services/operations/inventory-import.integration.spec.js#opens the mug’s item through the ledger: a count correction of twelve and a damage of two, so the trigger holds ten available - >- services-commerce:modules/data-operations/aws/api/data-operations.routes.ts:dataJobRoutesOf controls: [TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-CRY-001, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-007, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-FUL-05-01, FAS-COM-FUL-05-02, FAS-COM-FUL-05-03, FAS-COM-FUL-05-04, FAS-COM-FUL-05-05] suites: [TST-COM-FUL-003, TST-COM-FUL-004, TST-COM-FUL-005, TST-COM-FUL-006, TST-COM-FUL-007, TST-COM-FUL-009, TST-COM-FUL-011, TST-COM-FUL-013, TST-COM-FUL-014, TST-COM-FUL-015] --- # Import Commerce history and reconcile source records ## Purpose Implementation staff load prepared migration records and verify their resulting identities. ## How It Works Staff submit prepared records to the collection's data-job workflow. Validation describes the impact before application is requested. Batches run with the submitter's current authority and retain their committed results. Missing references can wait for related records to arrive. Source-key readback lets staff reconcile the imported shape against the original records. Migrated orders and stock use their own opening behavior rather than ordinary live selling. The product should settle whether each import belongs with its record-owning module before design begins. ## Relationships - Keep stock movements and transfers accountable supplies or consumes related delivery records.