brane 0.1.1 → 0.3.1

package/dist/db/events.js

@@ -0,0 +1,152 @@
+/** Convert a raw DB row to a clean API event (parse JSON, omit nulls) */
+function toApiEvent(row) {
+    const evt = {
+        seq: row.seq,
+        time: row.time,
+        type: row.type,
+    };
+    if (row.content)
+        evt.content = row.content;
+    if (row.content_type)
+        evt.content_type = row.content_type;
+    if (row.source)
+        evt.source = row.source;
+    if (row.re) {
+        try {
+            evt.re = JSON.parse(row.re);
+        }
+        catch { /* ignore */ }
+    }
+    if (row.payloads) {
+        try {
+            evt.payloads = JSON.parse(row.payloads);
+        }
+        catch { /* ignore */ }
+    }
+    if (row.meta) {
+        try {
+            evt.meta = JSON.parse(row.meta);
+        }
+        catch { /* ignore */ }
+    }
+    return evt;
+}
+export function appendEvent(db, narrativeId, type, opts = {}) {
+    const maxSeqRow = db
+        .prepare("SELECT MAX(seq) as max_seq FROM events WHERE narrative_id = ?")
+        .get(narrativeId);
+    const seq = (maxSeqRow.max_seq ?? 0) + 1;
+    const time = Date.now();
+    const re = opts.re && opts.re.length > 0 ? JSON.stringify(opts.re) : null;
+    const payloads = opts.payloads && opts.payloads.length > 0 ? JSON.stringify(opts.payloads) : null;
+    const meta = opts.meta ? JSON.stringify(opts.meta) : null;
+    db.prepare(`INSERT INTO events (narrative_id, seq, time, type, content, content_type, source, re, payloads, meta)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(narrativeId, seq, time, type, opts.content ?? null, opts.content_type ?? null, opts.source ?? null, re, payloads, meta);
+    return toApiEvent({
+        narrative_id: narrativeId,
+        seq,
+        time,
+        type,
+        content: opts.content ?? null,
+        content_type: opts.content_type ?? null,
+        source: opts.source ?? null,
+        re,
+        payloads,
+        meta,
+    });
+}
+export function readEventsSince(db, narrativeId, sinceSeq, limit) {
+    const sql = limit !== undefined
+        ? `SELECT * FROM events WHERE narrative_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`
+        : `SELECT * FROM events WHERE narrative_id = ? AND seq > ? ORDER BY seq ASC`;
+    const params = limit !== undefined
+        ? [narrativeId, sinceSeq, limit]
+        : [narrativeId, sinceSeq];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(toApiEvent);
+}
+export function readEventsBefore(db, narrativeId, beforeSeq, limit) {
+    const rows = db.prepare(`SELECT * FROM events WHERE narrative_id = ? AND seq < ? ORDER BY seq DESC LIMIT ?`).all(narrativeId, beforeSeq, limit);
+    // Reverse to return in ascending seq order
+    rows.reverse();
+    return rows.map(toApiEvent);
+}
+/**
+ * The events with these exact seqs, ascending — an indexed lookup rather than a
+ * scan, for the caller that already knows which rows it wants. `src/export.ts`
+ * uses it for an excerpt: exporting two messages out of ten thousand should
+ * cost two rows, not ten thousand.
+ *
+ * Chunked because SQLite bounds the number of bound parameters in one
+ * statement, and a selection has no ceiling imposed on it anywhere else.
+ */
+export function readEventsBySeqs(db, narrativeId, seqs) {
+    if (seqs.length === 0)
+        return [];
+    const CHUNK = 500;
+    const rows = [];
+    for (let i = 0; i < seqs.length; i += CHUNK) {
+        const chunk = seqs.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        rows.push(...db
+            .prepare(`SELECT * FROM events WHERE narrative_id = ? AND seq IN (${placeholders}) ORDER BY seq ASC`)
+            .all(narrativeId, ...chunk));
+    }
+    // Chunks are each ascending; a multi-chunk read has to be sorted as a whole.
+    rows.sort((a, b) => a.seq - b.seq);
+    return rows.map(toApiEvent);
+}
+/**
+ * Flexible event query supporting after (lower bound), before (upper bound),
+ * and tail (last N). All bounds are exclusive. Results always in ascending
+ * seq order.
+ *
+ * Combinations:
+ * - {} → all events (like after: 0)
+ * - { after: N } → events where seq > N
+ * - { before: N } → events where seq < N
+ * - { after: A, before: B } → events where seq > A AND seq < B
+ * - { tail: N } → last N events
+ * - { tail: N, before: B } → last N events where seq < B (backward pagination)
+ * - { after: A, tail: N } → last N events where seq > A
+ * - { after: A, before: B, tail: N } → last N events in range (A, B)
+ */
+export function readEvents(db, narrativeId, opts) {
+    const { after, before, tail } = opts;
+    const conditions = ["narrative_id = ?"];
+    const params = [narrativeId];
+    if (after !== undefined && after > 0) {
+        conditions.push("seq > ?");
+        params.push(after);
+    }
+    if (before !== undefined) {
+        conditions.push("seq < ?");
+        params.push(before);
+    }
+    const where = conditions.join(" AND ");
+    if (tail !== undefined) {
+        if (tail <= 0)
+            return [];
+        // Fetch last N matching rows (DESC), then reverse for ASC order
+        const sql = `SELECT * FROM events WHERE ${where} ORDER BY seq DESC LIMIT ?`;
+        const rows = db.prepare(sql).all(...params, tail);
+        rows.reverse();
+        return rows.map(toApiEvent);
+    }
+    const sql = `SELECT * FROM events WHERE ${where} ORDER BY seq ASC`;
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(toApiEvent);
+}
+export function getMinSeq(db, narrativeId) {
+    const row = db
+        .prepare("SELECT MIN(seq) as min_seq FROM events WHERE narrative_id = ?")
+        .get(narrativeId);
+    return row.min_seq ?? 0;
+}
+export function getMaxSeq(db, narrativeId) {
+    const row = db
+        .prepare("SELECT MAX(seq) as max_seq FROM events WHERE narrative_id = ?")
+        .get(narrativeId);
+    return row.max_seq ?? 0;
+}
+//# sourceMappingURL=events.js.map

package/dist/db/mentions.js

@@ -0,0 +1,179 @@
+/** The mention ledger: who was addressed, from where, and what became of it.
+ *
+ *  Two kinds of state share a row, on purpose.
+ *
+ *  The **mention** — `mentioned_nid`, `src_narrative`, `src_seq`, `author`,
+ *  `time` — is derived data. A re-scan of the event log reproduces it exactly,
+ *  because `UNIQUE (mentioned_nid, src_narrative, src_seq)` makes a second
+ *  insert a no-op. Rebuild freely, but only additively (see the schema
+ *  comment: rowids are stable and the row carries state).
+ *
+ *  **`sent_at` and `seen_at`** are not derived from anything. They record what
+ *  passed between the daemon and one agent, which no amount of re-reading the
+ *  log can recompute, and they answer two different questions:
+ *
+ *    `sent_at` — handed over. Governs whether a parked `listen` resolves now,
+ *    so a mention wakes an agent exactly once and can't spin.
+ *
+ *    `seen_at` — demonstrably attended to, evidenced by the agent reading the
+ *    narrative the mention was written in. Delivery alone doesn't set it: a
+ *    frame can arrive and still go unnoticed — buried in a long result, lost
+ *    to compaction, or simply not acted on. So a delivered-but-unread mention
+ *    keeps reappearing in the receipt.
+ *
+ *  Both live on the row rather than as a high-water mark per narrative,
+ *  because acknowledgment is per *source*. Reading narrative B says nothing
+ *  about a mention written in C, and a scalar watermark over a shared id space
+ *  settles every lower id regardless of origin — silently marking unread
+ *  mentions read. NULL → timestamp also makes monotonicity structural: there
+ *  is no value that could rewind.
+ */
+/** Inserts one row per mentioned nid; returns the nids *newly* recorded.
+ *
+ *  The return value is the rising edge, and callers use it to decide whom to
+ *  wake. A re-scan of an event already in the ledger returns `[]` and wakes
+ *  nobody, which is what makes a backfill safe to run against live
+ *  narratives. */
+export function recordMentions(db, input) {
+    const stmt = db.prepare(`INSERT OR IGNORE INTO mentions (mentioned_nid, src_narrative, src_seq, author, time)
+     VALUES (?, ?, ?, ?, ?)`);
+    const fresh = [];
+    for (const nid of input.mentionedNids) {
+        const info = stmt.run(nid, input.srcNarrative, input.srcSeq, input.author, input.time);
+        if (info.changes === 1)
+            fresh.push(nid);
+    }
+    return fresh;
+}
+const SELECT_ROWS = `
+  SELECT m.id, m.src_narrative AS src, m.src_seq AS seq, m.author, m.time,
+         n.brane_id AS src_brane
+  FROM mentions m
+  LEFT JOIN narratives n ON n.id = m.src_narrative
+`;
+function toRows(raw, ownBrane) {
+    return raw.map((r) => ({
+        id: r.id,
+        src: r.src,
+        seq: r.seq,
+        author: r.author,
+        time: r.time,
+        // Stamped only when it differs, so the common case stays quiet and a
+        // cross-brane mention is legible rather than spooky.
+        ...(r.src_brane && r.src_brane !== ownBrane ? { brane_id: r.src_brane } : {}),
+    }));
+}
+/** Whether a mention is waiting that this agent has not been woken for.
+ *
+ *  This is the listen predicate, and it reads `sent_at` — not `seen_at`. An
+ *  unread mention must keep appearing in receipts without re-waking the agent
+ *  every time it parks. */
+export function hasUnsentMentions(db, nid) {
+    return (db
+        .prepare("SELECT 1 FROM mentions WHERE mentioned_nid = ? AND sent_at IS NULL LIMIT 1")
+        .get(nid) !== undefined);
+}
+/** What the agent is still owed: everything it hasn't demonstrably read.
+ *
+ *  `total` counts all of them; `rows` is the capped slice actually shown. The
+ *  remainder stays owed and surfaces in later receipts — it just doesn't cost
+ *  another wake, because `markSent` covers every pending row, not only the
+ *  ones displayed. */
+export function pendingMentions(db, nid, limit, ownBrane) {
+    const { total } = db
+        .prepare("SELECT COUNT(*) AS total FROM mentions WHERE mentioned_nid = ? AND seen_at IS NULL")
+        .get(nid);
+    if (!total)
+        return { rows: [], total: 0 };
+    const raw = db
+        .prepare(`${SELECT_ROWS} WHERE m.mentioned_nid = ? AND m.seen_at IS NULL ORDER BY m.id DESC LIMIT ?`)
+        .all(nid, limit);
+    // Newest first out of the query so the cap keeps the most recent; ascending
+    // on the way out so the agent reads them in the order they happened.
+    return { rows: toRows(raw.reverse(), ownBrane), total };
+}
+/** Every mention of this narrative, capped — regardless of either mark, and
+ *  moving neither.
+ *
+ *  This is the recovery surface. Delivery is at-most-once (a tool result can
+ *  be dropped by a socket that closes mid-flight), so "settled" must never
+ *  mean "unreachable". An agent that suspects it missed something, or that has
+ *  restarted with no memory of its cursor, reads here. */
+export function allMentions(db, nid, limit, ownBrane) {
+    const raw = db
+        .prepare(`${SELECT_ROWS} WHERE m.mentioned_nid = ? ORDER BY m.id DESC LIMIT ?`)
+        .all(nid, limit);
+    return toRows(raw.reverse(), ownBrane);
+}
+/** Records that everything currently owed has been handed over.
+ *
+ *  Covers every pending row, including any the receipt's cap left out —
+ *  otherwise the uncapped remainder would re-wake the agent the moment it
+ *  parked again, which is the storm the cap exists to prevent. */
+export function markSent(db, nid, now = Date.now()) {
+    db.prepare("UPDATE mentions SET sent_at = ? WHERE mentioned_nid = ? AND sent_at IS NULL").run(now, nid);
+}
+/** Which narratives each of these events mentions.
+ *
+ *  Keyed `"<src>:<seq>"`, and present only for events that mention someone —
+ *  an event with no mentions has no entry, so annotating a batch adds nothing
+ *  to the common case. Lets a returned event say what it addresses, right
+ *  where the agent reads it, rather than only in a separate receipt. */
+export function mentionsInEvents(db, delivered) {
+    const out = {};
+    const stmt = db.prepare("SELECT src_seq, mentioned_nid FROM mentions WHERE src_narrative = ? AND src_seq = ?");
+    for (const [src, seqs] of Object.entries(delivered)) {
+        for (const seq of seqs) {
+            for (const row of stmt.all(src, seq)) {
+                (out[`${src}:${row.src_seq}`] ??= []).push(row.mentioned_nid);
+            }
+        }
+    }
+    return out;
+}
+/** Marks mentions read because the agent was handed the very events carrying
+ *  them — the acknowledgment that cannot be faked.
+ *
+ *  Interpreting a mention means going and looking at its source, and an agent
+ *  does that by naming the narrative in the cursor it already passes to
+ *  `listen`/`narrate`:
+ *
+ *      { "after": { "self": 42, "claude-4c7289d1": 17 } }
+ *
+ *  So the evidence and the attention are the same act. An explicit ack tool
+ *  would be weaker: an agent can call one reflexively without looking, but it
+ *  cannot receive a narrative's events without them landing in its context.
+ *
+ *  `delivered` maps narrative id → the seqs actually returned, **not** the
+ *  cursor bound. Those differ: `before` truncates a range, and `tail: N`
+ *  returns the last N events while skipping everything in between. Settling on
+ *  `seq > after` would mark mentions read that the read never showed — the
+ *  silent drop this whole mechanism exists to prevent. Keys arrive already
+ *  resolved ("self" → the real nid), and the agent's own narrative is skipped:
+ *  reading your own log is not evidence you looked at someone else's.
+ *
+ *  Returns how many were acknowledged, for logging. */
+export function ackMentionsByRead(db, nid, delivered, now = Date.now()) {
+    const stmt = db.prepare(`UPDATE mentions SET seen_at = ?
+     WHERE mentioned_nid = ? AND src_narrative = ? AND src_seq = ? AND seen_at IS NULL`);
+    let count = 0;
+    for (const [src, seqs] of Object.entries(delivered)) {
+        if (src === nid)
+            continue;
+        for (const seq of seqs)
+            count += stmt.run(now, nid, src, seq).changes;
+    }
+    return count;
+}
+/** The explicit escape hatch: "I've seen these and I am not going to read
+ *  those narratives."
+ *
+ *  Without it, a mention an agent has rightly judged irrelevant reappears in
+ *  every receipt forever. Deliberately a parameter on `listen` rather than a
+ *  fourth tool — one call, no new vocabulary. */
+export function dismissMentions(db, nid, now = Date.now()) {
+    return db
+        .prepare("UPDATE mentions SET seen_at = ? WHERE mentioned_nid = ? AND seen_at IS NULL")
+        .run(now, nid).changes;
+}
+//# sourceMappingURL=mentions.js.map