Last reviewed: 2026-07-30

Accounting Import Candidate Contract

Canonical objects: - AccountingImportIdentityDecision - AccountingImportAcceptedCandidateIdentity - AccountingImportIdentifiedCandidate

Purpose: - give every normalized transaction group explicit provider-agnostic source identity, replay, conflict, duplicate-review, and change-relationship behavior before workflow records are created; - keep transaction identity distinct from file replay, physical rows, workflow staging, and ledger truth.

Candidate granularity: - one identity evaluation applies to one normalized transaction group; - the source group id correlates rows only within the import and is not durable source-event identity; - a later workflow may combine evaluated candidates only under its own accepted batch contract.

Required identity-decision fields: - source group id - source object type - external object id - external event or version id - idempotency key - change type - decision evidence reference

Accepted-candidate identity fields: - import run id and source group id - company id and source system - source object type, external object id, and external event or version id - idempotency key and change type - normalized meaning hash - durable owning-workflow record id - human-visible owning-workflow reference

Optional identity-decision fields: - related-original source object type, external object id, and external event or version id as one complete identity

Identified-candidate provenance: - import run id - company id - source system - verified currency when the import profile and reviewed intake establish one

The identified candidate must carry this accepted import context forward so a workflow can validate company, source, and currency without reconstructing them from file names, source references, descriptions, or provider fields.

Allowed change types: - original - correction - reversal

Allowed identity outcomes: - ready_for_workflow - idempotent_replay - held_for_routing - held_for_identity - held_for_conflict - held_for_duplicate_meaning - held_for_change_relationship - held_for_correction_workflow

Identity and replay rules: - identity is scoped by company and source system; - exact transaction replay requires the same source object/event identity, the same idempotency key, and the same normalized meaning hash; - an exact replay links the previously accepted workflow record and does not authorize creation of a duplicate workflow record; - the owning-workflow record id is the durable link used for persistence and recovery; its human-visible reference is retained for review and display but is not durable identity; - reuse of either source event identity or idempotency key with a different or partially mismatched identity is held as a conflict; - the same normalized meaning under different source identities is held for duplicate review and is not silently merged; - coincidentally equal amounts do not by themselves establish replay or duplicate meaning; - missing, duplicate, or unknown identity decisions remain visible and held; - file name, file hash, source group id, physical row number, description, journal code, subaccount, external reference, amount alone, and redundant source fields must not become durable transaction identity.

Change rules: - an original candidate must not identify a related original; - a correction or reversal requires a complete explicit related-original identity; - the related identity must resolve to an accepted original in the same company and source-system scope; - correction and reversal candidates remain held for the correction workflow until their related original resolves; after resolution they may enter the Accounting Correction workflow but remain non-posting until that workflow prepares, reviews, and authorizes them; - change type and the Correction/Reversal workflow route must agree. - initial machine and file correction intake targets an accepted original event, not a prior correction; - the accepted original must resolve to the same posted journal entry targeted by the Accounting Correction workflow; and - resolving change identity or relationship does not itself authorize a reversal or adjustment posting.

Normalized meaning hash: - the hash schema is accounting-import-meaning-v1; - the value is lowercase hexadecimal SHA-256 over a deterministic, length-delimited UTF-8 representation; - included fields are workflow route, posting date, verified currency, total debit, total credit, explicit change type, related-original identity, and the sorted normalized external lines' account code, debit, and credit; - excluded fields are transaction identity, idempotency key, import-run and source-group identity, row order and row number, source reference, descriptions, journals, subaccounts, redundant signed amount, and redundant source account; - line ordering, decimal scale, surrounding text whitespace, and currency case do not change an otherwise equivalent hash; - the meaning hash supports replay, conflict, and duplicate review. It is not source identity, evidence identity, a posting request, or formal report truth.

Persistence boundary: - identity evaluation is in-memory review behavior; - ready_for_workflow does not create a Source Document, Summary Accounting batch, preview, journal entry, or ledger effect; - an accepted candidate identity is persisted only after its owning workflow record exists; - a retry after an interrupted link write must reuse the existing owning workflow record and complete the missing accepted-candidate link rather than create a duplicate; - accepted identity and workflow links are company-scoped and immutable; a conflicting source identity or idempotency reuse must not overwrite them. - a correction candidate accepted by the Accounting Correction workflow links to that durable correction record as its owning-workflow record.

Related truth: - accounting-import-run.contract.md - summary-accounting-batch.contract.md - ../accounting/summary-accounting.md - ../decisions/accepted/0007-provider-agnostic-import-boundaries.md - ../decisions/accepted/0022-reviewable-accounting-file-intake.md - accounting-correction.contract.md - company-conversion-run.contract.md