@astrosheep/square 0.3.70 → 0.3.71

package/dist/delivery-health.js

@@ -1,11 +1,10 @@
-import { deriveDeliveryModel } from './delivery.js';
+import { collectPending } from './delivery.js';
 import { formatActivityId } from './square-core.js';
 import { participantIdentity, truncateChars } from './presentation.js';
 import { formatDuration } from './time.js';
-import { projectWakeEvidenceFromState } from './square-projections.js';
-import { openSquare } from './square-file-adapter.js';
+import { projectWakeEvidence } from './wake-eligibility.js';
+import { openSquare } from './open-square.js';
 import { closeOpenSquare } from './open-square.js';
-import { pendingDeliveriesFromState } from './views.js';
 import { readWakeReleaseDiagnostics } from './wake-attempts.js';
 const DISPLAY_ORDER = [
     'awaiting',
@@ -23,21 +22,13 @@ export async function classifyDeliveryHealth(squarePath, opts) {
     const env = opts.env ?? process.env;
     const square = await openSquare(squarePath, { clock: () => now, env });
     try {
-        const { state } = await square.artifact.read();
-        const delivery = deriveDeliveryModel(state);
-        const pending = pendingDeliveriesFromState(state, delivery);
-        const evidenceProjection = await projectWakeEvidenceFromState({
-            location: squarePath,
-            state,
-            hostLedger: square.hostLedger,
-            now,
-            delivery,
-        });
+        const { scan, routes, pending } = await collectPending(square.artifact);
+        const evidenceProjection = await projectWakeEvidence({ location: squarePath, routes, pending, hostLedger: square.hostLedger, now });
         const items = [];
-        for (const pendingDelivery of pending) {
-            for (const note of pendingDelivery.notifications) {
-                const ageMs = Math.max(0, now - note.item.at);
-                const evidence = evidenceProjection.evidence(pendingDelivery.recipient, note.item.index);
+        for (const participant of scan.roster) {
+            for (const note of pending.filter((head) => head.recipient === participant.name)) {
+                const ageMs = Math.max(0, now - note.at);
+                const evidence = evidenceProjection.evidence(note.recipient, note.index);
                 const kind = evidence.presented
                     ? 'presented-not-delivered'
                     : evidence.terminal?.outcome === 'accepted'
@@ -50,10 +41,10 @@ export async function classifyDeliveryHealth(squarePath, opts) {
                 const attempt = evidence.terminal ?? evidence.attempts.at(-1);
                 items.push({
                     squarePath,
-                    recipient: pendingDelivery.recipient,
-                    actIndex: note.item.index,
-                    actor: note.item.actor,
-                    at: note.item.at,
+                    recipient: note.recipient,
+                    actIndex: note.index,
+                    actor: note.actor,
+                    at: note.at,
                     ageMs,
                     route: note.route,
                     kind,

package/dist/delivery-operations.d.ts

@@ -1,6 +1,4 @@
-import type { SquareState } from './model.js';
 import type { HostLedgerPort, SquareArtifactPort, DeliverPendingInput, DeliveryResult } from './ports.js';
-import { deriveDeliveryModel } from './delivery.js';
 export declare function deliverPending(input: DeliverPendingInput): Promise<DeliveryResult>;
 export declare function sweepPending(input: {
     readonly artifact: SquareArtifactPort;
@@ -10,12 +8,3 @@ export declare function sweepPending(input: {
     readonly graceMs: number;
     readonly limit: number;
 }): Promise<number[]>;
-export declare function sweepPendingFromState(input: {
-    readonly state: SquareState;
-    readonly hostLedger: HostLedgerPort;
-    readonly location: string;
-    readonly now: number;
-    readonly graceMs: number;
-    readonly limit: number;
-    readonly deriveDelivery?: (snapshot: SquareState) => ReturnType<typeof deriveDeliveryModel>;
-}): Promise<number[]>;

package/dist/delivery-operations.js

@@ -1,7 +1,6 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { deriveDeliveryModel } from './delivery.js';
-import { projectWakeEvidenceFromState } from './square-projections.js';
-import { wakeIsEligible } from './wake-eligibility.js';
+import { capturePendingScan, collectPending, pendingFacts, pendingHead, pendingPages, sameJoin } from './delivery.js';
+import { projectWakeEvidence, wakeIsEligible } from './wake-eligibility.js';
 import { canonicalPath } from './canonical-path.js';
 import { retireWakeRouteFromArtifact } from './routes.js';
 import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
@@ -35,12 +34,20 @@ async function attemptWakeWithin(transport, request, timeoutMs, beforeSend) {
 }
 export async function deliverPending(input) {
     const location = await canonicalPath(input.location);
-    const { state } = await input.artifact.read();
-    const delivery = deriveDeliveryModel(state);
-    const eligibility = await projectWakeEvidenceFromState({ state, location, hostLedger: input.hostLedger, now: input.now ?? Date.now(), delivery });
+    const requested = input.activity === undefined ? undefined : typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
+    if (input.activity !== undefined && requested === undefined)
+        return { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 0 };
+    const owners = await input.hostLedger.listPresence({ location, now: input.now ?? Date.now() });
+    const { scan, routes, pending } = await collectPending(input.artifact, requested);
+    const eligibility = await projectWakeEvidence({ routes, pending, owners, location, hostLedger: input.hostLedger, now: input.now ?? Date.now() });
     const observeCurrentness = async (request, now) => {
-        const { state: currentState } = await input.artifact.read();
-        const projection = await projectWakeEvidenceFromState({ state: currentState, location, hostLedger: input.hostLedger, now });
+        const index = parseActivityId(request.activity);
+        const captured = scan.roster.find((participant) => participant.name === request.participant);
+        const { value: facts } = await input.artifact.read((facts) => {
+            const head = sameJoin(facts, captured) ? pendingHead(facts, request.participant, index) : undefined;
+            return { routes: facts.routes(), pending: head === undefined ? [] : [head] };
+        });
+        const projection = await projectWakeEvidence({ ...facts, bindings: owners, location, hostLedger: input.hostLedger, now });
         return { ...projection.currentness({ ...request, location }), observationAvailable: true };
     };
     let attempted = 0;
@@ -48,14 +55,10 @@ export async function deliverPending(input) {
     let failed = 0;
     let unknown = 0;
     let notCapable = 0;
-    for (const recipient of delivery.joinedRecipients()) {
-        for (const notification of delivery.pendingFor(recipient)) {
-            if (input.activity !== undefined) {
-                const requested = typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
-                if (requested === undefined || requested !== notification.item.index)
-                    continue;
-            }
-            const evidence = eligibility.evidence(recipient, notification.item.index);
+    for (const participant of scan.roster) {
+        const recipient = participant.name;
+        for (const notification of pending.filter((head) => head.recipient === recipient)) {
+            const evidence = eligibility.evidence(recipient, notification.index);
             if (evidence.terminal !== undefined)
                 continue;
             const candidates = evidence.attemptableRoutes;
@@ -66,8 +69,8 @@ export async function deliverPending(input) {
             if (candidates.length === 0 && !evidence.presented)
                 notCapableForAttention = true;
             for (const route of candidates) {
-                const activity = formatActivityId(notification.item.index);
-                const attention = { squarePath: location, actIndex: notification.item.index, recipient };
+                const activity = formatActivityId(notification.index);
+                const attention = { squarePath: location, actIndex: notification.index, recipient };
                 const leaseMs = input.timeoutMs ?? 5000;
                 const requestRoute = route;
                 if (input.transport.probe !== undefined) {
@@ -102,7 +105,7 @@ export async function deliverPending(input) {
                 if (claim.status === 'terminal')
                     break;
                 const { claimToken, attemptN } = claim;
-                const request = { location: input.location, participant: recipient, activity, actor: notification.item.actor, route: requestRoute };
+                const request = { location: input.location, participant: recipient, activity, actor: notification.actor, route: requestRoute };
                 const claimRelease = { hostLedger: input.hostLedger, location, participant: recipient, session: route.sessionId, activity, claimToken, routeKind: route.kind, attemptN };
                 // One teardown path for every exit after claim acquisition; each call site keeps its own error policy.
                 const abandon = async (details, options = {}) => {
@@ -202,20 +205,28 @@ export async function deliverPending(input) {
     return { attempted, accepted, failed, unknown, notCapable };
 }
 export async function sweepPending(input) {
-    const { state } = await input.artifact.read();
-    return sweepPendingFromState({ ...input, state });
-}
-export async function sweepPendingFromState(input) {
-    const delivery = input.deriveDelivery?.(input.state) ?? deriveDeliveryModel(input.state);
-    const eligibility = await projectWakeEvidenceFromState({ ...input, delivery });
-    const selected = new Set();
-    for (const recipient of delivery.joinedRecipients()) {
-        for (const notification of delivery.pendingFor(recipient)) {
-            if (input.now - notification.item.at <= input.graceMs)
-                continue;
-            if (wakeIsEligible(eligibility.evidence(recipient, notification.item.index)))
-                selected.add(notification.item.index);
+    if (input.limit <= 0)
+        return [];
+    const location = await canonicalPath(input.location);
+    const owners = await input.hostLedger.listPresence({ location, now: input.now });
+    const { value: scan } = await input.artifact.read(capturePendingScan);
+    const selected = [];
+    const indexes = new Set();
+    for await (const page of pendingPages(input.artifact, scan)) {
+        const { value: facts } = await input.artifact.read((facts) => pendingFacts(facts, scan, page));
+        const eligibility = await projectWakeEvidence({ ...facts, bindings: owners, location, hostLedger: input.hostLedger, now: input.now });
+        for (const head of facts.pending) {
+            if (indexes.size >= input.limit && !indexes.has(head.index))
+                break;
+            if (input.now - head.at > input.graceMs && wakeIsEligible(eligibility.evidence(head.recipient, head.index))) {
+                selected.push(head);
+                indexes.add(head.index);
+            }
         }
+        if (indexes.size >= input.limit)
+            break;
     }
-    return [...selected].sort((left, right) => left - right).slice(0, Math.max(0, input.limit));
+    const { value: facts } = await input.artifact.read((facts) => pendingFacts(facts, scan, selected));
+    const eligibility = await projectWakeEvidence({ ...facts, bindings: owners, location, hostLedger: input.hostLedger, now: input.now });
+    return [...new Set(facts.pending.filter((head) => wakeIsEligible(eligibility.evidence(head.recipient, head.index))).map((head) => head.index))];
 }

package/dist/delivery.d.ts

@@ -1,6 +1,5 @@
-import { type DirectedNotificationRoute, type SquareState, type StoredAct, type WatchLease, type WakeRouteKind } from './model.js';
-import { type Perception } from './square-core.js';
-import type { WakeOutcome } from './ports.js';
+import type { DirectedNotificationRoute, StoredAct, WatchLease, WakeRouteKind } from './model.js';
+import type { DirectedHead, ParticipantFact, SquareArtifactPort, SquareRead, WakeOutcome } from './ports.js';
 export type { DirectedNotificationRoute } from './model.js';
 export type SayItem = StoredAct & {
     kind: 'say';
@@ -10,21 +9,13 @@ export interface PlannedNotification {
     recipient: string;
     route: DirectedNotificationRoute;
 }
-/**
- * What one adapter reports about a wake it was handed.
- * `gate-rejected` means exactly one thing: the supplied beforeSend gate returned false and nothing was sent.
- * It is not a bin for other not-sent reasons; those stay `failed` with `unavailable: true`.
- */
+/** gate-rejected means the supplied beforeSend returned false and nothing was sent. */
 export type WakeAdapterResult = Exclude<WakeOutcome, {
     outcome: 'not-capable';
 }> | {
     outcome: 'gate-rejected';
 };
-/**
- * The coordinates of one wake attempt. An adapter that must hand the receiver a
- * stable dedup key derives it from these, so a retry of the same attempt reuses
- * the same key and a later attempt gets a new one.
- */
+/** One attempt's stable coordinates; retries reuse its dedup key. */
 export interface WakeDispatchContext {
     readonly location: string;
     readonly participant: string;
@@ -40,24 +31,34 @@ export interface RoutedNotification {
     route: DirectedNotificationRoute;
     recipient: string;
 }
-export interface DeliveryModel {
-    plan(item: StoredAct): PlannedNotification[];
-    pendingFor(recipient: string): PlannedNotification[];
-    directedTo(item: StoredAct, recipient: string): boolean;
-    perceive(item: StoredAct, viewer: string): Perception;
-    cursorFor(recipient: string): number;
-    isSeen(recipient: string, actOrIndex: StoredAct | number): boolean;
-    knownParticipant(name: string): string | undefined;
-    participants(): readonly string[];
-    joinedRecipients(): readonly string[];
-    readonly replayedActivityCount: number;
+/** Notification pending is not cursor suffix or historical catch membership. */
+export declare function pendingHead(facts: SquareRead, name: string, index: number): DirectedHead | undefined;
+/** Complete recipient projection, assembled inside its one transaction. */
+export declare function pendingNotifications(facts: SquareRead, name: string): PlannedNotification[];
+export interface PendingScan {
+    readonly roster: readonly ParticipantFact[];
+    readonly throughIndex: number;
 }
-export declare function isActivitySeen(squareState: SquareState, name: string, actOrIndex: StoredAct | number): boolean;
-/**
- * Derive delivery behavior once from the decoded Square state.
- * All consumers share these targets instead of reinterpreting artifact text or cursor state.
- */
-export declare function deriveDeliveryModel(squareState: SquareState): DeliveryModel;
-export declare function perceiveActivity(squareState: SquareState, item: StoredAct, viewer: string, delivery?: DeliveryModel): Perception;
-/** True only when the live catch's own filters would deliver this unread notification, independent of page size. */
+export declare function capturePendingScan(facts: SquareRead): PendingScan;
+export declare function sameJoin(facts: SquareRead, captured: ParticipantFact): boolean;
+/** Finite bodyless pass: unrelated revisions never rewind the last examined group. */
+export declare function pendingPages(artifact: SquareArtifactPort, scan: PendingScan, afterIndex?: number): AsyncGenerator<{
+    index: number;
+    at: number;
+    actor: string;
+    recipient: string;
+    route: "bell" | "mention" | "reply" | "attention";
+}[], void, unknown>;
+/** A pass retains only its captured joins; routes and individual receipts are fresh. */
+export declare function pendingFacts(facts: SquareRead, scan: PendingScan, heads: readonly DirectedHead[]): {
+    routes: readonly import("./ports.js").RouteFact[];
+    pending: DirectedHead[];
+};
+/** Global discovery alone uses pendingAudience; exact dispatch uses its one landed audience. */
+export declare function collectPending(artifact: SquareArtifactPort, index?: number): Promise<{
+    routes: readonly import("./ports.js").RouteFact[];
+    pending: DirectedHead[];
+    scan: PendingScan;
+}>;
+/** A live catch owns every matching notification, independent of its page size. */
 export declare function leaseOwnsNotification(lease: WatchLease, notification: RoutedNotification): boolean;

package/dist/delivery.js

@@ -1,90 +1,79 @@
-import { findParticipantName, sameName, } from './model.js';
-import { activityAuthors, audienceOf, replayLandedAudiences } from './square-core.js';
-import { derivePerceptionProjection } from './perception-projection.js';
-import { matchesMentionTarget } from './runtime.js';
 import { matchesCatchSelection } from './catch-selection.js';
-export function isActivitySeen(squareState, name, actOrIndex) {
-    return deriveDeliveryModel(squareState).isSeen(name, actOrIndex);
+/** Notification pending is not cursor suffix or historical catch membership. */
+export function pendingHead(facts, name, index) {
+    const participant = facts.participant(name);
+    if (!participant?.joined || index <= (participant.lastJoinIndex ?? -1) || facts.receipt(participant.name, index))
+        return undefined;
+    return facts.directedAt(participant.name, index);
 }
-/**
- * Derive delivery behavior once from the decoded Square state.
- * All consumers share these targets instead of reinterpreting artifact text or cursor state.
- */
-export function deriveDeliveryModel(squareState) {
-    const landed = replayLandedAudiences(squareState.acts);
-    const authors = activityAuthors(squareState.acts);
-    const perception = derivePerceptionProjection(squareState, landed);
-    const roster = [...landed.joined];
-    const plannedByIndex = new Map();
-    let pendingByRecipient;
-    function isSeen(requestedRecipient, actOrIndex) {
-        const index = typeof actOrIndex === 'number' ? actOrIndex : actOrIndex.index;
-        return perception.isSeen(requestedRecipient, index);
+/** Complete recipient projection, assembled inside its one transaction. */
+export function pendingNotifications(facts, name) {
+    const participant = facts.participant(name);
+    if (!participant?.joined)
+        return [];
+    const heads = [];
+    let afterIndex = participant.lastJoinIndex ?? -1;
+    for (;;) {
+        const page = facts.directed(participant.name, { afterIndex, unseenOnly: true }, { edge: 'oldest', limit: 100 });
+        heads.push(...page.items);
+        if (!page.hasMore)
+            break;
+        afterIndex = page.items.at(-1).index;
     }
-    function plan(item) {
-        if (item.kind !== 'say')
-            return [];
-        const cached = plannedByIndex.get(item.index);
-        if (cached !== undefined)
-            return [...cached];
-        const sayItem = item;
-        const audience = audienceOf(sayItem);
-        const recipients = landed.recipientsFor(sayItem);
-        const replyAuthor = sayItem.reply === undefined ? undefined : authors.get(sayItem.reply);
-        const planned = recipients.map((recipient) => {
-            const route = audience.kind === 'bell'
-                ? 'bell'
-                : matchesMentionTarget(sayItem, recipient) ? 'mention'
-                    : replyAuthor !== undefined && sameName(replyAuthor, recipient) ? 'reply'
-                        : 'attention';
-            return { item: sayItem, recipient, route };
+    const routes = new Map(heads.map((head) => [head.index, head.route]));
+    return facts.activities(heads.map((head) => head.index)).flatMap((item) => item.kind === 'say'
+        ? [{ item, recipient: participant.name, route: routes.get(item.index) }] : []);
+}
+export function capturePendingScan(facts) {
+    return { roster: facts.roster().filter((participant) => participant.joined), throughIndex: facts.header().lastActIndex };
+}
+export function sameJoin(facts, captured) {
+    const current = facts.participant(captured.name);
+    return current?.joined === captured.joined && current?.lastJoinIndex === captured.lastJoinIndex;
+}
+/** Finite bodyless pass: unrelated revisions never rewind the last examined group. */
+export async function* pendingPages(artifact, scan, afterIndex = -1) {
+    const captured = new Map(scan.roster.map((participant) => [participant.name, participant]));
+    while (afterIndex < scan.throughIndex) {
+        const { value: page } = await artifact.read((facts) => {
+            const page = facts.pendingAudience(afterIndex, scan.throughIndex, 100);
+            return { ...page, groups: page.groups.map((group) => ({ ...group, recipients: group.recipients.filter((recipient) => {
+                        const participant = captured.get(recipient.recipient);
+                        return participant !== undefined && sameJoin(facts, participant);
+                    }) })) };
         });
-        plannedByIndex.set(item.index, planned);
-        return [...planned];
+        yield page.groups.flatMap((group) => group.recipients.map(({ recipient, route }) => ({
+            index: group.index, at: group.at, actor: group.actor, recipient, route,
+        })));
+        if (!page.hasMore)
+            break;
+        afterIndex = page.groups.at(-1).index;
     }
-    function pendingFor(requestedRecipient) {
-        const recipient = findParticipantName(roster, requestedRecipient);
-        if (recipient === undefined)
-            return [];
-        if (pendingByRecipient === undefined) {
-            pendingByRecipient = new Map(roster.map((name) => [name, []]));
-            const joinedAfter = new Map(roster.map((name) => [name, landed.lastJoinIndex(name)]));
-            for (const act of squareState.acts) {
-                if (act.kind !== 'say')
-                    continue;
-                for (const planned of plan(act)) {
-                    const joinedAt = joinedAfter.get(planned.recipient);
-                    if (joinedAt === undefined || act.index <= joinedAt)
-                        continue;
-                    if (isSeen(planned.recipient, act.index))
-                        continue;
-                    pendingByRecipient.get(planned.recipient)?.push(planned);
-                }
-            }
-        }
-        return [...(pendingByRecipient.get(recipient) ?? [])];
-    }
-    return {
-        plan,
-        pendingFor,
-        directedTo: perception.directedTo,
-        perceive: perception.perceive,
-        cursorFor: perception.cursorFor,
-        isSeen,
-        knownParticipant: (name) => landed.resolveParticipant(name),
-        participants: () => landed.participants,
-        joinedRecipients: () => roster,
-        replayedActivityCount: perception.replayedActivityCount,
-    };
 }
-export function perceiveActivity(squareState, item, viewer, delivery = deriveDeliveryModel(squareState)) {
-    return delivery.perceive(item, viewer);
+/** A pass retains only its captured joins; routes and individual receipts are fresh. */
+export function pendingFacts(facts, scan, heads) {
+    const joined = new Set(scan.roster.filter((participant) => sameJoin(facts, participant)).map((participant) => participant.name));
+    return { routes: facts.routes(), pending: heads.filter((head) => joined.has(head.recipient)
+            && pendingHead(facts, head.recipient, head.index) !== undefined) };
+}
+/** Global discovery alone uses pendingAudience; exact dispatch uses its one landed audience. */
+export async function collectPending(artifact, index) {
+    const { value: initial } = await artifact.read((facts) => ({
+        scan: capturePendingScan(facts),
+        pending: index === undefined ? [] : facts.audience(index).flatMap(({ recipient }) => {
+            const head = pendingHead(facts, recipient, index);
+            return head === undefined ? [] : [head];
+        }),
+    }));
+    const pending = [...initial.pending];
+    if (index === undefined)
+        for await (const page of pendingPages(artifact, initial.scan))
+            pending.push(...page);
+    const { value } = await artifact.read((facts) => ({ scan: initial.scan, ...pendingFacts(facts, initial.scan, pending) }));
+    return value;
 }
-/** True only when the live catch's own filters would deliver this unread notification, independent of page size. */
+/** A live catch owns every matching notification, independent of its page size. */
 export function leaseOwnsNotification(lease, notification) {
-    return matchesCatchSelection(notification.actor, notification.route === 'bell'
-        ? { kind: 'bell' }
-        : { kind: 'mentions', names: notification.route === 'mention' ? [notification.recipient] : [] }, lease.filter ?? {}, 
-    // A reply reaches the recipient as the author of the activity it answers.
-    notification.route === 'reply' ? notification.recipient : undefined);
+    return matchesCatchSelection(notification.actor, notification.route === 'bell' ? { kind: 'bell' }
+        : { kind: 'mentions', names: notification.route === 'mention' ? [notification.recipient] : [] }, lease.filter ?? {}, notification.route === 'reply' ? notification.recipient : undefined);
 }

package/dist/help.js

@@ -74,6 +74,11 @@ const COMMANDS = [
         names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
         summary: 'Validate artifact integrity.',
     },
+    {
+        names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
+        summary: 'Convert an existing version 1 square to row storage in place.',
+        details: ['It is the only migration command: there is no --check, --backup or --force.', 'A version 2 square is left untouched; an unrelated or unsupported artifact is refused without a write.'],
+    },
 ];
 function definitionFor(command) {
     return COMMANDS.find((item) => item.names.includes(command));
@@ -85,7 +90,7 @@ export function renderGlobalHelp() {
     const groups = [
         { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'ignore', 'listening', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
-        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor'] },
+        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate'] },
     ];
     const commandLines = groups.flatMap(({ key, title, order }) => [
         title,

package/dist/inbox.d.ts

@@ -1,4 +1,5 @@
 import { type InboxMembership } from './model.js';
+import type { PresentationProjection, SessionBindingProjection, SquareRead } from './ports.js';
 export interface PendingWaitOptions {
     signal?: AbortSignal;
     /** Local delivery suppression, never persisted as evidence of receipt. */
@@ -7,6 +8,32 @@ export interface PendingWaitOptions {
     skipImmediate?: boolean;
     onChangeArmed?: (armed: boolean) => void;
 }
+export declare function projectPresentation(facts: SquareRead, requested: SessionBindingProjection, now?: number): PresentationProjection;
+export interface NativePendingPreview {
+    readonly payload: string;
+    readonly clipped: boolean;
+}
+export type NativePendingPreviewInput = {
+    readonly location: string;
+    readonly sessionId: string;
+    readonly participant: string;
+    readonly actIndex: number;
+    readonly epoch?: number;
+    readonly cancelledThrough?: number;
+    readonly now: number;
+} & ({
+    readonly routeKind: 'claude-native';
+    readonly address: {
+        readonly endpoint: string;
+    };
+} | {
+    readonly routeKind: 'opencode-server';
+    readonly address: {
+        readonly sessionId: string;
+    };
+});
+/** First matching ordered route, exact native epoch/address and catch ownership. */
+export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
 export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
 export interface SessionPendingObserver {
     wait(timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;

package/dist/inbox.js

@@ -1,21 +1,55 @@
 import { nameKey } from './model.js';
-import { openSquareArtifact, observeSquareChanges } from './square-file-adapter.js';
+import { createArtifactPort, observeSquareRevision } from './artifact.js';
 import { hostLedgerForEnv } from './registry.js';
 import { canonicalPath } from './canonical-path.js';
-import { projectBoundaryEligibility, projectPresentation, projectSessionBindings } from './square-projections.js';
-import { WATCH_STALE_MS } from './runtime.js';
+import { projectBoundaryEligibility, projectSessionBindings } from './square-projections.js';
+import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
+import { pendingHead, pendingNotifications, leaseOwnsNotification } from './delivery.js';
+import { attentionBodyIsClipped, renderAttentionPreview } from './attention-presentation.js';
+function bindingCoordinate(binding) {
+    return JSON.stringify([binding.location, nameKey(binding.participant), binding.sessionId, binding.channel, binding.epoch, binding.cancelledThrough ?? -1]);
+}
 function notificationKey(membership, actIndex) {
     return membership.squarePath + '\0' + membership.name.toLocaleLowerCase() + '\0' + actIndex;
 }
+export function projectPresentation(facts, requested, now = Date.now()) {
+    const participant = facts.participant(requested.participant);
+    if (!participant?.joined)
+        return { binding: requested, joined: false, notifications: [] };
+    const binding = { ...requested, participant: participant.name };
+    const notifications = pendingNotifications(facts, participant.name).map(({ item, route }) => ({
+        actIndex: item.index, actor: item.actor, at: item.at, body: item.body, route,
+    }));
+    const catchLease = freshWatchLease(facts, participant.name, now);
+    return { binding, joined: true, notifications, ...(catchLease === undefined ? {} : { catchLease }) };
+}
+/** First matching ordered route, exact native epoch/address and catch ownership. */
+export function nativePendingPreview(facts, input) {
+    const route = facts.routes().find((candidate) => candidate.kind === input.routeKind && candidate.sessionId === input.sessionId
+        && candidate.epoch === input.epoch && nameKey(candidate.participant) === nameKey(input.participant)
+        && (input.routeKind === 'claude-native' ? candidate.address.endpoint === input.address.endpoint : candidate.address.sessionId === input.address.sessionId));
+    if (!route || input.actIndex <= (input.cancelledThrough ?? -1))
+        return undefined;
+    const head = pendingHead(facts, input.participant, input.actIndex);
+    const lease = freshWatchLease(facts, input.participant, input.now);
+    if (!head || (lease !== undefined && leaseOwnsNotification(lease, head)))
+        return undefined;
+    const item = facts.activity(input.actIndex);
+    if (item?.kind !== 'say')
+        return undefined;
+    return { payload: renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
+            actor: item.actor, route: head.route, body: item.body }), clipped: attentionBodyIsClipped(item.body) };
+}
 async function readInboxMembership(binding, signal) {
-    const artifact = openSquareArtifact(binding.location, signal);
+    const artifact = createArtifactPort(binding.location, undefined, signal);
     try {
-        const projection = await projectPresentation({ artifact, binding, now: Date.now() });
-        if (!projection.joined)
-            return undefined;
-        return { name: projection.binding.participant, squarePath: projection.binding.location,
-            notifications: [...projection.notifications],
-            ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) };
+        return await artifact.read((facts) => {
+            const projection = projectPresentation(facts, binding);
+            if (!projection.joined)
+                return undefined;
+            return { name: projection.binding.participant, squarePath: projection.binding.location, notifications: [...projection.notifications],
+                ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) };
+        }, signal);
     }
     finally {
         await artifact.close();
@@ -28,7 +62,7 @@ export async function sessionInbox(sessionId, env = process.env, signal) {
         if (signal?.aborted)
             throw signal.reason;
         try {
-            const membership = await readInboxMembership(binding, signal);
+            const { value: membership } = await readInboxMembership(binding, signal);
             if (membership !== undefined)
                 inbox.push(membership);
         }
@@ -100,19 +134,18 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                     for (const file of paths) {
                         if (artifacts.has(file))
                             continue;
-                        const observer = await observeSquareChanges(file);
+                        const observer = await observeSquareRevision(file);
                         if (signal.aborted) {
                             observer.close();
                             return [];
                         }
                         artifacts.set(file, { observer, inbox: new Map() });
                     }
+                    const revisions = new Map();
                     for (const [file, entry] of artifacts) {
                         const source = await capture(entry.observer, 'artifact', signal);
                         sources.push(source);
-                        if (source.value === undefined || source.value !== entry.revision)
-                            entry.inbox.clear();
-                        entry.revision = source.value;
+                        revisions.set(file, source.value);
                         const names = new Set(bindings.filter((binding) => binding.location === file).map((binding) => nameKey(binding.participant)));
                         for (const name of entry.inbox.keys())
                             if (!names.has(name))
@@ -125,9 +158,13 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                         const entry = artifacts.get(binding.location);
                         const name = nameKey(binding.participant);
                         try {
-                            if (!entry.inbox.has(name))
-                                entry.inbox.set(name, await readInboxMembership(binding, signal));
-                            const membership = entry.inbox.get(name);
+                            const coordinate = bindingCoordinate(binding);
+                            const cached = entry.inbox.get(name);
+                            if (cached?.version !== revisions.get(binding.location) || cached?.binding !== coordinate) {
+                                const projection = await readInboxMembership(binding, signal);
+                                entry.inbox.set(name, { ...projection, binding: coordinate });
+                            }
+                            const membership = entry.inbox.get(name)?.value;
                             if (membership === undefined)
                                 continue;
                             const { catchLease, ...rest } = membership;