tangl.vm.dispatch

Dispatch decorators and handler entrypoints that allow higher layers to contribute runtime, provisioning, and replay behavior.

Related design docs

• Provisioning Behavior for Authors

Related notes

• Code-Adjacent Design Docs

Dispatch module

Phase bus hooks for the VM pipeline.

This module provides the registration (on_*) and execution (do_*) surface for every phase in the resolution pipeline, plus the namespace gathering hook that assembles scoped context from entity-local publication plus dispatch contributors.

Design Principle — Explicit Names, DRY Bodies

Each on_* / do_* pair is an explicitly named module-level function (for IDE support, import clarity, and grep-ability) but the body is generated from a shared helper keyed by task name and aggregation mode.

The on_resolve / do_resolve hook is separate because it has a different call signature (takes requirement + offers, not caller).

The on_gather_ns / do_gather_ns hook family is separate because it assembles scoped namespaces from per-entity get_ns() publication plus immediate dispatch contributions.

See also

tangl.vm.resolution_phase

Phase ordering and semantics.

tangl.core.behavior

BehaviorRegistry and CallReceipt aggregation primitives.

tangl.vm.runtime.frame

Consumer of the do_* functions.

Phase decorators

on_validate(func=None, **kwargs)

Register a handler for the validate_edge task.

on_provision(func=None, **kwargs)

Register a handler for the provision_node task.

on_prereqs(func=None, **kwargs)

Register a handler for the get_prereqs task.

on_update(func=None, **kwargs)

Register a handler for the apply_update task.

on_journal(func=None, **kwargs)

Register a handler for the render_journal task.

on_finalize(func=None, **kwargs)

Register a handler for the finalize_step task.

on_postreqs(func=None, **kwargs)

Register a handler for the get_postreqs task.

Phase runners

do_validate(caller, *, ctx, **kwargs)

do_provision(caller, *, ctx, **kwargs)

do_prereqs(caller, *, ctx, **kwargs)

do_update(caller, *, ctx, **kwargs)

do_journal(caller, *, ctx, **kwargs)

do_finalize(caller, *, ctx, **kwargs)

do_postreqs(caller, *, ctx, **kwargs)

Namespace and scope hooks

on_gather_ns / do_gather_ns assemble the scoped runtime namespace. Entity get_ns() remains the lower-level local publication seam.

on_gather_ns(func=None, **kwargs)

Register a contributor to assembled scoped namespaces.

Use wants_caller_kind=Type to filter by caller type and wants_exact_kind=False to allow subclass matches.

do_gather_ns(node, *, ctx)

Assemble the scoped namespace for node in two phases.

Phase 1 calls entity-local get_ns() on node and its ancestor chain. Phase 2 merges immediate-caller gather_ns dispatch contributions.

The resulting ChainMap is the assembled scoped view consumed by PhaseCtx.get_ns(node) and availability/render helpers.

Resolution override hooks

on_resolve(func=None, **kwargs)

Register a handler for requirement resolution.

do_resolve(requirement, *, offers, ctx)

Execute resolve_req handlers and flatten validated offer overrides.

Contract: - handler returns None to keep existing offers unchanged - handler returns Iterable[ProvisionOffer] to contribute overrides