@astrosheep/square 0.3.69 → 0.3.71

package/dist/views.js

@@ -1,14 +1,25 @@
-import { formatActivityId, parseActivityId, replayLandedAudiences } from './square-core.js';
-import { deliveryDelta, directedPeerSays } from './activity-feed.js';
-import { coreActivities, coreParticipants, coreStatus, resolveKnownName } from './decisions.js';
-import { deriveDeliveryModel, isActivitySeen } from './delivery.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
+import { compareParticipantActivity, coreParticipants, resolveKnownName, unreadActivitySummaries } from './decisions.js';
 import { SquareError, nameKey } from './model.js';
-import { countSays, currentHold, foldedState, inSquareCount, isCurrentlyJoined, presenceAnchor, resolveRosterName, rosterNames, watchTerminalStatus } from './runtime.js';
+import { inSquareCount, readCursor, rosterNames } from './runtime.js';
+import { perceiveActivity } from './perception-projection.js';
+import { compileSearchPattern } from './search.js';
+const PAGE_SIZE = 100;
+export const HISTORY_DEFAULT_LIMIT = 10;
+export const HISTORY_MAX_LIMIT = 100;
+const STATUS_HERE_WINDOW_MS = 30 * 60_000;
+const PRESENCE_WINDOW_MS = 8 * 60 * 60_000;
+export const NON_READ = ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore'];
+const ARCHIVE = new Set(['join', 'done', 'say', 'hold', 'resume']);
 /** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
 export function toPublicActivity(stored) {
     if (stored.kind === 'read' || stored.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
-    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor, ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}), ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}), mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}), ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
+    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
+        ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
+        ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
+        mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
+        ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
 export function parseRequiredActivityId(id) {
     const index = parseActivityId(id);
@@ -16,97 +27,216 @@ export function parseRequiredActivityId(id) {
         throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
     return index;
 }
-function historyOptions(query) {
+/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+export function selectHistory(facts, query, limit, kinds) {
     if (query.before !== undefined && query.after !== undefined)
         throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
     const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
     const beforeIndex = query.before === undefined ? undefined : parseRequiredActivityId(query.before);
-    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.fixed === undefined ? {} : { fixed: query.fixed }), ...(query.mention === undefined ? {} : { mention: query.mention }), ...(afterIndex === undefined ? {} : { afterIndex }), ...(beforeIndex === undefined ? {} : { beforeIndex }), order: 'asc' };
-}
-function selectHistory(stored, query) {
-    let selected = stored.filter((activity) => activity.kind !== 'read');
-    if (query.limit !== undefined) {
-        if (!Number.isSafeInteger(query.limit) || query.limit < 1)
-            throw new SquareError('invalid_args', 'History limit must be a positive integer');
-        selected = query.after === undefined ? selected.slice(-query.limit) : selected.slice(0, query.limit);
+    const actors = (query.from ?? []).map((name) => resolveKnownName(facts, name));
+    const recipient = query.mention == null ? undefined : resolveKnownName(facts, query.mention);
+    const pattern = query.grep ?? query.fixed;
+    const search = pattern === undefined || pattern === '' ? undefined : compileSearchPattern(pattern, query.grep === undefined);
+    if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1))
+        throw new SquareError('invalid_args', 'History limit must be a positive integer');
+    const filter = {
+        ...(actors.length === 0 ? {} : { actors }), afterIndex, beforeIndex, afterAt: query.since,
+        ...(query.at?.length ? { indexes: facts.contextIndexes(query.at.map(parseRequiredActivityId), query.contextBefore ?? 0, query.contextAfter ?? 0) } : {}),
+        kinds: search === undefined ? kinds : ['say', 'done'],
+    };
+    let selected, totalMatches, publicBefore, publicAfter;
+    if (recipient === undefined && search === undefined && limit !== null && limit <= PAGE_SIZE) {
+        selected = facts.activityHeads(filter, { edge: afterIndex === undefined ? 'newest' : 'oldest', limit }).items;
+        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+        const publicFilter = { ...filter, kinds: [...ARCHIVE] };
+        totalMatches = facts.activityCount(filter);
+        publicBefore = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, beforeIndex: publicHeads[0].index }) > 0;
+        publicAfter = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, afterIndex: publicHeads.at(-1).index }) > 0;
+    }
+    else {
+        const page = [];
+        totalMatches = 0;
+        let firstPublic = Infinity, lastPublic = -1, cursor = afterIndex ?? -1;
+        while (true) {
+            const source = recipient === undefined
+                ? facts.activityHeads({ ...filter, afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE })
+                : facts.directed(recipient, { afterIndex: cursor, beforeIndex }, { edge: 'oldest', limit: PAGE_SIZE });
+            const heads = recipient === undefined ? source.items : source.items.length === 0 ? []
+                : facts.activityHeads({ ...filter, indexes: source.items.map((head) => head.index).filter((index) => filter.indexes === undefined || filter.indexes.includes(index)) }, { edge: 'oldest', limit: PAGE_SIZE }).items;
+            const matches = search === undefined ? undefined : new Set(facts.activities(heads.map((head) => head.index)).filter((act) => [formatActivityId(act.index), act.actor ?? '', 'body' in act ? act.body ?? '' : ''].some((field) => search.test(field))).map((act) => act.index));
+            for (const head of heads) {
+                if (matches !== undefined && !matches.has(head.index))
+                    continue;
+                totalMatches++;
+                if (ARCHIVE.has(head.kind)) {
+                    firstPublic = Math.min(firstPublic, head.index);
+                    lastPublic = head.index;
+                }
+                if (limit === null || afterIndex === undefined || page.length < limit)
+                    page.push(head);
+                if (limit !== null && page.length > limit)
+                    page.shift();
+            }
+            if (!source.hasMore)
+                break;
+            cursor = source.items.at(-1).index;
+        }
+        selected = page;
+        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+        publicBefore = publicHeads.length > 0 && firstPublic < publicHeads[0].index;
+        publicAfter = publicHeads.length > 0 && lastPublic > publicHeads.at(-1).index;
     }
-    return query.order === 'desc' ? selected.reverse() : selected;
+    const activities = [...facts.activities(selected.map((head) => head.index))];
+    if (query.order === 'desc')
+        activities.reverse();
+    const visibleActivities = activities.filter((activity) => ARCHIVE.has(activity.kind));
+    const direction = afterIndex === undefined ? 'before' : 'after';
+    const cursor = visibleActivities.length === 0 ? undefined : direction === 'before'
+        ? Math.min(...visibleActivities.map((activity) => activity.index)) : Math.max(...visibleActivities.map((activity) => activity.index));
+    const continuation = limit === null || cursor === undefined || !(direction === 'before' ? publicBefore : publicAfter)
+        ? undefined : { direction, cursor: formatActivityId(cursor), limit };
+    return { activities, visibleActivities, totalMatches, ...(continuation === undefined ? {} : { continuation }) };
 }
-function statuses(square, state) {
-    const delivery = deriveDeliveryModel(state);
-    return coreStatus(state, square.clock(), delivery).participants.filter((participant) => participant.state !== 'not joined').map((participant) => {
-        const cursor = delivery.cursorFor(participant.name);
-        return { name: participant.name, state: participant.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: participant.presence === 'watching', listening: participant.listening };
-    });
+export function publicActivities(activities) {
+    return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
 }
-function anchors(state, delivery) {
-    const result = {};
-    const landed = replayLandedAudiences(state.acts);
-    for (const name of delivery.participants()) {
-        const anchor = presenceAnchor(state, name, landed);
-        if (anchor >= 0)
-            result[anchor] = [...(result[anchor] ?? []), name];
-    }
-    return result;
-}
-function sayNumbers(state) {
-    const counts = new Map();
-    const result = {};
-    for (const activity of state.acts)
-        if (activity.kind === 'say') {
-            const next = (counts.get(nameKey(activity.actor)) ?? 0) + 1;
-            counts.set(nameKey(activity.actor), next);
-            result[activity.index] = next;
-        }
-    return result;
-}
-export async function history(square, query = {}, control) { const { state } = await square.artifact.read(control?.signal); return selectHistory(coreActivities(state, historyOptions(query)), query).map(toPublicActivity); }
-export async function participantHistory(square, _name, query = {}, control) { const { state } = await square.artifact.read(control?.signal); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective)), effective).map(toPublicActivity); }
-export async function resolveParticipant(square, name, control) { const { state } = await square.artifact.read(control?.signal); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
-export async function currentParticipant(square, name) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name); return known !== undefined && isCurrentlyJoined(state.acts, known) ? known : undefined; }
-export async function participants(square) { const { state } = await square.artifact.read(); return statuses(square, state); }
-export async function snapshot(square, control) { const { state } = await square.artifact.read(control?.signal); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isActivitySeen(state, name, parseRequiredActivityId(id)); } }; }
-export async function activityPresentation(square, name) { const { state } = await square.artifact.read(); const known = resolveKnownName(state, name); const delivery = deriveDeliveryModel(state); const delta = deliveryDelta(state, known, delivery); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: directedPeerSays(state, delta, known, delivery), activities: state.acts, state, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
-export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), state, sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
-export async function historyPresentation(square, options) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return { activities: coreActivities(state, options, delivery), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state, delivery), participantCount: inSquareCount(state) }; }
-export async function participantsPresentation(square) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return coreParticipants(state, square.clock(), delivery); }
-export async function listPresentation(square) { const { state } = await square.artifact.read(); return { context: state.preamble, participants: coreParticipants(state, square.clock()).filter((participant) => participant.state === 'active').map((participant) => participant.name), activities: state.acts.filter((activity) => activity.kind === 'say').length }; }
-export async function statusPresentation(square) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); const status = coreStatus(state, square.clock(), delivery); return { state, status, ...(status.latestAct?.kind === 'say' ? { latestActNumber: countSays(state.acts, status.latestAct.actor) } : {}) }; }
-export async function eventPresentation(square, id) { const { state } = await square.artifact.read(); const activity = state.acts.find((candidate) => candidate.index === parseRequiredActivityId(id)); if (activity === undefined)
-    throw new SquareError('invalid_args', `Unknown activity id: ${id}`); return { activity, participantCount: inSquareCount(state), held: currentHold(state.acts).active }; }
-export async function watchPresentation(square, name) { const { state } = await square.artifact.read(); const known = resolveKnownName(state, name); const now = square.clock(); const terminal = watchTerminalStatus(state, known); const delivery = deriveDeliveryModel(state); return { activities: state.acts, state, participantCount: inSquareCount(state), presence: { participants: coreParticipants(state, now, delivery), now }, ...(terminal === undefined ? {} : { terminalStatus: terminal }) }; }
-const STREAM_BATCH_MAX = 100;
-function projectStreamActivities(state, activities, recipient) {
-    const delivery = recipient === undefined ? undefined : deriveDeliveryModel(state);
-    return activities.flatMap((activity) => {
-        if (delivery === undefined || recipient === undefined)
-            return [{ activity }];
-        const notification = delivery.plan(activity).find((candidate) => nameKey(candidate.recipient) === nameKey(recipient));
-        return notification === undefined ? [] : [{ activity, route: notification.route }];
+export async function history(square, query = {}, control) {
+    return (await square.artifact.read((facts) => publicActivities(selectHistory(facts, query, query.limit ?? null, NON_READ).activities), control?.signal)).value;
+}
+export async function resolveParticipant(square, name, control) {
+    return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
+}
+export async function currentParticipant(square, name, control) {
+    return (await square.artifact.read((facts) => { const p = facts.participant(name); return p?.joined ? p.name : undefined; }, control?.signal)).value;
+}
+function statuses(facts, now) {
+    return coreParticipants(facts, now).filter((p) => p.state !== 'not joined').map((p) => {
+        const cursor = readCursor(facts, p.name);
+        return { name: p.name, state: p.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: p.presence === 'watching', listening: p.listening };
     });
 }
-export async function streamProjection(square, cursor, recipient) {
-    const artifact = 'artifact' in square ? square.artifact : square.cell;
-    const { state } = await artifact.read();
-    const pending = state.acts.filter((activity) => activity.index > cursor);
-    const batch = pending.slice(0, STREAM_BATCH_MAX);
-    return {
-        activities: projectStreamActivities(state, batch, recipient),
-        cursor: batch.at(-1)?.index ?? cursor,
-        hasMore: pending.length > batch.length,
-    };
+export async function participants(square) {
+    return (await square.artifact.read((facts) => statuses(facts, square.clock()))).value;
 }
-export async function streamTailProjection(square, last = 10, recipient) {
-    const artifact = 'artifact' in square ? square.artifact : square.cell;
-    const { state } = await artifact.read();
-    const activities = projectStreamActivities(state, state.acts, recipient);
-    if (!Number.isSafeInteger(last) || last < 0 || last > STREAM_BATCH_MAX) {
-        throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${STREAM_BATCH_MAX}.`);
-    }
+export async function snapshot(square, control) {
+    return (await square.artifact.read((facts) => {
+        const header = facts.header(), hold = facts.hold();
+        const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
+        const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
+        return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
+            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
+            held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
+            participants: statuses(facts, square.clock()), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
+    }, control?.signal)).value;
+}
+export async function recoveryObservation(square, name, control) {
+    return (await square.artifact.read((facts) => {
+        const known = resolveKnownName(facts, name), hold = facts.hold();
+        return { name: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), participantCount: inSquareCount(facts), held: hold.active,
+            ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
+    }, control?.signal)).value;
+}
+export async function entryPresentation(square, name, lastN = HISTORY_DEFAULT_LIMIT, control) {
+    return (await square.artifact.read((facts) => {
+        const header = facts.header(), p = facts.participant(name);
+        const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
+        return { joined: p?.joined ?? false, joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
+            scene: header.warmup.join('\n').trim(), context: header.preamble.join('\n').trim(),
+            joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
+            perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
+            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)), participantCount: inSquareCount(facts), held: facts.hold().active };
+    }, control?.signal)).value;
+}
+function classifyPresence(participants, now) {
+    const here = participants.filter((participant) => participant.state === 'active' && (participant.presence === 'watching'
+        || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= STATUS_HERE_WINDOW_MS)));
+    const hereNames = new Set(here.map((participant) => participant.name));
+    return { orderedHereNames: [...here.filter((participant) => participant.presence === 'watching'), ...here.filter((participant) => participant.presence !== 'watching')].map((participant) => participant.name),
+        lingeringCount: participants.filter((participant) => participant.state === 'active' && !hereNames.has(participant.name)).length,
+        classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.state === 'done' ? 'done'
+                : participant.state === 'not joined' ? 'not-joined' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
+}
+export function queryParticipants(facts, context) {
+    const participants = coreParticipants(facts, context.now);
+    return { data: { participants }, projection: { ...context, ...classifyPresence(participants, context.now),
+            standingCount: inSquareCount(facts), held: facts.hold().active } };
+}
+export async function listPresentation(square, control) {
+    return (await square.artifact.read((facts) => {
+        const participants = facts.roster().filter((p) => p.joined).map((p) => {
+            const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
+            return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
+        }).sort(compareParticipantActivity).map((p) => p.name);
+        return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
+    }, control?.signal)).value;
+}
+export function queryStatus(facts, context, viewer = '') {
+    const { data: { participants }, projection } = queryParticipants(facts, context);
+    const header = facts.header(), hold = facts.hold();
+    const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
+    const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
+    const afterIndex = latestAct?.index ?? -1;
+    const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({ activity,
+        rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0 }));
+    const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
-        activities: last === 0 ? [] : activities.slice(-last),
-        cursor: state.acts.at(-1)?.index ?? -1,
-        hasMore: false,
+        data: {
+            hardCap: header.hardCap,
+            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
+            activeCount: projection.standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
+            hold: hold.active ? {
+                ...(hold.actor === undefined ? {} : { by: hold.actor }),
+                ...(hold.reason === undefined ? {} : { reason: hold.reason }),
+                ...(hold.at === undefined ? {} : { at: hold.at }),
+            } : null,
+            participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
+            ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
+        },
+        projection: {
+            ...projection, knownParticipantCount: participants.length, viewer: canonicalViewer,
+            ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
+            joins, joinCount: facts.activityCount({ kinds: ['join'], afterIndex }),
+            attentionNames: participants.filter((p) => canonicalViewer === '' || nameKey(p.name) === nameKey(canonicalViewer)).map((p) => p.name),
+            ...(latestAct === undefined ? {} : { latestPerception: perceiveActivity(facts, latestAct, canonicalViewer) }),
+            ...(latestAct?.kind === 'say' ? { latestActNumber: facts.sayOrdinals([latestAct.index])[latestAct.index] } : {}),
+        },
     };
 }
-export function pendingDeliveriesFromState(state, delivery = deriveDeliveryModel(state)) { return delivery.joinedRecipients().map((recipient) => ({ recipient, notifications: delivery.pendingFor(recipient) })); }
+export async function eventPresentation(square, id, control) {
+    return (await square.artifact.read((facts) => {
+        const activity = facts.activity(parseRequiredActivityId(id));
+        if (activity === undefined)
+            throw new SquareError('invalid_args', `Unknown activity id: ${id}`);
+        return { activity, participantCount: inSquareCount(facts), held: facts.hold().active };
+    }, control?.signal)).value;
+}
+export async function catchPresence(square, control) {
+    return (await square.artifact.read((facts) => {
+        const now = square.clock();
+        const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
+            || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
+        return { participants, now };
+    }, control?.signal)).value;
+}
+export async function streamProjection(square, cursor, recipient, control) {
+    return (await square.artifact.read((facts) => {
+        const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
+        const heads = page.items.flatMap((head) => {
+            const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
+            return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
+        });
+        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
+                const route = heads.find((h) => h.index === activity.index).route;
+                return { activity, ...(route === undefined ? {} : { route }) };
+            }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
+    }, control?.signal)).value;
+}
+export async function streamTailProjection(square, last = HISTORY_DEFAULT_LIMIT, recipient, control) {
+    return (await square.artifact.read((facts) => {
+        if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
+            throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
+        const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
+                ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
+    }, control?.signal)).value;
+}

package/dist/wake-eligibility.d.ts

@@ -1,17 +1,21 @@
-import { type SquareState, type WakeRoute } from './model.js';
-import { deriveDeliveryModel } from './delivery.js';
+import { type WakeRoute } from './model.js';
 import type { EvidenceRecord, PresenceRecord } from './host-ledger.js';
-import type { PresentationEvidenceProjection, WakeRequest } from './ports.js';
+import type { DirectedHead, HostLedgerPort, PresentationEvidenceProjection, RouteFact, WakeRequest } from './ports.js';
 import { type WakeAttempt } from './wake-evidence.js';
 export interface WakeSnapshot {
-    readonly state: SquareState;
+    readonly routes: readonly RouteFact[];
+    readonly pending: readonly DirectedHead[];
+    readonly seen?: readonly {
+        readonly recipient: string;
+        readonly index: number;
+    }[];
     /** Canonicalized by the caller; every identity in this snapshot is square-local. */
     readonly location: string;
     readonly owners: readonly PresenceRecord[];
+    readonly bindings?: readonly PresenceRecord[];
     readonly wakeRecords: readonly EvidenceRecord[];
     readonly presentations: readonly PresentationEvidenceProjection[];
     readonly now: number;
-    readonly delivery?: ReturnType<typeof deriveDeliveryModel>;
 }
 export interface OwnedWakeRoute {
     readonly route: WakeRoute;
@@ -40,4 +44,10 @@ export interface WakeEligibility {
 }
 /** One strict ownership join, latest selection, and request fence over primary evidence only. */
 export declare function projectWakeEligibility(input: WakeSnapshot): WakeEligibility;
+/** Host observation happens only after detached artifact facts have left their transaction. */
+export declare function projectWakeEvidence(input: Pick<WakeSnapshot, 'routes' | 'pending' | 'seen' | 'location' | 'now' | 'bindings'> & {
+    readonly hostLedger: HostLedgerPort;
+    readonly owners?: readonly PresenceRecord[];
+}): Promise<WakeEligibility>;
+export declare function sameBinding(captured: PresenceRecord, current: PresenceRecord): boolean;
 export declare function wakeIsEligible(evidence: WakeEvidence): boolean;

package/dist/wake-eligibility.js

@@ -1,12 +1,11 @@
 import { nameKey } from './model.js';
-import { deriveDeliveryModel } from './delivery.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { presenceEpoch } from './registry.js';
+import { canonicalPath } from './canonical-path.js';
 import { decodeWakeEvidence } from './wake-evidence.js';
 function identity(...parts) { return JSON.stringify(parts); }
 /** One strict ownership join, latest selection, and request fence over primary evidence only. */
 export function projectWakeEligibility(input) {
-    const delivery = input.delivery ?? deriveDeliveryModel(input.state);
     const ownersBySession = new Map();
     for (const owner of input.owners) {
         if (owner.location !== input.location)
@@ -20,12 +19,14 @@ export function projectWakeEligibility(input) {
         : ownersBySession.get(identity(nameKey(route.participant), route.sessionId))?.find((row) => route.epoch === undefined || presenceEpoch(row) === route.epoch);
     const ownedRoutes = [];
     const latest = new Map();
-    for (const route of input.state.routes ?? []) {
-        const participant = nameKey(route.participant);
-        const owner = ownerFor(route);
-        if (owner === undefined)
+    for (const fact of input.routes) {
+        const participant = nameKey(fact.participant);
+        const owner = ownerFor(fact);
+        // Malformed legacy epoch cannot acquire an owner by coercion or enter a transport request.
+        if (owner === undefined || (fact.epoch !== undefined && typeof fact.epoch !== 'number'))
             continue;
-        ownedRoutes.push({ route, owner });
+        const { extra, epoch, ...route } = fact;
+        ownedRoutes.push({ route: { ...route, ...(epoch === undefined ? {} : { epoch }) }, owner });
         latest.set(participant, Math.max(latest.get(participant) ?? Number.NEGATIVE_INFINITY, route.updatedAt));
     }
     const selectedByRecipient = new Map();
@@ -37,11 +38,8 @@ export function projectWakeEligibility(input) {
         rows.push(owned);
         selectedByRecipient.set(key, rows);
     }
-    const pending = new Set();
-    for (const recipient of delivery.joinedRecipients()) {
-        for (const notification of delivery.pendingFor(recipient))
-            pending.add(identity(nameKey(recipient), notification.item.index));
-    }
+    const pending = new Set(input.pending.map((head) => identity(nameKey(head.recipient), head.index)));
+    const seen = new Set(input.seen?.map((receipt) => identity(nameKey(receipt.recipient), receipt.index)));
     const attemptsByAttention = new Map();
     for (const record of input.wakeRecords) {
         if (record.location !== input.location)
@@ -63,6 +61,8 @@ export function projectWakeEligibility(input) {
     }
     const isPresented = (route, actIndex) => presentedSessions.has(identity(nameKey(route.participant), formatActivityId(actIndex), route.sessionId));
     const isCancelled = (owner, actIndex) => actIndex <= (owner.cancelledThrough ?? -1);
+    const bindingCurrent = (owner) => input.bindings === undefined
+        || input.bindings.some((captured) => sameBinding(captured, owner));
     return {
         evidence(recipient, actIndex) {
             const key = nameKey(recipient);
@@ -73,10 +73,10 @@ export function projectWakeEligibility(input) {
             const routes = (selectedByRecipient.get(key) ?? []).filter(({ owner }) => !isCancelled(owner, actIndex));
             const presented = routes.length > 0 && routes.every(({ route }) => isPresented(route, actIndex));
             return {
-                delivered: delivery.isSeen(recipient, actIndex), presented, attempts,
+                delivered: seen.has(identity(key, actIndex)), presented, attempts,
                 ...(terminal === undefined ? {} : { terminal }),
                 attemptableRoutes: terminal === undefined && pending.has(identity(key, actIndex))
-                    ? routes.filter(({ route }) => !isPresented(route, actIndex)).map(({ route }) => route) : [],
+                    ? routes.filter(({ route, owner }) => bindingCurrent(owner) && !isPresented(route, actIndex)).map(({ route }) => route) : [],
             };
         },
         currentness(request) {
@@ -87,11 +87,11 @@ export function projectWakeEligibility(input) {
             const activityPending = actIndex !== undefined && request.location === input.location
                 && pending.has(identity(nameKey(request.participant), actIndex));
             const owner = sameLocation && sameRecipient ? ownerFor(route) : undefined;
-            const sessionBound = owner !== undefined;
+            const sessionBound = owner !== undefined && bindingCurrent(owner);
             const matchesRequest = (published) => published.location === route.location
                 && nameKey(published.participant) === nameKey(route.participant) && published.sessionId === route.sessionId
                 && published.kind === route.kind && published.epoch === route.epoch && Object.keys(published.address).length === Object.keys(route.address).length && Object.keys(published.address).every((key) => published.address[key] === route.address[key]);
-            const routePublished = sameLocation && sameRecipient && (input.state.routes ?? []).some(matchesRequest);
+            const routePublished = sameLocation && sameRecipient && input.routes.some(matchesRequest);
             const selectedOwner = sameLocation && sameRecipient
                 && (selectedByRecipient.get(nameKey(route.participant)) ?? []).some(({ route: published }) => matchesRequest(published));
             const cancelled = actIndex !== undefined && owner !== undefined && isCancelled(owner, actIndex);
@@ -102,6 +102,22 @@ export function projectWakeEligibility(input) {
         },
     };
 }
+/** Host observation happens only after detached artifact facts have left their transaction. */
+export async function projectWakeEvidence(input) {
+    const location = await canonicalPath(input.location);
+    const owners = input.owners ?? await input.hostLedger.listPresence({ location, now: input.now });
+    const records = await input.hostLedger.listEvidence({ location, now: input.now });
+    const presentations = records.filter((row) => row.kind === 'presentation').map((row) => ({
+        location: row.location, participant: row.participant, sessionId: row.session, activity: row.activity, outcome: row.outcome,
+        ...(row.at === undefined ? {} : { at: row.at }),
+    }));
+    return projectWakeEligibility({ ...input, location, owners, wakeRecords: records.filter((row) => row.kind === 'wake'), presentations });
+}
+export function sameBinding(captured, current) {
+    return captured.location === current.location && nameKey(captured.participant) === nameKey(current.participant)
+        && captured.session === current.session && captured.channel === current.channel && captured.epoch === current.epoch
+        && (captured.cancelledThrough ?? -1) === (current.cancelledThrough ?? -1);
+}
 export function wakeIsEligible(evidence) {
     return !evidence.delivered && !evidence.presented && evidence.terminal === undefined && evidence.attemptableRoutes.length > 0;
 }

package/dist/wakes.d.ts

@@ -21,7 +21,7 @@ export type WatchLeasePulse = {
     readonly type: 'sleep';
     readonly heartbeatAt?: number;
 };
-export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions): Promise<WatchLeaseStart>;
-export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean): Promise<WatchLeasePulse>;
+export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
+export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
 export declare function releaseWatchLease(square: OpenSquare, name: string, leaseId: string | undefined): Promise<void>;
-export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string): Promise<boolean>;
+export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string, signal?: AbortSignal): Promise<boolean>;

package/dist/wakes.js

@@ -1,40 +1,44 @@
 import { resolveKnownName } from './decisions.js';
-import { WATCH_STALE_MS, currentHold, freshWatchLease, removeWatchLease, watchTerminalStatus, writeWatchLease } from './runtime.js';
-function filter(options) {
-    return { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
+import { WATCH_STALE_MS, freshWatchLease, watchTerminalStatus } from './runtime.js';
+function newLease(leaseId, at, options) {
+    const filter = { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
+    return { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter).length === 0 ? {} : { filter }) };
 }
-export async function acquireWatchLease(square, name, leaseId, options) {
+export async function acquireWatchLease(square, name, leaseId, options, signal) {
     const at = square.clock();
-    return square.artifact.transact((state) => {
-        const known = resolveKnownName(state, name);
-        const existing = freshWatchLease(state, known, at);
+    const { value } = await square.artifact.transact((facts) => {
+        const known = resolveKnownName(facts, name);
+        const existing = freshWatchLease(facts, known, at);
         if (existing !== undefined && !options.replace)
-            return { result: { type: 'active', lease: existing } };
-        writeWatchLease(state, known, { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
-        return { state, result: { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at } };
-    });
+            return { type: 'active', lease: existing };
+        facts.putLease(known, newLease(leaseId, at, options));
+        return { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at };
+    }, signal);
+    return value;
 }
-export async function pulseWatchLease(square, name, leaseId, options, heartbeatDue) {
+export async function pulseWatchLease(square, name, leaseId, options, heartbeatDue, signal) {
     const at = square.clock();
-    return square.artifact.transact((state) => {
-        const known = resolveKnownName(state, name);
-        const lease = freshWatchLease(state, known, at);
+    const { value } = await square.artifact.transact((facts) => {
+        const known = resolveKnownName(facts, name);
+        const lease = freshWatchLease(facts, known, at);
         if (lease?.leaseId !== leaseId)
-            return { result: { type: 'replaced' } };
-        const held = currentHold(state.acts).active;
-        const terminal = held ? undefined : watchTerminalStatus(state, known);
+            return { type: 'replaced' };
+        const held = facts.hold().active;
+        const terminal = held ? undefined : watchTerminalStatus(facts, known);
         if (terminal !== undefined)
-            return { result: { type: 'terminal', status: terminal } };
+            return { type: 'terminal', status: terminal };
         const type = held ? 'held' : 'sleep';
         if (!heartbeatDue)
-            return { result: { type } };
-        writeWatchLease(state, known, { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
-        return { state, result: { type, heartbeatAt: at } };
-    });
+            return { type };
+        facts.putLease(known, newLease(leaseId, at, options));
+        return { type, heartbeatAt: at };
+    }, signal);
+    return value;
 }
 export async function releaseWatchLease(square, name, leaseId) {
-    if (leaseId === undefined)
-        return;
-    await square.artifact.transact((state) => { const known = resolveKnownName(state, name); return removeWatchLease(state, known, leaseId) ? { state, result: undefined } : { result: undefined }; });
+    if (leaseId !== undefined)
+        await square.artifact.transact((facts) => facts.removeLease(resolveKnownName(facts, name), leaseId));
+}
+export async function ownsWatchLease(square, name, leaseId, signal) {
+    return (await square.artifact.read((facts) => freshWatchLease(facts, resolveKnownName(facts, name), square.clock())?.leaseId === leaseId, signal)).value;
 }
-export async function ownsWatchLease(square, name, leaseId) { const { state } = await square.artifact.read(); return freshWatchLease(state, resolveKnownName(state, name), square.clock())?.leaseId === leaseId; }