@astrosheep/square 0.3.11 → 0.3.13

package/dist/decisions.js

@@ -1,59 +1,83 @@
 import { SquareError, sameName, validateName, } from './model.js';
+import { participantIdentity } from './participant-identity.js';
 import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, getReadState, publicActs, readCursor, resolveRosterName, rosterNames, matchesMentionTarget, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
-import { validate } from './square-core.js';
+import { extractMentions, formatActivityId, validate } from './square-core.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { compileSearchPattern } from './search.js';
-export function resolveKnownName(doc, name) {
+export function resolveKnownName(squareState, name) {
     validateName(name);
-    const known = resolveRosterName(doc, name);
+    const known = resolveRosterName(squareState, name);
     if (known === undefined) {
-        const roster = rosterNames(doc);
-        throw new SquareError('invalid_args', `Unknown participant "${name}". Expected one of: ${roster.join(', ')}.`);
+        const roster = rosterNames(squareState);
+        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(name)}". Expected one of: ${roster.map(participantIdentity).join(', ')}.`);
     }
     return known;
 }
 function participantState(state, name) {
     return state.participants.find((participant) => sameName(participant.name, name));
 }
-export function decideJoin(doc, name, now) {
-    const knownName = resolveRosterName(doc, name);
+export function decideJoin(squareState, name, now) {
+    validateName(name);
+    const knownName = resolveRosterName(squareState, name);
     const joinedName = knownName ?? name;
-    const state = foldedState(doc);
+    const state = foldedState(squareState);
     const result = validate(state, { kind: 'join', actor: joinedName, at: now });
     if (!result.ok && result.reason === 'already_joined') {
-        throw new SquareError('conflict', `A participant named "${joinedName}" is already in this square.`);
+        return { joinedName, addParticipant: false };
     }
     return {
         joinedName,
         addParticipant: knownName === undefined,
-        joinAct: { kind: 'join', actor: joinedName, at: now, body: '' },
+        joinAct: { kind: 'join', actor: joinedName, at: now },
     };
 }
+function resolveStandingName(squareState, requestedName) {
+    validateName(requestedName);
+    const name = resolveRosterName(squareState, requestedName);
+    if (name === undefined)
+        throw new SquareError('not_joined', `${participantIdentity(requestedName)} has not joined this square`);
+    return name;
+}
+function requireStanding(squareState, act) {
+    const result = validate(foldedState(squareState), act);
+    if (result.ok)
+        return;
+    if (result.reason === 'done')
+        throw new SquareError('already_done', `${act.actor === undefined ? 'participant' : participantIdentity(act.actor)} is already done`);
+    if (result.reason === 'not_joined')
+        throw new SquareError('not_joined', `${act.actor === undefined ? 'participant' : participantIdentity(act.actor)} has not joined this square`);
+    throw new Error(`Unexpected standing validation result: ${result.reason}`);
+}
 const UNREAD_PREVIEW_LIMIT = 3;
-export function decideAct(doc, input) {
+export function decideAct(squareState, input) {
     const { now, force } = input;
-    const name = resolveKnownName(doc, input.name);
+    const name = resolveStandingName(squareState, input.name);
     const body = input.body;
     if (body.trim() === '')
         throw new SquareError('invalid_args', 'express body cannot be empty');
     const reach = input.reach;
     const reply = input.reply;
     if (reply !== undefined) {
-        if (!Number.isSafeInteger(reply) || reply < 0 || reply >= doc.runtime.nextActIndex) {
-            throw new SquareError('invalid_args', `Unknown reply activity: act_${reply}`);
+        if (!Number.isSafeInteger(reply) || reply < 0 || reply >= squareState.runtime.nextActIndex) {
+            const label = Number.isSafeInteger(reply) && reply >= 0 ? formatActivityId(reply) : String(reply);
+            throw new SquareError('invalid_args', `Unknown reply activity: ${label}`);
         }
     }
-    const state = foldedState(doc);
+    const state = foldedState(squareState);
+    if (reach !== 'bell'
+        && extractMentions(body).length === 0) {
+        throw new SquareError('invalid_args', 'express requires an @mention unless using --bell');
+    }
     const current = participantState(state, name);
     const result = validate(state, {
         kind: 'say', actor: name, at: now, body,
         ...(reach !== undefined ? { reach } : {}),
         ...(reply !== undefined ? { reply } : {}),
-    }, { hardCap: doc.hardCap, throttlePerMinute: doc.throttlePerMinute, throttleWindowMs: THROTTLE_WINDOW_MS });
+    }, { hardCap: squareState.hardCap, throttlePerMinute: squareState.throttlePerMinute, throttleWindowMs: THROTTLE_WINDOW_MS });
     if (!result.ok) {
         if (result.reason === 'done')
-            throw new SquareError('conflict', `${name} is done; rejoin to express again`);
+            throw new SquareError('already_done', `${name} is already done`);
         if (result.reason === 'held')
             return { type: 'held', reason: result.hold.reason };
         if (result.reason === 'hard_cap')
@@ -63,9 +87,9 @@ export function decideAct(doc, input) {
         if (result.reason === 'bell_quota')
             return { type: 'bell_quota', nextAt: result.nextAt };
         if (result.reason === 'not_joined')
-            throw new SquareError('conflict', `${name} has not joined this square`);
+            throw new SquareError('not_joined', `${name} has not joined this square`);
     }
-    const delta = actDelta(doc.acts, readCursor(doc, name));
+    const delta = actDelta(squareState.acts, readCursor(squareState, name));
     const unreadPublic = peerPublicActs(delta, name);
     const unreadRoomChanges = peerRoomChanges(delta, name);
     const sayCountByActor = new Map();
@@ -97,7 +121,8 @@ export function decideAct(doc, input) {
     }))
         .sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
     const latestActivityAgeMs = activitySummaries[0]?.latestActivityAgeMs;
-    const hasUnread = unreadPublic.length > 0 || unreadRoomChanges.length > 0;
+    const hasUnreadBlockingChange = unreadRoomChanges.some((act) => act.kind !== 'join');
+    const hasUnread = unreadPublic.length > 0 || hasUnreadBlockingChange;
     const hasFreshUnreadActivity = latestActivityAgeMs !== undefined && latestActivityAgeMs <= UNREAD_BLOCK_GRACE_MS;
     if (!force && hasUnread && !hasFreshUnreadActivity) {
         return { type: 'blocked', activitySummaries, unreadRoomChanges };
@@ -116,21 +141,29 @@ export function decideAct(doc, input) {
         pendingRoomChanges: unreadRoomChanges,
     };
 }
-export function coreDone(doc, name, body, now) {
-    const resolvedName = resolveKnownName(doc, name);
-    return { kind: 'done', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+export function coreDone(squareState, name, body, now) {
+    const resolvedName = resolveStandingName(squareState, name);
+    const act = { kind: 'done', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+    requireStanding(squareState, act);
+    return act;
 }
-export function coreHold(_doc, actor, body, now) {
-    return { kind: 'hold', actor, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+export function coreHold(squareState, actor, body, now) {
+    const resolvedName = resolveStandingName(squareState, actor);
+    const act = { kind: 'hold', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+    requireStanding(squareState, act);
+    return act;
 }
-export function coreResume(_doc, actor, now) {
-    return { kind: 'resume', actor, at: now, body: '' };
+export function coreResume(squareState, actor, now) {
+    const resolvedName = resolveStandingName(squareState, actor);
+    const act = { kind: 'resume', actor: resolvedName, at: now };
+    requireStanding(squareState, act);
+    return act;
 }
-function presenceFor(doc, snapshot, name, now) {
+function presenceFor(squareState, snapshot, name, now) {
     if (snapshot?.done)
         return { state: 'done', lastAt: snapshot.lastActiveAt };
-    const cursor = getReadState(doc, name);
-    const lease = freshWatchLease(doc, name, now);
+    const cursor = getReadState(squareState, name);
+    const lease = freshWatchLease(squareState, name, now);
     if (lease !== undefined)
         return { state: 'watching', lastAt: cursor?.updatedAt ?? lease.heartbeatAt };
     const lastAt = cursor?.updatedAt ?? (snapshot?.joined ? snapshot.lastActiveAt : undefined);
@@ -138,16 +171,16 @@ function presenceFor(doc, snapshot, name, now) {
         ? { state: 'never-joined', lastAt: undefined }
         : { state: 'active', lastAt };
 }
-function buildParticipantStatuses(doc, now, state = foldedState(doc)) {
-    const delivery = deriveDeliveryModel(doc);
+function buildParticipantStatuses(squareState, now, state = foldedState(squareState)) {
+    const delivery = deriveDeliveryModel(squareState);
     return state.participants.map((snapshot) => {
         const participant = snapshot.name;
-        const presence = presenceFor(doc, snapshot, participant, now);
+        const presence = presenceFor(squareState, snapshot, participant, now);
         const participantStatus = snapshot?.done ? 'done' : snapshot?.joined ? 'active' : 'not joined';
-        const consumedThrough = readCursor(doc, participant);
+        const consumedThrough = readCursor(squareState, participant);
         let unreadActivityCount = 0;
         if (snapshot?.joined) {
-            for (const act of doc.acts) {
+            for (const act of squareState.acts) {
                 if (actStableIndex(act) <= consumedThrough || act.actor === undefined || sameName(act.actor, participant))
                     continue;
                 if (act.kind !== 'read')
@@ -166,43 +199,44 @@ function buildParticipantStatuses(doc, now, state = foldedState(doc)) {
         };
     });
 }
-export function coreStatus(doc, now) {
-    const state = foldedState(doc);
-    const latestAct = publicActs(doc.acts).at(-1);
+export function coreStatus(squareState, now) {
+    const state = foldedState(squareState);
+    const latestAct = publicActs(squareState.acts).at(-1);
     return {
-        hardCap: doc.hardCap,
-        throttlePerMinute: doc.throttlePerMinute,
+        hardCap: squareState.hardCap,
+        throttlePerMinute: squareState.throttlePerMinute,
         activeCount: state.joined.length,
         doneCount: state.done.length,
         holdActive: state.hold.active,
         holdReason: state.hold.reason,
         holdActor: state.hold.actor,
         holdAt: state.hold.at,
-        participants: buildParticipantStatuses(doc, now, state),
+        participants: buildParticipantStatuses(squareState, now, state),
         latestAct,
         now,
     };
 }
-export function coreParticipants(doc, now) {
-    return buildParticipantStatuses(doc, now);
+export function coreParticipants(squareState, now) {
+    return buildParticipantStatuses(squareState, now);
 }
-export function coreActivities(doc, opts) {
+export function coreActivities(squareState, opts) {
     const participants = opts.participants ?? [];
-    const canonicalParticipants = participants.map((participant) => resolveKnownName(doc, participant));
-    const viewer = opts.viewer !== undefined ? resolveKnownName(doc, opts.viewer) : undefined;
-    let acts = [...doc.acts];
-    // --at establishes a context window first; other filters AND inside it.
-    if (opts.atIndex != null) {
+    const canonicalParticipants = participants.map((participant) => resolveKnownName(squareState, participant));
+    const viewer = opts.viewer !== undefined ? resolveKnownName(squareState, opts.viewer) : undefined;
+    let acts = [...squareState.acts];
+    // --at establishes one or more context windows first; other filters AND inside their union.
+    if (opts.atIndexes !== undefined && opts.atIndexes.length > 0) {
         const before = opts.beforeContext ?? 0;
         const after = opts.afterContext ?? 0;
-        const centerPos = acts.findIndex((act) => act.index === opts.atIndex);
-        if (centerPos < 0)
-            return [];
-        acts = acts.slice(Math.max(0, centerPos - before), centerPos + after + 1);
-    }
-    if (opts.ids !== undefined && opts.ids.length > 0) {
-        const wanted = new Set(opts.ids);
-        acts = acts.filter((act) => wanted.has(act.index));
+        const selected = new Set();
+        for (const atIndex of opts.atIndexes) {
+            const centerPos = acts.findIndex((act) => act.index === atIndex);
+            if (centerPos < 0)
+                continue;
+            for (const act of acts.slice(Math.max(0, centerPos - before), centerPos + after + 1))
+                selected.add(act.index);
+        }
+        acts = acts.filter((act) => selected.has(act.index));
     }
     if (opts.afterIndex != null)
         acts = acts.filter((act) => act.index > opts.afterIndex);
@@ -214,13 +248,13 @@ export function coreActivities(doc, opts) {
     if (opts.after != null)
         acts = acts.filter((act) => act.at > opts.after);
     if (opts.mention != null) {
-        const mention = resolveKnownName(doc, opts.mention);
+        const mention = resolveKnownName(squareState, opts.mention);
         acts = acts.filter((act) => act.kind === 'say' && (act.reach === 'bell' || matchesMentionTarget(act, mention)));
     }
     if (opts.pending) {
         if (viewer === undefined)
             return [];
-        const pendingIndexes = new Set(deriveDeliveryModel(doc).pendingFor(viewer).map((notification) => notification.item.index));
+        const pendingIndexes = new Set(deriveDeliveryModel(squareState).pendingFor(viewer).map((notification) => notification.item.index));
         acts = acts.filter((act) => pendingIndexes.has(act.index));
     }
     const search = opts.grep !== undefined ? { pattern: opts.grep, fixed: false } : opts.fixed !== undefined ? { pattern: opts.fixed, fixed: true } : undefined;
@@ -243,25 +277,3 @@ export function coreActivities(doc, opts) {
     }
     return acts;
 }
-export function coreCompact(doc, keep) {
-    if (doc.acts.length <= keep)
-        return { archived: [], doc };
-    const splitAt = doc.acts.length - keep;
-    const archived = doc.acts.slice(0, splitAt);
-    const retained = doc.acts.slice(splitAt);
-    const cutoffIndex = actStableIndex(archived[archived.length - 1]);
-    const unread = foldedState(doc).participants
-        .filter((participant) => participant.joined && readCursor(doc, participant.name) < cutoffIndex)
-        .map((participant) => participant.name);
-    if (unread.length > 0) {
-        throw new SquareError('conflict', `Refusing to compact: ${unread.join(', ')} ${unread.length === 1 ? 'has' : 'have'} not read through the activities being archived.`);
-    }
-    return {
-        archived,
-        doc: {
-            ...doc,
-            acts: retained,
-            runtime: doc.runtime,
-        },
-    };
-}

package/dist/delivery-health.d.ts

@@ -0,0 +1,21 @@
+import { type DirectedNotificationRoute } from './delivery.js';
+import type { WakeAttempt } from './wake-attempts.js';
+export type DeliveryHealthKind = 'awaiting' | 'wake-accepted' | 'wake-unknown' | 'presented-not-delivered' | 'unreachable';
+export interface DeliveryHealthItem {
+    squarePath: string;
+    recipient: string;
+    actIndex: number;
+    actor: string;
+    at: number;
+    ageMs: number;
+    route: DirectedNotificationRoute;
+    kind: DeliveryHealthKind;
+    attempt?: WakeAttempt;
+}
+/** Purely classify current pending attention from the artifact and durable ledgers. */
+export declare function classifyDeliveryHealth(squarePath: string, opts: {
+    graceMs: number;
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<DeliveryHealthItem[]>;
+export declare function doctorDeliveryHealth(squarePath: string, graceMs: number, now?: number, env?: NodeJS.ProcessEnv): Promise<string[]>;

package/dist/delivery-health.js

@@ -1,7 +1,10 @@
-import { loadSquare } from './artifact.js';
-import { deriveDeliveryModel, } from './delivery.js';
+import { formatActivityId } from './square-core.js';
+import { participantIdentity } from './presentation.js';
 import { formatDuration } from './time.js';
-import { joinedRecipients, wakeEvidence } from './wake-evidence.js';
+import { wakeEvidence } from './wake-evidence.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { pendingDeliveries } from './views.js';
 const DISPLAY_ORDER = [
     'awaiting',
     'wake-accepted',
@@ -11,43 +14,47 @@ const DISPLAY_ORDER = [
 ];
 const ACTIONABLE = new Set(['wake-unknown', 'unreachable']);
 /** Purely classify current pending attention from the artifact and durable ledgers. */
-export function classifyDeliveryHealth(squarePath, opts) {
+export async function classifyDeliveryHealth(squarePath, opts) {
     const now = opts.now ?? Date.now();
     const env = opts.env ?? process.env;
-    const doc = loadSquare(squarePath);
-    const model = deriveDeliveryModel(doc);
-    return joinedRecipients(doc).flatMap((recipient) => model.pendingFor(recipient).map((note) => {
-        const ageMs = Math.max(0, now - note.item.at);
-        const evidence = wakeEvidence(squarePath, note.recipient, note.item.index, now, env);
-        const kind = evidence.presented
-            ? 'presented-not-delivered'
-            : evidence.terminal?.outcome === 'accepted'
-                ? 'wake-accepted'
-                : evidence.terminal?.outcome === 'unknown'
-                    ? 'wake-unknown'
-                    : ageMs > opts.graceMs && evidence.attemptableRoutes.length === 0
-                        ? 'unreachable'
-                        : 'awaiting';
-        const attempt = evidence.terminal ?? evidence.attempts.at(-1);
-        return {
-            squarePath,
-            recipient: note.recipient,
-            actIndex: note.item.index,
-            actor: note.item.actor,
-            at: note.item.at,
-            ageMs,
-            route: note.route,
-            kind,
-            ...(attempt === undefined ? {} : { attempt }),
-        };
-    }));
+    const square = await openSquare(squarePath, { clock: () => now });
+    const pending = await pendingDeliveries(square).finally(() => closeOpenSquare(square));
+    const items = [];
+    for (const delivery of pending) {
+        for (const note of delivery.notifications) {
+            const ageMs = Math.max(0, now - note.item.at);
+            const evidence = await wakeEvidence(squarePath, note.recipient, note.item.index, now, env);
+            const kind = evidence.presented
+                ? 'presented-not-delivered'
+                : evidence.terminal?.outcome === 'accepted'
+                    ? 'wake-accepted'
+                    : evidence.terminal?.outcome === 'unknown'
+                        ? 'wake-unknown'
+                        : ageMs > opts.graceMs && evidence.attemptableRoutes.length === 0
+                            ? 'unreachable'
+                            : 'awaiting';
+            const attempt = evidence.terminal ?? evidence.attempts.at(-1);
+            items.push({
+                squarePath,
+                recipient: note.recipient,
+                actIndex: note.item.index,
+                actor: note.item.actor,
+                at: note.item.at,
+                ageMs,
+                route: note.route,
+                kind,
+                ...(attempt === undefined ? {} : { attempt }),
+            });
+        }
+    }
+    return items;
 }
 function formatItem(item) {
     const evidence = item.attempt?.signature === undefined ? '' : ` · ${item.attempt.signature}`;
-    return `  · act_${item.actIndex} → @${item.recipient} from @${item.actor} · ${formatDuration(item.ageMs)}${evidence}`;
+    return `  · ${formatActivityId(item.actIndex)} → ${participantIdentity(item.recipient)} from ${participantIdentity(item.actor)} · ${formatDuration(item.ageMs)}${evidence}`;
 }
-export function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
-    const items = classifyDeliveryHealth(squarePath, { graceMs, now, env });
+export async function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
+    const items = await classifyDeliveryHealth(squarePath, { graceMs, now, env });
     if (items.length === 0)
         return ['✓ no pending delivery attention'];
     const out = [`· delivery attention · ${items.length} pending`];

package/dist/delivery.d.ts

@@ -0,0 +1,81 @@
+import { type DeliveryReceipt, type DirectedNotificationRoute, type SquareState, type SquareRuntimeState, type StoredAct, type WatchLease, type WatchLeaseFilter, type WakeRouteKind, type Reach } from './model.js';
+export type { DirectedNotificationRoute } from './model.js';
+export type SayItem = StoredAct & {
+    kind: 'say';
+};
+export declare function notificationMessageId(squarePath: string, actIndex: number): string;
+export interface PlannedNotification {
+    item: SayItem;
+    recipient: string;
+    route: DirectedNotificationRoute;
+}
+export interface WakeRequest {
+    squarePath: string;
+    actIndex: number;
+    recipient: string;
+    actor: string;
+    route: DirectedNotificationRoute;
+}
+export type WakeDispatchResult = {
+    outcome: 'accepted';
+} | {
+    outcome: 'unknown';
+    signature: string;
+    message: string;
+    diagnostic?: unknown;
+} | {
+    outcome: 'failed';
+    signature: string;
+    message: string;
+    diagnostic?: unknown;
+} | {
+    outcome: 'cancelled';
+};
+export interface WakeAdapter {
+    readonly kind: WakeRouteKind;
+    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>): Promise<WakeDispatchResult>;
+}
+export interface RoutedNotification {
+    actor: string;
+    body: string;
+    route: DirectedNotificationRoute;
+}
+export interface CatchFilterShape {
+    actor: string;
+    body: string;
+    reach?: Reach;
+}
+export interface DeliveryModel {
+    plan(item: StoredAct): PlannedNotification[];
+    pendingFor(recipient: string): PlannedNotification[];
+}
+/** Delivery receipts are the only durable acknowledgement of directed attention. */
+export declare function deliveryReceipt(squareState: SquareState, name: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
+export declare function deliveryReceiptFromRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
+export declare function isDeliveryDelivered(squareState: SquareState, name: string, actOrIndex: StoredAct | number): boolean;
+export declare function recordDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
+export declare function recordDeliveredRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
+export declare function markDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, at?: number): boolean;
+/**
+ * Derive delivery behavior once from the decoded Square state.
+ * All consumers share these targets instead of reinterpreting artifact text or cursor state.
+ */
+export declare function deriveDeliveryModel(squareState: SquareState): DeliveryModel;
+export declare function planActNotifications(squareState: SquareState, item: StoredAct): PlannedNotification[];
+/** Mark only the directed notifications selected by the canonical pending projection. */
+export declare function markDeliveredNotifications(squareState: SquareState, recipient: string, delivered: StoredAct[], at?: number): boolean;
+/** Canonical say-activity filter shared by catch selection and hook ownership. */
+export declare function matchesCatchFilter(activity: CatchFilterShape, filter: WatchLeaseFilter): boolean;
+/** True only when the live catch's own filters would deliver this notification. */
+export declare function leaseOwnsNotification(lease: WatchLease, notification: RoutedNotification): boolean;
+export type SquareRoute = Readonly<unknown>;
+interface ParsedSquareRoute {
+    readonly v: 1;
+    readonly squarePath: string;
+    readonly name: string;
+}
+export declare function parseSquareRoute(value: unknown): ParsedSquareRoute;
+export declare function captureRoute(input: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}): SquareRoute | null;