cadrumo.application.modelo.workspace module

The sole Modelo Workspace V1 assembly and dispatch entry point.

This module owns the one ordering-critical sequence every Workspace read must follow: capture WORK exactly once, derive the REGISTRY coordinate only from that captured ModeloWorkResolution, then evaluate the requested and stored revision axes independently against the SAME REGISTRY capture through the sole pure assertion, assert_work_target_revision(). Neither axis may ever select the revision the other is judged by, and REGISTRY is never captured a second time to answer a question the first capture already carries the coordinates for.

Currently landed: the WORK-then-REGISTRY capture-and-assertion core (resolve_modelo_workspace_revision_axes()), tested in isolation. The full request/admission dispatch and the STATIC_INSPECTION and GRADED_SNAPSHOT projection assemblies are NOT YET BUILT here; ModeloWorkspaceResolvedTargetV1 also requires a review_status this module cannot yet source for the STATIC_INSPECTION admission (see the exec record for the open question). Build those once that is resolved – do not infer the missing semantics.

exception ModeloWorkspaceAbsentRegistryProjectionError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a registry capture returns without its promised projection.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception ModeloWorkspaceUnresolvedWorkError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a workspace read reaches an unresolved work selection.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
modelo_work_selector_request_for_target(target, *, bucket_id)[source]

Project one Workspace target arm into the WORK capture’s selector request.

The Workspace-level target dataclasses already carry .to_work_address() for the legacy single-read call sites, but Workspace’s own WORK port captures over ModeloWorkSelectorRequest, not ModeloWorkAddress – so the mapping is built directly from the target’s own operands rather than round-tripping through the address shape.

Return type:

ModeloWorkSelectorRequest

Parameters:

  • target (ModeloWorkspaceTargetV1)

  • bucket_id (str)

class ModeloWorkspaceRevisionAxes(law_selected_revision_id, requested_revision_assertion, stored_revision_assertion)[source]

Bases: object

The law-determined revision plus both independently checked assertions.

Carries the exact two ModeloWorkspaceRevisionAssertionV1 rows ModeloWorkspaceResolvedTargetV1 requires, already in their final typed shape, so the caller assembling that record only has to plug them in.

Parameters:
law_selected_revision_id: str
requested_revision_assertion: ModeloWorkspaceRevisionAssertionV1
stored_revision_assertion: ModeloWorkspaceRevisionAssertionV1
resolve_modelo_workspace_revision_axes(resolution, *, registry_projection)[source]

Judge the requested and stored revision axes against one REGISTRY capture.

resolution MUST be the WORK capture already taken for this same target; registry_projection MUST be the REGISTRY capture taken from the coordinates that resolution carries (resolution.modelo, resolution.filing_year, resolution.period) and from no other source. This function never captures REGISTRY itself – it only evaluates the two axes against what the caller already captured.

This function never raises on a mismatch. Each independently evaluated assertion retains its typed MISMATCHED disposition in the resolved target, so callers receive the divergence without losing either axis.

Return type:

ModeloWorkspaceRevisionAxes

Parameters:
capture_modelo_workspace_target_captures(target, *, bucket_id, catalogue_repository, authority, grade=None)[source]

Capture WORK exactly once, then REGISTRY exactly once from its coordinates.

Returns the full stamped-and-epoched captures, not just their bare projections, so a baseline assembler can fold the WORK/REGISTRY contributor stamps and epochs into its consistency digest without a second capture of either.

This is the ordering-critical sequence itself: WORK is resolved first, its (modelo, filing_year, period) is read back to build the REGISTRY port – never the target’s own operands, which may name an exact work unit with no natural coordinates of their own – and REGISTRY is captured exactly once from that single WORK-derived coordinate. grade=None (the default) requests STATIC_INSPECTION admission (RegistryRevisionInspection); passing a RegistryAuthorityGrade requests GRADED_SNAPSHOT admission (RegistrySnapshot) through the exact same port and the exact same WORK-then-REGISTRY ordering – the two admissions differ only in which authority object the one REGISTRY read returns, never in how many reads happen or in what order.

Return type:

tuple[ModeloWorkspaceContributingProjectionV1[ModeloWorkResolution], ModeloWorkspaceContributingProjectionV1[ModeloWorkspaceRegistryProjectionV1], ModeloWorkspaceRevisionAxes]

Parameters:
capture_modelo_workspace_locale_summary(resolved_target, *, output_language)[source]

Resolve the canonical locale coordinate for one resolved Workspace target.

Tests the resolved target’s own revision-level display key (revision_locale_key()) through the sole LOCALE_CATALOGUE port. This is the natural per-read canonical key – one Workspace read names exactly one (modelo, revision) pair, and that pair’s own display label is a key every Workspace read already needs regardless of which facet a caller goes on to request.

Return type:

ModeloWorkspaceLocaleSummaryV1

Parameters:
static_inspection_modelo_workspace_capabilities(resolved_target)[source]

Return the complete STATIC_INSPECTION capability denominator.

Every row cites the capability’s own canonical producer contributor per the canonical capability mapping; see the module-level comment above this function. schema_inspection is AVAILABLE – field_manifest is a real STATIC_INSPECTION contributor. The other three are UNMEASURED: their producers are contributors this admission structurally never reads. GRADED_SNAPSHOT’s dispositions are a distinct, not-yet-answered question and MUST NOT be derived from this table.

Return type:

tuple[ModeloWorkspaceCapabilityV1, ...]

Parameters:

resolved_target (ModeloWorkspaceResolvedTargetV1)

formula_expression_operand_references(formula_id, expression)[source]

Walk one formula’s own declared expression tree for every operand it reads.

FormulaExpression is a self-recursive registry-declared tree: an operator node carries args, a leaf carries exactly one populated identity field. This walks that exact structure and needs no inference – every operand kind maps 1:1 to the leaf field the registry already names it by (casilla_id, binding, date_binding, parameter, relation, literal, dispatch_table).

This is the INPUT direction only: which identities this formula’s own expression reads. The OUTPUT direction (which casilla this formula produces) is FormulaDefinition.target_casilla_id and is a provenance-facet concern (“Provenance is projected from the canonical calculation-source graph”), never a schema-record field – the schema record’s plural, multi-kind-discriminated formula_operands field exists to carry exactly this INPUT set, not the single producing edge.

Return type:

tuple[TypeAliasType, ...]

Parameters:
formula_operand_references_for_casilla(formulas, casilla_id)[source]

Return every formula-operand entry naming casilla_id as an INPUT.

Deliberately never includes the formula whose target_casilla_id equals casilla_id unless that same formula’s own expression also reads casilla_id as an operand (a self-referential formula) – being the OUTPUT of a formula is a different edge from being an INPUT to one, and this function answers only the input question.

Return type:

tuple[ModeloWorkspaceFormulaCasillaOperandReferenceV1, ...]

Parameters:
fold_slots(bindings)[source]

Return every relation-prefill slot among a revision’s bindings.

The fold is declared by the binding itself now, so the slot identity and the fold identity are the same id; both workspace endpoint rows are built from this one pairing rather than from a second family that could name a binding this revision does not declare.

Return type:

tuple[tuple[TypeAliasType, RelationPrefillProvider], ...]

Parameters:

bindings (tuple[BindingDefinition, ...])

relation_source_endpoints_for_casilla(bindings, casilla_id, *, source_modelo)[source]

Return the fold-source-endpoint rows whose declared source casilla matches.

A source casilla id is only meaningful inside its own modelo, so a fold reading another modelo never matches a same-spelled casilla of this one.

Return type:

tuple[ModeloWorkspaceRelationSourceEndpointReferenceV1, ...]

Parameters:
relation_target_endpoints_for_binding(bindings, binding_id)[source]

Return the fold-target-endpoint row for a binding that is itself a fold slot.

Return type:

tuple[ModeloWorkspaceRelationTargetEndpointReferenceV1, ...]

Parameters:
resolve_static_inspection_schema_identity(inspection)[source]

Build the STATIC_INSPECTION schema identity from the one REGISTRY capture already held.

schema_fingerprint is a content digest over the inspection’s own declared identity sets (casilla and binding ids) – the same shape _edit_services.py uses for its own, differently-typed ModeloEditSchemaIdentityV1 (interface-ADR-governed), adapted to the flatter STATIC_INSPECTION type. field_manifest_digest is exclusively the inspection-rooted field manifest’s own digest; the edit contract’s CalculationCompletenessManifest digest has its own field (completeness_manifest_digest) on its own type and no longer shares this one.

Return type:

ModeloWorkspaceSchemaIdentityV1

Parameters:

inspection (RegistryRevisionInspection)

static_inspection_evidence_horizon(inspection)[source]

Build the evidence horizon straight from the inspection’s own retained source catalogue.

Return type:

ModeloWorkspaceEvidenceHorizonV1

Parameters:

inspection (RegistryRevisionInspection)

static_inspection_contributors()[source]

Return the four contributor identities STATIC_INSPECTION actually reads.

Matches the ADR’s own admission-scope sentence exactly: “Static inspection captures exactly registry, work, locale_catalogue, and field_manifest.”

Return type:

tuple[ModeloWorkspaceContributorIdentityV1, ...]

resolve_static_inspection_baseline(target, *, schema_identity, locale, work_stamp, work_epoch, registry_stamp, registry_epoch, locale_stamp, locale_epoch, field_manifest_stamp, field_manifest_epoch)[source]

Assemble the STATIC_INSPECTION baseline from the four contributors’ own stamps and epochs.

Every stamp/epoch pair passed in MUST come from the exact same captures that produced target, schema_identity and locale – this function performs no capture of its own, only digesting what the caller already atomically observed.

Return type:

ModeloWorkspaceBaselineV1

Parameters:
exception ModeloWorkspaceStaleCursorError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a cursor’s pinned coordinate no longer matches the current baseline.

A stale cursor MUST refuse rather than silently return a different page: resuming it against data that moved would return records the caller did not ask for and has no way to detect.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
static_inspection_casilla_schema_records(inspection, target, *, output_language)[source]

Build one schema record per casilla identity, sorted for stable pagination.

Bounded to identity: legal_refs and constraints are None (this admission’s producer never carries CasillaDefinition data), never (). formula_operands and relation_endpoints consume the shared join functions directly rather than re-deriving either edge here.

Return type:

tuple[ModeloWorkspaceSchemaRecordV1, ...]

Parameters:
binding_schema_records(binding_ids, bindings)[source]

Build one schema record per binding identity, sorted for stable pagination.

Narrowed from inspection: RegistryRevisionInspection to the raw tuples it read internally – BindingDefinition is the identical type on both RegistryRevisionInspection and RegistrySnapshot.revision, so this is ONE shared implementation both admissions call, never two copies that could drift. Unlike a casilla, BindingDefinition IS retained whole by both admissions, so legal_refs is the binding’s own real (possibly empty) tuple, never None – the absence rule applies only where an admission genuinely carries no such data. The label is ModeloWorkspaceTechnicalLabelV1: no locale convention exists for binding identities.

Return type:

tuple[ModeloWorkspaceSchemaRecordV1, ...]

Parameters:
formula_schema_records(formulas)[source]

Build one schema record per formula, carrying its own full operand set.

Narrowed from inspection: RegistryRevisionInspection to the raw formulas tuple – FormulaDefinition is the identical type on both admissions, so this is ONE shared implementation. A FORMULA row’s formula_operands is that formula’s own complete input list (every operand its expression declares, of every kind) – the mirror of a CASILLA row’s formula_operands, which lists only the subset naming that one casilla. Both readings are the same field walked from opposite ends of the identical join.

Return type:

tuple[ModeloWorkspaceSchemaRecordV1, ...]

Parameters:

formulas (tuple[FormulaDefinition, ...])

parameter_schema_records(parameters, formulas)[source]

Build one schema record per parameter, keyed off every formula that dispatches to it.

Narrowed from inspection: RegistryRevisionInspection to the raw parameters/formulas tuples – ParameterDefinition and FormulaDefinition are the identical type on both admissions, so this is ONE shared implementation. A parameter has no direct outbound edge of its own in the registry schema; the only declared connection is a formula’s own dispatch_table operand naming it, which formula_expression_operand_references() already extracts as ModeloWorkspaceFormulaParameterOperandReferenceV1 and ModeloWorkspaceFormulaDispatchOperandReferenceV1 entries.

Return type:

tuple[ModeloWorkspaceSchemaRecordV1, ...]

Parameters:
static_inspection_schema_records(inspection, target, *, output_language)[source]

Return the complete STATIC_INSPECTION schema_facet across all five reference kinds.

Sorted by (reference.kind, identity) so the whole sequence, and therefore pagination over it, is deterministic and stable across identical repeated reads.

Return type:

tuple[ModeloWorkspaceSchemaRecordV1, ...]

Parameters:
paginate_modelo_workspace_facet(facet_type, records, *, facet, target, schema_identity, baseline, contributors, disposition, page_size, cursor=None)[source]

Return one bounded, cursor-consistent page from the complete records sequence.

records MUST already be in the caller’s canonical stable order – pagination consumes an offset over that fixed order, never re-derives it. A cursor from a DIFFERENT baseline, revision, schema identity, facet, or contributor epoch refuses outright rather than silently starting over or returning a page from the wrong coordinate.

This is the ONE paginator for every bounded facet. It exists as a single authority because ModeloWorkspaceBoundedFacetV1 requires has_more to agree with next_cursor: a facet built by truncating records and setting has_more without minting the matching cursor does not merely lose pagination, it fails model validation outright and takes the whole projection down with it. Minting the cursor is therefore not a convenience this helper offers, it is the only way to construct an overflowing facet at all, and every facet routes through here so that no call site can rediscover that the hard way.

facet_type is the caller’s own concrete parametrization (for example ModeloWorkspaceBoundedFacetV1[ModeloWorkspaceSchemaRecordV1]). It is passed rather than parametrized here from RecordT because a type parameter is only a TypeVar at runtime: pydantic would build the model with the record field effectively unvalidated, silently trading this boundary’s strictness for the generalisation.

Return type:

ModeloWorkspaceBoundedFacetV1[TypeVar]

Parameters:
static_inspection_family_dispositions(inspection)[source]

Project only the family dispositions the inspection can honestly attest to.

See _not_applicable_family_dispositions() for the shared logic; the inspection carries no data for most schema families (it strips everything but casilla/binding/formula/relation/parameter/projection-endpoint/ workbook-parity/live-cross-reference identifiers).

Return type:

tuple[ModeloWorkspaceFamilyDispositionV1, ...]

Parameters:

inspection (RegistryRevisionInspection)

resolve_static_inspection_result(target, *, bucket_id, catalogue_repository, authority, output_language, page_size=200, cursor=None)[source]

Assemble the complete, single-page STATIC_INSPECTION result for one target.

page_size defaults to 200, the schema facet’s own maximum page size (ModeloWorkspaceBoundedFacetV1’s _MAX_FACET_PAGE_SIZE), so a revision whose schema fits within that bound returns in one page; a caller working through a larger schema paginates via next_cursor exactly as paginate_modelo_workspace_facet() proves.

Captures WORK then REGISTRY exactly once each (the ordering-critical core), then builds every remaining piece from that one REGISTRY capture’s inspection: schema identity, locale summary, evidence horizon, family dispositions, contributors, baseline, the five-kind schema_facet, the fixed work_review facet, and the capability denominator. No second registry or work read occurs anywhere in this function.

Return type:

ModeloWorkspaceStaticInspectionResultV1

Parameters: