@shardworks/dispatch-apparatus 0.1.101

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# `@shardworks/dispatch-apparatus`
+
+> **⚠️ Temporary rigging.** The Dispatch is a stand-in for the full rigging system (Walker, Formulary, Executor). When that system exists, this apparatus is retired.
+
+The Dispatch is the guild's interim work runner. It bridges the gap between the Clerk (which tracks obligations) and the session machinery (which runs animas). It does one thing: find the oldest ready writ and execute it.
+
+The Dispatch sits downstream of the Clerk and Animator:
+`clerk ← dispatch → animator → (codexes)`
+
+---
+
+## Installation
+
+Add to your package's dependencies:
+
+```json
+{
+  "@shardworks/dispatch-apparatus": "workspace:*"
+}
+```
+
+The Dispatch requires the Clerk, Scriptorium (codexes), and Animator to be installed in the guild. The Loom is recommended (used indirectly via `Animator.summon()`). The Stacks is used internally by the Clerk but is not a direct dependency of the Dispatch.
+
+---
+
+## API
+
+The Dispatch exposes a `DispatchApi` via its `provides` interface, retrieved at runtime:
+
+```typescript
+import type { DispatchApi } from '@shardworks/dispatch-apparatus';
+
+const dispatch = guild().apparatus<DispatchApi>('dispatch');
+```
+
+### `next(request?): Promise<DispatchResult | null>`
+
+Find the oldest ready writ and execute it.
+
+```typescript
+// Dispatch with defaults (role: 'artificer')
+const result = await dispatch.next();
+
+// Dispatch with a specific role
+const result = await dispatch.next({ role: 'scribe' });
+
+// Dry run — preview without dispatching
+const result = await dispatch.next({ dryRun: true });
+
+if (!result) {
+  console.log('No ready writs.');
+} else {
+  console.log(result.outcome); // 'completed' | 'failed' | undefined (dryRun)
+}
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `role` | `string` | Role to summon (default: `"artificer"`) |
+| `dryRun` | `boolean` | If true, find and report the writ but don't dispatch |
+
+Returns `null` if no ready writs exist.
+
+---
+
+## Dispatch Lifecycle
+
+```
+next({ role: 'artificer' })
+│
+├─ 1. Query Clerk: clerk.list({ status: 'ready' }), take oldest (last in desc list)
+│     → if none found, return null
+│
+├─ 2. Clerk: transition writ ready → active
+│
+├─ 3. [if writ.codex] Scriptorium: openDraft({ codexName: writ.codex })
+│     → draftRecord (worktree path = session cwd)
+│     → if no codex on writ, cwd = guild home
+│
+├─ 4. Animator: summon({ role, prompt, cwd, metadata: { writId, trigger: 'dispatch' } })
+│     → { chunks, result }
+│
+├─ 5. Await result
+│
+├─ 6a. [success] Session completed normally
+│      ├─ [if codex] Scriptorium: seal({ codexName, sourceBranch: draft.branch })
+│      ├─ [if codex] Scriptorium: push({ codexName })
+│      ├─ Clerk: transition writ active → completed
+│      └─ return DispatchResult { outcome: 'completed' }
+│
+└─ 6b. [failure] Session failed or timed out
+       ├─ [if codex] Scriptorium: abandonDraft({ codexName, branch, force: true })
+       ├─ Clerk: transition writ active → failed
+       └─ return DispatchResult { outcome: 'failed' }
+```
+
+### Error Handling
+
+| Failure | Writ transition | Draft |
+|---|---|---|
+| No ready writs | none | n/a |
+| Draft open fails | → `failed` | n/a (never opened) |
+| Session fails | → `failed` | abandoned (force) |
+| Seal fails | → `failed` | **preserved** (for recovery) |
+| Push fails | → `failed` | **preserved** (for recovery) |
+
+The Dispatch owns writ transitions — the anima does **not** call `writ-complete` or `writ-fail`. This keeps writ lifecycle management out of anima instructions.
+
+---
+
+## Support Kit
+
+The Dispatch contributes one tool:
+
+### Tools
+
+| Tool | Permission | Callable by | Description |
+|---|---|---|---|
+| `dispatch-next` | `dispatch:write` | `cli` | Find and dispatch the oldest ready writ |
+
+---
+
+## Key Types
+
+```typescript
+interface DispatchApi {
+  next(request?: DispatchRequest): Promise<DispatchResult | null>;
+}
+
+interface DispatchRequest {
+  role?: string;    // default: 'artificer'
+  dryRun?: boolean;
+}
+
+interface DispatchResult {
+  writId: string;
+  sessionId?: string;                    // absent if dryRun
+  outcome?: 'completed' | 'failed';     // absent if dryRun
+  resolution?: string;                  // absent if dryRun
+  dryRun: boolean;
+}
+```
+
+See `src/types.ts` for the complete type definitions.
+
+---
+
+## Configuration
+
+No configuration. The Dispatch reads writs from the Clerk and uses default behaviors for all apparatus calls. The role is specified per dispatch via the tool parameter.
+
+---
+
+## Exports
+
+The package exports all public types and the `createDispatch()` factory:
+
+```typescript
+import dispatchPlugin, { createDispatch, type DispatchApi } from '@shardworks/dispatch-apparatus';
+```
+
+The default export is a pre-built plugin instance, ready for guild installation.

package/dist/dispatch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The Dispatch — interim work runner.
+ *
+ * Bridges the Clerk (which tracks obligations) and the session machinery
+ * (which runs animas). Finds the oldest ready writ and executes it:
+ * opens a draft binding, composes context, launches a session, and handles
+ * the aftermath (seal the draft, transition the writ).
+ *
+ * This apparatus is temporary rigging — designed to be retired when the
+ * full rigging system (Walker, Formulary, Executor) is implemented.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+/**
+ * Create the Dispatch apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `requires: ['clerk', 'codexes', 'animator']`
+ * - `recommends: ['loom']` — used indirectly via Animator.summon()
+ * - `provides: DispatchApi` — the dispatch API
+ * - `supportKit` — contributes the `dispatch-next` tool
+ */
+export declare function createDispatch(): Plugin;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AA+BrD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAqHvC"}

package/dist/dispatch.js

@@ -0,0 +1,146 @@
+/**
+ * The Dispatch — interim work runner.
+ *
+ * Bridges the Clerk (which tracks obligations) and the session machinery
+ * (which runs animas). Finds the oldest ready writ and executes it:
+ * opens a draft binding, composes context, launches a session, and handles
+ * the aftermath (seal the draft, transition the writ).
+ *
+ * This apparatus is temporary rigging — designed to be retired when the
+ * full rigging system (Walker, Formulary, Executor) is implemented.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+import { guild } from '@shardworks/nexus-core';
+import { dispatchNext } from "./tools/index.js";
+// ── Prompt assembly ──────────────────────────────────────────────────
+function assemblePrompt(writ) {
+    const lines = [
+        'You have been dispatched to fulfill a commission.',
+        '',
+        '## Assignment',
+        '',
+        `**Title:** ${writ.title}`,
+        '',
+        `**Writ ID:** ${writ.id}`,
+    ];
+    if (writ.body) {
+        lines.push('', writ.body);
+    }
+    return lines.join('\n');
+}
+// ── Apparatus factory ────────────────────────────────────────────────
+/**
+ * Create the Dispatch apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `requires: ['clerk', 'codexes', 'animator']`
+ * - `recommends: ['loom']` — used indirectly via Animator.summon()
+ * - `provides: DispatchApi` — the dispatch API
+ * - `supportKit` — contributes the `dispatch-next` tool
+ */
+export function createDispatch() {
+    const api = {
+        async next(request) {
+            const role = request?.role ?? 'artificer';
+            const dryRun = request?.dryRun ?? false;
+            const clerk = guild().apparatus('clerk');
+            // 1. Find oldest ready writ (FIFO — list returns desc by createdAt, take last)
+            const readyWrits = await clerk.list({ status: 'ready' });
+            const writ = readyWrits[readyWrits.length - 1] ?? null;
+            if (!writ)
+                return null;
+            if (dryRun) {
+                return { writId: writ.id, dryRun: true };
+            }
+            const scriptorium = guild().apparatus('codexes');
+            const animator = guild().apparatus('animator');
+            // 2. Transition writ ready → active
+            await clerk.transition(writ.id, 'active');
+            // 3. Open draft if writ has a codex
+            const codexName = typeof writ.codex === 'string' ? writ.codex : undefined;
+            let draft;
+            if (codexName) {
+                try {
+                    draft = await scriptorium.openDraft({ codexName, associatedWith: writ.id });
+                }
+                catch (err) {
+                    const reason = `Draft open failed: ${String(err)}`;
+                    await clerk.transition(writ.id, 'failed', { resolution: reason });
+                    return { writId: writ.id, outcome: 'failed', resolution: reason, dryRun: false };
+                }
+            }
+            // Session cwd: draft worktree path if codex, otherwise guild home
+            const cwd = draft?.path ?? guild().home;
+            // 4. Assemble prompt and summon anima
+            const prompt = assemblePrompt(writ);
+            const handle = animator.summon({
+                role,
+                prompt,
+                cwd,
+                metadata: { writId: writ.id, trigger: 'dispatch' },
+            });
+            // 5. Await session result
+            let session;
+            try {
+                session = await handle.result;
+            }
+            catch (err) {
+                // Unexpected rejection (summon normally resolves with a failed status)
+                const reason = `Session error: ${String(err)}`;
+                if (codexName && draft) {
+                    await scriptorium.abandonDraft({ codexName, branch: draft.branch, force: true });
+                }
+                await clerk.transition(writ.id, 'failed', { resolution: reason });
+                return { writId: writ.id, outcome: 'failed', resolution: reason, dryRun: false };
+            }
+            // 6a. Success path
+            if (session.status === 'completed') {
+                if (codexName && draft) {
+                    // Seal the draft — fail writ if seal fails but preserve draft for recovery
+                    try {
+                        await scriptorium.seal({ codexName, sourceBranch: draft.branch });
+                    }
+                    catch (err) {
+                        const reason = `Seal failed: ${String(err)}`;
+                        await clerk.transition(writ.id, 'failed', { resolution: reason });
+                        return { writId: writ.id, sessionId: session.id, outcome: 'failed', resolution: reason, dryRun: false };
+                    }
+                    // Push — same treatment as seal failure
+                    try {
+                        await scriptorium.push({ codexName });
+                    }
+                    catch (err) {
+                        const reason = `Push failed: ${String(err)}`;
+                        await clerk.transition(writ.id, 'failed', { resolution: reason });
+                        return { writId: writ.id, sessionId: session.id, outcome: 'failed', resolution: reason, dryRun: false };
+                    }
+                }
+                const resolution = `Session ${session.id} completed`;
+                await clerk.transition(writ.id, 'completed', { resolution });
+                return { writId: writ.id, sessionId: session.id, outcome: 'completed', resolution, dryRun: false };
+            }
+            // 6b. Failure path (status: 'failed' | 'timeout')
+            if (codexName && draft) {
+                await scriptorium.abandonDraft({ codexName, branch: draft.branch, force: true });
+            }
+            const reason = session.error ?? `Session ${session.status}`;
+            await clerk.transition(writ.id, 'failed', { resolution: reason });
+            return { writId: writ.id, sessionId: session.id, outcome: 'failed', resolution: reason, dryRun: false };
+        },
+    };
+    return {
+        apparatus: {
+            requires: ['clerk', 'codexes', 'animator'],
+            recommends: ['loom'],
+            supportKit: {
+                tools: [dispatchNext],
+            },
+            provides: api,
+            start() {
+                // No initialization needed — clerk is resolved at call time in next().
+            },
+        },
+    };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAM/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,wEAAwE;AAExE,SAAS,cAAc,CAAC,IAAa;IACnC,MAAM,KAAK,GAAG;QACZ,mDAAmD;QACnD,EAAE;QACF,eAAe;QACf,EAAE;QACF,cAAc,IAAI,CAAC,KAAK,EAAE;QAC1B,EAAE;QACF,gBAAgB,IAAI,CAAC,EAAE,EAAE;KAC1B,CAAC;IAEF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,wEAAwE;AAExE;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAgB;QACvB,KAAK,CAAC,IAAI,CAAC,OAAyB;YAClC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,WAAW,CAAC;YAC1C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;YAExC,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;YAEnD,+EAA+E;YAC/E,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;YAEvD,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YAEvB,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YAED,MAAM,WAAW,GAAG,KAAK,EAAE,CAAC,SAAS,CAAiB,SAAS,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,SAAS,CAAc,UAAU,CAAC,CAAC;YAE5D,oCAAoC;YACpC,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;YAE1C,oCAAoC;YACpC,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1E,IAAI,KAA8B,CAAC;YAEnC,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,CAAC;oBACH,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9E,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,MAAM,GAAG,sBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;oBACnD,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;oBAClE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;gBACnF,CAAC;YACH,CAAC;YAED,kEAAkE;YAClE,MAAM,GAAG,GAAG,KAAK,EAAE,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,CAAC;YAExC,sCAAsC;YACtC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;gBAC7B,IAAI;gBACJ,MAAM;gBACN,GAAG;gBACH,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE;aACnD,CAAC,CAAC;YAEH,0BAA0B;YAC1B,IAAI,OAAsB,CAAC;YAC3B,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;YAChC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,uEAAuE;gBACvE,MAAM,MAAM,GAAG,kBAAkB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;oBACvB,MAAM,WAAW,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnF,CAAC;gBACD,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;gBAClE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACnF,CAAC;YAED,mBAAmB;YACnB,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBACnC,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;oBACvB,2EAA2E;oBAC3E,IAAI,CAAC;wBACH,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;oBACpE,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,MAAM,MAAM,GAAG,gBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC7C,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;wBAClE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;oBAC1G,CAAC;oBAED,wCAAwC;oBACxC,IAAI,CAAC;wBACH,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;oBACxC,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,MAAM,MAAM,GAAG,gBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC7C,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;wBAClE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;oBAC1G,CAAC;gBACH,CAAC;gBAED,MAAM,UAAU,GAAG,WAAW,OAAO,CAAC,EAAE,YAAY,CAAC;gBACrD,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC7D,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACrG,CAAC;YAED,kDAAkD;YAClD,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;gBACvB,MAAM,WAAW,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACnF,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,OAAO,CAAC,MAAM,EAAE,CAAC;YAC5D,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;YAClE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC1G,CAAC;KACF,CAAC;IAEF,OAAO;QACL,SAAS,EAAE;YACT,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC;YAC1C,UAAU,EAAE,CAAC,MAAM,CAAC;YAEpB,UAAU,EAAE;gBACV,KAAK,EAAE,CAAC,YAAY,CAAC;aACtB;YAED,QAAQ,EAAE,GAAG;YAEb,KAAK;gBACH,uEAAuE;YACzE,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @shardworks/dispatch-apparatus — The Dispatch.
+ *
+ * Interim work runner: finds the oldest ready writ and executes it through
+ * the guild's session machinery. Opens a draft binding on the target codex,
+ * summons an anima via The Animator, and handles the aftermath (seal the
+ * draft, transition the writ). Disposable — retired when the full rigging
+ * system (Walker, Formulary, Executor) is implemented.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+export { type DispatchApi, type DispatchRequest, type DispatchResult, } from './types.ts';
+export { createDispatch } from './dispatch.ts';
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;;AAI/C,wBAAgC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @shardworks/dispatch-apparatus — The Dispatch.
+ *
+ * Interim work runner: finds the oldest ready writ and executes it through
+ * the guild's session machinery. Opens a draft binding on the target codex,
+ * summons an anima via The Animator, and handles the aftermath (seal the
+ * draft, transition the writ). Disposable — retired when the full rigging
+ * system (Walker, Formulary, Executor) is implemented.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+import { createDispatch } from "./dispatch.js";
+// ── Dispatch API ──────────────────────────────────────────────────────
+export {} from "./types.js";
+export { createDispatch } from "./dispatch.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createDispatch();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,yEAAyE;AAEzE,OAAO,EAIN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,yEAAyE;AAEzE,eAAe,cAAc,EAAE,CAAC"}

package/dist/tools/dispatch-next.d.ts

@@ -0,0 +1,22 @@
+/**
+ * dispatch-next tool — find the oldest ready writ and dispatch it.
+ *
+ * The primary entry point for running guild work. Picks the oldest ready
+ * writ (FIFO order), opens a draft on its codex (if any), summons an anima
+ * to fulfill it, and transitions the writ to completed or failed based on
+ * the session outcome.
+ *
+ * Usage:
+ *   nsg dispatch-next
+ *   nsg dispatch-next --role scribe
+ *   nsg dispatch-next --dry-run
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    role: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}>;
+export default _default;
+//# sourceMappingURL=dispatch-next.d.ts.map

package/dist/tools/dispatch-next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-next.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch-next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAGxB,wBA6BG"}

package/dist/tools/dispatch-next.js

@@ -0,0 +1,46 @@
+/**
+ * dispatch-next tool — find the oldest ready writ and dispatch it.
+ *
+ * The primary entry point for running guild work. Picks the oldest ready
+ * writ (FIFO order), opens a draft on its codex (if any), summons an anima
+ * to fulfill it, and transitions the writ to completed or failed based on
+ * the session outcome.
+ *
+ * Usage:
+ *   nsg dispatch-next
+ *   nsg dispatch-next --role scribe
+ *   nsg dispatch-next --dry-run
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+import { tool } from '@shardworks/tools-apparatus';
+import { guild } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'dispatch-next',
+    description: 'Find the oldest ready writ and dispatch it',
+    instructions: 'Finds the oldest ready writ (FIFO order), opens a draft binding on its codex ' +
+        'if specified, summons an anima to fulfill the commission, and transitions the ' +
+        'writ to completed or failed based on the session outcome. Returns null if no ' +
+        'ready writs exist. Use dryRun to preview which writ would be dispatched.',
+    params: {
+        role: z.string().optional()
+            .describe('Role to summon (default: "artificer")'),
+        dryRun: z.boolean().optional().default(false)
+            .describe('If true, find and report the writ but do not dispatch'),
+    },
+    callableBy: 'cli',
+    permission: 'dispatch:write',
+    handler: async (params) => {
+        const dispatch = guild().apparatus('dispatch');
+        const result = await dispatch.next({
+            role: params.role,
+            dryRun: params.dryRun,
+        });
+        if (!result) {
+            return { status: 'idle', message: 'No ready writs found.' };
+        }
+        return result;
+    },
+});
+//# sourceMappingURL=dispatch-next.js.map

package/dist/tools/dispatch-next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-next.js","sourceRoot":"","sources":["../../src/tools/dispatch-next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,4CAA4C;IACzD,YAAY,EACV,+EAA+E;QAC/E,gFAAgF;QAChF,+EAA+E;QAC/E,0EAA0E;IAC5E,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aACxB,QAAQ,CAAC,uCAAuC,CAAC;QACpD,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;aAC1C,QAAQ,CAAC,uDAAuD,CAAC;KACrE;IACD,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,gBAAgB;IAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,SAAS,CAAc,UAAU,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC;YACjC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;QAC9D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dispatch tool re-exports.
+ */
+export { default as dispatchNext } from './dispatch-next.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,5 @@
+/**
+ * Dispatch tool re-exports.
+ */
+export { default as dispatchNext } from "./dispatch-next.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The Dispatch — public types.
+ *
+ * These types form the contract between The Dispatch apparatus and all
+ * callers (CLI, clockworks). No implementation details.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+export interface DispatchApi {
+    /**
+     * Find the oldest ready writ and execute it.
+     *
+     * The full dispatch lifecycle:
+     *   1. Query the Clerk for the oldest ready writ
+     *   2. Transition the writ to active
+     *   3. Open a draft binding on the writ's codex (if specified)
+     *   4. Summon an anima session with the writ context as prompt
+     *   5. Wait for session completion
+     *   6. On success: seal the draft, push, transition writ to completed
+     *   7. On failure: abandon the draft, transition writ to failed
+     *
+     * Returns null if no ready writs exist.
+     *
+     * If the writ has no codex, steps 3/6/7 (draft lifecycle) are
+     * skipped — the session runs in the guild home directory with
+     * no codex binding.
+     */
+    next(request?: DispatchRequest): Promise<DispatchResult | null>;
+}
+export interface DispatchRequest {
+    /** Role to summon. Default: 'artificer'. */
+    role?: string;
+    /** If true, find and report the writ but don't dispatch. */
+    dryRun?: boolean;
+}
+export interface DispatchResult {
+    /** The writ that was dispatched. */
+    writId: string;
+    /** The session id (from the Animator). Absent if dryRun. */
+    sessionId?: string;
+    /** Terminal writ status after dispatch. Absent if dryRun. */
+    outcome?: 'completed' | 'failed';
+    /** Resolution text set on the writ. Absent if dryRun. */
+    resolution?: string;
+    /** Whether this was a dry run. */
+    dryRun: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACjE;AAID,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * The Dispatch — public types.
+ *
+ * These types form the contract between The Dispatch apparatus and all
+ * callers (CLI, clockworks). No implementation details.
+ *
+ * See: docs/architecture/apparatus/dispatch.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@shardworks/dispatch-apparatus",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/dispatch"
+  },
+  "description": "The Dispatch — interim work runner: find the oldest ready writ and execute it",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@shardworks/clerk-apparatus": "0.1.101",
+    "@shardworks/animator-apparatus": "0.1.101",
+    "@shardworks/loom-apparatus": "0.1.101",
+    "@shardworks/codexes-apparatus": "0.1.101",
+    "@shardworks/nexus-core": "0.1.101",
+    "@shardworks/tools-apparatus": "0.1.101"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0",
+    "@shardworks/stacks-apparatus": "0.1.101"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}