@anureo/sdk 0.0.0-stage → 0.3.0

package/src/lifecycle/interactions.d.ts

@@ -0,0 +1,129 @@
+import { type InteractionRequested, type InteractionResponse, type InteractionResult } from "@anureo/protocol";
+import type { NativeInteractionResponder } from "../ports.js";
+/**
+ * Track native requests, settle their answers and retain bounded response replay state.
+ * Session uses this SDK implementation helper and supplies publication and privacy hooks.
+ * Direct consumers own those integrations and should await cancelAll with a teardown reason
+ * when releasing a session. The registry owns request expiry and native response wait timers.
+ */
+export declare class InteractionRegistry {
+    private readonly publish;
+    private readonly limits;
+    private readonly beforeResponse?;
+    /**
+     * Configure settlement publication and synchronous pre-response checks without starting native
+     * work. Session supplies a publisher that aborts the host handler and awaits publication of
+     * interaction/resolved while observation is open. It also supplies SecretRedactor.rememberResponse
+     * to register secrets before delivery. respond runs the check for every validated attempt, including
+     * replays, and propagates a throw before delivery. Settlement awaits publication without a deadline.
+     */
+    constructor(publish: (result: InteractionResult) => Promise<void>, limits: {
+        /** Pending and settling capacity. Admission trims resolved records at maxPending + 1024. */
+        maxPending: number;
+        /** Interaction lifetime in milliseconds, shortened by an earlier request expiresAt. */
+        timeoutMs: number;
+        /** Native response/cancellation wait in milliseconds, defaulting to 30,000. Native work can continue after timeout. */
+        responseTimeoutMs?: number;
+    }, beforeResponse?: ((request: InteractionRequested, response: InteractionResponse) => void) | undefined);
+    /**
+     * Count requests that consume admission capacity in begin, including native delivery and
+     * cancellation in flight. Capacity becomes available when a request is marked resolved.
+     */
+    get pendingCount(): number;
+    /**
+     * List detached copies of actionable requests for manual answering. Cloning failures throw
+     * without changing registry state. These copies retain native fields, so callers own projection
+     * before exposing them to observers.
+     */
+    pending(): InteractionRequested[];
+    /**
+     * Register a unique unexpired request and an unrefed expiry timer. Duplicate IDs, exhausted
+     * capacity and invalid/elapsed lifetimes throw synchronously. A request-cloning failure rejects
+     * the returned promise after the expiry timer is scheduled. On success, the promise resolves
+     * with the answer after native delivery and result publication.
+     * Cancellation and peer settlement reject it after publication is attempted. If native delivery
+     * fails and publishing its unknown outcome also fails, this waiter stays unresolved; respond
+     * rejects the publication failure instead.
+     * Session.requestInteraction adopts this promise after publishing interaction/requested and
+     * scheduling any host handler. Adapters supply the responder through that sink method and own
+     * the native resources it uses.
+     */
+    begin(request: InteractionRequested, responder: NativeInteractionResponder): Promise<InteractionResponse>;
+    /**
+     * Deliver an answer or replay the retained operation for the same request ID and serialized
+     * response. Validation and the synchronous pre-response hook run before any replay or delivery.
+     * Missing IDs reject with INTERACTION_EXPIRED. Conflicting answers to settling or resolved
+     * requests reject with INTERACTION_ALREADY_RESOLVED. The operation clears expiry, retains
+     * capacity during native delivery, and settles after the publication it initiates. If another
+     * settlement wins during delivery, late native success rejects with RESULT_UNKNOWN.
+     * Session.invokeRequest returns the promise for manual requests. Session.startInteractionHandler
+     * awaits it for automatic answers and attempts handler_failed cancellation on rejection while
+     * its signal remains active.
+     */
+    respond(id: string, requestId: string, response: InteractionResponse): Promise<InteractionResult>;
+    /**
+     * Cancel or expire an unresolved request, notifying native once when pending. The reason and
+     * outcome both default to "cancelled". Missing IDs reject with INTERACTION_EXPIRED. Resolved IDs
+     * and in-flight settlement with reason "cancelled" reject with INTERACTION_ALREADY_RESOLVED.
+     * Other reasons mark in-flight settlement unknown without another native call. Native notification
+     * failure or timeout also changes the outcome to unknown.
+     * Await publication, reject begin's waiter with INTERACTION_CANCELLED or RESULT_UNKNOWN, and
+     * return the outcome. If publication fails, the cancellation caller receives that failure and
+     * the original waiter still receives its lifecycle error. Session.invokeRequest returns this
+     * promise for manual cancellation. Session.startInteractionHandler and the expiry timer observe
+     * and suppress its rejection. cancelAll collects its outcome during teardown.
+     */
+    cancel(id: string, reason?: string, outcome?: CancellationOutcome): Promise<InteractionResult>;
+    /**
+     * Attempt concurrent cancellation of unresolved interactions, optionally limited to turnId; await
+     * every attempt and suppress individual failures. Session.fail, Session.finishClose and
+     * Session.dispose await this before releasing the backend. Use a reason other than "cancelled"
+     * to settle in-flight requests. The literal reason "connection_lost" requests an unknown outcome.
+     */
+    cancelAll(reason: string, turnId?: string): Promise<void>;
+    /**
+     * Publish native-side settlement without calling the responder; ignore unknown/resolved IDs
+     * and reject the waiter even for responded because no value is supplied. Clear expiry and release
+     * capacity before publication; publication failure rejects this call but still rejects the waiter.
+     * An unknown outcome rejects the waiter with RESULT_UNKNOWN; other outcomes use INTERACTION_ALREADY_RESOLVED.
+     * Session.resolveInteraction returns this promise to adapters reporting an already-settled native request.
+     */
+    resolveExternally(result: InteractionResult): Promise<void>;
+    private readonly records;
+    /**
+     * begin calls after admission checks, before inserting a new request. At the replay bound, evict
+     * only the oldest resolved record so unresolved native work and its capacity remain accounted for.
+     * Duplicate checks run first: a retained ID cannot be reused by evicting its own replay guard.
+     */
+    private evictOldestResolvedRecord;
+    /**
+     * respond caches this operation after admission. Bound native delivery without retrying it, then
+     * publish before resolving begin's waiter. If delivery succeeds after another settlement resolves
+     * the record, reject with RESULT_UNKNOWN without publishing again. Normalize delivery/publication
+     * failures for both callers. If publishing the unknown outcome itself fails, that failure escapes
+     * before the original waiter is rejected. Cancellation uses publishRejectedSettlement's finally instead.
+     */
+    private deliverResponse;
+    /**
+     * cancel calls only for an actionable record. Hold capacity and clear expiry before notifying native;
+     * timeout or notification failure changes the requested outcome to unknown. Release capacity before
+     * publication, then reject begin's waiter even if publication fails. Once started, this attempt
+     * still publishes after its native wait, even if teardown or peer settlement has already published.
+     */
+    private cancelPending;
+    /**
+     * Wait for publication before rejecting begin's waiter with its lifecycle error. A publication
+     * failure still reaches cancel, cancelPending or resolveExternally. Those callers clear expiry
+     * and release capacity before entering this step.
+     */
+    private publishRejectedSettlement;
+    /**
+     * Bound one invocation of the adapter's registered callback. deliverResponse supplies the answer
+     * and cancelPending supplies null and a reason. Both await and classify native errors or timeout.
+     * A timeout ends the registry's wait and keeps observing late rejection. The adapter still owns
+     * completion and native resource cleanup.
+     */
+    private notifyNative;
+}
+type CancellationOutcome = "cancelled" | "expired" | "unknown";
+export {};

package/src/lifecycle/interactions.js

@@ -0,0 +1,282 @@
+// Owns native interaction capacity, expiry, settlement and response replay.
+import { createHash } from "node:crypto";
+import { assertInteractionResponse } from "@anureo/protocol";
+import { HarnessSdkError, sdkError } from "../errors.js";
+import { waitForRequest } from "../request.js";
+/**
+ * Track native requests, settle their answers and retain bounded response replay state.
+ * Session uses this SDK implementation helper and supplies publication and privacy hooks.
+ * Direct consumers own those integrations and should await cancelAll with a teardown reason
+ * when releasing a session. The registry owns request expiry and native response wait timers.
+ */
+export class InteractionRegistry {
+    publish;
+    limits;
+    beforeResponse;
+    /**
+     * Configure settlement publication and synchronous pre-response checks without starting native
+     * work. Session supplies a publisher that aborts the host handler and awaits publication of
+     * interaction/resolved while observation is open. It also supplies SecretRedactor.rememberResponse
+     * to register secrets before delivery. respond runs the check for every validated attempt, including
+     * replays, and propagates a throw before delivery. Settlement awaits publication without a deadline.
+     */
+    constructor(publish, limits, beforeResponse) {
+        this.publish = publish;
+        this.limits = limits;
+        this.beforeResponse = beforeResponse;
+    }
+    /**
+     * Count requests that consume admission capacity in begin, including native delivery and
+     * cancellation in flight. Capacity becomes available when a request is marked resolved.
+     */
+    get pendingCount() {
+        return [...this.records.values()].filter((record) => record.state !== "resolved").length;
+    }
+    /**
+     * List detached copies of actionable requests for manual answering. Cloning failures throw
+     * without changing registry state. These copies retain native fields, so callers own projection
+     * before exposing them to observers.
+     */
+    pending() {
+        return [...this.records.values()]
+            .filter((record) => record.state === "pending")
+            .map((record) => structuredClone(record.request));
+    }
+    /**
+     * Register a unique unexpired request and an unrefed expiry timer. Duplicate IDs, exhausted
+     * capacity and invalid/elapsed lifetimes throw synchronously. A request-cloning failure rejects
+     * the returned promise after the expiry timer is scheduled. On success, the promise resolves
+     * with the answer after native delivery and result publication.
+     * Cancellation and peer settlement reject it after publication is attempted. If native delivery
+     * fails and publishing its unknown outcome also fails, this waiter stays unresolved; respond
+     * rejects the publication failure instead.
+     * Session.requestInteraction adopts this promise after publishing interaction/requested and
+     * scheduling any host handler. Adapters supply the responder through that sink method and own
+     * the native resources it uses.
+     */
+    begin(request, responder) {
+        if (this.records.has(request.interactionId))
+            throw new HarnessSdkError("INTERACTION_ALREADY_EXISTS");
+        if (this.pendingCount >= this.limits.maxPending)
+            throw new HarnessSdkError("BACKPRESSURE_EXCEEDED", "Pending interaction limit exceeded");
+        const ttl = interactionTtl(request, this.limits.timeoutMs);
+        if (!Number.isFinite(ttl) || ttl <= 0)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        this.evictOldestResolvedRecord();
+        const result = new Promise((resolve, reject) => {
+            // Expiry has no caller to receive cancellation failure. Settlement owns the request waiter.
+            const timer = setTimeout(() => { void this.cancel(request.interactionId, "timeout", "expired").catch(() => { }); }, ttl);
+            timer.unref?.();
+            this.records.set(request.interactionId, { request: structuredClone(request), responder, state: "pending", timer, resolve, reject });
+        });
+        // An adapter can still attach its await after the event publication; retain rejection observation meanwhile.
+        void result.catch(() => { });
+        return result;
+    }
+    /**
+     * Deliver an answer or replay the retained operation for the same request ID and serialized
+     * response. Validation and the synchronous pre-response hook run before any replay or delivery.
+     * Missing IDs reject with INTERACTION_EXPIRED. Conflicting answers to settling or resolved
+     * requests reject with INTERACTION_ALREADY_RESOLVED. The operation clears expiry, retains
+     * capacity during native delivery, and settles after the publication it initiates. If another
+     * settlement wins during delivery, late native success rejects with RESULT_UNKNOWN.
+     * Session.invokeRequest returns the promise for manual requests. Session.startInteractionHandler
+     * awaits it for automatic answers and attempts handler_failed cancellation on rejection while
+     * its signal remains active.
+     */
+    async respond(id, requestId, response) {
+        const record = this.records.get(id);
+        if (!record)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        assertInteractionResponse(record.request, response);
+        this.beforeResponse?.(record.request, response);
+        const fingerprint = responseFingerprint(response);
+        const replay = record.responseReplay;
+        if (replay && replay.requestId === requestId && replay.fingerprint === fingerprint) {
+            return replay.operation;
+        }
+        if (record.state !== "pending")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        // The responder can reenter synchronously. Mark the request settling before invoking it.
+        startSettlement(record);
+        const operation = this.deliverResponse({ id, record, response });
+        record.responseReplay = { requestId, fingerprint, operation };
+        return operation;
+    }
+    /**
+     * Cancel or expire an unresolved request, notifying native once when pending. The reason and
+     * outcome both default to "cancelled". Missing IDs reject with INTERACTION_EXPIRED. Resolved IDs
+     * and in-flight settlement with reason "cancelled" reject with INTERACTION_ALREADY_RESOLVED.
+     * Other reasons mark in-flight settlement unknown without another native call. Native notification
+     * failure or timeout also changes the outcome to unknown.
+     * Await publication, reject begin's waiter with INTERACTION_CANCELLED or RESULT_UNKNOWN, and
+     * return the outcome. If publication fails, the cancellation caller receives that failure and
+     * the original waiter still receives its lifecycle error. Session.invokeRequest returns this
+     * promise for manual cancellation. Session.startInteractionHandler and the expiry timer observe
+     * and suppress its rejection. cancelAll collects its outcome during teardown.
+     */
+    async cancel(id, reason = "cancelled", outcome = "cancelled") {
+        const record = this.records.get(id);
+        if (!record)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        if (record.state === "resolved")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        if (record.state === "pending")
+            return this.cancelPending({ id, record, reason, outcome });
+        if (reason === "cancelled")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        record.state = "resolved";
+        clearTimeout(record.timer);
+        const result = { interactionId: id, outcome: "unknown", reason };
+        await this.publishRejectedSettlement({ record, result, error: endedInFlight() });
+        return result;
+    }
+    /**
+     * Attempt concurrent cancellation of unresolved interactions, optionally limited to turnId; await
+     * every attempt and suppress individual failures. Session.fail, Session.finishClose and
+     * Session.dispose await this before releasing the backend. Use a reason other than "cancelled"
+     * to settle in-flight requests. The literal reason "connection_lost" requests an unknown outcome.
+     */
+    async cancelAll(reason, turnId) {
+        const ids = [...this.records]
+            .filter(([, record]) => record.state !== "resolved" && (turnId === undefined || record.request.turnId === turnId))
+            .map(([id]) => id);
+        const outcome = reason === "connection_lost" ? "unknown" : "cancelled";
+        await Promise.allSettled(ids.map((id) => this.cancel(id, reason, outcome)));
+    }
+    /**
+     * Publish native-side settlement without calling the responder; ignore unknown/resolved IDs
+     * and reject the waiter even for responded because no value is supplied. Clear expiry and release
+     * capacity before publication; publication failure rejects this call but still rejects the waiter.
+     * An unknown outcome rejects the waiter with RESULT_UNKNOWN; other outcomes use INTERACTION_ALREADY_RESOLVED.
+     * Session.resolveInteraction returns this promise to adapters reporting an already-settled native request.
+     */
+    async resolveExternally(result) {
+        const record = this.records.get(result.interactionId);
+        if (!record || record.state === "resolved")
+            return;
+        record.state = "resolved";
+        clearTimeout(record.timer);
+        await this.publishRejectedSettlement({
+            record, result,
+            error: new HarnessSdkError(result.outcome === "unknown" ? "RESULT_UNKNOWN" : "INTERACTION_ALREADY_RESOLVED", "Interaction was resolved by the native peer", false, result.outcome === "unknown"),
+        });
+    }
+    records = new Map();
+    /**
+     * begin calls after admission checks, before inserting a new request. At the replay bound, evict
+     * only the oldest resolved record so unresolved native work and its capacity remain accounted for.
+     * Duplicate checks run first: a retained ID cannot be reused by evicting its own replay guard.
+     */
+    evictOldestResolvedRecord() {
+        const atReplayLimit = this.records.size >= this.limits.maxPending + 1024;
+        if (!atReplayLimit)
+            return;
+        for (const [id, record] of this.records) {
+            if (record.state === "resolved") {
+                this.records.delete(id);
+                return;
+            }
+        }
+    }
+    /**
+     * respond caches this operation after admission. Bound native delivery without retrying it, then
+     * publish before resolving begin's waiter. If delivery succeeds after another settlement resolves
+     * the record, reject with RESULT_UNKNOWN without publishing again. Normalize delivery/publication
+     * failures for both callers. If publishing the unknown outcome itself fails, that failure escapes
+     * before the original waiter is rejected. Cancellation uses publishRejectedSettlement's finally instead.
+     */
+    async deliverResponse({ id, record, response }) {
+        try {
+            await this.notifyNative(record, response);
+            if (record.state === "resolved")
+                throw endedInFlight();
+            const result = { interactionId: id, outcome: "responded" };
+            // Release capacity before publication, but never release the waiter before publication finishes.
+            record.state = "resolved";
+            await this.publish(result);
+            record.resolve(response);
+            return result;
+        }
+        catch (cause) {
+            // This also catches publication failures, not just responder failures.
+            const error = sdkError(cause, "RESULT_UNKNOWN", true);
+            if (record.state !== "resolved") {
+                record.state = "resolved";
+                await this.publish({ interactionId: id, outcome: "unknown", reason: error.code });
+            }
+            record.reject(error);
+            throw error;
+        }
+    }
+    /**
+     * cancel calls only for an actionable record. Hold capacity and clear expiry before notifying native;
+     * timeout or notification failure changes the requested outcome to unknown. Release capacity before
+     * publication, then reject begin's waiter even if publication fails. Once started, this attempt
+     * still publishes after its native wait, even if teardown or peer settlement has already published.
+     */
+    async cancelPending({ id, record, reason, outcome }) {
+        startSettlement(record);
+        try {
+            await this.notifyNative(record, null, reason);
+        }
+        catch {
+            outcome = "unknown";
+        }
+        record.state = "resolved";
+        const result = { interactionId: id, outcome, reason };
+        const outcomeUnknown = outcome === "unknown";
+        await this.publishRejectedSettlement({
+            record, result,
+            error: new HarnessSdkError(outcomeUnknown ? "RESULT_UNKNOWN" : "INTERACTION_CANCELLED", "Interaction is no longer actionable", false, outcomeUnknown),
+        });
+        return result;
+    }
+    /**
+     * Wait for publication before rejecting begin's waiter with its lifecycle error. A publication
+     * failure still reaches cancel, cancelPending or resolveExternally. Those callers clear expiry
+     * and release capacity before entering this step.
+     */
+    async publishRejectedSettlement({ record, result, error }) {
+        try {
+            await this.publish(result);
+        }
+        finally {
+            record.reject(error);
+        }
+    }
+    /**
+     * Bound one invocation of the adapter's registered callback. deliverResponse supplies the answer
+     * and cancelPending supplies null and a reason. Both await and classify native errors or timeout.
+     * A timeout ends the registry's wait and keeps observing late rejection. The adapter still owns
+     * completion and native resource cleanup.
+     */
+    notifyNative(record, ...args) {
+        return waitForRequest(() => record.responder(...args), { timeoutMs: this.limits.responseTimeoutMs ?? 30_000 });
+    }
+}
+/** Hold admission capacity and clear expiry before respond or cancelPending invokes the adapter. */
+function startSettlement(record) {
+    record.state = "settling";
+    clearTimeout(record.timer);
+}
+/** Share the unknown-outcome error between in-flight teardown and a superseded response delivery. */
+function endedInFlight() {
+    return new HarnessSdkError("RESULT_UNKNOWN", "Interaction ended while response was in flight", false, true);
+}
+/**
+ * InteractionRegistry.begin uses the returned duration before allocating its expiry timer. Clamp a
+ * nonempty request expiry to the configured interaction lifetime; omitted/empty expiry uses the full
+ * lifetime. begin rejects a non-finite or non-positive result before allocating its timer.
+ */
+function interactionTtl(request, timeoutMs) {
+    return request.expiresAt ? Math.min(timeoutMs, new Date(request.expiresAt).getTime() - Date.now()) : timeoutMs;
+}
+/**
+ * InteractionRegistry.respond stores and compares this fingerprint before deciding whether to replay
+ * the response promise. Hash the serialized payload for replay detection; the request ID alone
+ * cannot distinguish conflicting retries.
+ */
+function responseFingerprint(response) {
+    return createHash("sha256").update(JSON.stringify(response)).digest("hex");
+}

package/src/lifecycle/limits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate the selected retention budget as a positive safe integer, using the caller's fallback
+ * for an omitted value. Throw INVALID_PARAMS on failure. assertClientOptions checks configured
+ * limits at construction. Session.context, getOrCreateSubmission and retainEvent use the returned
+ * budget for allocation or accounting in units chosen at each call site.
+ */
+export declare function positive(value: number | undefined, fallback: number): number;

package/src/lifecycle/limits.js

@@ -0,0 +1,13 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Validate the selected retention budget as a positive safe integer, using the caller's fallback
+ * for an omitted value. Throw INVALID_PARAMS on failure. assertClientOptions checks configured
+ * limits at construction. Session.context, getOrCreateSubmission and retainEvent use the returned
+ * budget for allocation or accounting in units chosen at each call site.
+ */
+export function positive(value, fallback) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result <= 0)
+        throw new HarnessSdkError('INVALID_PARAMS');
+    return result;
+}

package/src/lifecycle/result.d.ts

@@ -0,0 +1,77 @@
+import type { AhpEvent } from '@anureo/protocol';
+import type { TurnResult } from "../types.js";
+/**
+ * Session.context creates one accumulator per execution. Session.retainEvent supplies privacy-projected
+ * events in publication order and uses the terminal snapshot to resolve the promise read by Turn.result.
+ * Session owns event validation, publication, shared budgets and reclamation.
+ */
+export declare class ResultAccumulator {
+    private readonly maxBytes;
+    private readonly maxItems;
+    /**
+     * Session.context supplies positive safe integers for serialized bytes and distinct items.
+     * Omitted session limits default to 16 MiB and 2,048 items before construction.
+     */
+    constructor(maxBytes: number, maxItems: number);
+    /**
+     * Return the UTF-8 JSON byte total of the individual items as if buffered text were materialized.
+     * Session.retainEvent uses the difference across an update for its shared budget, and
+     * Session.reclaimExecution subtracts the total on eviction. Usage and envelope bytes are excluded.
+     */
+    get size(): number;
+    /**
+     * Retain detached turn usage and item content before Session.retainEvent publishes the event.
+     * Snapshots replace buffered content and completed items ignore subsequent deltas. A conflicting
+     * patch throws PROTOCOL_ERROR. Exceeding either limit throws RESULT_BUDGET_EXCEEDED. These throws
+     * reject Session.emit and reach Session.fail, which rejects unfinished Turn.result waits.
+     * Serialization and clone failures also propagate to Session.emit.
+     */
+    accept(event: AhpEvent): void;
+    /**
+     * Build a detached, frozen snapshot from the current retention. Turn-scoped usage in the terminal
+     * event takes precedence over the latest retained turn usage. Final messages are joined with
+     * newlines in first-seen order. Failed results without native error details get TURN_FAILED.
+     * Session.retainEvent resolves the promise read by Turn.result with this snapshot for every native
+     * terminal status, then publishes the terminal event and ends the execution stream. If cloning or
+     * freezing throws, Session.emit rejects before the snapshot or event is delivered.
+     */
+    finish(payload: Extract<AhpEvent, {
+        type: 'turn/completed';
+    }>['payload']): TurnResult;
+    /**
+     * Reset retained items, completion markers, usage and bytes for reuse. Previously returned snapshots
+     * stay independent.
+     */
+    clear(): void;
+    private readonly items;
+    private readonly completed;
+    private bytes;
+    private usage?;
+    /**
+     * Apply a delta for an item without a completion marker. Snapshot patches take the replacement
+     * path. Text deltas buffer only their matching field on a retained item. Retention failures
+     * propagate to accept.
+     */
+    private acceptDelta;
+    /**
+     * acceptDelta passes patch values here after Session.publish has projected them.
+     * Only a patch object with a type discriminator can replace a snapshot. SecretRedactor.deltaValue
+     * validates its shape upstream. Throw PROTOCOL_ERROR on a missing base item or a mismatch in ID
+     * or family. A valid patch replaces the snapshot and discards its text buffer.
+     */
+    private applySnapshotPatch;
+    /**
+     * acceptDelta supplies a matching field and its snapshot value. Check the exact JSON byte change
+     * before updating the buffer or accounting. Throw RESULT_BUDGET_EXCEEDED without retaining the
+     * chunk on overflow. An empty chunk can establish an absent or non-string field. Preserve a
+     * buffered surrogate tail across empty chunks so a later chunk can complete the pair.
+     */
+    private append;
+    /**
+     * accept and applySnapshotPatch store detached snapshots here. Check capacity and clone before
+     * mutation. Budget failure throws RESULT_BUDGET_EXCEEDED and serialization or clone failures
+     * propagate. Replacing an existing entry discards its provisional buffer while preserving its
+     * first-seen position for finish.
+     */
+    private retainSnapshot;
+}