@gajae-code/coding-agent 0.12.19 → 0.12.20

package/dist/types/session/internal/session-memory-sidecar.d.ts

@@ -0,0 +1,881 @@
+/**
+ * Standalone sidecar primitives for bounded-memory cold-session offloading.
+ *
+ * This module is intentionally self-contained: it imports only Node built-ins and
+ * defines the reusable P2/P3/P4 primitives agreed in the approved memory spec —
+ * the retained-byte accountant, reducer disk-ref demotion guardrails, the
+ * `isDerivedSessionMemoryFile` lifecycle predicate, the disposable sidecar v2
+ * index schemas, the unsorted append-only bounded dictionary builder with
+ * duplicate-ID sidecar-ineligibility detection, fixed-size cache accounting,
+ * the anchored base digest + rolling tail checksum chain with commit validation
+ * and the five-class reopen classifier, the `latestModelChange` / TTSR
+ * latest-wins reducer semantics, and bounded parent→children / labels/pins
+ * descriptors.
+ *
+ * Transcript v5 remains authoritative and every sidecar index is disposable /
+ * rebuildable. No builder here requires the whole transcript resident in
+ * memory; all builders consume records one at a time and enforce their peak
+ * budgets as they go.
+ */
+/** Provider-context materialization acceptance peak (AC1). */
+export declare const SESSION_MEMORY_ACCEPTANCE_BUDGET_BYTES: number;
+/** Steady-state retained-byte budget: 61.0625 MiB leaves the 64 MiB margin. */
+export declare const SESSION_MEMORY_STEADY_STATE_BUDGET_BYTES: number;
+/** Fixed 24 B resident disk-ref descriptor (ADR / A.1). */
+export declare const DESCRIPTOR_BYTES = 24;
+/** Conservative per-record object overhead (A.1). */
+export declare const RECORD_OBJECT_OVERHEAD_BYTES = 48;
+/** labels+pins steady-state budget (0.0625 MiB). */
+export declare const LABELS_PINS_BUDGET_BYTES: number;
+/** Reducer resident budget (4 MiB) — enforced by disk-ref demotion. */
+export declare const REDUCER_BUDGET_BYTES: number;
+/** Guardrail: values over this are demoted to disk-ref descriptors. */
+export declare const MAX_REDUCER_INLINE_BYTES: number;
+/** Guardrail: max resident string length. */
+export declare const MAX_REDUCER_STRING_BYTES: number;
+/** Guardrail: max distinct roles. */
+export declare const MAX_ROLES = 64;
+/** Guardrail: max chain entries per role. */
+export declare const MAX_CHAIN_ENTRIES = 32;
+/** Guardrail: max TTSR rules. */
+export declare const MAX_TTSR_RULES = 256;
+/** Guardrail: max MCP names. */
+export declare const MAX_MCP_NAMES = 4096;
+/** Guardrail: max chars per MCP name. */
+export declare const MAX_MCP_NAME_CHARS = 256;
+/** Guardrail: modeData ≤ 64 KiB. */
+export declare const MODE_DATA_MAX_BYTES: number;
+/** Guardrail: compaction summary ≤ 64 KiB. */
+export declare const COMPACTION_SUMMARY_MAX_BYTES: number;
+/** preserveData.openaiRemoteCompaction ≤ 8 MiB (always a disk ref). */
+export declare const OPENAI_REMOTE_COMPACTION_MAX_BYTES: number;
+/** Fixed-size index block cache (steady-state). */
+export declare const BLOCK_CACHE_BUDGET_BYTES: number;
+/** Fixed-size resolved-entry cache (steady-state). */
+export declare const ENTRY_CACHE_BUDGET_BYTES: number;
+/** Tail journal buffer/index (steady-state). */
+export declare const TAIL_BUFFER_BUDGET_BYTES: number;
+/** Bounded forward-scan window for transcript-ahead recovery (R2.4). */
+export declare const INDEX_TAIL_SCAN_MAX_BYTES: number;
+/** Maximum ordinal-index records retained transiently for one cold branch activation. */
+export declare const COLD_BRANCH_PREFETCH_MAX_INDEX_ENTRIES: number;
+/**
+ * Decide the cold-branch ordinal-run fast path before allocating its Map or
+ * transcript window. Large sparse/interleaved intervals fail closed to bounded
+ * dictionary/index fallback; the transcript remains authoritative.
+ */
+export declare function coldBranchOrdinalRunWithinPrefetchBounds(input: {
+    boundaryOrdinal: number;
+    leafOrdinal: number;
+    transcriptStart: number;
+    transcriptEnd: number;
+    maxTranscriptBytes: number;
+}): boolean;
+/** Dictionary build acceptance cap; default buffers stay well below this 20 MiB maximum. */
+export declare const DICTIONARY_BUILD_PEAK_BYTES: number;
+/** One dictionary partition buffer. */
+export declare const DICTIONARY_PARTITION_BUFFER_BYTES: number;
+/** Dictionary bucket journal flush buffer. */
+export declare const DICTIONARY_BUCKET_JOURNAL_BYTES: number;
+/** Bounded parent→children index bounds. */
+export declare const PARENT_CHILDREN_MAX_PARENTS = 4096;
+export declare const PARENT_CHILDREN_MAX_CHILDREN_PER_PARENT = 256;
+export declare const PARENT_CHILDREN_BUDGET_BYTES: number;
+/** Deterministic hash-bucket count for the disposable on-disk parent artifact. */
+export declare const PARENT_CHILDREN_BUCKET_COUNT = 64;
+/** Resident string = `2 × charCount + 16 B`. */
+export declare function residentStringBytes(value: string): number;
+/** Resident array = `8 B/slot + Σ elements`. */
+export declare function residentArrayBytes(slotCount: number, elementBytes: number): number;
+/** Per-record object with `childBytes` of payload = 48 B overhead + payload. */
+export declare function residentRecordBytes(childBytes: number): number;
+/**
+ * Authoritative measured retained-byte counter. Enforcement acts on the total,
+ * never on field counts alone. `tryCharge`/`wouldExceed` let callers enforce a
+ * budget without mutating state (used by the provider-context preflight which
+ * must never retain an over-budget graph).
+ */
+export declare class SessionMemoryAccountant {
+    private total;
+    private readonly budget;
+    constructor(budgetBytes?: number);
+    get totalBytes(): number;
+    get budgetBytes(): number;
+    get remainingBytes(): number;
+    /** Adds `bytes` to the running total and returns the new total. */
+    charge(bytes: number): number;
+    /** Charges one resident string via the `2 × charCount + 16` formula. */
+    chargeString(value: string): number;
+    /** Charges one resident array via the `8 B/slot + Σ elements` formula. */
+    chargeArray(slotCount: number, elementBytes: number): number;
+    /** Charges one fixed 24 B disk-ref descriptor. */
+    chargeDescriptor(): number;
+    /** Charges one per-record object (48 B overhead + payload). */
+    chargeRecord(childBytes: number): number;
+    /**
+     * Adds `bytes` only if the running total stays within the budget.
+     * Returns `false` (and does not mutate) when the addition would exceed it.
+     */
+    tryCharge(bytes: number): boolean;
+    /** Returns `true` when charging `bytes` would exceed the budget. */
+    wouldExceed(bytes: number): boolean;
+    isWithinBudget(): boolean;
+    release(bytes: number): void;
+    snapshot(): {
+        totalBytes: number;
+        budgetBytes: number;
+        remainingBytes: number;
+    };
+    private assertBytes;
+}
+/**
+ * A 24 B resident descriptor that points at a value stored in the sidecar
+ * metadata-delta section. Demoted values are never resident as full strings.
+ */
+export interface ReducerDemotionDescriptor {
+    section: "metadata-delta";
+    key: string;
+    offset: number;
+    length: number;
+    sha256: string;
+}
+export interface ReducerValueSnapshot {
+    key: string;
+    kind: "inline" | "disk_ref";
+    residentBytes: number;
+    storedBytes: number;
+}
+export type ReducerBudgetResult = {
+    kind: "ok";
+    totalBytes: number;
+} | {
+    kind: "over_budget_irreducible";
+    totalBytes: number;
+};
+/**
+ * Tracks the reducer's resident bytes against the 4 MiB budget. Values over
+ * `MAX_REDUCER_INLINE_BYTES` are immediately stored as 24 B disk-ref
+ * descriptors. When the total would exceed the budget, the largest resident
+ * inline value is demoted, repeating until the total fits or only
+ * descriptors/scalars remain (impossible by arithmetic — checked anyway).
+ */
+export declare class ReducerBudget {
+    private readonly values;
+    private total;
+    private nextOffset;
+    private readonly budgetBytesValue;
+    private readonly maxInlineBytes;
+    constructor(budgetBytes?: number, maxInlineBytes?: number);
+    get totalBytes(): number;
+    get budgetBytes(): number;
+    get(key: string): ReducerValueSnapshot | undefined;
+    /** Returns the resident 24 B descriptor for a demoted key, if any. */
+    getDescriptor(key: string): ReducerDemotionDescriptor | undefined;
+    /**
+     * Records a reducer value of `storedBytes` bytes (optionally with its content
+     * digest) and enforces the budget by demoting the largest resident inline
+     * value until the total fits.
+     */
+    setInline(key: string, storedBytes: number, sha256?: string): ReducerBudgetResult;
+    /** Demotes every currently resident inline value to a disk-ref descriptor. */
+    demoteAll(): void;
+    private enforceBudget;
+    private largestDemotableInline;
+    private demote;
+}
+/**
+ * Single source of truth for every sidecar artifact and temp: `*.spill.idx`,
+ * `*.spill.tail`, `*.spill.commit`, `*.spill.buckets`, `*.spill.dict-*`,
+ * `*.spill.capture-*`, `*.spill.fork-*`, `*.spill.overlay-*`,
+ * `*.spill.parent-*` (persistent parent→children buckets),
+ * `*.spill.metadata-*` (persistent metadata-delta section), and any
+ * `*.spill.*.tmp`. Used at every fork/delete/sweep/Memory-parity callsite so
+ * ad-hoc filters cannot drift.
+ */
+export declare function isDerivedSessionMemoryFile(pathname: string): boolean;
+/** Common header for every sidecar v2 index file. */
+export interface SidecarIndexHeaderV2 {
+    version: 2;
+    sessionId: string;
+    /** Set when duplicate record IDs were detected; session is eager-ineligible. */
+    sidecarIneligible: boolean;
+}
+/** Unsorted append-only variable-width dictionary (term → id). */
+export interface SidecarDictionaryV2 {
+    header: SidecarIndexHeaderV2;
+    /** Insertion-ordered unique terms (append-only; deterministic). */
+    terms: readonly string[];
+    /** term → dictionary id, assigned by first-insertion order. */
+    idByTerm: ReadonlyMap<string, number>;
+    /** Combined serialized term bytes. */
+    totalBytes: number;
+}
+/** Rolling tail checksum index (anchored base + terminal chain). */
+export interface SidecarTailIndexV2 {
+    header: SidecarIndexHeaderV2;
+    base: BaseAnchor;
+    records: readonly TailRecord[];
+    terminalChecksum: string;
+    terminalSeq: number;
+    transcriptSize: number;
+}
+/** Metadata-delta section: demoted reducer values + deltas. */
+export interface SidecarMetadataIndexV2 {
+    header: SidecarIndexHeaderV2;
+    /** key → { offset, length, sha256 } for demoted values. */
+    entries: Record<string, {
+        offset: number;
+        length: number;
+        sha256: string;
+    }>;
+}
+/** Bounded parent→children index. */
+export interface SidecarParentIndexV2 {
+    header: SidecarIndexHeaderV2;
+    entries: readonly ParentChildrenIndexEntry[];
+}
+/** Bounded labels/pins descriptor. */
+export interface SidecarLabelsPinsIndexV2 {
+    header: SidecarIndexHeaderV2;
+    labels: ReadonlyMap<string, string>;
+    pins: ReadonlyMap<string, string>;
+    totalBytes: number;
+}
+export interface DictionaryRecordInput {
+    ordinal: number;
+    id: string;
+    bytes: Uint8Array;
+}
+export interface DictionaryBuildOptions {
+    peakBudgetBytes?: number;
+    partitionBufferBytes?: number;
+    bucketJournalBytes?: number;
+}
+export type DictionaryAddResult = {
+    kind: "ok";
+} | {
+    kind: "budget_exceeded";
+    peakBytes: number;
+    budgetBytes: number;
+};
+export type DictionaryBuildResult = {
+    kind: "ok";
+    dictionary: SidecarDictionaryV2;
+    stats: DictionaryBuildStats;
+} | {
+    kind: "budget_exceeded";
+    peakBytes: number;
+    budgetBytes: number;
+};
+export interface DictionaryBuildStats {
+    totalRecords: number;
+    uniqueTerms: number;
+    totalBytes: number;
+    peakBytes: number;
+    duplicateIds: readonly string[];
+    sidecarIneligible: boolean;
+}
+/**
+ * Unsorted append-only variable-width dictionary builder. Consumes records one
+ * at a time (no whole transcript resident) and tracks the 20 MiB build peak as
+ * `Σ term bytes + 4 × partition buffer + bucket journal`. Duplicate record IDs
+ * mark the session sidecar-ineligible (eager fallback) while the build still
+ * completes deterministically.
+ */
+export declare class BoundedDictionaryBuilder {
+    private readonly terms;
+    private readonly idByTerm;
+    private readonly seenRecordIds;
+    private readonly duplicateIds;
+    private totalTermBytes;
+    private recordIdBytes;
+    private duplicateIdBytes;
+    private peakBytes;
+    private sidecarIneligible;
+    private recordCount;
+    private finished;
+    private readonly peakBudget;
+    private readonly partitionBase;
+    constructor(options?: DictionaryBuildOptions);
+    add(record: DictionaryRecordInput): DictionaryAddResult;
+    finish(): DictionaryBuildResult;
+    private updatePeak;
+}
+/**
+ * Tracks a fixed-size cache budget (8 MiB block, 28 MiB entry, 4 MiB tail).
+ * `tryAllocate` rejects allocations that would exceed the budget without
+ * mutating state.
+ */
+export declare class FixedCacheAccount {
+    private allocated;
+    private readonly budget;
+    constructor(budgetBytes: number);
+    get allocatedBytes(): number;
+    get budgetBytes(): number;
+    get remainingBytes(): number;
+    tryAllocate(bytes: number): boolean;
+    release(bytes: number): void;
+}
+/** Anchors the base range `[0, baseEndOffset)` with a content digest. */
+export interface BaseAnchor {
+    baseDigest: string;
+    baseEndOffset: number;
+}
+export type TailRecordKind = "user" | "assistant" | "tool" | "model_change" | "ttsr_injection" | "internal" | "other";
+/** One committed rolling tail record. */
+export interface TailRecord {
+    gen: number;
+    seq: number;
+    kind: TailRecordKind;
+    ordinal: number;
+    id: string;
+    parentId: string | null;
+    type: string;
+    byteOffset: number;
+    byteLength: number;
+    recordDigest: string;
+    checksum: string;
+}
+/** Input for appending to a rolling tail chain (checksum is computed). */
+export interface TailRecordInput {
+    gen?: number;
+    seq: number;
+    kind: TailRecordKind;
+    ordinal: number;
+    id: string;
+    parentId: string | null;
+    type: string;
+    byteOffset: number;
+    byteLength: number;
+    recordDigest: string;
+}
+/** Effective base+tail identity (no per-append whole-file hash). */
+export interface CommittedTail {
+    base: BaseAnchor;
+    records: readonly TailRecord[];
+    terminalChecksum: string;
+    terminalSeq: number;
+    transcriptSize: number;
+}
+/** SHA-256 of one record line's bytes. */
+export declare function computeLineDigest(bytes: Uint8Array): string;
+/**
+ * Canonical length-prefixed chain hash. Each part is hashed as its UTF-8 /
+ * raw bytes prefixed by a 4-byte big-endian length, so concatenations are
+ * unambiguous.
+ */
+export declare function hashChain(parts: ReadonlyArray<bigint | number | string | Uint8Array>): string;
+/** First tail checksum: `C0 = H(baseDigest ‖ baseEndOffset ‖ seq0 ‖ lineDigest0)`. */
+export declare function computeC0(base: BaseAnchor, seq0: number, lineDigest0: string): string;
+/** Checksum one complete tail record, including every field used for ordering or lookup. */
+export declare function computeTailRecordChecksum(base: BaseAnchor, previousChecksum: string | undefined, record: TailRecordInput & {
+    gen?: number;
+}): string;
+/** Resident bytes for every retained tail string plus the record object. */
+export declare function tailRecordResidentBytes(record: TailRecordInput, checksumChars?: number): number;
+/** Terminal checksum for a committed tail (empty chain → base only). */
+export declare function computeTerminalChecksum(base: BaseAnchor, records: readonly TailRecord[]): string;
+export interface TailValidationResult {
+    valid: boolean;
+    firstInvalidSeq?: number;
+    reason?: string;
+}
+/**
+ * Validates a committed tail chain: contiguous seq from 0, contiguous absolute
+ * offsets from `baseEndOffset`, and checksum continuity
+ * `checksum_i = H(checksum_{i-1} ‖ seq_i ‖ offset_i ‖ length_i ‖ lineDigest_i)`.
+ */
+export declare function validateTailChain(base: BaseAnchor, records: readonly TailRecord[]): TailValidationResult;
+/**
+ * Streams tail records, computing the rolling checksum chain incrementally and
+ * enforcing the 4 MiB tail buffer budget. Never buffers the whole transcript.
+ */
+export declare class RollingTailChainBuilder {
+    private readonly records;
+    private readonly base;
+    private lastChecksum;
+    private lastSeq;
+    private lastEndOffset;
+    private remainingTailBytes;
+    constructor(base: BaseAnchor, options?: {
+        tailBufferBytes?: number;
+    });
+    get recordCount(): number;
+    /** Appends one tail record; returns `undefined` when the buffer budget is hit. */
+    append(input: TailRecordInput): TailRecord | undefined;
+    build(): CommittedTail;
+}
+/** Descriptor snapshot captured post-fsync from the authoritative open handle. */
+export interface DescriptorSnapshot {
+    dev: bigint;
+    ino: bigint;
+    nlink?: bigint;
+    size: number;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+}
+/** Exact enum-order descriptor comparison (dev/ino/nlink/size/mtimeNs/ctimeNs). */
+export declare function sameDescriptor(left: DescriptorSnapshot, right: DescriptorSnapshot): boolean;
+/** Contents of the mutable `.spill.commit` marker (R2). */
+export interface CommitMarkerContents {
+    gen: number;
+    descriptor: DescriptorSnapshot;
+    base: BaseAnchor;
+    terminalChecksum: string;
+    terminalSeq: number;
+    transcriptSize: number;
+}
+export type CommitInvalidReason = "missing_fields" | "base_invalid" | "chain_invalid" | "terminal_checksum_mismatch" | "terminal_seq_mismatch" | "transcript_size_mismatch" | "descriptor_mismatch" | "terminal_marker_mismatch";
+export type CommitValidationResult = {
+    kind: "valid";
+} | {
+    kind: "invalid";
+    reason: CommitInvalidReason;
+};
+/**
+ * Validates a commit marker's internal consistency plus its descriptor against
+ * the currently opened transcript. `baseValid`/`tailValid`/`terminalMarkerValid`
+ * are the externally-observed proof results.
+ */
+export declare function validateCommit(commit: Partial<CommitMarkerContents> | CommitMarkerContents, records: readonly TailRecord[], observed: {
+    descriptor: DescriptorSnapshot;
+    baseValid: boolean;
+    tailValid: boolean;
+    terminalMarkerValid: boolean;
+}): CommitValidationResult;
+export type ReopenClassKind = "exact" | "transcript_ahead" | "tail_ahead" | "rebuild" | "stale_commit";
+/** Physical evidence the reopen classifier consumes. */
+export interface ReopenEvidence {
+    markerPresent: boolean;
+    descriptorExact: boolean;
+    sameObject: boolean;
+    sameSize: boolean;
+    sizeGrew: boolean;
+    sizeShrank: boolean;
+    withinScanWindow: boolean;
+    timesAdvanced: boolean;
+    timesChanged: boolean;
+    baseValid: boolean;
+    tailValid: boolean;
+    terminalMarkerValid: boolean;
+}
+export interface ReopenClassification {
+    kind: ReopenClassKind;
+    reason: string;
+}
+/**
+ * Five-class reopen classification (R2.4). Deterministic over the supplied
+ * evidence; a stale commit is never accepted as current on any path.
+ */
+export declare function classifyReopen(evidence: ReopenEvidence): ReopenClassification;
+export interface LatestModelChangeDelta {
+    kind: "latest_model_change";
+    ordinal: number;
+    role?: string;
+}
+export interface TtsrDelta {
+    kind: "ttsr_injection";
+    ordinal: number;
+    rulesCount: number;
+    recordsCount: number;
+    count: number;
+}
+export type ReducerDelta = LatestModelChangeDelta | TtsrDelta;
+export interface ModelChangeReducerState {
+    latest: {
+        ordinal: number;
+        role: string | undefined;
+    } | undefined;
+}
+export interface TtsrReducerState {
+    count: number;
+    rulesCount: number;
+    recordsCount: number;
+    largestOrdinal: number;
+}
+export interface ReducerState {
+    modelChange: ModelChangeReducerState;
+    ttsr: TtsrReducerState;
+}
+export declare function createReducerState(): ReducerState;
+/**
+ * Applies one reducer delta. `latest_model_change` overwrites the nearest
+ * event's `{ordinal, role}`; `ttsr_injection.count` replaces the prior value
+ * (authoritative `buildSessionContext`, latest-wins).
+ */
+export declare function applyReducerDelta(state: ReducerState, delta: ReducerDelta): ReducerState;
+/**
+ * R1 consumer: returns `latestModelChange.role ?? "default"` when a
+ * `model_change` exists on the path, else `undefined`. `hasExplicitDefaultModel`
+ * only gates legacy assistant inference into `models.default`; it never feeds
+ * this getter.
+ */
+export declare function getLastModelChangeRole(state: ReducerState): string | undefined;
+/**
+ * Compaction fold: keeps the max-ordinal `model_change` (nearest wins) and the
+ * latest-ordinal TTSR state, matching the eager leaf→root first-hit semantics.
+ */
+export declare function foldReducerStates(left: ReducerState, right: ReducerState): ReducerState;
+export interface ParentChildrenIndexEntry {
+    parentId: string;
+    children: readonly string[];
+}
+/** Bounded parent→children index (rejects when either bound is exceeded). */
+export declare class BoundedParentChildrenIndex {
+    private readonly childrenByParent;
+    private readonly maxParents;
+    private readonly maxChildrenPerParent;
+    private readonly budgetBytesValue;
+    private total;
+    constructor(options?: {
+        maxParents?: number;
+        maxChildrenPerParent?: number;
+        budgetBytes?: number;
+    });
+    get size(): number;
+    get totalBytes(): number;
+    get budgetBytes(): number;
+    add(parentId: string, childId: string): boolean;
+    get(parentId: string): readonly string[] | undefined;
+    entries(): ParentChildrenIndexEntry[];
+}
+/**
+ * Bounded labels/pins store. Accounting uses `stored bytes + map overhead`
+ * (resident string formulas + per-entry overhead), rejected when the labels+pins
+ * budget would be exceeded.
+ */
+export declare class BoundedLabelsPinsStore {
+    private readonly labels;
+    private readonly pins;
+    private total;
+    private readonly budget;
+    constructor(budgetBytes?: number);
+    get totalBytes(): number;
+    get budgetBytes(): number;
+    setLabel(key: string, value: string): boolean;
+    deleteLabel(key: string): void;
+    setPin(key: string, value: string): boolean;
+    getLabel(key: string): string | undefined;
+    getPin(key: string): string | undefined;
+    labelsEntries(): ReadonlyMap<string, string>;
+    pinsEntries(): ReadonlyMap<string, string>;
+    clear(): void;
+    private setIn;
+}
+/**
+ * One parent→child edge plus the child's authoritative cold index fields. The
+ * artifact is disposable derived proof; the `.spill.idx` remains authoritative
+ * for entry offsets and the transcript remains authoritative for entry bytes.
+ */
+export interface ParentBucketRecordInput {
+    parentId: string;
+    childId: string;
+    ordinal: number;
+    seq: number;
+    byteOffset: number;
+    byteLength: number;
+    recordDigest: string;
+    entryType?: string;
+}
+/** Committed on-disk state of one parent bucket (exact bytes). */
+export interface ParentBucketCommit {
+    size: number;
+    digest: string;
+    complete: boolean;
+}
+/**
+ * Commit-marker binding for the disposable parent artifact. The artifact
+ * covers exactly the entry set of the `.spill.idx` whose digest is bound here;
+ * a binding mismatch fails closed to the authoritative cold scan.
+ */
+export interface ParentArtifactCommit {
+    bucketCount: number;
+    indexDigest: string;
+    buckets: ParentBucketCommit[];
+}
+/**
+ * Deterministic hash-partition assignment for a parent id. Bucket files are
+ * append-only journals; a lookup reads exactly one bucket (bounded range read)
+ * and verifies each record's `parentId` to filter hash collisions.
+ */
+export declare function parentBucketForId(parentId: string, bucketCount?: number): number;
+/** Serialize one parent→child edge as a compact JSON journal line (trailing newline). */
+export declare function serializeParentBucketRecord(input: ParentBucketRecordInput): string;
+/** Strictly parse one parent bucket journal line; `undefined` marks the bucket corrupt. */
+export declare function parseParentBucketRecord(line: string): ParentBucketRecordInput | undefined;
+export interface ParentArtifactBuildResult {
+    metadata: ParentArtifactCommit;
+    /** Per-bucket records in physical (transcript) order. */
+    buckets: string[][];
+    /** Parents excluded because a bound (children/budget/parents) was exceeded. */
+    excludedParents: readonly string[];
+}
+/**
+ * Bounded builder for the persistent parent artifact. Parents are indexed
+ * fully or not at all: a parent whose children would exceed
+ * `PARENT_CHILDREN_MAX_CHILDREN_PER_PARENT`, whose first record would exceed
+ * `PARENT_CHILDREN_BUDGET_BYTES`, or that would exceed
+ * `PARENT_CHILDREN_MAX_PARENTS` is excluded (lookups for it fail closed), and
+ * its buffered records are dropped so a truncated "complete" result can never
+ * be published. Per-parent child order is preserved (insertion order).
+ */
+export declare class BoundedParentArtifactBuilder {
+    private readonly parents;
+    private readonly excluded;
+    private readonly incompleteBuckets;
+    private totalBytesValue;
+    private readonly maxParents;
+    private readonly maxChildrenPerParent;
+    private readonly budgetBytesValue;
+    private readonly bucketCount;
+    private finished;
+    private capacityExhausted;
+    constructor(options?: {
+        maxParents?: number;
+        maxChildrenPerParent?: number;
+        budgetBytes?: number;
+        bucketCount?: number;
+    });
+    get distinctParents(): number;
+    get totalBytes(): number;
+    add(record: ParentBucketRecordInput): void;
+    private exclude;
+    finish(indexDigest: string): ParentArtifactBuildResult;
+}
+/** Fixed in-memory cost of the retained parent-artifact runtime state (block-cache charged). */
+export declare function parentArtifactRuntimeBytes(bucketCount?: number): number;
+/** Fixed partition count for the on-disk dictionary artifact (4 × 4 MiB buffers). */
+export declare const DICTIONARY_PARTITION_COUNT = 4;
+/** Maximum unique duplicate record ids retained as diagnostics in the meta. */
+export declare const DICTIONARY_DUPLICATE_DIAGNOSTIC_MAX = 64;
+/** Fixed capacity of the bounded duplicate-id detector (open addressing). */
+export declare const DICTIONARY_ID_SET_CAPACITY = 1125001;
+/** Maximum records the bounded duplicate-id detector can prove unique. */
+export declare const DICTIONARY_ID_SET_MAX_RECORDS = 1000000;
+/**
+ * One partition journal record. `term` is the lossless record id (never
+ * truncated or hash-substituted); the remaining fields are the same exact
+ * index fields the covered `.spill.idx` records, so a partition is a
+ * self-sufficient hash-partitioned flat index for one id.
+ */
+export interface DictionaryPartitionRecord {
+    term: string;
+    dictId: number;
+    ordinal: number;
+    seq: number;
+    byteOffset: number;
+    byteLength: number;
+    recordDigest: string;
+    parentId: string | null;
+    entryType: string;
+}
+/** Serialize one dictionary partition record as a compact JSON journal line (trailing newline). */
+export declare function serializeDictionaryPartitionRecord(input: DictionaryPartitionRecord): string;
+/** Strictly parse one dictionary partition journal line; `undefined` marks the partition corrupt. */
+export declare function parseDictionaryPartitionRecord(line: string): DictionaryPartitionRecord | undefined;
+/**
+ * Deterministic hash-partition assignment for a record id (same FNV-1a family
+ * as `parentBucketForId`). The same id always lands in the same partition, so
+ * every occurrence of a duplicate id is confined to one journal.
+ */
+export declare function dictionaryPartitionForId(id: string, partitionCount?: number): number;
+/** Committed exact bytes of one on-disk dictionary partition. */
+export interface DictionaryPartitionCommit {
+    size: number;
+    digest: string;
+    records: number;
+    complete: boolean;
+}
+/**
+ * Commit-marker binding for the disposable dictionary artifact. Every partition
+ * and the meta file are bound by exact size + SHA-256, and the artifact covers
+ * exactly the entry set of the `.spill.idx` whose digest is bound here; a
+ * binding mismatch fails closed to the authoritative cold scan.
+ */
+export interface DictionaryArtifactCommit {
+    header: SidecarIndexHeaderV2;
+    /** Exact `.spill.idx` digest the artifact covers. */
+    indexDigest: string;
+    /** Per-partition exact-byte commits, one per partition file. */
+    partitions: DictionaryPartitionCommit[];
+    /** Exact bytes of the `.spill.dict-meta` file (self-referential fields omitted from the payload). */
+    metaSize: number;
+    metaDigest: string;
+    recordCount: number;
+    uniqueTerms: number;
+    /** Combined serialized term bytes (lossless ids). */
+    totalBytes: number;
+    /** Bounded duplicate-id diagnostics; non-empty ⇒ the artifact must never be adopted. */
+    duplicateIds: readonly string[];
+    sidecarIneligible: boolean;
+}
+/**
+ * Exact serialized bytes of the meta file. `metaSize`/`metaDigest` are omitted
+ * from the payload (they authenticate the bytes that omit them), so
+ * serialization is deterministic and self-referentiality is impossible.
+ */
+export declare function dictionaryArtifactMetaBytes(commit: Omit<DictionaryArtifactCommit, "metaSize" | "metaDigest">): string;
+/** Compute the exact meta bytes and the resulting self-authenticating commit. */
+export declare function finalizeDictionaryArtifactCommit(commit: Omit<DictionaryArtifactCommit, "metaSize" | "metaDigest">): {
+    bytes: string;
+    commit: DictionaryArtifactCommit;
+};
+/**
+ * Strictly parse the exact meta bytes. The digest and size are recomputed over
+ * the supplied exact bytes; any structural, bound, or digest mismatch returns
+ * `undefined` (the artifact is then never trusted).
+ */
+export declare function parseDictionaryArtifactCommit(bytes: string | Uint8Array): DictionaryArtifactCommit | undefined;
+/** Bounded duplicate-id oracle for the streaming dictionary build. */
+export interface DictionaryIdDetector {
+    add(id: string): "added" | "duplicate" | "full";
+}
+/**
+ * Bounded duplicate-id oracle. Small transcripts stay in a tiny exact set;
+ * larger transcripts promote once to the fixed-capacity 48-bit hash table.
+ * A hash collision can only produce a spurious duplicate (fail closed), never
+ * miss a true duplicate.
+ */
+export declare class BoundedDictionaryIdSet implements DictionaryIdDetector {
+    #private;
+    has(value: string): boolean;
+    add(value: string): "added" | "duplicate" | "full";
+}
+/** One record consumed by the streaming dictionary artifact builder. */
+export interface DictionaryArtifactRecordInput {
+    id: string;
+    ordinal: number;
+    seq: number;
+    byteOffset: number;
+    byteLength: number;
+    recordDigest: string;
+    parentId: string | null;
+    entryType: string;
+}
+/**
+ * Persistence target for flushed partition lines. The target owns the exact
+ * bytes on disk and their running digests (it must keep per-partition hashes
+ * for append-time rebinding); the builder never retains flushed lines.
+ */
+export interface DictionaryArtifactFlushTarget {
+    /** Append `lines` to `partition`'s journal, fsyncing before returning false on failure. */
+    writePartitionLines(partition: number, lines: readonly string[]): boolean;
+    /** Exact-byte commit of one partition as currently persisted. */
+    getPartitionCommit(partition: number): DictionaryPartitionCommit;
+}
+export type DictionaryArtifactAddResult = {
+    kind: "ok";
+} | {
+    kind: "budget_exceeded";
+    peakBytes: number;
+    budgetBytes: number;
+} | {
+    kind: "flush_failed";
+};
+export type DictionaryArtifactBuildResult = {
+    kind: "ok";
+    commit: DictionaryArtifactCommit;
+    stats: DictionaryBuildStats;
+} | {
+    kind: "budget_exceeded";
+    peakBytes: number;
+    budgetBytes: number;
+} | {
+    kind: "flush_failed";
+};
+export interface DictionaryArtifactBuildOptions {
+    peakBudgetBytes?: number;
+    partitionBufferBytes?: number;
+    journalBytes?: number;
+    partitionCount?: number;
+    detector?: DictionaryIdDetector;
+    /** Persistence target for flushed partition lines; required for `add`/`finish`. */
+    target?: DictionaryArtifactFlushTarget;
+}
+/**
+ * Streaming dictionary artifact builder with a deterministic 20 MiB build peak
+ * (4 × `partitionBufferBytes` partition buffers + one `journalBytes` flush
+ * buffer). Consumes records one at a time, flushes full partition buffers
+ * through the journal to the flush target, and never retains the complete
+ * dictionary object/JSON graph. Record ids are stored losslessly as terms.
+ * Duplicate record ids mark the artifact `sidecarIneligible` (never adopted;
+ * the session falls back to eager) while the build still completes
+ * deterministically.
+ */
+export declare class BoundedDictionaryArtifactBuilder {
+    private readonly buffers;
+    private readonly bufferBytes;
+    private journal;
+    private journalBytes;
+    private journalPartition;
+    private readonly partitionCountValue;
+    private readonly partitionBufferBytesValue;
+    private readonly journalBytesValue;
+    private readonly peakBudgetValue;
+    private readonly detector;
+    private readonly target;
+    private readonly duplicateIds;
+    private duplicateIdBytes;
+    private uniqueTerms;
+    private totalTermBytes;
+    private recordCount;
+    private peakBytesValue;
+    private sidecarIneligible;
+    private flushFailed;
+    private finished;
+    constructor(options?: DictionaryArtifactBuildOptions);
+    get peakBytes(): number;
+    /** Consumes one record. The build peak stays within the 20 MiB buffer model. */
+    add(record: DictionaryArtifactRecordInput): DictionaryArtifactAddResult;
+    /** Flush every buffer, read the exact partition commits from the target, and finalize. */
+    finish(sessionId: string, indexDigest: string): DictionaryArtifactBuildResult;
+    /** Moves one partition's buffer into the journal (≤ 4 MiB) and flushes it to the target. */
+    private flushPartition;
+    private flushJournal;
+    private updatePeak;
+}
+/** Fixed in-memory cost of the retained dictionary-artifact runtime state (block-cache charged). */
+export declare function dictionaryArtifactRuntimeBytes(partitionCount?: number): number;
+/**
+ * One demoted provider-state value descriptor: exact ordinal, kind, byte
+ * location, and digest inside the `.spill.metadata-delta` section. The value
+ * bytes are persisted before demotion, so a descriptor always points at
+ * durable authenticated bytes.
+ */
+export interface MetadataDeltaValue {
+    /** Provider-state key (`providerStateEntryKey` semantics: type or `type:role`). */
+    key: string;
+    /** Entry type of the demoted value. */
+    kind: string;
+    /** Exact transcript ordinal of the demoted entry. */
+    ordinal: number;
+    /** Position in the build's ordered provider list (reopen merge slot). */
+    position: number;
+    offset: number;
+    length: number;
+    sha256: string;
+}
+/** Commit-marker binding for the disposable metadata-delta section. */
+export interface MetadataDeltaArtifactCommit {
+    /** Exact `.spill.idx` digest the sidecar set was built with. */
+    indexDigest: string;
+    /** Exact bytes of the `.spill.metadata-delta` file. */
+    size: number;
+    sha256: string;
+    values: readonly MetadataDeltaValue[];
+}
+/** Strict descriptor validation (any ambiguity fails closed). */
+export declare function isValidMetadataDeltaValue(value: unknown): value is MetadataDeltaValue;
+/** Strict commit-binding validation: bounded values, unique keys/positions, in-range offsets. */
+export declare function isValidMetadataDeltaCommit(value: unknown): value is MetadataDeltaArtifactCommit;
+/** Compute the descriptor for one value whose exact line bytes are about to be persisted. */
+export declare function metadataDeltaValueDescriptor(input: {
+    key: string;
+    kind: string;
+    ordinal: number;
+    position: number;
+    offset: number;
+    lineBytes: Uint8Array;
+}): MetadataDeltaValue;
+/** Resident bytes of one retained metadata-delta descriptor (key + 24 B descriptor + object). */
+export declare function metadataDeltaDescriptorResidentBytes(key: string): number;