@astrosheep/square 0.3.94 → 0.3.96

package/dist/square-tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod/v4';
-import { isSquareError } from './model.js';
+import { isSquareError, SquareError } from './model.js';
 import { requireOwner, requireJoinName, selectOwnSeat, CATCH_DEFAULT_LIMIT } from './square-api.js';
 import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, } from './operation-presentation.js';
 const location = z.string().optional().describe('Which square: a .square file path. Relative paths start from the working directory. Leave it out for the configured square.');
@@ -19,6 +19,14 @@ function tool(name, description, shape, run, render) {
             return render(receipt, operationArgs) ?? '';
         } };
 }
+export function squareToolsEnabled(env = process.env) {
+    const raw = env.SQUARE_TOOLS?.trim().toLowerCase();
+    if (raw === undefined || raw === '' || raw === '1' || raw === 'true')
+        return true;
+    if (raw === '0' || raw === 'false' || raw === 'none')
+        return false;
+    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.';
 const target = z.string().describe('The participant to turn toward or away from.');
 export const SQUARE_TOOLS = [
@@ -33,7 +41,7 @@ export const SQUARE_TOOLS = [
         reply: activityId.optional().describe('The activity you are answering, like act/12. Its author hears you if still here.'),
         noMention: z.boolean().optional().describe('Leave @names in the body as plain text. Mentions and reply still reach people.'),
         force: z.boolean().optional().describe('Speak now, even if something reached you that you have not caught yet.'),
-        noWait: z.boolean().optional().describe('If a hand is raised or you are speaking too fast, return at once instead of waiting.'),
+        noWait: z.boolean().optional().describe('If you are speaking too fast, return at once instead of waiting.'),
     }, async (square, { body, as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).express(body, { ...options, observe: true }, control), rendering((result) => renderExpression(result.observation?.location ?? '', result))),
     tool('catch', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you catch no longer waits for you; history lets you look back.', {
         as: participant,
@@ -64,16 +72,8 @@ export const SQUARE_TOOLS = [
         const self = await selectOwnSeat(square, identity.owner, as);
         return self[action](target, { observe: true }, control);
     }, rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, result))),
-    tool('hold', 'Raise a hand to pause the conversation; lower it with release. While a hand is up, new words wait to land.', {
-        as: participant,
-        reason: z.string().optional().describe('Why you are pausing. Everyone sees it.'),
-        release: z.boolean().optional().describe('true lowers the raised hand so the conversation goes on.'),
-    }, async (square, { as, reason, release }, control, identity) => {
-        const self = await selectOwnSeat(square, identity.owner, as);
-        return release === true ? self.resume({ observe: true }, control) : self.hold(reason, { observe: true }, control);
-    }, rendering((result, args) => renderLifecycleResult(result.observation?.location ?? '', args.release === true ? 'resume' : 'hold', result))),
-    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { as: participant }, async (square, { as }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).done(undefined, { observe: true }, control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
-    tool('status', 'Look around the square: who is here, whether a hand is raised, the latest activity, and who you listen to.', {
+    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { as: participant }, async (square, { as }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).done(undefined, { observe: true }, control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', result))),
+    tool('status', 'Look around the square: who is here, the latest activity, and who you listen to.', {
         as: z.string().optional().describe('Whose listening to show. Leave it out if you hold exactly one name here.'),
     }, async (square, { as }, control, identity) => {
         const viewer = (await selectOwnSeat(square, identity.owner, as, { optional: true }))?.name;

package/dist/views.d.ts

@@ -4,8 +4,8 @@ import type { ActivityFilter, SquareRead } from './ports.js';
 import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, 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", "hold", "resume", "listen", "ignore", "unlisten"];
-/** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
+export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignore", "unlisten"];
+/** The one StoredAct-to-public-Activity field mapping. Rejects read bookkeeping. */
 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;
@@ -22,7 +22,6 @@ export declare function recoveryObservation(facts: SquareRead, name: string, now
     participant: string;
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
     standingCount: number;
-    held: boolean;
     ownActivityCount: number;
     hardCap: import("./model.js").HardCap;
 };

package/dist/views.js

@@ -9,16 +9,17 @@ export const HISTORY_DEFAULT_LIMIT = 10;
 export const HISTORY_MAX_LIMIT = 100;
 const STATUS_HERE_WINDOW_MS = 30 * 60_000;
 const PRESENCE_WINDOW_MS = 8 * 60 * 60_000;
-export const NON_READ = ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore', 'unlisten'];
-const ARCHIVE = new Set(['join', 'done', 'say', 'hold', 'resume']);
-/** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
+export const NON_READ = ['join', 'done', 'say', 'listen', 'ignore', 'unlisten'];
+const ARCHIVE = new Set(['join', 'done', 'say']);
+/** The one StoredAct-to-public-Activity field mapping. Rejects read bookkeeping. */
 export function toPublicActivity(stored) {
-    if (stored.kind === 'read' || stored.actor === undefined)
+    if (stored.kind === 'read')
         throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
     return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
         ...(stored.kind === 'say' && stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
+        ...(stored.kind === 'say' && stored.delivery !== undefined ? { delivery: stored.delivery } : {}),
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
@@ -108,21 +109,20 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
     return { activities, visibleActivities, totalMatches, ...(continuation === undefined ? {} : { continuation }) };
 }
 export function publicActivities(activities) {
-    return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
+    return activities.flatMap((activity) => activity.kind === 'read' ? [] : [toPublicActivity(activity)]);
 }
 export function snapshot(facts, now) {
-    const header = facts.header(), hold = facts.hold();
+    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 }),
-        held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
         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), hold = facts.hold();
-    return { participant: known, activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
+    const known = resolveKnownName(facts, name);
+    return { participant: known, activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts),
         ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
 }
 export function entryPresentation(facts, name, lastN = HISTORY_DEFAULT_LIMIT) {
@@ -146,7 +146,7 @@ function classifyPresence(participants, now) {
 export function queryParticipants(facts, context, observe = false) {
     const participants = coreParticipants(facts, context.now);
     return { participants, ...(!observe ? {} : { observation: { ...context, ...classifyPresence(participants, context.now),
-                standingCount: inSquareCount(facts), held: facts.hold().active } }) };
+                standingCount: inSquareCount(facts) } }) };
 }
 export function listPresentation(facts) {
     const participants = facts.roster().filter((p) => p.joined).map((p) => {
@@ -157,21 +157,16 @@ export function listPresentation(facts) {
 }
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
-    const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
+    const header = facts.header(), standingCount = inSquareCount(facts);
     const listener = participants.find((p) => p.presence !== 'never-joined' && nameKey(p.name) === nameKey(viewer));
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
     const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
     const data = {
         hardCap: header.hardCap,
         ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-        held: hold.active ? {
-            ...(hold.actor === undefined ? {} : { by: hold.actor }),
-            ...(hold.reason === undefined ? {} : { reason: hold.reason }),
-            ...(hold.at === undefined ? {} : { at: hold.at }),
-        } : null,
         ...(listener === undefined ? {} : { listening: listener.listening }),
         participants: participants.filter((p) => p.presence !== 'never-joined'), now: context.now,
-        ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
+        ...(latestAct === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };
     if (!observe)
         return data;
@@ -200,7 +195,7 @@ export function catchPresence(facts, now) {
     return { participants, now };
 }
 export function streamProjection(facts, cursor, recipient) {
-    const page = facts.activityHeads({ afterIndex: cursor, kinds: NON_READ, actorRequired: true }, { edge: 'oldest', limit: PAGE_SIZE });
+    const page = facts.activityHeads({ afterIndex: cursor, kinds: NON_READ }, { edge: 'oldest', limit: PAGE_SIZE });
     const heads = recipient === undefined ? page.items : page.items.filter((head) => facts.directedAt(recipient, head.index) !== undefined);
     const activities = facts.activities(heads.map((head) => head.index)).map((activity) => recipient === undefined
         ? toPublicActivity(activity) : toPerceivedActivity(facts, activity, recipient));
@@ -210,7 +205,7 @@ export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipi
     if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
         throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
     const heads = last === 0 ? [] : recipient === undefined
-        ? facts.activityHeads({ kinds: NON_READ, actorRequired: true }, { edge: 'newest', limit: last }).items
+        ? facts.activityHeads({ kinds: NON_READ }, { edge: 'newest', limit: last }).items
         : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
     const activities = facts.activities(heads.map((head) => head.index)).map((activity) => recipient === undefined
         ? toPublicActivity(activity) : toPerceivedActivity(facts, activity, recipient));

package/dist/wakes.d.ts

@@ -11,9 +11,6 @@ export type WatchLeaseStart = {
 };
 export type WatchLeasePulse = {
     readonly type: 'replaced';
-} | {
-    readonly type: 'held';
-    readonly heartbeatAt?: number;
 } | {
     readonly type: 'terminal';
     readonly status: 'capped' | 'quorum';

package/dist/wakes.js

@@ -21,15 +21,13 @@ export async function pulseWatchLease(artifact, seat, at, leaseId, options, hear
         const known = resolveKnownName(facts, name), lease = freshWatchLease(facts, known, at);
         if (lease?.leaseId !== leaseId)
             return { type: 'replaced' };
-        const held = facts.hold().active;
-        const terminal = held ? undefined : watchTerminalStatus(facts, known);
+        const terminal = watchTerminalStatus(facts, known);
         if (terminal !== undefined)
             return { type: 'terminal', status: terminal };
-        const type = held ? 'held' : 'sleep';
         if (!heartbeatDue)
-            return { type };
+            return { type: 'sleep' };
         facts.putLease(known, newLease(leaseId, at, options), seat.generation);
-        return { type, heartbeatAt: at };
+        return { type: 'sleep', heartbeatAt: at };
     }, signal);
     return value;
 }

package/examples/symmetric-domains.mjs

@@ -0,0 +1,250 @@
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { resolveAudience } from '@astrosheep/square/attention';
+import { receive, consumeReceived, recordConsumed } from '@astrosheep/square/receive';
+import { claimAttempt, settleAttempt, dispatchEffect, preparePresentation, presentPrepared } from '@astrosheep/square/delivery';
+
+// Application routing fixture, not discovery or a core identity format.
+const directory = new Map([
+  ['e/author', 'east'], ['e/reader', 'east'], ['e/other', 'east'],
+  ['w/author', 'west'], ['w/reader', 'west'], ['w/other', 'west'],
+]);
+
+// One structural ReceiveWrite adapter. Array insertion order is local order;
+// opaque item keys are only compared for equality, never parsed or sorted.
+function receiveStore(state) {
+  const tx = {
+    insertItem({ key, data }) {
+      if (state.items.has(key)) throw new Error('duplicate item');
+      state.items.set(key, structuredClone(data));
+    },
+    insertAddress(key, address) {
+      if (tx.addressed(address.recipient, key)) throw new Error('duplicate address');
+      state.addresses.push({ key, ...address });
+    },
+    heads(recipient, query, { unconsumed, limit }) {
+      return state.addresses.filter(row => row.recipient === recipient
+        && (!query.via || row.via === query.via)
+        && (!unconsumed || !tx.receipt({ recipient, item: row.key }))).slice(0, limit);
+    },
+    addressed: (recipient, key) => state.addresses.find(row => row.recipient === recipient && row.key === key),
+    load: keys => new Map(keys.filter(key => state.items.has(key)).map(key => [key, state.items.get(key)])),
+    count: (recipient, query, unconsumed) => tx.heads(recipient, query, { unconsumed, limit: Infinity }).length,
+    receipt: ({ recipient, item }) => state.receipts.get(recipient)?.get(item),
+    insertReceipt({ recipient, item }, at) {
+      if (!state.receipts.has(recipient)) state.receipts.set(recipient, new Map());
+      const receipts = state.receipts.get(recipient);
+      if (receipts.has(item)) return false;
+      receipts.set(item, { at });
+      return true;
+    },
+  };
+  return tx;
+}
+
+// A tiny illustrative consumer, NOT a storage backend or durable runtime.
+class Domain {
+  #state = { items: new Map(), addresses: [], receipts: new Map(), series: [] };
+
+  constructor(name, nextKey) {
+    this.name = name;
+    this.nextKey = nextKey;
+  }
+
+  transaction(change) {
+    const draft = structuredClone(this.#state);
+    const result = change(draft, receiveStore(draft));
+    if (result instanceof Promise) throw new Error('no awaits inside memory transactions');
+    // A throw above discards the draft. No capability or mutable row escapes.
+    const captured = structuredClone(result);
+    this.#state = draft;
+    return captured;
+  }
+
+  originate(actor, mentions, text) {
+    // Attention names its route; receive stores that application route as via.
+    const audience = resolveAudience({ actor, recipients: [...directory.keys()], mentions })
+      .map(({ recipient, route }) => ({ recipient, via: route }));
+    const key = this.nextKey();
+    const data = { text, origin: { domain: this.name, key } };
+    this.transaction((_state, tx) => receive(tx, {
+      item: { key, data }, audience: audience.filter(a => directory.get(a.recipient) === this.name),
+    }));
+    const outgoing = new Map();
+    for (const address of audience) {
+      const destination = directory.get(address.recipient);
+      if (destination === this.name) continue;
+      if (!outgoing.has(destination)) outgoing.set(destination, []);
+      outgoing.get(destination).push(address);
+    }
+    return { key, data, outgoing };
+  }
+
+  admit(data, audience) {
+    const key = this.nextKey(); // Destination owns this identity, not origin.key.
+    this.transaction((_state, tx) => receive(tx, {
+      item: { key, data }, audience,
+    }));
+    return key;
+  }
+
+  // Captured item/target/purpose are application coordinates, not an encoded key.
+  // For dispatch target is a destination; for presentation it is one recipient.
+  effectPort(purpose, item, target, fullReceipts = []) {
+    const rows = state => {
+      let series = state.series.find(s => s.purpose === purpose && s.item === item && s.target === target);
+      if (!series) {
+        series = { purpose, item, target, attempts: new Map() };
+        state.series.push(series);
+      }
+      return {
+        list: () => structuredClone([...series.attempts.values()].sort((a, b) => b.ordinal - a.ordinal)),
+        byToken: token => structuredClone(series.attempts.get(token)),
+        insert: row => { series.attempts.set(row.token, structuredClone(row)); },
+        replace: row => { series.attempts.set(row.token, structuredClone(row)); },
+      };
+    };
+    const current = (state, tx) => state.items.has(item) && (purpose === 'dispatch'
+      || Boolean(tx.addressed(target, item)) && !tx.receipt({ recipient: target, item }));
+    return {
+      claim: async () => this.transaction((state, tx) => {
+        if (!current(state, tx)) return undefined;
+        const claim = claimAttempt(rows(state), {
+          purpose, token: randomUUID(), at: Date.now(), leaseMs: 30_000, data: {},
+        });
+        return claim.status === 'acquired' ? { token: claim.token, ordinal: claim.ordinal } : undefined;
+      }),
+      current: async () => this.transaction(current),
+      settle: async (claim, completion) => this.transaction((state, tx) => {
+        const recorded = settleAttempt(rows(state), {
+          token: claim.token, outcome: completion.outcome, at: Date.now(), data: completion,
+        });
+        // ONE commit: attempt completion plus captured full-consumption receipts.
+        // No post-effect cancellation/currentness veto and no re-selection.
+        if (recorded && completion.outcome === 'presented') recordConsumed(tx, fullReceipts, Date.now());
+        return recorded;
+      }),
+    };
+  }
+
+  consume(recipient, selection) {
+    return this.transaction((_state, tx) => consumeReceived(tx, recipient, selection, Date.now()));
+  }
+
+  pending(recipient) {
+    return this.transaction((_state, tx) => tx.heads(recipient, {}, { unconsumed: true, limit: Infinity }).map(h => h.key));
+  }
+
+  receipts() {
+    return this.transaction(state => [...state.receipts].flatMap(([recipient, items]) =>
+      [...items].map(([item, { at }]) => ({ recipient, item, at }))));
+  }
+
+  attempts() {
+    return this.transaction(state => state.series.map(({ purpose, item, target, attempts }) =>
+      ({ purpose, item, target, outcomes: [...attempts.values()].map(a => a.outcome) })));
+  }
+
+  async present(recipient, item, sink) {
+    const payload = this.transaction((_state, tx) => {
+      if (!tx.addressed(recipient, item)) throw new Error('not addressed');
+      return tx.load([item]).get(item);
+    });
+    const prepared = await preparePresentation({
+      payload, coverage: 'full',
+      port: this.effectPort('presentation', item, recipient, [{ recipient, item }]),
+    });
+    return prepared ? presentPrepared(prepared, sink) : undefined;
+  }
+}
+
+export async function demonstrateSymmetricDomains() {
+  // Same implementation, truly separate stores and unrelated key spaces.
+  let westKey = -700;
+  const east = new Domain('east', () => `opaque?${randomUUID()}`);
+  const west = new Domain('west', () => westKey--);
+  const domains = new Map([['east', east], ['west', west]]);
+  const handoffs = [];
+  let online = true;
+
+  async function sendAll(source, message, mode = 'accepted') {
+    const reports = [];
+    for (const [destination, audience] of message.outgoing) {
+      const report = await dispatchEffect(source.effectPort('dispatch', message.key, destination), async context => {
+        if (!await context.beforeSend()) return { outcome: 'not-capable' };
+        // A final policy gate may finish after the runner's timeout. Never mutate
+        // the destination after our deadline or cancellation, even if it said yes.
+        if (context.signal?.aborted || Date.now() >= context.deadline) return { outcome: 'not-capable' };
+        if (!online) return { outcome: 'failed' }; // Known no-send in this in-process fixture.
+        const key = domains.get(destination).admit(message.data, audience);
+        handoffs.push({ from: source.name, to: destination, key, audience: structuredClone(audience) });
+        // Unknown deliberately happens AFTER admission. This is not a dedup protocol.
+        return { outcome: mode, data: { destinationKey: key } };
+      }, { timeoutMs: 1000 });
+      reports.push(report);
+    }
+    return reports;
+  }
+
+  const eastMessage = east.originate('e/author', ['e/reader', 'w/reader', 'w/other'], 'East says hello');
+  const westMessage = west.originate('w/author', ['w/reader', 'e/reader', 'e/other'], 'West says hello');
+  // Establish origin receipts before destination presentation: neither can overwrite the other.
+  east.consume('e/reader', { kind: 'exact', key: eastMessage.key, remainingQuery: {} });
+  west.consume('w/reader', { kind: 'exact', key: westMessage.key, remainingQuery: {} });
+
+  const exchanges = [];
+  for (const [source, destination, message, mode, first, second] of [
+    [east, west, eastMessage, 'accepted', 'w/reader', 'w/other'],
+    [west, east, westMessage, 'unknown', 'e/reader', 'e/other'],
+  ]) {
+    const [report] = await sendAll(source, message, mode);
+    const destinationKey = report.settlement.completion.data.destinationKey;
+    const admission = [destination.pending(first), destination.pending(second)];
+    const originReceiptsBefore = source.receipts();
+    const output = [];
+    // The sink proves only that this example callback captured the full payload.
+    const presentation = await destination.present(first, destinationKey, payload => { output.push(payload); });
+    const afterPresentation = [destination.pending(first), destination.pending(second)];
+    const presentationReceipts = destination.receipts().filter(ref => ref.item === destinationKey);
+    const originReceiptsAfter = source.receipts();
+    const exact = { kind: 'exact', key: destinationKey, remainingQuery: {} };
+    const unmatched = destination.consume(second, { kind: 'page', query: { via: 'bell' }, limit: 1 });
+    const consumed = destination.consume(second, { kind: 'page', query: { via: 'mention' }, limit: 1 });
+    const repeated = destination.consume(second, exact);
+    const handoffsBeforeReplay = handoffs.length;
+    const [replay] = await sendAll(source, message, mode);
+    exchanges.push({
+      from: source.name, to: destination.name, sourceKey: message.key, destinationKey,
+      dispatch: report, admission, presentation, output, afterPresentation, presentationReceipts,
+      originReceiptsBefore, originReceiptsAfter, unmatched, consumed, repeated, replay,
+      handoffsBeforeReplay, handoffsAfterReplay: handoffs.length,
+    });
+  }
+
+  online = false;
+  const handoffsBeforeOffline = handoffs.length;
+  const offline = [];
+  for (const [domain, author, recipient] of [[east, 'e/author', 'e/reader'], [west, 'w/author', 'w/reader']]) {
+    const messages = [];
+    for (const text of ['oldest', 'middle', 'newest']) {
+      const message = domain.originate(author, [recipient], text);
+      messages.push(message);
+      await sendAll(domain, message); // Local work has no remote destination at all.
+    }
+    const exact = { kind: 'exact', key: messages[1].key, remainingQuery: {} };
+    const middle = domain.consume(recipient, exact);
+    const repeated = domain.consume(recipient, exact);
+    const page = () => domain.consume(recipient, { kind: 'page', query: { via: 'mention' }, limit: 1 });
+    offline.push({ domain: domain.name, keys: messages.map(m => m.key), middle, repeated, pages: [page(), page()] });
+  }
+  return {
+    exchanges, handoffs, offline, handoffsBeforeOffline, handoffsAfterOffline: handoffs.length,
+    attempts: { east: east.attempts(), west: west.attempts() },
+    receipts: { east: east.receipts(), west: west.receipts() },
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  console.log(JSON.stringify(await demonstrateSymmetricDomains(), null, 2));
+}

package/guides/application-facade-delivery-evidence.md

@@ -117,7 +117,7 @@ production line delta -7
 - Root `activity.ts` (271 lines) and `watch.ts` (328 lines) are deleted. Their surviving draft/retry/rendering code is counted in the new CLI helpers (206 + 68 lines); moving renderers is not claimed as semantic deletion.
 - CLI build/join/listener/lifecycle/history/status/catch no longer open storage for admission, before/after facts, projections or sweep coordination. `cli/context.ts` no longer constructs a ledger or discovers bindings during parsing. Application `selected` captures an actor per operation, not a mutable-binding cache.
 - Catch has one leased quiet-wait owner; the old action absolute-idle loop and CLI heartbeat/revision/finish wrappers are removed. Selection carries records/ordinals/header facts in its receipt transaction. Optional nearby presence does not rehydrate the selected page.
-- Express has one preparation/reentry and retry/commit owner. It selects the pending directed feed once, and uses commit-observed count/hold/cap facts rather than rebuilding that feed or issuing a duplicate post-success header query.
+- Express has one preparation/reentry and retry/commit owner. It selects the pending directed feed once, and uses commit-observed count/cap facts rather than rebuilding that feed or issuing a duplicate post-success header query.
 - MCP `publicResult`, stored-activity conversion and status-result policy are deleted. Private producers reuse the facade DTOs instead of maintaining parallel status/unread declarations.
 - Deleted unused `Square.joinWithActivity`, `takeoverWithActivity`, `joinFacts`, `standingCount`; deleted `views.activityPresentation`, `standingCount`, `joinFacts`, `watchPresentation`, and `presentation.renderWatchOutput`. Focused `recoveryObservation` and optional `catchPresence` replace the displaced mixed queries. Supported SDK/session methods remain.
 - `list.ts` no longer parses argv or writes process output; `stream.ts` no longer owns stdout/drain. The CLI owns those adaptations.
@@ -141,7 +141,7 @@ rg exit: 1
 
 ## private action imports
 pattern: from\s*['"][^'"]*square-actions\.js['"]
-square-application.ts:14:import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, retireEndedSessionRoutes, type ExpressCommittedResult } from './square-actions.js';
+square-application.ts:14:import { catchUp, done, endOwnedSession, express, ignore, implicitJoin, join, takeover, listen, listening, retireEndedSessionRoutes, type ExpressCommittedResult } from './square-actions.js';
 rg exit: 0
 
 ## adapter direct private execution
@@ -157,7 +157,7 @@ rg exit: 1
 
 The adapter grep's sole match resolves to **`cli/registry.ts`**, the argv registry, not the root host-binding `registry.ts`. The AST dependency test resolves paths instead of mistaking equal basenames for equal ownership.
 
-`test/architecture-boundary.test.js` passed the transitive adapter/helper traversal and its deliberate hidden-bypass fixtures. It checks all CLI roots, MCP and presentation helpers; permits only named pure bindings (core IDs, immutable held limit, model syntax/errors, identity formatting, search formatting) and closed protocol edges (harness, native hook I/O, MCP immutable `operationEnv`). It rejects private execution hidden through nested helpers, namespace/extra mixed-module bindings, an exceeded native exception and unbounded imports. These are not blanket directory exemptions. Existing storage-boundary/synchronous-capability tests also pass.
+`test/architecture-boundary.test.js` passed the transitive adapter/helper traversal and its deliberate hidden-bypass fixtures. It checks all CLI roots, MCP and presentation helpers; permits only named pure bindings (core IDs, model syntax/errors, identity formatting, search formatting) and closed protocol edges (harness, native hook I/O, MCP immutable `operationEnv`). It rejects private execution hidden through nested helpers, namespace/extra mixed-module bindings, an exceeded native exception and unbounded imports. These are not blanket directory exemptions. Existing storage-boundary/synchronous-capability tests also pass.
 
 ## Closure map for pre-delivery findings
 
@@ -174,8 +174,8 @@ These are deliverer closures, not a reviewer verdict. Rows distinguish behavior
 | Actor discovery cached across binding changes | No actor cache. Reused-app fixture joins Alice, leaves, binds Bob, then expresses as current Bob without reentering Alice or claiming a second name. |
 | Join count derived by racy pre-read arithmetic | `square-actions.join` returns known joined-or-done count from its authoritative join transaction; takeover returns the same fact from its atomic done+join transaction. `joinOwned` uses returned count, never adds to a pre-read. Verified by transaction/source inspection; existing concurrent-owner/join tests remain passing. Standing headers remain distinct. |
 | Express cleanup/enrichment erases commit or calls it unsent | Resource close cannot replace a completed result. Action route/host publication is best effort after commit. Commit observation replaces duplicate post-read. Boundary fixtures prove postcommit host-publication failure returns the activity, projection-clock failure retains landed ID without replay, and selected-row corruption is unknown rather than proven unsent. Operation-cancellation has before-return commit abort coverage. |
-| Catch completion/enrichment erases a committed page | Raw page, ordinals/count/cap/hold/terminal facts travel with receipt selection; completion never rereads them. Only optional `catchPresence` can be unavailable. `performance`: real selection hydrates exactly its page; presence/rendering adds no hydration/reads. Operation-cancellation preserves committed consumption after abort. |
-| Replaced/cancelled waiter consumes later activity or releases new lease | Catch selection transaction checks lease ID. Finally cleanup is non-aborted and ID-fenced. Boundary fixtures prove replacement owns consumption, old waiter returns replaced, cancelled waiter releases lease, later attention stays pending. Hold/expiry and CLI watch-wait heartbeat fixtures pass. |
+| Catch completion/enrichment erases a committed page | Raw page, ordinals/count/cap/terminal facts travel with receipt selection; completion never rereads them. Only optional `catchPresence` can be unavailable. `performance`: real selection hydrates exactly its page; presence/rendering adds no hydration/reads. Operation-cancellation preserves committed consumption after abort. |
+| Replaced/cancelled waiter consumes later activity or releases new lease | Catch selection transaction checks lease ID. Finally cleanup is non-aborted and ID-fenced. Boundary fixtures prove replacement owns consumption, old waiter returns replaced, cancelled waiter releases lease, later attention stays pending. Lease expiry and CLI watch-wait heartbeat fixtures pass. |
 | SDK projection roundtrip / leaked observations | The current SDK result shapes are documented in [Square/Participant API](square-api.md); parity tests exercise the real resource and projection tests preserve the detached delivered predicate. |
 | Duplicate contracts, aliases and dead mixed views | Private status/unread producers import/re-export facade contracts; catch observation extends shared expression facts and enriched projection reuses it; required express participant replaces name alias. Retired helper search is empty. Recovery selects only gates/bounded unread summaries, not discarded feed/ordinals/perceptions. |
 | Packed owner orchestration hides effects/count integrity | History, lifecycle branches, maintenance/discovery/recovery, catch conflict and SDK recognize are expanded into readable steps. Remaining one-line SDK delegates are supported simple resource calls, not packed async policy. Inspect implementation diff; all new source is included in count. |

package/guides/attention-primitive.md

@@ -0,0 +1,32 @@
+# Attention audience resolution
+
+The standalone `@astrosheep/square/attention` subpath computes an audience from
+caller data. It does not open a square, send or consume anything, or grant permission.
+
+```ts
+import { resolveAudience } from '@astrosheep/square/attention';
+
+const audience = resolveAudience({
+  actor: 'east:alice',
+  recipients: ['east:bob', 'west:carol'],
+  mentions: ['west:carol'],
+  incoming: [{ listener: 'east:bob', kind: 'listen' }],
+});
+// [{ recipient: 'west:carol', route: 'mention' },
+//  { recipient: 'east:bob', route: 'attention' }]
+```
+
+The caller supplies eligible recipients in canonical spelling and order, and owns
+their validation and persistence. Identity is exact by default; `sameIdentity` may
+provide a deterministic equivalence relation. The first equivalent recipient gives
+the output spelling. Mentions precede the reply author, followed by listeners in
+recipient order; ignores exclude all three. A `reach: 'bell'` reaches all eligible
+recipients except the actor, bypassing ignores. Equivalent recipients appear once.
+
+The caller decides whether a bell's recipient snapshot is local or global, and when
+that snapshot is authoritative. Square supplies its standing participants and
+incoming relationships at landing, inside its persistence transaction. The result
+is computed attention, separate from delivery and consumption.
+
+For an installed consumer composing this with receive and delivery in two equal,
+independent domains, see the [symmetric domains example](symmetric-domains.md).

package/guides/change-waits.md

@@ -28,9 +28,9 @@ notifications are hints, not activity delivery or consumption receipts.
   returns promptly. An existing active delivery observer will reconsider release/expiry; absent an
   observer, pending work waits for the next normal delivery opportunity. A lease does not create a
   process that was not already running.
-- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. A held catch keeps
+- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. An active catch keeps
   its single lease alive and pauses quiet expiry. Core catch and streams use the same storage change
-  detector. Held express also waits for changes; throttling waits for its eligibility time.
+  detector. Throttling waits for its eligibility time.
 - Deferrals are independent of catch filters, presentation claims, full-delivery seen receipts,
   clipped previews and session-local cancellation. Sharing storage detection does not share session
   delivery state. Cancellation never creates a receipt or removes archive history. A deferral cannot

package/guides/codex-delivery.md

@@ -40,7 +40,7 @@ an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare se
 boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
 defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
 conversation storage and are not proof of current native execution or consumption.
-Square's format-7 artifact remains authoritative for membership, attachment and delivery evidence.
+Square's format-8 artifact remains authoritative for membership, attachment and delivery evidence.
 Detached members appear away indefinitely and keep accumulating unread audience, but have no
 write or proactive delivery eligibility until same-owner reattachment. Only a host-confirmed
 permanent deletion uses fenced membership-ending cleanup; Codex SessionEnd is not that proof.