@astrosheep/square 0.3.106 → 0.4.1

package/dist/sqlite-square.js

@@ -1,54 +1,34 @@
-import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
+import { formatActivityId } from './square-core.js';
 import { assertCurrentSeat } from './square-domain.js';
 import { canonicalPath } from './canonical-path.js';
-import { activityQueryFilter } from './activity-query.js';
-import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { activityMetadataHasContent, InternalSquareError, SquareError, isSquareError, nameKey, sameName, validateActivityMetadata, validateName } from './model.js';
+import { InternalSquareError, SquareError, isSquareError, nameKey, validateName } from './model.js';
+import { checkControl, failure, squareClock } from './operation-control.js';
+import { validateMetadataMatch } from './delivery-deferral.js';
+import { flushSquarePosts, reconcileSquareDelivery, readSquareSessions, ensureInitialDeliverySession } from './square-posting.js';
 import { attentionChange, coreDone, coreListening, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
 import { expressionContext } from './activity-feed.js';
 import { expressHint } from './hints.js';
-import { ATTENTION_BODY_MAX } from './attention-presentation.js';
-import { asSeatRef, participantAuthority, requireOwner, requireJoinName } from './seats.js';
-import { recoveryObservation, entryPresentation, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, toPerceivedActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+import { asSeatRef, participantAuthority, requireJoinName, requireOwner } from './seats.js';
+import { recoveryObservation, entryPresentation, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, toPerceivedActivity, publicActivities, selectHistory, NON_READ, HISTORY_MAX_LIMIT, HISTORY_DEFAULT_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
-import { rememberSquarePath, squareIndexPath } from './square-index.js';
-import { deliverPending } from './delivery-operations.js';
 import { participantIdentity } from './participant-identity.js';
 import { joinRecoveryCommand } from './presentation.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
 import { createArtifactPort, createSquare, diagnoseSquareFile, prepareSquareBuild } from './artifact.js';
-import { migrateSquareFile } from './square-migration.js';
+import { activityQueryFilter } from './activity-query.js';
 import { discoverSquares } from './list.js';
 import { streamSquare } from './stream.js';
 export { createSquareResourceOwner } from './artifact.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';
 export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
-function checkControl(control) {
-    if (control?.signal?.aborted)
-        throw control.signal.reason ?? new Error('Square operation was cancelled');
-}
-export function squareClock(env, clock) {
-    if (clock !== undefined)
-        return clock;
-    if (env.SQUARE_NOW_MS === undefined)
-        return Date.now;
-    const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
-    if (!Number.isFinite(value))
-        throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
-    return () => value;
-}
-function failure(error, detail) {
-    const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
-    Object.assign(normalized, { operation: detail });
-    return normalized;
-}
 function rejectUnsentActivity(operation) {
     try {
         return operation();
@@ -59,28 +39,25 @@ function rejectUnsentActivity(operation) {
         throw error;
     }
 }
-/** A generic managed address must not displace the receiver's native registration on reconnect. */
-function canRefreshWakeAddress(current, proposed) {
-    return proposed.kind !== 'paseo' || current === undefined || current.kind === 'paseo';
-}
 /** One concrete local resource, including its entry-resolved dependencies and lifetime. */
 export class SqliteSquare {
     location;
     artifact;
     clock;
-    wakeTransport;
-    indexPath;
+    env;
     closesArtifact;
     deliveryLocation;
-    constructor(location, artifact, clock, wakeTransport, indexPath, closesArtifact = true, deliveryLocation = location) {
+    constructor(location, artifact, clock, env, closesArtifact = true, deliveryLocation = location) {
         this.location = location;
         this.artifact = artifact;
         this.clock = clock;
-        this.wakeTransport = wakeTransport;
-        this.indexPath = indexPath;
+        this.env = env;
         this.closesArtifact = closesArtifact;
         this.deliveryLocation = deliveryLocation;
     }
+    reconcile() { return reconcileSquareDelivery(this.artifact, this.deliveryLocation, this.env, this.clock); }
+    // Posting is retryable after commit; a delivery failure cannot make a landed write unsent.
+    async flush() { await flushSquarePosts(this.artifact, this.deliveryLocation, this.env, this.clock).catch(() => undefined); }
     static async at(input, control) {
         const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
         const clock = squareClock(env, input.clock);
@@ -89,7 +66,7 @@ export class SqliteSquare {
         const artifact = borrowed ?? createArtifactPort(location, undefined, control?.signal);
         try {
             await artifact.read(facts => facts.header(), control?.signal);
-            return new SqliteSquare(location, artifact, clock, input.wakeTransport || undefined, squareIndexPath(env), borrowed === undefined, await canonicalPath(location));
+            return new SqliteSquare(location, artifact, clock, env, borrowed === undefined, await canonicalPath(location));
         }
         catch (error) {
             if (borrowed === undefined)
@@ -109,12 +86,64 @@ export class SqliteSquare {
     }
     static inMemory(input) {
         const env = { ...(input.env ?? process.env) };
-        return new SqliteSquare(`memory://${crypto.randomUUID()}`, createArtifactPort(':memory:', prepareSquareBuild(input, input.markdown)), squareClock(env, input.clock), input.wakeTransport || undefined);
+        return new SqliteSquare(`memory://${crypto.randomUUID()}`, createArtifactPort(':memory:', prepareSquareBuild(input, input.markdown)), squareClock(env, input.clock), env);
     }
-    /** Discovery is best effort and never grants write authority. */
-    async publishSeat(owner) {
-        if (this.indexPath !== undefined)
-            await rememberSquarePath(this.location, owner, this.indexPath).catch(() => undefined);
+    /** Join establishes membership and local producer custody in one transaction. */
+    async joinSeat(name, options, control) {
+        checkControl(control);
+        const owner = requireOwner(options?.owner), now = this.clock();
+        const initial = !options.takeover ? undefined : (await this.artifact.read(facts => facts.participant(name)?.joined ? facts.seat(name) : undefined, control?.signal)).value;
+        const authority = initial === undefined ? { kind: 'join', participant: name, owner }
+            : { kind: 'takeover', participant: initial.participant, owner, expectedGeneration: initial.generation };
+        const committed = (await this.artifact.transactAs(authority, facts => {
+            const participant = facts.participant(name)?.name ?? name;
+            const current = facts.participant(participant), currentSeat = facts.seat(participant);
+            let kind = 'joined', activity = null;
+            if (initial !== undefined) {
+                if (!current?.joined)
+                    throw new SquareError('already_done', `${participantIdentity(participant)} is no longer standing here`);
+                facts.land(coreDone(facts, participant, '', now));
+                kind = 'taken-over';
+            }
+            else if (current?.joined) {
+                if (currentSeat === undefined || currentSeat.owner !== owner)
+                    throw new SquareError('already_joined', `${participantIdentity(participant)} is held by another owner; take it over explicitly`);
+                if (currentSeat.attachment !== 'attached')
+                    throw new SquareError('already_joined', `${participantIdentity(participant)} is away; resume the host session first`);
+                kind = 'reconnected';
+            }
+            if (kind !== 'reconnected') {
+                const joinAct = decideJoin(facts, participant, now);
+                if (joinAct === undefined)
+                    throw new SquareError('already_joined', `${participantIdentity(participant)} could not be joined`);
+                activity = toPublicActivity(facts.land(joinAct));
+            }
+            const seat = facts.seat(participant);
+            if (seat === undefined)
+                throw new SquareError('invalid_args', 'The join activity did not establish participant custody.');
+            return { seat, activity, kind,
+                ...(!options.observe ? {} : { observation: { ...this.observation(inSquareCount(facts), seat.participant, now),
+                        deliveryAvailable: false } }) };
+        }, control?.signal)).value;
+        return committed;
+    }
+    async requiredSeat(name, { owner }) {
+        validateName(name);
+        requireOwner(owner);
+        return (await this.artifact.read(facts => {
+            const participant = facts.participant(name), seat = facts.seat(name);
+            if (!participant?.joined || seat === undefined || seat.owner !== owner || seat.attachment !== 'attached') {
+                const reason = participant === undefined ? 'has never stepped into this square'
+                    : !participant.joined ? 'needs to join first'
+                        : seat !== undefined && seat.owner !== owner ? 'is not held by this owner; join before writing'
+                            : seat?.attachment === 'detached' ? 'is away; resume the host session first'
+                                : 'needs a current participant seat; join first';
+                throw new SquareError('already_joined', `${participantIdentity(participant?.name ?? name)} ${reason}`, {
+                    reason: 'needs_seat', join: joinRecoveryCommand(this.location, participant?.name ?? name),
+                });
+            }
+            return seat;
+        })).value;
     }
     observation(standingCount, participant, now = this.clock()) {
         return { location: this.location, standingCount, now,
@@ -123,6 +152,28 @@ export class SqliteSquare {
     async contextObservation(participant, control) {
         return (await this.artifact.read(facts => this.observation(inSquareCount(facts), participant), control?.signal)).value;
     }
+    /** Host liveness is a read-only, non-atomic overlay; it never changes membership. */
+    async withHostPresence(select, control) {
+        const seats = (await this.artifact.read(facts => facts.roster().filter(person => person.joined)
+            .flatMap(person => { const seat = facts.seat(person.name); return seat === undefined ? [] : [seat]; }), control?.signal)).value;
+        const sessions = await readSquareSessions(seats, this.env);
+        const captured = new Map(seats.map(seat => [nameKey(seat.participant), seat]));
+        return (await this.artifact.read(facts => {
+            const seat = (name) => {
+                const current = facts.seat(name);
+                if (current === undefined)
+                    return undefined;
+                const before = captured.get(nameKey(current.participant));
+                const attached = before?.owner === current.owner && before.generation === current.generation
+                    && sessions.get(current.owner)?.state === 'attached';
+                return { ...current, attachment: attached ? 'attached' : 'detached' };
+            };
+            return select(Object.assign({}, facts, { seat }), name => {
+                const current = seat(name);
+                return current?.attachment === 'attached' && (sessions.get(current.owner)?.routes.length ?? 0) > 0;
+            });
+        }, control?.signal)).value;
+    }
     handle(seat) { return new SqliteSquare.ParticipantHandle(seat.participant, this, seat); }
     // The nested handle uses its resource's private dependencies without copying
     // them into a second context.
@@ -146,12 +197,14 @@ export class SqliteSquare {
             let landedId;
             try {
                 checkControl(control);
+                await square.reconcile();
                 name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
                 const seat = this.seat;
                 const context = !options.observe ? undefined : (await square.artifact.read(facts => expressionContext(facts, name), control?.signal)).value;
                 while (true) {
                     checkControl(control);
                     try {
+                        await square.reconcile();
                         effect = 'unknown';
                         const now = square.clock();
                         const reply = rejectUnsentActivity(() => {
@@ -179,15 +232,15 @@ export class SqliteSquare {
                                     throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, proposed.nextAt - now) });
                                 return proposed;
                             });
-                            return { stored: facts.land(decision.act), standingCount: inSquareCount(facts),
+                            const stored = facts.land(decision.act);
+                            return { stored, standingCount: inSquareCount(facts),
                                 ownActivityCount: facts.participant(name).sayCount, hardCap: facts.header().hardCap,
                                 ...(decision.unmatchedMentions === undefined ? {} : { unmatchedMentions: decision.unmatchedMentions }),
                                 ...(decision.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: decision.replyAuthorNotHere }) };
                         }, control?.signal)).value;
                         landedId = formatActivityId(committed.stored.index);
                         effect = 'landed';
-                        if (square.wakeTransport !== undefined)
-                            await deliverPending({ artifact: square.artifact, transport: square.wakeTransport, location: square.deliveryLocation, activity: committed.stored.index, now }).catch(() => undefined);
+                        await square.flush();
                         const { stored, standingCount, ownActivityCount, hardCap, ...metadata } = committed;
                         const hint = expressHint(ownActivityCount);
                         return { activity: toPublicActivity(stored), ...metadata,
@@ -213,10 +266,11 @@ export class SqliteSquare {
         }
         async listener(verb, target, options, control) {
             const square = this.owner;
-            const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
             checkControl(control);
+            await square.reconcile();
+            const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
             const seat = this.seat, now = square.clock();
-            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
+            const result = (await square.artifact.transactAs(participantAuthority(seat), facts => {
                 const act = attentionChange(facts, verb, name, target, now);
                 const activity = act === undefined ? null : toPublicActivity(facts.land(act));
                 return { activity, ...(!options.observe ? {} : { observation: {
@@ -224,6 +278,8 @@ export class SqliteSquare {
                             target: activity?.target ?? target,
                         } }) };
             }, control?.signal)).value;
+            await square.flush();
+            return result;
         }
         listen(target, options = {}, control) { return this.listener('listen', target, options, control); }
         ignore(target, options = {}, control) { return this.listener('ignore', target, options, control); }
@@ -237,6 +293,7 @@ export class SqliteSquare {
         }
         /** Receipt selection rechecks the lease inside the writer, not at its last heartbeat. */
         async catchPage(name, seat, options, control, leaseId) {
+            await this.owner.reconcile();
             return (await this.owner.artifact.transactAs(participantAuthority(seat), facts => {
                 if (leaseId !== undefined && facts.lease(name)?.leaseId !== leaseId)
                     return null;
@@ -255,27 +312,35 @@ export class SqliteSquare {
                 }, square.clock()))).value;
                 if (reason === 'drained')
                     reason = view.terminalStatus ?? reason;
+                await square.flush();
                 if (leaseId !== undefined) {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
                     leaseId = undefined;
                 }
-                let presence;
+                let presence, deliveryAvailable = false;
                 if (options.observe) {
                     try {
-                        presence = (await square.artifact.read(facts => catchPresence(facts, square.clock()), control?.signal)).value;
+                        const observed = await square.withHostPresence((facts, available) => {
+                            const data = catchPresence(facts, square.clock());
+                            return { presence: { ...data, participants: data.participants.map(person => ({ ...person, deliveryAvailable: available(person.name) })) },
+                                deliveryAvailable: available(view.participant) };
+                        }, control);
+                        presence = observed.presence;
+                        deliveryAvailable = observed.deliveryAvailable;
                     }
                     catch { /* Optional presence cannot erase the completed selection or receipts. */ }
                 }
                 return { activities: view.activities, remaining: view.remaining, reason,
                     ...(view.hint === undefined ? {} : { hint: view.hint }), ...(!options.observe ? {} : { observation: {
                             ...square.observation(view.standingCount, view.participant, view.now), participant: view.participant,
-                            deliveryAvailable: view.deliveryAvailable,
+                            deliveryAvailable,
                             ownActivityCount: view.ownActivityCount, hardCap: view.hardCap,
                             ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }),
                         } }) };
             };
             try {
                 checkControl(control);
+                await square.reconcile();
                 validateName(name);
                 if (!Number.isFinite(idle) || idle < 0)
                     throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
@@ -350,219 +415,107 @@ export class SqliteSquare {
             const limit = options.limit === undefined ? 100 : options.limit;
             if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
                 throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
-            const { actors, ...query } = activityQueryFilter(options), square = this.owner;
-            return (await square.artifact.read(facts => {
+            // Pending follows the shared archive cursor: act/N with before/after.
+            const shared = activityQueryFilter(options);
+            const filter = { kinds: ['say'], unseenOnly: true,
+                ...(shared.indexes === undefined ? {} : { indexes: shared.indexes }),
+                ...(shared.actors === undefined ? {} : { senders: shared.actors }),
+                ...(shared.metadataMatch === undefined ? {} : { metadataMatch: shared.metadataMatch }),
+                ...(shared.search === undefined ? {} : { search: shared.search }),
+                ...(shared.afterIndex === undefined ? {} : { afterIndex: shared.afterIndex }),
+                ...(shared.beforeIndex === undefined ? {} : { beforeIndex: shared.beforeIndex }) };
+            return (await this.owner.artifact.read(facts => {
                 assertCurrentSeat(facts, asSeatRef(this.seat));
-                const filter = { ...query, senders: actors, unseenOnly: true };
                 const heads = facts.directed(this.name, filter, { edge: 'oldest', limit });
-                const activities = facts.activities(heads.items.map(head => head.index))
-                    .map(activity => toPerceivedActivity(facts, activity, this.name));
-                return { activities, remaining: facts.directedCount(this.name, filter) - activities.length };
+                return { activities: facts.activities(heads.items.map(head => head.index)).map(activity => toPerceivedActivity(facts, activity, this.name)),
+                    remaining: facts.directedCount(this.name, filter) - heads.items.length };
             }, control?.signal)).value;
         }
-        async ack(ids, control) {
+        ack(input, control) {
+            const square = this.owner;
             checkControl(control);
-            if (!Array.isArray(ids))
-                throw new SquareError('invalid_args', 'Ack requires an array of activity IDs.');
-            const indexes = [...new Set(Array.from(ids, parseRequiredActivityId))], square = this.owner;
-            return (await square.artifact.transactAs(participantAuthority(this.seat), facts => {
-                for (const index of indexes) {
-                    if (facts.directedAt(this.name, index) === undefined)
-                        throw new SquareError('invalid_args', `${formatActivityId(index)} is not addressed to you.`, {
-                            reason: 'not_addressed', activityId: formatActivityId(index),
-                        });
+            return square.artifact.transactAs(participantAuthority(this.seat), facts => {
+                if (!Array.isArray(input)) {
+                    const exact = input;
+                    if (exact?.future !== 'exact')
+                        throw new SquareError('invalid_args', 'Ack requires an exact future predicate.');
+                    validateName(exact.from);
+                    return { consumed: facts.ackMatching(asSeatRef(this.seat), { from: exact.from, match: validateMetadataMatch(exact.match), future: 'exact' }, square.clock()) };
+                }
+                const indexes = [];
+                for (const id of input) {
+                    const activity = facts.activity(parseRequiredActivityId(id));
+                    if (activity?.kind !== 'say')
+                        throw new SquareError('invalid_args', `${id} is not addressed to you.`, { reason: 'not_addressed', activityId: id });
+                    const head = facts.directed(this.name, { indexes: [activity.index], kinds: ['say'] }, { edge: 'oldest', limit: 1 }).items[0];
+                    if (head === undefined)
+                        throw new SquareError('invalid_args', `${id} is not addressed to you.`, { reason: 'not_addressed', activityId: id });
+                    indexes.push(activity.index);
                 }
                 return { consumed: facts.markSeen(this.name, indexes, square.clock()) };
-            }, control?.signal)).value;
-        }
-        async deferDelivery(input, control) {
-            checkControl(control);
-            const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
-            const square = this.owner, seat = this.seat;
-            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const now = square.clock(), expiresAt = now + duration, id = crypto.randomUUID();
-                const result = { id, expiresAt: new Date(expiresAt).toISOString() };
-                facts.putDeliveryDeferral(asSeatRef(seat), id, match, expiresAt, now);
-                return result;
-            }, control?.signal)).value;
-        }
-        async renewDeliveryDeferral(id, durationMs, control) {
-            checkControl(control);
-            validateDeferralId(id);
-            const duration = validateDeferralDuration(durationMs), square = this.owner;
-            const seat = this.seat;
-            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const now = square.clock(), expiresAt = now + duration;
-                const result = { id, expiresAt: new Date(expiresAt).toISOString() };
-                return facts.renewDeliveryDeferral(asSeatRef(seat), id, expiresAt, now) ? result : null;
-            }, control?.signal)).value;
-        }
-        async releaseDeliveryDeferral(id, control) {
-            checkControl(control);
-            validateDeferralId(id);
-            const square = this.owner, seat = this.seat;
-            return (await square.artifact.transactAs(participantAuthority(seat), facts => facts.releaseDeliveryDeferral(asSeatRef(seat), id, square.clock()), control?.signal)).value;
+            }, control?.signal).then(result => result.value);
         }
         async done(body, options = {}, control) {
             validateDoneBody(body);
+            checkControl(control);
             const square = this.owner;
+            await square.reconcile();
             const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
             const seat = this.seat, now = square.clock();
-            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
+            const result = (await square.artifact.transactAs(participantAuthority(seat), facts => {
                 const stored = facts.land(coreDone(facts, name, body ?? '', now));
                 return { activity: toPublicActivity(stored), ...(!options.observe ? {} : { observation: square.observation(inSquareCount(facts), name, now),
                     }) };
             }, control?.signal)).value;
+            await square.flush();
+            return result;
         }
     };
-    /** Direct messages use explicit recipients, not participant expression admission or body attention. */
     async send(input, control) {
         checkControl(control);
-        const { from, to, body, truncate = ATTENTION_BODY_MAX } = input;
-        if (typeof from !== 'string')
-            throw new SquareError('invalid_args', 'Channel sender must be a name.');
-        validateName(from);
-        const targets = typeof to === 'string' ? [to] : to;
-        if (!Array.isArray(targets) || targets.length < 1 || targets.length > MAX_IDENTITY_SET_SIZE)
-            throw new SquareError('invalid_args', `Channel needs between 1 and ${MAX_IDENTITY_SET_SIZE} recipients.`);
-        const unique = [];
-        for (const target of targets) {
-            if (typeof target !== 'string')
-                throw new SquareError('invalid_args', 'Channel recipients must be names.');
-            validateName(target);
-            if (!unique.some(name => sameName(name, target)))
-                unique.push(target);
-        }
-        if (typeof body !== 'string' || body.trim() === '')
-            throw new SquareError('invalid_args', 'Channel body must be non-empty.');
-        if (truncate !== false && (!Number.isSafeInteger(truncate) || truncate < 1))
-            throw new SquareError('invalid_args', 'Channel truncate must be false or a positive integer.');
-        const fullBody = body.replace(/\r\n/g, '\n');
-        const preview = truncate !== false && fullBody.length > truncate
-            ? `${fullBody.slice(0, truncate).trimEnd()}… (truncated ${fullBody.length - truncate} chars)`
-            : undefined;
-        const delivery = preview === undefined ? { mode: 'direct' } : { mode: 'direct', preview };
-        const metadata = validateActivityMetadata(input.metadata);
-        const { stored, resolvedTo } = (await this.artifact.transactAs({ kind: 'send', actor: from }, facts => {
-            const standing = facts.roster().filter(p => p.joined), resolvedTo = [], missing = [];
-            for (const target of unique) {
-                const recipient = standing.find(p => sameName(p.name, target));
-                if (recipient === undefined)
-                    missing.push(target);
-                else
-                    resolvedTo.push(recipient.name);
-            }
-            if (missing.length > 0)
-                throw new SquareError('invalid_args', `Channel recipients are not standing: ${missing.join(', ')}`, {
-                    reason: 'not_standing', targets: missing, activityUnsent: true,
-                });
-            return { stored: facts.land({ kind: 'say', actor: from, at: this.clock(), body: fullBody,
-                    ...(activityMetadataHasContent(metadata) ? { metadata } : {}), delivery, mentions: resolvedTo }), resolvedTo };
-        }, control?.signal)).value;
-        if (this.wakeTransport !== undefined)
-            await deliverPending({ artifact: this.artifact, transport: this.wakeTransport, location: this.deliveryLocation,
-                activity: stored.index, now: stored.at }).catch(() => undefined);
-        return { id: formatActivityId(stored.index), at: stored.at, from: stored.actor, to: resolvedTo, body: preview ?? fullBody,
-            ...(stored.kind !== 'say' || stored.metadata === undefined ? {} : { metadata: stored.metadata }) };
+        await this.reconcile();
+        const result = (await this.artifact.transactAs({ kind: 'send', actor: input.from }, facts => facts.insertNotice(input, this.clock()), control?.signal)).value;
+        await this.flush();
+        return result;
     }
-    async participant(name, { owner }) {
-        validateName(name);
-        requireOwner(owner);
-        return (await this.artifact.read(facts => {
-            const participant = facts.participant(name), seat = facts.seat(name);
-            if (!participant?.joined || seat === undefined || seat.owner !== owner || seat.attachment !== 'attached') {
-                const reason = participant === undefined ? 'has never stepped into this square'
-                    : !participant.joined ? 'needs a current attached seat; join first'
-                        : seat !== undefined && seat.owner !== owner ? 'is not held by this owner; join before writing'
-                            : seat?.attachment === 'detached' ? 'is away — join again before writing'
-                                : 'needs a current attached seat; join first';
-                throw new SquareError('already_joined', `${participantIdentity(participant?.name ?? name)} ${reason}`, {
-                    reason: 'needs_seat', join: joinRecoveryCommand(this.location, participant?.name ?? name),
-                });
-            }
-            return this.handle(seat);
-        })).value;
+    async participant(name, options) {
+        return this.handle(await this.requiredSeat(name, options));
     }
     async join(requested, options, control) {
         let name = requested;
         try {
             checkControl(control);
             name = requireJoinName(requested);
-            const last = options?.last ?? HISTORY_DEFAULT_LIMIT;
+            const last = options.last ?? HISTORY_DEFAULT_LIMIT;
             if (!Number.isSafeInteger(last) || last < 1 || last > HISTORY_MAX_LIMIT)
                 throw new SquareError('invalid_args', 'Join history limit must be between 1 and 100');
-            const owner = requireOwner(options?.owner), wakeAddress = options.wakeAddress, now = this.clock();
-            const initial = !options.takeover ? undefined : (await this.artifact.read(facts => facts.participant(name)?.joined ? facts.seat(name) : undefined, control?.signal)).value;
-            const authority = initial === undefined ? { kind: 'join', participant: name, owner, wakeAddress }
-                : { kind: 'takeover', participant: initial.participant, owner, expectedGeneration: initial.generation, wakeAddress };
-            const committed = (await this.artifact.transactAs(authority, facts => {
-                const participant = facts.participant(name)?.name ?? name;
-                const current = facts.participant(participant), currentSeat = facts.seat(participant);
-                let kind = 'joined', activity = null;
-                if (initial !== undefined) {
-                    if (!current?.joined)
-                        throw new SquareError('already_done', `${participantIdentity(participant)} is no longer standing here`);
-                    facts.land(coreDone(facts, participant, '', now));
-                    kind = 'taken-over';
-                }
-                else if (current?.joined) {
-                    if (currentSeat === undefined || currentSeat.owner !== owner)
-                        throw new SquareError('already_joined', `${participantIdentity(participant)} is held by another owner; take it over explicitly`);
-                    if (currentSeat.attachment === 'detached')
-                        facts.reattachSeat(asSeatRef(currentSeat), wakeAddress);
-                    else if (wakeAddress !== undefined && canRefreshWakeAddress(currentSeat.wakeAddress, wakeAddress))
-                        facts.updateWakeAddress(asSeatRef(currentSeat), wakeAddress);
-                    kind = 'reconnected';
-                }
-                if (kind !== 'reconnected') {
-                    const joinAct = decideJoin(facts, participant, now);
-                    if (joinAct === undefined)
-                        throw new SquareError('already_joined', `${participantIdentity(participant)} could not be joined`);
-                    activity = toPublicActivity(facts.land(joinAct));
-                }
-                const seat = facts.seat(participant);
-                if (seat === undefined)
-                    throw new SquareError('invalid_args', 'The join activity did not establish its artifact seat.');
-                return { participant: this.handle(seat), activity, kind,
-                    ...(!options.observe ? {} : { observation: { ...this.observation(inSquareCount(facts), seat.participant, now),
-                            deliveryAvailable: seat.wakeAddress !== undefined } }) };
-            }, control?.signal)).value;
-            await this.publishSeat(owner);
+            if (!await ensureInitialDeliverySession(requireOwner(options.owner), this.env, options.wakeAddress))
+                throw new SquareError('already_joined', `${participantIdentity(name)} is away; resume the host session first`, { reason: 'needs_seat' });
+            await this.reconcile();
+            const committed = await this.joinSeat(name, options, control);
+            await this.flush();
+            const participant = this.handle(committed.seat);
+            const result = { participant, activity: committed.activity, kind: committed.kind,
+                ...(committed.observation === undefined ? {} : { observation: committed.observation }) };
             if (!options.observe)
-                return committed;
-            let entry;
+                return result;
+            let entry, deliveryAvailable = false;
             try {
-                entry = (await this.artifact.read(facts => entryPresentation(facts, committed.participant.name, last), control?.signal)).value;
+                const observed = await this.withHostPresence((facts, available) => ({
+                    entry: entryPresentation(facts, participant.name, options.last ?? HISTORY_DEFAULT_LIMIT),
+                    deliveryAvailable: available(participant.name),
+                }), control);
+                entry = observed.entry;
+                deliveryAvailable = observed.deliveryAvailable;
             }
             catch { /* Keep the committed join even when optional history is unavailable. */ }
-            return { ...committed, observation: { ...committed.observation, ...(entry === undefined ? { enrichmentUnavailable: true } : { entry }) } };
+            return { ...result, observation: { ...committed.observation, deliveryAvailable,
+                    ...(entry === undefined ? { enrichmentUnavailable: true } : { entry }) } };
         }
         catch (error) {
             throw failure(error, { operation: 'join', subject: 'caller', participant: name });
         }
     }
-    /** Restore only a standing seat; a concurrent departure or takeover cannot be revived. */
-    async reattach(name, { owner, wakeAddress }, control) {
-        checkControl(control);
-        validateName(name);
-        requireOwner(owner);
-        const captured = (await this.artifact.read(facts => facts.seat(name), control?.signal)).value;
-        if (captured === undefined || captured.owner !== owner)
-            return null;
-        const seat = (await this.artifact.transactAs({ kind: 'join', participant: name, owner, wakeAddress }, facts => {
-            const current = facts.seat(name);
-            if (!facts.participant(name)?.joined || current === undefined || current.generation !== captured.generation || current.owner !== owner)
-                return null;
-            if (current.attachment === 'detached')
-                facts.reattachSeat(asSeatRef(current), wakeAddress);
-            else if (wakeAddress !== undefined && canRefreshWakeAddress(current.wakeAddress, wakeAddress))
-                facts.updateWakeAddress(asSeatRef(current), wakeAddress);
-            return facts.seat(name);
-        }, control?.signal)).value;
-        if (seat !== null)
-            await this.publishSeat(owner);
-        return seat === null ? null : this.handle(seat);
-    }
     async history(query = {}, control) {
         if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
             throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);
@@ -575,7 +528,7 @@ export class SqliteSquare {
                 throw new SquareError('invalid_args', 'History context must be a non-negative safe integer');
         const limit = query.limit === undefined ? (query.at?.length ? null : HISTORY_DEFAULT_LIMIT) : query.limit;
         const contextual = !!query.at?.length || query.contextBefore !== undefined || query.contextAfter !== undefined;
-        const kinds = contextual || query.since !== undefined ? undefined : NON_READ;
+        const kinds = contextual || query.since !== undefined ? [...NON_READ, 'read'] : NON_READ;
         return (await this.artifact.read(facts => {
             const selected = selectHistory(facts, query, limit, kinds, query.observe === true);
             if (contextual && limit === null && selected.totalMatches > HISTORY_MAX_LIMIT)
@@ -594,12 +547,22 @@ export class SqliteSquare {
         }, control?.signal)).value;
     }
     async status(options = {}, control) {
-        return (await this.artifact.read(facts => queryStatus(facts, { location: this.location, now: this.clock() }, options.viewer, options.observe === true), control?.signal)).value;
+        return this.withHostPresence((facts, available) => {
+            const result = queryStatus(facts, { location: this.location, now: this.clock() }, options.viewer, options.observe === true);
+            return { ...result, participants: result.participants.map(person => ({ ...person, deliveryAvailable: available(person.name) })) };
+        }, control);
     }
+    /** Local mode reads only World-known facts; it does not verify host attachment. */
     async participants(options = {}, control) {
-        return (await this.artifact.read(facts => queryParticipants(facts, {
-            location: this.location, now: this.clock(),
-        }, options.observe === true), control?.signal)).value;
+        if (options.local)
+            return (await this.artifact.read(facts => {
+                const result = queryParticipants(facts, { location: this.location, now: this.clock() }, options.observe === true);
+                return { ...result, participants: result.participants.map(person => ({ ...person, deliveryAvailable: false })) };
+            }, control?.signal)).value;
+        return this.withHostPresence((facts, available) => {
+            const result = queryParticipants(facts, { location: this.location, now: this.clock() }, options.observe === true);
+            return { ...result, participants: result.participants.map(person => ({ ...person, deliveryAvailable: available(person.name) })) };
+        }, control);
     }
     async recovery(requested, control) {
         const facts = requested === undefined ? undefined : (await this.artifact.read(facts => recoveryObservation(facts, requested, this.clock()), control?.signal).catch(() => undefined))?.value;
@@ -612,39 +575,13 @@ export class SqliteSquare {
     }
     async seatsOf(owner) {
         requireOwner(owner);
-        return (await this.artifact.read(facts => facts.seatsForOwner(owner).map(({ participant: name, generation, attachment }) => ({ name, generation, attachment })))).value;
+        return (await this.artifact.read(facts => facts.seatsForOwner(owner)
+            .filter(seat => facts.participant(seat.participant)?.joined && seat.attachment === 'attached')
+            .map(seat => ({ name: seat.participant, generation: seat.generation })))).value;
     }
     close() { return this.closesArtifact ? this.artifact.close() : Promise.resolve(); }
-    async heldSeat(name, { owner, generation }) {
-        requireOwner(owner);
-        const seat = (await this.artifact.read(facts => facts.seat(name))).value;
-        return seat?.generation === generation && seat.owner === owner ? seat : undefined;
-    }
-    async cancelDeliveries(name, identity) {
-        const seat = await this.heldSeat(name, identity);
-        return seat === undefined ? false : this.artifact.cancelDeliveries(asSeatRef(seat));
-    }
-    async detach(name, identity) {
-        const captured = await this.heldSeat(name, identity);
-        if (captured === undefined)
-            return null;
-        const seat = asSeatRef(captured);
-        return (await this.artifact.transactAs({ kind: 'host-cleanup', seat }, facts => facts.detachSeat(seat) ? true : null)).value;
-    }
-    async endHeld(name, identity) {
-        const captured = await this.heldSeat(name, identity);
-        if (captured === undefined)
-            return null;
-        return (await this.artifact.transactAs({ kind: 'host-cleanup', seat: asSeatRef(captured) }, facts => {
-            const current = facts.seat(name);
-            if (current === undefined || current.generation !== captured.generation || current.owner !== captured.owner)
-                return null;
-            return { activity: toPublicActivity(facts.land(coreDone(facts, current.participant, '', this.clock()))) };
-        })).value;
-    }
 }
 export function diagnoseSquare(input, control) { checkControl(control); return diagnoseSquareFile(squareLocation(input)); }
-export function migrateSquare(input, control) { checkControl(control); const env = input.env ?? process.env; return migrateSquareFile(squareLocation(input), control?.signal, env); }
 export function discover(input, options = {}, control) {
     if (input.path !== undefined || (input.env ?? process.env).SQUARE_LOCATION)
         squareLocation(input);
@@ -654,10 +591,10 @@ export function discover(input, options = {}, control) {
 export async function inbox(input, owner, options = {}, control) {
     checkControl(control);
     requireOwner(owner);
-    const env = { ...(input.env ?? process.env) }, limit = options.limit ?? 20;
+    const limit = options.limit ?? 20;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
         throw new SquareError('invalid_args', 'Inbox limit must be between 1 and 100');
-    const rows = await sessionInboxCounts({ owner, env }, control?.signal);
+    const rows = await sessionInboxCounts({ owner, cwd: input.cwd }, control?.signal);
     checkControl(control);
     const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
     rows.sort((a, b) => compare(a.squarePath, b.squarePath) || compare(nameKey(a.name), nameKey(b.name)) || compare(a.name, b.name));