@astrosheep/square 0.3.61 → 0.3.63

package/dist/file-changes.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Filesystem notifications are hints, never proof of a committed change. */
+const RECONCILE_MS = 2_000;
+export async function canonicalFilePath(value) {
+    let current = path.resolve(value);
+    const suffix = [];
+    for (;;) {
+        try {
+            return path.join(await fs.promises.realpath(current), ...suffix.reverse());
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                return path.resolve(value);
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(value);
+            suffix.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/** A local edge counter: register first, inspect state, then wait from that counter. */
+class Edges {
+    version = 0;
+    listeners = new Set();
+    emit() { this.version += 1; for (const listener of [...this.listeners])
+        listener(); }
+    wait(since, timeoutMs, signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new Error('Wait aborted'));
+        if (this.version !== since)
+            return Promise.resolve(true);
+        if (timeoutMs <= 0)
+            return Promise.resolve(false);
+        return new Promise((resolve, reject) => {
+            let timer;
+            const cleanup = () => { if (timer !== undefined)
+                clearTimeout(timer); this.listeners.delete(changed); signal?.removeEventListener('abort', aborted); };
+            const changed = () => { cleanup(); resolve(true); };
+            const aborted = () => { cleanup(); reject(signal?.reason ?? new Error('Wait aborted')); };
+            this.listeners.add(changed);
+            signal?.addEventListener('abort', aborted, { once: true });
+            if (Number.isFinite(timeoutMs))
+                timer = setTimeout(() => { cleanup(); resolve(false); }, Math.min(timeoutMs, 2_147_483_647));
+            if (signal?.aborted)
+                aborted();
+            else if (this.version !== since)
+                changed();
+        });
+    }
+}
+const directories = new Map();
+function attachDirectory(directory, entry) {
+    try {
+        const stat = fs.statSync(directory);
+        const identity = stat.dev + ':' + stat.ino;
+        if (entry.watcher !== undefined && entry.identity === identity)
+            return;
+        entry.watcher?.close();
+        entry.watcher = undefined;
+        entry.identity = identity;
+        const watcher = fs.watch(directory, (_event, filename) => {
+            const name = filename?.toString();
+            for (const [target, edges] of entry.targets) {
+                if (name === undefined || name === target || name === target + '-journal' || name === target + '-wal') {
+                    for (const edge of edges)
+                        edge.emit();
+                }
+            }
+        });
+        entry.watcher = watcher;
+        watcher.on('error', () => {
+            if (entry.watcher !== watcher)
+                return;
+            watcher.close();
+            entry.watcher = undefined;
+            for (const edges of entry.targets.values())
+                for (const edge of edges)
+                    edge.emit();
+        });
+    }
+    catch {
+        entry.watcher?.close();
+        entry.watcher = undefined;
+        // Missing paths, resource limits, and unsupported filesystems use reconciliation.
+    }
+}
+function subscribeHints(file) {
+    const directory = path.dirname(file);
+    const name = path.basename(file);
+    let entry = directories.get(directory);
+    if (entry === undefined) {
+        entry = { targets: new Map() };
+        directories.set(directory, entry);
+        const owned = entry;
+        entry.timer = setInterval(() => {
+            attachDirectory(directory, owned);
+            for (const edges of owned.targets.values())
+                for (const edge of edges)
+                    edge.emit();
+        }, RECONCILE_MS);
+    }
+    const edges = new Edges();
+    const targets = entry.targets.get(name) ?? new Set();
+    targets.add(edges);
+    entry.targets.set(name, targets);
+    attachDirectory(directory, entry);
+    let closed = false;
+    return { edges, close() {
+            if (closed)
+                return;
+            closed = true;
+            targets.delete(edges);
+            if (targets.size === 0)
+                entry.targets.delete(name);
+            if (entry.targets.size === 0) {
+                entry.watcher?.close();
+                clearInterval(entry.timer);
+                directories.delete(directory);
+            }
+        } };
+}
+/** Await a shared read without allowing one subscriber to cancel other subscribers. */
+async function abortable(promise, signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Wait aborted');
+    if (signal === undefined)
+        return promise;
+    let abort;
+    try {
+        return await Promise.race([promise, new Promise((_resolve, reject) => {
+                abort = () => reject(signal.reason ?? new Error('Wait aborted'));
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            })]);
+    }
+    finally {
+        if (abort !== undefined)
+            signal.removeEventListener('abort', abort);
+    }
+}
+const versions = new Map();
+/** Shared only within this process. Durable state is always read at the storage boundary. */
+export async function observeFileVersion(filePath, kind, read) {
+    const file = await canonicalFilePath(filePath);
+    const key = kind + '\0' + file;
+    let shared = versions.get(key);
+    if (shared === undefined) {
+        shared = { refs: 0, hints: subscribeHints(file), controller: new AbortController() };
+        versions.set(key, shared);
+    }
+    shared.refs += 1;
+    const entry = shared;
+    const local = new AbortController();
+    const readVersion = async (signal) => {
+        const opSignal = signal === undefined ? local.signal : AbortSignal.any([local.signal, signal]);
+        if (opSignal.aborted)
+            throw opSignal.reason;
+        const generation = entry.hints.edges.version;
+        if (entry.cached?.generation === generation)
+            return entry.cached.value;
+        if (entry.pending === undefined) {
+            entry.pending = read(file, entry.controller.signal).then((value) => {
+                entry.cached = { generation, value };
+                return value;
+            }).finally(() => { entry.pending = undefined; });
+        }
+        return abortable(entry.pending, opSignal);
+    };
+    return {
+        get generation() { return entry.hints.edges.version; },
+        hinted(since, timeoutMs, signal) {
+            return entry.hints.edges.wait(since, timeoutMs, signal === undefined ? local.signal : AbortSignal.any([local.signal, signal]));
+        },
+        read: readVersion,
+        async changed(since, timeoutMs, signal) {
+            const timeout = new AbortController();
+            const timer = Number.isFinite(timeoutMs) ? setTimeout(() => timeout.abort(), Math.min(Math.max(1, timeoutMs), 2_147_483_647)) : undefined;
+            const deadline = Date.now() + Math.max(0, timeoutMs);
+            const opSignal = AbortSignal.any([local.signal, timeout.signal, ...(signal === undefined ? [] : [signal])]);
+            try {
+                for (;;) {
+                    const edge = entry.hints.edges.version;
+                    if (!Object.is(await readVersion(opSignal), since))
+                        return true;
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0)
+                        return false;
+                    // Another subscriber's in-flight read may predate the edge captured above.
+                    if (entry.cached?.generation !== entry.hints.edges.version)
+                        continue;
+                    if (!await entry.hints.edges.wait(edge, remaining, opSignal))
+                        return false;
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw signal.reason ?? error;
+                if (local.signal.aborted || timeout.signal.aborted)
+                    return false;
+                throw error;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        },
+        close() {
+            if (local.signal.aborted)
+                return;
+            local.abort(new Error('Change subscription closed'));
+            if (--entry.refs === 0) {
+                entry.controller.abort(new Error('Change monitor closed'));
+                entry.hints.close();
+                versions.delete(key);
+            }
+        },
+    };
+}
+/** File metadata invalidates a ledger projection; it is not presentation evidence. */
+export function observeFileMetadata(file) {
+    return observeFileVersion(file, 'metadata', async (target) => {
+        try {
+            const stat = await fs.promises.stat(target, { bigint: true });
+            return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return 'missing';
+            throw error;
+        }
+    });
+}

package/dist/help.js

@@ -1,6 +1,7 @@
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
+    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION and SQUARE_PARTICIPANT_NAME, or pass --location and --as before the command.'] },
     {
         names: ['build'], usage: 'build [--cap <N|unlimited>] [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true, group: 'host',
         summary: 'Create a square from Markdown on stdin.',
@@ -18,7 +19,7 @@ const COMMANDS = [
     {
         names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] (--mention <name>... | --no-mention | --bell) [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Reach:', '  --mention <name>  Address one participant; repeat for multiple participants. The body stays unchanged.', '  --no-mention      Land a bare activity explicitly; listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity.", '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
+        details: ['Reach:', '  --mention <name>  Address one participant; repeat for multiple participants. The body stays unchanged.', '  --no-mention      Land a bare activity explicitly; @names stay plain text. listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity.", '  @name             An @name in the body also addresses that standing participant; `backticks` keep @text literal.', '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return instead of waiting. A held wait gives up on its own after 10 minutes.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future bare says.' },
     { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },
@@ -28,7 +29,7 @@ const COMMANDS = [
         summary: 'Catch directed conversation since you last looked.',
         details: ['Modes:', '  --id <activity-id> Catch exactly one activity addressed to you, with its full body; implies --now.', '                    Marks only this activity seen; repeats return it again. No filters, limit, idle or replace.', '                    history stays read-only; catch --id consumes the selected activity.', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention         Match direct attention for your current participant (and bells).', '  --limit <count>   Return one page (default 10, maximum 100).', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
-    { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
+    { names: ['done'], usage: '--as <name> done', usesSquare: true, group: 'participant', summary: 'Step out of the square.', details: ['done takes no message. Use express before leaving to send one.'] },
     {
         names: ['stream'], usage: 'stream [--ndjson [--for <name>] [--last <N> | --after <id>]]', usesSquare: true, hiddenFromIndex: true,
         summary: 'Follow activity without consuming participant presence.',
@@ -43,7 +44,7 @@ const COMMANDS = [
     {
         names: ['history'], usage: 'history [filters] [output]', usesSquare: true, group: 'participant',
         summary: 'Read or search the archive without changing what you have caught.',
-        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>                  Match activities after a time.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --before <id>                   Read the page immediately before an activity.', '  --after <id>                    Read the page immediately after an activity.', '', 'Results:', '  --limit <N>                     Page size (default 10, maximum 100).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  One result shows its full body; multiple results use previews.', '  --no-truncate shows every original body.'],
+        details: ['Optional --as is accepted but does not change the archive or claim a name.', '', 'Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>                  Match activities after a time.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --before <id>                   Read the page immediately before an activity.', '  --after <id>                    Read the page immediately after an activity.', '', 'Results:', '  --limit <N>                     Page size (default 10, maximum 100).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  One result shows its full body; multiple results use previews.', '  --no-truncate shows every original body.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
     {
@@ -125,22 +126,17 @@ export function renderSubcommandHelp(command) {
 }
 export function helpRequest(rawArgs) {
     const args = [];
-    let hasExplicitName = false;
     for (let index = 0; index < rawArgs.length; index++) {
         const arg = rawArgs[index];
         if (arg === '--location' || arg === '--as') {
             const value = rawArgs[index + 1];
             if (value === undefined || value.startsWith('--'))
                 return undefined;
-            if (arg === '--as')
-                hasExplicitName = true;
             index++;
             continue;
         }
         args.push(arg);
     }
-    if (hasExplicitName && args[0] === 'history')
-        return undefined;
     if (isHelpFlag(args[0]))
         return {};
     if (args[0] === 'help') {

package/dist/host-ledger-file-adapter.d.ts

@@ -1,24 +1,27 @@
-import type { HostLedgerPort, HostLedgerScope, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, PresenceClaimResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, ReconcileBindingInput, ReconcileBindingResult, WakeDispatchClaim, WakeDispatchClaimInput, WakeDispatchReleaseInput, WakeDispatchTransitionInput, WakeAttemptLookup } from './host-ledger.js';
+import { type VersionObserver } from './file-changes.js';
+import type { HostLedgerPort, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, PresenceClaimResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, WakeDispatchClaim, WakeDispatchClaimInput, WakeDispatchReleaseInput, WakeDispatchTransitionInput, WakeAttemptLookup } from './host-ledger.js';
 export interface HostLedgerFileAdapterOptions {
-    userPath?: string;
-    localPath?: string;
-    writableScope?: HostLedgerScope;
-    readableScopes?: readonly HostLedgerScope[];
+    rootPath?: string;
     claimsPath?: string;
     now?: () => number;
 }
 export declare class FileHostLedgerPort implements HostLedgerPort {
-    private readonly user;
-    private readonly local;
-    private readonly writable;
-    private readonly readable;
+    private readonly root;
     private readonly claims;
     private readonly clock;
     constructor(o?: HostLedgerFileAdapterOptions);
     private file;
-    claimPresence(i: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceClaimResult>;
-    ensurePresence(i: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
+    /** Invalidation only: callers still use the ledger projections as their authority. */
+    observeChanges(): Promise<{
+        presence: VersionObserver<string>;
+        evidence: VersionObserver<string>;
+    }>;
+    /** Time can expire bindings/evidence even when their files do not change. */
+    nextExpiry(session: string): Promise<number>;
+    claimPresence(i: PresenceRecord, signal?: AbortSignal): Promise<PresenceClaimResult>;
+    ensurePresence(i: PresenceRecord): Promise<PresenceResult>;
     removePresence(i: PresenceKey): Promise<void>;
+    removePresenceIfUnchanged(i: PresenceRecord): Promise<boolean>;
     listPresence(i?: PresenceLookup): Promise<readonly PresenceRecord[]>;
     claimWakeDispatch(i: WakeDispatchClaimInput): Promise<WakeDispatchClaim>;
     transitionWakeDispatch(i: WakeDispatchTransitionInput): Promise<boolean>;
@@ -34,6 +37,5 @@ export declare class FileHostLedgerPort implements HostLedgerPort {
     }): Promise<void>;
     listEvidence(i?: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
     gcEvidence(i: EvidenceGc): Promise<void>;
-    reconcileBinding(i?: ReconcileBindingInput): Promise<ReconcileBindingResult>;
 }
-export declare function createHostLedgerPort(o?: HostLedgerFileAdapterOptions): HostLedgerPort;
+export declare function createHostLedgerPort(o?: HostLedgerFileAdapterOptions): FileHostLedgerPort;

package/dist/host-ledger-file-adapter.js

@@ -1,14 +1,18 @@
 import { promises as fs } from 'node:fs';
 import fsSync from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { withFileLock as acquireFileLock } from './file-lock.js';
 import { nameKey } from './model.js';
-import { isCurrentlyJoined } from './runtime.js';
+import { hostLedgerRoot } from './host-ledger-root.js';
+import { observeFileMetadata } from './file-changes.js';
 const LOCK = { retryMs: 10 };
 const RETENTION = 7 * 86400000;
 // Prepare before locking: lock databases and their journals are local runtime data too.
 async function withFileLock(file, options, fn) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error('File lock acquisition aborted');
     const directory = path.dirname(file);
     await fs.mkdir(directory, { recursive: true });
     try {
@@ -56,8 +60,35 @@ catch (e) {
         return [];
     throw e;
 } }
-async function write(file, rows) { await fs.mkdir(path.dirname(file), { recursive: true }); const tmp = `${file}.${process.pid}.${Date.now()}.tmp`; await fs.writeFile(tmp, rows.length ? rows.map(row => JSON.stringify(row)).join('\n') + '\n' : '', { mode: 0o600 }); await fs.rename(tmp, file); }
-function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind, v.scope ?? null]); }
+/** Keep the old ledger intact while Windows readers briefly deny replacement.
+ * The owning file lock stays held throughout; never unlink the destination. */
+async function write(file, rows, signal) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        if (signal?.aborted)
+            throw signal.reason ?? new Error('Ledger write aborted');
+        await fs.writeFile(tmp, rows.length ? rows.map((row) => JSON.stringify(row)).join('\n') + '\n' : '', { mode: 0o600, flag: 'wx' });
+        for (let attempt = 0;; attempt += 1) {
+            if (signal?.aborted)
+                throw signal.reason ?? new Error('Ledger write aborted');
+            try {
+                await fs.rename(tmp, file);
+                return;
+            }
+            catch (error) {
+                const code = error.code;
+                if (attempt >= 5 || (code !== 'EPERM' && code !== 'EACCES' && code !== 'EBUSY'))
+                    throw error;
+                await sleep(10 * 2 ** attempt, undefined, { signal });
+            }
+        }
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+    }
+}
+function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind]); }
 function evidenceKey(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.activity, v.kind, v.attemptN ?? null]); }
 async function readClaims(file, now) { try {
     return (await fs.readFile(file, 'utf8')).split('\n').flatMap(line => { try {
@@ -81,50 +112,103 @@ function processAlive(pid) { if (pid === undefined)
 catch (error) {
     return error.code === 'ESRCH' ? false : true;
 } }
-async function writeClaims(file, rows) { await fs.mkdir(path.dirname(file), { recursive: true }); const tmp = `${file}.${process.pid}.${Date.now()}.tmp`; await fs.writeFile(tmp, rows.length ? rows.map(row => JSON.stringify(row)).join('\n') + '\n' : '', { mode: 0o600 }); await fs.rename(tmp, file); }
+function writeClaims(file, rows) { return write(file, rows); }
 export class FileHostLedgerPort {
-    user;
-    local;
-    writable;
-    readable;
+    root;
     claims;
     clock;
-    constructor(o = {}) { const testRoot = process.env.SQUARE_REGISTRY ? path.dirname(process.env.SQUARE_REGISTRY) : undefined; this.user = canonRoot(o.userPath ?? (testRoot ?? path.join(os.homedir(), '.square', 'host-ledger'))); this.local = canonRoot(o.localPath ?? (testRoot ?? path.join(process.cwd(), '.square', 'host-ledger'))); this.writable = o.writableScope ?? 'local'; this.readable = o.readableScopes ?? ['user', 'local']; this.claims = canonRoot(o.claimsPath ?? path.join(this.user, 'wake-claims.ndjsonl')); this.clock = o.now ?? Date.now; }
-    file(s, f) { return path.join(s === 'user' ? this.user : this.local, `${f}.ndjsonl`); }
-    async claimPresence(i, scope = this.writable) { const location = await canon(i.location), r = { ...i, location, scope, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }, lock = path.join(this.user, 'presence-claim.lock'); try {
-        return await withFileLock(lock, LOCK, async () => { const candidates = []; for (const s of ['user', 'local']) {
-            for (const row of await read(this.file(s, 'presence'), this.clock(), true)) {
-                if ((row.scope ?? s) !== s || row.location !== location || nameKey(row.participant) !== nameKey(r.participant))
-                    continue;
-                candidates.push(s === 'user' ? row : { ...row, route: undefined });
+    constructor(o = {}) {
+        this.root = canonRoot(o.rootPath ?? hostLedgerRoot());
+        this.claims = canonRoot(o.claimsPath ?? path.join(this.root, 'wake-claims.ndjsonl'));
+        this.clock = o.now ?? Date.now;
+    }
+    file(kind) { return path.join(this.root, `${kind}.ndjsonl`); }
+    /** Invalidation only: callers still use the ledger projections as their authority. */
+    async observeChanges() {
+        const presence = await observeFileMetadata(this.file('presence'));
+        try {
+            return { presence, evidence: await observeFileMetadata(this.file('evidence')) };
+        }
+        catch (error) {
+            presence.close();
+            throw error;
+        }
+    }
+    /** Time can expire bindings/evidence even when their files do not change. */
+    async nextExpiry(session) {
+        const now = this.clock();
+        const rows = [...await read(this.file('presence'), now, true),
+            ...await read(this.file('evidence'), now, true)].filter((row) => row.session === session);
+        let next = Infinity;
+        for (const row of rows) {
+            const at = 'updatedAt' in row ? row.updatedAt : 'at' in row ? row.at : undefined;
+            if (typeof at === 'number') {
+                if (at > now)
+                    next = Math.min(next, at);
+                if (at + RETENTION + 1 > now && !('kind' in row && row.kind === 'wake' && row.outcome === 'accepted'))
+                    next = Math.min(next, at + RETENTION + 1);
             }
-        } const existing = candidates.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0]; if (existing !== undefined) {
-            if (existing.session === r.session)
-                return { status: 'owned', record: existing };
-            return { status: 'busy', record: existing };
-        } const f = this.file(scope, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k({ ...x, scope: x.scope ?? scope }) !== k(r)), r])); return { status: 'acquired', record: r }; });
+            if ('expiresAt' in row && typeof row.expiresAt === 'number' && row.expiresAt > now)
+                next = Math.min(next, row.expiresAt);
+        }
+        return next;
     }
-    catch (error) {
-        return { status: 'degraded', record: r, error };
-    } }
-    async ensurePresence(i, scope = this.writable) { const r = { ...i, location: await canon(i.location), scope, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }; const f = this.file(scope, 'presence'); try {
-        await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k({ ...x, scope: x.scope ?? scope }) !== k(r)), r]));
-        return { status: 'ensured', record: r };
+    async claimPresence(i, signal) {
+        const location = await canon(i.location);
+        const record = { ...i, location, updatedAt: i.updatedAt ?? this.clock(), v: 1 };
+        try {
+            return await withFileLock(path.join(this.root, 'presence-claim.lock'), { ...LOCK, signal }, async () => {
+                const file = this.file('presence');
+                // The authoritative read, ownership check, and write share the presence file lock:
+                // a concurrent ensurePresence/removePresence between them must never be overwritten
+                // by a stale snapshot.
+                return withFileLock(file + '.lock', { ...LOCK, signal }, async () => {
+                    const rows = await read(file, this.clock(), true);
+                    const existing = rows.filter((row) => row.location === location && nameKey(row.participant) === nameKey(record.participant)).sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0];
+                    if (existing !== undefined)
+                        return existing.session === record.session ? { status: 'owned', record: existing } : { status: 'busy', record: existing };
+                    await write(file, [...rows, record], signal);
+                    return { status: 'acquired', record };
+                });
+            });
+        }
+        catch (error) {
+            return { status: 'degraded', record, error };
+        }
+    }
+    async ensurePresence(i) {
+        const record = { ...i, location: await canon(i.location), updatedAt: i.updatedAt ?? this.clock(), v: 1 };
+        try {
+            await withFileLock(this.file('presence') + '.lock', LOCK, async () => write(this.file('presence'), [...(await read(this.file('presence'), this.clock(), true)).filter((row) => k(row) !== k(record)), record]));
+            return { status: 'ensured', record };
+        }
+        catch (error) {
+            return { status: 'degraded', record, error };
+        }
+    }
+    async removePresence(i) {
+        const record = { ...i, location: await canon(i.location) };
+        await withFileLock(this.file('presence') + '.lock', LOCK, async () => write(this.file('presence'), (await read(this.file('presence'), this.clock(), true)).filter((row) => k(row) !== k(record))));
+    }
+    async removePresenceIfUnchanged(i) {
+        const record = { ...i, location: await canon(i.location) };
+        return withFileLock(this.file('presence') + '.lock', LOCK, async () => {
+            const file = this.file('presence');
+            const rows = await read(file, this.clock(), true);
+            const matches = (row) => k(row) === k(record)
+                && (row.epoch ?? undefined) === (record.epoch ?? undefined)
+                && (row.updatedAt ?? undefined) === (record.updatedAt ?? undefined);
+            const current = rows.findLast(matches);
+            if (current === undefined)
+                return false;
+            await write(file, rows.filter((row) => row !== current));
+            return true;
+        });
+    }
+    async listPresence(i = {}) {
+        const location = i.location === undefined ? undefined : await canon(i.location);
+        return (await read(this.file('presence'), i.now ?? this.clock())).filter((row) => (!location || row.location === location) && (!i.participant || nameKey(row.participant) === nameKey(i.participant)) && (!i.session || row.session === i.session)).map(({ scope: _scope, ...row }) => row);
     }
-    catch (error) {
-        return { status: 'degraded', record: r, error };
-    } }
-    async removePresence(i) { const r = { ...i, location: await canon(i.location), scope: this.writable }, f = this.file(this.writable, 'presence'), shared = this.user === this.local; await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(x => { const rowScope = x.scope ?? this.writable; return shared ? k({ ...x, scope: rowScope }) !== k({ ...r, scope: rowScope }) : k({ ...x, scope: rowScope }) !== k(r); }))); }
-    async listPresence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location), m = new Map(); for (const s of i.scopes ?? this.readable)
-        for (const r of await read(this.file(s, 'presence'), i.now ?? this.clock())) {
-            if ((r.scope ?? s) !== s || loc && r.location !== loc || i.participant && nameKey(r.participant) !== nameKey(i.participant) || i.session && r.session !== i.session)
-                continue;
-            const x = s === 'user' ? r : { ...r, route: undefined }, key = k({ ...x, scope: undefined }), old = m.get(key);
-            if (old?.scope === 'user' && s === 'local')
-                continue;
-            if (!old || s === 'user' || x.updatedAt >= old.record.updatedAt)
-                m.set(key, { record: x, scope: s });
-        } return [...m.values()].map(({ record }) => { const { scope: _scope, ...publicRecord } = record; return publicRecord; }); }
     async claimWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), existing = rows.find((row) => row.attention_key === key); if (existing?.phase === 'dispatching') {
         const alive = processAlive(existing.ownerPid);
         if (existing.expiresAt <= at || alive === false)
@@ -145,7 +229,7 @@ export class FileHostLedgerPort {
     async listWakeAttempts(i = {}) { const attention = i.attention; return this.listEvidence({ kind: 'wake', ...(attention === undefined ? {} : { location: await canon(attention.squarePath), participant: attention.recipient, activity: `act/${attention.actIndex}` }), ...(i.session === undefined ? {} : { session: i.session }), now: i.now }); }
     async appendWakeAttempt(i) { if (i.kind !== 'wake')
         throw new Error('Wake attempt rows require wake evidence kind'); await this.appendEvidence(i); }
-    async claimEvidence(i) { const f = this.file('user', 'evidence'), at = i.now ?? this.clock(), { leaseMs, claimToken: requestedToken, ...claim } = i, r = { ...claim, location: await canon(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 }; try {
+    async claimEvidence(i) { const f = this.file('evidence'), at = i.now ?? this.clock(), { leaseMs, claimToken: requestedToken, ...claim } = i, r = { ...claim, location: await canon(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 }; try {
         return await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), matching = all.filter(x => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session), old = matching.findLast(x => x.outcome === 'dispatching'); if (old !== undefined && typeof old.expiresAt === 'number' && old.expiresAt > at)
             return { status: 'busy', record: old }; const delivered = (r.kind === 'wake' && matching.some(x => x.outcome === 'accepted')) || (r.kind === 'presentation' && matching.some(x => x.outcome === 'presented')); if (delivered)
             return { status: 'delivered', record: matching.findLast(x => x.outcome === 'accepted' || x.outcome === 'presented') }; const index = Number(r.activity.slice(4)), attentionKey = JSON.stringify([r.location, nameKey(r.participant), index, r.session ?? null, 'wake']), dispatchToken = r.kind === 'wake' && typeof requestedToken === 'string' && Number.isInteger(index) && (await readClaims(this.claims, at)).some((row) => row.leaseId === requestedToken && row.attention_key === attentionKey) ? requestedToken : undefined, claimToken = dispatchToken ?? `${process.pid}-${at}-${Math.random().toString(36).slice(2)}`, row = { ...r, claimToken }; await write(f, [...all.filter(x => !(x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session && (x.outcome === 'dispatching' || x.outcome === 'released'))), row]); return { status: 'acquired', claimToken }; });
@@ -153,44 +237,12 @@ export class FileHostLedgerPort {
     catch (error) {
         return { status: 'degraded', error };
     } }
-    async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), same = (x) => x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session, current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== i.claimToken)
+    async releaseEvidence(i) { const f = this.file('evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), same = (x) => x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session, current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== i.claimToken)
         return; const tombstone = { ...current, outcome: 'released', at, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.signature === undefined ? {} : { signature: i.signature }), ...(i.message === undefined ? {} : { message: i.message }), ...(i.diagnostic === undefined ? {} : { diagnostic: i.diagnostic }), expiresAt: undefined }; delete tombstone.expiresAt; await write(f, [...all.filter(x => x !== current), tombstone]); }); }
-    async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; const token = i.claimToken; if (typeof token !== 'string' || token.length === 0)
+    async appendEvidence(i) { const f = this.file('evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; const token = i.claimToken; if (typeof token !== 'string' || token.length === 0)
         return; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const same = (x) => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session; const current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== token)
         return; const terminalKey = (x) => same(x) && x.attemptN === r.attemptN && x.outcome !== 'dispatching' && x.outcome !== 'released'; await write(f, [...all.filter(x => x !== current && !terminalKey(x)), r]); }); }
-    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || r.outcome !== 'released') && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
-    async gcEvidence(i) { const f = this.file('user', 'evidence'), pending = new Set(i.pendingWakeActivities ?? []); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(r => r.at >= i.before || r.kind === 'wake' && r.outcome === 'accepted' && pending.has(r.activity)))); }
-    async reconcileBinding(i = {}) { let b = []; try {
-        b = [...await this.listPresence({ scopes: i.scopes, now: i.now })];
-        if (i.artifact) {
-            const { state } = await i.artifact.read();
-            const stale = b.filter(x => !isCurrentlyJoined(state.acts, x.participant));
-            for (const x of stale) {
-                for (const scope of i.scopes ?? this.readable) {
-                    const remover = new FileHostLedgerPort({ userPath: this.user, localPath: this.local, writableScope: scope, readableScopes: [scope], now: this.clock });
-                    await remover.removePresence(x);
-                }
-            }
-            b = b.filter(x => !stale.includes(x));
-        }
-        const latest = new Map();
-        for (const x of b) {
-            const key = JSON.stringify([x.location, nameKey(x.participant), x.session]);
-            const current = latest.get(key);
-            if (current === undefined || ((x.updatedAt ?? 0) > (current.updatedAt ?? 0)))
-                latest.set(key, x);
-        }
-        const winners = [...latest.values()];
-        const u = new FileHostLedgerPort({ userPath: this.user, localPath: this.local, writableScope: 'user', readableScopes: ['user'], now: this.clock });
-        for (const x of winners) {
-            const result = await u.ensurePresence(x);
-            if (result.status === 'degraded')
-                return { status: 'degraded', bindings: winners, error: result.error };
-        }
-        return { status: 'reconciled', bindings: winners };
-    }
-    catch (error) {
-        return { status: 'degraded', bindings: b, error };
-    } }
+    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || r.outcome !== 'released') && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
+    async gcEvidence(i) { const f = this.file('evidence'), pending = new Set(i.pendingWakeActivities ?? []); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(r => r.at >= i.before || r.kind === 'wake' && r.outcome === 'accepted' && pending.has(r.activity)))); }
 }
 export function createHostLedgerPort(o = {}) { return new FileHostLedgerPort(o); }

package/dist/host-ledger-root.d.ts

@@ -0,0 +1,2 @@
+/** Resolve the single user-level host ledger root. */
+export declare function hostLedgerRoot(env?: NodeJS.ProcessEnv): string;

package/dist/host-ledger-root.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { homedir } from 'node:os';
+/** Resolve the single user-level host ledger root. */
+export function hostLedgerRoot(env = process.env) {
+    return env.SQUARE_HOST_LEDGER_ROOT
+        ?? (env.SQUARE_REGISTRY === undefined
+            ? path.join(homedir(), '.square', 'host-ledger')
+            : path.dirname(env.SQUARE_REGISTRY));
+}