@allocator-one/rcl 4.4.19

package/dist/telemetry/recovery/types.d.ts

@@ -0,0 +1,100 @@
+import type { RunTarget } from '../../report/run-header.js';
+export interface RecoveryFinding {
+    ref: string;
+    identity: string | null;
+    model: string | null;
+    note: string | null;
+}
+export interface RepositoryProof {
+    worktree: string;
+    repo: string;
+    reference_path?: string;
+    reference_sha256?: string;
+}
+export interface RecoverySource {
+    sha256: string;
+    bytes: number;
+    paths: string[];
+    mtime: string;
+    format: 'modern' | 'legacy' | 'unknown';
+    run_id: string | null;
+    repo: string | null;
+    target: RunTarget | null;
+    repository_proofs: RepositoryProof[];
+    state: 'ready' | 'no_refutations' | 'synthetic' | 'unbound' | 'unsafe' | 'conflict' | 'unsupported';
+    reason?: string;
+    refutations: RecoveryFinding[];
+}
+export interface DiscoveryIssue {
+    path: string;
+    reason: string;
+}
+export interface RecoveryInventory {
+    kind: 'rcl-refutation-inventory';
+    version: 1;
+    created_at: string;
+    coverage: {
+        roots: string[];
+        worktrees: RepositoryProof[];
+        git_common_dirs: string[];
+        references: string[];
+        issues: DiscoveryIssue[];
+        excluded_sha256: string[];
+        outbox: Array<{
+            path: string;
+            sha256: string;
+            run_id: string | null;
+            report_sha256: string | null;
+            report_path: string;
+        }>;
+    };
+    reports: RecoverySource[];
+}
+export interface DiscoveryOptions {
+    roots?: string[];
+    excludeSha256?: string[];
+    progress?: (message: string) => void;
+}
+export interface RecoveryPlan {
+    sha256: string;
+    run_id: string | null;
+    action: 'import_history' | 'upload_and_recover' | 'recover' | 'already_present' | 'skip' | 'conflict' | 'unavailable';
+    reason?: string;
+    delivery?: {
+        report_sha256: string;
+        report_bytes: number;
+    };
+    server?: {
+        exists: boolean;
+        provenance: 'live' | 'backfill' | null;
+        artifact_stored: boolean;
+        report_sha256: string | null;
+        report_bytes: number | null;
+    };
+    findings: Array<RecoveryFinding & {
+        state: 'missing' | 'already_present' | 'original_note_absent' | 'conflict';
+    }>;
+}
+export interface RecoveryManifest {
+    kind: 'rcl-refutation-recovery';
+    version: 1;
+    created_at: string;
+    destination: {
+        base_url: string;
+        org_id: string;
+    };
+    inventory: RecoveryInventory;
+    plans: RecoveryPlan[];
+}
+export interface RecoveryOutcome {
+    kind: 'rcl-refutation-recovery-outcome';
+    version: 1;
+    created_at: string;
+    destination: RecoveryManifest['destination'];
+    writes: {
+        runs: number;
+        artifacts: number;
+    };
+    server_recovery_run_ids: string[];
+    reports: RecoveryPlan[];
+}

package/dist/telemetry/recovery/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/telemetry/recovery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/telemetry/recovery/types.ts"],"names":[],"mappings":""}

package/dist/telemetry/recovery-request-budget.d.ts

@@ -0,0 +1,39 @@
+/** Time is injectable for quota tests; production always uses monotonic elapsed time. */
+export interface RecoveryClock {
+    now: () => number;
+    wallTime: () => number;
+    sleep: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+declare const permitBrand: unique symbol;
+export interface RecoveryWritePermit {
+    readonly [permitBrand]: true;
+}
+export interface RecoveryRateLimit {
+    retryAfterMs?: number;
+    retryable: boolean;
+    reason: 'rate_limited' | 'invalid_retry_after' | 'rate_limit_allowance_exhausted';
+}
+/** One authenticated recovery operation; transport permits confer no evidence authority. */
+export declare class RecoveryRequestBudget {
+    private readonly onWait?;
+    private readonly clock;
+    private starts;
+    private readonly reserved;
+    private blockedUntil;
+    private blocked;
+    private rateLimitWaits;
+    private lastNow;
+    constructor(clock?: RecoveryClock, onWait?: ((milliseconds: number) => void) | undefined);
+    private now;
+    private admit;
+    /** Admission precedes creation of the per-request network timeout. */
+    acquire(signal?: AbortSignal): Promise<void>;
+    /** Reserve before final source validation; proof reads cannot consume this slot. */
+    reserveWrite(): Promise<RecoveryWritePermit>;
+    /** No scheduling wait is permitted between successful source proof and this write. */
+    consumeWrite(permit: RecoveryWritePermit): void;
+    releaseWrite(permit: RecoveryWritePermit): void;
+    /** Only actual 429s consume the finite contention allowance; normal pacing is unbounded. */
+    rateLimited(retryAfter: string | null, responseDate: string | null): RecoveryRateLimit;
+}
+export {};

package/dist/telemetry/recovery-request-budget.js

@@ -0,0 +1,102 @@
+import { setTimeout as delay } from 'node:timers/promises';
+const systemClock = {
+    now: () => performance.now(), wallTime: () => Date.now(),
+    sleep: (milliseconds, signal) => delay(milliseconds, undefined, { signal }),
+};
+const WINDOW_MS = 60_000;
+// Leave room in the unchanged 300/minute token bucket for other callers.
+const REQUESTS_PER_WINDOW = 240;
+const MAX_RATE_LIMIT_WAITS = 3;
+const permitBrand = Symbol('recovery write permit');
+/** One authenticated recovery operation; transport permits confer no evidence authority. */
+export class RecoveryRequestBudget {
+    onWait;
+    clock;
+    starts = [];
+    reserved = new Set();
+    blockedUntil = 0;
+    blocked;
+    rateLimitWaits = 0;
+    lastNow = -Infinity;
+    constructor(clock = systemClock, onWait) {
+        this.onWait = onWait;
+        this.clock = { ...clock };
+    }
+    now() {
+        const now = this.clock.now();
+        if (!Number.isFinite(now) || now < this.lastNow)
+            throw new Error('recovery_clock_invalid');
+        this.lastNow = now;
+        this.starts = this.starts.filter(start => now - start < WINDOW_MS);
+        return now;
+    }
+    async admit(reserve, signal) {
+        for (;;) {
+            signal?.throwIfAborted();
+            if (this.blocked)
+                throw new Error(this.blocked);
+            const now = this.now();
+            const quotaWait = this.starts.length + this.reserved.size >= REQUESTS_PER_WINDOW
+                ? Math.max(1, (this.starts[0] ?? now) + WINDOW_MS - now) : 0;
+            const wait = Math.max(0, this.blockedUntil - now, quotaWait);
+            if (!wait) {
+                if (!reserve) {
+                    this.starts.push(now);
+                    return;
+                }
+                const permit = Object.freeze({ [permitBrand]: true });
+                this.reserved.add(permit);
+                return permit;
+            }
+            this.onWait?.(wait);
+            await this.clock.sleep(wait, signal);
+        }
+    }
+    /** Admission precedes creation of the per-request network timeout. */
+    async acquire(signal) {
+        await this.admit(false, signal);
+    }
+    /** Reserve before final source validation; proof reads cannot consume this slot. */
+    async reserveWrite() {
+        return (await this.admit(true));
+    }
+    /** No scheduling wait is permitted between successful source proof and this write. */
+    consumeWrite(permit) {
+        const now = this.now();
+        if (!this.reserved.has(permit))
+            throw new Error('recovery_write_permit_invalid');
+        if (this.blocked || now < this.blockedUntil)
+            throw new Error(this.blocked ?? 'recovery_write_rate_limited');
+        this.reserved.delete(permit);
+        this.starts.push(now);
+    }
+    releaseWrite(permit) { this.reserved.delete(permit); }
+    /** Only actual 429s consume the finite contention allowance; normal pacing is unbounded. */
+    rateLimited(retryAfter, responseDate) {
+        let milliseconds;
+        if (retryAfter !== null && /^\d+$/.test(retryAfter)) {
+            const seconds = Number(retryAfter);
+            if (Number.isSafeInteger(seconds))
+                milliseconds = seconds * 1000;
+        }
+        else if (retryAfter !== null && /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(retryAfter)) {
+            const parsedDate = Date.parse(retryAfter);
+            const date = Number.isFinite(parsedDate) && new Date(parsedDate).toUTCString() === retryAfter ? parsedDate : NaN;
+            const serverTime = responseDate === null ? NaN : Date.parse(responseDate);
+            milliseconds = date - (Number.isFinite(serverTime) ? serverTime : this.clock.wallTime());
+        }
+        if (milliseconds === undefined || !Number.isFinite(milliseconds) || milliseconds < 0 || milliseconds > WINDOW_MS) {
+            this.blocked = 'recovery_retry_after_invalid';
+            return { retryable: false, reason: 'invalid_retry_after' };
+        }
+        // Even Retry-After: 0 must not spin against a competing caller's bucket.
+        milliseconds = Math.max(1000, milliseconds);
+        if (++this.rateLimitWaits > MAX_RATE_LIMIT_WAITS) {
+            this.blocked = 'recovery_rate_limit_allowance_exhausted';
+            return { retryable: false, reason: 'rate_limit_allowance_exhausted', retryAfterMs: milliseconds };
+        }
+        this.blockedUntil = Math.max(this.blockedUntil, this.now() + milliseconds);
+        return { retryable: true, reason: 'rate_limited', retryAfterMs: milliseconds };
+    }
+}
+//# sourceMappingURL=recovery-request-budget.js.map

package/dist/telemetry/recovery-request-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-request-budget.js","sourceRoot":"","sources":["../../src/telemetry/recovery-request-budget.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/report-consistency.d.ts

@@ -0,0 +1,11 @@
+import type { ReviewResult } from '../consensus/types.js';
+import { type RunEnvelope } from './envelope.js';
+/**
+ * A verified-consensus envelope must agree with the immutable report bytes.
+ * The wire builder can supply `none` for a missing label, so labels are
+ * checked before projecting the report. This check is shared by direct
+ * delivery and queued replay.
+ */
+export declare function verifiedConsensusReportProblem(report: unknown, envelope: RunEnvelope, reportJson: string, directResult?: ReviewResult, options?: {
+    allowUnlabeledStrictFallback?: boolean;
+}): string | undefined;

package/dist/telemetry/report-consistency.js

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { buildRunEnvelope } from './envelope.js';
+const GATING_REASONS = new Set(['consensus', 'critical', 'verified', 'none']);
+/** Before 3.6.0, verifier outages could retain a `verified` gate. */
+function allowsUnavailableVerified(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match)
+        return false;
+    const parts = match.slice(1).map(Number);
+    if (!parts.every(Number.isSafeInteger))
+        return false;
+    const [major, minor] = parts;
+    return major >= 1 && (major < 3 || (major === 3 && minor < 6));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Compare JSON values, ignoring properties that JSON serialization omits. */
+function sameJson(left, right) {
+    return isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+}
+/**
+ * A verified-consensus envelope must agree with the immutable report bytes.
+ * The wire builder can supply `none` for a missing label, so labels are
+ * checked before projecting the report. This check is shared by direct
+ * delivery and queued replay.
+ */
+export function verifiedConsensusReportProblem(report, envelope, reportJson, directResult, options = {}) {
+    if (!isRecord(report) || !isRecord(report['run']) || !isRecord(report['run']['gating']) ||
+        report['run']['id'] !== envelope.run.id || report['run']['rcl_version'] !== envelope.run.rcl_version ||
+        report['run']['gating']['mode'] !== 'verified-consensus') {
+        return 'report_json does not match the queued verified-consensus run';
+    }
+    if (!Array.isArray(report['findings']) ||
+        (report['belowThresholdFindings'] !== undefined && !Array.isArray(report['belowThresholdFindings']))) {
+        return 'report_json findings are missing or malformed';
+    }
+    const groups = [
+        ['findings', report['findings']],
+        ['belowThresholdFindings', report['belowThresholdFindings'] ?? []],
+    ];
+    const sourceFindings = groups.flatMap(([, findings]) => findings);
+    // `envelope` telemetry omits rows entirely, even when the report has findings.
+    const hasWireFindings = envelope.findings.length > 0;
+    if (hasWireFindings && sourceFindings.length !== envelope.findings.length)
+        return 'report_json finding count differs from the queued envelope';
+    let hasVerification = false;
+    let wireIndex = 0;
+    for (const [group, findings] of groups) {
+        for (const [index, finding] of findings.entries()) {
+            if (!isRecord(finding))
+                return `${group}.${index}.gating.reason missing or invalid in report_json`;
+            const gating = finding['gating'];
+            const strictFallback = options.allowUnlabeledStrictFallback === true && gating === undefined;
+            if (!strictFallback && (!isRecord(gating) || !GATING_REASONS.has(gating['reason']))) {
+                return `${group}.${index}.gating.reason missing or invalid in report_json`;
+            }
+            const verification = strictFallback ? undefined : gating['verification'];
+            if (verification !== undefined)
+                hasVerification = true;
+            const verdict = isRecord(verification) ? verification['verdict'] : undefined;
+            const reason = strictFallback ? 'none' : gating['reason'];
+            const coherent = reason === 'verified'
+                ? verdict === 'confirmed' || verdict === 'unrefuted' ||
+                    (verdict === 'unavailable' && allowsUnavailableVerified(envelope.run.rcl_version))
+                : reason === 'none'
+                    ? verification === undefined || verdict === 'refuted' || verdict === 'insufficient_evidence' || verdict === 'unavailable'
+                    : verification === undefined;
+            if (!coherent) {
+                return `${group}.${index}.gating.verification.verdict contradicts the ${reason} gating reason in report_json`;
+            }
+            const wire = envelope.findings[wireIndex++];
+            if (hasWireFindings && (wire?.gating_reason !== reason || wire?.below_threshold !== (group === 'belowThresholdFindings'))) {
+                return `${group}.${index}.gating.reason differs from the queued envelope`;
+            }
+        }
+    }
+    if (hasVerification && (!isRecord(report['stats']) || report['stats']['verification'] == null)) {
+        return 'stats.verification missing for annotated candidates in report_json';
+    }
+    // Envelope-level telemetry intentionally has no finding rows. A direct
+    // delivery still has the completed result, so bind both original groups
+    // before projecting the report into that empty wire view.
+    if (directResult !== undefined) {
+        for (const group of ['findings', 'belowThresholdFindings']) {
+            if (!sameJson(report[group] ?? [], directResult[group] ?? [])) {
+                return `report_json ${group} differ from the completed result`;
+            }
+        }
+    }
+    // No reviewer rows are present at envelope level. Otherwise the optional
+    // parse-failure text setting is not encoded on the wire, so either legal
+    // projection may match the queued calls.
+    const level = envelope.findings.length > 0 || envelope.calls.length > 0 ? 'findings' : 'envelope';
+    try {
+        if (!Array.isArray(report['reviews']) || !isRecord(report['stats']))
+            return 'report_json reviews or stats are malformed';
+        const projected = [false, true].map(parseFailures => buildRunEnvelope(report, { report_json: reportJson }, { level, delivery: envelope.delivery, parseFailures,
+            ...(envelope.reviewer_recovery === undefined ? {} : { reviewerRecovery: envelope.reviewer_recovery }) }));
+        for (const field of ['run', 'stats', 'findings', 'calls']) {
+            if (!projected.some(candidate => sameJson(candidate[field], envelope[field]))) {
+                return `report_json ${field} differ from the queued envelope`;
+            }
+        }
+    }
+    catch {
+        return 'report_json cannot be projected into the queued envelope';
+    }
+    return undefined;
+}
+//# sourceMappingURL=report-consistency.js.map

package/dist/telemetry/report-consistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-consistency.js","sourceRoot":"","sources":["../../src/telemetry/report-consistency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAoB,MAAM,eAAe,CAAC;AAEnE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9E,qEAAqE;AACrE,SAAS,yBAAyB,CAAC,OAAe;IAChD,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAC7B,OAAO,KAAM,IAAI,CAAC,IAAI,CAAC,KAAM,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,KAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,8EAA8E;AAC9E,SAAS,QAAQ,CAAC,IAAa,EAAE,KAAc;IAC7C,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAe,EAAE,QAAqB,EAAE,UAAkB,EAAE,YAA2B,EACvF,UAAsD,EAAE;IAExD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;QACnF,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,WAAW;QACpG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,oBAAoB,EAAE,CAAC;QAC7D,OAAO,8DAA8D,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC,MAAM,CAAC,wBAAwB,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;QACzG,OAAO,+CAA+C,CAAC;IACzD,CAAC;IACD,MAAM,MAAM,GAAG;QACb,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAChC,CAAC,wBAAwB,EAAE,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,CAAC;KAC1D,CAAC;IACX,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;IAClE,+EAA+E;IAC/E,MAAM,eAAe,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACrD,IAAI,eAAe,IAAI,cAAc,CAAC,MAAM,KAAK,QAAQ,CAAC,QAAQ,CAAC,MAAM;QAAE,OAAO,4DAA4D,CAAC;IAC/I,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAClD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,OAAO,GAAG,KAAK,IAAI,KAAK,kDAAkD,CAAC;YACnG,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACjC,MAAM,cAAc,GAAG,OAAO,CAAC,4BAA4B,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,CAAC;YAC7F,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAW,CAAC,CAAC,EAAE,CAAC;gBAC9F,OAAO,GAAG,KAAK,IAAI,KAAK,kDAAkD,CAAC;YAC7E,CAAC;YACD,MAAM,YAAY,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,MAAkC,CAAC,cAAc,CAAC,CAAC;YACtG,IAAI,YAAY,KAAK,SAAS;gBAAE,eAAe,GAAG,IAAI,CAAC;YACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC7E,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,MAAkC,CAAC,QAAQ,CAAC,CAAC;YACvF,MAAM,QAAQ,GAAG,MAAM,KAAK,UAAU;gBACpC,CAAC,CAAC,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,WAAW;oBAClD,CAAC,OAAO,KAAK,aAAa,IAAI,yBAAyB,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;gBACpF,CAAC,CAAC,MAAM,KAAK,MAAM;oBACjB,CAAC,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,uBAAuB,IAAI,OAAO,KAAK,aAAa;oBACzH,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC;YACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,GAAG,KAAK,IAAI,KAAK,gDAAgD,MAAM,+BAA+B,CAAC;YAChH,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;YAC5C,IAAI,eAAe,IAAI,CAAC,IAAI,EAAE,aAAa,KAAK,MAAM,IAAI,IAAI,EAAE,eAAe,KAAK,CAAC,KAAK,KAAK,wBAAwB,CAAC,CAAC,EAAE,CAAC;gBAC1H,OAAO,GAAG,KAAK,IAAI,KAAK,iDAAiD,CAAC;YAC5E,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,eAAe,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC;QAC/F,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IAED,uEAAuE;IACvE,wEAAwE;IACxE,0DAA0D;IAC1D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,wBAAwB,CAAU,EAAE,CAAC;YACpE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC9D,OAAO,eAAe,KAAK,mCAAmC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,yEAAyE;IACzE,yCAAyC;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;IAClG,IAAI,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAAE,OAAO,4CAA4C,CAAC;QACzH,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,gBAAgB,CAAC,MAAiC,EACrG,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa;YAC9E,GAAG,CAAC,QAAQ,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9G,KAAK,MAAM,KAAK,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAU,EAAE,CAAC;YACnE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9E,OAAO,eAAe,KAAK,kCAAkC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,0DAA0D,CAAC;IACpE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/telemetry/reviewer-delivery.d.ts

@@ -0,0 +1,39 @@
+import { type ReviewerArtifact } from '../report/reviewer-artifact.js';
+import type { ArtifactBytes, RunEnvelope } from './envelope.js';
+import type { FlushOptions, FlushSummary } from './outbox.js';
+import { HarnessSink } from './sink.js';
+export declare const REVIEWER_OUTBOX_DIR = "reviewer-outbox";
+export interface ReviewerDeliveryInput {
+    sink: HarnessSink;
+    envelope: RunEnvelope;
+    artifacts: ArtifactBytes;
+    artifact: ReviewerArtifact;
+}
+export interface ReviewerDeliveryOptions {
+    deadlineMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Immutable private delivery copies. No token or token fingerprint is retained.
+ * Current server authorization, not this local directory, determines ownership.
+ * Unknown-run restart refuses: a replacement principal cannot recreate a run.
+ */
+export declare class ReviewerDeliveryQueue {
+    readonly root: string;
+    constructor(dataDir: string);
+    /** Retain exact already-validated local bytes; never admit deserialized brands. */
+    retain(input: ReviewerDeliveryInput): Promise<void>;
+    /** Initial delivery is the only path allowed to create an as-yet unknown run. */
+    deliver(input: ReviewerDeliveryInput, options?: ReviewerDeliveryOptions): Promise<void>;
+    /** Explicit/current-credential retry; no provider calls or changed run identity. */
+    flush(sink: HarnessSink, options?: FlushOptions, authorizeTransfer?: () => Promise<void>): Promise<FlushSummary>;
+    /** Local retention only; never a server acknowledgment. */
+    isRetained(runId: string): Promise<boolean>;
+    private snapshot;
+    private lock;
+    private save;
+    private load;
+    private ack;
+    private acknowledged;
+    private transfer;
+}