@cotal-ai/connector-core 0.18.0 → 0.20.0

package/dist/event-wal.d.ts

@@ -0,0 +1,265 @@
+import { type FileHandle } from "node:fs/promises";
+import { type Part } from "@cotal-ai/core";
+import type { BracketState } from "./agui.js";
+/**
+ * Bump ONLY with a migration. An OLDER document is migrated forward; a NEWER one fails loud.
+ *
+ * **v2 added `brackets`** — the AG-UI bracket machine's state, persisted so a mid-run restart can
+ * continue instead of refusing the first event it re-reads.
+ *
+ * **v3 added `gen`** — a counter this writer bumps on every durable replace, so a write can tell
+ * whether the document it is about to replace is the one it last read. See {@link EventWal.write}.
+ * A v2 document has never been written by a generation-aware writer, so it migrates forward at
+ * generation 0; from v3 on the field is REQUIRED, because "absent" and "zero" would otherwise be
+ * the same value and stripping the field would disable the guard silently.
+ *
+ * **THE MIGRATION IS FORWARD-ONLY, AND THAT MAKES THE STATE OUTLIVE A CODE ROLLBACK.** Once a
+ * process writes v2, reverting the code does NOT revert the state: the older build refuses the
+ * document it now finds. That is the right trade — fail-loud beats silently reading a schema you do
+ * not understand — but it converts "revert the commit" into "revert the commit and hand-migrate the
+ * state", and the person doing the reverting will otherwise discover that at the worst moment. So
+ * the refusal below distinguishes NEWER-than-this-code from unknown, and says which migration.
+ * There is deliberately no downgrade path: a lossy downgrade is worse than a halt.
+ */
+export declare const EVENT_WAL_VERSION = 3;
+export interface WalFrontier {
+    /** The `seq` of the last frame FOLDED into the frontier. 0 before the first frame lands. */
+    seq: number;
+    /** The subject sequence the next publish must expect (`E`). 0 on a virgin thread. */
+    lastSubjectSeq: number;
+    /** The durable source position everything up to `seq` was derived from. */
+    sourceCursor: string | undefined;
+}
+export interface WalPending {
+    state: "sent_unacked" | "acked";
+    /** Frozen at transition 1 and NEVER re-minted — a retry must carry the same id. */
+    id: string;
+    /** The expectation frozen at transition 1, likewise never recomputed on retry. */
+    E: number;
+    seq: number;
+    sourceCursor: string;
+    /**
+     * The frame's parts, FROZEN at transition 1 beside the id and `E` that identify them.
+     *
+     * Without this the WAL froze what NAMES a frame and not the frame: a restart holding
+     * `sent_unacked` recovered the id and the expectation and had nothing to re-publish, so
+     * "retry the same frame after a crash" — the one thing this file exists to make possible —
+     * could not be performed from the document. The write-ahead rule requires it and it was absent.
+     *
+     * It is the parts and not a rendered message because `multicastExpecting` builds the envelope
+     * (`ts`, `from`, `space`) at publish time; storing that too would freeze a second copy of fields
+     * the publisher owns, and a retry would then carry a stale `ts` under a frozen id.
+     */
+    body: Part[];
+    /** Present iff `state === "acked"`: the sequence the server assigned. */
+    ackSeq?: number;
+    /**
+     * The bracket machine's state AFTER this frame's events (v2).
+     *
+     * Frozen with the frame rather than derived on fold, for the same reason the body is: the state
+     * that belongs to a frame is decided when the frame is decided. Transition 3 promotes it to the
+     * document's own `brackets`, so what is persisted always describes exactly the events that have
+     * been published AND folded — never a batch that was validated and not yet sent.
+     */
+    brackets: BracketState;
+}
+export interface WalDoc {
+    v: number;
+    /**
+     * How many durable replaces this document has been through (v3).
+     *
+     * It is a WITNESS, not a clock: its only job is to let a writer notice that the file it is about
+     * to replace is no longer the file it read. Nothing orders two documents by it and nothing derives
+     * a position from it.
+     */
+    gen: number;
+    /**
+     * The space this WAL belongs to — stored because it is a PATH COMPONENT and a path component is
+     * not a trusted input. `principal` and `threadId` were verified on
+     * load and `space` was not, so a WAL copied or mis-resolved between two space directories under
+     * the same principal and thread LOADED, and one space's frontier was adopted as another's. Two
+     * thirds of a three-part guard is not the guard.
+     */
+    space: string;
+    epoch: string;
+    threadId: string;
+    principal: string;
+    frontier: WalFrontier;
+    pending: WalPending | null;
+    /**
+     * The bracket machine at the FOLDED position, or `null` for **unknown** (v2).
+     *
+     * `null` and an explicitly empty state are different facts and the difference is load-bearing.
+     * An empty state is this writer saying "nothing is open"; `null` is a document that cannot say —
+     * a WAL migrated from v1, which recorded no bracket state at all. A restart on `null` therefore
+     * still takes the lost-state path and still says so, while a restart on a recorded state simply
+     * continues. Collapsing the two would make a migrated document silently claim a clean boundary it
+     * never observed, which is the same class as treating a zero-byte file as a virgin thread.
+     */
+    brackets: BracketState | null;
+}
+/** Every refusal in this file is one of these, so a caller can never mistake it for an I/O blip. */
+export declare class WalCorruptError extends Error {
+    readonly path: string;
+    readonly invariant: string;
+    constructor(path: string, invariant: string, detail: string);
+}
+/**
+ * Thrown when this handle's document is not the one on disk any more.
+ *
+ * A DISTINCT type from {@link WalCorruptError} because the file is not corrupt: it is FINE, and it
+ * belongs to somebody else's newer view. An operator reading "corrupt" would go looking for a bad
+ * disk; the actual situation is two writers, and only one of them is current.
+ */
+export declare class WalStaleWriterError extends Error {
+    readonly path: string;
+    readonly expectedGen: number;
+    readonly foundGen: number | undefined;
+    constructor(path: string, expectedGen: number, foundGen: number | undefined);
+}
+/**
+ * Create a file EXCLUSIVELY and WITHOUT following a symlink, at mode 0600.
+ *
+ * **Exported so a test can drive the shipped flags rather than recompose them.** A cell that builds
+ * `O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW` itself is testing a COPY of this rule: it stays green
+ * while the production open drifts or loses a flag. That is not hypothetical here — the first
+ * version of those cells did exactly that, and a mutation reverting the real open to `"w"` left the
+ * suite fully green. Driving this function is what makes the mutation land.
+ *
+ * `O_EXCL` refuses a pre-existing file rather than adopting it — which matters because `"w"` does
+ * NOT re-chmod an existing inode, so an adopted 0644 temp would carry its mode onto the renamed WAL
+ * and expose `pending.id`. `O_NOFOLLOW` refuses a symlink rather than truncating its target.
+ */
+export declare function openExclusiveNoFollow(path: string): Promise<FileHandle>;
+export declare class EventWal {
+    readonly path: string;
+    private doc;
+    /**
+     * Every mutation runs one-at-a-time on this chain.
+     *
+     * Without it, two concurrent `beginSend` calls both read `this.doc.pending === null` before either
+     * durable replace finishes — the guard is an in-memory read that is NOT atomic with the write
+     * across its `await` points. Reviewers reproduced the split: one call fulfils, one rejects, and
+     * the process is left holding `pending.id === "A"` in memory while the disk says `"B"`. Recovery
+     * would then resume the frame on disk while the live emitter retries the other, which breaks the
+     * one thing this file exists to guarantee — that `id` and `E` are frozen and agreed.
+     *
+     * A per-instance chain is sufficient and honest about its scope, and the scope is narrower than it
+     * once claimed: it serializes THIS INSTANCE's callers. It does nothing about a SECOND `EventWal`
+     * on the same file, in this process or another — the chain is per object, so two objects are two
+     * chains and both of them "succeed". That gap was described here as "solved upstream by the
+     * principal-level lock" while no lock was ever acquired. Two things close it now, and neither is
+     * this chain: `acquirePrincipalLock` refuses a second emitter for the principal at start, and
+     * {@link EventWal.assertNotClobbering} refuses a stale handle's write even when it got past that.
+     */
+    private chain;
+    /** Run `op` after every previously-queued mutation, whether they resolved or threw. */
+    private serialize;
+    private constructor();
+    get epoch(): string;
+    /** The principal this WAL was loaded FOR — exposed so a consumer can prove it is holding its own.
+     *  `open()` already refuses a document whose stored principal disagrees, but that check protects
+     *  the FILE, not the caller: an emitter handed the wrong WAL object entirely would sail past it. */
+    get principal(): string;
+    get threadId(): string;
+    /** The bracket machine at the folded position, or `null` when the document cannot say (migrated
+     *  from v1). The two are different facts; see {@link WalDoc.brackets}. */
+    get brackets(): BracketState | null;
+    get frontier(): WalFrontier;
+    get pending(): WalPending | null;
+    /**
+     * Load an existing WAL, or start a virgin one.
+     *
+     * `subjectMayExist` is the caller's honest statement about whether this principal+thread could
+     * already have published. It is NOT a convenience flag: with it true, a missing or empty WAL is a
+     * refusal, because the tip cannot be inferred — agent creds hold no read shape over the subject,
+     * and guessing `E := 0` either CAS-halts forever or appends under a stale expectation. Recovery
+     * from that state is an explicit operator act, never a startup heuristic.
+     */
+    static open(path: string, opts: {
+        space: string;
+        threadId: string;
+        principal: string;
+        subjectMayExist: boolean;
+    }): Promise<EventWal>;
+    private static virgin;
+    /** Transition 1 — record the frame, with `id` and `E` frozen, BEFORE any publish. */
+    beginSend(frame: {
+        id: string;
+        E: number;
+        seq: number;
+        sourceCursor: string;
+        body: Part[];
+        /** The bracket machine AFTER this frame's events — frozen with the frame, promoted on fold. */
+        brackets: BracketState;
+    }): Promise<void>;
+    /**
+     * Transition 2 — a NON-duplicate ack becomes durable before the frontier moves.
+     * A duplicate ack must never reach here; the caller fails loud on one.
+     */
+    recordAck(ackSeq: number): Promise<void>;
+    /** Transition 3 — fold the acked frame into the frontier and clear pending. */
+    fold(): Promise<void>;
+    /**
+     * Transition 4 — a bounded source range that mapped to NOTHING.
+     *
+     * A mapper SUCCESS returning zero events advances the cursor atomically and alone: no
+     * `seq` consumed, no pending written, no publish. A mapper ERROR never advances it. Empty and
+     * failed must not share a path: conflating them turns a parser bug into silently skipped history.
+     */
+    advanceCursorOnly(rangeEnd: string): Promise<void>;
+    /**
+     * Abandonment — explicit, destructive and TOTAL. Mints a new epoch AND resets `seq`,
+     * `lastSubjectSeq` and `sourceCursor` together, reusing the same subject; the new epoch is what
+     * tells a consumer the chain broke. Partial abandonment is not a state: either all four move or
+     * the emitter stays halted. Required after a filtered channel purge, which returns the subject
+     * tip to 0 while the WAL still holds a non-zero `E`, permanently CAS-failing every later publish.
+     */
+    abandon(): Promise<void>;
+    /**
+     * Durable replace: write a sibling temp file, fsync it, then rename over the target. The rename
+     * is what makes a reader see either the whole old document or the whole new one and never a torn
+     * prefix — which is precisely why a zero-byte WAL is treated as corruption rather than as virgin.
+     *
+     * **MODE 0600, AND THE REASON IS NOT TIDINESS: `pending.id` IS A PRE-PUBLICATION SECRET.**
+     * The dedup cache the frozen id is checked against is STREAM-WIDE, so anyone who learns an id
+     * BEFORE its frame is published can pre-seed it and make the real publish come back
+     * `duplicate: true`. The design attributes the safety of that entirely to `randomUUID()` entropy —
+     * which holds only while the id is unguessable AND unread. An id already on the wire is harmless
+     * (that message has landed); the only window where it is dangerous is exactly the window this
+     * file holds it in, between transition 1 and the ack.
+     *
+     * So the residual a reviewer raised as "gated on a local disk read rather than mesh access" is
+     * gated on a read OF THIS FILE. A world-readable WAL would convert a property the design credits
+     * to entropy into one credited to filesystem luck. Under our own rules the attack yields a LOUD
+     * halt rather than silent loss — a duplicate ack on a retry fails loud with the frontier and
+     * cursor unmoved — so this is denial of service, not corruption. Closing it by construction is
+     * cheap enough that naming it as an accepted residual would be the worse trade.
+     */
+    private write;
+    /**
+     * Refuse to replace a document this handle did not read.
+     *
+     * **THE FAILURE THIS EXISTS FOR WAS EXECUTED, NOT IMAGINED.** Two `EventWal` objects were opened
+     * on one file. A ran the full cycle and folded a frontier of `{seq:1, lastSubjectSeq:5}`. B, whose
+     * in-memory document was frozen back at the pending write, then called `recordAck(99)` and
+     * `fold()` — both SUCCEEDED, each replacing the whole file, and the WAL came back up claiming a
+     * durable tip of 99: a subject sequence the broker never assigned. The next publish freezes
+     * `E := 99` against a stream whose real tip is 5, so the emitter either CAS-halts forever or
+     * recovers a frontier that never existed. Nothing about that is loud; it reads as a healthy WAL.
+     *
+     * The per-instance `serialize` chain cannot see it (two instances, two chains) and neither can the
+     * principal lock (B's handle predates any lock B would take, and a lock is not held against a
+     * process's own second object). The guard has to be HERE, on the write, where the two views
+     * finally meet.
+     *
+     * **This is a check, not a transaction, and the difference is stated rather than glossed.** The
+     * read and the `rename` are separate syscalls, so a writer that lands in between is not caught by
+     * this; what is caught is every stale handle — the case that actually occurs, because a stale
+     * handle stays stale for as long as it exists rather than for a syscall's width. The lock is what
+     * keeps a second live writer from starting; this is what keeps one that already exists from
+     * winning.
+     */
+    private assertNotClobbering;
+}
+//# sourceMappingURL=event-wal.d.ts.map

package/dist/event-wal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-wal.d.ts","sourceRoot":"","sources":["../src/event-wal.ts"],"names":[],"mappings":"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"}