@mmnto/totem 1.44.0 → 1.45.0

package/dist/compile-cache.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Per-lesson compile cache (Proposal 281 — Per-Lesson Hash Stability).
+ *
+ * Short-circuits `totem lesson compile` for lessons whose source content is
+ * unchanged across compile runs. Eliminates the per-lesson hash rotation on
+ * unrelated lessons when a single lesson is added or modified.
+ *
+ * Cache key is layered (not composite):
+ *   1. `stableId` (when present — reserved for P280; P281 never writes it)
+ *   2. `sourceHash` — sha256 of normalized lesson source content
+ *   3. `fingerprint` — compile_worker_fingerprint from Proposal 278; mismatch
+ *      invalidates the entry (e.g., model bump rotates every entry once)
+ *
+ * `cli_version` is intentionally NOT part of the cache key — including it
+ * would invalidate every cohort bump, defeating the purpose. Per the impl
+ * contract § Cache key composition.
+ *
+ * Storage: `.totem/cache/compile-lesson/<sourceHash-first-16-chars>.json`,
+ * one entry per file, flat directory for v1 (see follow-on for fan-out
+ * cutover at ~1000 lessons).
+ *
+ * Emergency escape: set `TOTEM_DISABLE_COMPILE_CACHE=1` to bypass the
+ * cache entirely (lookup always returns null; write becomes a no-op).
+ * Emergency only — not a long-term flag.
+ */
+import { z } from 'zod';
+import type { CompileLessonResult } from './compile-lesson.js';
+/**
+ * Cache entry for one lesson's compile output.
+ *
+ * `stableId` is reserved for P280 (Wind-Tunnel Decoupling). P281 does not
+ * populate or query it. Reserving the slot from day one avoids a full cache
+ * re-key event when P280 lands; with the reservation, P280's integration is
+ * an additive lookup extension, not a refactor. Per
+ * `mmnto-ai/totem-strategy#387` § Dependencies (load-bearing).
+ */
+export declare const CacheEntrySchema: z.ZodObject<{
+    sourceHash: z.ZodString;
+    stableId: z.ZodOptional<z.ZodString>;
+    fingerprint: z.ZodString;
+    output: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+        status: z.ZodLiteral<"compiled">;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        status: z.ZodLiteral<"compiled">;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        status: z.ZodLiteral<"compiled">;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        status: z.ZodLiteral<"skipped">;
+        hash: z.ZodString;
+        reasonCode: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        status: z.ZodLiteral<"skipped">;
+        hash: z.ZodString;
+        reasonCode: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        status: z.ZodLiteral<"skipped">;
+        hash: z.ZodString;
+        reasonCode: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        status: z.ZodLiteral<"failed">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        status: z.ZodLiteral<"failed">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        status: z.ZodLiteral<"failed">;
+    }, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+        status: z.ZodLiteral<"noop">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        status: z.ZodLiteral<"noop">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        status: z.ZodLiteral<"noop">;
+    }, z.ZodTypeAny, "passthrough">>]>;
+    compiledAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    compiledAt: string;
+    sourceHash: string;
+    fingerprint: string;
+    output: z.objectOutputType<{
+        status: z.ZodLiteral<"compiled">;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | z.objectOutputType<{
+        status: z.ZodLiteral<"skipped">;
+        hash: z.ZodString;
+        reasonCode: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | z.objectOutputType<{
+        status: z.ZodLiteral<"failed">;
+    }, z.ZodTypeAny, "passthrough"> | z.objectOutputType<{
+        status: z.ZodLiteral<"noop">;
+    }, z.ZodTypeAny, "passthrough">;
+    stableId?: string | undefined;
+}, {
+    compiledAt: string;
+    sourceHash: string;
+    fingerprint: string;
+    output: z.objectInputType<{
+        status: z.ZodLiteral<"compiled">;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | z.objectInputType<{
+        status: z.ZodLiteral<"skipped">;
+        hash: z.ZodString;
+        reasonCode: z.ZodString;
+    }, z.ZodTypeAny, "passthrough"> | z.objectInputType<{
+        status: z.ZodLiteral<"failed">;
+    }, z.ZodTypeAny, "passthrough"> | z.objectInputType<{
+        status: z.ZodLiteral<"noop">;
+    }, z.ZodTypeAny, "passthrough">;
+    stableId?: string | undefined;
+}>;
+export type CacheEntry = Omit<z.infer<typeof CacheEntrySchema>, 'output'> & {
+    output: CompileLessonResult;
+};
+/**
+ * Discrete cache decisions, emitted per lesson per compile run as
+ * telemetry. Maps to the `compile_cache_decision` ledger event's
+ * `activity_name` field.
+ */
+export type CacheDecision = 'cache_hit' | 'cache_miss_source_changed' | 'cache_miss_fingerprint_changed' | 'cache_miss_force' | 'cache_miss_no_prior_record';
+/**
+ * Compute the cache key for a lesson source. SHA-256 of the content with
+ * line endings normalized to `\n` — same normalization as
+ * `generateInputHash` in compile-manifest.ts so both surfaces produce
+ * identical hashes for identical inputs.
+ */
+export declare function computeLessonSourceHash(lessonSource: string): string;
+/**
+ * Compose the hashable lesson source from a parsed lesson's heading and body.
+ * Use this from any call site that has a parsed `LessonInput`-shaped object to
+ * ensure runtime and migration paths produce identical hashes for the same
+ * lesson. Without a shared composition helper, the runtime hash (computed from
+ * `lesson.heading` + `lesson.body`) and a migration hash (computed from raw
+ * file content with `## Lesson — ` framing) would diverge — exactly the bug
+ * GCA R2 surfaced on `#1983`.
+ */
+export declare function composeLessonSourceForHash(heading: string, body: string): string;
+/**
+ * Resolve the on-disk cache file path for a given source hash. Pure;
+ * does not check existence. Callers handle missing files.
+ */
+export declare function cacheEntryPath(totemDir: string, sourceHash: string): string;
+interface LookupResult {
+    entry: CacheEntry | null;
+    decision: CacheDecision;
+}
+/**
+ * Look up a cache entry by `(sourceHash, fingerprint)`. Returns the entry
+ * with `decision: 'cache_hit'` on a clean hit, or `null` with a
+ * decision discriminating the miss reason.
+ *
+ * `stableId` parameter is reserved for P280 wiring — when present, the
+ * lookup tries the stable-id-indexed entry first, falling back to
+ * `sourceHash` on miss. v1 (this PR) never receives a non-undefined
+ * value here.
+ */
+export declare function lookupCacheEntry(totemDir: string, sourceHash: string, fingerprint: string, options?: {
+    force?: boolean;
+    stableId?: string;
+}): LookupResult;
+/**
+ * Persist a cache entry after a successful compile. Idempotent — writing
+ * the same `(sourceHash, fingerprint, output)` twice is a no-op-shaped
+ * overwrite. Fire-and-forget: I/O failures are surfaced via `onWarn` and
+ * never propagate (a failed cache write should not crash a compile).
+ *
+ * Returns `true` when the entry was successfully persisted, `false` on any
+ * I/O failure or when the cache is disabled via env var. Callers that need
+ * to track migration outcomes (e.g., `migrateFromCompiledRules`) inspect
+ * the return; callers that don't care can ignore it.
+ */
+export declare function writeCacheEntry(totemDir: string, entry: CacheEntry, onWarn?: (msg: string) => void): boolean;
+/**
+ * Construct a `CacheEntry` from the inputs of a fresh compile. Pure;
+ * callers persist via `writeCacheEntry`.
+ */
+export declare function buildCacheEntry(sourceHash: string, fingerprint: string, output: CompileLessonResult): CacheEntry;
+interface MigrationSeedInput {
+    /** Canonical lesson hash (rotation-prone). Carried for diagnostics only. */
+    lessonHash: string;
+    /**
+     * Parsed lesson heading — the `## Lesson — …` heading-text minus the
+     * leading `##` markdown. MUST match what `readAllLessons` (or equivalent
+     * parser) provides at runtime to the compile path. Composed with `body`
+     * via `composeLessonSourceForHash` to produce the same sourceHash the
+     * runtime cache lookup will compute.
+     */
+    heading: string;
+    /**
+     * Parsed lesson body — the content between the heading and the next
+     * lesson heading. MUST match what `readAllLessons` provides at runtime.
+     */
+    body: string;
+    /** The compile output to seed into the cache. */
+    output: CompileLessonResult;
+}
+interface MigrationResult {
+    seeded: number;
+    skipped: number;
+}
+/**
+ * One-shot seed migration: walk an existing compiled-rules.json + lesson
+ * sources, materialize the cache entries that would have been produced
+ * if the cache had existed from day one. After this step, the first
+ * post-migration compile run produces 100% cache hits and `compiled-
+ * rules.json` byte-for-byte matches its prior state.
+ *
+ * Idempotent — running twice with the same inputs writes the same entries
+ * a second time (overwrite). Per the impl contract § Migration sequence.
+ *
+ * Heading + body are taken separately (rather than a single raw-source
+ * string) to enforce the canonical `composeLessonSourceForHash` call shape.
+ * If migration accepted a free-form `lessonSource` string, the migration
+ * and runtime hash paths could diverge (per GCA R2 critical on `#1983`).
+ */
+export declare function migrateFromCompiledRules(totemDir: string, fingerprint: string, inputs: MigrationSeedInput[], onWarn?: (msg: string) => void): MigrationResult;
+/**
+ * List all cache-entry filenames currently on disk. Returns the file basenames
+ * (not full paths). Useful for `totem cache --prune-orphans` (out of scope for
+ * v1) and for test isolation cleanup.
+ */
+export declare function listCacheEntries(totemDir: string): string[];
+export {};
+//# sourceMappingURL=compile-cache.d.ts.map

package/dist/compile-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cache.d.ts","sourceRoot":"","sources":["../src/compile-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAsF/D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,EAAE,QAAQ,CAAC,GAAG;IAC1E,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,2BAA2B,GAC3B,gCAAgC,GAChC,kBAAkB,GAClB,4BAA4B,CAAC;AAIjC;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAc3E;AAED,UAAU,YAAY;IACpB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,YAAY,CA4Cd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAiBT;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,mBAAmB,GAC1B,UAAU,CAOZ;AAED,UAAU,kBAAkB;IAC1B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAAE,EAC5B,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC7B,eAAe,CA8BjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAM3D"}

package/dist/compile-cache.js

@@ -0,0 +1,325 @@
+/**
+ * Per-lesson compile cache (Proposal 281 — Per-Lesson Hash Stability).
+ *
+ * Short-circuits `totem lesson compile` for lessons whose source content is
+ * unchanged across compile runs. Eliminates the per-lesson hash rotation on
+ * unrelated lessons when a single lesson is added or modified.
+ *
+ * Cache key is layered (not composite):
+ *   1. `stableId` (when present — reserved for P280; P281 never writes it)
+ *   2. `sourceHash` — sha256 of normalized lesson source content
+ *   3. `fingerprint` — compile_worker_fingerprint from Proposal 278; mismatch
+ *      invalidates the entry (e.g., model bump rotates every entry once)
+ *
+ * `cli_version` is intentionally NOT part of the cache key — including it
+ * would invalidate every cohort bump, defeating the purpose. Per the impl
+ * contract § Cache key composition.
+ *
+ * Storage: `.totem/cache/compile-lesson/<sourceHash-first-16-chars>.json`,
+ * one entry per file, flat directory for v1 (see follow-on for fan-out
+ * cutover at ~1000 lessons).
+ *
+ * Emergency escape: set `TOTEM_DISABLE_COMPILE_CACHE=1` to bypass the
+ * cache entirely (lookup always returns null; write becomes a no-op).
+ * Emergency only — not a long-term flag.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod';
+// ─── Constants ──────────────────────────────────────
+// CACHE_DIR is resolved relative to `totemDir` (the already-configured
+// `.totem` location). Including `.totem` in this constant duplicated the
+// prefix and landed cache files at `<totemDir>/.totem/cache/...` instead of
+// `<totemDir>/cache/...`. Per CR R3 Major on `mmnto-ai/totem#1983`.
+const CACHE_DIR = path.join('cache', 'compile-lesson');
+const HASH_FILENAME_PREFIX_LENGTH = 16;
+const DISABLE_ENV_VAR = 'TOTEM_DISABLE_COMPILE_CACHE';
+/**
+ * Strict sha256-hex shape for `sourceHash`. Used to gate `cacheEntryPath`
+ * against path-traversal inputs (`/`, `..`, etc.) per CR R4 Major on
+ * `mmnto-ai/totem#1983`. Matches the digest computeLessonSourceHash emits.
+ */
+const SOURCE_HASH_RE = /^[a-f0-9]{64}$/;
+/**
+ * Best-effort wrapper around an optional warning callback. The cache module's
+ * non-throwing contract requires that a caller-supplied `onWarn` cannot
+ * propagate exceptions out of cache write/seed paths — even an `onWarn` that
+ * throws must not abort compile. Per CR R4 Major on `mmnto-ai/totem#1983`.
+ */
+function safeOnWarn(onWarn, message) {
+    if (onWarn === undefined)
+        return;
+    try {
+        onWarn(message);
+        // totem-context: intentional cleanup — onWarn must never propagate exceptions per the cache's non-throwing contract; swallow any caller-thrown errors silently.
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — onWarn must never propagate exceptions per the cache's non-throwing contract; swallow any caller-thrown errors silently.
+        void err;
+    }
+}
+// ─── Schema ─────────────────────────────────────────
+/**
+ * Validator for the `output` field. CompileLessonResult is a discriminated
+ * union (status: 'compiled' | 'skipped' | 'failed' | 'noop'); each variant
+ * carries required fields that downstream consumers dereference unconditionally
+ * (e.g., the cache-hit path reads `result.rule` for compiled outputs and
+ * `result.hash` / `result.reasonCode` for skipped outputs). A minimal
+ * status-only schema would accept truncated cache files like
+ * `{ output: { status: 'compiled' } }` and break the file's own "bad cache
+ * entry → miss, not crash" contract on the next lookup.
+ *
+ * Per CR R3 Major on `mmnto-ai/totem#1983`: validate the required-per-variant
+ * shape so structurally incomplete payloads are rejected upfront. `rule` is
+ * `z.unknown()` to avoid coupling this module to the full `CompiledRule`
+ * shape (changes to that schema must not invalidate every cohort's cache);
+ * variant-required fields like `hash` and `reasonCode` are typed concretely
+ * since they're the dereferences that would crash.
+ */
+const CompileLessonResultMinimalSchema = z.discriminatedUnion('status', [
+    z
+        .object({
+        status: z.literal('compiled'),
+        // `rule` MUST be a non-null object (the CompiledRule payload). z.unknown()
+        // would accept missing fields too, which defeats the contract — a payload
+        // like `{ status: 'compiled' }` would survive validation and crash the
+        // cache-hit path on `result.rule` dereference. `z.record(z.unknown())`
+        // requires an object without coupling to CompiledRule's exact shape.
+        rule: z.record(z.unknown()),
+    })
+        .passthrough(),
+    z
+        .object({
+        status: z.literal('skipped'),
+        hash: z.string(),
+        reasonCode: z.string(),
+    })
+        .passthrough(),
+    z
+        .object({
+        status: z.literal('failed'),
+    })
+        .passthrough(),
+    z
+        .object({
+        status: z.literal('noop'),
+    })
+        .passthrough(),
+]);
+/**
+ * Cache entry for one lesson's compile output.
+ *
+ * `stableId` is reserved for P280 (Wind-Tunnel Decoupling). P281 does not
+ * populate or query it. Reserving the slot from day one avoids a full cache
+ * re-key event when P280 lands; with the reservation, P280's integration is
+ * an additive lookup extension, not a refactor. Per
+ * `mmnto-ai/totem-strategy#387` § Dependencies (load-bearing).
+ */
+export const CacheEntrySchema = z.object({
+    sourceHash: z.string(),
+    stableId: z.string().optional(),
+    fingerprint: z.string(),
+    output: CompileLessonResultMinimalSchema,
+    compiledAt: z.string(),
+});
+// ─── Public API ─────────────────────────────────────
+/**
+ * Compute the cache key for a lesson source. SHA-256 of the content with
+ * line endings normalized to `\n` — same normalization as
+ * `generateInputHash` in compile-manifest.ts so both surfaces produce
+ * identical hashes for identical inputs.
+ */
+export function computeLessonSourceHash(lessonSource) {
+    // Normalization: collapse CRLF → LF ONLY. No trailing-whitespace trim — the
+    // canonical `generateInputHash` (`compile-manifest.ts`) and `lessonHash` (per
+    // `.gemini/styleguide.md` line 142) are both trailing-whitespace-sensitive.
+    // Trimming here would desynchronize the cache key from the canonical hashes:
+    // a whitespace-only edit would hit the cache (return stale lessonHash output)
+    // while the manifest pipeline would compute a fresh lessonHash for the same
+    // edit, breaking the deterministic link between lessons and rules.
+    // Reverses an over-correction from R1; per GCA R2 critical on `#1983`.
+    const normalized = lessonSource.replace(/\r\n/g, '\n');
+    return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+/**
+ * Compose the hashable lesson source from a parsed lesson's heading and body.
+ * Use this from any call site that has a parsed `LessonInput`-shaped object to
+ * ensure runtime and migration paths produce identical hashes for the same
+ * lesson. Without a shared composition helper, the runtime hash (computed from
+ * `lesson.heading` + `lesson.body`) and a migration hash (computed from raw
+ * file content with `## Lesson — ` framing) would diverge — exactly the bug
+ * GCA R2 surfaced on `#1983`.
+ */
+export function composeLessonSourceForHash(heading, body) {
+    return `${heading}\n${body}`;
+}
+/**
+ * Resolve the on-disk cache file path for a given source hash. Pure;
+ * does not check existence. Callers handle missing files.
+ */
+export function cacheEntryPath(totemDir, sourceHash) {
+    // Reject non-SHA inputs at the boundary (CR R4 Major on `mmnto-ai/totem#1983`).
+    // Without this, a sourceHash carrying `/` or `..` would flow through
+    // path.join() and escape `<totemDir>/cache/compile-lesson`, letting lookup or
+    // write touch arbitrary files. computeLessonSourceHash always emits the
+    // matching 64-char hex shape; this catches misuse where a caller hands us
+    // unvalidated input.
+    if (!SOURCE_HASH_RE.test(sourceHash)) {
+        throw new Error(`[Totem Error] Invalid sourceHash: expected 64-char sha256 hex digest, got ${JSON.stringify(sourceHash.slice(0, 80))}`);
+    }
+    const filename = `${sourceHash.slice(0, HASH_FILENAME_PREFIX_LENGTH)}.json`;
+    return path.join(totemDir, CACHE_DIR, filename);
+}
+/**
+ * Look up a cache entry by `(sourceHash, fingerprint)`. Returns the entry
+ * with `decision: 'cache_hit'` on a clean hit, or `null` with a
+ * decision discriminating the miss reason.
+ *
+ * `stableId` parameter is reserved for P280 wiring — when present, the
+ * lookup tries the stable-id-indexed entry first, falling back to
+ * `sourceHash` on miss. v1 (this PR) never receives a non-undefined
+ * value here.
+ */
+export function lookupCacheEntry(totemDir, sourceHash, fingerprint, options = {}) {
+    if (options.force === true) {
+        return { entry: null, decision: 'cache_miss_force' };
+    }
+    if (process.env[DISABLE_ENV_VAR] === '1') {
+        // totem-context: intentional cleanup — emergency escape hatch reverts
+        // cache to no-op without throwing.
+        return { entry: null, decision: 'cache_miss_no_prior_record' };
+    }
+    const filePath = cacheEntryPath(totemDir, sourceHash);
+    if (!fs.existsSync(filePath)) {
+        return { entry: null, decision: 'cache_miss_no_prior_record' };
+    }
+    let raw;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        raw = JSON.parse(content);
+        // totem-context: intentional cleanup — a bad cache entry must downgrade to a miss, never propagate; the cache is a side-channel optimization, not a load-bearing data path.
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — a bad cache entry must downgrade to a miss, never propagate; the cache is a side-channel optimization, not a load-bearing data path.
+        void err;
+        return { entry: null, decision: 'cache_miss_no_prior_record' };
+    }
+    const parsed = CacheEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        return { entry: null, decision: 'cache_miss_no_prior_record' };
+    }
+    // CacheEntrySchema validates the discriminator only; downstream casts back
+    // to the rich CompileLessonResult union type. See COMPILE_LESSON_STATUS.
+    const entry = parsed.data;
+    if (entry.sourceHash !== sourceHash) {
+        // File was named by hash but its content disagrees — corrupted state,
+        // treat as miss. Defensive against manual cache edits.
+        return { entry: null, decision: 'cache_miss_source_changed' };
+    }
+    if (entry.fingerprint !== fingerprint) {
+        return { entry: null, decision: 'cache_miss_fingerprint_changed' };
+    }
+    return { entry, decision: 'cache_hit' };
+}
+/**
+ * Persist a cache entry after a successful compile. Idempotent — writing
+ * the same `(sourceHash, fingerprint, output)` twice is a no-op-shaped
+ * overwrite. Fire-and-forget: I/O failures are surfaced via `onWarn` and
+ * never propagate (a failed cache write should not crash a compile).
+ *
+ * Returns `true` when the entry was successfully persisted, `false` on any
+ * I/O failure or when the cache is disabled via env var. Callers that need
+ * to track migration outcomes (e.g., `migrateFromCompiledRules`) inspect
+ * the return; callers that don't care can ignore it.
+ */
+export function writeCacheEntry(totemDir, entry, onWarn) {
+    if (process.env[DISABLE_ENV_VAR] === '1') {
+        return false;
+    }
+    try {
+        const filePath = cacheEntryPath(totemDir, entry.sourceHash);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(entry, null, 2) + '\n', 'utf-8');
+        return true;
+        // totem-context: intentional cleanup — cache writes are fire-and-forget; a failed write degrades to "no cache entry exists" on next lookup, never blocks compile.
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — cache writes are fire-and-forget; a failed write degrades to "no cache entry exists" on next lookup, never blocks compile.
+        const msg = err instanceof Error ? err.message : String(err);
+        safeOnWarn(onWarn, `Compile cache write failed: ${msg}`);
+        return false;
+    }
+}
+/**
+ * Construct a `CacheEntry` from the inputs of a fresh compile. Pure;
+ * callers persist via `writeCacheEntry`.
+ */
+export function buildCacheEntry(sourceHash, fingerprint, output) {
+    return {
+        sourceHash,
+        fingerprint,
+        output,
+        compiledAt: new Date().toISOString(),
+    };
+}
+/**
+ * One-shot seed migration: walk an existing compiled-rules.json + lesson
+ * sources, materialize the cache entries that would have been produced
+ * if the cache had existed from day one. After this step, the first
+ * post-migration compile run produces 100% cache hits and `compiled-
+ * rules.json` byte-for-byte matches its prior state.
+ *
+ * Idempotent — running twice with the same inputs writes the same entries
+ * a second time (overwrite). Per the impl contract § Migration sequence.
+ *
+ * Heading + body are taken separately (rather than a single raw-source
+ * string) to enforce the canonical `composeLessonSourceForHash` call shape.
+ * If migration accepted a free-form `lessonSource` string, the migration
+ * and runtime hash paths could diverge (per GCA R2 critical on `#1983`).
+ */
+export function migrateFromCompiledRules(totemDir, fingerprint, inputs, onWarn) {
+    if (process.env[DISABLE_ENV_VAR] === '1') {
+        return { seeded: 0, skipped: inputs.length };
+    }
+    let seeded = 0;
+    let skipped = 0;
+    for (const input of inputs) {
+        try {
+            const sourceForHash = composeLessonSourceForHash(input.heading, input.body);
+            const sourceHash = computeLessonSourceHash(sourceForHash);
+            const entry = buildCacheEntry(sourceHash, fingerprint, input.output);
+            // writeCacheEntry returns false on I/O failure or when the cache is
+            // disabled. Both count as "skipped" — seeded reflects entries actually
+            // persisted to disk, matching the operator's mental model of the
+            // post-migration cache hit rate.
+            if (writeCacheEntry(totemDir, entry, onWarn)) {
+                seeded += 1;
+            }
+            else {
+                skipped += 1;
+            }
+            // totem-context: intentional cleanup — migration is best-effort per-input; one bad lesson source must not abort seeding the rest. Failed inputs accumulate in `skipped` count and surface via safeOnWarn for operator visibility.
+        }
+        catch (err) {
+            // totem-context: intentional cleanup — migration is best-effort per-input; one bad lesson source must not abort seeding the rest. Failed inputs accumulate in `skipped` count and surface via safeOnWarn for operator visibility.
+            const msg = err instanceof Error ? err.message : String(err);
+            safeOnWarn(onWarn, `Compile cache seed skipped for ${input.lessonHash}: ${msg}`);
+            skipped += 1;
+        }
+    }
+    return { seeded, skipped };
+}
+/**
+ * List all cache-entry filenames currently on disk. Returns the file basenames
+ * (not full paths). Useful for `totem cache --prune-orphans` (out of scope for
+ * v1) and for test isolation cleanup.
+ */
+export function listCacheEntries(totemDir) {
+    const dir = path.join(totemDir, CACHE_DIR);
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs.readdirSync(dir).filter((name) => name.endsWith('.json'));
+}
+//# sourceMappingURL=compile-cache.js.map

package/dist/compile-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cache.js","sourceRoot":"","sources":["../src/compile-cache.ts"],"names":[],"mappings":"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"}

package/dist/compile-cache.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for the per-lesson compile cache (Proposal 281).
+ *
+ * Falsifying-metric test is `partial_mutation_invariant` — exercises the
+ * load-bearing claim that a +1-lesson PR produces a 1-row compiled-rules
+ * delta, not a 130-row rotation.
+ */
+export {};
+//# sourceMappingURL=compile-cache.test.d.ts.map

package/dist/compile-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-cache.test.d.ts","sourceRoot":"","sources":["../src/compile-cache.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}