@astrosheep/square 0.3.106 → 0.4.1

package/dist/square-tools.d.ts

@@ -16,6 +16,14 @@ export declare class SquareExpressDrafts {
     consume(token?: string): void;
     retain(args: JsonObject, owner: Owner | undefined, token: string | undefined, failure: JsonObject, expressAttempted: boolean): string | undefined;
 }
+interface ToolBinding {
+    identity: ToolIdentity;
+    open(location: string | undefined, control: OperationControl): Promise<Square>;
+}
+export declare function createSquareToolRunner(): (tool: ToolDefinition, args: JsonObject, control: OperationControl, bind: () => Promise<ToolBinding> | ToolBinding, defaultLocation?: string) => Promise<{
+    text: string;
+    isError?: true;
+}>;
 interface ToolDefinition {
     name: string;
     description: string;

package/dist/square-tools.js

@@ -45,6 +45,45 @@ export class SquareExpressDrafts {
         return created;
     }
 }
+export function createSquareToolRunner() {
+    const drafts = new SquareExpressDrafts();
+    return async (tool, args, control, bind, defaultLocation) => {
+        let toolArgs = args;
+        let owner;
+        let token;
+        let attempted = false;
+        let square;
+        try {
+            const binding = await bind();
+            owner = binding.identity.owner;
+            if (tool.name === 'express') {
+                const resolved = drafts.resolve(toolArgs, owner);
+                toolArgs = resolved.args;
+                token = resolved.token;
+            }
+            square = await binding.open(toolArgs.location, control);
+            let text;
+            try {
+                attempted = tool.name === 'express';
+                text = await tool.run(square, toolArgs, control, binding.identity);
+                drafts.consume(token);
+            }
+            finally {
+                await square.close();
+            }
+            return { text };
+        }
+        catch (error) {
+            const failure = squareToolFailure(error, control.signal);
+            const draft = tool.name === 'express' ? drafts.retain(toolArgs, owner, token, failure, attempted) : undefined;
+            return { isError: true, text: squareToolFailureText(failure, {
+                    location: square?.location ?? toolArgs.location ?? defaultLocation,
+                    participant: typeof toolArgs.as === 'string' ? toolArgs.as : undefined,
+                    draft,
+                }) };
+        }
+    };
+}
 const location = z.string().optional().describe('Which square: a .square file path. Relative paths start from the working directory. Leave it out for the configured square.');
 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]*)$/);

package/dist/square-values.d.ts

@@ -0,0 +1,27 @@
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
+export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type MessageMetadata = Readonly<Record<string, JsonValue>>;
+export declare const MESSAGE_METADATA_MAX_BYTES: number;
+export declare const MESSAGE_METADATA_MAX_DEPTH = 256;
+/** Validate the bounded, lossless JSON object carried by a message. */
+export declare function validateMessageMetadata(value: unknown): MessageMetadata | undefined;
+export declare function messageMetadataHasContent(metadata: MessageMetadata | undefined): boolean;
+export interface WakeAddress {
+    readonly kind: WakeRouteKind;
+    readonly address: Readonly<Record<string, string>>;
+}
+export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
+export interface WakeRoute {
+    epoch?: number;
+    location: string;
+    participant: string;
+    kind: WakeRouteKind;
+    address: Record<string, string>;
+    updatedAt: number;
+}
+export declare function sameName(a: string, b: string): boolean;
+export declare const NAME_GRAPHEME_SOURCE: string;
+export declare function validateName(name: string): void;

package/dist/square-values.js

@@ -0,0 +1,90 @@
+import { SquareError, nameKey } from './neutral.js';
+export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
+export const MESSAGE_METADATA_MAX_BYTES = 16 * 1024;
+export const MESSAGE_METADATA_MAX_DEPTH = 256;
+/** Validate the bounded, lossless JSON object carried by a message. */
+export function validateMessageMetadata(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new SquareError('invalid_args', 'Activity metadata must be a non-null JSON object.');
+    const visiting = new Set();
+    const stack = [{ value, depth: 0 }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.exit !== undefined) {
+            visiting.delete(frame.exit);
+            continue;
+        }
+        const item = frame.value;
+        if (item === null || typeof item === 'boolean' || typeof item === 'string')
+            continue;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                throw new SquareError('invalid_args', 'Activity metadata must contain only finite JSON values.');
+            continue;
+        }
+        if (typeof item !== 'object')
+            throw new SquareError('invalid_args', 'Activity metadata must contain only JSON values.');
+        if (frame.depth > MESSAGE_METADATA_MAX_DEPTH)
+            throw new SquareError('invalid_args', `Activity metadata nesting cannot exceed ${MESSAGE_METADATA_MAX_DEPTH} levels.`);
+        if (visiting.has(item))
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain a cycle.');
+        visiting.add(item);
+        stack.push({ value: item, depth: frame.depth, exit: item });
+        if (Array.isArray(item)) {
+            if (Object.getOwnPropertySymbols(item).length > 0 || Object.keys(item).length !== item.length)
+                throw new SquareError('invalid_args', 'Activity metadata arrays must be dense JSON arrays.');
+            const names = Object.getOwnPropertyNames(item);
+            if (names.some(name => name !== 'length' && (!/^(0|[1-9]\d*)$/.test(name) || Number(name) >= item.length)))
+                throw new SquareError('invalid_args', 'Activity metadata arrays must contain only indexed values.');
+            for (const key of Object.keys(item).reverse()) {
+                const descriptor = Object.getOwnPropertyDescriptor(item, key);
+                if (descriptor === undefined || !('value' in descriptor))
+                    throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
+                stack.push({ value: descriptor.value, depth: frame.depth + 1 });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(item);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new SquareError('invalid_args', 'Activity metadata must contain only plain JSON objects.');
+        if (Object.getOwnPropertySymbols(item).length > 0)
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain symbol keys.');
+        const names = Object.getOwnPropertyNames(item);
+        if (names.some(name => !Object.prototype.propertyIsEnumerable.call(item, name)))
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain non-enumerable properties.');
+        for (const name of names.reverse()) {
+            const descriptor = Object.getOwnPropertyDescriptor(item, name);
+            if (!('value' in descriptor))
+                throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
+            stack.push({ value: descriptor.value, depth: frame.depth + 1 });
+        }
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new SquareError('invalid_args', 'Activity metadata must contain only lossless JSON values.');
+    }
+    if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > MESSAGE_METADATA_MAX_BYTES)
+        throw new SquareError('invalid_args', `Activity metadata cannot exceed ${MESSAGE_METADATA_MAX_BYTES} UTF-8 bytes.`);
+    return value;
+}
+export function messageMetadataHasContent(metadata) {
+    return metadata !== undefined && Object.keys(metadata).length > 0;
+}
+export function isWakeRouteKind(value) {
+    return typeof value === 'string' && WAKE_ROUTE_KINDS.includes(value);
+}
+export function sameName(a, b) { return nameKey(a) === nameKey(b); }
+const TEXT_NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]`;
+export const NAME_GRAPHEME_SOURCE = String.raw `${TEXT_NAME_GRAPHEME_SOURCE}|\p{RGI_Emoji}`;
+const TEXT_NAME_PATTERN = new RegExp(`^(?:${TEXT_NAME_GRAPHEME_SOURCE})+(?:/(?:${TEXT_NAME_GRAPHEME_SOURCE})+)*$`, 'v');
+const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
+export function validateName(name) {
+    if (!name || (!TEXT_NAME_PATTERN.test(name) && !NAME_PATTERN.test(name))) {
+        throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
+    }
+}

package/dist/views.d.ts

@@ -1,19 +1,19 @@
 import { type ActivityId } from './square-core.js';
-import { type StoredAct } from './model.js';
+import { type HydratedAct } from './model.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
 import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
 export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignore", "unlisten"];
-/** The one StoredAct-to-public-Activity field mapping. Rejects read bookkeeping. */
-export declare function toPublicActivity(stored: StoredAct): Activity;
-export declare function toPerceivedActivity(facts: SquareRead, stored: StoredAct, viewer: string): PerceivedActivity;
+/** The one stored-to-public Activity field mapping. Rejects read bookkeeping. */
+export declare function toPublicActivity(stored: HydratedAct): Activity;
+export declare function toPerceivedActivity(facts: SquareRead, stored: HydratedAct, viewer: string): PerceivedActivity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** History adds archive context and ordering to the shared storage-side query predicates. */
 export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
-    activities: StoredAct[];
-    visibleActivities: StoredAct[];
+    activities: import("./model.js").StoredAct[];
+    visibleActivities: import("./model.js").StoredAct[];
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];

package/dist/views.js

@@ -11,15 +11,14 @@ const STATUS_HERE_WINDOW_MS = 30 * 60_000;
 const PRESENCE_WINDOW_MS = 8 * 60 * 60_000;
 export const NON_READ = ['join', 'done', 'say', 'listen', 'ignore', 'unlisten'];
 const ARCHIVE = new Set(['join', 'done', 'say']);
-/** The one StoredAct-to-public-Activity field mapping. Rejects read bookkeeping. */
+/** The one stored-to-public Activity field mapping. Rejects read bookkeeping. */
 export function toPublicActivity(stored) {
     if (stored.kind === 'read')
         throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
     return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
-        ...(stored.kind === 'say' && stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
-        ...(stored.kind === 'say' && stored.delivery !== undefined ? { delivery: stored.delivery } : {}),
+        ...('metadata' in stored && 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) } : {}) };
 }
@@ -144,7 +143,10 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
     const header = facts.header(), standingCount = inSquareCount(facts);
     const listener = participants.find((p) => p.presence !== 'never-joined' && nameKey(p.name) === nameKey(viewer));
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
-    const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
+    const joinHeads = observe ? facts.activityHeads({ kinds: ['join'], afterIndex: latest?.index ?? -1 }, { edge: 'newest', limit: 3 }).items : [];
+    const indexes = [...new Set([...(latest === undefined ? [] : [latest.index]), ...joinHeads.map(head => head.index)])];
+    const hydrated = new Map(facts.activities(indexes).map(activity => [activity.index, activity]));
+    const latestAct = latest === undefined ? undefined : hydrated.get(latest.index);
     const data = {
         hardCap: header.hardCap,
         ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
@@ -155,10 +157,13 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
     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) => ({
-        rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0,
-        activity: toPublicActivity(activity)
-    }));
+    const joins = joinHeads.flatMap(head => {
+        const activity = hydrated.get(head.index);
+        return activity === undefined ? [] : [{
+                rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0,
+                activity: toPublicActivity(activity)
+            }];
+    });
     const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
         ...data,
@@ -190,7 +195,7 @@ export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipi
         throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
     const heads = last === 0 ? [] : recipient === undefined
         ? facts.activityHeads({ kinds: NON_READ }, { edge: 'newest', limit: last }).items
-        : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+        : facts.directed(recipient, { kinds: ['say'] }, { edge: 'newest', limit: last }).items;
     const activities = facts.activities(heads.map((head) => head.index)).map((activity) => recipient === undefined
         ? toPublicActivity(activity) : toPerceivedActivity(facts, activity, recipient));
     return { activities, cursor: facts.header().lastActIndex, hasMore: false };

package/dist/wake-sink.d.ts

@@ -1,18 +1,11 @@
-/** One Paseo wake attempt: where it goes, what it says, and what identifies it. */
 export interface PaseoWakeRequest {
     agentId: string;
     prompt: string;
-    location: string;
-    participant: string;
-    activity: string;
-    attemptN?: number;
+    messageId: string;
 }
-/**
- * The daemon's own dedup key for one attempt. Every retry of the same attempt
- * derives the same id; a later attempt of the same attention derives a new one.
- */
-export declare function paseoWakeMessageId(request: Pick<PaseoWakeRequest, 'location' | 'participant' | 'activity' | 'attemptN'>): string;
-/** Steer one existing Paseo agent through the shared delivery entry. Never interrupts a turn. */
+/** Steer one existing Paseo agent, without interrupting its turn. */
 export declare function sendPaseoWake(request: PaseoWakeRequest, opts?: {
     timeoutMs?: number;
+    beforeSend?: () => Promise<boolean>;
+    signal?: AbortSignal;
 }): Promise<void>;

package/dist/wake-sink.js

@@ -1,37 +1,13 @@
-import { createHash } from 'node:crypto';
 import { DeliveryError, connect } from './packages/agent-delivery/src/index.js';
-/**
- * The daemon's own dedup key for one attempt. Every retry of the same attempt
- * derives the same id; a later attempt of the same attention derives a new one.
- */
-export function paseoWakeMessageId(request) {
-    const digest = createHash('sha256')
-        .update([request.location, request.participant, request.activity, request.attemptN ?? 0].join('|'))
-        .digest('hex');
-    return `square-${digest.slice(0, 32)}`;
-}
-/** Steer one existing Paseo agent through the shared delivery entry. Never interrupts a turn. */
+/** Steer one existing Paseo agent, without interrupting its turn. */
 export async function sendPaseoWake(request, opts = {}) {
-    const budgetMs = opts.timeoutMs;
-    // A usable budget becomes one deadline both phases share; anything else is an
-    // argument error, so it is handed to the entry untouched to classify.
-    const bounded = budgetMs !== undefined && Number.isFinite(budgetMs) && budgetMs > 0;
-    const deadline = bounded ? Date.now() + budgetMs : 0;
-    // An elapsed budget never reached the daemon, so it is the shared entry's own
-    // "unavailable" failure rather than a send error of its own.
-    const connectMs = bounded ? Math.max(0, deadline - Date.now()) : budgetMs;
-    if (bounded && connectMs === 0)
+    const budget = opts.timeoutMs;
+    const deadline = budget === undefined ? undefined : Date.now() + budget;
+    if (deadline !== undefined && (!Number.isFinite(budget) || budget <= 0))
         throw new DeliveryError('unavailable');
-    const agent = await connect({
-        harness: 'paseo',
-        agentId: request.agentId,
-        ...(connectMs === undefined ? {} : { timeoutMs: connectMs }),
-    });
-    const steerMs = bounded ? Math.max(0, deadline - Date.now()) : budgetMs;
-    if (bounded && steerMs === 0)
+    const agent = await connect({ harness: 'paseo', agentId: request.agentId, ...(budget === undefined ? {} : { timeoutMs: budget }), signal: opts.signal });
+    if (opts.signal?.aborted || (deadline !== undefined && Date.now() >= deadline))
         throw new DeliveryError('unavailable');
-    await agent.steer(request.prompt, {
-        id: paseoWakeMessageId(request),
-        ...(steerMs === undefined ? {} : { timeoutMs: steerMs }),
-    });
+    const remaining = deadline === undefined ? undefined : deadline - Date.now();
+    await agent.steer(request.prompt, { id: request.messageId, ...(remaining === undefined ? {} : { timeoutMs: remaining }), signal: opts.signal, beforeSend: opts.beforeSend });
 }

package/dist/wake-transports.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryTransport } from './delivery-ledger.js';
+export type WakeTransports = readonly DeliveryTransport[];
+/** Concrete transports share no producer-specific state. */
+export declare function createDefaultDeliveryTransports(env?: NodeJS.ProcessEnv): Promise<WakeTransports>;

package/dist/wake-transports.js

@@ -0,0 +1,11 @@
+/** Concrete transports share no producer-specific state. */
+export async function createDefaultDeliveryTransports(env = process.env) {
+    const { createClaudeWakeTransport } = await import('./claude-transport.js');
+    const { HttpWakeTransport } = await import('./http-delivery.js');
+    const transports = [createClaudeWakeTransport(env), new HttpWakeTransport({ env })];
+    if (env.SQUARE_DISABLE_PASEO_WAKE !== '1') {
+        const { PaseoWakeTransport } = await import('./paseo-delivery.js');
+        transports.push(new PaseoWakeTransport());
+    }
+    return transports;
+}

package/examples/symmetric-domains.mjs

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