@astrosheep/square 0.3.93 → 0.3.95

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 { 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;
-};
+export { localUserOwner, harnessOwner, decodeHarnessOwner } from './owner.js';
+export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, 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';

package/dist/square-api.js

@@ -1,26 +1,30 @@
 import { SqliteSquare } from './sqlite-square.js';
-import { squareLocation, backendConfiguration, parseSquareLocation } from './square-location.js';
-import { openStdioSquare } from './square-stdio.js';
+import { SquareError } from './model.js';
+import { requireOwner } from './seats.js';
+import { createDefaultWakeTransport } from './notifications.js';
+export const Square = { at: async (input, control) => SqliteSquare.at({ ...input, wakeTransport: await resolveWakeTransport(input) }, control),
+    build: async (input, control) => SqliteSquare.build({ ...input, wakeTransport: await resolveWakeTransport(input) }, control), inMemory: SqliteSquare.inMemory };
+const resolveWakeTransport = (input) => input.wakeTransport !== undefined
+    ? Promise.resolve(input.wakeTransport)
+    : createDefaultWakeTransport(input.env ?? process.env).catch(() => undefined);
+export { requireOwner, requireJoinName } from './seats.js';
 export { squareLocation } from './square-location.js';
+export async function selectOwnSeat(square, owner, name, options) {
+    if (owner === undefined && options?.optional && name === undefined)
+        return undefined;
+    const caller = requireOwner(owner);
+    if (name !== undefined)
+        return square.participant(name, { owner: caller });
+    const seats = (await square.seatsOf(caller)).filter(seat => seat.attachment === 'attached');
+    if (seats.length !== 1) {
+        if (options?.optional)
+            return undefined;
+        throw new SquareError('invalid_args', seats.length > 1
+            ? 'Square needs an explicit participant name: this owner holds multiple names'
+            : 'Square needs one unambiguous participant name');
+    }
+    return square.participant(seats[0].name, { owner: caller });
+}
 export { ACTIVITY_METADATA_MAX_BYTES } from './model.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';
-export const Square = {
-    async at(input, control) {
-        const captured = { ...input, cwd: input.cwd ?? process.cwd(), env: { ...(input.env ?? process.env) } };
-        const location = squareLocation(captured);
-        const selected = parseSquareLocation(location);
-        return selected.kind === 'local' ? SqliteSquare.at({ ...captured, path: location }, control)
-            : openStdioSquare(location, selected, captured, await backendConfiguration(captured), undefined, control);
-    },
-    async build(input, control) {
-        const captured = { ...input, cwd: input.cwd ?? process.cwd(), env: { ...(input.env ?? process.env) } };
-        const location = squareLocation(captured);
-        const selected = parseSquareLocation(location);
-        return selected.kind === 'local' ? SqliteSquare.build({ ...captured, path: location }, control)
-            : openStdioSquare(location, selected, captured, await backendConfiguration(captured), {
-                markdown: input.markdown, hardCap: input.hardCap, throttlePerMinute: input.throttlePerMinute,
-                template: input.template, force: input.force,
-            }, control);
-    },
-    inMemory(input) { return SqliteSquare.inMemory(input); },
-};
+export { localUserOwner, harnessOwner, decodeHarnessOwner } from './owner.js';
+export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, 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';

package/dist/square-core.d.ts

@@ -29,15 +29,6 @@ export type Act = {
     mentions?: readonly Participant[];
     reach?: Reach;
     reply?: number;
-} | {
-    kind: 'hold';
-    actor?: Participant;
-    at?: number;
-    body?: string;
-} | {
-    kind: 'resume';
-    actor?: Participant;
-    at?: number;
 } | {
     kind: 'read';
     actor: Participant;
@@ -59,9 +50,4 @@ export type Act = {
     target: Participant;
     at?: number;
 };
-export declare function audienceOf(say: {
-    body?: string;
-    mentions?: readonly Participant[];
-    reach?: Reach;
-}): Audience;
 export declare function audienceIncludes(audience: Audience, name: string): boolean;

package/dist/square-core.js

@@ -13,15 +13,6 @@ export function parseActivityId(value) {
     const index = Number(value.slice(4));
     return Number.isSafeInteger(index) ? index : undefined;
 }
-export function audienceOf(say) {
-    if (say.reach === 'bell')
-        return { kind: 'bell' };
-    const names = [];
-    for (const name of say.mentions ?? [])
-        if (!names.some((existing) => sameName(existing, name)))
-            names.push(name);
-    return { kind: 'mentions', names };
-}
 export function audienceIncludes(audience, name) {
     return audience.kind === 'bell' || audience.names.some((mentioned) => sameName(mentioned, name));
 }

package/dist/square-domain.d.ts

@@ -1,5 +1,5 @@
 import { type Seat, type StoredAct } from './model.js';
-import type { ArtifactWriteAuthority, AttentionFact, LandedRecipient, ParticipantFact, SquareRead, SquareWrite } from './ports.js';
+import type { ArtifactWriteAuthority, AttentionFact, LandedRecipient, ParticipantFact, SeatRef, SquareRead, SquareWrite } from './ports.js';
 export interface LandingEffect {
     readonly activity: StoredAct;
     readonly participant?: ParticipantFact;
@@ -21,7 +21,7 @@ export interface LandingFacts {
 /** The single landing transition, shared by both adapters and explicit rebuild. */
 export declare function deriveLanding(activity: StoredAct, facts: LandingFacts): LandingEffect;
 export declare function landingFacts(read: SquareRead, activity: StoredAct): LandingFacts;
-export interface LandingWriter extends Pick<SquareWrite, 'markSeen' | 'putLease' | 'removeLease' | 'updateWakeAddress' | 'cancelThrough' | 'putDeliveryDeferral' | 'renewDeliveryDeferral' | 'releaseDeliveryDeferral' | 'claimDelivery' | 'prepareDelivery' | 'completeDelivery' | 'observeNativeDelivery'> {
+export interface LandingWriter extends Pick<SquareWrite, 'markSeen' | 'putLease' | 'removeLease' | 'updateWakeAddress' | 'reattachSeat' | 'detachSeat' | 'cancelThrough' | 'putDeliveryDeferral' | 'renewDeliveryDeferral' | 'releaseDeliveryDeferral' | 'claimDelivery' | 'prepareDelivery' | 'completeDelivery' | 'observeNativeDelivery'> {
     /** Artifact-private seat persistence used only by this gate's lifecycle transition. */
     storeSeat(seat: Seat): boolean;
     removeSeat(seat: import('./ports.js').SeatRef): boolean;
@@ -31,5 +31,7 @@ export interface SquareWriteGate {
     readonly facts: SquareWrite;
     complete(): void;
 }
+/** Read probes and writes share the same captured-coordinate and attachment fence. */
+export declare function assertCurrentSeat(read: SquareRead, expected: SeatRef, allowDetached?: boolean): void;
 /** The artifact transaction supplies one captured authority; every mutation checks it here. */
 export declare function wrapSquareWrite(read: SquareRead, writes: LandingWriter, authority: ArtifactWriteAuthority): SquareWriteGate;

package/dist/square-domain.js

@@ -1,35 +1,13 @@
-import { SquareError, formatActivityId, parseActivityId, sameBody, sameName, validateBody, validateName } from './model.js';
+import { SquareError, formatActivityId, parseActivityId, sameName, validateOwner, validateName } from './model.js';
+import { resolveAudience } from './attention.js';
 /** The single landing transition, shared by both adapters and explicit rebuild. */
 export function deriveLanding(activity, facts) {
-    const audience = [];
-    if (activity.kind === 'say') {
-        const add = (requested, route) => {
-            const recipient = facts.standing.find((item) => sameName(item.name, requested))?.name;
-            if (recipient === undefined || sameName(recipient, activity.actor)
-                || audience.some((item) => sameName(item.recipient, recipient)))
-                return;
-            if (activity.reach !== 'bell' && facts.incoming.some((item) => item.kind === 'ignore' && sameName(item.listener, recipient)))
-                return;
-            audience.push({ recipient, route });
-        };
-        if (activity.reach === 'bell') {
-            for (const peer of facts.standing)
-                add(peer.name, 'bell');
-        }
-        else {
-            for (const mention of activity.mentions ?? [])
-                add(mention, 'mention');
-            if (facts.replyAuthor !== undefined)
-                add(facts.replyAuthor, 'reply');
-            for (const peer of facts.standing) {
-                if (facts.incoming.some((item) => item.kind === 'listen' && sameName(item.listener, peer.name)))
-                    add(peer.name, 'attention');
-            }
-        }
-    }
+    const audience = activity.kind === 'say' ? resolveAudience({
+        actor: activity.actor, recipients: facts.standing.map((item) => item.name),
+        mentions: activity.mentions, replyAuthor: facts.replyAuthor, reach: activity.reach,
+        incoming: facts.incoming, sameIdentity: sameName,
+    }) : [];
     const actor = activity.actor;
-    if (actor === undefined)
-        return { activity, audience };
     const previous = facts.actor ?? { name: actor, firstIndex: activity.index, joined: false, done: false, sayCount: 0 };
     const participant = {
         ...previous,
@@ -57,7 +35,7 @@ export function deriveLanding(activity, facts) {
 }
 export function landingFacts(read, activity) {
     return {
-        actor: activity.actor === undefined ? undefined : read.participant(activity.actor),
+        actor: read.participant(activity.actor),
         standing: activity.kind === 'say' ? read.roster().filter((item) => item.joined) : [],
         incoming: activity.kind === 'say' ? read.incomingAttention(activity.actor) : [],
         outgoing: activity.kind === 'listen' || activity.kind === 'ignore' || activity.kind === 'unlisten' ? read.attention(activity.actor) : [],
@@ -68,31 +46,38 @@ function validateGeneration(value) {
     if (typeof value !== 'string' || parseActivityId(value) === undefined)
         throw new SquareError('invalid_args', 'Artifact authority requires a valid join generation.');
 }
+/** Read probes and writes share the same captured-coordinate and attachment fence. */
+export function assertCurrentSeat(read, expected, allowDetached = false) {
+    const current = read.seat(expected.participant);
+    if (current === undefined || current.owner !== expected.owner || current.generation !== expected.generation)
+        throw new SquareError('already_joined', 'This participant seat has been replaced.');
+    if (!allowDetached && current.attachment !== 'attached')
+        throw new SquareError('already_joined', 'This participant is away; join again before writing.', { reason: 'needs_seat', activityUnsent: true });
+}
 /** The artifact transaction supplies one captured authority; every mutation checks it here. */
 export function wrapSquareWrite(read, writes, authority) {
     if (authority === undefined || typeof authority !== 'object' || authority === null)
         throw new SquareError('invalid_args', 'Artifact writes require an explicit authority.');
     const { applyLanding, ...mutations } = writes;
-    const expectedName = authority.kind === 'participant' ? authority.seat?.participant : authority.participant;
-    if (!['participant', 'join', 'takeover'].includes(authority.kind) || typeof expectedName !== 'string')
+    const seated = authority.kind === 'participant' || authority.kind === 'host-cleanup';
+    const expectedName = seated ? authority.seat?.participant : authority.participant;
+    if (!['participant', 'host-cleanup', 'join', 'takeover'].includes(authority.kind) || typeof expectedName !== 'string')
         throw new SquareError('invalid_args', 'Artifact write authority is malformed.');
     validateName(expectedName);
-    if (authority.kind === 'participant') {
-        validateBody(authority.seat.body);
+    if (seated) {
+        validateOwner(authority.seat.owner);
         validateGeneration(authority.seat.generation);
     }
     else {
-        validateBody(authority.body);
+        validateOwner(authority.owner);
         if (authority.kind === 'takeover')
             validateGeneration(authority.expectedGeneration);
     }
-    const assertSeat = (seat, expected = authority.kind === 'participant' ? authority.seat : undefined) => {
+    const assertSeat = (seat, expected = authority.kind === 'participant' ? authority.seat : undefined, allowDetached = false) => {
         if (expected === undefined || !sameName(expected.participant, seat.participant)
-            || seat.generation !== expected.generation || !sameBody(seat.body, expected.body))
+            || seat.generation !== expected.generation || seat.owner !== expected.owner)
             throw new SquareError('already_joined', 'This write needs the current participant seat.');
-        const current = read.seat(seat.participant);
-        if (current === undefined || !sameBody(current.body, expected.body) || current.generation !== expected.generation)
-            throw new SquareError('already_joined', 'This participant seat has been replaced.');
+        assertCurrentSeat(read, expected, allowDetached);
     };
     const assertParticipant = (name, generation) => {
         if (authority.kind !== 'participant')
@@ -104,11 +89,14 @@ export function wrapSquareWrite(read, writes, authority) {
     if (authority.kind === 'participant') {
         assertSeat(authority.seat);
     }
+    else if (authority.kind === 'host-cleanup') {
+        // A late host cleanup is allowed to inspect a stale coordinate and return a no-op.
+    }
     else if (authority.kind === 'join') {
         const participant = read.participant(expectedName), seat = read.seat(expectedName);
         if (participant?.joined) {
-            if (seat === undefined || !sameBody(seat.body, authority.body))
-                throw new SquareError('already_joined', `${expectedName} is held by another body; take it over explicitly`);
+            if (seat === undefined || seat.owner !== authority.owner)
+                throw new SquareError('already_joined', `${expectedName} is held by another owner; take it over explicitly`);
             reconnectSeat = seat;
         }
     }
@@ -131,6 +119,11 @@ export function wrapSquareWrite(read, writes, authority) {
                 if (activity.kind === 'join')
                     throw new SquareError('invalid_args', 'A participant seat can only be re-established by join.');
             }
+            else if (authority.kind === 'host-cleanup') {
+                assertSeat(authority.seat, authority.seat, true);
+                if (activity.kind !== 'done')
+                    throw new SquareError('invalid_args', 'Host cleanup may only end membership.');
+            }
             else if (authority.kind === 'join') {
                 if (activity.kind !== 'join')
                     throw new SquareError('invalid_args', 'A new seat must be established by its join activity.');
@@ -157,27 +150,28 @@ export function wrapSquareWrite(read, writes, authority) {
             const stored = { ...activity, index };
             applyLanding(deriveLanding(stored, landingFacts(read, stored)));
             if (stored.kind === 'join') {
-                if (authority.kind === 'participant')
-                    throw new SquareError('invalid_args', 'Participant authority cannot establish a seat.');
+                if (seated)
+                    throw new SquareError('invalid_args', 'Seat authority cannot establish another seat.');
                 const seat = {
                     participant: stored.actor,
-                    body: authority.body,
+                    owner: authority.owner,
                     generation: formatActivityId(stored.index),
+                    attachment: 'attached',
                     ...(authority.wakeAddress === undefined ? {} : { wakeAddress: authority.wakeAddress }),
                 };
                 mutations.storeSeat(seat);
                 const established = read.seat(seat.participant);
-                if (established === undefined || !sameBody(established.body, seat.body) || established.generation !== seat.generation)
+                if (established === undefined || established.owner !== seat.owner || established.generation !== seat.generation)
                     throw new SquareError('invalid_args', 'The join activity did not establish its artifact seat.');
                 if (authority.kind === 'takeover')
                     takeoverPhase = 'joined';
             }
-            else if (stored.kind === 'done' && authority.kind === 'participant') {
+            else if (stored.kind === 'done' && seated) {
                 if (!mutations.removeSeat(authority.seat))
                     throw new SquareError('already_joined', 'The participant seat changed while it was being completed.');
             }
             else if (stored.kind === 'done' && authority.kind === 'takeover') {
-                if (captured === undefined || !mutations.removeSeat({ participant: expectedName, body: captured.body, generation: captured.generation }))
+                if (captured === undefined || !mutations.removeSeat({ participant: expectedName, owner: captured.owner, generation: captured.generation }))
                     throw new SquareError('already_joined', 'The participant seat changed while takeover was completing it.');
                 takeoverPhase = 'done';
             }
@@ -185,13 +179,32 @@ export function wrapSquareWrite(read, writes, authority) {
             return lastActivity;
         },
         updateWakeAddress(seat, wakeAddress) {
-            assertSeat(seat, authority.kind === 'join' ? reconnectSeat : undefined);
+            if (authority.kind !== 'join' && authority.kind !== 'participant')
+                throw new SquareError('already_joined', 'This write needs the current participant seat.');
+            assertSeat(seat, authority.kind === 'join' ? reconnectSeat : authority.seat);
             return mutations.updateWakeAddress(seat, wakeAddress);
         },
+        reattachSeat(seat, wakeAddress) {
+            if (authority.kind !== 'join')
+                throw new SquareError('already_joined', 'Reattachment requires a same-owner join.');
+            assertSeat(seat, reconnectSeat, true);
+            return mutations.reattachSeat(seat, wakeAddress);
+        },
+        detachSeat(seat) {
+            if (authority.kind !== 'host-cleanup')
+                throw new SquareError('already_joined', 'Detach requires captured host cleanup authority.');
+            const current = read.seat(seat.participant), expected = authority.seat;
+            if (!sameName(seat.participant, expected.participant) || seat.owner !== expected.owner || seat.generation !== expected.generation)
+                throw new SquareError('already_joined', 'Host cleanup does not match its captured seat.');
+            if (current === undefined || current.attachment !== 'attached' || current.owner !== expected.owner
+                || current.generation !== expected.generation)
+                return false;
+            return mutations.detachSeat(seat);
+        },
         cancelThrough(seat, through) {
             assertSeat(seat);
-            if (!Number.isSafeInteger(through) || through < 0 || through > read.header().lastActIndex || read.activity(through) === undefined)
-                throw new SquareError('invalid_args', 'Cancellation boundary must name an existing activity at or below the current head.');
+            if (!Number.isSafeInteger(through) || through < 0 || through >= read.header().nextActIndex)
+                throw new SquareError('invalid_args', 'Cancellation boundary must be an assigned activity index below the allocator.');
             return mutations.cancelThrough(seat, through);
         },
         markSeen(name, indexes, at) {
@@ -242,7 +255,7 @@ export function wrapSquareWrite(read, writes, authority) {
                 return;
             const seat = read.seat(expectedName);
             if (takeoverPhase !== 'joined' || lastActivity?.kind !== 'join' || seat === undefined
-                || !sameBody(seat.body, authority.body) || seat.generation !== formatActivityId(lastActivity.index))
+                || seat.owner !== authority.owner || seat.generation !== formatActivityId(lastActivity.index))
                 throw new SquareError('already_joined', 'Takeover did not complete its replacement join.');
         },
     };