@shardworks/clerk-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,209 @@
+# `@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.
+
+The Clerk sits downstream of The Stacks: `stacks ← clerk`.
+
+---
+
+## Installation
+
+Add to your package's dependencies:
+
+```json
+{
+  "@shardworks/clerk-apparatus": "workspace:*"
+}
+```
+
+The Clerk requires The Stacks to be installed in the guild.
+
+---
+
+## API
+
+The Clerk exposes a `ClerkApi` via its `provides` interface, retrieved at runtime:
+
+```typescript
+import type { ClerkApi } from '@shardworks/clerk-apparatus';
+
+const clerk = guild().apparatus<ClerkApi>('clerk');
+```
+
+### `post(request): Promise<WritDoc>`
+
+Post a new commission, creating a writ in `ready` status.
+
+```typescript
+const writ = await clerk.post({
+  title: 'Refactor the session layer',
+  body: 'Move all session logic into a dedicated module',
+  type: 'mandate',      // optional, defaults to guild defaultType or "mandate"
+  codex: 'artificer',  // optional target codex
+});
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `title` | `string` | Short human-readable title |
+| `body` | `string` | Detail text (required) |
+| `type` | `string` | Writ type — must be declared or built-in (optional) |
+| `codex` | `string` | Target codex name (optional) |
+
+Throws if the writ type is not declared in the guild config and is not a built-in type (`mandate`, `summon`).
+
+### `show(id): Promise<WritDoc>`
+
+Show a writ by id. Throws if not found.
+
+### `list(filters?): Promise<WritDoc[]>`
+
+List writs with optional filters, ordered by `createdAt` descending (newest first).
+
+```typescript
+const activeWrits = await clerk.list({ status: 'active', limit: 10 });
+```
+
+| Filter | Type | Description |
+|---|---|---|
+| `status` | `WritStatus` | Filter by status |
+| `type` | `string` | Filter by writ type |
+| `limit` | `number` | Maximum results (default: 20) |
+| `offset` | `number` | Number of results to skip |
+
+### `count(filters?): Promise<number>`
+
+Count writs matching optional filters. Accepts the same filters as `list()` (except `limit` and `offset`).
+
+```typescript
+const total = await clerk.count({ status: 'ready' });
+```
+
+### `transition(id, to, fields?): Promise<WritDoc>`
+
+Transition a writ to a new status, optionally setting additional fields atomically.
+
+```typescript
+// Accept
+await clerk.transition(id, 'active');
+
+// Complete with resolution
+await clerk.transition(id, 'completed', { resolution: 'Shipped to production' });
+
+// Fail with resolution
+await clerk.transition(id, 'failed', { resolution: 'Build pipeline broke' });
+
+// Cancel (resolution optional)
+await clerk.transition(id, 'cancelled', { resolution: 'No longer needed' });
+```
+
+Throws if the transition is not legal for the writ's current status.
+
+---
+
+## Status Machine
+
+```
+ready ──────► active ──────► completed
+  │              │
+  │              └──────────► failed
+  │
+  └──────────────────────────► cancelled
+         (from ready or active)
+```
+
+`completed`, `failed`, and `cancelled` are **terminal** — no transitions out.
+
+---
+
+## Configuration
+
+Configure The Clerk under the `"clerk"` key in your guild config:
+
+```json
+{
+  "clerk": {
+    "defaultType": "mandate"
+  }
+}
+```
+
+Writ types are declared at the top level of the guild config:
+
+```json
+{
+  "writTypes": {
+    "quest": { "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.
+
+---
+
+## Support Kit
+
+The Clerk contributes one book and seven tools to the guild:
+
+### Books
+
+| Book | Indexes | Contents |
+|---|---|---|
+| `writs` | `status`, `type`, `createdAt`, `[status, type]`, `[status, createdAt]` | Writ documents |
+
+### Tools
+
+| Tool | Permission | Description |
+|---|---|---|
+| `commission-post` | `clerk:write` | Post a new commission (create a writ) |
+| `writ-show` | `clerk:read` | Show full detail for a writ |
+| `writ-list` | `clerk:read` | List writs with optional filters |
+| `writ-accept` | `clerk:write` | Accept a writ (ready → active) |
+| `writ-complete` | `clerk:write` | Complete a writ (active → completed) |
+| `writ-fail` | `clerk:write` | Fail a writ (active → failed) |
+| `writ-cancel` | `clerk:write` | Cancel a writ (ready\|active → cancelled) |
+
+---
+
+## Key Types
+
+```typescript
+type WritStatus = 'ready' | 'active' | 'completed' | 'failed' | 'cancelled';
+
+interface WritDoc {
+  id: string;           // ULID-like, prefixed "writ-"
+  type: string;         // declared or built-in type
+  status: WritStatus;
+  title: string;
+  body: string;
+  codex?: string;       // target codex name
+  createdAt: string;    // ISO timestamp
+  updatedAt: string;    // ISO timestamp, updated on every mutation
+  acceptedAt?: string;  // ISO timestamp, set when transitioning to active
+  resolvedAt?: string;  // ISO timestamp, set on any terminal transition
+  resolution?: string;  // summary of how the writ resolved
+}
+
+interface PostCommissionRequest {
+  title: string;
+  body: string;         // required
+  type?: string;        // defaults to guild defaultType or "mandate"
+  codex?: string;
+}
+```
+
+See `src/types.ts` for the complete type definitions.
+
+---
+
+## Exports
+
+The package exports all public types and the `createClerk()` factory:
+
+```typescript
+import clerkPlugin, { createClerk, type ClerkApi } from '@shardworks/clerk-apparatus';
+```
+
+The default export is a pre-built plugin instance, ready for guild installation.

package/dist/clerk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Clerk — writ lifecycle management apparatus.
+ *
+ * The Clerk manages the lifecycle of writs: lightweight work orders that flow
+ * through a fixed status machine (ready → active → completed/failed, or
+ * ready/active → cancelled). Each writ has a type, a title, a body, and
+ * optional codex and resolution fields.
+ *
+ * Writ types are validated against the guild config's writTypes field plus the
+ * built-in type ('mandate'). An unknown type is rejected at post time.
+ *
+ * See: docs/architecture/apparatus/clerk.md
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+export declare function createClerk(): Plugin;
+//# sourceMappingURL=clerk.d.ts.map

package/dist/clerk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clerk.d.ts","sourceRoot":"","sources":["../src/clerk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAyCrE,wBAAgB,WAAW,IAAI,MAAM,CAsJpC"}

package/dist/clerk.js

@@ -0,0 +1,149 @@
+/**
+ * The Clerk — writ lifecycle management apparatus.
+ *
+ * The Clerk manages the lifecycle of writs: lightweight work orders that flow
+ * through a fixed status machine (ready → active → completed/failed, or
+ * ready/active → cancelled). Each writ has a type, a title, a body, and
+ * optional codex and resolution fields.
+ *
+ * Writ types are validated against the guild config's writTypes field plus the
+ * built-in type ('mandate'). An unknown type is rejected at post time.
+ *
+ * See: docs/architecture/apparatus/clerk.md
+ */
+import { guild, generateId } from '@shardworks/nexus-core';
+import { commissionPost, writShow, writList, writAccept, writComplete, writFail, writCancel, } from "./tools/index.js";
+// ── Built-in writ types ──────────────────────────────────────────────
+const BUILTIN_TYPES = new Set(['mandate']);
+// ── Status machine ───────────────────────────────────────────────────
+const ALLOWED_FROM = {
+    active: ['ready'],
+    completed: ['active'],
+    failed: ['active'],
+    cancelled: ['ready', 'active'],
+    ready: [],
+};
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+// ── Factory ──────────────────────────────────────────────────────────
+export function createClerk() {
+    let writs;
+    // ── Helpers ──────────────────────────────────────────────────────
+    function resolveClerkConfig() {
+        return guild().guildConfig().clerk ?? {};
+    }
+    function resolveWritTypes() {
+        const config = resolveClerkConfig();
+        const declared = (config.writTypes ?? []).map((entry) => entry.name);
+        return new Set([...BUILTIN_TYPES, ...declared]);
+    }
+    function resolveDefaultType() {
+        const config = resolveClerkConfig();
+        return config.defaultType ?? 'mandate';
+    }
+    function buildWhereClause(filters) {
+        const conditions = [];
+        if (filters?.status) {
+            conditions.push(['status', '=', filters.status]);
+        }
+        if (filters?.type) {
+            conditions.push(['type', '=', filters.type]);
+        }
+        return conditions.length > 0 ? conditions : undefined;
+    }
+    // ── API ──────────────────────────────────────────────────────────
+    const api = {
+        async post(request) {
+            const type = request.type ?? resolveDefaultType();
+            const validTypes = resolveWritTypes();
+            if (!validTypes.has(type)) {
+                throw new Error(`Unknown writ type "${type}". Declared types: ${[...validTypes].join(', ')}.`);
+            }
+            const now = new Date().toISOString();
+            const writ = {
+                id: generateId('w', 6),
+                type,
+                status: 'ready',
+                title: request.title,
+                body: request.body,
+                ...(request.codex !== undefined ? { codex: request.codex } : {}),
+                createdAt: now,
+                updatedAt: now,
+            };
+            await writs.put(writ);
+            return writ;
+        },
+        async show(id) {
+            const writ = await writs.get(id);
+            if (!writ) {
+                throw new Error(`Writ "${id}" not found.`);
+            }
+            return writ;
+        },
+        async list(filters) {
+            const where = buildWhereClause(filters);
+            const limit = filters?.limit ?? 20;
+            const offset = filters?.offset;
+            return writs.find({
+                where,
+                orderBy: ['createdAt', 'desc'],
+                limit,
+                ...(offset !== undefined ? { offset } : {}),
+            });
+        },
+        async count(filters) {
+            const where = buildWhereClause(filters);
+            return writs.count(where);
+        },
+        async transition(id, to, fields) {
+            const writ = await writs.get(id);
+            if (!writ) {
+                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(', ')}.`);
+            }
+            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, acceptedAt: _a, resolvedAt: _r, ...safeFields } = (fields ?? {});
+            const patch = {
+                status: to,
+                updatedAt: now,
+                ...(to === 'active' ? { acceptedAt: now } : {}),
+                ...(isTerminal ? { resolvedAt: now } : {}),
+                ...safeFields,
+            };
+            return writs.patch(id, patch);
+        },
+    };
+    // ── Apparatus ────────────────────────────────────────────────────
+    return {
+        apparatus: {
+            requires: ['stacks'],
+            supportKit: {
+                books: {
+                    writs: {
+                        indexes: ['status', 'type', 'createdAt', ['status', 'type'], ['status', 'createdAt']],
+                    },
+                },
+                tools: [
+                    commissionPost,
+                    writShow,
+                    writList,
+                    writAccept,
+                    writComplete,
+                    writFail,
+                    writCancel,
+                ],
+            },
+            provides: api,
+            start(_ctx) {
+                const stacks = guild().apparatus('stacks');
+                writs = stacks.book('clerk', 'writs');
+            },
+        },
+    };
+}
+//# sourceMappingURL=clerk.js.map

package/dist/clerk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clerk.js","sourceRoot":"","sources":["../src/clerk.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @shardworks/clerk-apparatus — The Clerk.
+ *
+ * Writ lifecycle management: post commissions, accept work, complete or fail
+ * writs, and cancel them at any pre-terminal stage. Writs flow through a fixed
+ * status machine and are persisted in The Stacks.
+ *
+ * See: docs/architecture/apparatus/clerk.md
+ */
+export { type ClerkApi, type ClerkConfig, type WritTypeEntry, type WritDoc, type WritStatus, type PostCommissionRequest, type WritFilters, } from './types.ts';
+export { createClerk } from './clerk.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;;;;;;;;GAQG;AAMH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;;AAIzC,wBAA6B"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @shardworks/clerk-apparatus — The Clerk.
+ *
+ * Writ lifecycle management: post commissions, accept work, complete or fail
+ * writs, and cancel them at any pre-terminal stage. Writs flow through a fixed
+ * status machine and are persisted in The Stacks.
+ *
+ * See: docs/architecture/apparatus/clerk.md
+ */
+import { createClerk } from "./clerk.js";
+// ── Clerk API ─────────────────────────────────────────────────────────
+export {} from "./types.js";
+export { createClerk } from "./clerk.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createClerk();
+//# 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;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,yEAAyE;AAEzE,OAAO,EAQN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,yEAAyE;AAEzE,eAAe,WAAW,EAAE,CAAC"}

package/dist/tools/commission-post.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    title: z.ZodString;
+    body: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    codex: z.ZodOptional<z.ZodString>;
+}>;
+export default _default;
+//# sourceMappingURL=commission-post.d.ts.map

package/dist/tools/commission-post.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commission-post.d.ts","sourceRoot":"","sources":["../../src/tools/commission-post.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;AAKxB,wBAuBG"}

package/dist/tools/commission-post.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'commission-post',
+    description: 'Post a new commission, creating a writ in ready status',
+    instructions: 'Creates a new writ and places it in ready status awaiting acceptance. ' +
+        'The writ type must be a type declared in the guild config, or the built-in type "mandate". ' +
+        'If type is omitted, the guild\'s configured default type is used (defaults to "mandate").',
+    params: {
+        title: z.string().describe('Short human-readable title describing the work'),
+        body: z.string().describe('Detail text or description'),
+        type: z.string().optional().describe('Writ type (default: guild defaultType or "mandate")'),
+        codex: z.string().optional().describe('Target codex name'),
+    },
+    permission: 'clerk:write',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.post({
+            title: params.title,
+            body: params.body,
+            type: params.type,
+            codex: params.codex,
+        });
+    },
+});
+//# sourceMappingURL=commission-post.js.map

package/dist/tools/commission-post.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commission-post.js","sourceRoot":"","sources":["../../src/tools/commission-post.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,wDAAwD;IACrE,YAAY,EACV,wEAAwE;QACxE,6FAA6F;QAC7F,2FAA2F;IAC7F,MAAM,EAAE;QACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QAC5E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;QACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;QAC3F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;KAC3D;IACD,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,8 @@
+export { default as commissionPost } from './commission-post.ts';
+export { default as writShow } from './writ-show.ts';
+export { default as writList } from './writ-list.ts';
+export { default as writAccept } from './writ-accept.ts';
+export { default as writComplete } from './writ-complete.ts';
+export { default as writFail } from './writ-fail.ts';
+export { default as writCancel } from './writ-cancel.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,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,8 @@
+export { default as commissionPost } from "./commission-post.js";
+export { default as writShow } from "./writ-show.js";
+export { default as writList } from "./writ-list.js";
+export { default as writAccept } from "./writ-accept.js";
+export { default as writComplete } from "./writ-complete.js";
+export { default as writFail } from "./writ-fail.js";
+export { default as writCancel } from "./writ-cancel.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,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tools/writ-accept.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    id: z.ZodString;
+}>;
+export default _default;
+//# sourceMappingURL=writ-accept.d.ts.map

package/dist/tools/writ-accept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-accept.d.ts","sourceRoot":"","sources":["../../src/tools/writ-accept.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;AAKxB,wBAeG"}

package/dist/tools/writ-accept.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-accept',
+    description: 'Accept a writ, transitioning it from ready to active',
+    instructions: 'Accepts the writ, signalling that work has begun. ' +
+        'Only writs in ready status can be accepted. ' +
+        'Returns the updated writ.',
+    params: {
+        id: z.string().describe('Writ id'),
+    },
+    permission: 'clerk:write',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.transition(params.id, 'active');
+    },
+});
+//# sourceMappingURL=writ-accept.js.map

package/dist/tools/writ-accept.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-accept.js","sourceRoot":"","sources":["../../src/tools/writ-accept.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,sDAAsD;IACnE,YAAY,EACV,oDAAoD;QACpD,8CAA8C;QAC9C,2BAA2B;IAC7B,MAAM,EAAE;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;KACnC;IACD,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/writ-cancel.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    id: z.ZodString;
+    resolution: z.ZodOptional<z.ZodString>;
+}>;
+export default _default;
+//# sourceMappingURL=writ-cancel.d.ts.map

package/dist/tools/writ-cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-cancel.d.ts","sourceRoot":"","sources":["../../src/tools/writ-cancel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAKxB,wBAoBG"}

package/dist/tools/writ-cancel.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-cancel',
+    description: 'Cancel a writ, transitioning it from ready or active to cancelled',
+    instructions: 'Cancels the writ. Both ready and active writs can be cancelled. ' +
+        'Optionally record a resolution explaining why. ' +
+        'Returns the updated writ.',
+    params: {
+        id: z.string().describe('Writ id'),
+        resolution: z.string().optional().describe('Optional summary of why the writ was cancelled'),
+    },
+    permission: 'clerk:write',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.transition(params.id, 'cancelled', params.resolution !== undefined ? { resolution: params.resolution } : undefined);
+    },
+});
+//# sourceMappingURL=writ-cancel.js.map

package/dist/tools/writ-cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-cancel.js","sourceRoot":"","sources":["../../src/tools/writ-cancel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,mEAAmE;IAChF,YAAY,EACV,kEAAkE;QAClE,iDAAiD;QACjD,2BAA2B;IAC7B,MAAM,EAAE;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;KAC7F;IACD,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,UAAU,CACrB,MAAM,CAAC,EAAE,EACT,WAAW,EACX,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAChF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/writ-complete.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    id: z.ZodString;
+    resolution: z.ZodString;
+}>;
+export default _default;
+//# sourceMappingURL=writ-complete.d.ts.map

package/dist/tools/writ-complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-complete.d.ts","sourceRoot":"","sources":["../../src/tools/writ-complete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAKxB,wBAgBG"}

package/dist/tools/writ-complete.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-complete',
+    description: 'Complete a writ, transitioning it from active to completed',
+    instructions: 'Marks the writ as successfully completed. ' +
+        'Only writs in active status can be completed. ' +
+        'Returns the updated writ.',
+    params: {
+        id: z.string().describe('Writ id'),
+        resolution: z.string().describe('Summary of how the writ was completed'),
+    },
+    permission: 'clerk:write',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.transition(params.id, 'completed', { resolution: params.resolution });
+    },
+});
+//# sourceMappingURL=writ-complete.js.map

package/dist/tools/writ-complete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-complete.js","sourceRoot":"","sources":["../../src/tools/writ-complete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,4DAA4D;IACzE,YAAY,EACV,4CAA4C;QAC5C,gDAAgD;QAChD,2BAA2B;IAC7B,MAAM,EAAE;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;KACzE;IACD,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACrF,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/writ-fail.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    id: z.ZodString;
+    resolution: z.ZodString;
+}>;
+export default _default;
+//# sourceMappingURL=writ-fail.d.ts.map

package/dist/tools/writ-fail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-fail.d.ts","sourceRoot":"","sources":["../../src/tools/writ-fail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAKxB,wBAgBG"}

package/dist/tools/writ-fail.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-fail',
+    description: 'Fail a writ, transitioning it from active to failed',
+    instructions: 'Marks the writ as failed. Record a resolution explaining why it failed. ' +
+        'Only writs in active status can be failed. ' +
+        'Returns the updated writ.',
+    params: {
+        id: z.string().describe('Writ id'),
+        resolution: z.string().describe('Summary of why the writ failed'),
+    },
+    permission: 'clerk:write',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.transition(params.id, 'failed', { resolution: params.resolution });
+    },
+});
+//# sourceMappingURL=writ-fail.js.map

package/dist/tools/writ-fail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-fail.js","sourceRoot":"","sources":["../../src/tools/writ-fail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,qDAAqD;IAClE,YAAY,EACV,0EAA0E;QAC1E,6CAA6C;QAC7C,2BAA2B;IAC7B,MAAM,EAAE;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KAClE;IACD,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAClF,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/writ-list.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    status: z.ZodOptional<z.ZodEnum<{
+        ready: "ready";
+        active: "active";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>>;
+    type: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}>;
+export default _default;
+//# sourceMappingURL=writ-list.d.ts.map

package/dist/tools/writ-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-list.d.ts","sourceRoot":"","sources":["../../src/tools/writ-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;;;;;;;AAKxB,wBAyBG"}

package/dist/tools/writ-list.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-list',
+    description: 'List writs with optional filters',
+    instructions: 'Returns writ summaries ordered by createdAt descending (newest first). ' +
+        'Filter by status or type to narrow results.',
+    params: {
+        status: z
+            .enum(['ready', 'active', 'completed', 'failed', 'cancelled'])
+            .optional()
+            .describe('Filter by writ status'),
+        type: z.string().optional().describe('Filter by writ type'),
+        limit: z.number().optional().default(20).describe('Maximum results (default: 20)'),
+        offset: z.number().optional().describe('Number of results to skip'),
+    },
+    permission: 'clerk:read',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.list({
+            status: params.status,
+            type: params.type,
+            limit: params.limit,
+            offset: params.offset,
+        });
+    },
+});
+//# sourceMappingURL=writ-list.js.map

package/dist/tools/writ-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-list.js","sourceRoot":"","sources":["../../src/tools/writ-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,kCAAkC;IAC/C,YAAY,EACV,yEAAyE;QACzE,6CAA6C;IAC/C,MAAM,EAAE;QACN,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;aAC7D,QAAQ,EAAE;aACV,QAAQ,CAAC,uBAAuB,CAAC;QACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QAC3D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,+BAA+B,CAAC;QAClF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;KACpE;IACD,UAAU,EAAE,YAAY;IACxB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC;YAChB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/writ-show.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/tools-apparatus").ToolDefinition<{
+    id: z.ZodString;
+}>;
+export default _default;
+//# sourceMappingURL=writ-show.d.ts.map

package/dist/tools/writ-show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-show.d.ts","sourceRoot":"","sources":["../../src/tools/writ-show.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;AAKxB,wBAYG"}

package/dist/tools/writ-show.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+export default tool({
+    name: 'writ-show',
+    description: 'Show full detail for a writ',
+    instructions: 'Returns the complete writ record including its current status, timestamps, body text, and resolution.',
+    params: {
+        id: z.string().describe('Writ id'),
+    },
+    permission: 'clerk:read',
+    handler: async (params) => {
+        const clerk = guild().apparatus('clerk');
+        return clerk.show(params.id);
+    },
+});
+//# sourceMappingURL=writ-show.js.map

package/dist/tools/writ-show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writ-show.js","sourceRoot":"","sources":["../../src/tools/writ-show.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,6BAA6B;IAC1C,YAAY,EAAE,uGAAuG;IACrH,MAAM,EAAE;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;KACnC;IACD,UAAU,EAAE,YAAY;IACxB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,SAAS,CAAW,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Clerk public types.
+ *
+ * All types exported from @shardworks/clerk-apparatus.
+ */
+/**
+ * A writ's position in its lifecycle.
+ *
+ * Transitions:
+ *   ready → active (accept)
+ *   active → completed (complete)
+ *   active → failed (fail)
+ *   ready | active → cancelled (cancel)
+ *
+ * completed, failed, cancelled are terminal — no further transitions.
+ */
+export type WritStatus = 'ready' | 'active' | 'completed' | 'failed' | 'cancelled';
+/**
+ * A writ document as stored in The Stacks.
+ */
+export interface WritDoc {
+    /** Index signature required to satisfy BookEntry constraint. */
+    [key: string]: unknown;
+    /** Unique writ id (`w-{base36_timestamp}{hex_random}`). Sortable by creation time. */
+    id: string;
+    /** Writ type — must be a type declared in guild config, or a built-in type. */
+    type: string;
+    /** Current lifecycle status. */
+    status: WritStatus;
+    /** Short human-readable title. */
+    title: string;
+    /** Detail text. */
+    body: string;
+    /** Target codex name. */
+    codex?: string;
+    /** ISO timestamp when the writ was created. */
+    createdAt: string;
+    /** ISO timestamp of the last mutation. */
+    updatedAt: string;
+    /** ISO timestamp when the writ was accepted (transitioned to active). */
+    acceptedAt?: string;
+    /** ISO timestamp when the writ reached a terminal state. */
+    resolvedAt?: string;
+    /** Summary of how the writ resolved (set on any terminal transition). */
+    resolution?: string;
+}
+/**
+ * Request to post a new commission (create a writ).
+ */
+export interface PostCommissionRequest {
+    /**
+     * Writ type. Defaults to the guild's configured defaultType, or "mandate"
+     * if no default is configured. Must be a valid declared type.
+     */
+    type?: string;
+    /** Short human-readable title describing the work. */
+    title: string;
+    /** Detail text. */
+    body: string;
+    /** Optional target codex name. */
+    codex?: string;
+}
+/**
+ * Filters for listing writs.
+ */
+export interface WritFilters {
+    /** Filter by status. */
+    status?: WritStatus;
+    /** Filter by writ type. */
+    type?: string;
+    /** Maximum number of results (default: 20). */
+    limit?: number;
+    /** Number of results to skip. */
+    offset?: number;
+}
+/**
+ * A writ type entry declared in clerk config.
+ */
+export interface WritTypeEntry {
+    /** The writ type name (e.g. "mandate", "task", "bug"). */
+    name: string;
+    /** Optional human-readable description of this writ type. */
+    description?: string;
+}
+/**
+ * Clerk apparatus configuration — lives under the `clerk` key in guild.json.
+ */
+export interface ClerkConfig {
+    /** Additional writ type declarations. The built-in type "mandate" is always valid. */
+    writTypes?: WritTypeEntry[];
+    /** Default writ type when commission-post is called without a type (default: "mandate"). */
+    defaultType?: string;
+}
+declare module '@shardworks/nexus-core' {
+    interface GuildConfig {
+        clerk?: ClerkConfig;
+    }
+}
+/**
+ * The Clerk's runtime API — retrieved via guild().apparatus<ClerkApi>('clerk').
+ */
+export interface ClerkApi {
+    /**
+     * Post a new commission, creating a writ in 'ready' status.
+     * Validates the writ type against declared types in guild config.
+     */
+    post(request: PostCommissionRequest): Promise<WritDoc>;
+    /**
+     * Show a writ by id. Throws if not found.
+     */
+    show(id: string): Promise<WritDoc>;
+    /**
+     * List writs with optional filters, ordered by createdAt descending.
+     */
+    list(filters?: WritFilters): Promise<WritDoc[]>;
+    /**
+     * Count writs matching optional filters.
+     */
+    count(filters?: WritFilters): Promise<number>;
+    /**
+     * Transition a writ to a new status, optionally setting additional fields.
+     * Validates that the transition is legal.
+     */
+    transition(id: string, to: WritStatus, fields?: Partial<WritDoc>): Promise<WritDoc>;
+}
+//# 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;;;;GAIG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAInF;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,gEAAgE;IAChE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,WAAW;QACnB,KAAK,CAAC,EAAE,WAAW,CAAC;KACrB;CACF;AAID;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvD;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEhD;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9C;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrF"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Clerk public types.
+ *
+ * All types exported from @shardworks/clerk-apparatus.
+ */
+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;;;;GAIG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@shardworks/clerk-apparatus",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/clerk"
+  },
+  "description": "The Clerk — writ lifecycle management apparatus",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@shardworks/nexus-core": "0.1.101",
+    "@shardworks/tools-apparatus": "0.1.101",
+    "@shardworks/stacks-apparatus": "0.1.101"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}