@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/frontend-typed-event-store.js

@@ -0,0 +1,438 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { appendJsonlLineAtomic, writeJsonlAtomic, } from "../../infrastructure/harness/atomic-write.js";
+/**
+ * M1 typed event store (AC-001).
+ *
+ * A pure, side-effect-free event store for the frontend DAG refactor. The store
+ * distinguishes three phases — `staged`, `quarantined`, `committed` — and
+ * partitions records by `attemptId` so that sibling attempts cannot observe
+ * each other's facts. `committed` is the single terminal phase.
+ *
+ * Phase transition rules (enforced by the helpers below, not by loose field
+ * assignment):
+ *   staged        --adopt success--> committed (terminal)
+ *   staged        --validation fail--> quarantined
+ *   quarantined   --(no transition)-->  (never visible to committed readers)
+ *
+ * This module only defines data + transitions. Persistence is delegated to the
+ * existing atomic-write boundary (`appendJsonlLineAtomic` / `writeJsonlAtomic`),
+ * and hashing reuses `sha256OfCanonicalJson` from the task-contract boundary so
+ * the fact identity is deterministic and reusable.
+ */
+export const TYPED_EVENT_SCHEMA_VERSION = 1;
+export const TYPED_EVENT_FACT_KINDS = [
+    "terminal-commit",
+    "disconnect",
+    "duplicate-tool-call",
+    "length-before-terminal",
+    "reasoning-timeout",
+    "provider-ended-without-terminal",
+    "read-only-fact-channel",
+];
+/**
+ * M2 shadow-only fact catalog (AC-001 shadow dual write). These facts are
+ * audit-only observations derived from the authoritative text/JSON outputs of
+ * the frontend-contract-pi / frontend-scout-pi / frontend-plan-pi nodes. They
+ * are never branch-control signals and never participate in writer admission.
+ *
+ * Kept deliberately separate from `TYPED_EVENT_FACT_KINDS`: widening the shadow
+ * catalog must never widen the provider capability matrix (which stays frozen
+ * at its seven kinds). `target-surface` is shared by the scout and plan
+ * origins, so the union of the two catalogs is 12 unique kinds.
+ */
+export const SHADOW_FACT_KINDS = [
+    "requirement",
+    "constraint",
+    "open-question",
+    "split-proposal",
+    "target-surface",
+    "design-evidence",
+    "component-choice",
+    "state-flow",
+    "data-flow",
+    "mock-api",
+    "design-deviation",
+    "dependency",
+];
+/**
+ * M5 review terminal fact catalog (AC-001). These two committed typed tools are
+ * the authoritative terminal verdict of `frontend-review-pi`. They are kept in
+ * a dedicated catalog so widening the review terminal surface never widens the
+ * frozen 7/7/12 provider/shadow/event catalogs.
+ */
+export const REVIEW_TERMINAL_FACT_KINDS = [
+    "approve_review",
+    "request_review_changes",
+];
+/**
+ * M8 design terminal fact catalog. `frontend-design-review-pi` emits its
+ * authoritative terminal verdict through the committed typed tools
+ * `approve_design` / `request_design_changes` instead of the legacy first-line
+ * `VERDICT: pass|request-revision` text protocol. Kept in a dedicated catalog
+ * so widening the design terminal surface never widens the frozen provider /
+ * shadow / event / review catalogs.
+ */
+export const DESIGN_TERMINAL_FACT_KINDS = [
+    "approve_design",
+    "request_design_changes",
+];
+/**
+ * A+B: frontend-contract-pi incremental typed fact catalog. The contract node
+ * submits requirement/constraint/evidence-expectation/handoff-intent/
+ * open-question/split-proposal facts plus the `contract-finalized` terminal
+ * fact carrying the terminal disposition (`ready | ready-with-assumptions |
+ * blocked` + optional `blockingOwner`). Kept in a dedicated catalog so
+ * widening the contract surface never widens the frozen provider / shadow /
+ * event / review / design catalogs.
+ */
+export const CONTRACT_FACT_KINDS = [
+    "requirement",
+    "constraint",
+    "evidence-expectation",
+    "handoff-intent",
+    "open-question",
+    "split-proposal",
+    "contract-finalized",
+];
+export const CONTRACT_TERMINAL_FACT_KINDS = ["contract-finalized"];
+export const contractDispositionSchema = z.enum([
+    "ready",
+    "ready-with-assumptions",
+    "blocked",
+]);
+export const contractBlockingOwnerSchema = z.enum([
+    "blocked-human",
+    "blocked-external",
+]);
+/**
+ * A+B: `frontend-plan-pi` terminal fact. The plan node now records its decision
+ * ledger through seven incremental `record_*` tools and closes with exactly one
+ * `finalize_plan` terminal fact.
+ */
+export const PLAN_TERMINAL_FACT_KINDS = ["finalize_plan"];
+/**
+ * A+B (AC-009): typed issue category shared by review and design change
+ * requests. The five-value enum replaces free-form issueCategory strings.
+ */
+export const FRONTEND_ISSUE_CATEGORY_VALUES = [
+    "implementation-mismatch",
+    "approved-design-defect",
+    "target-surface-defect",
+    "contract-requirement-gap",
+    "unknown",
+];
+export const frontendIssueCategorySchema = z.enum(FRONTEND_ISSUE_CATEGORY_VALUES);
+/** Runtime control facts committed at frontend shape boundaries. Kept outside
+ * the frozen provider/shadow catalogs so adding control authority cannot widen
+ * either legacy capability surface. */
+export const FRONTEND_SHAPE_FACT_KINDS = ["frontend-shape"];
+export const typedEventPhaseSchema = z.enum([
+    "staged",
+    "quarantined",
+    "committed",
+]);
+const ALL_TYPED_EVENT_FACT_KIND_VALUES = [
+    ...new Set([
+        ...TYPED_EVENT_FACT_KINDS,
+        ...SHADOW_FACT_KINDS,
+        ...REVIEW_TERMINAL_FACT_KINDS,
+        ...DESIGN_TERMINAL_FACT_KINDS,
+        ...FRONTEND_SHAPE_FACT_KINDS,
+        ...CONTRACT_FACT_KINDS,
+        ...PLAN_TERMINAL_FACT_KINDS,
+    ]),
+];
+export const typedEventFactKindSchema = z.enum(ALL_TYPED_EVENT_FACT_KIND_VALUES);
+/** A typed event fact is a `kind`-discriminated record. The schema stays
+ * permissive beyond `kind` (arbitrary JSON-safe payload) so provider/model
+ * shadow facts can carry their own fields, but `kind` is always validated. */
+export const typedEventFactSchema = z
+    .record(z.unknown())
+    .superRefine((value, ctx) => {
+    if (!typedEventFactKindSchema.safeParse(value.kind).success) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "fact.kind must be a valid typed event fact kind",
+            path: ["kind"],
+        });
+    }
+});
+/** A single review finding shared by both typed terminal verdicts. Mirrors the
+ * legacy JSON review finding shape so typed↔JSON equivalence stays total. */
+export const reviewFindingSchema = z
+    .object({
+    severity: z.enum(["Critical", "Important", "Minor", "Info"]),
+    file: z.string().min(1).optional(),
+    line: z.number().int().positive().optional(),
+    issue: z.string().min(1),
+    requiredChange: z.string().min(1).optional(),
+})
+    .strict();
+/** `approve_review` terminal fact payload. Approval may carry informational
+ * findings (Minor/Info) but never Critical/Important — the same rule the legacy
+ * JSON verdict applies to `verdict: "pass"`. */
+export const approveReviewFactSchema = z
+    .object({
+    kind: z.literal("approve_review"),
+    verdict: z.literal("approve_review"),
+    findings: z.array(reviewFindingSchema),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.findings.some((finding) => finding.severity === "Critical" ||
+        finding.severity === "Important")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "approve_review cannot carry Critical or Important findings",
+            path: ["findings"],
+        });
+    }
+});
+/** `request_review_changes` terminal fact payload. Requires a typed issue
+ * category, at least one evidence ref, and at least one finding. */
+export const requestReviewChangesFactSchema = z
+    .object({
+    kind: z.literal("request_review_changes"),
+    verdict: z.literal("request_review_changes"),
+    issueCategory: frontendIssueCategorySchema,
+    evidenceRefs: z.array(z.string().min(1)).min(1),
+    findings: z.array(reviewFindingSchema).min(1),
+})
+    .strict();
+/** `approve_design` terminal fact payload. Approval may carry informational
+ * findings (Minor/Info) but never Critical/Important — the same rule the legacy
+ * text protocol applies to `VERDICT: pass`. */
+export const approveDesignFactSchema = z
+    .object({
+    kind: z.literal("approve_design"),
+    verdict: z.literal("approve_design"),
+    findings: z.array(reviewFindingSchema),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.findings.some((finding) => finding.severity === "Critical" ||
+        finding.severity === "Important")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "approve_design cannot carry Critical or Important findings",
+            path: ["findings"],
+        });
+    }
+});
+/** `request_design_changes` terminal fact payload. Requires a typed issue
+ * category, at least one evidence ref, and at least one finding. */
+export const requestDesignChangesFactSchema = z
+    .object({
+    kind: z.literal("request_design_changes"),
+    verdict: z.literal("request_design_changes"),
+    issueCategory: frontendIssueCategorySchema,
+    evidenceRefs: z.array(z.string().min(1)).min(1),
+    findings: z.array(reviewFindingSchema).min(1),
+})
+    .strict();
+export const typedEventRecordSchema = z
+    .object({
+    schemaVersion: z.literal(TYPED_EVENT_SCHEMA_VERSION),
+    eventId: z.string().min(1),
+    requestId: z.string().min(1),
+    attemptId: z.string().min(1),
+    phase: typedEventPhaseSchema,
+    payloadSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    fact: typedEventFactSchema,
+    revision: z.number().int().nonnegative(),
+    recordedAt: z.string().min(1),
+    quarantineReason: z.string().min(1).optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.phase === "quarantined" && !value.quarantineReason) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "quarantined event requires a quarantineReason",
+            path: ["quarantineReason"],
+        });
+    }
+});
+/** A fact kind that closes the attempt. Only one such fact may commit per
+ * attempt; the transaction layer's terminal conflict gate depends on this. */
+export function isTerminalFactKind(kind) {
+    return (kind === "terminal-commit" ||
+        kind === "provider-ended-without-terminal" ||
+        REVIEW_TERMINAL_FACT_KINDS.includes(kind) ||
+        DESIGN_TERMINAL_FACT_KINDS.includes(kind) ||
+        PLAN_TERMINAL_FACT_KINDS.includes(kind) ||
+        CONTRACT_TERMINAL_FACT_KINDS.includes(kind));
+}
+/** Deterministic fact identity shared by staging and adoption. */
+export function typedEventPayloadSha256(fact) {
+    return sha256OfCanonicalJson(fact);
+}
+export class TypedEventStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TypedEventStoreError";
+        this.code = code;
+    }
+}
+export function createTypedEventStore(initial) {
+    return {
+        revision: initial?.revision ?? 0,
+        records: [...(initial?.records ?? [])],
+    };
+}
+function replaceRecord(store, eventId, next) {
+    const index = store.records.findIndex((record) => record.eventId === eventId);
+    if (index < 0) {
+        throw new TypedEventStoreError("EVENT_NOT_FOUND", `no typed event with eventId ${eventId}`);
+    }
+    store.records[index] = next;
+}
+/** Stage a fact as `staged` without any commit decision. */
+export function stageTypedEventRecord(store, input) {
+    const existing = store.records.find((record) => record.eventId === input.eventId);
+    if (existing) {
+        throw new TypedEventStoreError("EVENT_ID_CONFLICT", `eventId ${input.eventId} already exists with phase ${existing.phase}`);
+    }
+    const record = typedEventRecordSchema.parse({
+        schemaVersion: TYPED_EVENT_SCHEMA_VERSION,
+        eventId: input.eventId,
+        requestId: input.requestId,
+        attemptId: input.attemptId,
+        phase: "staged",
+        payloadSha256: typedEventPayloadSha256(input.fact),
+        fact: input.fact,
+        revision: 0,
+        recordedAt: input.recordedAt ?? new Date().toISOString(),
+    });
+    store.records.push(record);
+    return record;
+}
+/** Quarantine a staged event after validation failure. */
+export function quarantineTypedEventRecord(store, eventId, reason) {
+    const record = store.records.find((candidate) => candidate.eventId === eventId);
+    if (!record) {
+        throw new TypedEventStoreError("EVENT_NOT_FOUND", `no typed event with eventId ${eventId}`);
+    }
+    if (record.phase !== "staged") {
+        throw new TypedEventStoreError("INVALID_PHASE_TRANSITION", `event ${eventId} is ${record.phase}, not staged`);
+    }
+    const next = typedEventRecordSchema.parse({
+        ...record,
+        phase: "quarantined",
+        quarantineReason: reason,
+    });
+    replaceRecord(store, eventId, next);
+    return next;
+}
+/** Commit a staged event at `revision`. Committed is terminal. */
+export function commitTypedEventRecord(store, eventId, revision) {
+    const record = store.records.find((candidate) => candidate.eventId === eventId);
+    if (!record) {
+        throw new TypedEventStoreError("EVENT_NOT_FOUND", `no typed event with eventId ${eventId}`);
+    }
+    if (record.phase !== "staged") {
+        throw new TypedEventStoreError("INVALID_PHASE_TRANSITION", `event ${eventId} is ${record.phase}, not staged`);
+    }
+    const { quarantineReason: _reason, ...rest } = record;
+    void _reason;
+    const next = typedEventRecordSchema.parse({
+        ...rest,
+        phase: "committed",
+        revision,
+    });
+    replaceRecord(store, eventId, next);
+    return next;
+}
+/** Explicitly adopt a quarantined event as committed at `revision`. This is the
+ * only quarantined → committed transition and is reserved for the explicit
+ * `adopt_staged_fact` path (a later attempt adopts a fact a prior attempt
+ * quarantined). Committed is terminal; the quarantine reason is dropped. */
+export function commitQuarantinedTypedEventRecord(store, eventId, revision) {
+    const record = store.records.find((candidate) => candidate.eventId === eventId);
+    if (!record) {
+        throw new TypedEventStoreError("EVENT_NOT_FOUND", `no typed event with eventId ${eventId}`);
+    }
+    if (record.phase !== "quarantined") {
+        throw new TypedEventStoreError("INVALID_PHASE_TRANSITION", `event ${eventId} is ${record.phase}, not quarantined`);
+    }
+    const { quarantineReason: _reason, ...rest } = record;
+    void _reason;
+    const next = typedEventRecordSchema.parse({
+        ...rest,
+        phase: "committed",
+        revision,
+    });
+    replaceRecord(store, eventId, next);
+    return next;
+}
+/** Read committed events only. Staged/quarantined events are never returned
+ * here (AC-001: quarantine facts must not leak downstream). */
+export function readCommittedEvents(store, attemptId) {
+    return store.records.filter((record) => record.phase === "committed" &&
+        (attemptId === undefined || record.attemptId === attemptId));
+}
+/** Read events for a single attempt, optionally filtered by phase. */
+export function readEventsByAttempt(store, attemptId, options) {
+    const phases = options?.phases;
+    return store.records.filter((record) => record.attemptId === attemptId &&
+        (!phases || phases.includes(record.phase)));
+}
+/** Find a record by requestId, optionally scoped to phase/attempt. */
+export function findEventByRequestId(store, requestId, options) {
+    return store.records.find((record) => record.requestId === requestId &&
+        (options?.phase === undefined || record.phase === options.phase) &&
+        (options?.attemptId === undefined ||
+            record.attemptId === options.attemptId));
+}
+export function findCommittedEventByRequestId(store, requestId) {
+    return findEventByRequestId(store, requestId, { phase: "committed" });
+}
+/** Whether the attempt already has a committed terminal fact. */
+export function hasCommittedTerminalEvent(store, attemptId) {
+    return store.records.some((record) => record.attemptId === attemptId &&
+        record.phase === "committed" &&
+        isTerminalFactKind(record.fact.kind));
+}
+/* ------------------------------------------------------------------ *
+ * Persistence (JSONL). Reuses the atomic-write boundary so every write *
+ * is either fully present or absent.                                  *
+ * ------------------------------------------------------------------ */
+function parseTypedEventRecordLine(line) {
+    return typedEventRecordSchema.parse(JSON.parse(line));
+}
+export async function readTypedEventStoreFromJsonl(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => parseTypedEventRecordLine(line));
+}
+/** Load a store from disk, deriving `revision` from the highest committed
+ * record revision. */
+export async function loadTypedEventStore(filePath) {
+    const records = await readTypedEventStoreFromJsonl(filePath);
+    const revision = records.reduce((max, record) => Math.max(max, record.revision), 0);
+    return { revision, records };
+}
+export async function appendTypedEventRecordJsonl(filePath, record) {
+    await appendJsonlLineAtomic(filePath, record);
+}
+export async function writeTypedEventStoreJsonl(filePath, records) {
+    await writeJsonlAtomic(filePath, records);
+}

package/dist/workflows/dag/frontend-typed-event-transaction.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { commitQuarantinedTypedEventRecord, commitTypedEventRecord, findCommittedEventByRequestId, hasCommittedTerminalEvent, stageTypedEventRecord, typedEventPayloadSha256, } from "./frontend-typed-event-store.js";
+export class TypedEventTransactionError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "TypedEventTransactionError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Stage a fact without committing. Returns the eventId for later adoption. */
+export function stageTypedEventFact(options) {
+    const eventId = options.eventId ?? randomUUID();
+    const record = stageTypedEventRecord(options.store, {
+        eventId,
+        requestId: options.requestId,
+        attemptId: options.attemptId,
+        fact: options.fact,
+        recordedAt: (options.now ?? new Date()).toISOString(),
+    });
+    return { eventId, record };
+}
+function resolveReplayOrConflict(options, existing) {
+    const expectedPayload = typedEventPayloadSha256(options.fact);
+    if (existing.payloadSha256 !== expectedPayload) {
+        throw new TypedEventTransactionError("REQUEST_ID_REUSE_CONFLICT", `requestId ${options.requestId} was used with a different payload hash`, { existingPayloadSha256: existing.payloadSha256, expectedPayload });
+    }
+    return {
+        ok: true,
+        eventId: existing.eventId,
+        record: existing,
+        idempotentReplay: true,
+        revision: existing.revision,
+    };
+}
+/**
+ * Explicitly adopt a staged fact as committed.
+ *
+ * Order of checks matters and is deterministic:
+ *   1. requestId idempotency (pre-check + re-check inside the critical section);
+ *   2. terminal conflict gate;
+ *   3. revision drift;
+ *   4. staged-record integrity;
+ *   5. commit (single logical commit point) + optional post-commit hook.
+ */
+export async function adoptTypedEventFact(options) {
+    const defaultRunExclusive = async (fn) => {
+        return await fn();
+    };
+    const runExclusive = options.runExclusive ?? defaultRunExclusive;
+    const preExisting = findCommittedEventByRequestId(options.store, options.requestId);
+    if (preExisting)
+        return resolveReplayOrConflict(options, preExisting);
+    return runExclusive(async () => {
+        const underLock = findCommittedEventByRequestId(options.store, options.requestId);
+        if (underLock)
+            return resolveReplayOrConflict(options, underLock);
+        if (hasCommittedTerminalEvent(options.store, options.attemptId)) {
+            throw new TypedEventTransactionError("TERMINAL_CONFLICT", `attempt ${options.attemptId} already has a committed terminal fact; refusing late commit of requestId ${options.requestId}`);
+        }
+        if (options.store.revision !== options.expectedRevision) {
+            throw new TypedEventTransactionError("REVISION_CONFLICT", `expectedRevision ${options.expectedRevision} does not match store revision ${options.store.revision}`, {
+                expectedRevision: options.expectedRevision,
+                currentRevision: options.store.revision,
+            });
+        }
+        const staged = options.store.records.find((record) => record.eventId === options.eventId);
+        if (!staged) {
+            throw new TypedEventTransactionError("EVENT_NOT_FOUND", `no typed event with eventId ${options.eventId}`);
+        }
+        if (staged.phase !== "staged") {
+            throw new TypedEventTransactionError("EVENT_NOT_STAGED", `event ${options.eventId} is ${staged.phase}, not staged`);
+        }
+        if (staged.requestId !== options.requestId ||
+            staged.attemptId !== options.attemptId) {
+            throw new TypedEventTransactionError("EVENT_MISMATCH", `staged event ${options.eventId} does not match requestId/attemptId`);
+        }
+        if (staged.payloadSha256 !== typedEventPayloadSha256(options.fact)) {
+            throw new TypedEventTransactionError("EVENT_PAYLOAD_MISMATCH", `staged event ${options.eventId} payload hash does not match the adoption fact`);
+        }
+        const nextRevision = options.expectedRevision + 1;
+        const record = commitTypedEventRecord(options.store, options.eventId, nextRevision);
+        options.store.revision = nextRevision;
+        if (options.afterCommit) {
+            try {
+                await options.afterCommit({ record, revision: nextRevision });
+            }
+            catch (error) {
+                throw new TypedEventTransactionError("POST_COMMIT_ERROR", `post-commit step failed after requestId ${options.requestId} was committed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return {
+            ok: true,
+            eventId: options.eventId,
+            record,
+            idempotentReplay: false,
+            revision: nextRevision,
+        };
+    });
+}
+/**
+ * A+B (AC-005): explicitly adopt a quarantined (or still-staged) fact from a
+ * previous attempt into the committed ledger. This is the `adopt_staged_fact`
+ * semantics: a fact that failed validation and was quarantined becomes visible
+ * to committed readers only through an explicit adopt by a later attempt.
+ *
+ * Reuses the existing adoption double-check (requestId idempotency, terminal
+ * conflict gate, revision CAS) without re-staging: the fact payload is the
+ * already-recorded staged/quarantined payload, so adoption cannot mutate it.
+ */
+export async function adoptStagedFact(options) {
+    const defaultRunExclusive = async (fn) => {
+        return await fn();
+    };
+    const runExclusive = options.runExclusive ?? defaultRunExclusive;
+    const preExisting = findCommittedEventByRequestId(options.store, options.requestId);
+    if (preExisting) {
+        return {
+            ok: true,
+            eventId: preExisting.eventId,
+            record: preExisting,
+            idempotentReplay: true,
+            revision: preExisting.revision,
+        };
+    }
+    return runExclusive(async () => {
+        const underLock = findCommittedEventByRequestId(options.store, options.requestId);
+        if (underLock) {
+            return {
+                ok: true,
+                eventId: underLock.eventId,
+                record: underLock,
+                idempotentReplay: true,
+                revision: underLock.revision,
+            };
+        }
+        if (hasCommittedTerminalEvent(options.store, options.attemptId)) {
+            throw new TypedEventTransactionError("TERMINAL_CONFLICT", `attempt ${options.attemptId} already has a committed terminal fact; refusing late adoption of requestId ${options.requestId}`);
+        }
+        if (options.store.revision !== options.expectedRevision) {
+            throw new TypedEventTransactionError("REVISION_CONFLICT", `expectedRevision ${options.expectedRevision} does not match store revision ${options.store.revision}`, {
+                expectedRevision: options.expectedRevision,
+                currentRevision: options.store.revision,
+            });
+        }
+        const existing = options.store.records.find((record) => record.eventId === options.eventId);
+        if (!existing) {
+            throw new TypedEventTransactionError("EVENT_NOT_FOUND", `no typed event with eventId ${options.eventId}`);
+        }
+        if (existing.phase !== "staged" && existing.phase !== "quarantined") {
+            throw new TypedEventTransactionError("EVENT_NOT_STAGED", `event ${options.eventId} is ${existing.phase}, not staged/quarantined`);
+        }
+        if (existing.requestId !== options.requestId ||
+            existing.attemptId !== options.attemptId) {
+            throw new TypedEventTransactionError("EVENT_MISMATCH", `staged event ${options.eventId} does not match requestId/attemptId`);
+        }
+        const nextRevision = options.expectedRevision + 1;
+        const record = existing.phase === "quarantined"
+            ? commitQuarantinedTypedEventRecord(options.store, options.eventId, nextRevision)
+            : commitTypedEventRecord(options.store, options.eventId, nextRevision);
+        options.store.revision = nextRevision;
+        if (options.afterCommit) {
+            try {
+                await options.afterCommit({ record, revision: nextRevision });
+            }
+            catch (error) {
+                throw new TypedEventTransactionError("POST_COMMIT_ERROR", `post-commit step failed after requestId ${options.requestId} was committed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return {
+            ok: true,
+            eventId: options.eventId,
+            record,
+            idempotentReplay: false,
+            revision: nextRevision,
+        };
+    });
+}