@north-light/crouter 0.3.318 → 0.3.319

package/dist/core/__tests__/node-outcome.test.js

@@ -1,246 +0,0 @@
-import { after, afterEach, beforeEach, test } from 'node:test';
-import assert from 'node:assert/strict';
-import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { closeDb, MIGRATIONS, migrate, openDb, withCanvasWrite } from '../canvas/db.js';
-import { createNode, getNode, getRow } from '../canvas/canvas.js';
-import { activateArmedExternalActionDelivery, armExternalActionDelivery, claimExternalActionDelivery, messageBodyForDelivery, readExternalActionDelivery, resetHandedOffDeliveries, settleDelivery, } from '../canvas/deliveries.js';
-import { transition } from '../runtime/lifecycle.js';
-import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
-import { pushFinal } from '../feed/feed.js';
-import { OUTCOME_PAYLOAD_MAX_BYTES } from '../canvas/types.js';
-let home;
-const priorHome = process.env['CRTR_HOME'];
-function outcomeKey(nodeId) {
-    return `node-outcome:${nodeId}`;
-}
-function outcomeDelivery(nodeId) {
-    return readExternalActionDelivery(outcomeKey(nodeId));
-}
-function nodeAtOutcome(node) {
-    const reason = node.outcome_reason;
-    let status;
-    let intent;
-    if (node.outcome_kind === 'result' || reason === 'finished' || reason === 'declined') {
-        status = 'done';
-        intent = 'done';
-    }
-    else if (reason === 'parked') {
-        status = 'done';
-        intent = 'parked';
-    }
-    else if (reason === 'closed' || reason === 'retired' || reason === 'stranded' || reason === 'deadline_exceeded') {
-        status = 'canceled';
-        intent = null;
-    }
-    else {
-        status = 'dead';
-        intent = null;
-    }
-    return { ...node, status, intent, terminal_reason: reason };
-}
-function armOutcomeAction(input) {
-    const payload = input.payload ?? null;
-    const json = JSON.stringify(payload);
-    if (json === undefined)
-        throw new TypeError('outcome delivery payload must be JSON-serializable');
-    if (Buffer.byteLength(json, 'utf8') > OUTCOME_PAYLOAD_MAX_BYTES)
-        throw new RangeError(`outcome delivery payload exceeds ${OUTCOME_PAYLOAD_MAX_BYTES} bytes`);
-    return withCanvasWrite((db) => {
-        const existing = outcomeDelivery(input.nodeId);
-        if (existing !== null && existing.state !== 'armed')
-            return null;
-        armExternalActionDelivery(db, {
-            destinationId: input.actionName,
-            adapter: { adapter: 'subprocess', argv: input.argv, cwd: input.cwd, config_origin: input.configOrigin, payload },
-            idempotencyKey: outcomeKey(input.nodeId),
-        }, input.now);
-        const node = getNode(input.nodeId);
-        if (node === null)
-            throw new Error(`unknown node ${input.nodeId}`);
-        if (node.outcome_at !== null) {
-            if (node.outcome_kind === null || node.outcome_reason === null)
-                throw new Error(`outcome latch is incomplete for node ${input.nodeId}`);
-            activateArmedExternalActionDelivery(db, {
-                idempotencyKey: outcomeKey(input.nodeId),
-                label: input.nodeId,
-                bodyJson: JSON.stringify(composeNodeOutcomeDocument({
-                    node: nodeAtOutcome(node),
-                    outcome: { kind: node.outcome_kind, reason: node.outcome_reason, at: node.outcome_at, revision: node.outcome_revision, detailJson: node.outcome_detail_json ?? null },
-                    action: { name: input.actionName, payload },
-                    finalReport: node.final_report,
-                })),
-                supersede: false,
-            }, input.now);
-        }
-        return outcomeDelivery(input.nodeId);
-    });
-}
-function node(nodeId) {
-    return {
-        node_id: nodeId,
-        name: nodeId,
-        created: new Date().toISOString(),
-        cwd: home,
-        kind: 'general',
-        mode: 'base',
-        lifecycle: 'terminal',
-        status: 'active',
-    };
-}
-beforeEach(() => {
-    closeDb();
-    home = mkdtempSync(join(tmpdir(), 'crtr-node-outcome-'));
-    process.env['CRTR_HOME'] = home;
-    migrate(openDb());
-});
-afterEach(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-});
-after(() => {
-    closeDb();
-    if (priorHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = priorHome;
-});
-test('the terminal outcome latch survives competing terminal transitions and revive', () => {
-    createNode(node('latched'));
-    transition('latched', 'finish');
-    transition('latched', 'cancel');
-    let row = getRow('latched');
-    assert.deepEqual({ kind: row.outcome_kind, reason: row.outcome_reason, revision: row.outcome_revision }, {
-        kind: 'failure', reason: 'finished', revision: 1,
-    });
-    transition('latched', 'revive');
-    row = getRow('latched');
-    assert.equal(row.outcome_at === null, false, 'revive must not clear a latched outcome');
-    assert.equal(row.outcome_revision, 1);
-});
-test('outcome detail keeps only a 500-byte first line', () => {
-    createNode(node('detail'));
-    transition('detail', 'crash', {
-        outcome: { detail: { schema: 'crtr.node-outcome-detail/v1', message: `${'x'.repeat(1_000)}\nignored` } },
-    });
-    const detail = JSON.parse(getRow('detail').outcome_detail_json);
-    assert.equal(Buffer.byteLength(detail.message, 'utf8'), 500);
-    assert.equal(detail.message.includes('\n'), false);
-});
-test('the outcome composer is total and omits an oversized structured result', () => {
-    const meta = node('document');
-    meta.description = 'x'.repeat(2 * 1024);
-    createNode(meta);
-    const document = composeNodeOutcomeDocument({
-        node: meta,
-        outcome: { kind: 'result', reason: 'finalized', at: new Date().toISOString(), revision: 1, detailJson: null },
-        action: { name: 'test-action', payload: { callback: 'one' } },
-        finalReport: 'final.md',
-        structuredResult: { value: 'y'.repeat(300 * 1024) },
-    });
-    assert.ok(Buffer.byteLength(JSON.stringify(document), 'utf8') <= 256 * 1024);
-    assert.equal(Buffer.byteLength(document.node.description, 'utf8') <= 1024, true);
-    assert.equal(document.result?.structuredResult, undefined);
-    assert.equal(document.result?.structuredResultOmitted, true);
-});
-test('the outcome composer caps a failure document with an oversized node name', () => {
-    const meta = node('failure-document');
-    meta.name = 'x'.repeat(300 * 1024);
-    const document = composeNodeOutcomeDocument({
-        node: meta,
-        outcome: { kind: 'failure', reason: 'crashed', at: new Date().toISOString(), revision: 1, detailJson: null },
-        action: { name: 'test-action', payload: { callback: 'one' } },
-    });
-    assert.ok(Buffer.byteLength(JSON.stringify(document), 'utf8') <= 256 * 1024);
-    assert.ok(Buffer.byteLength(document.node.name, 'utf8') <= 1024);
-    assert.equal(document.result, undefined);
-    assert.ok(document.failure);
-});
-test('a canonical final supersedes a prior failure outcome and increments revision', async () => {
-    createNode(node('supersede'));
-    transition('supersede', 'crash');
-    transition('supersede', 'revive');
-    await pushFinal('supersede', 'recovered and finished');
-    const row = getRow('supersede');
-    assert.deepEqual({ kind: row.outcome_kind, reason: row.outcome_reason, revision: row.outcome_revision }, {
-        kind: 'result', reason: 'finalized', revision: 2,
-    });
-    assert.equal(row.outcome_detail_json, null);
-});
-test('outcome delivery rejects an oversized payload before a node is armed', () => {
-    createNode(node('oversized-payload'));
-    assert.throws(() => armOutcomeAction({
-        nodeId: 'oversized-payload', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { value: 'x'.repeat(OUTCOME_PAYLOAD_MAX_BYTES) },
-    }), /exceeds/);
-    assert.equal(outcomeDelivery('oversized-payload'), null);
-});
-test('outcome delivery armed after settlement is born pending with its document', () => {
-    createNode(node('settled-delivery'));
-    transition('settled-delivery', 'crash');
-    const delivery = armOutcomeAction({
-        nodeId: 'settled-delivery', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { callback: 'one' }, now: 123,
-    });
-    assert.equal(delivery?.state, 'pending');
-    assert.equal(delivery?.nextAttemptAt, 123);
-    const document = delivery === null ? null : messageBodyForDelivery(delivery.deliveryId);
-    assert.deepEqual(document && {
-        schema: document.schema,
-        outcomeId: document.outcomeId,
-        action: document.action,
-    }, {
-        schema: 'crtr.node-outcome/v1',
-        outcomeId: 'settled-delivery:1',
-        action: { name: 'test-action', payload: { callback: 'one' } },
-    });
-});
-test('outcome delivery state is fenced, recoverable, and follows the durable backoff', () => {
-    createNode(node('delivery'));
-    assert.ok(armOutcomeAction({
-        nodeId: 'delivery', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', payload: { callback: 'one' }, now: 100,
-    }));
-    transition('delivery', 'crash');
-    assert.equal(outcomeDelivery('delivery')?.state, 'pending');
-    assert.ok(messageBodyForDelivery(outcomeDelivery('delivery').deliveryId), 'the armed row is stamped with its outcome document');
-    const first = claimExternalActionDelivery(outcomeDelivery('delivery').deliveryId, Date.now(), 'daemon-a');
-    assert.equal(first.state, 'handed_off');
-    assert.equal(settleDelivery(first.deliveryId, first.attempts, 'daemon-b', { state: 'accepted' }, Date.now()), false, 'a stale claimant cannot settle');
-    assert.equal(settleDelivery(first.deliveryId, first.attempts, 'daemon-a', { state: 'accepted' }, Date.now()), true);
-    assert.equal(outcomeDelivery('delivery')?.state, 'acknowledged');
-    createNode(node('recover'));
-    armOutcomeAction({ nodeId: 'recover', actionName: 'test-action', argv: ['/bin/true'], cwd: home, configOrigin: 'test', now: 100 });
-    transition('recover', 'crash');
-    const running = claimExternalActionDelivery(outcomeDelivery('recover').deliveryId, Date.now(), 'daemon-a');
-    assert.equal(running.state, 'handed_off');
-    const recoveredAt = Date.now();
-    assert.equal(resetHandedOffDeliveries(recoveredAt), 1);
-    assert.deepEqual(outcomeDelivery('recover') && {
-        state: outcomeDelivery('recover').state,
-        nextAttemptAt: outcomeDelivery('recover').nextAttemptAt,
-        claimOwner: outcomeDelivery('recover').claimOwner,
-    }, { state: 'pending', nextAttemptAt: recoveredAt, claimOwner: null });
-});
-test('v39 migrates a v38 database and backfills finalized and terminal rows', () => {
-    const dbPath = join(home, 'v38.db');
-    mkdirSync(join(home, 'nodes'), { recursive: true });
-    const db = new DatabaseSync(dbPath);
-    db.exec('PRAGMA foreign_keys = ON;');
-    for (const migration of MIGRATIONS.slice(0, 38))
-        migration(db);
-    db.prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, final_report, finalized_at, terminal_reason)
-    VALUES (?, ?, 'general', 'base', 'terminal', ?, ?, ?, ?, ?, ?)`)
-        .run('finalized', 'finalized', 'done', home, '2026-01-01T00:00:00.000Z', 'report.md', '2026-01-01T01:00:00.000Z', 'finalized');
-    db.prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, terminal_reason)
-    VALUES (?, ?, 'general', 'base', 'terminal', ?, ?, ?, ?)`)
-        .run('dead', 'dead', 'dead', home, '2026-01-02T00:00:00.000Z', 'crashed');
-    MIGRATIONS[38](db);
-    const rows = db.prepare('SELECT node_id, outcome_kind, outcome_reason, outcome_at, outcome_revision FROM nodes ORDER BY node_id').all().map((row) => ({ ...row }));
-    assert.deepEqual(rows, [
-        { node_id: 'dead', outcome_kind: 'failure', outcome_reason: 'crashed', outcome_at: '2026-01-02T00:00:00.000Z', outcome_revision: 1 },
-        { node_id: 'finalized', outcome_kind: 'result', outcome_reason: 'finalized', outcome_at: '2026-01-01T01:00:00.000Z', outcome_revision: 1 },
-    ]);
-    assert.ok(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'node_outcome_deliveries'").get());
-    assert.ok(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_nodes_deadline'").get());
-    db.close();
-});

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

@@ -1 +0,0 @@
-export {};

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

@@ -1,66 +0,0 @@
-// Explicit file-context discovery never treats the crouter home
-// (`~/.crouter`, the user scope root) as a project ancestor. Canvas runtime
-// artifacts live below that root, while a nested `~/.crouter/.crouter/memory/`
-// store can belong to a differently scoped node. The user-root fence keeps its
-// explicitly routed docs out of unrelated canvas-file reads.
-//
-// Run: node --import tsx/esm --test src/core/__tests__/on-read-crouter-home-fence.test.ts
-import { test, before, beforeEach, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { closeDb, migrate, openDb } 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;
-before(() => {
-    prevHomeEnv = process.env['HOME'];
-});
-beforeEach(() => {
-    closeDb();
-    resetScopeCache();
-    // A private user HOME so `homedir()`/`userScopeRoot()` resolve into our
-    // sandbox, not the real machine.
-    fakeHome = mkdtempSync(join(tmpdir(), 'crtr-fence-home-'));
-    process.env['HOME'] = fakeHome;
-    // The node graph (canvas.db) lives in its own CRTR_HOME so spawnNode does not
-    // touch the fake user home; the read path we test is constructed by hand.
-    canvasHome = mkdtempSync(join(tmpdir(), 'crtr-fence-canvas-'));
-    process.env['CRTR_HOME'] = canvasHome;
-    migrate(openDb());
-});
-after(() => {
-    closeDb();
-    resetScopeCache();
-    rmSync(canvasHome, { recursive: true, force: true });
-    rmSync(fakeHome, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-    if (prevHomeEnv === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = prevHomeEnv;
-});
-test('a store nested in the crouter home does not leak into a canvas-artifact read', async () => {
-    const node = (await spawnNode({ kind: 'general', cwd: fakeHome, parent: null })).node_id;
-    // A private store misresolved into the crouter home: `~/.crouter/.crouter/memory/`.
-    const leakedStore = join(fakeHome, '.crouter', '.crouter', 'memory');
-    mkdirSync(leakedStore, { recursive: true });
-    writeFileSync(join(leakedStore, 'private-thing.md'), '---\nkind: knowledge\n' +
-        "when-and-why-to-read: When X, read this because Y.\n" +
-        'surfaces:\n' +
-        '  - {on: read, match: "**/*.md", at: content}\n---\n' +
-        'PRIVATE ASSISTANT MEMORY MUST NOT LEAK\n');
-    // A canvas runtime artifact under the crouter home — the shape of every node
-    // report/context file the harness auto-reads.
-    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, 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.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1,132 +0,0 @@
-// 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';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { closeDb, migrate, openDb } from '../canvas/db.js';
-import { resetScopeCache } from '../scope.js';
-import { spawnNode } from '../runtime/nodes.js';
-import { renderOnReadDocs } from '../substrate/on-read-node.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;
-let prevHomeEnv;
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-onread-home-'));
-    process.env['CRTR_HOME'] = home;
-    prevHomeEnv = process.env['HOME'];
-});
-beforeEach(() => {
-    closeDb();
-    resetScopeCache();
-    rmSync(home, { recursive: true, force: true });
-    if (prevHomeEnv === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = prevHomeEnv;
-    work = mkdtempSync(join(tmpdir(), 'crtr-onread-work-'));
-    migrate(openDb());
-});
-after(() => {
-    closeDb();
-    resetScopeCache();
-    rmSync(home, { recursive: true, force: true });
-    rmSync(work, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-    if (prevHomeEnv === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = prevHomeEnv;
-});
-test('project and user memory docs without read surfaces do not fire on file reads', async () => {
-    const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
-    process.env['HOME'] = fakeHome;
-    resetScopeCache();
-    const node = (await spawnNode({ kind: 'general', cwd: join(fakeHome, 'work'), parent: null })).node_id;
-    const userMemDir = join(fakeHome, '.crouter', 'memory');
-    mkdirSync(userMemDir, { recursive: true });
-    writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
-        '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');
-    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, 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 exposure survives a strict resume and resets for a fresh context', async () => {
-    const node = (await 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');
-    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' +
-        '  - {on: read, match: "./src/**", at: content}\n---\n' +
-        `${FIXTURE_BODY}\n`);
-    const readFile = join(work, 'src', 'file.ts');
-    mkdirSync(join(work, 'src'), { recursive: true });
-    writeFileSync(readFile, 'export const x = 1;\n');
-    // pi process #1: cold load; first read surfaces the doc
-    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');
-    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', async () => {
-    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
-    const memDir = join(work, '.crouter', 'memory');
-    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' +
-        'surfaces:\n' +
-        '  - {on: read, match: "./src/**", at: content}\n---\n' +
-        'ACME PROJECT OPERATING GUIDE\n');
-    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, freshTranscriptTarget());
-    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
-    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.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1,135 +0,0 @@
-// 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 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.
-//
-// Run: node --import tsx/esm --test src/core/__tests__/on-read-nested-store.test.ts
-import { test, before, beforeEach, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { closeDb, migrate, openDb } from '../canvas/db.js';
-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;
-let fakeHome;
-let prevHomeEnv;
-before(() => {
-    prevHomeEnv = process.env['HOME'];
-});
-beforeEach(() => {
-    closeDb();
-    resetScopeCache();
-    clearSessionCache();
-    fakeHome = mkdtempSync(join(tmpdir(), 'crtr-nested-home-'));
-    process.env['HOME'] = fakeHome;
-    canvasHome = mkdtempSync(join(tmpdir(), 'crtr-nested-canvas-'));
-    process.env['CRTR_HOME'] = canvasHome;
-    migrate(openDb());
-});
-after(() => {
-    closeDb();
-    resetScopeCache();
-    rmSync(canvasHome, { recursive: true, force: true });
-    rmSync(fakeHome, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-    if (prevHomeEnv === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = prevHomeEnv;
-});
-/** 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'), '---\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' +
-        '  - {on: read, match: "./**", at: content}\n---\n' +
-        `${ROOT_BODY}\n`);
-    const nestedStore = join(work, 'pkg', '.crouter', 'memory');
-    mkdirSync(nestedStore, { recursive: true });
-    writeFileSync(join(nestedStore, 'INDEX.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When working in pkg, this knowledge should be read because it carries the package constraints.\n' +
-        'surfaces:\n' +
-        '  - {on: workspace-open, at: content}\n' +
-        '  - {on: read, match: "./**", at: content}\n---\n' +
-        `${NESTED_BODY}\n`);
-    // A bootless neighbour in the same discovered store: it wins no delivery of
-    // its own, so only a listing can ever disclose it.
-    writeFileSync(join(nestedStore, 'constraint.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When changing pkg internals, this knowledge should be read because it names the constraint.\n---\n' +
-        'NESTED NEIGHBOUR BODY\n');
-    return work;
-}
-test('a nested store front door surfaces on a read beneath its owning dir, not outside it', async () => {
-    const work = makeWorkTree();
-    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
-    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, freshTranscriptTarget());
-    assert.ok(rendered.includes(NESTED_BODY), `read beneath pkg surfaces the nested front door; got: ${rendered}`);
-    // A content delivery is a read: the discovered store's own listing comes
-    // with it, answered from the corpus the read walk discovered.
-    assert.match(rendered, /\[\[work\/pkg\/constraint\]\]: When changing pkg internals/, `the delivered front door discloses its directory's bootless member; 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, 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 exposure ledger', async () => {
-    const work = makeWorkTree();
-    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
-    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, 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', async () => {
-    const userStore = join(fakeHome, '.crouter', 'memory');
-    mkdirSync(userStore, { recursive: true });
-    writeFileSync(join(userStore, 'control.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When reading markdown, this knowledge should be read because it is the corpus-loaded control fixture.\n' +
-        'surfaces:\n' +
-        '  - {on: read, match: "**/*.md", at: content}\n---\n' +
-        'USER CONTROL BODY\n');
-    writeFileSync(join(userStore, 'dot-routed.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When anything, this knowledge should be read because it must never fire.\n' +
-        'surfaces:\n' +
-        '  - {on: read, match: "./**", at: content}\n---\n' +
-        'USER DOT BODY MUST NOT FIRE\n');
-    const work = join(fakeHome, 'work');
-    mkdirSync(work, { recursive: true });
-    const node = (await spawnNode({ kind: 'general', cwd: work, parent: null })).node_id;
-    const readFile = join(fakeHome, 'notes', 'thing.md');
-    mkdirSync(join(fakeHome, 'notes'), { recursive: true });
-    writeFileSync(readFile, '# a note\n');
-    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}`);
-});

package/dist/core/__tests__/parse-argv-stdin-secret.test.d.ts

@@ -1 +0,0 @@
-export {};