@x1a0f3n9/dsh-session-snapshot 0.1.5-rc.3

package/lib/types/harness.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Shared subprocess harness for ACP snapshot suites. A library module driven by
+ * the suite factory in ./suite.ts (and directly by harness-level specs); each
+ * profile adapter names its own agent-under-test paths.
+ *
+ * It boots the REAL agent bin subprocess via the cordis Loader (so the
+ * export-shape bug class stays guarded — see docs/postmortem/0001), drives it
+ * over real ACP JSON-RPC stdio with a deterministic input script, tees raw
+ * stdout (for the expected-output and purity checks) into an SDK client app,
+ * and — in record mode — harvests the persisted session JSONL after a graceful
+ * shutdown flush. The pure normalizers in ./normalize.ts turn the captured
+ * stdout frames and the session-log events into stable, snapshot-able text.
+ *
+ * See .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md.
+ *
+ * @module @x1a0f3n9/dsh-session-snapshot/harness
+ */
+import { type ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+import { type AgentUnderTest } from './launcher.ts';
+import { type WorkspaceSnapshotEntry } from './workspace.ts';
+export type { AgentUnderTest } from './launcher.ts';
+/**
+ * One step of a scenario's deterministic input script (`input.json`). The
+ * harness interprets these in order. `newSession` captures the server-issued
+ * (random) session id into a `{{sessionId}}` variable that later steps
+ * reference, since a committed file cannot know the id in advance.
+ *
+ * `promptAndCancel` starts a prompt without awaiting completion, waits for a
+ * readiness condition, then cancels and awaits completion. Its optional
+ * `waitForFile` observes a cwd-relative marker; otherwise it waits for the
+ * durable turn start. The standalone `waitForFile` holds the next script step
+ * behind the same marker.
+ * `promptAndWaitForAgentMessage` arms an exact text-chunk waiter before sending
+ * the prompt, then keeps the application live until that later update arrives.
+ * `waitForTurnStart` waits for an open durable turn, optionally at or beyond a
+ * specified turn number. `waitForTurnEnd` holds the subprocess open until the
+ * selected session's latest complete raw-JSONL turn boundary is `turn/end`.
+ * `waitForGoalPhase` waits for the latest durable goal snapshot to reach one phase.
+ * `waitForInboxMessage` waits for inserted inbox text containing a scenario marker.
+ * `waitForSubagentTurnEnd` waits until one background child has persisted a
+ * closed model-work turn after its own descriptor; child progress has no ACP
+ * update to wait on. Failures identify the child, turn, and deadline even if
+ * the first log read is still pending; the underlying failure is retained as cause.
+ * `waitForTitleAfterTurnEnd` additionally waits for a later durable title.
+ * `waitForEventAfterTurnEnd` waits until a complete record of the given event
+ * type follows the latest closed turn — for scenarios whose asserted state
+ * (e.g. a goal pause) is appended only after cancellation reaches idle.
+ * A standalone `cancel` may also wait for a cwd-relative readiness marker.
+ * All wait timeouts default to 10s.
+ */
+export type InputStep = {
+    op: 'initialize';
+} | {
+    op: 'newSession';
+} | {
+    op: 'newSessionExpectError';
+    additionalDirectories?: string[];
+} | {
+    op: 'prompt';
+    text: string;
+} | {
+    op: 'promptContent';
+    content: AcpContentBlock[];
+} | {
+    op: 'promptAndWaitForAgentMessage';
+    text: string;
+    waitForText: string;
+} | {
+    op: 'promptExpectError';
+    text: string;
+} | {
+    op: 'promptAndCancel';
+    text: string;
+    waitForFile?: {
+        path: string;
+        timeoutMs?: number;
+    };
+} | {
+    op: 'waitForFile';
+    path: string;
+    timeoutMs?: number;
+} | {
+    op: 'waitForTurnStart';
+    minimumTurn?: number;
+    timeoutMs?: number;
+} | {
+    op: 'waitForTurnEnd';
+    timeoutMs?: number;
+} | {
+    op: 'waitForSubagentTurnEnd';
+    child?: number;
+    minimumTurn?: number;
+    timeoutMs?: number;
+} | {
+    op: 'waitForGoalPhase';
+    phase: 'active' | 'paused' | 'blocked' | 'complete';
+    timeoutMs?: number;
+} | {
+    op: 'waitForInboxMessage';
+    text: string;
+    timeoutMs?: number;
+} | {
+    op: 'waitForTitleAfterTurnEnd';
+    timeoutMs?: number;
+} | {
+    op: 'waitForEventAfterTurnEnd';
+    type: string;
+    timeoutMs?: number;
+} | {
+    op: 'cancel';
+    waitForFile?: {
+        path: string;
+        timeoutMs?: number;
+    };
+};
+/** A scenario's `input.json`: an ordered list of input steps. */
+export interface InputScript {
+    steps: InputStep[];
+    /**
+     * Ordered answers for the agent's `session/request_permission` round-trips,
+     * consumed FIFO — the Nth request gets the Nth answer. Each answer selects
+     * by option KIND: option ids are agent-issued randoms a committed script
+     * cannot know, while kinds are the ACP-stable vocabulary, so the client maps
+     * kind → the offered `optionId` at answer time. A request beyond the queue
+     * (or with no queue at all) is answered `cancelled` — the stub behavior a
+     * scenario without approvals relies on. A scripted kind the request does
+     * not offer REJECTS the run: the scenario scripted an impossible selection,
+     * and {@link runScenario} throws once the in-flight step settles (the
+     * agent itself just sees `cancelled`, so it cannot absorb the bug).
+     */
+    permissionAnswers?: PermissionAnswer[];
+}
+/** One scripted answer to a permission request: which offered option kind to select. */
+export interface PermissionAnswer {
+    /** The `PermissionOption.kind` to select (`allow_once`, `reject_always`, …). */
+    kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always';
+}
+/** One harvested session log plus the identifying facts off its header line. */
+export interface HarvestedLog {
+    /** The recorded session id (header `id`). */
+    id: string;
+    /** Session creation time (header `createdAt`) — the child-ordering key. */
+    createdAt: number;
+    /** The parent session id, if this log is a subagent child (header `parentSession`). */
+    parentSession?: string;
+    /** The full `.jsonl` file content. */
+    content: string;
+}
+/** The result of running a scenario: raw stdout + the harvested session log(s). */
+export interface RunResult {
+    /** Raw stdout bytes (decoded utf8), every newline-delimited JSON-RPC frame. */
+    rawStdout: string;
+    /** stderr (for diagnostics on failure). */
+    stderr: string;
+    /** The session id the server issued (undefined if no session was created). */
+    sessionId?: string;
+    /** The generated cwd the session ran in (the bash workspace). */
+    cwd: string;
+    /** Filesystem-resolved spellings of {@link cwd} that child processes may report. */
+    cwdAliases: string[];
+    /** User-visible workspace state after committed and runtime-only setup. */
+    initialWorkspace: WorkspaceSnapshotEntry[];
+    /** User-visible workspace state after the controlled interface has settled. */
+    finalWorkspace: WorkspaceSnapshotEntry[];
+    /**
+     * Every persisted session log harvested after the run, ordered primary-first:
+     * the top-level (parent) session — the one with no `parentSession` — then each
+     * subagent child by ascending `createdAt`. A single-session scenario harvests
+     * exactly one; a nested-agent scenario harvests the parent plus one per child.
+     */
+    sessionLogs: HarvestedLog[];
+}
+/** How to run one scenario: the agent to boot, the mode, and the fixture wiring. */
+export interface RunOptions {
+    /** The agent composition to boot. */
+    agent: AgentUnderTest;
+    /** `replay` (default, keyless) or `record` (real API, harvests the log). */
+    mode: 'replay' | 'record';
+    /** Scenario-specific deployment environment layered into the subprocess. */
+    env?: NodeJS.ProcessEnv;
+    /** The recorded session JSONL fixture path (replay reads it; record writes near it). */
+    fixtureFile: string;
+    /** Optional sidecar override path (replay). */
+    overrideFile?: string;
+    /**
+     * Recorded SUBAGENT child-session fixture paths (replay). A nested-agent
+     * scenario ships one per child (`session.1.jsonl`, …); the harness forwards
+     * them to `dsh-llm-replay` via `$DSH_SNAPSHOT_CHILD_FILES` so each child
+     * session replays from its own recorded script. Empty for single-session
+     * scenarios. Ignored in record mode (children are harvested, not replayed).
+     */
+    childFiles?: string[];
+    /**
+     * Optional `<scenario>/workspace/` directory whose contents are copied into
+     * the generated cwd BEFORE the run — the standard way to seed files the agent
+     * operates on (a file to read, edit, or grep). Absent for scenarios that
+     * start from an empty workspace.
+     */
+    workspaceDir?: string;
+    /**
+     * Optional final workspace preparation, run after {@link workspaceDir} is
+     * copied and before the agent starts. This is for fixtures that cannot be
+     * represented portably in Git (for example, a POSIX-only filename that is
+     * invalid on Windows); ordinary seeded files belong in `workspaceDir`.
+     */
+    prepareWorkspace?: (cwd: string) => void | Promise<void>;
+    /**
+     * Parent directory for the generated session cwd. Defaults to
+     * `os.tmpdir()`. A scenario that must distinguish its workspace from the
+     * sandbox's always-writable temporary roots can place the generated child
+     * under `os.homedir()` instead. The harness removes only that generated
+     * child, never the supplied parent.
+     */
+    workspaceParent?: string;
+    /**
+     * Alternate live profile patch (absolute), overriding
+     * {@link AgentUnderTest.configPath} for this run. Its basename still ends
+     * in `cordis.yml` so the launcher can select the replay sibling.
+     */
+    configPath?: string;
+}
+/**
+ * Derive the stable, fixed-length logical spill prefix; never allocate files here.
+ * Windows uses a two-character-shorter root because drive resolution adds its drive prefix.
+ * @param fixtureFile - The scenario fixture whose parent directory provides the stable identity.
+ * @param platform - the host platform, injectable for unit coverage.
+ * @returns the root-relative snapshot spill directory.
+ */
+export declare function snapshotSpillRoot(fixtureFile: string, platform?: NodeJS.Platform): string;
+/**
+ * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the
+ * child and its generated dirs; always tears them down. Returns the captured stdout
+ * and (record mode) the harvested session-log path.
+ *
+ * @param input The scenario's input script (steps + optional permission answers).
+ * @param opts The agent to boot, the mode, and the fixture wiring.
+ * @returns The captured stdout/stderr, session id, generated cwd, and harvested logs.
+ */
+export declare function runScenario(input: InputScript, opts: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=harness.d.ts.map

package/lib/types/identity.d.ts

@@ -0,0 +1,8 @@
+/** Relationship-preserving identity redaction for committed session snapshots. */
+/**
+ * Replace volatile opaque ids while preserving equality relationships across a parent and its child logs.
+ * @param logs - one scenario's primary-first session JSONL fixtures.
+ * @returns compact JSONL with typed first-seen identity tokens.
+ */
+export declare function redactSessionSnapshotIds(logs: readonly string[]): string[];
+//# sourceMappingURL=identity.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Session-log snapshot support behind the keyless snapshot tier
+ * (`pnpm run test:snapshot`). The current ACP adapter has four layers: the
+ * shared subprocess/client launcher ({@link launchAcpTestAgent}), the scripted
+ * scenario harness ({@link runScenario}), the pure expected-output normalizers
+ * ({@link normalizeStdout} / {@link normalizeSessionLog} /
+ * {@link scrubModelRequestBulk} / {@link scrubSystemPrompts}), and the suite
+ * factory ({@link defineAcpSnapshotSuite}) that registers a scenario table as a
+ * full describe/it tree. Transport-neutral normalizers and fixture invariants
+ * remain reusable by other profile adapters. Ordinary ACP e2e tests can use the launcher directly;
+ * the ACP corpus adapter supplies only its {@link AgentUnderTest} paths,
+ * snapshots directory, and {@link Scenario} table.
+ *
+ * NOTE: ./suite.ts imports vitest, so this package is importable only inside a
+ * vitest run — a support-tier constraint stated in the README.
+ *
+ * @module @x1a0f3n9/dsh-session-snapshot
+ */
+export { redactSessionSnapshotIds, } from './identity.ts';
+export { runScenario, snapshotSpillRoot, type HarvestedLog, type InputScript, type InputStep, type PermissionAnswer, type RunOptions, type RunResult, } from './harness.ts';
+export { launchAcpTestAgent, materializeProfilePatch, type AcpTestLaunchOptions, type AgentUnderTest, type LaunchedAcpTestAgent, } from './launcher.ts';
+export { extractSnapshotSpillPaths, normalizeSessionFormatProvenance, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, scrubModelRequestBulk, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.ts';
+export { parseSnapshotManifest, writesCurrentSessionFixtures, type SnapshotHeaderManifest, type SnapshotInputAttachment, type SnapshotInputManifest, type SnapshotManifest, type SnapshotPermission, type SnapshotPlatform, type SnapshotProfile, type SnapshotRecording, type SnapshotReplayManifest, type SnapshotSessionReference, type SnapshotSessionFormatCoverage, type SnapshotSessionFormatManifest, type SnapshotSessionWriteMode, type SnapshotWorkspaceManifest, } from './manifest.ts';
+export { assertPersistedSessionVersion, assertSessionFixtureVersion, latestPersistedSessionPaths, parsePersistedSessionFilename, parseSessionFixtureName, persistedSessionFilename, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, writerSnapshotName, type PersistedSessionFile, type SessionFixtureFile, } from './session-files.ts';
+export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseSystemPromptSnapshot, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, type Scenario, type SnapshotSuiteOptions, } from './suite.ts';
+export { captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, EMPTY_WORKSPACE_MARKER, type CaptureWorkspaceSnapshotOptions, type WorkspaceBinaryFileSnapshot, type WorkspaceEmptyDirectorySnapshot, type WorkspaceSnapshotEntry, type WorkspaceSymlinkSnapshot, type WorkspaceTextFileSnapshot, } from './workspace.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/launcher.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared launcher for ACP tests that drive an agent subprocess over JSON-RPC
+ * stdio. It owns source-or-built launch resolution, workspace environment,
+ * stdout tee, SDK client, update collection, permission fallback, and process
+ * shutdown so e2e and snapshot suites do not each reconstruct that boundary.
+ *
+ * @module @x1a0f3n9/dsh-session-snapshot/launcher
+ */
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type CancelNotification, type CloseSessionRequest, type CloseSessionResponse, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type RequestPermissionRequest, type RequestPermissionResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SessionNotification } from '@agentclientprotocol/sdk';
+/** The source/built entry, profile patch, and workspace tsconfig an ACP test boots. */
+export interface AgentUnderTest {
+    /** The source bin entry; product suites use `apps/cli/src/bin.ts`. */
+    binScript: string;
+    /** Explicit built-mode entry for fixtures whose source path is not under `src/`. */
+    libBinScript?: string | undefined;
+    /** Base config or profile patch loaded by the bin. */
+    configPath: string;
+    /** Named dsh profile; omitted only for test-only fake bins with their own config grammar. */
+    profile?: string;
+    /** The repo tsconfig whose paths resolve unbuilt workspace imports. */
+    tsconfigPath: string;
+}
+/** Options for one ACP test subprocess. */
+export interface AcpTestLaunchOptions {
+    /** The agent composition to boot. */
+    agent: AgentUnderTest;
+    /** Process cwd and default session-home root. */
+    cwd: string;
+    /** Alternate leaf config for this launch. */
+    configPath?: string;
+    /** Extra environment values layered over the parent environment. */
+    env?: NodeJS.ProcessEnv;
+    /** Permission handler; omitted requests fail closed as `cancelled`. */
+    requestPermission?: (params: RequestPermissionRequest) => Promise<RequestPermissionResponse>;
+}
+/** Stable ACP methods used by the subprocess test harness. */
+export interface AcpTestClient {
+    readonly closed: Promise<void>;
+    initialize: (params: InitializeRequest) => Promise<InitializeResponse>;
+    newSession: (params: NewSessionRequest) => Promise<NewSessionResponse>;
+    listSessions: (params: ListSessionsRequest) => Promise<ListSessionsResponse>;
+    resumeSession: (params: ResumeSessionRequest) => Promise<ResumeSessionResponse>;
+    closeSession: (params: CloseSessionRequest) => Promise<CloseSessionResponse>;
+    setSessionConfigOption: (params: SetSessionConfigOptionRequest) => Promise<SetSessionConfigOptionResponse>;
+    prompt: (params: PromptRequest) => Promise<PromptResponse>;
+    cancel: (params: CancelNotification) => Promise<void>;
+}
+/** A running ACP test process and its captured client-side outputs. */
+export interface LaunchedAcpTestAgent {
+    /** The child process, exposed for process-level assertions. */
+    child: ChildProcessWithoutNullStreams;
+    /** Resolve when the OS spawns the child; reject with its asynchronous spawn failure. */
+    spawned: Promise<void>;
+    /** The SDK connection backed by the child's stdio. */
+    client: AcpTestClient;
+    /** Session updates in receive order. */
+    updates: SessionNotification['update'][];
+    /** Decode all stdout bytes captured so far. */
+    rawStdout(): string;
+    /** Decode all stderr chunks captured so far. */
+    stderr(): string;
+    /** Resolve when a future session update matches the predicate. */
+    waitForUpdate(match: (update: SessionNotification['update']) => boolean): Promise<SessionNotification['update']>;
+    /** Close the process and drain its streams and callbacks; rejects promptly if fallback termination is refused. */
+    close(signal?: NodeJS.Signals): Promise<void>;
+}
+/**
+ * Boot an ACP agent subprocess and connect an SDK client to its stdio.
+ *
+ * @param options Agent paths, cwd, environment, and optional permission handler.
+ * @returns The running process, connected client, captures, and shutdown handle.
+ */
+export declare function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTestAgent;
+/**
+ * Copy one authored patch into the launch cwd with relative plugin names made absolute.
+ * @param source - authored profile patch path.
+ * @param cwd - isolated process cwd whose profile fallback receives package links.
+ * @param targetDir - existing directory that owns the materialized patch.
+ * @param index - stable patch ordinal used in the output filename.
+ * @returns absolute materialized patch path.
+ */
+export declare function materializeProfilePatch(source: string, cwd: string, targetDir: string, index: number): string;
+//# sourceMappingURL=launcher.d.ts.map

package/lib/types/manifest.d.ts

@@ -0,0 +1,123 @@
+/** Parse and validate one recorded-session snapshot manifest. */
+/** Public `dsh` profile used to control a recorded-session scenario. */
+export type SnapshotProfile = 'headless' | 'sdk' | 'acp' | 'web';
+/** How a canonical session may be regenerated. */
+export type SnapshotRecording = 'live' | 'authored';
+/** Request-header ownership metadata for one composition. */
+export interface SnapshotHeaderManifest {
+    /** Stable class name shared only by byte-identical request headers. */
+    class: string;
+    /** Whether this scenario owns the class's tokenized header sequence. */
+    pin?: true;
+    /** Scenario that owns the readable system-prompt sidecar. */
+    systemPromptSource?: string;
+    /** Scenario that owns the readable tool-schema sidecar. */
+    toolSchemasSource?: string;
+    /** Child fixture indexes that own distinct system-prompt sidecars. */
+    childSystemPrompts?: number[];
+    /** Child fixture indexes that own distinct tool-schema sidecars. */
+    childToolSchemas?: number[];
+    /** Legitimate changed-header count after the initial request header. */
+    changes?: number;
+    /** Legitimate later `system/message` count (replacements or in-history appends) after the initial system prompt. */
+    promptChanges?: number;
+}
+/** Replay facts that cannot be reconstructed from successful model chunks. */
+export interface SnapshotReplayManifest {
+    /** A scenario-local `replay.override.json` replaces or patches the recorded model script. */
+    override: true;
+}
+/** Host requirements for a scenario's process-level controller. */
+export type SnapshotPlatform = 'posix' | 'pwsh';
+/** Deployment permission preset selected before the scenario starts. */
+export type SnapshotPermission = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Scenario-local workspace preparation and expected-state metadata. */
+export interface SnapshotWorkspaceManifest {
+    /** Named setup needed for state Git cannot represent directly. */
+    setup?: string;
+    /** Whether `workspace.expected/` owns the complete final world state. */
+    final?: true;
+    /** Place the generated cwd outside automatically writable temporary roots. */
+    parent?: 'outside-temp';
+}
+/** Controller input that cannot enter a session because admission rejects it. */
+export interface SnapshotInputAttachment {
+    /** Content-addressed attachment id stored in the session message. */
+    id: string;
+    /** MIME type supplied by the controlling interface. */
+    mediaType: string;
+    /** Complete base64 payload needed to reconstruct the input block. */
+    data: string;
+}
+/** Controller input bytes or rejected text that the persisted session cannot retain. */
+export interface SnapshotInputManifest {
+    /** One-shot task absent from the canonical log only when no user event was accepted. */
+    task?: string;
+    /** Binary inputs keyed by the content-addressed ids retained in session JSONL. */
+    attachments?: SnapshotInputAttachment[];
+}
+/** Optional reference to another scenario's canonical session. */
+export interface SnapshotSessionReference {
+    /** Repository-relative POSIX path to the owning scenario's selected parent Session fixture. */
+    source: string;
+}
+/** Historical-format behavior one retained scenario permanently exercises. */
+export type SnapshotSessionFormatCoverage = 'multi-hop' | 'packed-row' | 'retry-failure' | 'shipped-profile' | 'adjacent-migration';
+/** Explicit historical generation retained by an owning scenario. */
+export interface SnapshotSessionFormatManifest {
+    /** Selected fixture generation; absent manifest metadata tracks the current writer. */
+    readonly version: number;
+    /** Migration behaviors that require this historical fixture. */
+    readonly coverage: readonly SnapshotSessionFormatCoverage[];
+}
+/** Declarative ownership metadata stored beside a recorded session. */
+export interface SnapshotManifest {
+    /** Manifest format version. */
+    version: 1;
+    /** Scenario directory name, repeated for reviewable move and copy diagnostics. */
+    scenario?: string;
+    /** Shipped profile whose public interface controls the scenario. */
+    profile: SnapshotProfile;
+    /** Composition id whose sole pin owns its profile patches. */
+    composition?: string;
+    /** Whether the session is live-recordable or deliberately authored. */
+    recording?: SnapshotRecording;
+    /** Request-header class and sidecar ownership. */
+    header?: SnapshotHeaderManifest;
+    /** Exceptional replay metadata absent for ordinary successful recordings. */
+    replay?: SnapshotReplayManifest;
+    /** Optional host requirement; portable scenarios omit it. */
+    platform?: SnapshotPlatform;
+    /** Explicit process fallback permission preset. */
+    permission?: SnapshotPermission;
+    /** Test-only string environment additions needed by the declared composition. */
+    environment?: Record<string, string>;
+    /** Workspace setup and external final-state ownership. */
+    workspace?: SnapshotWorkspaceManifest;
+    /** Exceptional controller input absent for ordinary log-driven scenarios. */
+    input?: SnapshotInputManifest;
+    /** Absent when this directory owns its selected parent fixture; present for a read-only borrower. */
+    session?: SnapshotSessionReference;
+    /** Historical generation retained by an owner instead of tracking the current writer. */
+    sessionFormat?: SnapshotSessionFormatManifest;
+}
+/** Snapshot execution modes that may read or replace committed fixture generations. */
+export type SnapshotSessionWriteMode = 'replay' | 'record' | 'refresh';
+/**
+ * Whether one run writes current-writer Session fixtures for this scenario.
+ * Explicit historical generations remain immutable replay inputs; record and
+ * refresh may still update their non-Session expected outputs.
+ *
+ * @param manifest - Parsed scenario ownership and retained-generation metadata.
+ * @param mode - Snapshot execution mode.
+ * @returns True only when a write-capable mode tracks the current writer.
+ */
+export declare function writesCurrentSessionFixtures(manifest: SnapshotManifest, mode: SnapshotSessionWriteMode): boolean;
+/**
+ * Parse one `snapshot.yml` without admitting JavaScript YAML tags or unknown fields.
+ * @param source - complete manifest text.
+ * @param path - diagnostic path.
+ * @returns validated manifest metadata.
+ */
+export declare function parseSnapshotManifest(source: string, path?: string): SnapshotManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/lib/types/normalize.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Pure ACP transcript and session-log normalizers. They scrub session ids, run cwd, RPC ids,
+ * timestamps, goal lifecycle clocks, and hook duration while preserving semantic payload values.
+ * The prompt-text and tool-schema scrubbers stay composable so one scenario per header class can
+ * pin prompt and tool-schema sidecars.
+ * @module @x1a0f3n9/dsh-session-snapshot/normalize
+ */
+/**
+ * Extract every snapshot-mode spill path from a session log, keyed by spill
+ * filename. Used by refresh write-back to keep spill paths stable across runs.
+ * @param content - the raw session log text to scan.
+ * @returns spill filename → the full matched spill path, last match wins per name.
+ */
+export declare function extractSnapshotSpillPaths(content: string): Map<string, string>;
+/** Inputs the normalizers need to recognize a run's volatile values. */
+export interface NormalizeContext {
+    /** The session id(s) the run issued — replaced with `{{sessionId}}`. */
+    sessionIds: string[];
+    /** The generated cwd the run used — replaced with `{{cwd}}`. */
+    cwd: string;
+    /** Other filesystem spellings of the same cwd (for example Windows short and long paths). */
+    cwdAliases?: readonly string[];
+}
+/** How cwd-rooted path separators are represented after the cwd is tokenized. */
+export type CwdPathMode = 'canonical' | 'native';
+/** Optional controls shared by stdout and session-log normalization. */
+export interface NormalizeOptions {
+    /** Use `/` for shared goldens, or preserve captured separators for a platform-specific golden. */
+    cwdPathMode?: CwdPathMode;
+    /** Keep already-redacted typed ids and arbitrary UUID-like prose unchanged. */
+    identityMode?: 'legacy' | 'preserve';
+}
+/**
+ * Store one generated workspace as `{{cwd}}` while retaining every other
+ * session value. The caller opts in only for workspaces created under a
+ * platform temporary root; explicitly relocated workspaces keep their real
+ * path.
+ *
+ * @param rawLog The raw or refresh-stabilized session JSONL fixture.
+ * @returns Compact JSONL whose known cwd spellings become `{{cwd}}`.
+ * @throws If a non-empty line is invalid JSON or the session cwd has no basename.
+ */
+export declare function tokenizeSessionFixtureCwd(rawLog: string): string;
+/**
+ * Normalize a raw stdout transcript (newline-delimited JSON-RPC frames) into a stable expected output
+ * in the same shape as the wire: one compact JSON frame per line (NDJSON), with the JSON-RPC
+ * `id` rewritten to a per-transcript sequence (1, 2, 3, …) and all volatile strings scrubbed.
+ * Invalid JSON throws, doubling as a protocol-stdout purity check.
+ *
+ * @param rawStdout The captured stdout bytes, decoded utf8.
+ * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
+ * @returns The normalized NDJSON transcript, one frame per line.
+ */
+export declare function normalizeStdout(rawStdout: string, ctx: NormalizeContext, options?: NormalizeOptions): string;
+/**
+ * Normalize a session JSONL log into a stable expected output: the header line's
+ * volatile fields (`createdAt`, `id`, `cwd`) are zeroed/scrubbed; event,
+ * historical packed-row, embedded Assistant-stream, goal lifecycle, and
+ * catalog child-creation clocks are zeroed; and all volatile strings are
+ * scrubbed. Projected inputs remain
+ * projected. Packed `data.dt` gaps are normalized even when the projected row
+ * omits its `time0` anchor.
+ * Output is JSONL in the same shape as the input — one compact record per
+ * line.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
+ * @returns The normalized JSONL log, one record per line.
+ */
+export declare function normalizeSessionLog(rawLog: string, ctx: NormalizeContext, options?: NormalizeOptions): string;
+/**
+ * Normalize and project persisted session JSONL for a committed fixture.
+ * This composes ordinary log normalization with request-header scrubbing and
+ * persistence-envelope projection, then writes the v3 logical event stream as
+ * one record per event, independent of persistence flush boundaries. Event order
+ * and source-event references are preserved.
+ *
+ * @param rawLog - persisted or already-projected session JSONL.
+ * @param ctx - the run's volatile values to scrub.
+ * @param options - separator output controls.
+ * @returns normalized committed session snapshot JSONL.
+ */
+export declare function normalizeSessionSnapshot(rawLog: string, ctx: NormalizeContext, options?: NormalizeOptions): string;
+/**
+ * Normalize one scenario's primary and child logs with shared typed identity redaction.
+ * @param rawLogs - primary-first persisted or projected session JSONL.
+ * @param ctx - generated cwd spellings and other volatile run facts.
+ * @param options - separator controls; relationship-preserving identity mode is mandatory.
+ * @returns normalized session fixtures in input order.
+ */
+export declare function normalizeSessionSnapshots(rawLogs: readonly string[], ctx: NormalizeContext, options?: Omit<NormalizeOptions, 'identityMode'>): string[];
+/**
+ * Omit the artifact header generation after official migration for comparison.
+ * Delivery and captured-source generations retain their opaque recorded values.
+ * @param rawLog - Session records or events as compact JSON lines.
+ * @returns the same records with only the Session header version omitted.
+ */
+export declare function normalizeSessionFormatProvenance(rawLog: string): string;
+/**
+ * Replace the rendered prompt text of every `system/message` event with the
+ * `{{system}}` token. The text block keeps its position and type, so the
+ * fixture still shows one system node per prompt version; an empty `content`
+ * (no system prompt) stays empty. Request headers and every other line pass
+ * through byte-for-byte; the transform is idempotent.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with system-prompt text tokenized.
+ */
+export declare function scrubSystemPrompts(rawLog: string): string;
+/**
+ * Replace tool schemas in full request-header snapshots with `{{tools}}`
+ * tokens while retaining field presence. System-prompt text stays verbatim so
+ * pinning fixtures can move only schema bulk into their dedicated JSON
+ * sidecar. Lines without a tool payload pass through byte-for-byte; the
+ * transform is idempotent.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with tool-schema content tokenized.
+ */
+export declare function scrubToolSchemas(rawLog: string): string;
+/**
+ * Replace all bulky model-request content in a session JSONL with stable
+ * tokens: the `system/message` prompt text handled by
+ * {@link scrubSystemPrompts} and the request-header tool schemas handled by
+ * {@link scrubToolSchemas}. Field presence, config, and reason are kept.
+ * Lines without content to scrub pass through byte-for-byte, and the
+ * transform is idempotent.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with prompt text and schema bulk tokenized, other lines byte-identical.
+ */
+export declare function scrubModelRequestBulk(rawLog: string): string;
+/**
+ * Project a persisted session log while tokenizing prompt text and schema
+ * bulk. Each non-empty line is parsed at most once; the session header stays
+ * byte-identical. Body records omit their persistence-only envelopes.
+ *
+ * @param rawLog - persisted or already-projected session JSONL.
+ * @returns committed snapshot JSONL with prompt text and tool schemas tokenized.
+ */
+export declare function scrubSessionSnapshot(rawLog: string): string;
+//# sourceMappingURL=normalize.d.ts.map