@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/resources/Federation.js

@@ -109,7 +109,9 @@ export function noteFederationMergedMemory(recordTable, mergedData) {
  * AdminInstance.ts/AdminDashboard.ts: this is an admin-view endpoint (peers
  * never call it during pairing — FederationPair.post() reads the Instance
  * table directly server-side to hand a peer our identity; this HTTP GET is
- * CLI tooling only).
+ * CLI tooling only). The spoke pair CLI must not GET this path to fill a
+ * missing pair publicKey (flair#822): allowRead is allowAdmin, and get()
+ * find-or-creates an Instance (that would invent a hub row; #839).
  */
 export class FederationInstance extends Resource {
     async allowRead() {
@@ -325,7 +327,11 @@ export class FederationPair extends Resource {
                 console.warn(`[federation] drop_user failed: ${err?.message} — cleanup sweep will retry`);
             }
         }
-        // Return our own identity for the peer to record
+        // Return our own identity for the peer to record. Already
+        // `{ id, publicKey, role }` when an Instance row exists (flair#213).
+        // `instance: null` means the hub has no FederationInstance — that is
+        // #839, not a pair-response-shape bug. The spoke must ERROR, never
+        // store publicKey:"" (flair#822).
         let ourInstance = null;
         try {
             for await (const i of databases.flair.Instance.search()) {

package/dist/resources/Memory.js

@@ -269,9 +269,10 @@ async function runDedupGate(ctx, content) {
     // miss a near-duplicate during that window. Bounded (the re-embed pass is
     // batched and finishes in minutes), self-healing once the pass completes,
     // and a missed dedup is a duplicate row, not data loss — quality, not
-    // correctness. Stage 1 (this PR) doesn't trigger this at all: no re-embed
-    // runs, so there's no mixed-space window until stage 2's separate,
-    // deliberate ops step.
+    // correctness. flair#1073: if that window lasts days (boot cycle marked
+    // embedding-stamp complete without converging), /HealthDetail names the
+    // outstanding migration and that duplicate detection is inactive — do
+    // not treat a long-lived split as this documented transient.
     let embedding = Array.isArray(content.embedding) ? content.embedding : null;
     if (!embedding) {
         try {

package/dist/resources/MemoryBootstrap.js

@@ -19,6 +19,9 @@ import { hybridEnabled } from "./bm25.js";
 import { buildTrustBlock } from "./trust-block.js";
 import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
 import { estimateTokens } from "./token-estimate.js";
+import { initialPosition, ORG_EVENT_STREAM } from "./agent-read-position-lib.js";
+import { defaultReadPositionTable, ensureReadPosition } from "./agent-read-position.js";
+import { catchupSeekTimestamp, isCatchupEligible } from "./org-event-catchup-lib.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -188,11 +191,11 @@ function buildTrustEntry(m, section) {
         : undefined;
     return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
 }
-// flair#1199/#1206 — the default cap on how many org events bootstrap ships.
-// Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
-// #1199) token-charged, so this bounds both the count and the spend; the shared
-// tokenBudget is the harder ceiling (an event that doesn't fit is skipped even
-// under the cap).
+// flair#1199/#1206 — the default DISPLAY cap on how many org events bootstrap
+// ships. Overridable per-request via `maxEvents`. This is no longer a silent
+// drop (flair#931): leftover events set eventsHasMore / eventsRemaining so the
+// caller pages /OrgEventCatchup. Event slots are scarce AND (as of #1199)
+// token-charged; the shared tokenBudget is the harder ceiling.
 const MAX_ORG_EVENTS = 10;
 // ─── Bootstrap scale fix (flair-bootstrap-scale-fix) tunables ───────────────
 //
@@ -440,6 +443,12 @@ export class BootstrapMemories extends Resource {
         // skipped events — never a gap derived from some larger tally, which
         // could imply the existence of rows the caller was not allowed to see.
         let eventsBudgetTruncated = 0;
+        // flair#931 — watermark path. Always present on the response so a
+        // display cap (maxEvents / budget) is never a silent drop: the agent
+        // pages /OrgEventCatchup until drained, then acks.
+        let eventWatermark = null;
+        let eventsHasMore = false;
+        let eventsRemaining = 0;
         const leanMemory = (m, section) => ({
             id: m.id,
             content: m.content,
@@ -1293,28 +1302,27 @@ export class BootstrapMemories extends Resource {
             // dependency — WorkspaceState/OrgEvent/Presence being briefly
             // unavailable must not break bootstrap's core memory context.
         }
-        // --- 5. Recent OrgEvents for this agent ---
+        // --- 5. OrgEvents for this agent (per-agent watermark, flair#931) ---
         try {
-            const eventSince = data?.lastBootAt
-                ? new Date(data.lastBootAt)
-                : new Date(Date.now() - 24 * 3600_000);
-            const eventSinceStr = eventSince.toISOString();
+            // Optional lastBootAt remains a createdAt floor (legacy / probe), never
+            // the primary cursor. Default path is the durable watermark: "now" on
+            // first seen (or FLAIR_CATCHUP_BACKFILL_MS), then position > watermark.
+            // The old 24h window + silent slice(0, 10) is retired as the primary path.
+            const sinceFloor = data?.lastBootAt ? new Date(data.lastBootAt).toISOString() : null;
+            eventWatermark = await ensureReadPosition(defaultReadPositionTable(), agentId, ORG_EVENT_STREAM, initialPosition(), ctx);
+            const seekTs = catchupSeekTimestamp(eventWatermark, sinceFloor);
             const eventResults = [];
-            // Seek the indexed lookback window before materializing events. Keep detail
+            // Seek the indexed floor before materializing events. Keep detail
             // for no-op suppression/dedup even when the response omits it. No limit here:
-            // expiry, targeting, dedup and budget admission must run before the cap.
+            // expiry, targeting, dedup and budget admission must run before the display cap.
             const recentEvents = withDetachedTxn(ctx, () => databases.flair.OrgEvent.search({
-                conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: eventSinceStr }],
+                ...(seekTs
+                    ? { conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: seekTs }] }
+                    : {}),
                 select: ["id", "kind", "summary", "detail", "targetIds", "createdAt", "expiresAt", "scope"],
             }));
             for await (const event of recentEvents) {
-                if (!event.createdAt || event.createdAt < eventSinceStr)
-                    continue;
-                if (event.expiresAt && new Date(event.expiresAt) < new Date())
-                    continue;
-                const targets = event.targetIds;
-                const isRelevant = !targets || targets.length === 0 || targets.includes(agentId);
-                if (!isRelevant)
+                if (!isCatchupEligible(event, { participantId: agentId, after: eventWatermark, since: sinceFloor }))
                     continue;
                 // flair#1200 — suppress zero-row no-op auto-heal migration events at
                 // render. On a healthy store every boot emits a "migration graph-heal
@@ -1365,8 +1373,10 @@ export class BootstrapMemories extends Resource {
             const dedupedEvents = [...eventBySignature.values()]
                 .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
             for (const evt of dedupedEvents) {
-                if (sections.events.length >= eventCap)
-                    break;
+                if (sections.events.length >= eventCap) {
+                    eventsRemaining++;
+                    continue;
+                }
                 // The structured object a connector actually reads (flair#1206). Lean by
                 // default; `detail` (the verbose migration-internals/summary-restating
                 // JSON) only when explicitly requested. Optional fields are omitted when
@@ -1389,6 +1399,7 @@ export class BootstrapMemories extends Resource {
                 // can say so instead of claiming "empty by design" (#1182 contract).
                 if (cost > tokenBudget) {
                     eventsBudgetTruncated++;
+                    eventsRemaining++;
                     continue;
                 }
                 const elapsed = Date.now() - new Date(evt.createdAt).getTime();
@@ -1400,9 +1411,10 @@ export class BootstrapMemories extends Resource {
                 includedEvents.push(structured);
                 tokenBudget -= cost;
             }
+            eventsHasMore = eventsRemaining > 0;
         }
         catch {
-            // non-fatal: OrgEvent table may not exist yet
+            // non-fatal: OrgEvent / AgentReadPosition table may not exist yet
         }
         // flair#1207 — derive the own-memory counters from the unique-id sets so the
         // invariant memoriesIncluded + memoriesTruncated <= memoriesAvailable holds.
@@ -1615,8 +1627,9 @@ export class BootstrapMemories extends Resource {
         const eventsHint = includedEvents.length === 0
             ? (eventsBudgetTruncated > 0
                 ? `No org events fit the token budget: ${eventsBudgetTruncated} relevant event(s) cleared the `
-                    + "lookback window but were budget-truncated. Raise maxTokens to include them."
-                : "No org events in the lookback window were relevant to you (org-wide, or targeted at you) "
+                    + "watermark (or optional lastBootAt floor) but were budget-truncated. Raise maxTokens "
+                    + "or GET /OrgEventCatchup to page the rest."
+                : "No org events after your watermark were relevant to you (org-wide, or targeted at you) "
                     + "after zero-row no-op auto-heal filtering. This container is present-but-empty by design, not dropped.")
             : undefined;
         // teammateFindings: [] — name WHICH legitimate empty this is (no task → no
@@ -1657,6 +1670,9 @@ export class BootstrapMemories extends Resource {
             // delivered. Deduped (#1200) and targetIds-scoped (same set as the prose
             // "## Recent Org Events" lines), so count/charge/delivery all agree.
             events: includedEvents,
+            eventWatermark,
+            eventsHasMore,
+            eventsRemaining,
             ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(predictedHint ? { predictedHint } : {}),
             // flair#1182 (0.44.11) — empty-container hints, present only when the

package/dist/resources/MemoryCandidate.js

@@ -83,12 +83,11 @@ export class MemoryCandidate extends databases.flair.MemoryCandidate {
         return memoryCandidateByIdReadGate.call(this, target, (t) => super.get(t));
     }
     /**
-     * Scope collection reads to the caller's own candidates. This is the
-     * handler `flair rem candidates` reaches via `POST
-     * /MemoryCandidate/search_by_conditions` (src/cli.ts) — the agentId
-     * condition is wrapped as the OUTERMOST `and` block (Relationship.ts's
-     * same "Security Critical" discipline) so a caller-supplied `operator:
-     * "or"` in the request body cannot boolean-inject past the owner scope.
+     * Scope collection reads to the caller's own candidates. Agent-facing
+     * collection reads (`GET /MemoryCandidate`) reach this handler — the agentId
+     * condition is wrapped as the OUTERMOST `and` block (Relationship.ts's same
+     * "Security Critical" discipline) so a caller-supplied `operator: "or"` in
+     * the query cannot boolean-inject past the owner scope.
      */
     async search(query) {
         const ctx = this.getContext?.();

package/dist/resources/OrgEventCatchup.js

@@ -1,24 +1,94 @@
 /**
- * OrgEventCatchup.ts — Custom resource for filtered event retrieval.
+ * OrgEventCatchup.ts — Paginated catch-up against a per-agent watermark.
  *
- * GET /OrgEventCatchup/{participantId}?since=<ISO timestamp>
+ * GET  /OrgEventCatchup/{participantId}?after=<position>&since=<ISO>&limit=50
+ * POST /OrgEventCatchup/{participantId}  { position }
  *
  * Returns events where:
  *   - targetIds includes participantId OR targetIds is empty/null
- *   - createdAt >= since
- * Sorted by createdAt ascending (oldest first for in-order processing).
- * Limit 50 events max.
+ *   - position > after (after defaults to the durable per-agent watermark)
+ *   - optional `since` is an extra createdAt floor, never the primary cursor
+ *
+ * Ordered by position ascending. Page-sized, never silently truncated
+ * (`hasMore` + `nextAfter` — the caller pages until drained). Watermark
+ * advances on ack (POST), not on read — at-least-once; consumers must be
+ * idempotent (flair#931).
  */
 import { Resource, databases } from "harper";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { initialPosition, ORG_EVENT_STREAM, parsePageSize, positionAfterTimestamp, } from "./agent-read-position-lib.js";
+import { advanceReadPosition, defaultReadPositionTable, ensureReadPosition, getReadPosition, } from "./agent-read-position.js";
+import { catchupSeekTimestamp, collectCatchupEvents, pageCatchupEvents, } from "./org-event-catchup-lib.js";
+function queryValue(pathInfo, name) {
+    if (typeof pathInfo !== "object" || pathInfo === null)
+        return null;
+    return pathInfo.conditions?.find((c) => c.attribute === name)?.value ?? null;
+}
+function pathParticipantId(pathInfo, resource) {
+    return ((typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
+        (typeof pathInfo === "string" ? pathInfo : null) ??
+        resource.getId?.() ??
+        null);
+}
+function ownerDenied(auth, participantId) {
+    if (auth.kind === "anonymous")
+        return true;
+    if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== participantId)
+        return true;
+    return false;
+}
+function forbidden() {
+    return new Response(JSON.stringify({ error: "forbidden: can only fetch events for yourself" }), { status: 403, headers: { "Content-Type": "application/json" } });
+}
+async function resolveAfter(participantId, pathInfo, ctx) {
+    const afterParam = queryValue(pathInfo, "after");
+    const since = queryValue(pathInfo, "since");
+    if (since) {
+        const sinceDate = new Date(since);
+        if (isNaN(sinceDate.getTime())) {
+            throw new Response(JSON.stringify({ error: "invalid since timestamp" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+    }
+    const table = defaultReadPositionTable();
+    const watermark = await getReadPosition(table, participantId, ORG_EVENT_STREAM, ctx);
+    if (afterParam != null && afterParam !== "") {
+        return { after: afterParam, watermark, since };
+    }
+    if (watermark) {
+        return { after: watermark, watermark, since };
+    }
+    if (since) {
+        // Legacy explicit since, no watermark yet — do not invent a "now" floor
+        // that would hide the window the caller asked for.
+        return { after: positionAfterTimestamp(since), watermark: null, since };
+    }
+    const created = await ensureReadPosition(table, participantId, ORG_EVENT_STREAM, initialPosition(), ctx);
+    return { after: created, watermark: created, since: null };
+}
+async function searchOrgEvents(seekTs) {
+    const table = databases.flair?.OrgEvent;
+    if (!table?.search) {
+        async function* empty() { }
+        return empty();
+    }
+    const query = seekTs
+        ? {
+            conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: seekTs }],
+        }
+        : undefined;
+    return table.search(query);
+}
 export class OrgEventCatchup extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may catch up; participant scoping is in
-    // get(). Uses getContext().request — the reliable v5 path (this.request is not
-    // populated on Harper v5 Resources).
+    // get()/post(). Uses getContext().request — the reliable v5 path (this.request
+    // is not populated on Harper v5 Resources).
     async allowRead() {
         return allowVerified(this.getContext?.());
     }
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
     // HarperDB calls get(pathInfo, context) where pathInfo is the URL segment after /OrgEventCatchup/
     async get(pathInfo) {
         // Harper v5 does not populate this.request on Resource subclasses —
@@ -27,55 +97,64 @@ export class OrgEventCatchup extends Resource {
         // any).request` read was always undefined, so the ownership check below
         // never ran — fail-open cross-agent read).
         const auth = await resolveAgentAuth(this.getContext?.());
-        // Harper routes /OrgEventCatchup/{id} with pathInfo.id as the path segment
-        const participantId = (typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
-            (typeof pathInfo === "string" ? pathInfo : null) ??
-            this.getId?.() ??
-            null;
+        const ctx = this.getContext?.();
+        const participantId = pathParticipantId(pathInfo, this);
         if (!participantId) {
             return new Response(JSON.stringify({ error: "participantId required in path: GET /OrgEventCatchup/{participantId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
         // Auth: internal calls and admins pass unfiltered; a verified agent may only
         // fetch its own catchup feed; anonymous is denied. allowRead() already
         // blocks anonymous HTTP, but this handler must fail closed on its own too.
-        if (auth.kind === "anonymous") {
-            return new Response(JSON.stringify({ error: "forbidden: can only fetch events for yourself" }), { status: 403, headers: { "Content-Type": "application/json" } });
-        }
-        if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== participantId) {
-            return new Response(JSON.stringify({ error: "forbidden: can only fetch events for yourself" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        if (ownerDenied(auth, participantId))
+            return forbidden();
+        let resolved;
+        try {
+            resolved = await resolveAfter(participantId, pathInfo, ctx);
         }
-        // Harper parses query params into pathInfo.conditions array:
-        // e.g. ?since=value → conditions: [{attribute:"since", value:"...", comparator:"equals"}]
-        // pathInfo.id is the URL path segment (participantId).
-        const since = (typeof pathInfo === "object" && pathInfo !== null
-            ? pathInfo.conditions?.find((c) => c.attribute === "since")?.value ?? null
-            : null);
-        if (!since) {
-            return new Response(JSON.stringify({ error: "since query parameter required (ISO timestamp)" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        catch (err) {
+            if (err instanceof Response)
+                return err;
+            throw err;
         }
-        const sinceDate = new Date(since);
-        if (isNaN(sinceDate.getTime())) {
-            return new Response(JSON.stringify({ error: "invalid since timestamp" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        const pageSize = parsePageSize(queryValue(pathInfo, "limit"));
+        const seekTs = catchupSeekTimestamp(resolved.after, resolved.since);
+        const ordered = await collectCatchupEvents(await searchOrgEvents(seekTs), {
+            participantId,
+            after: resolved.after,
+            since: resolved.since,
+        });
+        const paged = pageCatchupEvents(ordered, resolved.after, pageSize);
+        return {
+            events: paged.page,
+            watermark: resolved.watermark,
+            after: resolved.after,
+            nextAfter: paged.nextAfter,
+            hasMore: paged.hasMore,
+            pageSize,
+        };
+    }
+    /**
+     * Advance-on-ack. Body: `{ position }` (the last delivered event's
+     * `position`, or `nextAfter` from a drained page). Monotonic.
+     */
+    async post(content, pathInfo) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        const ctx = this.getContext?.();
+        const participantId = pathParticipantId(pathInfo, this) ??
+            (content && typeof content === "object" ? content.participantId ?? content.agentId : null) ??
+            null;
+        if (!participantId) {
+            return new Response(JSON.stringify({ error: "participantId required in path: POST /OrgEventCatchup/{participantId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // Query all OrgEvents and filter in-memory
-        const results = [];
-        for await (const event of databases.flair.OrgEvent.search()) {
-            // Filter by createdAt >= since
-            if (!event.createdAt || event.createdAt < since)
-                continue;
-            // Filter by targetIds: includes participantId OR empty/null
-            const targets = event.targetIds;
-            const isTargeted = !targets || targets.length === 0 || targets.includes(participantId);
-            if (!isTargeted)
-                continue;
-            // Skip expired events
-            if (event.expiresAt && new Date(event.expiresAt) < new Date())
-                continue;
-            results.push(event);
+        if (ownerDenied(auth, participantId))
+            return forbidden();
+        const position = content && typeof content === "object"
+            ? String(content.position ?? content.ackThrough ?? "")
+            : "";
+        if (!position) {
+            return new Response(JSON.stringify({ error: "position required to ack catch-up (advance-on-ack)" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // Sort ascending by createdAt (oldest first)
-        results.sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
-        // Limit to 50
-        return results.slice(0, 50);
+        const result = await advanceReadPosition(defaultReadPositionTable(), participantId, ORG_EVENT_STREAM, position, ctx);
+        return { participantId, stream: ORG_EVENT_STREAM, ...result };
     }
 }

package/dist/resources/agent-read-position-lib.js

@@ -0,0 +1,83 @@
+/**
+ * agent-read-position-lib.ts — pure per-agent read-position (watermark) helpers.
+ *
+ * This is the reusable catch-up floor (flair#931), not OrgEvent-table plumbing.
+ * OrgEventCatchup is the first consumer; light-comms (#1583) inherits the same
+ * (agentId, stream) → position primitive when the board lands.
+ *
+ * Position is a monotonic total order, NOT a wall-clock `since`:
+ *   `${createdAt}\t${id}`
+ * ISO-8601 timestamps sort lexicographically; `id` breaks same-ms ties so a
+ * sort without a tie-break cannot drop an event. Compare with `<` / `>`.
+ *
+ * Harper-free so unit tests can pin encoding, paging, and init without a store.
+ */
+import { compareKey } from "./sort-comparators.js";
+/** First shipped stream. Additional streams (message-board, …) are additive. */
+export const ORG_EVENT_STREAM = "org-event";
+export const POSITION_SEP = "\t";
+export const DEFAULT_CATCHUP_PAGE_SIZE = 50;
+export const MAX_CATCHUP_PAGE_SIZE = 500;
+/** Env: bounded backfill on first watermark. Unset = 24h (retired window, once). `0` = "now". */
+export const CATCHUP_BACKFILL_MS_ENV = "FLAIR_CATCHUP_BACKFILL_MS";
+export const DEFAULT_CATCHUP_BACKFILL_MS = 24 * 3600_000;
+export function readPositionId(agentId, stream) {
+    return `${agentId}:${stream}`;
+}
+/** Total-order position for a record that has `createdAt` + `id`. */
+export function recordPosition(record) {
+    return `${record.createdAt ?? ""}${POSITION_SEP}${record.id ?? ""}`;
+}
+/** Exclusive cursor just after every record at-or-before this ISO timestamp. */
+export function positionAfterTimestamp(iso) {
+    return `${iso}${POSITION_SEP}`;
+}
+export function comparePosition(a, b) {
+    return compareKey(a, b);
+}
+/** Leading createdAt of a position, or null if the cursor has no timestamp. */
+export function createdAtFloorFromPosition(position) {
+    if (!position)
+        return null;
+    const sep = position.indexOf(POSITION_SEP);
+    const ts = sep === -1 ? position : position.slice(0, sep);
+    return ts || null;
+}
+export function laterTimestamp(a, b) {
+    if (!a)
+        return b || null;
+    if (!b)
+        return a;
+    return a >= b ? a : b;
+}
+export function parseBackfillMs(raw = process.env[CATCHUP_BACKFILL_MS_ENV]) {
+    if (raw === undefined || raw === "")
+        return DEFAULT_CATCHUP_BACKFILL_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_CATCHUP_BACKFILL_MS;
+    return n;
+}
+/**
+ * Sane first watermark. Default a 24h bounded backfill (the retired bootstrap
+ * window, applied once); `FLAIR_CATCHUP_BACKFILL_MS=0` is Flint's "now"
+ * (fresh agent does not replay history). After init the durable position governs.
+ */
+export function initialPosition(nowMs = Date.now(), backfillMs = parseBackfillMs()) {
+    const floor = Math.max(0, nowMs - Math.max(0, backfillMs));
+    return positionAfterTimestamp(new Date(floor).toISOString());
+}
+export function parsePageSize(raw, fallback = DEFAULT_CATCHUP_PAGE_SIZE, max = MAX_CATCHUP_PAGE_SIZE) {
+    const n = typeof raw === "number" ? raw : raw != null && raw !== "" ? Number(raw) : fallback;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(1, Math.floor(n)));
+}
+/** Exclusive `after`, already-sorted by position ascending. Never silent-truncates. */
+export function pageAfter(ordered, after, pageSize) {
+    const slice = ordered.filter((row) => comparePosition(row.position, after) > 0);
+    const hasMore = slice.length > pageSize;
+    const page = hasMore ? slice.slice(0, pageSize) : slice;
+    const nextAfter = page.length > 0 ? page[page.length - 1].position : after;
+    return { page, hasMore, nextAfter };
+}

package/dist/resources/agent-read-position.js

@@ -0,0 +1,120 @@
+/**
+ * agent-read-position.ts — durable per-agent read-position (watermark) store.
+ *
+ * Storage + monotonic advance for resources/agent-read-position-lib.ts.
+ * Owner-scoping lives in the HTTP resource / catch-up handler; this module
+ * is the internal contract for raw table access (Harper table I/O bypasses
+ * Resource rules).
+ *
+ * Advance is at-least-once (advance-on-ack): only move forward, never back.
+ * Same-process concurrent advances serialize on a per-id promise tail so two
+ * acks cannot clobber a higher watermark with a lower one.
+ */
+import { databases } from "harper";
+import { withDetachedTxn } from "./table-helpers.js";
+import { comparePosition, readPositionId } from "./agent-read-position-lib.js";
+export function defaultReadPositionTable() {
+    try {
+        const table = databases.flair?.AgentReadPosition;
+        if (!table || typeof table.get !== "function" || typeof table.put !== "function")
+            return null;
+        return table;
+    }
+    catch {
+        return null;
+    }
+}
+const tails = new Map();
+function enqueue(id, work) {
+    const prev = tails.get(id) ?? Promise.resolve();
+    const next = prev.then(work, work);
+    tails.set(id, next);
+    return next.finally(() => {
+        if (tails.get(id) === next)
+            tails.delete(id);
+    });
+}
+async function readRow(table, id, ctx) {
+    try {
+        const row = await withDetachedTxn(ctx, () => table.get(id));
+        return row && typeof row.position === "string" ? row : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function getReadPosition(table, agentId, stream, ctx) {
+    if (!table)
+        return null;
+    const row = await readRow(table, readPositionId(agentId, stream), ctx);
+    return row?.position ?? null;
+}
+/**
+ * Return the stored watermark, creating it at `initial` when absent.
+ * Concurrent first-writers serialize; the stored row wins if one appears.
+ */
+export async function ensureReadPosition(table, agentId, stream, initial, ctx, now = () => new Date().toISOString()) {
+    if (!table)
+        return initial;
+    const id = readPositionId(agentId, stream);
+    return enqueue(id, async () => {
+        const existing = await readRow(table, id, ctx);
+        if (existing)
+            return existing.position;
+        const row = {
+            id,
+            agentId,
+            stream,
+            position: initial,
+            updatedAt: now(),
+        };
+        try {
+            await withDetachedTxn(ctx, () => table.put(row));
+        }
+        catch {
+            const raced = await readRow(table, id, ctx);
+            if (raced)
+                return raced.position;
+            return initial;
+        }
+        return initial;
+    });
+}
+/**
+ * Monotonic advance. A lower-or-equal ack is a no-op. Serialized per
+ * (agent, stream) so concurrent catch-up acks cannot regress the watermark.
+ */
+export async function advanceReadPosition(table, agentId, stream, position, ctx, now = () => new Date().toISOString()) {
+    if (!position) {
+        const current = table ? await getReadPosition(table, agentId, stream, ctx) : null;
+        return { position: current ?? "", advanced: false };
+    }
+    if (!table)
+        return { position, advanced: false };
+    const id = readPositionId(agentId, stream);
+    return enqueue(id, async () => {
+        const existing = await readRow(table, id, ctx);
+        const current = existing?.position ?? "";
+        if (current && comparePosition(position, current) <= 0) {
+            return { position: current, advanced: false };
+        }
+        const row = {
+            id,
+            agentId,
+            stream,
+            position,
+            updatedAt: now(),
+        };
+        try {
+            await withDetachedTxn(ctx, () => table.put(row));
+        }
+        catch {
+            const raced = await readRow(table, id, ctx);
+            if (raced && comparePosition(raced.position, position) >= 0) {
+                return { position: raced.position, advanced: false };
+            }
+            return { position: current || position, advanced: false };
+        }
+        return { position, advanced: true };
+    });
+}