@astrosheep/square 0.3.62 → 0.3.64

package/dist/delivery-operations.js

@@ -1,8 +1,8 @@
-import { randomUUID } from 'node:crypto';
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { nameKey } from './model.js';
 import { deriveDeliveryModel } from './delivery.js';
-import { currentSessionBindings, isWakeRouteAttemptable, presentationSuppressesWake, projectPresentationEvidence } from './square-projections.js';
+import { projectWakeEvidenceFromState } from './square-projections.js';
+import { wakeIsEligible } from './wake-eligibility.js';
+import { canonicalPath } from './canonical-path.js';
 import { retireWakeRouteFromArtifact } from './routes.js';
 import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
 async function releaseWakeClaim(input, details) {
@@ -33,80 +33,43 @@ async function attemptWakeWithin(transport, request, timeoutMs, beforeSend) {
             clearTimeout(timer);
     }
 }
-export async function observeSquare(input) {
-    const snapshot = await input.artifact.read();
-    const delivery = deriveDeliveryModel(snapshot.state);
-    let rows = [];
-    if (input.hostLedger !== undefined) {
-        try {
-            rows = await input.hostLedger.listPresence({ location: input.location, now: input.now });
-        }
-        catch {
-            rows = [];
-        }
-    }
-    const bindings = rows.map((record) => ({
-        location: record.location,
-        participant: record.participant,
-        sessionId: record.session,
-        channel: record.channel,
-        ...(record.route === undefined ? {} : { route: { location: record.location, participant: record.participant, sessionId: record.session, channel: record.channel, kind: record.route.kind, address: { ...record.route.address }, updatedAt: record.updatedAt ?? 0 } }),
-        updatedAt: record.updatedAt ?? 0,
-    }));
-    return { ...(input.location === undefined ? {} : { location: input.location }), version: snapshot.version, state: snapshot.state, pending: delivery.joinedRecipients().map((recipient) => ({ recipient, notifications: delivery.pendingFor(recipient) })), bindings };
-}
 export async function deliverPending(input) {
-    const observation = await observeSquare({ artifact: input.artifact, hostLedger: input.hostLedger, location: input.location, now: input.now });
-    const routes = (observation.state.routes ?? []).map((route) => ({
-        location: route.location,
-        participant: route.participant,
-        session: route.sessionId,
-        channel: route.channel,
-        route: { kind: route.kind, address: route.address },
-        updatedAt: route.updatedAt,
-    }));
-    const liveRoutes = currentSessionBindings(routes.filter((route) => observation.bindings.some((binding) => nameKey(binding.participant) === nameKey(route.participant)
-        && binding.sessionId === route.session
-        && binding.location === route.location)));
-    let presentations = [];
-    try {
-        presentations = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: input.location, now: input.now });
-    }
-    catch { /* capability is handled by the route-level wake checks */ }
+    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 observeCurrentness = async (request, now) => {
+        const { state: currentState } = await input.artifact.read();
+        const projection = await projectWakeEvidenceFromState({ state: currentState, location, hostLedger: input.hostLedger, now });
+        return { ...projection.currentness({ ...request, location }), observationAvailable: true };
+    };
     let attempted = 0;
     let accepted = 0;
     let failed = 0;
     let unknown = 0;
     let notCapable = 0;
-    for (const membership of observation.pending) {
-        for (const notification of membership.notifications) {
+    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 candidates = liveRoutes.filter((route) => nameKey(route.participant) === nameKey(membership.recipient));
+            const evidence = eligibility.evidence(recipient, notification.item.index);
+            if (evidence.terminal !== undefined)
+                continue;
+            const candidates = evidence.attemptableRoutes;
             let acceptedForAttention = false;
             let failedForAttention = false;
             let unknownForAttention = false;
             let notCapableForAttention = false;
-            try {
-                const prior = await input.hostLedger.listWakeAttempts({ attention: { squarePath: input.location, actIndex: notification.item.index, recipient: membership.recipient }, now: Date.now() });
-                acceptedForAttention = prior.some((attempt) => attempt.outcome === 'accepted');
-            }
-            catch { /* capability is handled by the route-level probe */ }
-            if (acceptedForAttention)
-                continue;
-            if (candidates.length === 0)
+            if (candidates.length === 0 && !evidence.presented)
                 notCapableForAttention = true;
             for (const route of candidates) {
                 const activity = formatActivityId(notification.item.index);
-                const presented = presentations.filter((row) => row.activity === activity && row.participant.toLocaleLowerCase() === membership.recipient.toLocaleLowerCase() && row.sessionId === route.session && presentationSuppressesWake([row]));
-                if (presented.length > 0)
-                    continue;
-                const attention = { squarePath: input.location, actIndex: notification.item.index, recipient: membership.recipient };
+                const attention = { squarePath: location, actIndex: notification.item.index, recipient };
                 const leaseMs = input.timeoutMs ?? 5000;
-                const requestRoute = { location: route.location, participant: route.participant, sessionId: route.session, channel: route.channel, kind: route.route.kind, address: { ...route.route.address }, updatedAt: route.updatedAt ?? 0 };
+                const requestRoute = route;
                 if (input.transport.probe !== undefined) {
                     try {
                         const probe = await input.transport.probe(requestRoute);
@@ -120,167 +83,101 @@ export async function deliverPending(input) {
                         continue;
                     }
                 }
-                let leaseId = randomUUID();
-                let lease;
+                let claim;
                 try {
-                    lease = await input.hostLedger.claimWakeDispatch({ attention, leaseId, leaseMs, session: route.session });
+                    claim = await input.hostLedger.claimWakeAttempt({ attention, session: route.sessionId, routeKind: route.kind, leaseMs });
                 }
                 catch {
                     notCapableForAttention = true;
                     continue;
                 }
-                if (lease.type === 'ambiguous') {
-                    let recovered = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, claimToken: lease.lease.leaseId });
-                    if (recovered.status === 'busy' && recovered.record.claimToken !== undefined) {
-                        await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken: recovered.record.claimToken, routeKind: lease.lease.routeKind ?? route.route.kind, attemptN: lease.lease.attemptN }, {
-                            signature: 'stale_dispatch_claim_recovered',
-                            message: 'A stale dispatch claim was released so recovery could continue.',
-                        });
-                        recovered = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, claimToken: lease.lease.leaseId });
-                    }
-                    if (recovered.status === 'acquired') {
-                        await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: 'unknown', routeKind: lease.lease.routeKind ?? route.route.kind, attemptN: lease.lease.attemptN ?? 1, signature: 'worker_interrupted_during_dispatch', message: 'The notification worker ended after dispatch began; transport acceptance is unknown.', claimToken: recovered.claimToken });
-                    }
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId: lease.lease.leaseId, session: route.session });
-                    break;
-                }
-                if (lease.type === 'busy')
-                    break;
-                if (lease.type !== 'acquired')
-                    continue;
-                try {
-                    const completed = await input.hostLedger.listWakeAttempts({ attention, now: Date.now() });
-                    if (completed.some((attempt) => attempt.outcome === 'accepted')) {
-                        await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
-                        acceptedForAttention = true;
-                        break;
-                    }
-                }
-                catch { /* continue with the evidence claim */ }
-                let attempts;
-                try {
-                    attempts = await input.hostLedger.listWakeAttempts({ attention, now: Date.now() });
-                }
-                catch {
+                if (claim.status === 'degraded') {
                     notCapableForAttention = true;
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
                     continue;
                 }
-                if (attempts.some((attempt) => attempt.outcome === 'unknown')) {
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
+                // Busy and terminal outcomes are attention-wide: no other session or route may dispatch.
+                // A terminal attempt was already accepted or may already have been sent, so it reports nothing new.
+                if (claim.status === 'busy')
                     break;
-                }
-                const sessionAttempts = attempts.filter((attempt) => attempt.session === route.session);
-                const attemptN = sessionAttempts.reduce((highest, record) => Math.max(highest, record.attemptN ?? 0), 0) + 1;
-                const request = { location: input.location, participant: membership.recipient, activity, actor: notification.item.actor, route: requestRoute };
-                let outcome;
-                const claim = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, claimToken: leaseId });
-                if (claim.status !== 'acquired') {
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
-                    if (claim.status === 'degraded')
-                        notCapableForAttention = true;
-                    continue;
-                }
-                const claimToken = claim.claimToken;
-                const dispatching = await input.hostLedger.transitionWakeDispatch({ attention, leaseId, phase: 'dispatching', leaseMs, routeKind: route.route.kind, attemptN, session: route.session });
-                if (!dispatching) {
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
-                        signature: 'dispatch_claim_transition_failed',
-                        message: 'The wake dispatch claim could not enter the dispatching phase.',
-                    }).catch(() => undefined);
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
-                    continue;
-                }
+                if (claim.status === 'terminal')
+                    break;
+                const { claimToken, attemptN } = claim;
+                const request = { location: input.location, participant: recipient, activity, actor: notification.item.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 = {}) => {
+                    const release = releaseWakeClaim(claimRelease, details);
+                    if (options.bestEffortClaim === true)
+                        await release.catch(() => undefined);
+                    else
+                        await release;
+                };
                 let current;
                 try {
-                    current = await observeSquare({ artifact: input.artifact, hostLedger: input.hostLedger, location: input.location, now: input.now });
+                    current = await observeCurrentness(request, input.now ?? Date.now());
                 }
                 catch {
-                    current = { ...observation, pending: [], bindings: [] };
-                }
-                const stillPending = current.pending.some((entry) => nameKey(entry.recipient) === nameKey(membership.recipient)
-                    && entry.notifications.some((entryNotification) => entryNotification.item.index === notification.item.index));
-                const stillBound = current.bindings.some((binding) => nameKey(binding.participant) === nameKey(route.participant)
-                    && binding.sessionId === route.session
-                    && binding.location === route.location);
-                const stillPublished = (current.state.routes ?? []).some((published) => published.location === route.location
-                    && nameKey(published.participant) === nameKey(route.participant)
-                    && published.sessionId === route.session
-                    && published.kind === route.route.kind
-                    && JSON.stringify(published.address) === JSON.stringify(route.route.address));
-                if (!stillPending || !stillBound || !stillPublished) {
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
-                        signature: 'pre_send_revalidation_failed',
-                        message: 'Wake was not sent because the activity, session binding, or published route changed before dispatch.',
-                        diagnostic: { pending: stillPending, bound: stillBound, publishedRoute: stillPublished },
-                    }).catch(() => undefined);
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
+                    await abandon({ signature: 'pre_send_revalidation_failed', message: 'Wake was not sent because current Square delivery state could not be verified.', diagnostic: { observationAvailable: false } }, { bestEffortClaim: true }).catch(() => undefined);
                     continue;
                 }
-                let latestPresentations = [];
-                try {
-                    latestPresentations = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, sessionId: route.session, activity, now: input.now });
-                }
-                catch { /* capability is handled by the transport path */ }
-                if (presentationSuppressesWake(latestPresentations)) {
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
-                        signature: 'presentation_already_recorded',
-                        message: 'Wake was suppressed because presentation evidence already exists.',
-                        diagnostic: { outcomes: latestPresentations.map((row) => row.outcome) },
-                    }).catch(() => undefined);
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
+                if (!current.current) {
+                    await abandon({
+                        signature: current.presented ? 'presentation_already_recorded' : 'pre_send_revalidation_failed',
+                        message: current.presented ? 'Wake was suppressed because presentation evidence already exists.' : 'Wake was not sent because current attention, session binding, or route no longer matches.',
+                        diagnostic: current,
+                    }, { bestEffortClaim: true }).catch(() => undefined);
                     continue;
                 }
+                let outcome;
                 let suppressedDuringSend = false;
+                let finalCurrentness;
                 const beforeSend = async () => {
-                    let finalPresentations = [];
                     try {
-                        finalPresentations = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, sessionId: route.session, activity, now: Date.now() });
+                        finalCurrentness = await observeCurrentness(request, Date.now());
+                        suppressedDuringSend = !finalCurrentness.current;
+                    }
+                    catch {
+                        suppressedDuringSend = true;
                     }
-                    catch { /* capability is handled by the transport path */ }
-                    suppressedDuringSend = presentationSuppressesWake(finalPresentations);
                     return !suppressedDuringSend;
                 };
                 try {
-                    outcome = await attemptWakeWithin(input.transport, request, leaseMs, beforeSend);
+                    outcome = await attemptWakeWithin(input.transport, { ...request, claimToken, attemptN }, leaseMs, beforeSend);
                 }
                 catch (error) {
                     outcome = { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
                 }
                 if (suppressedDuringSend) {
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
-                        signature: 'presentation_recorded_during_dispatch',
-                        message: 'Wake was cancelled because presentation evidence appeared before the final send check.',
-                    }).catch(() => undefined);
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
+                    await abandon({
+                        signature: finalCurrentness?.presented === true ? 'presentation_recorded_during_dispatch' : 'pre_send_revalidation_failed',
+                        message: finalCurrentness === undefined ? 'Wake was not sent because current Square delivery state could not be verified.' : 'Wake was cancelled because current attention, ownership, cancellation, or presentation changed before the final send check.',
+                        diagnostic: finalCurrentness ?? { observationAvailable: false },
+                    }, { bestEffortClaim: true }).catch(() => undefined);
                     continue;
                 }
                 attempted += 1;
                 if (outcome.outcome === 'not-capable') {
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                    await abandon({
                         signature: 'transport_not_capable',
                         message: 'The wake transport reported that it could not deliver this route.',
                         diagnostic: outcome.diagnostic,
-                    }).catch(() => undefined);
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
+                    }, { bestEffortClaim: true }).catch(() => undefined);
                     notCapableForAttention = true;
                     continue;
                 }
                 if (outcome.outcome === 'failed' && outcome.unavailable) {
                     if (outcome.routeStale === true)
-                        await retireWakeRouteFromArtifact(input.artifact, { location: route.location, participant: route.participant, sessionId: route.session });
-                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN: outcome.attemptN ?? attemptN }, {
+                        await retireWakeRouteFromArtifact(input.artifact, { location: route.location, participant: route.participant, sessionId: route.sessionId });
+                    await abandon({
                         signature: outcome.signature ?? 'transport_unavailable',
                         message: outcome.message ?? 'The wake transport was unavailable.',
                         diagnostic: outcome.diagnostic,
                     });
-                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
                     failedForAttention = true;
                     continue;
                 }
                 const safeOutcome = redactCurrentDiagnostic(outcome);
-                await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: safeOutcome.outcome, routeKind: route.route.kind, attemptN: safeOutcome.attemptN ?? attemptN, ...(safeOutcome.signature === undefined ? {} : { signature: safeOutcome.signature }), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.message !== undefined ? { message: safeOutcome.message } : {}), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.diagnostic !== undefined ? { diagnostic: safeOutcome.diagnostic } : {}), claimToken });
-                await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
+                await input.hostLedger.appendEvidence({ location, participant: recipient, session: route.sessionId, activity, kind: 'wake', outcome: safeOutcome.outcome, routeKind: route.kind, attemptN, ...(safeOutcome.signature === undefined ? {} : { signature: safeOutcome.signature }), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.message !== undefined ? { message: safeOutcome.message } : {}), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.diagnostic !== undefined ? { diagnostic: safeOutcome.diagnostic } : {}), claimToken });
                 if (outcome.outcome === 'accepted') {
                     acceptedForAttention = true;
                     break;
@@ -304,55 +201,21 @@ export async function deliverPending(input) {
     }
     return { attempted, accepted, failed, unknown, notCapable };
 }
-export function selectPendingWakeActivities(state, routes, attempts, now, graceMs, limit, delivery = deriveDeliveryModel(state), presentations = []) {
-    const selected = new Set();
-    for (const membership of delivery.joinedRecipients()) {
-        for (const notification of delivery.pendingFor(membership)) {
-            if (now - notification.item.at <= graceMs)
-                continue;
-            if (attempts.some((attempt) => attempt.attention.actIndex === notification.item.index && nameKey(attempt.attention.recipient) === nameKey(membership) && attempt.outcome === 'accepted'))
-                continue;
-            const eligible = routes.some((binding) => {
-                if (binding.route === undefined || nameKey(binding.participant) !== nameKey(membership))
-                    return false;
-                const presented = presentations.filter((row) => row.activity === formatActivityId(notification.item.index) && row.participant.toLocaleLowerCase() === membership.toLocaleLowerCase() && row.sessionId === binding.session && presentationSuppressesWake([row]));
-                if (presented.length > 0)
-                    return false;
-                const matching = attempts.filter((attempt) => attempt.session === binding.session && nameKey(attempt.attention.recipient) === nameKey(membership) && attempt.attention.actIndex === notification.item.index);
-                return isWakeRouteAttemptable({ kind: binding.route.kind, updatedAt: binding.updatedAt ?? 0 }, matching);
-            });
-            if (eligible)
-                selected.add(notification.item.index);
-        }
-    }
-    return [...selected].sort((left, right) => left - right).slice(0, Math.max(0, limit));
-}
 export async function sweepPending(input) {
     const { state } = await input.artifact.read();
     return sweepPendingFromState({ ...input, state });
 }
 export async function sweepPendingFromState(input) {
-    const bindings = currentSessionBindings((input.state.routes ?? []).map((route) => ({ location: input.location, participant: route.participant, session: route.sessionId, channel: route.channel, route: { kind: route.kind, address: route.address }, updatedAt: route.updatedAt })));
-    let records = [];
-    try {
-        records = await input.hostLedger.listWakeAttempts({ now: input.now });
-    }
-    catch {
-        records = [];
-    }
-    let presentations = [];
-    try {
-        presentations = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: input.location, now: input.now });
-    }
-    catch {
-        presentations = [];
-    }
-    const attempts = records.flatMap((record) => {
-        const index = parseActivityId(record.activity);
-        if (index === undefined || record.routeKind === undefined || typeof record.attemptN !== 'number')
-            return [];
-        return [{ at: record.at ?? input.now, attention: { squarePath: record.location, actIndex: index, recipient: record.participant }, routeKind: record.routeKind, outcome: record.outcome, attemptN: record.attemptN, ...(record.session === undefined ? {} : { session: record.session }) }];
-    });
     const delivery = input.deriveDelivery?.(input.state) ?? deriveDeliveryModel(input.state);
-    return selectPendingWakeActivities(input.state, bindings, attempts, input.now, input.graceMs, input.limit, delivery, presentations);
+    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);
+        }
+    }
+    return [...selected].sort((left, right) => left - right).slice(0, Math.max(0, input.limit));
 }

package/dist/delivery.d.ts

@@ -1,61 +1,44 @@
-import { type DirectedNotificationRoute, type SquareState, type StoredAct, type WatchLease, type WatchLeaseFilter, type WakeRouteKind, type Reach } from './model.js';
+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';
 export type { DirectedNotificationRoute } from './model.js';
 export type SayItem = StoredAct & {
     kind: 'say';
 };
-export declare function notificationMessageId(squarePath: string, actIndex: number): string;
 export interface PlannedNotification {
     item: SayItem;
     recipient: string;
     route: DirectedNotificationRoute;
 }
-export interface WakeRequest {
-    squarePath: string;
-    actIndex: number;
-    recipient: string;
-    actor: string;
-    route: DirectedNotificationRoute;
-}
-export type WakeDispatchResult = {
-    outcome: 'accepted';
-} | {
-    outcome: 'unknown';
-    signature: string;
-    message: string;
-    diagnostic?: unknown;
-} | {
-    outcome: 'failed';
-    signature: string;
-    message: string;
-    diagnostic?: unknown;
-} | {
-    outcome: 'unavailable';
-    signature: string;
-    message: string;
-    diagnostic?: unknown;
-    retainRoute?: boolean;
-    routeStale?: boolean;
-} | {
-    outcome: 'cancelled';
+/**
+ * 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`.
+ */
+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.
+ */
+export interface WakeDispatchContext {
+    readonly location: string;
+    readonly participant: string;
+    readonly activity: string;
+    readonly attemptN?: number;
+}
 export interface WakeAdapter {
     readonly kind: WakeRouteKind;
-    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>, timeoutMs?: number): Promise<WakeDispatchResult>;
+    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>, timeoutMs?: number, context?: WakeDispatchContext): Promise<WakeAdapterResult>;
 }
 export interface RoutedNotification {
     actor: string;
-    body: string;
-    mentions?: readonly string[];
     route: DirectedNotificationRoute;
-    recipient?: string;
-}
-export interface CatchFilterShape {
-    actor: string;
-    body: string;
-    mentions?: readonly string[];
-    reach?: Reach;
-    recipients?: readonly string[];
+    recipient: string;
 }
 export interface DeliveryModel {
     plan(item: StoredAct): PlannedNotification[];
@@ -75,11 +58,6 @@ export declare function isActivitySeen(squareState: SquareState, name: string, a
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
  */
 export declare function deriveDeliveryModel(squareState: SquareState): DeliveryModel;
-export declare function planActNotifications(squareState: SquareState, item: StoredAct, delivery?: DeliveryModel): PlannedNotification[];
 export declare function perceiveActivity(squareState: SquareState, item: StoredAct, viewer: string, delivery?: DeliveryModel): Perception;
-/** Mark only the notifications selected by the canonical catch projection as fully seen. */
-export declare function markSeenNotifications(squareState: SquareState, recipient: string, delivered: StoredAct[], at?: number, delivery?: DeliveryModel): boolean;
-/** Canonical say-activity filter shared by catch selection and hook ownership. */
-export declare function matchesCatchFilter(activity: CatchFilterShape, filter: WatchLeaseFilter): boolean;
-/** True only when the live catch's own filters would deliver this notification. */
+/** True only when the live catch's own filters would deliver this unread notification, independent of page size. */
 export declare function leaseOwnsNotification(lease: WatchLease, notification: RoutedNotification): boolean;

package/dist/delivery.js

@@ -1,10 +1,8 @@
 import { findParticipantName, sameName, } from './model.js';
-import { audienceOf, formatActivityId, replayLandedAudiences } from './square-core.js';
+import { activityAuthors, audienceOf, replayLandedAudiences } from './square-core.js';
 import { derivePerceptionProjection } from './perception-projection.js';
-import { matchesMentionTarget, recordObservation } from './runtime.js';
-export function notificationMessageId(squarePath, actIndex) {
-    return `square:${squarePath}#${formatActivityId(actIndex)}`;
-}
+import { matchesMentionTarget } from './runtime.js';
+import { matchesCatchSelection } from './catch-selection.js';
 export function isActivitySeen(squareState, name, actOrIndex) {
     return deriveDeliveryModel(squareState).isSeen(name, actOrIndex);
 }
@@ -14,6 +12,7 @@ export function isActivitySeen(squareState, name, actOrIndex) {
  */
 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();
@@ -31,10 +30,13 @@ export function deriveDeliveryModel(squareState) {
         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' : 'attention';
+                : matchesMentionTarget(sayItem, recipient) ? 'mention'
+                    : replyAuthor !== undefined && sameName(replyAuthor, recipient) ? 'reply'
+                        : 'attention';
             return { item: sayItem, recipient, route };
         });
         plannedByIndex.set(item.index, planned);
@@ -75,48 +77,14 @@ export function deriveDeliveryModel(squareState) {
         replayedActivityCount: perception.replayedActivityCount,
     };
 }
-export function planActNotifications(squareState, item, delivery = deriveDeliveryModel(squareState)) {
-    return delivery.plan(item);
-}
 export function perceiveActivity(squareState, item, viewer, delivery = deriveDeliveryModel(squareState)) {
     return delivery.perceive(item, viewer);
 }
-/** Mark only the notifications selected by the canonical catch projection as fully seen. */
-export function markSeenNotifications(squareState, recipient, delivered, at = Date.now(), delivery = deriveDeliveryModel(squareState)) {
-    const deliveredIndexes = new Set(delivered.map((item) => item.index));
-    let changed = false;
-    for (const notification of delivery.pendingFor(recipient)) {
-        if (!deliveredIndexes.has(notification.item.index))
-            continue;
-        changed = recordObservation(squareState, notification.recipient, notification.item.index, 'seen', at) || changed;
-    }
-    return changed;
-}
-/** Canonical say-activity filter shared by catch selection and hook ownership. */
-export function matchesCatchFilter(activity, filter) {
-    if (filter.participants !== undefined &&
-        !filter.participants.some((participant) => sameName(participant, activity.actor))) {
-        return false;
-    }
-    if (audienceOf(activity).kind === 'bell')
-        return true;
-    if (filter.mention === undefined)
-        return true;
-    return activity.recipients?.some((recipient) => sameName(recipient, filter.mention)) === true
-        || matchesMentionTarget(activity, filter.mention);
-}
-/** True only when the live catch's own filters would deliver this notification. */
+/** True only when the live catch's own filters would deliver this unread notification, independent of page size. */
 export function leaseOwnsNotification(lease, notification) {
-    if (lease.filter?.mention !== undefined
-        && notification.route !== 'bell'
-        && notification.recipient !== undefined
-        && !sameName(lease.filter.mention, notification.recipient))
-        return false;
-    return matchesCatchFilter({
-        actor: notification.actor,
-        body: notification.body,
-        ...(notification.mentions === undefined ? {} : { mentions: notification.mentions }),
-        ...(notification.recipient === undefined ? {} : { recipients: [notification.recipient] }),
-        ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
-    }, lease.filter ?? {});
+    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);
 }

package/dist/diagnostic-redaction.js

@@ -1,16 +1,14 @@
 const MAX_STRING_LENGTH = 1_000;
 const MAX_COLLECTION_ITEMS = 32;
 const MAX_NESTING = 8;
-function redactText(value, secret) {
-    const withoutSecret = secret?.trim() ? value.split(secret.trim()).join('[redacted]') : value;
-    const withoutUrlPassword = withoutSecret.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
-    return [...withoutUrlPassword].length <= MAX_STRING_LENGTH
-        ? withoutUrlPassword
-        : `${[...withoutUrlPassword].slice(0, MAX_STRING_LENGTH - 1).join('')}…`;
-}
 function redactValue(value, secret, seen, depth) {
-    if (typeof value === 'string')
-        return redactText(value, secret);
+    if (typeof value === 'string') {
+        const withoutSecret = secret?.trim() ? value.split(secret.trim()).join('[redacted]') : value;
+        const withoutUrlPassword = withoutSecret.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
+        return [...withoutUrlPassword].length <= MAX_STRING_LENGTH
+            ? withoutUrlPassword
+            : `${[...withoutUrlPassword].slice(0, MAX_STRING_LENGTH - 1).join('')}…`;
+    }
     if (depth >= MAX_NESTING)
         return '[truncated]';
     if (Array.isArray(value)) {

package/dist/file-changes.d.ts

@@ -1,4 +1,3 @@
-export declare function canonicalFilePath(value: string): Promise<string>;
 export interface VersionObserver<T> {
     readonly generation: number;
     hinted(since: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;