@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/surfaces/host.d.ts

@@ -0,0 +1,66 @@
+import type { Component } from '@earendil-works/pi-tui';
+/**
+ * A surface root: a pi-tui component rendered inside a host-assigned rectangle.
+ * The host pushes the rectangle height before every render and on resize; a
+ * surface must render exactly that many rows and must not read terminal or
+ * process geometry itself. A surface must never place its cursor marker on row
+ * 0, which is reserved for host notices.
+ */
+export interface SurfaceComponent extends Component {
+    /** Set the number of rows assigned by the host for the next render. */
+    setRows(rows: number): void;
+    /** Consume wheel input at the terminal's 1-based column, when applicable. */
+    handleWheel?(direction: 'up' | 'down', lines: number, column: number): boolean;
+}
+/** The identities used for mounted Phase 3 surfaces. */
+export type SurfaceId = 'inbox' | 'review';
+/**
+ * The only host boundary available to a surface. Surfaces render only through
+ * the mounted component and use {@link notice} as their only output channel;
+ * they never write to the terminal, stdout, stderr, or raw input themselves.
+ */
+export interface SurfaceHost {
+    /**
+     * Mount a component into the host-assigned full rectangle. When the focused
+     * input component differs from the rendered root, pass it as `focus` so
+     * input and cursor ownership remain with that component.
+     */
+    mount(component: SurfaceComponent, opts?: {
+        focus?: Component;
+    }): SurfaceHandle;
+    /** Report transient output through the host; this is the only surface output channel. */
+    notice(text: string): void;
+    /**
+     * Temporarily release the terminal for a child process and return a resume
+     * closure. Callers must invoke the closure in a `finally` block.
+     */
+    suspendForChild(): () => void;
+    /** Bring a node's viewer to the front; failures are reported through notice and never reject. */
+    focusNode(nodeId: string): Promise<boolean>;
+    /** Mount the shared review-file picker and resolve to its chosen path or null on cancellation. */
+    pickReviewFile(spec: {
+        candidates: readonly string[];
+        cwd: string;
+        title?: string;
+    }): Promise<string | null>;
+    /** Capability facts resolved once by the host for this session. */
+    readonly capabilities: {
+        /** True when this viewer is attached to a remote session. */
+        readonly remote: boolean;
+        /** True when focusing another node's viewer is available. */
+        readonly canFocusNode: boolean;
+    };
+}
+/** A mounted surface's lifecycle controls. */
+export interface SurfaceHandle {
+    /** Close this surface and any surfaces mounted above it. Idempotent. */
+    close(): void;
+    /** Mark the surface dirty; the host schedules a redraw rather than drawing synchronously. */
+    invalidate(): void;
+    /**
+     * Register the only sanctioned teardown hook for timers, watchers, listeners,
+     * and poll re-arms. Closing initiates both synchronous and asynchronous
+     * cleanup; asynchronous cleanup is not awaited by the host.
+     */
+    onClose(fn: () => void | Promise<void>): void;
+}

package/dist/clients/surfaces/host.js

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

package/dist/clients/surfaces/region.d.ts

@@ -0,0 +1,16 @@
+export interface SurfaceRegion {
+    /** Geometry is PUSHED. A region never reads terminal or process geometry. */
+    setViewport(cols: number, rows: number): void;
+    /** Exactly `rows` lines, each ≤ `cols` display cells. */
+    render(): string[];
+    /** True when the chunk was consumed. Unconsumed chunks are DROPPED, never re-offered. */
+    handleInput(data: string): boolean;
+    handleWheel(direction: 'up' | 'down', lines: number): boolean;
+    /** Only a focused region may emit CURSOR_MARKER. */
+    setFocused(value: boolean): void;
+    /** One line of state for the composition's status row. */
+    summary(): string;
+    /** The region's ONLY repaint channel. */
+    onDirty(fn: () => void): void;
+    close(): void;
+}

package/dist/clients/surfaces/region.js

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

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

@@ -14,9 +14,6 @@ function makeStores(dir) {
         lastSeen: new PushLastSeenStore(join(dir, 'last-seen.json')),
     };
 }
-// 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 (see push-registry.ts's PUSH_SERVICE_HOST_ALLOWLIST).
 function fakeSubscription(id, authScope = 'local') {
     return {
         id,
@@ -28,17 +25,11 @@ function fakeSubscription(id, authScope = 'local') {
         prefs: { doneNotifications: true },
     };
 }
-/** Seed a registry with one subscription directly (bypassing HTTP validation,
- *  which is covered in push-registry.test.ts). */
-function seedRegistryWithOneSubscription(registry) {
-    registry.upsert(fakeSubscription('sub-1'));
-}
 function buildHarness(dir, opts = {}) {
     const { registry, lastSeen } = makeStores(dir);
     const sent = [];
     const sentTo = [];
     const nodes = [];
-    const asks = [];
     const clock = { now: 1_000_000 };
     const defaultSend = async (record, payload) => {
         sent.push(payload);
@@ -49,26 +40,25 @@ function buildHarness(dir, opts = {}) {
         registry,
         lastSeen,
         readCanvasNodes: () => nodes,
-        readPendingAsks: () => asks,
         sendPush: opts.sendPush ?? defaultSend,
         isTargetScope: opts.isTargetScope ?? (() => true),
         now: () => clock.now,
         rateWindowMs: opts.rateWindowMs,
     });
-    return { engine, sent, sentTo, registry, lastSeen, nodes, asks, clock };
+    return { engine, sent, sentTo, registry, lastSeen, nodes, clock };
 }
-test('seed() sends nothing regardless of current state (no restart storm)', async () => {
+function seedRegistryWithOneSubscription(registry) {
+    registry.upsert(fakeSubscription('sub-1'));
+}
+test('seed() sends nothing regardless of current state', async () => {
     const dir = tmpDir();
     try {
         const h = buildHarness(dir);
         seedRegistryWithOneSubscription(h.registry);
         h.nodes.push({ node_id: 'root-1', parent: null, status: 'done', attention_count: 0 });
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
         await h.engine.seed();
         assert.equal(h.sent.length, 0);
-        const snap = h.lastSeen.snapshot();
-        assert.deepEqual(snap.roots['root-1'], { status: 'done', attention_count: 0 });
-        assert.deepEqual(snap.asks['ask-1'], { present: true });
+        assert.deepEqual(h.lastSeen.snapshot().roots['root-1'], { status: 'done', attention_count: 0 });
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -81,13 +71,11 @@ test('active -> done emits exactly one done push, and a repeat pass does not dup
         seedRegistryWithOneSubscription(h.registry);
         h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
         await h.engine.seed();
-        assert.equal(h.sent.length, 0);
         h.nodes[0].status = 'done';
         await h.engine.onNodesInvalidation();
         assert.equal(h.sent.length, 1);
         assert.equal(h.sent[0].kind, 'done');
         assert.equal(h.sent[0].conversationId, 'root-1');
-        // Repeated invalidation with the same (already-done) status must not re-fire.
         await h.engine.onNodesInvalidation();
         assert.equal(h.sent.length, 1);
     }
@@ -95,71 +83,16 @@ test('active -> done emits exactly one done push, and a repeat pass does not dup
         rmSync(dir, { recursive: true, force: true });
     }
 });
-test('a new ask emits exactly one needs-you push, and repeated invalidations do not duplicate it', async () => {
-    const dir = tmpDir();
-    try {
-        const h = buildHarness(dir);
-        seedRegistryWithOneSubscription(h.registry);
-        await h.engine.seed(); // no asks yet
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1);
-        assert.equal(h.sent[0].kind, 'needs-you');
-        assert.equal(h.sent[0].askId, 'job-1');
-        // Same ask still pending on a second invalidation — no duplicate.
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});
-test('a resolved/missing ask never notifies', async () => {
+test('push targeting is scope-filtered', async () => {
     const dir = tmpDir();
     try {
-        const h = buildHarness(dir);
-        seedRegistryWithOneSubscription(h.registry);
-        await h.engine.seed();
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1);
-        // The ask resolves — it disappears from the pending list.
-        h.asks.length = 0;
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1); // no new push
-        assert.deepEqual(h.lastSeen.snapshot().asks, {});
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});
-test('multiple new asks in the same conversation within the rate window coalesce into one push', async () => {
-    const dir = tmpDir();
-    try {
-        const h = buildHarness(dir, { rateWindowMs: 30_000 });
-        seedRegistryWithOneSubscription(h.registry);
-        await h.engine.seed();
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' }, { id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:01.000Z' });
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1);
-        assert.match(h.sent[0].snippet, /\+1 more/);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});
-test('push targeting is scope-filtered: only subscriptions on the watched auth boundary are sent to', async () => {
-    const dir = tmpDir();
-    try {
-        const h = buildHarness(dir, { isTargetScope: (s) => s === 'token:abc' });
-        // One local-scope sub and one token-scope sub in the SAME registry.
+        const h = buildHarness(dir, { isTargetScope: (scope) => scope === 'token:abc' });
         h.registry.upsert(fakeSubscription('sub-local', 'local'));
         h.registry.upsert(fakeSubscription('sub-token', 'token:abc'));
         h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
         await h.engine.seed();
         h.nodes[0].status = 'done';
         await h.engine.onNodesInvalidation();
-        // Exactly one send, and it went to the token-scoped endpoint only.
         assert.equal(h.sent.length, 1);
         assert.deepEqual(h.sentTo, ['https://fcm.googleapis.com/fcm/send/sub-token']);
     }
@@ -174,7 +107,7 @@ test('a transient send failure does not advance last-seen and is retried next pa
         const attempts = [];
         const h = buildHarness(dir, {
             rateWindowMs: 30_000,
-            sendPush: async (_r, payload) => {
+            sendPush: async (_record, payload) => {
                 attempts.push(payload);
                 call += 1;
                 return call === 1 ? 'error' : 'sent';
@@ -185,40 +118,27 @@ test('a transient send failure does not advance last-seen and is retried next pa
         await h.engine.seed();
         h.nodes[0].status = 'done';
         await h.engine.onNodesInvalidation();
-        // The send was attempted but failed transiently — last-seen root must stay
-        // pre-transition ('active') so the edge is re-detected next pass.
         assert.equal(attempts.length, 1);
         assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'active');
-        // Advance past the rate window (the failed pass set lastPushAt) and retry.
         h.clock.now += 60_000;
         await h.engine.onNodesInvalidation();
         assert.equal(attempts.length, 2);
         assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'done');
-        // A further pass does not re-fire.
-        h.clock.now += 60_000;
-        await h.engine.onNodesInvalidation();
-        assert.equal(attempts.length, 2);
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
     }
 });
-test('a transient failure on one subscription does not cause a retry to re-send to an already-delivered subscription', async () => {
+test('a transient failure on one subscription does not re-send to an already-delivered subscription', async () => {
     const dir = tmpDir();
     try {
-        // Keyed by endpoint, not `record.id` — upsert() derives the persisted id
-        // from `subscriptionIdForEndpoint(endpoint)`, discarding the fixture's
-        // caller-supplied id, so the endpoint is the stable fixture identity here.
         const attemptsBySub = new Map();
         const h = buildHarness(dir, {
             rateWindowMs: 30_000,
-            sendPush: async (record, _payload) => {
-                const n = (attemptsBySub.get(record.endpoint) ?? 0) + 1;
-                attemptsBySub.set(record.endpoint, n);
-                // sub-ok always succeeds; sub-fail fails transiently on its first
-                // attempt only, then succeeds on retry — so the second pass proves
-                // sub-ok is never touched again while sub-fail finally lands.
-                return record.endpoint.includes('sub-fail') && n === 1 ? 'error' : 'sent';
+            sendPush: async (record) => {
+                const attempts = (attemptsBySub.get(record.endpoint) ?? 0) + 1;
+                attemptsBySub.set(record.endpoint, attempts);
+                return record.endpoint.includes('sub-fail') && attempts === 1 ? 'error' : 'sent';
             },
         });
         h.registry.upsert(fakeSubscription('sub-ok'));
@@ -227,19 +147,6 @@ test('a transient failure on one subscription does not cause a retry to re-send
         await h.engine.seed();
         h.nodes[0].status = 'done';
         await h.engine.onNodesInvalidation();
-        // Both subscriptions were attempted once; the event is not fully delivered
-        // (sub-fail errored), so last-seen must stay pre-transition.
-        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1);
-        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-fail'), 1);
-        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'active');
-        // Retry next pass (past the rate window): sub-ok must NOT be re-sent to —
-        // only sub-fail, which never succeeded, is retried.
-        h.clock.now += 60_000;
-        await h.engine.onNodesInvalidation();
-        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1, 'an already-delivered subscription must not be re-sent to on retry');
-        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-fail'), 2);
-        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'done');
-        // Fully delivered now — a further pass does not re-fire for anyone.
         h.clock.now += 60_000;
         await h.engine.onNodesInvalidation();
         assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1);
@@ -249,54 +156,3 @@ test('a transient failure on one subscription does not cause a retry to re-send
         rmSync(dir, { recursive: true, force: true });
     }
 });
-test('overlapping inbox invalidations serialize — each distinct ask notifies exactly once', async () => {
-    const dir = tmpDir();
-    try {
-        const h = buildHarness(dir);
-        seedRegistryWithOneSubscription(h.registry);
-        await h.engine.seed();
-        // First invalidation kicked off but NOT awaited; a second ask + invalidation
-        // land while the first pass is in-flight. The drain queue must serialize
-        // them so neither ask is notified twice.
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
-        const p1 = h.engine.onInboxInvalidation();
-        h.asks.push({ id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-2', conversationTitle: 'Root Two', blockedSince: '2026-01-01T00:00:01.000Z' });
-        const p2 = h.engine.onInboxInvalidation();
-        await Promise.all([p1, p2]);
-        const askIds = h.sent.map((p) => p.askId).sort();
-        assert.deepEqual(askIds, ['job-1', 'job-2']);
-        assert.deepEqual(Object.keys(h.lastSeen.snapshot().asks).sort(), ['ask-1', 'ask-2']);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});
-test('a rate-capped ask is suppressed within the window then retried once it clears — never lost, never duplicated', async () => {
-    const dir = tmpDir();
-    try {
-        const h = buildHarness(dir, { rateWindowMs: 30_000 });
-        seedRegistryWithOneSubscription(h.registry);
-        await h.engine.seed();
-        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1); // first ask fires immediately
-        // A second, distinct ask lands in the same conversation moments later —
-        // still inside the rate window, so it must be suppressed, not sent.
-        h.asks.push({ id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:05.000Z' });
-        h.clock.now += 5_000;
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 1); // still suppressed
-        assert.equal(h.lastSeen.snapshot().asks['ask-2'], undefined); // left untracked so it retries
-        // Once the rate window clears, the still-pending ask-2 is retried exactly once.
-        h.clock.now += 30_000;
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 2);
-        assert.equal(h.sent[1].askId, 'job-2');
-        // And it never fires a third time on a further no-op pass.
-        await h.engine.onInboxInvalidation();
-        assert.equal(h.sent.length, 2);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-});

package/dist/clients/web/dev-server.d.ts

@@ -1,7 +1,7 @@
 import type { Server as HttpServer } from 'node:http';
 import type { ViteDevServer } from 'vite';
 /** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
- *  Mirrors the old `view serve` resolve setup so the shell's bare imports
- *  (react, the `@north-light/crouter/web` self-subpath) resolve from the
- *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+ *  It loads the shell's Vite config rather than duplicating its plugins: that
+ *  config supplies the PWA virtual-module resolver as well as the production
+ *  build settings. Lazily imports vite so the shipped path never loads it. */
 export declare function createDevServer(httpServer: HttpServer): Promise<ViteDevServer>;

package/dist/clients/web/dev-server.js

@@ -1,8 +1,8 @@
 // dev-server.ts — `crtr web serve --dev` Vite middleware mode.
 //
 // The shipped server serves a prebuilt static shell bundle from dist/web-client/
-// (§11). In --dev a contributor iterating on the shell or a builtin view gets
-// HMR instead: a Vite dev server in MIDDLEWARE mode mounted on the SAME HTTP
+// (§11). In --dev a contributor iterating on the shell gets HMR instead: a Vite
+// dev server in MIDDLEWARE mode mounted on the SAME HTTP
 // server as the crtrd proxy + attach tunnel. This is the one place Vite runs at
 // runtime — the mainstream "Vite middleware in dev, static dist in prod" split.
 //
@@ -22,32 +22,18 @@ function resolveShellRoot(packageRoot) {
     return join(packageRoot, 'src', 'clients', 'web', 'web-client');
 }
 /** Create a Vite dev server in middleware mode, HMR bound to `httpServer`.
- *  Mirrors the old `view serve` resolve setup so the shell's bare imports
- *  (react, the `@north-light/crouter/web` self-subpath) resolve from the
- *  generated/shell root. Lazily imports vite so the shipped path never loads it. */
+ *  It loads the shell's Vite config rather than duplicating its plugins: that
+ *  config supplies the PWA virtual-module resolver as well as the production
+ *  build settings. Lazily imports vite so the shipped path never loads it. */
 export async function createDevServer(httpServer) {
     const packageRoot = resolve(HERE, '../../..');
-    const nodeModules = join(packageRoot, 'node_modules');
     const shellRoot = resolveShellRoot(packageRoot);
     const { createServer } = await import('vite');
-    const react = (await import('@vitejs/plugin-react')).default;
-    const tailwindcss = (await import('@tailwindcss/vite')).default;
     return createServer({
-        configFile: false,
-        root: shellRoot,
-        plugins: [react(), tailwindcss()],
-        appType: 'spa',
-        resolve: {
-            alias: {
-                react: join(nodeModules, 'react'),
-                'react-dom': join(nodeModules, 'react-dom'),
-                '@': shellRoot,
-                // The crtr web runtime is a self-subpath of crouter's own package;
-                // pin it to the built barrel so the shell can import it from any root.
-                '@north-light/crouter/web': join(packageRoot, 'dist', 'web', 'index.js'),
-            },
-            dedupe: ['react', 'react-dom'],
-        },
+        configFile: join(shellRoot, 'vite.config.ts'),
+        // The integrated middleware already owns /node, /v1, and /__crtr. The
+        // shell config uses this mode to omit its standalone-server proxies.
+        mode: 'middleware',
         server: {
             middlewareMode: true,
             // Share our HTTP server for HMR; server.ts's upgrade handler hands every

package/dist/clients/web/events.js

@@ -1,10 +1,8 @@
-// events.ts — the `crtr web` realtime push lane.
+// events.ts — the browser shell's realtime invalidation 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.
+// One server-sent-events stream, `GET /__crtr/events`, carries change
+// invalidations, never data. On an event the shell re-reads through the REST
+// proxy rather than waiting for its fixed polling interval.
 //
 // Event vocabulary (deliberately minimal): { kind: 'nodes' | 'inbox', ts }.
 //   - 'nodes' — the node graph changed (topology, status/intent transitions,

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

@@ -1,49 +1,23 @@
 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;
+    kind: 'done';
     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;
@@ -52,57 +26,19 @@ 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. */
+    /** Record the current canvas state without sending notifications. */
     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;
 }