@mmnto/totem 1.26.1 → 1.28.0

package/dist/substrate-resolver.js

@@ -0,0 +1,216 @@
+/**
+ * Substrate-path resolver (mmnto-ai/totem#1820, ADR-100 Phase C).
+ *
+ * Single source of truth for "where are the substrate `.handoff/` and
+ * `.journal/` directories on disk." After ADR-100, both directories live
+ * in a sibling `mmnto-ai/totem-substrate` repo; the original in-repo paths
+ * are sediment-frozen per ADR-100 Q7C and serve as fallback during the
+ * sediment window.
+ *
+ * Resolution walks four precedence layers:
+ *
+ *   1. **env** — `TOTEM_SUBSTRATE_PATH`.
+ *   2. **config** — `TotemConfig.substratePath`.
+ *   3. **sibling-walk** — walk up to 3 levels from `configRoot` looking for
+ *      `<parent>/totem-substrate/`.
+ *   4. **repo-local sediment** — `<configRoot>/.handoff/` and
+ *      `<configRoot>/.journal/`.
+ *
+ * Layers 1-3 require full substrate shape (a git metadata subdir plus
+ * `.handoff/` and `.journal/` subdirs) to gate against stale empty
+ * clones. Layer 4 (sediment) accepts partial state — `.handoff/` alone
+ * OR `.journal/` alone is valid and returns the populated dir with the
+ * missing one as null.
+ *
+ * Returns a `SubstratePaths` record whose `source` field discriminates
+ * the resolution outcome. ADR-090 graceful degradation: if all four
+ * layers fail, returns `{ handoffRoot: null, journalRoot: null,
+ * source: 'none' }`. Consumers handle null per their existing contract.
+ *
+ * Pure utility. No caching, no side effects, no logging — same stance as
+ * `resolveStrategyRoot` (PR mmnto-ai/totem#1743). Each call walks the chain
+ * from scratch so a process that mutates `process.env` mid-run sees the
+ * new value next call.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveGitRoot } from './sys/git.js';
+const ENV_VAR = 'TOTEM_SUBSTRATE_PATH';
+const SIBLING_DIRNAME = 'totem-substrate';
+const SIBLING_WALK_MAX_DEPTH = 3;
+/**
+ * Substrate shape predicate — a directory qualifies as a real substrate
+ * clone only when it carries the git metadata subdir AND both the
+ * handoff and journal subdirs. Used by layers 1-3 (env, config,
+ * sibling-walk) to reject stale empty directories that would otherwise
+ * satisfy a plain `isDirectory` check.
+ *
+ * Layer 4 (repo-local sediment) does NOT use this — sediment lives
+ * inside the product repo so the nested git metadata isn't there.
+ */
+function validateSubstrateShape(dir) {
+    // totem-context: shape gate (substrate clone detection), not a gitRoot probe — the rule that flags raw git-metadata-dir checks is targeted at resolveGitRoot-style probing, not clone-shape detection.
+    // `fs.existsSync` (not `isDirectory`) handles submodule + linked-worktree
+    // setups where the git metadata path is a pointer file rather than a
+    // directory. Per GCA review on mmnto-ai/totem#1821.
+    return (fs.existsSync(path.join(dir, '.git')) && // totem-context: shape gate, not gitRoot probe; submodule/worktree compat.
+        isDirectory(path.join(dir, '.handoff')) &&
+        isDirectory(path.join(dir, '.journal')));
+}
+/**
+ * `fs.statSync` raises on missing paths and on EACCES/ENOTDIR; treat any
+ * stat failure as "not a directory" and let the resolver fall through to
+ * the next layer. Matches the `resolveStrategyRoot` pattern.
+ */
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+        // totem-context: intentional fall-through — stat failures (ENOENT, EACCES, ENOTDIR) are the precedence-chain "miss" signal; rethrowing would force every consumer to wrap the resolver in try/catch for a routine outcome.
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read `TOTEM_SUBSTRATE_PATH` from the env map. Whitespace-only values
+ * are treated as unset so a `TOTEM_SUBSTRATE_PATH="   "` accident does
+ * not short-circuit the precedence chain.
+ */
+function readEnvValue(env) {
+    const raw = env[ENV_VAR];
+    if (typeof raw === 'string' && raw.trim().length > 0)
+        return raw;
+    return undefined;
+}
+/**
+ * Resolve a raw value (env or config) to an absolute path anchored at
+ * `configRoot`. Absolute values are returned normalized as-is; relative
+ * values are joined against the anchor. Mirrors `resolveStrategyRoot`'s
+ * `resolveValue` pattern.
+ */
+function resolveValue(raw, anchor) {
+    const trimmed = raw.trim();
+    if (path.isAbsolute(trimmed))
+        return path.normalize(trimmed);
+    return path.normalize(path.join(anchor, trimmed));
+}
+/**
+ * Build the substrate-shaped `SubstratePaths` record for a resolved
+ * substrate directory. Both paths populated; source is 'substrate'.
+ */
+function substrateResult(dir) {
+    return {
+        handoffRoot: path.normalize(path.join(dir, '.handoff')),
+        journalRoot: path.normalize(path.join(dir, '.journal')),
+        source: 'substrate',
+    };
+}
+/**
+ * Walk the four-layer precedence chain. Returns a `SubstratePaths` record
+ * whose `source` discriminates the resolution outcome.
+ *
+ * Layer order: env → config → sibling-walk (up to 3 levels from
+ * `configRoot`) → repo-local sediment (`<configRoot>/.handoff/` and
+ * `<configRoot>/.journal/`).
+ *
+ * @param configRoot Anchor for relative env / config values and start
+ *   of the sibling-walk. Typically the directory containing
+ *   `totem.config.ts` (the project root).
+ */
+export function resolveSubstratePaths(configRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const config = options.config;
+    // Two distinct anchors per CR review on PR mmnto-ai/totem#1821:
+    //
+    // - `gitAnchor` (lazy, repo-wide) — anchors relative env/config values
+    //   and the sibling-walk start. Mirrors `resolveStrategyRoot` (PR
+    //   mmnto-ai/totem#1743): `options.gitRoot` test seam →
+    //   `resolveGitRoot(configRoot)` probe → `configAnchor` fallback. The
+    //   user's intent for a relative `TOTEM_SUBSTRATE_PATH=../...` is
+    //   "relative to my repo," not "relative to my subpackage."
+    //
+    // - `configAnchor` (eager, caller-scoped) — anchors layer 4 (repo-local
+    //   sediment). Per the trigger spec, sediment lives at
+    //   `<configRoot>/.handoff/` and `<configRoot>/.journal/`. In a
+    //   monorepo subpackage where `configRoot != gitRoot`, anchoring layer
+    //   4 at `gitRoot` would look for sediment in the wrong directory.
+    const configAnchor = path.resolve(configRoot);
+    let cachedGitAnchor;
+    const getGitAnchor = () => {
+        if (cachedGitAnchor !== undefined)
+            return cachedGitAnchor;
+        let gitRoot;
+        if (options.gitRoot !== undefined) {
+            gitRoot = options.gitRoot;
+        }
+        else {
+            try {
+                gitRoot = resolveGitRoot(configRoot);
+                // totem-context: intentional fall-through — resolveGitRoot throws on permission errors / corrupted index; fall back to configAnchor so the precedence chain still completes.
+            }
+            catch {
+                gitRoot = null;
+            }
+        }
+        cachedGitAnchor = gitRoot ?? configAnchor;
+        return cachedGitAnchor;
+    };
+    // Layer 1 — env var. Validate substrate shape; fall through on shape miss.
+    const envValue = readEnvValue(env);
+    if (envValue !== undefined) {
+        const candidate = resolveValue(envValue, getGitAnchor());
+        if (validateSubstrateShape(candidate)) {
+            return substrateResult(candidate);
+        }
+    }
+    // Layer 2 — config field. The `typeof string` guard is load-bearing:
+    // a JS caller (or unsafe cast) could pass a non-string `substratePath`
+    // that would crash `.trim()` with `TypeError`. Treating non-string as
+    // unset preserves the contract. Mirrors `resolveStrategyRoot`.
+    if (typeof config?.substratePath === 'string' && config.substratePath.trim().length > 0) {
+        const candidate = resolveValue(config.substratePath, getGitAnchor());
+        if (validateSubstrateShape(candidate)) {
+            return substrateResult(candidate);
+        }
+    }
+    // Layer 3 — sibling-walk. Walk up to SIBLING_WALK_MAX_DEPTH levels
+    // from `gitAnchor` looking for `<parent>/totem-substrate/`. Cap
+    // protects against pathological resolution when the anchor is
+    // accidentally a deep subpath.
+    let walkAnchor = getGitAnchor();
+    for (let i = 0; i < SIBLING_WALK_MAX_DEPTH; i++) {
+        const parent = path.dirname(walkAnchor);
+        // path.dirname returns the path itself at filesystem root; break to
+        // avoid an infinite loop if SIBLING_WALK_MAX_DEPTH outruns the
+        // tree depth.
+        if (parent === walkAnchor)
+            break;
+        const candidate = path.normalize(path.join(parent, SIBLING_DIRNAME));
+        if (validateSubstrateShape(candidate)) {
+            return substrateResult(candidate);
+        }
+        walkAnchor = parent;
+    }
+    // Layer 4 — repo-local sediment, anchored at `configAnchor` (NOT
+    // `gitAnchor`). Per-directory presence: either `.handoff/` alone OR
+    // `.journal/` alone is a valid partial sediment result; consumer
+    // reads non-null only. The Phase B cutover left both as
+    // `.gitkeep`-only frozen markers in the product repos, so
+    // existence-of-directory (not existence-of-content) is the right
+    // gate here — matches `isDirectory`'s semantic on layers 1-3.
+    const localHandoff = path.normalize(path.join(configAnchor, '.handoff'));
+    const localJournal = path.normalize(path.join(configAnchor, '.journal'));
+    const handoffExists = isDirectory(localHandoff);
+    const journalExists = isDirectory(localJournal);
+    // totem-context: boolean-or for presence check; nullish-coalescing rule is targeted at numeric-metric defaults, not booleans.
+    if (handoffExists || journalExists) {
+        return {
+            handoffRoot: handoffExists ? localHandoff : null,
+            journalRoot: journalExists ? localJournal : null,
+            source: 'repo-local',
+        };
+    }
+    // All four layers failed — graceful degradation per ADR-090.
+    return { handoffRoot: null, journalRoot: null, source: 'none' };
+}
+//# sourceMappingURL=substrate-resolver.js.map

package/dist/substrate-resolver.js.map

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

package/dist/substrate-resolver.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for `resolveSubstratePaths` (mmnto-ai/totem#1820, ADR-100 Phase C).
+ *
+ * Filesystem-driven; tests construct real temp directories for each
+ * precedence layer (env / config / sibling-walk / repo-local sediment)
+ * and pass `env` / `config` via the option seams to avoid touching
+ * `process.env`. Per-test cleanup wipes the tmp tree so a re-run starts
+ * from a clean state.
+ */
+export {};
+//# sourceMappingURL=substrate-resolver.test.d.ts.map

package/dist/substrate-resolver.test.d.ts.map

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

package/dist/substrate-resolver.test.js

@@ -0,0 +1,406 @@
+/**
+ * Tests for `resolveSubstratePaths` (mmnto-ai/totem#1820, ADR-100 Phase C).
+ *
+ * Filesystem-driven; tests construct real temp directories for each
+ * precedence layer (env / config / sibling-walk / repo-local sediment)
+ * and pass `env` / `config` via the option seams to avoid touching
+ * `process.env`. Per-test cleanup wipes the tmp tree so a re-run starts
+ * from a clean state.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { resolveSubstratePaths, } from './substrate-resolver.js';
+import { cleanTmpDir } from './test-utils.js';
+const ENV_KEYS = ['TOTEM_SUBSTRATE_PATH'];
+let tmpRoot;
+let configRoot;
+let parent;
+function emptyEnv() {
+    return {};
+}
+function mkDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+    return p;
+}
+/**
+ * Build a fully-shaped substrate clone at `dir` — git metadata subdir +
+ * handoff + journal subdirs all present. Returns the absolute dir path.
+ */
+function mkSubstrate(dir) {
+    mkDir(dir);
+    // totem-context: building a fake substrate fixture for shape-gate test; not a gitRoot probe — see substrate-resolver.ts validateSubstrateShape JSDoc.
+    mkDir(path.join(dir, '.git'));
+    mkDir(path.join(dir, '.handoff'));
+    mkDir(path.join(dir, '.journal'));
+    return dir;
+}
+beforeEach(() => {
+    // Layout:
+    //   <tmpRoot>/
+    //     parent/
+    //       repo/             ← configRoot
+    //       totem-substrate/  ← sibling target (per-test)
+    //     elsewhere/          ← env / config target (per-test)
+    // totem-context: test fixture only; agents do not consume this temp dir.
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-substrate-resolver-'));
+    parent = mkDir(path.join(tmpRoot, 'parent'));
+    configRoot = mkDir(path.join(parent, 'repo'));
+});
+afterEach(() => {
+    cleanTmpDir(tmpRoot);
+    for (const k of ENV_KEYS)
+        delete process.env[k];
+});
+// ─── Task 1 — substrate shape validation ───────────────────────────────────
+describe('resolveSubstratePaths shape validation', () => {
+    // TEST DIRECTIVE (Task 1): a valid directory missing one of the three
+    // expected subdirs MUST be rejected by the internal validator and the
+    // resolver MUST fall through to the next layer.
+    it('rejects empty directory without required substrate shape', () => {
+        const incomplete = mkDir(path.join(tmpRoot, 'incomplete-substrate'));
+        // totem-context: fake substrate fixture; shape gate, not gitRoot probe.
+        mkDir(path.join(incomplete, '.git'));
+        mkDir(path.join(incomplete, '.handoff'));
+        // .journal intentionally missing → shape invalid
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: incomplete },
+        });
+        // Env layer rejects on shape miss; no other layers populated → 'none'.
+        expect(result).toEqual({
+            handoffRoot: null,
+            journalRoot: null,
+            source: 'none',
+        });
+    });
+    it('rejects directory missing the git subdir (sibling-walk layer)', () => {
+        // No git metadata subdir — looks like an empty `totem-substrate` dir
+        // created by accident, not a real clone.
+        const stale = mkDir(path.join(parent, 'totem-substrate'));
+        mkDir(path.join(stale, '.handoff'));
+        mkDir(path.join(stale, '.journal'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        // Sibling-walk layer rejects on shape miss; no other layers populated → 'none'.
+        expect(result.source).toBe('none');
+    });
+    it('accepts a fully-shaped substrate (env layer)', () => {
+        const real = mkSubstrate(path.join(tmpRoot, 'elsewhere'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: real },
+        });
+        expect(result).toEqual({
+            handoffRoot: path.normalize(path.join(real, '.handoff')),
+            journalRoot: path.normalize(path.join(real, '.journal')),
+            source: 'substrate',
+        });
+    });
+});
+// ─── Task 2 — precedence cascade ───────────────────────────────────────────
+describe('resolveSubstratePaths precedence', () => {
+    it('returns substrate source when TOTEM_SUBSTRATE_PATH points to a valid clone', () => {
+        const target = mkSubstrate(path.join(tmpRoot, 'env-target'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: target },
+        });
+        expect(result.source).toBe('substrate');
+        expect(result.handoffRoot).toBe(path.normalize(path.join(target, '.handoff')));
+    });
+    it('returns substrate source when env is unset and config.substratePath is set', () => {
+        const target = mkSubstrate(path.join(tmpRoot, 'config-target'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: emptyEnv(),
+            config: { substratePath: target },
+        });
+        expect(result.source).toBe('substrate');
+        expect(result.handoffRoot).toBe(path.normalize(path.join(target, '.handoff')));
+    });
+    it('prefers env over config when both are set', () => {
+        const envTarget = mkSubstrate(path.join(tmpRoot, 'env-pref'));
+        const configTarget = mkSubstrate(path.join(tmpRoot, 'config-pref'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: envTarget },
+            config: { substratePath: configTarget },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(envTarget, '.handoff')));
+    });
+    it('returns substrate source when env+config unset and ../totem-substrate exists', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result).toEqual({
+            handoffRoot: path.normalize(path.join(sibling, '.handoff')),
+            journalRoot: path.normalize(path.join(sibling, '.journal')),
+            source: 'substrate',
+        });
+    });
+    it('prefers config over sibling-walk when both resolve', () => {
+        mkSubstrate(path.join(parent, 'totem-substrate'));
+        const configTarget = mkSubstrate(path.join(tmpRoot, 'config-pref'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: emptyEnv(),
+            config: { substratePath: configTarget },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(configTarget, '.handoff')));
+    });
+    it('falls through env when path is missing — config takes over', () => {
+        const configTarget = mkSubstrate(path.join(tmpRoot, 'config-fallback'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: path.join(tmpRoot, 'does-not-exist') },
+            config: { substratePath: configTarget },
+        });
+        expect(result.source).toBe('substrate');
+        expect(result.handoffRoot).toBe(path.normalize(path.join(configTarget, '.handoff')));
+    });
+    it('treats whitespace-only env value as unset', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: '   ' },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('treats whitespace-only config value as unset', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: emptyEnv(),
+            config: { substratePath: '   ' },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('treats non-string config.substratePath as unset (R5 — runtime type guard)', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: emptyEnv(),
+            // totem-context: cast is the SUBJECT of the test — proves the resolver's runtime guard catches non-string inputs that bypass TS type-checking.
+            config: { substratePath: 42 },
+        });
+        expect(result.source).toBe('substrate');
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+});
+// ─── Sibling-walk depth cap ────────────────────────────────────────────────
+describe('resolveSubstratePaths sibling-walk', () => {
+    // TEST DIRECTIVE (Task 2): a configRoot deeper than 3 levels from the
+    // substrate sibling MUST NOT find it via walk; falls through.
+    it('bounds sibling discovery to maximum 3 directory levels', () => {
+        // Layout: <tmpRoot>/totem-substrate/ + <tmpRoot>/a/b/c/d/e/repo
+        // Walk from repo: depth 1 = e, 2 = d, 3 = c. Looking for
+        // c/totem-substrate, d/totem-substrate, e/totem-substrate at each
+        // level. None is at <tmpRoot>/, so depth-cap stops the walk
+        // before finding the substrate at <tmpRoot>/totem-substrate.
+        mkSubstrate(path.join(tmpRoot, 'totem-substrate'));
+        const deepRepo = mkDir(path.join(tmpRoot, 'a', 'b', 'c', 'd', 'e', 'repo'));
+        const result = resolveSubstratePaths(deepRepo, { env: emptyEnv() });
+        // Walk doesn't find substrate within 3 levels → falls through to
+        // repo-local sediment (which is also absent) → 'none'.
+        expect(result.source).toBe('none');
+    });
+    it('finds sibling within 3 levels — depth 1 (parent)', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('finds sibling within 3 levels — depth 3 (grandparent of grandparent)', () => {
+        // Layout: <tmpRoot>/totem-substrate/ + <tmpRoot>/a/b/repo
+        // Walk: depth 1 = b, 2 = a, 3 = tmpRoot. Substrate at depth 3.
+        const sibling = mkSubstrate(path.join(tmpRoot, 'totem-substrate'));
+        const repo = mkDir(path.join(tmpRoot, 'a', 'b', 'repo'));
+        const result = resolveSubstratePaths(repo, { env: emptyEnv() });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('does not loop infinitely when configRoot is at filesystem root', () => {
+        // path.dirname('/') === '/' on posix; 'C:\\' on win32. Walk loop must
+        // detect dirname-equals-self and break, not spin forever.
+        const rootishPath = path.parse(tmpRoot).root;
+        const result = resolveSubstratePaths(rootishPath, { env: emptyEnv() });
+        // No assertion on source — just proving the call returns within the
+        // test's effective timeout.
+        expect(result).toBeDefined();
+    });
+});
+// ─── Layer 4 — repo-local sediment ─────────────────────────────────────────
+describe('resolveSubstratePaths repo-local sediment', () => {
+    it('returns repo-local source when both .handoff/ and .journal/ exist locally', () => {
+        mkDir(path.join(configRoot, '.handoff'));
+        mkDir(path.join(configRoot, '.journal'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result).toEqual({
+            handoffRoot: path.normalize(path.join(configRoot, '.handoff')),
+            journalRoot: path.normalize(path.join(configRoot, '.journal')),
+            source: 'repo-local',
+        });
+    });
+    it('returns partial repo-local when only .journal/ exists', () => {
+        mkDir(path.join(configRoot, '.journal'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result).toEqual({
+            handoffRoot: null,
+            journalRoot: path.normalize(path.join(configRoot, '.journal')),
+            source: 'repo-local',
+        });
+    });
+    it('returns partial repo-local when only .handoff/ exists', () => {
+        mkDir(path.join(configRoot, '.handoff'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result).toEqual({
+            handoffRoot: path.normalize(path.join(configRoot, '.handoff')),
+            journalRoot: null,
+            source: 'repo-local',
+        });
+    });
+    it('anchors layer-4 sediment at configRoot, not gitRoot (CR R2 catch)', () => {
+        // Monorepo-subpackage scenario: configRoot is a deep subpath; gitRoot
+        // is the monorepo root. Sediment lives under configRoot per the
+        // trigger spec (`<configRoot>/.handoff/`), NOT under gitRoot.
+        // Pre-fix bug (CR R2): both anchors collapsed to gitRoot, so layer 4
+        // looked for sediment in the wrong directory.
+        //
+        // Place sediment ONLY under configRoot. If the resolver mistakenly
+        // anchors at gitRoot, sediment lookup fails and we fall through to
+        // 'none'. Correct behavior: 'repo-local' with paths under configRoot.
+        const subpackage = mkDir(path.join(configRoot, 'packages', 'mcp'));
+        mkDir(path.join(subpackage, '.handoff'));
+        mkDir(path.join(subpackage, '.journal'));
+        // gitRoot is `parent` (monorepo root); no sediment there.
+        const result = resolveSubstratePaths(subpackage, {
+            env: emptyEnv(),
+            gitRoot: parent, // pin gitAnchor distinct from configAnchor
+        });
+        expect(result).toEqual({
+            handoffRoot: path.normalize(path.join(subpackage, '.handoff')),
+            journalRoot: path.normalize(path.join(subpackage, '.journal')),
+            source: 'repo-local',
+        });
+    });
+    it('repo-local accepts placeholder-marker-only sediment dirs (Phase B cutover state)', () => {
+        // Sediment-frozen dirs in product repos retain a placeholder marker
+        // after Phase B markers landed. The resolver must accept these as
+        // valid fallback (the consumer is responsible for handling
+        // empty-content cases).
+        const handoff = mkDir(path.join(configRoot, '.handoff'));
+        // totem-context: writing a tracked-empty placeholder for fixture; not a hooks-manager bypass.
+        fs.writeFileSync(path.join(handoff, '.gitkeep'), '');
+        const journal = mkDir(path.join(configRoot, '.journal'));
+        // totem-context: writing a tracked-empty placeholder for fixture; not a hooks-manager bypass.
+        fs.writeFileSync(path.join(journal, '.gitkeep'), '');
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result.source).toBe('repo-local');
+        expect(result.handoffRoot).toBe(path.normalize(handoff));
+        expect(result.journalRoot).toBe(path.normalize(journal));
+    });
+});
+// ─── ADR-090 graceful degradation ──────────────────────────────────────────
+describe('resolveSubstratePaths graceful degradation', () => {
+    it('returns source: none when all four layers fail (ADR-090 contract)', () => {
+        // No env, no config, no sibling, no repo-local sediment.
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(result).toEqual({
+            handoffRoot: null,
+            journalRoot: null,
+            source: 'none',
+        });
+    });
+    it('tolerates configRoot at tmp root without crashing', () => {
+        // Ensure resolver tolerates a configRoot whose dirname() may not exist
+        // as a real ancestor (filesystem root edge cases). The body assertion
+        // proves the call returned cleanly under any source.
+        const result = resolveSubstratePaths(tmpRoot, { env: emptyEnv() });
+        expect(result.source).toMatch(/^(repo-local|none)$/);
+    });
+});
+// ─── Path normalization ────────────────────────────────────────────────────
+describe('resolveSubstratePaths path normalization', () => {
+    // Mixed-separator handling is Windows-specific: on POSIX, backslash is a
+    // valid filename character and `/` is the only path separator, so the
+    // resolver-level mixed-sep behavior only matters on `process.platform ===
+    // 'win32'`. Coverage for `path.normalize`-driven cleanup is provided by
+    // the segment-collapse test below, which works on every platform.
+    const onWindows = process.platform === 'win32' ? it : it.skip;
+    onWindows('normalizes mixed separators in env value (Windows-only)', () => {
+        const target = mkSubstrate(path.join(tmpRoot, 'mixed-seps'));
+        const mixed = target.replace('\\', '/');
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: mixed },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(target, '.handoff')));
+    });
+    it('normalizes . and .. segments in env value', () => {
+        const target = mkSubstrate(path.join(tmpRoot, 'nested', 'real-substrate'));
+        const noisy = path.join(tmpRoot, 'nested', '.', 'real-substrate', '..', 'real-substrate');
+        const result = resolveSubstratePaths(configRoot, {
+            env: { TOTEM_SUBSTRATE_PATH: noisy },
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(target, '.handoff')));
+    });
+    it('returns absolute paths regardless of caller anchor', () => {
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, { env: emptyEnv() });
+        expect(path.isAbsolute(result.handoffRoot ?? '')).toBe(true);
+        expect(path.isAbsolute(result.journalRoot ?? '')).toBe(true);
+        // Sanity: the absolute path points at the sibling we built.
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('uses options.gitRoot test seam to override the natural configRoot anchor', () => {
+        // The lazy gitRoot probe lets monorepo subpackage callers anchor at
+        // the real repo root. To prove the seam overrides configRoot, we
+        // place substrate near the SEAM, NOT near configRoot — if the seam
+        // is honored, the walk finds substrate; if the seam is ignored and
+        // configRoot becomes the anchor, the walk fails.
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        // Build an unrelated path whose dirname has NO substrate near it.
+        const unrelated = mkDir(path.join(tmpRoot, 'unrelated', 'somewhere'));
+        const result = resolveSubstratePaths(unrelated, {
+            env: emptyEnv(),
+            // Seam pins anchor at `configRoot` (= parent/repo); walk from
+            // there finds substrate at `parent/totem-substrate`.
+            gitRoot: configRoot,
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('falls back to absolutized configRoot when gitRoot is explicitly null', () => {
+        // `gitRoot: null` simulates the "configRoot is not in a git repo"
+        // case — production callers in fresh clones or non-git dirs hit this
+        // path. The resolver must absolutize configRoot (path.resolve) so the
+        // walk doesn't break on a relative anchor.
+        const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+        const result = resolveSubstratePaths(configRoot, {
+            env: emptyEnv(),
+            gitRoot: null,
+        });
+        expect(result.handoffRoot).toBe(path.normalize(path.join(sibling, '.handoff')));
+    });
+    it('absolutizes a relative configRoot before walking (review-1 catch)', () => {
+        // Pre-fix bug: `path.dirname('.') === '.'`, so a relative anchor
+        // broke the sibling-walk loop on the first iteration. The resolver
+        // must absolutize via `path.resolve` so the walk reaches real ancestors.
+        const prevCwd = process.cwd();
+        try {
+            // chdir into configRoot so '.' resolves to it. The sibling at
+            // `parent/totem-substrate/` becomes reachable via the walk's
+            // first iteration once `path.resolve('.')` produces an absolute path.
+            const sibling = mkSubstrate(path.join(parent, 'totem-substrate'));
+            process.chdir(configRoot);
+            const result = resolveSubstratePaths('.', { env: emptyEnv() });
+            // Path equality on the absolutized resolution. Use realpathSync so
+            // macOS `/tmp` ↔ `/private/tmp` symlink discrepancies don't break
+            // assertions on `process.chdir`-resolved paths.
+            const expected = fs.realpathSync.native(path.join(sibling, '.handoff'));
+            const actual = result.handoffRoot ? fs.realpathSync.native(result.handoffRoot) : null;
+            expect(actual).toBe(expected);
+            expect(path.isAbsolute(result.handoffRoot ?? '')).toBe(true);
+        }
+        finally {
+            process.chdir(prevCwd);
+        }
+    });
+});
+// ─── Type compile-checks (no runtime behavior) ─────────────────────────────
+describe('resolveSubstratePaths type contract', () => {
+    it('accepts SubstrateResolverOptions with all optional fields omitted', () => {
+        // Compile-time check — these calls just need to typecheck and not throw.
+        const opts = {};
+        const cfg = {};
+        expect(() => resolveSubstratePaths(configRoot, opts)).not.toThrow();
+        expect(() => resolveSubstratePaths(configRoot, { config: cfg })).not.toThrow();
+    });
+});
+//# sourceMappingURL=substrate-resolver.test.js.map