@event4u/agent-config 9.8.0 → 9.10.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/preservation_migration.ts

@@ -0,0 +1,291 @@
+/**
+ * Preservation-conformance verifier for safety-floor rule edits.
+ *
+ * `check_safety_floor_untouched` blocks every edit to the four safety-floor
+ * rules. That is right for substantive edits and wrong for a P4 migration, which
+ * moves lookup material into a `load_context:` target without losing anything.
+ * This module decides which one a diff is — by CHECKING, never by trusting a
+ * label, a commit message, or a contributor's word. A migration that cannot be
+ * proven conformant is treated as substantive and blocked (fail-closed).
+ *
+ * The contract it enforces is `preservation-guard`'s: every paragraph, list
+ * item, and fenced block from the source survives — either still in the rule
+ * (telegraph condensation is allowed, so matching is fuzzy) or verbatim in one
+ * of the rule's declared `load_context:` targets (a migration is a move, so
+ * matching there is near-exact). Iron Law sections are stricter still: their
+ * headings must survive at the same level and their fenced blocks byte-for-byte.
+ *
+ * Pure functions over strings — no git, no fs — so the whole decision is unit
+ * testable without manufacturing commits. That absence is why the guard it
+ * serves shipped inert for months.
+ */
+
+/** A structural unit of a markdown body: heading, paragraph, list item, or fence. */
+export interface Unit {
+    kind: 'heading' | 'paragraph' | 'list-item' | 'fence';
+    /** Heading depth (1-6) for `heading`, else 0. */
+    level: number;
+    /** Raw text as it appeared, minus the trailing newline. */
+    raw: string;
+    /** Normalised form used for comparison. */
+    norm: string;
+}
+
+/** Strip frontmatter; return the body. */
+export function strip_frontmatter(text: string): string {
+    const m = /^---\n[\s\S]*?\n---\n/.exec(text);
+    return m === null ? text : text.slice(m[0].length);
+}
+
+/** `load_context:` targets declared in a rule's frontmatter, in order. */
+export function load_context_targets(text: string): string[] {
+    const fm = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (fm === null) return [];
+    const out: string[] = [];
+    let inBlock = false;
+    for (const line of fm[1]!.split('\n')) {
+        if (/^load_context:\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        if (inBlock) {
+            const item = /^\s*-\s+(.+?)\s*$/.exec(line);
+            if (item !== null) {
+                out.push(item[1]!.replace(/^["']|["']$/g, ''));
+                continue;
+            }
+            if (/^\S/.test(line)) inBlock = false;
+        }
+    }
+    return out;
+}
+
+/**
+ * Normalise a unit for comparison.
+ *
+ * Deliberately blind to the three things a legitimate migration changes and
+ * nothing else: heading depth (an H2 becomes an H3 under a host section), link
+ * targets (relative paths are rewritten for the new location), and whitespace.
+ * Everything that carries obligation — words, emphasis, negations — is compared
+ * as written.
+ */
+export function normalise(raw: string): string {
+    return raw
+        .replace(/^#{1,6}\s+/gm, '') // heading depth
+        .replace(/\]\([^)]*\)/g, ']()') // link targets
+        .replace(/^\s*[-*+]\s+/gm, '') // list markers
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/** Split a markdown body into structural units. Fenced blocks stay intact. */
+export function parse_units(body: string): Unit[] {
+    const lines = body.split('\n');
+    const units: Unit[] = [];
+    let para: string[] = [];
+
+    const flush = (): void => {
+        if (para.length === 0) return;
+        const raw = para.join('\n');
+        if (raw.trim() !== '') units.push({ kind: 'paragraph', level: 0, raw, norm: normalise(raw) });
+        para = [];
+    };
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i]!;
+        const fence = /^(\s*)(`{3,}|~{3,})/.exec(line);
+        if (fence !== null) {
+            flush();
+            const marker = fence[2]!;
+            const block = [line];
+            i += 1;
+            while (i < lines.length) {
+                block.push(lines[i]!);
+                if (lines[i]!.trimStart().startsWith(marker)) break;
+                i += 1;
+            }
+            const raw = block.join('\n');
+            units.push({ kind: 'fence', level: 0, raw, norm: raw.replace(/\s+$/gm, '') });
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading !== null) {
+            flush();
+            units.push({
+                kind: 'heading',
+                level: heading[1]!.length,
+                raw: line,
+                norm: normalise(line),
+            });
+            continue;
+        }
+        const item = /^\s*[-*+]\s+/.test(line) || /^\s*\d+\.\s+/.test(line);
+        if (item) {
+            flush();
+            units.push({ kind: 'list-item', level: 0, raw: line, norm: normalise(line) });
+            continue;
+        }
+        if (line.trim() === '') {
+            flush();
+            continue;
+        }
+        para.push(line);
+    }
+    flush();
+    return units;
+}
+
+/** Dice coefficient over character bigrams — cheap, order-sensitive enough. */
+export function similarity(a: string, b: string): number {
+    if (a === b) return 1;
+    if (a.length < 2 || b.length < 2) return a === b ? 1 : 0;
+    const grams = (s: string): Map<string, number> => {
+        const m = new Map<string, number>();
+        for (let i = 0; i < s.length - 1; i += 1) {
+            const g = s.slice(i, i + 2);
+            m.set(g, (m.get(g) ?? 0) + 1);
+        }
+        return m;
+    };
+    const ga = grams(a);
+    const gb = grams(b);
+    let overlap = 0;
+    for (const [g, n] of ga) overlap += Math.min(n, gb.get(g) ?? 0);
+    return (2 * overlap) / (a.length - 1 + b.length - 1);
+}
+
+/** A unit still present in the rule after telegraph condensation. */
+const KEPT_IN_RULE = 0.6;
+/** A unit moved into a context file — a move, so near-verbatim. */
+const MOVED_TO_CONTEXT = 0.9;
+
+export interface Finding {
+    code:
+        | 'iron-law-heading-lost'
+        | 'iron-law-fence-changed'
+        | 'passage-lost'
+        | 'unexplained-addition';
+    detail: string;
+}
+
+/** Units belonging to an Iron Law section (heading matches, until the next same-or-shallower heading). */
+export function iron_law_units(units: readonly Unit[]): Unit[] {
+    const out: Unit[] = [];
+    let depth: number | null = null;
+    for (const u of units) {
+        if (u.kind === 'heading') {
+            if (/^(the\s+)?iron\s+law/i.test(u.norm)) {
+                depth = u.level;
+                out.push(u);
+                continue;
+            }
+            if (depth !== null && u.level <= depth) depth = null;
+        }
+        if (depth !== null) out.push(u);
+    }
+    return out;
+}
+
+export interface VerifyInput {
+    /** Rule file content before the change. */
+    base_rule: string;
+    /** Rule file content after the change. */
+    head_rule: string;
+    /** Declared `load_context` target path → content AFTER the change. */
+    head_contexts: ReadonlyMap<string, string>;
+    /** Same targets, content BEFORE — so only ADDED context text counts as a landing site. */
+    base_contexts: ReadonlyMap<string, string>;
+}
+
+/**
+ * Decide whether a safety-floor rule edit is a preservation-conforming
+ * migration. Returns [] when it is; otherwise every reason it is not.
+ */
+export function verify_migration(input: VerifyInput): Finding[] {
+    const findings: Finding[] = [];
+    const baseUnits = parse_units(strip_frontmatter(input.base_rule));
+    const headUnits = parse_units(strip_frontmatter(input.head_rule));
+
+    // ── Iron Law: headings survive at depth, fences survive byte-for-byte ──
+    const baseIron = iron_law_units(baseUnits);
+    const headIron = iron_law_units(headUnits);
+    for (const u of baseIron) {
+        if (u.kind === 'heading') {
+            const hit = headIron.some((h) => h.kind === 'heading' && h.norm === u.norm && h.level === u.level);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-heading-lost',
+                    detail: `${u.raw.trim()} — must survive verbatim at the same level`,
+                });
+            }
+        } else if (u.kind === 'fence') {
+            const hit = headIron.some((h) => h.kind === 'fence' && h.raw === u.raw);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-fence-changed',
+                    detail: `fenced block under ${u.raw.split('\n')[0] ?? ''} changed — Iron Law fences are byte-exact`,
+                });
+            }
+        }
+    }
+
+    // ── Landing sites: only text ADDED to a DECLARED context counts ──
+    //
+    // The declared set is re-derived here from the rule's own frontmatter rather
+    // than trusted from the caller. A migration is only legitimate into a file
+    // the rule actually points readers at; dropping a passage into some other
+    // file leaves it unreachable from the rule and is a loss, not a move.
+    const declared = load_context_targets(input.head_rule);
+    const isDeclared = (p: string): boolean =>
+        declared.some((rel) => p === rel || p.endsWith(`/${rel}`));
+    const landing: string[] = [];
+    for (const [path, head] of input.head_contexts) {
+        if (!isDeclared(path)) continue;
+        const before = new Set(parse_units(strip_frontmatter(input.base_contexts.get(path) ?? '')).map((u) => u.norm));
+        for (const u of parse_units(strip_frontmatter(head))) {
+            if (!before.has(u.norm)) landing.push(u.norm);
+        }
+    }
+
+    // ── Every base unit survives: in the rule (fuzzy) or in a context (near-exact) ──
+    const headNorms = headUnits.map((u) => u.norm);
+    const usedHead = new Set<number>();
+    for (const u of baseUnits) {
+        let bestIdx = -1;
+        let best = 0;
+        for (let i = 0; i < headNorms.length; i += 1) {
+            if (usedHead.has(i)) continue;
+            const s = similarity(u.norm, headNorms[i]!);
+            if (s > best) {
+                best = s;
+                bestIdx = i;
+            }
+        }
+        if (best >= KEPT_IN_RULE) {
+            usedHead.add(bestIdx);
+            continue;
+        }
+        const moved = landing.some((l) => similarity(u.norm, l) >= MOVED_TO_CONTEXT);
+        if (!moved) {
+            findings.push({
+                code: 'passage-lost',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — not kept in the rule and not found in any declared load_context target`,
+            });
+        }
+    }
+
+    // ── Nothing genuinely new in the rule: a migration only removes ──
+    for (let i = 0; i < headUnits.length; i += 1) {
+        if (usedHead.has(i)) continue;
+        const u = headUnits[i]!;
+        const back = baseUnits.some((b) => similarity(b.norm, u.norm) >= KEPT_IN_RULE);
+        if (!back) {
+            findings.push({
+                code: 'unexplained-addition',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — new content in a safety-floor rule is a substantive edit, not a migration`,
+            });
+        }
+    }
+
+    return findings;
+}