Machine Authority

Meerkat uses executable machine definitions for state that must have one semantic owner. The goal is simple: for any important lifecycle question, there should be one authoritative answer to what state exists, which transitions are legal, and what effects follow.

Canonical Machines

The canonical registry is canonical_machine_schemas() in meerkat-machine-schema/src/catalog/mod.rs.

Machine	Production owner	Scope
`MeerkatMachine`	`meerkat-runtime`	Session runtime lifecycle, input admission, turn execution, tool visibility, comms drain, peer interaction.
`MobMachine`	`meerkat-mob`	Mob lifecycle, roster, member runtime bindings, wiring, flows, tasks, and supervisor handoffs.
`AuthMachine`	`meerkat-runtime` auth handles	Per-binding auth lease and OAuth flow lifecycle.
`ApprovalLifecycleMachine`	`meerkat-core`	Approval request and decision lifecycle and gating.
`SessionDocumentMachine`	`meerkat-core`	Session document, transcript, system-context, and pending-continuation lifecycle.
`SessionTurnAdmissionMachine`	`meerkat-session`	Per-turn input admission and classification lifecycle.
`ScheduleLifecycleMachine`	`meerkat-schedule`	Schedule definition lifecycle, trigger state, and revision handling.
`OccurrenceLifecycleMachine`	`meerkat-schedule`	Claimed occurrence delivery and terminal outcomes.
`WorkGraphLifecycleMachine`	`meerkat-workgraph`	Work item lifecycle, readiness, dependency eligibility, claim leases, terminal state, and evidence revision handling.
`WorkAttentionLifecycleMachine`	`meerkat-workgraph`	Goal attention binding lifecycle, pause/resume/supersession/stop state, and binding revision handling.

MeerkatMachine and MobMachine are the two runtime kernels. Auth and scheduling are auxiliary authority machines that protect specific perimeter state. WorkGraph is an optional subsystem authority for durable agent commitments, dependency-aware claim state, and goal attention bindings.

Canonical Compositions

The canonical registry is canonical_composition_schemas() in meerkat-machine-schema/src/catalog/mod.rs.

Composition	Purpose
`meerkat_mob_seam`	Session-runtime and mob-runtime handoffs.
`auth_lease_bundle`	Auth authority publication into runtime credential consumers.
`schedule_bundle`	Schedule and occurrence lifecycle coordination.
`schedule_runtime_bundle`	Occurrence delivery into runtime sessions.
`schedule_mob_bundle`	Occurrence delivery into mob runs.
`workgraph_attention_bundle`	WorkGraph lifecycle and attention binding coordination.

These compositions are not marketing concepts or public APIs. They are contributor-facing guardrails for the runtime implementation.

Generated Artifacts

Generated and checked artifacts live in:

Artifact	Path
Catalog DSL	`meerkat-machine-schema/src/catalog/dsl/`
Generated kernels	`meerkat-machine-kernels/src/generated/`
Machine specs	`specs/machines/`
Composition specs	`specs/compositions/`
Code generation	`meerkat-machine-codegen/`

Contribution Rules

When a change affects lifecycle, routing, admission, credential state, mob membership, or scheduling, treat it as a machine-authority change until proven otherwise. Use this checklist:

Identify the semantic owner.
Add or update the catalog DSL if the legal states or transitions changed.
Regenerate machine artifacts.
Update production bridge code to call the generated authority path.
Run the machine verification gates.

Do not add a side map, status enum, or handwritten reducer that decides the same fact in parallel with a machine.

Validation

Use the Make surface:

make machine-codegen
make machine-check-drift
make machine-verify
make seam-inventory

make agent-gate and CI run the relevant gates for normal development. Use the direct targets when you are touching the catalog, generated kernels, composition routes, or runtime bridge code.

​Canonical Machines

​Canonical Compositions

​Generated Artifacts

​Contribution Rules

​Validation

​See Also

Canonical Machines

Canonical Compositions

Generated Artifacts

Contribution Rules

Validation

See Also