firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/observations.js

@@ -0,0 +1,1159 @@
+/**
+ * Bounded in-memory observation buffer (Plan20 W09, spec 3.5).
+ *
+ * Converts driver observations into immutable artifacts and ObservationBatch v1
+ * envelopes for one assignment attempt:
+ *  - every observation becomes one JSON artifact (canonical JSON, bounded,
+ *    sha256-hashed). A binary attachment is described, not uploaded (below);
+ *  - events get NATIVE_ID-shaped ids and contiguous sequences after the cloud's
+ *    last acknowledgement, with `elapsed_ms` relative to the drill start and
+ *    non-decreasing (root validation requires that within a batch);
+ *  - artifacts are uploaded BEFORE the batch that references them;
+ *  - batches hold at most 128 events and match observation-batch.v1 exactly;
+ *  - at most `maxBufferedBytes` of not-yet-uploaded artifact bytes are held;
+ *    `room()` is the backpressure point and `add()` drops (and reports) instead
+ *    of exceeding the cap;
+ *  - transient failures are retried with capped backoff; the cloud's returned
+ *    acknowledgement is authoritative: anything at or below it is dropped from
+ *    memory, anything above it is re-sent, and a regressed acknowledgement is
+ *    adopted (resequencing only events the cloud never accepted).
+ *
+ * There is no durable local journal. Bytes dropped for capacity, lost on a
+ * regressed acknowledgement, or left unacknowledged after the final flush make
+ * the evidence incomplete; they are reported, never regenerated.
+ *
+ * Root evidence rules applied here:
+ *  - each observation is one declared JSON record (<= 256 KiB) whose role is the
+ *    event kind; root assigns the artifact id after declaration and the event
+ *    references it; at most 4096 records and 64 MiB per assignment;
+ *  - content passes the client-filtered-v1 profile (evidence-filter.ts) first;
+ *  - a `conversation.observed` event carries exactly the target-message
+ *    document cloud participants read;
+ *  - binary attachments are refused by root, so they are counted as
+ *    unsupported (not uploaded) without making the evidence incomplete;
+ *  - approved captures are their own `state.observed` records: masked PNG
+ *    screenshots and interval frames (role `screenshot.observed`) and sanitized
+ *    action trace segments (role `trace.observed`, exactly root's document).
+ *    They are optional, so each leaves room for the step's own records;
+ *  - one record root refuses (privacy or capacity) is dropped and reported;
+ *    the rest of the evidence keeps flowing.
+ */
+import { randomBytes, randomUUID } from 'node:crypto';
+import { CliError } from '../http.js';
+import { canonicalJson, sha256Hex } from './canonical.js';
+import { CAPTURE_SCHEMA, CAPTURE_UNAVAILABLE_REASONS, EVIDENCE_MAX_RECORDS, EVIDENCE_MAX_TOTAL_BYTES, EVIDENCE_RECORD_MAX_BYTES, FRAME_OMISSION_REASONS, MAX_FRAMES_PER_STEP, NATIVE_ID, OBSERVATION_BATCH_MAX_EVENTS, UUID_PATTERN, OBSERVATION_KINDS, SHA256_HEX, TARGET_MESSAGE_MAX_CHARS, TARGET_RESULT_MAX_BYTES, TARGET_RESULT_SCAN_CHARS, TRACE_OPERATIONS, TRACE_OUTCOMES, TRACE_PARTIAL_REASONS, TRACE_PROFILE, TRACE_SEGMENT_MAX_EVENTS, TRACE_SEGMENT_SCHEMA, } from './contracts.js';
+import { PNG_MAX_BYTES, isMetadataFreePng } from './png.js';
+import { backoffMs, errorCode, isTransient, retryTransient, sleep } from './control-plane.js';
+import { evidenceNodes, filterEvidenceValue } from './evidence-filter.js';
+/** Root refusals that end one record, not the whole evidence stream. */
+const RECORD_REFUSALS = new Set(['native_evidence_privacy_refused', 'native_artifact_capacity', 'native_artifact_invalid']);
+/**
+ * The record's request key can no longer be used: its upload window closed
+ * (`expired`), or root already ended it — expiry cleanup ran, or a refusal whose
+ * answer was lost (`unavailable`). A new request key re-declares the same bytes.
+ */
+const RECORD_RENEWABLE = new Set(['native_artifact_expired', 'native_artifact_unavailable']);
+const MAX_RECORD_RENEWALS = 3;
+/** Smaller string caps tried, in order, when a record's filtered JSON exceeds the per-record limit. */
+const SHRINK_STRING_CHARS = [4_000, 1_000, 256];
+export const OBSERVATION_ARTIFACT_MEDIA_TYPE = 'application/json';
+const ARTIFACT_VERSION = 1;
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+/** Room kept for the drill's signed close record (one record, at most 64 KiB) within root's per-assignment caps. */
+const CLOSE_RESERVE_RECORDS = 1;
+const CLOSE_RESERVE_BYTES = 65_536;
+/**
+ * Screenshots are optional evidence: together they may use at most this share of
+ * the drill's byte budget, so the replies and results root completes each action
+ * with always keep their room.
+ */
+const SCREENSHOT_BUDGET_SHARE = 0.5;
+/**
+ * Room kept for the step's reply or result after an optional capture record:
+ * a target reply of 16,000 characters, each at most six bytes once escaped,
+ * plus its fields (a task or event result is smaller, at most 32,000 bytes).
+ */
+const STEP_RESULT_RESERVE_BYTES = 98_304;
+/** Records kept after an optional capture record: the observation naming it and the step's reply or result. */
+const STEP_RESERVE_RECORDS = 2;
+/** Room an interval frame keeps for the step's own screenshot outcome: at least its `capture.unavailable` record. */
+const CAPTURE_RECORD_RESERVE_BYTES = 2_048;
+/** Accounting overhead per pending event (ids, numbers, bookkeeping). */
+const EVENT_OVERHEAD_BYTES = 256;
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9.+-]{0,63}\/[a-z0-9][a-z0-9.+-]{0,63}$/i;
+const KINDS = new Set(OBSERVATION_KINDS);
+function nativeId(prefix) {
+    return `${prefix}${randomBytes(16).toString('hex')}`;
+}
+const isFrameReason = (value) => FRAME_OMISSION_REASONS.includes(value);
+/** The driver's frames, bounded: at most MAX_FRAMES_PER_STEP shots (any more are omitted for `step_limit`), known reasons only. */
+function boundedFrames(frames) {
+    const shots = Array.isArray(frames?.shots) ? frames.shots : [];
+    const extra = Math.max(0, shots.length - MAX_FRAMES_PER_STEP);
+    const reasons = new Set((Array.isArray(frames?.reasons) ? frames.reasons : []).filter(isFrameReason));
+    if (extra)
+        reasons.add('step_limit');
+    const counted = typeof frames?.omitted === 'number' && Number.isSafeInteger(frames.omitted) && frames.omitted > 0 ? frames.omitted : 0;
+    return { shots: shots.slice(0, MAX_FRAMES_PER_STEP), omitted: Math.min(MAX_SAFE, counted + extra),
+        reasons: FRAME_OMISSION_REASONS.filter((reason) => reasons.has(reason)) };
+}
+/** What the step observation says about its interval frames. */
+function frameReference(ids, omitted, reasons) {
+    return { frame_event_ids: ids, frames_omitted: omitted, frame_omission_reasons: [...reasons] };
+}
+function positiveInt(value, fallback, max = MAX_SAFE) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? Math.min(value, max) : fallback;
+}
+function assignmentInvalid() {
+    return new CliError('native_assignment_invalid', 'Observations were not recorded: the assignment identity, lease or acknowledgement is malformed.');
+}
+function checkAssignment(assignment) {
+    const id = (value) => typeof value === 'string' && NATIVE_ID.test(value);
+    const int = (value, min) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+    if (!id(assignment.assignment_id) || !id(assignment.attempt_id) || !int(assignment.lease_epoch, 1)
+        || !int(assignment.state_generation, 1) || !int(assignment.observation_ack, 0)
+        || (assignment.observation_elapsed_ms !== undefined && !int(assignment.observation_elapsed_ms, 0)))
+        throw assignmentInvalid();
+}
+export class ObservationBuffer {
+    #options;
+    #assignment;
+    #maxBuffered;
+    #maxArtifact;
+    #maxTotal;
+    #flushDelay;
+    #attempts;
+    #pending = [];
+    #acked;
+    #assigned;
+    #lastElapsed = 0;
+    #buffered = 0;
+    #uploadedBytes = 0;
+    #acceptedBytes = 0;
+    #droppedObservations = 0;
+    #droppedBytes = 0;
+    #omitted = 0;
+    #unsupportedAttachments = 0;
+    #screenshots = 0;
+    #frames = 0;
+    #traceSegments = 0;
+    /** Bytes of screenshots and frames together, held to SCREENSHOT_BUDGET_SHARE of the drill's budget. */
+    #screenshotBytes = 0;
+    #captureUnavailable = 0;
+    #filtered = 0;
+    #records = 0;
+    #lostSequences = 0;
+    #inconsistent = false;
+    #closed = false;
+    #pump = null;
+    #rerun = false;
+    #timer = null;
+    #failure = null;
+    #permanentFailure = false;
+    #roomWaiters = new Set();
+    /**
+     * The batch in flight. Its id, events and previous_ack are pinned until the
+     * cloud's acknowledgement moves: a re-send (after a transient failure or an
+     * unchanged acknowledgement) carries the same batch_id and the same events,
+     * even if more observations arrived meanwhile.
+     */
+    #batch = null;
+    #lostStepEvidence = 0;
+    #wholeDependencyCaptureLost = 0;
+    /** The final outcome event and its batch, pinned so a retry re-sends the same batch. */
+    #outcome = null;
+    /** Event ids the cloud acknowledged (at most EVIDENCE_MAX_RECORDS), for `delivered`. */
+    #acknowledgedIds = new Set();
+    /** Committed records of acknowledged events added with `keep`. */
+    #kept = new Map();
+    /** True while the readiness event's sequence is reserved: nothing else is sent. */
+    #holding = false;
+    /** The readiness event and its batch, pinned so a retry re-sends the same batch. */
+    #readiness = null;
+    constructor(options) {
+        checkAssignment(options.assignment);
+        this.#options = options;
+        this.#assignment = options.assignment;
+        this.#maxBuffered = positiveInt(options.maxBufferedBytes, 32 * 1024 * 1024);
+        this.#maxArtifact = positiveInt(options.maxArtifactBytes, EVIDENCE_RECORD_MAX_BYTES, Math.min(this.#maxBuffered, EVIDENCE_RECORD_MAX_BYTES));
+        const budget = options.assignment.budgets?.max_observation_bytes;
+        this.#maxTotal = positiveInt(budget, EVIDENCE_MAX_TOTAL_BYTES, EVIDENCE_MAX_TOTAL_BYTES);
+        this.#flushDelay = Math.max(0, Math.min(options.flushDelayMs ?? 250, 10_000));
+        this.#attempts = positiveInt(options.attempts, 5, 20);
+        this.#acked = options.assignment.observation_ack;
+        this.#assigned = options.assignment.observation_ack;
+        // A resumed attempt continues from root's acknowledged elapsed floor; root refuses lower values.
+        this.#lastElapsed = options.assignment.observation_elapsed_ms ?? 0;
+    }
+    /** True once delivery stopped for a non-transient reason; further observations will not be delivered. */
+    get failed() { return this.#permanentFailure; }
+    get bufferedBytes() { return this.#buffered; }
+    /**
+     * Accept one observation. Never throws and never blocks: capacity overruns and
+     * malformed observations are dropped and reported as incomplete evidence.
+     * Returns the event id it will be sent under, or null when it was dropped.
+     */
+    add(observation, keep = false) {
+        if (this.#closed || this.#permanentFailure) {
+            if (observation?.dependency_exchange !== undefined)
+                this.#wholeDependencyCaptureLost++;
+            this.#drop(0);
+            return null;
+        }
+        if (!observation || typeof observation !== 'object' || !KINDS.has(observation.kind)) {
+            if (observation?.dependency_exchange !== undefined)
+                this.#wholeDependencyCaptureLost++;
+            this.#drop(0);
+            return null;
+        }
+        if (this.#assigned >= MAX_SAFE || this.#records >= EVIDENCE_MAX_RECORDS - CLOSE_RESERVE_RECORDS) {
+            if (observation.dependency_exchange !== undefined)
+                this.#wholeDependencyCaptureLost++;
+            this.#drop(0);
+            return null;
+        }
+        let json;
+        let role;
+        // Optional evidence keeps room (bytes and records) for what the step still has to record.
+        let reserve = 0, reserveRecords = 0;
+        if (observation.dependency_exchange !== undefined) {
+            json = observation.kind === 'action.observed' ? this.#encodeDependencyExchange(observation.dependency_exchange) : null;
+            if (!json) {
+                this.#wholeDependencyCaptureLost++;
+                this.#drop(0);
+                return null;
+            }
+            role = 'dependency.exchange.observed';
+            reserve = Math.min(this.#maxArtifact, STEP_RESULT_RESERVE_BYTES) + EVENT_OVERHEAD_BYTES;
+            reserveRecords = STEP_RESERVE_RECORDS;
+        }
+        else if (observation.target_message !== undefined) {
+            json = observation.kind === 'conversation.observed' ? this.#encodeTargetMessage(observation.target_message) : null;
+            if (!json) {
+                this.#drop(0);
+                return null;
+            }
+        }
+        else if (observation.target_result !== undefined) {
+            json = observation.kind === 'action.observed' ? this.#encodeTargetResult(observation.target_result) : null;
+            if (!json) {
+                this.#drop(0);
+                return null;
+            }
+        }
+        else if (observation.trace_segment !== undefined) {
+            // Exactly root's segment document; a segment that cannot be one is dropped, which root reads as a gap.
+            json = observation.kind === 'state.observed' ? this.#encodeTraceSegment(observation.trace_segment) : null;
+            if (!json) {
+                this.#drop(0);
+                return null;
+            }
+            role = 'trace.observed';
+            reserve = Math.min(this.#maxArtifact, STEP_RESULT_RESERVE_BYTES) + EVENT_OVERHEAD_BYTES;
+            reserveRecords = 1;
+        }
+        else {
+            let attachmentRef = null;
+            // The reference the content's value budget is sized for: the longest one when captures were measured with it.
+            let sizedFor = null;
+            if (observation.capture !== undefined) {
+                if (observation.kind === 'action.observed') {
+                    // Each capture is its own state.observed record, sent just before this one, which names it: the
+                    // approved interval frames in capture order, then the step's screenshot, or a capture.unavailable
+                    // record when it has no image. Captures are optional, so they may only use room left after this
+                    // record (measured with its longest reference) and the step's reply or result, which root completes
+                    // the action with; a frame also leaves room for the step's screenshot outcome.
+                    const capture = observation.capture;
+                    const frames = capture.frames === undefined ? null : boundedFrames(capture.frames);
+                    const longest = { capture_unavailable_event_id: nativeId('ev'),
+                        ...(frames ? frameReference(frames.shots.map(() => nativeId('ev')), MAX_SAFE, FRAME_OMISSION_REASONS) : {}) };
+                    sizedFor = longest;
+                    const captureReserve = this.#encode(observation.kind, observation.content, longest, false).byteLength
+                        + Math.min(this.#maxArtifact, STEP_RESULT_RESERVE_BYTES) + 2 * EVENT_OVERHEAD_BYTES;
+                    const framed = frames ? this.#addFrames(frames, captureReserve + CAPTURE_RECORD_RESERVE_BYTES + EVENT_OVERHEAD_BYTES) : null;
+                    attachmentRef = { ...this.#addCapture(observation.at_ms, capture, captureReserve), ...(framed ?? {}) };
+                }
+                else {
+                    attachmentRef = { omitted: 'screenshot_not_recorded' };
+                }
+            }
+            const attachment = observation.capture === undefined ? observation.attachment : undefined;
+            if (attachment !== undefined) {
+                const bytes = attachment?.bytes, mediaType = attachment?.media_type;
+                // The media type is recorded as text, so it must pass the same filter unchanged.
+                if (!(bytes instanceof Uint8Array) || typeof mediaType !== 'string' || !MEDIA_TYPE.test(mediaType)
+                    || filterEvidenceValue(mediaType.toLowerCase(), 2).value !== mediaType.toLowerCase()) {
+                    attachmentRef = { omitted: 'malformed' };
+                    this.#omitted++;
+                }
+                else {
+                    // Root accepts JSON and text evidence only; binary capture waits for its masking profile.
+                    attachmentRef = { omitted: 'unsupported_media', media_type: mediaType.toLowerCase(), bytes: bytes.byteLength };
+                    this.#unsupportedAttachments++;
+                }
+            }
+            // The real reference never holds more values than the longest, so the content filters exactly as measured.
+            json = this.#encode(observation.kind, observation.content, attachmentRef, true, sizedFor ?? attachmentRef);
+        }
+        if (!this.#fits(json.byteLength + reserve) || this.#records >= EVIDENCE_MAX_RECORDS - CLOSE_RESERVE_RECORDS - reserveRecords) {
+            // Not even the bounded JSON fits: drop the whole observation, never partially record it.
+            if (observation.dependency_exchange !== undefined)
+                this.#wholeDependencyCaptureLost++;
+            this.#drop(json.byteLength);
+            return null;
+        }
+        const artifact = {
+            artifact_id: null, screenshot: null, role, request_key: randomUUID(), renewals: 0, sha256: sha256Hex(json), size: json.byteLength, bytes: json,
+        };
+        const event = {
+            event_id: nativeId('ev'), sequence: ++this.#assigned, kind: observation.kind,
+            elapsed_ms: this.#elapsed(observation.at_ms), artifact_id: '', artifact_sha256: artifact.sha256,
+        };
+        this.#records++;
+        this.#buffered += artifact.size + EVENT_OVERHEAD_BYTES;
+        this.#acceptedBytes += artifact.size;
+        this.#pending.push({ event, artifact, keep });
+        if (role === 'trace.observed')
+            this.#traceSegments++;
+        this.#schedule(this.#pending.length >= OBSERVATION_BATCH_MAX_EVENTS);
+        return event.event_id;
+    }
+    /**
+     * Queue the approved interval frames, oldest first, each its own masked PNG
+     * record at its own capture time, and return what the step observation says
+     * about them. A frame that is malformed or does not fit is counted as omitted
+     * with its reason: frames are optional, so a missing one is reported in that
+     * reference and never makes the evidence incomplete.
+     */
+    #addFrames(frames, reserve) {
+        const ids = [];
+        let omitted = frames.omitted;
+        const reasons = new Set(frames.reasons);
+        for (const shot of frames.shots) {
+            const added = this.#addScreenshot(shot?.at_ms, shot, reserve, STEP_RESERVE_RECORDS + 1, true);
+            if (added.event_id !== null) {
+                ids.push(added.event_id);
+                continue;
+            }
+            omitted = Math.min(MAX_SAFE, omitted + 1);
+            reasons.add(added.reason);
+        }
+        return frameReference(ids, omitted, FRAME_OMISSION_REASONS.filter((reason) => reasons.has(reason)));
+    }
+    /**
+     * Queue an approved capture's record and return the reference the observation
+     * that captured it carries: the screenshot event, or a `capture.unavailable`
+     * record when there is no image. When not even that small record fits, the
+     * overflow already counted stands and no capture record is invented.
+     */
+    #addCapture(atMs, capture, reserve) {
+        let reason;
+        if ('png' in capture) {
+            const added = this.#addScreenshot(atMs, capture, reserve);
+            if (added.event_id !== null)
+                return { screenshot_event_id: added.event_id };
+            reason = added.reason;
+        }
+        else {
+            reason = capture.unavailable;
+        }
+        const id = this.#addCaptureUnavailable(atMs, capture, reason, reserve);
+        return id ? { capture_unavailable_event_id: id } : { omitted: 'screenshot_not_recorded' };
+    }
+    /**
+     * Queue one bounded `state.observed` `capture.unavailable` record: ids, the
+     * policy digest and the reason, never error text or page content. Returns its
+     * event id, or null when it is malformed (counted as omitted) or does not fit
+     * (counted as dropped).
+     */
+    #addCaptureUnavailable(atMs, capture, reason, reserve) {
+        if (!CAPTURE_UNAVAILABLE_REASONS.includes(reason) || typeof capture?.masking_policy_sha256 !== 'string'
+            || !SHA256_HEX.test(capture.masking_policy_sha256) || typeof capture.step_id !== 'string' || typeof capture.session_key !== 'string') {
+            this.#omitted++;
+            return null;
+        }
+        if (this.#assigned >= MAX_SAFE || this.#records >= EVIDENCE_MAX_RECORDS - CLOSE_RESERVE_RECORDS - STEP_RESERVE_RECORDS) {
+            this.#drop(0);
+            return null;
+        }
+        const json = this.#encode('state.observed', {
+            type: 'capture.unavailable', schema: CAPTURE_SCHEMA, capture: 'screenshot', step_id: capture.step_id,
+            session_key: capture.session_key, masking_policy_sha256: capture.masking_policy_sha256, reason,
+        }, null);
+        if (!this.#fits(json.byteLength + reserve)) {
+            this.#drop(json.byteLength);
+            return null;
+        }
+        const artifact = {
+            artifact_id: null, screenshot: null, request_key: randomUUID(), renewals: 0, sha256: sha256Hex(json), size: json.byteLength, bytes: json,
+        };
+        const event = {
+            event_id: nativeId('ev'), sequence: ++this.#assigned, kind: 'state.observed',
+            elapsed_ms: this.#elapsed(atMs), artifact_id: '', artifact_sha256: artifact.sha256,
+        };
+        this.#records++;
+        this.#buffered += artifact.size + EVENT_OVERHEAD_BYTES;
+        this.#acceptedBytes += artifact.size;
+        this.#pending.push({ event, artifact, keep: false });
+        this.#captureUnavailable++;
+        return event.event_id;
+    }
+    /**
+     * Queue an approved masked screenshot or interval frame as its own
+     * `state.observed` event whose record is the PNG (artifact role
+     * `screenshot.observed`), which root's captured-frame playback reads by
+     * elapsed time. Returns its event id, or the reason it was not queued. For the
+     * step's screenshot, malformed is counted as omitted and not fitting as
+     * dropped; a frame (`frame`) is reported only in the step's frame reference.
+     */
+    #addScreenshot(atMs, shot, reserve, reserveRecords = STEP_RESERVE_RECORDS, frame = false) {
+        const png = shot?.png;
+        if (!(png instanceof Uint8Array) || !isMetadataFreePng(png) || png.byteLength > PNG_MAX_BYTES
+            || typeof shot.masking_policy_sha256 !== 'string' || !SHA256_HEX.test(shot.masking_policy_sha256)) {
+            if (!frame)
+                this.#omitted++;
+            return { event_id: null, reason: 'image_unsupported' };
+        }
+        // Past the screenshot share the step records why instead (a capture.unavailable record): nothing is lost.
+        if (this.#screenshotBytes + png.byteLength > Math.floor(this.#maxTotal * SCREENSHOT_BUDGET_SHARE)) {
+            return { event_id: null, reason: 'evidence_capacity' };
+        }
+        if (this.#assigned >= MAX_SAFE || this.#records >= EVIDENCE_MAX_RECORDS - CLOSE_RESERVE_RECORDS - reserveRecords
+            || !this.#fits(png.byteLength + reserve)) {
+            if (!frame)
+                this.#drop(png.byteLength);
+            return { event_id: null, reason: 'evidence_capacity' };
+        }
+        const artifact = {
+            artifact_id: null, request_key: randomUUID(), renewals: 0, sha256: sha256Hex(png), size: png.byteLength, bytes: png,
+            screenshot: { consent: true, source: 'playwright', masking_applied: true, masking_policy_sha256: shot.masking_policy_sha256 },
+        };
+        const event = {
+            event_id: nativeId('ev'), sequence: ++this.#assigned, kind: 'state.observed',
+            elapsed_ms: this.#elapsed(atMs), artifact_id: '', artifact_sha256: artifact.sha256,
+        };
+        this.#records++;
+        this.#buffered += artifact.size + EVENT_OVERHEAD_BYTES;
+        this.#acceptedBytes += artifact.size;
+        this.#pending.push({ event, artifact, keep: false });
+        if (frame)
+            this.#frames++;
+        else
+            this.#screenshots++;
+        this.#screenshotBytes += png.byteLength;
+        return { event_id: event.event_id };
+    }
+    /** The committed record of an acknowledged event added with `keep`, or null (not yet acknowledged, refused or dropped). */
+    record(eventId) {
+        return this.#kept.get(eventId) ?? null;
+    }
+    /**
+     * Record that a step's own observations never reached the buffer (the driver
+     * did not return them before the runner's bound). The count is unknown, so
+     * the evidence is reported incomplete; nothing is regenerated.
+     */
+    noteLostStepEvidence() { this.#lostStepEvidence++; }
+    /**
+     * Backpressure: resolves when buffered bytes are at or below half the cap,
+     * delivery failed, the buffer closed, the transport signal aborted, or the
+     * caller's `wake` signal fired (graceful stop, lease expiry).
+     */
+    async room(wake) {
+        const low = Math.floor(this.#maxBuffered / 2);
+        const signals = wake ? [this.#options.signal, wake] : [this.#options.signal];
+        const woken = () => signals.some((signal) => signal.aborted);
+        if (this.#buffered <= low || this.#permanentFailure || woken())
+            return;
+        this.#schedule(true);
+        await new Promise((resolve) => {
+            const check = () => {
+                if (this.#buffered <= low || this.#permanentFailure || woken() || this.#closed) {
+                    this.#roomWaiters.delete(check);
+                    for (const signal of signals)
+                        signal.removeEventListener('abort', check);
+                    resolve();
+                }
+            };
+            this.#roomWaiters.add(check);
+            for (const signal of signals)
+                signal.addEventListener('abort', check, { once: true });
+            check();
+        });
+    }
+    /**
+     * Resolves true once the cloud acknowledged event `eventId` (root completes a
+     * target action only with an acknowledged reply event); false when the event
+     * was refused or dropped, delivery failed for good, the buffer finished
+     * without it, or the transport or `wake` aborted first. Never throws.
+     */
+    async delivered(eventId, wake) {
+        const signals = wake ? [this.#options.signal, wake] : [this.#options.signal];
+        const state = () => {
+            if (this.#acknowledgedIds.has(eventId))
+                return true;
+            if (!this.#pending.some((item) => item.event.event_id === eventId))
+                return false;
+            if (this.#permanentFailure || signals.some((signal) => signal.aborted) || (this.#closed && !this.#pump))
+                return false;
+            return null;
+        };
+        const now = state();
+        if (now !== null)
+            return now;
+        this.#schedule(true);
+        return new Promise((resolve) => {
+            const check = () => {
+                const value = state();
+                if (value === null)
+                    return;
+                this.#roomWaiters.delete(check);
+                for (const signal of signals)
+                    signal.removeEventListener('abort', check);
+                resolve(value);
+            };
+            this.#roomWaiters.add(check);
+            for (const signal of signals)
+                signal.addEventListener('abort', check, { once: true });
+            check();
+        });
+    }
+    /** Send everything buffered now (does not close). Resolves when the attempt ends; never throws. */
+    async flush() {
+        this.#schedule(true);
+        while (this.#pump)
+            await this.#pump;
+    }
+    /**
+     * Stop accepting observations, deliver what is buffered (bounded retries), and
+     * return the evidence summary. Safe to call more than once.
+     */
+    async close() {
+        this.#closed = true;
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        while (this.#pump)
+            await this.#pump;
+        if (this.#pending.length > 0 && !this.#permanentFailure && !this.#options.signal.aborted) {
+            this.#failure = null;
+            this.#startPump();
+            while (this.#pump)
+                await this.#pump;
+        }
+        this.#notifyRoom();
+        return this.summary();
+    }
+    /**
+     * Send the drill's single `driver.started` event, whose signed record must name
+     * the event's own sequence: everything buffered is delivered first, later
+     * observations are held back, `build(sequence)` signs and commits the readiness
+     * record for exactly that sequence, and the event referencing it is sent alone
+     * as the next batch. Observations added meanwhile follow it. Resolves null once
+     * root acknowledged it, otherwise the code of why not (`build` may return one).
+     * A repeated call after acknowledgement resolves null. Never throws.
+     */
+    async submitReadiness(build) {
+        if (this.#readiness && this.#acknowledgedIds.has(this.#readiness.event_id))
+            return null;
+        if (this.#closed || this.#permanentFailure || this.#holding)
+            return this.summary().failure_code ?? 'native_observation_delivery_failed';
+        // Deliver what is buffered, then hold delivery with nothing pending.
+        for (let round = 0;; round++) {
+            await this.flush();
+            if (this.#permanentFailure)
+                return this.summary().failure_code ?? 'native_observation_delivery_failed';
+            this.#holding = true;
+            while (this.#pump)
+                await this.#pump;
+            if (this.#pending.length === 0)
+                break;
+            this.#holding = false;
+            if (round >= 4 || this.#options.signal.aborted)
+                return this.summary().failure_code ?? 'native_observation_delivery_failed';
+        }
+        try {
+            const sequence = this.#acked + 1;
+            // Reserved now: observations added while the record is built follow it, in sequence and in time.
+            const elapsed = this.#elapsed(Date.now());
+            this.#assigned = sequence;
+            const built = await build(sequence);
+            if (typeof built === 'string')
+                return built;
+            if (!NATIVE_ID.test(built.artifact_id) || !SHA256_HEX.test(built.sha256) || !Number.isSafeInteger(built.size) || built.size < 1) {
+                return 'native_readiness_invalid';
+            }
+            this.#records++;
+            this.#acceptedBytes += built.size;
+            const event = { event_id: nativeId('ev'), sequence, kind: 'driver.started', elapsed_ms: elapsed,
+                artifact_id: built.artifact_id, artifact_sha256: built.sha256 };
+            const batch = {
+                version: 1, assignment_id: this.#assignment.assignment_id, attempt_id: this.#assignment.attempt_id,
+                lease_epoch: this.#assignment.lease_epoch, state_generation: this.#assignment.state_generation,
+                batch_id: nativeId('ob'), previous_ack: this.#acked, events: [event],
+            };
+            try {
+                checkBatch(batch);
+            }
+            catch (error) {
+                return errorCode(error) ?? 'native_observation_batch_invalid';
+            }
+            this.#readiness = { batch, event_id: event.event_id };
+            return await this.#sendSingle(batch, event.event_id);
+        }
+        catch (error) {
+            return errorCode(error) ?? 'native_observation_delivery_failed';
+        }
+        finally {
+            // Unsent, the reservation is released: held observations move up to follow the acknowledgement.
+            if (!(this.#readiness && this.#acknowledgedIds.has(this.#readiness.event_id)))
+                this.#readiness = null;
+            this.#resequence(this.#acked);
+            this.#holding = false;
+            this.#schedule(true);
+        }
+    }
+    /**
+     * After close() delivered everything: send the drill's final driver outcome
+     * event as the next sequence, referencing an already committed record (the
+     * signed execution close), and wait for root to acknowledge it. Root admits a
+     * close only after this event is acknowledged, and no observation follows it.
+     * Resolves null once acknowledged, otherwise the code of why not. A repeated
+     * call re-sends the same batch. Never throws.
+     */
+    async submitOutcome(kind, record) {
+        while (this.#pump)
+            await this.#pump;
+        if (this.#outcome && this.#acknowledgedIds.has(this.#outcome.event_id))
+            return null;
+        if (!this.#closed || this.#pending.length > 0 || this.#permanentFailure || this.#failure !== null) {
+            return this.summary().failure_code ?? 'native_observation_delivery_failed';
+        }
+        if (!this.#outcome) {
+            if (!KINDS.has(kind) || record.observation_sequence !== this.#acked + 1 || !NATIVE_ID.test(record.artifact_id)
+                || !SHA256_HEX.test(record.sha256))
+                return 'native_close_invalid';
+            const event = {
+                event_id: nativeId('ev'), sequence: record.observation_sequence, kind, elapsed_ms: this.#elapsed(Date.now()),
+                artifact_id: record.artifact_id, artifact_sha256: record.sha256,
+            };
+            const batch = {
+                version: 1, assignment_id: this.#assignment.assignment_id, attempt_id: this.#assignment.attempt_id,
+                lease_epoch: this.#assignment.lease_epoch, state_generation: this.#assignment.state_generation,
+                batch_id: nativeId('ob'), previous_ack: this.#acked, events: [event],
+            };
+            try {
+                checkBatch(batch);
+            }
+            catch (error) {
+                return errorCode(error) ?? 'native_observation_batch_invalid';
+            }
+            this.#outcome = { batch, event_id: event.event_id };
+            this.#assigned = event.sequence;
+        }
+        return this.#sendSingle(this.#outcome.batch, this.#outcome.event_id);
+    }
+    /** Send one pinned single-event batch until root acknowledges exactly its event. Resolves null, or why not. */
+    async #sendSingle(batch, eventId) {
+        const sequence = batch.events[0].sequence;
+        const signal = this.#options.signal;
+        const retry = { signal, attempts: this.#attempts, onTransient: (error) => this.#options.onTransient?.(error) };
+        for (let stalled = 1; stalled <= 3; stalled++) {
+            let ack;
+            try {
+                ack = (await retryTransient(() => this.#options.controlPlane.submitObservations(batch, signal), retry))?.acknowledged;
+            }
+            catch (error) {
+                return errorCode(error) ?? 'native_observation_delivery_failed';
+            }
+            if (ack === sequence) {
+                this.#acked = sequence;
+                this.#acknowledgedIds.add(eventId);
+                return null;
+            }
+            // Anything but the unchanged cursor means root holds a different stream than this buffer: never guess.
+            if (ack !== batch.previous_ack) {
+                this.#inconsistent = true;
+                return 'native_observation_delivery_failed';
+            }
+            if (!await sleep(backoffMs(stalled, 500, 5_000), signal))
+                break;
+        }
+        return 'native_observation_delivery_failed';
+    }
+    dependencyCaptureUnavailable() {
+        this.#wholeDependencyCaptureLost++;
+        this.#omitted++;
+        const content = { type: 'dependency.capture_unavailable', provenance: 'customer_device', reason: 'capture_unavailable' };
+        const bytes = this.#encode('action.observed', content, null, false).byteLength;
+        const reserve = Math.min(this.#maxArtifact, STEP_RESULT_RESERVE_BYTES) + EVENT_OVERHEAD_BYTES;
+        if (!this.#fits(bytes + reserve) || this.#records >= EVIDENCE_MAX_RECORDS - CLOSE_RESERVE_RECORDS - STEP_RESERVE_RECORDS) {
+            this.#drop(bytes);
+            return;
+        }
+        this.add({ kind: 'action.observed', at_ms: Date.now(), content });
+    }
+    summary() {
+        const unacknowledged = this.#pending.length;
+        return {
+            last_sequence: this.#acked,
+            assigned_sequence: this.#assigned,
+            dependency_capture_records_complete: unacknowledged === 0 && this.#failure === null && this.#droppedObservations === 0
+                && this.#droppedBytes === 0 && this.#lostSequences === 0 && !this.#inconsistent
+                && this.#lostStepEvidence === 0 && this.#wholeDependencyCaptureLost === 0,
+            evidence_complete: unacknowledged === 0 && this.#failure === null && this.#droppedObservations === 0
+                && this.#droppedBytes === 0 && this.#omitted === 0 && this.#lostSequences === 0 && !this.#inconsistent
+                && this.#lostStepEvidence === 0,
+            dropped_observations: this.#droppedObservations,
+            dropped_bytes: this.#droppedBytes,
+            omitted_contents: this.#omitted,
+            unsupported_attachments: this.#unsupportedAttachments,
+            screenshots: this.#screenshots,
+            frames: this.#frames,
+            trace_segments: this.#traceSegments,
+            capture_unavailable: this.#captureUnavailable,
+            filtered_values: this.#filtered,
+            unacknowledged,
+            uploaded_bytes: this.#uploadedBytes,
+            failure_code: this.#failure === null ? null : (errorCode(this.#failure) ?? 'native_observation_delivery_failed'),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Encoding and accounting.
+    /** Exactly root's target-message document, or null when the reply cannot be one. */
+    #encodeTargetMessage(message) {
+        if (!message || message.schema !== 'firedrill.native-target-message.v2' || message.role !== 'assistant'
+            || typeof message.action_id !== 'string' || !UUID_PATTERN.test(message.action_id) || typeof message.content !== 'string')
+            return null;
+        // A string at depth 1 of the document; the filter keeps it within 16000 characters.
+        const filtered = filterEvidenceValue(message.content, 1);
+        this.#filtered += filtered.stats.removed + filtered.stats.rewritten;
+        const content = filtered.value;
+        if (typeof content !== 'string' || content.length < 1 || content.length > TARGET_MESSAGE_MAX_CHARS)
+            return null;
+        const bytes = Buffer.from(canonicalJson({ schema: message.schema, action_id: message.action_id, role: 'assistant', content }), 'utf8');
+        return bytes.byteLength <= this.#maxArtifact ? bytes : null;
+    }
+    /**
+     * Root's `firedrill.native-target-result.v2`: exactly the v1 fields plus
+     * `output_coverage`. The driver's result stays v1; only this artifact adds
+     * coverage, from what this encoder did and never from the output's own keys.
+     * The target's output is filtered like any evidence (root refuses
+     * credentials): `redacted` when the filter removed or rewrote anything,
+     * otherwise `complete`. An output that would not fit root's 64 KiB result is
+     * `omitted` with a null output, never cut into a different value. Outcome
+     * and completion are kept exactly as the driver recorded them.
+     */
+    #encodeTargetResult(result) {
+        const completion = result?.completion;
+        const messageFailure = result?.kind === 'participant_message' || result?.kind === 'scenario_message';
+        if (!result || result.schema !== 'firedrill.native-target-result.v1' || typeof result.action_id !== 'string'
+            || !UUID_PATTERN.test(result.action_id) || typeof result.input_digest !== 'string' || !/^[a-f0-9]{64}$/.test(result.input_digest)
+            || (result.kind !== 'task' && result.kind !== 'event' && !messageFailure) || !['completed', 'failed', 'cancelled'].includes(result.outcome)
+            || (messageFailure && (result.outcome !== 'failed' || typeof result.claim_key !== 'string' || !UUID_PATTERN.test(result.claim_key)))
+            || !completion || (result.kind === 'task' || messageFailure
+            ? completion.kind !== 'target_returned' || completion.delivery_id !== null
+            : (completion.kind !== 'delivery_acknowledged' && completion.kind !== 'correlated_result') || completion.delivery_id !== result.action_id)) {
+            return null;
+        }
+        const filtered = filterEvidenceValue(result.output ?? null, 1);
+        const changed = filtered.stats.removed + filtered.stats.rewritten;
+        this.#filtered += changed;
+        const document = (output, coverage) => Buffer.from(canonicalJson({
+            schema: messageFailure ? 'firedrill.native-target-result.v3' : 'firedrill.native-target-result.v2', action_id: result.action_id,
+            ...(messageFailure ? { claim_key: result.claim_key } : {}),
+            input_digest: result.input_digest, kind: result.kind, outcome: result.outcome, output, output_coverage: coverage,
+            completion: { kind: completion.kind, delivery_id: completion.delivery_id }
+        }), 'utf8');
+        // canonicalJson escapes like Python's ensure_ascii json.dumps, so these bytes are exactly the characters root's
+        // credential scan reads (its first 32,000). Root re-measures the parsed body with default separators (a space
+        // after each structural ',' and ':'), which stays under twice this size: within its 64 KiB bound.
+        const limit = Math.min(this.#maxArtifact, TARGET_RESULT_MAX_BYTES, TARGET_RESULT_SCAN_CHARS);
+        // Missing producer provenance cannot be upgraded to complete merely because
+        // this final filter found nothing else to remove. Preserve the original v1
+        // evidence contract so the server reports legacy_unknown.
+        const coverage = result.output_coverage;
+        if (!messageFailure && coverage !== 'complete' && coverage !== 'redacted' && coverage !== 'omitted') {
+            const legacy = Buffer.from(canonicalJson({ schema: result.schema, action_id: result.action_id,
+                input_digest: result.input_digest, kind: result.kind, outcome: result.outcome, output: filtered.value,
+                completion: { kind: completion.kind, delivery_id: completion.delivery_id } }), 'utf8');
+            return legacy.byteLength <= limit ? legacy : document(null, 'omitted');
+        }
+        let bytes = coverage === 'omitted' ? document(null, 'omitted')
+            : document(filtered.value, changed > 0 || coverage === 'redacted' ? 'redacted' : 'complete');
+        if (bytes.byteLength > limit)
+            bytes = document(null, 'omitted');
+        return bytes.byteLength <= limit ? bytes : null;
+    }
+    /**
+     * Root's `firedrill.native-trace-segment.v1`, exactly its eight fields, or
+     * null when the segment cannot be one. Times become drill-relative elapsed
+     * milliseconds on the evidence clock (the drill start), kept non-decreasing
+     * and within the segment's interval. Only closed values are written: ids,
+     * counts, times and the operation, outcome and coverage enums.
+     */
+    #encodeTraceSegment(segment) {
+        const events = segment?.events;
+        const terminal = segment?.terminal;
+        if (!segment || typeof segment.capture_id !== 'string' || !UUID_PATTERN.test(segment.capture_id)
+            || typeof segment.segment_index !== 'number' || !Number.isSafeInteger(segment.segment_index) || segment.segment_index < 0
+            || !Array.isArray(events) || events.length > TRACE_SEGMENT_MAX_EVENTS
+            || (terminal !== null && !(terminal?.coverage === 'complete' && terminal.reason === null)
+                && !(terminal?.coverage === 'partial' && TRACE_PARTIAL_REASONS.includes(terminal.reason))))
+            return null;
+        const relative = (atMs) => Math.min(MAX_SAFE, Math.max(0, Math.floor((typeof atMs === 'number' && Number.isFinite(atMs) ? atMs : Date.now()) - this.#options.startedAtMs)));
+        const start = relative(segment.start_at_ms);
+        let elapsed = start, sequence = 0;
+        const written = [];
+        for (const event of events) {
+            if (!event || typeof event.sequence !== 'number' || !Number.isSafeInteger(event.sequence) || event.sequence < 1
+                || (sequence > 0 && event.sequence !== sequence + 1)
+                || !TRACE_OPERATIONS.includes(event.operation) || !TRACE_OUTCOMES.includes(event.outcome))
+                return null;
+            sequence = event.sequence;
+            elapsed = Math.max(elapsed, relative(event.at_ms));
+            written.push({ sequence, elapsed_ms: elapsed, operation: event.operation, outcome: event.outcome });
+        }
+        const bytes = Buffer.from(canonicalJson({
+            schema: TRACE_SEGMENT_SCHEMA, capture_id: segment.capture_id, segment_index: segment.segment_index,
+            start_elapsed_ms: start, end_elapsed_ms: Math.max(elapsed, relative(segment.end_at_ms)),
+            capture: { consent: true, source: 'playwright', profile: TRACE_PROFILE }, events: written,
+            terminal: terminal === null ? null : { coverage: terminal.coverage, reason: terminal.reason },
+        }), 'utf8');
+        return bytes.byteLength <= this.#maxArtifact ? bytes : null;
+    }
+    /**
+     * `count` false measures only: the same bytes, without filtering or omission accounting.
+     * `sizedFor` is the attachment reference the content's value budget leaves room for
+     * (at least as many values as `attachment`), so the whole record stays within root's count.
+     */
+    #encodeDependencyExchange(exchange) {
+        try {
+            if (exchange.schema !== 'firedrill.native-dependency-exchange.v1'
+                || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(exchange.exchange_id)
+                || !/^[a-f0-9]{64}$/.test(exchange.binding_digest)
+                || typeof exchange.dependency_alias !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(exchange.dependency_alias)
+                || typeof exchange.service_key !== 'string' || exchange.service_key.length < 1 || exchange.service_key.length > 200
+                || typeof exchange.operation !== 'string' || !/^[A-Za-z0-9_.:/-]{1,128}$/.test(exchange.operation)
+                || !['http', 'mcp'].includes(exchange.protocol)
+                || !['returned', 'refused', 'pending', 'unknown'].includes(exchange.outcome)
+                || !['json', 'text', 'unavailable'].includes(exchange.response_format)
+                || ![exchange.request_coverage, exchange.response_coverage].every(value => ['captured', 'redacted', 'truncated', 'unsupported', 'unavailable'].includes(value))
+                || exchange.http_status !== null && (!Number.isInteger(exchange.http_status) || exchange.http_status < 100 || exchange.http_status > 599)
+                || exchange.is_error !== null && typeof exchange.is_error !== 'boolean'
+                || !Array.isArray(exchange.omission_reasons) || exchange.omission_reasons.length > 5
+                || exchange.omission_reasons.some(reason => !['privacy_filtered', 'size_limit', 'unsupported_content', 'no_response', 'capture_unavailable'].includes(reason)))
+                return null;
+            const request = filterEvidenceValue(exchange.request, 1, undefined, 32);
+            const response = filterEvidenceValue(exchange.response, 1, undefined, 32 + evidenceNodes(request.value));
+            if (!request.value || typeof request.value !== 'object' || Array.isArray(request.value))
+                return null;
+            const requestChanged = request.stats.removed + request.stats.rewritten > 0;
+            const responseChanged = response.stats.removed + response.stats.rewritten > 0;
+            const requestTruncated = (request.stats.truncated ?? 0) > 0;
+            const responseTruncated = (response.stats.truncated ?? 0) > 0;
+            const document = { schema: exchange.schema, exchange_id: exchange.exchange_id,
+                dependency_alias: exchange.dependency_alias, service_key: exchange.service_key, operation: exchange.operation,
+                binding_digest: exchange.binding_digest, protocol: exchange.protocol, outcome: exchange.outcome,
+                http_status: exchange.http_status, is_error: exchange.is_error, response_format: exchange.response_format,
+                request: request.value, response: response.value,
+                request_coverage: requestTruncated ? 'truncated' : requestChanged && exchange.request_coverage === 'captured' ? 'redacted' : exchange.request_coverage,
+                response_coverage: responseTruncated ? 'truncated' : responseChanged && exchange.response_coverage === 'captured' ? 'redacted' : exchange.response_coverage,
+                omission_reasons: [...new Set([...exchange.omission_reasons,
+                        ...(requestChanged || responseChanged ? ['privacy_filtered'] : []),
+                        ...(requestTruncated || responseTruncated ? ['size_limit'] : [])])] };
+            this.#filtered += request.stats.removed + request.stats.rewritten + response.stats.removed + response.stats.rewritten;
+            if (document.request_coverage !== 'captured' || document.response_coverage !== 'captured')
+                this.#omitted++;
+            let bytes = Buffer.from(canonicalJson(document), 'utf8');
+            if (bytes.byteLength > Math.min(131072, this.#maxArtifact)) {
+                this.#omitted++;
+                bytes = Buffer.from(canonicalJson({ ...document, request: {}, response: null, response_format: 'unavailable',
+                    request_coverage: 'truncated', response_coverage: 'unavailable',
+                    omission_reasons: [...new Set([...document.omission_reasons, 'size_limit'])] }), 'utf8');
+            }
+            return bytes.byteLength <= Math.min(131072, this.#maxArtifact) ? bytes : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    #encode(kind, content, attachment, count = true, sizedFor = attachment) {
+        const envelope = (body) => Buffer.from(canonicalJson({ version: ARTIFACT_VERSION, kind, content: body, attachment }), 'utf8');
+        let bytes;
+        try {
+            if (!content || typeof content !== 'object' || Array.isArray(content))
+                throw new Error('content');
+            // client-filtered-v1: content sits at depth 1 of the evidence document, beside the
+            // envelope's own values (the document, version and kind) and the attachment reference.
+            const outside = 3 + Math.max(evidenceNodes(attachment), evidenceNodes(sizedFor));
+            let filtered = filterEvidenceValue(content, 1, undefined, outside);
+            bytes = envelope(filtered.value);
+            // ASCII escaping can grow text up to six times; shorten strings before giving up on the record.
+            for (const cap of SHRINK_STRING_CHARS) {
+                if (bytes.byteLength <= this.#maxArtifact)
+                    break;
+                filtered = filterEvidenceValue(content, 1, cap, outside);
+                bytes = envelope(filtered.value);
+            }
+            if (count)
+                this.#filtered += filtered.stats.removed + filtered.stats.rewritten;
+        }
+        catch {
+            if (count)
+                this.#omitted++;
+            return envelope({ omitted: 'unserializable' });
+        }
+        if (bytes.byteLength > this.#maxArtifact) {
+            if (count) {
+                this.#omitted++;
+                this.#droppedBytes += bytes.byteLength;
+            }
+            return envelope({ omitted: 'capacity', bytes: bytes.byteLength });
+        }
+        return bytes;
+    }
+    #fits(size) {
+        return this.#buffered + size + EVENT_OVERHEAD_BYTES <= this.#maxBuffered
+            && this.#acceptedBytes + size <= Math.max(0, this.#maxTotal - CLOSE_RESERVE_BYTES);
+    }
+    #drop(bytes) {
+        this.#droppedObservations++;
+        this.#droppedBytes += bytes;
+    }
+    #elapsed(atMs) {
+        const now = Date.now();
+        const at = typeof atMs === 'number' && Number.isFinite(atMs) && atMs <= now + 60_000 ? atMs : now;
+        const elapsed = Math.min(MAX_SAFE, Math.max(0, Math.floor(at - this.#options.startedAtMs)));
+        this.#lastElapsed = Math.max(this.#lastElapsed, elapsed);
+        return this.#lastElapsed;
+    }
+    #release(bytes) {
+        this.#buffered = Math.max(0, this.#buffered - bytes);
+        this.#notifyRoom();
+    }
+    #notifyRoom() {
+        for (const check of [...this.#roomWaiters])
+            check();
+    }
+    // -------------------------------------------------------------------------
+    // Delivery.
+    #schedule(immediate) {
+        if (this.#permanentFailure || this.#pending.length === 0 || this.#holding)
+            return;
+        if (this.#pump) {
+            this.#rerun = true;
+            return;
+        }
+        if (immediate) {
+            if (this.#timer) {
+                clearTimeout(this.#timer);
+                this.#timer = null;
+            }
+            this.#startPump();
+            return;
+        }
+        if (!this.#timer) {
+            this.#timer = setTimeout(() => { this.#timer = null; this.#startPump(); }, this.#flushDelay);
+            this.#timer.unref?.();
+        }
+    }
+    #startPump() {
+        if (this.#pump || this.#pending.length === 0 || this.#permanentFailure || this.#holding)
+            return;
+        this.#pump = this.#deliver().finally(() => {
+            this.#pump = null;
+            if (this.#rerun && !this.#closed) {
+                this.#rerun = false;
+                this.#schedule(true);
+            }
+            this.#notifyRoom();
+        });
+    }
+    async #deliver() {
+        let stalled = 0;
+        while (this.#pending.length > 0 && !this.#options.signal.aborted) {
+            try {
+                const progressed = await this.#sendOne();
+                stalled = progressed ? 0 : stalled + 1;
+                if (stalled >= 3) {
+                    throw new CliError('native_observation_delivery_failed', 'Observations were not acknowledged after repeated submissions.');
+                }
+                if (!progressed && !await sleep(backoffMs(stalled, 500, 5_000), this.#options.signal))
+                    return;
+                this.#failure = null;
+            }
+            catch (error) {
+                this.#failure = error;
+                if (!isTransient(error)) {
+                    this.#permanentFailure = true;
+                    this.#notifyRoom();
+                    return;
+                }
+                // Retries exhausted on a transient condition: try again later unless closing.
+                if (!this.#closed && !this.#timer) {
+                    this.#timer = setTimeout(() => { this.#timer = null; this.#startPump(); }, 15_000);
+                    this.#timer.unref?.();
+                }
+                return;
+            }
+        }
+    }
+    /** Upload artifacts for the next slice, submit its batch and reconcile the acknowledgement. Returns whether the ack advanced. */
+    async #sendOne() {
+        const signal = this.#options.signal;
+        const retry = { signal, attempts: this.#attempts, onTransient: (error) => this.#options.onTransient?.(error) };
+        // Re-send the pinned batch unchanged while the acknowledgement has not moved.
+        const pinned = this.#batch && this.#batch.previous === this.#acked && this.#pending.length >= this.#batch.count
+            && this.#pending[0].event.sequence === this.#batch.first ? this.#batch : null;
+        if (!pinned)
+            this.#batch = null;
+        const slice = this.#pending.slice(0, pinned ? pinned.count : OBSERVATION_BATCH_MAX_EVENTS);
+        // Records are committed before the batch that references them. Events of a
+        // pinned batch were all committed before it was first sent.
+        for (const item of slice) {
+            const artifact = item.artifact;
+            if (!artifact.bytes)
+                continue;
+            const bytes = artifact.bytes;
+            let committed;
+            try {
+                const capture = artifact.screenshot;
+                committed = await retryTransient(() => this.#options.controlPlane.uploadArtifact(this.#assignment, capture
+                    ? { request_key: artifact.request_key, role: 'screenshot.observed', media_type: 'image/png', capture, sha256: artifact.sha256, bytes }
+                    : artifact.role
+                        ? { request_key: artifact.request_key, role: artifact.role, media_type: OBSERVATION_ARTIFACT_MEDIA_TYPE, sha256: artifact.sha256, bytes }
+                        : { request_key: artifact.request_key, role: item.event.kind, media_type: OBSERVATION_ARTIFACT_MEDIA_TYPE, sha256: artifact.sha256, bytes }, signal), retry);
+            }
+            catch (error) {
+                const code = errorCode(error);
+                if (code !== null && RECORD_RENEWABLE.has(code) && artifact.renewals < MAX_RECORD_RENEWALS) {
+                    // Root closed this record's upload window and asks for a new request key. Root counts
+                    // every declared record against its caps, so the re-declaration counts again here too.
+                    artifact.renewals++;
+                    artifact.request_key = randomUUID();
+                    this.#records++;
+                    this.#acceptedBytes += artifact.size;
+                    return true;
+                }
+                if (code !== null && (RECORD_REFUSALS.has(code) || RECORD_RENEWABLE.has(code))) {
+                    this.#refuseRecord(item);
+                    return true;
+                }
+                throw error;
+            }
+            if (typeof committed?.artifact_id !== 'string' || !NATIVE_ID.test(committed.artifact_id)) {
+                throw new CliError('native_observation_delivery_failed', 'The evidence record receipt was malformed. No evidence was regenerated.');
+            }
+            artifact.artifact_id = committed.artifact_id;
+            item.event.artifact_id = committed.artifact_id;
+            artifact.bytes = null;
+            this.#uploadedBytes += artifact.size;
+            this.#release(artifact.size);
+        }
+        const first = slice[0].event.sequence;
+        const last = slice[slice.length - 1].event.sequence;
+        if (first !== this.#acked + 1) {
+            // Invariant guard: pending must start right after the acknowledgement.
+            this.#resequence(this.#acked);
+            this.#inconsistent = true;
+            return true;
+        }
+        const previous = this.#acked;
+        if (!this.#batch)
+            this.#batch = { id: nativeId('ob'), first, count: slice.length, previous };
+        const batch = {
+            version: 1,
+            assignment_id: this.#assignment.assignment_id,
+            attempt_id: this.#assignment.attempt_id,
+            lease_epoch: this.#assignment.lease_epoch,
+            state_generation: this.#assignment.state_generation,
+            batch_id: this.#batch.id,
+            previous_ack: previous,
+            events: slice.map((item) => ({ ...item.event })),
+        };
+        checkBatch(batch);
+        const response = await retryTransient(() => this.#options.controlPlane.submitObservations(batch, signal), retry);
+        const ack = response?.acknowledged;
+        if (typeof ack !== 'number' || !Number.isSafeInteger(ack) || ack < 0) {
+            throw new CliError('native_observation_delivery_failed', 'The observation acknowledgement was malformed. No evidence was regenerated.');
+        }
+        return this.#reconcile(ack, last);
+    }
+    /** Adopt the cloud acknowledgement for a batch ending at `last`. Returns whether it advanced. */
+    #reconcile(ack, last) {
+        if (ack === this.#acked)
+            return false;
+        this.#batch = null;
+        if (ack < this.#acked) {
+            // The cloud holds less than it acknowledged before. Those events left memory
+            // and cannot be re-sent: report the loss and renumber only unaccepted events.
+            this.#lostSequences += this.#acked - ack;
+            this.#acked = ack;
+            this.#resequence(ack);
+            return true;
+        }
+        // Drop everything the cloud now holds. Events above `last` were never sent, so an
+        // acknowledgement beyond the batch is inconsistent: keep those events and continue after it.
+        const covered = Math.min(ack, last);
+        let released = 0;
+        while (this.#pending.length > 0 && this.#pending[0].event.sequence <= covered) {
+            const item = this.#pending.shift();
+            this.#acknowledgedIds.add(item.event.event_id);
+            if (item.keep)
+                this.#kept.set(item.event.event_id, { artifact_id: item.event.artifact_id, sha256: item.event.artifact_sha256 });
+            released += EVENT_OVERHEAD_BYTES + (item.artifact.bytes ? item.artifact.size : 0);
+        }
+        this.#acked = ack;
+        if (ack > last) {
+            this.#inconsistent = true;
+            this.#resequence(ack);
+        }
+        this.#release(released);
+        return true;
+    }
+    /**
+     * Root refused one record (privacy profile, capacity) or its upload window
+     * ended for good. Its event never left this process, so it is removed and
+     * the later never-sent events are renumbered; the loss is reported.
+     */
+    #refuseRecord(item) {
+        const index = this.#pending.indexOf(item);
+        if (index === -1)
+            return;
+        this.#pending.splice(index, 1);
+        this.#drop(item.artifact.size);
+        this.#release(EVENT_OVERHEAD_BYTES + (item.artifact.bytes ? item.artifact.size : 0));
+        item.artifact.bytes = null;
+        this.#resequence(this.#acked);
+    }
+    /** Renumber pending (never-accepted) events contiguously after `after`, keeping order and ids. */
+    #resequence(after) {
+        this.#batch = null;
+        let next = after;
+        for (const item of this.#pending)
+            item.event.sequence = ++next;
+        this.#assigned = next;
+    }
+}
+/** Local mirror of observation-batch.v1 shape and continuity rules (root validates authoritatively). */
+function checkBatch(batch) {
+    const invalid = () => new CliError('native_observation_batch_invalid', 'The observation batch was not sent: it does not match observation-batch.v1.');
+    const int = (value, min) => Number.isSafeInteger(value) && value >= min && value <= MAX_SAFE;
+    if (!NATIVE_ID.test(batch.assignment_id) || !NATIVE_ID.test(batch.attempt_id) || !NATIVE_ID.test(batch.batch_id)
+        || !int(batch.lease_epoch, 1) || !int(batch.state_generation, 1) || !int(batch.previous_ack, 0)
+        || batch.events.length < 1 || batch.events.length > OBSERVATION_BATCH_MAX_EVENTS)
+        throw invalid();
+    let expected = batch.previous_ack + 1;
+    let elapsed = -1;
+    const seen = new Set();
+    for (const event of batch.events) {
+        if (event.sequence !== expected || !int(event.sequence, 1) || !NATIVE_ID.test(event.event_id) || seen.has(event.event_id)
+            || !KINDS.has(event.kind) || !int(event.elapsed_ms, 0) || event.elapsed_ms < elapsed
+            || !NATIVE_ID.test(event.artifact_id) || !SHA256_HEX.test(event.artifact_sha256))
+            throw invalid();
+        seen.add(event.event_id);
+        elapsed = event.elapsed_ms;
+        expected++;
+    }
+}