@astrosheep/square 0.3.29 → 0.3.31

package/dist/routes.d.ts

@@ -1,10 +1,11 @@
-import { type WakeRoute, type WakeRouteKind } from './model.js';
-export { isWakeRouteKind, WAKE_ROUTE_KINDS } from './model.js';
+import { type WakeRoute } from './model.js';
+export { WAKE_ROUTE_KINDS } from './model.js';
 export type { WakeRoute, WakeRouteKind } from './model.js';
 export declare const ROUTE_FRESH_MS: number;
-export declare function routesPath(env?: NodeJS.ProcessEnv): string;
 export declare function readWakeRoutes(opts?: {
-    ownerId?: string;
+    location?: string;
+    participant?: string;
+    sessionId?: string;
     freshOnly?: boolean;
     now?: number;
     env?: NodeJS.ProcessEnv;
@@ -13,35 +14,7 @@ export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opt
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
-export declare function retireOwnerWakeRoutes(ownerId: string, opts?: {
-    at?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<void>;
-/** Retire one capability without touching sibling identities in the same claim. */
-export declare function retireWakeRoute(route: Pick<WakeRoute, 'ownerId' | 'sessionId' | 'kind'>, opts?: {
-    at?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<void>;
-export interface WakeRouteEvidence {
-    sessionId: string;
-    address: Record<string, string>;
-}
-/** A provider's self-check: complete, callable endpoint evidence for one kind, or nothing. */
-export type WakeRouteProbe = (env: NodeJS.ProcessEnv) => WakeRouteEvidence | undefined;
-/**
- * One probe per kind. A probe publishes only when its provider's complete
- * endpoint evidence is present; Codex uses its thread id as that evidence.
- * The other native transports have no endpoint lifecycle in this delivery,
- * so their probes publish nothing until those transports land.
- */
-export declare const WAKE_ROUTE_PROBES: Readonly<Record<WakeRouteKind, WakeRouteProbe>>;
-/** The kind-neutral publication loop; probes supply complete evidence per kind. */
-export declare function publishWakeRoutesFrom(ownerId: string, probes: Readonly<Record<WakeRouteKind, WakeRouteProbe>>, opts?: {
-    at?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<void>;
-/** Publication boundary: every route written is complete provider evidence. */
-export declare function publishWakeRoutes(ownerId: string, opts?: {
+export declare function retireWakeRoute(route: WakeRoute, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;

package/dist/routes.js

@@ -1,173 +1,9 @@
-import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { WAKE_ROUTE_KINDS, isWakeRouteKind } from './model.js';
-export { isWakeRouteKind, WAKE_ROUTE_KINDS } from './model.js';
-const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+export { WAKE_ROUTE_KINDS } from './model.js';
 export const ROUTE_FRESH_MS = 24 * 60 * 60 * 1000;
-/**
- * Dispatch priority doubles as the kind declaration order: native kinds
- * precede paseo. Within one kind, the freshest route wins.
- */
-const ROUTE_KIND_PRIORITY = new Map(WAKE_ROUTE_KINDS.map((kind, index) => [kind, index]));
-export function routesPath(env = process.env) {
-    return env.SQUARE_ROUTES || path.join(os.homedir(), '.square', 'routes.ndjsonl');
-}
-function routeKey(ownerId, kind) {
-    return `${ownerId}\0${kind}`;
-}
-function stringRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value) &&
-        Object.values(value).every((item) => typeof item === 'string');
-}
-function parseRow(raw, now) {
-    let value;
-    try {
-        value = JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-    if (value === null || typeof value !== 'object')
-        return undefined;
-    const row = value;
-    if (row.v !== 1 ||
-        (row.op !== 'upsert' && row.op !== 'retire') ||
-        typeof row.ts !== 'number' || !Number.isFinite(row.ts) || row.ts > now || now - row.ts > RETENTION_MS ||
-        typeof row.owner_id !== 'string' || row.owner_id === '' ||
-        typeof row.session_id !== 'string' || row.session_id === '' ||
-        !isWakeRouteKind(row.kind))
-        return undefined;
-    if (row.op === 'upsert' && !stringRecord(row.address))
-        return undefined;
-    return row;
-}
-async function readRows(env, now) {
-    let raw;
-    try {
-        raw = await fs.readFile(routesPath(env), 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    return raw.split('\n').filter(Boolean).map((line) => parseRow(line, now)).filter((row) => row !== undefined);
-}
-export async function readWakeRoutes(opts = {}) {
-    const now = opts.now ?? Date.now();
-    const state = new Map();
-    for (const row of await readRows(opts.env ?? process.env, now)) {
-        const key = routeKey(row.owner_id, row.kind);
-        const current = state.get(key);
-        if (current === undefined || row.ts >= current.ts)
-            state.set(key, row);
-    }
-    return [...state.values()]
-        .filter((row) => row.op === 'upsert')
-        .map((row) => ({
-        ownerId: row.owner_id,
-        sessionId: row.session_id,
-        kind: row.kind,
-        address: row.address,
-        updatedAt: row.ts,
-    }))
-        .filter((route) => opts.ownerId === undefined || route.ownerId === opts.ownerId)
-        .filter((route) => opts.freshOnly !== true || now - route.updatedAt < ROUTE_FRESH_MS)
-        .sort((a, b) => (ROUTE_KIND_PRIORITY.get(a.kind) ?? 0) - (ROUTE_KIND_PRIORITY.get(b.kind) ?? 0) ||
-        b.updatedAt - a.updatedAt);
-}
-async function appendRouteRow(row, env) {
-    const file = routesPath(env);
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.appendFile(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
-}
-export async function upsertWakeRoute(route, opts = {}) {
-    const at = opts.at ?? Date.now();
-    await appendRouteRow({
-        v: 1,
-        ts: at,
-        op: 'upsert',
-        owner_id: route.ownerId,
-        session_id: route.sessionId,
-        kind: route.kind,
-        address: route.address,
-    }, opts.env ?? process.env);
-}
-export async function retireOwnerWakeRoutes(ownerId, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    for (const route of await readWakeRoutes({ ownerId, now: at, env })) {
-        await appendRouteRow({
-            v: 1,
-            ts: at,
-            op: 'retire',
-            owner_id: ownerId,
-            session_id: route.sessionId,
-            kind: route.kind,
-        }, env);
-    }
-}
-/** Retire one capability without touching sibling identities in the same claim. */
-export async function retireWakeRoute(route, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    const current = (await readWakeRoutes({ ownerId: route.ownerId, now: at, env }))
-        .find((candidate) => candidate.sessionId === route.sessionId && candidate.kind === route.kind);
-    if (current === undefined)
-        return;
-    await appendRouteRow({
-        v: 1,
-        ts: at,
-        op: 'retire',
-        owner_id: route.ownerId,
-        session_id: route.sessionId,
-        kind: route.kind,
-    }, env);
-}
-/** Publication requires a non-blank session and a non-empty address of non-blank values. */
-function completeRouteEvidence(value) {
-    if (value === undefined || value === null)
-        return false;
-    if (typeof value.sessionId !== 'string' || value.sessionId.trim() === '')
-        return false;
-    const address = value.address;
-    if (address === null || typeof address !== 'object' || Array.isArray(address))
-        return false;
-    const entries = Object.entries(address);
-    return entries.length > 0 && entries.every(([key, item]) => key.trim() !== '' && typeof item === 'string' && item.trim() !== '');
-}
-/**
- * One probe per kind. A probe publishes only when its provider's complete
- * endpoint evidence is present; Codex uses its thread id as that evidence.
- * The other native transports have no endpoint lifecycle in this delivery,
- * so their probes publish nothing until those transports land.
- */
-export const WAKE_ROUTE_PROBES = {
-    'opencode-server': () => undefined,
-    'codex-queue': (env) => {
-        const threadId = env.CODEX_THREAD_ID?.trim();
-        return threadId ? { sessionId: threadId, address: { threadId } } : undefined;
-    },
-    'claude-native': () => undefined,
-    'pi-extension': () => undefined,
-    paseo: (env) => {
-        const agentId = env.PASEO_AGENT_ID?.trim();
-        return agentId ? { sessionId: agentId, address: { agentId } } : undefined;
-    },
-};
-/** The kind-neutral publication loop; probes supply complete evidence per kind. */
-export async function publishWakeRoutesFrom(ownerId, probes, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    for (const kind of WAKE_ROUTE_KINDS) {
-        const evidence = probes[kind](env);
-        if (!completeRouteEvidence(evidence))
-            continue;
-        await upsertWakeRoute({ ownerId, sessionId: evidence.sessionId, kind, address: evidence.address }, { at, env });
-    }
-}
-/** Publication boundary: every route written is complete provider evidence. */
-export async function publishWakeRoutes(ownerId, opts = {}) {
-    await publishWakeRoutesFrom(ownerId, WAKE_ROUTE_PROBES, opts);
-}
+function ledger(env) { return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? path.join(os.homedir(), '.square', 'host-ledger'), writableScope: 'user', readableScopes: ['user'] }); }
+export async function readWakeRoutes(opts = {}) { const now = opts.now ?? Date.now(); const records = await ledger(opts.env ?? process.env).listPresence({ location: opts.location, participant: opts.participant, session: opts.sessionId, now, scopes: ['user'] }); return records.flatMap((record) => record.route === undefined || (opts.freshOnly === true && now - (record.updatedAt ?? 0) >= ROUTE_FRESH_MS) ? [] : [{ location: record.location, participant: record.participant, sessionId: record.session, channel: record.channel, kind: record.route.kind, address: { ...record.route.address }, updatedAt: record.updatedAt ?? 0 }]); }
+export async function upsertWakeRoute(route, opts = {}) { await ledger(opts.env ?? process.env).ensurePresence({ location: route.location, participant: route.participant, session: route.sessionId, channel: route.channel, route: { kind: route.kind, address: route.address }, updatedAt: opts.at ?? Date.now() }); }
+export async function retireWakeRoute(route, opts = {}) { await ledger(opts.env ?? process.env).ensurePresence({ location: route.location, participant: route.participant, session: route.sessionId, channel: route.channel, updatedAt: opts.at ?? Date.now() }); }

package/dist/runtime.d.ts

@@ -35,7 +35,7 @@ export declare function publicActs(acts: StoredAct[]): Array<Extract<StoredAct,
     kind: 'say' | 'done';
 }>>;
 export declare function observationFor(squareState: SquareState, name: string, index: number): ActivityObservation | undefined;
-export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number, ownerId?: string): boolean;
+export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number): boolean;
 export declare function readCursor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
 export declare function latestActIndex(acts: StoredAct[]): number;
 export declare function freshWatchLease(squareState: SquareState, name: string, at?: number): WatchLease | undefined;

package/dist/runtime.js

@@ -146,18 +146,17 @@ function canonicalRuntimeName(squareState, name) {
 export function observationFor(squareState, name, index) {
     return observationMap(squareState, name)[formatActivityId(index)];
 }
-export function recordObservation(squareState, name, index, state, at = Date.now(), ownerId) {
+export function recordObservation(squareState, name, index, state, at = Date.now()) {
     if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(at))
         return false;
     const key = observationRecipient(squareState, name);
     const id = formatActivityId(index);
     const current = squareState.runtime.observations[key]?.[id];
-    if (current?.state === 'seen' || (current?.state === state && current.at >= at && current.ownerId === ownerId))
+    if (current?.state === 'seen' || (current?.state === state && current.at >= at))
         return false;
     const next = {
-        state: state === 'seen' ? 'seen' : 'notified',
+        state: 'seen',
         at: Math.max(current?.at ?? -Infinity, at),
-        ...(ownerId === undefined ? (current?.ownerId === undefined ? {} : { ownerId: current.ownerId }) : { ownerId }),
     };
     ((squareState.runtime.observations ??= {})[key] ??= {})[id] = next;
     return true;

package/dist/square-actions.d.ts

@@ -0,0 +1,32 @@
+import { type SquareState } from './model.js';
+import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
+import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
+import { type CatchProjection } from './catch-decisions.js';
+import type { CatchOptions, CatchResult } from './square-facade.js';
+export interface OperationContext {
+    readonly artifact: SquareArtifactPort;
+    readonly clock: () => number;
+    readonly location?: string;
+    readonly hostLedger?: HostLedgerPort;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;
+export declare function join(square: OperationContext, name: string): Promise<{
+    readonly name: string;
+    readonly activity: Activity | null;
+}>;
+export declare function implicitJoin(square: OperationContext, name: string): Promise<{
+    readonly name: string;
+    readonly state: 'joined' | 'active' | 'done';
+    readonly activity: Activity | null;
+}>;
+export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export interface ListenerChangeResult {
+    readonly activity: Activity | null;
+}
+export declare function listen(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function ignore(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function listening(square: OperationContext, actor: string): Promise<readonly string[]>;
+export declare function done(square: OperationContext, name: string, body?: string): Promise<ExpressResult>;
+export declare function hold(square: OperationContext, name: string, reason?: string): Promise<ExpressResult>;
+export declare function resume(square: OperationContext, name: string): Promise<ExpressResult>;

package/dist/square-actions.js

@@ -0,0 +1,167 @@
+import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin } from './decisions.js';
+import { SquareError } from './model.js';
+import { participantIdentity } from './participant-identity.js';
+import { decideCatch } from './catch-decisions.js';
+function processIdentity(env) {
+    const choices = [
+        [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
+        [env.OPENCODE_SESSION_ID, 'opencode'], [env.SQUARE_PI_SESSION_ID, 'pi'], [env.PASEO_AGENT_ID, 'paseo'],
+    ];
+    const found = choices.find(([session]) => session?.trim());
+    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
+}
+/** Presence is best effort and runs only after the artifact mutation commits. */
+async function ensureLocalPresence(context, participant) {
+    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    const result = await context.hostLedger.ensurePresence({
+        location: context.location, participant, session: identity.session, channel: identity.channel, updatedAt: context.clock(),
+    }, 'local').catch((error) => ({ status: 'degraded', record: { location: context.location, participant, session: identity.session, channel: identity.channel }, error }));
+    if (result.status === 'degraded')
+        process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
+}
+function exposeCaught(activity, perception) {
+    if (activity.kind === 'read' || activity.actor === undefined)
+        throw new Error(`Cannot expose stored activity ${formatActivityId(activity.index)}`);
+    const result = {
+        id: formatActivityId(activity.index), at: activity.at, kind: activity.kind, actor: activity.actor,
+        mentions: activity.kind === 'say' ? extractMentions(activity.body) : [],
+        ...('body' in activity && activity.body !== undefined ? { body: activity.body } : {}),
+        ...('target' in activity ? { target: activity.target } : {}),
+        ...(activity.kind === 'say' && activity.reply !== undefined ? { reply: formatActivityId(activity.reply) } : {}),
+    };
+    if (perception === 'full' || !('body' in result))
+        return { ...result, perception };
+    const { body: _body, ...withoutBody } = result;
+    return { ...withoutBody, perception };
+}
+export async function catchUp(square, name, options = {}, project) {
+    const idle = options.idle ?? 0;
+    if (!Number.isFinite(idle) || idle < 0)
+        throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
+    const deadline = Date.now() + idle;
+    while (true) {
+        const attempt = await square.artifact.transact((state, version) => {
+            const decision = decideCatch(state, name, options, square.clock(), project);
+            return { ...(decision.changed ? { state } : {}), result: { version, decision } };
+        });
+        await ensureLocalPresence(square, name);
+        if (attempt.decision.delivered.length > 0 || idle === 0) {
+            return {
+                activities: attempt.decision.delivered.map((activity) => exposeCaught(activity, attempt.decision.perceptions.get(activity.index) ?? 'full')),
+                consumedThrough: attempt.decision.consumedThrough,
+                idleExpired: false,
+            };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 || !await square.artifact.changed(attempt.version, remaining)) {
+            return { activities: [], consumedThrough: attempt.decision.consumedThrough, idleExpired: true };
+        }
+    }
+}
+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)}`);
+    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) } : {}),
+    };
+}
+function parseRequiredActivityId(id) {
+    const index = parseActivityId(id);
+    if (index === undefined)
+        throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
+    return index;
+}
+export async function join(square, name) {
+    const now = square.clock();
+    const committed = await square.artifact.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') } };
+    });
+    await ensureLocalPresence(square, committed.name);
+    return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
+export async function implicitJoin(square, name) {
+    const now = square.clock();
+    const committed = await square.artifact.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') } };
+    });
+    await ensureLocalPresence(square, committed.name);
+    return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
+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.artifact.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 } };
+    });
+    await ensureLocalPresence(square, name);
+    return { activity: exposeActivity(committed.stored) };
+}
+async function landListenerChange(square, verb, actor, target) {
+    const now = square.clock();
+    const stored = await square.artifact.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 listen(square, actor, target) { return landListenerChange(square, 'listen', actor, target); }
+export function ignore(square, actor, target) { return landListenerChange(square, 'ignore', actor, target); }
+export async function listening(square, actor) { const { state } = await square.artifact.read(); return coreListening(state, actor); }
+async function landCore(square, verb, actor, body = '') {
+    const now = square.clock();
+    const stored = await square.artifact.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 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); }

package/dist/square-facade.d.ts

@@ -1,4 +1,5 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
+import type { HostLedgerPort } from './ports.js';
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
@@ -9,9 +10,6 @@ export interface Activity {
     readonly target?: string;
     readonly reply?: ActivityId;
 }
-export interface WakeNotifier {
-    wake(recipients: readonly string[], activity: Activity): void;
-}
 export interface PerceivedActivity extends Activity {
     readonly perception: Perception;
 }
@@ -39,8 +37,8 @@ export interface CatchResult {
 export interface HistoryQuery {
     readonly limit?: number;
     readonly order?: 'asc' | 'desc';
-    readonly all?: boolean;
-    readonly full?: boolean;
+    readonly before?: ActivityId;
+    readonly after?: ActivityId;
     readonly grep?: string;
     readonly from?: readonly string[];
     readonly mention?: boolean;
@@ -69,7 +67,8 @@ export type SquareSource = {
 };
 export interface OpenOptions {
     clock?: () => number;
-    notifier?: WakeNotifier;
+    hostLedger?: HostLedgerPort;
+    env?: NodeJS.ProcessEnv;
 }
 export interface SquareAtInput extends SquareSource, OpenOptions {
 }
@@ -78,7 +77,8 @@ export interface SquareBuildInput extends SquareSource {
     hardCap?: number | null;
     throttlePerMinute?: number;
     clock?: () => number;
-    notifier?: WakeNotifier;
+    hostLedger?: HostLedgerPort;
+    env?: NodeJS.ProcessEnv;
 }
 export interface Participant {
     readonly name: string;

package/dist/square-file-adapter.d.ts

@@ -1,6 +1,6 @@
 import { type BuildOptions, type HardCap } from './model.js';
 import { type OpenSquare } from './open-square.js';
-import type { WakeNotifier } from './square-facade.js';
+import type { HostLedgerPort } from './ports.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export declare function createSquare(squarePath: string, options: BuildOptions & {
     hardCap: HardCap;
@@ -10,9 +10,10 @@ export interface SquareBuildOptions {
     hardCap?: number | null;
     throttlePerMinute?: number;
     clock?: () => number;
-    notifier?: WakeNotifier;
+    hostLedger?: HostLedgerPort;
+    env?: NodeJS.ProcessEnv;
 }
-export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'notifier'>): Promise<OpenSquare>;
+export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'env'>): Promise<OpenSquare>;
 export declare function probeSquare(squarePath: string): Promise<OpenSquare | undefined>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;

package/dist/square-file-adapter.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { createSquareState, probeSquareFile, writeSquareSnapshot, withSquareFileLock, openSquareCell, createMemoryCell, } from './square-storage.js';
 import { InternalSquareError, SquareError, } from './model.js';
 import { closeOpenSquare } from './open-square.js';
+import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export async function createSquare(squarePath, options, snippet) {
     await withSquareFileLock(squarePath, async () => {
@@ -22,10 +24,22 @@ function validateBuildOptions(options) {
     }
 }
 export async function openSquare(squarePath, options = {}) {
+    const env = options.env ?? process.env;
+    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
     const cell = openSquareCell(squarePath);
     try {
         await cell.read();
-        return { cell, clock: options.clock ?? Date.now, ...(options.notifier === undefined ? {} : { notifier: options.notifier }), location: squarePath };
+        const artifact = { read: () => cell.read(), transact: (fn) => cell.transact(fn), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
+        return {
+            artifact,
+            clock: options.clock ?? Date.now,
+            location: squarePath,
+            env,
+            hostLedger: options.hostLedger ?? createHostLedgerPort({
+                userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
+                localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
+            }),
+        };
     }
     catch (error) {
         await cell.close();
@@ -37,7 +51,7 @@ export async function openSquare(squarePath, options = {}) {
 }
 export async function probeSquare(squarePath) {
     const state = await probeSquareFile(squarePath);
-    return state === undefined ? undefined : { cell: createMemoryCell(state), clock: Date.now, location: squarePath };
+    return state === undefined ? undefined : { artifact: memoryArtifact(createMemoryCell(state)), clock: Date.now, location: squarePath };
 }
 export async function buildSquare(squarePath, options) {
     validateBuildOptions(options);
@@ -63,7 +77,10 @@ export function buildMemorySquare(options) {
         hardCap: options.hardCap ?? null,
         ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
     }, options.markdown);
-    return { cell: createMemoryCell(squareState), clock: options.clock ?? Date.now, ...(options.notifier === undefined ? {} : { notifier: options.notifier }), location: 'memory' };
+    return { artifact: memoryArtifact(createMemoryCell(squareState)), clock: options.clock ?? Date.now, location: 'memory', hostLedger: options.hostLedger };
+}
+function memoryArtifact(cell) {
+    return { read: () => cell.read(), transact: (fn) => cell.transact(fn), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
 }
 export async function waitForSquareChanges(squarePaths, timeoutMs, signal, afterReady) {
     if (timeoutMs <= 0 || signal?.aborted || squarePaths.length === 0)
@@ -80,13 +97,13 @@ export async function waitForSquareChanges(squarePaths, timeoutMs, signal, after
             return { status: 'expired' };
         const baselines = await Promise.all(squares.map(async (square) => ({
             square,
-            version: (await square.cell.read()).version,
+            version: (await square.artifact.read()).version,
         })));
         const ready = await afterReady?.();
         if (ready !== undefined)
             return { status: 'ready', value: ready };
         const waits = baselines.map(async ({ square, version }) => {
-            const changed = await square.cell.changed(version, timeoutMs).catch(() => false);
+            const changed = await square.artifact.changed(version, timeoutMs).catch(() => false);
             if (changed)
                 return true;
             throw new Error('square wait expired');