@crouton-kit/crouter 0.3.56 → 0.3.58

package/dist/clients/web/__tests__/push-registry.test.js

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { PushRegistryStore, PushRequestError, isAllowedPushEndpoint, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, subscriptionIdForEndpoint, } from '../push-registry.js';
+function tmpDir() {
+    return mkdtempSync(join(tmpdir(), 'crtr-push-registry-'));
+}
+// A real, allowlisted vendor push-service endpoint shape (Chromium/FCM) —
+// endpoints must resolve to one of the small set of known browser-vendor push
+// services; arbitrary hosts (including this suite's old `push.example.com`
+// placeholder) are no longer accepted.
+const VALID_ENDPOINT = 'https://fcm.googleapis.com/fcm/send/abc123';
+const VALID_P256DH = 'p'.repeat(64);
+const VALID_AUTH = 'a'.repeat(22);
+function validBody(overrides = {}) {
+    return JSON.stringify({
+        endpoint: VALID_ENDPOINT,
+        keys: { p256dh: VALID_P256DH, auth: VALID_AUTH },
+        ...overrides,
+    });
+}
+test('a well-formed subscription body parses and persists behind a scoped, non-secret authScope', () => {
+    const dir = tmpDir();
+    try {
+        const record = parsePushSubscriptionBody(validBody(), 'token:deadbeef');
+        assert.equal(record.endpoint, VALID_ENDPOINT);
+        assert.equal(record.authScope, 'token:deadbeef');
+        assert.equal(record.id, subscriptionIdForEndpoint(VALID_ENDPOINT));
+        assert.equal(record.prefs.doneNotifications, true);
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(record);
+        assert.equal(registry.listByScope('token:deadbeef').length, 1);
+        // The persisted file never carries a raw bearer token \u2014 only the derived
+        // scope string, which is exactly what was passed in above.
+        const onDisk = readFileSync(join(dir, 'registry.json'), 'utf8');
+        assert.ok(onDisk.includes('token:deadbeef'));
+        assert.ok(!onDisk.toLowerCase().includes('bearer'));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('the registry persists only the derived scope digest, never the raw token pre-image', () => {
+    const dir = tmpDir();
+    try {
+        // Mirror scopeForToken (server.ts): scope = 'token:' + sha256(raw).base64url[:16].
+        const raw = 'SUPERSECRET-TOKEN-VALUE';
+        const scope = `token:${createHash('sha256').update(raw).digest('base64url').slice(0, 16)}`;
+        const record = parsePushSubscriptionBody(validBody(), scope);
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(record);
+        const onDisk = readFileSync(join(dir, 'registry.json'), 'utf8');
+        assert.ok(onDisk.includes(scope));
+        assert.ok(!onDisk.includes(raw));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('rejects IPv6 and v4-mapped private/localhost endpoints before persistence', () => {
+    for (const endpoint of [
+        'https://[::1]/x',
+        'https://[fc00::1]/x',
+        'https://[fe80::1]/x',
+        'https://[::ffff:127.0.0.1]/x',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('the endpoint host must be an allowlisted push service — an arbitrary host is rejected even over https', () => {
+    for (const endpoint of [
+        'https://push.example.com/abc123', // not a recognized push-service host
+        'https://evil.attacker.example/abc123',
+        'https://fcm.googleapis.com.attacker.example/abc123', // suffix-spoof attempt
+        'https://notgooglapis.com/fcm/send/abc123',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+        assert.equal(isAllowedPushEndpoint(endpoint), false, endpoint);
+    }
+});
+test('a trailing DNS root dot never bypasses the allowlist/localhost check', () => {
+    for (const endpoint of ['https://localhost./x', 'https://foo.localhost./x', 'https://fcm.googleapis.com./fcm/send/abc']) {
+        // The last one is a real allowlisted host WITH a trailing dot: it must
+        // canonicalize to the same allowed match, not be rejected as a foreign
+        // host, and localhost-with-trailing-dot must still be rejected.
+        if (endpoint.includes('localhost')) {
+            assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+        }
+        else {
+            assert.doesNotThrow(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), endpoint);
+        }
+    }
+});
+test('the private/reserved IP ranges the old blocklist missed are moot under the allowlist — no IP literal is ever allowed', () => {
+    for (const endpoint of [
+        'https://0.0.0.0/x', // 0.0.0.0/8
+        'https://100.64.0.1/x', // CGNAT 100.64.0.0/10
+        'https://192.0.0.1/x', // 192.0.0.0/24
+        'https://198.18.0.1/x', // 198.18.0.0/15
+        'https://240.0.0.1/x', // 240.0.0.0/4
+        'https://224.0.0.1/x', // multicast
+        'https://[::]/x', // IPv6 unspecified
+        'https://[fe90::1]/x', // fe80::/10, beyond the fe80* prefix
+        'https://[ff02::1]/x', // IPv6 multicast
+        'https://8.8.8.8/x', // a genuinely PUBLIC IP — still not allowlisted
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('every real browser-vendor push-service endpoint shape is allowlisted, including a subdomain form', () => {
+    for (const endpoint of [
+        'https://fcm.googleapis.com/fcm/send/abc123',
+        'https://android.googleapis.com/gcm/send/abc123',
+        'https://updates.push.services.mozilla.com/wpush/v2/abc123',
+        'https://web.push.apple.com/abc123',
+        'https://notify.windows.com/w/abc123',
+        'https://sub.notify.windows.com/w/abc123',
+        'https://wns.windows.com/w/abc123',
+        'https://sub.wns.windows.com/w/abc123',
+    ]) {
+        assert.equal(isAllowedPushEndpoint(endpoint), true, endpoint);
+        assert.doesNotThrow(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), endpoint);
+    }
+});
+test('deleteByEndpoint is scoped: a caller can only remove a subscription it owns', () => {
+    const dir = tmpDir();
+    try {
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(parsePushSubscriptionBody(validBody(), 'scope-A'));
+        assert.equal(registry.deleteByEndpoint(VALID_ENDPOINT, 'scope-B'), false);
+        assert.equal(registry.listByScope('scope-A').length, 1);
+        assert.equal(registry.deleteByEndpoint(VALID_ENDPOINT, 'scope-A'), true);
+        assert.equal(registry.listByScope('scope-A').length, 0);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('rejects a malformed body shape (unknown keys, missing fields)', () => {
+    assert.throws(() => parsePushSubscriptionBody(JSON.stringify({ endpoint: VALID_ENDPOINT }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody(JSON.stringify({ endpoint: VALID_ENDPOINT, keys: { p256dh: VALID_P256DH, auth: VALID_AUTH }, extra: 'nope' }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody('not json', 'local'), PushRequestError);
+});
+test('rejects an oversized body before persistence', () => {
+    const oversized = validBody({ prefs: { doneNotifications: true, pad: 'x'.repeat(pushBodyMaxBytes()) } });
+    assert.throws(() => parsePushSubscriptionBody(oversized, 'local'), PushRequestError);
+});
+test('rejects private/localhost/file/http endpoints before persistence', () => {
+    for (const endpoint of [
+        'http://push.example.com/abc', // not https
+        'https://localhost/abc',
+        'https://127.0.0.1/abc',
+        'https://10.0.0.5/abc',
+        'https://192.168.1.5/abc',
+        'file:///etc/passwd',
+        'not-a-url',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('rejects malformed base64url subscription keys', () => {
+    assert.throws(() => parsePushSubscriptionBody(validBody({ keys: { p256dh: 'not base64url!!', auth: VALID_AUTH } }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody(validBody({ keys: { p256dh: VALID_P256DH, auth: 'short' } }), 'local'), PushRequestError);
+});
+test('DELETE body parses down to just the endpoint', () => {
+    const { endpoint } = parsePushDeleteBody(JSON.stringify({ endpoint: VALID_ENDPOINT }));
+    assert.equal(endpoint, VALID_ENDPOINT);
+    assert.throws(() => parsePushDeleteBody(JSON.stringify({ endpoint: 'https://localhost/x' })), PushRequestError);
+});
+test('the id is a stable hash of the normalized endpoint, independent of scope', () => {
+    const a = parsePushSubscriptionBody(validBody(), 'local');
+    const b = parsePushSubscriptionBody(validBody(), 'token:other');
+    assert.equal(a.id, b.id);
+});

package/dist/clients/web/events.d.ts

@@ -4,6 +4,11 @@ export interface EventHub {
     /** Register an SSE client: writes the event-stream headers, streams events
      *  until the connection closes, and self-removes on close. */
     addClient: (res: ServerResponse) => void;
+    /** Internal, in-process subscription to the same invalidations SSE clients
+     *  receive — for a server-side consumer (the push diff engine) that needs
+     *  the trigger without opening an HTTP/SSE connection to itself. Returns an
+     *  unsubscribe function. */
+    subscribe: (listener: (kind: ChangeKind) => void) => () => void;
     /** Tear down watchers + heartbeat and end all open streams. */
     close: () => void;
 }

package/dist/clients/web/events.js

@@ -36,6 +36,7 @@ export function startEventHub() {
     const clients = new Set();
     const watchers = [];
     const timers = new Map();
+    const listeners = new Set();
     const broadcast = (kind) => {
         const line = `data: ${JSON.stringify({ kind, ts: Date.now() })}\n\n`;
         for (const res of clients) {
@@ -46,6 +47,14 @@ export function startEventHub() {
                 /* a dead stream is reaped by its own 'close' handler */
             }
         }
+        for (const listener of listeners) {
+            try {
+                listener(kind);
+            }
+            catch {
+                /* an in-process consumer's failure must never break SSE fan-out */
+            }
+        }
     };
     // Debounce per kind: an fs event arms a trailing timer; a fresh event within
     // the window resets it, so a write cluster emits exactly once.
@@ -122,6 +131,12 @@ export function startEventHub() {
             res.on('close', drop);
             res.on('error', drop);
         },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
         close() {
             clearInterval(heartbeat);
             for (const t of timers.values())
@@ -144,6 +159,7 @@ export function startEventHub() {
                 }
             }
             clients.clear();
+            listeners.clear();
         },
     };
 }

package/dist/clients/web/push-engine.d.ts

@@ -0,0 +1,108 @@
+import type { NodeLifeStatus } from './web-client/shared/protocol.js';
+import type { PushLastSeenStore, PushRegistryStore, PushSubscriptionRecord } from './push-registry.js';
+/** The subset of `NodeSummary` the diff engine needs — kept minimal and
+ *  decoupled from the full wire type so the engine can be fed by any canvas
+ *  reader (production: `canvas snapshot`; tests: a fixture array). */
+export interface CanvasNodeRow {
+    node_id: string;
+    parent: string | null;
+    status: NodeLifeStatus;
+    attention_count: number;
+}
+/** A pending human ask with just the `DeckSummary` provenance the payload/dedupe
+ *  logic needs (design: "ask provenance comes from DeckSummary"). */
+export interface PendingAsk {
+    /** Opaque, stable inbox-entry id — the dedupe key (never re-notify the same
+     *  unresolved ask). */
+    id: string;
+    /** The interaction job id — carried in the payload as `askId` for the deep-link. */
+    jobId: string;
+    title: string;
+    conversationId: string;
+    conversationTitle: string;
+    blockedSince: string;
+}
+export type PushSendResult = 'sent' | 'gone' | 'error';
+export interface PushPayload {
+    conversationId: string;
+    kind: 'needs-you' | 'done';
+    askId?: string;
+    title: string;
+    snippet: string;
+}
+export interface PushEngineDeps {
+    registry: PushRegistryStore;
+    lastSeen: PushLastSeenStore;
+    /** Re-read the live canvas roster. */
+    readCanvasNodes: () => Promise<CanvasNodeRow[]> | CanvasNodeRow[];
+    /** Re-read every currently pending ask (deck provenance). */
+    readPendingAsks: () => Promise<PendingAsk[]> | PendingAsk[];
+    /** Deliver one push to one subscription. Implementations classify a
+     *  service-side 404/410 as `'gone'` so the engine can prune the record. */
+    sendPush: (record: PushSubscriptionRecord, payload: PushPayload) => Promise<PushSendResult>;
+    /** True iff a subscription's persisted authScope matches the canvas/user this
+     *  engine is watching (design line 252: push is sent ONLY to subscriptions
+     *  whose authScope is on the identical boundary that protects /__crtr/source).
+     *  Required — no lenient default — so a foreign scope can never be targeted. */
+    isTargetScope: (authScope: string) => boolean;
+    now?: () => number;
+    rateWindowMs?: number;
+}
+export declare class PushDiffEngine {
+    private readonly registry;
+    private readonly lastSeen;
+    private readonly readCanvasNodes;
+    private readonly readPendingAsks;
+    private readonly sendPush;
+    private readonly isTargetScope;
+    private readonly now;
+    private readonly rateWindowMs;
+    /** Drain-queue state: only one diff pass mutates last-seen at a time. An
+     *  invalidation arriving mid-pass sets its pending flag and is reprocessed
+     *  when the current pass finishes — no two passes race the same snapshot. */
+    private draining;
+    private pendingNodes;
+    private pendingInbox;
+    /** Per-conversation rate-cap clock. Deliberately in-memory/process-lifetime
+     *  only (not persisted) — a restart re-seeding silently is already the
+     *  no-storm guarantee; the rate cap only smooths a live process's bursts. */
+    private readonly lastPushAt;
+    /** Per-(conversationId+kind) set of subscription ids already delivered for
+     *  the CURRENT still-pending notification. A transient failure on one
+     *  subscription must never cause a later retry to re-send to subscriptions
+     *  that already got `'sent'` — this is exactly what remembers them across
+     *  passes. Cleared the moment the event fully succeeds (or has no eligible
+     *  subscriber left), since a later, distinct event reusing the same key
+     *  must start fresh. */
+    private readonly deliveredForKey;
+    constructor(deps: PushEngineDeps);
+    /** Seed last-seen from a fresh canvas+deck read and send nothing. Call once
+     *  on server start — a restart must never be an attention event. */
+    seed(): Promise<void>;
+    /** 'nodes' invalidation: re-read the canvas roster, emit a 'done' push for
+     *  every conversation root that just crossed into a done|dead|canceled
+     *  status from a non-done status. */
+    onNodesInvalidation(): Promise<void>;
+    onInboxInvalidation(): Promise<void>;
+    /** Serialize passes: if a pass is already running, just set the pending flag
+     *  and return — the running drain loop will pick it up. Otherwise run pending
+     *  passes until none remain. */
+    private drain;
+    private runNodesPass;
+    /** 'inbox' invalidation: re-read pending asks, emit exactly one 'needs-you'
+     *  push per conversation for its NEW (not-yet-notified) asks, coalesced. An
+     *  ask no longer present (resolved/missing) is simply dropped, never
+     *  notified. */
+    private runInboxPass;
+    /** Send one push per ELIGIBLE subscription — one whose authScope is on the
+     *  watched boundary (`isTargetScope`) AND that opted in for this payload kind.
+     *  Respects the per-conversation rate cap; prunes any subscription the push
+     *  service reports gone (404/410) or whose endpoint fails the push-service
+     *  allowlist re-check. Tracks per-subscription delivery for this notification
+     *  (`deliveredForKey`) so a retry after a transient failure on one
+     *  subscription never re-sends to a subscription that already got `'sent'`.
+     *  Returns true iff last-seen may advance: false when suppressed by the rate
+     *  cap OR when a transient send error means the item must be retried next
+     *  pass. A no-eligible pass returns true (nothing to retry). */
+    private emit;
+}

package/dist/clients/web/push-engine.js

@@ -0,0 +1,256 @@
+// push-engine.ts — the server-side web-push DIFF ENGINE (design D8/push
+// contract). SSE (`events.ts`) is a TRIGGER ONLY (`{kind, ts}`, never data);
+// this module is the one authority that re-reads canvas + decks on that
+// trigger, diffs against persisted last-seen state, and decides what (if
+// anything) to push. It never invents a second attention signal — decks/canvas
+// stay the truth.
+//
+// Two invalidation kinds drive two independent diff passes:
+//   - 'nodes'  -> re-read the canvas roster, detect a conversation ROOT
+//                 (parent === null) crossing into a done|dead|canceled status
+//                 from a non-done status, emit one 'done' push per transition.
+//   - 'inbox'  -> re-read pending asks (deck provenance), detect an ask id that
+//                 is present now but was not known-notified before, emit one
+//                 'needs-you' push per NEW ask, coalesced per conversation.
+//
+// On server start, `seed()` records the current state and sends NOTHING — a
+// restart is not an attention event.
+//
+// Last-seen state is only advanced past a suppressed (rate-capped) item when
+// that item was not actually the reason for suppression; a rate-capped
+// transition/ask is deliberately left out of the persisted state so the NEXT
+// invalidation retries it rather than silently losing it forever.
+import { isAllowedPushEndpoint } from './push-registry.js';
+const DONE_STATUSES = new Set(['done', 'dead', 'canceled']);
+/** Minimum interval between pushes for the same conversation root — coalesces
+ *  a burst of distinct events (several new asks, or an ask+done in close
+ *  succession) into at most one send per window, never a storm. */
+const DEFAULT_RATE_WINDOW_MS = 30_000;
+export class PushDiffEngine {
+    registry;
+    lastSeen;
+    readCanvasNodes;
+    readPendingAsks;
+    sendPush;
+    isTargetScope;
+    now;
+    rateWindowMs;
+    /** Drain-queue state: only one diff pass mutates last-seen at a time. An
+     *  invalidation arriving mid-pass sets its pending flag and is reprocessed
+     *  when the current pass finishes — no two passes race the same snapshot. */
+    draining = false;
+    pendingNodes = false;
+    pendingInbox = false;
+    /** Per-conversation rate-cap clock. Deliberately in-memory/process-lifetime
+     *  only (not persisted) — a restart re-seeding silently is already the
+     *  no-storm guarantee; the rate cap only smooths a live process's bursts. */
+    lastPushAt = new Map();
+    /** Per-(conversationId+kind) set of subscription ids already delivered for
+     *  the CURRENT still-pending notification. A transient failure on one
+     *  subscription must never cause a later retry to re-send to subscriptions
+     *  that already got `'sent'` — this is exactly what remembers them across
+     *  passes. Cleared the moment the event fully succeeds (or has no eligible
+     *  subscriber left), since a later, distinct event reusing the same key
+     *  must start fresh. */
+    deliveredForKey = new Map();
+    constructor(deps) {
+        this.registry = deps.registry;
+        this.lastSeen = deps.lastSeen;
+        this.readCanvasNodes = deps.readCanvasNodes;
+        this.readPendingAsks = deps.readPendingAsks;
+        this.sendPush = deps.sendPush;
+        this.isTargetScope = deps.isTargetScope;
+        this.now = deps.now ?? (() => Date.now());
+        this.rateWindowMs = deps.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
+    }
+    /** Seed last-seen from a fresh canvas+deck read and send nothing. Call once
+     *  on server start — a restart must never be an attention event. */
+    async seed() {
+        const [nodes, asks] = await Promise.all([this.readCanvasNodes(), this.readPendingAsks()]);
+        const roots = {};
+        for (const n of nodes) {
+            if (n.parent !== null)
+                continue;
+            roots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+        }
+        const askState = {};
+        for (const a of asks)
+            askState[a.id] = { present: true };
+        this.lastSeen.replace({ schemaVersion: 1, updatedAt: this.now(), roots, asks: askState });
+    }
+    /** 'nodes' invalidation: re-read the canvas roster, emit a 'done' push for
+     *  every conversation root that just crossed into a done|dead|canceled
+     *  status from a non-done status. */
+    async onNodesInvalidation() {
+        this.pendingNodes = true;
+        await this.drain();
+    }
+    async onInboxInvalidation() {
+        this.pendingInbox = true;
+        await this.drain();
+    }
+    /** Serialize passes: if a pass is already running, just set the pending flag
+     *  and return — the running drain loop will pick it up. Otherwise run pending
+     *  passes until none remain. */
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            while (this.pendingNodes || this.pendingInbox) {
+                if (this.pendingNodes) {
+                    this.pendingNodes = false;
+                    await this.runNodesPass();
+                }
+                if (this.pendingInbox) {
+                    this.pendingInbox = false;
+                    await this.runInboxPass();
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async runNodesPass() {
+        const nodes = await this.readCanvasNodes();
+        const prev = this.lastSeen.snapshot();
+        const nextRoots = {};
+        for (const n of nodes) {
+            if (n.parent !== null)
+                continue;
+            const before = prev.roots[n.node_id];
+            const isTransition = before !== undefined && !DONE_STATUSES.has(before.status) && DONE_STATUSES.has(n.status);
+            if (!isTransition) {
+                nextRoots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+                continue;
+            }
+            const sent = await this.emit(n.node_id, {
+                conversationId: n.node_id,
+                kind: 'done',
+                title: 'Conversation finished',
+                snippet: `This conversation is now ${n.status}.`,
+            });
+            // Rate-capped: keep the PRE-transition state so the next 'nodes'
+            // invalidation still sees a non-done -> done edge and retries.
+            nextRoots[n.node_id] = sent ? { status: n.status, attention_count: n.attention_count } : before;
+        }
+        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: nextRoots, asks: prev.asks });
+    }
+    /** 'inbox' invalidation: re-read pending asks, emit exactly one 'needs-you'
+     *  push per conversation for its NEW (not-yet-notified) asks, coalesced. An
+     *  ask no longer present (resolved/missing) is simply dropped, never
+     *  notified. */
+    async runInboxPass() {
+        const asks = await this.readPendingAsks();
+        const prev = this.lastSeen.snapshot();
+        const nextAsks = {};
+        const newByConversation = new Map();
+        for (const ask of asks) {
+            if (prev.asks[ask.id]?.present === true) {
+                // Already known + already notified at some point — keep tracked, never
+                // re-notify the same unresolved ask.
+                nextAsks[ask.id] = { present: true };
+                continue;
+            }
+            const list = newByConversation.get(ask.conversationId) ?? [];
+            list.push(ask);
+            newByConversation.set(ask.conversationId, list);
+        }
+        for (const [conversationId, list] of newByConversation) {
+            const first = list[0];
+            const extra = list.length - 1;
+            const sent = await this.emit(conversationId, {
+                conversationId,
+                kind: 'needs-you',
+                askId: first.jobId,
+                title: first.conversationTitle,
+                snippet: extra > 0 ? `${first.title} (+${extra} more)` : first.title,
+            });
+            if (sent) {
+                for (const ask of list)
+                    nextAsks[ask.id] = { present: true };
+            }
+            // Rate-capped: leave these ask ids OUT of nextAsks so the next 'inbox'
+            // invalidation still sees them as new and retries once the window clears.
+        }
+        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: prev.roots, asks: nextAsks });
+    }
+    /** Send one push per ELIGIBLE subscription — one whose authScope is on the
+     *  watched boundary (`isTargetScope`) AND that opted in for this payload kind.
+     *  Respects the per-conversation rate cap; prunes any subscription the push
+     *  service reports gone (404/410) or whose endpoint fails the push-service
+     *  allowlist re-check. Tracks per-subscription delivery for this notification
+     *  (`deliveredForKey`) so a retry after a transient failure on one
+     *  subscription never re-sends to a subscription that already got `'sent'`.
+     *  Returns true iff last-seen may advance: false when suppressed by the rate
+     *  cap OR when a transient send error means the item must be retried next
+     *  pass. A no-eligible pass returns true (nothing to retry). */
+    async emit(conversationId, payload) {
+        // Eligible = in the watched auth scope AND opted-in for this payload kind.
+        const eligible = this.registry.snapshot().filter((r) => {
+            if (!this.isTargetScope(r.authScope))
+                return false;
+            if (payload.kind === 'done' && !r.prefs.doneNotifications)
+                return false;
+            return true;
+        });
+        // Keyed by conversation + kind: a later, distinct event reusing this key
+        // (once cleared below) must start with a fresh delivered set.
+        const key = `${conversationId}:${payload.kind}`;
+        // No eligible subscriber -> the event is fully handled (nothing to retry);
+        // advance last-seen. Checked BEFORE the rate cap so a no-eligible pass never
+        // stalls the state on a phantom retry.
+        if (eligible.length === 0) {
+            this.deliveredForKey.delete(key);
+            return true;
+        }
+        const now = this.now();
+        const last = this.lastPushAt.get(conversationId) ?? 0;
+        if (now - last < this.rateWindowMs)
+            return false; // rate-capped -> retry next pass
+        this.lastPushAt.set(conversationId, now);
+        const delivered = this.deliveredForKey.get(key) ?? new Set();
+        let transientFailure = false;
+        for (const record of eligible) {
+            // Already delivered to this subscription for this event on an earlier
+            // pass — never re-send it (this is the fix for duplicate pushes on
+            // transient-failure retry: only the subscriptions that actually failed
+            // are retried).
+            if (delivered.has(record.id))
+                continue;
+            if (!isAllowedPushEndpoint(record.endpoint)) {
+                // Defense in depth: re-check the push-service allowlist immediately
+                // before every outbound connect (no DNS/host TOCTOU), even though
+                // normalizeEndpoint already enforced it at subscribe time. A record
+                // that fails this can never be sent to safely — prune it.
+                this.registry.deleteById(record.id);
+                continue;
+            }
+            let result;
+            try {
+                result = await this.sendPush(record, payload);
+            }
+            catch {
+                result = 'error';
+            }
+            if (result === 'gone')
+                this.registry.deleteById(record.id);
+            else if (result === 'sent')
+                delivered.add(record.id);
+            else
+                transientFailure = true;
+        }
+        // A transient send failure must NOT advance last-seen — retry next pass
+        // (design: "update last-seen only after a successful diff pass"), and the
+        // subscriptions already delivered above must stay remembered so that retry
+        // only reaches the ones that failed. A pruned 'gone'/disallowed record is
+        // not a failure: nothing left to retry for it.
+        if (transientFailure) {
+            this.deliveredForKey.set(key, delivered);
+            return false;
+        }
+        this.deliveredForKey.delete(key);
+        return true;
+    }
+}