@anureo/adapter-claude 0.0.0-stage → 0.3.0

package/src/catalog.d.ts

@@ -0,0 +1,26 @@
+import { type CatalogProbeOptions } from '@anureo/sdk/diagnostics';
+import type { ClaudeAdapterOptions } from "./options.js";
+/** Create a reusable catalog for discovering Claude models without submitting prompts.
+ * Construction retains the adapter launch configuration. When a probe opens a query, it uses
+ * the current working directory and disables session persistence and file checkpoints.
+ * Await dispose when finished with the catalog. Aborting an active probe requests disposal of
+ * the shared connection and can affect concurrent callers. Pass a signal to request cancellation.
+ * Deadline enforcement belongs to the caller even when timeoutMs is supplied.
+ *
+ * @example
+ * ```ts
+ * import { createClaudeCatalogSession } from '@anureo/adapter-claude/catalog'
+ *
+ * const catalog = createClaudeCatalogSession({ defaultHome: true })
+ * try {
+ *   console.log(await catalog.listModels())
+ * } finally {
+ *   await catalog.dispose()
+ * }
+ * ```
+ */
+export declare function createClaudeCatalogSession(options: ClaudeAdapterOptions): {
+    prepare: (context?: CatalogProbeOptions) => Promise<void>;
+    listModels: (context?: CatalogProbeOptions) => Promise<import("@anthropic-ai/claude-agent-sdk").ModelInfo[]>;
+    dispose: () => Promise<void>;
+};

package/src/catalog.js

@@ -0,0 +1,168 @@
+// Owns the resident Claude query for prompt-free model discovery.
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { BoundedEventQueue, HarnessSdkError } from '@anureo/sdk';
+import { catalogPhase } from '@anureo/sdk/diagnostics';
+import { createClaudeAdapter } from "./adapter.js";
+/** Create a reusable catalog for discovering Claude models without submitting prompts.
+ * Construction retains the adapter launch configuration. When a probe opens a query, it uses
+ * the current working directory and disables session persistence and file checkpoints.
+ * Await dispose when finished with the catalog. Aborting an active probe requests disposal of
+ * the shared connection and can affect concurrent callers. Pass a signal to request cancellation.
+ * Deadline enforcement belongs to the caller even when timeoutMs is supplied.
+ *
+ * @example
+ * ```ts
+ * import { createClaudeCatalogSession } from '@anureo/adapter-claude/catalog'
+ *
+ * const catalog = createClaudeCatalogSession({ defaultHome: true })
+ * try {
+ *   console.log(await catalog.listModels())
+ * } finally {
+ *   await catalog.dispose()
+ * }
+ * ```
+ */
+export function createClaudeCatalogSession(options) {
+    const adapter = createClaudeAdapter(options);
+    let stream;
+    let input;
+    let pendingHandshakeModels;
+    let preparing;
+    let disposing;
+    return { prepare, listModels, dispose };
+    /** Warm up the catalog by awaiting launch and initial model discovery.
+     * Wait for ongoing disposal before reusing a prepared query or starting a new one. Concurrent
+     * callers share preparation, and the caller that starts it supplies the spawn and handshake
+     * observers. An already-aborted signal rejects with RPC_ABORTED before touching the connection.
+     * Startup failures reject after cleanup, with any cleanup failure taking precedence.
+     */
+    function prepare(context = {}) {
+        return withProbeCleanup(context, async () => {
+            await disposing;
+            if (preparing) {
+                await preparing;
+                return;
+            }
+            if (stream)
+                return;
+            preparing = openConnection(context)
+                .catch(async (cause) => {
+                // Shared disposal can be waiting for this preparation to settle.
+                await closeConnection();
+                throw cause;
+            })
+                .finally(() => { preparing = undefined; });
+            await preparing;
+        });
+    }
+    /** Return native model metadata, preparing the catalog if needed.
+     * Use each query's initial discovery once. Later reads refresh via native reinitialization or
+     * replace the query when it lacks that capability. The supplied observer receives the spawn
+     * and handshake phases this call starts, and model reads are reported after initial preparation.
+     * Success leaves the connection open for reuse. An already-aborted signal rejects with
+     * RPC_ABORTED before work. Probe failures await shared cleanup before rejecting, with any
+     * cleanup failure taking precedence.
+     */
+    async function listModels(context = {}) {
+        return withProbeCleanup(context, async () => {
+            await prepare(context);
+            return catalogPhase(context, 'models', () => readModels(context));
+        });
+    }
+    /** Release the directory connection and allow a later probe to reopen it.
+     * End input, close the query and await its optional native return(). Then wait for pending
+     * preparation to settle and close any query it established in the meantime. Concurrent callers
+     * share the cleanup promise. A cleanup failure rejects that promise and skips remaining steps.
+     */
+    function dispose() {
+        return disposing ??= (async () => {
+            await closeConnection();
+            await preparing?.catch(() => { });
+            // Preparation may establish a connection while dispose waits for it to finish.
+            await closeConnection();
+        })().finally(() => { disposing = undefined; });
+    }
+    /** Run spawn and handshake in order for prepare, caching initial models for listModels.
+     * Retain the input queue before launch so prepare's rollback or dispose can end it after failure.
+     */
+    async function openConnection(context) {
+        input = new BoundedEventQueue();
+        await catalogPhase(context, 'spawn', launchDirectoryQuery);
+        pendingHandshakeModels = await catalogPhase(context, 'handshake', () => stream.supportedModels());
+    }
+    /** Launch the query for openConnection's spawn phase. Publish it to shared state as soon as
+     * the factory returns so cleanup can reach it. A launch failure rejects the phase.
+     */
+    async function launchDirectoryQuery() {
+        stream = (options.queryFactory ?? query)({
+            prompt: input,
+            options: {
+                ...adapter.queryOptions(process.cwd()),
+                persistSession: false,
+                sessionStore: undefined,
+                enableFileCheckpointing: false,
+                mcpServers: {},
+                settingSources: [],
+            },
+        });
+    }
+    /** Supply listModels with cached discovery or refreshed models during its models phase.
+     * A query without reinitialize needs a replacement to obtain fresh metadata. Await disposal
+     * before reopening so a failed close rejects the read before a replacement starts.
+     */
+    async function readModels(context) {
+        if (pendingHandshakeModels)
+            return takeHandshakeModels();
+        const current = stream;
+        if (current.reinitialize)
+            return (await current.reinitialize()).models;
+        await dispose();
+        await prepare(context);
+        return takeHandshakeModels();
+    }
+    /** Transfer the handshake result to readModels and clear the cache so the next read refreshes. */
+    function takeHandshakeModels() {
+        const models = pendingHandshakeModels;
+        pendingHandshakeModels = undefined;
+        return models;
+    }
+    /** Scope a cancellation listener to each prepare or listModels call. The signal invokes it to
+     * request shared disposal so native closure can settle pending work. Reject pre-aborted probes
+     * before registration. If work rejects, await disposal and propagate the cleanup failure if any,
+     * otherwise propagate the work failure.
+     */
+    async function withProbeCleanup(context, work) {
+        const disposeOnAbort = () => {
+            // The abort event has no caller awaiting this cleanup promise.
+            void dispose().catch(() => { });
+        };
+        if (context.signal?.aborted) {
+            throw new HarnessSdkError('RPC_ABORTED');
+        }
+        context.signal?.addEventListener('abort', disposeOnAbort, { once: true });
+        try {
+            return await work();
+        }
+        catch (cause) {
+            await dispose();
+            throw cause;
+        }
+        finally {
+            context.signal?.removeEventListener('abort', disposeOnAbort);
+        }
+    }
+    /** Release the current input and query for prepare's startup rollback or either disposal pass.
+     * Clear shared query state before calling native cleanup so overlapping calls cannot close the
+     * same query twice. End input before closing, then await native return when supplied. Native
+     * cleanup failures reject the caller's cleanup path.
+     */
+    async function closeConnection() {
+        const current = stream;
+        stream = undefined;
+        pendingHandshakeModels = undefined;
+        input?.end();
+        input = undefined;
+        current?.close();
+        await current?.return?.();
+    }
+}

package/src/file-changes.d.ts

@@ -0,0 +1,22 @@
+import type { FileChange, Item } from '@anureo/protocol';
+/**
+ * Project native Edit, MultiEdit and Write payloads into file evidence using only the supplied data.
+ * Return undefined for other tools, an empty array when neither payload supplies a string path,
+ * or one change. Prefer result.filePath over input.file_path and fall back to input evidence
+ * when the result supplies no usable material.
+ * ClaudeBackendSession.blockItem attaches input evidence to live and history items.
+ * completeClaudeTool projects evidence again when a matching native result arrives.
+ */
+export declare function claudeFileChanges(name: string, input: unknown, result?: unknown): FileChange[] | undefined;
+/**
+ * Return a new tool item from an earlier call and its matching native result. The caller supplies
+ * JSON-normalized and privacy-projected content. The item exposes content as output and uses
+ * structuredContent for file evidence when it is non-nullish, otherwise using content.
+ * Declined and interrupted statuses survive later results. Other calls fail on truthy is_error
+ * and complete otherwise.
+ * ClaudeBackendSession.mapMessage stores and emits the item as item/completed, and projectHistory
+ * replaces the earlier call's item in the history snapshot.
+ */
+export declare function completeClaudeTool(previous: Extract<Item, {
+    type: 'toolCall';
+}>, block: Record<string, unknown>): Item;

package/src/file-changes.js

@@ -0,0 +1,124 @@
+/**
+ * Project native Edit, MultiEdit and Write payloads into file evidence using only the supplied data.
+ * Return undefined for other tools, an empty array when neither payload supplies a string path,
+ * or one change. Prefer result.filePath over input.file_path and fall back to input evidence
+ * when the result supplies no usable material.
+ * ClaudeBackendSession.blockItem attaches input evidence to live and history items.
+ * completeClaudeTool projects evidence again when a matching native result arrives.
+ */
+export function claudeFileChanges(name, input, result) {
+    if (!['Edit', 'MultiEdit', 'Write'].includes(name))
+        return undefined;
+    const data = record(input);
+    const output = record(result);
+    const path = typeof output.filePath === 'string'
+        ? output.filePath
+        : typeof data.file_path === 'string' ? data.file_path : undefined;
+    if (path === undefined)
+        return [];
+    return [resultFileChange(path, name, output) ?? inputFileChange(path, name, data)];
+}
+/**
+ * Return a new tool item from an earlier call and its matching native result. The caller supplies
+ * JSON-normalized and privacy-projected content. The item exposes content as output and uses
+ * structuredContent for file evidence when it is non-nullish, otherwise using content.
+ * Declined and interrupted statuses survive later results. Other calls fail on truthy is_error
+ * and complete otherwise.
+ * ClaudeBackendSession.mapMessage stores and emits the item as item/completed, and projectHistory
+ * replaces the earlier call's item in the history snapshot.
+ */
+export function completeClaudeTool(previous, block) {
+    const name = previous.nativeType ?? previous.title;
+    const fileChanges = claudeFileChanges(name, previous.input, block.structuredContent ?? block.content);
+    let status = previous.status;
+    if (status !== 'declined' && status !== 'interrupted') {
+        status = block.is_error ? 'failed' : 'completed';
+    }
+    return {
+        ...previous,
+        status,
+        output: block.content,
+        ...(fileChanges !== undefined ? { fileChanges } : {}),
+    };
+}
+function record(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+/** Try raw patch, whole-file text, structured hunks and Write output in that order before falling back to input. */
+function resultFileChange(path, name, output) {
+    if (typeof output.patch === 'string') {
+        return { path, operation: 'modify', materials: [{ format: 'unified', patch: output.patch }], completeness: 'complete' };
+    }
+    if ((output.oldText === null || typeof output.oldText === 'string') && typeof output.newText === 'string') {
+        return {
+            path,
+            operation: output.oldText === null ? 'add' : 'modify',
+            materials: [{ format: 'text', scope: 'file', oldText: output.oldText, newText: output.newText }],
+            completeness: 'complete',
+        };
+    }
+    const patch = structuredPatch(output.structuredPatch);
+    if (patch !== undefined) {
+        return { path, operation: output.type === 'create' ? 'add' : 'modify', materials: [{ format: 'unified', patch }], completeness: 'complete' };
+    }
+    if (name !== 'Write' || typeof output.content !== 'string')
+        return undefined;
+    // An update can omit the original text. Null is evidence of an absent file only for create.
+    const originalFile = output.originalFile;
+    const created = output.type === 'create';
+    if (typeof originalFile !== 'string' && !(created && originalFile === null))
+        return undefined;
+    return {
+        path,
+        operation: created ? 'add' : 'modify',
+        materials: [{ format: 'text', scope: 'file', oldText: originalFile, newText: output.content }],
+        completeness: 'complete',
+    };
+}
+/**
+ * Preserve Edit and MultiEdit input fragments in request order. Only a single Edit with both
+ * fragments and no replace_all flag set to true is complete evidence. Write input alone leaves
+ * the operation and material unknown because it does not establish the prior state of the file.
+ */
+function inputFileChange(path, name, data) {
+    if (name === 'Write') {
+        return { path, operation: 'unknown', materials: [{ format: 'unavailable', reason: 'notProvided' }], completeness: 'partial' };
+    }
+    const edits = name === 'MultiEdit' && Array.isArray(data.edits) ? data.edits : [data];
+    const materials = edits.flatMap(value => {
+        const edit = record(value);
+        if (typeof edit.old_string !== 'string' || typeof edit.new_string !== 'string')
+            return [];
+        return [{ format: 'text', scope: 'fragment', oldText: edit.old_string, newText: edit.new_string }];
+    });
+    // A result that only reports success cannot prove replacement count or independent edits.
+    const partial = name === 'MultiEdit'
+        || edits.some(value => record(value).replace_all === true)
+        || materials.length !== edits.length;
+    return {
+        path,
+        operation: 'modify',
+        materials: materials.length ? materials : [{ format: 'unavailable', reason: 'notProvided' }],
+        completeness: partial || !materials.length ? 'partial' : 'complete',
+    };
+}
+/** Render a nonempty pinned-SDK hunk array in native order after checking its hunk shapes. */
+function structuredPatch(value) {
+    if (!Array.isArray(value) || !value.length)
+        return undefined;
+    const hunks = value.map(record);
+    if (!hunks.every(isStructuredPatchHunk))
+        return undefined;
+    return hunks.map(hunk => `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@\n${hunk.lines.join('\n')}\n`).join('');
+}
+/** Accept diff markers, including the backslash marker for a missing final newline. */
+function isPatchLine(line) {
+    return typeof line === 'string' && /^[ +\\-]/.test(line);
+}
+/** Require nonnegative integer range fields and diff markers before using native positions. */
+function isStructuredPatchHunk(hunk) {
+    const hasValidRange = ['oldStart', 'oldLines', 'newStart', 'newLines'].every(key => Number.isInteger(hunk[key]) && hunk[key] >= 0);
+    return hasValidRange && Array.isArray(hunk.lines) && hunk.lines.every(isPatchLine);
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export { ClaudeNativeAdapter, ClaudeBackendSession, createClaudeAdapter } from "./adapter.js";
+export type { ClaudeAdapterOptions, ClaudeQuery, ClaudeQueryFactory } from "./options.js";
+export { FileSessionStore } from "./store.js";
+export { createClaudeCatalogSession } from "./catalog.js";

package/src/index.js

@@ -0,0 +1,4 @@
+// Public application and extension exports; runtime implementations live in their owning modules.
+export { ClaudeNativeAdapter, ClaudeBackendSession, createClaudeAdapter } from "./adapter.js";
+export { FileSessionStore } from "./store.js";
+export { createClaudeCatalogSession } from "./catalog.js";

package/src/options.d.ts

@@ -0,0 +1,47 @@
+import type { query, getSessionMessages, getSessionInfo, forkSession, Query, SDKMessage, SessionStore } from "@anthropic-ai/claude-agent-sdk";
+/** Implement message iteration, session controls and discovery for an injected Claude backend.
+ * End message iteration when the query closes. Session and catalog cleanup also await a native
+ * return() method when present. One-shot ClaudeNativeAdapter.listModels calls close alone. */
+export type ClaudeQuery = AsyncIterable<SDKMessage> & Pick<Query, "interrupt" | "setModel" | "setPermissionMode" | "setMaxThinkingTokens" | "applyFlagSettings" | "rewindFiles" | "supportedModels" | "close">;
+/** Supply a native-compatible query for adapter sessions or prompt-less catalog discovery.
+ * This factory runs synchronously for each query, including replacements. The operation that
+ * invokes the factory owns its query and propagates startup failures according to its contract. */
+export type ClaudeQueryFactory = (params: Parameters<typeof query>[0]) => ClaudeQuery;
+/** Configure Claude launch, state storage and host-supplied query or transcript operations.
+ * Initialization accepts an explicit Claude home, defaultHome or a custom query factory.
+ * Native launch begins with discovery or a session open. Dispose the SDK client or catalog
+ * after use and manage the lifecycle of any injected store separately. */
+export interface ClaudeAdapterOptions {
+    /** Native executable path; takes precedence over the executable alias. */
+    command?: string;
+    /** Alias for command when command is omitted; omission of both uses the native SDK executable. */
+    executable?: string;
+    /** Extra child arguments appended after the native SDK arguments. */
+    args?: string[];
+    /** Explicit launch environment layered over the adapter's platform-essential variables. */
+    env?: Record<string, string | undefined>;
+    /** Adapter state directory, defaulting to env.CLAUDE_CONFIG_DIR; also selects native home unless defaultHome. */
+    stateDir?: string;
+    /** Suppress the stateDir native-home override while retaining adapter storage. Explicit
+     * env.CLAUDE_CONFIG_DIR still applies; otherwise the CLI uses its default home and login. */
+    defaultHome?: boolean;
+    /** Replace native query creation for host integrations or scripted tests; adapter/catalog cleanup owns each returned query. */
+    queryFactory?: ClaudeQueryFactory;
+    /** Inject an opaque native store instead of the state-directory store; the host retains its lifecycle. */
+    sessionStore?: SessionStore;
+    /** Replace native transcript reads during fork setup, history snapshot creation and stored
+     * revert-boundary lookup. Receives the session cwd and a wrapper around the selected store.
+     * Read failures reject the operation that requested the transcript. */
+    getSessionMessages?: typeof getSessionMessages;
+    /** Replace title reads for resumed queries, committed main-session appends and terminal results.
+     * Use the supplied session ID, cwd and optional store. Read failures trigger a best-effort warning. */
+    getSessionInfo?: typeof getSessionInfo;
+    /** Replace native transcript copying for fork and conversation revert when a cutoff entry exists.
+     * Return the destination sessionId. Rejections fail the operation. A revert that already rewound
+     * files reports REVERT_PARTIAL with the applied file scope. */
+    forkSession?: typeof forkSession;
+    /** Enable native file checkpoints/revert; defaults to false. History/conversation support also requires a store. */
+    enableFileCheckpointing?: boolean;
+    /** Script-based external executables can specify the interpreter; native binaries need none. */
+    executableRuntime?: "node" | "bun" | "deno";
+}

package/src/output-schema.d.ts

@@ -0,0 +1,17 @@
+import { type ValidateFunction } from 'ajv';
+import type { JsonObject, JsonSchema } from '@anureo/protocol';
+/** Internal pair retained by ClaudeBackendSession for the active query format. */
+export interface OutputSchema {
+    /** Detached schema used for format comparison and native query setup. Treat it as read-only. */
+    schema: JsonObject;
+    /** Synchronous draft-07 validator used to decide whether terminal output can be published as JSON. */
+    validate: ValidateFunction;
+}
+/**
+ * Compile a detached, self-contained draft-07 schema with an explicit object root. The validator
+ * skips format assertions. Invalid, asynchronous or uncloneable schemas throw INVALID_PARAMS
+ * synchronously with a message that omits schema contents.
+ * ClaudeBackendSession.submitInput compiles a changed schema before replacing the query or
+ * dispatching input. completeTurn uses the retained validator before publishing final JSON text.
+ */
+export declare function compileOutputSchema(schema: JsonSchema): OutputSchema;

package/src/output-schema.js

@@ -0,0 +1,23 @@
+import Ajv from 'ajv';
+import { HarnessSdkError } from '@anureo/sdk';
+/**
+ * Compile a detached, self-contained draft-07 schema with an explicit object root. The validator
+ * skips format assertions. Invalid, asynchronous or uncloneable schemas throw INVALID_PARAMS
+ * synchronously with a message that omits schema contents.
+ * ClaudeBackendSession.submitInput compiles a changed schema before replacing the query or
+ * dispatching input. completeTurn uses the retained validator before publishing final JSON text.
+ */
+export function compileOutputSchema(schema) {
+    if (!schema || typeof schema !== 'object' || schema.type !== 'object' || schema.$async) {
+        throw new HarnessSdkError('INVALID_PARAMS', 'Claude outputSchema must declare an object root and cannot be asynchronous');
+    }
+    try {
+        const copy = structuredClone(schema);
+        const ajv = new Ajv({ allErrors: true, validateFormats: false, multipleOfPrecision: 6, logger: false });
+        return { schema: copy, validate: ajv.compile(copy) };
+    }
+    catch {
+        // Schema descriptions, enum values and reference URLs may contain private data.
+        throw new HarnessSdkError('INVALID_PARAMS', 'Claude outputSchema must be a valid, self-contained draft-07 JSON Schema');
+    }
+}

package/src/store.d.ts

@@ -0,0 +1,71 @@
+import type { SessionKey, SessionStore, SessionStoreEntry } from "@anthropic-ai/claude-agent-sdk";
+/** Persist JSON-safe, opaque Claude transcript entries in a host-owned directory.
+ * Supply this as sessionStore to ClaudeNativeAdapter. With a configured state directory and no
+ * supplied store, the adapter creates one in its ahp-session-store subdirectory and also uses it
+ * to persist turn IDs for boundary lookup. The native SDK invokes the SessionStore methods for
+ * mirroring, resume and history. Transcript keys include the project, session and optional
+ * subpath. The host owns retention and coordinates deletion with writers. Construction opens no
+ * resources and requires no disposal. */
+export declare class FileSessionStore implements SessionStore {
+    readonly directory: string;
+    /** Use directory for transcripts and turn maps. Writes create missing directories with mode 0700. */
+    constructor(directory: string);
+    /** Commit a batch of JSON-safe entries under the lock for this transcript key.
+     * A truthy UUID replaces its existing entry in place. New UUIDs and entries without a truthy
+     * UUID append in batch order. Resolve after file sync, atomic rename and lock cleanup.
+     * An unreclaimable lock that is still contended at the 10-second retry deadline rejects with
+     * SESSION_STORE_BUSY. Transcript read, write and cleanup failures also reject, including
+     * cleanup after publication. ClaudeBackendSession.observedStore awaits successful
+     * main-transcript appends before scheduling a title refresh for the active query. Rejections
+     * return to the native SDK. */
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    /** Load a detached full transcript, or null when the requested file is absent.
+     * An envelope without a truthy key or an entries array rejects with SESSION_STORE_INVALID.
+     * Other filesystem and JSON parse failures propagate. ClaudeBackendSession.boundaryPoint and
+     * structuredHistory also read these entries to include opaque records omitted by native history
+     * in fork/revert cutoffs and structured output in history pages, respectively. */
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    /** List transcripts with no truthy subpath for a project in filesystem order.
+     * The stored mtime is in Unix epoch milliseconds and advances on every committed append.
+     * A missing directory yields an empty list. Read and envelope errors anywhere in the
+     * transcript scan reject the listing. */
+    listSessions(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    /** List nonempty transcript subpaths for a project and session in filesystem order.
+     * A missing directory yields an empty list. Scan failures propagate as in listSessions. */
+    listSubkeys(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+    /** Remove the transcript for this exact key, accepting an absent file.
+     * Other subpaths and turn maps remain. The caller must coordinate this unlocked deletion with
+     * writers. Other removal failures reject. */
+    delete(key: SessionKey): Promise<void>;
+    /** Load adapter boundary metadata mapping native input UUIDs to AHP turn IDs by native session ID.
+     * Return the parsed JSON as stored, or an empty map when the file is absent. Other read and
+     * parse failures reject.
+     * ClaudeBackendSession.open restores the map for the active session or reads it from the fork
+     * source. ClaudeBackendSession.boundaryPoint uses the map to resolve AHP turn IDs to candidates
+     * that it verifies in native history. */
+    loadTurnMap(sessionId: string): Promise<Record<string, string>>;
+    /** Replace the adapter's turn map for a native session ID.
+     * Resolve after file sync, atomic rename and temporary-file cleanup. Callers must order
+     * concurrent replacements if publication order matters. Cleanup can reject after publication.
+     * ClaudeBackendSession.open and restoreConversation await the save before starting a query.
+     * Saves during input association or a native ID change can fail the query pump. */
+    saveTurnMap(sessionId: string, turns: Record<string, string>): Promise<void>;
+    /** Keep each transcript at its stable hashed path. Omitted subpaths use the null slot in the
+     * tuple, preserving the on-disk key format and keeping an explicit empty string distinct. */
+    private transcriptPath;
+    /** Read a transcript envelope for load, append or a scan. Return null on absence and reject
+     * malformed JSON or a missing key/entries array so append cannot overwrite those records. */
+    private readTranscript;
+    /** Scan the hashed transcript filenames for both listing methods. Preserve directory order and
+     * skip files removed before they can be read. Directory absence also yields an empty result.
+     * Other read or envelope errors reject before the caller filters by project or session. */
+    private scanTranscripts;
+    /** Keep boundary metadata at its stable session-ID path, outside the transcript filename pattern. */
+    private turnMapPath;
+}