@astrosheep/square 0.3.94 → 0.3.96

package/dist/runtime.d.ts

@@ -4,7 +4,6 @@ export declare const WATCH_HEARTBEAT_MS: number;
 export declare const WATCH_STALE_MS: number;
 export declare const THROTTLE_WINDOW_MS: number;
 export declare const UNREAD_BLOCK_GRACE_MS: number;
-export declare const HELD_WAIT_BUDGET_MS: number;
 export declare const FACT_PAGE_SIZE = 100;
 export declare function inSquareCount(facts: SquareRead): number;
 export declare function terminalStatusFor(current: ParticipantFact | undefined, hardCap: number | null, counts: ParticipantCounts): 'capped' | 'quorum' | undefined;

package/dist/runtime.js

@@ -12,7 +12,6 @@ export const WATCH_HEARTBEAT_MS = parseIntegerEnv('SQUARE_WATCH_HEARTBEAT_MS', 6
 export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', 180000);
 export const THROTTLE_WINDOW_MS = parseIntegerEnv('SQUARE_THROTTLE_WINDOW_MS', 60000);
 export const UNREAD_BLOCK_GRACE_MS = parseIntegerEnv('SQUARE_UNREAD_BLOCK_GRACE_MS', 90000);
-export const HELD_WAIT_BUDGET_MS = parseIntegerEnv('SQUARE_HELD_WAIT_BUDGET_MS', 10 * 60 * 1000);
 export const FACT_PAGE_SIZE = 100;
 export function inSquareCount(facts) { return facts.participantCounts().joined; }
 export function terminalStatusFor(current, hardCap, counts) {
@@ -33,8 +32,8 @@ export function readCursor(facts, name) {
     const boundary = facts.participant(name)?.lastJoinIndex ?? -1;
     const block = facts.directed(name, { afterIndex: boundary, unseenOnly: true }, { edge: 'oldest', limit: 1 }).items[0]?.index;
     const last = facts.activityHeads({
-        afterIndex: boundary, ...(block === undefined ? {} : { beforeIndex: block }), actorRequired: true,
-        kinds: ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore', 'unlisten'],
+        afterIndex: boundary, ...(block === undefined ? {} : { beforeIndex: block }),
+        kinds: ['join', 'done', 'say', 'listen', 'ignore', 'unlisten'],
     }, { edge: 'newest', limit: 1 }).items[0]?.index;
     return Math.max(boundary, last ?? boundary);
 }

package/dist/sqlite-square.d.ts

@@ -1,10 +1,9 @@
 import { type Owner } from './model.js';
-import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, LifecycleResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity } from './square-facade.js';
+import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, LifecycleResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity, ChannelSendInput, ChannelSendResult } from './square-facade.js';
 export type * from './square-facade.js';
 export { createSquareResourceOwner } from './artifact.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
-export { HELD_WAIT_BUDGET_MS } from './runtime.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';
 export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
@@ -27,6 +26,8 @@ export declare class SqliteSquare {
     private contextObservation;
     private handle;
     private static readonly ParticipantHandle;
+    /** Direct messages use explicit recipients, not participant expression admission or body attention. */
+    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
     participant(name: string, { owner }: {
         readonly owner: Owner;
     }): Promise<Participant>;

package/dist/sqlite-square.js

@@ -1,16 +1,17 @@
-import { formatActivityId } from './square-core.js';
+import { formatActivityId, MAX_IDENTITY_SET_SIZE } 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 } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-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 { activityMetadataHasContent, InternalSquareError, SquareError, isSquareError, nameKey, sameName, validateActivityMetadata, validateName } from './model.js';
+import { coreDone, coreIgnore, coreListen, coreListening, coreUnlisten, 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, snapshot, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
@@ -26,7 +27,6 @@ import { streamSquare } from './stream.js';
 export { createSquareResourceOwner } from './artifact.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
-export { HELD_WAIT_BUDGET_MS } from './runtime.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) {
@@ -115,12 +115,12 @@ export class SqliteSquare {
         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,
+    observation(standingCount, participant, now = this.clock()) {
+        return { location: this.location, standingCount, now,
             ...(participant === undefined ? {} : { participant }) };
     }
     async contextObservation(participant, control) {
-        return (await this.artifact.read(facts => this.observation(inSquareCount(facts), facts.hold().active, participant), control?.signal)).value;
+        return (await this.artifact.read(facts => this.observation(inSquareCount(facts), participant), control?.signal)).value;
     }
     handle(seat) { return new SqliteSquare.ParticipantHandle(seat.participant, this, seat); }
     // The nested handle uses its resource's private dependencies without copying
@@ -134,6 +134,7 @@ export class SqliteSquare {
             this.owner = owner;
             this.seat = seat;
         }
+        get generation() { return this.seat.generation; }
         async express(bodyOrInput, optionsOrControl = {}, operationControl) {
             const square = this.owner;
             const input = typeof bodyOrInput === 'object' && bodyOrInput !== null ? bodyOrInput : undefined;
@@ -142,7 +143,6 @@ export class SqliteSquare {
             const control = input === undefined ? operationControl : optionsOrControl;
             let name = this.name, effect = 'unsent';
             let landedId;
-            let heldWaitedMs = 0;
             try {
                 checkControl(control);
                 name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
@@ -167,12 +167,9 @@ export class SqliteSquare {
                             // Decoding selected rows is storage work, not proof of safe admission refusal.
                             const proposed = decideAct(facts, { name, body, force: options.force ?? false, metadata: options.metadata, now, mentions: options.mentions,
                                 ...(options.reach === undefined ? {} : { reach: options.reach }), ...(options.noMention === undefined ? {} : { noMention: options.noMention }), ...(reply === undefined ? {} : { reply }) });
-                            const holder = proposed.type === 'held' ? facts.hold().actor : undefined;
                             const decision = rejectUnsentActivity(() => {
                                 if (proposed.type === 'blocked')
                                     throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending: proposed.activitySummaries.reduce((count, summary) => count + summary.count, 0) });
-                                if (proposed.type === 'held')
-                                    throw new SquareError('held', 'The square is held', { ...(holder === undefined ? {} : { holder }), ...(proposed.reason === undefined ? {} : { holdReason: proposed.reason }) });
                                 if (proposed.type === 'capped')
                                     throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
                                 if (proposed.type === 'throttled')
@@ -181,7 +178,7 @@ 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), held: facts.hold().active,
+                            return { stored: facts.land(decision.act), standingCount: inSquareCount(facts),
                                 ownActivityCount: facts.participant(name).sayCount, hardCap: facts.header().hardCap,
                                 ...(decision.unmatchedMentions === undefined ? {} : { unmatchedMentions: decision.unmatchedMentions }),
                                 ...(decision.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: decision.replyAuthorNotHere }) };
@@ -190,33 +187,20 @@ export class SqliteSquare {
                         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, held, ownActivityCount, hardCap, ...metadata } = committed;
+                        const { stored, standingCount, ownActivityCount, hardCap, ...metadata } = committed;
                         const hint = expressHint(ownActivityCount);
                         return { activity: toPublicActivity(stored), ...metadata,
                             ...(hint === undefined ? {} : { hint }), ...(context === undefined ? {} : { observation: {
-                                    ...square.observation(standingCount, held, name, now), ownActivityCount, hardCap, context, participant: name,
+                                    ...square.observation(standingCount, name, now), ownActivityCount, hardCap, context, participant: name,
                                 } }) };
                     }
                     catch (error) {
                         if (effect !== 'landed' && isSquareError(error) && error.facts?.activityUnsent === true)
                             effect = 'unsent';
-                        if (effect === 'landed' || !isSquareError(error) || options.noWait || (error.code !== 'held' && error.code !== 'throttled'))
+                        if (effect === 'landed' || !isSquareError(error) || options.noWait || error.code !== 'throttled')
                             throw error;
-                        if (error.code === 'held' && heldWaitedMs >= HELD_WAIT_BUDGET_MS)
-                            throw error;
-                        control?.onProgress?.({ kind: 'waiting', reason: error.code,
-                            ...(error.code === 'throttled' ? { delayMs: error.facts?.retryAfterMs ?? 1 } : {}),
-                            ...(error.facts?.holder === undefined ? {} : { holder: error.facts.holder }),
-                            ...(error.facts?.holdReason === undefined ? {} : { holdReason: error.facts.holdReason }) });
-                        if (error.code === 'throttled')
-                            await sleep(error.facts?.retryAfterMs ?? 1, undefined, { signal: control?.signal });
-                        else {
-                            const started = Date.now();
-                            const observation = await square.artifact.read(facts => facts.hold().active, control?.signal);
-                            if (observation.value)
-                                await square.artifact.changed(observation.version, Math.max(1, HELD_WAIT_BUDGET_MS - heldWaitedMs), control?.signal);
-                            heldWaitedMs += Date.now() - started;
-                        }
+                        control?.onProgress?.({ kind: 'waiting', reason: 'throttled', delayMs: error.facts?.retryAfterMs ?? 1 });
+                        await sleep(error.facts?.retryAfterMs ?? 1, undefined, { signal: control?.signal });
                     }
                 }
             }
@@ -235,7 +219,7 @@ export class SqliteSquare {
                 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,
+                            ...square.observation(inSquareCount(facts), name, now), participant: name,
                             target: activity?.target ?? target,
                         } }) };
             }, control?.signal)).value;
@@ -247,7 +231,7 @@ export class SqliteSquare {
             const square = this.owner;
             return (await square.artifact.read(facts => {
                 const name = resolveKnownName(facts, this.name);
-                return { listening: coreListening(facts, name), ...(!options.observe ? {} : { observation: square.observation(inSquareCount(facts), facts.hold().active, name) }) };
+                return { listening: coreListening(facts, name), ...(!options.observe ? {} : { observation: square.observation(inSquareCount(facts), name) }) };
             }, control?.signal)).value;
         }
         /** Receipt selection rechecks the lease inside the writer, not at its last heartbeat. */
@@ -283,7 +267,7 @@ export class SqliteSquare {
                 }
                 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,
+                            ...square.observation(view.standingCount, view.participant, view.now), participant: view.participant,
                             deliveryAvailable: view.deliveryAvailable,
                             ownActivityCount: view.ownActivityCount, hardCap: view.hardCap,
                             ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }),
@@ -325,7 +309,8 @@ export class SqliteSquare {
                     return await complete(undefined, 'already-active');
                 leaseId = start.leaseId;
                 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;
+                const quietSince = square.clock();
+                let nextHeartbeat = start.heartbeatAt + WATCH_HEARTBEAT_MS;
                 while (true) {
                     checkControl(control);
                     // Arm before selecting: a commit during selection must not be missed.
@@ -337,21 +322,16 @@ export class SqliteSquare {
                         return await complete(undefined, pulse.status);
                     if (pulse.heartbeatAt !== undefined)
                         nextHeartbeat = pulse.heartbeatAt + WATCH_HEARTBEAT_MS;
-                    if (pulse.type === 'sleep') {
-                        const caught = await this.catchPage(name, seat, selection, control, leaseId);
-                        if (caught === null)
-                            return await complete(undefined, 'replaced');
-                        if (caught.activities.length > 0)
-                            return await complete(caught);
-                    }
-                    if (pulse.type === 'held' || wasHeld)
-                        quietSince = square.clock();
-                    wasHeld = pulse.type === 'held';
-                    if (!wasHeld && square.clock() - quietSince >= idle) {
+                    const caught = await this.catchPage(name, seat, selection, control, leaseId);
+                    if (caught === null)
+                        return await complete(undefined, 'replaced');
+                    if (caught.activities.length > 0)
+                        return await complete(caught);
+                    if (square.clock() - quietSince >= idle) {
                         const owns = await ownsWatchLease(square.artifact, seat, square.clock(), leaseId, control?.signal);
                         return await complete(undefined, owns ? 'idle' : 'replaced');
                     }
-                    const deadline = Math.min(nextHeartbeat, wasHeld ? Infinity : quietSince + idle);
+                    const deadline = Math.min(nextHeartbeat, quietSince + idle);
                     await square.artifact.changed(baseline, Math.max(0, deadline - square.clock()), control?.signal);
                 }
             }
@@ -392,22 +372,68 @@ export class SqliteSquare {
             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;
         }
-        async lifecycle(verb, body, options, control) {
-            if (verb === 'done')
-                validateDoneBody(body);
+        async done(body, options = {}, control) {
+            validateDoneBody(body);
             const square = this.owner;
             const name = (await square.artifact.read(facts => resolveKnownName(facts, this.name), control?.signal)).value;
             const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const 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),
+                const stored = facts.land(coreDone(facts, name, body ?? '', now));
+                return { activity: toPublicActivity(stored), ...(!options.observe ? {} : { observation: square.observation(inSquareCount(facts), name, now),
                     }) };
             }, control?.signal)).value;
         }
-        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); }
     };
+    /** 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 || facts.seat(recipient.name)?.attachment !== 'attached')
+                    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 }) };
+    }
     async participant(name, { owner }) {
         validateName(name);
         requireOwner(owner);
@@ -467,7 +493,7 @@ export class SqliteSquare {
                 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), facts.hold().active, seat.participant, now),
+                    ...(!options.observe ? {} : { observation: { ...this.observation(inSquareCount(facts), seat.participant, now),
                             deliveryAvailable: seat.wakeAddress !== undefined } }) };
             }, control?.signal)).value;
             await this.publishSeat(owner);
@@ -535,7 +561,7 @@ export class SqliteSquare {
                 if (indexes.includes(anchor))
                     (presenceAnchors[anchor] ??= []).push(participant.name);
             }
-            return { activities, observation: { ...this.observation(inSquareCount(facts), facts.hold().active), ...selected,
+            return { activities, observation: { ...this.observation(inSquareCount(facts)), ...selected,
                     sayNumbers: facts.sayOrdinals(indexes), presenceAnchors } };
         }, control?.signal)).value;
     }

package/dist/square-api.d.ts

@@ -16,4 +16,4 @@ export declare function selectOwnSeat(square: Pick<SqliteSquare, 'participant' |
 }): 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';
+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

@@ -27,4 +27,4 @@ export async function selectOwnSeat(square, owner, name, options) {
 }
 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';
+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

@@ -26,18 +26,10 @@ export type Act = {
     at?: number;
     body?: string;
     metadata?: import('./model.js').ActivityMetadata;
+    delivery?: import('./model.js').ActivityDelivery;
     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;

package/dist/square-domain.js

@@ -1,35 +1,22 @@
-import { SquareError, formatActivityId, parseActivityId, sameName, validateOwner, validateName } from './model.js';
+import { SquareError, formatActivityId, parseActivityId, sameName, validateActivityDelivery, 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');
-            }
+    if (activity.kind === 'say' && activity.delivery?.mode === 'direct') {
+        const audience = [];
+        for (const mention of activity.mentions ?? []) {
+            const recipient = facts.standing.find(item => sameName(item.name, mention))?.name;
+            if (recipient !== undefined && !audience.some(item => sameName(item.recipient, recipient)))
+                audience.push({ recipient, route: 'mention' });
         }
+        return { activity, audience };
     }
+    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 +44,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) : [],
@@ -82,15 +69,15 @@ export function wrapSquareWrite(read, writes, authority) {
         throw new SquareError('invalid_args', 'Artifact writes require an explicit authority.');
     const { applyLanding, ...mutations } = writes;
     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')
+    const expectedName = seated ? authority.seat?.participant : authority.kind === 'send' ? authority.actor : authority.participant;
+    if (!['participant', 'host-cleanup', 'join', 'takeover', 'send'].includes(authority.kind) || typeof expectedName !== 'string')
         throw new SquareError('invalid_args', 'Artifact write authority is malformed.');
     validateName(expectedName);
     if (seated) {
         validateOwner(authority.seat.owner);
         validateGeneration(authority.seat.generation);
     }
-    else {
+    else if (authority.kind !== 'send') {
         validateOwner(authority.owner);
         if (authority.kind === 'takeover')
             validateGeneration(authority.expectedGeneration);
@@ -122,7 +109,7 @@ export function wrapSquareWrite(read, writes, authority) {
             reconnectSeat = seat;
         }
     }
-    else {
+    else if (authority.kind === 'takeover') {
         const current = read.seat(expectedName);
         if (current === undefined || current.generation !== authority.expectedGeneration)
             throw new SquareError('already_joined', 'The participant seat changed before takeover.');
@@ -136,7 +123,13 @@ export function wrapSquareWrite(read, writes, authority) {
             validateName(actor);
             if (!sameName(actor, expectedName))
                 throw new SquareError('already_joined', 'Activity actor does not match the artifact authority.');
-            if (authority.kind === 'participant') {
+            if (activity.kind === 'say')
+                validateActivityDelivery(activity.delivery);
+            if (authority.kind === 'send') {
+                if (activity.kind !== 'say' || activity.delivery?.mode !== 'direct' || activity.reach !== undefined || activity.reply !== undefined)
+                    throw new SquareError('invalid_args', 'Send authority may only land direct messages without bell or reply.');
+            }
+            else if (authority.kind === 'participant') {
                 assertSeat(authority.seat);
                 if (activity.kind === 'join')
                     throw new SquareError('invalid_args', 'A participant seat can only be re-established by join.');
@@ -172,7 +165,7 @@ export function wrapSquareWrite(read, writes, authority) {
             const stored = { ...activity, index };
             applyLanding(deriveLanding(stored, landingFacts(read, stored)));
             if (stored.kind === 'join') {
-                if (seated)
+                if (authority.kind !== 'join' && authority.kind !== 'takeover')
                     throw new SquareError('invalid_args', 'Seat authority cannot establish another seat.');
                 const seat = {
                     participant: stored.actor,
@@ -225,8 +218,8 @@ export function wrapSquareWrite(read, writes, authority) {
         },
         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) {

package/dist/square-facade.d.ts

@@ -1,19 +1,20 @@
 import type { DeliveryDeferral, MetadataMatch } from './delivery-deferral.js';
 export type { DeliveryDeferral, MetadataMatch, MetadataScalar } from './delivery-deferral.js';
 import type { ActivityId, Perception, Reach } from './square-core.js';
-import type { Owner, StoredAct, WakeAddress, ActivityMetadata, DirectedNotificationRoute } from './model.js';
+import type { Owner, StoredAct, WakeAddress, ActivityMetadata, ActivityDelivery, DirectedNotificationRoute } from './model.js';
 import type { WakeTransportPort, SquareResourceOwner } from './ports.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
-export type { Owner, WakeAddress, ActivityMetadata, JsonValue, DirectedNotificationRoute } from './model.js';
-/** Indexed archive event, including read and historical actorless lifecycle records. */
+export type { Owner, WakeAddress, ActivityMetadata, ActivityDelivery, JsonValue, DirectedNotificationRoute } from './model.js';
+/** Indexed archive event, including read bookkeeping. */
 export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
-    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
+    readonly kind: 'join' | 'say' | 'done' | 'listen' | 'ignore' | 'unlisten';
     readonly actor: string;
     readonly body?: string;
     readonly metadata?: ActivityMetadata;
+    readonly delivery?: ActivityDelivery;
     readonly mentions: readonly string[];
     readonly reach?: Reach;
     readonly target?: string;
@@ -49,6 +50,22 @@ export interface ExpressResult {
     readonly hint?: string;
     readonly observation?: ExpressObservation;
 }
+export type ChannelTruncate = number | false;
+export interface ChannelSendInput {
+    readonly from: string;
+    readonly to: string | readonly string[];
+    readonly body: string;
+    readonly truncate?: ChannelTruncate;
+    readonly metadata?: ActivityMetadata;
+}
+export interface ChannelSendResult {
+    readonly id: ActivityId;
+    readonly at: number;
+    readonly from: string;
+    readonly to: readonly string[];
+    readonly body: string;
+    readonly metadata?: ActivityMetadata;
+}
 export interface ListenerChangeResult {
     readonly activity: Activity | null;
     readonly observation?: ListenerObservation;
@@ -85,10 +102,8 @@ export interface CatchWaitStart {
 }
 export type OperationProgress = {
     readonly kind: 'waiting';
-    readonly reason: 'held' | 'throttled';
+    readonly reason: 'throttled';
     readonly delayMs?: number;
-    readonly holder?: string;
-    readonly holdReason?: string;
 } | ({
     readonly kind: 'catch-started';
     readonly participant: string;
@@ -135,10 +150,6 @@ export interface SquareSnapshot {
     readonly actCount: number;
     readonly hardCap: number | null;
     readonly throttlePerMinute?: number;
-    readonly held: {
-        readonly by: string;
-        readonly reason?: string;
-    } | null;
     readonly participants: readonly Pick<ParticipantSummary, 'name' | 'presence' | 'listening'>[];
     delivered(name: string, id: ActivityId): boolean;
 }
@@ -176,6 +187,7 @@ export interface JoinResult {
 }
 export interface Participant {
     readonly name: string;
+    readonly generation: ActivityId;
     express(body: string | undefined, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
     express(input: ExpressInput, control?: OperationControl): Promise<ExpressResult>;
     listen(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
@@ -183,8 +195,6 @@ export interface Participant {
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
     catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
-    hold(reason?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
-    resume(options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
     /** Leave without a message. Only an omitted or empty body is accepted. */
     done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
     deferDelivery(input: Readonly<{
@@ -220,12 +230,6 @@ export interface StatusResult {
     readonly participants: readonly ParticipantSummary[];
     readonly now: number;
     readonly throttlePerMinute?: number;
-    /** Non-null whenever held; by is present with an actor and omitted only for historical actorless holds. */
-    readonly held: {
-        readonly by?: string;
-        readonly reason?: string;
-        readonly at?: number;
-    } | null;
     readonly latestActivity?: Activity;
     readonly observation?: StatusObservation;
 }
@@ -267,7 +271,6 @@ export interface InboxResult {
 export interface RecoveryResult {
     readonly participant?: string;
     readonly standingCount?: number;
-    readonly held?: boolean;
     readonly ownActivityCount?: number;
     readonly hardCap?: number | null;
     readonly activitySummaries?: readonly UnreadActivitySummary[];
@@ -310,7 +313,6 @@ export interface CatchPresence {
 export interface SquareObservation {
     readonly location: string;
     readonly standingCount: number;
-    readonly held: boolean;
     readonly now: number;
     readonly participant?: string;
 }
@@ -320,7 +322,7 @@ export interface JoinObservation extends SquareObservation {
     /** The receipt succeeded, but optional recent-history/context enrichment was unavailable. */
     readonly enrichmentUnavailable?: true;
 }
-export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'held' | 'now'> {
+export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'now'> {
     readonly ownActivityCount: number;
     readonly hardCap: number | null;
 }
@@ -361,7 +363,7 @@ export interface ListenerObservation extends SquareObservation {
     readonly participant: string;
     readonly target: string;
 }
-export interface StatusObservation extends Omit<SquareObservation, 'now' | 'held'>, PresenceClassification {
+export interface StatusObservation extends Omit<SquareObservation, 'now'>, PresenceClassification {
     readonly knownParticipantCount: number;
     readonly latestPerception?: Perception;
     readonly joins: readonly {

package/dist/square-legacy-framing.d.ts

@@ -1,6 +1,8 @@
 import type { DatabaseSync } from 'node:sqlite';
 export declare const FORMAT4_ADDED_OBJECTS: ReadonlySet<string>;
 export declare const FORMAT4_REPLACED_OBJECTS: ReadonlySet<string>;
+/** Historical activity framing only; no runtime activity decoder accepts these kinds. */
+export declare function legacyActivitySchema(currentSchemaSql: string): string;
 /**
  * Read-only recognition of the exact row framing accepted by explicit migration.
  * It inspects identity, owned schema and journal mode only; it never reads row