@cotal-ai/connector-core 0.67.0 → 0.69.0

package/dist/agui.js

@@ -23,17 +23,16 @@
  * ## What is here, and what is deliberately NOT
  *
  * Here: the event constructors, the frame envelope, the routing/validity split
- * ({@link isAguiFramePart} / {@link parseAguiFrame}), the {@link AguiBrackets} stream machine, and
- * the `cotal.*` `CUSTOM` table, which is empty in v1.
+ * ({@link isAguiFramePart} / {@link parseAguiFrame}), the {@link AguiBrackets} stream machine, the
+ * `cotal.*` `CUSTOM` table (empty in v1), the preview plane's {@link splitFrames}, and the egress
+ * policy that decides which events may leave for the event channel.
  *
- * Not here, and NAMED rather than stubbed, because a stub is a claim that the shape is known: the
- * channel derivation, the `max_payload` split, and the emitter that publishes. Each of those talks
- * to something outside this module, and each lands with the surface that calls it.
+ * Not here: the emitter that publishes, with the channel derivation and the durable source, WAL and
+ * subject frontier it drives. Those are in `agui-emitter.ts`, which imports this module and is never
+ * imported by it, so a change to the delivery machine cannot reach the vocabulary.
  *
- * **Nothing constructs a frame outside a smoke.** No connector emits, and this module publishes
- * nothing: every export below is a pure function of its arguments. That is a statement about the
- * tree, not a disclaimer — a reader deciding whether a change here can reach a customer needs it to
- * be accurate, so it is maintained rather than left to rot.
+ * **This module publishes nothing and does no I/O.** A reader deciding whether a change here can
+ * reach the wire on its own needs that to be accurate, so it is maintained rather than left to rot.
  */
 // The frame's wire identity lives in `@cotal-ai/core`: an adopted vocabulary is a standard concept,
 // and core must be able to RENDER a frame without depending on an extension. Re-exported here so an
@@ -42,10 +41,6 @@
 // `packages/core/src/agui-kind.ts`.
 export { AGUI_FRAME_KIND, AGUI_EVENT_TYPE, isAguiFramePart } from "@cotal-ai/core";
 import { AGUI_FRAME_KIND, AGUI_EVENT_TYPE, isAguiFramePart } from "@cotal-ai/core";
-import { randomUUID } from "node:crypto";
-import { isCasLoss, principalKey } from "@cotal-ai/core";
-import { dirname } from "node:path";
-import { eventChannelForSession } from "./launch.js";
 /**
  * The `cotal.*` `CUSTOM` event table — the second and ONLY other vehicle for Cotal-specific data.
  *
@@ -566,13 +561,13 @@ const TRUNCATABLE_FIELDS = [
  *  surrogate pair in half and produce a lone surrogate, which is not well-formed UTF-16 — the exact
  *  defect `fix(core)!: refuse names that are not well-formed UTF-16` landed on this branch for. A
  *  splitter that reintroduced it here would emit a frame the wire layer is now obliged to refuse. */
-const takeCodePoints = (s, codePoints) => Array.from(s).slice(0, codePoints).join("");
+export const takeCodePoints = (s, codePoints) => Array.from(s).slice(0, codePoints).join("");
 /**
  * Split `events` into as many frames as the wire requires, truncating only what physically cannot
  * cross it, and LABELLING every truncation.
  *
  * **THIS IS THE PREVIEW PLANE'S SPLITTER, AND IT HAS NO DURABLE-PLANE CALLER BY DESIGN.**
- * Read that as a boundary, not as an oversight: the durable emitter packs with {@link packUnits} at
+ * Read that as a boundary, not as an oversight: the durable emitter packs with `packUnits` at
  * SOURCE-RECORD boundaries and refuses an oversized unit, because one durable emit unit must be one
  * frame carrying a cursor that resumes after it, and a frame ending mid-record has no cursor it can
  * honestly store. This event-boundary split and its labelled truncation were specified before the
@@ -581,10 +576,11 @@ const takeCodePoints = (s, codePoints) => Array.from(s).slice(0, codePoints).joi
  * right answer and why this machinery is worth keeping.
  *
  * **Calling this from the durable emitter would be a silent-loss bug**, not a performance choice —
- * so if you are here looking for the packer, you want `packUnits`. And it is marked rather than
- * deleted for the reason one module over already demonstrated: `assertExpectationSemantics()` sat
- * with zero production callers looking exactly like live code, and unreachable code that looks live
- * is a hazard whichever direction the next reader resolves it in.
+ * so if you are here looking for the packer, you want `packUnits` in `agui-emitter.ts`. And it is
+ * marked rather than deleted for the reason one module over already demonstrated:
+ * `assertExpectationSemantics()` sat with zero production callers looking exactly like live code,
+ * and unreachable code that looks live is a hazard whichever direction the next reader resolves it
+ * in.
  *
  * **Say the uncomfortable thing:** this is a content truncation, which is one of the
  * sins `tr-` is being abolished for. The difference is not that we are gentler about it. `tr-` cut
@@ -699,132 +695,6 @@ function truncateToFit(event, seq, fits, limit, measure, build) {
     }
     return at(lo);
 }
-/**
- * A bracket violation that is OURS, not the writer's: the machine that tracks open runs and messages
- * was lost across a process restart.
- *
- * **This exists because two halts that both say "unbalanced" prove nothing about which produced
- * one.** The WAL persists `epoch`, `frontier` and the pending frame, and NOT the set of open
- * runs and messages, so a process that dies mid-run restarts with an empty {@link AguiBrackets},
- * resumes from `sourceCursor` at events whose `RUN_STARTED` was already published, and refuses the
- * first of them. Without this class the operator sees "nothing may be emitted outside an open run"
- * and files a bug against a writer that did nothing wrong.
- *
- * It is deliberately a SUBCLASS: every existing catch of {@link AguiVocabularyError} still catches
- * it, and only code that wants to tell the two apart has to know it exists.
- */
-export class AguiBracketStateLost extends AguiVocabularyError {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "AguiBracketStateLost";
-    }
-}
-/**
- * The emitter has stopped and will not publish again without operator action.
- *
- * Halting is a SUCCESS of this design, not a failure of it: every halt below is a case where the
- * alternative is to report success for a message that was not stored, or to fold an ack for a body
- * we did not write. A halt is loud, bounded and recoverable by a human; the alternative is silent
- * and permanent.
- */
-export class AguiEmitterHalted extends Error {
-    reason;
-    constructor(reason, message) {
-        super(message);
-        this.reason = reason;
-        this.name = "AguiEmitterHalted";
-    }
-}
-/**
- * The id used only for SIZING, and it is the longest one `assertIdToken` admits.
- *
- * Sizing must never report a smaller number than publishing will produce, and the id is not known
- * when a frame is measured — it is minted per publish attempt. Measuring at the maximum admissible
- * length makes the measurement an UPPER BOUND over every id the emitter could mint, which costs a
- * few bytes of packing density and removes an entire class of near-ceiling defect. The alternative,
- * measuring with the id we intend to use, requires minting before packing and freezing an id for a
- * frame that may never be built.
- */
-const SIZING_ID = "S".repeat(64);
-/**
- * Likewise for the expectation, and this one CANNOT be known at pack time even in principle.
- *
- * `expectedLastSubjectSeq` for frame k+1 is the sequence the broker assigns frame k, and the stream
- * sequence advances with every message in the space, not only ours. Its decimal length is therefore
- * unknowable while packing. `MAX_SAFE_INTEGER` is the widest value the publish path will accept, so
- * measuring at it bounds every expectation the emitter can ever send.
- */
-const SIZING_EXPECTATION = Number.MAX_SAFE_INTEGER;
-/**
- * Pack units into frames, splitting ONLY at unit boundaries and never inside one.
- *
- * Deliberately NOT {@link splitFrames}, and the difference is the durable plane's one-unit-one-frame
- * rule. `splitFrames` splits at EVENT boundaries, which is the right answer for a frame considered
- * on its own, but a frame that ends mid-record has no cursor it can honestly store: the only value
- * available says the whole record was consumed, and folding that after a crash skips the rest of the
- * record's events with no `seq` gap for a consumer to notice.
- *
- * **So the event-boundary split and the one-unit-one-frame rule are in tension, and this resolves it
- * in the direction the durable plane requires: a single unit that does not fit FAILS LOUD rather
- * than being truncated at a frame boundary.** That leaves `splitFrames`'s truncation path with no
- * caller on the durable plane, which is reported as a design conflict rather than decided here.
- *
- * @throws {AguiVocabularyError} when one unit cannot fit in a frame alone.
- */
-export function packUnits(opts) {
-    const { threadId, epoch, measure, limit } = opts;
-    if (!Number.isSafeInteger(limit) || limit <= 0)
-        throw new AguiVocabularyError(`pack limit must be a positive safe integer, got ${JSON.stringify(limit)}`);
-    const out = [];
-    let seq = opts.firstSeq;
-    let batch = [];
-    let batchRun;
-    let batchCursor;
-    const flush = () => {
-        if (batch.length === 0)
-            return;
-        out.push({ frame: aguiFrame({ threadId, runId: batchRun, epoch, seq, events: batch }), cursor: batchCursor });
-        seq += 1;
-        batch = [];
-        batchRun = undefined;
-        batchCursor = undefined;
-    };
-    for (const unit of opts.units) {
-        if (unit.events.length === 0)
-            throw new AguiVocabularyError("packUnits was handed an empty unit; a record that maps to nothing advances the cursor and never becomes a frame");
-        // A frame names ONE run. A unit from a different run cannot join the open batch even if it
-        // would fit, so the run change is a flush and not a size decision.
-        if (batchRun !== undefined && unit.runId !== batchRun)
-            flush();
-        const candidate = [...batch, ...unit.events];
-        const fits = measure(aguiFrame({ threadId, runId: batchRun ?? unit.runId, epoch, seq, events: candidate })) <= limit;
-        if (fits) {
-            batch = candidate;
-            batchRun = batchRun ?? unit.runId;
-            batchCursor = unit.cursor;
-            continue;
-        }
-        // It did not fit WITH the open batch. Flush and try it alone before concluding anything about
-        // the unit itself: an ordinary unit that happens to arrive behind a nearly-full frame is not an
-        // oversized unit, and treating it as one would halt the emitter on a packing accident.
-        flush();
-        const alone = aguiFrame({ threadId, runId: unit.runId, epoch, seq, events: unit.events });
-        const aloneBytes = measure(alone);
-        if (aloneBytes > limit)
-            throw new AguiVocabularyError(`a single source observation does not fit in one frame (${aloneBytes} > ${limit} bytes, ` +
-                `${unit.events.length} event(s), run ${unit.runId}). One source observation is one frame, ` +
-                `and that rule requires this to fail loud rather ` +
-                `than be truncated at a frame boundary: a frame that ends mid-record has no cursor it can ` +
-                `honestly store, and a dropped boundary with no gap marker is worse than a halt.`);
-        batch = [...unit.events];
-        batchRun = unit.runId;
-        batchCursor = unit.cursor;
-    }
-    flush();
-    return out;
-}
 /**
  * Events that must never reach `events.<owner>.<actor>`.
  *
@@ -1064,566 +934,4 @@ export function frozenBodyEgressVerdict(body) {
     }
     return unreadable ? "unreadable" : "clean";
 }
-/**
- * The notice a bounded `RUN_ERROR` carries so a reader cannot mistake a shortened or omitted
- * upstream detail for the original. The close path is the one place this string is composed.
- */
-const RUN_ERROR_DETAIL_BOUND_NOTICE = "original detail omitted or shortened because it exceeded the frame bound";
-/**
- * Rebuild a `RUN_ERROR` so the closing frame fits the live payload ceiling.
- *
- * **This exists because the close is a terminal a reader waits on, and the message is untrusted
- * upstream free text.** `packUnits` is right to refuse an oversized source observation — a unit
- * that does not fit has no honest cursor. A close unit is not a source observation: we author it,
- * it consumes no record, and refusing it leaves the run with no terminal, no pending WAL recovery,
- * and a dead holder. So the close rebuilds the one event until the SAME `measure` `packUnits` will
- * use says it fits, and says in the message that the original detail was omitted or shortened. A
- * short message that already fits is returned unchanged. Since #1431 the close passes only
- * {@link RUN_ERROR_EGRESS_MESSAGE}, which is shorter than the notice, so this either returns it
- * unchanged or throws.
- *
- * It does not live in `packUnits` and it does not call {@link splitFrames}. Those are a different
- * contract (source-record packing, and the preview plane). Putting the bound on this close is the
- * one place every connector already goes through.
- */
-function boundRunErrorForFrame(opts) {
-    const build = (message) => runError({
-        message,
-        timestamp: opts.timestamp,
-        ...(opts.code ? { code: opts.code } : {}),
-        ...(opts.cotal ? { cotal: opts.cotal } : {}),
-    });
-    const frameOf = (event) => aguiFrame({
-        threadId: opts.threadId,
-        runId: opts.runId,
-        epoch: opts.epoch,
-        seq: opts.seq,
-        events: [event],
-    });
-    const original = build(opts.message);
-    if (opts.measure(frameOf(original)) <= opts.limit)
-        return original;
-    const labelled = (kept) => kept.length === 0 ? RUN_ERROR_DETAIL_BOUND_NOTICE : `${RUN_ERROR_DETAIL_BOUND_NOTICE}: ${kept}`;
-    const at = (codePoints) => build(labelled(takeCodePoints(opts.message, codePoints)));
-    const emptied = at(0);
-    if (opts.measure(frameOf(emptied)) > opts.limit)
-        throw new AguiVocabularyError(`a RUN_ERROR close does not fit in ${opts.limit} bytes even with the failure detail emptied ` +
-            `and replaced by a bound notice — the envelope, the code and the headers alone are ` +
-            `${opts.measure(frameOf(emptied))} bytes. No bound on the detail can help, so this fails ` +
-            `loudly rather than leaving the run without a terminal.`);
-    // Binary-search the largest well-formed prefix that still fits, re-measuring the whole frame
-    // each step: JSON escaping and UTF-8 length are nonlinear, so cutting by the overage is wrong.
-    let lo = 0;
-    let hi = Array.from(opts.message).length + 1;
-    while (hi - lo > 1) {
-        const mid = Math.floor((lo + hi) / 2);
-        if (opts.measure(frameOf(at(mid))) <= opts.limit)
-            lo = mid;
-        else
-            hi = mid;
-    }
-    return at(lo);
-}
-/**
- * The event emitter: one per principal, one thread at a time.
- *
- * **BRACKET STATE SURVIVES A RESTART, AND THIS PARAGRAPH USED TO SAY THE OPPOSITE.** It described a
- * declared gap — an emitter coming back with an empty machine, resuming at events whose
- * `RUN_STARTED` had already been published, and refusing the first of them — long after the WAL
- * started persisting the machine. The words were true when they were written and stayed on the page
- * through the change that falsified them, which is the failure mode a class header is worst at
- * showing: it is the first thing a cutover author reads about recovery, and it was telling them to
- * expect a halt the code no longer produces.
- *
- * What actually happens: {@link AguiBrackets} is a property of the WRITER'S STREAM across frames, so
- * the WAL freezes the machine's state WITH each pending frame and promotes it on fold. A restart
- * therefore reopens knowing exactly which run, messages and tool calls were open at the last FOLDED
- * position, and {@link AguiBrackets.restore} continues from there rather than from empty.
- *
- * **The lost-state path still exists, and it is now the narrow case it should always have been:** a
- * document that CANNOT SAY what was open. That is a WAL migrated from v1, which recorded no bracket
- * state at all, and it loads as `null` rather than as an empty machine precisely so the difference
- * stays visible. Only there does the emitter start empty, resume into an already-open run, and
- * refuse the first event with {@link AguiBracketStateLost} — a halt rather than a loss, which is the
- * safe direction, and diagnosed by name rather than surfacing as an anonymous protocol violation.
- */
-export class AguiEmitter {
-    ep;
-    wal;
-    source;
-    map;
-    channel;
-    threadId;
-    /**
-     * The bracket machine AT THE FOLDED POSITION — deliberately not "wherever validation got to".
-     *
-     * It advances one frame at a time, immediately before that frame's `beginSend`, so the state
-     * frozen with a pending frame is the state that belongs to it. A machine advanced by the whole
-     * batch up front would freeze a state describing events that had not been sent.
-     */
-    brackets;
-    halted;
-    /** True once THIS process has fed an event through the bracket machine. It is the half of the
-     *  restart diagnosis that keeps a genuine mid-stream violation from being blamed on a restart. */
-    fedAnyEvent = false;
-    constructor(ep, wal, source, map, 
-    /** Derived from the endpoint's OWN principal, never from a config name or the launch env. */
-    channel, threadId) {
-        this.ep = ep;
-        this.wal = wal;
-        this.source = source;
-        this.map = map;
-        this.channel = channel;
-        this.threadId = threadId;
-        // RESTORED FROM THE WAL, which is the whole point of the v2 migration: a process that died
-        // mid-run comes back knowing which runs and messages are open, instead of refusing the first
-        // event it re-reads. `null` means the document cannot say (migrated from v1) — an empty machine
-        // is the honest starting point there, and `diagnoseBracket` is what keeps the resulting refusal
-        // from being blamed on the writer.
-        this.brackets = wal.brackets ? AguiBrackets.restore(wal.brackets) : new AguiBrackets();
-    }
-    /**
-     * Start an emitter: resolve the channel, run the single-replica preflight, and settle any pending
-     * frame.
-     *
-     * **THIS IS THAT PREFLIGHT'S PRODUCTION CALL SITE, AND UNTIL THIS FUNCTION EXISTED THERE WAS
-     * NONE.** `CotalEndpoint.assertExpectationSemantics()` had zero production callers: it was a
-     * check that shipped, was covered by its own suite, and never ran outside one. That is why it is
-     * called HERE, before recovery and therefore before any publish — a serialized append on an
-     * unverified stream is the exact case it exists to prevent, and doing it after recovery would
-     * leave the one publish that matters most, the re-publish of a frozen frame, outside the guard.
-     */
-    static async start(opts) {
-        const { endpoint, wal } = opts;
-        const channel = eventChannelForSession(endpoint);
-        // The WAL must be THIS principal's. `EventWal.open` refuses a document whose stored principal
-        // disagrees with what it was asked for, but that protects the file against being mistaken for
-        // another; it cannot notice an emitter handed the wrong WAL object. Publishing under one
-        // principal's identity while recovering another's frozen `E` is a fabricated frontier.
-        const live = principalKey(endpoint.principal.owner, endpoint.principal.actor).key;
-        if (wal.principal !== live)
-            throw new Error(`event WAL belongs to principal ${wal.principal}, but this endpoint is ${live} — refusing to ` +
-                `publish under one identity from another's write-ahead log`);
-        // THE SINGLE-REPLICA PREFLIGHT: before recovery, before any publish.
-        await endpoint.assertExpectationSemantics();
-        // REQUIRED AT RUNTIME, NOT ONLY IN THE TYPE. Smoke files in this repo are not typechecked, so a
-        // caller that omits this would bind `undefined`, fall back to the per-thread number, and pass
-        // every existing cell while shipping the exact defect this parameter exists to remove. A type
-        // that only the compiler enforces is not a guard for the callers the compiler never sees.
-        if (!opts.subjectFrontier || typeof opts.subjectFrontier.advance !== "function")
-            throw new Error(`event emitter for ${channel}: a subject frontier is required — the subject is shared by every ` +
-                `thread of this principal, so the publish expectation cannot come from one thread's log`);
-        // BOUND BEFORE RECOVERY, and the order matters for the same reason the preflight's does:
-        // recovery can republish a frozen frame, and a WAL whose expectation still came from its own
-        // thread would republish against the wrong tip.
-        await wal.bindSubjectFrontier(opts.subjectFrontier);
-        const em = new AguiEmitter(endpoint, wal, opts.source, opts.map, channel, wal.threadId);
-        await em.recover();
-        return em;
-    }
-    /** True once the emitter has stopped for good. */
-    get stopped() {
-        return this.halted !== undefined;
-    }
-    /** The run {@link closeRun} would close now, or `undefined` at a stopping point. */
-    get openRunId() {
-        return this.brackets.runId;
-    }
-    /**
-     * Boot recovery, branching on the WAL's tag.
-     *
-     * `acked` NEVER republishes: the frame landed and we know it, so the only remaining work is to
-     * fold. `sent_unacked` is the genuinely uncertain case and republishes with the SAME frozen `id`
-     * and `E` — never the current tip, because re-deriving either is what turns an uncertain publish
-     * into a second, different message.
-     */
-    async recover() {
-        const p = this.wal.pending;
-        if (!p)
-            return;
-        if (p.state === "acked") {
-            await this.wal.fold();
-            this.brackets = AguiBrackets.restore(p.brackets);
-            return;
-        }
-        // The retried frame was accepted by a PREVIOUS process and is not fed through this instance's
-        // machine again. Folding promotes its bracket snapshot on disk; promote the same snapshot here
-        // or this emitter continues from the pre-pending state and rejects the next legal event.
-        await this.attempt({ id: p.id, E: p.E, body: p.body, retry: true });
-        this.brackets = AguiBrackets.restore(p.brackets);
-    }
-    /**
-     * Read forward, map, pack, and publish. Returns what it did, so a caller can distinguish "nothing
-     * to do" from "did work" without inspecting the WAL.
-     */
-    async pump() {
-        if (this.halted)
-            throw this.halted;
-        if (this.wal.pending)
-            throw new Error(`event emitter for ${this.channel}: a frame is still pending; recovery must settle it before a new read`);
-        const read = await this.source.read(this.wal.frontier.sourceCursor);
-        // Units the mapper dropped are not errors and not frames. Their cursor folds FORWARD into the
-        // preceding unit, so consuming that frame consumes them too and they are never re-read. A drop
-        // stays apart from a mapper error, which reaches the caller with the cursor unmoved.
-        const units = [];
-        for (const rec of read.records) {
-            const mapped = this.map(rec.value);
-            if (mapped === null || mapped.events.length === 0) {
-                const last = units[units.length - 1];
-                if (last)
-                    last.cursor = rec.cursor;
-                continue;
-            }
-            // WRITE-PATH POLICY, before packing and therefore before beginSend. Disk and wire then agree.
-            // A record that mapped only to forbidden kinds becomes a drop: its cursor folds forward like
-            // any other drop, and packUnits never sees an empty unit.
-            const events = applyAguiEgressPolicy(mapped.events);
-            if (events.length === 0) {
-                const last = units[units.length - 1];
-                if (last)
-                    last.cursor = rec.cursor;
-                continue;
-            }
-            units.push({ runId: mapped.runId, events, cursor: rec.cursor });
-        }
-        // A bounded range that mapped to nothing advances the cursor atomically and ALONE.
-        //
-        // THIS IS THE COMMON PATH, NOT AN EDGE CASE, and the number is here so nobody reads it as one.
-        // Measured on a real Claude session of 5938 records: only 2694 (45%) carry a `message` at all —
-        // the rest are attachments, queue operations, mode changes, prompt markers and system entries
-        // the mapping deliberately drops. So the MAJORITY of a real session maps to nothing. An emitter
-        // advanced the cursor only through an acked frame would re-read the same 55% forever, and no
-        // fixture would ever show it, because a fixture author writes records that mean something.
-        //
-        // It must also advance on an ADOPT, which reads zero records by design: without that the position
-        // is never persisted and the next read adopts a LATER end, silently skipping everything appended
-        // in between.
-        if (units.length === 0) {
-            if (read.cursor !== this.wal.frontier.sourceCursor)
-                await this.wal.advanceCursorOnly(read.cursor);
-            return { frames: 0, events: 0 };
-        }
-        // Validate the WHOLE batch before publishing any of it. A vocabulary violation discovered
-        // halfway through would leave a valid prefix on the wire and the rest refused, and the refusal
-        // is supposed to mean "this stream never carried that", not "it carried some of it".
-        // Validated on a CLONE, so the machine that is in step with the disk does not advance for a
-        // batch that may never be sent. The clone starts from the folded state, so it sees exactly what
-        // the real machine will see, in the same order.
-        const probe = this.brackets.clone();
-        for (const u of units)
-            for (const e of u.events) {
-                try {
-                    probe.accept(e);
-                }
-                catch (err) {
-                    throw this.diagnoseBracket(err);
-                }
-            }
-        // Set only after the WHOLE batch validated. Setting it per event would make a batch that failed
-        // on its FIRST event count as "this process has fed something", which is the precise input that
-        // turns the restart diagnosis off.
-        this.fedAnyEvent = true;
-        const frames = packUnits({
-            threadId: this.threadId,
-            epoch: this.wal.epoch,
-            firstSeq: this.wal.frontier.seq + 1,
-            units,
-            measure: (f) => this.measure(f),
-            limit: this.ep.maxPayload,
-        });
-        let events = 0;
-        for (const { frame, cursor } of frames) {
-            await this.publish(frame, cursor);
-            events += frame.events.length;
-        }
-        // Records the mapper dropped AFTER the last unit have no frame to ride on, so their cursor is
-        // advanced on its own: the same cursor-only rule, applied to the tail of the batch.
-        if (read.cursor !== this.wal.frontier.sourceCursor)
-            await this.wal.advanceCursorOnly(read.cursor);
-        return { frames: frames.length, events };
-    }
-    /**
-     * Close the run this stream currently has open, at a boundary the RECORD STREAM CANNOT SEE.
-     *
-     * **This exists because the two halves of the mapping were specified against different inputs.**
-     * The plan sources `RUN_FINISHED` from a harness lifecycle hook, and the durable plane reads a
-     * FILE: a hook fires in another process and writes no record, so a hook-sourced terminal has no
-     * vehicle into a record-sourced stream. Deriving the terminal from records instead is possible but
-     * lies about time in two ways that matter to a live view: the finish lands only when the NEXT turn
-     * starts, so a finished agent renders as still running, and the last run of a session never closes
-     * at all, because there is no later record to close it on. This is that vehicle.
-     *
-     * It is a FRAME LIKE ANY OTHER: same epoch, same `seq` line, same write-ahead discipline, same
-     * halt rules. The single thing that differs is the cursor, which is republished UNCHANGED, because
-     * this frame consumes no source record. A frame that advanced the cursor here would mark records
-     * consumed that were never mapped.
-     *
-     * Idempotent by construction rather than by a flag: the bracket machine is the only state it
-     * reads, so once the run is closed there is nothing open to close and it answers `null`. That also
-     * makes it safe on a stream whose run was opened by a PREVIOUS process, since the machine is
-     * restored from the WAL.
-     *
-     * **AN `error` CLOSES THE SAME RUN WITH `RUN_ERROR` INSTEAD, and it is one method rather than two
-     * ON PURPOSE.** `RUN_ERROR` closes a run on its own, so a run that emitted one must never also
-     * emit a `RUN_FINISHED`. With a second method that invariant would be a rule someone has to
-     * remember; with one method and one branch it is a property of the shape: exactly one terminal is
-     * built, and the bracket machine has closed the run by the time anything could ask for another, so
-     * a following close answers `null` like any other close on a settled stream. Which harness signals
-     * mean a turn FAILED is a connector's decision and is stated at each connector's own mapping site;
-     * this file only carries the answer to the wire.
-     *
-     * **`error.message` AND `error.code` NEVER REACH THE WIRE.** Both are upstream values, so the close
-     * publishes {@link RUN_ERROR_EGRESS_MESSAGE} with no code, the same shape the write path's
-     * {@link egressRunError} produces (#1431). The frame bound still runs after that, so a close whose
-     * envelope cannot fit fails loud rather than leaving the run without a terminal.
-     *
-     * @returns the run that was closed, or `null` when the stream was already at a stopping point.
-     */
-    async closeRun(o) {
-        if (this.halted)
-            throw this.halted;
-        if (this.wal.pending)
-            throw new Error(`event emitter for ${this.channel}: a frame is still pending; recovery must settle it before a run can be closed`);
-        const runId = this.brackets.runId;
-        if (runId === undefined)
-            return null;
-        const cursor = this.wal.frontier.sourceCursor;
-        if (cursor === undefined)
-            throw new Error(`event emitter for ${this.channel}: run "${runId}" is open on a frontier that carries no source ` +
-                `cursor. A run can only be open because a frame published it, and a frame that published ` +
-                `cannot leave the cursor unset, so this WAL disagrees with itself. Refusing to invent a ` +
-                `cursor for the closing frame.`);
-        // `RUN_ERROR` carries no `runId` and no `threadId` of its own — its schema is `message` plus an
-        // optional `code` — so the run it closes is named by the frame's unit below, not by the event.
-        // The bound is measured with the same function and ceiling `packUnits` will use, at the `seq`
-        // the closing frame will actually carry.
-        const event = o.error
-            ? boundRunErrorForFrame({
-                message: RUN_ERROR_EGRESS_MESSAGE,
-                timestamp: o.timestamp,
-                ...(o.cotal ? { cotal: o.cotal } : {}),
-                threadId: this.threadId,
-                runId,
-                epoch: this.wal.epoch,
-                seq: this.wal.frontier.seq + 1,
-                measure: (f) => this.measure(f),
-                limit: this.ep.maxPayload,
-            })
-            : runFinished({
-                threadId: this.threadId,
-                runId,
-                timestamp: o.timestamp,
-                ...(o.cotal ? { cotal: o.cotal } : {}),
-            });
-        // Validated on a clone first, exactly as a mapped batch is. The refusal that matters here is a
-        // message or tool call still open under this run: either terminal while something it opened is
-        // unclosed is a protocol violation, and it must surface as one rather than be published.
-        const probe = this.brackets.clone();
-        try {
-            probe.accept(event);
-        }
-        catch (err) {
-            throw this.diagnoseBracket(err);
-        }
-        this.fedAnyEvent = true;
-        const frames = packUnits({
-            threadId: this.threadId,
-            epoch: this.wal.epoch,
-            firstSeq: this.wal.frontier.seq + 1,
-            units: [{ runId, events: [event], cursor }],
-            measure: (f) => this.measure(f),
-            limit: this.ep.maxPayload,
-        });
-        for (const { frame, cursor: c } of frames)
-            await this.publish(frame, c);
-        return runId;
-    }
-    /** Measure a candidate frame EXACTLY as the wire will, at an upper bound over id and expectation. */
-    measure(frame) {
-        return this.ep.encodedSize({
-            channel: this.channel,
-            parts: [frame],
-            id: SIZING_ID,
-            expectedLastSubjectSeq: SIZING_EXPECTATION,
-        });
-    }
-    /** Transition 1 then the first network attempt. */
-    async publish(frame, cursor) {
-        // Advance the real machine by exactly this frame. It cannot throw: the identical sequence was
-        // already accepted by a clone starting from this same state, in this same order. It is not
-        // wrapped in a diagnosis for that reason — a throw here would be a bug in this file, not a
-        // stream problem, and dressing it as one would hide it.
-        for (const e of frame.events)
-            this.brackets.accept(e);
-        const brackets = this.brackets.snapshot();
-        const id = randomUUID();
-        // THE SUBJECT'S TIP, NOT THIS THREAD'S LAST ACK. The two were the same number until a second
-        // session of the same principal existed, and then they were not: the subject is per principal
-        // and the log is per thread, so a new thread's own `lastSubjectSeq` is 0 on a subject its
-        // predecessor already filled.
-        const E = this.wal.expectedTip;
-        const body = [frame];
-        // Durable BEFORE the wire. The order is the whole state machine: a crash between this line and
-        // the next is recoverable precisely because the id and `E` are already frozen on disk.
-        await this.wal.beginSend({ id, E, seq: frame.seq, sourceCursor: cursor, body, brackets });
-        await this.attempt({ id, E, body, retry: false });
-    }
-    /**
-     * One publish attempt — first or retry — with the FROZEN id and the FROZEN `E`. Never the tip.
-     *
-     * The three outcomes are not symmetric and the asymmetry is the design:
-     * - `!duplicate` → transition 2 then 3. Success becomes durable before the frontier moves.
-     * - `duplicate` → HALT. On a first attempt it means a body WE DID NOT WRITE holds our id, and
-     *   folding its `ackSeq` would advance the frontier and the source cursor past events that were
-     *   never published. On a retry it cannot happen on a single-replica stream at all, because such a
-     *   stream evaluates the expectation before the dedup cache, so observing it proves the stream is
-     *   not single-replica. Both are
-     *   fail-loud, and neither is a case where guessing is better than stopping.
-     * - CAS loss → HALT. Someone else moved the tip on a subject only this principal may write, or
-     *   the subject was purged. Uncertainty plus a moved tip is exactly what must not be guessed at.
-     *
-     * A NETWORK error is deliberately none of these: it leaves `pending` as `sent_unacked`, which is
-     * the state that means "we do not know", and the next boot retries the same frozen frame.
-     */
-    async attempt(o) {
-        const egress = frozenBodyEgressVerdict(o.body);
-        if (egress === "forbidden-kind") {
-            throw this.halt("egress-policy", `event emitter for ${this.channel}: refusing to ${o.retry ? "republish a frozen" : "publish a"} ` +
-                `frame whose body carries TOOL_CALL_ARGS or TOOL_CALL_RESULT onto ${this.channel}. ` +
-                `That channel has a different read ACL from the one a mesh read tool ran on, and those ` +
-                `kinds republish tool inputs and outputs. The body is not rewritten: the WAL froze it at ` +
-                `beginSend, a retry must republish those bytes or not at all, and mutating them between ` +
-                `disk and wire would break the recovery machine. An upgrade across a pending pre-fix ` +
-                `frame therefore HALTS rather than leaks. Clear the pending frame only as an explicit ` +
-                `abandonment of this epoch.`);
-        }
-        if (egress === "unreadable") {
-            throw this.halt("egress-unreadable", `event emitter for ${this.channel}: refusing to ${o.retry ? "republish a frozen" : "publish a"} ` +
-                `frame whose event list this policy cannot read onto ${this.channel}. A frame-shaped body ` +
-                `whose \`events\` is absent, or is not an array, cannot be checked for TOOL_CALL_ARGS or ` +
-                `TOOL_CALL_RESULT, and a body whose \`events\` is a bare string carries its bytes exactly ` +
-                `where the check would have looked. The boundary is the wire and not what a renderer ` +
-                `folds, so an uninspectable body is withheld rather than published opaque onto a channel ` +
-                `with a different read ACL. \`aguiFrame\` enforces a non-empty events ARRAY at ` +
-                `construction, so no frame this version writes can land here; one that does was frozen by ` +
-                `something else. Clear the pending frame only as an explicit abandonment of this epoch.`);
-        }
-        if (egress === "run-error-content") {
-            throw this.halt("egress-run-error", `event emitter for ${this.channel}: refusing to ${o.retry ? "republish a frozen" : "publish a"} ` +
-                `frame whose RUN_ERROR carries upstream text onto ${this.channel}. Since #1431 a published ` +
-                `RUN_ERROR has the fixed message "${RUN_ERROR_EGRESS_MESSAGE}" and no code or rawEvent, because ` +
-                `the upstream error text can echo a prompt, a peer message or tool output and that channel ` +
-                `has a different read ACL. The body is not rewritten: the WAL froze it at beginSend, so an ` +
-                `upgrade across a pending pre-fix frame HALTS rather than leaks. Clear the pending frame ` +
-                `only as an explicit abandonment of this epoch.`);
-        }
-        if (egress === "extra-property") {
-            // Re-scan to name the path. This is the error path; the cost is negligible.
-            let path = "(unknown)";
-            for (const part of o.body) {
-                if (!isAguiFramePart(part))
-                    continue;
-                const p = extraPropertyPath(part);
-                if (p !== undefined) {
-                    path = p;
-                    break;
-                }
-            }
-            throw this.halt("egress-extra-property", `event emitter for ${this.channel}: refusing to ${o.retry ? "republish a frozen" : "publish a"} ` +
-                `frame whose body carries an unknown property at \`${path}\` onto ${this.channel}. ` +
-                `The egress fence validates the whole envelope against a closed schema: known top-level ` +
-                `frame keys (kind, protocol, threadId, runId, epoch, seq, events) and known per-event ` +
-                `keys per type. A property outside that schema could carry tool output or other content ` +
-                `that bypasses the event-kind check. The body is not rewritten: the WAL froze it at ` +
-                `beginSend, and mutating it between disk and wire would break the recovery machine. ` +
-                `Clear the pending frame only as an explicit abandonment of this epoch.`);
-        }
-        let ack;
-        try {
-            ({ ack } = await this.ep.multicastExpecting({
-                channel: this.channel,
-                parts: o.body,
-                id: o.id,
-                expectedLastSubjectSeq: o.E,
-            }));
-        }
-        catch (e) {
-            if (isCasLoss(e))
-                throw this.halt("cas-loss", `event emitter for ${this.channel}: the subject tip is no longer ${o.E} (${e.message}). ` +
-                    `The broker ACL confines this subject to one principal, so the tip moved for one of: a ` +
-                    `CONCURRENT emitter under this same principal. The per-principal lock refuses a second ` +
-                    `one, but the lock FILE lives under a workspace root, so an emitter started against a ` +
-                    `DIFFERENT root, or by a path that never takes the lock, meets no lock at all. Another ` +
-                    `host and a stale pid do not get past it; they refuse the start instead, loudly; a ` +
-                    `subject frontier record that disagrees with the stream, ` +
-                    `which is what an interrupted upgrade or a restored backup leaves behind; a RESTORED ` +
-                    `stream; or a FILTERED PURGE, which returns the tip to 0 for every thread on the channel. ` +
-                    `One more cause is not a second writer at all: this log's OWN last ack. The shared record ` +
-                    `advances before the log records the ack, so a crash between those two writes leaves the ` +
-                    `record ahead of the frozen expectation this frame carries, and the retry publishes a ` +
-                    `sequence the subject has already passed. On disk it reads as a pending frame in state ` +
-                    `sent_unacked whose E is BEHIND the record's tip, which a restored record can also look ` +
-                    `like, so it narrows the search rather than ending it. ` +
-                    `None of these is resolvable by re-reading the tip, which agent credentials cannot read in ` +
-                    `any case. Clearing it is an explicit abandonment of epoch, seq, E, cursor and the shared ` +
-                    `subject record together, and it is VALID ONLY ONCE THE SUBJECT IS ACTUALLY EMPTY, which ` +
-                    `of the causes above is true of the FILTERED PURGE alone. On any other cause the tip is ` +
-                    `still where it is, so removing this state does not clear the halt: the next session ` +
-                    `opens virgin, expects 0, halts on the same tip, and the sibling logs a tip could have ` +
-                    `been rebuilt from are gone. Purge the channel first, or find the second writer, or match the ` +
-                    `signature above and stop looking for one. Once ` +
-                    `the subject really is back to 0, no command performs the abandonment, so by hand it ` +
-                    `means removing ${dirname(dirname(this.wal.path))} whole, and removing less than that ` +
-                    `leaves a mixed state the next start refuses.`);
-            throw e;
-        }
-        if (ack.duplicate)
-            throw this.halt("duplicate-ack", `event emitter for ${this.channel}: the broker answered ${o.retry ? "a RETRY" : "a FIRST attempt"} ` +
-                `for id ${o.id} with duplicate:true. ` +
-                (o.retry
-                    ? `Under the SINGLE-REPLICA RETRY RULE this cannot happen on an R1 stream, which ` +
-                        `evaluates the subject expectation ` +
-                        `before the dedup cache — so either the stream is not R1 or a foreign body holds our ` +
-                        `stream-wide id. `
-                    : `We have never published this id, so a body we did not write holds it. `) +
-                `Folding this ack would advance the frontier and the source cursor past events that were ` +
-                `never published: silent loss of real events. The frontier and cursor are unchanged.`);
-        await this.wal.recordAck(ack.seq);
-        await this.wal.fold();
-    }
-    /**
-     * Decide whether a bracket refusal is the WRITER's fault or OURS, and say which.
-     *
-     * Ours iff ALL THREE hold, and each is load-bearing:
-     * - this process has fed NO event through the machine yet, so the machine cannot have been put
-     *   into a bad state by anything we did in this run; and
-     * - the frontier is non-virgin, so frames — and therefore possibly an open `RUN_STARTED` — were
-     *   published by a PREVIOUS process; and
-     * - the WAL cannot say what was open. Since v2 the machine is PERSISTED, so an ordinary restart
-     *   restores it and never reaches here at all; `null` means the document was migrated from v1 and
-     *   genuinely never recorded the state. Without this condition the diagnosis would survive as a
-     *   permanent excuse for a case the migration fixed.
-     *
-     * Drop the first condition and a genuine mid-stream violation by the writer gets blamed on a
-     * restart that happened an hour ago. Drop the second and a violation on a virgin thread, where
-     * nothing was ever published and nothing could have been lost, gets blamed on a restart that never
-     * happened. Each condition alone produces a confident, wrong diagnosis — which is worse than the
-     * undiagnosed error it replaced, because a named cause stops the search.
-     */
-    diagnoseBracket(err) {
-        if (this.fedAnyEvent || this.wal.frontier.seq === 0 || this.wal.brackets !== null)
-            return err;
-        return new AguiBracketStateLost(`event emitter for ${this.channel}: bracket state was LOST ACROSS A RESTART — this is not a ` +
-            `protocol violation by the writer. This process has emitted nothing yet, but the WAL says ` +
-            `frame ${this.wal.frontier.seq} already went out, and the document records NO bracket state ` +
-            `(it was migrated from v1, which never stored one), so any run or message the previous ` +
-            `process left open is invisible to this one. Resuming from the source cursor therefore lands ` +
-            `mid-run and the first event is refused. A WAL written by this build persists the machine and ` +
-            `does not reach this path. The underlying refusal was: ${err.message}`, err);
-    }
-    halt(reason, message) {
-        this.halted = new AguiEmitterHalted(reason, message);
-        return this.halted;
-    }
-}
 //# sourceMappingURL=agui.js.map