cadrumo.application.operator_surface.manifest module

Protocol-neutral reconciliation of declared and live command contracts.

class ReconciliationSurface(*values)[source]

Bases: StrEnum

A projection that must account for every live command identity.

The values name data feeds, rather than implementation modules, so the application-owned reconciliation stays independent of entrypoint and consumer adapters that collect the inventory.

RESULT_SCHEMA
INPUT_SCHEMA
MOUNTED_FAMILY
PROFILE_POLICY
SURFACE_EXPOSURE
class LiveLeafInventoryRow(**data)[source]

Bases: BaseModel

One callable leaf as resolved from the live command tree.

subject_leaf_key is the stable cross-surface identity. The canonical Click path is the only path used to resolve a mounted family; aliases are retained as alternate dispatch paths and cannot silently change a leaf’s family ownership.

Parameters:
subject_leaf_key: str
canonical_cli_path: tuple[str, ...]
alias_cli_paths: tuple[tuple[str, ...], ...]
provenance: str
class ResultSchemaInventoryRow(**data)[source]

Bases: BaseModel

One result-schema registration projected by an entrypoint adapter.

Parameters:

  • subject_leaf_key (str)

  • schema_name (str)

  • provenance (str)

subject_leaf_key: str
schema_name: str
provenance: str
class InputSchemaInventoryRow(**data)[source]

Bases: BaseModel

The required-input identity projection of one registered input schema.

The registered command spec remains the authority for the full parameter models. This row carries the stable leaf identity and every required parameter name so this pure join can prove that the input-schema projection was considered without importing the entrypoint-owned VerbInputSchema type.

Parameters:

  • subject_leaf_key (str)

  • required_input_names (tuple[str, ...])

  • provenance (str)

subject_leaf_key: str
required_input_names: tuple[str, ...]
provenance: str
class MountedFamilyInventoryRow(**data)[source]

Bases: BaseModel

One mounted-family declaration projected from the operator contract.

Parameters:
root: str
child: str
provenance: str
property identity: tuple[str, str]

Return the stable mounted-family identity.

class ProfilePolicyInventoryRow(**data)[source]

Bases: BaseModel

One leaf’s profile-policy classification and external exposure rule.

Parameters:

  • subject_leaf_key (str)

  • classification (str)

  • should_expose_externally (bool)

  • provenance (str)

subject_leaf_key: str
classification: str
should_expose_externally: bool
provenance: str
class SurfaceExposureInventoryRow(**data)[source]

Bases: BaseModel

One observed operator-surface exposure decision for a stable leaf identity.

Named for the SUBJECT, not for one consumer: the decision is whether this CLI leaf may be exposed on an external operator surface at all, computed by the command tree’s protocol-neutral exposure policy.

Parameters:

  • subject_leaf_key (str)

  • exposed (bool)

  • provenance (str)

subject_leaf_key: str
exposed: bool
provenance: str
class ExplicitExclusionInventoryRow(**data)[source]

Bases: BaseModel

An intentional omission from one reconciliation projection.

An exclusion is not a boolean convenience flag. It names the omitted projection and carries both a concrete reason and the authority that made the decision, making every non-join reviewable at campaign closure.

Parameters:
subject_leaf_key: str
surface: ReconciliationSurface
reason: str
authority: str
provenance: str
class ReconciledOperatorLeaf(**data)[source]

Bases: BaseModel

The complete accounted-for projections of one live callable leaf.

Parameters:
live_leaf: LiveLeafInventoryRow
result_schema: ResultSchemaInventoryRow | None
input_schema: InputSchemaInventoryRow | None
mounted_family: MountedFamilyInventoryRow | None
profile_policy: ProfilePolicyInventoryRow | None
surface_exposure: SurfaceExposureInventoryRow | None
exclusions: tuple[ExplicitExclusionInventoryRow, ...]
class OperatorSurfaceReconciliation(**data)[source]

Bases: BaseModel

An exact, application-owned join over the live operator surface.

Parameters:

leaves (tuple[ReconciledOperatorLeaf, ...])

leaves: tuple[ReconciledOperatorLeaf, ...]
class ResolvedCatalogueAction(**data)[source]

Bases: BaseModel

One canonical action joined to a live command and its schemas.

The canonical catalogue declaration remains the action authority. This record retains only resolution evidence: the exact live leaf whose stable subject key equals the declaration’s target command key. It introduces no applicability predicate, presentation text, command string, or runtime argument value.

Parameters:
declaration: ActionCatalogueEntry
target_leaf: ReconciledOperatorLeaf
property action_id: str

Return the canonical catalogue identity.

property target_command_key: str

Return the exact resolved command-schema identity.

class ResolvedManifestActionProfile(**data)[source]

Bases: BaseModel

One declared condition scenario joined to its live subject and action.

Parameters:
declaration: ManifestActionProfile
subject_leaf: ReconciledOperatorLeaf
resolved_action: ResolvedCatalogueAction | None
reconcile_operator_surface_inventory(*, live_leaves, result_schemas, input_schemas, mounted_families, profile_policies, surface_exposures, exclusions=())[source]

Join every live leaf to all surface projections by stable identity.

This is intentionally a pure application function. Click traversal, JSON result-schema registration, parameter projection, profile policy discovery and external enumeration remain adapter concerns. Their typed rows are joined here so a missing row, orphan, duplicate, path ambiguity, silent omission, or policy/exposure conflict is a hard failure rather than a hand-maintained hint.

Every disagreement found is accumulated and reported together through one OperatorSurfaceContractError, so the reader of a failed reconciliation sees the whole census rather than whichever item the iteration order happened to reach first.

Return type:

OperatorSurfaceReconciliation

Parameters:
resolve_action_catalogue(*, catalogue, reconciliation)[source]

Resolve every canonical catalogue target against the live schemas.

All catalogue entries are checked, including entries not yet referenced by a manifest action profile during incremental migration. The input row exposes the complete set of required names, so sufficiency means each of those names has one canonical source specification. Additional specifications are retained: it deliberately does not claim an inventory of optional parameter names and this layer cannot soundly reject them.

Return type:

tuple[ResolvedCatalogueAction, ...]

Parameters:
class CommandSchemaRef(**data)[source]

Bases: BaseModel

One registered command-path to result-schema reference.

command is a stable command-spec result identity (e.g. "modelo.calculate"); schema_name is the authored OutputSchema subclass name an adapter resolves to read the command’s result shape.

Parameters:

  • command (str)

  • schema_name (str)

command: str
schema_name: str