@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/__tests__/memory-resolver-precedence.test.js

@@ -1,26 +1,30 @@
-// Regression matrix for `resolveMemoryDoc`'s precedence rule: exact identity
-// and direct physical-path matches are resolved NEAREST-FIRST across the whole
-// scope stack before bare-leaf fallback is considered. This prevents a nested
-// doc's coincidental leaf from hiding a farther canonical identity while still
-// ensuring a nearer worktree's own physical `AGENTS.md` beats a farther doc
-// named exactly `AGENTS`, even when the nearer file's explicit frontmatter
-// identity has diverged from its physical filename.
+// Regression matrix for exact canonical memory identity: a project store
+// declares a namespace and every document in it answers ONLY at
+// `<namespace>/<local name>`. Nothing else addresses it — not the old
+// unqualified name, not the physical path, not a unique leaf, not a
+// scope-prefixed spelling, and not a trailing `/INDEX` (a directory's own
+// document answers at the directory name). Linked worktrees that declare the
+// same repository namespace expose the same canonical identities: source order
+// picks the address winner, every candidate stays ordered and reachable through
+// its exact store.
 //
-// Fixture shape: two nested project scopes on disk —
-//   root/.crouter/memory/...       (farther project scope)
-//   root/child/.crouter/memory/... (nearer project scope; cwd lives here)
-// `findProjectScopeRoots` walks every ancestor `.crouter/` from cwd upward, so
-// from `root/child` the resolved stack is exactly [child, root], nearest first
-// — no profile indirection needed to exercise multi-scope precedence.
+// Fixture shape: one repository's main checkout plus a linked worktree, both
+// declaring `namespace: root`. The cwd is the linked worktree and the main
+// checkout enters the precedence stack through the selected profile:
+//   main/.crouter/memory/...                 (farther store, namespace root)
+//   linked/.crouter/memory/...               (nearer store, namespace root; cwd)
+//   linked/grandchild/.crouter/memory/...    (metadata-free nested store)
 //
-// Run: node --import tsx/esm --test src/core/__tests__/memory-resolver-precedence.test.ts
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/memory-resolver-precedence.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { gitSync } from '../git.js';
+import { createProfile } from '../profiles/manifest.js';
 import { resetScopeCache } from '../scope.js';
-import { resolveMemoryDoc, resolveMemoryDocs } from '../memory-resolver.js';
+import { loadMemoryStoreView, openProjectMemoryStore, resolveMemoryCandidates, resolveMemoryDoc, resolveMemoryDocInStore, resolveMemoryDocs, } from '../memory-resolver.js';
 let home;
 let base;
 let root;
@@ -28,42 +32,58 @@ let child;
 let grandchild;
 let prevCwd;
 let prevHome;
-function writeDoc(path, body, frontmatterName) {
+let prevProfile;
+function writeDoc(path, body, frontmatter) {
     mkdirSync(join(path, '..'), { recursive: true });
-    const fm = frontmatterName ? `---\nname: ${frontmatterName}\n---\n` : '';
+    const fm = frontmatter ? `---\n${frontmatter}\n---\n` : '';
     writeFileSync(path, `${fm}${body}\n`, 'utf8');
 }
+function initWorktreeRepository(main, linked) {
+    mkdirSync(main, { recursive: true });
+    assert.equal(gitSync(['-C', main, 'init', '-q'], undefined).status, 0);
+    writeFileSync(join(main, 'README.md'), 'fixture\n', 'utf8');
+    assert.equal(gitSync(['-C', main, 'add', 'README.md'], undefined).status, 0);
+    assert.equal(gitSync(['-C', main, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.com', 'commit', '-qm', 'initial'], undefined).status, 0);
+    assert.equal(gitSync(['-C', main, 'worktree', 'add', '-q', '-b', 'linked', linked], undefined).status, 0);
+}
+function assertNotFound(name) {
+    assert.throws(() => resolveMemoryDoc(name), (err) => err.code === 'not_found', `${name} must not resolve`);
+}
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-home-'));
     prevHome = process.env.HOME;
+    prevProfile = process.env.CRTR_PROFILE_ID;
     process.env.HOME = home;
-    // A farther user-scope preference doc, shared across every test below (the
-    // fixture for the --kind shadowing regression case).
+    // A wider user-scope doc whose name a project doc used to shadow.
     mkdirSync(join(home, '.crouter', 'memory'), { recursive: true });
     writeFileSync(join(home, '.crouter', 'memory', 'testing-stance.md'), '---\nkind: preference\n---\nUSER PREFERENCE BODY\n', 'utf8');
 });
 beforeEach(() => {
     resetScopeCache();
     base = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-')));
-    root = join(base, 'root');
-    child = join(root, 'child');
+    root = join(base, 'main');
+    child = join(base, 'linked');
     grandchild = join(child, 'grandchild');
-    mkdirSync(root, { recursive: true });
-    mkdirSync(child, { recursive: true });
+    initWorktreeRepository(root, child);
     mkdirSync(grandchild, { recursive: true });
-    // --- root (FARTHER project scope) ---
-    writeDoc(join(root, '.crouter', 'memory', 'AGENTS.md'), 'ROOT AGENTS BODY'); // derived name "AGENTS"
-    writeDoc(join(root, '.crouter', 'memory', 'shared.md'), 'ROOT SHARED BODY'); // derived name "shared"
-    writeDoc(join(root, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'ROOT TASTE BODY'); // derived "taste/document-substrate"
-    writeDoc(join(root, '.crouter', 'memory', 'taste', 'INDEX.md'), 'ROOT TASTE INDEX'); // derived "taste/INDEX"
-    // --- child (NEARER project scope; cwd resolves here) ---
-    writeDoc(join(child, '.crouter', 'memory', 'AGENTS.md'), 'CHILD AGENTS BODY', 'crouter'); // physical AGENTS.md, identity diverged to "crouter"
-    writeDoc(join(child, '.crouter', 'memory', 'sub', 'shared.md'), 'CHILD SUB SHARED BODY'); // derived "sub/shared" — leaf "shared"
-    writeDoc(join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'CHILD TASTE BODY'); // derived "taste/document-substrate"
-    writeDoc(join(child, '.crouter', 'memory', 'taste', 'INDEX.md'), 'CHILD TASTE INDEX'); // derived "taste/INDEX"
-    writeDoc(join(child, '.crouter', 'memory', 'testing-stance.md'), 'CHILD TESTING STANCE BODY'); // frontmatter-less, kind defaults to "knowledge"
-    // --- grandchild (nearest still; own migrated slashed identity) ---
-    writeDoc(join(grandchild, '.crouter', 'memory', 'AGENTS.md'), 'GRANDCHILD SUBDIR BODY', 'root/subdir');
+    // --- main (FARTHER store, namespace root) ---
+    writeDoc(join(root, '.crouter', 'memory', 'INDEX.md'), 'ROOT STORE INDEX', 'namespace: root');
+    writeDoc(join(root, '.crouter', 'memory', 'shared.md'), 'ROOT SHARED BODY'); // root/shared
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'INDEX.md'), 'ROOT TASTE INDEX'); // root/taste
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'ROOT TASTE BODY');
+    writeDoc(join(root, '.crouter', 'memory', 'dup.md'), 'ROOT DUP PREFERENCE', 'kind: preference'); // root/dup
+    // --- linked (NEARER store; the same repository namespace means its docs are
+    //     alternate physical candidates for the SAME canonical identities) ---
+    writeDoc(join(child, '.crouter', 'memory', 'INDEX.md'), 'CHILD STORE INDEX', 'namespace: root');
+    writeDoc(join(child, '.crouter', 'memory', 'dup.md'), 'CHILD DUP KNOWLEDGE'); // root/dup
+    writeDoc(join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'CHILD TASTE BODY');
+    writeDoc(join(child, '.crouter', 'memory', 'testing-stance.md'), 'CHILD TESTING STANCE BODY');
+    writeDoc(join(child, '.crouter', 'memory', 'AGENTS.md'), 'CHILD AGENTS BODY', 'name: notes/agents');
+    // --- grandchild (metadata-free nested store: identity comes from linked's
+    //     repository-root declaration) ---
+    writeDoc(join(grandchild, '.crouter', 'memory', 'orphan.md'), 'ORPHAN BODY');
+    process.env.CRTR_PROFILE_ID = createProfile('precedence', [{ path: root, memory: 'content' }]).profileId;
+    resetScopeCache();
     prevCwd = process.cwd();
 });
 after(() => {
@@ -75,119 +95,130 @@ after(() => {
         delete process.env.HOME;
     else
         process.env.HOME = prevHome;
+    if (prevProfile === undefined)
+        delete process.env.CRTR_PROFILE_ID;
+    else
+        process.env.CRTR_PROFILE_ID = prevProfile;
 });
-test('a physical-path query whose nearest match diverged in identity from a farther same-derived-name doc resolves to the NEAREST physical file (the AGENTS shadowing case)', () => {
+test('a project doc answers only at its full canonical name', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const byPhysicalName = resolveMemoryDoc('AGENTS');
-        assert.equal(byPhysicalName.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
-        assert.match(byPhysicalName.body, /CHILD AGENTS BODY/);
-        const byExplicitIdentity = resolveMemoryDoc('crouter');
-        assert.equal(byExplicitIdentity.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
-        assert.match(byExplicitIdentity.body, /CHILD AGENTS BODY/);
+        const doc = resolveMemoryDoc('root/taste/document-substrate');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'));
+        assert.equal(doc.localName, 'taste/document-substrate');
+        assert.match(doc.body, /CHILD TASTE BODY/);
+        assertNotFound('taste/document-substrate'); // the old unqualified project name
+        assertNotFound('document-substrate'); // a unique leaf
+        assertNotFound('project/root/taste/document-substrate'); // a scope-prefixed spelling
+        assertNotFound('root/taste/document-substrate.md'); // a physical path spelling
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('batch resolution preserves direct-path precedence over a farther matching identity', () => {
+test("a directory's own document answers at the directory name, a store root at its namespace", () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDocs(['AGENTS']).get('AGENTS');
-        assert.equal(doc?.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
-        assert.match(doc?.body ?? '', /CHILD AGENTS BODY/);
+        const dir = resolveMemoryDoc('root/taste');
+        assert.equal(dir.path, join(root, '.crouter', 'memory', 'taste', 'INDEX.md'));
+        assert.equal(dir.representation, 'directory-index');
+        assert.equal(dir.routingAnchor, 'root/taste');
+        assert.match(dir.body, /ROOT TASTE INDEX/);
+        const storeRoot = resolveMemoryDoc('root');
+        assert.equal(storeRoot.path, join(child, '.crouter', 'memory', 'INDEX.md'));
+        assert.equal(storeRoot.localName, '');
+        assert.match(storeRoot.body, /CHILD STORE INDEX/);
+        assertNotFound('root/taste/INDEX');
+        assertNotFound('root/INDEX');
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('a migrated nested doc resolves by its explicit slashed identity', () => {
-    process.chdir(grandchild);
+test('a namespaced project doc no longer shadows a wider unqualified name', () => {
+    process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDoc('root/subdir');
-        assert.equal(doc.path, join(grandchild, '.crouter', 'memory', 'AGENTS.md'));
-        assert.equal(doc.name, 'root/subdir');
-        assert.match(doc.body, /GRANDCHILD SUBDIR BODY/);
+        const wider = resolveMemoryDoc('testing-stance');
+        assert.equal(wider.scope, 'user');
+        assert.match(wider.body, /USER PREFERENCE BODY/);
+        const project = resolveMemoryDoc('root/testing-stance');
+        assert.equal(project.scope, 'project');
+        assert.match(project.body, /CHILD TESTING STANCE BODY/);
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('a plain path-named doc with no explicit name resolves to the nearest copy', () => {
+test('equal canonical identities keep every candidate in source order and stay exact-store targetable', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDoc('taste/document-substrate');
-        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'));
-        assert.match(doc.body, /CHILD TASTE BODY/);
+        const set = resolveMemoryCandidates('root/dup');
+        assert.deepEqual(set.candidates.map((d) => d.path), [join(child, '.crouter', 'memory', 'dup.md'), join(root, '.crouter', 'memory', 'dup.md')], 'nearest-first candidate order, both linked-worktree stores retained');
+        assert.equal(set.winner.path, join(child, '.crouter', 'memory', 'dup.md'));
+        const store = openProjectMemoryStore(root);
+        assert.equal(store.namespace, 'root');
+        assert.equal(store.mountStatus, 'ready');
+        const nonWinner = resolveMemoryDocInStore('root/dup', store);
+        assert.equal(nonWinner.path, join(root, '.crouter', 'memory', 'dup.md'));
+        assert.match(nonWinner.body, /ROOT DUP PREFERENCE/);
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('a bare-directory query does not resolve to a doc — directories answer with listings, not INDEX.md', () => {
+test('--kind is a constraint across equal-canonical candidates, not a post-filter', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        assert.throws(() => resolveMemoryDoc('taste'), (err) => {
-            assert.equal(err.code, 'not_found');
-            return true;
-        });
+        // The nearer candidate is frontmatter-less (kind defaults to knowledge) and
+        // must be SKIPPED, not returned and not not_found.
+        const doc = resolveMemoryDoc('root/dup', { kind: 'preference' });
+        assert.equal(doc.path, join(root, '.crouter', 'memory', 'dup.md'));
+        assert.match(doc.body, /ROOT DUP PREFERENCE/);
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test("an explicit '<dir>/INDEX' identity resolves to that physical INDEX.md", () => {
-    // The assembled memory tree addresses a directory INDEX by its extensionless
-    // resolver identity, so `<dir>/INDEX` must resolve to the physical INDEX.md
-    // and report back the same identifier it was asked for.
+test('an explicit frontmatter name is store-local and composes under the namespace', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDoc('taste/INDEX');
-        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'INDEX.md'));
-        assert.equal(doc.name, 'taste/INDEX');
-        assert.match(doc.body, /CHILD TASTE INDEX/);
+        const doc = resolveMemoryDoc('root/notes/agents');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(doc.localName, 'notes/agents');
+        assertNotFound('notes/agents'); // the explicit name is not an address by itself
+        assertNotFound('root/AGENTS'); // nor is the physical filename
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('--kind skips a nearer wrong-kind (frontmatter-less, kind-defaulted) doc and resolves the farther matching-kind doc', () => {
-    process.chdir(child);
+test('a metadata-free nested project store mounts under its derived prefix', () => {
+    process.chdir(grandchild);
     resetScopeCache();
     try {
-        // No --kind: nearest scope's frontmatter-less copy wins, as always.
-        const noKind = resolveMemoryDoc('testing-stance');
-        assert.equal(noKind.scope, 'project');
-        assert.match(noKind.body, /CHILD TESTING STANCE BODY/);
-        // --kind preference: the nearer project doc defaults to kind "knowledge"
-        // and must be SKIPPED (not returned, not not_found) so resolution keeps
-        // walking outward to the farther user-scope doc that actually carries
-        // kind: preference.
-        const withKind = resolveMemoryDoc('testing-stance', { kind: 'preference' });
-        assert.equal(withKind.scope, 'user');
-        assert.match(withKind.body, /USER PREFERENCE BODY/);
+        const store = openProjectMemoryStore(grandchild);
+        assert.equal(store.mountStatus, 'ready');
+        assert.equal(store.namespace, 'root/grandchild');
+        assert.equal(resolveMemoryDoc('root/grandchild/orphan').path, join(grandchild, '.crouter', 'memory', 'orphan.md'));
+        assert.deepEqual(loadMemoryStoreView(store, true).docs.map((d) => d.name), ['root/grandchild/orphan'], 'exact-store inspection uses the same derived identity');
     }
     finally {
         process.chdir(prevCwd);
     }
 });
-test('an exact identity match beats a nearer document reached only by leaf fallback', () => {
+test('batch resolution takes canonical names only', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        // Nearest scope's doc lives at "sub/shared.md" (derived name "sub/shared",
-        // leaf "shared"); the farther scope's doc lives at top-level "shared.md"
-        // (derived name "shared", an exact identity match for the bare query).
-        const doc = resolveMemoryDoc('shared');
-        assert.equal(doc.path, join(root, '.crouter', 'memory', 'shared.md'));
-        assert.equal(doc.name, 'shared');
-        assert.match(doc.body, /ROOT SHARED BODY/);
+        const resolved = resolveMemoryDocs(['root/shared', 'shared']);
+        assert.equal(resolved.get('root/shared')?.path, join(root, '.crouter', 'memory', 'shared.md'));
+        assert.equal(resolved.get('shared'), undefined);
     }
     finally {
         process.chdir(prevCwd);

package/dist/core/__tests__/nested-store-discovery.test.js

@@ -72,16 +72,18 @@ test('non-git owner: the walk finds a store at the depth cap and stops below it'
 test('resolveMemoryDocForTarget resolves a nested doc only with includeDescendants', () => {
     const proj = join(fakeHome, 'proj');
     mkdirSync(join(proj, '.crouter', 'memory'), { recursive: true }); // project scope engages
+    writeFileSync(join(proj, '.crouter', 'memory', 'INDEX.md'), '---\nnamespace: proj\n---\nPROJ STORE\n');
     const nestedMemory = join(proj, 'sub', '.crouter', 'memory');
     mkdirSync(nestedMemory, { recursive: true });
+    writeFileSync(join(nestedMemory, 'INDEX.md'), '# nested store\n');
     writeFileSync(join(nestedMemory, 'guide.md'), '---\nkind: knowledge\n' +
         'name: nested-guide\n' +
         'when-and-why-to-read: When working in sub, this knowledge should be read because it carries the subsystem constraints.\n---\n' +
         'NESTED GUIDE BODY\n');
     const target = { cwd: proj, profileId: null, nodeId: null };
-    assert.throws(() => resolveMemoryDocForTarget('nested-guide', target, {}), (e) => e instanceof CrtrError && e.code === 'not_found', 'without the opt-in the flat ancestor stack does not see the nested store');
-    const doc = resolveMemoryDocForTarget('nested-guide', target, { includeDescendants: true });
-    assert.equal(doc.name, 'nested-guide', 'resolves by explicit frontmatter name');
+    assert.throws(() => resolveMemoryDocForTarget('proj/sub/nested-guide', target, {}), (e) => e instanceof CrtrError && e.code === 'not_found', 'without the opt-in the flat ancestor stack does not see the nested store');
+    const doc = resolveMemoryDocForTarget('proj/sub/nested-guide', target, { includeDescendants: true });
+    assert.equal(doc.name, 'proj/sub/nested-guide', 'the root namespace composes with the nested owner path and local name');
     assert.equal(doc.scope, 'project');
     assert.ok(doc.body.includes('NESTED GUIDE BODY'));
 });

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -14,6 +14,7 @@ import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs } from '../substrate/on-read-node.js';
+import { emptyContextExposureState, exposureTarget } from '../substrate/injected-store.js';
 let canvasHome;
 let fakeHome;
 let prevHomeEnv;
@@ -58,7 +59,7 @@ test('a store nested in the crouter home does not leak into a canvas-artifact re
     const reportFile = join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports', 'r.md');
     mkdirSync(join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports'), { recursive: true });
     writeFileSync(reportFile, '# a node report\n');
-    const rendered = renderOnReadDocs(node, reportFile, new Map());
+    const rendered = renderOnReadDocs(node, reportFile, exposureTarget(emptyContextExposureState(), 'transcript'));
     assert.ok(!rendered.includes('PRIVATE ASSISTANT MEMORY MUST NOT LEAK'), `crouter-home-nested store must not surface on a canvas read; got: ${rendered}`);
     assert.ok(!rendered.includes('private-thing'), `crouter-home-nested store name must not surface on a canvas read; got: ${rendered}`);
 });

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -1,8 +1,8 @@
-// On-read context surfaces at most once per conversation. The dedup set lives
-// at nodes/<id>/injected-docs.json so a process resumed onto the same transcript
-// rehydrates it, while a fresh transcript clears it. The same loader resolves a
-// doc's identity with the explicit-name-then-path-fallback rule the boot resolver
-// uses (schema.ts's resolveDocName), never deriving `name` from the path alone.
+// On-read context surfaces once per loaded context at the requested rung. The
+// exposure ledger lives at nodes/<id>/injected-docs.json, survives a strict
+// resume, and resets at a fresh-context boundary. A project store delivers
+// only once it declares its namespace, and an explicit frontmatter `name` is
+// store-local: the injected envelope carries the composed canonical name.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-dedup-resume.test.ts
 import { test, before, beforeEach, after } from 'node:test';
@@ -14,7 +14,18 @@ import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs } from '../substrate/on-read-node.js';
-import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
+import { clearContextExposureState, emptyContextExposureState, exposureTarget, loadContextExposureState, saveContextExposureState, } from '../substrate/injected-store.js';
+function freshTranscriptTarget() {
+    return exposureTarget(emptyContextExposureState(), 'transcript');
+}
+/** A repository-root project store mounts only once its root INDEX declares
+ *  the namespace its documents compose under. */
+function declareRepositoryRoot(memDir) {
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'INDEX.md'), '---\nnamespace: work\nkind: knowledge\n' +
+        'when-and-why-to-read: When working in this workspace, this knowledge should be read because it is the front door.\n---\n' +
+        'FRONT DOOR BODY\n');
+}
 const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
 let home;
 let work;
@@ -56,25 +67,25 @@ test('project and user memory docs without read surfaces do not fire on file rea
         'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n---\n' +
         'NOISY USER BODY\n');
     const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
-    mkdirSync(projectMemDir, { recursive: true });
+    declareRepositoryRoot(projectMemDir);
     writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n---\n' +
         'LOCAL PROJECT BODY\n');
     const readFile = join(fakeHome, 'work', 'ideas.md');
     writeFileSync(readFile, 'turn off xml closer\n');
-    const rendered = renderOnReadDocs(node, readFile, new Map());
+    const rendered = renderOnReadDocs(node, readFile, freshTranscriptTarget());
     assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc has no explicit file route');
     assert.ok(!rendered.includes('LOCAL PROJECT BODY'), 'project doc also has no implicit file route');
     assert.equal(rendered, '', 'no file context renders without an explicit trigger');
     rmSync(fakeHome, { recursive: true, force: true });
 });
-test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
+test('on-read exposure survives a strict resume and resets for a fresh context', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
     // A file-routed substrate doc in a `.crouter/memory/` ancestor. The
     // `./`-anchored glob pins the repo-relative anchor: `src/file.ts` matches
     // only relative to the doc's owning repo dir, never absolutely.
     const memDir = join(work, '.crouter', 'memory');
-    mkdirSync(memDir, { recursive: true });
+    declareRepositoryRoot(memDir);
     writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
         'surfaces:\n' +
@@ -84,25 +95,26 @@ test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfa
     mkdirSync(join(work, 'src'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
     // --- pi process #1: cold load; first read surfaces the doc ---
-    const seen = loadInjectedDocs(node);
-    const first = renderOnReadDocs(node, readFile, seen);
+    const state = loadContextExposureState(node);
+    const transcript = exposureTarget(state, 'transcript');
+    const first = renderOnReadDocs(node, readFile, transcript);
     assert.match(first, new RegExp(FIXTURE_BODY.replace(/[.]/g, '\\.')), 'first read surfaces the doc body');
-    saveInjectedDocs(node, seen);
-    // Same process, repeat read of the same file → deduped in-memory.
-    assert.ok(!renderOnReadDocs(node, readFile, seen).includes(FIXTURE_BODY), 'same-process repeat read is deduped');
-    // --- dormancy → revive(resume): NEW process rehydrates the set from disk ---
-    const seenAfterRevive = loadInjectedDocs(node);
-    assert.deepEqual(seenAfterRevive, seen, 'revive(resume) rehydrates the persisted dedup set');
-    assert.ok(!renderOnReadDocs(node, readFile, seenAfterRevive).includes(FIXTURE_BODY), 'resumed process does not re-inject the doc');
-    // --- fresh launch (revive resume=false, e.g. a refresh-yield) clears the set ---
-    clearInjectedDocs(node);
-    const seenFresh = loadInjectedDocs(node);
-    assert.ok(renderOnReadDocs(node, readFile, seenFresh).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');
+    saveContextExposureState(node, state);
+    // The active ledger suppresses an equal-rung repeat.
+    assert.ok(!renderOnReadDocs(node, readFile, transcript).includes(FIXTURE_BODY), 'same-context repeat read is already exposed');
+    // --- dormancy → revive(resume): NEW process rehydrates the state from disk ---
+    const stateAfterRevive = loadContextExposureState(node);
+    assert.deepEqual(stateAfterRevive, state, 'revive(resume) rehydrates the persisted context state');
+    assert.ok(!renderOnReadDocs(node, readFile, exposureTarget(stateAfterRevive, 'transcript')).includes(FIXTURE_BODY), 'strict resume does not re-deliver the document');
+    // --- fresh launch (revive resume=false, e.g. a refresh-yield) clears the state ---
+    clearContextExposureState(node);
+    const stateFresh = loadContextExposureState(node);
+    assert.ok(renderOnReadDocs(node, readFile, exposureTarget(stateFresh, 'transcript')).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');
 });
 test('an explicitly routed doc injects on-read under its frontmatter name, not the path-derived one', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
     const memDir = join(work, '.crouter', 'memory');
-    mkdirSync(memDir, { recursive: true });
+    declareRepositoryRoot(memDir);
     writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +
         'name: acme-project\n' +
         'when-and-why-to-read: When reading acme source, this knowledge should be read because it carries the project-specific implementation constraints.\n' +
@@ -112,8 +124,8 @@ test('an explicitly routed doc injects on-read under its frontmatter name, not t
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
-    const rendered = renderOnReadDocs(node, readFile, new Map());
+    const rendered = renderOnReadDocs(node, readFile, freshTranscriptTarget());
     assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
-    assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
-    assert.ok(!rendered.includes('name="physical-guide"'), 'must not fall back to the path-derived name when frontmatter sets one');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="work/acme-project"'), `expected the explicit local name composed under the store's namespace, got: ${rendered}`);
+    assert.ok(!rendered.includes('work/physical-guide'), 'must not fall back to the path-derived name when frontmatter sets one');
 });

package/dist/core/__tests__/on-read-nested-store.test.js

@@ -1,7 +1,7 @@
 // A `.crouter/memory` store nested BELOW a mounted project root is delivered
 // by the read path, not by boot: its `./**`-routed docs surface on the first
-// read beneath the store's owning dir, deduplicated against the
-// workspace-open render through the shared transcript dedup set. The `./`
+// read beneath the store's owning dir and share the active transcript exposure
+// ledger with the workspace-open render. The `./`
 // anchor stays fenced to project-store docs — a hand-authored `./` glob in a
 // user-scope doc must never match a read.
 //
@@ -16,6 +16,10 @@ import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs, renderWorkspaceOpenDocs } from '../substrate/on-read-node.js';
 import { clearSessionCache } from '../substrate/session-cache.js';
+import { emptyContextExposureState, exposureTarget, } from '../substrate/injected-store.js';
+function freshTranscriptTarget() {
+    return exposureTarget(emptyContextExposureState(), 'transcript');
+}
 const ROOT_BODY = 'ROOT WORKSPACE FRONT DOOR BODY';
 const NESTED_BODY = 'NESTED PKG FRONT DOOR BODY';
 let canvasHome;
@@ -44,14 +48,14 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-/** A work tree with a root front door and a nested store front door, both
- *  carrying the explicit front-door pair (workspace-open + `./**` read).
- *  Returns the work dir. */
+/** A work tree with a root front door declaring the repository namespace and a
+ *  nested store front door carrying the explicit front-door pair (workspace-open
+ *  + `./**` read), but no nested namespace declaration. Returns the work dir. */
 function makeWorkTree() {
     const work = join(fakeHome, 'work');
     const rootStore = join(work, '.crouter', 'memory');
     mkdirSync(rootStore, { recursive: true });
-    writeFileSync(join(rootStore, 'INDEX.md'), '---\nkind: knowledge\n' +
+    writeFileSync(join(rootStore, 'INDEX.md'), '---\nnamespace: work\nkind: knowledge\n' +
         'when-and-why-to-read: When working in this workspace, this knowledge should be read because it is the operating guide.\n' +
         'surfaces:\n' +
         '  - {on: workspace-open, at: content}\n' +
@@ -73,26 +77,28 @@ test('a nested store front door surfaces on a read beneath its owning dir, not o
     const inside = join(work, 'pkg', 'lib', 'file.ts');
     mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
     writeFileSync(inside, 'export const x = 1;\n');
-    const rendered = renderOnReadDocs(node, inside, new Map());
+    const rendered = renderOnReadDocs(node, inside, freshTranscriptTarget());
     assert.ok(rendered.includes(NESTED_BODY), `read beneath pkg surfaces the nested front door; got: ${rendered}`);
     const outside = join(work, 'docs', 'notes.ts');
     mkdirSync(join(work, 'docs'), { recursive: true });
     writeFileSync(outside, 'export const y = 2;\n');
-    const renderedOutside = renderOnReadDocs(node, outside, new Map());
+    const renderedOutside = renderOnReadDocs(node, outside, freshTranscriptTarget());
     assert.ok(!renderedOutside.includes(NESTED_BODY), `read outside pkg must not surface the nested front door; got: ${renderedOutside}`);
 });
-test('workspace-open and on-read share one dedup set: root front door once, nested store on first read beneath it', () => {
+test('workspace-open and on-read share one exposure ledger', () => {
     const work = makeWorkTree();
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    const seen = new Map();
-    const opened = renderWorkspaceOpenDocs(node, seen);
+    const transcript = freshTranscriptTarget();
+    const opened = renderWorkspaceOpenDocs(node, transcript);
     assert.ok(opened.includes(ROOT_BODY), 'workspace open delivers the mounted root front door');
+    assert.ok(opened.includes('name="work"'), `a store's root INDEX answers at its declared namespace, with no trailing INDEX segment; got: ${opened}`);
     assert.ok(!opened.includes(NESTED_BODY), 'boot stays flat: the nested store is not in the mounted stack');
     const readFile = join(work, 'pkg', 'lib', 'file.ts');
     mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
-    const onRead = renderOnReadDocs(node, readFile, seen);
+    const onRead = renderOnReadDocs(node, readFile, transcript);
     assert.ok(onRead.includes(NESTED_BODY), 'the nested front door delivers on the first read beneath it');
+    assert.ok(onRead.includes('name="work/pkg"'), 'the nested front door answers under the root namespace plus owner path');
     assert.ok(!onRead.includes(ROOT_BODY), 'the root front door already delivered at workspace open — never twice');
 });
 test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', () => {
@@ -114,7 +120,7 @@ test('a hand-authored `./`-anchored read glob in a user-scope doc never matches
     const readFile = join(fakeHome, 'notes', 'thing.md');
     mkdirSync(join(fakeHome, 'notes'), { recursive: true });
     writeFileSync(readFile, '# a note\n');
-    const rendered = renderOnReadDocs(node, readFile, new Map());
+    const rendered = renderOnReadDocs(node, readFile, freshTranscriptTarget());
     assert.ok(rendered.includes('USER CONTROL BODY'), 'the glob-routed user doc proves the user store is in the corpus');
     assert.ok(!rendered.includes('USER DOT BODY MUST NOT FIRE'), `the \`./\` anchor is project-store only — a user doc's owning root is ~; got: ${rendered}`);
 });