cadrumo.domain.filing.schema module

Pydantic v2 schema for the domain.filing subpackage.

Every type in this module is a strict, frozen pydantic v2 model or a closed enum.StrEnum. These are the boundary-crossing records the rest of the project pins against — keep them stable.

class ModeloValueKind(*values)[source]

Bases: StrEnum

Provenance kind of a ModeloValue.

LITERAL
COMPUTED
INHERITED
DEFAULT
EMPTY
class ModeloValue(**data)[source]

Bases: BaseModel

The typed value of one casilla on a ModeloDraft.

Variables:

  • casilla_id – Stable casilla ID (e.g. "03").

  • value – The scalar value carried by this casilla. None iff kind is ModeloValueKind.EMPTY.

  • kind – Provenance kind — literal user input, computed, inherited from a previous draft, default from the casilla schema, or empty.

  • source – Free-text provenance string — e.g. "user-supplied", "computed from 01,02", "default per modelo schema".

  • formula_trace_casilla_ids – For COMPUTED values, the casilla IDs that fed the computation. None for non-computed kinds.

Parameters:

data (Any)

casilla_id: CasillaId
value: ModeloScalar
kind: ModeloValueKind
source: str
formula_trace_casilla_ids: tuple[CasillaId, ...] | None
class ModeloBindingValue(**data)[source]

Bases: BaseModel

The typed value of one registry binding on a ModeloDraft.

Carries the same regulatory grounding the casilla half exposes via ModeloCasillaProvenance: legal_refs and source_refs populated from the binding definition, plus a typed BindingSourceKind source (replacing the former free-text provenance string) so a bound value is operator-traceable at parity with a computed casilla.

Variables:

  • binding_id – Stable registry binding id this value materialises.

  • value – The scalar value carried for this binding.

  • kind – Provenance kind — literal input, computed, inherited, etc.

  • source – Typed registry binding source kind (e.g. MANUAL_INPUT, LEDGER_IVA_AGGREGATION).

  • legal_refs – Legal references carried from the binding definition.

  • source_refs – Source references carried from the binding definition.

  • row_index – 1-based row index for multi-row (detail-record) bindings.

Parameters:
binding_id: BindingId
value: ModeloScalar
kind: ModeloValueKind
source: BindingSourceKind
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
row_index: int | None
row_source_identity: RowSourceIdentity | None
class ModeloCasillaProvenance(**data)[source]

Bases: BaseModel

Regulatory grounding for one casilla carried on a filing draft.

formula_id is set for computed casillas (those whose value is produced by a registry formula) and None for manual-input or bound casillas. legal_refs and source_refs are always populated from the registry casilla definition when the draft is created.

Parameters:

data (Any)

casilla_id: CasillaId
formula_id: FormulaId | None
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class ModeloValidationFinding(**data)[source]

Bases: BaseModel

One finding produced by the validator.

Variables:

  • casilla_id – The casilla the finding is about, or None for cross-cutting findings such as deadline checks.

  • severity – ERROR / WARNING / INFO.

  • code – A stable machine-readable code (e.g. "casilla-required-missing").

  • message – A strictly-typed Translatable key.

  • references_rules – Tuple of Manual práctico Rule IDs that justify the finding.

Parameters:

data (Any)

casilla_id: CasillaId | None
severity: BaseSeverity
code: str
message: tr
references_rules: tuple[str, ...]
class ModeloApprovalBasis(**data)[source]

Bases: BaseModel

Persisted approval-basis digests for deterministic stale detection.

Every field is a re-computable claim, so each is shape-constrained: left as bare strings, a blank, short, over-long, uppercase or non-hex value persisted and read back as though it were content-addressed, and the mismatch surfaced only when some later pass happened to recompute.

The eight fingerprints are deliberately NOT one uniform type. draft_payload_fingerprint carries the draft’s own 16-character content address (the approval path assigns it straight from ModeloDraft.draft_id), while the other seven are full SHA-256 hex-64 digests of upstream state. Typing all eight as ContentDigest would refuse the value the approval path actually writes.

Parameters:

data (Any)

version: str
draft_payload_fingerprint: ModeloDraftContentAddress
draft_review_fingerprint: ContentDigest
transaction_catalogue_fingerprint: ContentDigest
invoice_catalogue_fingerprint: ContentDigest
prior_filing_observations_fingerprint: ContentDigest
profile_activity_fingerprint: ContentDigest
category_profiles_fingerprint: ContentDigest
schema_formula_fingerprint: ContentDigest
registry_schema_version(*, modelo, revision_id)[source]

Return the canonical registry:{modelo}:{revision} schema marker.

The marker names the registry modelo and revision a filing artefact was built against. It is the sole declaration of that format: the runtime projection, the draft’s schema_version, and the staleness comparisons in application.filing all derive it here rather than re-inlining the f-string, so the marker and the coherence checks that read it cannot drift apart.

Return type:

str

Parameters:

  • modelo (str)

  • revision_id (RevisionId)

class ModeloDraft(**data)[source]

Bases: BaseModel

A typed, validated draft of one filing.

The draft_id is a content-addressed hash of (modelo, period, profile_tax_id, snapshot_ref, values). Re-validating a draft preserves its identity because findings, status, updated_at and notes are deliberately excluded from the hash.

Parameters:

data (Any)

draft_id: str
modelo: str
period: Period
profile_tax_id: SubjectTaxId
subject_tax_id: SubjectTaxId
snapshot_ref: RegistrySnapshotRef
status: ModeloDraftStatus
values: tuple[ModeloValue, ...]
binding_values: tuple[ModeloBindingValue, ...]
casilla_provenance: tuple[ModeloCasillaProvenance, ...]
findings: tuple[ModeloValidationFinding, ...]
created_at: UtcInstant
updated_at: UtcInstant
schema_version: str
notes: str
approved_at: UtcInstant | None
approved_by: str | None
review_checksum: str | None
approval_basis: ModeloApprovalBasis | None
compute_modelo_draft_id(*, modelo, period, profile_tax_id, snapshot_ref, values, binding_values=())[source]

Compute the stable, content-addressed draft_id.

The period is serialised as {"filing_year": <int>, "code": "<token>"} so the hash is deterministic and self-consistent regardless of the human-readable str(period) form.

Parameters:
Return type:

str

Returns:

A 16-character lowercase hex SHA-256 prefix.