@north-light/crouter 0.3.154

package/dist/clients/web/events.js

@@ -0,0 +1,165 @@
+// events.ts — the `crtr web` realtime push lane.
+//
+// ONE server-sent-events stream, `GET /__crtr/events`, that carries change
+// invalidations — never data. The shell and built-in views subscribe and, on an
+// event, re-pull through their existing bridge reads instead of waiting on a
+// fixed poll tick. SSE carries "something in this class changed"; the consumer
+// decides what to re-read.
+//
+// Event vocabulary (deliberately minimal): { kind: 'nodes' | 'inbox', ts }.
+//   - 'nodes' — the node graph changed (topology, status/intent transitions,
+//     naming). Source: canvas.db (+ its WAL sidecar) mtime. Every transition()
+//     and canvas mutation writes the WAL, so a watch on the home dir's
+//     `canvas.db*` files detects all of them with one cheap watcher.
+//   - 'inbox' — a node's inbox.jsonl gained a message. Source: a recursive watch
+//     on the nodes/ tree, filtered to `inbox.jsonl` writes.
+//
+// WHY these sources: they are the cheapest things that detect node-graph +
+// inbox changes without a daemon hook or a db trigger — pure fs.watch on the
+// two on-disk authorities (canvas.db for the graph, inbox.jsonl for messages).
+import { watch } from 'node:fs';
+import { crtrHome, nodesRoot, ensureHome } from '../../core/canvas/paths.js';
+/** Coalesce a burst of fs events into one emission per kind. WAL writes and
+ *  inbox appends arrive in clusters (a single transition can touch -wal/-shm);
+ *  a short trailing debounce collapses each cluster into a single invalidation,
+ *  which is all a re-pull consumer needs. */
+const DEBOUNCE_MS = 150;
+/** SSE keepalive comment cadence — keeps proxies/clients from idling the stream
+ *  shut. A bare `:` comment line is ignored by EventSource. */
+const HEARTBEAT_MS = 25_000;
+/** Start the change-event hub: open the two fs watchers once, fan their
+ *  debounced invalidations out to every connected SSE client. Watchers run for
+ *  the server's lifetime (cheap — two inotify/FSEvents registrations), not
+ *  per-client, so N browsers share one watch. */
+export function startEventHub() {
+    ensureHome();
+    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) {
+            try {
+                res.write(line);
+            }
+            catch {
+                /* 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.
+    const emit = (kind) => {
+        const existing = timers.get(kind);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        timers.set(kind, setTimeout(() => {
+            timers.delete(kind);
+            broadcast(kind);
+        }, DEBOUNCE_MS));
+    };
+    // Watcher 1 — the canvas home dir (non-recursive). canvas.db lives in WAL
+    // mode, so graph writes land in canvas.db-wal and checkpoints in canvas.db;
+    // watching the dir catches every `canvas.db*` sidecar touch → 'nodes'.
+    try {
+        const homeWatcher = watch(crtrHome(), (_event, filename) => {
+            if (filename !== null && filename.startsWith('canvas.db'))
+                emit('nodes');
+        });
+        homeWatcher.on('error', () => {
+            /* watch dropped (dir replaced) — non-fatal; the poll cadence still backs us */
+        });
+        watchers.push(homeWatcher);
+    }
+    catch {
+        /* fs.watch unavailable on this platform — degrade to poll-only (no SSE) */
+    }
+    // Watcher 2 — the nodes/ tree (recursive). An inbox.jsonl append is a message
+    // landing; a meta.json write is a graph/identity change (naming, polymorph).
+    // Recursive fs.watch is supported on macOS/Windows always and Linux ≥ v20.
+    try {
+        const nodesWatcher = watch(nodesRoot(), { recursive: true }, (_event, filename) => {
+            if (filename === null)
+                return;
+            if (filename.endsWith('inbox.jsonl'))
+                emit('inbox');
+            else if (filename.endsWith('meta.json'))
+                emit('nodes');
+        });
+        nodesWatcher.on('error', () => {
+            /* recursive watch refused/dropped — non-fatal */
+        });
+        watchers.push(nodesWatcher);
+    }
+    catch {
+        /* recursive watch unsupported — inbox push degrades to poll-only */
+    }
+    const heartbeat = setInterval(() => {
+        for (const res of clients) {
+            try {
+                res.write(': ping\n\n');
+            }
+            catch {
+                /* reaped by its 'close' handler */
+            }
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        addClient(res) {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                // The browser EventSource is same-origin here; no CORS header needed.
+            });
+            // An initial comment flushes headers and confirms the stream is open.
+            res.write(': connected\n\n');
+            clients.add(res);
+            const drop = () => {
+                clients.delete(res);
+            };
+            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())
+                clearTimeout(t);
+            timers.clear();
+            for (const w of watchers) {
+                try {
+                    w.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            for (const res of clients) {
+                try {
+                    res.end();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            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 gates the /v1 proxy).
+     *  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;
+    }
+}

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

@@ -0,0 +1,89 @@
+import type { NodeLifeStatus } from './web-client/shared/protocol.js';
+export interface PushPreferences {
+    doneNotifications: boolean;
+}
+export interface PushSubscriptionRecord {
+    id: string;
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    authScope: string;
+    createdAt: number;
+    lastSeenAt: number;
+    prefs: PushPreferences;
+}
+export interface PushRegistryFile {
+    schemaVersion: number;
+    records: PushSubscriptionRecord[];
+}
+export interface PushLastSeenRootState {
+    status: NodeLifeStatus;
+    attention_count: number;
+}
+export interface PushLastSeenAskState {
+    present: boolean;
+}
+export interface PushLastSeenFile {
+    schemaVersion: number;
+    updatedAt: number;
+    roots: Record<string, PushLastSeenRootState>;
+    asks: Record<string, PushLastSeenAskState>;
+}
+/** A locally generated VAPID keypair, persisted so the same identity signs
+ *  every outbound push across restarts. The private key never leaves this
+ *  file/process — only `publicKey` is ever served to a client. */
+export interface VapidKeypairFile {
+    schemaVersion: number;
+    publicKey: string;
+    privateKey: string;
+    subject: string;
+}
+export declare class PushRequestError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare function registryPath(): string;
+export declare function lastSeenPath(): string;
+export declare function vapidPath(): string;
+export declare function pushBodyMaxBytes(): number;
+/** Re-checkable at any later point (e.g. immediately before an outbound send,
+ *  not just at subscribe time) with no dependency on DNS resolution — the
+ *  allowlist match is a pure string check, so there is nothing to TOCTOU. */
+export declare function isAllowedPushEndpoint(endpoint: string): boolean;
+export declare function normalizeEndpoint(endpoint: unknown): string;
+export declare function subscriptionIdForEndpoint(endpoint: string): string;
+export declare function parsePushSubscriptionBody(rawBody: string, authScope: string, now?: number): PushSubscriptionRecord;
+export declare function parsePushDeleteBody(rawBody: string): {
+    endpoint: string;
+};
+/** Load the persisted VAPID keypair, generating and persisting a fresh one on
+ *  first run. One keypair per server identity (design D8/push contract) —
+ *  every subscription is signed with the same public key for the life of this
+ *  `crtrHome()`. The private key never leaves this file/process. */
+export declare function loadOrCreateVapidKeypair(path?: string, subject?: string): VapidKeypairFile;
+export declare class PushRegistryStore {
+    private readonly path;
+    private state;
+    private readonly byId;
+    constructor(path?: string);
+    snapshot(): PushSubscriptionRecord[];
+    listByScope(authScope: string): PushSubscriptionRecord[];
+    upsert(record: PushSubscriptionRecord): PushSubscriptionRecord;
+    touchById(id: string, lastSeenAt: number): PushSubscriptionRecord | null;
+    /** Scoped delete for the HTTP DELETE verb: a caller may only remove a
+     *  subscription it owns (its authScope matches the stored record's). Pruning a
+     *  service-reported-gone endpoint is a separate, unscoped path (`deleteById`). */
+    deleteByEndpoint(endpoint: string, authScope: string): boolean;
+    deleteById(id: string): boolean;
+    private persist;
+}
+export declare class PushLastSeenStore {
+    private readonly path;
+    private state;
+    constructor(path?: string);
+    snapshot(): PushLastSeenFile;
+    replace(next: PushLastSeenFile): void;
+    private persist;
+}