@purista/harness 1.2.6 → 1.5.1

package/dist/skills/index.d.ts

@@ -1,4 +1,3 @@
-import type { JsonValue } from '../models/json.js';
 import type { DiscoveredSkills, DiscoverSkillsOptions, ResolvedSkill, SkillDefinition } from '../harness/defineHarness.js';
 import type { SandboxSession } from '../sandbox/index.js';
 export declare function loadSkillsSync(skills: Record<string, SkillDefinition>): Record<string, ResolvedSkill>;
@@ -6,4 +5,3 @@ export declare function loadSkills(skills: Record<string, SkillDefinition>): Pro
 export declare function mountSkillsOnce(session: SandboxSession, mounted: Set<string>, skills: Record<string, ResolvedSkill>, skillIds: readonly string[]): Promise<void>;
 export declare function buildSkillIndex(skills: Record<string, ResolvedSkill>, ids: readonly string[]): string;
 export declare function discoverSkills(options?: DiscoverSkillsOptions): Promise<DiscoveredSkills>;
-export declare function assertSerializable(value: unknown): asserts value is JsonValue;

package/dist/skills/index.js

@@ -319,11 +319,3 @@ export async function discoverSkills(options = {}) {
     }
     return { skills, diagnostics };
 }
-export function assertSerializable(value) {
-    try {
-        JSON.stringify(value);
-    }
-    catch {
-        throw new SkillManifestError('Non-serializable value', { reason: 'invalid_frontmatter', directory: '' });
-    }
-}

package/dist/state/in-memory.js

@@ -41,7 +41,7 @@ export class InMemoryStateStore {
         }
     }
     async appendMessages(sessionId, messages) {
-        return this.withMessageLock(sessionId, async () => {
+        return this.withMessageLock(sessionId, 'appendMessages', async () => {
             const current = this.messages.get(sessionId) ?? [];
             const ids = new Set(current.map((msg) => msg.id));
             for (const message of messages) {
@@ -68,16 +68,16 @@ export class InMemoryStateStore {
         return rows;
     }
     async clearMessages(sessionId) {
-        return this.withMessageLock(sessionId, async () => {
+        return this.withMessageLock(sessionId, 'clearMessages', async () => {
             this.messages.delete(sessionId);
         });
     }
     async replaceMessages(sessionId, messages) {
-        return this.withMessageLock(sessionId, async () => {
+        return this.withMessageLock(sessionId, 'replaceMessages', async () => {
             const ids = new Set();
             for (const message of messages) {
                 if (ids.has(message.id)) {
-                    throw new StateError('Duplicate message id.', { op: 'appendMessages', reason: 'duplicate_message_id' });
+                    throw new StateError('Duplicate message id.', { op: 'replaceMessages', reason: 'duplicate_message_id' });
                 }
                 ids.add(message.id);
             }
@@ -137,7 +137,7 @@ export class InMemoryStateStore {
         this.events.clear();
         this.messageLocks.clear();
     }
-    async withMessageLock(sessionId, fn) {
+    async withMessageLock(sessionId, op, fn) {
         let lock = this.messageLocks.get(sessionId);
         if (!lock) {
             lock = new Mutex();
@@ -149,7 +149,7 @@ export class InMemoryStateStore {
         catch (error) {
             if (error instanceof StateError)
                 throw error;
-            throw new StateError('State store operation failed.', { op: 'appendMessages' }, error);
+            throw new StateError('State store operation failed.', { op }, error);
         }
     }
 }

package/dist/telemetry/shim.js

@@ -1,7 +1,7 @@
 import { SpanStatusCode, context, metrics, propagation, trace } from '@opentelemetry/api';
 import { ATTR_ERROR_TYPE } from '@opentelemetry/semantic-conventions';
 import { HarnessError } from '../errors/index.js';
-import { sanitizeForLog, sanitizeProviderBody } from '../errors/redaction.js';
+import { sanitizeProviderBody } from '../errors/redaction.js';
 import { HARNESS_VERSION } from '../version.js';
 function sanitizeAttrs(attrs) {
     const out = {};
@@ -83,11 +83,7 @@ export class OtelTelemetryShim {
             }
             catch (error) {
                 span.setAttributes(sanitizeAttrs(errorAttributes(error)));
-                const recordedError = error instanceof HarnessError
-                    ? new Error(error.message)
-                    : error instanceof Error
-                        ? new Error(error.message)
-                        : new Error(String(error));
+                const recordedError = new Error(error instanceof Error ? error.message : String(error));
                 span.recordException(recordedError);
                 span.setStatus({ code: SpanStatusCode.ERROR, message: recordedError.message });
                 throw error;

package/dist/telemetry/span-attrs.d.ts

@@ -0,0 +1,9 @@
+import type { JsonValue } from '../models/json.js';
+/**
+ * Converts caller-supplied invoke metadata into namespaced span attributes.
+ *
+ * Only scalar values survive: strings up to 256 chars, finite numbers, and
+ * booleans. Keys must look like attribute identifiers; everything else is
+ * dropped so unvetted metadata can never grow spans without bound.
+ */
+export declare function metadataSpanAttrs(metadata: Readonly<Record<string, JsonValue>> | undefined): Record<string, string | number | boolean | undefined>;

package/dist/telemetry/span-attrs.js

@@ -0,0 +1,27 @@
+/**
+ * Converts caller-supplied invoke metadata into namespaced span attributes.
+ *
+ * Only scalar values survive: strings up to 256 chars, finite numbers, and
+ * booleans. Keys must look like attribute identifiers; everything else is
+ * dropped so unvetted metadata can never grow spans without bound.
+ */
+export function metadataSpanAttrs(metadata) {
+    const attrs = {};
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(key))
+            continue;
+        if (typeof value === 'string') {
+            if (value.length <= 256)
+                attrs[`harness.metadata.${key}`] = value;
+            continue;
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            attrs[`harness.metadata.${key}`] = value;
+            continue;
+        }
+        if (typeof value === 'boolean') {
+            attrs[`harness.metadata.${key}`] = value;
+        }
+    }
+    return attrs;
+}

package/dist/testing/durableWorkspaceStoreContract.js

@@ -25,6 +25,75 @@ export function durableWorkspaceStoreContract(make) {
                 meta: { reason: 'idempotency_conflict' }
             });
         });
+        it('replays pause and resume results for repeated idempotency keys', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            const checkpoint = await adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'pause', signal });
+            const replayedCheckpoint = await adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'pause', signal });
+            expect(replayedCheckpoint.checkpointRef).toBe(checkpoint.checkpointRef);
+            expect(replayedCheckpoint.committedAt).toBe(checkpoint.committedAt);
+            const resumed = await adapter.resumeWorkspace({ workspaceRef: handle.workspaceRef, sessionId: 's', runId: 'r2', attempt: 2, idempotencyKey: 'resume', signal });
+            const replayedResume = await adapter.resumeWorkspace({ workspaceRef: handle.workspaceRef, sessionId: 's', runId: 'r2', attempt: 2, idempotencyKey: 'resume', signal });
+            expect(replayedResume.workspaceRef).toBe(resumed.workspaceRef);
+            expect(replayedResume.startedAt).toBe(resumed.startedAt);
+        });
+        it('conflicts when pause reuses a key under a different run/session', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            await adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'op', signal });
+            const otherHandle = { ...handle, runId: 'r2', sessionId: 's2' };
+            await expect(adapter.pauseWorkspace({ handle: otherHandle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'op', signal })).rejects.toMatchObject({
+                constructor: WorkspaceError,
+                meta: { reason: 'idempotency_conflict' }
+            });
+        });
+        it('conflicts when resume reuses a key under a different run/session', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            await adapter.resumeWorkspace({ workspaceRef: handle.workspaceRef, sessionId: 's', runId: 'r2', attempt: 2, idempotencyKey: 'op', signal });
+            await expect(adapter.resumeWorkspace({ workspaceRef: handle.workspaceRef, sessionId: 's3', runId: 'r3', attempt: 2, idempotencyKey: 'op', signal })).rejects.toMatchObject({
+                constructor: WorkspaceError,
+                meta: { reason: 'idempotency_conflict' }
+            });
+        });
+        it('conflicts when abort reuses a key under a different run/session', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            await adapter.abortWorkspace?.({ workspaceRef: handle.workspaceRef, runId: 'r', sessionId: 's', reason: 'cancelled', idempotencyKey: 'op', signal });
+            await expect(adapter.abortWorkspace?.({ workspaceRef: handle.workspaceRef, runId: 'r2', sessionId: 's2', reason: 'cancelled', idempotencyKey: 'op', signal })).rejects.toMatchObject({
+                constructor: WorkspaceError,
+                meta: { reason: 'idempotency_conflict' }
+            });
+        });
+        it('conflicts when a key crosses operation kinds (pause then resume)', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            await adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'shared', signal });
+            await expect(adapter.resumeWorkspace({ workspaceRef: handle.workspaceRef, sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'shared', signal })).rejects.toMatchObject({
+                constructor: WorkspaceError,
+                meta: { reason: 'idempotency_conflict' }
+            });
+        });
+        it('inspects a workspace through one of its checkpoint refs', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            const checkpoint = await adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'pause', signal });
+            const inspection = await adapter.inspectWorkspace?.({ checkpointRef: checkpoint.checkpointRef, signal });
+            expect(inspection?.workspaceRef).toBe(handle.workspaceRef);
+            expect(inspection?.checkpoints.map((item) => item.checkpointRef)).toContain(checkpoint.checkpointRef);
+        });
+        it('rejects pause on an aborted workspace and replays the abort result', async () => {
+            const adapter = await make();
+            const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });
+            const aborted = await adapter.abortWorkspace?.({ workspaceRef: handle.workspaceRef, runId: 'r', sessionId: 's', reason: 'cancelled', idempotencyKey: 'abort', signal });
+            const abortedAgain = await adapter.abortWorkspace?.({ workspaceRef: handle.workspaceRef, runId: 'r', sessionId: 's', reason: 'cancelled', idempotencyKey: 'abort', signal });
+            expect(abortedAgain?.state).toBe('aborted');
+            expect(abortedAgain?.abortedAt).toBe(aborted?.abortedAt);
+            await expect(adapter.pauseWorkspace({ handle, stepId: 'step-1', sequence: 1, attempt: 1, reason: 'step_completed', idempotencyKey: 'pause', signal })).rejects.toMatchObject({
+                constructor: WorkspaceError,
+                meta: { reason: 'aborted' }
+            });
+        });
         it('blocks resume after abort and is idempotent on repeated cleanup', async () => {
             const adapter = await make();
             const handle = await adapter.startWorkspace({ sessionId: 's', runId: 'r', attempt: 1, idempotencyKey: 'start', signal });

package/dist/testing/fakeLogger.d.ts

@@ -0,0 +1,29 @@
+import type { Logger, LogLevel } from '../logger/index.js';
+/** Single log record captured by {@link FakeLogger}. */
+export interface FakeLogRecord {
+    level: LogLevel;
+    msg: string;
+    /** RFC3339 timestamp of the record. */
+    time: string;
+    /** Effective bindings (parent bindings merged with child bindings). */
+    bindings: Record<string, unknown>;
+    fields?: Record<string, unknown>;
+}
+/** Logger that captures records in memory for assertions. Child loggers share the parent's record list. */
+export declare class FakeLogger implements Logger {
+    private readonly bindings;
+    readonly records: FakeLogRecord[];
+    constructor(bindings?: Record<string, unknown>, records?: FakeLogRecord[]);
+    trace(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    fatal(msg: string, fields?: Record<string, unknown>): void;
+    child(bindings: Record<string, unknown>): Logger;
+    /** Returns captured records filtered by level. */
+    recordsAt(level: LogLevel): FakeLogRecord[];
+    /** Clears all captured records. */
+    clear(): void;
+    private capture;
+}

package/dist/testing/fakeLogger.js

@@ -0,0 +1,47 @@
+/** Logger that captures records in memory for assertions. Child loggers share the parent's record list. */
+export class FakeLogger {
+    bindings;
+    records;
+    constructor(bindings = {}, records) {
+        this.bindings = bindings;
+        this.records = records ?? [];
+    }
+    trace(msg, fields) {
+        this.capture('trace', msg, fields);
+    }
+    debug(msg, fields) {
+        this.capture('debug', msg, fields);
+    }
+    info(msg, fields) {
+        this.capture('info', msg, fields);
+    }
+    warn(msg, fields) {
+        this.capture('warn', msg, fields);
+    }
+    error(msg, fields) {
+        this.capture('error', msg, fields);
+    }
+    fatal(msg, fields) {
+        this.capture('fatal', msg, fields);
+    }
+    child(bindings) {
+        return new FakeLogger({ ...this.bindings, ...bindings }, this.records);
+    }
+    /** Returns captured records filtered by level. */
+    recordsAt(level) {
+        return this.records.filter((record) => record.level === level);
+    }
+    /** Clears all captured records. */
+    clear() {
+        this.records.length = 0;
+    }
+    capture(level, msg, fields) {
+        this.records.push({
+            level,
+            msg,
+            time: new Date().toISOString(),
+            bindings: { ...this.bindings },
+            ...(fields ? { fields } : {})
+        });
+    }
+}

package/dist/testing/fakeSandbox.d.ts

@@ -0,0 +1,27 @@
+import type { ExecOptions, ExecResult } from '../harness/types.js';
+import type { AdapterCapability } from '../ports/capabilities.js';
+import type { ExecCapableSandboxSession, Sandbox } from '../sandbox/index.js';
+/** Options for {@link FakeSandbox}. */
+export interface FakeSandboxOptions {
+    /** Whether sessions report an available command executor. Default: `'available'`. */
+    executor?: 'available' | 'unavailable';
+    /** Optional scripted exec handler. Defaults to a deterministic `echo`-only executor. */
+    exec?: (command: string, opts?: ExecOptions) => ExecResult | Promise<ExecResult>;
+}
+/**
+ * Deterministic in-memory sandbox fake with a configurable executor flag.
+ *
+ * Sessions are typed exec-capable; when constructed with
+ * `executor: 'unavailable'` dynamically widened `exec(...)` calls throw
+ * `SandboxNoExecutorError`, matching the sandbox contract.
+ */
+export declare class FakeSandbox implements Sandbox {
+    private readonly options;
+    readonly capabilities: readonly AdapterCapability[];
+    constructor(options?: FakeSandboxOptions);
+    open(opts: {
+        sessionId: string;
+        runId: string;
+        signal?: AbortSignal;
+    }): Promise<ExecCapableSandboxSession>;
+}

package/dist/testing/fakeSandbox.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import { OperationCancelledError, SandboxError, SandboxNoExecutorError } from '../errors/index.js';
+function now() {
+    return new Date().toISOString();
+}
+function normalizePath(input) {
+    if (!input.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    const normalized = path.posix.normalize(input);
+    if (!normalized.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    return normalized;
+}
+/** Deterministic default executor: supports `echo <text>`; everything else exits 127. */
+function defaultExec(command) {
+    const trimmed = command.trim();
+    if (trimmed === 'echo' || trimmed.startsWith('echo ')) {
+        return { stdout: `${trimmed.slice(4).trim()}\n`, stderr: '', exitCode: 0, durationSeconds: 0 };
+    }
+    const name = trimmed.split(/\s+/)[0] ?? '';
+    return { stdout: '', stderr: `command not found: ${name}\n`, exitCode: 127, durationSeconds: 0 };
+}
+class FakeSandboxSession {
+    sessionId;
+    options;
+    executor;
+    closed = false;
+    fs = new Map([['/', { kind: 'directory', modifiedAt: now() }]]);
+    constructor(sessionId, options) {
+        this.sessionId = sessionId;
+        this.options = options;
+        this.executor = options.executor ?? 'available';
+    }
+    async read(filePath) {
+        this.assertOpen();
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node || node.kind !== 'file')
+            throw new SandboxError('File not found', { reason: 'fs_failed' });
+        return new Uint8Array(node.data);
+    }
+    async readText(filePath) {
+        return new TextDecoder().decode(await this.read(filePath));
+    }
+    async write(filePath, data) {
+        this.assertOpen();
+        const target = normalizePath(filePath);
+        this.ensureParent(target);
+        const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+        this.fs.set(target, { kind: 'file', data: bytes, modifiedAt: now() });
+    }
+    async remove(filePath, opts) {
+        this.assertOpen();
+        const target = normalizePath(filePath);
+        if (opts?.recursive) {
+            for (const key of [...this.fs.keys()]) {
+                if (key === target || key.startsWith(`${target}/`))
+                    this.fs.delete(key);
+            }
+            return;
+        }
+        this.fs.delete(target);
+    }
+    async list(rootPath, opts) {
+        this.assertOpen();
+        const root = normalizePath(rootPath);
+        const out = [];
+        for (const [entryPath, node] of this.fs.entries()) {
+            if (entryPath === root)
+                continue;
+            if (!entryPath.startsWith(root === '/' ? '/' : `${root}/`))
+                continue;
+            const relative = root === '/' ? entryPath.slice(1) : entryPath.slice(root.length + 1);
+            if (!opts?.recursive && relative.includes('/'))
+                continue;
+            if (opts?.glob && !new RegExp(opts.glob.replaceAll('.', '\\.').replaceAll('*', '.*')).test(entryPath))
+                continue;
+            out.push({
+                name: entryPath.split('/').at(-1) ?? '',
+                path: entryPath,
+                kind: node.kind,
+                ...(node.kind === 'file' ? { size: node.data.byteLength } : {})
+            });
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async stat(filePath) {
+        this.assertOpen();
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node)
+            throw new SandboxError('Path not found', { reason: 'fs_failed' });
+        return { kind: node.kind, size: node.kind === 'file' ? node.data.byteLength : 0, modifiedAt: node.modifiedAt };
+    }
+    async exists(filePath) {
+        this.assertOpen();
+        return this.fs.has(normalizePath(filePath));
+    }
+    async mount(files, atPath) {
+        this.assertOpen();
+        const base = normalizePath(atPath);
+        for (const [rel, data] of files.entries()) {
+            const relNorm = rel.startsWith('/') ? rel.slice(1) : rel;
+            await this.write(`${base}/${relNorm}`, data);
+        }
+    }
+    async exec(command, opts) {
+        this.assertOpen();
+        if (this.executor !== 'available') {
+            throw new SandboxNoExecutorError('Sandbox executor unavailable.', { session_id: this.sessionId });
+        }
+        if (opts?.signal?.aborted) {
+            throw new OperationCancelledError('Sandbox exec was cancelled.', { scope: 'sandbox' });
+        }
+        return (this.options.exec ?? defaultExec)(command, opts);
+    }
+    async close() {
+        this.closed = true;
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new SandboxError('Sandbox session is closed.', { reason: 'session_closed' });
+    }
+    ensureParent(filePath) {
+        const parts = normalizePath(filePath).split('/').filter(Boolean);
+        let current = '/';
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            current = current === '/' ? `/${parts[i]}` : `${current}/${parts[i]}`;
+            if (!this.fs.has(current))
+                this.fs.set(current, { kind: 'directory', modifiedAt: now() });
+        }
+    }
+}
+/**
+ * Deterministic in-memory sandbox fake with a configurable executor flag.
+ *
+ * Sessions are typed exec-capable; when constructed with
+ * `executor: 'unavailable'` dynamically widened `exec(...)` calls throw
+ * `SandboxNoExecutorError`, matching the sandbox contract.
+ */
+export class FakeSandbox {
+    options;
+    capabilities;
+    constructor(options = {}) {
+        this.options = options;
+        this.capabilities = (options.executor ?? 'available') === 'available'
+            ? ['sandbox.fs', 'sandbox.exec']
+            : ['sandbox.fs'];
+    }
+    async open(opts) {
+        // The session reports the configured executor flag at runtime; the static
+        // exec-capable session type mirrors `SandboxSession` dynamic widening.
+        return new FakeSandboxSession(opts.sessionId, this.options);
+    }
+}

package/dist/testing/fakeStateStore.d.ts

@@ -0,0 +1,36 @@
+import { InMemoryStateStore } from '../state/in-memory.js';
+import type { Message, PersistedRunEvent, RunRecord, SessionRecord } from '../models/state.js';
+import type { FinishRunPatch } from '../ports/state.js';
+/** Operation names recorded by {@link FakeStateStore}. */
+export type FakeStateStoreOp = 'getSession' | 'upsertSession' | 'closeSession' | 'appendMessages' | 'listMessages' | 'clearMessages' | 'replaceMessages' | 'createRun' | 'finishRun' | 'getRun' | 'listRuns' | 'appendEvents' | 'listEvents';
+/** In-memory state store that records every invoked operation for test inspection. */
+export declare class FakeStateStore extends InMemoryStateStore {
+    /** Ordered list of operations invoked on this store. */
+    readonly ops: FakeStateStoreOp[];
+    getSession(id: string): Promise<SessionRecord | undefined>;
+    upsertSession(record: SessionRecord): Promise<void>;
+    closeSession(id: string): Promise<void>;
+    appendMessages(sessionId: string, messages: Message[]): Promise<void>;
+    listMessages(sessionId: string, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Message[]>;
+    clearMessages(sessionId: string): Promise<void>;
+    replaceMessages(sessionId: string, messages: Message[]): Promise<void>;
+    createRun(record: RunRecord): Promise<void>;
+    finishRun(runId: string, patch: FinishRunPatch): Promise<void>;
+    getRun(runId: string): Promise<RunRecord | undefined>;
+    listRuns(sessionId: string, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<RunRecord[]>;
+    appendEvents(runId: string, events: PersistedRunEvent[]): Promise<void>;
+    listEvents(runId: string, opts?: {
+        limit?: number;
+        after?: string;
+    }): Promise<PersistedRunEvent[]>;
+    /** Returns how often the given operation was invoked. */
+    opCount(op: FakeStateStoreOp): number;
+    /** Clears the recorded operation log without touching stored data. */
+    resetOps(): void;
+}

package/dist/testing/fakeStateStore.js

@@ -0,0 +1,66 @@
+import { InMemoryStateStore } from '../state/in-memory.js';
+/** In-memory state store that records every invoked operation for test inspection. */
+export class FakeStateStore extends InMemoryStateStore {
+    /** Ordered list of operations invoked on this store. */
+    ops = [];
+    async getSession(id) {
+        this.ops.push('getSession');
+        return super.getSession(id);
+    }
+    async upsertSession(record) {
+        this.ops.push('upsertSession');
+        return super.upsertSession(record);
+    }
+    async closeSession(id) {
+        this.ops.push('closeSession');
+        return super.closeSession(id);
+    }
+    async appendMessages(sessionId, messages) {
+        this.ops.push('appendMessages');
+        return super.appendMessages(sessionId, messages);
+    }
+    async listMessages(sessionId, opts = {}) {
+        this.ops.push('listMessages');
+        return super.listMessages(sessionId, opts);
+    }
+    async clearMessages(sessionId) {
+        this.ops.push('clearMessages');
+        return super.clearMessages(sessionId);
+    }
+    async replaceMessages(sessionId, messages) {
+        this.ops.push('replaceMessages');
+        return super.replaceMessages(sessionId, messages);
+    }
+    async createRun(record) {
+        this.ops.push('createRun');
+        return super.createRun(record);
+    }
+    async finishRun(runId, patch) {
+        this.ops.push('finishRun');
+        return super.finishRun(runId, patch);
+    }
+    async getRun(runId) {
+        this.ops.push('getRun');
+        return super.getRun(runId);
+    }
+    async listRuns(sessionId, opts = {}) {
+        this.ops.push('listRuns');
+        return super.listRuns(sessionId, opts);
+    }
+    async appendEvents(runId, events) {
+        this.ops.push('appendEvents');
+        return super.appendEvents(runId, events);
+    }
+    async listEvents(runId, opts = {}) {
+        this.ops.push('listEvents');
+        return super.listEvents(runId, opts);
+    }
+    /** Returns how often the given operation was invoked. */
+    opCount(op) {
+        return this.ops.filter((entry) => entry === op).length;
+    }
+    /** Clears the recorded operation log without touching stored data. */
+    resetOps() {
+        this.ops.length = 0;
+    }
+}

package/dist/testing/index.d.ts

@@ -1,13 +1,19 @@
 export { FakeModelProvider } from './fakeModelProvider.js';
+export { FakeStateStore, type FakeStateStoreOp } from './fakeStateStore.js';
+export { FakeSandbox, type FakeSandboxOptions } from './fakeSandbox.js';
+export { FakeLogger, type FakeLogRecord } from './fakeLogger.js';
 export { FakeMemoryAdapter, memoryAdapterContract } from './fakeMemoryAdapter.js';
 export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from '../workspace/index.js';
-export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
 export { adapterCapabilitiesContract, fakeCapabilityAdapter, type FakeCapabilityAdapter } from './capabilities.js';
+export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
+export { stateStoreContract } from './stateStoreContract.js';
+export { sandboxContract } from './sandboxContract.js';
+export { modelProviderContract } from './modelProviderContract.js';
+export { loggerContract } from './loggerContract.js';
+export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
+export { recordEvents } from './recordEvents.js';
 export { createInMemoryFeedbackRecorder } from './feedback.js';
 export { evaluateDeterministicScorer } from '../eval/index.js';
 export type { DeterministicScorerDefinition, ScorerResult, ScorerTarget } from '../eval/index.js';
-export { sandboxContract } from './sandboxContract.js';
-export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
-export { stateStoreContract } from './stateStoreContract.js';
 /** Returns a fresh harness builder for tests. */
 export declare function makeHarness(): import("../harness/defineHarness.js").HarnessBuilder<{}>;

package/dist/testing/index.js

@@ -1,14 +1,24 @@
 import { defineHarness } from '../harness/defineHarness.js';
+// Fakes
 export { FakeModelProvider } from './fakeModelProvider.js';
+export { FakeStateStore } from './fakeStateStore.js';
+export { FakeSandbox } from './fakeSandbox.js';
+export { FakeLogger } from './fakeLogger.js';
 export { FakeMemoryAdapter, memoryAdapterContract } from './fakeMemoryAdapter.js';
 export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from '../workspace/index.js';
-export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
 export { adapterCapabilitiesContract, fakeCapabilityAdapter } from './capabilities.js';
-export { createInMemoryFeedbackRecorder } from './feedback.js';
-export { evaluateDeterministicScorer } from '../eval/index.js';
-export { sandboxContract } from './sandboxContract.js';
 export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
+// Contract suites
 export { stateStoreContract } from './stateStoreContract.js';
+export { sandboxContract } from './sandboxContract.js';
+export { modelProviderContract } from './modelProviderContract.js';
+export { loggerContract } from './loggerContract.js';
+export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
+// Helpers
+export { recordEvents } from './recordEvents.js';
+export { createInMemoryFeedbackRecorder } from './feedback.js';
+// AI eval test helpers (re-exported from the main entry for test ergonomics)
+export { evaluateDeterministicScorer } from '../eval/index.js';
 /** Returns a fresh harness builder for tests. */
 export function makeHarness() {
     return defineHarness();

package/dist/testing/loggerContract.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from '../logger/index.js';
+/**
+ * Shared contract for `Logger` implementations.
+ *
+ * Record-shape assertions require a capturing logger that exposes its emitted
+ * records via a `records` array (e.g. `FakeLogger`); non-capturing loggers are
+ * verified for the behavioral contract only.
+ */
+export declare function loggerContract(make: () => Logger): void;