@astrosheep/square 0.3.11 → 0.3.13

package/dist/presentation.js

@@ -1,8 +1,10 @@
 import { sameName } from './model.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { fold, perceive } from './square-core.js';
-import { actId, actStableIndex, extractMentions, publicActs, readCursor, rosterNames, sayNumberFor } from './runtime.js';
+import { participantIdentity } from './participant-identity.js';
+export { participantIdentity } from './participant-identity.js';
+import { audienceIncludes, audienceOf, perceive } from './square-core.js';
+import { actId, publicActs, readCursor, rosterNames, sayNumberFor } from './runtime.js';
 import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { grepSnippet } from './search.js';
 function headerLine(squarePath, opts = {}) {
@@ -49,7 +51,7 @@ function pluralize(count, singular, plural = `${singular}s`) {
 const PRESENCE_WINDOW_MS = 8 * 60 * 60 * 1000;
 function presenceGlyph(participant) {
     if (participant.state === 'done')
-        return '×';
+        return '○';
     if (participant.presence === 'watching')
         return '◎';
     if (participant.presenceAt !== undefined)
@@ -77,7 +79,7 @@ export function renderPresenceLines(participants, now, limit = 5) {
     const shown = recent.slice(0, limit);
     if (shown.length === 0)
         return ['  ○ nobody nearby'];
-    const lines = shown.map((p) => `  ${presenceGlyph(p)} ${p.name} · ${presenceText(p, now)}`);
+    const lines = shown.map((p) => `  ${presenceGlyph(p)} ${participantIdentity(p.name)} · ${presenceText(p, now)}`);
     const remaining = recent.length - shown.length;
     if (remaining > 0)
         lines.push(`  ○ …and ${remaining} more`);
@@ -116,15 +118,16 @@ export function previewActivityBody(body) {
 }
 export function renderRoomChangeText(event) {
     const actor = event.actor ?? 'someone';
+    const identity = actor === 'someone' ? actor : participantIdentity(actor);
     switch (event.kind) {
         case 'join':
-            return `${actor} stepped into the square`;
+            return `${identity} stepped into the square`;
         case 'done':
-            return `${actor} stepped out of the square`;
+            return `${identity} stepped out of the square`;
         case 'hold':
-            return `${actor} raised a hand${event.body ? ` — ${event.body}` : ''}`;
+            return `${identity} raised a hand${event.body ? ` — ${event.body}` : ''}`;
         case 'resume':
-            return `${actor} lowered the hand`;
+            return `${identity} lowered the hand`;
     }
 }
 function renderedBody(body, maxChars) {
@@ -150,38 +153,32 @@ export function renderEventCli(event, opts = {}) {
         case 'say': {
             const body = renderedBody(event.body, maxBody);
             const mention = opts.mention;
-            const mentionSuffix = mention !== undefined && extractMentions(event.body).some((name) => sameName(name, mention))
-                ? ` · calls your name across the square — @${mention}`
+            const mentionSuffix = mention !== undefined && audienceIncludes(audienceOf(event), mention)
+                ? ` · calls your name across the square — ${participantIdentity(mention)}`
                 : '';
             const replySuffix = event.reply === undefined ? '' : ` · replies to ${actId(event.reply)}`;
-            return `● ${event.actor} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}${bodySuffix(body)}`;
+            return `● ${participantIdentity(event.actor)} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}${bodySuffix(body)}`;
         }
         case 'done': {
             const body = renderedBody(event.body, maxBody);
-            return `× ${event.actor} stepped out of the square — done · ${actId(event)} · ${formatRelativeTime(event.at, now)}${bodySuffix(body)}`;
+            return `○ ${participantIdentity(event.actor)} stepped out of the square — done · ${actId(event)} · ${formatRelativeTime(event.at, now)}${bodySuffix(body)}`;
         }
         case 'read':
             return '';
     }
 }
-function renderPresenceOnlySay(event) {
-    if (event.kind !== 'say' || event.reach === undefined || event.reach === 'bell')
-        return '';
-    return `*walks over to @${event.reach.beside}*`;
-}
-function perceptionFor(history, event, viewer) {
-    const cutoff = history.findIndex((item) => actStableIndex(item) === actStableIndex(event));
-    const acts = cutoff >= 0 ? history.slice(0, cutoff) : history;
-    return perceive(fold(acts), event, viewer);
+function renderPresenceOnlySay(event, opts = {}) {
+    const audience = audienceOf(event);
+    const targets = audience.kind === 'bell' ? [] : audience.names;
+    const dest = targets.length === 0 ? '' : ` ${targets.map((name) => participantIdentity(name)).join(' and ')}`;
+    return `● ${participantIdentity(event.actor)} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, opts.now)}\n  talked to${dest}`;
 }
-export function renderVisibleEvent(history, event, viewer, opts = {}) {
+export function renderAmbientEvent(event, viewer, opts = {}) {
     if (event.kind !== 'say')
         return renderEventCli(event, opts);
-    const seen = perceptionFor(history, event, viewer);
-    if (seen === 'none')
-        return '';
+    const seen = perceive(event, viewer);
     if (seen === 'presence')
-        return renderPresenceOnlySay(event);
+        return renderPresenceOnlySay(event, opts);
     return renderEventCli(event, opts);
 }
 function draftSavedLines(draftPath) {
@@ -194,12 +191,13 @@ function renderUnreadSummary(opts) {
     return [
         ...opts.activitySummaries.flatMap((item) => [
             ...item.previews.slice(-1).map((preview) => {
-                const rendered = renderVisibleEvent([preview.act], preview.act, opts.viewer, { actNumber: preview.number });
+                const rendered = renderAmbientEvent(preview.act, opts.viewer, { actNumber: preview.number });
                 if (rendered === '')
-                    return `  · ${item.name} spoke — ${formatAge(item.latestActivityAgeMs)} ago`;
-                if (rendered.startsWith('*'))
-                    return `  · ${item.name} spoke — ${formatAge(item.latestActivityAgeMs)} ago · ${rendered}`;
-                return `  · ${item.name} spoke — ${formatAge(item.latestActivityAgeMs)} ago · "${previewActivityBody(preview.act.body)}"`;
+                    return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago`;
+                if (preview.act.kind === 'say' && perceive(preview.act, opts.viewer) === 'presence') {
+                    return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · ${rendered.replace(/\n/g, ' ')}`;
+                }
+                return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · "${previewActivityBody(preview.act.body)}"`;
             }),
         ]),
         ...opts.roomChanges.map((act) => `  · ${renderRoomChangeText(act)}`),
@@ -208,7 +206,7 @@ function renderUnreadSummary(opts) {
 export function renderPendingFeed(history, publicItems, roomChanges, viewer = '') {
     const lines = [];
     for (const act of publicItems) {
-        const rendered = renderVisibleEvent(history, act, viewer, {
+        const rendered = renderAmbientEvent(act, viewer, {
             actNumber: act.kind === 'say' ? sayNumberFor(history, act) : undefined,
         });
         if (rendered !== '')
@@ -262,15 +260,15 @@ export function renderPublicTail(events, lastN, now, viewer = '') {
     const selected = lastN == null ? publicItems : publicItems.slice(-lastN);
     const preview = lastN == null ? undefined : BODY_PREVIEW_LENGTH;
     return selected
-        .map((event) => renderVisibleEvent(events, event, viewer, { now, preview, actNumber: event.kind === 'say' ? sayNumberFor(events, event) : undefined }))
+        .map((event) => renderAmbientEvent(event, viewer, { now, preview, actNumber: event.kind === 'say' ? sayNumberFor(events, event) : undefined }))
         .filter(Boolean)
         .join('\n\n');
 }
-function lastPresenceAnchor(doc, name) {
-    const cursor = readCursor(doc, name);
-    for (let i = doc.acts.length - 1; i >= 0; i--) {
-        const event = doc.acts[i];
-        const index = actStableIndex(event);
+function lastPresenceAnchor(squareState, name) {
+    const cursor = readCursor(squareState, name);
+    for (let i = squareState.acts.length - 1; i >= 0; i--) {
+        const event = squareState.acts[i];
+        const index = event.index;
         if (index > cursor)
             continue;
         if (event.kind === 'say' || event.kind === 'done')
@@ -279,24 +277,27 @@ function lastPresenceAnchor(doc, name) {
     return -1;
 }
 function renderLastPresenceMarker(name) {
-    return `· ${name}'s footprints reach here`;
+    return `→ ${participantIdentity(name)} was here`;
 }
-export function renderActivitiesView(doc, visible, lastN, full, squarePath, viewer = '') {
+export function renderActivitiesView(squareState, visible, lastN, full, squarePath, viewer = '', mode = 'ambient') {
     const publicVisible = visible.filter((act) => act.kind === 'say' || act.kind === 'done');
     const shown = lastN == null ? publicVisible : publicVisible.slice(-lastN);
     const previewLen = full ? undefined : BODY_PREVIEW_LENGTH;
     const markers = new Map();
-    for (const participant of rosterNames(doc)) {
-        const anchor = lastPresenceAnchor(doc, participant);
+    for (const participant of rosterNames(squareState)) {
+        const anchor = lastPresenceAnchor(squareState, participant);
         if (anchor >= 0)
             markers.set(anchor, [...(markers.get(anchor) ?? []), participant]);
     }
     const chunks = [];
     for (const act of shown) {
-        const rendered = renderVisibleEvent(doc.acts, act, viewer, {
+        const opts = {
             preview: previewLen,
-            actNumber: act.kind === 'say' ? sayNumberFor(doc.acts, act) : undefined,
-        });
+            actNumber: act.kind === 'say' ? sayNumberFor(squareState.acts, act) : undefined,
+        };
+        const rendered = mode === 'archive'
+            ? renderEventCli(act, opts)
+            : renderAmbientEvent(act, viewer, opts);
         if (rendered !== '')
             chunks.push(rendered);
         for (const participant of markers.get(act.index) ?? []) {
@@ -306,7 +307,7 @@ export function renderActivitiesView(doc, visible, lastN, full, squarePath, view
     if (chunks.length === 0)
         return 'latest\n  ○ no public activity in this view';
     if (previewLen !== undefined) {
-        const truncated = shown.some((act) => act.kind === 'say' && act.body.length > previewLen);
+        const truncated = shown.some((act) => act.kind === 'say' && act.body.length > previewLen && (mode === 'archive' || perceive(act, viewer) === 'full'));
         if (truncated)
             chunks.push(`» ${commandPrefix(squarePath)} history --full`);
     }
@@ -329,13 +330,13 @@ export function renderGrepActivitiesView(visible, totalMatches, full, squarePath
         const rawBody = act.body ?? '';
         if (full === true) {
             const body = rawBody.split('\n').map((line) => `  ${line}`).join('\n');
-            chunks.push(`${actId(act.index)} · ${act.actor ?? 'unknown'} · ${formatTimestamp(act.at)}\n${body}`);
+            chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}\n${body}`);
             continue;
         }
         const snippet = grepSnippet(rawBody, pattern, GREP_PREVIEW_CHARS, fixed);
         if (snippet === undefined) {
             const preview = previewBody(rawBody, GREP_PREVIEW_CHARS);
-            chunks.push(`${actId(act.index)} · ${act.actor ?? 'unknown'} · ${formatTimestamp(act.at)}${preview === '' ? '' : `\n  ${preview}`}`);
+            chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}${preview === '' ? '' : `\n  ${preview}`}`);
             continue;
         }
         const clippedBefore = snippet.beforeOmitted > 0;
@@ -345,7 +346,7 @@ export function renderGrepActivitiesView(visible, totalMatches, full, squarePath
         const omitted = clippedBefore || clippedAfter
             ? `\n  · ${snippet.beforeOmitted} chars before · ${snippet.afterOmitted} chars after`
             : '';
-        chunks.push(`${actId(act.index)} · ${act.actor ?? 'unknown'} · ${formatTimestamp(act.at)}\n  ${text.trim()}${omitted}`);
+        chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}\n  ${text.trim()}${omitted}`);
     }
     if (publicVisible.length === 1) {
         chunks.push(`» ${commandPrefix(squarePath)} history --at ${actId(publicVisible[0].index)} -C 2${truncated ? ' --full' : ''}`);
@@ -412,20 +413,8 @@ function renderRoomChanges(changes) {
 export function renderDoctorClean() {
     return '✓ no problems found';
 }
-export function renderDoctorProblems(problems) {
-    return [`✕ ${problems.length} ${pluralize(problems.length, 'problem')} found`, ...problems.map((problem) => `  · ${problem.kind}: ${problem.message}`)].join('\n');
-}
 export function renderDoctorUnfixable(reason) {
-    return ['✕ cannot repair', `  · ${reason}`].join('\n');
-}
-export function renderDoctorRepaired(actions, quarantinedCount, sidecarPath) {
-    if (actions.length === 0)
-        return '✓ no problems found';
-    return [
-        '✓ repaired',
-        ...actions.map((action) => `  · ${action.message}`),
-        ...(quarantinedCount > 0 && sidecarPath !== undefined ? [`  · quarantined ${quarantinedCount} act block(s)`, `  · sidecar ${sidecarPath}`] : []),
-    ].join('\n');
+    return ['✕ unreadable artifact', `  · ${reason}`].join('\n');
 }
 export function renderWatchOutput(history, publicItems, roomChanges, opts) {
     const sections = [];
@@ -448,7 +437,7 @@ export function renderWatchOutput(history, publicItems, roomChanges, opts) {
         sections.push(room);
     if (publicItems.length > 0) {
         const rendered = publicItems
-            .map((act) => renderVisibleEvent(history, act, opts.viewer, {
+            .map((act) => renderAmbientEvent(act, opts.viewer, {
             actNumber: act.kind === 'say' ? sayNumberFor(history, act) : undefined,
             mention: opts.mention,
         }))

package/dist/presented.d.ts

@@ -0,0 +1,11 @@
+import { type InboxMembership } from './model.js';
+export declare function presentedPath(env?: NodeJS.ProcessEnv): string;
+export declare function hasPresentedForOwner(ownerId: string, squarePath: string, name: string, actIndex: number, env?: NodeJS.ProcessEnv, now?: number): boolean;
+/** True when any current participant owner has already received this attention. */
+export declare function hasPresentedAttention(squarePath: string, name: string, actIndex: number, env?: NodeJS.ProcessEnv, now?: number): boolean;
+/**
+ * Serialize presentation only for the affected participants. Delivery runs
+ * outside the short ledger-write lock, so unrelated owners never wait on an
+ * adapter. A throwing callback leaves no row and remains unpresented.
+ */
+export declare function presentOnce<T>(sessionId: string, lookup: (sessionId: string) => InboxMembership[], deliver: (inbox: InboxMembership[]) => T, env?: NodeJS.ProcessEnv, at?: number): T | undefined;

package/dist/registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Machine-local participant discovery cache.
+ *
+ * The Square artifact remains authoritative for membership. This append-only
+ * cache only maps native harness sessions and optional Paseo agent ids back to
+ * active (square path, participant name) pairs.
+ */
+import { type StoredAct } from './model.js';
+export type SessionChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
+export interface RegistryBinding {
+    sessionId: string;
+    name: string;
+    squarePath: string;
+    channel: SessionChannel;
+    child: boolean;
+    paseoAgentId?: string;
+    ownerId: string;
+    updatedAt: number;
+}
+export interface RegistryWriteOptions {
+    channel?: SessionChannel;
+    child?: boolean;
+    paseoAgentId?: string;
+    ownerId?: string;
+    at?: number;
+}
+export declare function registryPath(): string;
+export declare function canonicalSquarePath(squarePath: string): string;
+export declare function recordJoin(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): void;
+export declare function recordDone(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): void;
+export declare function lookupSessionBindings(sessionId: string, now?: number): RegistryBinding[];
+export declare function lookupSession(sessionId: string, now?: number): Array<{
+    name: string;
+    squarePath: string;
+}>;
+export declare function lookupParticipant(squarePath: string, name: string, now?: number): RegistryBinding[];
+/** Resolve the current local harness owner for a participant, if one is registered. */
+export declare function localParticipantOwner(squarePath: string, name: string, env?: NodeJS.ProcessEnv, now?: number): string | undefined;
+export declare function localParticipantName(squarePath: string, env?: NodeJS.ProcessEnv): string | undefined;
+export interface RegistryPruneResult {
+    removed: number;
+    kept: number;
+}
+/** Compact the registry and remove only bindings disproved by their authoritative artifact. */
+export declare function pruneRegistry(readActs: (squarePath: string) => StoredAct[] | undefined, now?: number): RegistryPruneResult;
+export interface LocalSessionIdentity {
+    sessionId: string;
+    channel: SessionChannel;
+    child: boolean;
+    paseoAgentId?: string;
+}
+export declare function localSessionIdentities(env?: NodeJS.ProcessEnv): LocalSessionIdentity[];
+/** True when this process belongs to a harness that can deliver Square attention without a foreground catch. */
+export declare function hasAutomaticDeliveryIdentity(env?: NodeJS.ProcessEnv): boolean;
+export declare function recordLocalJoin(name: string, squarePath: string, env?: NodeJS.ProcessEnv): void;
+export declare function recordLocalDone(name: string, squarePath: string, env?: NodeJS.ProcessEnv): void;
+export declare function recordSessionJoin(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): string;
+export declare function recordSessionDone(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): boolean;

package/dist/registry.js

@@ -36,8 +36,8 @@ export function canonicalSquarePath(squarePath) {
         return absolute;
     }
 }
-function bindingKey(sessionId, squarePath, name) {
-    return JSON.stringify([sessionId, canonicalSquarePath(squarePath), nameKey(name)]);
+function bindingKey(sessionId, squarePath, name, channel) {
+    return JSON.stringify([sessionId, canonicalSquarePath(squarePath), nameKey(name), channel]);
 }
 function participantKey(squarePath, name) {
     return JSON.stringify([canonicalSquarePath(squarePath), nameKey(name)]);
@@ -94,7 +94,7 @@ function foldRegistry(raw, now) {
             continue;
         order++;
         const ownerId = entry.owner_id ?? `legacy:${order}`;
-        state.set(bindingKey(entry.session_id, entry.square_path, entry.name), {
+        state.set(bindingKey(entry.session_id, entry.square_path, entry.name, entry.channel), {
             entry,
             updatedAt: Date.parse(entry.ts),
             ownerId,
@@ -231,6 +231,11 @@ export function localParticipantOwner(squarePath, name, env = process.env, now =
         return undefined;
     return lookupParticipant(squarePath, name, now).find((binding) => sessionIds.has(binding.sessionId))?.ownerId;
 }
+export function localParticipantName(squarePath, env = process.env) {
+    const identities = localSessionIdentities(env);
+    const names = new Set(identities.flatMap((identity) => lookupSession(identity.sessionId).filter((item) => canonicalSquarePath(item.squarePath) === canonicalSquarePath(squarePath)).map((item) => item.name)));
+    return names.size === 1 ? [...names][0] : undefined;
+}
 function bindingIsProvablyObsolete(binding, acts) {
     return acts !== undefined && !isCurrentlyJoined(acts, binding.name);
 }
@@ -306,3 +311,31 @@ export function recordLocalDone(name, squarePath, env = process.env) {
         retireOwnerWakeRoutes(ownerId, { at, env });
     }
 }
+export function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) {
+    const at = Date.now();
+    const ownerId = nextOwnerId();
+    const current = lookupParticipant(squarePath, name, at);
+    for (const binding of current) {
+        recordDone(binding.sessionId, binding.name, binding.squarePath, {
+            channel: binding.channel,
+            child: binding.child,
+            ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}),
+            at,
+        });
+        retireOwnerWakeRoutes(binding.ownerId, { at, env });
+    }
+    recordJoin(sessionId, name, squarePath, { channel, at, ownerId });
+    publishWakeRoutes(ownerId, { at, env });
+    return ownerId;
+}
+export function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) {
+    const binding = lookupSessionBindings(sessionId).find((item) => canonicalSquarePath(item.squarePath) === canonicalSquarePath(squarePath)
+        && sameName(item.name, name)
+        && item.channel === channel);
+    if (binding === undefined)
+        return false;
+    const at = Date.now();
+    recordDone(sessionId, binding.name, binding.squarePath, { channel, at });
+    retireOwnerWakeRoutes(binding.ownerId, { at, env });
+    return true;
+}

package/dist/routes.d.ts

@@ -0,0 +1,42 @@
+import { type WakeRoute, type WakeRouteKind } from './model.js';
+export { isWakeRouteKind, WAKE_ROUTE_KINDS } from './model.js';
+export type { WakeRoute, WakeRouteKind } from './model.js';
+export declare const ROUTE_FRESH_MS: number;
+export declare function routesPath(env?: NodeJS.ProcessEnv): string;
+export declare function readWakeRoutes(opts?: {
+    ownerId?: string;
+    freshOnly?: boolean;
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): WakeRoute[];
+export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opts?: {
+    at?: number;
+    env?: NodeJS.ProcessEnv;
+}): void;
+export declare function retireOwnerWakeRoutes(ownerId: string, opts?: {
+    at?: number;
+    env?: NodeJS.ProcessEnv;
+}): void;
+export interface WakeRouteEvidence {
+    sessionId: string;
+    address: Record<string, string>;
+}
+/** A provider's self-check: complete, callable endpoint evidence for one kind, or nothing. */
+export type WakeRouteProbe = (env: NodeJS.ProcessEnv) => WakeRouteEvidence | undefined;
+/**
+ * One probe per kind. A probe publishes only when its provider's complete
+ * endpoint evidence is present; session identity alone never publishes. The
+ * four native transports have no endpoint lifecycle in this delivery, so
+ * their probes publish nothing until those transports land.
+ */
+export declare const WAKE_ROUTE_PROBES: Readonly<Record<WakeRouteKind, WakeRouteProbe>>;
+/** The kind-neutral publication loop; probes supply complete evidence per kind. */
+export declare function publishWakeRoutesFrom(ownerId: string, probes: Readonly<Record<WakeRouteKind, WakeRouteProbe>>, opts?: {
+    at?: number;
+    env?: NodeJS.ProcessEnv;
+}): void;
+/** Publication boundary: every route written is complete provider evidence. */
+export declare function publishWakeRoutes(ownerId: string, opts?: {
+    at?: number;
+    env?: NodeJS.ProcessEnv;
+}): void;

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+import { type ActivityId, type Reach } from './square-core.js';
+import { type StoredAct, type SquareState, type HoldState, type ReadCursor, type WatchLease } from './model.js';
+export declare const WATCH_HEARTBEAT_MS: number;
+export declare const SLEEP_MS: number;
+export declare const STALE_MS: number;
+export declare const WATCH_STALE_MS: number;
+export declare const LOCK_RETRY_MS: number;
+export declare const LOCK_STALE_MS: number;
+export declare const THROTTLE_WINDOW_MS: number;
+export declare const UNREAD_BLOCK_GRACE_MS: number;
+export declare function nowMs(): number;
+/** Pure directed-activity filter. Bell matches every viewer; mentions match by audience. */
+export declare function matchesMentionTarget(act: {
+    body: string;
+    reach?: Reach;
+}, mention: string | true): boolean;
+export declare function foldedState(squareState: SquareState): import("./square-core.js").FoldedSquareState;
+export declare function rosterNames(squareState: SquareState): string[];
+export declare function inSquareCount(squareState: SquareState): number;
+export declare function resolveRosterName(squareState: SquareState, name: string): string | undefined;
+export declare function hasQuorum(squareState: SquareState, name: string, outs: Set<string>): boolean;
+export declare function countSays(acts: StoredAct[], name: string): number;
+export declare function sayNumberFor(acts: StoredAct[], target: StoredAct): number;
+/** Shared terminal condition for a participant's watch lifecycle. */
+export declare function watchTerminalStatus(squareState: SquareState, name: string): 'capped' | 'quorum' | undefined;
+export declare function doneNames(acts: StoredAct[]): Set<string>;
+export declare function joinedNames(acts: StoredAct[]): Set<string>;
+export declare function isCurrentlyJoined(acts: StoredAct[], name: string): boolean;
+/** Stable index of the recipient's most recent join act, if any. */
+export declare function lastJoinIndex(acts: StoredAct[], name: string): number | undefined;
+export declare function actStableIndex(act: StoredAct): number;
+export declare function actId(actOrIndex: StoredAct | number): ActivityId;
+export declare function getReadState(squareState: SquareState, name: string): ReadCursor | undefined;
+export declare function readCursor(squareState: SquareState, name: string): number;
+export declare function currentHold(acts: StoredAct[]): HoldState;
+export declare function publicActs(acts: StoredAct[]): Array<Extract<StoredAct, {
+    kind: 'say' | 'done';
+}>>;
+export declare function advanceCursor(squareState: SquareState, name: string, index: number, updatedAt?: number): boolean;
+export declare function touchPresenceCursor(squareState: SquareState, name: string, at: number, consumedThroughIndex?: number): boolean;
+export declare function latestActIndex(acts: StoredAct[]): number;
+export declare function freshWatchLease(squareState: SquareState, name: string, at?: number): WatchLease | undefined;
+export declare function watchLease(squareState: SquareState, name: string): WatchLease | undefined;
+export declare function writeWatchLease(squareState: SquareState, name: string, lease: WatchLease): void;
+export declare function removeWatchLease(squareState: SquareState, name: string, leaseId: string): boolean;

package/dist/runtime.js

@@ -1,4 +1,4 @@
-import { fold } from './square-core.js';
+import { audienceIncludes, audienceOf, fold, formatActivityId } from './square-core.js';
 import { SquareError, findParticipantName, nameKey, sameName, } from './model.js';
 function parseIntegerEnvValue(name, raw, fallback) {
     if (raw === undefined)
@@ -51,42 +51,27 @@ export function nowMs() {
     }
     return value;
 }
-export function extractMentions(body) {
-    const matches = [];
-    const re = /@([\p{L}\p{N}_-]+)/gu;
-    let match;
-    while ((match = re.exec(body)) !== null)
-        matches.push(match[1]);
-    return matches;
-}
-/** Pure directed-activity filter. Broadcast bodies (no @) match any named viewer. */
+/** Pure directed-activity filter. Bell matches every viewer; mentions match by audience. */
 export function matchesMentionTarget(act, mention) {
-    if (act.reach === 'bell')
-        return true;
-    if (act.reach !== undefined) {
-        return mention === true || sameName(act.reach.beside, mention);
-    }
-    const mentions = extractMentions(act.body);
+    const audience = audienceOf(act);
     if (mention === true)
-        return mentions.length > 0;
-    if (mentions.length === 0)
-        return true;
-    return mentions.some((name) => sameName(name, mention));
+        return audience.kind === 'bell' || audience.names.length > 0;
+    return audienceIncludes(audience, mention);
 }
-export function foldedState(doc) {
-    return fold(doc.acts);
+export function foldedState(squareState) {
+    return fold(squareState.acts);
 }
-export function rosterNames(doc) {
-    return foldedState(doc).participants.map((participant) => participant.name);
+export function rosterNames(squareState) {
+    return foldedState(squareState).participants.map((participant) => participant.name);
 }
-export function inSquareCount(doc) {
-    return foldedState(doc).joined.length;
+export function inSquareCount(squareState) {
+    return foldedState(squareState).joined.length;
 }
-export function resolveRosterName(doc, name) {
-    return findParticipantName(rosterNames(doc), name);
+export function resolveRosterName(squareState, name) {
+    return findParticipantName(rosterNames(squareState), name);
 }
-export function hasQuorum(doc, name, outs) {
-    const peers = rosterNames(doc).filter((participant) => !sameName(participant, name));
+export function hasQuorum(squareState, name, outs) {
+    const peers = rosterNames(squareState).filter((participant) => !sameName(participant, name));
     return peers.length > 0 && peers.every((peer) => outs.has(nameKey(peer)));
 }
 export function countSays(acts, name) {
@@ -106,6 +91,14 @@ export function sayNumberFor(acts, target) {
     }
     throw new Error('target say act is not present in act history');
 }
+/** Shared terminal condition for a participant's watch lifecycle. */
+export function watchTerminalStatus(squareState, name) {
+    if (squareState.hardCap !== null && countSays(squareState.acts, name) >= squareState.hardCap)
+        return 'capped';
+    const done = doneNames(squareState.acts);
+    done.delete(nameKey(name));
+    return hasQuorum(squareState, name, done) ? 'quorum' : undefined;
+}
 export function doneNames(acts) {
     return new Set(fold(acts).done.map((participant) => nameKey(participant)));
 }
@@ -131,13 +124,13 @@ export function actStableIndex(act) {
 }
 export function actId(actOrIndex) {
     const index = typeof actOrIndex === 'number' ? actOrIndex : actStableIndex(actOrIndex);
-    return `act_${index}`;
+    return formatActivityId(index);
 }
-export function getReadState(doc, name) {
-    return doc.runtime.cursors[name] ?? Object.entries(doc.runtime.cursors).find(([participant]) => sameName(participant, name))?.[1];
+export function getReadState(squareState, name) {
+    return squareState.runtime.cursors[name] ?? Object.entries(squareState.runtime.cursors).find(([participant]) => sameName(participant, name))?.[1];
 }
-export function readCursor(doc, name) {
-    return getReadState(doc, name)?.consumedThroughIndex ?? -1;
+export function readCursor(squareState, name) {
+    return getReadState(squareState, name)?.consumedThroughIndex ?? -1;
 }
 export function currentHold(acts) {
     const hold = fold(acts).hold;
@@ -146,48 +139,48 @@ export function currentHold(acts) {
 export function publicActs(acts) {
     return acts.filter((act) => act.kind === 'say' || act.kind === 'done');
 }
-function canonicalRuntimeName(doc, name) {
-    return resolveRosterName(doc, name) ?? name;
+function canonicalRuntimeName(squareState, name) {
+    return resolveRosterName(squareState, name) ?? name;
 }
-export function advanceCursor(doc, name, index, updatedAt = Date.now()) {
-    return touchPresenceCursor(doc, name, updatedAt, index);
+export function advanceCursor(squareState, name, index, updatedAt = Date.now()) {
+    return touchPresenceCursor(squareState, name, updatedAt, index);
 }
-export function touchPresenceCursor(doc, name, at, consumedThroughIndex) {
+export function touchPresenceCursor(squareState, name, at, consumedThroughIndex) {
     if (!Number.isFinite(at))
         return false;
     if (consumedThroughIndex !== undefined && (!Number.isInteger(consumedThroughIndex) || consumedThroughIndex < 0))
         return false;
-    const key = canonicalRuntimeName(doc, name);
-    const current = getReadState(doc, key);
+    const key = canonicalRuntimeName(squareState, name);
+    const current = getReadState(squareState, key);
     const nextIndex = consumedThroughIndex === undefined
-        ? (current?.consumedThroughIndex ?? readCursor(doc, key))
+        ? (current?.consumedThroughIndex ?? readCursor(squareState, key))
         : Math.max(current?.consumedThroughIndex ?? -1, consumedThroughIndex);
     const updatedAt = current === undefined ? at : Math.max(current.updatedAt, at);
     if (current?.consumedThroughIndex === nextIndex && current.updatedAt === updatedAt)
         return false;
-    doc.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt };
+    squareState.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt };
     return true;
 }
 export function latestActIndex(acts) {
     return acts.reduce((max, act) => Math.max(max, act.index), -1);
 }
-export function freshWatchLease(doc, name, at = Date.now()) {
-    const key = canonicalRuntimeName(doc, name);
-    const lease = watchLease(doc, key);
+export function freshWatchLease(squareState, name, at = Date.now()) {
+    const key = canonicalRuntimeName(squareState, name);
+    const lease = watchLease(squareState, key);
     if (lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS)
         return undefined;
     return lease;
 }
-export function watchLease(doc, name) {
-    return doc.runtime.leases[canonicalRuntimeName(doc, name)];
+export function watchLease(squareState, name) {
+    return squareState.runtime.leases[canonicalRuntimeName(squareState, name)];
 }
-export function writeWatchLease(doc, name, lease) {
-    doc.runtime.leases[canonicalRuntimeName(doc, name)] = lease;
+export function writeWatchLease(squareState, name, lease) {
+    squareState.runtime.leases[canonicalRuntimeName(squareState, name)] = lease;
 }
-export function removeWatchLease(doc, name, leaseId) {
-    const key = canonicalRuntimeName(doc, name);
-    if (doc.runtime.leases[key]?.leaseId !== leaseId)
+export function removeWatchLease(squareState, name, leaseId) {
+    const key = canonicalRuntimeName(squareState, name);
+    if (squareState.runtime.leases[key]?.leaseId !== leaseId)
         return false;
-    delete doc.runtime.leases[key];
+    delete squareState.runtime.leases[key];
     return true;
 }