canvas_engineering.program

Typed process semantics for canvas regions and connections.

canvas_engineering.program.ClockSpec dataclass

When a region updates.

Parameters:

Name	Type	Description	Default
domain	str	Time domain. "external" = environment time, "boundary" = lifecycle events.	'external'
mode	str	Firing rule. "periodic" = every N steps, "on_event" = threshold on residual summary, "boundary" = fires on named boundary event.	'periodic'
period	int	For periodic mode, fire every N steps.	1
event_source	Optional[str]	For on_event/boundary mode, the source identifier. Format: "region_name.kind_name" for on_event, event name for boundary.	None
event_threshold	float	For on_event mode, fire when summary exceeds this.	0.0
cooldown	int	After firing, suppress for this many steps.	0
max_silence	Optional[int]	Force fire after this many steps of silence.	None

canvas_engineering.program.LearningSpec dataclass

How a region learns during training.

Parameters:

Name	Type	Description	Default
mode	str	Learning paradigm. "supervised" = task loss, "ssl_prediction" = self-supervised next-step/masked prediction, "posterior_match" = train student to match teacher posterior, "retrieval" = retrieval accuracy + write utility, "calibration" = uncertainty calibration, "none" = no learning.	'supervised'
losses	Tuple[str, ...]	Named loss functions to apply. Interpreted by the training loop.	()
compile_mode	str	What happens at deploy. "runtime" = keep live, "freeze" = no more learning, "distill" = train small student, "constant" = materialize as buffer, "export" = save to disk and remove.	'runtime'

canvas_engineering.program.ConstraintSpec dataclass

Structural constraints on a region's dynamics.

Constraints are declarative assertions that the region's learned dynamics should respect. They are checked by validate_constraints() and can be used by the compiler for optimization.

Parameters:

Name	Type	Description	Default
equivariance	Optional[str]	Symmetry the region must respect. "translation" = shift-equivariant, "rotation" = rotation-equivariant, "permutation" = permutation-equivariant. None = unconstrained.	None
conservation	Optional[str]	Conservation law. "capacity" = total activation is conserved (competition), "energy" = total energy is conserved (Hamiltonian). None = unconstrained.	None
causal_direction	Optional[str]	Causal constraint on outgoing connections. "acyclic" = no cycles in the connection graph rooted here, "forward_only" = only connects to regions with later temporal bounds. None = unconstrained.	None
monotonicity	Optional[str]	Monotonicity constraint on the region's state. "non_decreasing" = state values can only increase over time, "non_increasing" = state values can only decrease over time. None = unconstrained.	None

canvas_engineering.program.RegionProgram dataclass

Process semantics for a canvas region.

Parameters:

Name	Type	Description	Default
family	str	What kind of state this region holds. One of: observation, state, memory, residual, action. Custom strings allowed.	'state'
tags	Tuple[str, ...]	Semantic sub-tags for nuance within a family. E.g., a state region might have tags=("belief", "object") or tags=("goal",).	()
carrier	str	What dynamics govern this region. "deterministic" = standard forward updates, "diffusive" = noise/denoise, "filter" = predict/ correct, "memory" = persistent lookup, "residual" = error traces.	'deterministic'
clock	Optional[ClockSpec]	When this region updates. None = always active.	None
learning	Optional[LearningSpec]	Training recipe. None = use family default.	None
compile_mode	str	Deploy behavior. "runtime" = keep live, "freeze" = no more learning, "constant" = materialize, "export" = save & remove.	'runtime'
constraints	Optional[ConstraintSpec]	Structural constraints on dynamics. None = unconstrained.	None
identity	Optional['IdentitySpec']	Identity/slot persistence spec. None = no identity tracking.	None

effective_compile_mode()

Resolve the effective compile mode (region override > learning > runtime).

effective_learning()

Resolve the effective learning recipe for this region.

Returns the explicit learning field if set, otherwise the family default from canvas_engineering.learning.FAMILY_DEFAULTS. Unknown families fall back to a generic LearningSpec().

canvas_engineering.program.ConnectionProgram dataclass

Process semantics for a canvas connection.

Parameters:

Name	Type	Description	Default
operator	str	Semantic intent of this edge. "attend" = generic attention (backward compat default), "observe" = write evidence, "predict" = propagate forward, "correct" = error-driven update, etc. Each operator carries default (fn, write_mode, trigger) semantics — see OPERATOR_DEFAULTS.	'attend'
trigger	Optional[str]	Optional condition for firing. Serializable string expression referencing residual summaries. E.g., "vision.err.prediction > 0.25". When None, the operator's default trigger applies (if any).	None
write_mode	str	How output accumulates at destination. "add" = additive (current behavior), "replace" = overwrite, "gate" = learned gate. When left at the default and the operator declares a non-default write_mode, the operator's default applies at dispatch time.	'add'
mask_spec	Optional['MaskSpec']	Optional MaskSpec controlling the sparsity pattern of attention between src and dst (full / tile / sparse). When None, the dispatcher uses dense src↔dst attention.	None

canvas_engineering.program.CanvasProgram dataclass

Typed process semantics layered on top of CanvasSchema.

The schema declares structure (where things live, who talks to whom). The program declares behavior (what each region is, how it learns, when it updates, what happens at deploy).

Usage

program = CanvasProgram( schema=my_schema, regions={"obs": RegionProgram(family="observation")}, ) program.to_json("my_program.json") loaded = CanvasProgram.from_json("my_program.json")

from_dict(d) classmethod

Deserialize from a dict.

from_json(path) classmethod

Deserialize from a JSON file.

summary()

Human-readable summary of the program.

to_dict()

Serialize to a JSON-compatible dict.

to_json(path)

Serialize to a JSON file.

Validation & helpers

canvas_engineering.program.validate_constraints(program)

Check structural constraints declared on regions and return violations.

Validates: - ConstraintSpec field values are from known enums - causal_direction="acyclic" — no cycles in the connection sub-graph rooted at constrained regions - causal_direction="forward_only" — constrained regions only connect to regions whose temporal bounds start at the same or later time

Returns:

Type	Description
List[str]	List of human-readable violation strings. Empty list = all good.

canvas_engineering.program.evaluate_trigger(trigger, summaries)

Evaluate a ConnectionProgram.trigger string against residual summaries.

Syntax: "<region>.<kind> <op> <number>" where <op> is one of < > <= >= == !=. Multiple clauses may be ANDed with &&. A None trigger always evaluates to True. A trigger referencing summaries that are missing evaluates to False (cannot fire without evidence).

canvas_engineering.program.resolve_operator_defaults(cp, base_fn)

Resolve the effective (fn, write_mode, trigger) for an edge.

Parameters:

Name	Type	Description	Default
cp	Optional[ConnectionProgram]	The ConnectionProgram for this edge (or None).	required
base_fn	str	The attention fn already resolved from the Connection and region defaults (the "explicit" fn — wins over operator).	required

Returns:

Type	Description
str	Tuple of (effective_fn, effective_write_mode, effective_trigger).
str	For unknown operators all fields fall back to (base_fn, "add", None).