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

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

@@ -0,0 +1,104 @@
+/** Immutable Session-generation filenames used by recorded-session fixtures. */
+/** One canonical recorded-session fixture filename. */
+export interface SessionFixtureFile {
+    /** Parent is `0`; positive values are child/ordinal slots. */
+    readonly index: number;
+    /** Physical Session format generation; zero is encoded by omission. */
+    readonly version: number;
+    /** Canonical filename. */
+    readonly name: string;
+}
+/** One canonical persistence filename in a Session's own storage directory. */
+export interface PersistedSessionFile {
+    /** Physical Session format generation; zero is encoded by omission. */
+    readonly version: number;
+    /** Physical compression selected by the backend. */
+    readonly compression: 'raw' | 'zstd';
+    /** Canonical basename. */
+    readonly name: string;
+}
+/**
+ * Return the canonical fixture filename for one parent/ordinal and generation.
+ *
+ * @param index - Parent `0` or a positive child/ordinal slot.
+ * @param version - Physical format generation; `0` is omitted.
+ * @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.
+ *
+ * @param name - Basename from a scenario directory.
+ * @returns Parsed role and generation, or `undefined` for an unrelated file.
+ */
+export declare function parseSessionFixtureName(name: string): SessionFixtureFile | undefined;
+/**
+ * Select the highest generation for every parent/ordinal fixture role.
+ * Older generations remain in the directory but do not count as extra Sessions.
+ *
+ * @param names - File basenames in one scenario directory.
+ * @returns Parent first, followed by contiguous child/ordinal roles.
+ */
+export declare function sessionFixtureFiles(names: readonly string[]): SessionFixtureFile[];
+/**
+ * Validate and order a scenario directory's selected Session fixture filenames.
+ *
+ * @param names - File basenames in one scenario directory.
+ * @returns Highest-generation parent and child/ordinal filenames.
+ */
+export declare function sessionFixtureNames(names: readonly string[]): string[];
+/**
+ * Read the declared physical generation from one Session JSONL header.
+ *
+ * @param content - Complete UTF-8 JSONL content.
+ * @param label - Diagnostic filename or path.
+ * @returns The declared non-negative format generation.
+ */
+export declare function sessionHeaderVersion(content: string, label: string): number;
+/**
+ * Require one fixture's canonical filename generation to equal its header.
+ *
+ * @param name - Canonical fixture basename.
+ * @param content - Complete UTF-8 JSONL content.
+ * @returns The validated format generation.
+ */
+export declare function assertSessionFixtureVersion(name: string, content: string): number;
+/**
+ * Return the canonical persistence basename for one generation and compression.
+ *
+ * @param version - Physical format generation; `0` is omitted.
+ * @param compression - Backend compression mode.
+ * @returns The canonical persistence basename.
+ */
+export declare function persistedSessionFilename(version: number, compression?: 'raw' | 'zstd'): string;
+/**
+ * Parse a canonical persistence basename from a Session's own directory.
+ *
+ * @param name - Candidate basename.
+ * @returns Its generation and compression, or `undefined` for noise and noncanonical names.
+ */
+export declare function parsePersistedSessionFilename(name: string): PersistedSessionFile | undefined;
+/**
+ * Select one highest-generation persistence path per physical Session directory.
+ *
+ * @param paths - Relative or absolute paths beneath a sessions root.
+ * @param compression - Compression selected by the snapshot composition.
+ * @returns Stable path order with older generations and filesystem noise omitted.
+ */
+export declare function latestPersistedSessionPaths(paths: readonly string[], compression?: 'raw' | 'zstd'): string[];
+/**
+ * Require one persistence basename's generation to equal its Session header.
+ *
+ * @param name - Canonical persistence basename.
+ * @param content - Complete uncompressed UTF-8 JSONL content.
+ * @returns The validated generation.
+ */
+export declare function assertPersistedSessionVersion(name: string, content: string): number;
+//# sourceMappingURL=session-files.d.ts.map

package/lib/types/suite.d.ts

@@ -0,0 +1,430 @@
+/**
+ * Keyless-by-default ACP snapshot suite factory. Each scenario drives the real
+ * subprocess and compares normalized stdout; comparable session fixtures are
+ * both replay input and expected output. Record mode refreshes reproducible
+ * model scenarios from the live API, while refresh mode replays committed
+ * scripts and rewrites derived artifacts without a key.
+ * Replay scenarios run concurrently because each subprocess owns unique temp
+ * cwd and persistence roots and reads only committed fixtures. Record and
+ * refresh stay serial while writing.
+ *
+ * Exactly one scenario per header-composition class pins the tokenized header
+ * 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 @x1a0f3n9/dsh-session-snapshot/suite
+ */
+import { type AgentUnderTest, type HarvestedLog } from './harness.ts';
+import { type SnapshotSessionFormatManifest } from './manifest.ts';
+import { type CwdPathMode, type NormalizeContext } from './normalize.ts';
+/** A snapshot scenario and how its fixtures are produced. */
+export interface Scenario {
+    name: string;
+    /** Deployment environment for this scenario's subprocess. */
+    env?: NodeJS.ProcessEnv;
+    /** Whether the scenario drives at least one model turn (so a JSONL expected output applies). */
+    hasModelTurn: boolean;
+    /**
+     * Whether the run persists a comparable session log to diff against the
+     * selected parent Session fixture. Defaults to {@link hasModelTurn} (a model turn
+     * always produces a log worth comparing). Set it independently for a scenario
+     * that produces a non-trivial durable log without calling the model.
+     */
+    comparesLog?: boolean;
+    /**
+     * Whether `test:snapshot:record` regenerates this scenario's current-version
+     * Session fixtures from the LIVE API. `recorded` scenarios are model-driven and reproducible;
+     * `authored` scenarios (fixtures hand-written or hand-harvested — e.g. a
+     * provider error or a cancel the live API can't be coaxed into
+     * deterministically, a deterministic hook scenario, or a scripted repetition
+     * a live model won't reproduce) are NEVER re-recorded.
+     */
+    recorded: boolean;
+    /** Historical generation retained as a read-only migration fixture. */
+    sessionFormat?: SnapshotSessionFormatManifest;
+    /**
+     * Whether replay is driven by a hand-written `replay.override.json` sidecar
+     * (a `ReplayOverrideDoc` that replaces or patches the script derived from
+     * selected parent Session fixture) — the throw/hang cases chunks cannot express. The fixture
+     * guard requires the sidecar exactly when this is set: the harness forwards
+     * the file purely on existence, so an unregistered stray sidecar would
+     * silently alter the derived script. The guard fails loud on either
+     * mismatch. Defaults to false (replay derives from the fixture's
+     * `assistant/chunk` events).
+     */
+    overridden?: boolean;
+    /**
+     * Whether this scenario is its header class's sole tokenized request-header
+     * pin. Prompt and tool-schema sidecars are selected independently, while
+     * every classmate is checked for equality with the reconstructed header.
+     */
+    pinsHeader?: boolean;
+    /**
+     * 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 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}; only valid on a pin.
+     */
+    toolSchemasSource?: string;
+    /**
+     * Child fixture indices whose own schema sequence is pinned separately,
+     * where `1` names `session.1.jsonl` and
+     * `tool-schemas.1.expected.json`. The class pin still owns every other
+     * request-header field.
+     */
+    pinsChildToolSchemas?: readonly number[];
+    /**
+     * Child fixture indices whose own system prompt is pinned separately, where
+     * `1` names `session.1.jsonl` and `system-prompt.1.expected.md`. A child
+     * scope that installs its own prompt section (the continuable `report`
+     * guidance) composes a prompt the class pin cannot describe.
+     */
+    pinsChildSystemPrompts?: readonly number[];
+    /**
+     * How many changed `request/header` snapshots this PINNING scenario's primary
+     * 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
+     * {@link pinsHeader} scenario, and the uniformity guard compares every
+     * other member against ITS class's pin. Defaults to `'default'`; a
+     * scenario booting an alternate config ({@link configPath}) whose tool
+     * list or prompt sections differ by construction carries its own class.
+     */
+    headerClass?: string;
+    /**
+     * Alternate live profile patch (absolute) this scenario boots instead of
+     * {@link AgentUnderTest.configPath}. Its basename must still end in
+     * `cordis.yml` so the launcher finds the replay sibling. A scenario whose
+     * patch changes the composed header also needs its own
+     * {@link headerClass}.
+     */
+    configPath?: string;
+    /**
+     * Parent directory for the generated session cwd. Defaults to the platform
+     * temp directory; set this when temp is itself part of the behavior under
+     * test and the scenario needs an independent project location.
+     */
+    workspaceParent?: string;
+    /**
+     * Optional final workspace preparation after the committed fixture is
+     * copied. Reserve this for paths that Git cannot represent portably; normal
+     * scenario files belong under the scenario's `workspace/` directory.
+     */
+    prepareWorkspace?: (cwd: string) => void | Promise<void>;
+    /**
+     * Whether Windows additionally compares stdout with native separators against
+     * `stdout.expected.windows.jsonl`. The shared canonical stdout expected output is still
+     * compared on every platform, and the fixture guard requires this sidecar
+     * exactly when the option is set.
+     */
+    pinsNativeWindowsStdout?: boolean;
+    /**
+     * Whether the scenario requires a non-Windows host, such as for POSIX process
+     * semantics or generated paths Windows cannot represent. The scenario's run
+     * test is skipped on Windows; its fixtures stay guarded on every platform.
+     */
+    posixOnly?: boolean;
+    /**
+     * Whether the scenario boots a composition that needs a usable `pwsh`
+     * (the pwsh-tool-turn scenario). The run test is skipped when the suite's
+     * {@link SnapshotSuiteOptions.hasPwsh} probe is false; fixtures stay guarded
+     * on every platform.
+     */
+    pwshOnly?: boolean;
+}
+/**
+ * Whether a scenario's run test is skipped for this mode and host: record mode
+ * skips authored (non-`recorded`) scenarios and explicit historical Session
+ * generations, {@link Scenario.posixOnly} scenarios skip on Windows, and
+ * {@link Scenario.pwshOnly} scenarios skip when the caller's `hasPwsh` probe
+ * is false.
+ *
+ * @param scenario The scenario whose run test is being registered.
+ * @param recording Whether the suite runs in record mode.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @param hasPwsh The caller's pwsh-availability probe; `pwshOnly` scenarios
+ *   skip unless it is true.
+ * @returns True when the scenario's run test must not execute.
+ */
+export declare function scenarioSkipped(scenario: Scenario, recording: boolean, platform?: NodeJS.Platform, hasPwsh?: boolean): boolean;
+/** One stdout expected output selected for a platform run. */
+interface StdoutExpectedVariant {
+    file: string;
+    cwdPathMode: CwdPathMode;
+}
+/**
+ * Select the shared stdout expected output plus any platform-native assertion declared by a scenario.
+ *
+ * @param scenario The scenario whose stdout contract is being selected.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @returns The ordered expected-output variants: shared canonical first, then optional Windows native.
+ */
+export declare function stdoutExpectedVariants(scenario: Scenario, platform?: NodeJS.Platform): StdoutExpectedVariant[];
+/** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */
+export interface SnapshotSuiteOptions {
+    /** The agent composition every scenario boots. */
+    agent: AgentUnderTest;
+    /** Absolute path of the suite's `snapshots/` directory (one subdir per scenario). */
+    snapshotsDir: string;
+    /** The scenario table; exactly one entry per header class must set `pinsHeader`. */
+    scenarios: Scenario[];
+    /**
+     * `replay` (keyless, the default tier), `record` (live API; re-records the
+     * `recorded` scenarios' fixtures and refreshes the Vitest expected outputs under
+     * `--update`), or `refresh` (keyless replay that rewrites stdout expected outputs and
+     * comparable session fixtures from the replay run). The caller derives this
+     * from `$DSH_SNAPSHOT` — env reading stays outside this library.
+     */
+    mode: 'replay' | 'record' | 'refresh';
+    /**
+     * Whether a real `pwsh` executable is available on this host (the probe the
+     * caller owns; `pwshOnly` scenarios skip when this is not true).
+     */
+    hasPwsh?: boolean;
+}
+/** One scenario's generated claim on a shared snapshot file. */
+export interface SharedSnapshotClaim {
+    /** Scenario that first generated the snapshot in this suite run. */
+    scenario: string;
+    /** Complete generated file content. */
+    content: string;
+}
+/** One committed snapshot file and its complete content. */
+export interface NamedSnapshotContent {
+    /** Diagnostic path of the committed file. */
+    path: string;
+    /** Complete committed file content. */
+    content: string;
+}
+/**
+ * Record one scenario's generated content for a shared snapshot source.
+ * A later claimant must generate identical bytes; otherwise record/refresh
+ * would make the final file depend on scenario order.
+ *
+ * @param claims Claims already made in this suite run, keyed by source path.
+ * @param source The shared snapshot path being claimed.
+ * @param scenario The scenario generating the content.
+ * @param content The complete content the scenario generated.
+ * @returns Nothing.
+ */
+export declare function claimSharedSnapshot(claims: Map<string, SharedSnapshotClaim>, source: string, scenario: string, content: string): void;
+/**
+ * Reject byte-identical committed snapshots stored under different paths.
+ *
+ * @param kind Human-readable snapshot kind for the diagnostic.
+ * @param snapshots The committed files to compare.
+ * @returns Nothing.
+ */
+export declare function assertUniqueSnapshotContents(kind: string, snapshots: readonly NamedSnapshotContent[]): void;
+/**
+ * Derive normalization values from a fixture's own session header. Recorded ids and cwd differ
+ * from the live replay run; the non-empty sentinel for missing cwd avoids accidental empty-
+ * string replacement.
+ *
+ * @param fixture The selected committed parent Session fixture content.
+ * @returns The fixture's own volatile values, ready for {@link normalizeSessionLog}.
+ */
+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 — 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.
+ * @returns The normalized `data.header` payloads, in log order.
+ */
+export declare function normalizedHeaders(rawLog: string, ctx: NormalizeContext): unknown[];
+/**
+ * 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 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
+ * so callers can assert one schema set per header explicitly.
+ *
+ * @param rawLog The session `.jsonl` content to inspect.
+ * @param ctx The volatile values of the run that produced it.
+ * @returns The normalized initial tool-schema arrays, in header order.
+ */
+export declare function normalizedToolSchemas(rawLog: string, ctx: NormalizeContext): unknown[][];
+/** The structured contents of a tool-schema sidecar. */
+export interface ToolSchemasSnapshot {
+    /** The complete tool schemas from the pinned request header. */
+    initial: unknown[];
+    /** Complete tool schemas from subsequent changed-header snapshots. */
+    changes: unknown[][];
+}
+/**
+ * Render the full tool-schema sequence as canonical, readable JSON.
+ *
+ * @param initial The pinned request header's complete tool schemas.
+ * @param changes Complete tool schemas from later changed headers.
+ * @returns A pretty-printed JSON snapshot ending in one newline.
+ */
+export declare function formatToolSchemasSnapshot(initial: readonly unknown[], changes?: readonly unknown[][]): string;
+/**
+ * Parse and validate the stable top-level fields of a tool-schema sidecar.
+ *
+ * @param snapshot The JSON sidecar text.
+ * @returns Its initial and changed-header schema sets.
+ */
+export declare function parseToolSchemasSnapshot(snapshot: string): ToolSchemasSnapshot;
+/**
+ * Restore one sidecar schema set into a tokenized pinned header.
+ *
+ * @param header The parsed request header carrying `tools: "{{tools}}"`.
+ * @param schemas The complete schemas for this full header snapshot.
+ * @returns A copy of the header with its complete schemas restored.
+ */
+export declare function restorePinnedToolSchemas(header: unknown, schemas: readonly unknown[]): unknown;
+/**
+ * Render a normalized prompt as a repository-friendly Markdown snapshot.
+ * 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 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.
+ * @param classPin - initial prompt snapshot owned by the scenario's header class.
+ * @param label - repository-relative fixture label for diagnostics.
+ */
+export declare function assertChildSystemPromptSnapshot(sidecar: string, classPin: string, label: string): void;
+/**
+ * Count changed `request/header` snapshots in a session JSONL.
+ *
+ * @param rawLog The session `.jsonl` content.
+ * @returns How many headers carry reason `change`.
+ */
+export declare function headerChangeCount(rawLog: string): number;
+/** A literal replacement from a fresh replay-run volatile to its existing fixture value. */
+export interface FixtureReplacement {
+    /** The fresh replay run's volatile value. */
+    from: string;
+    /** The existing fixture value retained during write-back. */
+    to: string;
+}
+/**
+ * Carry committed UUIDs into unchanged, unambiguous messages in fresh session fixtures.
+ *
+ * @param logs Fresh fixture-ready session JSONL contents for one scenario.
+ * @param fixtures Existing fixture contents in matching order; missing fixtures may be empty strings.
+ * @returns The fresh contents with only reusable message UUIDs replaced.
+ */
+export declare function stabilizeFixtureMessageIds(logs: readonly string[], fixtures: readonly string[]): string[];
+/**
+ * Find tool calls whose structured result reports `UNKNOWN_TOOL`.
+ *
+ * Snapshot refresh must not turn a missing registration into accepted behavior;
+ * intentional unknown-tool behavior belongs in a focused unit or e2e test.
+ *
+ * @param rawLog The session JSONL to inspect.
+ * @returns The failing call ids in log order, using a diagnostic placeholder when absent.
+ */
+export declare function unknownToolCallIds(rawLog: string): string[];
+/**
+ * Build refresh write-back replacements for per-log session ids, cwd values,
+ * and spill paths. Durable message ids have a later structural owner.
+ *
+ * @param logs The freshly harvested logs, in fixture order.
+ * @param fixtures The existing fixture contents, in matching order.
+ * @returns Literal replacements from fresh values to the fixture's existing values.
+ */
+export declare function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[];
+/**
+ * Rewrite a fresh replay-produced log so repeated refreshes do not churn
+ * volatile fixture fields. Meaningful event payloads come from `fresh`; the
+ * existing fixture lends normalized-equivalent values, including non-message ids, paths,
+ * creation/event times, spill locators, and hook durations, only when the
+ * complete record layout aligns and volatile strings form a consistent
+ * bijection. Complete durable-message ids are excluded because the later
+ * fixture-ready structural pass owns them. Ambiguous layouts or mappings
+ * keep fresh strings. Packed timing gaps expand from zero when a projected
+ * fixture omits `time0`, so packing does not shift later records;
+ * fresh semantic values and fragment arrays remain authoritative.
+ *
+ * @param fresh The newly harvested session JSONL.
+ * @param existing The committed fixture JSONL being refreshed.
+ * @param replacements Cross-log literal replacements from {@link refreshFixtureReplacements}.
+ * @param freshContext The harvested run's ids, cwd, and every cwd alias.
+ * @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 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- 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).
+ *
+ * @param options The agent, snapshots directory, scenario table, and mode.
+ */
+export declare function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void;
+export {};
+//# sourceMappingURL=suite.d.ts.map

package/lib/types/workspace.d.ts

@@ -0,0 +1,58 @@
+/** Capture readable, path-stable workspace state for recorded-session tests. */
+/** Marker that lets Git retain an expected empty directory without becoming expected workspace state. */
+export declare const EMPTY_WORKSPACE_MARKER = ".empty";
+/** One UTF-8 file in a captured workspace. */
+export interface WorkspaceTextFileSnapshot {
+    /** Cwd-relative POSIX path. */
+    readonly path: string;
+    /** Entry discriminator. */
+    readonly kind: 'text';
+    /** Exact UTF-8 contents. */
+    readonly content: string;
+}
+/** One non-text file in a captured workspace. */
+export interface WorkspaceBinaryFileSnapshot {
+    /** Cwd-relative POSIX path. */
+    readonly path: string;
+    /** Entry discriminator. */
+    readonly kind: 'binary';
+    /** Exact bytes encoded for deterministic diffs. */
+    readonly base64: string;
+}
+/** One symbolic link in a captured workspace. */
+export interface WorkspaceSymlinkSnapshot {
+    /** Cwd-relative POSIX path. */
+    readonly path: string;
+    /** Entry discriminator. */
+    readonly kind: 'symlink';
+    /** Exact link text without resolving the target. */
+    readonly target: string;
+}
+/** One empty directory in a captured workspace. */
+export interface WorkspaceEmptyDirectorySnapshot {
+    /** Cwd-relative POSIX path. */
+    readonly path: string;
+    /** Entry discriminator. */
+    readonly kind: 'empty-directory';
+}
+/** Stable complete file, link, and empty-directory state below one workspace root. */
+export type WorkspaceSnapshotEntry = WorkspaceTextFileSnapshot | WorkspaceBinaryFileSnapshot | WorkspaceSymlinkSnapshot | WorkspaceEmptyDirectorySnapshot;
+/** Options for excluding harness-owned root entries from a runtime workspace. */
+export interface CaptureWorkspaceSnapshotOptions {
+    /** Exact immediate children of the workspace root to omit. */
+    readonly ignoredRootEntries?: readonly string[];
+}
+/**
+ * Capture one workspace without resolving links or depending on host path separators.
+ * @param root - Absolute directory whose user-visible state is captured.
+ * @param options - Harness-owned immediate children to omit.
+ * @returns Stable entries sorted by relative path.
+ */
+export declare function captureWorkspaceSnapshot(root: string, options?: CaptureWorkspaceSnapshotOptions): Promise<WorkspaceSnapshotEntry[]>;
+/**
+ * Capture a committed `workspace.expected/` tree, excluding its Git-only empty marker.
+ * @param root - Absolute expected-workspace directory.
+ * @returns Stable expected entries.
+ */
+export declare function captureExpectedWorkspaceSnapshot(root: string): Promise<WorkspaceSnapshotEntry[]>;
+//# sourceMappingURL=workspace.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@x1a0f3n9/dsh-session-snapshot",
+  "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/test-support/session-snapshot"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "js-yaml": "^4.2.0",
+    "vitest": "^4.1.8",
+    "@deepseek-ai/cordis-plugin-include": "1.0.7",
+    "@x1a0f3n9/dsh-llm-replay": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-loader-smoke": "0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session-format": "^0.1.5-rc.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-agent-loop": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-compaction": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-sandbox": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-sandbox-policy": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-subagent": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-user-questions": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.3"
+  }
+}