@astrosheep/square 0.3.29 → 0.3.31

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

@@ -0,0 +1,165 @@
+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)).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)]);
+            const current = latest.get(key);
+            if (current === undefined || ((x.updatedAt ?? 0) > (current.updatedAt ?? 0)))
+                latest.set(key, x);
+        }
+        const winners = [...latest.values()];
+        for (const x of b) {
+            const winner = latest.get(JSON.stringify([x.location, nameKey(x.participant)]));
+            if (winner === undefined || winner.session === x.session)
+                continue;
+            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);
+            }
+        }
+        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 {};

package/dist/landing.js

@@ -1,126 +1,42 @@
-import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
-import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin } from './decisions.js';
-import { deriveDeliveryModel } from './delivery.js';
-import { SquareError } from './model.js';
-import { participantIdentity } from './participant-identity.js';
-function storeActs(state, acts) {
-    const stored = [];
-    for (const act of acts) {
-        const item = { ...act, index: state.runtime.nextActIndex };
-        state.runtime.nextActIndex += 1;
-        state.acts.push(item);
-        stored.push(item);
-    }
-    return stored;
-}
-function committedActivity(stored, verb) {
-    const activity = stored[0];
-    if (activity === undefined)
-        throw new Error(`${verb} activity did not commit`);
-    return activity;
-}
-function exposeActivity(stored) {
-    if (stored.kind === 'read' || stored.actor === undefined)
-        throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
+import { done as applyDone, express as applyExpress, hold as applyHold, ignore as applyIgnore, implicitJoin as applyImplicitJoin, join as applyJoin, listen as applyListen, listening as applyListening, resume as applyResume, } from './square-actions.js';
+function artifactOf(square) {
+    if ('artifact' in square)
+        return square.artifact;
+    const { cell } = square;
     return {
-        id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
-        ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
-        mentions: stored.kind === 'say' ? extractMentions(stored.body) : [],
-        ...('target' in stored ? { target: stored.target } : {}),
-        ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}),
+        read: () => cell.read(),
+        transact: (fn) => cell.transact(fn),
+        changed: (sinceVersion, timeoutMs) => cell.changed(sinceVersion, timeoutMs),
+        close: () => cell.close(),
     };
 }
-function parseRequiredActivityId(id) {
-    const index = parseActivityId(id);
-    if (index === undefined)
-        throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
-    return index;
-}
-async function wakeAfterCommit(square, recipients, activity) {
-    if (recipients.length === 0)
-        return;
-    try {
-        square.notifier?.wake(recipients, activity);
-    }
-    catch { /* post-commit effects cannot undo activities */ }
+function contextOf(square) {
+    return { artifact: artifactOf(square), clock: square.clock, ...('location' in square ? { location: square.location, hostLedger: square.hostLedger, env: square.env } : {}) };
 }
-export async function join(square, name) {
-    const now = square.clock();
-    const committed = await square.cell.transact((state) => {
-        const decision = decideJoin(state, name, now);
-        if (decision.joinAct === undefined)
-            return { result: { name: decision.joinedName, stored: null } };
-        return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
-    });
-    return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+export function join(square, name) {
+    return applyJoin(contextOf(square), name);
 }
-/** Automatic presence distinguishes first entry, current presence, and completed presence. */
-export async function implicitJoin(square, name) {
-    const now = square.clock();
-    const committed = await square.cell.transact((state) => {
-        const decision = decideImplicitJoin(state, name, now);
-        if (decision.joinAct === undefined)
-            return { result: { name: decision.joinedName, state: decision.state, stored: null } };
-        return { state, result: { name: decision.joinedName, state: decision.state, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
-    });
-    return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+export function implicitJoin(square, name) {
+    return applyImplicitJoin(contextOf(square), name);
 }
-export async function express(square, name, body, options = {}) {
-    const now = square.clock();
-    const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
-    const committed = await square.cell.transact((state) => {
-        const decision = decideAct(state, { name, body, force: options.force ?? false, now, ...(options.reach === undefined ? {} : { reach: options.reach }), ...(reply === undefined ? {} : { reply }) });
-        if (decision.type === 'blocked') {
-            const pending = decision.activitySummaries.reduce((count, summary) => count + summary.count, 0) + decision.unreadRoomChanges.length;
-            throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending });
-        }
-        if (decision.type === 'held') {
-            const holder = state.acts.filter((activity) => activity.kind === 'hold').at(-1)?.actor;
-            throw new SquareError('held', 'The square is held', holder === undefined ? undefined : { holder });
-        }
-        if (decision.type === 'capped')
-            throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
-        if (decision.type === 'throttled')
-            throw new SquareError('throttled', `${name} is throttled`, { retryAfterMs: decision.delayMs });
-        if (decision.type === 'bell_quota')
-            throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, decision.nextAt - now) });
-        const stored = committedActivity(storeActs(state, [decision.act]), 'express');
-        return { state, result: { stored, recipients: deriveDeliveryModel(state).plan(stored).map((notification) => notification.recipient) } };
-    });
-    const activity = exposeActivity(committed.stored);
-    await wakeAfterCommit(square, committed.recipients, activity);
-    return { activity };
-}
-async function landListenerChange(square, verb, actor, target) {
-    const now = square.clock();
-    const stored = await square.cell.transact((state) => {
-        const act = verb === 'listen'
-            ? coreListen(state, actor, target, now)
-            : coreIgnore(state, actor, target, now);
-        if (act === undefined)
-            return { result: null };
-        return { state, result: committedActivity(storeActs(state, [act]), verb) };
-    });
-    return { activity: stored === null ? null : exposeActivity(stored) };
+export function express(square, name, body, options) {
+    return applyExpress(contextOf(square), name, body, options);
 }
 export function listen(square, actor, target) {
-    return landListenerChange(square, 'listen', actor, target);
+    return applyListen(contextOf(square), actor, target);
 }
 export function ignore(square, actor, target) {
-    return landListenerChange(square, 'ignore', actor, target);
+    return applyIgnore(contextOf(square), actor, target);
+}
+export function listening(square, actor) {
+    return applyListening(contextOf(square), actor);
+}
+export function done(square, name, body = '') {
+    return applyDone(contextOf(square), name, body);
 }
-export async function listening(square, actor) {
-    const { state } = await square.cell.read();
-    return coreListening(state, actor);
+export function hold(square, name, reason = '') {
+    return applyHold(contextOf(square), name, reason);
 }
-async function landCore(square, verb, actor, body = '') {
-    const now = square.clock();
-    const stored = await square.cell.transact((state) => {
-        const act = verb === 'done' ? coreDone(state, actor, body, now) : verb === 'hold' ? coreHold(state, actor, body, now) : coreResume(state, actor, now);
-        return { state, result: committedActivity(storeActs(state, [act]), verb) };
-    });
-    return { activity: exposeActivity(stored) };
+export function resume(square, name) {
+    return applyResume(contextOf(square), name);
 }
-export function done(square, name, body = '') { return landCore(square, 'done', name, body); }
-export function hold(square, name, reason = '') { return landCore(square, 'hold', name, reason); }
-export function resume(square, name) { return landCore(square, 'resume', name); }