@mmnto/totem 1.44.0 → 1.46.0

package/dist/ast-grep-query.js

@@ -2,7 +2,7 @@ import { Lang, parse } from '@ast-grep/napi';
 import { extensionToLanguage } from './ast-classifier.js';
 import { rethrowAsParseError } from './errors.js';
 // ─── Constants ──────────────────────────────────────
-const AST_GREP_HINT = 'Check the rule pattern syntax. If valid, the source file may contain syntax that crashes the parser.';
+const AST_GREP_HINT = "Check the rule pattern syntax. If valid, the source file may contain syntax that crashes the parser, OR the language isn't supported on this platform (e.g. Rust on Windows). Operator escape: run `totem lint --ast-parse-mode lenient` (or set TOTEM_LINT_AST_PARSE_MODE=lenient) to skip AST rules. Durable per-file degrade tracked at mmnto-ai/totem#1786.";
 // ─── Language mapping ───────────────────────────────
 /**
  * Map our `SupportedLanguage` string (e.g., `'typescript'`) to the

package/dist/ast-grep-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-grep-query.js","sourceRoot":"","sources":["../src/ast-grep-query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ast-grep-query.js","sourceRoot":"","sources":["../src/ast-grep-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAYlD,uDAAuD;AAEvD,MAAM,aAAa,GACjB,iWAAiW,CAAC;AAEpW,uDAAuD;AAEvD;;;;;;;;GAQG;AACH,SAAS,2BAA2B,CAAC,IAAY;IAC/C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,YAAY;YACf,OAAO,IAAI,CAAC,UAAU,CAAC;QACzB,KAAK,KAAK;YACR,OAAO,IAAI,CAAC,GAAG,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,IAAI,CAAC,UAAU,CAAC;QACzB;YACE,qEAAqE;YACrE,oEAAoE;YACpE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,2BAA2B,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA6B;IAC/D,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE5D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAaD,SAAS,YAAY,CACnB,IAAqC,EACrC,IAAiB,EACjB,gBAA0B,EAC1B,KAAe;IAEf,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE7C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE3C,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;YAE3C,KAAK,IAAI,OAAO,GAAG,SAAS,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;gBAC5D,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC1B,OAAO,CAAC,IAAI,CAAC;wBACX,UAAU,EAAE,OAAO;wBACnB,QAAQ,EAAE,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE;qBACnC,CAAC,CAAC;oBACH,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mBAAmB,CAAC,uBAAuB,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,uDAAuD;AAEvD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,GAAW,EACX,OAAoB,EACpB,gBAA0B;IAE1B,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAClC,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mBAAmB,CAAC,uBAAuB,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,GAAW,EACX,OAAiE,EACjE,aAA6B;IAE7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElC,IAAI,IAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mBAAmB,CAAC,6BAA6B,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,EAAE;QACvD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,qDAAqD;YACrD,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8DAA8D;YAC9D,4DAA4D;YAC5D,4DAA4D;YAC5D,wCAAwC;YACxC,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACpF,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

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"}