@skillstate/core 0.0.1 → 2.0.1

package/dist/atomic-write.d.ts

@@ -0,0 +1,40 @@
+/** Default stale-lock TTL for {@link acquireLock} (30s). */
+export declare const DEFAULT_LOCK_TTL_MS = 30000;
+/**
+ * A `{ root, name }` pair resolving to a state file inside `root`.
+ * Used by the adapter overloads so codegen can accept user-supplied names
+ * without path-traversal risk.
+ */
+export interface StatePathRef {
+    root: string;
+    name: string;
+}
+/**
+ * Write `content` to `filePath` atomically: temp sibling + fsync + rename.
+ * Parent directories are created. A crash can leave a `.tmp.<pid>.*`
+ * sibling behind, but never a truncated `filePath`.
+ */
+export declare function atomicWriteFile(filePath: string, content: string | Uint8Array): Promise<void>;
+/** Handle returned by {@link acquireLock}; removes the lockfile. */
+export interface LockHandle {
+    release: () => void;
+}
+/**
+ * Create an exclusive lockfile at `lockPath` (`O_EXCL` via `wx`).
+ *
+ * - Fresh path → lock acquired, returns a handle.
+ * - Existing lock younger than `ttlMs` (default {@link DEFAULT_LOCK_TTL_MS})
+ *   → held by a live process, returns `null`.
+ * - Existing lock older than `ttlMs` → stale (crashed holder), removed and
+ *   re-acquired.
+ * - Unreadable/missing locations (stat fails) → `null`, never throws.
+ */
+export declare function acquireLock(lockPath: string, ttlMs?: number): Promise<LockHandle | null>;
+/**
+ * Resolve `name` inside `root` and return the absolute path. Throws when
+ * the result escapes `root` (`..` traversal or an absolute outsider).
+ * `name` values that stay inside (`sub/dir.json`, `a/../b.json`) and `root`
+ * itself (`.` / `''`) are returned as-is.
+ */
+export declare function resolveStatePath(root: string, name: string): string;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwB5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnE"}

package/dist/atomic-write.js

@@ -0,0 +1,97 @@
+/**
+ * @non-paper atomic persistence + lockfiles + safe path resolution.
+ *
+ * The paper has no I/O layer; the @non-paper adapters persist SKILL.state
+ * to disk. These helpers make that persistence crash-safe:
+ *
+ * - {@link atomicWriteFile}: write to a temp sibling, `fsync`, then
+ *   `rename` — readers never observe a half-written state file;
+ * - {@link acquireLock}: exclusive lockfile creation (`wx`) with stale-TTL
+ *   takeover for crashed holders;
+ * - {@link resolveStatePath}: confine a state file name inside a root
+ *   directory — `..` escapes and absolute outsiders throw.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Default stale-lock TTL for {@link acquireLock} (30s). */
+export const DEFAULT_LOCK_TTL_MS = 30_000;
+/**
+ * Write `content` to `filePath` atomically: temp sibling + fsync + rename.
+ * Parent directories are created. A crash can leave a `.tmp.<pid>.*`
+ * sibling behind, but never a truncated `filePath`.
+ */
+export async function atomicWriteFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.promises.mkdir(dir, { recursive: true });
+    const tmp = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    const handle = await fs.promises.open(tmp, 'w');
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.promises.rename(tmp, filePath);
+}
+function makeHandle(lockPath) {
+    return {
+        release: () => {
+            fs.rmSync(lockPath, { force: true });
+        },
+    };
+}
+/**
+ * Create an exclusive lockfile at `lockPath` (`O_EXCL` via `wx`).
+ *
+ * - Fresh path → lock acquired, returns a handle.
+ * - Existing lock younger than `ttlMs` (default {@link DEFAULT_LOCK_TTL_MS})
+ *   → held by a live process, returns `null`.
+ * - Existing lock older than `ttlMs` → stale (crashed holder), removed and
+ *   re-acquired.
+ * - Unreadable/missing locations (stat fails) → `null`, never throws.
+ */
+export async function acquireLock(lockPath, ttlMs) {
+    const ttl = ttlMs ?? DEFAULT_LOCK_TTL_MS;
+    try {
+        await fs.promises.writeFile(lockPath, String(process.pid), {
+            flag: 'wx',
+        });
+        return makeHandle(lockPath);
+    }
+    catch {
+        let mtimeMs = 0;
+        try {
+            const stat = await fs.promises.stat(lockPath);
+            mtimeMs = stat.mtimeMs;
+        }
+        catch {
+            return null;
+        }
+        if (Date.now() - mtimeMs <= ttl) {
+            return null;
+        }
+        await fs.promises.unlink(lockPath);
+        await fs.promises.writeFile(lockPath, String(process.pid), {
+            flag: 'wx',
+        });
+        return makeHandle(lockPath);
+    }
+}
+/**
+ * Resolve `name` inside `root` and return the absolute path. Throws when
+ * the result escapes `root` (`..` traversal or an absolute outsider).
+ * `name` values that stay inside (`sub/dir.json`, `a/../b.json`) and `root`
+ * itself (`.` / `''`) are returned as-is.
+ */
+export function resolveStatePath(root, name) {
+    const base = path.resolve(root);
+    const target = path.resolve(base, name);
+    if (target !== base && !target.startsWith(base + path.sep)) {
+        throw new Error(`Path traversal blocked: ${name}`);
+    }
+    return target;
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

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

package/dist/clock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @non-paper time/identity source. `SystemClock` is the production
+ * implementation; tests inject frozen/counter clocks for determinism.
+ */
+export interface Clock {
+    /** Current unix-epoch millis (like `Date.now()`). */
+    now(): number;
+    /** A unique id (like `crypto.randomUUID()`). */
+    uuid(): string;
+}
+/**
+ * @non-paper production clock: `Date.now()` + `crypto.randomUUID()`.
+ * This is exactly what the runtime does by default when no `clock?` is
+ * passed — injecting it explicitly changes nothing.
+ */
+export declare class SystemClock implements Clock {
+    now(): number;
+    uuid(): string;
+}
+/**
+ * @non-paper deep copy: `structuredClone` when the value is cloneable,
+ * otherwise a JSON round-trip. Values JSON cannot represent (a bare
+ * function, `undefined` inside the fallback) are returned as-is rather
+ * than throwing — persistence must never crash on exotic state.
+ */
+export declare function clone<T>(value: T): T;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,qDAAqD;IACrD,GAAG,IAAI,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,IAAI,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,KAAK;IACvC,GAAG,IAAI,MAAM,CAEZ;IAED,IAAI,IAAI,MAAM,CAEb;CACF;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAOpC"}

package/dist/clock.js

@@ -0,0 +1,45 @@
+/**
+ * @non-paper injectable clock + deep clone helper.
+ *
+ * The paper core calls `Date.now()` directly for observation/step
+ * timestamps. This module adds an OPTIONAL seam for deterministic tests and
+ * crash-recovery replays: pass a `Clock` into `SkillStateRuntime`
+ * (`clock?` option) and timestamps come from it instead. Unset = the
+ * paper-exact `Date.now()` path, byte-for-byte unchanged behavior.
+ *
+ * `clone` is a `structuredClone` deep copy with a JSON fallback for values
+ * the structured-clone algorithm rejects (functions, symbols). Used by the
+ * @non-paper persistence layer so saved/loaded states never alias memory.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * @non-paper production clock: `Date.now()` + `crypto.randomUUID()`.
+ * This is exactly what the runtime does by default when no `clock?` is
+ * passed — injecting it explicitly changes nothing.
+ */
+export class SystemClock {
+    now() {
+        return Date.now();
+    }
+    uuid() {
+        return randomUUID();
+    }
+}
+/**
+ * @non-paper deep copy: `structuredClone` when the value is cloneable,
+ * otherwise a JSON round-trip. Values JSON cannot represent (a bare
+ * function, `undefined` inside the fallback) are returned as-is rather
+ * than throwing — persistence must never crash on exotic state.
+ */
+export function clone(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        const json = JSON.stringify(value);
+        return json === undefined ? value : JSON.parse(json);
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACtB,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,IAAI;QACF,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAI,KAAQ;IAC/B,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAO,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/** @non-paper resolved runtime configuration for the CLI. */
+export interface SkillStateConfig {
+    /** Path to the procedural-spec JSON (or `@intercode-ctf` builtin). */
+    specPath: string;
+    /** Path to the persisted state envelope. */
+    statePath: string;
+    /** Path to the tracker report JSON. */
+    reportPath: string;
+    /** Default cap for `run()` steps. */
+    maxSteps: number;
+    /** Retries after the first failed validation attempt (§7). */
+    maxValidationRetries: number;
+    /** Per-call transport deadline in ms (unset = no timeout layer). */
+    timeoutMs?: number;
+    /** Cumulative char cap for `run()` (unset = no cap). */
+    maxChars?: number;
+    /** Tracker platform label. */
+    platform: 'claude' | 'opencode' | 'generic';
+    /** Tracker session name. */
+    sessionName: string;
+}
+/** @non-paper config file name read from `cwd` by {@link loadConfig}. */
+export declare const CONFIG_FILE_NAME = "skillstate.json";
+/** @non-paper defaults used when neither file nor env sets a value. */
+export declare function defaultConfig(): SkillStateConfig;
+/**
+ * @non-paper merge a parsed config object with `SKILLSTATE_*` env vars
+ * over {@link defaultConfig} (env wins). Unparseable values are ignored.
+ * Never throws.
+ */
+export declare function mergeConfig(file: unknown): SkillStateConfig;
+/**
+ * @non-paper load `skillstate.json` from `cwd` and overlay `SKILLSTATE_*`
+ * env vars (env wins). Never throws: a missing or corrupt file behaves
+ * like an empty one, and unparseable env values are ignored.
+ *
+ * Env map: `SKILLSTATE_SPEC_PATH`, `SKILLSTATE_STATE_PATH`,
+ * `SKILLSTATE_REPORT_PATH`, `SKILLSTATE_MAX_STEPS`,
+ * `SKILLSTATE_MAX_VALIDATION_RETRIES`, `SKILLSTATE_TIMEOUT_MS`,
+ * `SKILLSTATE_MAX_CHARS`, `SKILLSTATE_PLATFORM`, `SKILLSTATE_SESSION_NAME`.
+ */
+export declare function loadConfig(cwd: string): SkillStateConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAeA,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,uEAAuE;AACvE,wBAAgB,aAAa,IAAI,gBAAgB,CAUhD;AA4CD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAwE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAExD"}

package/dist/config.js

@@ -0,0 +1,152 @@
+/**
+ * @non-paper file + env configuration (Wave 4 DX).
+ *
+ * The paper has no config file; this module adds an OPTIONAL, additive
+ * seam so the CLI can run without flags:
+ *
+ * - `skillstate.json` in `cwd` holds a partial `SkillStateConfig`;
+ * - `SKILLSTATE_*` environment variables override the file (env wins);
+ * - missing/corrupt files resolve to defaults (fresh start), never throw.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** @non-paper config file name read from `cwd` by {@link loadConfig}. */
+export const CONFIG_FILE_NAME = 'skillstate.json';
+/** @non-paper defaults used when neither file nor env sets a value. */
+export function defaultConfig() {
+    return {
+        specPath: './skill-spec.json',
+        statePath: './.skillstate.json',
+        reportPath: './skillstate-report.json',
+        maxSteps: 100,
+        maxValidationRetries: 2,
+        platform: 'generic',
+        sessionName: 'skillstate',
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function asNonNegativeInt(value) {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isInteger(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function asPlatform(value) {
+    return value === 'claude' || value === 'opencode' || value === 'generic'
+        ? value
+        : undefined;
+}
+function readConfigFile(cwd) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(cwd, CONFIG_FILE_NAME), 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * @non-paper merge a parsed config object with `SKILLSTATE_*` env vars
+ * over {@link defaultConfig} (env wins). Unparseable values are ignored.
+ * Never throws.
+ */
+export function mergeConfig(file) {
+    const base = defaultConfig();
+    const obj = isRecord(file) ? file : {};
+    const env = process.env;
+    const fileSpec = asNonEmptyString(obj['specPath']);
+    const fileState = asNonEmptyString(obj['statePath']);
+    const fileReport = asNonEmptyString(obj['reportPath']);
+    const fileSteps = asNonNegativeInt(obj['maxSteps']);
+    const fileRetries = asNonNegativeInt(obj['maxValidationRetries']);
+    const fileTimeout = asNonNegativeInt(obj['timeoutMs']);
+    const fileMaxChars = asNonNegativeInt((obj['maxChars'] ?? obj['tokenBudgetChars']));
+    const filePlatform = asPlatform(obj['platform']);
+    const fileSession = asNonEmptyString(obj['sessionName']);
+    const merged = {
+        specPath: fileSpec ?? base.specPath,
+        statePath: fileState ?? base.statePath,
+        reportPath: fileReport ?? base.reportPath,
+        maxSteps: fileSteps ?? base.maxSteps,
+        maxValidationRetries: fileRetries ?? base.maxValidationRetries,
+        platform: filePlatform ?? base.platform,
+        sessionName: fileSession ?? base.sessionName,
+    };
+    if (fileTimeout !== undefined) {
+        merged.timeoutMs = fileTimeout;
+    }
+    if (fileMaxChars !== undefined) {
+        merged.maxChars = fileMaxChars;
+    }
+    const envSpec = asNonEmptyString(env['SKILLSTATE_SPEC_PATH']);
+    const envState = asNonEmptyString(env['SKILLSTATE_STATE_PATH']);
+    const envReport = asNonEmptyString(env['SKILLSTATE_REPORT_PATH']);
+    const envSteps = asNonNegativeInt(env['SKILLSTATE_MAX_STEPS']);
+    const envRetries = asNonNegativeInt(env['SKILLSTATE_MAX_VALIDATION_RETRIES']);
+    const envTimeout = asNonNegativeInt(env['SKILLSTATE_TIMEOUT_MS']);
+    const envMaxChars = asNonNegativeInt(env['SKILLSTATE_MAX_CHARS']);
+    const envPlatform = asPlatform(env['SKILLSTATE_PLATFORM']);
+    const envSession = asNonEmptyString(env['SKILLSTATE_SESSION_NAME']);
+    if (envSpec !== undefined) {
+        merged.specPath = envSpec;
+    }
+    if (envState !== undefined) {
+        merged.statePath = envState;
+    }
+    if (envReport !== undefined) {
+        merged.reportPath = envReport;
+    }
+    if (envSteps !== undefined) {
+        merged.maxSteps = envSteps;
+    }
+    if (envRetries !== undefined) {
+        merged.maxValidationRetries = envRetries;
+    }
+    if (envTimeout !== undefined) {
+        merged.timeoutMs = envTimeout;
+    }
+    if (envMaxChars !== undefined) {
+        merged.maxChars = envMaxChars;
+    }
+    if (envPlatform !== undefined) {
+        merged.platform = envPlatform;
+    }
+    if (envSession !== undefined) {
+        merged.sessionName = envSession;
+    }
+    return merged;
+}
+/**
+ * @non-paper load `skillstate.json` from `cwd` and overlay `SKILLSTATE_*`
+ * env vars (env wins). Never throws: a missing or corrupt file behaves
+ * like an empty one, and unparseable env values are ignored.
+ *
+ * Env map: `SKILLSTATE_SPEC_PATH`, `SKILLSTATE_STATE_PATH`,
+ * `SKILLSTATE_REPORT_PATH`, `SKILLSTATE_MAX_STEPS`,
+ * `SKILLSTATE_MAX_VALIDATION_RETRIES`, `SKILLSTATE_TIMEOUT_MS`,
+ * `SKILLSTATE_MAX_CHARS`, `SKILLSTATE_PLATFORM`, `SKILLSTATE_SESSION_NAME`.
+ */
+export function loadConfig(cwd) {
+    return mergeConfig(readConfigFile(cwd));
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @non-paper typed runtime event emitter + shared singleton.
+ *
+ * The paper defines no observability; Algorithm 1 just runs. This module
+ * adds an OPTIONAL, additive event seam the runtime emits into ONLY when a
+ * caller passes `events?` (unset = zero overhead, zero behavior change):
+ *
+ * - `step:start` — before the LLM call (`{ step, observation }`);
+ * - `step:end` — after a completed step (`{ step, action, invalidated }`);
+ * - `step:error` — validation-exhausted or transport-thrown steps
+ *   (`{ step, error }`);
+ * - `budget:exceeded` — `run()` char-budget trip
+ *   (`{ step, totalChars, maxChars }`).
+ *
+ * Zero dependencies, Node >= 20, ESM. Deliberately NOT `node:events`:
+ * a 30-line typed emitter keeps payloads type-safe without any import.
+ */
+import type { Observation } from './types.js';
+/** @non-paper runtime event names. */
+export type RuntimeEventName = 'step:start' | 'step:end' | 'step:error' | 'budget:exceeded';
+/** @non-paper payloads per runtime event. */
+export interface RuntimeEventPayloads {
+    'step:start': {
+        step: number;
+        observation: Observation;
+    };
+    'step:end': {
+        step: number;
+        action: string;
+        invalidated: boolean;
+    };
+    'step:error': {
+        step: number;
+        error: string;
+    };
+    'budget:exceeded': {
+        step: number;
+        totalChars: number;
+        maxChars: number;
+    };
+}
+/** @non-paper listener for one runtime event. */
+export type RuntimeEventListener<E extends RuntimeEventName> = (payload: RuntimeEventPayloads[E]) => void;
+/**
+ * @non-paper minimal typed emitter. `on` returns an unsubscribe closure;
+ * `emit` to an event with no listeners is a no-op (never throws).
+ */
+export declare class RuntimeEventEmitter {
+    private readonly listeners;
+    /** Subscribe; returns an unsubscribe function. */
+    on<E extends RuntimeEventName>(event: E, listener: RuntimeEventListener<E>): () => void;
+    /** Unsubscribe (no-op when absent — never throws). */
+    off<E extends RuntimeEventName>(event: E, listener: RuntimeEventListener<E>): void;
+    /** Deliver `payload` to a snapshot of the current listeners. */
+    emit<E extends RuntimeEventName>(event: E, payload: RuntimeEventPayloads[E]): void;
+}
+/** @non-paper process-wide runtime event bus (use explicitly, never magic). */
+export declare const runtimeEvents: RuntimeEventEmitter;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,iBAAiB,CAAC;AAEtB,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC;IACzD,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IACnE,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,iBAAiB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,IAAI,CAC7D,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAC7B,IAAI,CAAC;AAEV;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ,kDAAkD;IAClD,EAAE,CAAC,CAAC,SAAS,gBAAgB,EAC3B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,MAAM,IAAI,CAUZ;IAED,sDAAsD;IACtD,GAAG,CAAC,CAAC,SAAS,gBAAgB,EAC5B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,IAAI,CAEN;IAED,gEAAgE;IAChE,IAAI,CAAC,CAAC,SAAS,gBAAgB,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,IAAI,CAQN;CACF;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,qBAA4B,CAAC"}

package/dist/events.js

@@ -0,0 +1,36 @@
+/**
+ * @non-paper minimal typed emitter. `on` returns an unsubscribe closure;
+ * `emit` to an event with no listeners is a no-op (never throws).
+ */
+export class RuntimeEventEmitter {
+    listeners = new Map();
+    /** Subscribe; returns an unsubscribe function. */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (set === undefined) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            this.off(event, listener);
+        };
+    }
+    /** Unsubscribe (no-op when absent — never throws). */
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    /** Deliver `payload` to a snapshot of the current listeners. */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (set === undefined) {
+            return;
+        }
+        for (const listener of [...set]) {
+            listener(payload);
+        }
+    }
+}
+/** @non-paper process-wide runtime event bus (use explicitly, never magic). */
+export const runtimeEvents = new RuntimeEventEmitter();
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAuCA;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACb,SAAS,GAAG,IAAI,GAAG,EAGjC,CAAC;IAEJ,kDAAkD;IAClD,EAAE,CACA,KAAQ,EACR,QAAiC;QAEjC,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAsC,CAAC,CAAC;QAChD,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC5B,CAAC,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,GAAG,CACD,KAAQ,EACR,QAAiC;QAEjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAsC,CAAC,CAAC;IAC5E,CAAC;IAED,gEAAgE;IAChE,IAAI,CACF,KAAQ,EACR,OAAgC;QAEhC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAC/B,QAAoC,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,mBAAmB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export * from './types.js';
+export * from './state-manager.js';
+export * from './prompt-transformer.js';
+export * from './token-tracker.js';
+export * from './runtime.js';
+export * from './instrumentation.js';
+export * from './resilience.js';
+export * from './validate.js';
+export * from './redaction.js';
+export * from './atomic-write.js';
+export * from './clock.js';
+export * from './migrations.js';
+export * from './state-store.js';
+export * from './events.js';
+export * from './logger.js';
+export * from './provider.js';
+export * from './config.js';
+export * from './shutdown.js';
+export * from './schemas/index.js';
+//# 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":"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,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+// Public API of the skillstate core.
+//
+// Paper-exact baseline (§3-§4): types, state-manager, prompt-transformer,
+// token-tracker, runtime. `instrumentation` is an OPTIONAL @non-paper helper
+// module (heuristics/estimates, not from the paper).
+export * from './types.js';
+export * from './state-manager.js';
+export * from './prompt-transformer.js';
+export * from './token-tracker.js';
+export * from './runtime.js';
+export * from './instrumentation.js';
+// @non-paper Wave-2 reliability/security helpers (additive, opt-in).
+export * from './resilience.js';
+export * from './validate.js';
+export * from './redaction.js';
+export * from './atomic-write.js';
+// @non-paper Wave-3 observability/persistence helpers (additive, opt-in).
+export * from './clock.js';
+export * from './migrations.js';
+export * from './state-store.js';
+export * from './events.js';
+export * from './logger.js';
+// @non-paper Wave-4 DX helpers (additive, opt-in).
+export * from './provider.js';
+export * from './config.js';
+export * from './shutdown.js';
+export * from './schemas/index.js';
+//# 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,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,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/instrumentation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @non-paper — OPTIONAL instrumentation helpers, NOT part of the paper.
+ *
+ * Nothing in this module appears in arXiv 2608.26263v3. The paper's §4.3
+ * methodology measures prompts in raw string chars (Average Prompt Size =
+ * mean char length per call, Total Token Cost = cumulative burn) and reports
+ * no tokenizer heuristic and no dollar pricing. Import from here only when
+ * you explicitly want a rough, clearly-labelled estimate outside the
+ * paper-exact baseline in `./token-tracker.js`.
+ */
+/** Pluggable character-to-token estimator (heuristic, never exact). */
+export interface TokenCounter {
+    /** Roughly estimate the tokens in `text`. */
+    count(text: string): number;
+}
+/**
+ * @non-paper legacy heuristic: 1 token ≈ 4 chars, rounded up.
+ *
+ * Kept for backward compatibility of ad-hoc estimates only. Do NOT use it
+ * for paper §4.3 metrics — those are measured in chars (see `TokenTracker`).
+ * Empty text costs zero.
+ */
+export declare class CharDiv4Counter implements TokenCounter {
+    count(text: string): number;
+}
+/**
+ * @non-paper estimated dollar savings of state prompts vs the conversation
+ * baseline, from measured char counts (e.g. `TokenTracker.compareWithBaseline`).
+ *
+ * This is a back-of-the-envelope estimate, NOT a paper metric: the paper
+ * reports no pricing. `usdPerMillionChars` defaults to 3 (a placeholder
+ * rate, not a paper figure). Returns 0 when there is nothing to save.
+ */
+export declare function estimateCostSavings(conversationChars: number, stateChars: number, usdPerMillionChars?: number): number;
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK1B;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM,EAClB,kBAAkB,SAAI,GACrB,MAAM,CAMR"}