Load and Reconcile Record Files

Purpose

A repeated source file should reconcile records without duplicating the register. Data jobs validate the expected impact before applying normal record writes.

How It Works

An authorized submitter provides record or relationship lines identified by source keys. Validation resolves existing targets and checks the proposed writes. It reports line problems before applying records. The caller applies the job using the validated impact. Record lines change only differing supplied properties through normal storage rules. Relationship correction lines currently replace their complete attributes, which can erase omitted history. Job controls support recovery and repetition, while result access remains with the submitter.

Relationships

The Data Job Engine owns execution and job controls. Custom-record and relationship stores provide the writes and validation contracts.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: A repeated source file should reconcile records without duplicating the register.Relationship correction lines currently replace their complete attributes, which can erase omitted history.
Surfaces: jobapi
Preconditions: Object properties are configured before loading, and object and relationship types are active.
Intent sources: services-platform:docs/milestones/PLAT-M7-custom-record-loads-reports-events.md#Scope (Proposed; no plan)services-platform:docs/milestones/plans/PLAT-M6-plan.md#2. Scope (loading links from a file, built)

Controls

22 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.associations.create`	api	tenant
`platform.associations.update`	service	tenant
`platform.custom-records.create`	service	record
`platform.custom-records.update`	service	record

Business Rules

8 rules, 7 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Producer keys identify load lines within their object and become external identifiers; new crosswalk keys can adopt matching records, known keys patch only differing supplied properties and identical reloads make no changes. proved by `ATS-PFM-MTD-016-01`, `TST-PFM-MTD-135`	policy	service	documented services-platform:docs/custom-objects.md#Import, export and reset
`02`must prove Proposed	Preflight validates object state, property contracts, references, requirements, conditions, uniqueness within storage and the file, and caller reach, reporting rejected lines and properties without values. proved by `ATS-PFM-MTD-016-02`, `TST-PFM-MTD-134`	validation	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0400.spec.js#step 3: the rejections name each bad line and its property, never a value or an error class
`03`must prove Proposed	Validation computes impact without writing records, and apply refuses a mismatched impact digest while keeping the job validated. proved by `ATS-PFM-MTD-016-03`, `TST-PFM-MTD-134`	validation	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0400.spec.js#step 4: an apply with a stale digest is refused 409 impact_digest_mismatch and the job stays validated
`04`must prove Proposed	Loaded records use normal write behaviour for numbering, names, unique values, assets and audits and reject archived targets until restoration. proved by `ATS-PFM-MTD-016-04`, `ATS-PFM-MTD-016-08`, `TST-PFM-MTD-134`	invariant	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0400.spec.js#step 6: every created boat reads back as the file said, and the id refused at step 2 named no record
`05`must prove Proposed	Link loads resolve type and endpoint keys or identities, validate type state, endpoint kind, dates, attributes and cardinality, and refuse changes to known link endpoints before applying. proved by `ATS-PFM-MTD-016-05`, `ATS-PFM-MTD-016-08`, `TST-PFM-MTD-136`	validation	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0402.spec.js#step 9: OWN-2 naming another boat is refused because endpoints never change, and with its own endpoints its notes update
`06`must prove Proposed	A known-link correction replaces all link attributes, clears omitted dates, position and notes and reopens an ended link when its end date is omitted, without warning. proved by `ATS-PFM-MTD-016-06`, `TST-PFM-MTD-136`	policy	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0402.spec.js#step 6: a CRW-1 line with only isPrimary replaces the association and clears its dates, position and notes, silently
`07`must prove Proposed	Link-load submission requires create permission and each line needs create or update according to whether it is new, while results remain limited to the submitter and workspace. proved by `ATS-PFM-MTD-016-07`, `TST-PFM-MTD-137`	permission	api, service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0404.spec.js#step 5: a clerk with the create key only has the known key refused as not found and the new key created
`08` Proposed	Load controls support pause, resume, cancel and retry, and resubmission of an idempotency key returns its original job.	lifecycle	service	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0400.spec.js#step 9: the list is newest first with the three jobs, and a resent idempotent request answers the first job

Scenarios

Id	Given	When	Then	Provenance
`01`	A club has source files for builders and boats.	Validate the files and apply their accepted impact.	Validation reports rejected lines without writing records, and application creates the valid boats and their stated information.	test services-platform:tests/acceptance/custom-objects/journeys/data-operations/CO-ACC-0400.spec.js#step 5: applies with the digest; the job completes with rejections, writing three lines and rejecting five

Planning

Implementation

Load and Reconcile Record Files ​

Purpose ​

How It Works ​

Relationships ​