Lean Contract Seams (bootstrap)
This skill is a bootstrap skill. It is the hand-run form of the practice, kept so lanes can test and
iterate on the process while the real mechanism is built; it is a tool to make tools. It runs nothing
for you: it puts the existing commands in the one order the operator ruled (about 2026-10-31T02:25Z):
"Start with contracts. Let's create seams for all the contracts and have everything
connects before we do anything else." It is replaced by its node-backed skill when that skill comes
online.
Replaced by the node-backed contract-seams skill on node_contract_seams_orchestrator (not built; it
would compose node_generate_node_effect for step 3, core's node_contract_walker_check_compute and event-chain
walker, node_golden_chain_sweep and node_seam_reading_compute for step 5).
Its implementation ticket has not been assigned.
Replace this skill with the node-backed skill when that node lands.
The practice
A design is a graph before it is code: nodes, the crossings between them, and the typed models that
cross. Build the whole graph first, with every node returning a typed empty or INSUFFICIENT result,
and prove that an event travels from the first node to the last on every overlay. Defects found then
cost a contract edit. Defects found after the handlers are filled cost a rewrite, because each side
was built against its own idea of the seam.
When to use
At the first build wave of any design that adds more than one node. When a plan says "contracts
first" or "seams first". When a later change wants a new contract: that is a design change, and it
starts again at step 1 (step 6).
Do not use it for a change inside one handler behind a seam that already connects.
Steps by hand today
- List the graph from the design. Read the design document itself, not a summary of it. Write
three tables: every node with its archetype (orchestrator, compute, effect or reducer, nothing
else); every crossing between two nodes, named by its topic (
onex.cmd.<owner>.<name>.v1 for a
command, onex.evt.<owner>.<name>.v1 for an event) or by its call; every typed model that crosses,
one per crossing. A crossing with no model, or a node with no crossing, is a gap in the design: ask
about it now, by one plain question, before writing anything.
- Write every model and every contract before any logic. The models that cross a repository
boundary go to omnibase_core (frozen Pydantic,
extra="forbid", enums for every closed set, with
unit tests); node-local models stay in the node. Then write each node's contract.yaml: its
archetype, its handler and input and output models, event_bus subscribe and publish topics, a
typed state_machine with state_machine_version for every orchestrator and reducer (so the
walker arms it), protocol_dependencies for every dependency (bus, clock, store, route, model,
host, timeout, credential) with no literal value, and runtime_dispatch.command_topic or
externally_consumed_topics where the graph meets the world. A value the design leaves open stays
open in the contract and blocks evaluation; it is never guessed. Models in omnibase_core land in
two stages: the models pull request first, then the contracts pull request with the pin moved to
the dev-merge tag that carries them (a node repository admits only a released or dev-merge-tagged
core). Prove the contracts against the core branch locally while the models land.
- Scaffold every node from its contract. Use
onex:generate_node for the package skeleton (it is
scaffold-only; read its own status table first). Each handler returns a typed empty result or a
typed INSUFFICIENT result with a reason code, and no business logic. Every dependency arrives
through the constructor from DI; an in-memory implementation is only ever an injected default.
- Wire the chain and boot it on both overlays. One chain test publishes the first event and reads
the last, through the contracts only (handler, models and topics resolved by name from each
contract.yaml). Run it on the in-memory overlay as a unit test, then on the Redpanda overlay as an
integration test on a lab host through /omni:lab-run, with no code change between the two: only
the overlay binds a different bus.
- Prove that it connects. All three readings, each with its command and read time.
Run the Python commands below with the interpreter from the environment where omnibase_core is
installed (0.47.58 or later); they need no source checkout or project-local
uv environment.
- the event-chain walk over the new contracts with core's
ValidatorEventChainWalker
(python -m omnibase_core.nodes.node_validation_report_write_effect.runtime_validator_run omnibase_core.validation.validator_event_chain_walker:ValidatorEventChainWalker <node dirs>,
merged in omnibase_core#2165, released in 0.47.58): zero unconsumed topics, zero unproduced
topics, zero states with no exit, zero undeclared triggers. Add core's contract walker report
(python -m omnibase_core.nodes.node_contract_walker_check_compute.runtime_contract_walker_check)
for the orchestrator graph composed with the reducer FSM: every golden path reaches a terminal
state;
onex:golden_chain_sweep over a chain registered for the new graph, from its head topic to its
projection, fed the rows the chain test projected;
onex:lean_seam_read at each crossing: what crossed, compared with the model both sides
declare, with zero mismatches and zero unreadable crossings.
Plant one broken crossing (drop one subscription) and show that the walk refuses it, so the proof
is not vacuous; then restore it.
- Only then fill the handlers. Each later change fills a handler body behind a seam that already
connects, and keeps the chain test, the walk and the seam reading green. A later change that adds a
contract, a topic or a crossing model is a design change: it goes back to step 1, and the whole
graph is proven again.
Factory task per step
Each step above is replaced by this part of the node-backed skill.
| Step |
Factory task |
| 1 |
node_contract_seams_orchestrator design read (not built) |
| 2 |
node_contract_seams_orchestrator contract and model emission (not built) |
| 3 |
node_generate_node_effect (merged, scaffold only) |
| 4 |
the chain test generated from the contracts (node_event_chain_generator_compute, merged) |
| 5 |
node_contract_walker_check_compute (merged, core), node_golden_chain_sweep (merged), node_seam_reading_compute (merged; its skill is not built) |
| 6 |
none: filling handlers is ordinary build work behind the proven seams |
What this skill cannot do
It cannot decide a design question the document leaves open, and it cannot make the walk, the sweep
or the seam reading pass by editing a check. If a hook refuses a correct shape, fix the hook in its
home repository or report it; never add a baseline or a suppression to get past it.
1---2name: lean-contract-seams3description: Bootstrap skill for contracts and seams first. From a design, list every node, crossing and crossing model; write the models and contracts; scaffold every node; wire the chain on the in-memory and Redpanda overlays; prove it connects; only then fill handlers. Replaced by its node-backed skill on node_contract_seams_orchestrator; replace it when that lands.4mode: full5version: 1.0.06level: intermediate7debug: false8category: process9bootstrap: true10skill_kind: methodology11tags:12 - lean13 - seam14 - contracts15 - bootstrap16author: omninode17metadata:18 source: https://skillmd.com/skills/omninode-ai/lean-contract-seams19---2021# Lean Contract Seams (bootstrap)2223This skill is a bootstrap skill. It is the hand-run form of the practice, kept so lanes can test and24iterate on the process while the real mechanism is built; it is a tool to make tools. It runs nothing25for you: it puts the existing commands in the one order the operator ruled (about 2026-10-31T02:25Z):26"Start with contracts. Let's create seams for all the contracts and have everything27connects before we do anything else." It is replaced by its node-backed skill when that skill comes28online.2930**Replaced by** the node-backed contract-seams skill on `node_contract_seams_orchestrator` (not built; it31would compose `node_generate_node_effect` for step 3, core's `node_contract_walker_check_compute` and event-chain32walker, `node_golden_chain_sweep` and `node_seam_reading_compute` for step 5).33Its implementation ticket has not been assigned.34**Replace this skill with the node-backed skill when that node lands.**3536## The practice3738A design is a graph before it is code: nodes, the crossings between them, and the typed models that39cross. Build the whole graph first, with every node returning a typed empty or INSUFFICIENT result,40and prove that an event travels from the first node to the last on every overlay. Defects found then41cost a contract edit. Defects found after the handlers are filled cost a rewrite, because each side42was built against its own idea of the seam.4344## When to use4546At the first build wave of any design that adds more than one node. When a plan says "contracts47first" or "seams first". When a later change wants a new contract: that is a design change, and it48starts again at step 1 (step 6).4950Do not use it for a change inside one handler behind a seam that already connects.5152## Steps by hand today53541. **List the graph from the design.** Read the design document itself, not a summary of it. Write55 three tables: every node with its archetype (orchestrator, compute, effect or reducer, nothing56 else); every crossing between two nodes, named by its topic (`onex.cmd.<owner>.<name>.v1` for a57 command, `onex.evt.<owner>.<name>.v1` for an event) or by its call; every typed model that crosses,58 one per crossing. A crossing with no model, or a node with no crossing, is a gap in the design: ask59 about it now, by one plain question, before writing anything.602. **Write every model and every contract before any logic.** The models that cross a repository61 boundary go to omnibase_core (frozen Pydantic, `extra="forbid"`, enums for every closed set, with62 unit tests); node-local models stay in the node. Then write each node's `contract.yaml`: its63 archetype, its handler and input and output models, `event_bus` subscribe and publish topics, a64 typed `state_machine` with `state_machine_version` for every orchestrator and reducer (so the65 walker arms it), `protocol_dependencies` for every dependency (bus, clock, store, route, model,66 host, timeout, credential) with no literal value, and `runtime_dispatch.command_topic` or67 `externally_consumed_topics` where the graph meets the world. A value the design leaves open stays68 open in the contract and blocks evaluation; it is never guessed. Models in omnibase_core land in69 two stages: the models pull request first, then the contracts pull request with the pin moved to70 the dev-merge tag that carries them (a node repository admits only a released or dev-merge-tagged71 core). Prove the contracts against the core branch locally while the models land.723. **Scaffold every node from its contract.** Use `onex:generate_node` for the package skeleton (it is73 scaffold-only; read its own status table first). Each handler returns a typed empty result or a74 typed INSUFFICIENT result with a reason code, and no business logic. Every dependency arrives75 through the constructor from DI; an in-memory implementation is only ever an injected default.764. **Wire the chain and boot it on both overlays.** One chain test publishes the first event and reads77 the last, through the contracts only (handler, models and topics resolved by name from each78 `contract.yaml`). Run it on the in-memory overlay as a unit test, then on the Redpanda overlay as an79 integration test on a lab host through `/omni:lab-run`, with no code change between the two: only80 the overlay binds a different bus.815. **Prove that it connects.** All three readings, each with its command and read time.82 Run the Python commands below with the interpreter from the environment where omnibase_core is83 installed (0.47.58 or later); they need no source checkout or project-local `uv` environment.84 - the event-chain walk over the new contracts with core's `ValidatorEventChainWalker`85 (`python -m omnibase_core.nodes.node_validation_report_write_effect.runtime_validator_run86 omnibase_core.validation.validator_event_chain_walker:ValidatorEventChainWalker <node dirs>`,87 merged in omnibase_core#2165, released in 0.47.58): zero unconsumed topics, zero unproduced88 topics, zero states with no exit, zero undeclared triggers. Add core's contract walker report89 (`python -m omnibase_core.nodes.node_contract_walker_check_compute.runtime_contract_walker_check`)90 for the orchestrator graph composed with the reducer FSM: every golden path reaches a terminal91 state;92 - `onex:golden_chain_sweep` over a chain registered for the new graph, from its head topic to its93 projection, fed the rows the chain test projected;94 - `onex:lean_seam_read` at each crossing: what crossed, compared with the model both sides95 declare, with zero mismatches and zero unreadable crossings.96 Plant one broken crossing (drop one subscription) and show that the walk refuses it, so the proof97 is not vacuous; then restore it.986. **Only then fill the handlers.** Each later change fills a handler body behind a seam that already99 connects, and keeps the chain test, the walk and the seam reading green. A later change that adds a100 contract, a topic or a crossing model is a design change: it goes back to step 1, and the whole101 graph is proven again.102103## Factory task per step104105Each step above is replaced by this part of the node-backed skill.106107| Step | Factory task |108| -- | -- |109| 1 | `node_contract_seams_orchestrator` design read (not built) |110| 2 | `node_contract_seams_orchestrator` contract and model emission (not built) |111| 3 | `node_generate_node_effect` (merged, scaffold only) |112| 4 | the chain test generated from the contracts (`node_event_chain_generator_compute`, merged) |113| 5 | `node_contract_walker_check_compute` (merged, core), `node_golden_chain_sweep` (merged), `node_seam_reading_compute` (merged; its skill is not built) |114| 6 | none: filling handlers is ordinary build work behind the proven seams |115116## What this skill cannot do117118It cannot decide a design question the document leaves open, and it cannot make the walk, the sweep119or the seam reading pass by editing a check. If a hook refuses a correct shape, fix the hook in its120home repository or report it; never add a baseline or a suppression to get past it.