@elvisw/dsh-magic-context 0.0.0-stage → 0.14.0

package/lib/core/profile-write.js

@@ -0,0 +1,283 @@
+/**
+ * WP5 — the `user` domain's COLLECTION half: historian observations →
+ * Magic Context's `user_memory_candidates`.
+ *
+ * Why a separate writer from `memory-write.ts`: candidates are not memories.
+ * They are the staging pool a review pass later promotes into `user_memories`,
+ * and MC keeps them in their own table with their own lifetime. Sharing the
+ * memory writer's connection would couple two different fences (this one needs
+ * the candidate table, the memory one needs `memories`), so it gets its own
+ * open/probe/fence sequence — the same three steps, its own table.
+ *
+ * Deliberate properties, each with a reason:
+ *
+ *  - **fail-open.** A candidate that cannot be written is a missed opportunity,
+ *    never a failure of the turn: the caller journals and continues. The
+ *    compartment is already durable when this runs.
+ *  - **fail-CLOSED on a newer contract.** If `context.db` is ahead of the
+ *    version this adapter understands, the column layout of the candidate table
+ *    is unknown, so the writer refuses instead of writing a guessed row. Same
+ *    fence as `memory-write.ts`.
+ *  - **the table is optional.** Older contracts (and every synthetic fixture
+ *    that does not care about the profile lane) lack it; that is not an error,
+ *    it is a lane that does not exist yet.
+ *  - **no dedup across passes, dedup inside one.** MC's requirement for a
+ *    promoted profile fact is cross-session RECURRENCE, so the same observation
+ *    arriving in a later compartment is the evidence, not noise. Within a single
+ *    batch a repeat is just the model saying the same thing twice.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync } from 'node:fs';
+import { MEMORY_SCHEMA_MAX_VERSION } from "./memory-bridge.js";
+import { errText } from "./types.js";
+/** Anything longer is truncated: a runaway observation must not become a row. */
+export const MAX_OBSERVATION_CHARS = 600;
+/**
+ * Trim, drop empties and duplicates, and bound the length. Pure, so the rules
+ * are testable without a database; the truncation is silent by design (a long
+ * observation is still a useful candidate, just a bounded one) and the count of
+ * what was dropped is reported to the caller for the journal.
+ */
+export function normalizeObservations(observations) {
+    const kept = [];
+    const seen = new Set();
+    let skipped = 0;
+    for (const raw of observations) {
+        if (typeof raw !== 'string') {
+            skipped += 1;
+            continue;
+        }
+        const trimmed = raw.trim();
+        if (trimmed === '' || seen.has(trimmed)) {
+            skipped += 1;
+            continue;
+        }
+        seen.add(trimmed);
+        kept.push(trimmed.length > MAX_OBSERVATION_CHARS ? trimmed.slice(0, MAX_OBSERVATION_CHARS) : trimmed);
+    }
+    return { kept, skipped };
+}
+const INSERT_CANDIDATE = `
+  INSERT INTO user_memory_candidates(
+    content, session_id, source_compartment_start, source_compartment_end, created_at
+  ) VALUES(?, ?, ?, ?, ?)
+`;
+const SELECT_CANDIDATES = `
+  SELECT id, content, session_id AS sessionId,
+         source_compartment_start AS compartmentStart,
+         source_compartment_end AS compartmentEnd,
+         created_at AS createdAt
+    FROM user_memory_candidates
+   ORDER BY created_at ASC, id ASC
+   LIMIT ?
+`;
+/**
+ * Promotion (WP7). `status` is written explicitly rather than left to the
+ * column default: the render lane reads `status = 'active'`, and a profile row
+ * that arrives with any other value would be invisible while looking written.
+ */
+const INSERT_PROFILE = `
+  INSERT INTO user_memories(
+    content, status, promoted_at, source_candidate_ids, created_at, updated_at,
+    source_candidate_provenance
+  ) VALUES(?, 'active', ?, ?, ?, ?, ?)
+`;
+const SELECT_PROFILES = `
+  SELECT id, content, promoted_at AS promotedAt,
+         source_candidate_ids AS sourceCandidateIds
+    FROM user_memories
+   WHERE status = 'active'
+   ORDER BY promoted_at ASC, id ASC
+`;
+export function openProfileWriter(options) {
+    const now = options.now ?? Date.now;
+    const unavailable = (detail) => {
+        options.logger.warn(`magic-context profile writer disabled: ${detail} (${options.dbPath})`);
+        return {
+            dbPath: options.dbPath,
+            status: { ok: false, detail },
+            recordCandidates: () => ({ inserted: 0, skipped: 0 }),
+            listCandidates: () => [],
+            countCandidates: () => 0,
+            expireCandidates: () => 0,
+            deleteCandidates: () => 0,
+            listActiveProfiles: () => [],
+            retireProfile: () => false,
+            promoteProfile: () => undefined,
+            close: () => undefined,
+        };
+    };
+    if (!existsSync(options.dbPath))
+        return unavailable('database not found');
+    let db;
+    try {
+        db = new DatabaseSync(options.dbPath);
+        // Same order as the memory writer (contract §10.1): the busy timeout must
+        // precede WAL, because acquiring the mode itself can need the lock.
+        db.exec(`PRAGMA busy_timeout = ${String(options.busyTimeoutMs ?? 5_000)}`);
+        db.exec('PRAGMA journal_mode = WAL');
+    }
+    catch (error) {
+        return unavailable(`cannot open (${errText(error)})`);
+    }
+    try {
+        const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all()
+            .map(row => row.name));
+        if (!tables.has('user_memory_candidates')) {
+            db.close();
+            return unavailable('user_memory_candidates table missing');
+        }
+        const row = db.prepare('SELECT MAX(version) AS version FROM schema_migrations WHERE version < 10000').get();
+        const version = row?.version ?? null;
+        if (version !== null && version > MEMORY_SCHEMA_MAX_VERSION) {
+            db.close();
+            return unavailable(`corpus version ${String(version)} is newer than this adapter understands (${String(MEMORY_SCHEMA_MAX_VERSION)})`);
+        }
+    }
+    catch (error) {
+        db.close();
+        return unavailable(`contract probe failed (${errText(error)})`);
+    }
+    const insert = db.prepare(INSERT_CANDIDATE);
+    const selectCandidates = db.prepare(SELECT_CANDIDATES);
+    const countCandidates = db.prepare('SELECT COUNT(*) AS c FROM user_memory_candidates');
+    const deleteCandidate = db.prepare('DELETE FROM user_memory_candidates WHERE id = ?');
+    const expireCandidates = db.prepare('DELETE FROM user_memory_candidates WHERE created_at < ?');
+    const insertProfile = db.prepare(INSERT_PROFILE);
+    const selectProfiles = db.prepare(SELECT_PROFILES);
+    const retireProfileStatement = db.prepare("UPDATE user_memories SET status = 'dismissed', updated_at = ? WHERE id = ? AND status = 'active'");
+    /** Run `fn` inside BEGIN IMMEDIATE, rolling back on any throw. */
+    const inTransaction = (fn) => {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                /* the transaction may already be gone */
+            }
+            throw error;
+        }
+    };
+    return {
+        dbPath: options.dbPath,
+        status: { ok: true },
+        recordCandidates: (input) => {
+            const { kept, skipped } = normalizeObservations(input.observations);
+            if (kept.length === 0)
+                return { inserted: 0, skipped };
+            const timestamp = now();
+            const start = input.compartmentStart ?? null;
+            const end = input.compartmentEnd ?? null;
+            try {
+                inTransaction(() => {
+                    for (const content of kept) {
+                        insert.run(content, input.sessionId, start, end, timestamp);
+                    }
+                });
+                return { inserted: kept.length, skipped };
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile candidate write failed: ${errText(error)}`);
+                return { inserted: 0, skipped };
+            }
+        },
+        listCandidates: (limit) => {
+            if (!Number.isFinite(limit) || limit <= 0)
+                return [];
+            try {
+                return selectCandidates.all(limit);
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile candidate read failed: ${errText(error)}`);
+                return [];
+            }
+        },
+        countCandidates: () => {
+            try {
+                return countCandidates.get()?.c ?? 0;
+            }
+            catch {
+                return 0;
+            }
+        },
+        expireCandidates: (cutoffMs) => {
+            try {
+                return Number(expireCandidates.run(cutoffMs).changes);
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile candidate expiry failed: ${errText(error)}`);
+                return 0;
+            }
+        },
+        deleteCandidates: (ids) => {
+            if (ids.length === 0)
+                return 0;
+            try {
+                return inTransaction(() => {
+                    let removed = 0;
+                    for (const id of ids)
+                        removed += Number(deleteCandidate.run(id).changes);
+                    return removed;
+                });
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile candidate consumption failed: ${errText(error)}`);
+                return 0;
+            }
+        },
+        listActiveProfiles: () => {
+            try {
+                return selectProfiles.all().map((row) => {
+                    let ids = [];
+                    try {
+                        const parsed = JSON.parse(row.sourceCandidateIds ?? '[]');
+                        if (Array.isArray(parsed))
+                            ids = parsed.filter((id) => typeof id === 'number');
+                    }
+                    catch {
+                        // A malformed provenance list is not worth failing a read over.
+                    }
+                    return { id: row.id, content: row.content, promotedAt: row.promotedAt, sourceCandidateIds: ids };
+                });
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile read failed: ${errText(error)}`);
+                return [];
+            }
+        },
+        retireProfile: (id, nowMs) => {
+            try {
+                return Number(retireProfileStatement.run(nowMs, id).changes) === 1;
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile retirement failed: ${errText(error)}`);
+                return false;
+            }
+        },
+        promoteProfile: (input) => {
+            const content = input.content.trim();
+            if (content === '')
+                return undefined;
+            const timestamp = now();
+            try {
+                return inTransaction(() => {
+                    const result = insertProfile.run(content, input.promotedAt, JSON.stringify([...input.candidateIds]), timestamp, timestamp, input.provenance ?? null);
+                    return Number(result.lastInsertRowid);
+                });
+            }
+            catch (error) {
+                options.logger.warn(`magic-context profile promotion failed: ${errText(error)}`);
+                return undefined;
+            }
+        },
+        close: () => {
+            db.close();
+        },
+    };
+}

package/lib/core/reference-seeds.js

@@ -0,0 +1,63 @@
+/** Highest score first: the scale runs from here down to the trivial spans. */
+export const REFERENCE_ANCHORS = [
+    { importance: 96, title: "Fail-closed tenant context", episodeType: "design,feature", gist: "Acorn Suite made JWT tenant_id the single tenant authority across REST, GraphQL, and Prisma; slug/h…" },
+    { importance: 95, title: "Chorus: op-log-as-source-of-truth architecture established", episodeType: "design,infra", gist: "Chorus op log is the source of truth; snapshots derived on-read and cached; compaction at 10 k ops/…" },
+    { importance: 95, title: "Standby-safe status writer", episodeType: "design,infra,feature", gist: "The durable decision was to allow standby replicas to do read-heavy reconcile work while centralizi…" },
+    { importance: 94, title: "Tenant isolation: chose Postgres RLS over schema-per-tenant", episodeType: "design", gist: "Chose RLS with `tenant_id` and `SET LOCAL app.current_tenant` per request. BYPASSRLS reserved for t…" },
+    { importance: 92, title: "Tenant context from membership", episodeType: "design,feature", gist: "Tenant authorization now flows from membership state rather than browser-selected tenant IDs. The d…" },
+    { importance: 91, title: "Leader election thrash from leases held across pod terminations", episodeType: "investigation,bug,refactor", gist: "Operator leader-election bug: custom shutdown-error suppression shim swallowed lease releases, leav…" },
+    { importance: 91, title: "Luminary: run_id idempotency model established for all pipeline runs", episodeType: "design,feature", gist: "All Luminary ETL loads idempotent via run_id; DB-enforced deduplication; any run can be safely retr…" },
+    { importance: 91, title: "Per-namespace QueueShard leases", episodeType: "design,infra,feature", gist: "Harborlight sharding is namespace-scoped: one operator binary can run cluster-wide, but failover is…" },
+    { importance: 88, title: "Moved CAN notify out of ISR", episodeType: "bug,infra", gist: "CAN RX no longer allocates or sends BLE notifications inside the ISR; frames are buffered and flush…" },
+    { importance: 87, title: "NaN in mixed-precision training traced to clip_grad_norm_ before scaler.unscale_", episodeType: "investigation,bug", gist: "Mixed-precision NaN root cause: gradient clipping must run after the GradScaler unscale, never befo…" },
+    { importance: 86, title: "CRDT merge ordering: hybrid logical clocks over wall-clock LWW", episodeType: "design,feature", gist: "Conflict resolution is HLC-based with a 300s skew cap; per-character editing uses Yjs." },
+    { importance: 86, title: "Auditable proration credit ledger", episodeType: "design,feature,release", gist: "Billetto made proration credits auditable by storing them in its own ledger table rather than Strip…" },
+    { importance: 82, title: "Stopped contrastive loss cliff", episodeType: "investigation,bug", gist: "Nereid contrastive training stabilized after restoring per-worker augmentation seeds." },
+    { importance: 79, title: "Idempotency strategy for Stripe webhook handlers", episodeType: "design,bug", gist: "Stripe webhook idempotency keys on event.id with stored response replay; old signature-based dedup…" },
+    { importance: 78, title: "Tethys: JWT refresh not re-fetching tenant roles after role change", episodeType: "investigation,bug,refactor", gist: "Tethys token refresh now embeds freshly-fetched tenant_roles; revoked role lag bounded by access_to…" },
+    { importance: 74, title: "HLS segment numbering migration from 5-digit to 9-digit indices", episodeType: "refactor,infra", gist: "HLS segment indices widened after a live-channel index wraparound." },
+    { importance: 74, title: "Partition stats invalidation fence", episodeType: "investigation,bug", gist: "Partition membership changes now fence planner statistics through partition_epoch. The durable poin…" },
+    { importance: 72, title: "CRDT ordering by Lamport site", episodeType: "design,refactor,investigation", gist: "CollabPad CRDT ordering now follows document clocks rather than server receive time." },
+    { importance: 71, title: "BLE bonding records lost across firmware OTA — bond table erase fix", episodeType: "bug,feature", gist: "OTA was erasing the SDK bond table; carved a dedicated partition to protect it." },
+    { importance: 71, title: "Vesper: controller leader election via Kubernetes Lease", episodeType: "feature,infra", gist: "Vesper uses Lease-based leader election; only one replica reconciles at a time; handoff within one…" },
+    { importance: 68, title: "boltpkg: plugin lifecycle hook API design and documentation", episodeType: "design,docs", gist: "boltpkg plugin lifecycle uses explicit ordered hooks in dependency-declaration order; schema_versio…" },
+    { importance: 68, title: "Added subscription day fact table", episodeType: "feature,infra", gist: "Subscription MRR history moved into a daily fact table instead of being reconstructed from raw bill…" },
+    { importance: 67, title: "Matchmaking bucket calibration after season-3 player distribution shift", episodeType: "feature", gist: "Matchmaking buckets narrowed and bucket expansion made asymmetric to stop top-skill players from ge…" },
+    { importance: 61, title: "Preserved PDF rotation before OCR", episodeType: "investigation,bug", gist: "PDF page rotation is captured before OCR rasterization so Tesseract sees the correct orientation." },
+    { importance: 58, title: "Moved synonym rollout to shadow index", episodeType: "infra,refactor", gist: "Synonym edits are now shipped by building and promoting a shadow index, not by reloading the hot on…" },
+    { importance: 54, title: "Kept ranked parties intact", episodeType: "feature", gist: "Ranked duo matchmaking now preserves parties even when it increases queue time." },
+    { importance: 52, title: "Slowly-changing-dim fix in dim_customer dbt model", episodeType: "refactor,bug", gist: "Customer SCD moved from custom triggers to dbt snapshots." },
+    { importance: 48, title: "CSP nonce missing on injected MV3 content script", episodeType: "bug", gist: "Content script moved to the isolated world to sidestep page CSP." },
+    { importance: 46, title: "Tesseract pinned to 5.3.3 after multi-column regression in 5.3.4", episodeType: "bug,infra", gist: "Tesseract pinned to 5.3.3 due to a multi-column regression in 5.3.4." },
+    { importance: 41, title: "Added Snapbench record examples", episodeType: "feature,docs", gist: "Snapbench recording examples became runnable instead of descriptive only." },
+    { importance: 38, title: "Add --json output flag to status command", episodeType: "feature", gist: "Status command gained a `--json` output mode." },
+    { importance: 38, title: "Meridian: fix HLS segment pts discontinuity causing playback stutters", episodeType: "bug", gist: "HLS segment boundary pts continuity enforced; -copyts required in Meridian mux args." },
+    { importance: 36, title: "Statistics-refresh hook on bulk-load completion in query planner integration", episodeType: "feature,refactor", gist: "Bulk loader triggers asynchronous statistics refresh on large loads to keep the planner from pickin…" },
+    { importance: 36, title: "Removed Electron pane jitter", episodeType: "bug", gist: "Electron pane positioning was made stable under fractional display scaling." },
+    { importance: 33, title: "Polaris: extract dataset preprocessing into offline cached stage", episodeType: "refactor", gist: "Polaris has a separate preprocessing stage; training loop reads from data/preprocessed/ cache." },
+    { importance: 31, title: "SKU import defaults to preview", episodeType: "feature,docs", gist: "The SKU importer now defaults to a safe preview workflow instead of assuming live writes. The durab…" },
+    { importance: 29, title: "Routed malformed telemetry to DLQ", episodeType: "infra", gist: "Invalid IoT telemetry is retained in a DLQ instead of silently disappearing." },
+    { importance: 27, title: "Scoped mobile offline sync MVP", episodeType: "feature,design", gist: "Mobile offline sync shipped with a narrow notes-only scope." },
+    { importance: 27, title: "Manual page rotation escape hatch", episodeType: "feature,bug", gist: "Low-confidence scan rotation is now handled through a manual override path, with automation reserve…" },
+    { importance: 24, title: "Cut v2.4.1 patch release for the segment-wraparound fix", episodeType: "release", gist: "Patch release 2.4.1." },
+    { importance: 24, title: "Ferrite: write amplification spike investigation — inconclusive", episodeType: "investigation", gist: "Ferrite WA spike is expected LSM behavior during level merges; no fix needed; defaults appropriate." },
+    { importance: 22, title: "Narrowed May orders replay", episodeType: "infra,investigation", gist: "This was a scoped replay, not a lasting data-model change: the useful outcome was knowing the repai…" },
+    { importance: 21, title: "Collapsed package harness helpers", episodeType: "refactor", gist: "Package resolver test setup was deduplicated without behavior changes." },
+    { importance: 20, title: "README install path correction for darwin-arm64", episodeType: "docs", gist: "README install path fixed for Apple Silicon." },
+    { importance: 17, title: "Rename internal `bilUtil` helper to `invoiceMath`", episodeType: "refactor", gist: "Naming cleanup in the billing service." },
+    { importance: 14, title: "Inconclusive investigation into nightly training throughput drift", episodeType: "investigation", gist: "Inconclusive performance investigation, parked." },
+    { importance: 14, title: "Vesper: add kind cluster to CI integration test pipeline", episodeType: "infra", gist: "Vesper CI now runs integration tests against a real kind cluster instead of envtest mock." },
+    { importance: 12, title: "Dropped table-detector detour", episodeType: "investigation,docs", gist: "This was a discarded OCR detour: table detection did not improve enough documents to justify replac…" },
+    { importance: 9, title: "CLI nightly dry run", episodeType: "release", gist: "A CLI nightly dry run passed and left no artifacts." },
+    { importance: 8, title: "Tried replacing controller-runtime cache with informer-direct; reverted", episodeType: "refactor", gist: "False start: attempted-and-reverted controller-runtime cache bypass." },
+    { importance: 7, title: "Ledger: invoice_status column rename reversed after reporting breakage", episodeType: "bug", gist: "Column rename reverted; reporting service has raw SQL dependency on invoice_status that must be upd…" },
+    { importance: 7, title: "Discarded Percy baseline theory", episodeType: "investigation", gist: "A false Playwright/Percy lead was ruled out." },
+    { importance: 7, title: "Added --dry-run flag to transcode CLI", episodeType: "feature", gist: "Added dry-run mode to video transcode CLI." },
+    { importance: 7, title: "Upload button spacing", episodeType: "bug", gist: "Minor upload empty-state spacing tweak." },
+    { importance: 5, title: "Aborted feature flag tweak — wrong env", episodeType: "feature", gist: "Flag-toggle misfire, reverted." },
+    { importance: 5, title: "Canopy: popup container width CSS typo (300 px → 400 px)", episodeType: "bug", gist: "CSS typo fixed." },
+    { importance: 4, title: "Noted CAN bus arbitration failure under high load", episodeType: "infra", gist: "Captured high-load CAN bus limitation in firmware docs." },
+    { importance: 3, title: "Typo fix in CRDT conflict error message", episodeType: "bug", gist: "Typo fix." },
+    { importance: 3, title: "boltpkg: fix 'dependancy' typo in resolver error message", episodeType: "bug", gist: "Typo fixed." },
+    { importance: 3, title: "Renamed docs Recipes to Cookbook", episodeType: "docs", gist: "Docs examples section was renamed." },
+];

package/lib/core/route-health.js

@@ -0,0 +1,106 @@
+/**
+ * Route health — the volatile "this route is quota-exhausted" observation lane.
+ *
+ * Two decisions live here, both deliberately tiny:
+ *
+ *  1. **What counts as an exhausted quota.** Wording only — the canonical
+ *     provider-neutral wording family DSH itself recognizes (`insufficient
+ *     quota/balance/credits`, `quota/usage limit exceeded…`), plus the Chinese
+ *     limit wording this deployment actually produces (`已达到 7 天使用上限`).
+ *     Transient throttling is NOT this: `quota resets in one minute` says the
+ *     route is alive, so it must not arm a skip (DSH's own classifier makes the
+ *     same distinction).
+ *
+ *  2. **How long one observation holds.** A fixed hold, nothing persisted. The
+ *     signal's owner is real traffic — the host's `agent/request-error` events
+ *     keep re-arming it while the main conversation keeps failing on that
+ *     route, and it simply expires after the hold when nothing does. That is
+ *     the whole point: an externally reset quota (admin reset, pay-as-you-go
+ *     enabled, early recovery) cannot be trapped by a stale guess, because
+ *     there is no durable state to go stale — the worst case is one hold's
+ *     worth of skipped maintenance, and the maintenance tick's own next probe
+ *     re-discovers the truth at the cost of one cheap rejected request.
+ */
+/**
+ * Exhausted-quota wording. `detail` is whatever the failure surface exposed
+ * (message preferred, code as a fallback) — callers concatenate what they have.
+ */
+export function isQuotaExhaustedDetail(detail) {
+    return /insufficient[\s_-]*(?:quota|balance|credits?)/i.test(detail)
+        || /(?:quota|usage[\s_-]*limit)[\s_-]*(?:exceeded|exhausted|reached)/i.test(detail)
+        || /exceed(?:ed|s)?[\s_-]*(?:(?:your|the)[\s_-]*)?(?:current[\s_-]*)?quota/i.test(detail)
+        || /(?:balance|credits?)[\s_-]*(?:exhausted|depleted)/i.test(detail)
+        || /使用上限|额度(?:已)?(?:用尽|耗尽)|余额不足/.test(detail);
+}
+/** How long one quota observation suppresses the maintenance lane. */
+export const ROUTE_QUOTA_HOLD_MS = 45 * 60_000;
+/**
+ * The observation map. Volatile by design: process lifetime, no persistence,
+ * no reset-time parsing. `now` is always injected so the hold is testable.
+ */
+export class RouteHealth {
+    quotaAt = new Map();
+    /** Arm the skip for one provider. Idempotent; the latest observation wins. */
+    observeQuotaFailure(provider, at) {
+        if (provider.length === 0)
+            return;
+        this.quotaAt.set(provider, at);
+    }
+    /**
+     * Milliseconds since the latest quota observation for this provider, when
+     * that observation is still inside the hold; `undefined` when the route is
+     * not suppressed (no observation, or an expired one).
+     */
+    quotaSince(provider, now, holdMs = ROUTE_QUOTA_HOLD_MS) {
+        const at = this.quotaAt.get(provider);
+        if (at === undefined)
+            return undefined;
+        const age = now - at;
+        return age >= 0 && age < holdMs ? age : undefined;
+    }
+    /** Read-only copy, for journaling and the doctor surface. */
+    snapshot(now, holdMs = ROUTE_QUOTA_HOLD_MS) {
+        const out = new Map();
+        for (const [provider, at] of this.quotaAt) {
+            if (now - at < holdMs)
+                out.set(provider, at);
+        }
+        return out;
+    }
+}
+/**
+ * The skip decision the maintenance tick actually uses — deliberately narrower
+ * than the observation. The event carries a provider but no model, while a
+ * quota is route-scoped (provider/model): the live 2026-10-09 incident had
+ * provider-a/model-a exhausted while provider-a/model-b
+ * verified normally, and a provider-keyed skip would have suppressed the live
+ * route. So an observation may only suppress the main conversation's OWN
+ * exact route: the tick route must equal the last session route in provider
+ * AND model, and the observation must be for that provider. A pinned route
+ * that diverges from the main conversation never skips — one cheap rejected
+ * request beats silently stalling a working route.
+ */
+export function quotaSkipSince(health, tickRoute, lastSessionRoute, now, holdMs = ROUTE_QUOTA_HOLD_MS) {
+    if (tickRoute === undefined || lastSessionRoute === undefined)
+        return undefined;
+    if (tickRoute.provider !== lastSessionRoute.provider || tickRoute.model !== lastSessionRoute.model)
+        return undefined;
+    return health.quotaSince(tickRoute.provider, now, holdMs);
+}
+/**
+ * The maintenance lane's route, resolved once per tick.
+ *
+ * Priority is explicit over following: a pinned `maintenance.verifyProvider`
+ * wins (it is the rollback lever), the main conversation's latest route is the
+ * default, and neither being available means the lane runs its LLM-less steps
+ * only — exactly the pre-existing behavior. "Latest" is last-seen-wins across
+ * concurrent sessions, which is fine for a lane whose only requirement is "a
+ * route the user currently trusts".
+ */
+export function resolveMaintenanceRoute(explicit, lastSession) {
+    if (explicit !== undefined && explicit.provider.length > 0 && explicit.model.length > 0)
+        return explicit;
+    if (lastSession !== undefined && lastSession.provider.length > 0 && lastSession.model.length > 0)
+        return lastSession;
+    return undefined;
+}