@astrosheep/square 0.3.61 → 0.3.62

package/dist/cli/square-commands.js

@@ -1,13 +1,14 @@
 import { cmdActivity } from '../activity.js';
-import { formatActivityId, formatHardCap, parseActivityId, } from '../model.js';
-import { formatRefusal, participantCommandPrefix, participantIdentity, quoteShell, renderRoomChangeText, renderAmbientEvent, withPathOutput, } from '../presentation.js';
-import { claimSessionParticipant, hasAutomaticDeliveryIdentity, localSessionIdentities, lookupParticipant, readParticipantOwner, recordSessionDone, } from '../registry.js';
-import { createHostLedgerPort } from '../host-ledger-file-adapter.js';
-import { sessionIdsFromEnvironment } from '../square-projections.js';
+import { scanMentionCandidates } from '../mention-parse.js';
+import { validateDoneBody } from '../decisions.js';
+import { formatHardCap, } from '../model.js';
+import { formatRefusal, participantCommandPrefix, participantIdentity, takeoverRecoveryLines, renderRoomChangeText, renderAmbientEvent, withPathOutput, } from '../presentation.js';
+import { hostLedgerForEnv, hasAutomaticDeliveryIdentity, } from '../registry.js';
 import { actId, nowMs } from '../runtime.js';
 import { createSquare, openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
-import { openParticipant, Square } from '../square-wiring.js';
+import { Square } from '../square-wiring.js';
+import { createSquareApplication } from '../square-application.js';
 import { entryPresentation, eventPresentation } from '../views.js';
 import { createDefaultWakeTransport } from '../notifications.js';
 import { style } from '../tty-style.js';
@@ -85,78 +86,60 @@ export const joinCommand = {
     parse: parseJoin,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const beforeSquare = await openSquare(squarePath, { clock: nowMs });
+        const hostLedger = hostLedgerForEnv(context.env);
+        const beforeSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger });
         const before = await entryPresentation(beforeSquare, intent.name, intent.lastN);
         await closeOpenSquare(beforeSquare);
-        const hostLedger = createHostLedgerPort();
-        const square = await Square.at({ path: squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
+        let joinedName;
+        let joinKind;
         try {
-            const identity = localSessionIdentities()[0];
-            const owner = before.joined ? await readParticipantOwner(squarePath, intent.name) : undefined;
-            const reconnect = before.joined && identity !== undefined && owner?.sessionId === identity.sessionId;
-            const isRejoin = before.joined;
-            if (isRejoin && !intent.kick && !reconnect) {
+            const result = await application.join({ takeover: intent.kick });
+            joinedName = result.participant;
+            joinKind = result.kind;
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'already_joined') {
                 process.stderr.write(formatRefusal(squarePath, [
                     `✕ ${participantIdentity(intent.name)} shoos you out of the square`,
-                    `  · a same-named participant stands here — the name is taken`,
-                    `  · --kick banishes the one standing there — the name becomes yours`,
-                    `${participantCommandPrefix(squarePath, intent.name)} join --kick`,
+                    '  · a same-named participant stands here — the name is taken',
+                    ...takeoverRecoveryLines(squarePath, intent.name),
                 ], { participantCount: before.participantCount }));
                 process.exit(2);
             }
-            const takeoverNeeded = isRejoin && intent.kick;
-            const oldBindings = takeoverNeeded ? await lookupParticipant(squarePath, intent.name) : [];
-            let participant;
-            if (takeoverNeeded) {
-                const currentSessions = new Set(sessionIdsFromEnvironment());
-                await square.takeover(intent.name);
-                for (const binding of oldBindings) {
-                    if (!currentSessions.has(binding.sessionId)) {
-                        await recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel).catch(() => undefined);
-                    }
-                }
-                await claimSessionParticipant(squarePath, intent.name, process.env);
-                participant = await square.join(intent.name);
-            }
-            else {
-                await claimSessionParticipant(squarePath, intent.name, process.env);
-                participant = await square.join(intent.name);
-            }
-            const joinedName = participant.name;
-            const afterSquare = await openSquare(squarePath, { clock: nowMs });
-            const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
-            await closeOpenSquare(afterSquare);
-            await square.reconcileBinding().catch(() => undefined);
-            const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
-                now: nowMs(),
-                preview: intent.lastN === null ? undefined : 200,
-                actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
-                squareState: after.state,
-            })).filter(Boolean).join('\n\n');
-            const contextText = after.joinContext;
-            const fallback = hasAutomaticDeliveryIdentity()
-                ? []
-                : ['', `${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`, '  the square has no way to call you — keep this catch open and stay within earshot'];
-            const scene = after.scene;
-            const entryLine = !isRejoin
-                ? '● you stepped into the square'
-                : reconnect && !intent.kick
-                    ? '● you are already in the square'
-                    : `✓ you banished the original ${participantIdentity(joinedName)} — the name is yours`;
-            const output = [
-                entryLine,
-                '',
-                "· carved into the fountain's edge: every word here lands on a real ear — speak when someone needs it.",
-                ...(reconnect || scene === '' ? [] : ['', scene]),
-                ...(isRejoin || contextText === '' ? [] : ['', style('dim', 'context'), contextText]),
-                ...(isRejoin || activities === '' ? [] : ['', style('dim', 'recent activity'), activities]),
-                ...fallback,
-            ].join('\n');
-            return withPathOutput(squarePath, output, { participantCount: after.participantCount });
-        }
-        finally {
-            await square.close();
+            throw error;
         }
+        const afterSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger });
+        const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
+        await closeOpenSquare(afterSquare);
+        const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
+            now: nowMs(),
+            preview: intent.lastN === null ? undefined : 200,
+            actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
+            squareState: after.state,
+        })).filter(Boolean).join('\n\n');
+        const contextText = after.joinContext;
+        const fallback = hasAutomaticDeliveryIdentity()
+            ? []
+            : ['', `${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`, '  the square has no way to call you — keep this catch open and stay within earshot'];
+        const scene = after.scene;
+        const entryLine = joinKind === 'joined'
+            ? '● you stepped into the square'
+            : joinKind === 'reconnected'
+                ? '● you are already in the square'
+                : `✓ you banished the original ${participantIdentity(joinedName)} — the name is yours`;
+        const isRejoin = joinKind !== 'joined';
+        const reconnect = joinKind === 'reconnected';
+        const output = [
+            entryLine,
+            '',
+            "· carved into the fountain's edge: every word here lands on a real ear — speak when someone needs it.",
+            ...(reconnect || scene === '' ? [] : ['', scene]),
+            ...(isRejoin || contextText === '' ? [] : ['', style('dim', 'context'), contextText]),
+            ...(isRejoin || activities === '' ? [] : ['', style('dim', 'recent activity'), activities]),
+            ...fallback,
+        ].join('\n');
+        return withPathOutput(squarePath, output, { participantCount: after.participantCount });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -181,14 +164,11 @@ function parseActivity(argv, context) {
         else if (argument === '--no-mention')
             noMention = true;
         else if (argument === '--mention') {
-            mentions.push(requireParticipant(requireValue(argv, index, argument)));
+            mentions.push(requireValue(argv, index, argument));
             index += 1;
         }
         else if (argument === '--reply') {
-            const replyIndex = parseActivityId(requireValue(argv, index, argument));
-            if (replyIndex === undefined)
-                fail('Invalid --reply: expected an activity id like act/12');
-            reply = replyIndex;
+            reply = requireValue(argv, index, argument);
             index += 1;
         }
         else
@@ -199,8 +179,6 @@ function parseActivity(argv, context) {
         fail('✕ --bell cannot be combined with --mention or --no-mention\nsquare express --help');
     if (noMention && mentions.length > 0)
         fail('✕ --no-mention cannot be combined with --mention\nsquare express --help');
-    if (!bell && !noMention && mentions.length === 0)
-        fail('✕ express needs --mention <name>, --no-mention, or --bell\nsquare express --help');
     if (bodyArgs.length !== 1) {
         if (bodyArgs.length === 0) {
             if (!process.stdin.isTTY)
@@ -215,14 +193,18 @@ export const expressCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const body = await resolveBody(intent.activity);
-        const reachArg = intent.reach === 'bell' ? ' --bell' : intent.noMention ? ' --no-mention' : intent.mentions.map((name) => ` --mention ${quoteShell(name)}`).join('');
+        if (intent.reach === undefined && !intent.noMention && intent.mentions.length === 0 && scanMentionCandidates(body).length === 0) {
+            fail('✕ express needs --mention <name>, --no-mention, --bell, or an @name in the body\nsquare express --help');
+        }
         await cmdActivity(squarePath, intent.name, body, (value) => value, {
             force: intent.force,
             noWait: intent.noWait,
+            noMention: intent.noMention,
             mentions: intent.mentions,
             reach: intent.reach,
             reply: intent.reply,
-            forceCommand: `${participantCommandPrefix(squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply ${formatActivityId(intent.reply)}`} -`,
+            cwd: context.cwd,
+            env: context.env,
         });
     },
     present: () => { },
@@ -249,15 +231,12 @@ export const listenCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const result = await participant.listen(intent.target);
+            const result = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).listen(intent.target);
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
-            return listenerPresentation(squarePath, participant.name, intent.target, 'listen', result.activity, participantCount);
+            return listenerPresentation(squarePath, intent.name, intent.target, 'listen', result.activity, participantCount);
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
@@ -268,15 +247,12 @@ export const ignoreCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const result = await participant.ignore(intent.target);
+            const result = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).ignore(intent.target);
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
-            return listenerPresentation(squarePath, participant.name, intent.target, 'ignore', result.activity, participantCount);
+            return listenerPresentation(squarePath, intent.name, intent.target, 'ignore', result.activity, participantCount);
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
@@ -287,10 +263,9 @@ export const listeningCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const targets = await participant.listening();
+            const participant = { name: intent.name };
+            const targets = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).listening();
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
             const body = targets.length === 0
                 ? `○ ${participantIdentity(participant.name)} is not turned toward anyone`
@@ -298,29 +273,36 @@ export const listeningCommand = {
             return withPathOutput(squarePath, body, { participantCount });
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
     present: (result) => process.stdout.write(result),
 };
+function validateDoneInput(body) {
+    try {
+        validateDoneBody(body);
+    }
+    catch (error) {
+        fail(`${error instanceof Error ? error.message : String(error)}\nsquare done --help`);
+    }
+}
 function parseDone(argv, context) {
     if (argv.length > 1)
         usage(context.command);
+    if (argv[0] !== '-')
+        validateDoneInput(argv[0]);
     return { name: requireParticipant(context.name), body: argv.length === 1 ? argv[0] : undefined };
 }
 export const doneCommand = {
     parse: parseDone,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const body = (await resolveBody(intent.body ?? (process.stdin.isTTY ? '' : '-'))).replace(/\r\n/g, '\n').trim();
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        const participant = await square.join(intent.name);
-        const result = await participant.done(body);
-        await square.reconcileBinding();
-        await square.close();
+        const body = intent.body === '-' || !process.stdin.isTTY ? await readStdin() : '';
+        validateDoneInput(body);
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.done(body);
         const name = result.activity.actor;
-        const presentation = await openSquare(squarePath, { clock: nowMs });
+        const presentation = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
         const participantCount = (await entryPresentation(presentation, name).finally(() => closeOpenSquare(presentation))).participantCount;
         return withPathOutput(squarePath, `○ ${participantIdentity(name)} steps out of the square — done · ${result.activity.id} · just now`, { participantCount });
     },
@@ -335,19 +317,12 @@ export const holdCommand = {
     parse: parseHold,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        try {
-            const participant = await square.join(intent.name);
-            const result = await participant.hold((await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim());
-            await square.close();
-            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
-            const presentation = await eventPresentation(presentationSquare, result.activity.id);
-            await closeOpenSquare(presentationSquare);
-            return withPathOutput(squarePath, `· ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount, held: true });
-        }
-        finally {
-            await square.close();
-        }
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.hold((await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim());
+        const presentationSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
+        const presentation = await eventPresentation(presentationSquare, result.activity.id);
+        await closeOpenSquare(presentationSquare);
+        return withPathOutput(squarePath, `· ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount, held: true });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -359,19 +334,12 @@ export const resumeCommand = {
     },
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        try {
-            const participant = await square.join(intent.name);
-            const result = await participant.resume();
-            await square.close();
-            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
-            const presentation = await eventPresentation(presentationSquare, result.activity.id);
-            await closeOpenSquare(presentationSquare);
-            return withPathOutput(squarePath, `✓ ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount });
-        }
-        finally {
-            await square.close();
-        }
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.resume();
+        const presentationSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
+        const presentation = await eventPresentation(presentationSquare, result.activity.id);
+        await closeOpenSquare(presentationSquare);
+        return withPathOutput(squarePath, `✓ ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount });
     },
     present: (result) => process.stdout.write(result),
 };

package/dist/decisions.d.ts

@@ -68,7 +68,9 @@ export declare function decideAct(squareState: SquareState, input: {
     mentions?: readonly string[];
     reach?: Reach;
     reply?: number;
+    noMention?: boolean;
 }): ActDecision;
+export declare function validateDoneBody(body: unknown): void;
 export declare function coreDone(squareState: SquareState, name: string, body: string, now: number): Extract<Act, {
     kind: 'done';
 }>;

package/dist/decisions.js

@@ -1,10 +1,11 @@
 import { SquareError, sameName, validateName, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
-import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, THROTTLE_WINDOW_MS, } from './runtime.js';
+import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, rosterNames, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, directedPeerSays } from './activity-feed.js';
 import { formatActivityId, isIgnored, isListening, listeningTo, MAX_IDENTITY_SET_SIZE, validate } from './square-core.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { compileSearchPattern } from './search.js';
+import { scanMentionCandidates, resolveNameAt } from './mention-parse.js';
 export function resolveKnownName(squareState, name) {
     validateName(name);
     const known = resolveRosterName(squareState, name);
@@ -124,8 +125,42 @@ export function decideAct(squareState, input) {
             mentionNames.push(resolved);
         }
     }
+    if (input.noMention !== true) {
+        // Body @name tokens resolve against the standing roster at landing time; the stored
+        // body never changes, only mention metadata is derived. Explicit --no-mention turns
+        // this scan off entirely.
+        const unmatched = [];
+        for (const candidate of scanMentionCandidates(body)) {
+            const resolved = resolveNameAt(body, candidate, joinedNames);
+            if (resolved === undefined) {
+                unmatched.push(candidate);
+                continue;
+            }
+            if (!mentionNames.some((existing) => sameName(existing, resolved))) {
+                if (mentionNames.length >= MAX_IDENTITY_SET_SIZE) {
+                    throw new SquareError('invalid_args', `An activity can mention at most ${MAX_IDENTITY_SET_SIZE} participants`);
+                }
+                mentionNames.push(resolved);
+            }
+        }
+        // A bell already reaches everyone: only there does an unmatched @token stay literal text.
+        if (reach !== 'bell' && unmatched.length > 0) {
+            const roster = rosterNames(squareState);
+            const notStanding = unmatched.filter((candidate) => resolveNameAt(body, candidate, roster) !== undefined);
+            const unknown = unmatched.filter((candidate) => !notStanding.includes(candidate));
+            const lines = [];
+            if (unknown.length > 0) {
+                lines.push(`✕ ${unknown.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${unknown.length === 1 ? 'does' : 'do'} not match anyone in this square`);
+            }
+            if (notStanding.length > 0) {
+                lines.push(`✕ ${notStanding.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${notStanding.length === 1 ? 'is' : 'are'} not standing in this square`);
+            }
+            lines.push('  · wrap literal @text in backticks, or pass --no-mention to land bare');
+            throw new SquareError('invalid_args', lines.join('\n'));
+        }
+    }
     if (reach === 'bell' && mentionNames.length > 0) {
-        throw new SquareError('invalid_args', 'A bell cannot be combined with --mention.');
+        throw new SquareError('invalid_args', 'A bell cannot be combined with a mention — remove --mention or the @name in the body.');
     }
     const reply = input.reply;
     if (reply !== undefined) {
@@ -181,9 +216,15 @@ export function decideAct(squareState, input) {
         pendingRoomChanges: unreadRoomChanges,
     };
 }
+export function validateDoneBody(body) {
+    if (body !== undefined && body !== '') {
+        throw new SquareError('invalid_args', 'done only leaves the square and does not accept a message; use express before leaving');
+    }
+}
 export function coreDone(squareState, name, body, now) {
+    validateDoneBody(body);
     const resolvedName = resolveStandingName(squareState, name);
-    const act = { kind: 'done', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+    const act = { kind: 'done', actor: resolvedName, at: now };
     requireStanding(squareState, act);
     return act;
 }

package/dist/delivery-operations.d.ts

@@ -1,9 +1,8 @@
 import { type SquareState } from './model.js';
-import type { HostLedgerPort, PresenceRecord, PresentationEvidenceProjection, SquareArtifactPort, DeliverPendingInput, DeliveryResult, ObserveSquareInput, ReconcileBindingInput, SquareObservation } from './ports.js';
+import type { HostLedgerPort, PresenceRecord, PresentationEvidenceProjection, SquareArtifactPort, DeliverPendingInput, DeliveryResult, ObserveSquareInput, SquareObservation } from './ports.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { type WakeAttempt } from './square-projections.js';
 export declare function observeSquare(input: ObserveSquareInput): Promise<SquareObservation>;
-export declare function reconcileBinding(input: ReconcileBindingInput): Promise<import("./host-ledger.js").ReconcileBindingResult>;
 export declare function deliverPending(input: DeliverPendingInput): Promise<DeliveryResult>;
 export declare function selectPendingWakeActivities(state: SquareState, routes: readonly PresenceRecord[], attempts: readonly WakeAttempt[], now: number, graceMs: number, limit: number, delivery?: import("./delivery.js").DeliveryModel, presentations?: readonly PresentationEvidenceProjection[]): number[];
 export declare function sweepPending(input: {

package/dist/delivery-operations.js

@@ -39,7 +39,7 @@ export async function observeSquare(input) {
     let rows = [];
     if (input.hostLedger !== undefined) {
         try {
-            rows = await input.hostLedger.listPresence({ location: input.location, scopes: ['user', 'local'], now: input.now });
+            rows = await input.hostLedger.listPresence({ location: input.location, now: input.now });
         }
         catch {
             rows = [];
@@ -55,9 +55,6 @@ export async function observeSquare(input) {
     }));
     return { ...(input.location === undefined ? {} : { location: input.location }), version: snapshot.version, state: snapshot.state, pending: delivery.joinedRecipients().map((recipient) => ({ recipient, notifications: delivery.pendingFor(recipient) })), bindings };
 }
-export async function reconcileBinding(input) {
-    return input.hostLedger.reconcileBinding({ artifact: input.artifact, scopes: input.scopes, now: input.now });
-}
 export async function deliverPending(input) {
     const observation = await observeSquare({ artifact: input.artifact, hostLedger: input.hostLedger, location: input.location, now: input.now });
     const routes = (observation.state.routes ?? []).map((route) => ({

package/dist/file-changes.d.ts

@@ -0,0 +1,12 @@
+export declare function canonicalFilePath(value: string): Promise<string>;
+export interface VersionObserver<T> {
+    readonly generation: number;
+    hinted(since: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    read(signal?: AbortSignal): Promise<T>;
+    changed(since: T, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    close(): void;
+}
+/** Shared only within this process. Durable state is always read at the storage boundary. */
+export declare function observeFileVersion<T>(filePath: string, kind: string, read: (file: string, signal: AbortSignal) => Promise<T>): Promise<VersionObserver<T>>;
+/** File metadata invalidates a ledger projection; it is not presentation evidence. */
+export declare function observeFileMetadata(file: string): Promise<VersionObserver<string>>;