govoplan-core/docs/RECORDS_FILING_CONTRACT.md

Records Filing Contract

Core exposes a small provider-neutral contract for filing exact source revisions into an institutional record. Core does not own records semantics, source-object authorization, or source bytes. govoplan-records owns filing orchestration and chronology; each source module owns resolution of its exact revision.

Capability Names

• records.filing is supplied by the enabled Records module.
• records.source.<module> is supplied by an enabled source module, for example records.source.files or records.source.cases.
• records.archive.<provider> is supplied by an enabled archive-transfer adapter. Discovery does not imply conformance or current health.

Callers discover capabilities through the module registry. They must not import optional source-module internals.

Exact Source Identity

RecordSourceLocator identifies one tenant, source module, resource type, resource ID, and immutable source revision. A source provider must:

1. reject cross-tenant resolution;
2. require a non-empty purpose;
3. re-evaluate the caller's current module and object authorization;
4. resolve exactly the requested revision, never a mutable "current" alias;
5. return safe display/provenance metadata and a SHA-256 digest when the source has stable bytes or a canonical snapshot;
6. fail closed when the revision is missing, quarantined, corrupt, or no longer authorized.

Historical Records browsing never revives historical access rights. The source's current authorization decision remains authoritative when filing.

Filing Semantics

RecordFilingRequest binds the exact source to a record, purpose, filing reason, relationship, institutional context, and idempotency key. Records must persist source identity and resolution evidence together with the filing actor, represented capacity, valid time, recorded time, and immutable chronology.

An idempotency key may replay only an identical request. A conflicting reuse must fail. Filing does not transfer ownership of source content and must not silently copy mutable source state.

Versioning

The Python DTOs and protocols live in govoplan_core.core.records. The manifest interface records.filing starts at 1.0.0. Incompatible DTO or behavior changes require a new interface version and release impact analysis; additional optional metadata remains backward compatible.

Initial Providers

• Files resolves an exact managed FileVersion, verifies current Files access and blob integrity, and returns its stored content digest.
• Cases resolves an exact immutable case revision after current case access and returns a digest of the canonical revision snapshot.

Provider-specific selection UI belongs to the source module. The generic Records dialog remains a diagnostic/manual fallback for exact identifiers.

Archive Transfer Boundary

RecordTransferPackage binds a stable package ID, record revision, provider profile, canonical manifest, and manifest SHA-256. An archive provider exposes RecordArchiveProviderState before dispatch and accepts only a RecordArchiveTransferRequest for a declared healthy profile. Its receipt must identify the same package and provider and return one bounded outcome: accepted, rejected, or outcome_unknown.

An unknown outcome is never retry-safe. Callers must retain the intent and reconcile it against the provider before another effect. Provider state also declares authority mode, freshness, limitations, and whether the provider is a simulation. Credentials, transport configuration, archive-specific package schemas, and custody semantics remain provider-owned.

Records includes records.archive.simulation to prove package and receipt handling. The simulation is explicitly non-conformant, transfers no custody, and cannot be used as evidence of an archive handoff. A real provider requires a selected target/profile, provider-specific recovery declaration, and target test evidence.

Form Evidence Boundary

Form attachments use the separate provider-neutral contract in govoplan_core.core.form_evidence. Forms Runtime requests short-lived, purpose-bound upload grants and re-inspects the exact provider-owned evidence before final submission. The provider keeps byte storage, quarantine, classification, and retention ownership; Forms Runtime stores only immutable evidence references and bounded verification results. This contract is not an alternative path for Records filing or archive custody.