@astrosheep/square 0.3.78 → 0.3.80

package/dist/views.d.ts

@@ -2,8 +2,8 @@ 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, ApplicationOutcome, ArchiveRecord, HistoryQuery, HistoryApplicationQuery, HistoryContinuation, OperationControl, ParticipantStatus, ParticipantsApplicationData, ParticipantsProjection, SquareSnapshot, RecoveryObservation, EntryPresentation, ListPresentation, StatusApplicationData, StatusProjection, SquareContextProjection, CatchPresence, StreamProjection, EventPresentation } from './square-facade.js';
-export type { RecoveryObservation, EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
+import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, OperationControl, 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;
 export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume", "listen", "ignore"];
@@ -11,29 +11,33 @@ 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'], presentation?: boolean): {
+export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
     visibleActivities: StoredAct[];
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function history(square: OpenSquare, query?: HistoryQuery, control?: OperationControl): Promise<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 participants(square: OpenSquare): Promise<ParticipantStatus[]>;
 export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
-export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<RecoveryObservation>;
+export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<{
+    ownActivityCount: number;
+    hardCap: import("./model.js").HardCap;
+    holdReason?: string | undefined;
+    participant: string;
+    roster: string[];
+    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>;
-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>;
+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 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 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>;

package/dist/views.js

@@ -104,9 +104,6 @@ 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 history(square, query = {}, control) {
-    return (await square.artifact.read((facts) => publicActivities(selectHistory(facts, query, query.limit ?? null, NON_READ).activities), control?.signal)).value;
-}
 export async function resolveParticipant(square, name, control) {
     return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
 }
@@ -119,9 +116,6 @@ function statuses(facts, now) {
         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 participants(square) {
-    return (await square.artifact.read((facts) => statuses(facts, square.clock()))).value;
-}
 export async function snapshot(square, control) {
     return (await square.artifact.read((facts) => {
         const header = facts.header(), hold = facts.hold();
@@ -136,19 +130,19 @@ export async function snapshot(square, control) {
 export async function recoveryObservation(square, name, control) {
     return (await square.artifact.read((facts) => {
         const known = resolveKnownName(facts, name), hold = facts.hold();
-        return { name: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), participantCount: inSquareCount(facts), held: hold.active,
+        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(), p = facts.participant(name);
+        const header = facts.header();
         const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
-        return { joined: p?.joined ?? false, joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
-            scene: header.warmup.join('\n').trim(), context: header.preamble.join('\n').trim(),
+        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)), participantCount: inSquareCount(facts), held: facts.hold().active };
+            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
     }, control?.signal)).value;
 }
 function classifyPresence(participants, now) {
@@ -160,10 +154,10 @@ 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, presentation = true) {
+export function queryParticipants(facts, context, observe = false) {
     const participants = coreParticipants(facts, context.now);
-    return { data: { participants }, projection: !presentation ? undefined : { ...context, ...classifyPresence(participants, context.now),
-            standingCount: inSquareCount(facts), held: facts.hold().active } };
+    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) => {
@@ -174,7 +168,7 @@ 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 = '', presentation = true) {
+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 latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
@@ -191,15 +185,15 @@ export function queryStatus(facts, context, viewer = '', presentation = true) {
         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 };
+    if (!observe)
+        return data;
     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,
-        projection: {
+        ...data,
+        observation: {
             ...context, ...classifyPresence(participants, context.now), standingCount, held: hold.active,
             knownParticipantCount: participants.length, viewer: canonicalViewer,
             ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
@@ -210,14 +204,6 @@ export function queryStatus(facts, context, viewer = '', presentation = true) {
         },
     };
 }
-export async function eventPresentation(square, id, control) {
-    return (await square.artifact.read((facts) => {
-        const activity = facts.activity(parseRequiredActivityId(id));
-        if (activity === undefined)
-            throw new SquareError('invalid_args', `Unknown activity id: ${id}`);
-        return { activity, participantCount: inSquareCount(facts), held: facts.hold().active };
-    }, control?.signal)).value;
-}
 export async function catchPresence(square, control) {
     return (await square.artifact.read((facts) => {
         const now = square.clock();

package/guides/application-demand-optimization.md

@@ -1,5 +1,10 @@
 # Application presentation demand
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 ## Design
 
 `createSquareApplication(context)` retains complete terminal-facing outcomes. MCP uses `createSquareApplication(context, { presentation: false })`; its outcome has the same `data` contract and `projection: undefined`.

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

@@ -1,6 +1,11 @@
 # Shared application boundary: delivery evidence
 
-Deliverer evidence, **not independent review or acceptance**. Design and the complete caller/deletion map are in [application-facade-design](application-facade-design.md).
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
+Deliverer evidence, **not independent review or acceptance**. The historical caller/deletion map is recorded below; current ownership is described in [Square/Participant API](square-api.md).
 
 ## Candidate coordinates
 
@@ -174,7 +179,7 @@ These are deliverer closures, not a reviewer verdict. Rows distinguish behavior
 | SDK projection roundtrip / leaked observations | SDK express uses `prepareExpression` + `landExpression`, strips observation/waited and retains delivery; SDK catch uses `catchOwned` and returns only established CatchResult. SDK test asserts established fields and avoids application body projections. SDK Square history stays unbounded, Participant recent-ten; parity history fixture proves both, and projection test preserves detached delivered predicate. |
 | Duplicate contracts, aliases and dead mixed views | Private status/unread producers import/re-export facade contracts; catch observation extends shared expression facts and enriched projection reuses it; required express participant replaces name alias. Retired helper search is empty. Recovery selects only gates/bounded unread summaries, not discarded feed/ordinals/perceptions. |
 | Packed owner orchestration hides effects/count integrity | History, lifecycle branches, maintenance/discovery/recovery, catch conflict and SDK recognize are expanded into readable steps. Remaining one-line SDK delegates are supported simple resource calls, not packed async policy. Inspect implementation diff; all new source is included in count. |
-| Invalid reply / missing reach / done repair regressions | Typed `invalid_reply` covers malformed and valid-but-absent IDs; typed reach/done reasons stay domain facts, CLI owns glyphs/flags. Express-recovery tests execute printed repaired commands, preserving raw drafts and other recipients; missing reach offers executable `--no-mention`; done ends scoped help. Unknown/landed effects offer reconciliation, never replay. |
+| Invalid reply / done repair regressions | Typed `invalid_reply` covers malformed and valid-but-absent IDs; typed reach/done reasons stay domain facts, CLI owns glyphs/flags. Express-recovery tests execute printed repaired commands, preserving raw drafts, body candidates and other recipients. Unknown/landed effects offer reconciliation, never replay. |
 | Failing application clock prevents draft creation | `executeExpression` uses `saveActivityDraft`'s transport-local `Date.now` default, never the failed owner clock. Focused `express-recovery` fixture supplies a throwing clock and landed error plus throwing recovery; exact CRLF raw is already saved at recovery invocation, landed ID remains in history reconciliation, and no replay is offered. |
 | Captured default wake stops at adapter or executable selection | Amended `defaultWakeAdapters(env)` builds `CodexQueueAdapter({env})`; queue executable comes from explicit bin, else supplied env, never later ambient env. Boundary test uses a real isolated fake executable and captured child environment/queue destination after global mutation; injected port wins. No real native delivery. |
 | Force-build ignores cancellation under lock | Amended build/create signal reaches existing lock retries and transaction boundaries; abort checked before public link, cleanup signal-free, no postcommit rejection. Real exclusive-lock fixture cancels, unlocks, and proves unchanged snapshot/no delayed rebuild/no temporary artifact. Separate published-link fixture aborts after commit and still gets the build result. |

package/guides/mcp-connection-lifetime.md

@@ -1,8 +1,8 @@
 # MCP connection lifetime
 
-An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call still creates an application with that request's participant and harness session. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
+An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call opens an actual `Square` handle with that request's captured environment, default participant and harness session; `square.participant()` performs nonmutating name selection. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
 
-`createSquareResourceOwner()` is the explicit lifetime boundary. `scoped()` borrows its connection; ordinary application callers still open and close their own. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
+`createSquareResourceOwner()` is the explicit lifetime boundary. `Square.at({resources, ...})` borrows its connection; closing a request handle leaves the owner open. Ordinary callers open and close their own Square. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
 
 ## Local measurement
 

package/guides/mcp.md

@@ -8,6 +8,6 @@ The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `l
 
 Claude's bundled plugin configures this server automatically. Its mod supplies live session/cwd/subagent attribution through an out-of-band tool-use-ID association, not AI-visible arguments; see [Claude call identity](claude-native.md#mcp-tools-and-call-identity). The bundled endpoint requires that association rather than falling back to its startup environment.
 
-Tool definitions and argument-to-facade calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
+Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Join serializes the handle's name and receipt fields, never resource internals. All callers use the [same concrete resource API](square-api.md), with no alternate factory or generic outcome envelope. `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
 
 Configure a client with command `npx` and arguments `--yes --package @astrosheep/square square mcp-server`, or use the installed `square` executable with argument `mcp-server`. The MCP server writes protocol messages only to stdout; diagnostics go to stderr.

package/guides/operation-cancellation.md

@@ -14,4 +14,6 @@ The single-root HostLedgerPort passes `(input, signal)` for cancellable claims;
 
 Ownership and delivery have the same limitation: cancellation can stop work that has not entered the boundary, but it cannot withdraw an ownership effect or a transport send that already happened. The returned committed result and existing degradation classification remain authoritative.
 
+The same `Square`/`Participant` methods serve SDK and adapters; see [resource API](square-api.md). Join, listener and lifecycle essential observations use commit-time facts. Join's optional entry enrichment may be unavailable without rejecting its successful receipt. CLI express passes its abort signal through the initial `Square.at`; raw draft saving precedes a separate uncancelled recovery reopen.
+
 Pi notification cancellation is separate and unchanged.

package/guides/primitive-catch-consolidation.md

@@ -1,5 +1,10 @@
 # Canonical catch selection — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence only, **not independent review or acceptance**.
 
 ## Coordinates and lane attribution

package/guides/primitive-history-consolidation.md

@@ -1,5 +1,10 @@
 # History query consolidation — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not an independent review or acceptance.
 
 ## Coordinates and lane-local reduction

package/guides/primitive-status-consolidation.md

@@ -1,5 +1,10 @@
 # Canonical status and participant queries — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not independent review or acceptance.
 
 ## Coordinates and lane attribution

package/guides/primitive-storage-consolidation.md

@@ -1,5 +1,10 @@
 # Artifact and resource primitive consolidation
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not independent review or acceptance.
 
 ## Coordinates and scope

package/guides/row-storage-design.md

@@ -414,7 +414,7 @@ No production structure below carries `.state`, all `.activities`, or a deferred
 |---|---|
 | openSquare/openSquareArtifact, wait baselines, watch headers, cli/program | header/revision only; remove preliminary whole-state validation/load. Every normal selected-row decode remains validated. |
 | square-actions join/implicitJoin/takeover/done/endOwnedSession, registry-associated route cleanup | participant/roster as needed, routes, land/replaceRoutes; same host claim lock scopes and cleanup sequences. Takeover done+join is one txn. No full SDK snapshot. |
-| createSquareApplication.join's before/after snapshot and CLI hold/resume/done count calls | new internal `joinFacts(name)` projection = requested participant, known joined-or-done count, standing count. Before conflict pending uses known joined-or-done count as today; application's participantCount keeps its existing known joined-or-done semantics. CLI header after hold/resume/done uses standing count. Wire private helpers on Square/context rather than calling public snapshot. |
+| Join's before/after snapshot and CLI hold/resume/done count calls | Current `Square.join` returns its concrete receipt with a Participant handle; optional observations use transaction-captured counts, held state and time. Listener/lifecycle commit facts likewise come from the mutation transaction; join's extra entry history is best-effort. Known joined-or-done `participantCount` remains distinct from the standing count. See [Square/Participant API](square-api.md). |
 | express/decideAct and behind rendering (activity.ts) | header, actor fact, roster for longest standing-body mention resolution, hold, reply head/existence, recentSayTimes, continuous cursor, directed suffix. Admission normalization/error order unchanged. A valid reply coordinate is <nextActIndex, even if a gap: preserve current acceptance of assigned-but-missing reply. ActivityPresentation supplies own count/cap/hold/roster, suffix items with lifetime ordinals + settled full perception, and behind summaries. No whole history used just to number previews. |
 | listen/ignore/listening, watch leases and terminal checks | actor fact, outgoing attention; roster only for quorum; land or lease methods. Unknown valid attention target still allowed. Pulse keeps hold-before-terminal priority. |
 | catch / native seen | directed selectors/activity exact, markSeen, cursor/counts in txn; native `current` becomes synchronous `(facts: SquareRead)=>boolean`, evaluated ONLY within reads/receipt txn. It cannot escape or call host I/O. |

package/guides/square-api.md

@@ -0,0 +1,107 @@
+# Square and Participant API
+
+`Square` is the actual resource handle shared by SDK, CLI, MCP and Pi. Its implementation is
+`square-api.ts`; `square.ts` remains the executable CLI entrypoint. `square-facade.ts` contains
+only public types. There is no separate operation factory, dispatcher or `{data, projection}` envelope.
+
+## Open, select, join, close
+
+```ts
+import { Square } from '@astrosheep/square';
+
+const square = await Square.at({ path: './PUBLIC.square', env: { ...process.env } });
+try {
+  const joined = await square.join('Alice');
+  const alice = joined.participant;
+  const sent = await alice.express('Hello @Bob', { force: true });
+  const page = await square.history();
+  console.log(sent.activity.id, page.activities);
+} finally {
+  await square.close();
+}
+```
+
+- `Square.build({path, markdown, hardCap?, throttlePerMinute?, template?, force?, ...})` returns
+  the same open resource. `Square.inMemory({markdown, ...})` is synchronous and creates no default
+  native wake transport.
+- `Square.at` accepts `path`, optional `cwd`, captured `env`, `clock`, `hostLedger`, `wakeTransport`
+  and default `participant`. An omitted path uses captured `SQUARE_LOCATION`; relative paths use
+  `cwd`. Explicit participant, configured default, nonblank captured `SQUARE_PARTICIPANT_NAME`,
+  then an unambiguous current-session ledger binding determine a name, in that order.
+- `await square.participant(name?)` selects a handle **without joining, claiming or reentering**.
+  Discovery happens on each selection, not through a cached session-to-name decision.
+- `square.join(name?, options?, control?)` returns one `JoinResult`: `{participant, activity, kind,
+  participantCount, observation?}`. `participant` is a handle, not a string. `takeover: true` reclaims
+  a standing name; fresh/departed names join normally. There is no separate `Participant.join()`
+  or public `takeover()` API. `participantCount` counts known joined-or-done names.
+- A Square owns its connection unless `resources: createSquareResourceOwner()` lends it one.
+  Closing a borrowing handle leaves that owner open. Request signals never become the borrowed
+  connection's lifetime. The MCP server drains cancelled/in-flight work before closing its owner;
+  explicit location overrides get independent request-owned connections.
+
+## One set of operations and defaults
+
+Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
+Participant owns `express`, `catch`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`;
+its `history` delegates to the same Square history operation.
+
+- Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
+  includes the committed `activity`, `waited`, optional `delivery`, and landing-time warnings
+  (`unmatchedMentions`, `replyAuthorNotHere`). Warnings are not stored on the activity.
+- Catch returns `{activities, consumedThrough, remaining, idleExpired, status?, observation?}`.
+  Omitted/zero idle is immediate; positive idle uses the single leased quiet wait. Receipt selection,
+  ordinals, counts and terminal facts settle in the receipt transaction. Cancellation/replacement
+  releases only that waiter's lease and never consumes future activity.
+- All history callers return a `HistoryResult` object with `activities`. Default page size is ten;
+  `limit: null` explicitly requests an unbounded archive. Numeric limits must be 1–100. Contextual
+  queries still reject an implicit merged window over 100 activities; an explicit numeric limit
+  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts.
+- `participants()` returns `{participants, observation?}` and `listening()` returns
+  `{listening, observation?}`, not arrays carrying metadata.
+- Lifecycle operations keep contextual reentry/ownership policy. In particular, done retains its
+  native owner epoch fence instead of blindly joining first. Done accepts no message.
+
+Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
+Listener/lifecycle operations take optional observation options before that control argument.
+
+## Optional observations, not another execution path
+
+Request `observe: true` on the **same method** when rendering needs additional facts. Each operation
+has a concrete optional observation type, without conditional generics or a generic outcome wrapper.
+Data-only calls do not hydrate join history, the pre-expression feed, catch presence enrichment,
+or history/status presentation annotations.
+
+Express captures its optional directed feed before the attempt and returns count/held/time facts
+from the committed transaction. Listener and lifecycle observations likewise use their mutation's
+facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
+entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the
+successful receipt survives. Catch preserves its committed page even if optional nearby presence
+fails. A cancellation or failed clock after commit cannot turn these receipts into an unsent retry.
+
+`OperationError.operation` supplements authoritative error facts with caller/filter/recipient and
+express certainty. Selected-row/execution failures remain unknown unless admission proved the
+expression unsent. CLI saves raw drafts even when opening the resource fails; its initial open
+receives the express abort signal, while recovery reopening is deliberately uncancelled.
+
+## Adapters and standalone functions
+
+CLI and tools only adapt input, identity, resource lifetime and output. They do not import private
+actions, storage, admission, scanners or query execution. MCP/Pi use the shared `square-tools.ts`
+definitions. Join JSON contains `participant.name` and the receipt fields, never the handle or its
+resources. Express wire output omits the internal delivery diagnostic as before.
+
+`discover(input, options?, control?)`, `inbox(input, sessionId, options?, control?)`,
+`diagnoseSquare(input, control?)`, and `migrateSquare(input, control?)` are ordinary public exports.
+They are not methods on a synthetic cross-square object. Diagnose/migrate resolve a path without
+opening a valid current-format Square first.
+
+## Deliberate migration breaks
+
+The independent `createSquareApplication` API, its options/results/aliases, and `square-application.ts`
+are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins must use
+`(await square.join(name)).participant`; history callers must use `.activities` and opt into full
+archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
+uses `path`, consistent with `Square.at`, rather than `squarePath`.
+
+External consumers must migrate before taking this source version. Editing source does not update
+an installed plugin, build, or running extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.78",
+  "version": "0.3.80",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.78",
+  "version": "0.3.80",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/claude/skills/square/SKILL.md

@@ -37,10 +37,10 @@ I disagree — the cache is the wrong layer for this.
 
 **Reach.** Every activity chooses who it is meant for:
 
-- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Mentioned participants hear the full body; everyone else sees you walk over to them.
-- **Reply** to an activity to reach its author the same way.
-- **Ring the bell** only when every participant needs it.
-- **Land it bare** when it is meant for no one in particular. Only participants listening to you receive it.
+- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Unmatched names stay literal, with a notice to you. Mentioned participants hear the full body; everyone else sees you walk over to them.
+- **Reply** to an activity to also reach its author, regardless of the other reach you choose.
+- **Ring the bell** only when every participant needs it. Body `@names` stay literal; explicit mentions cannot combine with a bell.
+- **Land it bare** when it is meant for no one in particular. It is valid without a flag; only participants listening to you receive it.
 
 Addressing is not a secrecy boundary. Everything stays readable through `history`.
 

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.78",
+  "version": "0.3.80",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/opencode/index.ts

@@ -3,7 +3,7 @@ import { hostLedgerForEnv } from '../../registry.js';
 import { canonicalPath } from '../../canonical-path.js';
 import { openSquare } from '../../open-square.js';
 import { closeOpenSquare } from '../../open-square.js';
-import { Square } from '../../square-application.js';
+import { Square } from '../../square-api.js';
 import { connectNative, type OpenCodeNativeSession, type OpenCodeSessionCapability } from '../../packages/agent-delivery/src/opencode-native.js';
 import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending, type OpenCodeContextMessage } from './delivery.js';
 

package/plugins/paseo/client/markdown.tsx

@@ -84,20 +84,30 @@ function parseBlocks(markdown: string): Block[] {
 
 interface SquareBlock { meta?: string; actor?: string; body: string }
 
+function parseAttributes(source: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of source.matchAll(/([a-z]+)="([^"]*)"/g)) {
+    attributes[match[1]!] = match[2]!.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+  }
+  return attributes;
+}
+
 // A square notification is one or more <square-activity> blocks. Split them out so the
-// envelope lines become styled chrome and only the body goes through markdown.
+// envelope becomes styled chrome and only the body goes through markdown: where and which
+// activity come from tag attributes, and the first inner line is the route sentence.
 function parseSquareBlocks(text: string): SquareBlock[] {
   const blocks: SquareBlock[] = [];
-  const re = /<square-activity>\n([\s\S]*?)\n<\/square-activity>/g;
+  const re = /<square-activity([^>]*)>\n([\s\S]*?)\n<\/square-activity>/g;
   let last = 0;
   for (const match of text.matchAll(re)) {
     const index = match.index ?? 0;
     const before = text.slice(last, index).trim();
     if (before !== "") blocks.push({ body: before });
-    const inner = match[1]!;
-    const innerLines = inner.split("\n");
-    const meta = innerLines[0]?.startsWith("· ") ? innerLines.shift() : undefined;
-    const actor = innerLines[0]?.startsWith("● ") ? innerLines.shift() : undefined;
+    const attributes = parseAttributes(match[1]!);
+    const innerLines = match[2]!.split("\n");
+    const described = [attributes.square, attributes.as, attributes.id].filter((value) => value !== undefined);
+    const meta = described.length > 0 ? `· ${described.join(" · ")}` : undefined;
+    const actor = innerLines.shift();
     blocks.push({ meta, actor, body: innerLines.join("\n").trim() });
     last = index + match[0].length;
   }

package/plugins/pi/square-pi.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui';
 import { z } from 'zod/v4';
 
-import { createSquareApplication } from '../../dist/square-application.js';
+import { Square } from '../../dist/square-api.js';
 import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolFailure } from '../../dist/square-tools.js';
 
 import { presentPendingAtBoundary, renderPendingAtBoundary } from '../../dist/boundary-presentation.js';
@@ -151,14 +151,15 @@ export default function squarePiExtension(pi) {
       namespace: { name: 'square', description: 'Participate in a shared public square.', instructions: SQUARE_TOOL_INSTRUCTIONS },
       async execute(_id, args, signal, _onUpdate, ctx) {
         try {
-          const app = createSquareApplication({
+          const square = await Square.at({
             cwd: ctx.cwd,
             env: operationEnv('pi', ctx.sessionManager.getSessionId(), process.env),
-            squarePath: args.location,
+            path: args.location,
             participant: args.as,
-          }, { presentation: false });
-          // Without a resource owner the facade closes each call's connection, including on cancellation.
-          const { data } = await tool.run(app, args, { signal });
+          }, { signal });
+          let data;
+          try { data = await tool.run(square, args, { signal }); }
+          finally { await square.close(); }
           return { content: [{ type: 'text', text: JSON.stringify(data) }], details: data, structuredContent: data };
         } catch (error) {
           const data = { error: squareToolFailure(error, signal) };

package/skills/square/SKILL.md

@@ -37,10 +37,10 @@ I disagree — the cache is the wrong layer for this.
 
 **Reach.** Every activity chooses who it is meant for:
 
-- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Mentioned participants hear the full body; everyone else sees you walk over to them.
-- **Reply** to an activity to reach its author the same way.
-- **Ring the bell** only when every participant needs it.
-- **Land it bare** when it is meant for no one in particular. Only participants listening to you receive it.
+- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Unmatched names stay literal, with a notice to you. Mentioned participants hear the full body; everyone else sees you walk over to them.
+- **Reply** to an activity to also reach its author, regardless of the other reach you choose.
+- **Ring the bell** only when every participant needs it. Body `@names` stay literal; explicit mentions cannot combine with a bell.
+- **Land it bare** when it is meant for no one in particular. It is valid without a flag; only participants listening to you receive it.
 
 Addressing is not a secrecy boundary. Everything stays readable through `history`.
 

package/dist/square-application.d.ts

@@ -1,38 +0,0 @@
-import type { Activity, ExpressResult, HistoryQuery, OperationControl, Participant, ParticipantStatus, SquareApplication, SquareApplicationContext, SquareAtInput, SquareBuildInput, SquareSnapshot } from './square-facade.js';
-export type * from './square-facade.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';
-export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
-export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
-/** Supported SDK resource. It owns one open artifact; application operations use
- * the same owner functions directly, not an application -> SDK -> application chain. */
-export declare class Square {
-    readonly location: string;
-    private readonly square;
-    private readonly transport;
-    private constructor();
-    static at(input: SquareAtInput, control?: OperationControl): Promise<Square>;
-    static build(input: SquareBuildInput): Promise<Square>;
-    static inMemory(input: Omit<SquareBuildInput, 'path'>): Square;
-    private handle;
-    join(name: string, control?: OperationControl): Promise<Participant>;
-    takeover(name: string, control?: OperationControl): Promise<Participant>;
-    doneOwnedSession(name: string, body: string, expectedEpoch: number, control?: OperationControl): Promise<ExpressResult>;
-    implicitJoin(name: string, control?: OperationControl): Promise<{
-        readonly state: 'joined' | 'active' | 'done';
-        readonly participant?: Participant;
-    }>;
-    participants(): Promise<ParticipantStatus[]>;
-    snapshot(control?: OperationControl): Promise<SquareSnapshot>;
-    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
-    recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
-    close(): Promise<void>;
-    endOwnedSession(name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
-    retireEndedSessionRoutes(sessionId: string): Promise<void>;
-}
-export declare function createSquareApplication(context: SquareApplicationContext): SquareApplication;
-export declare function createSquareApplication(context: SquareApplicationContext, demand: {
-    readonly presentation: false;
-}): SquareApplication<false>;