@shardworks/clerk-apparatus 0.1.270 → 0.1.271

package/README.md

@@ -1,8 +1,8 @@
 # `@shardworks/clerk-apparatus`
 
-The Clerk manages the lifecycle of **writs** — lightweight work orders that flow through a fixed phase machine. Writs are created as commissions and ultimately completed, failed, or cancelled. Writs may also enter a `stuck` phase when their rig encounters an engine failure — a non-terminal "needs attention" phase that preserves the obligation for future retry. Writs can be organized into parent/child hierarchies for decomposing complex work.
+The Clerk manages the lifecycle of **writs** — lightweight work orders whose state machine is declared per writ type via a `WritTypeConfig`. The Clerk's own built-in `mandate` type flows through a six-state lifecycle (below); other plugin-registered types declare their own states and transitions. Writs can be organized into parent/child hierarchies for decomposing complex work.
 
-Writ documents follow a Kubernetes-style spec/status split: **`phase`** is the Clerk-owned lifecycle state (the phase machine below), and **`status`** is a plugin-owned observation slot keyed by plugin id — a place for apparatuses like Spider to record side-channel observations (last rig, stuck cause, progress ratchets) without mutating the phase. See [Spec/Status Convention](#specstatus-convention) below.
+Writ documents follow a Kubernetes-style spec/status split: **`phase`** is the Clerk-owned lifecycle state (the phase machine below), **`status`** is a plugin-owned observation slot keyed by plugin id — a place for apparatuses like Spider to record side-channel observations (last rig, stuck cause, progress ratchets) without mutating the phase — and **`ext`** is a sibling plugin-owned metadata slot of the same shape, reserved for metadata-shape data (provenance, cross-references, classifier tags) attached at registration time rather than the post-hoc observation `status` records. See [Spec/Status Convention](#specstatus-convention) below.
 
 The Clerk sits downstream of The Stacks: `stacks ← clerk`.
 
@@ -34,7 +34,14 @@ const clerk = guild().apparatus<ClerkApi>('clerk');
 
 ### `post(request): Promise<WritDoc>`
 
-Post a new commission, creating a writ in `open` phase.
+Post a new commission, creating a writ in its registered type's declared `initial` state. For mandate that's `new` (a draft).
+
+> **API vs. tool — auto-publish UX lives in the tool layer.** `clerk.post()` always lands the writ in the type's `initial` state and never advances it on its own — the API surface is intentionally minimal and predictable. The two tool wrappers reach `open` for you:
+>
+> - **`commission-post`** transitions newly-posted **mandate** writs to `open` automatically unless `draft: true` is passed. Other types (anything plugin-registered) are left in their `initial` state — advancing them without a type-specific tool would be silent coupling, so the auto-advance is confined to mandate.
+> - **`piece-add`** unconditionally transitions the new piece to `open` (the tool has no `draft` parameter).
+>
+> Direct `clerk.post()` callers — including most plugin code — keep the `initial`-state landing semantics; if you want the writ to be dispatchable, follow up with `clerk.transition(id, 'open')`.
 
 ```typescript
 const writ = await clerk.post({
@@ -50,16 +57,16 @@ const writ = await clerk.post({
 |---|---|---|
 | `title` | `string` | Short human-readable title |
 | `body` | `string` | Detail text (required) |
-| `type` | `string` | Writ type — must be declared or built-in (optional) |
+| `type` | `string` | Writ type — must be a registered type (optional) |
 | `codex` | `string` | Target codex name (optional, inherited from parent if omitted) |
 | `parentId` | `string` | Parent writ id for hierarchical decomposition (optional) |
 
 When `parentId` is provided:
-- The parent must exist and be in `new`, `open`, or `stuck` phase.
+- The parent must exist and not be in a terminal state (as classified by its type config).
 - The child inherits the parent's `codex` if no explicit codex is provided.
 - The entire operation is atomic.
 
-Throws if the writ type is not declared in the guild config and is not a built-in type (`mandate`, `summon`).
+Throws if the writ type is not registered — register types with [`registerWritType`](#registerwrittypeconfig-void) from your plugin's `start()`.
 
 ### `show(id): Promise<WritDoc>`
 
@@ -118,14 +125,13 @@ const total = await clerk.count({ phase: 'open' });
 
 ### `listWritTypes(): WritTypeInfo[]`
 
-List all registered writ types with full metadata — descriptions, source tracking, and default flag.
+List all registered writ types. Returns an entry for each type registered via [`registerWritType`](#registerwrittypeconfig-void), including the Clerk's own `mandate`.
 
 ```typescript
 const types = clerk.listWritTypes();
 // [
 //   { name: 'mandate', description: null, source: 'builtin', isDefault: true },
-//   { name: 'task', description: 'A task', source: 'guild', isDefault: false },
-//   { name: 'quality-audit', description: 'Code quality audit', source: 'my-kit', isDefault: false },
+//   { name: 'piece',   description: null, source: 'plugin',  isDefault: false },
 // ]
 ```
 
@@ -134,11 +140,47 @@ Each entry includes:
 | Field | Type | Description |
 |---|---|---|
 | `name` | `string` | The writ type name |
-| `description` | `string \| null` | Human-readable description, or `null` if none was provided |
-| `source` | `string` | Origin: `"builtin"`, `"guild"`, or the contributing plugin's id |
+| `description` | `string \| null` | Reserved; always `null` today — `WritTypeConfig` does not currently model a description field |
+| `source` | `"builtin" \| "plugin"` | `"builtin"` for mandate (registered by the Clerk plugin itself); `"plugin"` for every other registered type |
 | `isDefault` | `boolean` | Whether this is the guild's default writ type |
 
-Source precedence: guild config entries fully shadow kit contributions with the same name (including description).
+Use [`getWritTypeConfig(name)`](#getwrittypeconfigname-writtypeconfig--undefined) when you need the full `WritTypeConfig` (states, transitions, etc.).
+
+### `registerWritType(config): void`
+
+Register a writ type's state machine with the Clerk. The config is validated via `validateWritTypeConfig` (validator errors propagate verbatim); registration-specific failures — duplicate names, or calls after the startup window has closed — throw with a `[clerk] registerWritType:` prefix.
+
+```typescript
+// From a plugin's own start():
+const clerk = guild().apparatus<ClerkApi>('clerk');
+clerk.registerWritType({
+  name: 'audit',
+  states: [
+    { name: 'new', classification: 'initial', allowedTransitions: ['open', 'cancelled'] },
+    { name: 'open', classification: 'active', allowedTransitions: ['completed', 'failed', 'cancelled'] },
+    { name: 'completed', classification: 'terminal', attrs: ['success'], allowedTransitions: [] },
+    { name: 'failed', classification: 'terminal', attrs: ['failure'], allowedTransitions: [] },
+    { name: 'cancelled', classification: 'terminal', attrs: ['cancelled'], allowedTransitions: [] },
+  ],
+});
+```
+
+`registerWritType` is the only path for a plugin to contribute a writ type. The registry is sealed at the framework's global `phase:started` signal — call it from your apparatus's `start()`. There is no guild-config writTypes field and no kit-contribution channel.
+
+### `getWritTypeConfig(name): WritTypeConfig | undefined`
+
+Return the registered `WritTypeConfig` for a writ type, or `undefined` when the name is not registered. Use this accessor when composing higher-level predicates or inspecting a type abstractly (e.g. to render a state-machine diagram).
+
+### `isInitial(writ): boolean` / `isActive(writ): boolean` / `isTerminal(writ): boolean`
+
+Classify a writ's current state by consulting its type's registered `WritTypeConfig`. Each predicate throws the fail-loud diagnostic when the writ's type is not registered, or when its stored state is not declared in that type's config.
+
+```typescript
+const writ = await clerk.show(id);
+if (clerk.isTerminal(writ)) { /* ... */ }
+```
+
+The three predicates partition registered states cleanly — every state in a validated `WritTypeConfig` carries exactly one classification.
 
 ### `link(sourceId, targetId, label, kind?): Promise<WritLinkDoc>`
 
@@ -219,11 +261,17 @@ await clerk.transition(id, 'failed', { resolution: 'Build pipeline broke' });
 await clerk.transition(id, 'cancelled', { resolution: 'No longer needed' });
 ```
 
-Throws if the transition is not legal for the writ's current phase.
+Throws if the transition is not legal for the writ's current phase. The rejection message carries the writ id, current state, attempted target, and the list of legal transitions declared by the writ's type config (or `none (terminal state)` when the current state is terminal).
+
+`transition()` strips the phase machine's managed fields from the body — `id`, `createdAt`, `updatedAt`, `resolvedAt`, and `parentId` — and rejects attempts to override `phase` through the `fields` argument with `[clerk] transition: cannot override phase via fields argument`. The plugin-owned slots `status` and `ext` are writable only via their dedicated writers (`setWritStatus()` for the observation slot, `setWritExt()` for the metadata slot — the two sanctioned slot-write paths), each of which performs a transactional read-modify-write on the sub-slot keyed by `pluginId` so sibling sub-slots are preserved under concurrent writers. See [Spec/Status Convention](#specstatus-convention).
 
-`transition()` silently strips the phase machine's managed fields from the body — `id`, `phase`, `status`, `createdAt`, `updatedAt`, `resolvedAt`, and `parentId`. The observation slot `status` is writable only via `setWritStatus()` (the one sanctioned slot-write path), which performs a transactional read-modify-write on the sub-slot keyed by `pluginId` so sibling sub-slots are preserved under concurrent writers. See [Spec/Status Convention](#specstatus-convention).
+The children-behavior engine — a Phase 1 watcher on the writs book — drives **three** cascade-engine branches. When any writ transitions to a terminal state, the engine evaluates the relevant `WritTypeConfig.childrenBehavior` block(s) and applies the configured actions via `transition`:
 
-**Cascade behavior:** When a writ with children transitions to `failed` or `cancelled`, all non-terminal children are automatically cancelled with resolution `'Automatically cancelled due to parent termination'` (exported as `CASCADE_PARENT_TERMINATION_RESOLUTION`). When a parent transitions to `completed`, non-terminal children are **not** cancelled — instead a warning is logged (their existence indicates an upstream bookkeeping gap). When a child fails and its parent is `open` or `stuck`, the parent is failed and remaining siblings are cancelled.
+- **Upward** (terminal child → parent lift) reads the *parent's* `childrenBehavior`. `anyFailure` is evaluated first; if it fires, `allSuccess` is skipped. When the firing trigger declares `copyResolution: true`, the triggering child's `resolution` string is copied verbatim onto the parent. On every upward fire the engine *also* publishes the immediate triggering child's id under the parent's Clerk-owned status sub-slot (`status['clerk'].triggeringChildId`) **before** the transition records — see [Worked example: `status.clerk.triggeringChildId`](#worked-example-statusclerktriggeringchildid) — so downstream observers (the Reckoner today) can chase the cascade chain back to the leaf cause without parsing the parent's resolution string.
+- **Downward** (terminal parent → non-terminal-children cancellation) reads the *triggering writ's own* `childrenBehavior.parentTerminal`. The downward branch fires only on `failure`- or `cancelled`-attr terminals; the `success` attr is handled by the tripwire branch instead. For each non-terminal child, the engine calls `transition` with the action's configured target and resolution. Already-terminal children are skipped (idempotent on re-fire); a child whose type cannot accept the configured target throws and rolls back the cascade.
+- **Tripwire** (success-attr terminal with non-terminal descendant — enforced invariant). When a writ whose type opts into `childrenBehavior` reaches a `success`-attr terminal state and any non-terminal descendant remains, the engine throws inside the firing transaction and Phase 1 atomicity rolls the offending parent transition back. The cascade engine itself can never produce this state — `allSuccess` enumerates every direct sibling and requires terminal-success — so any path that does is a direct `clerk.transition()` caller bypassing the cascade. Surfacing the gap as a hard error (rather than a log-only warn) makes it unrepresentable in the writs book and catches caller bugs at commit time. The branch walks the descendant subtree directly through the writs book (recursing through terminal nodes too — a bypass further down the tree could leave a non-terminal grandchild beneath an already-terminal child) and the throw message names the offending writ id, the success-attr state, and the non-terminal descendants.
+
+Types whose configs omit `childrenBehavior` are silent no-ops across all three branches — they have announced they do not couple parent and child outcomes. Mandate opts into all three upward/downward triggers (`allSuccess`, `anyFailure`, `parentTerminal`) and is therefore covered by the tripwire too; piece and observation-set declare none. Cascade writes join the triggering transaction (Phase 1 atomicity); grandparent lift and grandchild cancel both fall out naturally as the next update event re-enters the watcher.
 
 ### `setWritStatus(writId, pluginId, value): Promise<WritDoc>`
 
@@ -241,9 +289,27 @@ The write runs in a Stacks transaction (read-modify-write), so concurrent writes
 
 Throws if `writId` or `pluginId` is missing, or if the writ does not exist.
 
+### `setWritExt(writId, pluginId, value): Promise<WritDoc>`
+
+Write (or overwrite) a plugin-owned sub-slot inside the writ's metadata `ext` map. Sibling to `setWritStatus`: the `ext` field on `WritDoc` is the same plugin-keyed `Record<string, unknown>` shape, written through the same transactional read-modify-write contract, with the same CDC event emission and the same terminal-survival guarantee. The semantic distinction is what each slot is meant to hold — `ext` carries metadata-shape data attached at registration time, while `status` records post-hoc observations. See [`ext` (metadata) vs `status` (observation)](#ext-metadata-vs-status-observation).
+
+```typescript
+// Reckoner attaches the originating petition id when the writ is created
+await clerk.setWritExt(writ.id, 'reckoner', { petitionId: 'pet-01' });
+
+// A different plugin writes its own metadata key in the same slot — disjoint sub-slot, no clobber.
+await clerk.setWritExt(writ.id, 'astrolabe', { tag: 'spike' });
+```
+
+The write runs in a Stacks transaction (read-modify-write), so concurrent writes from different plugins to different sub-slots are disjoint and safe. The slot is optional and absent on freshly-posted writs (reads `ext === undefined` until the first sub-slot is written), and is not cleared on terminal transitions — metadata persists for cross-reference reads.
+
+Throws if `writId` or `pluginId` is missing, or if the writ does not exist.
+
 ---
 
-## Phase Machine
+## Mandate's lifecycle (an example registered type)
+
+Mandate is the one writ type the Clerk plugin registers for itself. Its lifecycle — six states, the transitions below — is just one example of a `WritTypeConfig`; other plugin-registered types declare their own state machines.
 
 ```
 new ──► open ──┬──► completed
@@ -260,10 +326,10 @@ new ──► open ──┬──► completed
   └───────┴────┴──► cancelled
 ```
 
-- `completed`, `failed`, and `cancelled` are **terminal** — no transitions out.
-- `stuck` is **non-terminal** — a "needs attention" phase for writs whose rig hit an engine failure. Recovery (future retry) transitions back to `open`; giving up transitions to `failed` or `cancelled`.
+- `completed`, `failed`, and `cancelled` are **terminal** (classification: `terminal`) — no transitions out.
+- `stuck` is **non-terminal** (classification: `active`) — a "needs attention" phase for writs whose rig hit an engine failure. Recovery transitions back to `open`; giving up transitions to `failed` or `cancelled`.
 
-### Allowed transitions
+### Mandate's allowed transitions
 
 | To | From |
 |---|---|
@@ -273,15 +339,16 @@ new ──► open ──┬──► completed
 | `failed` | `open`, `stuck` |
 | `cancelled` | `new`, `open`, `stuck` |
 
+The same table is carried as `allowedTransitions` on each state in mandate's `WritTypeConfig`. Other types (`piece`, `observation-set`, your own) live alongside mandate in the Clerk's runtime registry — their allowed transitions come from their own configs, not this table.
+
 ---
 
 ## Parent/Child Hierarchies
 
 Writs can be organized into parent/child relationships for decomposing complex work:
 
-- **Creating children:** Pass `parentId` to `post()`. The parent stays in its current phase. Parents in `new`, `open`, or `stuck` phase accept children.
-- **Failure cascade:** When a child fails and the parent is `open` or `stuck`, the parent is failed and remaining non-terminal siblings are cancelled.
-- **Cancellation cascade:** When a parent reaches `failed` or `cancelled`, all non-terminal children are cancelled. When a parent reaches `completed` with non-terminal children still present, the Clerk logs a warning and leaves the children alone — this signals an upstream bookkeeping gap rather than normal flow.
+- **Creating children:** Pass `parentId` to `post()`. The parent stays in its current phase. Parents accept children in any non-terminal state; a parent in a terminal state (as classified by its type config) rejects new children with a clear error.
+- **Children-behavior cascade:** the children-behavior engine drives three branches. Upward (terminal child → parent lift) evaluates the parent's `childrenBehavior` (`anyFailure` before `allSuccess`; a failing child wins precedence; `copyResolution: true` copies the triggering child's resolution onto the parent verbatim). Downward (terminal parent → non-terminal-children cancellation) evaluates the triggering writ's own type's `parentTerminal` action when the writ reaches a `failure`- or `cancelled`-attr terminal — every non-terminal descendant is driven to the configured target with the configured resolution string. Tripwire (enforced invariant) throws and rolls back when a cascade-opt-in writ would reach a `success`-attr terminal with any non-terminal descendant: the cascade itself can never produce this state, so any path that does is upstream-broken (a direct `transition()` caller bypassing the cascade), and Phase 1 atomicity makes the gap unrepresentable in the writs book. Cascade is opt-in per type: a type with no `childrenBehavior` block is a silent no-op across all three branches. Mandate opts into all three triggers; piece and observation-set declare none. Cascade fires inside the transaction that triggered it (Phase 1); grandparent lift and grandchild cancel both fall out naturally as the next update event re-enters the watcher.
 - **Codex inheritance:** Children inherit the parent's codex if none is specified.
 - **Immutability:** `parentId` cannot be changed after creation.
 
@@ -293,15 +360,73 @@ Clerk follows a Kubernetes-style spec/status split:
 
 - **Spec fields** are the declared intent of the writ — `title`, `body`, `type`, `codex`, `parentId`, and the Clerk-owned lifecycle field `phase`. These describe *what should happen* and *where the writ currently sits on the phase machine*.
 - **Status slot** (the `status` field on `WritDoc`) is a `Record<string, unknown>` — a free-form observation map keyed by plugin id. Each plugin owns one sub-slot and uses it to record side-channel observations about the writ: last rig used, stuck cause, progress ratchets, planner version, etc.
+- **Ext slot** (the `ext` field on `WritDoc`) is the structural sibling of `status` — same plugin-keyed `Record<string, unknown>` shape, same transactional write contract, same terminal-survival rule — but reserved for metadata-shape data (petition ids, cross-references, classifier tags, configuration extensions) attached at registration time rather than the post-hoc observation `status` records. See [`ext` (metadata) vs `status` (observation)](#ext-metadata-vs-status-observation) below.
+
+Both slots are soft conventions rather than hard enforcement boundaries. Wherever a rule below names one slot and writer, the same rule holds for the sibling.
+
+- No runtime guard stops a plugin from reading another plugin's sub-slot — the convention is *write only your own key*, and the dedicated APIs (`setWritStatus()` / `setWritExt()`) make the right thing easy.
+- **One sanctioned slot-write path per slot.** The observation slot is writable only via `setWritStatus(writId, pluginId, value)`; the metadata slot only via `setWritExt(writId, pluginId, value)`. Each performs a transactional read-modify-write on the sub-slot keyed by `pluginId` so sibling sub-slots are preserved under concurrent writers. `transition()` silently strips both `status` and `ext` from its body alongside the other managed fields (`id`, `phase`, `createdAt`, `updatedAt`, `resolvedAt`, `parentId`). The generic `put()` / `patch()` paths on the `clerk/writs` book are not supported slot-write mechanisms — every route other than the dedicated writer would wholesale-replace the slot and clobber sibling sub-slots.
+- Concurrent writes from different plugins to different sub-slots are disjoint and safe: `setWritStatus()` and `setWritExt()` each run their read-modify-write inside a Stacks transaction.
+- Within a single plugin's sub-slot, concurrent writes are last-writer-wins at the sub-slot level — the dedicated writer replaces the plugin's sub-slot value wholesale. Per-key atomicity inside a sub-slot is deferred until real contention appears.
+- Slot writes emit CDC events like any other field change. Downstream observers (page renderers, audits, further observation pipelines) can watch the writs book for `update` events and react to the new `status` / `ext` contents.
+- Terminal transitions do **not** clear the slots. Observations and metadata persist on the writ for post-mortem inspection and ongoing cross-reference reads.
 
-The slot is a soft convention rather than a hard enforcement boundary:
+### `ext` (metadata) vs `status` (observation)
 
-- No runtime guard stops a plugin from reading another plugin's sub-slot — the convention is *write only your own key*, and the `setWritStatus()` API makes the right thing easy.
-- **One sanctioned slot-write path.** The observation slot is writable only via `setWritStatus(writId, pluginId, value)`, which performs a transactional read-modify-write on the sub-slot keyed by `pluginId` so sibling sub-slots are preserved under concurrent writers. `transition()` silently strips `status` from its body alongside the other managed fields (`id`, `phase`, `createdAt`, `updatedAt`, `resolvedAt`, `parentId`). The generic `put()` / `patch()` paths on the `clerk/writs` book are not supported slot-write mechanisms — every route other than `setWritStatus()` would wholesale-replace the slot and clobber sibling sub-slots.
-- Concurrent writes from different plugins to different sub-slots are disjoint and safe: `setWritStatus()` runs its read-modify-write inside a Stacks transaction.
-- Within a single plugin's sub-slot, concurrent writes are last-writer-wins at the sub-slot level — `setWritStatus()` replaces the plugin's sub-slot value wholesale. Per-key atomicity inside a sub-slot is deferred until real contention appears.
-- Slot writes emit CDC events like any other field change. Downstream observers (page renderers, audits, further observation pipelines) can watch the writs book for `update` events and react to the new `status` contents.
-- Terminal transitions do **not** clear the slot. Observations persist on the writ for post-mortem inspection.
+Both slots are plugin-keyed `Record<string, unknown>` maps with identical mechanics. The semantic distinction is the *kind* of data each is meant to hold:
+
+- **`status` is for post-hoc observation** — what a plugin has *observed* about a writ after the fact. Examples: a stuck cause recorded by Spider's engine-failure handler, a triggering child id recorded by the Clerk's children-behavior cascade, a gate result recorded by an evaluator. The defining feature is that the observation is the plugin's reaction to something the writ has been through.
+- **`ext` is for attached metadata** — what a plugin needs the writ to *carry* as an attribute of its identity. Examples: a petition id linking a writ back to its originating registration, a foreign-system reference, a classifier tag baked in at creation. The defining feature is that the metadata is part of *what the writ is*, not a record of what has happened to it.
+
+Picking the wrong slot layers metadata under an observation contract or vice versa, so plugin authors should choose consciously. When in doubt: ask whether the data is set as the writ comes into being (or is registered with another system) — that points to `ext` — versus updated reactively as the writ evolves — that points to `status`.
+
+#### Worked example: `ext['reckoner'].petitionId`
+
+The Reckoner registers a petition for a writ at the moment the writ is created on its behalf, and attaches the petition id under `ext['reckoner']` so downstream consumers can chase the cross-reference back to the petition record without a separate index. The shape is established at attach time and stable for the writ's lifetime — a textbook metadata-shape consumer rather than an observation. See `docs/architecture/petitioner-registration.md` for the full Reckoner contract; the slot itself is opaque to the Clerk and validated only by the Reckoner.
+
+### Worked example: `status.clerk.triggeringChildId`
+
+The Clerk's children-behavior cascade engine writes a sub-slot of its
+own. When a parent writ is lifted into a terminal state by the cascade
+(one of its children's terminal transitions fired the parent's
+`WritTypeConfig.childrenBehavior` trigger), the engine records the
+immediate triggering child's id under `status['clerk']` *before* the
+parent's `transition()` call:
+
+```typescript
+interface ClerkWritStatus {
+  /**
+   * Id of the immediate child whose terminal transition fired the
+   * children-behavior cascade onto this writ. Absent on writs that
+   * reached terminal through a direct (non-cascaded) transition.
+   */
+  triggeringChildId?: string;
+}
+```
+
+The slot is owned by the Clerk; downstream observers (today, the
+Reckoner) read it through the standard plugin convention:
+
+```typescript
+const clerkStatus = writ.status?.clerk as
+  | { triggeringChildId?: string }
+  | undefined;
+```
+
+**Why the ordering matters.** Phase 2 CDC observers read `event.entry`
+(the post-commit snapshot) at emit time, keyed on the terminal-
+transition's `updatedAt`. Writing the slot *after* the transition would
+deliver the pulse against a snapshot that pre-dates the slot's
+existence and degrade the leaf-cause surface. The dual-write sequence
+(`setWritStatus(parent, 'clerk', …)` then `transition(parent, …)`) is
+preserved instead of relaxing `transition()`'s safe-fields strip —
+`status` continues to be writable only through `setWritStatus()`.
+
+**Chase-chain on the consumer side.** Multi-level cascades (root → mid
+→ leaf) leave each parent in the chain carrying its own immediate
+triggering child id; consumers walk the chain by reading each successive
+writ's own `status['clerk'].triggeringChildId`. Cascade depth is bounded
+by Stacks' `MAX_CASCADE_DEPTH = 16` invariant.
 
 ### Worked example: `status.spider.stuckCause`
 
@@ -347,18 +472,9 @@ Configure The Clerk under the `"clerk"` key in your guild config:
 }
 ```
 
-Writ types are declared at the top level of the guild config:
+Only `defaultType` is honored. It must name a writ type registered with the Clerk (via `registerWritType` from a plugin's `start()`); an unregistered default fails the guild's startup with a clear `[clerk] guild config:` error.
 
-```json
-{
-  "writTypes": {
-    "epic": { "description": "A significant multi-step task" },
-    "errand": { "description": "A small one-off task" }
-  }
-}
-```
-
-The built-in types `mandate` and `summon` are always available without declaration.
+There is no guild-config `writTypes` field. Plugins contribute writ types via `ClerkApi.registerWritType(config)` from their own apparatus's `start()`. The Clerk itself registers `mandate` the same way.
 
 ---
 
@@ -377,7 +493,8 @@ The Clerk contributes books, tools, and pages to the guild:
 
 | Tool | Permission | Description |
 |---|---|---|
-| `commission-post` | `clerk:write` | Post a new commission (create a writ, optionally as child) |
+| `commission-post` | `clerk:write` | Post a new commission (create a writ, optionally as child). Auto-publishes mandate writs to `open` unless `draft: true` is passed; other types stay in their `initial` state. |
+| `piece-add` | `clerk:write` | Add a child `piece` writ to a mandate from a structured task description; the piece is auto-published to `open` and joins the implement-loop queue. |
 | `writ-show` | `clerk:read` | Show full detail for a writ (includes parent/children context) |
 | `writ-list` | `clerk:read` | List writs with optional filters (phase, type, parentId) |
 | `writ-tree` | `clerk:read` | Render the writ hierarchy as a depth-aware tree (forest or single subtree); supports `phase` / `type` filters with prune semantics and a `depth` cap. Output is a box-drawing ASCII tree by default (`--format text`) or the structured `WritTree[]` forest (`--format json`). |
@@ -397,12 +514,15 @@ The Clerk contributes books, tools, and pages to the guild:
 ## Key Types
 
 ```typescript
+// Mandate-specific state union (kept for callers that knowingly downcast).
+// The structural type of WritDoc.phase is `string` so any plugin-registered
+// writ type's state name round-trips through the book.
 type WritPhase = 'new' | 'open' | 'stuck' | 'completed' | 'failed' | 'cancelled';
 
 interface WritDoc {
   id: string;           // ULID-like, prefixed "w-"
-  type: string;         // declared or built-in type
-  phase: WritPhase;     // Clerk-owned lifecycle state
+  type: string;         // a registered writ type
+  phase: string;        // Clerk-owned lifecycle state (any registered type's state name)
   title: string;
   body: string;
   codex?: string;       // target codex name
@@ -412,6 +532,7 @@ interface WritDoc {
   resolvedAt?: string;  // ISO timestamp, set on any terminal transition
   resolution?: string;  // summary of how the writ resolved
   status?: Record<string, unknown>; // plugin-owned observation slot (keyed by plugin id)
+  ext?: Record<string, unknown>;    // plugin-owned metadata slot (keyed by plugin id)
 }
 
 interface PostCommissionRequest {
@@ -454,10 +575,10 @@ interface WritTreeParams {
 }
 
 interface WritTypeInfo {
-  name: string;              // writ type name
-  description: string | null; // human-readable description
-  source: string;            // "builtin", "guild", or plugin id
-  isDefault: boolean;        // whether this is the default type
+  name: string;                       // writ type name
+  description: string | null;         // reserved; always null today
+  source: 'builtin' | 'plugin';       // "builtin" for mandate; "plugin" otherwise
+  isDefault: boolean;                 // whether this is the default type
 }
 
 interface WritLinkDoc {
@@ -497,7 +618,46 @@ See `src/types.ts` for the complete type definitions.
 The package exports all public types and the `createClerk()` factory:
 
 ```typescript
-import clerkPlugin, { createClerk, type ClerkApi, type WritTypeInfo } from '@shardworks/clerk-apparatus';
+import clerkPlugin, {
+  createClerk,
+  CLERK_PLUGIN_ID,
+  type ClerkApi,
+  type ClerkWritStatus,
+  type WritTypeInfo,
+} from '@shardworks/clerk-apparatus';
 ```
 
+`CLERK_PLUGIN_ID` is the constant (`'clerk'`) used as the `status` sub-slot key for the Clerk's own observations (see [Worked example: `status.clerk.triggeringChildId`](#worked-example-statusclerktriggeringchildid)). `ClerkWritStatus` is the writer-side shape of that slot.
+
 The default export is a pre-built plugin instance, ready for guild installation.
+
+### Writ-type configuration
+
+The package also exports the structural shape that describes a writ type's state machine and lifecycle behavior, plus a pure structural validator. These primitives are the foundation for plugin-registered writ types; they do not yet participate in the runtime lifecycle.
+
+```typescript
+import {
+  validateWritTypeConfig,
+  type WritTypeConfig,
+  type WritTypeStateDefinition,
+  type WritTypeStateClassification,
+  type WritTypeStateAttr,
+  type KnownWritTypeStateAttr,
+  type WritTypeChildrenBehavior,
+  type WritTypeChildrenBehaviorAction,
+} from '@shardworks/clerk-apparatus';
+```
+
+A `WritTypeConfig` names the type, enumerates its lifecycle states (each with a `classification` of `'initial' | 'active' | 'terminal'`, an optional `attrs` vocabulary, and per-state `allowedTransitions`), and optionally declares `childrenBehavior` triggers (`allSuccess`, `anyFailure`) that lift terminal-child outcomes back onto the parent.
+
+`validateWritTypeConfig(config)` throws a plain `Error` on the first structural violation it encounters and returns `void` on success. Error messages take the shape `[clerk] writTypeConfig.<path>: <problem>; received <value>` with the path naming the offending field (e.g. `states[2].classification`, `childrenBehavior.anyFailure.transition`). The validator enforces:
+
+- non-empty `name`
+- non-empty `states` array with unique non-empty state names
+- every `classification` drawn from the known vocabulary
+- every `allowedTransitions` entry references an existing state
+- exactly one state classified `initial`
+- every non-initial state has at least one inbound transition
+- terminal states declare no outbound transitions
+- every declared `childrenBehavior` trigger carries an action with a `transition` field that references an existing state
+- every `childrenBehavior` transition target is reachable from every non-terminal state via `allowedTransitions`

package/dist/children-behavior-engine.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Children-behavior cascade engine.
+ *
+ * Subscribes to `update` events on the `clerk/writs` book and, when a writ
+ * transitions to a terminal state, evaluates the relevant
+ * `WritTypeConfig.childrenBehavior` block(s) and applies the configured
+ * action via the supplied `transition` callback. The engine is generic in
+ * writ type — any registered type whose config declares a
+ * `childrenBehavior` block opts in; types that omit the block are no-ops.
+ *
+ * Three cascade-engine branches, all driven by the same firing rule
+ * (terminal transition on `update` events) and dispatched from the same
+ * `handle` function:
+ *
+ *   - **Upward** (terminal child → parent lift). Drives the parent through
+ *     the parent type's `allSuccess` / `anyFailure` triggers when the
+ *     triggering *child* reaches a `success`- or `failure`-attr terminal
+ *     state respectively.
+ *   - **Downward** (terminal parent → non-terminal children cancellation).
+ *     Drives every non-terminal descendant through the parent type's
+ *     `parentTerminal` trigger when the *parent itself* reaches a
+ *     `failure`- or `cancelled`-attr terminal state. Recursion to
+ *     grandchildren happens via natural CDC re-fire on each child's own
+ *     transition, not by an in-handler walk.
+ *   - **Tripwire** (success-attr terminal with non-terminal descendant —
+ *     enforced invariant). Throws when an entry whose type opts into
+ *     `childrenBehavior` reaches a `success`-attr terminal state while
+ *     any non-terminal descendant remains. The throw rolls the entry's
+ *     transition back via Phase 1 atomicity, so the bookkeeping gap is
+ *     unrepresentable in the writs book rather than a log-only signal.
+ *     The cascade engine itself can never produce this state —
+ *     `allSuccess` enumerates every sibling and requires terminal-success
+ *     — so any path that does produce it is upstream-broken (a direct
+ *     `clerk.transition()` caller bypassing the cascade); surfacing it as
+ *     a hard error catches caller bugs early.
+ *
+ * Upward firing rule (in order — first-fail short-circuits):
+ *
+ *   1. Event is an `update`.
+ *   2. The entry's phase actually changed (`entry.phase !== prev.phase`).
+ *   3. The entry is in a terminal state.
+ *   4. The entry has a `parentId`.
+ *   5. The parent writ exists. (Throws if not — dangling parent is a
+ *      data-integrity violation.)
+ *   6. The parent's writ-type is registered. (Throws if not — same
+ *      fail-loud shape as `classifyWritState`.)
+ *   7. The parent type declares a `childrenBehavior` block. (Silent
+ *      no-op when absent.)
+ *   8. The parent itself is non-terminal. (Idempotent short-circuit.)
+ *
+ * Upward trigger evaluation order: `anyFailure` is evaluated first; if it
+ * fires, `allSuccess` is skipped. Otherwise `allSuccess` is evaluated by
+ * enumerating *every* sibling under the same parent (not via the limited
+ * `api.list` path) and checking that every sibling has reached a terminal
+ * state and every terminal state carries the `success` attr.
+ *
+ * Downward firing rule (in order — first-fail short-circuits):
+ *
+ *   1. Event is an `update`.
+ *   2. The entry's phase actually changed (`entry.phase !== prev.phase`).
+ *   3. The entry is in a terminal state carrying the `failure` or
+ *      `cancelled` attr (the parent-itself-terminated signal). The
+ *      `success` attr — i.e. natural completion — is handled by the
+ *      tripwire branch instead.
+ *   4. The entry's own writ-type is registered.
+ *   5. The entry's type declares a `parentTerminal` action. (Silent
+ *      no-op when absent.)
+ *   6. The entry has at least one non-terminal child. The branch
+ *      enumerates children via direct-book read (bypassing `api.list`'s
+ *      20-row default) and skips already-terminal children using
+ *      `isTerminal`.
+ *
+ * For each non-terminal child, the engine calls `api.transition` with the
+ * action's configured `transition` target and `resolution` string (or the
+ * child's own resolution when `copyResolution: true`). If a child cannot
+ * accept the configured target — typically a child-type declaring no
+ * transition into the configured state from the child's current state —
+ * `api.transition` throws and the Phase 1 transaction rolls back per the
+ * engine's existing fail-loud convention. Already-terminal children are
+ * skipped (idempotent on re-fire).
+ *
+ * Tripwire firing rule (in order — first-fail short-circuits):
+ *
+ *   1. Event is an `update`.
+ *   2. The entry's phase actually changed (`entry.phase !== prev.phase`).
+ *   3. The entry is in a terminal state carrying the `success` attr.
+ *   4. The entry's own writ-type is registered.
+ *   5. The entry's type declares a `childrenBehavior` block. (Silent
+ *      no-op when absent — types that decline `childrenBehavior` have
+ *      announced they do not couple parent and child outcomes.)
+ *   6. The entry has at least one non-terminal descendant (direct child
+ *      OR deeper). Descendants are enumerated by walking the subtree
+ *      through the writs book directly (bypassing `api.list`'s 20-row
+ *      default), recursing through terminal nodes too — a terminal
+ *      child can still hide a non-terminal grandchild when an upstream
+ *      caller bypassed the cascade.
+ *
+ * On all six conditions, the tripwire throws a fail-loud error naming
+ * the offending entry id, the `success`-attr terminal state, and the
+ * non-terminal descendants. Phase 1 atomicity rolls the entry's
+ * transition back, so a parent cannot land in a `success`-attr terminal
+ * with open descendants — the gap is unrepresentable in the writs book.
+ * The branch reuses the same enumeration approach as the downward branch
+ * (direct-book read, type-aware `isTerminal` filtering) and stays
+ * idempotent under CDC re-fire: a re-fire with no phase change (rule 2)
+ * short-circuits before evaluation, and a re-fire with all descendants
+ * terminal is a no-op.
+ *
+ * Cascade ordering when both directions fire on the same chain (e.g. an
+ * upward `anyFailure` that lifts a parent into `failed`, which then
+ * needs to push down into the parent's other open siblings) is handled
+ * by natural CDC re-fire: the parent's own update event re-enters this
+ * handler and triggers the downward branch on the parent's now-terminal
+ * transition.
+ *
+ * When a trigger fires with `copyResolution: true`, the triggering
+ * writ's `resolution` string is copied onto the target as part of the
+ * transition. When a trigger fires with `resolution: '...'`, that static
+ * string is written onto every transitioned writ.
+ *
+ * On every upward fire, before the parent's transition is recorded, the
+ * engine publishes a structured record onto the parent's Clerk-owned
+ * status sub-slot (`status['clerk']`) containing the immediate triggering
+ * child's id. The write must precede the transition: downstream observers
+ * (notably the Reckoner) are CDC-driven from the terminal transition's
+ * `updatedAt`, and they read `status['clerk']` from the post-commit
+ * `entry` snapshot at that moment. Writing the slot *after* the transition
+ * would deliver the pulse against a snapshot that pre-dates the slot's
+ * existence and degrade the leaf-cause surface.
+ *
+ * The engine never writes to the writ document directly — every state
+ * change goes through `transition`, so allowedTransitions enforcement,
+ * terminal `resolvedAt` tagging, and CDC re-fire all behave identically
+ * to a direct caller.
+ */
+import type { Book, ChangeEvent } from '@shardworks/stacks-apparatus';
+import type { WritDoc, WritPhase } from './types.ts';
+import type { WritTypeConfig } from './writ-type-config.ts';
+/**
+ * Dependencies the engine needs from the surrounding Clerk runtime.
+ *
+ * `writs` is the book the engine reads sibling lists from directly (the
+ * limited `api.list` default would silently truncate parents with >20
+ * children). `getWritTypeConfig` is the registry accessor.
+ * `isTerminal` is the writ-type-classification predicate.
+ * `transition` is the sole sanctioned phase-change surface.
+ * `setWritStatus` is the sanctioned slot-write path; the engine uses it
+ * to publish `status['clerk']` immediately before the parent's terminal
+ * transition.
+ */
+export interface ChildrenBehaviorEngineDeps {
+    writs: Book<WritDoc>;
+    getWritTypeConfig(name: string): WritTypeConfig | undefined;
+    isTerminal(writ: WritDoc): boolean;
+    transition(id: string, to: WritPhase, fields?: Partial<WritDoc>): Promise<WritDoc>;
+    setWritStatus(writId: string, pluginId: string, value: unknown): Promise<WritDoc>;
+}
+/**
+ * Build the engine handler. Returns an async function suitable for
+ * passing to `stacks.watch('clerk', 'writs', handler, { failOnError: true })`.
+ */
+export declare function createChildrenBehaviorEngine(deps: ChildrenBehaviorEngineDeps): (event: ChangeEvent<WritDoc>) => Promise<void>;
+//# sourceMappingURL=children-behavior-engine.d.ts.map

package/dist/children-behavior-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"children-behavior-engine.d.ts","sourceRoot":"","sources":["../src/children-behavior-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEtE,OAAO,KAAK,EAAmB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC5D,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,UAAU,CACR,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,SAAS,EACb,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GACxB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CA+OhD"}