@skillstate/core 2.0.7 → 2.1.0

package/dist/adapter-shared.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @non-paper Wave-5 shared adapter plumbing — the SINGLE SOURCE OF TRUTH
+ * for the state-path resolution, atomic persistence, and hooks-merge
+ * mechanics that were duplicated across the platform adapters (claude,
+ * codex). Adapters stay EVENT TABLES + brand constants + script/config
+ * generators; everything below is host-agnostic:
+ *
+ * - {@link resolveTarget}: the `string | StatePathRef` resolution every
+ *   adapter save/generate methods shared (throws on `..` traversal);
+ * - {@link saveGenerated}: resolve + `atomicWriteFile` + return the dest —
+ *   the body of every adapter `save` method;
+ * - {@link mergeHookGroups}: the hooks.json / settings.json merge —
+ *   idempotent by skillstate commands, appends fresh groups, preserves
+ *   every foreign group and top-level key. Format specifics (which groups
+ *   to generate, which commands are "ours") are passed in by the adapter.
+ */
+import type { StatePathRef } from './atomic-write.js';
+/**
+ * Resolve a `string | StatePathRef` target via `resolveStatePath` — the
+ * exact logic every adapter's private `resolve` helper shared. Raw strings
+ * pass through; `{ root, name }` refs are confined to `root` (traversal
+ * throws).
+ */
+export declare function resolveTarget(target: string | StatePathRef): string;
+/**
+ * Persist adapter-generated content to `target` via `atomicWriteFile`
+ * (temp sibling + fsync + rename) and return the absolute destination
+ * path. The shared body of the adapter `save*` methods.
+ */
+export declare function saveGenerated(target: string | StatePathRef, content: string): Promise<string>;
+/** Parameters for {@link mergeHookGroups} (the adapter-provided specifics). */
+export interface MergeHookGroupsParams {
+    /** The existing hooks document text (hooks.json / settings.json). */
+    existingJson: string;
+    /** The adapter-generated `{ Event: [group, …] }` groups to append. */
+    generatedGroups: Record<string, unknown[]>;
+    /**
+     * JSON-stringified skillstate commands (one per generated event script)
+     * — a handler whose stringified `command` is in this set marks the
+     * document as already wired.
+     */
+    commandsOf: ReadonlySet<string>;
+}
+/**
+ * Merge the skillstate hook groups into an existing hooks document — the
+ * shared mechanics of the claude and codex `mergeHooksConfig` methods:
+ *
+ * - malformed/empty/non-object input starts from a fresh document (the
+ *   CLI guards a live config before calling);
+ * - idempotent: if ANY skillstate command is already wired, the ORIGINAL
+ *   text is returned byte-unchanged (no re-serialization, no duplicate
+ *   groups, no surprise reformatting of a hand-written file);
+ * - otherwise every generated group is APPENDED per event: existing
+ *   (non-skillstate) groups and every other top-level key survive, and a
+ *   non-array event value is replaced by the fresh group.
+ *
+ * Returns the merged document re-serialized (2-space indent, newline-
+ * terminated) — or the untouched input on the already-wired path.
+ */
+export declare function mergeHookGroups({ existingJson, generatedGroups, commandsOf, }: MergeHookGroupsParams): string;
+//# sourceMappingURL=adapter-shared.d.ts.map

package/dist/adapter-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-shared.d.ts","sourceRoot":"","sources":["../src/adapter-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,CAInE;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C;;;;OAIG;IACH,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,EAC9B,YAAY,EACZ,eAAe,EACf,UAAU,GACX,EAAE,qBAAqB,GAAG,MAAM,CAoChC"}

package/dist/adapter-shared.js

@@ -0,0 +1,96 @@
+/**
+ * @non-paper Wave-5 shared adapter plumbing — the SINGLE SOURCE OF TRUTH
+ * for the state-path resolution, atomic persistence, and hooks-merge
+ * mechanics that were duplicated across the platform adapters (claude,
+ * codex). Adapters stay EVENT TABLES + brand constants + script/config
+ * generators; everything below is host-agnostic:
+ *
+ * - {@link resolveTarget}: the `string | StatePathRef` resolution every
+ *   adapter save/generate methods shared (throws on `..` traversal);
+ * - {@link saveGenerated}: resolve + `atomicWriteFile` + return the dest —
+ *   the body of every adapter `save` method;
+ * - {@link mergeHookGroups}: the hooks.json / settings.json merge —
+ *   idempotent by skillstate commands, appends fresh groups, preserves
+ *   every foreign group and top-level key. Format specifics (which groups
+ *   to generate, which commands are "ours") are passed in by the adapter.
+ */
+import { atomicWriteFile, resolveStatePath } from './atomic-write.js';
+import { isPlainObject } from './hook-runtime.js';
+/**
+ * Resolve a `string | StatePathRef` target via `resolveStatePath` — the
+ * exact logic every adapter's private `resolve` helper shared. Raw strings
+ * pass through; `{ root, name }` refs are confined to `root` (traversal
+ * throws).
+ */
+export function resolveTarget(target) {
+    return typeof target === 'string'
+        ? target
+        : resolveStatePath(target.root, target.name);
+}
+/**
+ * Persist adapter-generated content to `target` via `atomicWriteFile`
+ * (temp sibling + fsync + rename) and return the absolute destination
+ * path. The shared body of the adapter `save*` methods.
+ */
+export async function saveGenerated(target, content) {
+    const dest = resolveTarget(target);
+    await atomicWriteFile(dest, content);
+    return dest;
+}
+/**
+ * Merge the skillstate hook groups into an existing hooks document — the
+ * shared mechanics of the claude and codex `mergeHooksConfig` methods:
+ *
+ * - malformed/empty/non-object input starts from a fresh document (the
+ *   CLI guards a live config before calling);
+ * - idempotent: if ANY skillstate command is already wired, the ORIGINAL
+ *   text is returned byte-unchanged (no re-serialization, no duplicate
+ *   groups, no surprise reformatting of a hand-written file);
+ * - otherwise every generated group is APPENDED per event: existing
+ *   (non-skillstate) groups and every other top-level key survive, and a
+ *   non-array event value is replaced by the fresh group.
+ *
+ * Returns the merged document re-serialized (2-space indent, newline-
+ * terminated) — or the untouched input on the already-wired path.
+ */
+export function mergeHookGroups({ existingJson, generatedGroups, commandsOf, }) {
+    let doc = {};
+    try {
+        doc = JSON.parse(existingJson);
+    }
+    catch {
+        // Missing or malformed input: start from a fresh document.
+    }
+    if (!isPlainObject(doc)) {
+        doc = {};
+    }
+    if (!isPlainObject(doc['hooks'])) {
+        doc['hooks'] = {};
+    }
+    const hooks = doc['hooks'];
+    let alreadyWired = false;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isPlainObject(group) || !Array.isArray(group['hooks']))
+                continue;
+            for (const handler of group['hooks']) {
+                if (isPlainObject(handler) && commandsOf.has(JSON.stringify(handler['command']))) {
+                    alreadyWired = true;
+                }
+            }
+        }
+    }
+    if (alreadyWired) {
+        return existingJson;
+    }
+    for (const [event, groups] of Object.entries(generatedGroups)) {
+        const existing = Array.isArray(hooks[event])
+            ? hooks[event]
+            : [];
+        hooks[event] = [...existing, ...groups];
+    }
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+//# sourceMappingURL=adapter-shared.js.map

package/dist/adapter-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-shared.js","sourceRoot":"","sources":["../src/adapter-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAA6B;IACzD,OAAO,OAAO,MAAM,KAAK,QAAQ;QAC/B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA6B,EAC7B,OAAe;IAEf,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,YAAY,EACZ,eAAe,EACf,UAAU,GACY;IACtB,IAAI,GAAG,GAA4B,EAAE,CAAC;IACtC,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAe,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,GAAG,GAAG,EAAE,CAAC;IACX,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAA4B,CAAC;IACtD,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAAE,SAAS;YACtE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjF,YAAY,GAAG,IAAI,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9D,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC,CAAE,KAAK,CAAC,KAAK,CAAe;YAC7B,CAAC,CAAC,EAAE,CAAC;QACP,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/hook-runtime.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @non-paper Wave-5 hook runtime — the SINGLE SOURCE OF TRUTH for every
+ * piece of logic embedded into self-contained generated hook scripts
+ * (Claude Code `.cjs` hooks, Codex `.cjs` hooks) and reused directly by
+ * the OpenCode plugin.
+ *
+ * CONSTRAINT: the generated scripts cannot import `@skillstate/*`, so the
+ * adapters inline these functions into the emitted `.cjs` via
+ * `fn.toString()` (see {@link hookRuntimeSnippet}). That means every
+ * function body below must be PLAIN JavaScript:
+ *
+ * - no imports and no `require` — dependencies are passed as parameters
+ *   (`readFile`, `writeFile`, `home`), so the caller wires the real
+ *   `node:fs`/`node:os`/`node:path` (or test mocks) at the call site;
+ * - type annotations live ONLY in the signatures — both `tsc` (dist) and
+ *   the vitest/esbuild transform erase them, so `fn.toString()` yields a
+ *   valid CJS snippet;
+ * - no references to module-scope helpers — each function is either fully
+ *   self-contained or calls only its sibling functions from this module
+ *   (which the snippet inlines together).
+ *
+ * The parity suite (`tests/core/hook-runtime-parity.test.ts`) evals the
+ * snippets extracted from the generated scripts and asserts byte-identical
+ * behavior against these originals, so the "embedded copy" can no longer
+ * drift from the source of truth.
+ */
+/** True for plain (non-null, non-array) objects. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Resolve the per-project state file for a working directory — the pure,
+ * dependency-free mirror of `resolveHostStateForCwd`
+ * (`<cwd>/.skillstate/skillstate.json`; the global bucket
+ * `<home>/.skillstate/global/skillstate.json` when cwd equals home).
+ *
+ * String arithmetic only (POSIX): absolute paths are normalized like
+ * `path.resolve` (empty/`.` segments dropped, `..` popped, trailing
+ * slashes trimmed); relative inputs stay relative because there is no
+ * `process` access. Callers that may see relative paths resolve them
+ * first (`path.resolve(cwd)`) — the generated hook scripts do exactly
+ * that. `home` must be provided to detect the global bucket; when it is
+ * omitted the project path is returned.
+ */
+export declare function resolveStatePathForCwd(cwd: string, home?: string): string;
+/**
+ * Read the state file through the injected `readFile` (real `fs` in
+ * generated scripts, mocks in tests). The on-disk envelope is
+ * `{ version: 1, state }`; a bare object is tolerated and treated as the
+ * state itself; anything else (missing file, corrupt JSON, arrays,
+ * scalars) yields `{}` — best-effort, never throws.
+ */
+export declare function readStateEnvelope(statePath: string, readFile: (p: string) => string): unknown;
+/**
+ * Persist the state through the injected `writeFile` as the
+ * `{ version: 1, state }` envelope (pretty-printed, newline-terminated).
+ * Throws on failure — the caller decides whether to swallow it (OpenCode
+ * plugin) or surface a `systemMessage` (PostToolUse hooks).
+ */
+export declare function saveStateEnvelope(statePath: string, state: object, writeFile: (p: string, data: string) => void): void;
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces. Pure — neither `state` nor
+ * `patch` is mutated.
+ */
+export declare function mergePatch(state: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Coerce a tool response into text: strings pass through, plain objects
+ * expose their `content` then `text` string field, other objects are
+ * JSON-stringified, null/undefined becomes `""`, everything else is
+ * `String()`-ed.
+ */
+export declare function readResponseText(response: unknown): string;
+/** Outcome of the patch extractors: a patch, an invalid attempt, or nothing. */
+export type PatchLookup = {
+    patch: Record<string, unknown>;
+} | {
+    invalid: true;
+} | {
+    absent: true;
+};
+/**
+ * Look for a fenced ```json block: `{ patch }` when it parses and carries
+ * an object-shaped `state_patch`, `{ invalid: true }` when a block exists
+ * but is malformed (an open fence that never closes — truncated output —
+ * is still a patch attempt and classifies as invalid), `{ absent: true }`
+ * when there is no block at all.
+ */
+export declare function findFencedPatch(text: string): PatchLookup;
+/**
+ * Fallback: a raw JSON object with `state_patch` anywhere in the text
+ * (first `{` … last `}`). Ordinary JSON output without a `state_patch`
+ * key is simply not a patch (`{ absent: true }`); a `state_patch` key
+ * holding a non-object is an invalid attempt.
+ */
+export declare function findRawPatch(text: string): PatchLookup;
+/**
+ * Assemble the CJS snippet embedded into every generated hook script:
+ * all sibling functions of this module, source-verbatim via
+ * `fn.toString()`. The adapters splice this block after their `require`
+ * preamble, which keeps the embedded logic byte-identical across hosts
+ * and impossible to drift from this module.
+ */
+export declare function hookRuntimeSnippet(): string;
+//# sourceMappingURL=hook-runtime.d.ts.map

package/dist/hook-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBzE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAaT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA4BtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C"}

package/dist/hook-runtime.js

@@ -0,0 +1,224 @@
+/**
+ * @non-paper Wave-5 hook runtime — the SINGLE SOURCE OF TRUTH for every
+ * piece of logic embedded into self-contained generated hook scripts
+ * (Claude Code `.cjs` hooks, Codex `.cjs` hooks) and reused directly by
+ * the OpenCode plugin.
+ *
+ * CONSTRAINT: the generated scripts cannot import `@skillstate/*`, so the
+ * adapters inline these functions into the emitted `.cjs` via
+ * `fn.toString()` (see {@link hookRuntimeSnippet}). That means every
+ * function body below must be PLAIN JavaScript:
+ *
+ * - no imports and no `require` — dependencies are passed as parameters
+ *   (`readFile`, `writeFile`, `home`), so the caller wires the real
+ *   `node:fs`/`node:os`/`node:path` (or test mocks) at the call site;
+ * - type annotations live ONLY in the signatures — both `tsc` (dist) and
+ *   the vitest/esbuild transform erase them, so `fn.toString()` yields a
+ *   valid CJS snippet;
+ * - no references to module-scope helpers — each function is either fully
+ *   self-contained or calls only its sibling functions from this module
+ *   (which the snippet inlines together).
+ *
+ * The parity suite (`tests/core/hook-runtime-parity.test.ts`) evals the
+ * snippets extracted from the generated scripts and asserts byte-identical
+ * behavior against these originals, so the "embedded copy" can no longer
+ * drift from the source of truth.
+ */
+/** True for plain (non-null, non-array) objects. */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolve the per-project state file for a working directory — the pure,
+ * dependency-free mirror of `resolveHostStateForCwd`
+ * (`<cwd>/.skillstate/skillstate.json`; the global bucket
+ * `<home>/.skillstate/global/skillstate.json` when cwd equals home).
+ *
+ * String arithmetic only (POSIX): absolute paths are normalized like
+ * `path.resolve` (empty/`.` segments dropped, `..` popped, trailing
+ * slashes trimmed); relative inputs stay relative because there is no
+ * `process` access. Callers that may see relative paths resolve them
+ * first (`path.resolve(cwd)`) — the generated hook scripts do exactly
+ * that. `home` must be provided to detect the global bucket; when it is
+ * omitted the project path is returned.
+ */
+export function resolveStatePathForCwd(cwd, home) {
+    const normalize = (p) => {
+        const isAbsolute = p.startsWith('/');
+        const segments = [];
+        for (const segment of p.split('/')) {
+            if (segment === '' || segment === '.')
+                continue;
+            if (segment === '..') {
+                if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+                    segments.pop();
+                }
+                else if (!isAbsolute) {
+                    segments.push('..');
+                }
+                continue;
+            }
+            segments.push(segment);
+        }
+        return (isAbsolute ? '/' : '') + segments.join('/');
+    };
+    const rootless = (p) => (p === '/' ? '' : p);
+    const resolvedCwd = normalize(cwd);
+    const resolvedHome = home === undefined || home === null ? '' : normalize(home);
+    if (resolvedCwd === resolvedHome) {
+        return `${rootless(resolvedHome)}/.skillstate/global/skillstate.json`;
+    }
+    return `${rootless(resolvedCwd)}/.skillstate/skillstate.json`;
+}
+/**
+ * Read the state file through the injected `readFile` (real `fs` in
+ * generated scripts, mocks in tests). The on-disk envelope is
+ * `{ version: 1, state }`; a bare object is tolerated and treated as the
+ * state itself; anything else (missing file, corrupt JSON, arrays,
+ * scalars) yields `{}` — best-effort, never throws.
+ */
+export function readStateEnvelope(statePath, readFile) {
+    try {
+        const parsed = JSON.parse(readFile(statePath));
+        if (isPlainObject(parsed)) {
+            if (isPlainObject(parsed.state)) {
+                return parsed.state;
+            }
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt state file — fall back to the empty state.
+    }
+    return {};
+}
+/**
+ * Persist the state through the injected `writeFile` as the
+ * `{ version: 1, state }` envelope (pretty-printed, newline-terminated).
+ * Throws on failure — the caller decides whether to swallow it (OpenCode
+ * plugin) or surface a `systemMessage` (PostToolUse hooks).
+ */
+export function saveStateEnvelope(statePath, state, writeFile) {
+    writeFile(statePath, `${JSON.stringify({ version: 1, state }, null, 2)}\n`);
+}
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces. Pure — neither `state` nor
+ * `patch` is mutated.
+ */
+export function mergePatch(state, patch) {
+    const result = { ...state };
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === null) {
+            delete result[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergePatch(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Coerce a tool response into text: strings pass through, plain objects
+ * expose their `content` then `text` string field, other objects are
+ * JSON-stringified, null/undefined becomes `""`, everything else is
+ * `String()`-ed.
+ */
+export function readResponseText(response) {
+    if (typeof response === 'string')
+        return response;
+    if (isPlainObject(response)) {
+        if (typeof response['content'] === 'string')
+            return response['content'];
+        if (typeof response['text'] === 'string')
+            return response['text'];
+        return JSON.stringify(response);
+    }
+    return response === null || response === undefined ? '' : String(response);
+}
+/**
+ * Look for a fenced ```json block: `{ patch }` when it parses and carries
+ * an object-shaped `state_patch`, `{ invalid: true }` when a block exists
+ * but is malformed (an open fence that never closes — truncated output —
+ * is still a patch attempt and classifies as invalid), `{ absent: true }`
+ * when there is no block at all.
+ */
+export function findFencedPatch(text) {
+    const match = text.match(/```json\s*\n?([\s\S]*?)\n?\s*```/) ||
+        text.match(/```json\s*\n?([\s\S]+)$/);
+    if (!match)
+        return { absent: true };
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (isPlainObject(parsed) && isPlainObject(parsed['state_patch'])) {
+            return { patch: parsed['state_patch'] };
+        }
+    }
+    catch {
+        // Malformed fenced JSON — report an invalid patch attempt.
+    }
+    return { invalid: true };
+}
+/**
+ * Fallback: a raw JSON object with `state_patch` anywhere in the text
+ * (first `{` … last `}`). Ordinary JSON output without a `state_patch`
+ * key is simply not a patch (`{ absent: true }`); a `state_patch` key
+ * holding a non-object is an invalid attempt.
+ */
+export function findRawPatch(text) {
+    const trimmed = text.trim();
+    const candidates = [];
+    try {
+        candidates.push(JSON.parse(trimmed));
+    }
+    catch {
+        // Not a whole-text JSON object — try the braced slice below.
+    }
+    const first = trimmed.indexOf('{');
+    const last = trimmed.lastIndexOf('}');
+    if (first !== -1 && last > first) {
+        try {
+            candidates.push(JSON.parse(trimmed.slice(first, last + 1)));
+        }
+        catch {
+            // The braced slice is not JSON either — no candidates left.
+        }
+    }
+    for (const candidate of candidates) {
+        if (isPlainObject(candidate)) {
+            if (isPlainObject(candidate['state_patch'])) {
+                return { patch: candidate['state_patch'] };
+            }
+            if (Object.prototype.hasOwnProperty.call(candidate, 'state_patch')) {
+                return { invalid: true };
+            }
+        }
+    }
+    return { absent: true };
+}
+/**
+ * Assemble the CJS snippet embedded into every generated hook script:
+ * all sibling functions of this module, source-verbatim via
+ * `fn.toString()`. The adapters splice this block after their `require`
+ * preamble, which keeps the embedded logic byte-identical across hosts
+ * and impossible to drift from this module.
+ */
+export function hookRuntimeSnippet() {
+    return [
+        isPlainObject,
+        resolveStatePathForCwd,
+        readStateEnvelope,
+        saveStateEnvelope,
+        mergePatch,
+        readResponseText,
+        findFencedPatch,
+        findRawPatch,
+    ]
+        .map((fn) => fn.toString())
+        .join('\n\n');
+}
+//# sourceMappingURL=hook-runtime.js.map

package/dist/hook-runtime.js.map

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

package/dist/index.d.ts

@@ -16,6 +16,9 @@ export * from './logger.js';
 export * from './provider.js';
 export * from './config.js';
 export * from './host-state.js';
+export * from './hook-runtime.js';
+export * from './adapter-shared.js';
+export * from './prompt-contract.js';
 export * from './shutdown.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -24,6 +24,14 @@ export * from './logger.js';
 export * from './provider.js';
 export * from './config.js';
 export * from './host-state.js';
+// @non-paper Wave-5 hook runtime (single source of truth for generated
+// hook scripts and the OpenCode plugin).
+export * from './hook-runtime.js';
+// @non-paper Wave-5 shared adapter plumbing (resolve/save/merge helpers
+// reused by the claude/codex adapters).
+export * from './adapter-shared.js';
+// @non-paper Wave-5 deduplicated prompt texts (shared adapter vocabulary).
+export * from './prompt-contract.js';
 export * from './shutdown.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,uEAAuE;AACvE,yCAAyC;AACzC,cAAc,mBAAmB,CAAC;AAClC,wEAAwE;AACxE,wCAAwC;AACxC,cAAc,qBAAqB,CAAC;AACpC,2EAA2E;AAC3E,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/prompt-contract.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @non-paper Canonical prompt texts — the SINGLE SOURCE OF TRUTH for the
+ * {state_patch, action} JSON contract, the history-unreliability hint, the
+ * schema renderer, and the SKILL.md body shared by every platform adapter.
+ *
+ * PROMPT-FIDELITY BOUNDARY: `PromptTransformer.formatPaper` (Appendix A.4)
+ * is byte-verbatim paper text and deliberately does NOT use these
+ * constants — its inline `{ "state_patch": { <dict: ...> }, "action": ... }`
+ * directive differs from the fenced example below by design. Everything
+ * here is the @non-paper adapter vocabulary, deduplicated across
+ * claude/codex/opencode adapters and the prompt transformer.
+ */
+import type { ProceduralSpec, StateSchema } from './types.js';
+/**
+ * The two-key response directive (without the fenced example). Adapters
+ * prepend their own lead-in ("Based on your current state, provide your
+ * response with:" etc.) and append the numbered items via
+ * {@link STATE_PATCH_CONTRACT}.
+ */
+export declare const STATE_PATCH_CONTRACT_HEADER = "A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:";
+/** Canonical fenced ```json example block for the two-key contract. */
+export declare const STATE_PATCH_EXAMPLE_JSON: string;
+/** Canonical sparse-patch rules: null deletes, omissions leave state unchanged. */
+export declare const STATE_PATCH_RULES = "In `state_patch`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.";
+/**
+ * The reasoning-is-discarded persistence bullet (paper §3.2, §4): any fact
+ * that must survive belongs in `state_patch`, never in the conversation.
+ */
+export declare const REASONING_DISCARDED_NOTE = "Reasoning is discarded after execution \u2014 put anything you need to persist into `state_patch`.";
+/**
+ * The full numbered response contract: reasoning is discarded (paper §3.2),
+ * the JSON block carries exactly the two keys, and the patch follows the
+ * sparse ⊕ semantics. Includes the example block and the rules — no lead-in.
+ */
+export declare const STATE_PATCH_CONTRACT: string;
+/**
+ * The single history-unreliability hint appended to the additionalContext
+ * of every inject-style hook script (claude + codex alike). Names the MCP
+ * tools AND the fenced ```json state_patch channel — one text for all
+ * hosts, so the Bash-carried patch option can no longer drift away.
+ */
+export declare const HISTORY_UNRELIABLE_NOTE = "\nHistory is not reliable. Persist anything you need via the skillstate MCP tools (state.summary / state.patch) or a fenced ```json state_patch block.";
+/**
+ * Render a state schema as the shared `## Schema` markdown block used by
+ * every prompt formatter and adapter `injectState`. Fields without a
+ * description fall back to "no description".
+ */
+export declare function describeSchema(schema: StateSchema): string;
+/** Options for {@link skillMdBody}. */
+export interface SkillMdBodyOptions {
+    /** Brand label woven into the hooks intro ("Claude Code", "Codex"). */
+    hostLabel: string;
+    /**
+     * How the injected state reaches the model, as a predicate:
+     * "injected into your context via hooks" (claude) /
+     * "provided as developer context" (codex).
+     */
+    injectionPhrase: string;
+    /** The skill spec — name/instructions/version fill the frontmatter. */
+    spec: ProceduralSpec;
+    /** State path written into the frontmatter and the body (default `./.skillstate/skillstate.json`). */
+    statePath?: string;
+}
+/**
+ * Generate the whole SKILL.md document shared by the hook-wiring adapters
+ * (claude, codex): identical frontmatter, Execution Context, and Process
+ * sections; the ONLY brand-specific parts are `hostLabel` (hooks intro)
+ * and `injectionPhrase` (how the state reaches the model). OpenCode keeps
+ * its own body — its history is trimmed by the plugin, not by hooks, so
+ * its Execution Context and Process genuinely differ.
+ */
+export declare function skillMdBody(options: SkillMdBodyOptions): string;
+//# sourceMappingURL=prompt-contract.d.ts.map

package/dist/prompt-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-contract.d.ts","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oHAC2E,CAAC;AAEpH,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAOzB,CAAC;AAEb,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,oIACqG,CAAC;AAEpI;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uGAC4D,CAAC;AAElG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAOrB,CAAC;AAEb;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2JACsH,CAAC;AAE3J;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAQ1D;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,cAAc,CAAC;IACrB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAmD/D"}

package/dist/prompt-contract.js

@@ -0,0 +1,115 @@
+/**
+ * The two-key response directive (without the fenced example). Adapters
+ * prepend their own lead-in ("Based on your current state, provide your
+ * response with:" etc.) and append the numbered items via
+ * {@link STATE_PATCH_CONTRACT}.
+ */
+export const STATE_PATCH_CONTRACT_HEADER = 'A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:';
+/** Canonical fenced ```json example block for the two-key contract. */
+export const STATE_PATCH_EXAMPLE_JSON = [
+    '```json',
+    '{',
+    '  "state_patch": { "key": "new_value", "obsolete_key": null },',
+    '  "action": "your_action_here"',
+    '}',
+    '```',
+].join('\n');
+/** Canonical sparse-patch rules: null deletes, omissions leave state unchanged. */
+export const STATE_PATCH_RULES = 'In `state_patch`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.';
+/**
+ * The reasoning-is-discarded persistence bullet (paper §3.2, §4): any fact
+ * that must survive belongs in `state_patch`, never in the conversation.
+ */
+export const REASONING_DISCARDED_NOTE = 'Reasoning is discarded after execution — put anything you need to persist into `state_patch`.';
+/**
+ * The full numbered response contract: reasoning is discarded (paper §3.2),
+ * the JSON block carries exactly the two keys, and the patch follows the
+ * sparse ⊕ semantics. Includes the example block and the rules — no lead-in.
+ */
+export const STATE_PATCH_CONTRACT = [
+    '1. Step-by-step reasoning (will be discarded after execution)',
+    `2. ${STATE_PATCH_CONTRACT_HEADER}`,
+    '',
+    STATE_PATCH_EXAMPLE_JSON,
+    '',
+    STATE_PATCH_RULES,
+].join('\n');
+/**
+ * The single history-unreliability hint appended to the additionalContext
+ * of every inject-style hook script (claude + codex alike). Names the MCP
+ * tools AND the fenced ```json state_patch channel — one text for all
+ * hosts, so the Bash-carried patch option can no longer drift away.
+ */
+export const HISTORY_UNRELIABLE_NOTE = '\nHistory is not reliable. Persist anything you need via the skillstate MCP tools (state.summary / state.patch) or a fenced ```json state_patch block.';
+/**
+ * Render a state schema as the shared `## Schema` markdown block used by
+ * every prompt formatter and adapter `injectState`. Fields without a
+ * description fall back to "no description".
+ */
+export function describeSchema(schema) {
+    const fields = Object.entries(schema)
+        .map(([name, field]) => `- ${name} (${field.type}): ${field.description ?? 'no description'}`)
+        .join('\n');
+    return `## Schema\n${fields}`;
+}
+/**
+ * Generate the whole SKILL.md document shared by the hook-wiring adapters
+ * (claude, codex): identical frontmatter, Execution Context, and Process
+ * sections; the ONLY brand-specific parts are `hostLabel` (hooks intro)
+ * and `injectionPhrase` (how the state reaches the model). OpenCode keeps
+ * its own body — its history is trimmed by the plugin, not by hooks, so
+ * its Execution Context and Process genuinely differ.
+ */
+export function skillMdBody(options) {
+    const resolvedStatePath = options.statePath ?? './.skillstate/skillstate.json';
+    return [
+        '---',
+        `name: ${JSON.stringify(options.spec.name)}`,
+        `description: ${JSON.stringify(options.spec.instructions)}`,
+        `version: ${options.spec.version}`,
+        'execution_context:',
+        `  state_path: ${resolvedStatePath}`,
+        '  format: json',
+        '---',
+        '',
+        `# ${options.spec.name}`,
+        '',
+        options.spec.instructions,
+        '',
+        '## Execution Context',
+        '',
+        `Your execution state lives at \`${resolvedStatePath}\` (per project; a`,
+        'session started in $HOME uses `~/.skillstate/global/skillstate.json`).',
+        `The skillstate ${options.hostLabel} hooks:`,
+        '',
+        `- the CURRENT state is ${options.injectionPhrase} on every prompt submit`,
+        '  (`UserPromptSubmit`) and is re-injected after compaction',
+        '  (`SessionStart` matcher `^compact$`);',
+        '- watch every Bash tool result and merge a fenced ```json block carrying',
+        '  a `state_patch` into the state file (`PostToolUse`).',
+        '',
+        'The injected state is authoritative — history is not reliable. Never',
+        'reconstruct execution context from the conversation.',
+        '',
+        '## Process',
+        '',
+        '1. Orient yourself: read the injected state, or call the skillstate MCP',
+        '   tools `state.summary` (compact) / `state.get` (full dump).',
+        '2. Observe the result of your last action.',
+        '3. Reason about what to do next, given the state and the observation.',
+        '4. Persist progress with the skillstate MCP tool `state.patch` (sparse',
+        '   patch; set a key to `null` to delete it; dry-run first with',
+        '   `state.validate` when unsure; `state.diff` shows what changed since',
+        '   your last look), and/or emit a fenced JSON block with exactly two',
+        '   keys inside a Bash tool call so the `PostToolUse` hook merges it:',
+        '',
+        STATE_PATCH_EXAMPLE_JSON,
+        '',
+        `- ${STATE_PATCH_RULES}`,
+        '- Put anything you need to survive into `state_patch`; never rely on',
+        '  the conversation remembering it.',
+        '- `action` names what you will do next (e.g. "continue", "done").',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=prompt-contract.js.map

package/dist/prompt-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-contract.js","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GACtC,iHAAiH,CAAC;AAEpH,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,SAAS;IACT,GAAG;IACH,gEAAgE;IAChE,gCAAgC;IAChC,GAAG;IACH,KAAK;CACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,iIAAiI,CAAC;AAEpI;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,+FAA+F,CAAC;AAElG;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+DAA+D;IAC/D,MAAM,2BAA2B,EAAE;IACnC,EAAE;IACF,wBAAwB;IACxB,EAAE;IACF,iBAAiB;CAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAClC,wJAAwJ,CAAC;AAE3J;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAClC,GAAG,CACF,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAChB,KAAK,IAAI,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,WAAW,IAAI,gBAAgB,EAAE,CACxE;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,cAAc,MAAM,EAAE,CAAC;AAChC,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,IAAI,+BAA+B,CAAC;IAC/E,OAAO;QACL,KAAK;QACL,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC5C,gBAAgB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE;QAC3D,YAAY,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE;QAClC,oBAAoB;QACpB,iBAAiB,iBAAiB,EAAE;QACpC,gBAAgB;QAChB,KAAK;QACL,EAAE;QACF,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE;QACxB,EAAE;QACF,OAAO,CAAC,IAAI,CAAC,YAAY;QACzB,EAAE;QACF,sBAAsB;QACtB,EAAE;QACF,mCAAmC,iBAAiB,oBAAoB;QACxE,wEAAwE;QACxE,kBAAkB,OAAO,CAAC,SAAS,SAAS;QAC5C,EAAE;QACF,0BAA0B,OAAO,CAAC,eAAe,yBAAyB;QAC1E,4DAA4D;QAC5D,yCAAyC;QACzC,0EAA0E;QAC1E,wDAAwD;QACxD,EAAE;QACF,sEAAsE;QACtE,sDAAsD;QACtD,EAAE;QACF,YAAY;QACZ,EAAE;QACF,yEAAyE;QACzE,+DAA+D;QAC/D,4CAA4C;QAC5C,uEAAuE;QACvE,wEAAwE;QACxE,gEAAgE;QAChE,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,EAAE;QACF,wBAAwB;QACxB,EAAE;QACF,KAAK,iBAAiB,EAAE;QACxB,sEAAsE;QACtE,oCAAoC;QACpC,mEAAmE;QACnE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/prompt-transformer.d.ts

@@ -98,9 +98,5 @@ export declare class PromptTransformer {
     serializeState(state: SkillState, options?: {
         pretty?: boolean;
     }, schema?: StateSchema): string;
-    /**
-     * Describe the schema fields for inclusion in prompts.
-     */
-    private describeSchema;
 }
 //# sourceMappingURL=prompt-transformer.d.ts.map

package/dist/prompt-transformer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-transformer.d.ts","sourceRoot":"","sources":["../src/prompt-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAMN;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAoC;IAEpD,YAAY,OAAO,CAAC,EAAE,wBAAwB,EAE7C;IAED;;;;;OAKG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAC3C,MAAM,CASR;IAED;;;;;OAKG;IACH,eAAe,CACb,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAmCR;IAED;;;;OAIG;IACH,iBAAiB,CACf,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAyBR;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAmBR;IAED;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAqCrB;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGrD;IAED;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG7C;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA2CnD;IAMD;;;;;OAKG;IACH,cAAc,CACZ,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,CAcR;IAED;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB"}
+{"version":3,"file":"prompt-transformer.d.ts","sourceRoot":"","sources":["../src/prompt-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAMN;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAoC;IAEpD,YAAY,OAAO,CAAC,EAAE,wBAAwB,EAE7C;IAED;;;;;OAKG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAC3C,MAAM,CASR;IAED;;;;;OAKG;IACH,eAAe,CACb,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAyBR;IAED;;;;OAIG;IACH,iBAAiB,CACf,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAkBR;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAmBR;IAED;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA2BrB;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGrD;IAED;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG7C;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA2CnD;IAMD;;;;;OAKG;IACH,cAAc,CACZ,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,CAcR;CACF"}

package/dist/prompt-transformer.js

@@ -1,3 +1,4 @@
+import { STATE_PATCH_CONTRACT, describeSchema } from './prompt-contract.js';
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -38,7 +39,7 @@ export class PromptTransformer {
      */
     formatForClaude(spec, state, observation) {
         const stateJson = this.serializeState(state, undefined, spec.schema);
-        const schemaDesc = this.describeSchema(spec.schema);
+        const schemaDesc = describeSchema(spec.schema);
         return `# System
 
 You are ${spec.name}. ${spec.instructions}
@@ -59,17 +60,7 @@ ${observation.content}
 
 Based on the observation and your current state, provide your response with:
 
-1. Step-by-step reasoning (will be discarded after execution)
-2. A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
-
-\`\`\`json
-{
-  "state_patch": { "key": "new_value", "obsolete_key": null },
-  "action": "your_action_here"
-}
-\`\`\`
-
-In \`state_patch\`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.`;
+${STATE_PATCH_CONTRACT}`;
     }
     /**
      * OpenCode-specific prompt format adapted for the opencode skill system.
@@ -78,7 +69,7 @@ In \`state_patch\`, set keys to null to delete them. Only include fields you wan
      */
     formatForOpenCode(spec, state, observation) {
         const stateJson = this.serializeState(state, undefined, spec.schema);
-        const schemaDesc = this.describeSchema(spec.schema);
+        const schemaDesc = describeSchema(spec.schema);
         return `<skill name="${spec.id}">
 <instructions>${spec.instructions}</instructions>
 ${schemaDesc}
@@ -90,16 +81,9 @@ ${observation.content}
 </observation>
 </skill>
 
-Respond with step-by-step reasoning followed by a JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
-
-\`\`\`json
-{
-  "state_patch": { "key": "new_value", "obsolete_key": null },
-  "action": "action_name"
-}
-\`\`\`
+Respond with:
 
-In \`state_patch\`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.`;
+${STATE_PATCH_CONTRACT}`;
     }
     /**
      * Paper-exact prompt format — byte-verbatim Appendix A.4.
@@ -138,7 +122,7 @@ Provide your response with:
      */
     formatGeneric(spec, state, observation) {
         const stateJson = this.serializeState(state, undefined, spec.schema);
-        const schemaDesc = this.describeSchema(spec.schema);
+        const schemaDesc = describeSchema(spec.schema);
         return `${spec.instructions}
 
 ${schemaDesc}
@@ -155,17 +139,7 @@ ${observation.content}
 
 Provide your response with:
 
-1. Step-by-step reasoning (will be discarded after execution)
-2. A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
-
-\`\`\`json
-{
-  "state_patch": { "key": "value", "obsolete_key": null },
-  "action": "action_name"
-}
-\`\`\`
-
-In \`state_patch\`, set keys to null to delete them.`;
+${STATE_PATCH_CONTRACT}`;
     }
     /**
      * Extract the state_patch from an LLM response containing a fenced JSON block.
@@ -252,14 +226,5 @@ In \`state_patch\`, set keys to null to delete them.`;
         }
         return JSON.stringify(toSerialize);
     }
-    /**
-     * Describe the schema fields for inclusion in prompts.
-     */
-    describeSchema(schema) {
-        const fields = Object.entries(schema)
-            .map(([name, field]) => `- ${name} (${field.type}): ${field.description ?? 'no description'}`)
-            .join('\n');
-        return `## Schema\n${fields}`;
-    }
 }
 //# sourceMappingURL=prompt-transformer.js.map

package/dist/prompt-transformer.js.map

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

package/dist/state-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,WAAW,EAEX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC9B,UAAU,CAWZ;AAcD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAkB3E;AAgDD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,GAChB,gBAAgB,CAkBlB;AAMD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEzD;AAMD,qBAAa,YAAY;IACvB,MAAM,CAAC,kBAAkB,4BAAsB;IAC/C,MAAM,CAAC,UAAU,oBAAc;IAC/B,MAAM,CAAC,aAAa,uBAAiB;IACrC,MAAM,CAAC,cAAc,wBAAkB;IACvC,MAAM,CAAC,gBAAgB,0BAAoB;CAC5C;AAMD,wBAAgB,kBAAkB;;;;;;EAQjC"}
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,WAAW,EAEX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC9B,UAAU,CAWZ;AAkBD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAE3E;AAyBD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,GAChB,gBAAgB,CAkBlB;AAMD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEzD;AAMD,qBAAa,YAAY;IACvB,MAAM,CAAC,kBAAkB,4BAAsB;IAC/C,MAAM,CAAC,UAAU,oBAAc;IAC/B,MAAM,CAAC,aAAa,uBAAiB;IACrC,MAAM,CAAC,cAAc,wBAAkB;IACvC,MAAM,CAAC,gBAAgB,0BAAoB;CAC5C;AAMD,wBAAgB,kBAAkB;;;;;;EAQjC"}

package/dist/state-manager.js

@@ -1,3 +1,4 @@
+import { mergePatch } from './hook-runtime.js';
 // ---------------------------------------------------------------------------
 // 1. createInitialState — Σ₀ from schema defaults + optional overrides
 // ---------------------------------------------------------------------------
@@ -19,41 +20,16 @@ export function createInitialState(schema, overrides) {
 //    - null values DELETE the key entirely
 //    - Nested dicts are merged recursively
 //    - Original state is NOT mutated
+//
+//    Delegates to the hook-runtime {@link mergePatch} — the single ⊕
+//    implementation shared with the generated hook scripts and the
+//    OpenCode plugin (one merge semantics everywhere).
 // ---------------------------------------------------------------------------
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 export function mergeState(state, patch) {
-    const result = { ...state };
-    for (const [key, value] of Object.entries(patch)) {
-        if (value === null) {
-            delete result[key];
-        }
-        else if (isPlainObject(value) && isPlainObject(result[key])) {
-            // Recursive merge for nested objects — apply null-deletion inside too
-            result[key] = mergeNestedObjects(result[key], value);
-        }
-        else {
-            result[key] = value;
-        }
-    }
-    return result;
-}
-/** Deep merge two plain objects with null-deletion semantics. */
-function mergeNestedObjects(base, patch) {
-    const result = { ...base };
-    for (const [key, value] of Object.entries(patch)) {
-        if (value === null) {
-            delete result[key];
-        }
-        else if (isPlainObject(value) && isPlainObject(result[key])) {
-            result[key] = mergeNestedObjects(result[key], value);
-        }
-        else {
-            result[key] = value;
-        }
-    }
-    return result;
+    return mergePatch(state, patch);
 }
 // ---------------------------------------------------------------------------
 // 3. validatePatch — reject unknown keys, wrong types; accept null for deletion

package/dist/state-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-manager.js","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-manager.js","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,8EAA8E;AAC9E,uEAAuE;AACvE,8EAA8E;AAE9E,MAAM,UAAU,kBAAkB,CAChC,MAAmB,EACnB,SAA+B;IAE/B,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IAC7B,CAAC;IACD,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,oDAAoD;AACpD,iCAAiC;AACjC,2CAA2C;AAC3C,2CAA2C;AAC3C,qCAAqC;AACrC,EAAE;AACF,qEAAqE;AACrE,mEAAmE;AACnE,uDAAuD;AACvD,8EAA8E;AAE9E,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,KAAiB;IAC7D,OAAO,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAE9E,SAAS,SAAS,CAAC,KAAc,EAAE,KAAkB;IACnD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,kCAAkC;IAEnE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;QACnC,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;QACnC,KAAK,SAAS;YACZ,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;QACpC,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9B;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAmB,EACnB,KAAiB;IAEjB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAE1B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACpE,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,2BAA2B,GAAG,eAAe,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE;gBACtH,KAAK,EAAE,GAAG;aACX,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,MAAM,UAAU,cAAc,CAC5B,KAAiB,EACjB,OAA8B;IAE9B,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,kEAAkE;AAClE,8EAA8E;AAE9E,MAAM,OAAO,YAAY;IACvB,MAAM,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,MAAM,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,MAAM,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,MAAM,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;CAC5C;AAED,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,kBAAkB;QAClB,UAAU;QACV,aAAa;QACb,cAAc;QACd,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillstate/core",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Paper-exact skillstate runtime core (A.4 byte-verbatim formatPaper, §4.3 token tracker).",
   "type": "module",
   "main": "dist/index.js",