@astrosheep/square 0.4.0 → 0.4.1

package/dist/plugins/opencode-v1/runtime.js

@@ -0,0 +1,152 @@
+import { canonicalPath } from '../../canonical-path.js';
+import { cancelOpenCodeDeliveries, currentOpenCodeGeneration, detachOpenCodeSession, endOpenCodeSession, listOpenCodeSessions, observeOpenCodeContext, observeOpenCodeSessions, publishOpenCodeAddress, receiveOpenCodePending } from '../opencode-shared/delivery.js';
+import { legacyTransport } from './transport.js';
+export async function startReceiver(ctx) {
+    const env = { ...process.env };
+    const directory = await canonicalPath(ctx.directory);
+    const discovery = await observeOpenCodeSessions(env);
+    const lifetime = new AbortController();
+    const receivers = new Map();
+    const terminal = new Set();
+    const interrupting = new Set();
+    const cancellationFailed = new Set();
+    let coordinating = Promise.resolve();
+    const coordinate = (operation) => {
+        coordinating = coordinating.then(() => lifetime.signal.aborted ? undefined : operation()).catch(() => { });
+        return coordinating;
+    };
+    const stop = (id) => {
+        const receiver = receivers.get(id);
+        receiver?.abort.abort();
+        receivers.delete(id);
+        return receiver?.running;
+    };
+    const validate = async (id) => {
+        const result = await ctx.client.session.get({ path: { id }, signal: lifetime.signal }).catch(() => undefined);
+        const info = result?.data;
+        return !result?.error && info?.id === id && info.projectID === ctx.project.id && typeof info.directory === 'string'
+            && await canonicalPath(info.directory) === directory;
+    };
+    const reconcile = async (active) => {
+        const candidates = new Set(await listOpenCodeSessions(env));
+        if (active)
+            candidates.add(active);
+        for (const id of candidates) {
+            if (lifetime.signal.aborted)
+                return;
+            if (interrupting.has(id) || cancellationFailed.has(id))
+                continue;
+            if (terminal.has(id) || !await validate(id) || terminal.has(id)) {
+                const receiver = receivers.get(id);
+                stop(id);
+                if (receiver)
+                    await detachOpenCodeSession(id, receiver.generation, env);
+                continue;
+            }
+            const existing = receivers.get(id);
+            if (existing?.settled === false || interrupting.has(id))
+                continue;
+            const generation = existing?.generation ?? await publishOpenCodeAddress(id, env, lifetime.signal);
+            if (!generation) {
+                stop(id);
+                continue;
+            }
+            if (terminal.has(id) || interrupting.has(id) || lifetime.signal.aborted) {
+                await detachOpenCodeSession(id, generation, env);
+                continue;
+            }
+            const abort = new AbortController();
+            const signal = AbortSignal.any([lifetime.signal, abort.signal]);
+            const receiver = { abort, generation, settled: false, running: receiveOpenCodePending(id, generation, legacyTransport(ctx.client, id, signal), env, signal).catch(() => { }).finally(() => { receiver.settled = true; }) };
+            receivers.set(id, receiver);
+        }
+        for (const id of receivers.keys())
+            if (!candidates.has(id))
+                stop(id);
+    };
+    const loop = (async () => {
+        while (!lifetime.signal.aborted) {
+            const baseline = discovery.observer.generation;
+            await coordinate(() => reconcile());
+            await discovery.observer.hinted(baseline, 2000, lifetime.signal);
+        }
+    })().catch(() => { });
+    let disposal;
+    return {
+        'experimental.chat.messages.transform': async (_input, output) => {
+            const ids = new Set(output.messages.map(message => message.info?.sessionID));
+            if (ids.size !== 1 || typeof [...ids][0] !== 'string')
+                return;
+            const id = [...ids][0];
+            if (terminal.has(id))
+                return;
+            await coordinate(() => reconcile(id));
+            const receiver = receivers.get(id);
+            if (!receiver || terminal.has(id) || lifetime.signal.aborted)
+                return;
+            const messages = output.messages.flatMap(({ info, parts }) => {
+                if (info?.role !== 'user' || !info.id || !parts?.length || !parts.every(part => part.type === 'text'
+                    && typeof part.text === 'string' && part.sessionID === id && part.messageID === info.id && !part.synthetic && !part.ignored))
+                    return [];
+                return [{ id: info.id, role: 'user', content: parts.map(part => ({ type: 'text', text: part.text })) }];
+            });
+            await observeOpenCodeContext(id, receiver.generation, messages, env, AbortSignal.any([lifetime.signal, receiver.abort.signal])).catch(() => { });
+        },
+        event: async ({ event }) => {
+            const interrupted = event.type === 'session.error' && event.properties?.error?.name === 'MessageAbortedError'
+                ? event.properties.sessionID : undefined;
+            if (interrupted) {
+                const receiver = receivers.get(interrupted);
+                if (!receiver || interrupting.has(interrupted))
+                    return;
+                interrupting.add(interrupted);
+                stop(interrupted);
+                await coordinate(async () => {
+                    try {
+                        await receiver.running;
+                        if (!await cancelOpenCodeDeliveries(interrupted, receiver.generation, env))
+                            throw new Error('OpenCode cancellation fence lost');
+                    }
+                    catch (error) {
+                        cancellationFailed.add(interrupted);
+                        await detachOpenCodeSession(interrupted, receiver.generation, env).catch(() => { });
+                        throw error;
+                    }
+                    finally {
+                        interrupting.delete(interrupted);
+                    }
+                    await reconcile(interrupted);
+                });
+                return;
+            }
+            const info = event.properties?.info;
+            if (event.type !== 'session.deleted' || !info?.id || info.projectID !== ctx.project.id || typeof info.directory !== 'string'
+                || await canonicalPath(info.directory).catch(() => undefined) !== directory)
+                return;
+            const id = info.id;
+            terminal.add(id);
+            const receiver = receivers.get(id);
+            stop(id);
+            await coordinate(async () => {
+                const generation = receiver?.generation ?? await currentOpenCodeGeneration(id, env);
+                if (generation)
+                    await endOpenCodeSession(id, generation, env);
+            });
+        },
+        dispose: () => disposal ??= (async () => {
+            lifetime.abort();
+            const captured = [...receivers.entries()];
+            const tasks = [loop, coordinating, ...captured.map(([id]) => stop(id))];
+            let timer;
+            try {
+                await Promise.race([Promise.allSettled(tasks), new Promise(resolve => { timer = setTimeout(resolve, 3000); })]);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+            await Promise.allSettled(captured.map(([id, receiver]) => detachOpenCodeSession(id, receiver.generation, env)));
+            await discovery.close();
+        })(),
+    };
+}

package/dist/plugins/opencode-v1/transport.d.ts

@@ -0,0 +1,13 @@
+import type { DeliveryTransport } from '../../delivery-ledger.js';
+type Client = {
+    session: {
+        promptAsync(input: unknown): Promise<{
+            error?: unknown;
+            response?: Response;
+        }>;
+    };
+};
+/** OpenCode's 48-bit timestamp/counter prefix followed by 14 random base62 digits. */
+export declare function nativeMessageId(): string;
+export declare function legacyTransport(client: Client, sessionId: string, lifetime: AbortSignal): DeliveryTransport;
+export {};

package/dist/plugins/opencode-v1/transport.js

@@ -0,0 +1,50 @@
+import { randomInt, createHash } from 'node:crypto';
+import { renderDeliveryReminder } from '../../delivery-frame.js';
+let lastTime = 0, counter = 0;
+const alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** OpenCode's 48-bit timestamp/counter prefix followed by 14 random base62 digits. */
+export function nativeMessageId() {
+    const now = Math.max(Date.now(), lastTime);
+    counter = now === lastTime ? counter + 1 : 0;
+    if (counter >= 0x1000) {
+        lastTime = now + 1;
+        counter = 0;
+    }
+    else
+        lastTime = now;
+    const prefix = (BigInt(lastTime) * 0x1000n + BigInt(counter)).toString(16).slice(-12).padStart(12, '0');
+    return `msg_${prefix}${Array.from({ length: 14 }, () => alphabet[randomInt(62)]).join('')}`;
+}
+export function legacyTransport(client, sessionId, lifetime) {
+    return {
+        kind: 'opencode-server',
+        async send(card, address, context) {
+            const signal = AbortSignal.any([lifetime, context.signal]);
+            if (address.sessionId !== sessionId || signal.aborted)
+                return 'not-capable';
+            const messageId = nativeMessageId();
+            const text = renderDeliveryReminder([card.text], { tagged: true });
+            const payloadHash = createHash('sha256').update(text).digest('hex');
+            if (!await context.prepare({ token: context.token, messageId, payloadHash }) || signal.aborted
+                || !await context.beforeSend() || signal.aborted || Date.now() >= context.deadline)
+                return 'not-capable';
+            let onAbort;
+            try {
+                await Promise.race([
+                    client.session.promptAsync({ path: { id: sessionId }, body: { messageID: messageId, parts: [{ type: 'text', text }] }, signal }),
+                    new Promise((_, reject) => { onAbort = () => reject(signal.reason); signal.addEventListener('abort', onAbort, { once: true }); if (signal.aborted)
+                        onAbort(); }),
+                ]);
+                // promptAsync acknowledges only submission, not native acceptance or presentation.
+                return 'unknown';
+            }
+            catch {
+                return 'unknown';
+            }
+            finally {
+                if (onAbort)
+                    signal.removeEventListener('abort', onAbort);
+            }
+        },
+    };
+}

package/dist/plugins/paseo/shared/card-presentation.d.ts

@@ -0,0 +1,10 @@
+/** Producer-neutral display facts; independent of model-facing delivery text. */
+export type CardPresentation = {
+    readonly kind: 'presentation';
+    readonly origin: string;
+    readonly author?: string;
+    readonly ref?: string;
+    readonly badge?: string;
+    readonly body: string;
+};
+export declare function isCardPresentation(value: unknown): value is CardPresentation;

package/dist/plugins/paseo/shared/card-presentation.js

@@ -0,0 +1,7 @@
+export function isCardPresentation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const item = value;
+    return item.kind === 'presentation' && typeof item.origin === 'string' && typeof item.body === 'string'
+        && ['author', 'ref', 'badge'].every(key => item[key] === undefined || typeof item[key] === 'string');
+}

package/dist/ports.d.ts

@@ -1,10 +1,9 @@
-import type { ActDraft, HydratedAct, SayRelation, Owner, HardCap, Seat, StoredAct, WakeAddress, WatchLease } from './model.js';
+import type { ActDraft, HydratedAct, Owner, HardCap, Seat, StoredAct, WakeAddress, WatchLease, DirectedNotificationRoute } from './model.js';
 import type { ActivitySearch } from './square-facade.js';
 import type { IndexPage, FactPage } from './neutral.js';
-export type { WakeTransportPort, WakePresentation, WakeProjectionContext, WakeProjection, WakeRequest, WakeOutcome } from './channel-transport.js';
+import type { MetadataMatch } from './delivery-deferral.js';
+import type { ProducerRead, ProducerWrite } from './square-post.js';
 export type { IndexPage, FactPage } from './neutral.js';
-import type { ChannelRead, ChannelWrite, ChannelWriteAuthority, ChannelDeliveryEvidence, ChannelDeliveryClaimInput, ChannelDeliveryClaimResult, ChannelDeliveryPreparation, ChannelDeliveryCompletion, MessageId, EndpointGeneration } from './channel-ports.js';
-export type { ChannelArtifact, ChannelRead, ChannelWrite, ChannelWriteAuthority, ChannelHeader, MessageFact, MessageAddressFact, MessageHead, MessageFilter, MessageDraft, EndpointFact, EndpointRef, ReceiveClaimFact, ChannelDeliveryEvidence, ChannelDeliveryClaimInput, ChannelDeliveryClaimResult, ChannelDeliveryPreparation, ChannelDeliveryCompletion } from './channel-ports.js';
 export type ActivityIndex = number;
 export interface SquareHeader {
     readonly revision: number;
@@ -43,7 +42,6 @@ export interface ActivityHead {
     readonly actor: string;
     readonly reach?: 'bell';
     readonly reply?: ActivityIndex;
-    readonly messageIndex?: number;
 }
 export interface ActivityFilter {
     readonly afterIndex?: number;
@@ -54,11 +52,9 @@ export interface ActivityFilter {
     readonly actors?: readonly string[];
     readonly actorMatch?: 'identity' | 'exact';
     readonly afterAt?: number;
-    /** Shared query predicates, applied before paging or counting. */
-    readonly metadataMatch?: import('./delivery-deferral.js').MetadataMatch;
+    readonly metadataMatch?: MetadataMatch;
     readonly search?: ActivitySearch;
 }
-/** Upper attention filter over its own landed reasons and lower message addresses. */
 export interface DirectedFilter extends Omit<ActivityFilter, 'actors' | 'actorMatch'> {
     readonly unseenOnly?: true;
     readonly currentGeneration?: true;
@@ -70,21 +66,24 @@ export interface DirectedHead {
     readonly at: number;
     readonly actor: string;
     readonly recipient: string;
-    readonly route: import('./model.js').DirectedNotificationRoute;
-    readonly messageIndex: number;
-    readonly generation?: EndpointGeneration;
+    readonly route: DirectedNotificationRoute;
+    readonly generation?: string;
 }
 export interface LandedRecipient {
     readonly recipient: string;
-    readonly route: import('./model.js').DirectedNotificationRoute;
-    readonly generation?: EndpointGeneration;
+    readonly route: DirectedNotificationRoute;
+    readonly generation?: string;
+    readonly owner?: Owner;
 }
 export interface ReceiptFacts {
     readonly latestAt?: number;
     readonly latestActorActivityIndex?: number;
 }
 export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
-export type ArtifactWriteAuthority = ChannelWriteAuthority | {
+export type ArtifactWriteAuthority = {
+    readonly kind: 'participant';
+    readonly seat: SeatRef;
+} | {
     readonly kind: 'host-cleanup';
     readonly seat: SeatRef;
 } | {
@@ -96,34 +95,26 @@ export type ArtifactWriteAuthority = ChannelWriteAuthority | {
     readonly kind: 'takeover';
     readonly participant: string;
     readonly owner: Owner;
-    readonly expectedGeneration: EndpointGeneration;
+    readonly expectedGeneration: string;
     readonly wakeAddress?: WakeAddress;
+} | {
+    readonly kind: 'producer';
+} | {
+    readonly kind: 'send';
+    readonly actor: string;
 };
-export type DeliveryEvidence = ChannelDeliveryEvidence;
-export type DeliveryClaimInput = ChannelDeliveryClaimInput;
-export type DeliveryClaimResult = ChannelDeliveryClaimResult;
-export type DeliveryPreparation = ChannelDeliveryPreparation;
-export type DeliveryCompletion = ChannelDeliveryCompletion;
-export type { MessageId, EndpointGeneration };
-/** Domain facts exist only during a synchronous artifact callback. Values are detached. */
-export interface SquareRead {
-    /** Lower Channel facts. Upper layers may use them; Channel never sees this composite. */
-    readonly channel: ChannelRead;
-    seat(requestedName: string): Seat | undefined;
+/** All callbacks are synchronous and their facts cannot escape the transaction. */
+export interface SquareRead extends ProducerRead {
+    seat(name: string): Seat | undefined;
     seatsForOwner(owner: Owner): readonly Seat[];
-    deliveryEvidence(participant: string, generation: EndpointGeneration, message?: MessageId): readonly DeliveryEvidence[];
-    deliveryByToken(claimToken: string): DeliveryEvidence | undefined;
-    cancelledThrough(participant: string, generation: EndpointGeneration): number | undefined;
     header(): SquareHeader;
-    participant(requestedName: string): ParticipantFact | undefined;
+    participant(name: string): ParticipantFact | undefined;
     participantCounts(): ParticipantCounts;
     roster(): readonly ParticipantFact[];
     attention(listener: string): readonly AttentionFact[];
     incomingAttention(sender: string): readonly AttentionFact[];
     activity(index: ActivityIndex): StoredAct | undefined;
-    activityByMessage(messageIndex: number): SayRelation | undefined;
     activityHeads(filter: ActivityFilter, page: IndexPage): FactPage<ActivityHead>;
-    /** The explicit content projection: each say resolved against its Channel message in one read. */
     activities(indexes: readonly ActivityIndex[]): readonly HydratedAct[];
     activityCount(filter: ActivityFilter): number;
     contextIndexes(centers: readonly ActivityIndex[], before: number, after: number): readonly ActivityIndex[];
@@ -133,24 +124,18 @@ export interface SquareRead {
     directed(recipient: string, filter: DirectedFilter, page: IndexPage): FactPage<DirectedHead>;
     directedAt(recipient: string, index: ActivityIndex): DirectedHead | undefined;
     directedCount(recipient: string, filter: DirectedFilter): number;
-    receipt(requestedName: string, index: ActivityIndex): {
+    receipt(name: string, index: ActivityIndex): {
         readonly at: number;
     } | undefined;
-    receiptFacts(requestedName: string, afterIndex: number): ReceiptFacts;
-    lease(requestedName: string): WatchLease | undefined;
-    deliveryDeferrals(participant: string, generation: EndpointGeneration): readonly import('./delivery-deferral.js').DeliveryDeferralFact[];
+    receiptFacts(name: string, afterIndex: number): ReceiptFacts;
+    lease(name: string): WatchLease | undefined;
 }
-export interface SquareWrite extends SquareRead {
-    readonly channel: ChannelWrite;
+export interface SquareWrite extends SquareRead, ProducerWrite {
     land(draft: ActDraft): StoredAct;
-    updateWakeAddress(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
-    /** Join authority only; preserves membership and its establishing generation. */
-    reattachSeat(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
-    /** Host-cleanup authority only; stale/already-detached coordinates are a no-op. */
-    detachSeat(seat: SeatRef): boolean;
-    /** Upper catch claim: the lease plus the message coverage it currently owns. */
-    putLease(requestedName: string, lease: WatchLease, generation?: EndpointGeneration, suppressed?: readonly number[]): boolean;
-    removeLease(requestedName: string, expectedLeaseId: string, generation?: EndpointGeneration): boolean;
+    putLease(name: string, lease: WatchLease, generation?: string): boolean;
+    removeLease(name: string, expectedLeaseId: string, generation?: string): boolean;
+    markSeen(recipient: string, indexes: readonly number[], at: number): number;
+    setSeatAttachment(seat: SeatRef, attachment: 'attached' | 'detached'): boolean;
 }
 export interface SquareReadResult<R> {
     readonly value: R;
@@ -159,60 +144,16 @@ export interface SquareReadResult<R> {
 export interface SquareCommitResult<R> extends SquareReadResult<R> {
     readonly changed: boolean;
 }
-/** Atomic artifact access; no framing, SQL or lazy transaction capability escapes. */
 export interface SquareArtifactPort {
     read<R>(select: (facts: SquareRead) => R, signal?: AbortSignal): Promise<SquareReadResult<R>>;
-    /** Participant/domain writes must carry an explicit owner; no owner-less mutation path exists. */
     transactAs<R>(authority: ArtifactWriteAuthority, change: (facts: SquareWrite) => R, signal?: AbortSignal): Promise<SquareCommitResult<R>>;
-    /** Bounded cleanup/evidence settlement on this same connection after custody was acquired.
-     * Independent of request/lifetime cancellation; explicit close and authority fences still apply. */
     settleAs<R>(authority: ArtifactWriteAuthority, change: (facts: SquareWrite) => R): Promise<SquareCommitResult<R>>;
     revision(signal?: AbortSignal): Promise<number>;
     deliveryRevision(signal?: AbortSignal): Promise<number>;
-    claimDelivery(input: DeliveryClaimInput, signal?: AbortSignal): Promise<DeliveryClaimResult>;
-    prepareDelivery(input: DeliveryPreparation, signal?: AbortSignal): Promise<boolean>;
-    completeDelivery(input: DeliveryCompletion, signal?: AbortSignal): Promise<boolean>;
-    /** Persist suppression through a fixed message, or atomically capture the current artifact head. */
-    cancelDeliveries(seat: SeatRef, through?: number, signal?: AbortSignal): Promise<boolean>;
     changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
-/** Explicit lifetime for an artifact connection reused by a long-lived caller.
- * Only the connection is shared: every open still derives its own environment,
- * clock, ledger and transport, and no request signal becomes a connection lifetime.
- * The owner holds one location and refuses a second rather than sharing the wrong
- * square; the caller lends the connection and never closes it. */
 export interface SquareResourceOwner {
-    /** The shared connection for a location. Never close it; the owner does. */
     artifact(location: string): SquareArtifactPort;
     close(): Promise<void>;
 }
-/** Executor-neutral presentation capability; intentionally separate from wake transport. */
-export interface PresentationSinkPort {
-    present(message: MessageFact): void | Promise<void>;
-}
-export interface PresentationResult {
-    readonly presented: boolean;
-    readonly message?: MessageFact;
-}
-export interface PresentPendingInput {
-    readonly artifact: SquareArtifactPort;
-    readonly location: string;
-    readonly participant: string;
-    readonly message: string | number;
-    readonly sink: PresentationSinkPort;
-    /** Existing wake observed by a native receiver; the sink must not inject content. */
-    readonly observationOf?: string;
-    /** Captured artifact seat; used to fence both presentation and consumption. */
-    readonly seat?: SeatRef;
-    readonly generation?: EndpointGeneration;
-    readonly now?: number;
-    readonly timeoutMs?: number;
-    /** Pre-effect work control only; successful sink evidence settles independently, with a bounded lifetime. */
-    readonly signal?: AbortSignal;
-    /** Boundary previews that were clipped remain pending for a later full presentation. */
-    readonly markSeen?: boolean;
-    /** Receiver-specific pre-effect eligibility, never a veto of an already successful sink. */
-    readonly current?: (facts: SquareRead) => boolean;
-}
-import type { MessageFact } from './channel-ports.js';

package/dist/session-lifecycle.d.ts

@@ -1,7 +1,8 @@
-import { type Owner } from './owner.js';
-import type { AutomaticProvider } from './participant-identity.js';
-import type { WakeAddress } from './model.js';
-/** Host shutdown suspends execution, not membership. Discovery never grants custody. */
-export declare function detachSessionSeats(provider: AutomaticProvider, sessionId: string, env?: NodeJS.ProcessEnv): Promise<void>;
-/** Restore only detached, standing seats of this exact owner before starting a receiver. */
-export declare function restoreSessionSeats(owner: Owner, env?: NodeJS.ProcessEnv, wakeAddress?: WakeAddress, signal?: AbortSignal): Promise<void>;
+import { type DeliveryRoute, type DeliverySession } from './delivery-ledger.js';
+import type { Owner } from './owner.js';
+/** Rotate the captured session generation; omitted routes retain its registrations. */
+export declare function attachDeliverySession(owner: Owner, env?: NodeJS.ProcessEnv, routes?: readonly DeliveryRoute[], signal?: AbortSignal): Promise<DeliverySession | false>;
+/** Replace the supplied route kinds while preserving every other registered route. */
+export declare function attachDeliverySessionRoutes(owner: Owner, env: NodeJS.ProcessEnv | undefined, routes: readonly DeliveryRoute[], signal?: AbortSignal): Promise<DeliverySession | false>;
+export declare function detachDeliverySession(owner: Owner, generation: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+export declare function markDeliverySessionDeleted(owner: Owner, generation: string, env?: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/session-lifecycle.js

@@ -1,47 +1,45 @@
-import { Square } from './square-api.js';
-import { harnessOwner } from './owner.js';
-import { projectSessionCandidates, projectSessionSeats } from './inbox.js';
-function ownerFor(provider, sessionId) {
-    return harnessOwner({ channel: provider === 'claude' ? 'claude-code' : provider, session: sessionId });
+import { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+function openLedger(env) {
+    return DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
 }
-/** Host shutdown suspends execution, not membership. Discovery never grants custody. */
-export async function detachSessionSeats(provider, sessionId, env = process.env) {
-    const owner = ownerFor(provider, sessionId);
-    for (const { location, seat } of await projectSessionSeats({ owner, env })) {
-        let square;
-        try {
-            square = await Square.at({ path: location, env });
-            await square.detach(seat.participant, { owner, generation: seat.generation });
-        }
-        catch { /* One unavailable or replaced seat must not block cleanup of the others. */ }
-        finally {
-            await square?.close();
-        }
-    }
+/** Rotate the captured session generation; omitted routes retain its registrations. */
+export async function attachDeliverySession(owner, env = process.env, routes, signal) {
+    return attach(owner, env, routes, false, signal);
+}
+/** Replace the supplied route kinds while preserving every other registered route. */
+export async function attachDeliverySessionRoutes(owner, env = process.env, routes, signal) {
+    return attach(owner, env, routes, true, signal);
 }
-/** Restore only detached, standing seats of this exact owner before starting a receiver. */
-export async function restoreSessionSeats(owner, env = process.env, wakeAddress, signal) {
-    const locations = new Set((await projectSessionCandidates({ owner, env })).map(candidate => candidate.location));
-    for (const location of locations) {
+async function attach(owner, env, routes, merge, signal) {
+    if (signal?.aborted)
+        return false;
+    const ledger = await openLedger(env);
+    try {
+        const previous = await ledger.session(owner);
         if (signal?.aborted)
-            return;
-        let square;
-        try {
-            square = await Square.at({ path: location, env }, { signal });
-            for (const seat of await square.seatsOf(owner)) {
-                if (signal?.aborted)
-                    return;
-                if (seat.attachment !== 'detached')
-                    continue;
-                try {
-                    await square.reattach(seat.name, { owner, wakeAddress }, { signal });
-                }
-                catch { /* A replacement or one failed seat does not block its peers. */ }
-            }
-        }
-        catch { /* An indexed location is only a candidate, not a promise of availability. */ }
-        finally {
-            await square?.close();
-        }
+            return false;
+        const selected = merge && routes ? [...(previous?.routes ?? []).filter(old => !routes.some(route => route.kind === old.kind)), ...routes] : routes ?? previous?.routes ?? [];
+        return await ledger.attach({ owner, expectedGeneration: previous?.generation ?? null, routes: selected });
+    }
+    finally {
+        await ledger.close();
+    }
+}
+export async function detachDeliverySession(owner, generation, env = process.env) {
+    const ledger = await openLedger(env);
+    try {
+        return await ledger.detach({ owner, generation });
+    }
+    finally {
+        await ledger.close();
+    }
+}
+export async function markDeliverySessionDeleted(owner, generation, env = process.env) {
+    const ledger = await openLedger(env);
+    try {
+        return await ledger.markDeleted({ owner, generation });
+    }
+    finally {
+        await ledger.close();
     }
 }

package/dist/sqlite-square.d.ts

@@ -1,8 +1,8 @@
 import { type Owner } from './model.js';
-import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, LifecycleResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity, ChannelSendInput, ChannelSendResult } from './square-facade.js';
+import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity, SendInput, SendResult } from './square-facade.js';
 export type * from './square-facade.js';
 export { createSquareResourceOwner } from './artifact.js';
-export { squareClock } from './channel-internal.js';
+export { squareClock } from './operation-control.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
 export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
@@ -12,32 +12,35 @@ export declare class SqliteSquare {
     readonly location: string;
     private readonly artifact;
     private readonly clock;
-    private readonly wakeTransport?;
+    private readonly env;
+    private readonly closesArtifact;
     private readonly deliveryLocation;
-    private readonly channel;
     private constructor();
+    private reconcile;
+    private flush;
     static at(input: SquareAtInput, control?: OperationControl): Promise<SqliteSquare>;
     static build(input: SquareBuildInput, control?: OperationControl): Promise<SqliteSquare>;
     static inMemory(input: Omit<SquareBuildInput, 'path' | 'resources'>): SqliteSquare;
-    /** Agora join composes membership and endpoint custody in one transaction. */
+    /** Join establishes membership and local producer custody in one transaction. */
     private joinSeat;
     private requiredSeat;
-    private reattachSeat;
-    private endHeldSeat;
-    private cancelHeld;
     private observation;
     private contextObservation;
+    /** Host liveness is a read-only, non-atomic overlay; it never changes membership. */
+    private withHostPresence;
     private handle;
     private static readonly ParticipantHandle;
-    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
+    send(input: SendInput, control?: OperationControl): Promise<SendResult>;
     participant(name: string, options: {
         readonly owner: Owner;
     }): Promise<Participant>;
     join(requested: string, options: JoinOptions, control?: OperationControl): Promise<JoinResult>;
-    reattach(name: string, { owner, wakeAddress }: Pick<JoinOptions, 'owner' | 'wakeAddress'>, control?: OperationControl): Promise<Participant | null>;
     history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
     status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
-    participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;
+    /** Local mode reads only World-known facts; it does not verify host attachment. */
+    participants(options?: ObservationOptions & {
+        readonly local?: boolean;
+    }, control?: OperationControl): Promise<ParticipantsResult>;
     recovery(requested?: string, control?: OperationControl): Promise<RecoveryResult>;
     stream(options: StreamOptions & {
         readonly recipient: string;
@@ -48,18 +51,6 @@ export declare class SqliteSquare {
     stream(options: StreamOptions, control?: OperationControl): AsyncIterable<StreamRecord>;
     seatsOf(owner: Owner): Promise<readonly import('./square-facade.js').HeldSeat[]>;
     close(): Promise<void>;
-    cancelDeliveries(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }): Promise<boolean>;
-    detach(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }): Promise<true | null>;
-    endHeld(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }): Promise<LifecycleResult | null>;
 }
 export declare function diagnoseSquare(input: SquareLocation, control?: OperationControl): Promise<import("./artifact.js").DiagnoseResult>;
 export declare function discover(input: SquareAtInput, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;