@astrosheep/square 0.3.96 → 0.3.98

package/dist/sqlite-square.js

@@ -1,19 +1,20 @@
 import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 import { assertCurrentSeat } from './square-domain.js';
 import { canonicalPath } from './canonical-path.js';
+import { activityQueryFilter } from './activity-query.js';
 import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { activityMetadataHasContent, InternalSquareError, SquareError, isSquareError, nameKey, sameName, validateActivityMetadata, validateName } from './model.js';
-import { coreDone, coreIgnore, coreListen, coreListening, coreUnlisten, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
+import { attentionChange, coreDone, coreListening, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
 import { expressionContext } from './activity-feed.js';
 import { expressHint } from './hints.js';
 import { ATTENTION_BODY_MAX } from './attention-presentation.js';
 import { asSeatRef, participantAuthority, requireOwner, requireJoinName } from './seats.js';
-import { recoveryObservation, entryPresentation, snapshot, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+import { recoveryObservation, entryPresentation, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, toPerceivedActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
 import { rememberSquarePath, squareIndexPath } from './square-index.js';
 import { deliverPending } from './delivery-operations.js';
@@ -216,7 +217,7 @@ export class SqliteSquare {
             checkControl(control);
             const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const act = verb === 'listen' ? coreListen(facts, name, target, now) : verb === 'ignore' ? coreIgnore(facts, name, target, now) : coreUnlisten(facts, name, target, now);
+                const act = attentionChange(facts, verb, name, target, now);
                 const activity = act === undefined ? null : toPublicActivity(facts.land(act));
                 return { activity, ...(!options.observe ? {} : { observation: {
                             ...square.observation(inSquareCount(facts), name, now), participant: name,
@@ -344,6 +345,36 @@ export class SqliteSquare {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
             }
         }
+        async pending(options = {}, control) {
+            checkControl(control);
+            const limit = options.limit === undefined ? 100 : options.limit;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
+            const { actors, ...query } = activityQueryFilter(options), square = this.owner;
+            return (await square.artifact.read(facts => {
+                assertCurrentSeat(facts, asSeatRef(this.seat));
+                const filter = { ...query, senders: actors, unseenOnly: true };
+                const heads = facts.directed(this.name, filter, { edge: 'oldest', limit });
+                const activities = facts.activities(heads.items.map(head => head.index))
+                    .map(activity => toPerceivedActivity(facts, activity, this.name));
+                return { activities, remaining: facts.directedCount(this.name, filter) - activities.length };
+            }, control?.signal)).value;
+        }
+        async ack(ids, control) {
+            checkControl(control);
+            if (!Array.isArray(ids))
+                throw new SquareError('invalid_args', 'Ack requires an array of activity IDs.');
+            const indexes = [...new Set(Array.from(ids, parseRequiredActivityId))], square = this.owner;
+            return (await square.artifact.transactAs(participantAuthority(this.seat), facts => {
+                for (const index of indexes) {
+                    if (facts.directedAt(this.name, index) === undefined)
+                        throw new SquareError('invalid_args', `${formatActivityId(index)} is not addressed to you.`, {
+                            reason: 'not_addressed', activityId: formatActivityId(index),
+                        });
+                }
+                return { consumed: facts.markSeen(this.name, indexes, square.clock()) };
+            }, control?.signal)).value;
+        }
         async deferDelivery(input, control) {
             checkControl(control);
             const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
@@ -416,7 +447,7 @@ export class SqliteSquare {
             const standing = facts.roster().filter(p => p.joined), resolvedTo = [], missing = [];
             for (const target of unique) {
                 const recipient = standing.find(p => sameName(p.name, target));
-                if (recipient === undefined || facts.seat(recipient.name)?.attachment !== 'attached')
+                if (recipient === undefined)
                     missing.push(target);
                 else
                     resolvedTo.push(recipient.name);
@@ -484,10 +515,10 @@ export class SqliteSquare {
                     kind = 'reconnected';
                 }
                 if (kind !== 'reconnected') {
-                    const decision = decideJoin(facts, participant, now);
-                    if (decision.joinAct === undefined)
+                    const joinAct = decideJoin(facts, participant, now);
+                    if (joinAct === undefined)
                         throw new SquareError('already_joined', `${participantIdentity(participant)} could not be joined`);
-                    activity = toPublicActivity(facts.land(decision.joinAct));
+                    activity = toPublicActivity(facts.land(joinAct));
                 }
                 const seat = facts.seat(participant);
                 if (seat === undefined)
@@ -532,14 +563,11 @@ export class SqliteSquare {
             await this.publishSeat(owner);
         return seat === null ? null : this.handle(seat);
     }
-    async snapshot(control) { return (await this.artifact.read(facts => snapshot(facts, this.clock()), control?.signal)).value; }
     async history(query = {}, control) {
         if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
             throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);
-        if (query.grep !== undefined && query.fixed !== undefined)
-            throw new SquareError('invalid_args', 'History cannot combine regular-expression and literal search');
-        if (query.grep === '' || query.fixed === '')
-            throw new SquareError('invalid_args', 'History search requires non-empty text');
+        if (query.order !== undefined && query.order !== 'asc' && query.order !== 'desc')
+            throw new SquareError('invalid_args', 'History order must be asc or desc.');
         if (query.since !== undefined && !Number.isFinite(query.since))
             throw new SquareError('invalid_args', 'History timestamp must be finite');
         for (const count of [query.contextBefore, query.contextAfter])

package/dist/square-facade.d.ts

@@ -86,6 +86,35 @@ export interface CatchOptions extends ObservationOptions {
     readonly limit?: number;
     readonly replace?: boolean;
 }
+export interface ActivitySearch {
+    readonly text: string;
+    readonly mode: 'literal' | 'regex';
+}
+export interface ActivityCursor {
+    readonly id: ActivityId;
+    readonly direction: 'before' | 'after';
+}
+/** Shared filters; absent arrays are unrestricted, empty arrays match nothing. */
+export interface ActivityQuery {
+    readonly at?: readonly ActivityId[];
+    readonly from?: readonly string[];
+    readonly match?: MetadataMatch;
+    readonly search?: ActivitySearch;
+    readonly cursor?: ActivityCursor;
+}
+export interface PendingOptions extends ActivityQuery {
+    /** Oldest first; defaults to 100, maximum 100. */
+    readonly limit?: number;
+}
+export interface PendingResult {
+    readonly activities: readonly PerceivedActivity[];
+    /** Matching unconsumed activities outside this page. */
+    readonly remaining: number;
+}
+export interface AckResult {
+    /** Newly consumed addressed IDs; repeated acknowledgement is a no-op. */
+    readonly consumed: number;
+}
 export type CatchReason = 'drained' | 'idle' | 'capped' | 'quorum' | 'replaced' | 'already-active';
 export interface CatchResult {
     readonly activities: readonly PerceivedActivity[];
@@ -126,18 +155,12 @@ export interface OperationFailureDetail {
 export interface OperationError extends Error {
     readonly operation?: OperationFailureDetail;
 }
-export interface HistoryQuery extends ObservationOptions {
+export interface HistoryQuery extends ActivityQuery, ObservationOptions {
     /** Ten by default; null explicitly reads the full archive. */
     readonly limit?: number | null;
     readonly order?: 'asc' | 'desc';
-    readonly before?: ActivityId;
-    readonly after?: ActivityId;
-    readonly grep?: string;
-    readonly fixed?: string;
-    readonly from?: readonly string[];
     readonly mention?: string;
     readonly since?: number;
-    readonly at?: readonly ActivityId[];
     readonly contextBefore?: number;
     readonly contextAfter?: number;
 }
@@ -145,14 +168,6 @@ export interface HistoryResult {
     readonly activities: readonly Activity[];
     readonly observation?: HistoryObservation;
 }
-export interface SquareSnapshot {
-    readonly context: string;
-    readonly actCount: number;
-    readonly hardCap: number | null;
-    readonly throttlePerMinute?: number;
-    readonly participants: readonly Pick<ParticipantSummary, 'name' | 'presence' | 'listening'>[];
-    delivered(name: string, id: ActivityId): boolean;
-}
 export interface OpenOptions {
     readonly clock?: () => number;
     readonly wakeTransport?: WakeTransportPort | false;
@@ -195,6 +210,8 @@ export interface Participant {
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
     catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    pending(options?: PendingOptions, control?: OperationControl): Promise<PendingResult>;
+    ack(ids: readonly ActivityId[], control?: OperationControl): Promise<AckResult>;
     /** Leave without a message. Only an omitted or empty body is accepted. */
     done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
     deferDelivery(input: Readonly<{

package/dist/square-sqlite.js

@@ -5,6 +5,8 @@ import { deriveLanding, landingFacts } from './square-domain.js';
 import { claimAttempt, prepareAttempt, settleAttempt } from './delivery-attempts.js';
 import { legacyRowFramingIssue, legacyActivitySchema } from './square-legacy-framing.js';
 import { receive, recordConsumed } from './receive.js';
+import { formatActivityId } from './square-core.js';
+import { compileSearchPattern } from './search.js';
 export function emptyRuntimeState(nextActIndex = 0) {
     return { nextActIndex, observations: {}, leases: {} };
 }
@@ -506,6 +508,30 @@ function activitySelection(filter, alias = 'a') {
             add(`${alias}.${column} IN (SELECT value FROM json_each(?))`, encode(values));
         }
     }
+    if (filter.metadataMatch !== undefined) {
+        // Walk literal object keys, never JSON-path strings or array indexes.
+        terms.push(`NOT EXISTS (
+            SELECT 1 FROM json_each(?) field WHERE NOT EXISTS (
+                WITH RECURSIVE walk(value,type,depth) AS (
+                    SELECT json_extract(${alias}.payload_json,'$.metadata'),json_type(${alias}.payload_json,'$.metadata'),0
+                    UNION ALL
+                    SELECT child.value,child.type,walk.depth+1
+                    FROM walk JOIN json_each(CASE WHEN walk.type='object' THEN walk.value ELSE '{}' END) child
+                      ON child.key=json_extract(field.value,'$.path['||walk.depth||']')
+                    WHERE walk.depth<json_array_length(field.value,'$.path')
+                )
+                SELECT 1 FROM walk WHERE depth=json_array_length(field.value,'$.path')
+                  AND (type=json_type(field.value,'$.equals')
+                    OR type IN ('integer','real') AND json_type(field.value,'$.equals') IN ('integer','real'))
+                  AND value IS json_extract(field.value,'$.equals')
+            )
+        )`);
+        args.push(encode(filter.metadataMatch.fields));
+    }
+    if (filter.search !== undefined) {
+        terms.push(`square_search(?,?,${alias}.act_index,${alias}.actor_json,json_extract(${alias}.payload_json,'$.body'))=1`);
+        args.push(filter.search.mode, filter.search.text);
+    }
     return { sql: terms.length ? terms.join(' AND ') : '1', args };
 }
 function pageRows(rows, page, decode) {
@@ -525,12 +551,28 @@ export function createSqliteDriver(db) {
     const all = (sql, args = []) => db.prepare(sql).all(...args);
     const one = (sql, args = []) => db.prepare(sql).get(...args);
     const run = (sql, args = []) => Number(db.prepare(sql).run(...args).changes);
+    let searchRegistered = false;
+    function selectActivity(filter) {
+        if (filter.search !== undefined && !searchRegistered) {
+            const patterns = new Map();
+            db.function('square_search', { deterministic: true }, (mode, text, index, actor, body) => {
+                const key = encode([mode, text]);
+                let pattern = patterns.get(key);
+                if (pattern === undefined) {
+                    pattern = compileSearchPattern(string(text), mode === 'literal');
+                    patterns.set(key, pattern);
+                }
+                return Number([formatActivityId(integer(index)), decoded(actor, true), body === null ? '' : string(body)]
+                    .some(field => pattern.test(field)));
+            });
+            searchRegistered = true;
+        }
+        return activitySelection(filter);
+    }
     const owner = (requested) => read.participant(requested)?.name ?? requested;
     const attentionRows = (condition, args) => all(`SELECT t.*,p.name_json FROM attention t JOIN participants p ON p.name_key_json=t.listener_key_json WHERE ${condition} ORDER BY t.since_index`, args).map(attention);
     function directedSelection(recipient, filter) {
-        const p = read.participant(recipient), base = activitySelection({
-            afterIndex: filter.afterIndex, beforeIndex: filter.beforeIndex, throughIndex: filter.throughIndex, actors: filter.senders
-        });
+        const p = read.participant(recipient), base = selectActivity({ ...filter, actors: filter.senders });
         base.sql += ' AND d.recipient_key_json=?';
         base.args.push(p ? key(p.name) : '');
         if (filter.unseenOnly) {
@@ -604,7 +646,7 @@ export function createSqliteDriver(db) {
             return r ? activity(r) : undefined;
         },
         activityHeads(filter, page) {
-            const s = activitySelection(filter), limit = pageLimit(page);
+            const s = selectActivity(filter), limit = pageLimit(page);
             return pageRows(all(`SELECT a.act_index,a.at,a.kind,a.actor_json,a.actor_key_json,a.reach,a.reply_index FROM activities a WHERE ${s.sql} ORDER BY a.act_index ${page.edge === 'newest' ? 'DESC' : 'ASC'} LIMIT ?`, [...s.args, limit]), page, head);
         },
         activities(indexes) {
@@ -612,7 +654,7 @@ export function createSqliteDriver(db) {
             return immutable(all('SELECT * FROM activities WHERE act_index IN (SELECT value FROM json_each(?)) ORDER BY act_index', [encode(indexes)]).map(activity));
         },
         activityCount(filter) {
-            const s = activitySelection(filter);
+            const s = selectActivity(filter);
             return integer(one(`SELECT COUNT(*) AS n FROM activities a WHERE ${s.sql}`, s.args).n);
         },
         contextIndexes(centers, before, after) {
@@ -691,7 +733,6 @@ export function createSqliteDriver(db) {
             const k = encode(owner(name)), r = one('SELECT MAX(at) AS latest FROM receipts WHERE owner_json=?', [k]), e = one('SELECT MAX(r.act_index) AS latest FROM receipts r JOIN activities a ON a.act_index=r.act_index WHERE r.owner_json=? AND r.act_index>? AND a.actor_json IS NOT NULL', [k, integer(afterIndex, -1)]);
             return immutable({ ...(r.latest === null ? {} : { latestAt: finite(r.latest) }), ...(e.latest === null ? {} : { latestActorActivityIndex: integer(e.latest) }) });
         },
-        receiptAssignments: () => immutable(all('SELECT owner_json,act_index FROM receipts ORDER BY owner_json,act_index').map(r => ({ owner: decoded(r.owner_json, true), index: integer(r.act_index) }))),
         deliveryDeferrals(name, generation) {
             const canonical = owner(name);
             const current = read.seat(canonical);

package/dist/square-tools.js

@@ -28,6 +28,16 @@ export function squareToolsEnabled(env = process.env) {
     throw new SquareError('invalid_args', 'Invalid SQUARE_TOOLS: expected 0, 1, true, false, or none.');
 }
 export const SQUARE_TOOL_INSTRUCTIONS = 'Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.';
+function historyToolQuery({ grep, fixed, before, after, ...query }) {
+    if (grep !== undefined && fixed !== undefined)
+        throw new SquareError('invalid_args', 'Use grep or fixed, not both.');
+    if (before !== undefined && after !== undefined)
+        throw new SquareError('invalid_args', 'Use before or after, not both.');
+    return { ...query,
+        search: grep !== undefined ? { text: grep, mode: 'regex' } : fixed === undefined ? undefined : { text: fixed, mode: 'literal' },
+        cursor: after !== undefined ? { id: after, direction: 'after' } : before === undefined ? undefined : { id: before, direction: 'before' },
+    };
+}
 const target = z.string().describe('The participant to turn toward or away from.');
 export const SQUARE_TOOLS = [
     tool('join', 'Step into the square under your name. Do this once before you speak or catch. You arrive seeing what was said most recently.', {
@@ -65,7 +75,7 @@ export const SQUARE_TOOLS = [
         fixed: z.string().optional().describe('Only activities containing this exact text.'),
         from: stringArray.optional().describe('Only what these participants said.'),
         mention: z.string().optional().describe('Only what was addressed to this participant.'),
-    }, (square, args, control) => square.history({ ...args, observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
+    }, (square, args, control) => square.history({ ...historyToolQuery(args), observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: historyToolQuery(args) }))),
     tool('attention', 'Turn toward someone or away from them, from now on. Listen: hear everything they say, even to others. Unlisten: stop listening without clearing an ignore; mentions and replies still reach you unless ignored. Ignore: hear nothing from them but bells. What was already said stays as it was.', {
         as: participant, action: z.enum(['listen', 'unlisten', 'ignore']).describe('"listen", "unlisten" or "ignore". Listening again ends an ignore.'), target,
     }, async (square, { as, action, target }, control, identity) => {

package/dist/views.d.ts

@@ -1,7 +1,7 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
+import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
 export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignore", "unlisten"];
@@ -9,7 +9,7 @@ export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignor
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function toPerceivedActivity(facts: SquareRead, stored: StoredAct, viewer: string): PerceivedActivity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
-/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+/** History adds archive context and ordering to the shared storage-side query predicates. */
 export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
@@ -17,7 +17,6 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function snapshot(facts: SquareRead, now: number): SquareSnapshot;
 export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     participant: string;
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];

package/dist/views.js

@@ -3,7 +3,7 @@ import { compareParticipantActivity, coreParticipants, resolveKnownName, unreadA
 import { SquareError, nameKey } from './model.js';
 import { inSquareCount } from './runtime.js';
 import { perceiveActivity } from './perception-projection.js';
-import { compileSearchPattern } from './search.js';
+import { activityQueryFilter } from './activity-query.js';
 const PAGE_SIZE = 100;
 export const HISTORY_DEFAULT_LIMIT = 10;
 export const HISTORY_MAX_LIMIT = 100;
@@ -34,30 +34,26 @@ export function parseRequiredActivityId(id) {
         throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
     return index;
 }
-/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+/** History adds archive context and ordering to the shared storage-side query predicates. */
 export function selectHistory(facts, query, limit, kinds, presentation = true) {
-    if (query.before !== undefined && query.after !== undefined)
-        throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
-    const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
-    const beforeIndex = query.before === undefined ? undefined : parseRequiredActivityId(query.before);
-    const actors = (query.from ?? []).map((name) => resolveKnownName(facts, name));
+    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'contextBefore', 'contextAfter']);
+    const { afterIndex } = shared;
     const recipient = query.mention == null ? undefined : resolveKnownName(facts, query.mention);
-    const pattern = query.grep ?? query.fixed;
-    const search = pattern === undefined || pattern === '' ? undefined : compileSearchPattern(pattern, query.grep === undefined);
     if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1))
         throw new SquareError('invalid_args', 'History limit must be a positive integer');
     const filter = {
-        ...(actors.length === 0 ? {} : { actors }), afterIndex, beforeIndex, afterAt: query.since,
-        ...(query.at?.length ? { indexes: facts.contextIndexes(query.at.map(parseRequiredActivityId), query.contextBefore ?? 0, query.contextAfter ?? 0) } : {}),
-        kinds: search === undefined ? kinds : ['say', 'done'],
+        ...shared, afterAt: query.since,
+        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.contextBefore ?? 0, query.contextAfter ?? 0) }),
+        kinds: query.search === undefined ? kinds : ['say', 'done'],
     };
     let selected, totalMatches, publicBefore = false, publicAfter = false;
-    if (recipient === undefined && search === undefined && limit !== null && limit <= PAGE_SIZE) {
+    if (recipient === undefined && limit !== null && limit <= PAGE_SIZE) {
         selected = facts.activityHeads(filter, { edge: afterIndex === undefined ? 'newest' : 'oldest', limit }).items;
         totalMatches = facts.activityCount(filter);
         if (presentation) {
             const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-            const publicFilter = { ...filter, kinds: [...ARCHIVE] };
+            const publicFilter = { ...filter, kinds: filter.kinds === undefined
+                    ? [...ARCHIVE] : filter.kinds.filter(kind => ARCHIVE.has(kind)) };
             publicBefore = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, beforeIndex: publicHeads[0].index }) > 0;
             publicAfter = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, afterIndex: publicHeads.at(-1).index }) > 0;
         }
@@ -69,13 +65,10 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
         while (true) {
             const source = recipient === undefined
                 ? facts.activityHeads({ ...filter, afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE })
-                : facts.directed(recipient, { afterIndex: cursor, beforeIndex }, { edge: 'oldest', limit: PAGE_SIZE });
+                : facts.directed(recipient, { ...filter, senders: filter.actors, afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
             const heads = recipient === undefined ? source.items : source.items.length === 0 ? []
                 : facts.activityHeads({ ...filter, indexes: source.items.map((head) => head.index).filter((index) => filter.indexes === undefined || filter.indexes.includes(index)) }, { edge: 'oldest', limit: PAGE_SIZE }).items;
-            const matches = search === undefined ? undefined : new Set(facts.activities(heads.map((head) => head.index)).filter((act) => [formatActivityId(act.index), act.actor ?? '', 'body' in act ? act.body ?? '' : ''].some((field) => search.test(field))).map((act) => act.index));
             for (const head of heads) {
-                if (matches !== undefined && !matches.has(head.index))
-                    continue;
                 totalMatches++;
                 if (presentation && ARCHIVE.has(head.kind)) {
                     firstPublic = Math.min(firstPublic, head.index);
@@ -111,15 +104,6 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' ? [] : [toPublicActivity(activity)]);
 }
-export function snapshot(facts, now) {
-    const header = facts.header();
-    const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
-    const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
-    return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
-        ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-        participants: coreParticipants(facts, now).filter((p) => p.presence !== 'never-joined').map(({ name, presence, listening }) => ({ name, presence, listening })),
-        delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
-}
 export function recoveryObservation(facts, name, now) {
     const known = resolveKnownName(facts, name);
     return { participant: known, activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts),

package/guides/operation-cancellation.md

@@ -8,7 +8,11 @@ Library operations accept a final non-serializable control value:
 
 The signal is checked before lifecycle work and before artifact mutation, and it is propagated through artifact reads, transactions, change waits, and ownership lock acquisition. An idle `catch` rejects promptly when cancelled; it does not wake later and consume activity. Cancellation before an artifact transition prevents mutation.
 
-Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot roll it back or turn the result into a retry. A caller may discard the response after the commit, but the committed activity remains recoverable through `history` or a later `catch`; Square does not add a second consumption acknowledgement phase.
+Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot
+roll it back or turn the result into a retry. A caller may discard the response after the commit,
+but the committed activity remains recoverable through `history` or a later `catch`; catch does not
+require a second acknowledgement. The separate `pending` query never consumes; its optional
+follow-up `ack(ids)` commits exact receipts with the same cancellation boundary.
 
 The single catch lease and independent delivery-deferral leases have distinct lifetimes. Cancelling
 an active catch releases only that catch's lease. Cancelling a deferral operation before commit

package/guides/primitive-status-consolidation.md

@@ -72,7 +72,7 @@ The amended guidance's reachable-latest clause is applied: the selector remains
 - `test/core.test.js`: status and participants continue sharing actual authored and receipt times, including a fresh rejoin and watcher.
 - `test/process/square-cli-render.test.js`: the compact ten-person preview now includes a valid historical never-joined actor in the artifact. Status still hides that actor but its executable continuation uses the full count 14 rather than filtered count 13; participants prints the complete roster. Existing exact rejoin, attention, clipping/public-id continuation and presence feedback remain covered.
 
-No observation timing change is intended: optional viewer discovery still precedes status's resource read; the clock is sampled once inside the transaction, and all domain data, classification, perception and rendering annotations are assembled in that read. Queries perform no I/O or mutations themselves. SDK participant/snapshot shapes and MCP serialization of data remain unchanged. No join/claim is introduced.
+No observation timing change is intended: optional viewer discovery still precedes status's resource read; the clock is sampled once inside the transaction, and all domain data, classification, perception and rendering annotations are assembled in that read. Queries perform no I/O or mutations themselves. At the time, SDK participant/snapshot shapes and MCP serialization of data remained unchanged; the SDK snapshot was subsequently retired. No join/claim is introduced.
 
 Production reference search for `coreStatus|StatusObservation|StatusPresentation|ParticipantsPresentation|statusPresentation|participantsPresentation|StatusResult` returns no matches. Neither status nor participants has a duplicate roster in its projection. `git diff --check` passes.
 

package/guides/receive-primitive.md

@@ -79,8 +79,10 @@ primitive entrypoints without constructing Square.
 
 ## Square composition
 
-Square uses these functions for production landing, catch and `markSeen` against
-its existing activity, audience and receipt tables. Numeric activity indexes stay
+Square uses these functions for production landing, catch and `markSeen` (including explicit
+`Participant.ack`) against its existing activity, audience and receipt tables. `Participant.pending`
+uses the same addressed/unconsumed relation without writing receipts; its shared exact-ID, sender,
+metadata, search and cursor filters are applied by storage before the page limit. Numeric activity indexes stay
 internal keys; the primitive does not know Square IDs. Square retains validation,
 limits, filtering, perception, ownership, leases, hints and error mapping. The
 empty-catch read probe does not hydrate or acquire a writer; a nonempty probe is

package/guides/row-runtime-delivery-evidence.md

@@ -30,9 +30,9 @@ rg -n 'validateSquareState|exportSqliteState|initializeSqlite|writeSquareSnapsho
 - `square-state.ts` retains legacy validation for the separately implemented migration and test oracle. Normal v1 recognition validates framing and refuses with `migration_required`; it never decodes v1 history. Common per-activity validation is also used by the row codec.
 - `artifact.ts::readSquareSnapshot` and `square-sqlite.ts::exportSqliteState` are explicit export/integrity capabilities. Doctor intentionally reads all authority and compares maintained indices against a rebuild. Neither is a hot-runtime fallback.
 - `createSquareSnapshot` initializes a new artifact. `writeSquareSnapshot/writeSquareFile` are explicit build `--force`/fixture import, not whole-state transaction callbacks. Existing v1 still refuses before destructive work. `initializeSqlite` also supplies the migration's shared rebuild; it calls the same `deriveLanding`, not another production fold.
-- Public SDK `snapshot().delivered()` copies raw receipt assignments into a detached exact-owner Set; it does not retain a query or transaction capability and copies no activity history.
+- Historical (retired SDK API): `snapshot().delivered()` copied raw receipt assignments into a detached exact-owner Set; it does not retain a query or transaction capability and copies no activity history.
 - `.state` matches elsewhere are participant/admission states, transport outcomes or Claude's native `$.state` API, not artifact snapshots. `packages/agent-delivery` remains untouched.
-- `test/fixtures/legacy-square-core.js` is a frozen test-only v1 replay oracle. `square_snapshot` in the benchmark is instrumentation for detecting forbidden legacy reads, not a runtime path.
+- `square_snapshot` in the benchmark is instrumentation for detecting forbidden legacy reads, not a runtime path.
 
 ### Production source size
 
@@ -59,7 +59,7 @@ Evidence locations:
 
 | Invariant | Tests |
 |---|---|
-| Maintained roster/attention/audience equals independent v1 replay, including gaps, mixed spelling, reply/mention/listen/ignore/bell/done/rejoin priority and order | `test/row-domain.test.js`, frozen `test/fixtures/legacy-square-core.js` |
+| Landing audience priority and directed attention, including mixed spelling, reply/mention/listen/ignore/bell and departure | `test/row-domain.test.js` |
 | Sparse receipts, exact raw owners/orphans, unseen hole vs later catch, repeat no-op, filtered remaining, historical catch vs latest-join pending, distinct cursor/presence | `test/row-domain.test.js`, `test/perception-projection.test.js` |
 | Exact v2 schema, optional field preservation, immutable detached facts, expired capabilities, synchronous callbacks, caught storage failure rollback, no-op revision, selected corruption vs doctor | `test/artifact.test.js`, `test/core.test.js` |
 | Two real processes serialize catches; process death rolls activity and indices back; busy COMMIT retains callback/result; abort preserves reason; revision read has a positive SQL control | `test/sqlite-storage.test.js` |

package/guides/row-storage-design.md

@@ -1,5 +1,7 @@
 # Row-oriented artifact design
 
+> Historical design: the public SDK `Square.snapshot()` and its closure were retired. Snapshot-specific proposals below record the design at the time, not the current API.
+
 **Historical accepted design for artifact format 2.** The current runtime uses format 3 for the
 `unlisten` event; see [Square API](square-api.md#artifact-format-and-explicit-migration) for current
 format/migration behavior. The schema and delivery-stage terms below record the original row-storage
@@ -428,7 +430,9 @@ No production structure below carries `.state`, all `.activities`, or a deferred
 | public Square.snapshot().delivered(name,id) | explicit receiptAssignments + detached roster resolution + small header/status in ONE read txn, as below. Other production callers must not use this for count/standing. |
 | doctor / explicit import/export tests | full selected-row validation and replay comparison of indices; detached result includes standing count, not state for CLI header. Legacy validator lives only in explicit migration/test oracle. No automatic repair. |
 
-### Public SDK snapshot closure
+### Public SDK snapshot closure (retired)
+
+This historical design described the removed SDK `Square.snapshot()` API; it is no longer supported.
 
 Keep synchronous arbitrary `delivered(name,id)`. `snapshot()` intentionally copies ALL raw receipt assignments into a private detached Set keyed by JSON.stringify([rawOwner,index]), along with an immutable nameKey->first-roster-spelling map. Closure validates/parses id with current parseRequiredActivityId, resolves `map[nameKey(name)] ?? name`, and tests that exact owner/index set. This covers dormant raw owner keys, orphan assigned coordinates, unknown-name fallback, and arbitrary later calls after port close. It does not query a DB or retain SquareRead. Later writes do not alter this snapshot. No receipt times/activity bodies are copied. This O(receipts) exception is necessary for the existing synchronous API, and is limited to explicit SDK snapshot calls; lifecycle/status/poll/render use narrower helpers.