Document candidates and interpretation
A document candidate is a reviewable interpretation of one attachment occurrence in a preserved source version. Preserving or extracting a document does not make its contents an accepted delivery, approved invoice or received material. Human classification and routing create those business relationships through separate, version-checked operations.
Records and processing stages
Section titled “Records and processing stages”| Stage | Representative record | Meaning |
|---|---|---|
| Source projection | Mail archive item and binding | Company/source identity, original version, attachment metadata and coverage |
| Protected original copy | mail_original_copies |
Verified, encrypted bytes for the matching source/version |
| Extraction occurrence | Delivery-note source document and attachment ordinal/hash | The concrete source part, preserved across replay |
| Review candidate | document_candidates |
Suggested type/fields/evidence, source hash, candidate version and review status |
| Technical job | mail_intake_jobs |
Pending, leased, retried or completed processing; not business approval |
| Human decision | Candidate event and routed domain record | Actor, request identity and checked source/version; routing remains distinct from later approval |
The attachment’s company, source occurrence, original version and ordinal preserve identity even when another occurrence contains identical bytes. Replay must not reset a human decision to an unclassified import. Source preservation and original coverage are prerequisites for trustworthy review, not substitutes for it.
flowchart LR Source[Preserved source version] --> Copy[Verified encrypted copy] Copy --> Candidate[Queued candidate] Candidate --> AI[Optional leased AI interpretation] AI --> Review[Needs human review] Candidate --> Manual[Authorized manual classification] Review --> Confirm[Version and hash checked confirmation] Manual --> Confirm Confirm --> Route[Explicit domain routing] Route --> Domain[Delivery or supplier-invoice workflow]
Permissions and decisions
Section titled “Permissions and decisions”Document inbox reads, technical operation and human review have separate
document_intake:read, document_intake:operate and document_intake:review
contracts. The API resolves current actor/company and passes the affected resource
to the owning service/RPC. MCP technical work can synchronize or enqueue a job;
that effect does not confirm the extracted business fields.
Classification and routing carry candidate ID, expected version/status, source SHA-256, actor and request key. The database compares them under its operation’s lock and records a candidate event. Reusing a request key for a different command is a conflict. A stale review must be refreshed; silently applying the operator’s old decision to a changed source is unsafe.
Current manual classification accepts eligible queued or needs-review candidates. The queued path requires a verified original copy. It consumes no model budget and completes pending interpretation work, revoking an in-flight lease so a late response cannot overwrite the human decision. This is an explicit supported path, not a reason to weaken source verification when AI is unavailable.
Routing and transaction limits
Section titled “Routing and transaction limits”A confirmed delivery-note classification can route into the delivery workflow. The supplier document remains a supplier claim; material receipt and allocation need their own confirmation. A supplier-invoice candidate must be confirmed, supported and current before routing into the purchase-invoice workflow. Settlement owns accounting and payment approval.
The invoice service can copy verified source attachments to application Storage before its routing RPC. That object transfer and the database transaction are not one atomic action. A committed request replay is detected first and goes back to the RPC without another source read/copy; a new uncertain failure still needs operation-specific recovery. Do not promise universal orphan cleanup.
Example and recovery
Section titled “Example and recovery”Synthetic Candidate A is queued with a verified original but its daily AI budget is exhausted. An authorized reviewer can inspect the source and classify it manually using its current version/hash. If another reviewer changes that candidate first, the stale command is refused. The original hash must not be replaced with another attachment’s hash merely to make confirmation succeed.
For an unavailable original, check verification status before retrying interpretation. For a failed route, inspect the existing request event and resulting domain record before creating another invoice. Candidate download verifies the protected copy, extracts the expected part and requires its audit operation before returning bytes. Local synthetic backend tests and database-role tests have different coverage; the PR records actual executions. No real mailbox, financial approval or provider write is required to establish this documentation’s source-grounded contract.