@north-light/crouter 0.3.227 → 0.3.228

package/dist/commands/__tests__/surface-reload-target.test.js

@@ -0,0 +1,21 @@
+// Regression: `crtr surface reload` refused every pane whose start command came
+// from a respawn path that shell-quotes the node id (the Markdown file-open
+// bridge, the review companion launch). The old gate compared the raw command
+// line to the canonical `crtr surface attach to <id>`, so
+// `crtr surface attach to '<id>'` read as a viewer/node mismatch and the reload
+// exited 2 — permanently, for that pane.
+// Run with: node --conditions=crtr-src --import tsx/esm --test 'src/commands/__tests__/surface-reload-target.test.ts'
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { attachTargetNode } from '../surface-reload.js';
+const NODE = '3zl47w7d-mt0cp6we-ed07d4c5';
+test('a viewer command line names its node whether or not the id is shell-quoted', () => {
+    assert.equal(attachTargetNode(`crtr surface attach to ${NODE}`), NODE);
+    assert.equal(attachTargetNode(`crtr surface attach to '${NODE}'`), NODE);
+    assert.equal(attachTargetNode(`crtr surface attach to '${NODE}' --observer`), NODE);
+    assert.equal(attachTargetNode(`crtr surface attach to ${NODE} --observer`), NODE);
+});
+test('a command line for another node does not read as this node', () => {
+    assert.notEqual(attachTargetNode(`crtr surface attach to '3zl47w7d-other-00000000'`), NODE);
+    assert.equal(attachTargetNode('zsh -l'), undefined);
+});

package/dist/commands/api-client.d.ts

@@ -45,13 +45,9 @@ export declare function readColdStartDiagnostic(): string | undefined;
  *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
  *  returns immediately, so the client's OWN `/healthz` poll is the only
  *  deadline the initiating CLI invocation actually waits on. It must never be
- *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
- *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
- *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
- *  and a 10s client poll would still give up and report `daemon_unavailable`
- *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
- *  here keeps the two in lockstep — one authoritative window, not two that can
- *  drift apart — without adding any retry/fallback poll loop. */
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows.
+ *  Both callers use the shared startup policy so a valid on-disk migration
+ *  cannot outlast the initiating CLI command. */
 export declare function cliClient(opts?: {
     timeoutMs?: number;
 }): CrtrClient;

package/dist/commands/api-client.js

@@ -18,7 +18,8 @@ import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
 import { join } from 'node:path';
 import { CrtrClient, ApiError } from '../api/index.js';
 import { apiErrorToCliError } from '../core/io.js';
-import { ensureDaemon, DAEMON_VERIFY_WINDOW_MS } from '../daemon/manage.js';
+import { ensureDaemon } from '../daemon/manage.js';
+import { DAEMON_STARTUP_WINDOW_MS } from '../daemon/startup-policy.js';
 import { readState } from '../core/config.js';
 import { resolveRemoteCanvasTarget } from '../core/remote-canvas-target.js';
 import { RemoteCanvasSource } from '../core/canvas/remote-canvas-source.js';
@@ -119,13 +120,9 @@ export function readColdStartDiagnostic() {
  *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
  *  returns immediately, so the client's OWN `/healthz` poll is the only
  *  deadline the initiating CLI invocation actually waits on. It must never be
- *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows (which
- *  `ensureDaemon`'s spawn transitively awaits, in the detached child, on the
- *  SAME cold-start path): a daemon that takes 12s is a valid, verified startup,
- *  and a 10s client poll would still give up and report `daemon_unavailable`
- *  against it. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
- *  here keeps the two in lockstep — one authoritative window, not two that can
- *  drift apart — without adding any retry/fallback poll loop. */
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows.
+ *  Both callers use the shared startup policy so a valid on-disk migration
+ *  cannot outlast the initiating CLI command. */
 export function cliClient(opts) {
     if (autostartDisabled()) {
         return CrtrClient.forLocalSocket({ autostart: false, ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
@@ -133,15 +130,13 @@ export function cliClient(opts) {
     return CrtrClient.forLocalSocket({
         ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
         onColdSocket: async () => {
-            // Fire-and-forget spawn; the client's bounded /healthz poll below (sized
-            // to the SAME window spawnDaemon's verifyDaemonStartup uses) owns the
-            // "did it come up?" wait and the loud failure.
+            // The client's bounded /healthz poll owns the readiness wait and failure.
             ensureDaemon();
         },
         // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
         // tail of crtrd's own stderr log instead of discarding it.
         coldStartDiagnostic: readColdStartDiagnostic,
-        coldStartPollWindowMs: DAEMON_VERIFY_WINDOW_MS,
+        coldStartPollWindowMs: DAEMON_STARTUP_WINDOW_MS,
     });
 }
 // ---------------------------------------------------------------------------

package/dist/commands/memory/__tests__/command-selector-and-mutation-guards.test.js

@@ -0,0 +1,292 @@
+// Regressions for the memory leaves' store selection and mutation guards. Each
+// case reproduces a failure the leaves actually shipped: an explicit --profile
+// silently answering from the ambient profile, a project root deletable out
+// from under its own namespace, `move --dir` rewriting links on behalf of a
+// duplicate that does not own the address, an `NN-` ordering prefix accepted as
+// an address, a `name:` pin that could not be retired in place, a numeric
+// `namespace:` mounting lint-clean, `lint` throwing its declared rows away on
+// failure, and deleted history recommending a read that cannot succeed.
+//
+// Fixture: one repository-root store declaring `namespace: acme` and a nested
+// store whose effective prefix is derived as `acme/child`; plus two single-store
+// projects for the lint cases and two profiles under a temp HOME.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test --test-concurrency=4 --test-timeout=10000 src/commands/memory/__tests__/command-selector-and-mutation-guards.test.ts
+import { test, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resetScopeCache } from '../../../core/scope.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { createProfile, profileMemoryDir } from '../../../core/profiles/manifest.js';
+import { openProjectMemoryStore } from '../../../core/memory-resolver.js';
+import { appendHistoryRecord, buildHistoryRecord, readHistoryRecords } from '../../../core/memory/history.js';
+import { CrtrError } from '../../../core/errors.js';
+import { deleteLeaf } from '../delete.js';
+import { editLeaf } from '../edit.js';
+import { historyLeaf } from '../history.js';
+import { lintLeaf } from '../lint.js';
+import { moveLeaf } from '../move.js';
+import { originLeaf } from '../origin.js';
+import { readLeaf } from '../read.js';
+import { writeLeaf } from '../write.js';
+let home;
+let canvasHome;
+let base;
+let root;
+let child;
+let badns;
+let dangling;
+let profileB;
+let nestedWrite;
+let nestedEmpty;
+const prevEnv = {};
+const prevCwd = process.cwd();
+function writeDoc(path, frontmatter, body) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, `---\n${frontmatter}\n---\n\n${body}\n`, 'utf8');
+}
+function storeDir(project) {
+    return join(project, '.crouter', 'memory');
+}
+/** The error a leaf threw, for `code`/`message` assertions. */
+async function thrownByAsync(run) {
+    try {
+        await run();
+    }
+    catch (e) {
+        assert.ok(e instanceof CrtrError, `expected a CrtrError, got ${String(e)}`);
+        return e;
+    }
+    assert.fail('expected the leaf to throw');
+}
+beforeEach(() => {
+    for (const key of ['HOME', 'CRTR_HOME', 'CRTR_PROFILE_ID', 'CRTR_NODE_ID']) {
+        if (!(key in prevEnv))
+            prevEnv[key] = process.env[key];
+    }
+    home = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-memcmd-home-')));
+    canvasHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-memcmd-canvas-')));
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-memcmd-')));
+    process.env['HOME'] = home;
+    process.env['CRTR_HOME'] = canvasHome;
+    delete process.env['CRTR_NODE_ID'];
+    mkdirSync(join(home, '.crouter', 'memory'), { recursive: true });
+    root = join(base, 'root');
+    child = join(root, 'child');
+    nestedWrite = join(root, 'nested-write');
+    nestedEmpty = join(root, 'nested-empty');
+    badns = join(base, 'badns');
+    dangling = join(base, 'dangling');
+    mkdirSync(child, { recursive: true });
+    mkdirSync(nestedWrite, { recursive: true });
+    mkdirSync(nestedEmpty, { recursive: true });
+    // --- repository root, declaring the namespace for every nested store ---
+    writeDoc(join(storeDir(root), 'INDEX.md'), 'kind: knowledge\nnamespace: acme\nwhen-and-why-to-read: "When the root acme store is addressed, this knowledge should be read because it names what the store holds."', 'ROOT STORE INDEX');
+    writeDoc(join(storeDir(root), 'foo.md'), 'kind: knowledge', 'ROOT FOO BODY');
+    writeDoc(join(storeDir(root), 'linker.md'), 'kind: knowledge', 'ROOT LINKER BODY linking [[acme/foo]] once.');
+    writeDoc(join(storeDir(root), 'disposable.md'), 'kind: knowledge', 'ROOT DISPOSABLE BODY');
+    writeDoc(join(storeDir(root), '04-ordered.md'), 'kind: knowledge', 'ROOT ORDERED BODY');
+    // A `name:` pin on a file whose own path already derives a different identity.
+    writeDoc(join(storeDir(root), 'x.md'), 'kind: knowledge\nname: y', 'ROOT PINNED BODY');
+    appendHistoryRecord(join(storeDir(root), '.history', 'x.jsonl'), buildHistoryRecord({ op: 'create', before: '', after: 'ROOT PINNED BODY' }));
+    // --- child: a nested store deriving `acme/child`; cwd lives here ---
+    writeDoc(join(storeDir(child), 'INDEX.md'), 'kind: knowledge\nwhen-and-why-to-read: "When the child guide is addressed, this knowledge should be read because it names what the nested store holds."', 'CHILD STORE INDEX');
+    writeDoc(join(storeDir(child), 'foo.md'), 'kind: knowledge', 'CHILD FOO BODY');
+    // This nested store has content but no guide, so a write at its exact prefix
+    // must create metadata-free INDEX.md rather than a second declaration.
+    writeDoc(join(storeDir(nestedWrite), 'topic.md'), 'kind: knowledge', 'NESTED WRITE TOPIC');
+    // --- lint fixtures ---
+    writeDoc(join(storeDir(badns), 'INDEX.md'), 'kind: knowledge\nnamespace: 42', 'BADNS STORE INDEX');
+    writeDoc(join(storeDir(dangling), 'INDEX.md'), 'kind: knowledge\nnamespace: dang\nwhen-and-why-to-read: "When the dang store is addressed, this knowledge should be read because it names what the store holds."', 'DANG STORE INDEX');
+    writeDoc(join(storeDir(dangling), 'broken.md'), 'kind: knowledge', 'Links [[dang/nowhere]], which no document answers to.');
+    // --- two profiles, both holding the SAME canonical name ---
+    const a = createProfile('memcmd-a');
+    const b = createProfile('memcmd-b');
+    profileB = profileMemoryDir(b.profileId);
+    writeDoc(join(profileMemoryDir(a.profileId), 'pdoc.md'), 'kind: knowledge', 'PROFILE A BODY');
+    writeDoc(join(profileB, 'pdoc.md'), 'kind: knowledge', 'PROFILE B BODY');
+    process.env['CRTR_PROFILE_ID'] = a.profileId;
+    process.chdir(child);
+    resetScopeCache();
+});
+after(() => {
+    closeDb();
+    process.chdir(prevCwd);
+    resetScopeCache();
+    for (const dir of [home, canvasHome, base])
+        rmSync(dir, { recursive: true, force: true });
+    for (const [key, value] of Object.entries(prevEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+});
+test('an explicit --profile selects that profile store for edit, origin, and history', async () => {
+    const target = join(profileB, 'pdoc.md');
+    const selector = { scope: 'profile', profile: 'memcmd-b' };
+    const edited = (await editLeaf.run({
+        ...selector,
+        name: 'pdoc',
+        rationale: 'regression: --profile must not answer from the ambient profile',
+        body: 'PROFILE B BODY REVISED',
+    }));
+    assert.equal(edited.path, target, 'the edit landed in the named profile store, not the ambient one');
+    assert.match(readFileSync(target, 'utf8'), /PROFILE B BODY REVISED/);
+    const origin = (await originLeaf.run({ ...selector, name: 'pdoc' }));
+    assert.equal(origin.path, target);
+    assert.equal(origin.scope, 'profile');
+    const history = (await historyLeaf.run({ ...selector, name: 'pdoc' }));
+    assert.equal(history.log_path, join(profileB, '.history', 'pdoc.jsonl'));
+    assert.equal(history.total, 1);
+});
+test('only the repository-root INDEX is immutable; nested guides move and delete normally', async () => {
+    const deleteErr = await thrownByAsync(() => deleteLeaf.run({ name: 'acme', dir: root }));
+    assert.equal(deleteErr.code, 'usage');
+    assert.match(deleteErr.message, /repository-root document/);
+    assert.ok(existsSync(join(storeDir(root), 'INDEX.md')), 'the namespace declaration is still on disk');
+    const moveErr = await thrownByAsync(() => moveLeaf.run({ name: 'acme', to: 'acme/other', dir: root }));
+    assert.equal(moveErr.code, 'usage');
+    assert.match(moveErr.message, /repository-root document/);
+    const moved = (await moveLeaf.run({ name: 'acme/child', to: 'acme/child/guide', dir: child }));
+    assert.equal(moved.path, join(storeDir(child), 'guide.md'));
+    assert.ok(!existsSync(join(storeDir(child), 'INDEX.md')));
+    writeDoc(join(storeDir(child), 'INDEX.md'), 'kind: knowledge\nwhen-and-why-to-read: "When the child guide is addressed, this knowledge should be read because it names what the nested store holds."', 'CHILD STORE INDEX');
+    const deleted = (await deleteLeaf.run({ name: 'acme/child', dir: child }));
+    assert.equal(deleted.path, join(storeDir(child), 'INDEX.md'));
+    assert.ok(!existsSync(join(storeDir(child), 'INDEX.md')));
+});
+test('nested stores cannot initialize a namespace, but writes to their exact prefix create a metadata-free guide', async () => {
+    const initErr = await thrownByAsync(() => writeLeaf.run({
+        name: 'acme/nested-empty',
+        kind: 'knowledge',
+        dir: nestedEmpty,
+        body: 'must not initialize a nested store',
+    }));
+    assert.equal(initErr.code, 'usage');
+    assert.match(initErr.message, /only the repository root declares a namespace/);
+    assert.match(String(initErr.details?.['next']), /crtr memory write <namespace> --dir <repositoryRoot>/);
+    const created = (await writeLeaf.run({
+        name: 'acme/nested-write',
+        kind: 'knowledge',
+        dir: nestedWrite,
+        body: 'NESTED GUIDE BODY',
+    }));
+    assert.equal(created.name, 'acme/nested-write');
+    assert.equal(created.path, join(storeDir(nestedWrite), 'INDEX.md'));
+    const text = readFileSync(created.path, 'utf8');
+    assert.ok(!/^namespace:/m.test(text), `nested guide must not declare a namespace; got:\n${text}`);
+});
+test('editing the repository-root guide preserves its namespace declaration', async () => {
+    await editLeaf.run({
+        name: 'acme',
+        dir: root,
+        rationale: 'regression: root namespace must remain immutable during edits',
+        body: 'ROOT STORE INDEX REVISED',
+    });
+    assert.match(readFileSync(join(storeDir(root), 'INDEX.md'), 'utf8'), /^namespace: acme$/m);
+});
+test('move and delete recover same-store collisions by stable physical path, while edit and origin refuse', async () => {
+    const collisionLeaf = join(storeDir(root), 'collision.md');
+    const collisionIndex = join(storeDir(root), 'collision', 'INDEX.md');
+    writeDoc(collisionLeaf, 'kind: knowledge', 'COLLISION LEAF');
+    writeDoc(collisionIndex, 'kind: knowledge', 'COLLISION INDEX');
+    const editErr = await thrownByAsync(() => editLeaf.run({
+        name: 'acme/collision',
+        dir: root,
+        rationale: 'collision must remain ambiguous to edit',
+        body: 'must not edit',
+    }));
+    assert.equal(editErr.code, 'usage');
+    assert.match(editErr.message, /owned by 2 files/);
+    assert.match(String(editErr.details?.['next']), /memory move acme\/collision --to <new-free-name>/);
+    const originErr = await thrownByAsync(() => originLeaf.run({ name: 'acme/collision', dir: root }));
+    assert.equal(originErr.code, 'usage');
+    assert.match(originErr.message, /owned by 2 files/);
+    try {
+        const lint = (await lintLeaf.run({ dir: root }));
+        const collision = lint.findings.find((finding) => finding.rule === 'canonical-collision');
+        assert.ok(collision, 'lint reports the physical collision');
+        assert.match(collision.message, /memory move acme\/collision --to <new-free-name>/);
+    }
+    finally {
+        process.exitCode = 0;
+    }
+    const moved = (await moveLeaf.run({ name: 'acme/collision', to: 'acme/recovered', dir: root }));
+    assert.equal(moved.path, join(storeDir(root), 'recovered.md'));
+    assert.ok(!existsSync(collisionLeaf), 'move selected the first lexical physical path');
+    assert.ok(existsSync(collisionIndex), 'move left the other representation untouched');
+    assert.ok(moved.follow_up.includes('first physical path') && moved.follow_up.includes(collisionLeaf));
+    const deleteLeafPath = join(storeDir(root), 'delete-collision.md');
+    const deleteIndexPath = join(storeDir(root), 'delete-collision', 'INDEX.md');
+    writeDoc(deleteLeafPath, 'kind: knowledge', 'DELETE COLLISION LEAF');
+    writeDoc(deleteIndexPath, 'kind: knowledge', 'DELETE COLLISION INDEX');
+    const deleted = (await deleteLeaf.run({ name: 'acme/delete-collision', dir: root }));
+    assert.equal(deleted.path, deleteLeafPath);
+    assert.ok(!existsSync(deleteLeafPath), 'delete selected the first lexical physical path');
+    assert.ok(existsSync(deleteIndexPath), 'delete left the other representation untouched');
+    assert.ok(deleted.follow_up.includes('first physical path') && deleted.follow_up.includes(deleteLeafPath));
+});
+test('move --dir addresses the selected repository store at its full effective name and rewrites its links', async () => {
+    const linker = join(storeDir(root), 'linker.md');
+    const result = (await moveLeaf.run({ name: 'acme/foo', to: 'acme/renamed', dir: root }));
+    assert.deepEqual(result.refs_rewritten.map((ref) => ref.path), [linker]);
+    assert.match(readFileSync(linker, 'utf8'), /\[\[acme\/renamed\]\]/, 'the root link follows its moved target');
+    const childDoc = await readLeaf.run({ name: 'acme/child/foo', kind: undefined, frontmatter: false, scope: undefined, dir: child });
+    assert.match(childDoc.content, /CHILD FOO BODY/, 'the nested effective prefix remains independently addressable through --dir');
+});
+test('an `NN-` ordering prefix is physical-path-only: not an address, not a mutation destination', async () => {
+    const read = (await readLeaf.run({ name: 'acme/ordered', kind: undefined, frontmatter: false, scope: undefined, dir: root }));
+    assert.match(read.content, /ROOT ORDERED BODY/, 'the path-derived identity strips the prefix');
+    const query = await thrownByAsync(() => readLeaf.run({ name: 'acme/04-ordered', kind: undefined, frontmatter: false, scope: undefined, dir: root }));
+    assert.equal(query.code, 'not_found', 'the prefixed spelling is not a canonical identity');
+    const mutation = await thrownByAsync(() => moveLeaf.run({ name: 'acme/ordered', to: 'acme/05-renamed', dir: root }));
+    assert.equal(mutation.code, 'usage');
+    assert.match(mutation.message, /ordering prefix/);
+    assert.ok(!existsSync(join(storeDir(root), '05-renamed.md')), 'nothing was renamed');
+    assert.ok(!existsSync(join(storeDir(root), 'renamed.md')), 'and nothing was silently renamed to the stripped form');
+});
+test('moving a `name:` pin back to the file’s own path identity retires the pin in place', async () => {
+    const path = join(storeDir(root), 'x.md');
+    const result = (await moveLeaf.run({ name: 'acme/y', to: 'acme/x', dir: root }));
+    assert.equal(result.path, path, 'the file stays exactly where it already sat');
+    const text = readFileSync(path, 'utf8');
+    assert.ok(!/^name:/m.test(text), `the pin is gone; got:\n${text}`);
+    assert.match(text, /ROOT PINNED BODY/);
+    const log = join(storeDir(root), '.history', 'x.jsonl');
+    assert.equal(result.log_path, log);
+    assert.equal(readHistoryRecords(log).length, 2, 'the existing log gained the move record and was not duplicated');
+    assert.ok(!existsSync(join(storeDir(root), '.history', 'y.jsonl')), 'no sidecar was created under the retired pin');
+});
+test('a numeric `namespace:` does not mount and lint reports it', async () => {
+    assert.equal(openProjectMemoryStore(badns).mountStatus, 'invalid', 'a non-string namespace is not coerced into one');
+    try {
+        const result = (await lintLeaf.run({ dir: badns }));
+        assert.ok(result.findings.some((f) => f.rule === 'store-namespace'), `lint reports the undeclared namespace; got: ${JSON.stringify(result.findings)}`);
+    }
+    finally {
+        process.exitCode = 0;
+    }
+});
+test('a failing lint returns its declared rows and fails by exit code', async () => {
+    try {
+        const result = (await lintLeaf.run({ dir: dangling }));
+        assert.equal(process.exitCode, 1, 'a failing lint exits non-zero');
+        assert.ok(result.checked > 0, 'the declared counts survive the failure');
+        assert.ok(Array.isArray(result.warnings) && Array.isArray(result.notices), 'so do the non-fatal rows');
+        assert.ok(result.findings.some((f) => f.rule === 'dangling-link'), `the findings carry the error rows; got: ${JSON.stringify(result.findings)}`);
+        assert.match(result.follow_up, /error/);
+    }
+    finally {
+        process.exitCode = 0;
+    }
+});
+test('deleted history points at the revision holding the retained text, never a read that cannot answer', async () => {
+    await deleteLeaf.run({ name: 'acme/disposable', dir: root });
+    const result = (await historyLeaf.run({ name: 'acme/disposable', dir: root }));
+    assert.equal(result.total, 1);
+    assert.match(result.follow_up, /--revision 1/, 'the follow-up names the revision carrying the final text');
+    assert.ok(!result.follow_up.includes('memory read acme/disposable'), `a read of a deleted document is guaranteed to fail and must not be recommended; got: ${result.follow_up}`);
+});

package/dist/commands/memory/__tests__/repository-root-lint.test.js

@@ -0,0 +1,146 @@
+// Regressions for repository-root memory identity linting: nested stores derive
+// their prefix and carry no declaration or required front door, while root-only
+// declarations, owner-path collisions, and profile coverage remain enforced.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test --test-timeout=10000 src/commands/memory/__tests__/repository-root-lint.test.ts
+import { after, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../../../core/canvas/db.js';
+import { lintMemoryStore, lintMemoryTarget } from '../../../core/memory/lint.js';
+import { openProjectMemoryStore } from '../../../core/memory-resolver.js';
+import { createProfile } from '../../../core/profiles/manifest.js';
+import { resetScopeCache } from '../../../core/scope.js';
+let home;
+let canvasHome;
+let base;
+const previousEnv = {};
+function storeDir(owner) {
+    return join(owner, '.crouter', 'memory');
+}
+function writeDoc(path, frontmatter, body = 'DOCUMENT BODY') {
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, `---\n${frontmatter}\n---\n\n${body}\n`, 'utf8');
+}
+function rootFrontmatter(namespace, frontDoor = false) {
+    const surfaces = frontDoor
+        ? '\nsurfaces:\n  - on: workspace-open\n    at: content\n  - on: read\n    match: "./**"\n    at: content'
+        : '';
+    return `kind: knowledge\nnamespace: ${namespace}\nwhen-and-why-to-read: "When this repository is opened, this knowledge should be read because it orients work in the repository."${surfaces}`;
+}
+function nestedFrontmatter() {
+    return 'kind: knowledge\nwhen-and-why-to-read: "When this nested store is addressed, this knowledge should be read because it orients work in its area."';
+}
+function makeRepository(name, frontDoor = true) {
+    const root = join(base, name);
+    writeDoc(join(storeDir(root), 'INDEX.md'), rootFrontmatter(name, frontDoor), 'ROOT GUIDE');
+    return root;
+}
+function target(cwd, profileId = null) {
+    return { cwd, profileId, nodeId: null };
+}
+beforeEach(() => {
+    for (const key of ['HOME', 'CRTR_HOME', 'CRTR_PROFILE_ID', 'CRTR_NODE_ID']) {
+        if (!(key in previousEnv))
+            previousEnv[key] = process.env[key];
+    }
+    home = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-root-lint-home-')));
+    canvasHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-root-lint-canvas-')));
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-root-lint-')));
+    process.env['HOME'] = home;
+    process.env['CRTR_HOME'] = canvasHome;
+    delete process.env['CRTR_PROFILE_ID'];
+    delete process.env['CRTR_NODE_ID'];
+    mkdirSync(join(home, '.crouter', 'memory'), { recursive: true });
+    resetScopeCache();
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    for (const dir of [home, canvasHome, base])
+        rmSync(dir, { recursive: true, force: true });
+    for (const [key, value] of Object.entries(previousEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+});
+test('a root declaration and substantive metadata-free nested index are clean', () => {
+    const root = makeRepository('acme', false);
+    const nested = join(root, 'packages', 'api');
+    writeDoc(join(storeDir(nested), 'INDEX.md'), nestedFrontmatter(), 'NESTED GUIDE');
+    assert.equal(lintMemoryStore(openProjectMemoryStore(root)).ok, true, 'one repository-root declaration is valid');
+    const nestedResult = lintMemoryStore(openProjectMemoryStore(nested));
+    assert.equal(nestedResult.ok, true, JSON.stringify(nestedResult.findings));
+    assert.equal(openProjectMemoryStore(nested).namespace, 'acme/packages/api');
+});
+test('nested declarations and root names are both rejected', () => {
+    const root = makeRepository('acme');
+    const nested = join(root, 'packages', 'api');
+    writeDoc(join(storeDir(nested), 'INDEX.md'), `${nestedFrontmatter()}\nnamespace: nested\nname: forbidden`, 'NESTED GUIDE');
+    const result = lintMemoryStore(openProjectMemoryStore(nested));
+    assert.deepEqual(result.errors.map((finding) => finding.rule), ['namespace-placement', 'root-name']);
+    assert.match(result.errors[0].message, /repository-root store/);
+    assert.match(result.errors[0].message, new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+});
+test('a nested non-root workspace-open guide remains an error', () => {
+    const root = makeRepository('acme');
+    const nested = join(root, 'packages', 'api');
+    writeDoc(join(storeDir(nested), 'INDEX.md'), nestedFrontmatter(), 'NESTED GUIDE');
+    writeDoc(join(storeDir(nested), 'second-guide.md'), `${nestedFrontmatter()}\nsurfaces:\n  - on: workspace-open\n    at: content`, 'SECOND GUIDE');
+    const result = lintMemoryStore(openProjectMemoryStore(nested));
+    assert.deepEqual(result.errors.map((finding) => finding.rule), ['front-door']);
+});
+test('owner-path collisions report one collision rather than a second namespace failure per store', () => {
+    const root = makeRepository('acme');
+    const first = join(root, 'api!');
+    const second = join(root, 'api?');
+    writeDoc(join(storeDir(first), 'INDEX.md'), nestedFrontmatter(), 'FIRST');
+    writeDoc(join(storeDir(second), 'INDEX.md'), nestedFrontmatter(), 'SECOND');
+    const result = lintMemoryTarget({ target: target(root), includeDescendants: true });
+    const collisionFindings = result.errors.filter((finding) => finding.rule === 'owner-path-collision');
+    assert.equal(collisionFindings.length, 2, JSON.stringify(result.errors));
+    assert.equal(result.errors.some((finding) => finding.rule === 'store-namespace'), false, JSON.stringify(result.errors));
+    for (const finding of collisionFindings) {
+        assert.match(finding.message, /api!/);
+        assert.match(finding.message, /api\?/);
+        assert.equal(result.errors.filter((candidate) => candidate.storeRoot === finding.storeRoot).length, 1, `the colliding store ${finding.storeRoot} emits only its collision finding`);
+    }
+});
+test('profile front-door coverage keeps all four repository-root cases distinct', () => {
+    // (a) Managed owners with no store still owe a root front door.
+    const absent = join(base, 'absent');
+    mkdirSync(absent, { recursive: true });
+    const absentProfile = createProfile('root-lint-absent', [{ path: absent, memory: 'content' }]);
+    const absentResult = lintMemoryTarget({ target: target(base, absentProfile.profileId) });
+    const absentDoors = absentResult.errors.filter((finding) => finding.rule === 'front-door');
+    assert.equal(absentDoors.length, 1, JSON.stringify(absentResult.errors));
+    assert.equal(absentDoors[0].path, absent);
+    // (b) A root store without its pair emits the required finding once, not once
+    // from the target view and again from managed-owner coverage.
+    const missing = makeRepository('missing-door', false);
+    const missingProfile = createProfile('root-lint-missing', [{ path: missing, memory: 'content' }]);
+    const missingResult = lintMemoryTarget({ target: target(missing, missingProfile.profileId) });
+    const missingDoors = missingResult.errors.filter((finding) => finding.rule === 'front-door');
+    assert.equal(missingDoors.length, 1, JSON.stringify(missingResult.errors));
+    assert.equal(missingDoors[0].path, missing);
+    // (c) A profile pointing at a nested owner does not make that store owe a
+    // front door, but the associated repository root still owes its pair.
+    const nestedManagedRoot = makeRepository('nested-managed', false);
+    const nestedManaged = join(nestedManagedRoot, 'area');
+    writeDoc(join(storeDir(nestedManaged), 'INDEX.md'), nestedFrontmatter(), 'NESTED GUIDE');
+    const nestedProfile = createProfile('root-lint-nested', [{ path: nestedManaged, memory: 'content' }]);
+    const nestedResult = lintMemoryTarget({ target: target(nestedManaged, nestedProfile.profileId) });
+    const nestedDoors = nestedResult.errors.filter((finding) => finding.rule === 'front-door');
+    assert.equal(nestedDoors.length, 1, JSON.stringify(nestedResult.errors));
+    assert.equal(nestedDoors[0].path, nestedManagedRoot);
+    // (d) A nested store with no door is clean when its repository root has one.
+    const cleanRoot = makeRepository('nested-clean');
+    const cleanNested = join(cleanRoot, 'area');
+    writeDoc(join(storeDir(cleanNested), 'INDEX.md'), nestedFrontmatter(), 'NESTED GUIDE');
+    const cleanResult = lintMemoryTarget({ target: target(cleanRoot) });
+    assert.equal(cleanResult.findings.length, 0, JSON.stringify(cleanResult.findings));
+});