@astrosheep/square 0.3.12 → 0.3.13

package/dist/presentation.js

@@ -1,6 +1,8 @@
 import { sameName } from './model.js';
 import fs from 'node:fs';
 import path from 'node:path';
+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';
@@ -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) {
@@ -151,31 +154,31 @@ export function renderEventCli(event, opts = {}) {
             const body = renderedBody(event.body, maxBody);
             const mention = opts.mention;
             const mentionSuffix = mention !== undefined && audienceIncludes(audienceOf(event), mention)
-                ? ` · calls your name across the square — @${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) {
+function renderPresenceOnlySay(event, opts = {}) {
     const audience = audienceOf(event);
     const targets = audience.kind === 'bell' ? [] : audience.names;
-    const dest = targets.length === 0 ? '' : ` to ${targets.map((name) => `@${name}`).join(' and ')}`;
-    return `*${event.actor} walks over${dest}*`;
+    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 renderAmbientEvent(event, viewer, opts = {}) {
     if (event.kind !== 'say')
         return renderEventCli(event, opts);
     const seen = perceive(event, viewer);
     if (seen === 'presence')
-        return renderPresenceOnlySay(event);
+        return renderPresenceOnlySay(event, opts);
     return renderEventCli(event, opts);
 }
 function draftSavedLines(draftPath) {
@@ -190,10 +193,11 @@ function renderUnreadSummary(opts) {
             ...item.previews.slice(-1).map((preview) => {
                 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)}`),
@@ -260,10 +264,10 @@ export function renderPublicTail(events, lastN, now, viewer = '') {
         .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];
+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;
@@ -273,15 +277,15 @@ 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 = '', mode = 'ambient') {
+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]);
     }
@@ -289,7 +293,7 @@ export function renderActivitiesView(doc, visible, lastN, full, squarePath, view
     for (const act of shown) {
         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)
@@ -326,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;
@@ -342,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' : ''}`);

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

@@ -58,20 +58,20 @@ export function matchesMentionTarget(act, 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) {
@@ -91,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)));
 }
@@ -118,11 +126,11 @@ export function actId(actOrIndex) {
     const index = typeof actOrIndex === 'number' ? actOrIndex : actStableIndex(actOrIndex);
     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;
@@ -131,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;
 }

package/dist/search.d.ts

@@ -0,0 +1,11 @@
+export declare function compileGrepPattern(pattern: string): RegExp;
+export declare function compileFixedPattern(pattern: string): RegExp;
+export declare function compileSearchPattern(pattern: string, fixed: boolean): RegExp;
+export interface GrepSnippet {
+    before: string;
+    match: string;
+    after: string;
+    beforeOmitted: number;
+    afterOmitted: number;
+}
+export declare function grepSnippet(body: string, pattern: string, maxChars: number, fixed?: boolean): GrepSnippet | undefined;

package/dist/square-core.d.ts

@@ -0,0 +1,111 @@
+export type Participant = string;
+export type Reach = 'bell';
+export type Audience = {
+    readonly kind: 'bell';
+} | {
+    readonly kind: 'mentions';
+    readonly names: readonly string[];
+};
+export type ActivityId = `act/${number}`;
+export declare function formatActivityId(index: number): ActivityId;
+export declare function parseActivityId(value: string): number | undefined;
+export interface Hold {
+    active: boolean;
+    at?: number;
+    reason?: string;
+    actor?: Participant;
+}
+export type Act = {
+    kind: 'join';
+    actor: Participant;
+    at?: number;
+} | {
+    kind: 'done';
+    actor: Participant;
+    at?: number;
+    body?: string;
+} | {
+    kind: 'say';
+    actor: Participant;
+    at?: number;
+    body: string;
+    reach?: Reach;
+    reply?: number;
+} | {
+    kind: 'hold';
+    actor?: Participant;
+    at?: number;
+    body?: string;
+} | {
+    kind: 'resume';
+    actor?: Participant;
+    at?: number;
+} | {
+    kind: 'read';
+    actor: Participant;
+    at?: number;
+    through: number;
+};
+export interface SquareValidationOptions {
+    hardCap?: number | null;
+    throttlePerMinute?: number;
+    throttleWindowMs?: number;
+}
+export type Perception = 'full' | 'presence';
+interface ParticipantSnapshot {
+    name: Participant;
+    key: string;
+    joined: boolean;
+    done: boolean;
+    activityCount: number;
+    lastActiveAt?: number;
+    lastReadThrough: number;
+}
+export interface FoldedSquareState {
+    participants: ParticipantSnapshot[];
+    hold: Hold;
+    joined: Participant[];
+    done: Participant[];
+    throttleActivityAts: number[];
+    bellSayAtsByActor: Map<string, number[]>;
+}
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'already_joined';
+} | {
+    ok: false;
+    reason: 'not_joined';
+} | {
+    ok: false;
+    reason: 'done';
+} | {
+    ok: false;
+    reason: 'held';
+    hold: Hold;
+} | {
+    ok: false;
+    reason: 'hard_cap';
+    count: number;
+    hardCap: number;
+} | {
+    ok: false;
+    reason: 'throttled';
+    delayMs: number;
+} | {
+    ok: false;
+    reason: 'bell_quota';
+    nextAt: number;
+};
+export declare function extractMentions(body: string): string[];
+export declare function audienceOf(say: {
+    body: string;
+    reach?: Reach;
+}): Audience;
+export declare function audienceIncludes(audience: Audience, name: string): boolean;
+export declare function resolveAudience(audience: Audience, candidateNames: readonly string[]): string[];
+export declare function fold(acts: readonly Act[]): FoldedSquareState;
+export declare function validate(state: FoldedSquareState, act: Act, options?: SquareValidationOptions): ValidationResult;
+export declare function perceive(act: Act, viewer: Participant | string): Perception;
+export {};