95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# 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.
|