@astrosheep/square 0.3.30 → 0.3.32

package/dist/help.js

@@ -43,7 +43,7 @@ const COMMANDS = [
     {
         names: ['history'], usage: '[--as <name>] 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>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --pending                       Match attention waiting for --as <name>.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --full  --json  --format <fields>', '  Without --as, the default view shows complete activity bodies.'],
+        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.', '  --pending                       Match attention waiting for --as <name>.', '  --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).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  Bodies are previews by default; --no-truncate expands them. --as keeps participant perception.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
     { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },

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

@@ -0,0 +1,34 @@
+import type { HostLedgerPort, HostLedgerScope, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, ReconcileBindingInput, ReconcileBindingResult, WakeDispatchClaim, WakeDispatchClaimInput, WakeDispatchReleaseInput, WakeDispatchTransitionInput, WakeAttemptLookup } from './host-ledger.js';
+export interface HostLedgerFileAdapterOptions {
+    userPath?: string;
+    localPath?: string;
+    writableScope?: HostLedgerScope;
+    readableScopes?: readonly HostLedgerScope[];
+    claimsPath?: string;
+    now?: () => number;
+}
+export declare class FileHostLedgerPort implements HostLedgerPort {
+    private readonly user;
+    private readonly local;
+    private readonly writable;
+    private readonly readable;
+    private readonly claims;
+    private readonly clock;
+    constructor(o?: HostLedgerFileAdapterOptions);
+    private file;
+    ensurePresence(i: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
+    removePresence(i: PresenceKey): Promise<void>;
+    listPresence(i?: PresenceLookup): Promise<readonly PresenceRecord[]>;
+    claimWakeDispatch(i: WakeDispatchClaimInput): Promise<WakeDispatchClaim>;
+    transitionWakeDispatch(i: WakeDispatchTransitionInput): Promise<boolean>;
+    releaseWakeDispatch(i: WakeDispatchReleaseInput): Promise<void>;
+    listWakeAttempts(i?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
+    appendWakeAttempt(i: EvidenceRecord): Promise<void>;
+    claimEvidence(i: EvidenceClaim): Promise<ClaimResult>;
+    releaseEvidence(i: EvidenceRelease): Promise<void>;
+    appendEvidence(i: EvidenceRecord): 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;

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

@@ -0,0 +1,156 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { withFileLock } from './file-lock.js';
+import { nameKey } from './model.js';
+import { isCurrentlyJoined } from './runtime.js';
+const LOCK = { retryMs: 10, staleMs: 300000 };
+const RETENTION = 7 * 86400000;
+async function canon(value) { const absolute = path.resolve(value); try {
+    return await fs.realpath(absolute);
+}
+catch {
+    return absolute;
+} }
+async function read(file, now, includeFuture = false) { try {
+    return (await fs.readFile(file, 'utf8')).split('\n').flatMap(line => { try {
+        const row = JSON.parse(line);
+        const at = row.at ?? row.updatedAt;
+        return row.v === 1 && typeof at === 'number' && at >= now - RETENTION && (includeFuture || at <= now) ? [row] : [];
+    }
+    catch {
+        return [];
+    } });
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        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]); }
+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 {
+        const row = JSON.parse(line);
+        return row.v === 1 && typeof row.ts === 'number' && typeof row.attention_key === 'string' && typeof row.leaseId === 'string' && typeof row.expiresAt === 'number' && (row.phase === 'claimed' || row.phase === 'dispatching') && row.ts >= now - RETENTION ? [row] : [];
+    }
+    catch {
+        return [];
+    } });
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return [];
+    throw e;
+} }
+function processAlive(pid) { if (pid === undefined)
+    return undefined; try {
+    process.kill(pid, 0);
+    return true;
+}
+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); }
+export class FileHostLedgerPort {
+    user;
+    local;
+    writable;
+    readable;
+    claims;
+    clock;
+    constructor(o = {}) { const testRoot = process.env.SQUARE_REGISTRY ? path.dirname(process.env.SQUARE_REGISTRY) : undefined; this.user = o.userPath ?? (testRoot ?? path.join(os.homedir(), '.square', 'host-ledger')); this.local = o.localPath ?? (testRoot ?? path.join(process.cwd(), '.square', 'host-ledger')); this.writable = o.writableScope ?? 'local'; this.readable = o.readableScopes ?? ['user', 'local']; this.claims = 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 ensurePresence(i, scope = this.writable) { const r = { ...i, location: await canon(i.location), ...(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) !== k(r)), r]));
+        return { status: 'ensured', record: r };
+    }
+    catch (error) {
+        return { status: 'degraded', record: r, error };
+    } }
+    async removePresence(i) { const r = { ...i, location: await canon(i.location) }, f = this.file(this.writable, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(x => k(x) !== 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 (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), 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 }) => record); }
+    async claimWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, '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)
+            return { type: 'ambiguous', lease: existing };
+        return { type: 'busy' };
+    } if (existing !== undefined && existing.expiresAt > at)
+        return { type: 'busy' }; const next = { v: 1, ts: at, attention_key: key, leaseId: i.leaseId, expiresAt: at + i.leaseMs, phase: 'claimed', ownerPid: process.pid, ...(i.session === undefined ? {} : { session: i.session }) }; await writeClaims(this.claims, [...rows.filter((row) => row.attention_key !== key), next]); return { type: 'acquired', leaseId: i.leaseId }; }); }
+    async transitionWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), current = rows.find((row) => { if (row.leaseId !== i.leaseId)
+        return false; try {
+        const parts = JSON.parse(row.attention_key);
+        return parts[0] === location && parts[1] === nameKey(i.attention.recipient) && parts[2] === i.attention.actIndex;
+    }
+    catch {
+        return false;
+    } }); if (current === undefined)
+        return false; const next = { v: 1, ts: at, attention_key: key, leaseId: i.leaseId, expiresAt: at + i.leaseMs, phase: i.phase, ownerPid: current.ownerPid, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.session === undefined ? {} : { session: i.session }) }; await writeClaims(this.claims, [...rows.filter((row) => row !== current), next]); return true; }); }
+    async releaseWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, 'wake']), at = i.at ?? this.clock(); await withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at); await writeClaims(this.claims, rows.filter((row) => { if (row.attention_key === key)
+        return false; if (row.leaseId !== i.leaseId)
+        return true; try {
+        const parts = JSON.parse(row.attention_key);
+        return parts[0] !== location || parts[1] !== nameKey(i.attention.recipient) || parts[2] !== i.attention.actIndex || (i.session !== undefined && parts[3] !== i.session);
+    }
+    catch {
+        return true;
+    } })); }); }
+    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'); return this.appendEvidence(i); }
+    async claimEvidence(i) { const f = this.file('user', 'evidence'), at = i.now ?? this.clock(), { leaseMs, ...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') }; 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')), r]); return { status: 'acquired' }; });
+    }
+    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 () => write(f, (await read(f, at, true)).filter(x => !(x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session && x.outcome === 'dispatching')))); }
+    async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const base = all.filter(x => k(x) === k(r)); const replaceable = new Set(base.filter(x => x.outcome === 'dispatching' || (r.attemptN !== undefined && x.attemptN === r.attemptN)).map(x => evidenceKey(x))); await write(f, [...all.filter(x => !(x.outcome === 'dispatching' && k(x) === k(r)) && !replaceable.has(evidenceKey(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 => (!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'); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock())).filter(r => r.at >= i.before))); }
+    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 };
+    } }
+}
+export function createHostLedgerPort(o = {}) { return new FileHostLedgerPort(o); }

package/dist/host-ledger.d.ts

@@ -0,0 +1,160 @@
+import type { WakeRouteKind } from './model.js';
+export type HostLedgerScope = 'user' | 'local';
+export type PresenceChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
+export interface PresenceRecord {
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly channel: PresenceChannel;
+    readonly route?: {
+        readonly kind: WakeRouteKind;
+        readonly address: Readonly<Record<string, string>>;
+    };
+    readonly updatedAt?: number;
+}
+export type PresenceKey = Pick<PresenceRecord, 'location' | 'participant' | 'session' | 'channel'>;
+export interface PresenceLookup {
+    readonly location?: string;
+    readonly participant?: string;
+    readonly session?: string;
+    readonly scopes?: readonly HostLedgerScope[];
+    readonly now?: number;
+}
+export type PresenceResult = {
+    readonly status: 'ensured';
+    readonly record: PresenceRecord;
+} | {
+    readonly status: 'degraded';
+    readonly record: PresenceRecord;
+    readonly error: unknown;
+};
+export interface EvidenceRecord {
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly activity: string;
+    readonly kind: 'wake' | 'presentation';
+    readonly outcome: string;
+    readonly at?: number;
+    readonly expiresAt?: number;
+    readonly routeKind?: WakeRouteKind;
+    readonly signature?: string;
+    readonly attemptN?: number;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
+export interface EvidenceClaim {
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly activity: string;
+    readonly kind: EvidenceRecord['kind'];
+    readonly leaseMs: number;
+    readonly now?: number;
+}
+export type EvidenceRelease = Omit<EvidenceClaim, 'leaseMs'>;
+export interface EvidenceLookup {
+    readonly location?: string;
+    readonly participant?: string;
+    readonly session?: string;
+    readonly activity?: string;
+    readonly kind?: EvidenceRecord['kind'];
+    readonly now?: number;
+}
+export interface EvidenceGc {
+    readonly before: number;
+}
+export interface WakeAttention {
+    readonly squarePath: string;
+    readonly actIndex: number;
+    readonly recipient: string;
+}
+export interface WakeDispatchLease {
+    readonly leaseId: string;
+    readonly expiresAt: number;
+    readonly phase: 'claimed' | 'dispatching';
+    readonly routeKind?: WakeRouteKind;
+    readonly attemptN?: number;
+    readonly session?: string;
+}
+export type WakeDispatchClaim = {
+    readonly type: 'acquired';
+    readonly leaseId: string;
+} | {
+    readonly type: 'busy';
+} | {
+    readonly type: 'ambiguous';
+    readonly lease: WakeDispatchLease;
+};
+export interface WakeDispatchClaimInput {
+    readonly attention: WakeAttention;
+    readonly leaseId: string;
+    readonly leaseMs: number;
+    readonly session?: string;
+    readonly at?: number;
+}
+export interface WakeDispatchTransitionInput {
+    readonly attention: WakeAttention;
+    readonly leaseId: string;
+    readonly phase: WakeDispatchLease['phase'];
+    readonly leaseMs: number;
+    readonly routeKind?: WakeRouteKind;
+    readonly attemptN?: number;
+    readonly session?: string;
+    readonly at?: number;
+}
+export interface WakeDispatchReleaseInput {
+    readonly attention: WakeAttention;
+    readonly leaseId: string;
+    readonly session?: string;
+    readonly at?: number;
+}
+export interface WakeAttemptLookup {
+    readonly attention?: WakeAttention;
+    readonly session?: string;
+    readonly now?: number;
+}
+export type ClaimResult = {
+    readonly status: 'acquired';
+} | {
+    readonly status: 'busy' | 'delivered';
+    readonly record: EvidenceRecord;
+} | {
+    readonly status: 'degraded';
+    readonly error: unknown;
+};
+export interface ReconcileBindingInput {
+    readonly scopes?: readonly HostLedgerScope[];
+    readonly now?: number;
+    readonly artifact?: {
+        read(): Promise<{
+            state: {
+                acts: readonly {
+                    kind: string;
+                    actor?: string;
+                }[];
+            };
+        }>;
+    };
+}
+export type ReconcileBindingResult = {
+    readonly status: 'reconciled' | 'degraded';
+    readonly bindings: readonly PresenceRecord[];
+    readonly error?: unknown;
+};
+export interface HostLedgerPort {
+    ensurePresence(input: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
+    removePresence(input: PresenceKey): Promise<void>;
+    listPresence(input: PresenceLookup): Promise<readonly PresenceRecord[]>;
+    claimEvidence(input: EvidenceClaim): Promise<ClaimResult>;
+    releaseEvidence(input: EvidenceRelease): Promise<void>;
+    appendEvidence(input: EvidenceRecord): Promise<void>;
+    listEvidence(input: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
+    listWakeAttempts(input?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
+    appendWakeAttempt(input: EvidenceRecord): Promise<void>;
+    claimWakeDispatch(input: WakeDispatchClaimInput): Promise<WakeDispatchClaim>;
+    transitionWakeDispatch(input: WakeDispatchTransitionInput): Promise<boolean>;
+    releaseWakeDispatch(input: WakeDispatchReleaseInput): Promise<void>;
+    gcEvidence(input: EvidenceGc): Promise<void>;
+    reconcileBinding(input: ReconcileBindingInput): Promise<ReconcileBindingResult>;
+}

package/dist/host-ledger.js

@@ -0,0 +1 @@
+export {};

package/dist/inbox.d.ts

@@ -6,6 +6,6 @@ export interface PendingWaitOptions {
     /** After a delivery failure, wait for a new state edge before retrying the same pending work. */
     skipImmediate?: boolean;
 }
-export declare function sessionInbox(sessionId: string): Promise<InboxMembership[]>;
+export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;
 /** Wait for a bound square to produce a new pending notification without consuming it. */
-export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;
+export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;

package/dist/inbox.js

@@ -1,8 +1,16 @@
-import { lookupSessionBindings } from './registry.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
-import { inboxProjection } from './views.js';
 import { waitForSquareChanges } from './square-file-adapter.js';
+import path from 'node:path';
+import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+import { projectPresentation, projectSessionBindings } from './square-projections.js';
+function hostLedgerForEnv(env) {
+    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    return createHostLedgerPort({
+        userPath: env.SQUARE_HOST_LEDGER_USER ?? root,
+        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root,
+    });
+}
 function notificationKey(membership, actIndex) {
     return `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${actIndex}`;
 }
@@ -16,19 +24,19 @@ function withoutExcluded(inbox, excludeKeys) {
     }))
         .filter((membership) => membership.notifications.length > 0);
 }
-export async function sessionInbox(sessionId) {
+export async function sessionInbox(sessionId, env = process.env) {
     const inbox = [];
-    for (const binding of await lookupSessionBindings(sessionId)) {
+    const hostLedger = hostLedgerForEnv(env);
+    for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
         let square;
         try {
-            square = await openSquare(binding.squarePath);
-            const projection = await inboxProjection(square, binding.name, binding.ownerId);
+            square = await openSquare(binding.location, { env, hostLedger });
+            const projection = await projectPresentation({ artifact: square.artifact, binding, now: square.clock() });
             if (!projection.joined)
                 continue;
             inbox.push({
-                name: projection.name,
-                squarePath: binding.squarePath,
-                ownerId: binding.ownerId,
+                name: projection.binding.participant,
+                squarePath: projection.binding.location,
                 notifications: [...projection.notifications],
                 ...(projection.catchLease !== undefined ? { catchLease: projection.catchLease } : {}),
             });
@@ -44,17 +52,17 @@ export async function sessionInbox(sessionId) {
     return inbox;
 }
 /** Wait for a bound square to produce a new pending notification without consuming it. */
-export async function waitForSessionPending(sessionId, timeoutMs, options = {}) {
+export async function waitForSessionPending(sessionId, timeoutMs, options = {}, env = process.env) {
     const deadline = Date.now() + Math.max(0, timeoutMs);
     if (!options.skipImmediate) {
-        const immediate = withoutExcluded(await sessionInbox(sessionId), options.excludeKeys);
+        const immediate = withoutExcluded(await sessionInbox(sessionId, env), options.excludeKeys);
         if (immediate.some((membership) => membership.notifications.length > 0))
             return immediate;
     }
     if (timeoutMs <= 0 || options.signal?.aborted)
         return [];
-    const bindings = await lookupSessionBindings(sessionId);
-    const paths = [...new Set(bindings.map((binding) => binding.squarePath))];
+    const bindings = await projectSessionBindings({ hostLedger: hostLedgerForEnv(env), sessionId });
+    const paths = [...new Set(bindings.map((binding) => binding.location))];
     let aborted = false;
     let projectAfterReady = !options.skipImmediate;
     const onAbort = () => { aborted = true; };
@@ -67,7 +75,7 @@ export async function waitForSessionPending(sessionId, timeoutMs, options = {})
             const change = await waitForSquareChanges(paths, remaining, options.signal, async () => {
                 if (!projectAfterReady)
                     return undefined;
-                const current = withoutExcluded(await sessionInbox(sessionId), options.excludeKeys);
+                const current = withoutExcluded(await sessionInbox(sessionId, env), options.excludeKeys);
                 return current.some((membership) => membership.notifications.length > 0) ? current : undefined;
             });
             if (aborted || change.status === 'expired')

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
 export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';
+export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';
+export type { HostLedgerPort, PresenceRecord, EvidenceRecord } from './host-ledger.js';
+export type { PresentationSinkPort } from './ports.js';
 export type { ActivityId } from './square-core.js';
-export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';
+export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, } from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
 export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';
+export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';

package/dist/landing.d.ts

@@ -1,22 +1,26 @@
+import type { SquareArtifactPort } from './ports.js';
 import type { OpenSquare } from './open-square.js';
+import { type ListenerChangeResult } from './square-actions.js';
 import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
-export declare function join(square: OpenSquare, name: string): Promise<{
+/** Transitional adapter for existing internal callers until they migrate to SquareArtifactPort. */
+type LegacySquare = {
+    readonly cell: SquareArtifactPort;
+    readonly clock: () => number;
+};
+export declare function join(square: OpenSquare | LegacySquare, name: string): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
 }>;
-/** Automatic presence distinguishes first entry, current presence, and completed presence. */
-export declare function implicitJoin(square: OpenSquare, name: string): Promise<{
+export declare function implicitJoin(square: OpenSquare | LegacySquare, name: string): Promise<{
     readonly name: string;
-    readonly state: 'joined' | 'active' | 'done';
+    readonly state: "joined" | "active" | "done";
     readonly activity: Activity | null;
 }>;
-export declare function express(square: OpenSquare, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
-export interface ListenerChangeResult {
-    readonly activity: Activity | null;
-}
-export declare function listen(square: OpenSquare, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function ignore(square: OpenSquare, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function listening(square: OpenSquare, actor: string): Promise<readonly string[]>;
-export declare function done(square: OpenSquare, name: string, body?: string): Promise<ExpressResult>;
-export declare function hold(square: OpenSquare, name: string, reason?: string): Promise<ExpressResult>;
-export declare function resume(square: OpenSquare, name: string): Promise<ExpressResult>;
+export declare function express(square: OpenSquare | LegacySquare, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export declare function listen(square: OpenSquare | LegacySquare, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function ignore(square: OpenSquare | LegacySquare, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function listening(square: OpenSquare | LegacySquare, actor: string): Promise<readonly string[]>;
+export declare function done(square: OpenSquare | LegacySquare, name: string, body?: string): Promise<ExpressResult>;
+export declare function hold(square: OpenSquare | LegacySquare, name: string, reason?: string): Promise<ExpressResult>;
+export declare function resume(square: OpenSquare | LegacySquare, name: string): Promise<ExpressResult>;
+export {};