@deepseek-ai/dsh-session-snapshot 0.1.2-alpha.2

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-snapshot`.
+* @module @deepseek-ai/dsh-session-snapshot/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-snapshot";
+/** Cordis companion plugin name. */
+const name = "session-snapshot-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this test-support package owns no production event stream or mutable data;
+* consuming test suites exercise its behavior.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/harness.d.ts

@@ -0,0 +1,239 @@
+/**
+ * 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 @deepseek-ai/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.
+ * `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 one stable, fixed-length spill root owned by this scenario.
+ * 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,26 @@
+/**
+ * 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 scrubRequestHeaders} / {@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 @deepseek-ai/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, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.ts';
+export { parseSnapshotManifest, type SnapshotHeaderManifest, type SnapshotInputAttachment, type SnapshotInputManifest, type SnapshotManifest, type SnapshotPermission, type SnapshotPlatform, type SnapshotProfile, type SnapshotRecording, type SnapshotReplayManifest, type SnapshotSessionReference, type SnapshotWorkspaceManifest, } from './manifest.ts';
+export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, sessionFixtureNames, stabilizeFixtureMessageIds, stabilizeRefreshLog, 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/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-snapshot`.
+ * @module @deepseek-ai/dsh-session-snapshot/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-snapshot-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.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 @deepseek-ai/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,98 @@
+/** 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;
+}
+/** 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 under the user's home instead of a temporary root. */
+    parent?: 'home';
+}
+/** 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 from this scenario directory to the owning `session.jsonl`. */
+    source: string;
+}
+/** 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 `session.jsonl`; present for a read-only borrower. */
+    session?: SnapshotSessionReference;
+}
+/**
+ * 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,137 @@
+/**
+ * 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.
+ * Request-header scrubbers stay composable so one scenario per header class can pin prompt and
+ * tool-schema sidecars.
+ * @module @deepseek-ai/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, ordinary
+ * event `time`, packed-row `time0`, and goal-change lifecycle clock values 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 packs the logical event stream into a
+ * canonical layout independent of persistence flush boundaries.
+ *
+ * @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[];
+/**
+ * Replace system-prompt content in request headers with `{{system}}` tokens
+ * while retaining field presence.
+ * Other header content stays verbatim, so a header-pinning fixture can keep
+ * its complete tool schemas while every JSONL fixture omits the prompt text.
+ * Lines without a system payload pass through byte-for-byte; the transform is
+ * idempotent.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with system-prompt content tokenized.
+ */
+export declare function scrubSystemPrompts(rawLog: string): string;
+/**
+ * Replace tool schemas in full request-header snapshots with `{{tools}}`
+ * tokens while retaining field presence. System prompts and session-prefix
+ * messages stay 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 request-header content in a session JSONL with stable
+ * tokens. This includes the system-prompt fields handled by
+ * {@link scrubSystemPrompts}, tool schemas, and session-prefix messages. It
+ * keeps prefix message counts, field presence, config, and reason. 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 all header bulk tokenized, other lines byte-identical.
+ */
+export declare function scrubRequestHeaders(rawLog: string): string;
+/**
+ * Project a persisted session log while tokenizing all request-header bulk.
+ * Each non-empty line is parsed at most once; the session header stays
+ * byte-identical. Body records omit their persistence-only envelopes, and
+ * request-header payloads are tokenized.
+ *
+ * @param rawLog - persisted or already-projected session JSONL.
+ * @returns committed snapshot JSONL with request headers tokenized.
+ */
+export declare function scrubSessionSnapshot(rawLog: string): string;
+//# sourceMappingURL=normalize.d.ts.map