@mmnto/totem 1.76.1 → 1.78.0

package/dist/parity-detect.js

@@ -39,8 +39,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import semver from 'semver';
 import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
 import { PARITY_SENSES } from './parity-manifest.js';
-import { resolveStrategyRoot } from './strategy-resolver.js';
+import { resolveStrategyRoot, } from './strategy-resolver.js';
 import { safeExec } from './sys/exec.js';
 import { resolveGitRoot } from './sys/git.js';
 // ─── Constants ──────────────────────────────────────────
@@ -60,6 +61,14 @@ const SIBLING_TOTEM_DIRNAME = 'totem';
  * — so `resolveCohortFloor` probes it via `resolveStrategyRoot`. mmnto-ai/totem#2108.
  */
 const SIBLING_STRATEGY_DIRNAME = 'totem-strategy';
+/**
+ * Parity dimension for toolchain-version rows. A row in this dimension that
+ * resolves NO deps package (e.g. `pnpm-engine-version`) pins its engine via the
+ * consumer's `packageManager` field instead — the toolchain reader senses it
+ * (mmnto-ai/totem#2115). `mmnto-cli-version` shares this dimension but resolves
+ * `@mmnto/cli`, so it stays on the deps path.
+ */
+export const TOOLCHAIN_DIMENSION = 'toolchain-version';
 /** Bounded git-command timeout for the origin-remote probe (matches `sys/git.ts`). */
 const GIT_REMOTE_TIMEOUT_MS = 15_000;
 /**
@@ -389,6 +398,12 @@ export function detectVersionPinnedContract(contract, ctx) {
     // standalone callers (tests). gitRoot is the floorRoot for a path locator.
     const packageName = ctx.packageName ?? packageNameForContract(contract, ctx.gitRoot);
     if (packageName === undefined) {
+        // A toolchain-version row with no deps package pins its engine via the
+        // consumer's `packageManager` field (e.g. pnpm-engine-version) — route it to
+        // the packageManager reader rather than skipping (mmnto-ai/totem#2115).
+        if (contract.dimension === TOOLCHAIN_DIMENSION) {
+            return detectPackageManagerToolchain(contract, ctx);
+        }
         return {
             status: 'skip',
             message: `not a deps version-pinned contract this slice handles (${contract.id})`,
@@ -477,6 +492,102 @@ export function detectVersionPinnedContract(contract, ctx) {
         remediation: `Bump the ${packageName} dependency to >= ${floor.version} and reinstall, then re-run totem doctor --parity.`,
     };
 }
+/**
+ * Parse a `<name>@<version>(+<hash>)?` corepack spec.
+ *
+ * Two modes (greptile review mmnto-ai/totem#2254):
+ *   - `exact: false` (default) — match the LEADING token, tolerating trailing
+ *     prose. For the manifest FLOOR, expressed as `pnpm@11.2.2 floor; pin >= floor`.
+ *   - `exact: true` — the WHOLE trimmed value must match. For the consumer's
+ *     `packageManager` field: corepack requires the entire value to be a valid
+ *     `<name>@<version>[+<hash>]`, so a declaration like `pnpm@11.2.2 garbage`
+ *     is MALFORMED — doctor must not report it current off a leading-token match.
+ *
+ * Returns undefined when no spec matches. Pure + total — never throws (mmnto-ai/totem#2115).
+ */
+function parsePackageManagerSpec(raw, opts = {}) {
+    if (typeof raw !== 'string')
+        return undefined;
+    // <name> = a package-manager slug; <version> = a semver core (+ optional
+    // prerelease/build that stops at whitespace or the `+hash` delimiter). Under
+    // `exact`, a trailing `$` rejects anything after the (optional) hash.
+    const pattern = opts.exact
+        ? /^([a-z][a-z0-9-]*)@(\d+\.\d+\.\d+[^\s+]*)(\+\S+)?$/i
+        : /^([a-z][a-z0-9-]*)@(\d+\.\d+\.\d+[^\s+]*)(\+\S+)?/i;
+    const m = raw.trim().match(pattern);
+    if (m?.[1] === undefined || m[2] === undefined)
+        return undefined;
+    return { name: m[1], version: m[2], hash: m[3] !== undefined ? m[3].slice(1) : undefined };
+}
+/**
+ * Sense a toolchain-version row that pins its engine via the consumer's
+ * `packageManager` field (e.g. `pnpm-engine-version`). The manifest row carries
+ * the floor in `expected-value-or-derivation` (`<engine>@<floor>` — there is no
+ * `packages/*​/package.json` to glob, `canonical-source` is null). Reads the
+ * DECLARATION only (`senses: declared`) — never probes the installed binary.
+ *
+ * Verdicts (claim-class bound to pin currency, mirroring the deps path):
+ *   - **pass** — consumer's `packageManager` engine matches + version ≥ floor.
+ *   - **warn** — engine matches but version < floor (stale).
+ *   - **skip** — no floor derivable / no `packageManager` field / unparseable pin
+ *     / a DIFFERENT engine (the floor doesn't apply) / invalid versions.
+ * NEVER throws, NEVER networks (mmnto-ai/totem#2115).
+ */
+function detectPackageManagerToolchain(contract, ctx) {
+    const floorSpec = parsePackageManagerSpec(contract.expectedValueOrDerivation);
+    if (floorSpec === undefined) {
+        return {
+            status: 'skip',
+            message: `${contract.id}: cohort floor not derivable from expected-value "${contract.expectedValueOrDerivation}"`,
+        };
+    }
+    const readPkg = ctx.readPackageJson ?? readPackageJson;
+    const consumerPkg = readPkg(path.join(ctx.cwd, 'package.json'));
+    const pmField = consumerPkg?.packageManager;
+    if (typeof pmField !== 'string' || pmField.trim().length === 0) {
+        return {
+            status: 'skip',
+            message: `${contract.id}: no packageManager field declared (honest-absent)`,
+        };
+    }
+    // Exact match: the WHOLE field must be a valid corepack pin — a malformed
+    // declaration (trailing junk after the version/hash) must not pass off a
+    // leading-token match (greptile mmnto-ai/totem#2254).
+    const pin = parsePackageManagerSpec(pmField, { exact: true });
+    if (pin === undefined) {
+        return {
+            status: 'skip',
+            message: `${contract.id}: packageManager "${pmField}" is not a parseable <name>@<version> pin`,
+        };
+    }
+    // A different engine → this row's floor simply doesn't apply here.
+    if (pin.name !== floorSpec.name) {
+        return {
+            status: 'skip',
+            message: `${contract.id}: consumer pins ${pin.name}@${pin.version}, not ${floorSpec.name} — cohort floor does not apply`,
+        };
+    }
+    if (semver.valid(pin.version) === null || semver.valid(floorSpec.version) === null) {
+        return {
+            status: 'skip',
+            message: `${contract.id}: unparseable version (pin "${pin.version}", floor "${floorSpec.version}")`,
+        };
+    }
+    // Hashless pins lose corepack integrity verification — surfaced as a note, not
+    // a failure (strategy#566 Greptile P2: hashless pins are a derive-before-authoring smell).
+    const hashNote = pin.hash === undefined ? ' (pin is hashless — corepack integrity not pinned)' : '';
+    if (semver.gte(pin.version, floorSpec.version)) {
+        return {
+            status: 'pass',
+            message: `${pin.name} engine pin current — packageManager ${pin.version} ≥ cohort floor ${floorSpec.version}${hashNote}`,
+        };
+    }
+    return {
+        status: 'warn',
+        message: `${pin.name} engine pin stale — packageManager ${pin.version} < cohort floor ${floorSpec.version}${hashNote}`,
+        remediation: `Bump the packageManager field to ${pin.name}@${floorSpec.version} (or a newer EXACT version — corepack requires an exact pin, not a range), then re-run totem doctor --parity.`,
+    };
+}
 /**
  * Resolve the consumer's installed `@mmnto/*` version. Walks UP the directory
  * tree from `cwd` reading `<dir>/node_modules/<pkg>/package.json#version` at each
@@ -1320,6 +1431,429 @@ export function detectValueEqualityContract(contract, ctx) {
         remediation: `Reconcile ${pathLabel} to ${rawExpected} in ${fileLabel}, or update the contract if the cohort canonical changed.`,
     };
 }
+// ─── Lock-content detector (mmnto-ai/totem#2107, strategy#754 content-hash rung) ──
+/**
+ * §6 normalize-before-hash for a distributed lock artifact — byte-for-byte the
+ * canonical `tools/build-strategy-doctrine.cjs` `normalize()` the publisher hashes
+ * with (the builder header MANDATES the verifier reconcile with it): CRLF / lone-CR
+ * → LF, strip trailing spaces/tabs per line, pop ALL trailing blank lines, join with
+ * exactly one terminal `\n`. Idempotent — re-normalizing a shipped (already-normalized)
+ * file is a no-op, so `hash(shipped)` holds cross-platform.
+ *
+ * DISTINCT from {@link normalizeManagedBlock} (which ALSO trims LEADING blank lines and
+ * leaves NO terminal newline) — the two must not be conflated; this one mirrors the lock
+ * publisher exactly. A golden test pins the byte-for-byte parity against a precomputed hash.
+ */
+export function normalizeLockArtifact(text) {
+    const lines = text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((l) => l.replace(/[ \t]+$/g, ''));
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.join('\n') + '\n';
+}
+/**
+ * Full sha256 of a normalized lock artifact, `sha256:`-prefixed hex — byte-for-byte
+ * the publisher's `sha256` helper (`'sha256:' + sha256hex(utf8)`). DISTINCT from
+ * {@link hashManagedBlock} (a 12-char SHORT hash for managed-block verdict records);
+ * the lock content-hash is the FULL digest the lock records.
+ */
+export function hashLockArtifact(normalized) {
+    return 'sha256:' + crypto.createHash('sha256').update(normalized, 'utf-8').digest('hex');
+}
+/** The single lock schema version this reader understands (mirrors the manifest gate). */
+export const SUPPORTED_LOCK_SCHEMA_VERSION = 1;
+const RawLockArtifactSchema = z.object({
+    path: z.string(),
+    'canonical-source': z.string(),
+    'content-hash': z.string(),
+    'last-published-sha': z.string(),
+});
+const RawStrategyDoctrineLockSchema = z.object({
+    'schema-version': z.number(),
+    package: z.string(),
+    version: z.string(),
+    published: z.string(),
+    artifacts: z.array(RawLockArtifactSchema),
+});
+/**
+ * Parse raw `strategy-doctrine.lock` JSON into a validated {@link StrategyDoctrineLock}.
+ * The `schema-version` gate runs BEFORE full validation so an incompatible future shape
+ * is rejected with a clear `unsupported-schema` signal rather than a confusing
+ * v1-shaped Zod failure (mirrors {@link parseParityManifest}). NEVER throws.
+ */
+export function parseStrategyDoctrineLock(jsonText) {
+    let doc;
+    try {
+        doc = JSON.parse(jsonText);
+        // totem-context: malformed lock JSON degrades to an `unparseable` signal (the sensor warns) — never a throw that would sink the doctor pipeline.
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message.split('\n')[0] : String(err);
+        return { status: 'unparseable', reason: `Invalid JSON: ${reason}` };
+    }
+    // schema-version gate BEFORE full validation (a non-mapping / missing version → unparseable).
+    const versionProbe = z.object({ 'schema-version': z.number() }).safeParse(doc);
+    if (!versionProbe.success) {
+        return {
+            status: 'unparseable',
+            reason: 'Lock is not a mapping with a numeric `schema-version`',
+        };
+    }
+    const rawVersion = versionProbe.data['schema-version'];
+    if (rawVersion !== SUPPORTED_LOCK_SCHEMA_VERSION) {
+        return { status: 'unsupported-schema', schemaVersion: rawVersion };
+    }
+    const parsed = RawStrategyDoctrineLockSchema.safeParse(doc);
+    if (!parsed.success) {
+        return {
+            status: 'unparseable',
+            reason: `Lock failed schema validation: ${parsed.error.issues
+                .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+                .join('; ')}`,
+        };
+    }
+    return {
+        status: 'ok',
+        lock: {
+            schemaVersion: parsed.data['schema-version'],
+            package: parsed.data.package,
+            version: parsed.data.version,
+            published: parsed.data.published,
+            artifacts: parsed.data.artifacts.map((a) => ({
+                path: a.path,
+                canonicalSource: a['canonical-source'],
+                contentHash: a['content-hash'],
+                lastPublishedSha: a['last-published-sha'],
+            })),
+        },
+    };
+}
+/** The canonical-source repo prefix this slice resolves for the vs-canonical layer. */
+const STRATEGY_CANONICAL_PREFIX = 'mmnto-ai/totem-strategy:';
+/** Default lock filename inside the `@mmnto/strategy-doctrine` package. */
+const STRATEGY_DOCTRINE_LOCK_FILENAME = 'strategy-doctrine.lock';
+/** The package name the lock-content slice senses (for honest-absent messages). */
+const STRATEGY_DOCTRINE_PACKAGE = '@mmnto/strategy-doctrine';
+/** A short, render-only form of a commit sha for provenance evidence. */
+function shortSha(sha) {
+    return /^[0-9a-f]{7,}$/i.test(sha) ? sha.slice(0, 8) : sha;
+}
+/**
+ * Parse a lock `canonical-source` into its strategy-repo-relative path, ONLY for the
+ * `mmnto-ai/totem-strategy:<path>` shape this slice resolves. Any other repo / shape →
+ * undefined (the vs-canonical layer skips that artifact rather than over-claiming).
+ */
+function parseStrategyCanonicalPath(canonicalSource) {
+    if (!canonicalSource.startsWith(STRATEGY_CANONICAL_PREFIX))
+        return undefined;
+    const rel = canonicalSource.slice(STRATEGY_CANONICAL_PREFIX.length).trim();
+    return rel.length > 0 ? rel : undefined;
+}
+/**
+ * Real-path resolver for the symlink-escape guard. Returns the canonicalized absolute
+ * path, or undefined when the target does not exist / is unresolvable.
+ */
+function defaultRealpath(p) {
+    try {
+        return fs.realpathSync(p);
+        // totem-context: a non-existent path (ENOENT) makes realpathSync throw — the honest "no real target to follow" signal; the caller keeps the lexical path and the subsequent read degrades to honest-absent, never a sensor crash.
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve `relPath` under `baseDir`, or undefined if it escapes (path-escape guard —
+ * a malformed lock must never read outside the package / sibling root). Also rejects a
+ * path that resolves to `baseDir` itself (a dir, not an artifact file).
+ *
+ * The lexical `path.relative` check proves only LEXICAL containment; a symlink INSIDE
+ * `baseDir` can still redirect the real read outside it (CR + greptile security review on
+ * mmnto-ai/totem#2256). So the real paths are re-checked: `realpath(baseDir)` canonicalizes
+ * pnpm's own symlinked `node_modules` (both sides resolve into `.pnpm`, so a legitimate
+ * install stays contained), while a malformed lock pointing THROUGH an escaping symlink
+ * fails the real-path containment. An absent target (`realpath` → undefined) keeps the
+ * lexical path — the subsequent read degrades to honest-absent, never a false escape.
+ */
+function resolveWithinDir(baseDir, relPath, realpath) {
+    const resolved = path.resolve(baseDir, relPath);
+    const rel = path.relative(baseDir, resolved);
+    if (rel.length === 0 || rel.startsWith('..') || path.isAbsolute(rel))
+        return undefined;
+    // Symlink-escape guard: re-check containment on the REAL paths.
+    const realTarget = realpath(resolved);
+    if (realTarget === undefined)
+        return resolved; // target absent → lexical guard holds; read honest-absents
+    const realBase = realpath(baseDir);
+    if (realBase === undefined)
+        return resolved; // base unresolvable → keep the lexical result
+    const realRel = path.relative(realBase, realTarget);
+    if (realRel.length === 0 || realRel.startsWith('..') || path.isAbsolute(realRel))
+        return undefined;
+    return resolved;
+}
+/**
+ * Local git-object existence check (`git cat-file -e <sha>^{commit}`) for the
+ * last-published-sha provenance note — NEVER networks, NEVER gates. A non-existent /
+ * non-commit object exits non-zero (the honest "not a local object" signal).
+ */
+function defaultGitObjectExists(sha, cwd) {
+    if (!/^[0-9a-f]{7,40}$/i.test(sha))
+        return false;
+    try {
+        safeExec('git', ['cat-file', '-e', `${sha}^{commit}`], { cwd, timeout: GIT_REMOTE_TIMEOUT_MS });
+        return true;
+        // totem-context: a missing / non-commit object makes `git cat-file -e` exit non-zero (safeExec throws) — the honest "not a local object" signal for a provenance-INFO note, never a sensor failure.
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The self-consistency line for ONE artifact: `sha256(normalize(packaged file)) == lock
+ * content-hash`. ALWAYS local — proves the shipped snapshot is internally intact. The
+ * `last-published-sha` rides as provenance-info evidence (never a comparator).
+ */
+function selfConsistencyLine(contract, artifact, packageDir, readFile, realpath) {
+    const lineName = `Parity: ${contract.id} (${artifact.path} · self)`;
+    const provenance = ` [last-published-sha ${shortSha(artifact.lastPublishedSha)}, provenance-info]`;
+    const pkg = contract.package ?? STRATEGY_DOCTRINE_PACKAGE;
+    const filePath = resolveWithinDir(packageDir, artifact.path, realpath);
+    if (filePath === undefined) {
+        return {
+            lineName,
+            verdict: {
+                status: 'warn',
+                message: `artifact path '${artifact.path}' escapes the package dir — refusing to read (lock may be malformed)`,
+            },
+        };
+    }
+    const raw = readFile(filePath);
+    if (raw === undefined) {
+        return {
+            lineName,
+            verdict: {
+                status: 'warn',
+                message: `packaged artifact ${artifact.path} absent — expected ${artifact.contentHash}${provenance}`,
+                remediation: `Reinstall ${pkg} to restore the packaged artifact, then re-run totem doctor --parity.`,
+            },
+        };
+    }
+    const actual = hashLockArtifact(normalizeLockArtifact(raw));
+    if (actual === artifact.contentHash) {
+        return {
+            lineName,
+            verdict: {
+                status: 'pass',
+                message: `packaged ${artifact.path} intact — ${artifact.contentHash}${provenance}`,
+            },
+        };
+    }
+    return {
+        lineName,
+        verdict: {
+            status: 'warn',
+            message: `integrity drift — recomputed ${actual} != lock ${artifact.contentHash} at ${artifact.path}${provenance}`,
+            remediation: `The packaged ${artifact.path} does not match its own lock record — reinstall ${pkg}.`,
+        },
+    };
+}
+/**
+ * The vs-canonical line for ONE artifact: the same recompute against the artifact's
+ * lock `canonical-source` within a resolved local `../totem-strategy` sibling. Runs ONLY
+ * when a sibling resolves (else SKIP honest-absent) — NEVER a fetch. A mismatch is
+ * currency drift (the pin lags local canonical), not an integrity failure.
+ */
+function vsCanonicalLine(contract, artifact, ctx, readFile, realpath, sibling) {
+    const lineName = `Parity: ${contract.id} (${artifact.path} · vs-canonical)`;
+    if (!sibling.resolved) {
+        return {
+            lineName,
+            verdict: {
+                status: 'skip',
+                message: `no local ../totem-strategy sibling resolvable — vs-canonical honest-absent (never a fetch): ${sibling.reason}`,
+            },
+        };
+    }
+    const relPath = parseStrategyCanonicalPath(artifact.canonicalSource);
+    if (relPath === undefined) {
+        return {
+            lineName,
+            verdict: {
+                status: 'skip',
+                message: `canonical-source '${artifact.canonicalSource}' is not a ${STRATEGY_CANONICAL_PREFIX}<path> ref — vs-canonical unprovable this slice`,
+            },
+        };
+    }
+    const canonicalPath = resolveWithinDir(sibling.path, relPath, realpath);
+    if (canonicalPath === undefined) {
+        return {
+            lineName,
+            verdict: {
+                status: 'warn',
+                message: `canonical-source path '${relPath}' escapes the strategy sibling root — refusing to read`,
+            },
+        };
+    }
+    const raw = readFile(canonicalPath);
+    const lpsNote = lastPublishedNote(artifact.lastPublishedSha, sibling.path, ctx);
+    if (raw === undefined) {
+        return {
+            lineName,
+            verdict: {
+                status: 'warn',
+                message: `canonical source ${relPath} absent under the resolved sibling (${sibling.path}) — vs-canonical drift${lpsNote}`,
+                remediation: `The local ../totem-strategy no longer carries ${relPath}; sync it, or this pin no longer reflects canonical.`,
+            },
+        };
+    }
+    const actual = hashLockArtifact(normalizeLockArtifact(raw));
+    if (actual === artifact.contentHash) {
+        return {
+            lineName,
+            verdict: {
+                status: 'pass',
+                message: `lock matches local strategy-canonical at ${relPath} — ${artifact.contentHash}${lpsNote}`,
+            },
+        };
+    }
+    return {
+        lineName,
+        verdict: {
+            status: 'warn',
+            message: `currency drift — lock ${artifact.contentHash} != current canonical ${actual} at ${relPath}${lpsNote}`,
+            remediation: `The consumed ${contract.package ?? STRATEGY_DOCTRINE_PACKAGE} pin lags the local ../totem-strategy canonical for ${relPath}; bump the pin when a new doctrine bundle publishes (a local sibling ahead of the published pin is expected currency drift, not a defect).`,
+        },
+    };
+}
+/** Render the last-published-sha provenance note (+ a local git-object existence check). */
+function lastPublishedNote(sha, strategyRoot, ctx) {
+    const exists = ctx.gitObjectExists ?? defaultGitObjectExists;
+    const resolvable = exists(sha, strategyRoot) ? 'resolvable in sibling' : 'not a local git object';
+    return ` [last-published-sha ${shortSha(sha)} ${resolvable}, provenance-info]`;
+}
+/**
+ * Detect drift for the `manifestation: content-hash` strategy-doctrine lock-content
+ * contract (mmnto-ai/totem#2107, strategy#754). Re-derives each distributed artifact's
+ * `content-hash` from the consumed lock via the §6 normalize+sha256 contract and compares
+ * it in TWO honest-absent layers, NEVER a fetch (Tenet 6/13):
+ *
+ *   - **self-consistency** (ALWAYS, local): `sha256(normalize(packaged file at path)) ==
+ *     its lock content-hash` — proves the shipped snapshot is internally intact.
+ *   - **vs-canonical** (ONLY when a local `../totem-strategy` sibling resolves): the same
+ *     recompute against the artifact's lock `canonical-source` within the sibling — proves
+ *     the pin still reflects strategy-canonical. SKIP honest-absent otherwise.
+ *
+ * Returns ONE line per artifact × per layer (the layers render SEPARATELY — a collapsed
+ * "content drift" verdict would over-claim which layer drifted). `last-published-sha` is
+ * provenance-INFO only (a LOCAL git-object existence note when a sibling resolves) — NEVER
+ * a gating comparator, NEVER `sha == HEAD`.
+ *
+ * Top-level honest-absent: not-a-consumer / repo-id-unresolvable → skip; package not
+ * installed → skip (the version-pin currency row senses the pin); lock absent while the
+ * package is present → warn (structurally incomplete); lock unparseable / unsupported-schema
+ * → warn.
+ *
+ * NEVER emits `fail` (the CLI edge owns `--strict` promotion). NEVER throws (reads
+ * degrade). NEVER networks.
+ */
+export function detectLockContentContract(contract, ctx) {
+    const idLine = (verdict) => [
+        { lineName: `Parity: ${contract.id}`, verdict },
+    ];
+    // ── Applicability: consumers scope (verbatim parity with the other detectors) ──
+    if (contract.consumers !== undefined) {
+        if (ctx.repoId === undefined) {
+            return idLine({
+                status: 'skip',
+                message: `cannot determine applicability — repo id unresolvable; contract is scoped to consumers [${contract.consumers.join(', ')}]`,
+            });
+        }
+        if (!contract.consumers.includes(ctx.repoId)) {
+            return idLine({
+                status: 'skip',
+                message: `cohort permits absence here (${ctx.repoId} not in consumers)`,
+            });
+        }
+    }
+    const readFile = ctx.readFile ?? readFileText;
+    const realpath = ctx.realpath ?? defaultRealpath;
+    const dirExists = ctx.dirExists ?? isDirectory;
+    const lockFileName = ctx.lockFileName ?? STRATEGY_DOCTRINE_LOCK_FILENAME;
+    const pkg = contract.package ?? STRATEGY_DOCTRINE_PACKAGE;
+    // ── Package not installed → honest-absent skip (the currency row senses the pin) ──
+    if (!dirExists(ctx.packageDir)) {
+        return idLine({
+            status: 'skip',
+            message: `${pkg} not installed at ${ctx.packageDir} — lock-content unprovable (the version-pin currency row senses the pin)`,
+        });
+    }
+    // ── Read the consumed lock (package present but lock absent → structurally incomplete) ──
+    // Route the lock filename through the same containment guard as artifacts/canonical
+    // sources so the exported `lockFileName` seam can't `../`-escape the package dir
+    // (CR review on mmnto-ai/totem#2256 — uniform "no raw path.join in this detector").
+    const lockPath = resolveWithinDir(ctx.packageDir, lockFileName, realpath);
+    if (lockPath === undefined) {
+        return idLine({
+            status: 'warn',
+            message: `${lockFileName} escapes the package dir — refusing to read (lock filename may be malformed)`,
+        });
+    }
+    const lockRaw = readFile(lockPath);
+    if (lockRaw === undefined) {
+        return idLine({
+            status: 'warn',
+            message: `${pkg} installed but ${lockFileName} is absent — distributed package is structurally incomplete`,
+            remediation: `Reinstall ${pkg} (a publish without its lock is a packaging defect), then re-run totem doctor --parity.`,
+        });
+    }
+    // ── Parse (unparseable / unsupported-schema → warn; never throw) ──
+    const parsed = parseStrategyDoctrineLock(lockRaw);
+    if (parsed.status === 'unparseable') {
+        return idLine({
+            status: 'warn',
+            message: `${lockFileName} is unparseable — ${parsed.reason}`,
+            remediation: `Reinstall ${pkg} to restore a valid lock, then re-run totem doctor --parity.`,
+        });
+    }
+    if (parsed.status === 'unsupported-schema') {
+        return idLine({
+            status: 'warn',
+            message: `${lockFileName} schema-version ${parsed.schemaVersion} unsupported (this doctor understands ${SUPPORTED_LOCK_SCHEMA_VERSION}) — content-hash unprovable`,
+            remediation: `Upgrade @mmnto/cli to a build that understands lock schema ${parsed.schemaVersion}, or reinstall a compatible ${pkg}.`,
+        });
+    }
+    const { lock } = parsed;
+    // Wrong-package guard (CR review on mmnto-ai/totem#2256): a stale / mispackaged lock from
+    // ANOTHER package could self-consistently `pass` (its hashes match its own bundled files),
+    // masking a packaging defect. The lock declaring a different package than the one it was
+    // loaded under IS the structural inconsistency this sensor exists to catch.
+    if (lock.package !== pkg) {
+        return idLine({
+            status: 'warn',
+            message: `${lockFileName} declares package ${lock.package} but was loaded from ${pkg} — distributed package is structurally inconsistent`,
+            remediation: `Reinstall ${pkg} to restore the correct lock, then re-run totem doctor --parity.`,
+        });
+    }
+    if (lock.artifacts.length === 0) {
+        return idLine({
+            status: 'warn',
+            message: `${lockFileName} declares no artifacts[] — nothing to verify (structurally incomplete)`,
+        });
+    }
+    // ── Resolve the vs-canonical sibling ONCE (honest-absent; never a fetch) ──
+    const resolveRoot = ctx.resolveStrategyRootFn ?? resolveStrategyRoot;
+    const sibling = resolveRoot(ctx.gitRoot, { gitRoot: ctx.gitRoot });
+    // ── Per artifact × per layer (rendered SEPARATELY — no collapsed verdict) ──
+    const lines = [];
+    for (const artifact of lock.artifacts) {
+        lines.push(selfConsistencyLine(contract, artifact, ctx.packageDir, readFile, realpath));
+        lines.push(vsCanonicalLine(contract, artifact, ctx, readFile, realpath, sibling));
+    }
+    return lines;
+}
 // ─── Shared filesystem helpers ──────────────────────────
 /** Read a UTF-8 text file, or undefined on any read failure (honest-absent). */
 function readFileText(absPath) {