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.

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:

reject cross-tenant resolution;
require a non-empty purpose;
re-evaluate the caller's current module and object authorization;
resolve exactly the requested revision, never a mutable "current" alias;
return safe display/provenance metadata and a SHA-256 digest when the source has stable bytes or a canonical snapshot;
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.

2.6 KiB Raw Blame History