@north-light/crouter 0.3.235 → 0.3.237

package/dist/core/substrate/plan.d.ts

@@ -0,0 +1,94 @@
+import { type MemoryDoc, type MemoryScope, type MemoryTarget } from '../memory-resolver.js';
+import { type DocKind, type Rung, type SubstrateDoc, type SurfaceEntry, type SurfaceEvent } from './schema.js';
+import type { EventCorpusDoc } from './session-cache.js';
+import type { NodeConfigSubject } from './subject-fields.js';
+/** What the event exposes to match against. Every field is optional: an event
+ *  invoked without its payload matches nothing rather than throwing. */
+export interface DeliveryPayload {
+    /** `read`: the file that was read. Realpathed by the planner. */
+    absoluteFile?: string;
+    /** `read`: the read file's own frontmatter. Parsed from the file when omitted. */
+    readFrontmatter?: Record<string, unknown>;
+    /** `memory-read`: the exact canonical name the read resolved to. */
+    resolvedCanonicalName?: string;
+    /** `memory-read`: realpath of the resolved document, which never delivers to
+     *  itself. */
+    resolvedDocPath?: string;
+    /** `command` / `pre-command`: the command string. */
+    command?: string;
+}
+/** A gate verdict with the reason a failure carries. */
+export type GateOutcome = {
+    pass: true;
+} | {
+    pass: false;
+    reason: string;
+};
+/** One authored surface entry of this event and how it fared. `matched` folds
+ *  the entry's constraints AND its own gate; `gate` isolates the gate so a
+ *  reader can tell "did not fit" from "excluded by this node's config". */
+export interface EntryDecision {
+    entry: SurfaceEntry;
+    matched: boolean;
+    gate: GateOutcome;
+}
+/** One document's delivery decision for one event. */
+export interface DeliveryRecord {
+    /** Canonical name — the identity dedup resolves. */
+    name: string;
+    kind: DocKind;
+    scope: MemoryScope;
+    /** Absolute path to the document file. */
+    storePath: string;
+    /** From the node's own store, which is floored rather than capped at boot. */
+    nodeLocal: boolean;
+    /** Every entry the document authored for this event. */
+    authoredEntries: EntryDecision[];
+    /** The highest-rung entry that matched, or null when none did. */
+    matchedEntry: SurfaceEntry | null;
+    /** The matched entry's rung — what the author asked for, before the cap. */
+    authoredRung: Rung;
+    /** The profile relationship's cap on this document's store, or null when the
+     *  event is uncapped or the document is node-local. */
+    projectMemoryCap: Rung | null;
+    /** `minRung(authoredRung, projectMemoryCap)`. */
+    cappedRung: Rung;
+    docGate: GateOutcome;
+    /** The matched entry's gate, or the verdict that excluded every authored
+     *  entry; null when the document authored no entry for this event. */
+    entryGate: GateOutcome | null;
+    /** What this document delivers at after gates, cap, and the boot node-local
+     *  floor. `none` = delivers nothing. */
+    finalRung: Rung;
+    /** This document is the one its canonical name resolves to for this event. */
+    winner: boolean;
+    /** The document that took this one's name, when it lost the dedup. */
+    shadowedBy: {
+        name: string;
+        scope: MemoryScope;
+        path: string;
+    } | null;
+    /** The parsed document — the renderers' input. */
+    doc: SubstrateDoc;
+    /** The resolver descriptor behind it: physical path, representation, and the
+     *  routing anchor a `./` memory-read glob matches against. */
+    source: MemoryDoc;
+}
+/** Every document considered for one event, in corpus (precedence) order. */
+export interface DeliveryPlan {
+    event: SurfaceEvent;
+    subject: NodeConfigSubject | null;
+    target: MemoryTarget;
+    docs: DeliveryRecord[];
+}
+/** Which boot block a record belongs to. The node's own store is the catch-all
+ *  this-node store and rides into the knowledge block whatever its kind, so a
+ *  record's kind alone does not answer this. */
+export declare function bootPartitionOf(record: Pick<DeliveryRecord, 'kind' | 'nodeLocal'>): DocKind;
+/** Plan one event's delivery.
+ *
+ *  `corpus` is the already-loaded document set. The live renderers pass their
+ *  session cache (the corpus is scanned and parsed once per session); an
+ *  inspection caller omits it and the planner loads the event's corpus from
+ *  `target`. Either way the planner writes nothing. */
+export declare function planDelivery(subject: NodeConfigSubject | null, target: MemoryTarget, event: SurfaceEvent, payload?: DeliveryPayload, corpus?: readonly EventCorpusDoc[]): DeliveryPlan;

package/dist/core/substrate/plan.js

@@ -0,0 +1,266 @@
+// plan.ts — the pure delivery planner: for one (subject, target, event,
+// payload) tuple it computes the structured per-document delivery decision the
+// renderers turn into text and the inspection commands print as a table. It
+// renders nothing and touches no exposure state.
+//
+// The pipeline has two halves and this module is the UPSTREAM one:
+//
+//   planDelivery (subject,event -> decisions) -> exposure ledger dedup ->
+//   render -> registerDocumentExposure
+//
+// The ledger (injected-store.ts) records what a live context has ALREADY been
+// given; the planner computes what a state WOULD be given. Renderers own the
+// downstream half, so a plan can be computed for a hypothetical subject without
+// disturbing any node's real ledger.
+//
+// Two decisions are event-specific and deliberately so:
+//
+//   • THE PROFILE CAP reaches boot and workspace-open only. Every other event
+//     is reached by an explicit act (a read, a command) and delivers at the
+//     authored rung.
+//   • DEDUP PARTICIPATION differs. At boot every ELIGIBLE document participates
+//     — including one with no boot entry, because the boot catalog counts it
+//     into its directory's `[+N more]` — and the dedup runs per boot partition,
+//     since the boot render emits an independent block per partition. At every
+//     other event only a document that actually DELIVERS participates, so a
+//     nearer document that does not match never suppresses a farther one that
+//     does.
+import { homedir } from 'node:os';
+import { dirname, parse, sep } from 'node:path';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { readText, realpathOrSelf } from '../fs-utils.js';
+import { listProjectMemoryDocs, loadMemoryTargetView, loadStoreMemoryDocs, openProjectMemoryStore, } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
+import { gatePasses, surfaceEntryGatePasses } from './gate.js';
+import { minRung, parseSubstrateDoc, rungAtLeast, } from './schema.js';
+import { matchingSurfaceEntry, surfaceEntryParticipates } from './surface-match.js';
+/** Which boot block a record belongs to. The node's own store is the catch-all
+ *  this-node store and rides into the knowledge block whatever its kind, so a
+ *  record's kind alone does not answer this. */
+export function bootPartitionOf(record) {
+    return record.nodeLocal ? 'knowledge' : record.kind;
+}
+/** Plan one event's delivery.
+ *
+ *  `corpus` is the already-loaded document set. The live renderers pass their
+ *  session cache (the corpus is scanned and parsed once per session); an
+ *  inspection caller omits it and the planner loads the event's corpus from
+ *  `target`. Either way the planner writes nothing. */
+export function planDelivery(subject, target, event, payload = {}, corpus) {
+    const resolved = resolvePayload(event, payload);
+    const considered = considerFor(event, corpus ?? loadEventCorpus(target, event), resolved);
+    const docs = considered.map(({ doc, source }) => decide(doc, source, subject, event, resolved));
+    resolveWinners(event, docs);
+    return { event, subject, target, docs };
+}
+function resolvePayload(event, payload) {
+    if (event !== 'read' || payload.absoluteFile === undefined) {
+        return { ...payload, readFrontmatter: payload.readFrontmatter ?? {} };
+    }
+    const absoluteFile = realpathOrSelf(payload.absoluteFile);
+    return {
+        ...payload,
+        absoluteFile,
+        readFrontmatter: payload.readFrontmatter ?? readFileFrontmatter(absoluteFile),
+    };
+}
+function readFileFrontmatter(absReadFile) {
+    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
+        return {};
+    try {
+        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+// The considered set — the corpus plus the event's own discovery and
+// self-exclusion rules.
+function considerFor(event, corpus, payload) {
+    if (event === 'read') {
+        const abs = payload.absoluteFile;
+        if (abs === undefined)
+            return [...corpus];
+        // Enclosing stores lead: a store discovered from the read file is the
+        // nearest source of an identity the mounted corpus may also carry.
+        return [...enclosingProjectDocs(abs), ...corpus].filter(({ doc }) => realpathOrSelf(doc.path) !== abs);
+    }
+    if (event === 'memory-read' && payload.resolvedDocPath !== undefined) {
+        const exclude = payload.resolvedDocPath;
+        return corpus.filter(({ doc }) => realpathOrSelf(doc.path) !== exclude);
+    }
+    return [...corpus];
+}
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
+function isJunkAncestor(dir) {
+    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
+}
+/** Project docs from every workspace store enclosing the read file, nearest
+ *  first. This is a discovery walk only: each returned doc must still match an
+ *  explicit trigger. A store that declares no namespace does not mount here
+ *  either — an unmounted store has no canonical identities to deliver under.
+ *  The stores carry the neutral ceiling: the read event is uncapped by design,
+ *  reached only by an explicit file read. */
+function enclosingProjectDocs(absReadFile) {
+    const out = [];
+    const seen = new Set();
+    const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    while (true) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
+            const store = openProjectMemoryStore(dir);
+            if (store.mountStatus === 'ready' && !seen.has(store.storeRoot)) {
+                seen.add(store.storeRoot);
+                for (const source of loadStoreMemoryDocs(store, true)) {
+                    const doc = parseSubstrateDoc(source);
+                    if (doc !== null)
+                        out.push({ doc, source });
+                }
+            }
+        }
+        if (dir === home || dir === fsRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return out;
+}
+/** The event's corpus for a target, for callers that hold no session cache.
+ *  Boot orders node-local docs LAST so a resolver document keeps its identity
+ *  against a same-named node-local one; workspace-open sees project stores
+ *  only; every other event sees the whole mounted corpus. */
+function loadEventCorpus(target, event) {
+    const sources = event === 'workspace-open'
+        ? listProjectMemoryDocs(target.cwd, target.profileId)
+        : loadMemoryTargetView(target, { quiet: true }).docs;
+    const parsed = [];
+    for (const source of sources) {
+        const doc = parseSubstrateDoc(source);
+        if (doc !== null)
+            parsed.push({ doc, source });
+    }
+    if (event !== 'boot')
+        return parsed;
+    return [
+        ...parsed.filter((e) => e.doc.scope !== 'node'),
+        ...parsed.filter((e) => e.doc.scope === 'node'),
+    ];
+}
+// The per-document decision.
+function decide(doc, source, subject, event, payload) {
+    const match = {
+        absoluteFile: payload.absoluteFile,
+        readFrontmatter: payload.readFrontmatter,
+        resolvedCanonicalName: payload.resolvedCanonicalName,
+        routingAnchor: source.routingAnchor,
+        command: payload.command,
+    };
+    const docGate = documentGateOutcome(doc, subject);
+    const authoredEntries = doc.surfaces
+        .filter((entry) => entry.on === event)
+        .map((entry) => ({
+        entry,
+        matched: surfaceEntryParticipates(entry, doc, subject, event, match),
+        gate: entryGateOutcome(entry, subject),
+    }));
+    const matchedEntry = matchingSurfaceEntry(doc, subject, event, match);
+    const authoredRung = matchedEntry?.at ?? 'none';
+    const nodeLocal = doc.scope === 'node';
+    const capped = event === 'boot' || event === 'workspace-open';
+    const projectMemoryCap = capped && !nodeLocal ? doc.projectMemory : null;
+    const cappedRung = projectMemoryCap === null ? authoredRung : minRung(authoredRung, projectMemoryCap);
+    let finalRung = docGate.pass ? cappedRung : 'none';
+    // The one rung FLOOR, scoped to the node store at boot: a node-local doc with
+    // no boot entry still shows its bare name rather than collapsing into its
+    // directory's hidden count. A node-local doc whose boot entries all fail
+    // stays absent.
+    if (event === 'boot' &&
+        nodeLocal &&
+        docGate.pass &&
+        !rungAtLeast(finalRung, 'name') &&
+        !doc.surfaces.some((entry) => entry.on === 'boot')) {
+        finalRung = 'name';
+    }
+    return {
+        name: doc.name,
+        kind: doc.kind,
+        scope: doc.scope,
+        storePath: doc.path,
+        nodeLocal,
+        authoredEntries,
+        matchedEntry,
+        authoredRung,
+        projectMemoryCap,
+        cappedRung,
+        docGate,
+        entryGate: recordEntryGate(authoredEntries, matchedEntry),
+        finalRung,
+        winner: false,
+        shadowedBy: null,
+        doc,
+        source,
+    };
+}
+/** A missing subject cannot satisfy a gate, so a gated document is skipped and
+ *  an ungated one still delivers. A predicate that throws excludes only its own
+ *  document — never the whole render. */
+function documentGateOutcome(doc, subject) {
+    if (doc.gate === undefined)
+        return { pass: true };
+    if (subject === null)
+        return { pass: false, reason: 'gated document with no node config to match' };
+    try {
+        return gatePasses(doc, subject)
+            ? { pass: true }
+            : { pass: false, reason: 'document gate does not match this node config' };
+    }
+    catch (err) {
+        return { pass: false, reason: `document gate failed to evaluate: ${String(err)}` };
+    }
+}
+function entryGateOutcome(entry, subject) {
+    if (entry.gate === undefined)
+        return { pass: true };
+    return surfaceEntryGatePasses(entry, subject)
+        ? { pass: true }
+        : { pass: false, reason: 'entry gate does not match this node config' };
+}
+function recordEntryGate(entries, matched) {
+    if (entries.length === 0)
+        return null;
+    if (matched !== null)
+        return { pass: true };
+    const gatedOut = entries.find((e) => !e.gate.pass);
+    return gatedOut === undefined ? { pass: true } : gatedOut.gate;
+}
+// Winner resolution — first-win by canonical name over the corpus's precedence
+// order, within the event's participating set.
+function participates(record, event) {
+    if (!record.docGate.pass)
+        return false;
+    // Boot counts an eligible document even when it delivers nothing, because the
+    // catalog tree still counts it. A `none` cap removes the document from the
+    // corpus entirely, so it cannot shadow a wider-scope document either.
+    if (event === 'boot')
+        return record.projectMemoryCap !== 'none';
+    return rungAtLeast(record.finalRung, 'name');
+}
+function resolveWinners(event, docs) {
+    const winners = new Map();
+    for (const record of docs) {
+        if (!participates(record, event))
+            continue;
+        const key = event === 'boot' ? `${bootPartitionOf(record)}:${record.name}` : record.name;
+        const held = winners.get(key);
+        if (held === undefined) {
+            winners.set(key, record);
+            record.winner = true;
+            continue;
+        }
+        record.shadowedBy = { name: held.name, scope: held.scope, path: held.storePath };
+    }
+}

package/dist/core/substrate/render.d.ts

@@ -4,7 +4,7 @@ import type { NodeConfigSubject } from './subject-fields.js';
 /** The computed "sub-personas you may spawn" menu for a subject's kind — the
  *  live restoration of the old `personas/resolve.ts` static menu, now derived
  *  at render time from the merged kind registry (`subKindsAvailableTo`) so it
- *  can never drift from `sys prompt-review --list`'s `subPersonas` metadata.
+ *  can never drift from `sys context prompt-review --list`'s `subPersonas` metadata.
  *  Returns '' when the kind has zero available sub-kinds (no dangling empty
  *  header). Emitted for BOTH base and orchestrator modes per the CTO's ruling —
  *  mode is irrelevant to which sub-kinds are spawnable. */
@@ -20,11 +20,10 @@ export declare function renderPreferencesForSubject(subject: NodeConfigSubject |
  *  doc PLUS the node-local memory docs (any kind) — resolver docs win
  *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
  *  like the preference block: content prose first (general→specific,
- *  node-local last), then the preview/name catalog tree. Node-local docs are
- *  floored HERE — a bootless node-local doc's rung is bumped to `name` before
- *  grouping, so it still surfaces as a bare-name tree entry rather than
- *  collapsing into a `[+N more]` count (its body still never renders: floored
- *  docs never reach the `content` rung). Procedural guidance and factual
+ *  node-local last), then the preview/name catalog tree. A bootless node-local
+ *  doc arrives floored to `name`, so it surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance and factual
  *  references both live here as `knowledge`. Returns '' when nothing is
  *  eligible. */
 export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string, target?: ExposureTarget): string;