@allocator-one/rcl 4.4.19

package/dist/dispatch/checkpoint-async-store.d.ts

@@ -0,0 +1,134 @@
+import { type FrozenCheckpointPlan } from './checkpoint.js';
+import { type SealedAsyncProof } from './checkpoint-async-context.js';
+import { type NativeTargetOwnership } from '../converge/target-ownership.js';
+import { type AsyncCall, type AsyncIntent, type AsyncPlan, type AsyncProof, type AsyncResult, type AsyncState } from './checkpoint-async.js';
+interface LocationInput {
+    commonDir: string;
+    namespace: string;
+    plan: FrozenCheckpointPlan;
+}
+export interface InitializeAsyncInput extends LocationInput {
+    ownership: NativeTargetOwnership;
+    calls: readonly AsyncCall[];
+    maxPhysicalCalls: number;
+    maxAttemptsPerCall: number;
+    expiresAtMs: number;
+}
+export interface AsyncDelegate {
+    version: 1;
+    commonDir: string;
+    namespace: string;
+    target: string;
+    checkpointPath: string;
+    planDigest: string;
+    callIndex: number;
+    token: string;
+}
+export interface AsyncWriter {
+    claim(prompts: {
+        systemPrompt: string;
+        userPrompt: string;
+    }, afterIntent?: (intent: AsyncIntent) => {
+        reviewBytes: string;
+    } | void): Promise<AsyncIntent | undefined>;
+    recordResult(attemptId: string, reviewBytes: string): Promise<'observed' | 'late'>;
+}
+interface OpinionCycle {
+    version: 1;
+    cycleId: string | null;
+}
+export interface AsyncPhaseSnapshot {
+    plan: AsyncPlan;
+    state: AsyncState;
+}
+export type CheckpointAsyncExecutionState = {
+    kind: 'phase';
+    phase: AsyncPhaseSnapshot;
+} | {
+    kind: 'unknown';
+    proof: SealedAsyncProof;
+};
+export interface AsyncLateRecord {
+    sequence: number;
+    previousDigest: string;
+    digest: string;
+    sealedProofSha256: string;
+    result: AsyncResult;
+}
+export interface AsyncLateFailure {
+    sequence: number;
+    kind: 'late_audit_failure';
+    callIndex: number;
+    attemptId: string;
+    digest: string;
+}
+/** Only initialization under live native ownership may create restricted per-call delegations. */
+export declare function initializeAsyncPhase(input: InitializeAsyncInput): Promise<{
+    delegates: readonly AsyncDelegate[];
+    plan: AsyncPlan;
+}>;
+/** Delegates cannot mutate native state, reviewer history, phase plan, cutoff or another call. */
+export declare function openAsyncDelegate(input: AsyncDelegate): Promise<AsyncWriter>;
+/** Parent-only cutoff is atomic with all delegated intent/retry admission. */
+export declare function sealAsyncPhase(input: LocationInput & {
+    ownership: NativeTargetOwnership;
+}): Promise<AsyncProof>;
+/** Structural local read; this does not authenticate capture matrix, producer or server authority. */
+export declare function readAsyncPhase(input: LocationInput): Promise<AsyncPhaseSnapshot>;
+/** Read the exact stored original-async evidence without creating or sealing state. */
+export declare function inspectCheckpointAsyncExecution(input: LocationInput): Promise<CheckpointAsyncExecutionState | undefined>;
+/** Read only terminal execution evidence; an open phase is deliberately not a proof. */
+export declare function readCheckpointAsyncExecution(input: LocationInput): Promise<SealedAsyncProof | undefined>;
+/**
+ * Seal a real phase or retain an explicit unknown outcome after a finalized,
+ * expired original launch. The unknown form never creates intents or claims
+ * that any captured async call did or did not dispatch.
+ */
+export declare function resolveFinalizedAsyncExecution(input: LocationInput & {
+    ownership: NativeTargetOwnership;
+    nowMs?: () => number;
+}): Promise<SealedAsyncProof | undefined>;
+export declare function readAsyncLateAudit(input: LocationInput): Promise<readonly AsyncLateRecord[]>;
+/** Record a bounded private diagnostic when a late result cannot be audited. */
+export declare function recordAsyncLateFailure(input: AsyncDelegate, attemptId: string): Promise<void>;
+/** Structural private diagnostic read; entries contain no provider error bytes. */
+export declare function readAsyncLateFailures(input: LocationInput): Promise<readonly AsyncLateFailure[]>;
+/** Authenticated restricted executor input, read only from the same journal and captured matrix. */
+export declare function openCapturedAsyncDelegate(input: AsyncDelegate): Promise<{
+    writer: AsyncWriter;
+    plan: {
+        version: 1;
+        context: {
+            runId: string;
+            target: string;
+            planDigest: string;
+            capturedInputsSha256: string;
+            launchSha256: string;
+            startedAtMs: number;
+            expiresAtMs: number;
+            reviewerReservedCalls: number;
+        };
+        calls: {
+            id: string;
+            assignment: string;
+            chunk: number;
+            chunkSha256: string;
+            provider: string;
+            model: string;
+            role: string;
+            systemPromptSha256: string;
+            userPromptSha256: string;
+        }[];
+        maxPhysicalCalls: number;
+        maxAttemptsPerCall: number;
+        expiresAtMs: number;
+    };
+    call: {
+        ref: AsyncCall;
+        assignment: import("../roles/types.js").ReviewAssignment;
+        prompt: import("../prepare/prompt-builder.js").BuiltPrompt;
+    };
+    timeoutMs: number;
+    opinionCycle: OpinionCycle;
+}>;
+export {};

package/dist/dispatch/checkpoint-async-store.js

@@ -0,0 +1,534 @@
+import { loadConvergeRunState } from '../converge/run-state.js';
+import { loadConvergeAttemptState } from '../converge/attempt-budget.js';
+import { assertReviewCyclePair } from '../converge/fresh-review.js';
+import { decodeOriginalLaunch } from './original-launch.js';
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, realpath, rename, rm, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { CheckpointJournal, checkpointPath, freezeCheckpointPlan } from './checkpoint.js';
+import { CAPTURED_INPUT_LIMITS } from './captured-inputs.js';
+import { asyncContextForBindings, assertCapturedAsyncPlan } from './checkpoint-async-context.js';
+import { decodeAsyncOutcomeUnknown, encodeAsyncOutcomeUnknown } from './checkpoint-async-unknown.js';
+import { withOwnedNativeOperation } from '../converge/target-ownership.js';
+import { syncNativeDirectory, withNativeLock } from '../converge/native-lock.js';
+import { readStable } from '../telemetry/recovery/files.js';
+import { writeExclusiveBytes } from '../evidence/original-run/journal.js';
+import { MAX_ARTIFACT_BYTES } from '../telemetry/envelope-validation.js';
+import { hasCheckpointIntentCapacity, MAX_ASYNC_PHASE_RECORDS } from './checkpoint-phase-limits.js';
+import { sha256Hex, stableStringify } from '../report/run-header.js';
+import { appendAsyncRecordToValidatedState, assertAsyncReviewBytes, asyncCallAdmission, asyncRefuse, decodeAsyncProof, encodeAsyncProof, freezeAsync, parseAsyncReview, validateAsyncNotDispatched, validateAsyncPlan, validateAsyncRecords, validateAsyncResult } from './checkpoint-async.js';
+const delegateSchema = z.object({ version: z.literal(1), commonDir: z.string().min(1), namespace: z.string().min(1), target: z.string().min(1),
+    checkpointPath: z.string().min(1), planDigest: z.string().regex(/^[a-f0-9]{64}$/), callIndex: z.number().int().nonnegative().safe(), token: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+const metadataSchema = z.object({ version: z.literal(1), plan: z.unknown(), grants: z.array(z.string().regex(/^[a-f0-9]{64}$/)).min(1).max(8),
+    opinionCycle: z.object({ version: z.literal(1), cycleId: z.string().uuid().nullable() }).strict().optional() }).strict();
+const filename = (index) => `${String(index).padStart(8, '0')}.json`;
+const isMissing = (error) => error?.code === 'ENOENT';
+const unknownFilename = 'async-outcome-unknown.json';
+async function privateDirectory(path) {
+    const stat = await lstat(path);
+    asyncRefuse(stat.isDirectory() && !stat.isSymbolicLink() && await realpath(path) === path &&
+        (stat.mode & 0o7777) === 0o700 && (!process.geteuid || stat.uid === process.geteuid()), 'unsafe_directory');
+}
+async function child(parent, name) {
+    await privateDirectory(parent);
+    const path = join(parent, name);
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    await privateDirectory(path);
+    await syncNativeDirectory(parent);
+    return path;
+}
+async function safeRead(path) {
+    await privateDirectory(dirname(path));
+    const before = await lstat(path);
+    asyncRefuse(before.isFile() && !before.isSymbolicLink() && (before.mode & 0o7777) === 0o600 && (!process.geteuid || before.uid === process.geteuid()), 'unsafe_file');
+    const { raw } = await readStable(path, MAX_ARTIFACT_BYTES), after = await lstat(path);
+    asyncRefuse(before.ino === after.ino && before.dev === after.dev && before.ctimeMs === after.ctimeMs && before.mtimeMs === after.mtimeMs && before.size === after.size, 'changing_file');
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+}
+async function resync(path, bytes) {
+    asyncRefuse(await safeRead(path) === bytes, 'conflict');
+    const before = await lstat(path), handle = await open(path, constants.O_RDWR | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        asyncRefuse(stat.ino === before.ino && stat.dev === before.dev && stat.size === before.size && stat.ctimeMs === before.ctimeMs, 'changing_file');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    asyncRefuse(await safeRead(path) === bytes, 'changing_file');
+    await syncNativeDirectory(dirname(path));
+}
+/** Stage, fsync, then link exclusively; readers never observe a partially written event. */
+async function publish(phase, destination, bytes) {
+    asyncRefuse(Buffer.byteLength(bytes, 'utf8') <= MAX_ARTIFACT_BYTES, 'too_large');
+    try {
+        await lstat(destination);
+        await resync(destination, bytes);
+        return;
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const staging = await child(phase, '.staging'), temporary = join(staging, `${randomUUID()}.pending`);
+    await writeExclusiveBytes(temporary, Buffer.from(bytes));
+    try {
+        await link(temporary, destination);
+        await syncNativeDirectory(dirname(destination));
+    }
+    finally {
+        await unlink(temporary);
+        await syncNativeDirectory(staging);
+    }
+    await resync(destination, bytes);
+}
+function snapshotLocation(input) {
+    const plan = freezeCheckpointPlan(input.plan);
+    asyncRefuse(stableStringify(plan) === stableStringify(input.plan), 'plan');
+    const commonDir = resolve(input.commonDir), path = checkpointPath(commonDir, plan.target, input.namespace);
+    return { commonDir, namespace: input.namespace, checkpointPath: path, phasePath: join(path, 'async'), plan };
+}
+async function contextAt(location) {
+    asyncRefuse(await realpath(location.commonDir) === location.commonDir, 'alias');
+    const journal = await CheckpointJournal.openRead(location.checkpointPath, location.plan), bindings = await journal.readBindings();
+    const bound = asyncContextForBindings(location.plan, bindings);
+    asyncRefuse(bound.context.runId === location.namespace, 'parent_binding');
+    return { journal, ...bound };
+}
+async function metadataAt(location) {
+    const bytes = await safeRead(join(location.phasePath, 'phase.json'));
+    let raw;
+    try {
+        raw = JSON.parse(bytes);
+    }
+    catch {
+        throw new Error('checkpoint_async_invalid_metadata');
+    }
+    const parsed = metadataSchema.safeParse(raw);
+    asyncRefuse(parsed.success && stableStringify(parsed.data) + '\n' === bytes, 'invalid_metadata');
+    const plan = validateAsyncPlan(parsed.data.plan), { context, captured } = await contextAt(location);
+    assertCapturedAsyncPlan(plan, captured);
+    asyncRefuse(stableStringify(plan.context) === stableStringify(context) && parsed.data.grants.length === plan.calls.length && new Set(parsed.data.grants).size === plan.calls.length, 'parent_binding');
+    for (const call of plan.calls)
+        asyncRefuse(location.plan.chunks.find(chunk => chunk.index === call.chunk)?.digest === call.chunkSha256, 'call');
+    return { version: 1, plan, grants: parsed.data.grants, ...(parsed.data.opinionCycle ? { opinionCycle: parsed.data.opinionCycle } : {}) };
+}
+async function recordsAt(location, plan) {
+    const directory = join(location.phasePath, 'events');
+    await privateDirectory(directory);
+    const names = (await readdir(directory)).sort();
+    asyncRefuse(names.length <= MAX_ASYNC_PHASE_RECORDS, 'too_many_records');
+    let total = 0;
+    const records = [];
+    for (const [index, name] of names.entries()) {
+        asyncRefuse(name === filename(index + 1), 'sequence');
+        const bytes = await safeRead(join(directory, name));
+        total += Buffer.byteLength(bytes);
+        asyncRefuse(total <= MAX_ARTIFACT_BYTES, 'too_large');
+        let record;
+        try {
+            record = JSON.parse(bytes);
+        }
+        catch {
+            throw new Error('checkpoint_async_invalid_record');
+        }
+        asyncRefuse(stableStringify(record) + '\n' === bytes, 'noncanonical_record');
+        records.push(record);
+    }
+    return validateAsyncRecords(records, plan);
+}
+async function locked(location, work) {
+    await privateDirectory(location.phasePath);
+    return withNativeLock(join(location.phasePath, 'locks'), 'phase', async () => {
+        const metadata = await metadataAt(location), state = await recordsAt(location, metadata.plan);
+        return work(metadata, state);
+    });
+}
+async function append(location, state, plan, event) {
+    const record = appendAsyncRecordToValidatedState(state, event, plan);
+    await publish(location.phasePath, join(location.phasePath, 'events', filename(record.sequence)), stableStringify(record) + '\n');
+    return record;
+}
+function logicalCutoffMs(plan, state) {
+    let cutoffMs = Math.max(Date.now(), plan.context.startedAtMs);
+    for (const intent of state.intents)
+        cutoffMs = Math.max(cutoffMs, intent.startedAtMs);
+    for (const outcome of state.outcomes)
+        cutoffMs = Math.max(cutoffMs, outcome.finishedAtMs);
+    for (const result of state.notDispatched)
+        cutoffMs = Math.max(cutoffMs, result.finishedAtMs);
+    asyncRefuse(Number.isSafeInteger(cutoffMs), 'clock');
+    return cutoffMs;
+}
+/** Freeze derivative opinion routing while the original native claim is still owned. */
+async function originalOpinionCycle(location, journal) {
+    const native = await loadConvergeRunState(location.commonDir, location.plan.target);
+    const attempts = await loadConvergeAttemptState(location.commonDir, location.plan.target);
+    if (native || attempts) {
+        const launch = decodeOriginalLaunch((await journal.readBindings()).launch);
+        const claim = launch.originalNativeClaim, pending = native?.lastLaunch;
+        asyncRefuse(native && attempts && pending?.status === 'pending' &&
+            pending.attempt === claim.attempt && pending.round === claim.round &&
+            pending.headSha === location.plan.headSha && attempts.attemptsUsed === claim.attempt &&
+            attempts.attempts.some(attempt => attempt.attempt === claim.attempt) &&
+            (pending.runId === undefined || pending.runId === location.namespace), 'native_claim');
+        await assertReviewCyclePair(location.commonDir, location.plan.target, native.cycle);
+    }
+    // Owned local/legacy initialization has no cycle. Never infer a cycle later.
+    return { version: 1, cycleId: native?.cycle?.id ?? null };
+}
+/** Only initialization under live native ownership may create restricted per-call delegations. */
+export function initializeAsyncPhase(input) {
+    const location = snapshotLocation(input), calls = structuredClone(input.calls), { ownership, maxPhysicalCalls, maxAttemptsPerCall, expiresAtMs } = input;
+    return withOwnedNativeOperation(ownership, location.commonDir, location.plan.target, async () => {
+        const { journal, context, captured } = await contextAt(location), state = await journal.read();
+        asyncRefuse(!state.finalized && !state.records.some(row => row.type === 'intent'), 'initialization_closed');
+        try {
+            await lstat(join(location.checkpointPath, 'terminal-report'));
+            throw new Error('checkpoint_async_initialization_closed');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const plan = validateAsyncPlan({ version: 1, context, calls, maxPhysicalCalls, maxAttemptsPerCall, expiresAtMs });
+        assertCapturedAsyncPlan(plan, captured);
+        asyncRefuse(Date.now() >= context.startedAtMs && Date.now() < plan.expiresAtMs, 'deadline');
+        for (const call of plan.calls)
+            asyncRefuse(location.plan.chunks.find(chunk => chunk.index === call.chunk)?.digest === call.chunkSha256, 'call');
+        try {
+            await lstat(location.phasePath);
+            throw new Error('checkpoint_async_already_initialized');
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const opinionCycle = await originalOpinionCycle(location, journal);
+        const bindingDigest = privateDelegateDigest({ plan, opinionCycle });
+        const tokens = calls.map(() => randomBytes(32).toString('hex'));
+        const metadata = { version: 1, plan, grants: tokens.map(token => delegateGrant(token, bindingDigest)), opinionCycle };
+        // The visible async directory is the initialization commit point. Preparing
+        // elsewhere cannot make main finalization depend on missing metadata.
+        const staging = await child(location.checkpointPath, '.staging');
+        const prepared = await child(staging, `async-${randomUUID()}.pending`), identity = await lstat(prepared);
+        let published = false;
+        try {
+            await child(prepared, 'events');
+            await child(prepared, 'late');
+            await child(prepared, 'failures');
+            await publish(prepared, join(prepared, 'phase.json'), stableStringify(metadata) + '\n');
+            await syncNativeDirectory(prepared);
+            // Native ownership serializes initializers. Never replace an existing
+            // phase, including an empty, malformed or symlinked path.
+            try {
+                await lstat(location.phasePath);
+                throw new Error('checkpoint_async_already_initialized');
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+            await rename(prepared, location.phasePath);
+            published = true;
+            await syncNativeDirectory(location.checkpointPath);
+            await syncNativeDirectory(staging);
+        }
+        finally {
+            if (!published) {
+                const current = await lstat(prepared);
+                asyncRefuse(current.ino === identity.ino && current.dev === identity.dev && !current.isSymbolicLink(), 'changing_file');
+                await rm(prepared, { recursive: true });
+                await syncNativeDirectory(staging);
+            }
+        }
+        const delegates = tokens.map((token, callIndex) => ({ version: 1, commonDir: location.commonDir, namespace: location.namespace,
+            target: location.plan.target, checkpointPath: location.checkpointPath, planDigest: bindingDigest, callIndex, token }));
+        return freezeAsync({ delegates, plan });
+    });
+}
+async function delegatedLocation(input) {
+    const parsed = delegateSchema.safeParse(input);
+    asyncRefuse(parsed.success, 'invalid_delegate');
+    const delegate = freezeAsync(parsed.data);
+    asyncRefuse(resolve(delegate.commonDir) === delegate.commonDir && checkpointPath(delegate.commonDir, delegate.target, delegate.namespace) === delegate.checkpointPath, 'delegate_path');
+    const journal = await CheckpointJournal.inspectRead(delegate.checkpointPath);
+    asyncRefuse(journal.getPlan().target === delegate.target, 'delegate_target');
+    return { location: snapshotLocation({ commonDir: delegate.commonDir, namespace: delegate.namespace, plan: journal.getPlan() }), delegate };
+}
+function privateDelegateDigest(metadata) {
+    asyncRefuse(metadata.opinionCycle, 'opinion_cycle_missing');
+    return sha256Hex(stableStringify({ plan: metadata.plan, opinionCycle: metadata.opinionCycle }));
+}
+function delegateGrant(token, bindingDigest) {
+    return createHmac('sha256', Buffer.from(token, 'hex')).update(bindingDigest).digest('hex');
+}
+function authorize(metadata, delegate) {
+    const expected = metadata.grants[delegate.callIndex], bindingDigest = privateDelegateDigest(metadata);
+    asyncRefuse(expected && bindingDigest === delegate.planDigest &&
+        timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(delegateGrant(delegate.token, bindingDigest), 'hex')), 'invalid_delegate');
+}
+/** Delegates cannot mutate native state, reviewer history, phase plan, cutoff or another call. */
+export async function openAsyncDelegate(input) {
+    const snapshot = structuredClone(input), { location, delegate } = await delegatedLocation(snapshot);
+    await locked(location, async (metadata) => authorize(metadata, delegate));
+    return Object.freeze({
+        claim: async (prompts, afterIntent) => {
+            const system = prompts.systemPrompt, user = prompts.userPrompt;
+            return locked(location, async (metadata, state) => {
+                authorize(metadata, delegate);
+                const call = metadata.plan.calls[delegate.callIndex];
+                asyncRefuse([system, user].every(value => typeof value === 'string' && Buffer.byteLength(value, 'utf8') <= CAPTURED_INPUT_LIMITS.bytes &&
+                    Buffer.from(value, 'utf8').toString('utf8') === value) && sha256Hex(system) === call.systemPromptSha256 && sha256Hex(user) === call.userPromptSha256, 'prompt_mismatch');
+                const now = Date.now();
+                asyncRefuse(Number.isSafeInteger(now) && now >= metadata.plan.context.startedAtMs, 'clock');
+                const admission = asyncCallAdmission(state, delegate.callIndex);
+                const { last, outcome, declined } = admission;
+                if (state.cutoffMs !== undefined || now >= metadata.plan.expiresAtMs || admission.billedTotal >= metadata.plan.maxPhysicalCalls ||
+                    admission.billedForCall >= metadata.plan.maxAttemptsPerCall ||
+                    !hasCheckpointIntentCapacity(state.records.length, state.uncertain.length, state.notDispatched.length, MAX_ASYNC_PHASE_RECORDS) ||
+                    last && !declined && (!outcome || parseAsyncReview(outcome.reviewBytes, call).status === 'success'))
+                    return undefined;
+                const intent = { callIndex: delegate.callIndex, attemptId: `async-${randomUUID()}`, startedAtMs: now };
+                const intentRecord = await append(location, state, metadata.plan, { type: 'intent', intent });
+                // A retained executor may synchronously start dispatch after fsync while
+                // this same cutoff lock is held. Never await provider work under the lock.
+                const frozen = freezeAsync(intent), undispatched = afterIntent?.(frozen);
+                if (undispatched) {
+                    const claimed = validateAsyncRecords([...state.records, intentRecord], metadata.plan);
+                    const result = validateAsyncNotDispatched({ callIndex: delegate.callIndex, attemptId: intent.attemptId,
+                        reviewBytes: undispatched.reviewBytes, reviewSha256: sha256Hex(undispatched.reviewBytes),
+                        finishedAtMs: Date.now() }, metadata.plan, claimed.intents);
+                    await append(location, claimed, metadata.plan, { type: 'not-dispatched', result });
+                }
+                return frozen;
+            });
+        },
+        recordResult: async (attemptId, reviewBytes) => {
+            assertAsyncReviewBytes(reviewBytes);
+            const finishedAtMs = Date.now();
+            return locked(location, async (metadata, state) => {
+                authorize(metadata, delegate);
+                const existing = state.outcomes.find(row => row.attemptId === attemptId);
+                const result = validateAsyncResult({ callIndex: delegate.callIndex, attemptId, reviewBytes, reviewSha256: sha256Hex(reviewBytes), possiblyBilled: true,
+                    finishedAtMs: existing?.finishedAtMs ?? finishedAtMs }, metadata.plan, state.intents);
+                if (existing) {
+                    asyncRefuse(stableStringify(existing) === stableStringify(result), 'result_conflict');
+                    const record = state.records.find(row => row.event.type === 'result' && row.event.result.attemptId === attemptId);
+                    await resync(join(location.phasePath, 'events', filename(record.sequence)), stableStringify(record) + '\n');
+                    return 'observed';
+                }
+                if (state.cutoffMs === undefined) {
+                    await append(location, state, metadata.plan, { type: 'result', result });
+                    return 'observed';
+                }
+                await appendLate(location, encodeAsyncProof(metadata.plan, state.records), result);
+                return 'late';
+            });
+        },
+    });
+}
+/** Parent-only cutoff is atomic with all delegated intent/retry admission. */
+export function sealAsyncPhase(input) {
+    const location = snapshotLocation(input);
+    return withOwnedNativeOperation(input.ownership, location.commonDir, location.plan.target, () => locked(location, async (metadata, state) => {
+        let records = state.records;
+        if (state.cutoffMs === undefined)
+            records = [...records, await append(location, state, metadata.plan, { type: 'seal', cutoffMs: logicalCutoffMs(metadata.plan, state) })];
+        for (const record of records)
+            await resync(join(location.phasePath, 'events', filename(record.sequence)), stableStringify(record) + '\n');
+        return decodeAsyncProof(encodeAsyncProof(metadata.plan, records).bytes, metadata.plan.context);
+    }));
+}
+/** Structural local read; this does not authenticate capture matrix, producer or server authority. */
+export function readAsyncPhase(input) {
+    const location = snapshotLocation(input);
+    return locked(location, async (metadata, state) => freezeAsync({ plan: metadata.plan, state }));
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+/** Read the exact stored original-async evidence without creating or sealing state. */
+export async function inspectCheckpointAsyncExecution(input) {
+    const location = snapshotLocation(input);
+    const [hasPhase, hasUnknown] = await Promise.all([
+        pathExists(location.phasePath), pathExists(join(location.checkpointPath, unknownFilename)),
+    ]);
+    asyncRefuse(!(hasPhase && hasUnknown), 'conflicting_execution_evidence');
+    if (hasPhase) {
+        return freezeAsync({ kind: 'phase', phase: await readAsyncPhase(input) });
+    }
+    if (!hasUnknown)
+        return undefined;
+    const { journal, context, captured } = await contextAt(location), root = await journal.exportProof();
+    const bytes = await safeRead(join(location.checkpointPath, unknownFilename));
+    const unknown = decodeAsyncOutcomeUnknown(bytes, root, context, captured);
+    return freezeAsync({ kind: 'unknown',
+        proof: freezeAsync({ bytes: unknown.bytes, digest: unknown.digest }) });
+}
+/** Read only terminal execution evidence; an open phase is deliberately not a proof. */
+export async function readCheckpointAsyncExecution(input) {
+    const stored = await inspectCheckpointAsyncExecution(input);
+    if (stored === undefined)
+        return undefined;
+    if (stored.kind === 'unknown')
+        return stored.proof;
+    const proof = encodeAsyncProof(stored.phase.plan, stored.phase.state.records);
+    return freezeAsync({ bytes: proof.bytes, digest: proof.digest });
+}
+/**
+ * Seal a real phase or retain an explicit unknown outcome after a finalized,
+ * expired original launch. The unknown form never creates intents or claims
+ * that any captured async call did or did not dispatch.
+ */
+export async function resolveFinalizedAsyncExecution(input) {
+    const location = snapshotLocation(input);
+    return withOwnedNativeOperation(input.ownership, location.commonDir, location.plan.target, async (ownership) => {
+        const { journal, context, captured } = await contextAt(location);
+        const [hasPhase, hasUnknown] = await Promise.all([
+            pathExists(location.phasePath), pathExists(join(location.checkpointPath, unknownFilename)),
+        ]);
+        asyncRefuse(!(hasPhase && hasUnknown), 'conflicting_execution_evidence');
+        if (captured.async === undefined) {
+            asyncRefuse(!hasPhase && !hasUnknown, 'unexpected_execution_evidence');
+            return undefined;
+        }
+        const state = await journal.read();
+        asyncRefuse(state.finalized, 'unknown_unfinalized_checkpoint');
+        if (hasPhase)
+            return sealAsyncPhase({ ...input, ownership });
+        const now = (input.nowMs ?? Date.now)();
+        asyncRefuse(Number.isSafeInteger(now) && now >= context.expiresAtMs, 'unknown_live_launch');
+        if (hasUnknown)
+            return readCheckpointAsyncExecution(input);
+        asyncRefuse(!await pathExists(join(location.checkpointPath, 'terminal-report')), 'unknown_terminal_report');
+        const root = await journal.exportProof(), unknown = encodeAsyncOutcomeUnknown(root, context, captured);
+        await publish(location.checkpointPath, join(location.checkpointPath, unknownFilename), unknown.bytes);
+        const readback = await readCheckpointAsyncExecution(input);
+        asyncRefuse(readback?.bytes === unknown.bytes && readback.digest === unknown.digest, 'unknown_readback');
+        return readback;
+    });
+}
+async function lateAt(location, proof) {
+    const directory = join(location.phasePath, 'late');
+    await privateDirectory(directory);
+    const names = (await readdir(directory)).sort();
+    asyncRefuse(names.length <= proof.state.uncertain.length, 'late_cap');
+    const rows = [];
+    const seen = new Set();
+    let previous = proof.digest, total = 0;
+    for (const [index, name] of names.entries()) {
+        asyncRefuse(name === filename(index + 1), 'late_sequence');
+        const bytes = await safeRead(join(directory, name));
+        total += Buffer.byteLength(bytes);
+        asyncRefuse(total <= MAX_ARTIFACT_BYTES, 'late_too_large');
+        let row;
+        try {
+            row = JSON.parse(bytes);
+        }
+        catch {
+            throw new Error('checkpoint_async_invalid_late');
+        }
+        asyncRefuse(row && typeof row === 'object' && Object.keys(row).sort().join(',') === 'digest,previousDigest,result,sealedProofSha256,sequence', 'invalid_late');
+        const { digest, ...unsigned } = row;
+        asyncRefuse(stableStringify(row) + '\n' === bytes && row.sequence === index + 1 && row.previousDigest === previous && row.sealedProofSha256 === proof.digest && sha256Hex(stableStringify(unsigned)) === digest, 'invalid_late');
+        validateAsyncResult(row.result, proof.plan, proof.state.uncertain);
+        asyncRefuse(!seen.has(row.result.attemptId), 'duplicate_late');
+        seen.add(row.result.attemptId);
+        rows.push(row);
+        previous = digest;
+    }
+    return freezeAsync(rows);
+}
+async function appendLate(location, proof, result) {
+    const rows = await lateAt(location, proof), existing = rows.find(row => row.result.attemptId === result.attemptId);
+    if (existing) {
+        asyncRefuse(stableStringify(existing.result) === stableStringify({ ...result, finishedAtMs: existing.result.finishedAtMs }), 'late_conflict');
+        await resync(join(location.phasePath, 'late', filename(existing.sequence)), stableStringify(existing) + '\n');
+        return;
+    }
+    validateAsyncResult(result, proof.plan, proof.state.uncertain);
+    const unsigned = { sequence: rows.length + 1, previousDigest: rows.at(-1)?.digest ?? proof.digest, sealedProofSha256: proof.digest, result };
+    const record = { ...unsigned, digest: sha256Hex(stableStringify(unsigned)) };
+    asyncRefuse(Buffer.byteLength(stableStringify([...rows, record])) <= MAX_ARTIFACT_BYTES, 'late_too_large');
+    await publish(location.phasePath, join(location.phasePath, 'late', filename(record.sequence)), stableStringify(record) + '\n');
+}
+export function readAsyncLateAudit(input) {
+    const location = snapshotLocation(input);
+    return locked(location, (metadata, state) => lateAt(location, encodeAsyncProof(metadata.plan, state.records)));
+}
+async function lateFailuresAt(location, plan, state) {
+    const directory = join(location.phasePath, 'failures');
+    await privateDirectory(directory);
+    const names = (await readdir(directory)).sort();
+    asyncRefuse(names.length <= plan.maxPhysicalCalls, 'late_failure_cap');
+    const rows = [];
+    for (const name of names) {
+        const bytes = await safeRead(join(directory, name));
+        let row;
+        try {
+            row = JSON.parse(bytes);
+        }
+        catch {
+            throw new Error('checkpoint_async_invalid_late_failure');
+        }
+        asyncRefuse(row && typeof row === 'object' && Object.keys(row).sort().join(',') === 'attemptId,callIndex,digest,kind,sequence', 'invalid_late_failure');
+        const candidate = row, { digest, ...unsigned } = candidate;
+        const intent = state.intents[candidate.sequence - 1];
+        asyncRefuse(stableStringify(candidate) + '\n' === bytes && candidate.sequence >= 1 && name === filename(candidate.sequence) &&
+            candidate.kind === 'late_audit_failure' && intent?.attemptId === candidate.attemptId && intent.callIndex === candidate.callIndex &&
+            sha256Hex(stableStringify(unsigned)) === digest, 'invalid_late_failure');
+        rows.push(candidate);
+    }
+    return freezeAsync(rows);
+}
+/** Record a bounded private diagnostic when a late result cannot be audited. */
+export async function recordAsyncLateFailure(input, attemptId) {
+    const { location, delegate } = await delegatedLocation(structuredClone(input));
+    await locked(location, async (metadata, state) => {
+        authorize(metadata, delegate);
+        const intentIndex = state.intents.findIndex(value => value.attemptId === attemptId), intent = state.intents[intentIndex];
+        asyncRefuse(intent?.callIndex === delegate.callIndex, 'late_failure_intent');
+        // Bind the marker path to the immutable physical-intent position. Exact
+        // replay reaches one file directly instead of rereading every prior marker.
+        const sequence = intentIndex + 1;
+        const unsigned = { sequence, kind: 'late_audit_failure', callIndex: delegate.callIndex, attemptId };
+        const record = { ...unsigned, digest: sha256Hex(stableStringify(unsigned)) };
+        await publish(location.phasePath, join(location.phasePath, 'failures', filename(sequence)), stableStringify(record) + '\n');
+    });
+}
+/** Structural private diagnostic read; entries contain no provider error bytes. */
+export function readAsyncLateFailures(input) {
+    const location = snapshotLocation(input);
+    return locked(location, (metadata, state) => lateFailuresAt(location, metadata.plan, state));
+}
+/** Authenticated restricted executor input, read only from the same journal and captured matrix. */
+export async function openCapturedAsyncDelegate(input) {
+    const { location, delegate } = await delegatedLocation(structuredClone(input));
+    const execution = await locked(location, async (metadata) => {
+        authorize(metadata, delegate);
+        const { captured } = await contextAt(location);
+        // Historical phases remain readable as evidence, but cannot guess routing authority.
+        asyncRefuse(metadata.opinionCycle, 'opinion_cycle_missing');
+        return freezeAsync({ plan: metadata.plan, call: captured.async.calls[delegate.callIndex], timeoutMs: captured.async.timeoutMs, opinionCycle: metadata.opinionCycle });
+    });
+    return { ...execution, writer: await openAsyncDelegate(delegate) };
+}
+//# sourceMappingURL=checkpoint-async-store.js.map