@astrosheep/square 0.3.14 → 0.3.15

package/dist/presence.js

@@ -1,14 +1,17 @@
-import { extractMentions, formatActivityId, perceive } from './square-core.js';
-import { ackPeerDelta, deliveryDelta, filteredRoomChanges, matchesFeedFilter, peerPublicActs } from './activity-feed.js';
-import { markDeliveredNotifications } from './delivery.js';
+import { extractMentions, formatActivityId } from './square-core.js';
+import { deliveryDelta, filteredRoomChanges, matchesFeedFilter, peerPublicActs } from './activity-feed.js';
+import { deriveDeliveryModel, markSeenNotifications, perceiveActivity } from './delivery.js';
 import { SquareError } from './model.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
 import { resolveKnownName } from './decisions.js';
 import { readCursor } from './runtime.js';
-function expose(activity, viewer) {
+import { recordObservation } from './runtime.js';
+function expose(squareState, activity, viewer) {
     if (activity.kind === 'read' || activity.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(activity.index)}`);
-    const perception = perceive(activity, viewer);
-    const result = { id: formatActivityId(activity.index), at: activity.at, kind: activity.kind, actor: activity.actor, mentions: activity.kind === 'say' ? extractMentions(activity.body) : [], ...('body' in activity && activity.body !== undefined ? { body: activity.body } : {}), ...(activity.kind === 'say' && activity.reply !== undefined ? { reply: formatActivityId(activity.reply) } : {}) };
+    const perception = perceiveActivity(squareState, activity, viewer);
+    const result = { id: formatActivityId(activity.index), at: activity.at, kind: activity.kind, actor: activity.actor, mentions: activity.kind === 'say' ? extractMentions(activity.body) : [], ...('body' in activity && activity.body !== undefined ? { body: activity.body } : {}), ...('target' in activity ? { target: activity.target } : {}), ...(activity.kind === 'say' && activity.reply !== undefined ? { reply: formatActivityId(activity.reply) } : {}) };
     if (perception === 'full' || !('body' in result))
         return { ...result, perception };
     const { body: _body, ...withoutBody } = result;
@@ -25,13 +28,14 @@ export async function catchUp(square, name, options = {}) {
             const viewer = resolveKnownName(state, name);
             const delta = deliveryDelta(state, viewer);
             const filter = { ...(options.from === undefined ? {} : { participants: [...options.from] }), ...(options.mention === true ? { mention: viewer } : {}) };
-            const delivered = [...peerPublicActs(delta, viewer).filter((activity) => matchesFeedFilter(activity, filter)), ...filteredRoomChanges(delta, viewer, filter)]
+            const delivery = deriveDeliveryModel(state);
+            const delivered = [...peerPublicActs(delta, viewer).filter((activity) => matchesFeedFilter(activity, filter, activity.kind === 'say' ? delivery.plan(activity).map((planned) => planned.recipient) : undefined)), ...filteredRoomChanges(delta, viewer, filter)]
                 .filter((activity, index, activities) => activities.findIndex((candidate) => candidate.index === activity.index) === index)
                 .sort((left, right) => left.index - right.index);
-            const cursorChanged = ackPeerDelta(state, viewer, delta, at);
-            const receiptsChanged = markDeliveredNotifications(state, viewer, delivered, at);
+            const seenChanged = delivered.reduce((changed, activity) => recordObservation(state, viewer, activity.index, 'seen', at) || changed, false)
+                || markSeenNotifications(state, viewer, delivered, at);
             const cursor = readCursor(state, viewer);
-            return { ...(cursorChanged || receiptsChanged ? { state } : {}), result: { version, caught: { activities: delivered.map((activity) => expose(activity, viewer)), consumedThrough: cursor < 0 ? null : formatActivityId(cursor), idleExpired: false } } };
+            return { ...(seenChanged ? { state } : {}), result: { version, caught: { activities: delivered.map((activity) => expose(state, activity, viewer)), consumedThrough: cursor < 0 ? null : formatActivityId(cursor), idleExpired: false } } };
         });
         if (attempt.caught.activities.length > 0 || idle === 0)
             return attempt.caught;
@@ -40,3 +44,29 @@ export async function catchUp(square, name, options = {}) {
             return { ...attempt.caught, idleExpired: true };
     }
 }
+/** Commit seen only for complete, actually rendered boundary bodies. */
+export async function markBoundarySeen(squarePath, name, ownerId, actIndexes, at = Date.now()) {
+    let square;
+    try {
+        square = await openSquare(squarePath);
+    }
+    catch {
+        return;
+    }
+    try {
+        await square.cell.transact((state) => {
+            let changed = false;
+            for (const index of actIndexes)
+                changed = recordObservation(state, name, index, 'seen', at, ownerId) || changed;
+            return changed ? { state, result: undefined } : { result: undefined };
+        });
+    }
+    finally {
+        await closeOpenSquare(square);
+    }
+}
+export async function markNotificationNotified(square, name, actIndex, ownerId, at = Date.now()) {
+    await square.cell.transact((state) => recordObservation(state, name, actIndex, 'notified', at, ownerId)
+        ? { state, result: undefined }
+        : { result: undefined });
+}

package/dist/presentation.d.ts

@@ -1,5 +1,6 @@
 import { type StoredAct, type SquareState, type PublicAct, type RoomChangeAct } from './model.js';
 export { participantIdentity } from './participant-identity.js';
+import { type Perception } from './square-core.js';
 import type { UnreadActivitySummary, ParticipantStatus } from './decisions.js';
 export type WatchStatus = 'stale' | 'empty-now' | 'quorum' | 'capped';
 interface HeaderOptions {
@@ -66,12 +67,14 @@ export declare function renderAmbientEvent(event: StoredAct, viewer: string, opt
     preview?: number;
     actNumber?: number;
     mention?: string;
+    squareState?: SquareState;
+    perception?: Perception;
 }): string;
-export declare function renderPendingFeed(history: StoredAct[], publicItems: PublicAct[], roomChanges: RoomChangeAct[], viewer?: string): string;
+export declare function renderPendingFeed(history: StoredAct[], publicItems: PublicAct[], roomChanges: RoomChangeAct[], viewer: string | undefined, squareState: SquareState): string;
 export declare function renderActivityBlocked(opts: ActivityBlockedOptions): string;
 export declare function renderExpressWaiting(opts: ExpressWaitingOptions): string;
 export declare function renderExpressNoWait(opts: ExpressNoWaitOptions): string;
-export declare function renderPublicTail(events: StoredAct[], lastN: number | null | undefined, now?: number, viewer?: string): string;
+export declare function renderPublicTail(squareState: SquareState, events: StoredAct[], lastN: number | null | undefined, now?: number, viewer?: string): string;
 export declare function renderActivitiesView(squareState: SquareState, visible: StoredAct[], lastN: number | null | undefined, full: boolean | undefined, squarePath: string, viewer?: string, mode?: 'ambient' | 'archive'): string;
 export declare function renderGrepActivitiesView(visible: StoredAct[], totalMatches: number, full: boolean | undefined, squarePath: string, pattern: string, fixed?: boolean): string;
 export declare function renderActivityLimit(opts: ActivityLimitOptions): string;
@@ -88,4 +91,5 @@ export declare function renderWatchOutput(history: StoredAct[], publicItems: Pub
     mention?: string;
     viewer: string;
     showCatchHint?: boolean;
+    squareState: SquareState;
 }): string;

package/dist/presentation.js

@@ -3,7 +3,8 @@ 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 { audienceIncludes, audienceOf } from './square-core.js';
+import { perceiveActivity } from './delivery.js';
 import { actId, publicActs, readCursor, rosterNames, sayNumberFor } from './runtime.js';
 import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { grepSnippet } from './search.js';
@@ -128,6 +129,10 @@ export function renderRoomChangeText(event) {
             return `${identity} raised a hand${event.body ? ` — ${event.body}` : ''}`;
         case 'resume':
             return `${identity} lowered the hand`;
+        case 'listen':
+            return `${identity} turns an ear toward ${participantIdentity(event.target)}`;
+        case 'ignore':
+            return `${identity} turns away from ${participantIdentity(event.target)}`;
     }
 }
 function renderedBody(body, maxChars) {
@@ -150,6 +155,9 @@ export function renderEventCli(event, opts = {}) {
             return `· ${renderRoomChangeText(event)}`;
         case 'resume':
             return `✓ ${renderRoomChangeText(event)}`;
+        case 'listen':
+        case 'ignore':
+            return `· ${renderRoomChangeText(event)}`;
         case 'say': {
             const body = renderedBody(event.body, maxBody);
             const mention = opts.mention;
@@ -176,7 +184,10 @@ function renderPresenceOnlySay(event, opts = {}) {
 export function renderAmbientEvent(event, viewer, opts = {}) {
     if (event.kind !== 'say')
         return renderEventCli(event, opts);
-    const seen = perceive(event, viewer);
+    if (opts.perception === undefined && opts.squareState === undefined) {
+        throw new Error('Ambient say rendering requires a settled perception or SquareState');
+    }
+    const seen = opts.perception ?? perceiveActivity(opts.squareState, event, viewer);
     if (seen === 'presence')
         return renderPresenceOnlySay(event, opts);
     return renderEventCli(event, opts);
@@ -191,10 +202,10 @@ function renderUnreadSummary(opts) {
     return [
         ...opts.activitySummaries.flatMap((item) => [
             ...item.previews.slice(-1).map((preview) => {
-                const rendered = renderAmbientEvent(preview.act, opts.viewer, { actNumber: preview.number });
+                const rendered = renderAmbientEvent(preview.act, opts.viewer, { actNumber: preview.number, perception: preview.perception });
                 if (rendered === '')
                     return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago`;
-                if (preview.act.kind === 'say' && perceive(preview.act, opts.viewer) === 'presence') {
+                if (preview.perception === '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)}"`;
@@ -203,11 +214,12 @@ function renderUnreadSummary(opts) {
         ...opts.roomChanges.map((act) => `  · ${renderRoomChangeText(act)}`),
     ];
 }
-export function renderPendingFeed(history, publicItems, roomChanges, viewer = '') {
+export function renderPendingFeed(history, publicItems, roomChanges, viewer = '', squareState) {
     const lines = [];
     for (const act of publicItems) {
         const rendered = renderAmbientEvent(act, viewer, {
             actNumber: act.kind === 'say' ? sayNumberFor(history, act) : undefined,
+            ...(squareState === undefined ? {} : { squareState }),
         });
         if (rendered !== '')
             lines.push(rendered);
@@ -255,12 +267,12 @@ export function renderExpressNoWait(opts) {
         ];
     return withPathOutput(opts.squarePath, lines.join('\n'), { participantCount: opts.participantCount, held: opts.held });
 }
-export function renderPublicTail(events, lastN, now, viewer = '') {
+export function renderPublicTail(squareState, events, lastN, now, viewer = '') {
     const publicItems = publicActs(events);
     const selected = lastN == null ? publicItems : publicItems.slice(-lastN);
     const preview = lastN == null ? undefined : BODY_PREVIEW_LENGTH;
     return selected
-        .map((event) => renderAmbientEvent(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, squareState }))
         .filter(Boolean)
         .join('\n\n');
 }
@@ -297,7 +309,7 @@ export function renderActivitiesView(squareState, visible, lastN, full, squarePa
         };
         const rendered = mode === 'archive'
             ? renderEventCli(act, opts)
-            : renderAmbientEvent(act, viewer, opts);
+            : renderAmbientEvent(act, viewer, { ...opts, squareState });
         if (rendered !== '')
             chunks.push(rendered);
         for (const participant of markers.get(act.index) ?? []) {
@@ -307,7 +319,7 @@ export function renderActivitiesView(squareState, visible, lastN, full, squarePa
     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 && (mode === 'archive' || perceive(act, viewer) === 'full'));
+        const truncated = shown.some((act) => act.kind === 'say' && act.body.length > previewLen && (mode === 'archive' || perceiveActivity(squareState, act, viewer) === 'full'));
         if (truncated)
             chunks.push(`» ${commandPrefix(squarePath)} history --full`);
     }
@@ -440,6 +452,7 @@ export function renderWatchOutput(history, publicItems, roomChanges, opts) {
             .map((act) => renderAmbientEvent(act, opts.viewer, {
             actNumber: act.kind === 'say' ? sayNumberFor(history, act) : undefined,
             mention: opts.mention,
+            squareState: opts.squareState,
         }))
             .filter(Boolean)
             .join('\n\n');

package/dist/presented.d.ts

@@ -3,6 +3,8 @@ 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;
+/** Record presentation by a transport that delivered the bounded attention body. */
+export declare function recordPresentedForOwner(ownerId: string, squarePath: string, name: string, actIndex: number, env?: NodeJS.ProcessEnv, at?: number): void;
 /**
  * Serialize presentation only for the affected participants. Delivery runs
  * outside the short ledger-write lock, so unrelated owners never wait on an

package/dist/presented.js

@@ -106,6 +106,26 @@ export function hasPresentedAttention(squarePath, name, actIndex, env = process.
         return false;
     return [...ownerIds].some((ownerId) => hasPresentedForOwner(ownerId, squarePath, name, actIndex, env, now));
 }
+/** Record presentation by a transport that delivered the bounded attention body. */
+export function recordPresentedForOwner(ownerId, squarePath, name, actIndex, env = process.env, at = Date.now()) {
+    const filePath = presentedPath(env);
+    const row = {
+        v: 2,
+        ts: at,
+        owner_id: ownerId,
+        square_path: canonicalSquarePath(squarePath),
+        name,
+        act_index: actIndex,
+    };
+    withAttentionLocks(filePath, [{ name, squarePath, notifications: [] }], () => {
+        withFileLockSync(`${filePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, () => {
+            const rows = readRows(filePath, at);
+            const known = new Set(rows.map(rowKey));
+            if (!known.has(rowKey(row)))
+                writeRows(filePath, [...rows, row]);
+        });
+    });
+}
 /**
  * Serialize presentation only for the affected participants. Delivery runs
  * outside the short ledger-write lock, so unrelated owners never wait on an

package/dist/registry.js

@@ -336,6 +336,9 @@ export function recordSessionDone(sessionId, name, squarePath, channel, env = pr
         return false;
     const at = Date.now();
     recordDone(sessionId, binding.name, binding.squarePath, { channel, at });
-    retireOwnerWakeRoutes(binding.ownerId, { at, env });
+    const remaining = lookupParticipant(squarePath, binding.name, at)
+        .some((candidate) => candidate.ownerId === binding.ownerId);
+    if (!remaining)
+        retireOwnerWakeRoutes(binding.ownerId, { at, env });
     return true;
 }

package/dist/routes.d.ts

@@ -17,6 +17,11 @@ export declare function retireOwnerWakeRoutes(ownerId: string, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): void;
+/** Retire one capability without touching sibling identities in the same claim. */
+export declare function retireWakeRoute(route: Pick<WakeRoute, 'ownerId' | 'sessionId' | 'kind'>, opts?: {
+    at?: number;
+    env?: NodeJS.ProcessEnv;
+}): void;
 export interface WakeRouteEvidence {
     sessionId: string;
     address: Record<string, string>;

package/dist/routes.js

@@ -108,6 +108,23 @@ export function retireOwnerWakeRoutes(ownerId, opts = {}) {
         }, env);
     }
 }
+/** Retire one capability without touching sibling identities in the same claim. */
+export function retireWakeRoute(route, opts = {}) {
+    const at = opts.at ?? Date.now();
+    const env = opts.env ?? process.env;
+    const current = readWakeRoutes({ ownerId: route.ownerId, now: at, env })
+        .find((candidate) => candidate.sessionId === route.sessionId && candidate.kind === route.kind);
+    if (current === undefined)
+        return;
+    appendRouteRow({
+        v: 1,
+        ts: at,
+        op: 'retire',
+        owner_id: route.ownerId,
+        session_id: route.sessionId,
+        kind: route.kind,
+    }, env);
+}
 /** Publication requires a non-blank session and a non-empty address of non-blank values. */
 function completeRouteEvidence(value) {
     if (value === undefined || value === null)

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 import { type ActivityId, type Reach } from './square-core.js';
-import { type StoredAct, type SquareState, type HoldState, type ReadCursor, type WatchLease } from './model.js';
+import { type StoredAct, type SquareState, type HoldState, type ActivityObservation, type ObservationState, type WatchLease } from './model.js';
 export declare const WATCH_HEARTBEAT_MS: number;
 export declare const SLEEP_MS: number;
 export declare const STALE_MS: number;
@@ -30,14 +30,13 @@ export declare function isCurrentlyJoined(acts: StoredAct[], name: string): bool
 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 observationFor(squareState: SquareState, name: string, index: number): ActivityObservation | undefined;
+export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number, ownerId?: string): boolean;
+export declare function readCursor(squareState: SquareState, name: string): number;
 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;

package/dist/runtime.js

@@ -126,11 +126,12 @@ export function actId(actOrIndex) {
     const index = typeof actOrIndex === 'number' ? actOrIndex : actStableIndex(actOrIndex);
     return formatActivityId(index);
 }
-export function getReadState(squareState, name) {
-    return squareState.runtime.cursors[name] ?? Object.entries(squareState.runtime.cursors).find(([participant]) => sameName(participant, name))?.[1];
+function observationRecipient(squareState, name) {
+    return resolveRosterName(squareState, name) ?? name;
 }
-export function readCursor(squareState, name) {
-    return getReadState(squareState, name)?.consumedThroughIndex ?? -1;
+function observationMap(squareState, name) {
+    const key = observationRecipient(squareState, name);
+    return squareState.runtime.observations?.[key] ?? {};
 }
 export function currentHold(acts) {
     const hold = fold(acts).hold;
@@ -142,25 +143,41 @@ export function publicActs(acts) {
 function canonicalRuntimeName(squareState, name) {
     return resolveRosterName(squareState, name) ?? name;
 }
-export function advanceCursor(squareState, name, index, updatedAt = Date.now()) {
-    return touchPresenceCursor(squareState, name, updatedAt, index);
+export function observationFor(squareState, name, index) {
+    return observationMap(squareState, name)[formatActivityId(index)];
 }
-export function touchPresenceCursor(squareState, name, at, consumedThroughIndex) {
-    if (!Number.isFinite(at))
+export function recordObservation(squareState, name, index, state, at = Date.now(), ownerId) {
+    if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(at))
         return false;
-    if (consumedThroughIndex !== undefined && (!Number.isInteger(consumedThroughIndex) || consumedThroughIndex < 0))
-        return false;
-    const key = canonicalRuntimeName(squareState, name);
-    const current = getReadState(squareState, key);
-    const nextIndex = consumedThroughIndex === undefined
-        ? (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)
+    const key = observationRecipient(squareState, name);
+    const id = formatActivityId(index);
+    const current = squareState.runtime.observations[key]?.[id];
+    if (current?.state === 'seen' || (current?.state === state && current.at >= at && current.ownerId === ownerId))
         return false;
-    squareState.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt };
+    const next = {
+        state: state === 'seen' ? 'seen' : 'notified',
+        at: Math.max(current?.at ?? -Infinity, at),
+        ...(ownerId === undefined ? (current?.ownerId === undefined ? {} : { ownerId: current.ownerId }) : { ownerId }),
+    };
+    ((squareState.runtime.observations ??= {})[key] ??= {})[id] = next;
     return true;
 }
+export function readCursor(squareState, name) {
+    const boundary = lastJoinIndex(squareState.acts, name) ?? -1;
+    let cursor = boundary;
+    for (const act of squareState.acts) {
+        if (act.index <= boundary || act.kind === 'read' || act.actor === undefined)
+            continue;
+        if (sameName(act.actor, name)) {
+            cursor = act.index;
+            continue;
+        }
+        if (observationFor(squareState, name, act.index)?.state !== 'seen')
+            break;
+        cursor = act.index;
+    }
+    return cursor;
+}
 export function latestActIndex(acts) {
     return acts.reduce((max, act) => Math.max(max, act.index), -1);
 }

package/dist/square-core.d.ts

@@ -45,6 +45,16 @@ export type Act = {
     actor: Participant;
     at?: number;
     through: number;
+} | {
+    kind: 'listen';
+    actor: Participant;
+    target: Participant;
+    at?: number;
+} | {
+    kind: 'ignore';
+    actor: Participant;
+    target: Participant;
+    at?: number;
 };
 export interface SquareValidationOptions {
     hardCap?: number | null;
@@ -68,6 +78,7 @@ export interface FoldedSquareState {
     done: Participant[];
     throttleActivityAts: number[];
     bellSayAtsByActor: Map<string, number[]>;
+    listening: Map<string, Participant[]>;
 }
 export type ValidationResult = {
     ok: true;
@@ -105,6 +116,12 @@ export declare function audienceOf(say: {
 }): Audience;
 export declare function audienceIncludes(audience: Audience, name: string): boolean;
 export declare function resolveAudience(audience: Audience, candidateNames: readonly string[]): string[];
+export declare function activeListeners(state: FoldedSquareState, sender: string): string[];
+export declare function audienceBefore(acts: readonly Act[], say: Extract<Act, {
+    kind: 'say';
+}>): string[];
+export declare function listeningTo(state: FoldedSquareState, listener: string): string[];
+export declare function isListening(state: FoldedSquareState, listener: string, sender: string): boolean;
 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;

package/dist/square-core.js

@@ -20,7 +20,7 @@ function sameName(a, b) {
 }
 export function extractMentions(body) {
     const matches = [];
-    const re = /@([\p{L}\p{N}_-]+)/gu;
+    const re = /@([\p{L}\p{N}_-]+(?:\/[\p{L}\p{N}_-]+)*)/gu;
     let match;
     while ((match = re.exec(body)) !== null)
         matches.push(match[1]);
@@ -57,6 +57,30 @@ export function resolveAudience(audience, candidateNames) {
     }
     return resolved;
 }
+export function activeListeners(state, sender) {
+    return state.participants
+        .filter((participant) => participant.joined && (state.listening.get(nameKey(participant.name)) ?? []).some((target) => sameName(target, sender)))
+        .map((participant) => participant.name);
+}
+export function audienceBefore(acts, say) {
+    const position = acts.findIndex((act) => act === say || ('index' in act && 'index' in say && act.index === say.index));
+    const before = fold(position < 0 ? acts : acts.slice(0, position));
+    const mentionTargets = resolveAudience(audienceOf(say), before.joined);
+    const listeners = activeListeners(before, say.actor);
+    const recipients = [];
+    for (const name of [...mentionTargets, ...listeners]) {
+        if (sameName(name, say.actor) || recipients.some((existing) => sameName(existing, name)))
+            continue;
+        recipients.push(name);
+    }
+    return recipients;
+}
+export function listeningTo(state, listener) {
+    return [...(state.listening.get(nameKey(listener)) ?? [])];
+}
+export function isListening(state, listener, sender) {
+    return listeningTo(state, listener).some((target) => sameName(target, sender));
+}
 function actorOf(act) {
     if ('actor' in act && typeof act.actor === 'string')
         return act.actor;
@@ -115,6 +139,7 @@ export function fold(acts) {
         done: [],
         throttleActivityAts: [],
         bellSayAtsByActor: new Map(),
+        listening: new Map(),
     };
     for (const act of acts) {
         const actor = actorOf(act);
@@ -132,8 +157,26 @@ export function fold(acts) {
                     snapshot.joined = false;
                     snapshot.done = true;
                     snapshot.lastActiveAt = act.at ?? snapshot.lastActiveAt;
+                    state.listening.delete(nameKey(snapshot.name));
                 }
                 break;
+            case 'listen': {
+                const key = nameKey(act.actor);
+                const targets = state.listening.get(key) ?? [];
+                if (!targets.some((target) => sameName(target, act.target)))
+                    targets.push(act.target);
+                state.listening.set(key, targets);
+                break;
+            }
+            case 'ignore': {
+                const key = nameKey(act.actor);
+                const targets = (state.listening.get(key) ?? []).filter((target) => !sameName(target, act.target));
+                if (targets.length === 0)
+                    state.listening.delete(key);
+                else
+                    state.listening.set(key, targets);
+                break;
+            }
             case 'say':
                 if (snapshot !== undefined) {
                     snapshot.activityCount += 1;
@@ -178,6 +221,13 @@ export function validate(state, act, options = {}) {
             if (current?.joined !== true)
                 return { ok: false, reason: 'not_joined' };
             return { ok: true };
+        case 'listen':
+        case 'ignore':
+            if (current?.done)
+                return { ok: false, reason: 'done' };
+            if (current?.joined !== true)
+                return { ok: false, reason: 'not_joined' };
+            return { ok: true };
         case 'say': {
             if (current?.done)
                 return { ok: false, reason: 'done' };

package/dist/square-facade.d.ts

@@ -2,10 +2,11 @@ import type { ActivityId, Perception, Reach } from './square-core.js';
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
-    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume';
+    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore';
     readonly actor: string;
     readonly body?: string;
     readonly mentions: readonly string[];
+    readonly target?: string;
     readonly reply?: ActivityId;
 }
 export interface WakeNotifier {
@@ -22,6 +23,9 @@ export interface ExpressOptions {
 export interface ExpressResult {
     readonly activity: Activity;
 }
+export interface ListenerChangeResult {
+    readonly activity: Activity | null;
+}
 export interface CatchOptions {
     readonly idle?: number;
     readonly from?: readonly string[];
@@ -46,6 +50,7 @@ export interface ParticipantStatus {
     readonly state: 'joined' | 'done';
     readonly consumedThrough: ActivityId | null;
     readonly watching: boolean;
+    readonly listening: readonly string[];
 }
 export interface SquareSnapshot {
     readonly context: string;
@@ -78,6 +83,9 @@ export interface SquareBuildInput extends SquareSource {
 export interface Participant {
     readonly name: string;
     express(body: string, options?: ExpressOptions): Promise<ExpressResult>;
+    listen(target: string): Promise<ListenerChangeResult>;
+    ignore(target: string): Promise<ListenerChangeResult>;
+    listening(): Promise<readonly string[]>;
     catch(options?: CatchOptions): Promise<CatchResult>;
     history(query?: HistoryQuery): Promise<PerceivedActivity[]>;
     hold(reason?: string): Promise<ExpressResult>;

package/dist/square-wiring.d.ts

@@ -1,3 +1,4 @@
+import { type OpenSquare } from './open-square.js';
 import type { Activity, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
 import type { Participant, SquareAtInput, SquareBuildInput } from './square-facade.js';
 export declare class Square {
@@ -8,11 +9,18 @@ export declare class Square {
     static build(input: SquareBuildInput): Promise<Square>;
     static inMemory(input: Omit<SquareBuildInput, 'path'>): Square;
     join(name: string): Promise<Participant>;
+    implicitJoin(name: string): Promise<{
+        readonly state: 'joined' | 'active' | 'done';
+        readonly participant?: Participant;
+    }>;
     participants(): Promise<ParticipantStatus[]>;
     snapshot(): Promise<SquareSnapshot>;
     history(query?: HistoryQuery): Promise<Activity[]>;
+    recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
     close(): Promise<void>;
 }
+export declare function markBoundarySeen(squarePath: string, name: string, ownerId: string | undefined, actIndexes: readonly number[], at?: number): Promise<void>;
+export declare function markNotificationNotified(square: OpenSquare, name: string, actIndex: number, ownerId: string | undefined, at?: number): Promise<void>;
 export declare function openParticipant(input: SquareAtInput, name: string): Promise<{
     readonly participant: Participant;
     close(): Promise<void>;

package/dist/square-wiring.js

@@ -1,8 +1,9 @@
 import { closeOpenSquare } from './open-square.js';
 import { buildMemorySquare, buildSquare, openSquare } from './square-file-adapter.js';
-import { done, express, hold, join, resume } from './landing.js';
-import { catchUp } from './presence.js';
-import { history, participantHistory, participants, resolveParticipant, snapshot } from './views.js';
+import { done, express, hold, ignore, implicitJoin, join, listen, listening, resume } from './landing.js';
+import { catchUp, markBoundarySeen as recordBoundarySeen, markNotificationNotified as recordNotificationNotified } from './presence.js';
+import { currentParticipant, history, participantHistory, participants, resolveParticipant, snapshot } from './views.js';
+import { localParticipantName } from './registry.js';
 class ParticipantHandle {
     name;
     square;
@@ -13,6 +14,15 @@ class ParticipantHandle {
     express(body, options) {
         return express(this.square, this.name, body, options);
     }
+    listen(target) {
+        return listen(this.square, this.name, target);
+    }
+    ignore(target) {
+        return ignore(this.square, this.name, target);
+    }
+    listening() {
+        return listening(this.square, this.name);
+    }
     catch(options) {
         return catchUp(this.square, this.name, options);
     }
@@ -49,11 +59,30 @@ export class Square {
         const joined = await join(this.square, name);
         return new ParticipantHandle(joined.name, this.square);
     }
+    async implicitJoin(name) {
+        const joined = await implicitJoin(this.square, name);
+        return joined.state === 'done'
+            ? { state: joined.state }
+            : { state: joined.state, participant: new ParticipantHandle(joined.name, this.square) };
+    }
     participants() { return participants(this.square); }
     snapshot() { return snapshot(this.square); }
     history(query) { return history(this.square, query); }
+    async recognize(env) {
+        const registered = localParticipantName(this.square.location, env);
+        if (registered === undefined)
+            return null;
+        const canonicalName = await currentParticipant(this.square, registered);
+        return canonicalName === undefined ? null : new ParticipantHandle(canonicalName, this.square);
+    }
     close() { return closeOpenSquare(this.square); }
 }
+export function markBoundarySeen(squarePath, name, ownerId, actIndexes, at) {
+    return recordBoundarySeen(squarePath, name, ownerId, actIndexes, at);
+}
+export function markNotificationNotified(square, name, actIndex, ownerId, at) {
+    return recordNotificationNotified(square, name, actIndex, ownerId, at);
+}
 export async function openParticipant(input, name) {
     const square = await openSquare(input.path, input);
     try {