@astrosheep/square 0.3.92 → 0.3.94

package/dist/sqlite-square.js

@@ -1,21 +1,23 @@
 import { formatActivityId } from './square-core.js';
+import { assertCurrentSeat } from './square-domain.js';
+import { canonicalPath } from './canonical-path.js';
 import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
-import { squareLocation, localSquareLocation } from './square-location.js';
+import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { InternalSquareError, SquareError, isSquareError, nameKey, sameBody, validateName } from './model.js';
-import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, coreUnlisten, decideAct, decideImplicitJoin, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
+import { InternalSquareError, SquareError, isSquareError, nameKey, validateName } from './model.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, coreUnlisten, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { HELD_WAIT_BUDGET_MS, WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
-import { directedSuffix } from './activity-feed.js';
+import { expressionContext } from './activity-feed.js';
 import { expressHint } from './hints.js';
-import { asSeatRef, participantAuthority, requireBody, requireJoinName, requireSeat } from './seats.js';
+import { asSeatRef, participantAuthority, requireOwner, requireJoinName } from './seats.js';
 import { recoveryObservation, entryPresentation, snapshot, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
 import { rememberSquarePath, squareIndexPath } from './square-index.js';
-import { createDefaultWakeTransport } from './notifications.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';
@@ -65,38 +67,28 @@ export class SqliteSquare {
     location;
     artifact;
     clock;
-    body;
-    wakeAddress;
     wakeTransport;
     indexPath;
-    automaticDelivery;
-    ownsArtifact;
-    defaultParticipant;
-    constructor(location, artifact, clock, body, wakeAddress, wakeTransport, indexPath, automaticDelivery = true, ownsArtifact = true, defaultParticipant) {
+    closesArtifact;
+    deliveryLocation;
+    constructor(location, artifact, clock, wakeTransport, indexPath, closesArtifact = true, deliveryLocation = location) {
         this.location = location;
         this.artifact = artifact;
         this.clock = clock;
-        this.body = body;
-        this.wakeAddress = wakeAddress;
         this.wakeTransport = wakeTransport;
         this.indexPath = indexPath;
-        this.automaticDelivery = automaticDelivery;
-        this.ownsArtifact = ownsArtifact;
-        this.defaultParticipant = defaultParticipant;
+        this.closesArtifact = closesArtifact;
+        this.deliveryLocation = deliveryLocation;
     }
-    static async at(input, control, automaticDelivery = true) {
+    static async at(input, control) {
         const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
         const clock = squareClock(env, input.clock);
-        const wakeTransport = input.wakeTransport ?? (automaticDelivery
-            ? await createDefaultWakeTransport(env).catch(() => undefined) : undefined);
         // A request can abort its own borrowed reads, never the owner's connection lifetime.
         const borrowed = input.resources?.artifact(location);
         const artifact = borrowed ?? createArtifactPort(location, undefined, control?.signal);
         try {
             await artifact.read(facts => facts.header(), control?.signal);
-            const resource = new SqliteSquare(location, artifact, clock, input.body, input.wakeAddress, wakeTransport, squareIndexPath(env), automaticDelivery, borrowed === undefined, input.participant);
-            await resource.publishIdentity();
-            return resource;
+            return new SqliteSquare(location, artifact, clock, input.wakeTransport || undefined, squareIndexPath(env), borrowed === undefined, await canonicalPath(location));
         }
         catch (error) {
             if (borrowed === undefined)
@@ -106,33 +98,33 @@ export class SqliteSquare {
             throw error;
         }
     }
-    static async build(input, control, automaticDelivery = true) {
+    static async build(input, control) {
         checkControl(control);
         const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
         await createSquare(location, { hardCap: input.hardCap, throttlePerMinute: input.throttlePerMinute,
             template: input.template, force: input.force ?? false }, input.markdown, control?.signal);
         // Publication already committed; cancellation cannot erase the completed build.
-        return SqliteSquare.at({ ...input, path: location, env }, undefined, automaticDelivery);
+        return SqliteSquare.at({ ...input, path: location, env });
     }
     static inMemory(input) {
         const env = { ...(input.env ?? process.env) };
-        return new SqliteSquare('memory', createArtifactPort(':memory:', prepareSquareBuild(input, input.markdown)), squareClock(env, input.clock), input.body, input.wakeAddress, input.wakeTransport, undefined, true, true, input.participant);
+        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. Finish it before returning. */
-    async publishIdentity() {
-        if (this.location !== 'memory' && this.body !== undefined && this.indexPath !== undefined)
-            await rememberSquarePath(this.location, this.body, this.indexPath).catch(() => 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);
     }
     observation(standingCount, held, participant, now = this.clock()) {
         return { location: this.location, standingCount, held, now,
-            ...(participant === undefined ? {} : { participant }), automaticDeliveryAvailable: this.automaticDelivery && this.body !== undefined };
+            ...(participant === undefined ? {} : { participant }) };
     }
     async contextObservation(participant, control) {
         return (await this.artifact.read(facts => this.observation(inSquareCount(facts), facts.hold().active, participant), control?.signal)).value;
     }
-    handle(name, seat) { return new SqliteSquare.ParticipantHandle(name, this, seat); }
-    // The nested handle can use its resource's private dependencies without widening
-    // the concrete-derived backend contract or copying them into a second context.
+    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.
     static ParticipantHandle = class {
         name;
         owner;
@@ -150,16 +142,12 @@ export class SqliteSquare {
             const control = input === undefined ? operationControl : optionsOrControl;
             let name = this.name, effect = 'unsent';
             let landedId;
-            let waited = false, heldWaitedMs = 0;
+            let heldWaitedMs = 0;
             try {
                 checkControl(control);
                 name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
-                const seat = requireSeat(this.seat, square.body, name);
-                const feed = !options.observe ? undefined : (await square.artifact.read(facts => {
-                    const pendingPublic = directedSuffix(facts, name);
-                    return { pendingPublic, sayNumbers: facts.sayOrdinals(pendingPublic.map(item => item.index)),
-                        perceptions: Object.fromEntries(pendingPublic.map(item => [item.index, 'full'])) };
-                }, 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 {
@@ -200,16 +188,13 @@ export class SqliteSquare {
                         }, control?.signal)).value;
                         landedId = formatActivityId(committed.stored.index);
                         effect = 'landed';
-                        await square.publishIdentity();
-                        const delivery = square.wakeTransport !== undefined && square.location !== 'memory'
-                            ? await deliverPending({ artifact: square.artifact, transport: square.wakeTransport, location: square.location, activity: committed.stored.index, now })
-                                .catch(() => ({ attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 }))
-                            : { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+                        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, held, ownActivityCount, hardCap, ...metadata } = committed;
                         const hint = expressHint(ownActivityCount);
-                        return { activity: toPublicActivity(stored), delivery, waited, ...metadata,
-                            ...(hint === undefined ? {} : { hint }), ...(feed === undefined ? {} : { observation: {
-                                    ...square.observation(standingCount, held, name, now), ownActivityCount, hardCap, ...feed, participant: name,
+                        return { activity: toPublicActivity(stored), ...metadata,
+                            ...(hint === undefined ? {} : { hint }), ...(context === undefined ? {} : { observation: {
+                                    ...square.observation(standingCount, held, name, now), ownActivityCount, hardCap, context, participant: name,
                                 } }) };
                     }
                     catch (error) {
@@ -219,7 +204,6 @@ export class SqliteSquare {
                             throw error;
                         if (error.code === 'held' && heldWaitedMs >= HELD_WAIT_BUDGET_MS)
                             throw error;
-                        waited = true;
                         control?.onProgress?.({ kind: 'waiting', reason: error.code,
                             ...(error.code === 'throttled' ? { delayMs: error.facts?.retryAfterMs ?? 1 } : {}),
                             ...(error.facts?.holder === undefined ? {} : { holder: error.facts.holder }),
@@ -246,13 +230,13 @@ export class SqliteSquare {
             const square = this.owner;
             const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
             checkControl(control);
-            const seat = requireSeat(this.seat, square.body, name), now = square.clock();
+            const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
                 const act = verb === 'listen' ? coreListen(facts, name, target, now) : verb === 'ignore' ? coreIgnore(facts, name, target, now) : coreUnlisten(facts, name, target, now);
                 const activity = act === undefined ? null : toPublicActivity(facts.land(act));
                 return { activity, ...(!options.observe ? {} : { observation: {
                             ...square.observation(inSquareCount(facts), facts.hold().active, name, now), participant: name,
-                            requestedTarget: target, target: activity?.target ?? target,
+                            target: activity?.target ?? target,
                         } }) };
             }, control?.signal)).value;
         }
@@ -278,15 +262,14 @@ export class SqliteSquare {
             const square = this.owner;
             let name = this.name, subject = 'caller';
             let leaseId, seat;
-            let waitStarted = false, replaced = false;
             let selection = options;
             const idle = options.idle ?? 0;
-            const complete = async (caught, stop) => {
+            const complete = async (caught, reason = 'drained') => {
                 const view = caught ?? (await square.artifact.read(facts => observeCatchSelection(facts, name, [], {
                     unseenOnly: true, senders: selection.from, ...(selection.mention === true ? { attentionOnly: true } : {}),
                 }, square.clock()))).value;
-                if (stop === 'empty-now' || stop === undefined)
-                    stop = view.terminalStatus ?? stop;
+                if (reason === 'drained')
+                    reason = view.terminalStatus ?? reason;
                 if (leaseId !== undefined) {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
                     leaseId = undefined;
@@ -298,13 +281,12 @@ export class SqliteSquare {
                     }
                     catch { /* Optional presence cannot erase the completed selection or receipts. */ }
                 }
-                const status = stop === 'already-active' || stop === 'replaced' || stop === 'capped' || stop === 'quorum' ? stop : undefined;
-                return { activities: view.activities.map(activity => ({ ...toPublicActivity(activity), perception: 'full' })),
-                    consumedThrough: view.consumedThrough, remaining: view.remaining, idleExpired: stop === 'stale',
-                    ...(status === undefined ? {} : { status }), ...(view.hint === undefined ? {} : { hint: view.hint }), ...(!options.observe ? {} : { observation: {
+                return { activities: view.activities, remaining: view.remaining, reason,
+                    ...(view.hint === undefined ? {} : { hint: view.hint }), ...(!options.observe ? {} : { observation: {
                             ...square.observation(view.standingCount, view.held, view.participant, view.now), participant: view.participant,
-                            sayNumbers: view.sayNumbers, ownActivityCount: view.ownActivityCount, hardCap: view.hardCap, stop,
-                            ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }), waitStarted, replaced,
+                            deliveryAvailable: view.deliveryAvailable,
+                            ownActivityCount: view.ownActivityCount, hardCap: view.hardCap,
+                            ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }),
                         } }) };
             };
             try {
@@ -319,7 +301,8 @@ export class SqliteSquare {
                 catchLimit(options.limit);
                 const probe = (await square.artifact.read(facts => {
                     name = resolveKnownName(facts, this.name);
-                    seat = requireSeat(this.seat, square.body, name);
+                    seat = this.seat;
+                    assertCurrentSeat(facts, asSeatRef(seat));
                     subject = 'filter';
                     const from = options.from?.map(target => resolveKnownName(facts, target));
                     selection = { ...options, ...(from === undefined ? {} : { from }) };
@@ -331,7 +314,7 @@ export class SqliteSquare {
                 }, control?.signal)).value;
                 if (idle === 0) {
                     const data = probe ?? (await this.catchPage(name, seat, selection, control));
-                    return await complete(data, data.activities.length === 0 ? 'empty-now' : undefined);
+                    return await complete(data);
                 }
                 const watch = {
                     ...(selection.from === undefined ? {} : { participants: [...selection.from] }), ...(options.mention ? { mention: name } : {}),
@@ -341,9 +324,7 @@ export class SqliteSquare {
                 if (start.type === 'active')
                     return await complete(undefined, 'already-active');
                 leaseId = start.leaseId;
-                waitStarted = true;
-                replaced = start.replaced;
-                control?.onProgress?.({ kind: 'catch-started', participant: name, idleMs: idle, replacementRequested: options.replace ?? false, replaced });
+                control?.onProgress?.({ kind: 'catch-started', participant: name, idleMs: idle, replacementRequested: options.replace ?? false, replaced: start.replaced });
                 let quietSince = square.clock(), wasHeld = false, nextHeartbeat = start.heartbeatAt + WATCH_HEARTBEAT_MS;
                 while (true) {
                     checkControl(control);
@@ -368,7 +349,7 @@ export class SqliteSquare {
                     wasHeld = pulse.type === 'held';
                     if (!wasHeld && square.clock() - quietSince >= idle) {
                         const owns = await ownsWatchLease(square.artifact, seat, square.clock(), leaseId, control?.signal);
-                        return await complete(undefined, owns ? 'stale' : 'replaced');
+                        return await complete(undefined, owns ? 'idle' : 'replaced');
                     }
                     const deadline = Math.min(nextHeartbeat, wasHeld ? Infinity : quietSince + idle);
                     await square.artifact.changed(baseline, Math.max(0, deadline - square.clock()), control?.signal);
@@ -386,7 +367,7 @@ export class SqliteSquare {
         async deferDelivery(input, control) {
             checkControl(control);
             const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
-            const square = this.owner, seat = requireSeat(this.seat, square.body, this.name);
+            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() };
@@ -398,7 +379,7 @@ export class SqliteSquare {
             checkControl(control);
             validateDeferralId(id);
             const duration = validateDeferralDuration(durationMs), square = this.owner;
-            const seat = requireSeat(this.seat, square.body, this.name);
+            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() };
@@ -408,55 +389,55 @@ export class SqliteSquare {
         async releaseDeliveryDeferral(id, control) {
             checkControl(control);
             validateDeferralId(id);
-            const square = this.owner, seat = requireSeat(this.seat, square.body, this.name);
+            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;
         }
-        history(query, control) { return this.owner.history(query, control); }
         async lifecycle(verb, body, options, control) {
             if (verb === 'done')
                 validateDoneBody(body);
             const square = this.owner;
             const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
-            const seat = requireSeat(this.seat, square.body, name), now = square.clock();
+            const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
                 const stored = facts.land(verb === 'done' ? coreDone(facts, name, body ?? '', now) : verb === 'hold' ? coreHold(facts, name, body ?? '', now) : coreResume(facts, name, now));
-                return { activity: toPublicActivity(stored), ...(!options.observe ? {} : { observation: {
-                            ...square.observation(inSquareCount(facts), facts.hold().active, name, now), activity: stored,
-                        } }) };
+                return { activity: toPublicActivity(stored), ...(!options.observe ? {} : { observation: square.observation(inSquareCount(facts), facts.hold().active, name, now),
+                    }) };
             }, control?.signal)).value;
         }
         hold(reason, options = {}, control) { return this.lifecycle('hold', reason, options, control); }
         resume(options = {}, control) { return this.lifecycle('resume', undefined, options, control); }
         done(body, options = {}, control) { return this.lifecycle('done', body, options, control); }
     };
-    async participant(requested) {
-        const selected = requested ?? this.defaultParticipant;
-        if (selected !== undefined) {
-            validateName(selected);
-            const seat = this.body === undefined ? undefined : (await this.artifact.read(facts => facts.seat(selected))).value;
-            return this.handle(selected, seat);
-        }
-        if (this.body !== undefined) {
-            const seats = (await this.artifact.read(facts => facts.seatsForBody(this.body))).value;
-            if (seats.length === 1)
-                return this.handle(seats[0].participant, seats[0]);
-            if (seats.length > 1)
-                throw new SquareError('invalid_args', 'Square needs an explicit participant name: this body holds multiple names');
-        }
-        throw new SquareError('invalid_args', 'Square needs one unambiguous participant name');
+    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 join(requested, options = {}, control) {
+    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 body = requireBody(this.body), now = this.clock();
+            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, body, wakeAddress: this.wakeAddress }
-                : { kind: 'takeover', participant: initial.participant, body, expectedGeneration: initial.generation, wakeAddress: this.wakeAddress };
+            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);
@@ -468,10 +449,12 @@ export class SqliteSquare {
                     kind = 'taken-over';
                 }
                 else if (current?.joined) {
-                    if (currentSeat === undefined || !sameBody(currentSeat.body, body))
-                        throw new SquareError('already_joined', `${participantIdentity(participant)} is held by another body; take it over explicitly`);
-                    if (this.wakeAddress !== undefined && canRefreshWakeAddress(currentSeat.wakeAddress, this.wakeAddress))
-                        facts.updateWakeAddress(asSeatRef(currentSeat), this.wakeAddress);
+                    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') {
@@ -483,11 +466,11 @@ export class SqliteSquare {
                 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.participant, seat), activity, kind,
-                    participantCount: facts.roster().filter(item => item.joined || item.done).length,
-                    ...(!options.observe ? {} : { observation: this.observation(inSquareCount(facts), facts.hold().active, seat.participant, now) }) };
+                return { participant: this.handle(seat), activity, kind,
+                    ...(!options.observe ? {} : { observation: { ...this.observation(inSquareCount(facts), facts.hold().active, seat.participant, now),
+                            deliveryAvailable: seat.wakeAddress !== undefined } }) };
             }, control?.signal)).value;
-            await this.publishIdentity();
+            await this.publishSeat(owner);
             if (!options.observe)
                 return committed;
             let entry;
@@ -501,30 +484,27 @@ export class SqliteSquare {
             throw failure(error, { operation: 'join', subject: 'caller', participant: name });
         }
     }
-    async implicitJoin(name, control) {
+    /** Restore only a standing seat; a concurrent departure or takeover cannot be revived. */
+    async reattach(name, { owner, wakeAddress }, control) {
         checkControl(control);
         validateName(name);
-        const body = requireBody(this.body), now = this.clock();
-        const result = (await this.artifact.transactAs({ kind: 'join', participant: name, body, wakeAddress: this.wakeAddress }, facts => {
-            const decision = decideImplicitJoin(facts, name, now);
-            let seat = facts.seat(decision.joinedName);
-            if (decision.joinAct === undefined) {
-                if (decision.state === 'active' && (seat === undefined || !sameBody(seat.body, body)))
-                    throw new SquareError('already_joined', `${participantIdentity(decision.joinedName)} is held by another body`);
-                if (decision.state === 'active' && this.wakeAddress !== undefined && canRefreshWakeAddress(seat.wakeAddress, this.wakeAddress))
-                    facts.updateWakeAddress(asSeatRef(seat), this.wakeAddress);
-            }
-            else {
-                facts.land(decision.joinAct);
-                seat = facts.seat(decision.joinedName);
-                if (seat === undefined)
-                    throw new SquareError('invalid_args', 'The implicit join did not establish its artifact seat.');
-            }
-            return { state: decision.state, ...(decision.state === 'done' ? {} : { participant: this.handle(decision.joinedName, seat) }) };
+        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 (result.participant !== undefined)
-            await this.publishIdentity();
-        return result;
+        if (seat !== null)
+            await this.publishSeat(owner);
+        return seat === null ? null : this.handle(seat);
     }
     async snapshot(control) { return (await this.artifact.read(facts => snapshot(facts, this.clock()), control?.signal)).value; }
     async history(query = {}, control) {
@@ -560,73 +540,70 @@ export class SqliteSquare {
         }, control?.signal)).value;
     }
     async status(options = {}, control) {
-        return (await this.artifact.read(facts => {
-            const seats = this.body === undefined ? [] : facts.seatsForBody(this.body);
-            const viewer = options.viewer ?? this.defaultParticipant ?? (seats.length === 1 ? seats[0].participant : '');
-            return queryStatus(facts, {
-                location: this.location, now: this.clock(), automaticDeliveryAvailable: this.automaticDelivery && this.body !== undefined,
-            }, viewer, options.observe === true);
-        }, control?.signal)).value;
+        return (await this.artifact.read(facts => queryStatus(facts, { location: this.location, now: this.clock() }, options.viewer, options.observe === true), control?.signal)).value;
     }
     async participants(options = {}, control) {
         return (await this.artifact.read(facts => queryParticipants(facts, {
-            location: this.location, now: this.clock(), automaticDeliveryAvailable: this.automaticDelivery && this.body !== undefined,
+            location: this.location, now: this.clock(),
         }, options.observe === true), control?.signal)).value;
     }
     async recovery(requested, control) {
-        const name = (await this.participant(requested).catch(() => undefined))?.name;
-        const facts = name === undefined ? undefined : (await this.artifact.read(facts => recoveryObservation(facts, name, this.clock()), control?.signal).catch(() => undefined))?.value;
-        return facts ?? await this.contextObservation(name, control);
+        const facts = requested === undefined ? undefined : (await this.artifact.read(facts => recoveryObservation(facts, requested, this.clock()), control?.signal).catch(() => undefined))?.value;
+        return facts ?? await this.contextObservation(requested, control);
     }
     stream(options, control) {
         // A path stream follows replacements independently of this connection's inode
         // and lifetime. Only explicit artifact readers borrow an existing port.
         return streamSquare(this.location, options, control);
     }
-    async recognize() {
-        if (this.body === undefined)
-            return [];
-        const candidates = (await this.artifact.read(facts => facts.seatsForBody(this.body))).value;
-        return candidates.map(seat => this.handle(seat.participant, seat));
+    async seatsOf(owner) {
+        requireOwner(owner);
+        return (await this.artifact.read(facts => facts.seatsForOwner(owner).map(({ participant: name, generation, attachment }) => ({ name, generation, attachment })))).value;
     }
-    close() { return this.ownsArtifact ? this.artifact.close() : Promise.resolve(); }
-    async cancelDeliveries(name, expectedGeneration) {
-        const body = this.body;
-        if (body === undefined)
-            return false;
+    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;
-        if (seat === undefined || seat.generation !== expectedGeneration || !sameBody(seat.body, body))
-            return false;
-        return this.artifact.cancelDeliveries(asSeatRef(seat));
+        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 endOwnedSession(name, sessionId, expectedGeneration, body) {
-        const captured = (await this.artifact.read(facts => facts.seat(name))).value;
-        if (captured === undefined || captured.body.session !== sessionId || (body !== undefined && !sameBody(captured.body, body))
-            || (expectedGeneration !== undefined && captured.generation !== expectedGeneration))
+    async endHeld(name, identity) {
+        const captured = await this.heldSeat(name, identity);
+        if (captured === undefined)
             return null;
-        return (await this.artifact.transactAs(participantAuthority(captured), facts => {
+        return (await this.artifact.transactAs({ kind: 'host-cleanup', seat: asSeatRef(captured) }, facts => {
             const current = facts.seat(name);
-            if (current === undefined || current.generation !== captured.generation || !sameBody(current.body, captured.body))
+            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(localSquareLocation(input)); }
-export function migrateSquare(input, control) { checkControl(control); const env = input.env ?? process.env; return migrateSquareFile(localSquareLocation(input), control?.signal, env); }
+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)
-        localSquareLocation(input);
+        squareLocation(input);
     const env = { ...(input.env ?? process.env) };
     return discoverSquares(input.cwd ?? process.cwd(), options, control, { clock: squareClock(env, input.clock) });
 }
-export async function inbox(input, identity, options = {}, control) {
+export async function inbox(input, owner, options = {}, control) {
     checkControl(control);
+    requireOwner(owner);
     const env = { ...(input.env ?? process.env) }, 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 query = typeof identity === 'string' ? { sessionId: identity, env } : { body: identity, env };
-    const rows = await sessionInboxCounts(query, control?.signal);
+    const rows = await sessionInboxCounts({ owner, env }, 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));

package/dist/square-api.d.ts

@@ -1,14 +1,19 @@
-import type { SquareBackend } from './square-backend.js';
-import type { SquareAtInput, SquareBuildInput, OperationControl } from './square-facade.js';
+import { SqliteSquare } from './sqlite-square.js';
+import { type Owner } from './model.js';
+import type { OperationControl, Participant, SquareAtInput, SquareBuildInput } from './square-facade.js';
+export type Square = SqliteSquare;
+export declare const Square: {
+    at: (input: SquareAtInput, control?: OperationControl) => Promise<SqliteSquare>;
+    build: (input: SquareBuildInput, control?: OperationControl) => Promise<SqliteSquare>;
+    inMemory: typeof SqliteSquare.inMemory;
+};
+export { requireOwner, requireJoinName } from './seats.js';
 export type * from './square-facade.js';
 export { squareLocation } from './square-location.js';
+export declare function selectOwnSeat(square: Pick<SqliteSquare, 'participant' | 'seatsOf'>, owner: Owner | undefined, name?: string): Promise<Participant>;
+export declare function selectOwnSeat(square: Pick<SqliteSquare, 'participant' | 'seatsOf'>, owner: Owner | undefined, name: string | undefined, options: {
+    readonly optional: true;
+}): Promise<Participant | undefined>;
 export { ACTIVITY_METADATA_MAX_BYTES } from './model.js';
+export { localUserOwner, harnessOwner, decodeHarnessOwner } from './owner.js';
 export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, HELD_WAIT_BUDGET_MS, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, migrateSquare, discover, inbox } from './sqlite-square.js';
-/** The same structural resource regardless of persistence or transport. */
-export interface Square extends SquareBackend {
-}
-export declare const Square: {
-    at(input: SquareAtInput, control?: OperationControl): Promise<Square>;
-    build(input: SquareBuildInput, control?: OperationControl): Promise<Square>;
-    inMemory(input: Omit<SquareBuildInput, "path" | "resources">): Square;
-};