@astrosheep/square 0.3.30 → 0.3.32

package/dist/notifications.js

@@ -1,25 +1,17 @@
-import { spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
-import { deriveDeliveryModel, leaseOwnsNotification, planActNotifications, } from './delivery.js';
-import { sessionInbox } from './inbox.js';
-import { hasPresentedAttention } from './presented.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { planActNotifications, } from './delivery.js';
 import { SquareError } from './model.js';
 import { SLEEP_MS, matchesMentionTarget } from './runtime.js';
-import { parseActivityId } from './square-core.js';
-import { displayAttentionPath, renderAttentionPreview } from './attention-presentation.js';
-import { lookupParticipant } from './registry.js';
-import { retireWakeRoute } from './routes.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
+import { displayAttentionPath } from './attention-presentation.js';
 import { openSquare } from './square-file-adapter.js';
-import { markNotificationNotified } from './square-wiring.js';
 import { closeOpenSquare } from './open-square.js';
-import { entryPresentation, notificationDelivered, notificationForAct, pendingDeliveriesFromState, resolveParticipant } from './views.js';
-import { claimNotificationLease, releaseNotificationLease, transitionNotificationLease } from './wakes.js';
-import { nextWakeAttemptNumber, recordRecoveredUnknown, recordWakeAttempt, } from './wake-attempts.js';
-import { wakeEvidence, wakeEvidenceProjectionFromState, wakeIsEligible } from './wake-evidence.js';
-import { WakePort } from './wake-port.js';
-const NOTIFY_LEASE_MS = 5 * 60 * 1000;
+import { notificationDelivered, resolveParticipant } from './views.js';
+import { deliverPending, sweepPending, sweepPendingFromState } from './delivery-operations.js';
+import { projectPresentationEvidence } from './square-projections.js';
+import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 export { planActNotifications, matchesMentionTarget };
 export { notificationMessageId } from './delivery.js';
 export function wakeGraceMs(env = process.env) {
@@ -36,48 +28,14 @@ function wakeLabel(kind) {
         return 'codex-queue';
     return kind;
 }
-function renderWakePayload(request, body, kind) {
+function renderWakePayload(request) {
     return [
-        `<system-reminder source="square" wake="${wakeLabel(kind)}">`,
-        `square: ${displayAttentionPath(request.squarePath)}`,
-        renderAttentionPreview({
-            squarePath: request.squarePath,
-            actIndex: request.actIndex,
-            recipient: request.recipient,
-            actor: request.actor,
-            route: request.route,
-            body,
-            compact: true,
-        }),
+        `<system-reminder source="square" wake="${wakeLabel(request.route.kind)}">`,
+        `square: ${displayAttentionPath(request.location)}`,
+        `attention: ${request.activity} for ${request.participant}`,
         '</system-reminder>',
     ].join('\n');
 }
-async function waitForCatch(route, request, body) {
-    const binding = (await lookupParticipant(request.squarePath, request.recipient))
-        .find((item) => item.ownerId === route.ownerId);
-    const activeCatch = binding && (await sessionInbox(binding.sessionId))
-        .find((item) => item.name === request.recipient)?.catchLease;
-    if (!activeCatch || !leaseOwnsNotification(activeCatch, {
-        actor: request.actor,
-        body,
-        route: request.route,
-        recipient: request.recipient,
-    }))
-        return false;
-    const deadline = Date.now() + 180_000;
-    while (Date.now() < deadline) {
-        if (await hasDeliveredNotification(request.squarePath, request.recipient, request.actIndex))
-            return true;
-        const currentBinding = (await lookupParticipant(request.squarePath, request.recipient))
-            .find((item) => item.ownerId === route.ownerId);
-        const lease = currentBinding && (await sessionInbox(currentBinding.sessionId))
-            .find((item) => item.name === request.recipient)?.catchLease;
-        if (!lease || lease.expiresAt <= Date.now())
-            return false;
-        await sleep(Math.min(250, lease.expiresAt - Date.now()));
-    }
-    return false;
-}
 function notificationIndex(ref) {
     if (typeof ref === 'number')
         return ref;
@@ -101,7 +59,11 @@ export async function hasAttentionNotification(squarePath, name, ref, env = proc
     try {
         const recipient = (await resolveParticipant(square, name)).name;
         const index = notificationIndex(ref);
-        return await notificationDelivered(square, recipient, index) || await hasPresentedAttention(squarePath, recipient, index, env);
+        if (await notificationDelivered(square, recipient, index))
+            return true;
+        const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+        const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+        return (await projectPresentationEvidence({ hostLedger, location: squarePath, participant: recipient, activity: formatActivityId(index), now: Date.now() })).some((row) => row.outcome === 'presented');
     }
     finally {
         await closeOpenSquare(square);
@@ -116,7 +78,7 @@ export async function waitForDeliveredNotification(squarePath, name, ref, opts =
     }
     return false;
 }
-async function defaultWakeAdapters() {
+export async function defaultWakeAdapters() {
     const adapters = [];
     try {
         const { CodexQueueAdapter } = await import('./codex-queue.js');
@@ -134,164 +96,134 @@ async function defaultWakeAdapters() {
     }
     return adapters;
 }
-async function claimNotifyLease(square, recipient, actIndex) {
-    const leaseId = randomUUID();
-    return claimNotificationLease(square, recipient, actIndex, leaseId, NOTIFY_LEASE_MS);
+export async function createDefaultWakeTransport(hostLedger, clock, env = process.env) {
+    const adapters = await defaultWakeAdapters();
+    return createWakeTransport(env.SQUARE_DISABLE_PASEO_WAKE === '1' ? adapters.filter((adapter) => adapter.kind !== 'paseo') : adapters, hostLedger, clock);
 }
-async function transitionNotifyLease(square, recipient, actIndex, leaseId, phase, routeKind, attemptN) {
-    return transitionNotificationLease(square, recipient, actIndex, leaseId, phase, NOTIFY_LEASE_MS, routeKind, attemptN);
-}
-async function releaseNotifyLease(square, recipient, actIndex, leaseId) {
-    await releaseNotificationLease(square, recipient, actIndex, leaseId);
+export function createWakeTransport(adapters, hostLedger, clock) {
+    return {
+        probe: async (route) => {
+            const adapter = adapters.find((candidate) => candidate.kind === route.kind);
+            if (adapter === undefined)
+                return { outcome: 'not-capable', diagnostic: `no adapter for ${route.kind}` };
+            const probe = adapter.probe;
+            if (probe === undefined)
+                return true;
+            try {
+                return await probe.call(adapter, route.address);
+            }
+            catch (error) {
+                return { outcome: 'not-capable', diagnostic: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        attempt: async (request, _timeoutMs) => {
+            const adapter = adapters.find((candidate) => candidate.kind === request.route.kind);
+            if (adapter === undefined)
+                return { outcome: 'not-capable', diagnostic: `no adapter for ${request.route.kind}` };
+            try {
+                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => true);
+                if (result.outcome === 'accepted')
+                    return { outcome: 'accepted' };
+                if (result.outcome === 'failed')
+                    return { outcome: 'failed', message: result.message };
+                if (result.outcome === 'unavailable')
+                    return { outcome: 'failed', message: result.message, unavailable: true, ...(result.retainRoute === true ? { retainRoute: true } : {}), ...(result.routeStale === true ? { routeStale: true } : {}) };
+                if (result.outcome === 'unknown')
+                    return { outcome: 'unknown', diagnostic: result.message };
+                return { outcome: 'unknown', diagnostic: 'wake dispatch cancelled' };
+            }
+            catch (error) {
+                return { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    };
 }
-async function processNotification(squarePath, notification, opts) {
+export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const env = opts.env ?? process.env;
     const now = opts.now ?? Date.now;
-    const attention = {
-        squarePath,
-        actIndex: notification.item.index,
-        recipient: notification.recipient,
-    };
-    const initialAt = now();
-    if (!wakeIsEligible(await wakeEvidence(squarePath, notification.recipient, notification.item.index, initialAt, env)))
-        return;
-    const square = await openSquare(squarePath, { clock: now });
-    const claim = await claimNotifyLease(square, notification.recipient, notification.item.index);
-    if (claim.type === 'busy' || claim.type === 'delivered') {
-        await closeOpenSquare(square);
-        return;
-    }
-    if (claim.type === 'ambiguous') {
-        const recovered = await recordRecoveredUnknown(attention, claim.lease, env);
-        if (recovered !== undefined) {
-            await releaseNotifyLease(square, notification.recipient, notification.item.index, claim.lease.leaseId);
+    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const hostLedger = createHostLedgerPort({
+        userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
+        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
+    });
+    const square = await openSquare(squarePath, { clock: now, hostLedger, env });
+    try {
+        const adapters = opts.adapters ?? await defaultWakeAdapters();
+        const transport = createWakeTransport(adapters, hostLedger, now);
+        try {
+            return await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
         }
+        catch {
+            return { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+        }
+    }
+    finally {
         await closeOpenSquare(square);
-        return;
     }
-    const { leaseId } = claim;
-    let releaseLease = true;
+}
+/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares. */
+export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAdapters) {
+    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+    let indexed = [];
     try {
-        const dispatchAt = now();
-        const evidence = await wakeEvidence(squarePath, notification.recipient, notification.item.index, dispatchAt, env);
-        if (!wakeIsEligible(evidence))
-            return;
-        const port = new WakePort(opts.adapters ?? await defaultWakeAdapters());
-        const request = {
-            squarePath,
-            actIndex: notification.item.index,
-            recipient: notification.recipient,
-            actor: notification.item.actor,
-            route: notification.route,
-        };
-        await port.dispatch(evidence.attemptableRoutes, (route) => renderWakePayload(request, notification.item.body, route.kind), {
-            nextAttemptN: async () => nextWakeAttemptNumber(attention, { env, now: now() }),
-            beforeSend: async (route, attemptN) => {
-                if (await waitForCatch(route, request, notification.item.body))
-                    return false;
-                const currentAt = now();
-                if (!(await entryPresentation(square, notification.recipient)).joined)
-                    return false;
-                const current = await wakeEvidence(squarePath, notification.recipient, notification.item.index, currentAt, env);
-                if (!wakeIsEligible(current))
-                    return false;
-                if (!current.attemptableRoutes.some((candidate) => candidate.ownerId === route.ownerId && candidate.kind === route.kind && candidate.sessionId === route.sessionId))
-                    return false;
-                const dispatching = await transitionNotifyLease(square, notification.recipient, notification.item.index, leaseId, 'dispatching', route.kind, attemptN);
-                if (dispatching)
-                    releaseLease = false;
-                return dispatching;
-            },
-            record: async (route, attemptN, outcome) => {
-                if (outcome.outcome === 'failed') {
-                    await transitionNotifyLease(square, notification.recipient, notification.item.index, leaseId, 'claimed');
-                    releaseLease = true;
-                }
-                await recordWakeAttempt({
-                    attention,
-                    routeKind: route.kind,
-                    outcome: outcome.outcome,
-                    attemptN,
-                    at: now(),
-                    ...('signature' in outcome ? { signature: outcome.signature } : {}),
-                    ...('message' in outcome ? { message: outcome.message } : {}),
-                    ...('diagnostic' in outcome && outcome.diagnostic !== undefined ? { diagnostic: outcome.diagnostic } : {}),
-                }, env);
-                if (outcome.outcome === 'accepted') {
-                    await markNotificationNotified(square, notification.recipient, notification.item.index, route.ownerId, now());
-                }
-                if (outcome.outcome !== 'failed')
-                    releaseLease = true;
-            },
-            invalidate: async (route) => {
-                await retireWakeRoute(route, { env, at: now() });
-            },
-        });
+        indexed = await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
     }
-    finally {
-        if (releaseLease) {
-            await releaseNotifyLease(square, notification.recipient, notification.item.index, leaseId);
+    catch { /* capability is best effort */ }
+    const paths = new Set(indexed.map((binding) => binding.location));
+    try {
+        for (const entry of await fs.promises.readdir(path.join(cwd, '.square'))) {
+            if (entry.endsWith('.square'))
+                paths.add(path.join(cwd, '.square', entry));
         }
-        await closeOpenSquare(square);
     }
-}
-export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
-    const square = await openSquare(squarePath);
-    const notifications = await notificationForAct(square, actIndex).finally(() => closeOpenSquare(square));
-    await Promise.all(notifications.map((notification) => processNotification(squarePath, notification, opts)));
-}
-function launchWorker(workerPath, args) {
-    const child = spawn(process.execPath, [workerPath, ...args], { detached: true, stdio: 'ignore', env: process.env });
-    child.unref();
-}
-export function wakeNotifierForSquare(squarePath, env = process.env) {
-    return {
-        wake(recipients, activity) {
-            if (env.SQUARE_DISABLE_PASEO_WAKE === '1' || recipients.length === 0)
-                return;
-            const actIndex = parseActivityId(activity.id);
-            if (actIndex === undefined)
-                return;
-            launchWorker(fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url)), ['--location', squarePath, '--act-index', String(actIndex)]);
-        },
-    };
-}
-/** Select sweep candidates from one frozen snapshot and one delivery replay. */
-export async function pendingNotificationSweepFromState(squarePath, state, now, env, limit, deriveDelivery = deriveDeliveryModel) {
-    const delivery = deriveDelivery(state);
-    const pending = pendingDeliveriesFromState(state, delivery);
-    const evidence = await wakeEvidenceProjectionFromState(squarePath, state, now, env, delivery);
-    const indexes = new Set();
-    for (const recipient of pending) {
-        for (const note of recipient.notifications) {
-            if (now - note.item.at <= wakeGraceMs(env))
-                continue;
-            if (!wakeIsEligible(evidence.evidence(recipient.recipient, note.item.index)))
-                continue;
-            indexes.add(note.item.index);
+    catch { /* no local square directory */ }
+    const adapters = suppliedAdapters ?? await defaultWakeAdapters();
+    for (const squarePath of paths) {
+        try {
+            const square = await openSquare(squarePath, { hostLedger, env });
+            try {
+                const snapshot = await square.artifact.read();
+                await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
+                const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
+                const graceMs = 0;
+                const selected = await sweepPending({ artifact: square.artifact, hostLedger, location: squarePath, now: Date.now(), graceMs, limit: Number.isFinite(limit) && limit > 0 ? limit : 8 }).catch(() => []);
+                const transport = createWakeTransport(adapters, hostLedger, Date.now);
+                for (const actIndex of selected)
+                    await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: Date.now() }).catch(() => undefined);
+            }
+            finally {
+                await closeOpenSquare(square);
+            }
         }
+        catch { /* stale index entries are ignored by the hook */ }
     }
-    return [...indexes].sort((left, right) => left - right).slice(0, Math.max(0, limit));
 }
-/** Reconsider old pending attention at a bounded action boundary using the existing worker. */
+/** Select sweep candidates from one frozen snapshot and one delivery replay. */
+export async function pendingNotificationSweepFromState(squarePath, state, now, env, limit, deriveDelivery) {
+    const ledger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER, writableScope: 'user', readableScopes: ['user'] });
+    return sweepPendingFromState({ state, hostLedger: ledger, location: squarePath, now, graceMs: wakeGraceMs(env), limit, deriveDelivery });
+}
+/** Select old pending attention at a bounded action boundary for an explicit executor. */
 export async function sweepPendingNotifications(squarePath, opts = {}) {
     const env = opts.env ?? process.env;
     if (env.SQUARE_DISABLE_PASEO_WAKE === '1')
         return [];
     const now = opts.now ?? Date.now();
     const limit = opts.limit ?? 8;
-    const square = await openSquare(squarePath, { clock: () => now });
-    let state;
+    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot });
+    const square = await openSquare(squarePath, { clock: () => now, hostLedger, env });
+    let selected;
     try {
-        ({ state } = await entryPresentation(square, ''));
+        selected = await sweepPending({ artifact: square.artifact, hostLedger, location: squarePath, now, graceMs: wakeGraceMs(env), limit });
     }
     finally {
         await closeOpenSquare(square);
     }
-    const selected = await pendingNotificationSweepFromState(squarePath, state, now, env, limit);
-    const workerPath = fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url));
-    for (const actIndex of selected) {
-        (opts.launchWorker ?? launchWorker)(workerPath, ['--location', squarePath, '--act-index', String(actIndex)]);
+    if (opts.dispatchCandidate !== undefined) {
+        for (const actIndex of selected)
+            await opts.dispatchCandidate(actIndex);
     }
     return selected;
 }

package/dist/open-square.d.ts

@@ -1,11 +1,12 @@
-import type { StateCell } from './state-cell.js';
-import type { WakeNotifier } from './square-facade.js';
+import type { HostLedgerPort, SquareArtifactPort, WakeTransportPort } from './ports.js';
 /** Private binding assembled by storage and consumed by the four concerns. */
 export interface OpenSquare {
-    readonly cell: StateCell;
+    readonly artifact: SquareArtifactPort;
     readonly clock: () => number;
-    readonly notifier?: WakeNotifier;
     readonly location: string;
+    readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: WakeTransportPort;
+    readonly env?: NodeJS.ProcessEnv;
 }
 /** Package-private lifecycle boundary for bound squares. */
 export declare function closeOpenSquare(square: OpenSquare): Promise<void>;

package/dist/open-square.js

@@ -1,4 +1,4 @@
 /** Package-private lifecycle boundary for bound squares. */
 export function closeOpenSquare(square) {
-    return square.cell.close();
+    return square.artifact.close();
 }

package/dist/paseo-delivery.js

@@ -37,6 +37,7 @@ export class PaseoAdapter {
                 outcome: 'unavailable',
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
+                routeStale: true,
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
             };
         }
@@ -58,6 +59,7 @@ export class PaseoAdapter {
                 message: agent === undefined ? 'The registered Paseo agent was not found.' : 'The registered Paseo agent is not idle.',
                 diagnostic: diagnostic('selection', address, agent === undefined ? 'not_found' : 'not_idle'),
                 ...(agent === undefined ? {} : { retainRoute: true }),
+                ...(agent === undefined ? { routeStale: true } : {}),
             };
         }
         if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent))) {

package/dist/ports.d.ts

@@ -0,0 +1,138 @@
+import type { InboxNotification, SquareState, StoredAct, WakeRoute, WatchLease } from './model.js';
+import type { PlannedNotification } from './delivery.js';
+export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, HostLedgerScope, PresenceKey, PresenceLookup, PresenceRecord, PresenceChannel, PresenceResult, ReconcileBindingInput as HostLedgerReconcileBindingInput, ReconcileBindingResult, } from './host-ledger.js';
+import type { HostLedgerPort } from './host-ledger.js';
+/** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
+export interface SquareArtifactPort {
+    read(): Promise<{
+        state: SquareState;
+        version: number;
+    }>;
+    transact<R>(fn: (state: SquareState, version: number) => {
+        state?: SquareState;
+        result: R;
+    }): Promise<R>;
+    changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** Capability-neutral wake transport. Unused by this Contract's activity operations. */
+export interface WakeTransportPort {
+    /** Capability check that performs no external wake and writes no evidence. */
+    probe?(route: WakeRoute): Promise<boolean | {
+        readonly outcome: 'not-capable';
+        readonly diagnostic?: string;
+    }>;
+    attempt(request: WakeRequest, timeoutMs: number): Promise<WakeOutcome>;
+    /** Optional route retirement supplied by the concrete executor adapter. */
+    invalidate?(request: WakeRequest): Promise<void>;
+}
+export interface WakeRequest {
+    readonly location: string;
+    readonly participant: string;
+    readonly activity: string;
+    readonly route: WakeRoute;
+}
+/** Executor-neutral presentation capability; intentionally separate from wake transport. */
+export interface PresentationSinkPort {
+    present(activity: StoredAct): void | Promise<void>;
+}
+/** Stable projection of a host binding; storage rows never cross this boundary. */
+export interface SessionBindingProjection {
+    readonly location: string;
+    readonly participant: string;
+    readonly sessionId: string;
+    readonly channel: import('./host-ledger.js').PresenceChannel;
+    readonly route?: WakeRoute;
+    readonly updatedAt: number;
+}
+/** Pending boundary presentation projected for one bound session. */
+export interface PresentationProjection {
+    readonly binding: SessionBindingProjection;
+    readonly joined: boolean;
+    readonly notifications: readonly InboxNotification[];
+    readonly catchLease?: WatchLease;
+}
+/** Read-only presentation evidence projection for diagnostics and migration callers. */
+export interface PresentationEvidenceProjection {
+    readonly location: string;
+    readonly participant: string;
+    readonly sessionId: string;
+    readonly activity: string;
+    readonly outcome: string;
+    readonly at?: number;
+}
+export type WakeOutcome = {
+    readonly outcome: 'accepted';
+    readonly signature?: string;
+    readonly attemptN?: number;
+} | {
+    readonly outcome: 'failed';
+    readonly message?: string;
+    readonly attemptN?: number;
+    readonly unavailable?: boolean;
+    readonly retainRoute?: boolean;
+    readonly routeStale?: boolean;
+} | {
+    readonly outcome: 'not-capable';
+    readonly diagnostic?: string;
+} | {
+    readonly outcome: 'unknown';
+    readonly diagnostic?: string;
+    readonly attemptN?: number;
+};
+export interface SquareObservation {
+    readonly location?: string;
+    readonly version: number;
+    readonly state: SquareState;
+    readonly pending: readonly {
+        readonly recipient: string;
+        readonly notifications: readonly PlannedNotification[];
+    }[];
+    readonly bindings: readonly SessionBindingProjection[];
+}
+export interface ObserveSquareInput {
+    readonly artifact: SquareArtifactPort;
+    readonly hostLedger?: HostLedgerPort;
+    readonly location?: string;
+    readonly now?: number;
+}
+export interface ReconcileBindingInput {
+    readonly artifact: SquareArtifactPort;
+    readonly hostLedger: HostLedgerPort;
+    readonly location?: string;
+    readonly scopes?: readonly import('./host-ledger.js').HostLedgerScope[];
+    readonly now?: number;
+}
+export interface DeliveryResult {
+    readonly attempted: number;
+    readonly accepted: number;
+    readonly failed: number;
+    readonly unknown: number;
+    readonly notCapable: number;
+}
+export interface DeliverPendingInput {
+    readonly artifact: SquareArtifactPort;
+    readonly hostLedger: HostLedgerPort;
+    readonly transport: WakeTransportPort;
+    readonly location: string;
+    readonly timeoutMs?: number;
+    readonly now?: number;
+    readonly activity?: string | number;
+}
+export interface PresentationResult {
+    readonly presented: boolean;
+    readonly activity?: StoredAct;
+}
+export interface PresentPendingInput {
+    readonly artifact: SquareArtifactPort;
+    readonly location: string;
+    readonly participant: string;
+    readonly activity: string | number;
+    readonly sink: PresentationSinkPort;
+    readonly hostLedger?: HostLedgerPort;
+    readonly session?: string;
+    readonly now?: number;
+    readonly timeoutMs?: number;
+    /** Boundary previews that were clipped remain pending for a later full presentation. */
+    readonly markSeen?: boolean;
+}

package/dist/ports.js

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

package/dist/presence.d.ts

@@ -3,5 +3,4 @@ import type { OpenSquare } from './open-square.js';
 import type { CatchOptions, CatchResult } from './square-facade.js';
 export declare function catchUp(square: OpenSquare, name: string, options?: CatchOptions, deriveDelivery?: (state: import('./model.js').SquareState) => DeliveryModel): Promise<CatchResult>;
 /** Commit seen only for complete, actually rendered boundary bodies. */
-export declare function markBoundarySeen(squarePath: string, name: string, ownerId: string | undefined, actIndexes: readonly number[], at?: number): Promise<void>;
-export declare function markNotificationNotified(square: OpenSquare, name: string, actIndex: number, ownerId: string | undefined, at?: number): Promise<void>;
+export declare function markBoundarySeen(squarePath: string, name: string, actIndexes: readonly number[], at?: number): Promise<void>;