@astrosheep/square 0.3.78 → 0.3.80

package/dist/square-actions.d.ts

@@ -1,5 +1,6 @@
+import { type StoredAct } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-import type { Activity, CatchOptions, ExpressOptions, ExpressResult, ExpressionObservation, ListenerChangeResult, OperationControl, OwnershipFenceOptions } from './square-facade.js';
+import type { Activity, ActivityResult, CatchOptions, ExpressOptions, ExpressResult, ExpressionObservation, OperationControl, OwnershipFenceOptions, SquareObservation } from './square-facade.js';
 import { type CatchSelection } from './catch-decisions.js';
 import { type HostContext } from './participant-host.js';
 export interface OperationContext extends HostContext {
@@ -8,6 +9,7 @@ export interface OperationContext extends HostContext {
 export type { OwnershipFenceOptions };
 export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, control?: OperationControl): Promise<CatchSelection>;
 export declare function catchUp(square: OperationContext, name: string, options: CatchOptions, control: OperationControl | undefined, leaseId: string): Promise<CatchSelection | null>;
+type LandingContext = Pick<SquareObservation, 'standingCount' | 'held' | 'now'>;
 export declare function join(square: OperationContext, name: string, control?: OperationControl, admission?: {
     readonly requireKnown?: boolean;
 }): Promise<{
@@ -15,28 +17,39 @@ export declare function join(square: OperationContext, name: string, control?: O
     readonly activity: Activity | null;
     readonly participantCount: number;
     readonly reconnected: boolean;
+    readonly observation: LandingContext;
 }>;
 /** Takeover holds the host CAS fence across the single done+join artifact transaction. */
-export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[], control?: OperationControl): Promise<{
+export declare function takeover(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
     readonly participantCount: number;
     readonly epoch?: number;
+    readonly observation: LandingContext;
 }>;
 export declare function implicitJoin(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly state: 'joined' | 'active' | 'done';
     readonly activity: Activity | null;
 }>;
-export interface ExpressCommittedResult extends ExpressResult {
+export interface ExpressCommittedResult extends Omit<ExpressResult, 'waited' | 'observation'> {
     readonly observation: ExpressionObservation;
 }
 export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressCommittedResult>;
-export declare function listen(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-export declare function ignore(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+export interface ListenerCommittedResult {
+    readonly activity: Activity | null;
+    readonly observation: LandingContext;
+}
+export declare function listen(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerCommittedResult>;
+export declare function ignore(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerCommittedResult>;
 export declare function listening(square: OperationContext, actor: string, control?: OperationControl): Promise<readonly string[]>;
-export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions, control?: OperationControl): Promise<ExpressResult>;
-export declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
+export interface LifecycleCommittedResult extends ActivityResult {
+    readonly observation: LandingContext & {
+        readonly activity: StoredAct;
+    };
+}
+export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions, control?: OperationControl): Promise<LifecycleCommittedResult>;
+export declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ActivityResult | null>;
 export declare function retireEndedSessionRoutes(square: OperationContext, sessionId: string): Promise<void>;
-export declare function hold(square: OperationContext, name: string, reason?: string, control?: OperationControl): Promise<ExpressResult>;
-export declare function resume(square: OperationContext, name: string, control?: OperationControl): Promise<ExpressResult>;
+export declare function hold(square: OperationContext, name: string, reason?: string, control?: OperationControl): Promise<LifecycleCommittedResult>;
+export declare function resume(square: OperationContext, name: string, control?: OperationControl): Promise<LifecycleCommittedResult>;

package/dist/square-actions.js

@@ -40,21 +40,23 @@ export async function join(square, name, control, admission = {}) {
     const preview = (await square.artifact.read((facts) => {
         // Express may reenter a known participant, but must never create a new name.
         const selected = admission.requireKnown ? resolveKnownName(facts, name) : name;
+        const now = square.clock();
         return {
-            ...decideJoin(facts, selected, square.clock()),
+            ...decideJoin(facts, selected, now),
             participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+            observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
         };
     }, control?.signal)).value;
     name = preview.joinedName;
     if (preview.joinAct === undefined) {
         if (hostLedger === undefined)
-            return { name: preview.joinedName, activity: null, participantCount: preview.participantCount, reconnected: false };
+            return { name: preview.joinedName, activity: null, participantCount: preview.participantCount, reconnected: false, observation: preview.observation };
         const identity = processIdentity(square.env ?? process.env);
         const owner = await readParticipantOwner(square.location, preview.joinedName, hostLedger);
         if (owner?.session === identity.session)
             return {
                 name: preview.joinedName, activity: null, participantCount: preview.participantCount,
-                reconnected: identity.channel !== 'unknown',
+                reconnected: identity.channel !== 'unknown', observation: preview.observation,
             };
         // Missing or foreign owner must pass CAS, not become a silent reconnect.
     }
@@ -80,6 +82,7 @@ export async function join(square, name, control, admission = {}) {
             return {
                 name: decision.joinedName, stored,
                 participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+                observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
             };
         }, control?.signal)).value;
     }
@@ -91,11 +94,11 @@ export async function join(square, name, control, admission = {}) {
     await publishCommittedIdentity(square, committed.name, epoch);
     return {
         name: committed.name, activity: committed.stored === null ? null : toPublicActivity(committed.stored),
-        participantCount: committed.participantCount, reconnected: false,
+        participantCount: committed.participantCount, reconnected: false, observation: committed.observation,
     };
 }
 /** Takeover holds the host CAS fence across the single done+join artifact transaction. */
-export async function takeover(square, name, _oldSessionIds = [], control) {
+export async function takeover(square, name, control) {
     throwIfAborted(control);
     validateName(name);
     const hostLedger = square.hostLedger;
@@ -113,6 +116,7 @@ export async function takeover(square, name, _oldSessionIds = [], control) {
             return {
                 name: joinedName, stored: [storedDone, storedJoin],
                 participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+                observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
             };
         }, control?.signal)).value;
     };
@@ -131,11 +135,11 @@ export async function takeover(square, name, _oldSessionIds = [], control) {
         }, control?.signal);
         if (outcome.status === 'busy')
             throw new SquareError('already_joined', `${participantIdentity(name)} already stands here — another session holds the name`);
-        return { name: outcome.result.name, activities: outcome.result.stored.map(toPublicActivity), participantCount: outcome.result.participantCount, epoch: outcome.epoch };
+        return { name: outcome.result.name, activities: outcome.result.stored.map(toPublicActivity), participantCount: outcome.result.participantCount, epoch: outcome.epoch, observation: outcome.result.observation };
     }
     const committed = await commitLifecycle();
     await publishCommittedIdentity(square, committed.name);
-    return { name: committed.name, activities: committed.stored.map(toPublicActivity), participantCount: committed.participantCount };
+    return { name: committed.name, activities: committed.stored.map(toPublicActivity), participantCount: committed.participantCount, observation: committed.observation };
 }
 export async function implicitJoin(square, name, control) {
     throwIfAborted(control);
@@ -185,14 +189,16 @@ export async function express(square, name, body, options = {}, control) {
         }
         catch (error) {
             if (isSquareError(error))
-                error.facts = { ...error.facts, reason: 'invalid_reply', activityId: options.reply };
+                error.facts = {
+                    ...error.facts, reason: 'invalid_reply', activityId: options.reply,
+                };
             throw error;
         }
     });
     const committed = (await square.artifact.transact((facts) => {
         // Selected-row decoding is storage work, not evidence that admission safely refused.
         const proposed = decideAct(facts, { name, body, force: options.force ?? false, now, mentions: options.mentions,
-            ...(options.reach === undefined ? {} : { reach: options.reach }), ...(options.noMention === undefined ? {} : { noMention: options.noMention }), ...('requireExplicitReach' in options ? { requireExplicitReach: options.requireExplicitReach === true } : {}), ...(reply === undefined ? {} : { reply }) });
+            ...(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(() => {
             const decision = proposed;
@@ -216,6 +222,7 @@ export async function express(square, name, body, options = {}, control) {
                 standingCount: inSquareCount(facts), held: facts.hold().active, now,
                 ownActivityCount: facts.participant(name).sayCount, hardCap: facts.header().hardCap,
             },
+            ...(decision.unmatchedMentions === undefined ? {} : { unmatchedMentions: decision.unmatchedMentions }),
             ...(decision.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: decision.replyAuthorNotHere }),
         };
     }, control?.signal)).value;
@@ -224,19 +231,18 @@ export async function express(square, name, body, options = {}, control) {
         ? await deliverPending({ artifact: square.artifact, hostLedger: square.hostLedger, 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 };
-    return {
-        activity: toPublicActivity(committed.stored), delivery, observation: committed.observation,
-        ...(committed.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: committed.replyAuthorNotHere }),
-    };
+    const { stored, observation, ...metadata } = committed;
+    return { activity: toPublicActivity(stored), delivery, observation, ...metadata };
 }
 async function landListenerChange(square, verb, actor, target, control) {
     throwIfAborted(control);
     const now = square.clock();
-    const stored = (await square.artifact.transact((facts) => {
+    const committed = (await square.artifact.transact((facts) => {
         const act = verb === 'listen' ? coreListen(facts, actor, target, now) : coreIgnore(facts, actor, target, now);
-        return act === undefined ? null : facts.land(act);
+        const stored = act === undefined ? null : facts.land(act);
+        return { stored, observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now } };
     }, control?.signal)).value;
-    return { activity: stored === null ? null : toPublicActivity(stored) };
+    return { activity: committed.stored === null ? null : toPublicActivity(committed.stored), observation: committed.observation };
 }
 export function listen(square, actor, target, control) { return landListenerChange(square, 'listen', actor, target, control); }
 export function ignore(square, actor, target, control) { return landListenerChange(square, 'ignore', actor, target, control); }
@@ -256,7 +262,9 @@ async function landCore(square, verb, actor, body = '', fence = {}, control) {
             const result = facts.land(verb === 'done' ? coreDone(facts, actor, body, now) : verb === 'hold' ? coreHold(facts, actor, body, now) : coreResume(facts, actor, now));
             if (session !== undefined)
                 dropEndedSessionWakeRoutes(facts, square.location, session, { expectedEpoch: fence.expectedEpoch, force: true, participant: actor });
-            return result;
+            return { activity: toPublicActivity(result), observation: {
+                    activity: result, standingCount: inSquareCount(facts), held: facts.hold().active, now,
+                } };
         }, control?.signal)).value;
         for (const row of owners)
             await hostLedger.removePresenceIfUnchanged(row).catch((error) => {
@@ -264,8 +272,7 @@ async function landCore(square, verb, actor, body = '', fence = {}, control) {
             });
         return stored;
     };
-    const stored = hostLedger === undefined ? await commitAndCleanup() : await hostLedger.withClaimLock(commitAndCleanup, control?.signal);
-    return { activity: toPublicActivity(stored) };
+    return hostLedger === undefined ? commitAndCleanup() : hostLedger.withClaimLock(commitAndCleanup, control?.signal);
 }
 export function done(square, name, body = '', fence = {}, control) { return landCore(square, 'done', name, body, fence, control); }
 function liveClaimedParticipants(rows, sessionId) {

package/dist/square-api.d.ts

@@ -0,0 +1,43 @@
+import type { ActivityResult, HistoryQuery, HistoryResult, JoinOptions, JoinResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions } from './square-facade.js';
+export type * from './square-facade.js';
+export { createSquareResourceOwner } from './open-square.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 squareLocation(input: SquareLocation): string;
+export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
+/** One concrete square resource. Request handles may borrow a server-owned connection. */
+export declare class Square {
+    readonly location: string;
+    private readonly square;
+    private readonly defaultParticipant?;
+    private readonly transport;
+    private constructor();
+    static at(input: SquareAtInput, control?: OperationControl): Promise<Square>;
+    static build(input: SquareBuildInput, control?: OperationControl): Promise<Square>;
+    static inMemory(input: Omit<SquareBuildInput, 'path' | 'resources'>): Square;
+    private handle;
+    participant(requested?: string): Promise<Participant>;
+    join(requested?: string, options?: JoinOptions, control?: OperationControl): Promise<JoinResult>;
+    doneOwnedSession(name: string, body: string, expectedEpoch: number, control?: OperationControl): Promise<ActivityResult>;
+    implicitJoin(name: string, control?: OperationControl): Promise<{
+        readonly state: 'joined' | 'active' | 'done';
+        readonly participant?: Participant;
+    }>;
+    snapshot(control?: OperationControl): Promise<import("./square-facade.js").SquareSnapshot>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
+    status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
+    participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;
+    recovery(requested?: string, control?: OperationControl): Promise<RecoveryResult>;
+    stream(options: StreamOptions, control?: OperationControl): AsyncIterable<import("./square-facade.js").StreamRecord>;
+    recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
+    close(): Promise<void>;
+    endOwnedSession(name: string, sessionId: string, expectedEpoch?: number): Promise<ActivityResult | null>;
+    retireEndedSessionRoutes(sessionId: string): Promise<void>;
+}
+export declare function diagnoseSquare(input: SquareLocation, control?: OperationControl): Promise<import("./artifact.js").DiagnoseResult>;
+export declare function migrateSquare(input: SquareLocation, control?: OperationControl): Promise<import("./square-migration.js").MigrationOutcome>;
+export declare function discover(input: SquareAtInput, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;
+export declare function inbox(input: SquareAtInput, sessionId: string, options?: InboxOptions, control?: OperationControl): Promise<InboxResult>;