@astrosheep/square 0.3.86 → 0.3.88

package/dist/square-stdio.js

@@ -3,9 +3,10 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { SquareError } from './model.js';
 import { harnessSessionSources } from './participant-identity.js';
+import { requireJoinName } from './seats.js';
 export const STDIO_PROTOCOL_VERSION = 1;
 export const STDIO_MAX_FRAME_BYTES = 8 * 1024 * 1024;
-export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])]), 'SQUARE_PARTICIPANT_NAME'];
+export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])])];
 export function wireIdentity(env) {
     return Object.fromEntries(identityVariables.map(key => [key, env[key] ?? '']));
 }
@@ -162,7 +163,11 @@ class StdioSquare {
     participantHandle(name) {
         return {
             name,
-            express: (body, options, control) => this.call('express', [body, options], control, name),
+            express: ((bodyOrInput, optionsOrControl, control) => {
+                if (typeof bodyOrInput === 'object' && bodyOrInput !== null)
+                    return this.call('express', [bodyOrInput, undefined], optionsOrControl, name);
+                return this.call('express', [bodyOrInput, optionsOrControl], control, name);
+            }),
             catch: (options, control) => this.call('catch', [options], control, name),
             listen: (target, options, control) => this.call('listen', [target, options], control, name),
             ignore: (target, options, control) => this.call('ignore', [target, options], control, name),
@@ -176,6 +181,7 @@ class StdioSquare {
     }
     async participant(name) { return this.participantHandle(await this.call('participant', [name])); }
     async join(...[name, options, control]) {
+        requireJoinName(name);
         const result = await this.call('join', [name, options], control);
         return { ...result, participant: this.participantHandle(result.participant) };
     }
@@ -187,14 +193,13 @@ class StdioSquare {
     stream() { unsupported('stream'); }
     recognize() { return Promise.reject(new SquareError('invalid_args', 'stdio does not support host recognition; select a participant explicitly')); }
     implicitJoin() { unsupported('host implicit join'); }
-    doneOwnedSession() { unsupported('host session cleanup'); }
     endOwnedSession() { unsupported('host session cleanup'); }
-    retireEndedSessionRoutes() { unsupported('host wake routes'); }
+    cancelDeliveries() { unsupported('host delivery cancellation'); }
     close() { return this.connection.close(); }
 }
 export async function openStdioSquare(location, selected, input, backends, build, control) {
-    if (input.clock || input.hostLedger || input.wakeTransport)
-        unsupported('client clock, hostLedger or wakeTransport injection');
+    if (input.clock || input.wakeTransport)
+        unsupported('client clock or wakeTransport injection');
     if (control?.signal?.aborted)
         throw control.signal.reason ?? new Error('Operation cancelled');
     const backend = Object.hasOwn(backends, selected.backend) ? backends[selected.backend] : undefined;
@@ -205,7 +210,7 @@ export async function openStdioSquare(location, selected, input, backends, build
     const connection = new Connection(command, backend.args ?? [], path.resolve(cwd, backend.cwd ?? '.'), { ...(input.env ?? process.env), ...backend.env });
     try {
         const result = await connection.request('square/open', { version: STDIO_PROTOCOL_VERSION, key: selected.key, location,
-            identity: wireIdentity(input.env ?? process.env), participant: input.participant, build }, control);
+            identity: wireIdentity(input.env ?? process.env), body: input.body, participant: input.participant, build }, control);
         if (result.version !== STDIO_PROTOCOL_VERSION || typeof result.handle !== 'string')
             throw new SquareError('unavailable', 'Backend protocol version mismatch');
         return new StdioSquare(location, connection, result.handle);

package/dist/square-tools.d.ts

@@ -16,7 +16,7 @@ interface ToolDefinition {
 export interface ToolControl extends OperationControl {
     readonly observe?: boolean;
 }
-export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
+export declare 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.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];
 export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;
 /** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */

package/dist/square-tools.js

@@ -1,9 +1,9 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
 import { CATCH_DEFAULT_LIMIT } from './square-api.js';
-import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderListeningResult, renderParticipantsResult, renderStatusResult, } from './operation-presentation.js';
-const location = z.string().optional().describe('Local .square artifact path or configured backend URI (stdio://name/key). Relative paths use the current working directory. Defaults to the configured square.');
-const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
+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, or a backend URI like stdio://name/key. Relative paths start from the working directory. Leave it out for the configured square.');
+const participant = z.string().optional().describe('Your name in the square. Leave it out if you hold exactly one name here.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 /** Keep the observation request internal: it is not an argument a caller decides. */
@@ -14,50 +14,103 @@ function observation(control) {
 function rendering(render) {
     return (result, args) => render(result, args);
 }
+/**
+ * Tool receipts are the one machine surface without activity metadata: a receipt copy drops every
+ * property named `metadata` while domain activities keep theirs for SDK, CLI, stdio and stream readers.
+ */
+function withoutActivityMetadata(value) {
+    if (Array.isArray(value))
+        return value.map(withoutActivityMetadata);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'metadata')
+        .map(([key, item]) => [key, withoutActivityMetadata(item)]));
+}
+/**
+ * Human text renders from the unfiltered receipt, so metadata-only says keep the placeholder the
+ * CLI prints and every other sentence stays identical. Machines only ever receive the filtered copy.
+ */
+const renderingReceipts = new WeakMap();
+function renderingReceipt(receipt) {
+    return (renderingReceipts.get(receipt) ?? receipt);
+}
 function tool(name, description, shape, run, render) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, render, run: (square, args, control) => {
+    return { name, description, inputSchema, render: (receipt, args) => render(renderingReceipt(receipt), args),
+        run: async (square, args, control) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            return run(square, operationArgs, control);
+            const receipt = await run(square, operationArgs, control);
+            const filtered = withoutActivityMetadata(receipt);
+            renderingReceipts.set(filtered, receipt);
+            return filtered;
         } };
 }
-export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
+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 = [
-    tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, async (square, { as, takeover }, control) => {
+    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.', {
+        as: z.string().optional().describe('Your name in the square. Give it explicitly when joining.'), takeover: z.boolean().optional().describe('Claim this name even though another session holds it now. That session loses it.'),
+    }, async (square, { as, takeover }, control) => {
         const { participant, ...receipt } = await square.join(as, { takeover, ...observation(control) }, control);
         return { ...receipt, participant: participant.name };
     }, rendering((result) => renderJoinResult(result))),
-    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone and keeps body @names literal. Bell cannot combine with explicit mentions. Bare activity is valid even with no listeners.', {
-        as: participant, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(),
-        reply: activityId.optional(), noMention: z.boolean().optional().describe('Disable body @name scanning; explicit mentions and reply still apply.'),
-        force: z.boolean().optional().describe('Speak without first catching unread activity or satisfying attention etiquette.'),
-        noWait: z.boolean().optional().describe('Return an error rather than waiting when held or throttled.'),
+    tool('express', 'Speak or act in the square. Plain words, half-formed ideas and *actions* all belong here. Mention or reply to someone to be heard by them; ring the bell to be heard by everyone. Said to no one in particular, your words reach those who listen to you.', {
+        as: participant,
+        body: z.string().describe('What you say or do. Markdown works; *asterisks* mark an action.'),
+        mentions: stringArray.optional().describe('Who you are speaking to. An @name in the body that matches someone here counts too.'),
+        reach: z.enum(['bell']).optional().describe('"bell" calls everyone in the square. Cannot be used with mentions.'),
+        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.'),
     }, async (square, { body, as, ...options }, control) => {
         const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, { ...options, ...observation(control) }, control);
         return result;
     }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
-    tool('catch', 'Catch and consume activities perceptible to the participant. idle waits for relevant activity or this many milliseconds of quiet; omitted means immediate. id catches one activity and cannot be combined with filters, idle or limit.', {
-        as: participant, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(),
-        mention: z.boolean().optional(), limit: z.number().int().min(1).optional(),
+    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,
+        id: activityId.optional().describe('Take in this activity in full, like act/12, even if you caught it before. Do not combine with idle, from, mention or limit.'),
+        idle: z.number().finite().min(0).optional().describe('When nothing is waiting, wait until something arrives or until it has been quiet this many milliseconds. Leave it out to return at once.'),
+        from: stringArray.optional().describe('Only what these participants said.'),
+        mention: z.boolean().optional().describe('Only what was addressed to you, and bells.'),
+        limit: z.number().int().min(1).optional().describe('At most this many at once (default 10, up to 100). The rest keeps waiting.'),
     }, async (square, { as, ...options }, control) => (await square.participant(as)).catch({ ...options, ...observation(control) }, control), rendering((result, args) => {
         // The CLI always spells the default cap in its continuation, so the tool does too.
         const options = args;
         const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? CATCH_DEFAULT_LIMIT } : options;
         return renderCatchOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
     })),
-    tool('history', 'Read the activity stream without consuming it, using stable activity-id cursors. Default page size is 10, maximum 100. grep is a regex; fixed is literal text; use only one.', {
-        limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(),
-        grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional(),
+    tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for catch keeps waiting. Page with before or after.', {
+        limit: z.number().int().min(1).optional().describe('How many per page (default 10, up to 100).'),
+        order: z.enum(['asc', 'desc']).optional().describe('"asc" for oldest first (default), "desc" for newest first.'),
+        before: activityId.optional().describe('The page just before this activity, like act/12.'),
+        after: activityId.optional().describe('The page just after this activity, like act/12.'),
+        grep: z.string().optional().describe('Only activities matching this regular expression in their names, ids or words. Use grep or fixed, not both.'),
+        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, ...observation(control) }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
-    tool('listen', 'Listen for future activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'listen', result))),
-    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'ignore', result))),
-    tool('unlisten', 'Stop listening to a participant’s future activity; mentions and replies still reach you. An existing ignore is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).unlisten(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'unlisten', result))),
-    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening(observation(control), control), rendering((result) => renderListeningResult(result.observation?.location ?? '', result))),
-    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'hold', result))),
-    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume(observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'resume', result))),
-    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
-    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status(observation(control), control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
-    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants(observation(control), control), rendering((result) => renderParticipantsResult(result.observation?.location ?? '', result))),
+    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) => {
+        const self = await square.participant(as);
+        return self[action](target, observation(control), 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) => {
+        const self = await square.participant(as);
+        return release === true ? self.resume(observation(control), control) : self.hold(reason, observation(control), 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) => (await square.participant(as)).done(undefined, observation(control), 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.', {
+        as: z.string().optional().describe('Whose listening to show. Leave it out if you hold exactly one name here.'),
+    }, (square, { as }, control) => square.status({ viewer: as, ...observation(control) }, control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/stdio-server.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
 import { SqliteSquare } from './sqlite-square.js';
-import { SquareError } from './model.js';
+import { SquareError, validateBody } from './model.js';
 import { canonicalPath } from './canonical-path.js';
 import { STDIO_PROTOCOL_VERSION, STDIO_MAX_FRAME_BYTES, encodeError, identityVariables } from './square-stdio.js';
 import { parseSquareLocation } from './square-location.js';
@@ -71,7 +71,9 @@ export async function runSquareStdioServer(root) {
                         throw new SquareError('invalid_args', 'Invalid operation identity');
                     env[key] = value ?? '';
                 }
-                const input = { path: target, env, participant: params.participant };
+                const input = { path: target, env, body: params.body, participant: params.participant };
+                if (params.body !== undefined)
+                    validateBody(params.body);
                 square = params.build === undefined ? await SqliteSquare.at(input, control, false)
                     : await SqliteSquare.build({ ...params.build, ...input }, control, false);
                 location = parsed.uri;

package/dist/stream.d.ts

@@ -1,3 +1,4 @@
-import type { OpenOptions, OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
+import type { SquareArtifactPort } from './ports.js';
+import type { OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamRecord>;
+export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, borrowed?: SquareArtifactPort): AsyncIterable<StreamRecord>;

package/dist/stream.js

@@ -1,15 +1,13 @@
 import fs from 'node:fs/promises';
 import { SquareError } from './model.js';
-import { observeSquareRevision } from './artifact.js';
-import { openSquare, closeOpenSquare } from './open-square.js';
+import { createArtifactPort, observeSquareRevision } from './artifact.js';
 import { streamProjection, streamTailProjection } from './views.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export function streamSquare(squarePath, options = {}, control, openOptions = {}) {
+export function streamSquare(squarePath, options = {}, control, borrowed) {
     return {
         [Symbol.asyncIterator]() {
             const disposal = new AbortController();
             const signal = control?.signal === undefined ? disposal.signal : AbortSignal.any([control.signal, disposal.signal]);
-            const iterationControl = { ...control, signal };
             const records = observe();
             return {
                 next: () => records.next(),
@@ -43,19 +41,20 @@ export function streamSquare(squarePath, options = {}, control, openOptions = {}
                             let projection;
                             try {
                                 baseline = await observer.read(signal);
-                                const square = await openSquare(squarePath, { ...openOptions, env: openOptions.env ?? {}, signal }, iterationControl);
+                                const artifact = borrowed ?? createArtifactPort(squarePath, undefined, signal);
                                 try {
-                                    projection = initial === undefined
-                                        ? await streamProjection(square, cursor, options.recipient, iterationControl)
-                                        : await streamTailProjection(square, initial.last, options.recipient, iterationControl);
+                                    projection = (await artifact.read(facts => initial === undefined
+                                        ? streamProjection(facts, cursor, options.recipient)
+                                        : streamTailProjection(facts, initial.last, options.recipient), signal)).value;
                                 }
                                 finally {
-                                    await closeOpenSquare(square);
+                                    if (borrowed === undefined)
+                                        await artifact.close();
                                 }
                             }
                             catch (error) {
                                 signal.throwIfAborted();
-                                if (error instanceof SquareError && error.code === 'invalid_args')
+                                if (borrowed !== undefined || error instanceof SquareError && error.code === 'invalid_args')
                                     throw error;
                                 // Repair/replacement is a hint, not a reason to scan history on a timer.
                                 await observer.hinted(generation, Infinity, signal);

package/dist/views.d.ts

@@ -1,8 +1,7 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
-import type { OpenSquare } from './open-square.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, OperationControl, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
+import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
 export type { EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
@@ -18,12 +17,8 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function resolveParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<{
-    name: string;
-}>;
-export declare function currentParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<string | undefined>;
-export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
-export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<{
+export declare function snapshot(facts: SquareRead, now: number): SquareSnapshot;
+export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     ownActivityCount: number;
     hardCap: import("./model.js").HardCap;
     holdReason?: string | undefined;
@@ -32,12 +27,12 @@ export declare function recoveryObservation(square: OpenSquare, name: string, co
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
     standingCount: number;
     held: boolean;
-}>;
-export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
+};
+export declare function entryPresentation(facts: SquareRead, name: string, lastN?: number | null): EntryPresentation;
 type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now' | 'automaticDeliveryAvailable'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, observe?: boolean): ParticipantsResult;
-export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
+export declare function listPresentation(facts: SquareRead): ListPresentation;
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string, observe?: boolean): StatusResult;
-export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
-export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
-export declare function streamTailProjection(square: OpenSquare, last?: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
+export declare function catchPresence(facts: SquareRead, now: number): CatchPresence;
+export declare function streamProjection(facts: SquareRead, cursor: number, recipient?: string): StreamProjection;
+export declare function streamTailProjection(facts: SquareRead, last?: number, recipient?: string): StreamProjection;

package/dist/views.js

@@ -18,6 +18,7 @@ export function toPublicActivity(stored) {
     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 } : {}),
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
@@ -104,46 +105,34 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
 }
-export async function resolveParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
-}
-export async function currentParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => { const p = facts.participant(name); return p?.joined ? p.name : undefined; }, control?.signal)).value;
-}
 function statuses(facts, now) {
     return coreParticipants(facts, now).filter((p) => p.state !== 'not joined').map((p) => {
         const cursor = readCursor(facts, p.name);
         return { name: p.name, state: p.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: p.presence === 'watching', listening: p.listening };
     });
 }
-export async function snapshot(square, control) {
-    return (await square.artifact.read((facts) => {
-        const header = facts.header(), hold = facts.hold();
-        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: statuses(facts, square.clock()), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
-    }, control?.signal)).value;
-}
-export async function recoveryObservation(square, name, control) {
-    return (await square.artifact.read((facts) => {
-        const known = resolveKnownName(facts, name), hold = facts.hold();
-        return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), standingCount: inSquareCount(facts), held: hold.active,
-            ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
-    }, control?.signal)).value;
-}
-export async function entryPresentation(square, name, lastN = HISTORY_DEFAULT_LIMIT, control) {
-    return (await square.artifact.read((facts) => {
-        const header = facts.header();
-        const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
-        return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
-            scene: header.warmup.join('\n').trim(),
-            joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
-            perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
-            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
-    }, control?.signal)).value;
+export function snapshot(facts, now) {
+    const header = facts.header(), hold = facts.hold();
+    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: statuses(facts, now), 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, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
+        ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
+}
+export function entryPresentation(facts, name, lastN = HISTORY_DEFAULT_LIMIT) {
+    const header = facts.header();
+    const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
+    return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
+        scene: header.warmup.join('\n').trim(),
+        joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
+        perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
+        sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
 }
 function classifyPresence(participants, now) {
     const here = participants.filter((participant) => participant.state === 'active' && (participant.presence === 'watching'
@@ -159,18 +148,17 @@ export function queryParticipants(facts, context, observe = false) {
     return { participants, ...(!observe ? {} : { observation: { ...context, ...classifyPresence(participants, context.now),
                 standingCount: inSquareCount(facts), held: facts.hold().active } }) };
 }
-export async function listPresentation(square, control) {
-    return (await square.artifact.read((facts) => {
-        const participants = facts.roster().filter((p) => p.joined).map((p) => {
-            const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
-            return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
-        }).sort(compareParticipantActivity).map((p) => p.name);
-        return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
-    }, control?.signal)).value;
+export function listPresentation(facts) {
+    const participants = facts.roster().filter((p) => p.joined).map((p) => {
+        const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
+        return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
+    }).sort(compareParticipantActivity).map((p) => p.name);
+    return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
 }
 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 listener = participants.find((p) => p.state !== 'not 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 = {
@@ -182,6 +170,7 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
             ...(hold.reason === undefined ? {} : { reason: hold.reason }),
             ...(hold.at === undefined ? {} : { at: hold.at }),
         } : null,
+        ...(listener === undefined ? {} : { listening: listener.listening }),
         participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
         ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };
@@ -204,33 +193,26 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
         },
     };
 }
-export async function catchPresence(square, control) {
-    return (await square.artifact.read((facts) => {
-        const now = square.clock();
-        const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
-            || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
-        return { participants, now };
-    }, control?.signal)).value;
-}
-export async function streamProjection(square, cursor, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
-        const heads = page.items.flatMap((head) => {
-            const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
-            return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
-        });
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
-                const route = heads.find((h) => h.index === activity.index).route;
-                return { activity, ...(route === undefined ? {} : { route }) };
-            }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
-    }, control?.signal)).value;
+export function catchPresence(facts, now) {
+    const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
+        || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
+    return { participants, now };
 }
-export async function streamTailProjection(square, last = HISTORY_DEFAULT_LIMIT, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        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({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
-                ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
-    }, control?.signal)).value;
+export function streamProjection(facts, cursor, recipient) {
+    const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
+    const heads = page.items.flatMap((head) => {
+        const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
+        return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
+    });
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
+            const route = heads.find((h) => h.index === activity.index).route;
+            return { activity, ...(route === undefined ? {} : { route }) };
+        }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
+}
+export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipient) {
+    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({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
+            ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
 }

package/dist/wakes.d.ts

@@ -1,5 +1,6 @@
 import { type WatchLease, type WatchOptions } from './model.js';
-import type { OpenSquare } from './open-square.js';
+import type { SquareArtifactPort } from './ports.js';
+import type { Seat } from './model.js';
 export type WatchLeaseStart = {
     readonly type: 'started';
     readonly leaseId: string;
@@ -21,7 +22,7 @@ export type WatchLeasePulse = {
     readonly type: 'sleep';
     readonly heartbeatAt?: number;
 };
-export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
-export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
-export declare function releaseWatchLease(square: OpenSquare, name: string, leaseId: string | undefined): Promise<void>;
-export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string, signal?: AbortSignal): Promise<boolean>;
+export declare function acquireWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
+export declare function pulseWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
+export declare function releaseWatchLease(artifact: SquareArtifactPort, seat: Seat, leaseId: string): Promise<void>;
+export declare function ownsWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, signal?: AbortSignal): Promise<boolean>;