dau_core.capability_contract

Composition-derived capability contract: the single source of truth for what a generated shell can do.

capability_contract(spec) derives the contract from the same ScanCompositionSpec that generates the shell top, using the registry’s declared HDL facts (opcodes, input types, count ports, contract kinds, row capacities). Three consumers read it:

• the identity register block (operator_bitmap / lane_count / host_opcode_bitmap / sort_capacity words, register map 0.2);

• the shell-build artlink manifest (to_mapping(), JSON-able);

• host planners (to_design() for the pushdown scheduler, driver capability decode via the manifest mapping).

Hardware truth vs protocol truth is explicit: operator_bitmap carries only OperationCodes some tile executes in HDL (MIN/MAX/SUM/COUNT); AVERAGE is never a hardware opcode — when a tile provides both SUM and COUNT it appears in host_opcodes (the host divides the results at protocol level), never in opcodes.

Attributes

CAPABILITY_CONTRACT_SCHEMA

Classes

TileCapability	One operator tile instance as the contract describes it: registry
LaneCapability	One scan lane: the terminal operator tile, its optional partition
CapabilityContract	The advertised capability truth of one composed design.

Functions

opcode_bitmap(opcodes) → int	The register encoding: bit 1 << opcode per OperationCode.
tile_capability(tile) → TileCapability	The registry-declared capability facts of one tile instance.
capability_contract(spec) → CapabilityContract	Derive the capability contract from the composition that generates

Module Contents

dau_core.capability_contract.CAPABILITY_CONTRACT_SCHEMA = 1

dau_core.capability_contract.opcode_bitmap(opcodes: tuple[dau_core.stream.OperationCode, ...]) → int

The register encoding: bit 1 << opcode per OperationCode.

class dau_core.capability_contract.TileCapability(/, **data: Any)

Bases: dau_core.models.CheckedModel

One operator tile instance as the contract describes it: registry identity, stream contract, HDL opcode truth, instance config, and the module parameters it was built with (each declared parameter, at its override or its default).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

core: str

module: str

contract_kind: dau_core.cores.ContractKind | None

count_port: str | None

opcodes: tuple[dau_core.stream.OperationCode, ...] = ()

input_types: tuple[dau_core.stream.LogicalType, ...] = ()

unit_kind: dau_core.design.UnitKind | None = None

row_capacity: int | None = None

config: tuple[tuple[str, str], ...] = ()

params: tuple[tuple[str, int], ...] = ()

property host_opcodes: tuple[dau_core.stream.OperationCode, ...]

Protocol-level opcodes the host can compute from this tile’s hardware results: AVERAGE = SUM/COUNT divided host-side. Never hardware opcodes and never advertised as such.

to_mapping() → dict[str, Any]

classmethod from_mapping(mapping: collections.abc.Mapping[str, Any]) → TileCapability

class dau_core.capability_contract.LaneCapability(/, **data: Any)

Bases: dau_core.models.CheckedModel

One scan lane: the terminal operator tile, its optional partition filter, and the ordered mid-lane operator chain between them.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

tile: TileCapability

partition: TileCapability | None = None

chain: tuple[TileCapability, ...] = ()

to_mapping() → dict[str, Any]

classmethod from_mapping(mapping: collections.abc.Mapping[str, Any]) → LaneCapability

class dau_core.capability_contract.CapabilityContract(/, **data: Any)

Bases: dau_core.models.CheckedModel

The advertised capability truth of one composed design.

A config-data model (it is what the shell-build manifest carries and what a planner matches against), so a ccflow model like the rest of the registry’s declarations; to_mapping/from_mapping remain the manifest serialization, unchanged, because manifests already on disk carry that form.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

name: str

lanes: tuple[LaneCapability, ...]

partitioner: TileCapability | None = None

register_map_version: dau_core.registers.RegisterMapVersion

reconfigurable: bool = False

property lane_count: int

property hardware_opcodes: tuple[dau_core.stream.OperationCode, ...]

Union of the lanes’ HDL opcodes (terminal tiles and chain stages), ordered by opcode value.

property host_opcodes: tuple[dau_core.stream.OperationCode, ...]

Protocol-level opcodes derivable host-side (AVERAGE when a tile provides both SUM and COUNT); explicitly not hardware opcodes.

property operator_bitmap: int

property host_opcode_bitmap: int

property sort_capacity: int

to_design() → dau_core.design.DauDesign

The operator inventory this contract advertises: identical lane tiles that contribute a design unit collapse into one counted unit.

to_mapping() → dict[str, Any]

JSON-able serialization for the shell-build manifest.

classmethod from_mapping(mapping: collections.abc.Mapping[str, Any]) → CapabilityContract

dau_core.capability_contract.tile_capability(tile: dau_core.composition.TileSpec | str) → TileCapability

The registry-declared capability facts of one tile instance.

dau_core.capability_contract.capability_contract(spec: dau_core.composition.ScanCompositionSpec) → CapabilityContract

Derive the capability contract from the composition that generates the shell top — same spec, same registry, one source of truth.

reconfigurable stays false: the generated walker binds every config port to the literal the composition names, so no composed design has runtime config registers yet. When the generator can bind them to registers, the composition will say so and this is where the contract reads it.