@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/_lib/persistence/detect_prisma_growth.ts

@@ -0,0 +1,74 @@
+/**
+ * R-A7 growth-budget for Prisma schemas (F7) —
+ * road-to-scale-and-history-discipline Phase 5.
+ *
+ * An append-only-shaped model (name or `@@map` target matching the shared
+ * append-only vocabulary: *_logs, *_events, *_history, audits, jobs, queue,
+ * sessions, notifications, …) must declare a retention policy as a doc
+ * comment on the model (`/// retention: <policy>`) or carry a
+ * `/// no-retention: <reason>` waiver. Same semantics as the raw-SQL
+ * adapter's R-A7 check, applied to schema.prisma.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { Finding } from './types.js';
+import { is_ignored_dir } from './types.js';
+import { is_append_only_name } from './adapter_raw_sql.js';
+
+const RETENTION_RE = /\/\/\/?\s*retention\s*:\s*\S/;
+const NO_RETENTION_RE = /\/\/\/?\s*no-retention\s*:\s*(\S.*)$/m;
+
+export function detect_prisma_growth(files: Array<{ path: string; content: string }>): Finding[] {
+    const findings: Finding[] = [];
+    for (const f of files) {
+        const lines = f.content.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const m = lines[i]!.match(/^\s*model\s+(\w+)\s*\{/);
+            if (!m) continue;
+            // Model body: find the closing brace (prisma blocks are flat).
+            let end = i;
+            for (let j = i + 1; j < lines.length; j += 1) {
+                if (/^\s*\}/.test(lines[j]!)) {
+                    end = j;
+                    break;
+                }
+            }
+            const body = lines.slice(i, end + 1).join('\n');
+            const mapped = body.match(/@@map\(\s*["'](\w+)["']\s*\)/);
+            const table_name = mapped ? mapped[1]! : m[1]!;
+            if (!is_append_only_name(table_name)) continue;
+
+            // Retention/waiver: doc comments directly above the model or inside it.
+            const head = lines.slice(Math.max(0, i - 3), i).join('\n');
+            if (RETENTION_RE.test(head) || RETENTION_RE.test(body)) continue;
+            const waiver = (head + '\n' + body).match(NO_RETENTION_RE);
+            findings.push({
+                failure_class: 'F7',
+                rule: 'R-A7',
+                file: f.path,
+                line: i + 1,
+                message: `model ${m[1]} (table ${table_name}) looks append-only but declares no retention policy (add "/// retention: <policy>" or a no-retention waiver)`,
+                tier: 'gate',
+                ...(waiver ? { waived: true, waiver_reason: waiver[1]!.trim() } : {}),
+            });
+        }
+    }
+    return findings;
+}
+
+export function scan_dir(dir: string): Finding[] {
+    const files: Array<{ path: string; content: string }> = [];
+    const walk = (d: string): void => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (!is_ignored_dir(e.name)) walk(p);
+            } else if (e.name.endsWith('.prisma')) {
+                files.push({ path: p, content: fs.readFileSync(p, 'utf8') });
+            }
+        }
+    };
+    walk(dir);
+    return detect_prisma_growth(files);
+}

package/src/scripts/_lib/persistence/offload_catalog.ts

@@ -0,0 +1,73 @@
+/**
+ * Offloadable-call catalog for R-A8 (thin-request-path, F9) and R-A10
+ * (durable-async, F11) — spike S0.5, road-to-scale-and-history-discipline.
+ *
+ * The catalog is CONFIG DATA, not detector logic: a positive list of
+ * expensive call classes per stack. A single indexed insert or a cache op is
+ * never in the catalog — over-application (queueing trivially cheap work) is
+ * the failure mode this shape prevents.
+ */
+
+export interface CatalogEntry {
+    /** Regex source matched against a single (masked) code line. */
+    pattern: string;
+    /** Human label used in the finding message. */
+    label: string;
+    /**
+     * Whether losing this work silently is unacceptable (drives F11 for
+     * fire-and-forget shapes): promised emails, billing, webhooks out.
+     */
+    must_not_lose: boolean;
+}
+
+export interface StackCatalog {
+    /** Offloadable call classes — firing inside a request handler is F9. */
+    offloadable: CatalogEntry[];
+    /**
+     * Patterns that are the CORRECT offload shape — their presence on the
+     * same line neutralizes an offloadable match (e.g. Mail::queue).
+     */
+    allowed_alternatives: string[];
+}
+
+export const ELOQUENT_CATALOG: StackCatalog = {
+    offloadable: [
+        { pattern: String.raw`\bMail::send\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\bMail::to\s*\([^)]*\)\s*->\s*send\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\bHttp::`, label: 'outbound HTTP call', must_not_lose: false },
+        { pattern: String.raw`\b(PDF|Pdf)::loadView\s*\(`, label: 'PDF generation', must_not_lose: false },
+        { pattern: String.raw`\bExcel::store\s*\(`, label: 'spreadsheet export to storage', must_not_lose: false },
+        { pattern: String.raw`\bImage::make\s*\(`, label: 'image processing chain', must_not_lose: false },
+        { pattern: String.raw`\bBrowsershot::`, label: 'headless-browser rendering', must_not_lose: false },
+        { pattern: String.raw`new\s+\\?Stripe\\StripeClient\b|\bStripe\\\w+::`, label: 'payment SDK call', must_not_lose: true },
+        { pattern: String.raw`\bTwilio\\|\bnew\s+\\?Twilio\b`, label: 'SMS/voice SDK call', must_not_lose: true },
+        { pattern: String.raw`\bOpenAI::|\bAnthropic\\|\bAnthropic::`, label: 'ML/AI inference call', must_not_lose: false },
+    ],
+    allowed_alternatives: [
+        String.raw`\bMail::queue\s*\(`,
+        String.raw`->\s*queue\s*\(`,
+    ],
+};
+
+export const TS_CATALOG: StackCatalog = {
+    offloadable: [
+        { pattern: String.raw`\.sendMail\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\b(fetch|axios(\.\w+)?)\s*\(\s*['"\`]https?://`, label: 'outbound HTTP call', must_not_lose: false },
+        { pattern: String.raw`\bpuppeteer\.launch\s*\(|\bchromium\.launch\s*\(`, label: 'headless-browser rendering', must_not_lose: false },
+        { pattern: String.raw`\bsharp\s*\([^)]*\)\s*\.`, label: 'image processing chain', must_not_lose: false },
+        { pattern: String.raw`\.chat\.completions\.create\s*\(|\banthropic\.messages\.create\s*\(`, label: 'ML/AI inference call', must_not_lose: false },
+        { pattern: String.raw`\bstripe\.\w+(\.\w+)*\.create\s*\(`, label: 'payment SDK call', must_not_lose: true },
+        { pattern: String.raw`\.updateMany\s*\(\s*\{\s*data\s*:`, label: 'unbounded bulk mutation', must_not_lose: false },
+    ],
+    allowed_alternatives: [
+        String.raw`\bqueue\.add\s*\(`,
+        String.raw`\.add\s*\(\s*['"\`]`,
+    ],
+};
+
+/**
+ * Job-class names whose loss is unacceptable — drives the
+ * dispatchAfterResponse / fire-and-forget F11 checks.
+ */
+export const MUST_NOT_LOSE_NAME_RE =
+    /(Mail|Email|Invoice|Webhook|Payment|Billing|Notification|Receipt)/;

package/src/scripts/_lib/persistence/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared types for the persistence-lint substrate (lint_persistence).
+ *
+ * Failure classes F1–F11 and rule ids R-A1…R-A11 / R-B1…R-B5 are defined in
+ * agents/roadmaps/archive/road-to-scale-and-history-discipline.md (roadmap) and,
+ * post-merge, in the scale-discipline / history-discipline pack rules.
+ *
+ * "Deterministic" throughout means: deterministic PATTERN detection with an
+ * auditable waiver process — the linter identifies the pattern class
+ * mechanically; instance-level correctness is contextual and handled by a
+ * reasoned waiver, never by the linter claiming judgment it does not have.
+ */
+
+export type FailureClass =
+    | 'F1' // N+1 queries
+    | 'F2' // missing indexes
+    | 'F3' // unbounded selects
+    | 'F6' // unsafe migrations
+    | 'F7' // unbounded table growth
+    | 'F8' // missing audit history
+    | 'F9' // sync work in request path
+    | 'F11'; // non-durable async
+
+export type FindingTier = 'gate' | 'advice';
+
+export interface Finding {
+    failure_class: FailureClass;
+    rule: string; // e.g. "R-A6"
+    file: string; // repo-relative path
+    line: number; // 1-indexed
+    message: string;
+    tier: FindingTier;
+    /** Set when the offending line carries a recognized waiver. */
+    waived?: boolean;
+    /** The waiver reason text, when present. */
+    waiver_reason?: string;
+}
+
+export interface ScanResult {
+    findings: Finding[];
+    /** Files the adapter looked at (for coverage reporting). */
+    scanned_files: string[];
+    /** Waivers encountered, incl. empty-reason violations. */
+    waivers: WaiverRecord[];
+}
+
+export interface WaiverRecord {
+    file: string;
+    line: number;
+    kind: string; // 'no-index' | 'sync-required' | 'accepted-loss' | 'no-retention' | 'migration-unsafe'
+    reason: string; // empty string = hygiene violation
+}
+
+/**
+ * Waiver comment grammar (shared across adapters):
+ *   PHP/TS:  // <kind>: <reason>     e.g. // no-index: read-heavy analytics column
+ *   SQL:     -- <kind>: <reason>
+ * Recognized kinds: no-index, sync-required, accepted-loss, no-retention,
+ * migration-unsafe.
+ */
+export const WAIVER_KINDS = [
+    'no-index',
+    'sync-required',
+    'accepted-loss',
+    'no-retention',
+    'migration-unsafe',
+] as const;
+
+const WAIVER_RE = new RegExp(
+    String.raw`(?://|--|#)\s*(${WAIVER_KINDS.join('|')})\s*:\s*(.*)$`,
+);
+
+/** Parse a waiver on the given line (or the line directly above). */
+export function parse_waiver(lines: string[], idx0: number): WaiverRecord | null {
+    for (const i of [idx0, idx0 - 1]) {
+        if (i < 0 || i >= lines.length) continue;
+        const m = lines[i]!.match(WAIVER_RE);
+        if (m) {
+            return { file: '', line: i + 1, kind: m[1]!, reason: (m[2] ?? '').trim() };
+        }
+    }
+    return null;
+}
+
+/** Directory names every persistence walker skips (dependency/build trees). */
+export const IGNORED_DIRS: ReadonlySet<string> = new Set([
+    'vendor',
+    'node_modules',
+    'storage',
+    '.git',
+    'bootstrap',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    // Test trees are not production read paths — R-A1/A2/A3/A8 target
+    // production code; test-suite queries run against small fixtures. The
+    // scan ROOT itself is never name-checked, so pointing the linter AT a
+    // fixture tree still works.
+    'tests',
+    'Tests',
+    'test',
+    '__tests__',
+    'spec',
+]);
+
+export function is_ignored_dir(name: string): boolean {
+    return IGNORED_DIRS.has(name) || name.startsWith('.');
+}

package/src/scripts/_lib/rtk_allowlist.ts

@@ -0,0 +1,44 @@
+/**
+ * rtk allowlist for worker tool loops (road-to-lean-agent-init Phase 4).
+ *
+ * Wraps ONLY the command class with a MEASURED ~55% output saving —
+ * `internal/bench/rtk-savings/RESULTS.md` is the single source of the
+ * numbers (referenced, never duplicated here). The ~0%-savings class stays
+ * unwrapped: wrap overhead without return. Congruence with RESULTS.md is
+ * enforced by `tests/scripts/_lib_rtk_allowlist.test.ts`, which parses the
+ * results table and asserts every allowlisted pattern measured ≥ the
+ * threshold and every excluded pattern measured below it.
+ */
+
+/** A worker wraps a command with rtk only when its saving measured ≥ this. */
+export const RTK_WRAP_THRESHOLD_PCT = 50;
+
+/**
+ * Command patterns in the measured high-savings class. Matched against the
+ * command a worker is about to run; first match wins.
+ */
+export const RTK_WRAP_ALLOWLIST: ReadonlyArray<{ pattern: RegExp; benchCommand: string }> = [
+    { pattern: /^git status\b/, benchCommand: 'git status' },
+    // Full-format git log (NOT --oneline — that class measured ~0%).
+    { pattern: /^git log(?!.*--oneline)\b/, benchCommand: 'git log -10' },
+    { pattern: /^ls -la?\b/, benchCommand: 'ls -la src/scripts' },
+];
+
+/**
+ * Measured-near-zero class — never wrapped (documented so nobody "helpfully"
+ * adds them back without a new measurement).
+ */
+export const RTK_NO_WRAP: ReadonlyArray<{ pattern: RegExp; benchCommand: string }> = [
+    { pattern: /^git log .*--oneline\b/, benchCommand: 'git log --oneline -50' },
+    { pattern: /^git diff .*--stat\b/, benchCommand: 'git diff --stat HEAD~5..HEAD' },
+    { pattern: /^git branch\b/, benchCommand: 'git branch -a' },
+    { pattern: /^npm ls\b/, benchCommand: 'npm ls --depth=0' },
+    { pattern: /^git show .*--stat\b/, benchCommand: 'git show --stat HEAD' },
+];
+
+/** Should a worker wrap this command with rtk? Deterministic, measured-class only. */
+export function shouldWrapWithRtk(command: string): boolean {
+    const cmd = command.trim();
+    if (RTK_NO_WRAP.some((e) => e.pattern.test(cmd))) return false;
+    return RTK_WRAP_ALLOWLIST.some((e) => e.pattern.test(cmd));
+}

package/src/scripts/_lib/secret_detector.test.ts

@@ -33,6 +33,11 @@ const EXPECTED_KIND: Readonly<Record<string, string>> = {
     jwt: 'jwt',
     dburl: 'db-connection-uri',
     assignment: 'generic-assignment',
+    // adversarial-corpus additions (road-to-feedback-9.8.0-followups Phase 3)
+    'github-fine-grained': 'github-pat',
+    'env-db-password': 'generic-assignment',
+    'env-api-key': 'generic-assignment',
+    'dburl-mysql': 'db-connection-uri',
 };
 
 function isReal(f: SecretFinding): boolean {

package/src/scripts/_lib/secret_detector.ts

@@ -66,6 +66,9 @@ const RULES: readonly Rule[] = [
     { rule: 'aws-access-key', kind: 'aws-access-key', regex: /AKIA[0-9A-Z]{16}/g },
     { rule: 'google-api-key', kind: 'google-api-key', regex: /AIza[0-9A-Za-z_-]{35}/g },
     { rule: 'github-pat', kind: 'github-pat', regex: /ghp_[0-9A-Za-z]{36}/g },
+    // Fine-grained PATs (github_pat_…) were a measured detector gap: the
+    // 2026-07-28 adversarial corpus pass flagged them as missed positives.
+    { rule: 'github-fine-grained-pat', kind: 'github-pat', regex: /github_pat_[0-9A-Za-z_]{22,}/g },
     {
         rule: 'jwt',
         kind: 'jwt',
@@ -282,6 +285,12 @@ export function scanText(text: string, opts: ScanOptions = {}): SecretFinding[]
                 if (UUID.test(token)) {
                     continue; // benign identifier
                 }
+                if (/^sha(?:256|384|512)-/.test(token)) {
+                    // SRI / npm-lockfile integrity digest (`sha512-<base64>`) —
+                    // a hash, not a credential. Measured FP class on the
+                    // 2026-07-28 adversarial corpus pass.
+                    continue;
+                }
                 const entropy = shannonEntropy(token);
                 const isHex = IS_HEX.test(token);
                 if (isHex && HASH_HEX_LENGTHS.has(token.length)) {

package/src/scripts/_lib/secret_detector_adversarial.test.ts

@@ -0,0 +1,116 @@
+// Adversarial precision/recall measurement for the secret detector
+// (road-to-feedback-9.8.0-followups Phase 3). Runs the REAL scanText over
+// the committed fixture corpus plus runtime-constructed multiline cases
+// (assembled from parts so nothing key-shaped beyond the existing corpus
+// convention lands in the tree), computes precision / recall / FP-rate, and
+// publishes the rates to internal/reports/secret-scanner-adversarial.json.
+//
+// Hard floor: recall = 100% on positives, FP-rate = 0% on negative controls.
+// A genuine detector miss must NOT be papered over by weakening a fixture —
+// it gets a known_gap entry excluded from the hard assertion and REPORTED.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import { scanText, type SecretFinding } from './secret_detector.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(HERE, 'fixtures', 'secret-detector');
+const REPO = path.resolve(HERE, '..', '..', '..');
+const REPORT = path.join(REPO, 'internal', 'reports', 'secret-scanner-adversarial.json');
+
+/** Measured, documented gaps — excluded from the hard floor, published. */
+const KNOWN_GAPS: string[] = [];
+
+const isReal = (f: SecretFinding): boolean => f.confidence === 'high' || f.confidence === 'medium';
+
+interface Case { id: string; text: string; expect_hit: boolean }
+
+function corpusCases(): Case[] {
+    const cases: Case[] = [];
+    for (const [file, expectHit] of [['positives.txt', true], ['negatives.txt', false]] as const) {
+        const lines = fs.readFileSync(path.join(FIXTURES, file), 'utf-8').split('\n');
+        lines.forEach((line, i) => {
+            if (line.trim().length === 0 || line.startsWith('#')) return;
+            const value = expectHit ? (line.split('|')[1] ?? line) : line;
+            cases.push({ id: `${file}:${i + 1}`, text: value, expect_hit: expectHit });
+        });
+    }
+    return cases;
+}
+
+/** Multiline / wrapped positives assembled at runtime. */
+function constructedCases(): Case[] {
+    // A fake PEM body: base64-ish filler between real BEGIN/END framing.
+    const pem = [
+        ['-----BEGIN', 'RSA PRIVATE KEY-----'].join(' '),
+        'MIIEpAIBAAKCAQEA7fakebodyfakebodyfakebodyfakebodyfakebody12345678',
+        'q7fakebodyfakebodyfakebodyfakebodyfakebodyfakebodyfakebody901234',
+        ['-----END', 'RSA PRIVATE KEY-----'].join(' '),
+    ].join('\n');
+    // A base64-WRAPPED credential next to a keyword: the wrapped payload is a
+    // fake AWS key; the wrapper alone must still trip entropy+keyword.
+    const wrapped = `api_key = "${Buffer.from('AKIA' + '1234567890ABCDEF').toString('base64')}"`;
+    // .env multiline block (several assignments in one scan call).
+    const envBlock = ['APP_ENV=production', 'DB_PASSWORD=q7Xp2Vr9kLm4Nt8wYz3BdF6h', 'MAIL_FROM=noreply@example.com'].join('\n');
+    return [
+        { id: 'constructed:pem-multiline', text: pem, expect_hit: true },
+        { id: 'constructed:base64-wrapped-key', text: wrapped, expect_hit: true },
+        { id: 'constructed:env-block', text: envBlock, expect_hit: true },
+        // Negative: random base64 with NO credential keyword nearby.
+        { id: 'constructed:naked-base64-no-keyword-short', text: 'blob dGhpcyBpcyBmaWxsZXI=', expect_hit: false },
+    ];
+}
+
+describe('secret detector — adversarial corpus measurement', () => {
+    const cases = [...corpusCases(), ...constructedCases()];
+    const rows = cases.map((c) => {
+        const real = scanText(c.text).filter(isReal);
+        return { ...c, hit: real.length > 0, kinds: [...new Set(real.map((f) => f.kind))] };
+    });
+
+    const positives = rows.filter((r) => r.expect_hit);
+    const negatives = rows.filter((r) => !r.expect_hit);
+    const detected = positives.filter((r) => r.hit);
+    const missed = positives.filter((r) => !r.hit).map((r) => r.id);
+    const falsePositives = negatives.filter((r) => r.hit).map((r) => r.id);
+    const recall = positives.length > 0 ? detected.length / positives.length : 1;
+    const fpRate = negatives.length > 0 ? falsePositives.length / negatives.length : 0;
+    const precision =
+        detected.length + falsePositives.length > 0
+            ? detected.length / (detected.length + falsePositives.length)
+            : 1;
+
+    it('publishes the measured rates', () => {
+        const report = {
+            _doc:
+                'Adversarial fixture measurement of the secret detector (scanText). ' +
+                'Regenerated by src/scripts/_lib/secret_detector_adversarial.test.ts on every run; ' +
+                'hard floor asserted there (recall 100% / FP 0% outside known_gaps).',
+            generated: new Date().toISOString().slice(0, 10),
+            corpus_size: rows.length,
+            positives: positives.length,
+            negatives: negatives.length,
+            detected: detected.length,
+            missed,
+            false_positives: falsePositives,
+            known_gaps: KNOWN_GAPS,
+            precision: +precision.toFixed(3),
+            recall: +recall.toFixed(3),
+            fp_rate: +fpRate.toFixed(3),
+        };
+        fs.mkdirSync(path.dirname(REPORT), { recursive: true });
+        fs.writeFileSync(REPORT, `${JSON.stringify(report, null, 2)}\n`);
+        expect(fs.existsSync(REPORT)).toBe(true);
+    });
+
+    it('recall floor: every positive outside known_gaps is detected', () => {
+        const hardMisses = missed.filter((id) => !KNOWN_GAPS.includes(id));
+        expect(hardMisses, `detector missed: ${hardMisses.join(', ')}`).toHaveLength(0);
+    });
+
+    it('FP floor: no negative control fires high/medium', () => {
+        expect(falsePositives, `false positives: ${falsePositives.join(', ')}`).toHaveLength(0);
+    });
+});

package/src/scripts/_lib/spawn_env.ts

@@ -54,6 +54,13 @@ const DENY_EXACT: ReadonlySet<string> = new Set([
     // attacker-controlled object stores; the GIT_CONFIG* family is handled by
     // prefix below (it is a general arbitrary-config-injection primitive).
     'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    // git path-redirection: GIT_DIR / GIT_INDEX_FILE / GIT_NAMESPACE point a
+    // child's git at an attacker-controlled repo, index file, or ref namespace
+    // — ordinary git ops then read and write attacker state (low severity,
+    // same family as GIT_ALTERNATE_OBJECT_DIRECTORIES above).
+    'GIT_DIR',
+    'GIT_INDEX_FILE',
+    'GIT_NAMESPACE',
     // resolver hijack: HOSTALIASES remaps hostnames via an attacker file,
     // redirecting any network fetch the child performs (CWE-427-adjacent).
     'HOSTALIASES',

package/src/scripts/_lib/sqlite_guard.ts

@@ -0,0 +1,191 @@
+// Shared `node:sqlite` guard — lazy import, availability probe, FTS5 probe,
+// and `PRAGMA user_version` helpers (road-to-reachable-code-memory Phase 6/7).
+//
+// Extracted from the two telemetry twins (mcp_telemetry_store.ts /
+// mcp_telemetry_query.ts) so every derived SQLite store (telemetry, the
+// memory FTS index, the graph store) shares one guard instead of three
+// copies of the same lazy-import + warning-silencer dance.
+//
+// `node:sqlite` ships from Node 22.5 (experimental on 22.x, stable/silent on
+// >= 23); the package's supported floor is `>=20.11` (package.json
+// `engines`), so every caller MUST treat this module's failure modes as
+// expected, not exceptional — lazy import + graceful fallback, never a hard
+// dependency (ADR-129).
+import { createRequire } from 'node:module';
+import type { DatabaseSync } from 'node:sqlite';
+import type * as NodeSqlite from 'node:sqlite';
+
+/** Thrown by {@link loadSqlite} when `node:sqlite` cannot be imported here. */
+export class SqliteUnavailableError extends Error {
+    constructor(callerName: string, cause: string) {
+        super(
+            `node:sqlite is unavailable in this runtime (${cause}). ` +
+                `${callerName} requires Node with the built-in SQLite module.`,
+        );
+        this.name = 'SqliteUnavailableError';
+    }
+}
+
+// Node 22 flags `node:sqlite` experimental and prints an `ExperimentalWarning:
+// SQLite …` line to stderr on first import (stable / silent on Node >= 23).
+// Drop only that specific warning so stderr stays byte-stable across Node
+// versions (CLI intent tests pin exact stderr bytes). Installed once,
+// narrowly matched — every other `emitWarning` call passes through unchanged.
+let _sqliteWarningSilenced = false;
+function _silenceSqliteExperimentalWarning(): void {
+    if (_sqliteWarningSilenced) return;
+    _sqliteWarningSilenced = true;
+    const orig = process.emitWarning.bind(process);
+    process.emitWarning = ((warning: string | Error, ...rest: unknown[]): void => {
+        const text = typeof warning === 'string' ? warning : (warning?.message ?? '');
+        if (/SQLite is an experimental/i.test(text)) return;
+        (orig as (w: string | Error, ...a: unknown[]) => void)(warning, ...rest);
+    }) as typeof process.emitWarning;
+}
+
+/**
+ * Lazy `node:sqlite` import — keeps the caller module loadable on a runtime
+ * without it. `callerName` (e.g. `"mcp_telemetry_store"`) is folded into the
+ * thrown message so each caller's error text stays distinguishable.
+ *
+ * Throws {@link SqliteUnavailableError} on failure; callers that want a
+ * non-throwing check should use {@link isSqliteAvailable} first.
+ */
+export async function loadSqlite(callerName: string): Promise<typeof NodeSqlite> {
+    _silenceSqliteExperimentalWarning();
+    try {
+        return await import('node:sqlite');
+    } catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        throw new SqliteUnavailableError(callerName, message);
+    }
+}
+
+/** Non-throwing availability probe — true iff `node:sqlite` imports cleanly. */
+export async function isSqliteAvailable(): Promise<boolean> {
+    _silenceSqliteExperimentalWarning();
+    try {
+        await import('node:sqlite');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Whether this runtime's `node:sqlite` supports FTS5 — probed via an
+ * in-memory `CREATE VIRTUAL TABLE ... USING fts5` + `MATCH` round-trip
+ * (ADR-129: re-verified live on v25.9.0). Some minimal SQLite builds omit
+ * the FTS5 extension even when `node:sqlite` itself loads, so this is a
+ * separate probe from {@link isSqliteAvailable}.
+ */
+export async function probeFts5(): Promise<boolean> {
+    let sqlite: typeof NodeSqlite;
+    try {
+        sqlite = await loadSqlite('sqlite_guard.probeFts5');
+    } catch {
+        return false;
+    }
+    let conn: DatabaseSync | null = null;
+    try {
+        conn = new sqlite.DatabaseSync(':memory:');
+        conn.exec("CREATE VIRTUAL TABLE _fts5_probe USING fts5(body)");
+        conn.exec("INSERT INTO _fts5_probe(body) VALUES ('probe')");
+        const row = conn.prepare("SELECT body FROM _fts5_probe WHERE _fts5_probe MATCH 'probe'").get();
+        return row !== undefined;
+    } catch {
+        return false;
+    } finally {
+        try {
+            conn?.close();
+        } catch {
+            /* best-effort */
+        }
+    }
+}
+
+// --- Synchronous variants ---------------------------------------------------
+//
+// `node:sqlite`'s `DatabaseSync` API is itself fully synchronous; the async
+// variants above exist only because the two telemetry twins happen to be
+// async CLIs. A caller that must stay synchronous end-to-end (memory_lookup.ts
+// — `retrieve()` is called synchronously all over the codebase and by tests)
+// uses `createRequire` for a sync `require('node:sqlite')` instead of the
+// dynamic `import()`, mirroring the file's own existing `_lazy_tokenizer()`
+// sync-require pattern for `./_lib/token_count.js`.
+let _require: NodeJS.Require | undefined;
+function _syncRequire(): NodeJS.Require {
+    if (_require === undefined) {
+        _require = createRequire(import.meta.url);
+    }
+    return _require;
+}
+
+/** Synchronous `node:sqlite` require — see "Synchronous variants" above. */
+export function loadSqliteSync(callerName: string): typeof NodeSqlite {
+    _silenceSqliteExperimentalWarning();
+    try {
+        return _syncRequire()('node:sqlite') as typeof NodeSqlite;
+    } catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        throw new SqliteUnavailableError(callerName, message);
+    }
+}
+
+/** Non-throwing sync availability probe — true iff `node:sqlite` requires cleanly. */
+export function isSqliteAvailableSync(): boolean {
+    _silenceSqliteExperimentalWarning();
+    try {
+        _syncRequire()('node:sqlite');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Sync twin of {@link probeFts5} — see "Synchronous variants" above. */
+export function probeFts5Sync(): boolean {
+    let sqlite: typeof NodeSqlite;
+    try {
+        sqlite = loadSqliteSync('sqlite_guard.probeFts5Sync');
+    } catch {
+        return false;
+    }
+    let conn: DatabaseSync | null = null;
+    try {
+        conn = new sqlite.DatabaseSync(':memory:');
+        conn.exec("CREATE VIRTUAL TABLE _fts5_probe USING fts5(body)");
+        conn.exec("INSERT INTO _fts5_probe(body) VALUES ('probe')");
+        const row = conn.prepare("SELECT body FROM _fts5_probe WHERE _fts5_probe MATCH 'probe'").get();
+        return row !== undefined;
+    } catch {
+        return false;
+    } finally {
+        try {
+            conn?.close();
+        } catch {
+            /* best-effort */
+        }
+    }
+}
+
+/** Read `PRAGMA user_version` — 0 on a freshly created (never-stamped) DB. */
+export function readUserVersion(conn: DatabaseSync): number {
+    const row = conn.prepare('PRAGMA user_version').get();
+    const v = row?.['user_version'];
+    if (typeof v === 'bigint') return Number(v);
+    if (typeof v === 'number') return v;
+    return 0;
+}
+
+/**
+ * Stamp `PRAGMA user_version`. SQLite's `PRAGMA` statements take no bind
+ * parameters, so `version` is range-checked (small non-negative 32-bit
+ * integer) before string interpolation.
+ */
+export function stampUserVersion(conn: DatabaseSync, version: number): void {
+    if (!Number.isInteger(version) || version < 0 || version > 2 ** 31 - 1) {
+        throw new RangeError(`stampUserVersion: version out of range: ${version}`);
+    }
+    conn.exec(`PRAGMA user_version = ${version}`);
+}