@deepseek-ai/dsh-session-snapshot 0.1.3-alpha.2 → 0.1.5-alpha.2

package/lib/types/harness.d.ts

@@ -39,7 +39,8 @@ export type { AgentUnderTest } from './launcher.ts';
  * `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.
+ * 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
@@ -219,7 +220,7 @@ export interface RunOptions {
     configPath?: string;
 }
 /**
- * Derive one stable, fixed-length spill root owned by this scenario.
+ * 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.

package/lib/types/index.d.ts

@@ -4,7 +4,7 @@
  * 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
+ * {@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;
@@ -19,9 +19,9 @@
 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, scrubRequestHeaders, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.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, type PersistedSessionFile, type SessionFixtureFile, } from './session-files.ts';
-export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeFixtureMessageIds, stabilizeRefreshLog, type Scenario, type SnapshotSuiteOptions, } from './suite.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/manifest.d.ts

@@ -19,6 +19,8 @@ export interface SnapshotHeaderManifest {
     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 {
@@ -35,8 +37,8 @@ export interface SnapshotWorkspaceManifest {
     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';
+    /** 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 {

package/lib/types/normalize.d.ts

@@ -1,8 +1,8 @@
 /**
  * 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.
+ * The prompt-text and tool-schema scrubbers stay composable so one scenario per header class can
+ * pin prompt and tool-schema sidecars.
  * @module @deepseek-ai/dsh-session-snapshot/normalize
  */
 /**
@@ -56,8 +56,9 @@ export declare function normalizeStdout(rawStdout: string, ctx: NormalizeContext
 /**
  * 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, and goal lifecycle clocks
- * are zeroed; and all volatile strings are scrubbed. Projected inputs remain
+ * 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
@@ -72,8 +73,9 @@ export declare function normalizeSessionLog(rawLog: string, ctx: NormalizeContex
 /**
  * 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 v2 logical event stream as
- * one record per event, independent of persistence flush boundaries.
+ * 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.
@@ -90,54 +92,53 @@ export declare function normalizeSessionSnapshot(rawLog: string, ctx: NormalizeC
  */
 export declare function normalizeSessionSnapshots(rawLogs: readonly string[], ctx: NormalizeContext, options?: Omit<NormalizeOptions, 'identityMode'>): string[];
 /**
- * Omit only generation-qualified operational provenance from expected-output comparison.
+ * 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 without delivery or captured-source generation qualifiers.
+ * @returns the same records with only the Session header version omitted.
  */
 export declare function normalizeSessionFormatProvenance(rawLog: string): 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.
+ * 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 content tokenized.
+ * @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 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.
+ * 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 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.
+ * 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 all header bulk tokenized, other lines byte-identical.
+ * @returns The JSONL with prompt text and schema bulk tokenized, other lines byte-identical.
  */
-export declare function scrubRequestHeaders(rawLog: string): string;
+export declare function scrubModelRequestBulk(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.
+ * 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 request headers tokenized.
+ * @returns committed snapshot JSONL with prompt text and tool schemas tokenized.
  */
 export declare function scrubSessionSnapshot(rawLog: string): string;
 //# sourceMappingURL=normalize.d.ts.map

package/lib/types/session-files.d.ts

@@ -25,6 +25,13 @@ export interface PersistedSessionFile {
  * @returns The lowercase canonical JSONL filename.
  */
 export declare function sessionFixtureName(index: number, version: number): string;
+/**
+ * Name the native-writer oracle for a retained historical replay role.
+ * This expected output never participates in replay generation selection.
+ * @param index - Parent `0` or a positive child/ordinal slot.
+ * @returns The expected-output JSONL basename.
+ */
+export declare function writerSnapshotName(index: number): string;
 /**
  * Parse one canonical recorded-session fixture filename.
  *

package/lib/types/suite.d.ts

@@ -9,9 +9,10 @@
  * refresh stay serial while writing.
  *
  * Exactly one scenario per header-composition class pins the tokenized header
- * sequence. Its prompt and tool-schema sequences live in independent
- * sidecars, each of which may be shared with another class pin when the bytes
- * are identical. Every live header is checked against the composed pin, so
+ * sequence and the tokenized `system/message` sequence. Its prompt and
+ * tool-schema sequences live in independent sidecars, each of which may be
+ * shared with another class pin when the bytes are identical. Every live
+ * header and system prompt is checked against the composed pin, so
  * session-dependent composition must declare a separate class instead of
  * escaping coverage.
  * @module @deepseek-ai/dsh-session-snapshot/suite
@@ -64,13 +65,13 @@ export interface Scenario {
     /**
      * Header-pinning scenario whose `system-prompt.expected.md` this pin reuses.
      * Defaults to this scenario. The source must own its prompt sidecar and
-     * declare the same {@link expectedHeaderChanges}; meaningless off a pin.
+     * declare the same {@link expectedPromptChanges}; only valid on a pin.
      */
     systemPromptSource?: string;
     /**
      * Header-pinning scenario whose `tool-schemas.expected.json` this pin reuses.
      * Defaults to this scenario. The source must own its schema sidecar and
-     * declare the same {@link expectedHeaderChanges}; meaningless off a pin.
+     * declare the same {@link expectedHeaderChanges}; only valid on a pin.
      */
     toolSchemasSource?: string;
     /**
@@ -89,10 +90,18 @@ export interface Scenario {
     pinsChildSystemPrompts?: readonly number[];
     /**
      * How many changed `request/header` snapshots this PINNING scenario's primary
-     * fixture legitimately carries (default 0). Their full prompt text is kept in
-     * the readable Markdown pin; any other count fails. Meaningless off the pin.
+     * fixture legitimately carries (default 0). Each change owns one more schema
+     * set in the structured JSON pin; any other count fails. Only valid on the pin.
      */
     expectedHeaderChanges?: number;
+    /**
+     * How many later `system/message` events — replacements of surface node 0
+     * or in-history appends — this PINNING scenario's primary fixture
+     * legitimately carries after the initial prompt (default 0). Each change's
+     * full prompt text is kept in the readable Markdown pin; any other count
+     * fails. Only valid on the pin.
+     */
+    expectedPromptChanges?: number;
     /**
      * Which header-composition class this scenario belongs to. Scenarios that
      * boot the same config compose the same header; each class has exactly one
@@ -240,8 +249,7 @@ export declare function fixtureContext(fixture: string): NormalizeContext;
  * The `data.header` payload of every `request/header` event in a session
  * JSONL, in log order, with the log's volatile values scrubbed first
  * ({@link normalizeSessionLog}) so headers harvested from different runs —
- * each embedding its own generated cwd in the composed prompt — compare on equal
- * footing.
+ * each embedding its own generated cwd — compare on equal footing.
  *
  * @param rawLog The session `.jsonl` content to extract headers from.
  * @param ctx The volatile values of the run that produced it.
@@ -249,15 +257,26 @@ export declare function fixtureContext(fixture: string): NormalizeContext;
  */
 export declare function normalizedHeaders(rawLog: string, ctx: NormalizeContext): unknown[];
 /**
- * The normalized string-valued system prompts carried by request headers in a
- * session JSONL, in log order. Headers without a string prompt are omitted so
- * callers can assert one prompt per header explicitly.
+ * The normalized prompt text of every `system/message` event in a session
+ * JSONL, in log order: the first is the initial system prompt (surface node 0)
+ * and each later one replaced it or, on an in-history route, appended the
+ * changed prompt after the cached history. An empty `content` yields `''`; a
+ * `system/message` without a text block is omitted.
  *
  * @param rawLog The session `.jsonl` content to inspect.
  * @param ctx The volatile values of the run that produced it.
- * @returns The normalized system prompts, in header order.
+ * @returns The normalized system prompts, in log order.
  */
 export declare function normalizedSystemPrompts(rawLog: string, ctx: NormalizeContext): string[];
+/**
+ * Whether every model request in a session JSONL is preceded by its system
+ * prompt: the log has no `request/header`, or a `system/message` event comes
+ * before its first `request/header`.
+ *
+ * @param rawLog The session `.jsonl` content to inspect.
+ * @returns True when the first `request/header` (if any) follows a `system/message`.
+ */
+export declare function systemPromptPrecedesRequests(rawLog: string): boolean;
 /**
  * The normalized tool-schema arrays carried by request headers in a session
  * JSONL, in log order. Headers without an array-valued tools field are omitted
@@ -303,11 +322,22 @@ export declare function restorePinnedToolSchemas(header: unknown, schemas: reado
  * Prompt text is unchanged except that a missing terminal newline is added so
  * the committed file follows the repository newline contract.
  *
- * @param prompt The normalized system prompt.
- * @param changes Full normalized prompts from later changed-header snapshots.
+ * @param prompt The normalized initial system prompt (surface node 0).
+ * @param changes Full normalized prompts from later `system/message` events, replacements or in-history appends.
  * @returns Markdown snapshot text ending in a newline.
  */
 export declare function formatSystemPromptSnapshot(prompt: string, changes?: readonly string[]): string;
+/**
+ * Split a prompt sidecar into its initial prompt and each later change, the
+ * inverse of {@link formatSystemPromptSnapshot}.
+ *
+ * @param snapshot The Markdown sidecar text.
+ * @returns The initial prompt snapshot plus one entry per later `system/message`.
+ */
+export declare function parseSystemPromptSnapshot(snapshot: string): {
+    initial: string;
+    changes: string[];
+};
 /**
  * Reject a child prompt sidecar that cannot own distinct, canonical prompt text.
  * @param sidecar - committed child prompt snapshot.
@@ -375,12 +405,20 @@ export declare function refreshFixtureReplacements(logs: HarvestedLog[], fixture
  * @returns The stabilized JSONL content to write back.
  */
 export declare function stabilizeRefreshLog(fresh: string, existing: string, replacements: FixtureReplacement[], freshContext: NormalizeContext): string;
+/**
+ * Check every selected role for tool/path defects and current generations for canonical prompt/identity storage.
+ * Historical roles retain their released bytes, including roles retired by the current writer.
+ * @param dir Scenario directory containing canonical Session fixtures.
+ * @param scenarioName Scenario name used in failure diagnostics.
+ * @returns Resolves when all selected fixtures satisfy the storage checks.
+ */
+export declare function assertSessionFixtureStorage(dir: string, scenarioName: string): Promise<void>;
 /**
  * Register the suite: one test per scenario (the expected-output and log comparisons and
- * the header-uniformity guard) plus the fixture guard block (no orphan
+ * the header and prompt uniformity guard) plus the fixture guard block (no orphan
  * scenario dirs, required files present, exactly one pin per header class,
- * shared sidecars unique and well-formed, every JSONL prompt-scrubbed,
- * non-pinning fixtures fully header-scrubbed). Must
+ * shared sidecars unique and well-formed, every JSONL prompt- and
+ * schema-scrubbed with a `system/message` before its first request). Must
  * run at vitest collection time — it calls `describe`/`it`. Throws
  * immediately if any header class lacks a pinning scenario or carries two
  * (the uniformity guard needs exactly one comparison anchor per class).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-snapshot",
   "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -31,28 +31,28 @@
     "js-yaml": "^4.2.0",
     "vitest": "^4.1.8",
     "@deepseek-ai/cordis-plugin-include": "1.0.7",
-    "@deepseek-ai/dsh-llm-replay": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-loader-smoke": "0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-format": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-loader-smoke": "0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-format": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm-replay": "^0.1.5-alpha.2"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-http-proxy": "^0.1.5-alpha.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-compaction": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-user-questions": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-compaction": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-user-questions": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.5-alpha.2"
   }
 }