@astrosheep/square 0.3.106 → 0.4.0

package/dist/sqlite-square.js

@@ -1,54 +1,36 @@
-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 { Channel, ChannelEndpoint, checkControl, failure, squareClock } from './channel-internal.js';
+import { channelArtifact } from './artifact.js';
+import { deliverPending } from './delivery-operations.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 { squareIndexPath } from './square-index.js';
 import { participantIdentity } from './participant-identity.js';
 import { joinRecoveryCommand } from './presentation.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
+import { squareWakeProjection } from './wake-preview.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 './channel-internal.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,27 +41,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;
-    closesArtifact;
     deliveryLocation;
+    channel;
     constructor(location, artifact, clock, wakeTransport, indexPath, closesArtifact = true, deliveryLocation = location) {
         this.location = location;
         this.artifact = artifact;
         this.clock = clock;
         this.wakeTransport = wakeTransport;
-        this.indexPath = indexPath;
-        this.closesArtifact = closesArtifact;
         this.deliveryLocation = deliveryLocation;
+        this.channel = Channel.fromPort({ location, artifact: channelArtifact(artifact), clock,
+            ...(wakeTransport === undefined ? {} : { deliverEffect: message => deliverPending({ artifact: channelArtifact(artifact),
+                    preparePresentation: squareWakeProjection(artifact), transport: wakeTransport, location: deliveryLocation,
+                    ...(message === undefined ? {} : { message }), now: clock() }) }),
+            ...(indexPath === undefined ? {} : { indexPath }), closesArtifact });
     }
     static async at(input, control) {
         const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
@@ -111,10 +91,115 @@ export class SqliteSquare {
         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);
     }
-    /** 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);
+    /** Agora join composes membership and endpoint custody in one transaction. */
+    async joinSeat(name, options, control) {
+        checkControl(control);
+        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 && (wakeAddress.kind !== 'paseo' || currentSeat.wakeAddress === undefined || currentSeat.wakeAddress.kind === 'paseo'))
+                    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 endpoint.');
+            return { seat, activity, kind,
+                ...(!options.observe ? {} : { observation: { ...this.observation(inSquareCount(facts), seat.participant, now),
+                        deliveryAvailable: seat.wakeAddress !== undefined } }) };
+        }, control?.signal)).value;
+        await this.channel.remember(owner);
+        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 a current attached endpoint; 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 endpoint; 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;
+    }
+    async reattachSeat(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 && (wakeAddress.kind !== 'paseo' || current.wakeAddress === undefined || current.wakeAddress.kind === 'paseo'))
+                facts.updateWakeAddress(asSeatRef(current), wakeAddress);
+            return facts.seat(name);
+        }, control?.signal)).value;
+        if (seat !== null)
+            await this.channel.remember(owner);
+        return seat;
+    }
+    async endHeldSeat(name, identity) {
+        const captured = (await this.artifact.read(facts => {
+            const seat = facts.seat(name);
+            return seat?.generation === identity.generation && seat.owner === identity.owner ? seat : undefined;
+        })).value;
+        if (captured === undefined)
+            return null;
+        return (await this.artifact.transactAs({ kind: 'host-cleanup', seat: 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;
+    }
+    async cancelHeld(name, identity) {
+        const captured = (await this.artifact.read(facts => {
+            const seat = facts.seat(name);
+            return seat?.generation === identity.generation && seat.owner === identity.owner ? seat : undefined;
+        })).value;
+        if (captured === undefined)
+            return false;
+        return (await this.artifact.transactAs({ kind: 'participant', seat: captured }, facts => {
+            const boundary = facts.channel.header().lastMessageIndex;
+            return boundary < 0 ? false : facts.channel.cancelThrough(captured, boundary);
+        })).value;
     }
     observation(standingCount, participant, now = this.clock()) {
         return { location: this.location, standingCount, now,
@@ -130,12 +215,14 @@ export class SqliteSquare {
         name;
         owner;
         seat;
+        endpoint;
         constructor(name, owner, seat) {
             this.name = name;
             this.owner = owner;
             this.seat = seat;
+            this.endpoint = new ChannelEndpoint(owner.channel, seat);
         }
-        get generation() { return this.seat.generation; }
+        get generation() { return this.endpoint.generation; }
         async express(bodyOrInput, optionsOrControl = {}, operationControl) {
             const square = this.owner;
             const input = typeof bodyOrInput === 'object' && bodyOrInput !== null ? bodyOrInput : undefined;
@@ -179,18 +266,22 @@ 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);
+                            // One explicit projection: a landed say resolves its own Channel content in this transaction.
+                            const activity = stored.kind === 'say' ? facts.activities([stored.index])[0] : stored;
+                            if (activity === undefined)
+                                throw new SquareError('io', 'The landed activity is missing.');
+                            return { stored, activity, 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);
-                        const { stored, standingCount, ownActivityCount, hardCap, ...metadata } = committed;
+                        await square.channel.deliver(committed.stored.kind === 'say' ? committed.stored.messageIndex : undefined);
+                        const { stored, activity, standingCount, ownActivityCount, hardCap, ...metadata } = committed;
                         const hint = expressHint(ownActivityCount);
-                        return { activity: toPublicActivity(stored), ...metadata,
+                        return { activity: toPublicActivity(activity), ...metadata,
                             ...(hint === undefined ? {} : { hint }), ...(context === undefined ? {} : { observation: {
                                     ...square.observation(standingCount, name, now), ownActivityCount, hardCap, context, participant: name,
                                 } }) };
@@ -350,58 +441,46 @@ 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, never a Channel msg/N cursor.
+            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) {
-            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),
-                        });
+        ack(ids, control) {
+            const square = this.owner;
+            return square.artifact.transactAs(participantAuthority(this.seat), facts => {
+                const indexes = [];
+                for (const id of ids) {
+                    const activity = facts.activity(parseRequiredActivityId(id));
+                    if (activity?.kind !== 'say' || activity.messageIndex === undefined)
+                        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.messageIndex);
                 }
-                return { consumed: facts.markSeen(this.name, indexes, square.clock()) };
-            }, control?.signal)).value;
+                return { consumed: facts.channel.markSeen(this.name, indexes, square.clock()) };
+            }, control?.signal).then(result => result.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;
+        deferDelivery(input, control) {
+            return this.endpoint.deferDelivery(input, control);
         }
-        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;
+        renewDeliveryDeferral(id, durationMs, control) {
+            return this.endpoint.renewDeliveryDeferral(id, durationMs, control);
         }
-        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;
+        releaseDeliveryDeferral(id, control) {
+            return this.endpoint.releaseDeliveryDeferral(id, control);
         }
         async done(body, options = {}, control) {
             validateDoneBody(body);
@@ -415,152 +494,37 @@ export class SqliteSquare {
             }, control?.signal)).value;
         }
     };
-    /** 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 }) };
+    send(input, control) {
+        return this.channel.send(input, control);
     }
-    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;
-            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);
+            const committed = await this.joinSeat(name, options, control);
+            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;
+                return result;
             let entry;
             try {
-                entry = (await this.artifact.read(facts => entryPresentation(facts, committed.participant.name, last), control?.signal)).value;
+                entry = (await this.artifact.read(facts => entryPresentation(facts, participant.name, options.last ?? HISTORY_DEFAULT_LIMIT), control?.signal)).value;
             }
             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,
+                    ...(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);
+        const seat = await this.reattachSeat(name, { owner, wakeAddress }, control);
         return seat === null ? null : this.handle(seat);
     }
     async history(query = {}, control) {
@@ -575,7 +539,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)
@@ -611,40 +575,20 @@ export class SqliteSquare {
         return streamSquare(this.location, options, control);
     }
     async seatsOf(owner) {
-        requireOwner(owner);
-        return (await this.artifact.read(facts => facts.seatsForOwner(owner).map(({ participant: name, generation, attachment }) => ({ name, generation, attachment })))).value;
+        return this.channel.endpointsOf(owner);
     }
-    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));
+    close() { return this.channel.close(); }
+    cancelDeliveries(name, identity) {
+        return this.cancelHeld(name, identity);
     }
-    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;
+    detach(name, identity) {
+        return this.channel.detach(name, identity);
     }
-    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;
+    endHeld(name, identity) {
+        return this.endHeldSeat(name, identity);
     }
 }
 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);

package/dist/sqlite-values.d.ts

@@ -0,0 +1,21 @@
+import { SquareError, type FactPage, type IndexPage } from './neutral.js';
+export type Row = Record<string, string | number | null>;
+export declare const encode: {
+    (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
+    (value: any, replacer?: (number | string)[] | null, space?: string | number): string;
+};
+export declare const key: (name: string) => string;
+export declare function invalidArtifact(detail: string): SquareError;
+export declare function requireFact(ok: unknown, detail?: string): asserts ok;
+export declare function integer(value: unknown, minimum?: number): number;
+export declare function finite(value: unknown): number;
+export declare function string(value: unknown, nonempty?: boolean): string;
+export declare function json(value: unknown): unknown;
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function shape(value: unknown, required: readonly string[], optional?: readonly string[]): Record<string, unknown>;
+export declare function strings(value: unknown): string[];
+export declare function decoded(value: unknown, nonempty?: boolean): string;
+export declare function immutable<T>(value: T): T;
+export declare function stableJson(value: unknown): string;
+export declare function pageRows<T>(rows: Row[], page: IndexPage, decode: (row: Row) => T): FactPage<T>;
+export declare function pageLimit(page: IndexPage): number;