@astrosheep/square 0.3.73 → 0.3.74

package/dist/square-application.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { SquareError, isSquareError, nameKey, validateName } from './model.js';
-import { validateDoneBody } from './decisions.js';
+import { resolveKnownName, validateDoneBody } from './decisions.js';
 import { HELD_WAIT_BUDGET_MS, WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, observeCatchSelection } from './catch-decisions.js';
 import { directedSuffix } from './activity-feed.js';
@@ -19,6 +19,7 @@ import { createSquare, diagnoseSquareFile } from './artifact.js';
 import { migrateSquareFile } from './square-migration.js';
 import { discoverSquares, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT } from './list.js';
 import { streamSquare } from './stream.js';
+export { createSquareResourceOwner } from './open-square.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
 export { HELD_WAIT_BUDGET_MS } from './runtime.js';
@@ -82,8 +83,8 @@ async function joinOwned(square, requested, options = {}, control) {
 async function prepareExpression(square, requested, control) {
     try {
         checkControl(control);
-        const name = (await resolveParticipant(square, requested, control)).name;
-        return await joinOwned(square, name, {}, control);
+        const result = await join(square, requested, control, { requireKnown: true });
+        return { participant: result.name, activity: result.activity };
     }
     catch (error) {
         throw failure(error, { operation: 'express', subject: 'caller', participant: requested, expressEffect: 'unsent' });
@@ -139,12 +140,12 @@ async function landExpression(square, name, body, options, transport, control) {
         });
     }
 }
-async function expressOwned(square, requested, body, options, transport, control) {
+async function expressOwned(square, requested, body, options, transport, presentation, control) {
     const entry = await prepareExpression(square, requested, control);
     const name = entry.participant;
     let result;
     try {
-        const feed = (await square.artifact.read((facts) => {
+        const feed = !presentation ? undefined : (await square.artifact.read((facts) => {
             const pendingPublic = directedSuffix(facts, name);
             return {
                 pendingPublic,
@@ -161,7 +162,7 @@ async function expressOwned(square, requested, body, options, transport, control
                 activity: result.activity, waited: result.waited,
                 ...(result.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: result.replyAuthorNotHere }),
             },
-            projection: {
+            projection: feed === undefined ? undefined : {
                 ...fresh, ...feed, participant: name,
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
                 ...(entry.activity === null ? {} : { reentry: entry.activity }),
@@ -217,9 +218,11 @@ async function catchOwned(square, requested, options = {}, control) {
         if (Object.hasOwn(options, 'replace') && idle === 0)
             throw new SquareError('invalid_args', 'Catch replacement requires a positive idle duration');
         catchLimit(options.limit);
-        name = (await resolveParticipant(square, requested, control)).name;
-        subject = 'filter';
-        const from = options.from === undefined ? undefined : await Promise.all(options.from.map(async (target) => (await resolveParticipant(square, target, control)).name));
+        const from = (await square.artifact.read((facts) => {
+            name = resolveKnownName(facts, requested);
+            subject = 'filter';
+            return options.from?.map((target) => resolveKnownName(facts, target));
+        }, control?.signal)).value;
         selection = { ...options, ...(from === undefined ? {} : { from }) };
         subject = 'caller';
         if (idle === 0) {
@@ -360,12 +363,14 @@ export class Square {
     endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.square, name, sessionId, expectedEpoch); }
     retireEndedSessionRoutes(sessionId) { return retireEndedSessionRoutes(this.square, sessionId); }
 }
-export function createSquareApplication(context) {
+export function createSquareApplication(context, demand = { presentation: true }) {
+    const presentation = demand.presentation;
     const env = { ...context.env };
     const clock = clockFor(env, context.clock);
     const hostLedger = context.hostLedger ?? hostLedgerForEnv(env);
     const openOptions = { env, clock, hostLedger, wakeTransport: context.wakeTransport };
     const getTransport = defaultTransport(openOptions);
+    const resources = context.resources;
     function location() {
         const selected = context.squarePath ?? env.SQUARE_LOCATION;
         if (selected === undefined || selected.trim() === '')
@@ -385,7 +390,9 @@ export function createSquareApplication(context) {
     }
     async function scoped(operation, control) {
         checkControl(control);
-        const square = await openSquare(location(), openOptions, control);
+        const selected = location();
+        const artifact = resources?.artifact(selected);
+        const square = await openSquare(selected, { ...openOptions, artifact }, control);
         try {
             return await operation(square);
         }
@@ -416,7 +423,7 @@ export function createSquareApplication(context) {
             const result = await (verb === 'listen' ? listen : ignore)(square, name, target, control);
             return {
                 data: result,
-                projection: {
+                projection: !presentation ? undefined : {
                     ...await contextProjection(square, name), participant: name,
                     requestedTarget: target, target: result.activity?.target ?? target,
                 },
@@ -442,6 +449,8 @@ export function createSquareApplication(context) {
             else {
                 result = await resume(square, name, control);
             }
+            if (!presentation)
+                return { data: { activity: result.activity }, projection: undefined };
             const view = await eventPresentation(square, result.activity.id);
             return {
                 data: { activity: result.activity },
@@ -461,7 +470,7 @@ export function createSquareApplication(context) {
             }, input.markdown, control?.signal);
             return {
                 data: { location: squarePath, ...configuration },
-                projection: { location: squarePath, standingCount: 0, held: false, now,
+                projection: !presentation ? undefined : { location: squarePath, standingCount: 0, held: false, now,
                     automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(env) },
             };
         },
@@ -472,6 +481,8 @@ export function createSquareApplication(context) {
                     throw new SquareError('invalid_args', 'Join history limit must be between 1 and 100');
                 }
                 const data = await joinOwned(square, name, options, control);
+                if (!presentation)
+                    return { data, projection: undefined };
                 try {
                     const view = await entryPresentation(square, data.participant, last);
                     return {
@@ -485,19 +496,19 @@ export function createSquareApplication(context) {
             }, control);
         },
         express(body, options = {}, control) {
-            return selected('express', (square, name) => expressOwned(square, name, body, options, getTransport, control), control);
+            return selected('express', (square, name) => expressOwned(square, name, body, options, getTransport, presentation, control), control);
         },
         catch(options, control) {
             return selected('catch', async (square, name) => {
                 const result = await catchOwned(square, name, options, control);
-                const presence = await catchPresence(square, control).catch(() => undefined);
+                const presence = !presentation ? undefined : await catchPresence(square, control).catch(() => undefined);
                 const view = result.selection;
                 const stop = result.stop;
                 const status = stop === 'already-active' || stop === 'replaced' || stop === 'capped' || stop === 'quorum'
                     ? stop : undefined;
                 return {
                     data: { ...caughtResult(result), ...(status === undefined ? {} : { status }) },
-                    projection: {
+                    projection: !presentation ? undefined : {
                         ...observedContext(square, view.standingCount, view.held, view.participant, view.now),
                         participant: view.participant, sayNumbers: view.sayNumbers,
                         ownActivityCount: view.ownActivityCount, hardCap: view.hardCap, stop,
@@ -525,12 +536,15 @@ export function createSquareApplication(context) {
                 const limit = query.limit ?? (query.at?.length ? null : HISTORY_DEFAULT_LIMIT);
                 const kinds = query.at?.length || query.contextBefore !== undefined || query.contextAfter !== undefined || query.since !== undefined ? undefined : NON_READ;
                 return (await square.artifact.read((facts) => {
-                    const selected = selectHistory(facts, query, limit, kinds);
+                    const selected = selectHistory(facts, query, limit, kinds, presentation);
                     if (limit === null && selected.totalMatches > HISTORY_MAX_LIMIT) {
                         throw failure(new SquareError('invalid_args', `History context exceeds ${HISTORY_MAX_LIMIT} activities`), {
                             operation: 'history', historyBounds: { maxLimit: HISTORY_MAX_LIMIT, totalMatches: selected.totalMatches },
                         });
                     }
+                    const data = { activities: publicActivities(selected.activities) };
+                    if (!presentation)
+                        return { data, projection: undefined };
                     const indexes = selected.activities.map((activity) => activity.index);
                     const presenceAnchors = {};
                     for (const participant of facts.roster()) {
@@ -539,7 +553,7 @@ export function createSquareApplication(context) {
                             (presenceAnchors[anchor] ??= []).push(participant.name);
                     }
                     return {
-                        data: { activities: publicActivities(selected.activities) },
+                        data,
                         projection: {
                             ...observedContext(square, inSquareCount(facts), facts.hold().active), ...selected,
                             sayNumbers: facts.sayOrdinals(indexes), presenceAnchors,
@@ -554,7 +568,7 @@ export function createSquareApplication(context) {
             return selected('other', async (square, requested) => {
                 const name = (await resolveParticipant(square, requested, control)).name;
                 const targets = await listening(square, name, control);
-                return { data: { listening: targets }, projection: await contextProjection(square, name, control) };
+                return { data: { listening: targets }, projection: !presentation ? undefined : await contextProjection(square, name, control) };
             }, control);
         },
         hold: (reason, control) => lifecycle('hold', reason, control),
@@ -562,15 +576,15 @@ export function createSquareApplication(context) {
         done: (body, control) => lifecycle('done', body, control),
         async status(viewer, control) {
             checkControl(control);
-            const selectedViewer = viewer ?? await actor().catch(() => '');
+            const selectedViewer = !presentation ? '' : viewer ?? await actor().catch(() => '');
             return scoped(async (square) => (await square.artifact.read((facts) => queryStatus(facts, {
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
-            }, selectedViewer), control?.signal)).value, control);
+            }, selectedViewer, presentation), control?.signal)).value, control);
         },
         participants(control) {
             return scoped(async (square) => (await square.artifact.read((facts) => queryParticipants(facts, {
                 location: square.location, now: square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env),
-            }), control?.signal)).value, control);
+            }, presentation), control?.signal)).value, control);
         },
         async diagnose(control) {
             checkControl(control);
@@ -578,7 +592,7 @@ export function createSquareApplication(context) {
             const data = await diagnoseSquareFile(squarePath);
             return {
                 data,
-                projection: { location: squarePath, now: clock(),
+                projection: !presentation ? undefined : { location: squarePath, now: clock(),
                     ...(data.standingCount === undefined ? {} : { standingCount: data.standingCount }) },
             };
         },
@@ -586,14 +600,14 @@ export function createSquareApplication(context) {
             checkControl(control);
             const squarePath = location();
             const data = await migrateSquareFile(squarePath, control?.signal);
-            return { data, projection: { location: squarePath, now: clock(), standingCount: data.standing } };
+            return { data, projection: !presentation ? undefined : { location: squarePath, now: clock(), standingCount: data.standing } };
         },
         async discover(options, control) {
             checkControl(control);
             const data = await discoverSquares(context.cwd, options, control, openOptions);
             return {
                 data,
-                projection: { cwd: context.cwd, now: clock(),
+                projection: !presentation ? undefined : { cwd: context.cwd, now: clock(),
                     depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT },
             };
         },
@@ -633,7 +647,7 @@ export function createSquareApplication(context) {
                 const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
                 return compare(a.squarePath, b.squarePath) || compare(nameKey(a.name), nameKey(b.name)) || compare(a.name, b.name);
             });
-            return { data: { rows: rows.slice(0, limit), total: rows.length }, projection: { sessionId, now: clock(), limit } };
+            return { data: { rows: rows.slice(0, limit), total: rows.length }, projection: !presentation ? undefined : { sessionId, now: clock(), limit } };
         },
         async recovery(control) {
             let projection = { now: clock() };
@@ -659,7 +673,7 @@ export function createSquareApplication(context) {
                 }, control);
             }
             catch { /* unavailable recovery observations never replace the original error */ }
-            return { data: projection, projection };
+            return { data: projection, projection: presentation ? projection : undefined };
         },
         stream(options, control) {
             checkControl(control);

package/dist/square-facade.d.ts

@@ -1,6 +1,6 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { StoredAct } from './model.js';
-import type { HostLedgerPort, WakeTransportPort, DeliveryResult } from './ports.js';
+import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
 import type { DiagnoseResult } from './artifact.js';
 import type { MigrationOutcome } from './square-migration.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
@@ -136,10 +136,14 @@ export interface SquareApplicationContext extends Readonly<OpenOptions> {
     readonly env: NodeJS.ProcessEnv;
     readonly squarePath?: string;
     readonly participant?: string;
+    /** Borrow the owner's connection for the configured square. The caller owns its lifetime;
+     *  without an owner, each operation opens and closes its own connection. */
+    readonly resources?: SquareResourceOwner;
 }
-export interface ApplicationOutcome<Data, Projection> {
+/** Data-only callers do not request or pay for presentation work. */
+export interface ApplicationOutcome<Data, Projection, Presentation extends boolean = true> {
     readonly data: Data;
-    readonly projection: Projection;
+    readonly projection: Presentation extends true ? Projection : undefined;
 }
 export interface ApplicationFailureDetail {
     readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
@@ -444,26 +448,26 @@ export interface StatusProjection extends SquareContextProjection, PresenceClass
 }
 export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
 }
-export interface SquareApplication {
+export interface SquareApplication<Presentation extends boolean = true> {
     now(): number;
-    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection>>;
-    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection>>;
-    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection>>;
-    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection>>;
-    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection>>;
-    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection>>;
-    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection>>;
-    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>>;
-    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>>>;
-    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>>>;
-    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection>>;
-    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection>>;
-    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection>>;
+    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection, Presentation>>;
+    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection, Presentation>>;
+    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection, Presentation>>;
+    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection, Presentation>>;
+    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection, Presentation>>;
+    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection, Presentation>>;
+    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection, Presentation>>;
+    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, Presentation>>;
+    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection, Presentation>>;
+    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection, Presentation>>;
+    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection, Presentation>>;
     stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
 }
 export type JoinApplicationResult = JoinApplicationData;

package/dist/views.d.ts

@@ -11,7 +11,7 @@ export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume"
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds']): {
+export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
     visibleActivities: StoredAct[];
@@ -29,8 +29,10 @@ export declare function recoveryObservation(square: OpenSquare, name: string, co
 export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
 type ParticipantQueryContext = Pick<SquareContextProjection, 'location' | 'now' | 'automaticDeliveryAvailable'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>;
+export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, presentation: boolean): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, boolean>;
 export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string): ApplicationOutcome<StatusApplicationData, StatusProjection>;
+export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer: string, presentation: boolean): ApplicationOutcome<StatusApplicationData, StatusProjection, boolean>;
 export declare function eventPresentation(square: OpenSquare, id: ActivityId, control?: OperationControl): Promise<EventPresentation>;
 export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
 export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;

package/dist/views.js

@@ -28,7 +28,7 @@ export function parseRequiredActivityId(id) {
     return index;
 }
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export function selectHistory(facts, query, limit, kinds) {
+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);
@@ -44,14 +44,16 @@ export function selectHistory(facts, query, limit, kinds) {
         ...(query.at?.length ? { indexes: facts.contextIndexes(query.at.map(parseRequiredActivityId), query.contextBefore ?? 0, query.contextAfter ?? 0) } : {}),
         kinds: search === undefined ? kinds : ['say', 'done'],
     };
-    let selected, totalMatches, publicBefore, publicAfter;
+    let selected, totalMatches, publicBefore = false, publicAfter = false;
     if (recipient === undefined && search === undefined && limit !== null && limit <= PAGE_SIZE) {
         selected = facts.activityHeads(filter, { edge: afterIndex === undefined ? 'newest' : 'oldest', limit }).items;
-        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-        const publicFilter = { ...filter, kinds: [...ARCHIVE] };
         totalMatches = facts.activityCount(filter);
-        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;
+        if (presentation) {
+            const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+            const publicFilter = { ...filter, kinds: [...ARCHIVE] };
+            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;
+        }
     }
     else {
         const page = [];
@@ -68,7 +70,7 @@ export function selectHistory(facts, query, limit, kinds) {
                 if (matches !== undefined && !matches.has(head.index))
                     continue;
                 totalMatches++;
-                if (ARCHIVE.has(head.kind)) {
+                if (presentation && ARCHIVE.has(head.kind)) {
                     firstPublic = Math.min(firstPublic, head.index);
                     lastPublic = head.index;
                 }
@@ -82,14 +84,16 @@ export function selectHistory(facts, query, limit, kinds) {
             cursor = source.items.at(-1).index;
         }
         selected = page;
-        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-        publicBefore = publicHeads.length > 0 && firstPublic < publicHeads[0].index;
-        publicAfter = publicHeads.length > 0 && lastPublic > publicHeads.at(-1).index;
+        if (presentation) {
+            const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+            publicBefore = publicHeads.length > 0 && firstPublic < publicHeads[0].index;
+            publicAfter = publicHeads.length > 0 && lastPublic > publicHeads.at(-1).index;
+        }
     }
     const activities = [...facts.activities(selected.map((head) => head.index))];
     if (query.order === 'desc')
         activities.reverse();
-    const visibleActivities = activities.filter((activity) => ARCHIVE.has(activity.kind));
+    const visibleActivities = presentation ? activities.filter((activity) => ARCHIVE.has(activity.kind)) : [];
     const direction = afterIndex === undefined ? 'before' : 'after';
     const cursor = visibleActivities.length === 0 ? undefined : direction === 'before'
         ? Math.min(...visibleActivities.map((activity) => activity.index)) : Math.max(...visibleActivities.map((activity) => activity.index));
@@ -156,9 +160,9 @@ function classifyPresence(participants, now) {
         classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.state === 'done' ? 'done'
                 : participant.state === 'not joined' ? 'not-joined' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
 }
-export function queryParticipants(facts, context) {
+export function queryParticipants(facts, context, presentation = true) {
     const participants = coreParticipants(facts, context.now);
-    return { data: { participants }, projection: { ...context, ...classifyPresence(participants, context.now),
+    return { data: { participants }, projection: !presentation ? undefined : { ...context, ...classifyPresence(participants, context.now),
             standingCount: inSquareCount(facts), held: facts.hold().active } };
 }
 export async function listPresentation(square, control) {
@@ -170,30 +174,34 @@ export async function listPresentation(square, control) {
         return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
     }, control?.signal)).value;
 }
-export function queryStatus(facts, context, viewer = '') {
-    const { data: { participants }, projection } = queryParticipants(facts, context);
-    const header = facts.header(), hold = facts.hold();
+export function queryStatus(facts, context, viewer = '', presentation = true) {
+    const participants = coreParticipants(facts, context.now);
+    const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
     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 }),
+        activeCount: standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
+        hold: hold.active ? {
+            ...(hold.actor === undefined ? {} : { by: hold.actor }),
+            ...(hold.reason === undefined ? {} : { reason: hold.reason }),
+            ...(hold.at === undefined ? {} : { at: hold.at }),
+        } : null,
+        participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
+        ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
+    };
+    if (!presentation)
+        return { data, projection: undefined };
     const afterIndex = latestAct?.index ?? -1;
     const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({ activity,
         rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0 }));
     const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
-        data: {
-            hardCap: header.hardCap,
-            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-            activeCount: projection.standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
-            hold: hold.active ? {
-                ...(hold.actor === undefined ? {} : { by: hold.actor }),
-                ...(hold.reason === undefined ? {} : { reason: hold.reason }),
-                ...(hold.at === undefined ? {} : { at: hold.at }),
-            } : null,
-            participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
-            ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
-        },
+        data,
         projection: {
-            ...projection, knownParticipantCount: participants.length, viewer: canonicalViewer,
+            ...context, ...classifyPresence(participants, context.now), standingCount, held: hold.active,
+            knownParticipantCount: participants.length, viewer: canonicalViewer,
             ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
             joins, joinCount: facts.activityCount({ kinds: ['join'], afterIndex }),
             attentionNames: participants.filter((p) => canonicalViewer === '' || nameKey(p.name) === nameKey(canonicalViewer)).map((p) => p.name),

package/guides/application-demand-optimization.md

@@ -0,0 +1,50 @@
+# Application presentation demand
+
+## Design
+
+`createSquareApplication(context)` retains complete terminal-facing outcomes. MCP uses `createSquareApplication(context, { presentation: false })`; its outcome has the same `data` contract and `projection: undefined`.
+
+This is one explicit result demand, not a second business implementation. The application still owns admission, retries, receipts, cancellation and delivery. Ordinary early returns and conditional expressions skip presentation work where it was previously performed; there is no deferred projector, registry, cache or resource-lifetime change. CLI projection types remain required, while the data-only factory overload exposes their absence explicitly.
+
+MCP no longer requests join history/perceptions, the pre-expression directed feed, catch presence enrichment, listener context reads, lifecycle event rereads, or history/status/participants presentation-only annotations. Selection/counts required for results and history limits remain. For terminal expressions the directed feed is still captured once **before** landing, not after sending or on each retry. Delivery and postcommit publication remain on the original path.
+
+Two same-operation observations are consolidated:
+
+- Catch resolves caller and all sender filters in one typed-fact read, preserving caller-first validation, canonical error subjects, filter order and known-but-departed senders. The actual selection/receipt transaction, ownership admission and lease fences remain separate and current.
+- Expression's known-name check runs inside the existing join preview via an internal `requireKnown` admission option. Unknown names still fail before claiming or mutating; departed participants still reenter once. Ordinary join may still create a name. Preview facts never replace the subsequent ownership/CAS or commit-time checks.
+
+Long-lived MCP connections and concurrent delivery are deliberately outside this change.
+
+## Local MCP measurement
+
+Baseline: `31cc1bf`. Candidate: the presentation-demand and observation changes above. Node v26.10.0. A real MCP client used the SDK's in-memory transport, not a direct call to application helpers. Each call still creates its application and opens/closes the artifact.
+
+Three runs per variant, alternating B1/A1/B2/A2/B3/A3. Each process seeds four participants and 120 2,048-byte historical says outside measurement, joins the probe participant, then runs three warmup cycles and twenty measured cycles of repeated join, express, two empty filtered catches, history and status. Harness session keys are cleared: the probe's `reconnect` label means a repeated no-op join (`kind: joined`), not a real harness ownership reconnect. New measured expressions are small (`probe body`) and use force without pending directed feed; catches are empty. This is not a bulk-payload, ownership-contention or concurrent benchmark. No test suite, build or second benchmark ran alongside the six probes.
+
+Wall times below are the median of three run-level p50s, each from twenty measured calls. Small local timings are illustrative, not a production SLA or the earlier 300-process catch-p95 workload. The stable transaction/statement counts establish removed work more directly.
+
+| MCP operation | Wall p50 before → after (ms) | Artifact read transactions/call | SQL prepares/call |
+| --- | ---: | ---: | ---: |
+| Repeated no-op join | 1.478 → 1.036 | 3 → 2 | 30 → 15 |
+| Express | 3.963 → 3.372 | 6 → 4 | 79 → 61 |
+| Empty catch, one sender filter | 3.157 → 1.613 | 5 → 3 | 124 → 40 |
+| Empty catch, three sender filters | 3.335 → 1.655 | 7 → 3 | 134 → 42 |
+| History | 1.582 → 0.808 | 2 → 2 | 52 → 16 |
+| Status | 2.344 → 2.093 | 2 → 2 | 103 → 94 |
+
+Sender lookups still scale with filter count; **transactions do not**. No participant validation has been omitted to obtain that result. Repeated join's body-hydrating row reads fall from ten to zero per call. History still hydrates its ten result rows, and both empty catches hydrate none. Express and status each retain one body-hydrating row in this probe; not all body reads are presentation work.
+
+SQLite counters are attributed by canonical database location. Host-ledger/lock database work is counted separately, never attributed to the artifact. A positive calibration observes one port read as one artifact read transaction and `activities([0,1])` as two hydrated rows. History moves the same hydration counters used for the zero checks. Hydrated bytes in the probe mean returned string/blob bytes, not filesystem I/O.
+
+All six probes passed their calibration, first-join, hydration and no-error controls: 720 measured calls plus six first joins have no recorded errors. Warmup results are not retained or included in that gate. Raw per-call records retain timing/counters/errors but not complete returned payloads; each operation also retains its first measured result summary. Public-data/error parity is established by regression tests, not by those no-error benchmark controls. Recorded compiled-module hashes were checked before and after each probe; the probe script itself was not included in those historical hash manifests. Independent review recomputed the raw timing/counter statistics and confirmed the stated measurement limits.
+
+## Regression evidence
+
+- New tests prove MCP avoids the extra presentation reads, while terminal-facing join/express still hydrate real presentation content and express retains its pre-send feed.
+- A body-bearing catch hydrates exactly its selected page; empty catch and archive/status/participants data parity remain intact.
+- One versus multiple catch filters has the same read-transaction count; canonical caller/filter errors remain distinct.
+- Both new tests fail against the unchanged baseline at the intended hydration/transaction assertions.
+- The existing CLI/application/MCP activity/receipt parity, never-joined refusal, departed reentry, metadata ownership, cancellation and postcommit behavior tests pass.
+- Full suite: 680 passed, one opt-in Claude runtime test skipped. CLI process suite: 48 passed. Independent static review accepted correctness and control-flow clarity.
+
+Local evidence: `/tmp/square-upper-{before,after}-{1,2,3}.{json,log,exit,sha,integrity}`. Probe: `/tmp/square-mcp-demand-bench.mjs`. Test logs: `/tmp/square-upper-{tests,cli,negative}.log`.

package/guides/catch-cold-path-optimization.md

@@ -0,0 +1,56 @@
+# Catch cold-path optimization
+
+## Result and scope
+
+Under the existing 300-process Pi-session workload, first-catch API p95 falls by **60.4% / 61.4%** for histories of 1,800 / 18,000 activities. These are reductions between the medians of three run-level p95s, not a guarantee for every run or operation. Whole catch-phase p95 falls by about **56%** for both histories.
+
+The comparison is against `90752ba`, the current production implementation plus the same instrumentation, not an older, slower implementation. The benchmark represents Pi sessions without a Paseo route; it does not establish equal gains for Codex/Paseo sessions, emoji-only names, or native notification delivery.
+
+## Two changes
+
+- `model.ts`: try the existing Unicode text-name grammar before the full RGI emoji grammar. It accepts letters, numbers, marks excluding variation selectors, hyphens, underscores, and nonempty slash-separated segments. It is an exact subset of the original grammar; the original full matcher remains the fallback. `NAME_GRAPHEME_SOURCE`, also used by mention scanning, retains its original value.
+- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. Paseo precedence, Codex fallback, harness identity, and publication failure isolation remain unchanged.
+
+CPU sampling of the baseline pointed to cold name validation inside reader transactions and optional adapter module loading during catch. The changes remove that work rather than prewarm it or move it outside measurement. The sampling and this combined experiment do not establish each change's individual contribution.
+
+SQLite storage, DELETE journaling, FULL synchronous durability, transaction validation, ownership/epoch fences, receipts, and retry policy are unchanged. Earlier lock/backoff/cache experiments did not show the required improvement and are not included. The earlier [COMMIT-gap investigation](catch-lock-investigation.md) measured preparation inside writers; it did not bound costs inside concurrent readers or optional postcommit module loading.
+
+## Controlled comparison
+
+```sh
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
+```
+
+Node v26.10.0. Three runs of each variant, ordered B1, A1, B2, A2, B3, A3. Each command covers both histories. Baseline worktree: `/tmp/square-half-baseline-final`, detached at `90752ba`; candidate: the main worktree with the two changes above. Benchmark scripts were byte-identical. The changed compiled modules and benchmark script were hashed before and checked after every command. No other benchmark, test suite, build, or profile ran alongside the sequence; read-only review and test-source editing did occur. This is a local, alternating experiment, not a randomized or controlled-host latency guarantee.
+
+The benchmark workload is unchanged: 300 processes, 2,048-byte historical bodies, a five-second idle window, bell discovery without filesystem hints, then open, recognize, first catch, empty catch, and close. First-catch timing covers the complete participant catch API. Whole-phase timing includes all those catch-phase steps; it is not one catch call.
+
+### Median of three run-level measurements
+
+| Metric | Before, 1,800 | After, 1,800 | Reduction | Before, 18,000 | After, 18,000 | Reduction |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| First catch API p95 (ms) | 3,923.86 | 1,554.02 | 60.4% | 3,568.86 | 1,378.74 | 61.4% |
+| Whole catch phase p95 (ms) | 4,354.45 | 1,924.30 | 55.8% | 3,907.48 | 1,723.48 | 55.9% |
+| Empty catch API p95 (ms) | 58.49 | 56.60 | 3.2% | 82.22 | 54.84 | 33.3% |
+| Aggregate catch-phase CPU (ms) | 15,643.35 | 7,184.01 | 54.1% | 15,274.12 | 6,515.09 | 57.3% |
+
+### Individual first-catch p95s
+
+| History | Before B1 / B2 / B3 (ms) | After A1 / A2 / A3 (ms) |
+| --- | --- | --- |
+| 1,800 | 4,044.22 / 3,404.54 / 3,923.86 | 1,544.62 / 1,554.02 / 1,720.00 |
+| 18,000 | 3,024.11 / 3,568.86 / 3,759.82 | 1,343.00 / 1,824.53 / 1,378.74 |
+
+The second large-history pair improves by 48.9%, so the evidence does **not** say every paired run exceeded 50%. Both median reductions exceed 50%, and every candidate first-catch p95 is below every baseline p95 in its history group.
+
+## Correctness evidence
+
+All six commands exited successfully with empty stderr. Each of the twelve scenarios had 300 ready/completed workers and discovered all 300 participants. The raw per-worker reports were separately checked, including `remaining` (which the benchmark's built-in success gate does not assert): every worker consumed exactly one activity, had zero remaining, and consumed nothing again. That is 3,600 successful worker outcomes.
+
+Every scenario retained 300 hydrated bodies, 600 SQL writes, 300 committed artifact writes and 1,800 committed artifact reads. The recorded COMMIT execution-plus-gap invariant held. No workload or instrumentation was removed to obtain the reduction.
+
+Focused regression coverage preserves explicit expected acceptance/rejection for Unicode text, complete emoji, slash boundaries, selectors, joiners and malformed strings. A fresh-process module-loading test verifies that no-candidate drafting imports neither adapter, and that real Codex and Pi-plus-Paseo candidates still resolve through installed adapters.
+
+`npm test` passed (678 passed, one opt-in runtime test skipped); the CLI process suite passed all 48 tests. Running the new module-loading test against the unchanged baseline fails at its zero-import assertion (two adapters loaded), providing a negative control. Rebuilding for regression tests preserved the measured production module hashes. An independent review recomputed p95s from raw worker timings and verified the reported medians and outcomes.
+
+Local raw evidence: `/tmp/square-half-final-{before,after}-{1,2,3}.{json,err,exit,sha,integrity}`. Summary and per-worker assertion audit: `/tmp/square-half-final-summary.{py,json}`. The earlier pilot is excluded from the table.