@shardworks/clerk-apparatus 0.1.222 → 0.1.224

package/README.md

@@ -1,6 +1,8 @@
 # `@shardworks/clerk-apparatus`
 
-The Clerk manages the lifecycle of **writs** — lightweight work orders that flow through a fixed status machine. Writs are created as commissions and ultimately completed, failed, or cancelled. Writs may also enter a `stuck` state when their rig encounters an engine failure — a non-terminal "needs attention" status 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 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.
+
+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.
 
 The Clerk sits downstream of The Stacks: `stacks ← clerk`.
 
@@ -32,7 +34,7 @@ const clerk = guild().apparatus<ClerkApi>('clerk');
 
 ### `post(request): Promise<WritDoc>`
 
-Post a new commission, creating a writ in `open` status.
+Post a new commission, creating a writ in `open` phase.
 
 ```typescript
 const writ = await clerk.post({
@@ -53,7 +55,7 @@ const writ = await clerk.post({
 | `parentId` | `string` | Parent writ id for hierarchical decomposition (optional) |
 
 When `parentId` is provided:
-- The parent must exist and be in `new`, `open`, or `stuck` status.
+- The parent must exist and be in `new`, `open`, or `stuck` phase.
 - The child inherits the parent's `codex` if no explicit codex is provided.
 - The entire operation is atomic.
 
@@ -68,13 +70,13 @@ Show a writ by id. Throws if not found.
 List writs with optional filters, ordered by `createdAt` descending (newest first).
 
 ```typescript
-const openWrits = await clerk.list({ status: 'open', limit: 10 });
+const openWrits = await clerk.list({ phase: 'open', limit: 10 });
 const children = await clerk.list({ parentId: parent.id });
 ```
 
 | Filter | Type | Description |
 |---|---|---|
-| `status` | `WritStatus \| WritStatus[]` | Filter by status (single or array — multiple values OR together) |
+| `phase` | `WritPhase \| WritPhase[]` | Filter by phase (single or array — multiple values OR together) |
 | `type` | `string` | Filter by writ type |
 | `parentId` | `string` | Filter to children of this parent writ |
 | `limit` | `number` | Maximum results (default: 20) |
@@ -85,12 +87,12 @@ const children = await clerk.list({ parentId: parent.id });
 Count writs matching optional filters. Accepts the same filters as `list()` (except `limit` and `offset`).
 
 ```typescript
-const total = await clerk.count({ status: 'open' });
+const total = await clerk.count({ phase: 'open' });
 ```
 
 ### `listWritTypes(): WritTypeInfo[]`
 
-List all registered writ types with full metadata — descriptions, source tracking, and default status.
+List all registered writ types with full metadata — descriptions, source tracking, and default flag.
 
 ```typescript
 const types = clerk.listWritTypes();
@@ -174,11 +176,11 @@ const edited = await clerk.edit({
 | `type` | `string` | New writ type — must be declared or built-in (optional) |
 | `codex` | `string` | New target codex name; empty string clears it (optional) |
 
-At least one field besides `id` must be provided. Title and body can be edited in any status. Type and codex can only be changed while the writ is in `new` (draft) status.
+At least one field besides `id` must be provided. Title and body can be edited in any phase. Type and codex can only be changed while the writ is in `new` (draft) phase.
 
 ### `transition(id, to, fields?): Promise<WritDoc>`
 
-Transition a writ to a new status, optionally setting additional fields atomically.
+Transition a writ to a new phase, optionally setting additional fields atomically.
 
 ```typescript
 // Complete with resolution
@@ -191,13 +193,31 @@ 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 status.
+Throws if the transition is not legal for the writ's current phase.
+
+`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).
 
 **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.
 
+### `setWritStatus(writId, pluginId, value): Promise<WritDoc>`
+
+Write (or overwrite) a plugin-owned sub-slot inside the writ's observation `status` map. The `status` field on `WritDoc` is a `Record<string, unknown>` keyed by plugin id — each plugin reads and writes under its own key.
+
+```typescript
+// Spider records stuck cause
+await clerk.setWritStatus(writ.id, 'spider', { stuckCause: 'engine-failed', lastRig: 'rig-01' });
+
+// Astrolabe records a progress ratchet in the same writ — does not clobber spider's slot.
+await clerk.setWritStatus(writ.id, 'astrolabe', { planVersion: 3 });
+```
+
+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 not cleared on terminal transitions — observations persist for post-mortem analysis. See [Spec/Status Convention](#specstatus-convention) for conventions and a worked example.
+
+Throws if `writId` or `pluginId` is missing, or if the writ does not exist.
+
 ---
 
-## Status Machine
+## Phase Machine
 
 ```
 new ──► open ──┬──► completed
@@ -215,7 +235,7 @@ new ──► open ──┬──► completed
 ```
 
 - `completed`, `failed`, and `cancelled` are **terminal** — no transitions out.
-- `stuck` is **non-terminal** — a "needs attention" state for writs whose rig hit an engine failure. Recovery (future retry) transitions back to `open`; giving up transitions to `failed` or `cancelled`.
+- `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`.
 
 ### Allowed transitions
 
@@ -233,7 +253,7 @@ new ──► open ──┬──► completed
 
 Writs can be organized into parent/child relationships for decomposing complex work:
 
-- **Creating children:** Pass `parentId` to `post()`. The parent stays in its current status. Parents in `new`, `open`, or `stuck` status accept children.
+- **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.
 - **Codex inheritance:** Children inherit the parent's codex if none is specified.
@@ -241,6 +261,54 @@ Writs can be organized into parent/child relationships for decomposing complex w
 
 ---
 
+## Spec/Status Convention
+
+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.
+
+The slot is a soft convention rather than a hard enforcement boundary:
+
+- 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.
+
+### Worked example: `status.spider.stuckCause`
+
+When Spider's engine fails for a writ, it transitions the writ to `stuck` (a phase change) *and* records the diagnostic cause in its sub-slot (an observation):
+
+```typescript
+// In Spider's engine-failure handler:
+await clerk.transition(writ.id, 'stuck', { resolution: 'Engine "implement-loop" failed' });
+await clerk.setWritStatus(writ.id, 'spider', {
+  stuckCause: 'engine-failed',
+  lastRig: rig.id,
+  failedEngine: 'implement-loop',
+});
+
+// Later, a human or tool reads the slot to triage:
+const writ = await clerk.show(writId);
+const spiderStatus = (writ.status ?? {})['spider'] as
+  | { stuckCause?: string; lastRig?: string; failedEngine?: string }
+  | undefined;
+
+if (spiderStatus?.stuckCause === 'engine-failed') {
+  console.log(`Stuck in rig ${spiderStatus.lastRig} at engine ${spiderStatus.failedEngine}`);
+}
+```
+
+The phase (`stuck`) is the authoritative lifecycle state — queries, cascades, and the phase machine all reason from it. The observation (`status.spider.stuckCause`) is diagnostic context that survives alongside the phase without becoming part of the state machine itself.
+
+### Guild-wide extensibility
+
+The spec/status split is guild-wide in intent, not a writs-only pattern. Other runtime objects — **rigs**, **engines**, **sessions**, **input requests**, **clicks**, and future apparatuses' primary objects — will adopt the same split on a per-consumer basis: the owning apparatus keeps the lifecycle field (renaming its current `status` to `phase` when the time comes), and a new plugin-keyed `status: Record<string, unknown>` slot appears when the first observation-slot consumer materializes. Until that trigger arrives, those objects keep their existing `status` field unchanged — the convention rolls out one object at a time, not in a big-bang migration. When you author a new apparatus whose primary object may gain observations, reach for the spec/status shape from day one to avoid the rename later.
+
+---
+
 ## Configuration
 
 Configure The Clerk under the `"clerk"` key in your guild config:
@@ -276,7 +344,7 @@ The Clerk contributes books, tools, and pages to the guild:
 
 | Book | Indexes | Contents |
 |---|---|---|
-| `writs` | `status`, `type`, `createdAt`, `parentId`, `[status, type]`, `[status, createdAt]`, `[parentId, status]` | Writ documents |
+| `writs` | `phase`, `type`, `createdAt`, `parentId`, `[phase, type]`, `[phase, createdAt]`, `[parentId, phase]` | Writ documents |
 | `links` | `sourceId`, `targetId`, `label`, `[sourceId, label]`, `[targetId, label]` | Writ relationship links |
 
 ### Tools
@@ -285,8 +353,8 @@ The Clerk contributes books, tools, and pages to the guild:
 |---|---|---|
 | `commission-post` | `clerk:write` | Post a new commission (create a writ, optionally as child) |
 | `writ-show` | `clerk:read` | Show full detail for a writ (includes parent/children context) |
-| `writ-list` | `clerk:read` | List writs with optional filters (status, type, parentId) |
-| `writ-edit` | `clerk:write` | Edit a writ (title/body any status; type/codex draft only) |
+| `writ-list` | `clerk:read` | List writs with optional filters (phase, type, parentId) |
+| `writ-edit` | `clerk:write` | Edit a writ (title/body any phase; type/codex draft only) |
 | `writ-complete` | `clerk:write` | Complete a writ (open → completed) |
 | `writ-fail` | `clerk:write` | Fail a writ (open/stuck → failed) |
 | `writ-cancel` | `clerk:write` | Cancel a writ (new/open/stuck → cancelled) |
@@ -302,12 +370,12 @@ The Clerk contributes books, tools, and pages to the guild:
 ## Key Types
 
 ```typescript
-type WritStatus = 'new' | 'open' | 'stuck' | 'completed' | 'failed' | 'cancelled';
+type WritPhase = 'new' | 'open' | 'stuck' | 'completed' | 'failed' | 'cancelled';
 
 interface WritDoc {
   id: string;           // ULID-like, prefixed "w-"
   type: string;         // declared or built-in type
-  status: WritStatus;
+  phase: WritPhase;     // Clerk-owned lifecycle state
   title: string;
   body: string;
   codex?: string;       // target codex name
@@ -316,6 +384,7 @@ interface WritDoc {
   updatedAt: string;    // ISO timestamp, updated on every mutation
   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)
 }
 
 interface PostCommissionRequest {
@@ -335,7 +404,7 @@ interface EditWritRequest {
 }
 
 interface WritFilters {
-  status?: WritStatus | WritStatus[];
+  phase?: WritPhase | WritPhase[];
   type?: string;
   parentId?: string;    // filter to children of this parent
   limit?: number;

package/dist/clerk.d.ts

@@ -2,7 +2,7 @@
  * The Clerk — writ lifecycle management apparatus.
  *
  * The Clerk manages the lifecycle of writs: lightweight work orders that flow
- * through a fixed status machine (new → open → completed/failed/cancelled,
+ * through a fixed phase machine (new → open → completed/failed/cancelled,
  * with stuck as a non-terminal "needs attention" state off open).
  * Each writ has a type, a title, a body, and optional codex and resolution
  * fields.
@@ -31,7 +31,7 @@ export interface ClerkKit {
 /**
  * Resolution string applied to non-terminal children that are cancelled by
  * the downward cascade when their parent transitions to a terminal failure
- * or cancellation status. Single source of truth — referenced by code,
+ * or cancellation phase. Single source of truth — referenced by code,
  * tests, and documentation. Modeled on `PIECE_EXECUTION_EPILOGUE` in the
  * Spider plugin.
  */

package/dist/clerk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clerk.d.ts","sourceRoot":"","sources":["../src/clerk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAKrE,OAAO,KAAK,EAWV,aAAa,EACb,SAAS,EAEV,MAAM,YAAY,CAAC;AAsBpB,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;CACzB;AAQD;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,sDACG,CAAC;AAoBtD,wBAAgB,WAAW,IAAI,MAAM,CA2sBpC"}
+{"version":3,"file":"clerk.d.ts","sourceRoot":"","sources":["../src/clerk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAKrE,OAAO,KAAK,EAWV,aAAa,EACb,SAAS,EAEV,MAAM,YAAY,CAAC;AAsBpB,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;CACzB;AAQD;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,sDACG,CAAC;AAoBtD,wBAAgB,WAAW,IAAI,MAAM,CAiyBpC"}

package/dist/clerk.js

@@ -2,7 +2,7 @@
  * The Clerk — writ lifecycle management apparatus.
  *
  * The Clerk manages the lifecycle of writs: lightweight work orders that flow
- * through a fixed status machine (new → open → completed/failed/cancelled,
+ * through a fixed phase machine (new → open → completed/failed/cancelled,
  * with stuck as a non-terminal "needs attention" state off open).
  * Each writ has a type, a title, a body, and optional codex and resolution
  * fields.
@@ -23,12 +23,12 @@ const BUILTIN_TYPES = new Set(['mandate']);
 /**
  * Resolution string applied to non-terminal children that are cancelled by
  * the downward cascade when their parent transitions to a terminal failure
- * or cancellation status. Single source of truth — referenced by code,
+ * or cancellation phase. Single source of truth — referenced by code,
  * tests, and documentation. Modeled on `PIECE_EXECUTION_EPILOGUE` in the
  * Spider plugin.
  */
 export const CASCADE_PARENT_TERMINATION_RESOLUTION = 'Automatically cancelled due to parent termination';
-// ── Status machine ───────────────────────────────────────────────────
+// ── Phase machine ────────────────────────────────────────────────────
 const ALLOWED_FROM = {
     open: ['new', 'stuck'],
     stuck: ['open'],
@@ -37,10 +37,10 @@ const ALLOWED_FROM = {
     cancelled: ['new', 'open', 'stuck'],
     new: [],
 };
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const TERMINAL_PHASES = new Set(['completed', 'failed', 'cancelled']);
 // ── Factory ──────────────────────────────────────────────────────────
-/** Parent statuses that allow adding children. */
-const CHILD_ALLOWED_PARENT_STATUSES = new Set(['new', 'open', 'stuck']);
+/** Parent phases that allow adding children. */
+const CHILD_ALLOWED_PARENT_PHASES = new Set(['new', 'open', 'stuck']);
 export function createClerk() {
     let stacks;
     let writs;
@@ -71,13 +71,13 @@ export function createClerk() {
     }
     function buildWhereClause(filters) {
         const conditions = [];
-        if (filters?.status) {
-            const statuses = Array.isArray(filters.status) ? filters.status : [filters.status];
-            if (statuses.length === 1) {
-                conditions.push(['status', '=', statuses[0]]);
+        if (filters?.phase) {
+            const phases = Array.isArray(filters.phase) ? filters.phase : [filters.phase];
+            if (phases.length === 1) {
+                conditions.push(['phase', '=', phases[0]]);
             }
-            else if (statuses.length > 1) {
-                conditions.push(['status', 'IN', statuses]);
+            else if (phases.length > 1) {
+                conditions.push(['phase', 'IN', phases]);
             }
         }
         if (filters?.type) {
@@ -178,13 +178,13 @@ export function createClerk() {
                 // Wrap in a transaction for atomicity
                 return stacks.transaction(async (tx) => {
                     const txWrits = tx.book('clerk', 'writs');
-                    // Validate parent exists and is in an allowed status
+                    // Validate parent exists and is in an allowed phase
                     const parent = await txWrits.get(request.parentId);
                     if (!parent) {
                         throw new Error(`Parent writ "${request.parentId}" not found.`);
                     }
-                    if (!CHILD_ALLOWED_PARENT_STATUSES.has(parent.status)) {
-                        throw new Error(`Cannot add children to writ "${request.parentId}": status is "${parent.status}", expected one of: ${[...CHILD_ALLOWED_PARENT_STATUSES].join(', ')}.`);
+                    if (!CHILD_ALLOWED_PARENT_PHASES.has(parent.phase)) {
+                        throw new Error(`Cannot add children to writ "${request.parentId}": phase is "${parent.phase}", expected one of: ${[...CHILD_ALLOWED_PARENT_PHASES].join(', ')}.`);
                     }
                     // Defensive self-parenting check
                     if (request.parentId === childId) {
@@ -197,7 +197,7 @@ export function createClerk() {
                     const writ = {
                         id: childId,
                         type,
-                        status: request.draft === true ? 'new' : 'open',
+                        phase: request.draft === true ? 'new' : 'open',
                         title: request.title,
                         body: request.body,
                         ...(codex !== undefined ? { codex } : {}),
@@ -212,7 +212,7 @@ export function createClerk() {
             const writ = {
                 id: childId,
                 type,
-                status: request.draft === true ? 'new' : 'open',
+                phase: request.draft === true ? 'new' : 'open',
                 title: request.title,
                 body: request.body,
                 ...(codex !== undefined ? { codex } : {}),
@@ -348,12 +348,12 @@ export function createClerk() {
                 throw new Error(`Writ "${request.id}" not found.`);
             }
             // Type and codex can only be changed while the writ is still a draft
-            if (writ.status !== 'new') {
+            if (writ.phase !== 'new') {
                 if (request.type !== undefined) {
-                    throw new Error(`Cannot change type on writ "${request.id}": status is "${writ.status}". Type can only be changed while the writ is in "new" status.`);
+                    throw new Error(`Cannot change type on writ "${request.id}": phase is "${writ.phase}". Type can only be changed while the writ is in "new" phase.`);
                 }
                 if (request.codex !== undefined) {
-                    throw new Error(`Cannot change codex on writ "${request.id}": status is "${writ.status}". Codex can only be changed while the writ is in "new" status.`);
+                    throw new Error(`Cannot change codex on writ "${request.id}": phase is "${writ.phase}". Codex can only be changed while the writ is in "new" phase.`);
                 }
             }
             // Validate type if provided
@@ -389,31 +389,67 @@ export function createClerk() {
                 throw new Error(`Writ "${id}" not found.`);
             }
             const allowedFrom = ALLOWED_FROM[to];
-            if (!allowedFrom.includes(writ.status)) {
-                throw new Error(`Cannot transition writ "${id}" to "${to}": status is "${writ.status}", expected one of: ${allowedFrom.join(', ')}.`);
+            if (!allowedFrom.includes(writ.phase)) {
+                throw new Error(`Cannot transition writ "${id}" to "${to}": phase is "${writ.phase}", expected one of: ${allowedFrom.join(', ')}.`);
             }
             const now = new Date().toISOString();
-            const isTerminal = TERMINAL_STATUSES.has(to);
-            // Strip managed fields — callers cannot override id, status, or timestamps
-            // controlled by the status machine.
-            const { id: _id, status: _status, createdAt: _c, updatedAt: _u, resolvedAt: _r, parentId: _p, ...safeFields } = (fields ?? {});
+            const isTerminal = TERMINAL_PHASES.has(to);
+            // Strip managed fields — callers cannot override id, phase, the
+            // plugin-owned observation slot `status`, or timestamps controlled
+            // by the phase machine.
+            //
+            // The observation slot is a plugin-keyed map (`Record<PluginId,
+            // unknown>`) whose sub-slots are owned by different plugins. The
+            // only slot-write path that preserves sibling sub-slots under
+            // concurrent writers is ClerkApi.setWritStatus(writId, pluginId,
+            // value), which performs a transactional read-modify-write on the
+            // sub-slot keyed by pluginId. Because patch() is a top-level
+            // shallow merge, a `status` value smuggled through transition()
+            // would wholesale-replace the slot and silently clobber sibling
+            // sub-slots — so `status` is silently dropped here alongside the
+            // other managed fields. There is exactly one sanctioned slot-write
+            // path, and it is setWritStatus().
+            const { id: _id, phase: _phase, status: _status, createdAt: _c, updatedAt: _u, resolvedAt: _r, parentId: _p, ...safeFields } = (fields ?? {});
             const patch = {
-                status: to,
+                phase: to,
                 updatedAt: now,
                 ...(isTerminal ? { resolvedAt: now } : {}),
                 ...safeFields,
             };
             return writs.patch(id, patch);
         },
+        async setWritStatus(writId, pluginId, value) {
+            if (!writId) {
+                throw new Error('setWritStatus: writId is required.');
+            }
+            if (!pluginId) {
+                throw new Error('setWritStatus: pluginId is required.');
+            }
+            // Read-modify-write in a single transaction so we do not clobber
+            // sibling sub-slots written concurrently by other plugins.
+            return stacks.transaction(async (tx) => {
+                const txWrits = tx.book('clerk', 'writs');
+                const existing = await txWrits.get(writId);
+                if (!existing) {
+                    throw new Error(`Writ "${writId}" not found.`);
+                }
+                const prevStatus = (existing.status ?? {});
+                const nextStatus = { ...prevStatus, [pluginId]: value };
+                return txWrits.patch(writId, {
+                    status: nextStatus,
+                    updatedAt: new Date().toISOString(),
+                });
+            });
+        },
     };
     // ── CDC cascade handlers ─────────────────────────────────────────
     async function handleChildTerminal(child) {
         if (!child.parentId)
             return;
         const parent = await writs.get(child.parentId);
-        if (!parent || (parent.status !== 'open' && parent.status !== 'stuck'))
+        if (!parent || (parent.phase !== 'open' && parent.phase !== 'stuck'))
             return;
-        if (child.status === 'failed') {
+        if (child.phase === 'failed') {
             const childResolution = child.resolution ?? 'unknown';
             await api.transition(parent.id, 'failed', {
                 resolution: `Child "${child.id}" failed: ${childResolution}`,
@@ -424,18 +460,18 @@ export function createClerk() {
         const children = await writs.find({ where: [['parentId', '=', parent.id]] });
         if (children.length === 0)
             return;
-        const nonTerminalChildren = children.filter((c) => !TERMINAL_STATUSES.has(c.status));
+        const nonTerminalChildren = children.filter((c) => !TERMINAL_PHASES.has(c.phase));
         if (nonTerminalChildren.length === 0)
             return;
         // When the parent reached `completed`, non-terminal children shouldn't
         // exist — their presence indicates an upstream bookkeeping gap (e.g. a
         // child-writ transition lost a race). Warn loudly rather than masking
         // the discrepancy by cancelling.
-        if (parent.status === 'completed') {
+        if (parent.phase === 'completed') {
             for (const child of nonTerminalChildren) {
                 console.warn(`[clerk] Parent writ "${parent.id}" transitioned to "completed" but ` +
-                    `child writ "${child.id}" is still in non-terminal status ` +
-                    `"${child.status}". Leaving the child as-is; this indicates an ` +
+                    `child writ "${child.id}" is still in non-terminal phase ` +
+                    `"${child.phase}". Leaving the child as-is; this indicates an ` +
                     `upstream bookkeeping gap that should be investigated.`);
             }
             return;
@@ -468,7 +504,7 @@ export function createClerk() {
             supportKit: {
                 books: {
                     writs: {
-                        indexes: ['status', 'type', 'createdAt', 'parentId', ['status', 'type'], ['status', 'createdAt'], ['parentId', 'status']],
+                        indexes: ['phase', 'type', 'createdAt', 'parentId', ['phase', 'type'], ['phase', 'createdAt'], ['parentId', 'phase']],
                     },
                     links: {
                         indexes: ['sourceId', 'targetId', 'label', ['sourceId', 'label'], ['targetId', 'label']],
@@ -526,32 +562,72 @@ export function createClerk() {
                         return;
                     const writ = event.entry;
                     const prev = event.prev;
-                    // Only act on status changes
-                    if (writ.status === prev.status)
+                    // Only act on phase changes
+                    if (writ.phase === prev.phase)
                         return;
                     // ── Upward cascade: child → parent ──
-                    if (writ.parentId && TERMINAL_STATUSES.has(writ.status)) {
+                    if (writ.parentId && TERMINAL_PHASES.has(writ.phase)) {
                         await handleChildTerminal(writ);
                     }
                     // ── Downward cascade: parent → children ──
-                    if (TERMINAL_STATUSES.has(writ.status)) {
+                    if (TERMINAL_PHASES.has(writ.phase)) {
                         await handleParentTerminal(writ);
                     }
                 }, { failOnError: true });
-                // ── One-shot migration: collapse legacy statuses to 'open' ──
+                // ── One-shot migration: rename `status` → `phase`, subsume legacy values ──
                 // Safe to run inside start(): stacks only seals the CDC registry
                 // at phase:started (after every apparatus has started), so these
                 // writes don't lock out downstream apparatuses that register
                 // watchers in their own start().
-                const legacyStatuses = ['ready', 'active', 'waiting'];
-                for (const oldStatus of legacyStatuses) {
-                    const found = await writs.find({ where: [['status', '=', oldStatus]] });
-                    for (const writ of found) {
-                        await writs.patch(writ.id, {
-                            status: 'open',
-                            updatedAt: new Date().toISOString(),
-                        });
+                //
+                // Every pre-rename row carries its lifecycle value in `status`.
+                // Post-rename rows carry `phase` instead, and `status` becomes the
+                // plugin-owned observation slot. We iterate every row, compute a
+                // clean post-rename document, and `put()` it back — `patch()` can't
+                // remove a field, so the full rewrite is required.
+                //
+                // Legacy lifecycle values (`ready`, `active`, `waiting`) are
+                // collapsed into `open` along the way (this subsumes the older
+                // `legacyStatuses` migration). Any unrecognized value aborts
+                // startup — unknown phase is a data-integrity issue.
+                const LEGACY_COLLAPSE = {
+                    ready: 'open',
+                    active: 'open',
+                    waiting: 'open',
+                };
+                const VALID_PHASES = new Set([
+                    'new', 'open', 'stuck', 'completed', 'failed', 'cancelled',
+                ]);
+                const allWrits = await writs.find({});
+                for (const row of allWrits) {
+                    // Already migrated — skip (idempotent).
+                    if (typeof row.phase === 'string')
+                        continue;
+                    const legacyStatus = row.status;
+                    if (typeof legacyStatus !== 'string') {
+                        throw new Error(`[clerk] Migration: writ "${row.id}" has neither \`phase\` nor a string \`status\` field; cannot migrate (got ${legacyStatus === undefined ? 'undefined' : typeof legacyStatus}).`);
+                    }
+                    let nextPhase;
+                    if (LEGACY_COLLAPSE[legacyStatus]) {
+                        nextPhase = LEGACY_COLLAPSE[legacyStatus];
+                    }
+                    else if (VALID_PHASES.has(legacyStatus)) {
+                        nextPhase = legacyStatus;
+                    }
+                    else {
+                        throw new Error(`[clerk] Migration: writ "${row.id}" has unrecognized status value "${legacyStatus}". Expected one of: ${[...VALID_PHASES].join(', ')} (or legacy: ${Object.keys(LEGACY_COLLAPSE).join(', ')}).`);
+                    }
+                    // Build a clean post-rename document — no `status` key, `phase`
+                    // set. `updatedAt` is preserved exactly as stored (this is a
+                    // storage-format change, not a logical edit).
+                    const migrated = {};
+                    for (const [k, v] of Object.entries(row)) {
+                        if (k === 'status')
+                            continue;
+                        migrated[k] = v;
                     }
+                    migrated.phase = nextPhase;
+                    await writs.put(migrated);
                 }
                 // ── One-shot migration: normalize link rows ──────────────────
                 // Two-pass flow per D7: