@north-light/api 0.3.579 → 0.3.587

package/dist/core/substrate/gate-explain.js

@@ -0,0 +1,397 @@
+// gate-explain.ts — why a gate refused THIS node, in the words the reader can
+// act on: their own value on the left, the gate's demand on the right.
+//
+// This is a SECOND, opt-in read of the same predicate `evalCondition` already
+// judged (predicate.ts), never a replacement for it. It shares that engine's
+// leaf primitives (`matchField`, `getField`), so a leaf verdict cannot drift
+// between the verdict and its explanation; only the structural walk exists
+// twice, and the fallback covers the walk. It is never called while planning —
+// only while rendering a document a human is already looking at.
+//
+// It is advisory. When it cannot decompose a failure it returns nothing, and
+// every caller falls back to the planner's generic sentence rather than
+// inventing one.
+import { getField, matchField, evalCondition } from '../predicate.js';
+import { tildify } from '../fs-utils.js';
+/** The subject has no value at this field path — distinct from a value of
+ *  `null`, which a gate can legitimately demand. */
+export const ABSENT = Symbol('absent');
+// The structural walk.
+/** The failing clauses of `condition` against `subject`, or an empty list when
+ *  the failure cannot be decomposed — an `any`/`not` combinator swallowed it,
+ *  or the predicate is a shape this walk does not recognise. An empty list is
+ *  the caller's signal to print the generic reason instead. */
+export function explainGate(condition, subject) {
+    return walk(condition, subject) ?? [];
+}
+/** The failing clauses of one predicate, or `null` when its failure is opaque.
+ *  Opacity travels outward: a sibling's mismatch is not the remedy when an
+ *  undecomposable branch also failed, so the whole explanation is abandoned. */
+function walk(condition, subject) {
+    if (condition == null || typeof condition !== 'object')
+        return [];
+    if (Array.isArray(condition))
+        return collect(condition, subject);
+    const c = condition;
+    const clauses = [];
+    if ('any' in c || 'not' in c) {
+        // Neither is decomposed: an OR has no single failing branch to name, and a
+        // satisfied negation has no failing clause at all. When one of them is what
+        // failed, the whole explanation is abandoned — an honest generic sentence
+        // beats an invented clause. When it PASSED, the failure is elsewhere and
+        // the rest of the predicate still explains itself.
+        if ('any' in c && !evalCondition({ any: c['any'] }, subject))
+            return null;
+        if ('not' in c && !evalCondition({ not: c['not'] }, subject))
+            return null;
+    }
+    if ('all' in c) {
+        const nested = collect(Array.isArray(c['all']) ? c['all'] : [c['all']], subject);
+        if (nested === null)
+            return null;
+        clauses.push(...nested);
+    }
+    const fields = Object.keys(c).filter((key) => key !== 'all' && key !== 'any' && key !== 'not');
+    // An empty condition is inert — it matches nothing, and no field explains why.
+    if (fields.length === 0 && !('all' in c) && !('any' in c) && !('not' in c)) {
+        return [{ field: '', failure: 'malformed', actual: ABSENT, demand: c, defect: 'is empty, and an empty gate never matches' }];
+    }
+    for (const field of fields) {
+        const matcher = c[field];
+        if (matchField(getField(subject, field), matcher))
+            continue;
+        clauses.push(clauseFor(field, matcher, subject));
+    }
+    return clauses;
+}
+/** Every sub-predicate's clauses, or `null` as soon as one is opaque. */
+function collect(subs, subject) {
+    const clauses = [];
+    for (const sub of subs) {
+        const nested = walk(sub, subject);
+        if (nested === null)
+            return null;
+        clauses.push(...nested);
+    }
+    return clauses;
+}
+function clauseFor(field, matcher, subject) {
+    const raw = getField(subject, field);
+    const actual = raw === undefined ? ABSENT : raw;
+    const defect = matcherDefect(matcher);
+    return defect === null
+        ? { field, failure: 'mismatch', actual, demand: matcher }
+        : { field, failure: 'malformed', actual, demand: matcher, defect };
+}
+const KNOWN_OPS = new Set([
+    'eq', 'ne', 'in', 'nin', 'exists', 'contains', 'containsAll', 'containsAny',
+    'matches', 'imatches', 'gt', 'gte', 'lt', 'lte',
+]);
+/** What makes this matcher unsatisfiable by ANY node, or null when it is a
+ *  well-formed demand this node merely does not meet. */
+function matcherDefect(matcher) {
+    // A scalar or an array is compared directly by the engine — a demand this
+    // node fails, never a defect of the gate.
+    if (matcher === null || Array.isArray(matcher) || typeof matcher !== 'object')
+        return null;
+    for (const [op, arg] of Object.entries(matcher)) {
+        if (!KNOWN_OPS.has(op))
+            return `uses unknown operator "${op}" \u2014 unknown operators never match`;
+        if (op === 'matches' || op === 'imatches') {
+            if (typeof arg !== 'string')
+                return 'is matched against something that is not a pattern \u2014 it never matches';
+            try {
+                new RegExp(arg, op === 'imatches' ? 'i' : '');
+            }
+            catch {
+                return 'has an invalid regular expression \u2014 an invalid pattern never matches';
+            }
+        }
+        if (['gt', 'gte', 'lt', 'lte'].includes(op) && Number.isNaN(Number(arg))) {
+            return `compares ${op} against something that is not a number \u2014 it never matches`;
+        }
+    }
+    return null;
+}
+// The single phrasing site.
+/** The rail row a gate field names, because that row is the remedy. */
+function labelFor(field) {
+    if (field === 'hasManager')
+        return 'manager';
+    if (field === 'orchestration.depth')
+        return 'depth';
+    return field;
+}
+/** The grammar's own break between the reader's value and the gate's demand —
+ *  the only place a clause line may be split. */
+export const CLAUSE_SEPARATOR = ' | gate: ';
+/** One clause as one line of plain text — the ONLY place a gate failure is put
+ *  into human words. Callers own indentation, colour, wrapping, and joining. */
+export function formatClause(clause) {
+    if (clause.failure === 'malformed') {
+        const label = clause.field === '' ? 'the gate' : labelFor(clause.field);
+        return `${label} ${clause.defect ?? 'never matches'}`;
+    }
+    return `${labelFor(clause.field)}: ${renderActual(clause.actual)}${CLAUSE_SEPARATOR}${renderDemand(clause.demand)}`;
+}
+function renderActual(value) {
+    if (value === ABSENT || value === null || value === undefined)
+        return 'none';
+    if (typeof value === 'boolean')
+        return value ? 'yes' : 'no';
+    if (Array.isArray(value))
+        return value.map((v) => renderActual(v)).join(', ');
+    if (typeof value === 'string')
+        return value === '' ? 'none' : shortPath(value);
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/** The gate's demand, per matcher shape. Never regex source, never a full
+ *  home-prefixed path. */
+function renderDemand(matcher) {
+    if (matcher === null || matcher === undefined)
+        return 'none';
+    if (typeof matcher === 'boolean')
+        return matcher ? 'yes' : 'no';
+    if (typeof matcher === 'string')
+        return matcher === '' ? 'none' : shortPath(matcher);
+    if (typeof matcher === 'number')
+        return String(matcher);
+    if (Array.isArray(matcher))
+        return orList(matcher);
+    const ops = Object.entries(matcher);
+    if (ops.length === 0)
+        return 'nothing';
+    return ops.map(([op, arg]) => renderOp(op, arg)).join(' and ');
+}
+function renderOp(op, arg) {
+    switch (op) {
+        case 'eq':
+            return renderDemand(arg);
+        case 'ne':
+            return `not ${renderDemand(arg)}`;
+        case 'in':
+            return orList(arg);
+        case 'nin':
+            return `not ${orList(arg)}`;
+        case 'exists':
+            return arg === false ? 'no value' : 'any value';
+        case 'contains':
+            return `includes ${renderDemand(arg)}`;
+        case 'containsAll':
+            return `includes all of ${commaList(arg)}`;
+        case 'containsAny':
+            return `includes any of ${commaList(arg)}`;
+        case 'matches':
+        case 'imatches':
+            return typeof arg === 'string' ? readableRegex(arg) : 'a pattern';
+        case 'gt':
+            return `> ${String(arg)}`;
+        case 'gte':
+            return `\u2265 ${String(arg)}`;
+        case 'lt':
+            return `< ${String(arg)}`;
+        case 'lte':
+            return `\u2264 ${String(arg)}`;
+        default:
+            return `${op} ${String(arg)}`;
+    }
+}
+function orList(arg) {
+    const items = (Array.isArray(arg) ? arg : [arg]).map((v) => renderDemand(v));
+    return items.length === 0 ? 'nothing' : items.join(' or ');
+}
+function commaList(arg) {
+    return (Array.isArray(arg) ? arg : [arg]).map((v) => renderDemand(v)).join(', ');
+}
+function shortPath(value) {
+    return value.startsWith('/') ? tildify(value) : value;
+}
+// Regex reduction — every real `cwd` gate is an anchored literal path, whole or
+// followed by one alternation of the projects it covers, and it should read as
+// the directory or directories it means.
+const META = new Set(['\\', '^', '$', '.', '|', '?', '*', '+', '(', ')', '[', ']', '{', '}']);
+/** The pattern as the thing it demands: an anchored literal path collapsed to
+ *  the directory it names, else the longest literal run it insists on, else an
+ *  admission that it is a pattern. The source is never printed. */
+export function readableRegex(source) {
+    let body = source;
+    if (body.startsWith('^'))
+        body = body.slice(1);
+    // The house `cwd` idiom: a trailing "this directory or anything under it".
+    body = body.replace(/\((?:\?:)?\\?\/\|\$\)\??$/, '');
+    if (body.endsWith('$') && !body.endsWith('\\$'))
+        body = body.slice(0, -1);
+    const literal = unescapeLiteral(body);
+    if (literal !== null && literal !== '')
+        return shortPath(literal);
+    const branches = distributeAlternation(body);
+    if (branches !== null)
+        return branches.map((branch) => shortPath(branch)).join(' or ');
+    const run = longestLiteralRun(source);
+    return run === null ? 'a pattern' : `contains "${shortPath(run)}"`;
+}
+/** The pattern's plain text when it holds no unescaped metacharacter, else
+ *  null. `\/` and `\.` are literal characters and survive; `\d` and the other shorthand escapes are
+ *  classes and disqualify the whole pattern. */
+function unescapeLiteral(source) {
+    let out = '';
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '\\') {
+            const next = source[i + 1];
+            if (next === undefined || (!META.has(next) && next !== '/' && next !== '-'))
+                return null;
+            out += next;
+            i++;
+            continue;
+        }
+        if (META.has(ch))
+            return null;
+        out += ch;
+    }
+    return out;
+}
+/** The paths a literal prefix followed by ONE alternation group means: each
+ *  branch appended to the prefix, so the reader is handed directories they can
+ *  actually be in rather than the prefix they all share. Null when the body is
+ *  any other shape — a second group, text after the group, or a branch holding
+ *  a metacharacter outside the glob vocabulary. */
+function distributeAlternation(body) {
+    const open = body.indexOf('(');
+    if (open === -1 || !body.endsWith(')'))
+        return null;
+    const prefix = unescapeLiteral(body.slice(0, open));
+    if (prefix === null)
+        return null;
+    let inner = body.slice(open + 1, -1);
+    if (inner.startsWith('?:'))
+        inner = inner.slice(2);
+    // One group only: a nested group is a shape this reduction does not read.
+    if (inner.includes('(') || inner.includes(')'))
+        return null;
+    const branches = inner.split('|');
+    if (branches.length < 2)
+        return null;
+    const paths = [];
+    for (const branch of branches) {
+        const text = branchText(branch);
+        if (text === null)
+            return null;
+        paths.push(prefix + text);
+    }
+    return paths;
+}
+/** One branch as plain text, with a whole-segment wildcard rendered as the path
+ *  glob it means. The vocabulary is exactly `[^/]+` and `.*`; any other
+ *  metacharacter means the branch is not a path and the whole shape is
+ *  abandoned. */
+function branchText(branch) {
+    let out = '';
+    for (let i = 0; i < branch.length; i++) {
+        if (branch.startsWith('[^/]+', i)) {
+            out += '*';
+            i += 4;
+            continue;
+        }
+        if (branch.startsWith('[^\\/]+', i)) {
+            out += '*';
+            i += 5;
+            continue;
+        }
+        if (branch.startsWith('.*', i)) {
+            out += '*';
+            i += 1;
+            continue;
+        }
+        const ch = branch[i];
+        if (ch === '\\') {
+            const next = branch[i + 1];
+            if (next === undefined || (!META.has(next) && next !== '/' && next !== '-'))
+                return null;
+            out += next;
+            i++;
+            continue;
+        }
+        if (META.has(ch))
+            return null;
+        out += ch;
+    }
+    return out;
+}
+/** The longest stretch of characters EVERY string the pattern accepts contains,
+ *  or null when it guarantees nothing longer than a single character. Only text
+ *  outside every group and character class counts: a group may be alternated or
+ *  quantified away, so its contents are not guaranteed. A top-level alternation
+ *  guarantees nothing at all. */
+function longestLiteralRun(source) {
+    let best = '';
+    let run = '';
+    let depth = 0;
+    let inClass = false;
+    const flush = () => {
+        if (run.length > best.length)
+            best = run;
+        run = '';
+    };
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '\\') {
+            const next = source[i + 1];
+            i++;
+            if (depth === 0 && !inClass && next !== undefined && (META.has(next) || next === '/' || next === '-')) {
+                run += next;
+                continue;
+            }
+            flush();
+            continue;
+        }
+        if (inClass) {
+            if (ch === ']')
+                inClass = false;
+            continue;
+        }
+        if (ch === '[') {
+            flush();
+            inClass = true;
+            continue;
+        }
+        if (ch === '(') {
+            flush();
+            depth++;
+            continue;
+        }
+        if (ch === ')') {
+            flush();
+            if (depth > 0)
+                depth--;
+            continue;
+        }
+        // Branches share no text, so nothing survives a top-level alternation.
+        if (ch === '|' && depth === 0)
+            return null;
+        if (ch === '{') {
+            // A repetition count can be zero — the character it applies to goes, and
+            // the count itself is syntax, not text the pattern matches.
+            if (run.length > 0)
+                run = run.slice(0, -1);
+            flush();
+            const close = source.indexOf('}', i);
+            if (close !== -1)
+                i = close;
+            continue;
+        }
+        if (META.has(ch) || depth > 0) {
+            // A quantifier applies to the character before it, which is therefore not
+            // guaranteed — drop it from the run.
+            if ((ch === '?' || ch === '*') && run.length > 0)
+                run = run.slice(0, -1);
+            flush();
+            continue;
+        }
+        run += ch;
+    }
+    flush();
+    return best.length > 1 ? best : null;
+}

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

@@ -0,0 +1,29 @@
+import { type ProfileProjectMemory } from '../../api/dto/profiles.js';
+export declare const KINDS: readonly ["knowledge", "preference"];
+export type DocKind = (typeof KINDS)[number];
+/** Is `v` one of the two valid document kinds? */
+export declare function isDocKind(v: unknown): v is DocKind;
+export declare const RUNGS: readonly ["none", "name", "preview", "content"];
+export type Rung = ProfileProjectMemory;
+/** Ordinal of a rung on the ladder (none=0 … content=3). */
+export declare function rungRank(r: Rung): number;
+/** Does rung `r` disclose at least as much as `min`? */
+export declare function rungAtLeast(r: Rung, min: Rung): boolean;
+/** The lower of two rungs — the clamp automatic delivery applies to an
+ *  authored rung against its project relationship's cap. */
+export declare function minRung(a: Rung, b: Rung): Rung;
+/** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
+ *  the node-config subject. Typed loosely on purpose — the matcher engine owns
+ *  validation; structurally it is a field→matcher map with optional
+ *  `all`/`any`/`not` combinators. */
+export type GatePredicate = Record<string, unknown>;
+export type DocRepresentation = 'leaf-file' | 'directory-index';
+/** Which form a store-relative markdown path takes. */
+export declare function representationForPath(physicalRelativePath: string): DocRepresentation;
+/** Local name derived from a store-relative markdown path: ordering prefixes
+ *  stripped from every segment and one trailing `INDEX` collapsed. Empty only
+ *  for a root `INDEX.md`. */
+export declare function localNameFromPath(physicalRelativePath: string): string;
+/** A document's explicit frontmatter `name` as a local name — normalized with
+ *  one trailing `INDEX` collapsed — or `null` when it carries none. */
+export declare function explicitLocalName(fm: Record<string, unknown> | null | undefined): string | null;

package/dist/core/substrate/schema.js

@@ -0,0 +1,81 @@
+// schema.ts — the document kinds, the visibility ladder, and the path-derived
+// identity rule package files use to name their documents. Pure and side-effect
+// free.
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
+// Kinds — the two semantic kinds: `knowledge` (consult — procedural playbooks +
+// factual references merged) vs `preference` (behave — standing directives).
+export const KINDS = ['knowledge', 'preference'];
+/** Is `v` one of the two valid document kinds? */
+export function isDocKind(v) {
+    return typeof v === 'string' && KINDS.includes(v);
+}
+// The 4-rung visibility ladder. A strict, monotone ordering where each rung is a
+// superset of disclosure over the one before:
+//   none < name < preview < content
+// The ladder is ONE union, owned by the public API DTO (`ProfileProjectMemory`)
+// so a profile relationship's cap and a doc's authored rung are the same values
+// and clamp against each other without a conversion.
+export const RUNGS = PROFILE_PROJECT_MEMORY_VALUES;
+/** Ordinal of a rung on the ladder (none=0 … content=3). */
+export function rungRank(r) {
+    return RUNGS.indexOf(r);
+}
+/** Does rung `r` disclose at least as much as `min`? */
+export function rungAtLeast(r, min) {
+    return rungRank(r) >= rungRank(min);
+}
+/** The lower of two rungs — the clamp automatic delivery applies to an
+ *  authored rung against its project relationship's cap. */
+export function minRung(a, b) {
+    return rungRank(a) <= rungRank(b) ? a : b;
+}
+// Identity — how a package file's store-relative markdown path names its
+// document. A physical path may carry a two-digit `NN-` prefix on any segment
+// purely to pin structural order; the prefix is never part of the name.
+// `foo.md` and `foo/INDEX.md` both name `foo`.
+const NUMERIC_PREFIX_RE = /^\d{2}-/;
+/** The filename (and path segment) whose document fronts its directory. */
+const INDEX_SEGMENT = 'INDEX';
+/** Strip an optional `NN-` ordering prefix from ONE segment. */
+function normalizeNameSegment(segment) {
+    return segment.replace(NUMERIC_PREFIX_RE, '');
+}
+/** Strip the ordering prefix from EVERY segment of a slash-separated name. */
+function normalizeDocName(name) {
+    return name.split('/').map(normalizeNameSegment).join('/');
+}
+/** Split a name into segments, dropping empties. */
+function canonicalSegments(name) {
+    return name.split('/').filter((s) => s !== '');
+}
+/** Remove EXACTLY ONE trailing `INDEX` segment. */
+function collapseTrailingIndex(name) {
+    const segments = canonicalSegments(name);
+    if (segments[segments.length - 1] === INDEX_SEGMENT)
+        segments.pop();
+    return segments.join('/');
+}
+/** Normalized identity segments of a store-relative markdown path, extension
+ *  stripped. */
+function pathIdentitySegments(physicalRelativePath) {
+    return canonicalSegments(physicalRelativePath.replace(/\\/g, '/').replace(/\.md$/i, '')).map(normalizeNameSegment);
+}
+/** Which form a store-relative markdown path takes. */
+export function representationForPath(physicalRelativePath) {
+    const segments = pathIdentitySegments(physicalRelativePath);
+    return segments[segments.length - 1] === INDEX_SEGMENT ? 'directory-index' : 'leaf-file';
+}
+/** Local name derived from a store-relative markdown path: ordering prefixes
+ *  stripped from every segment and one trailing `INDEX` collapsed. Empty only
+ *  for a root `INDEX.md`. */
+export function localNameFromPath(physicalRelativePath) {
+    return collapseTrailingIndex(pathIdentitySegments(physicalRelativePath).join('/'));
+}
+/** A document's explicit frontmatter `name` as a local name — normalized with
+ *  one trailing `INDEX` collapsed — or `null` when it carries none. */
+export function explicitLocalName(fm) {
+    const raw = fm?.['name'];
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    return collapseTrailingIndex(normalizeDocName(raw.trim()));
+}

package/dist/core/substrate/subject-fields.d.ts

@@ -0,0 +1,52 @@
+import type { Mode, Lifecycle } from '../canvas/types.js';
+/** The gate input: a node's configuration as a structured object. Field names
+ *  and shape are the predicate vocabulary's dotted paths (`orchestration.depth`,
+ *  `hasManager`, …). There is intentionally NO `tags` field — NodeMeta has none. */
+export interface NodeConfigSubject {
+    /** The node's role, free-form (developer | explore | design | …). NodeMeta.kind. */
+    kind: string;
+    /** base (hands-on worker) | orchestrator (delegating manager). NodeMeta.mode. */
+    mode: Mode;
+    /** terminal (worker) | resident (manager). NodeMeta.lifecycle. */
+    lifecycle: Lifecycle;
+    /** Spine position: does this node have a manager? (= parent !== null). */
+    hasManager: boolean;
+    /** The node's working directory on disk. NodeMeta.cwd. */
+    cwd: string;
+    /** DERIVED: the scope scope.ts resolves for `cwd` — `project` when a
+     *  nearest-ancestor `.crouter/` exists at/above cwd, else `user`. */
+    scope: 'user' | 'project';
+    /** DERIVED orchestration metrics. */
+    orchestration: {
+        /** Spine distance (hops) from this node up to its root orchestrator. The
+         *  root itself is 0; a direct child of the root is 1; etc. */
+        depth: number;
+    };
+    /** DERIVED: `meta.profile_id` resolved to its manifest's mutable `name` (NOT
+     *  the stable directory id — gate authors write `gate: {profile: <name>}`).
+     *  null for historical null-profile rows, and null (never throwing) when the
+     *  profile has been deleted or its manifest is unreadable — this is a HOT,
+     *  every-doc-render path and must never brick boot/on-read gating. */
+    profile: string | null;
+    /** The run's grantee principal (`app:firstlight`): what a rule's `if: {app: ...}` matches. */
+    app: string;
+    /** Effective per-run scopes. */
+    scopes: readonly string[];
+    /** DERIVED: handles of the repos eligible for the node's rules: those enclosing `cwd`
+     *  (nearest first), then the repos of its profile's project paths. A rule's
+     *  `if: {repo: crouter}` holds when any element is `crouter`; a condition about the
+     *  directory itself uses `cwd`. */
+    repo: readonly string[];
+}
+export declare function effectiveScopes(scopes: readonly string[] | null | undefined): string[];
+/** The scope a cwd resolves into: `project` when scope.ts finds a
+ *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
+ *  resolver (`projectScopeRoot`). */
+export declare function scopeForCwd(cwd: string): 'user' | 'project';
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export declare function profileNameFor(profileId: string | null | undefined): string | null;

package/dist/core/substrate/subject-fields.js

@@ -0,0 +1,39 @@
+// subject-fields.ts — the PURE half of subject assembly: the NodeConfigSubject
+// shape plus the two derived-field resolvers (`scopeForCwd`, `profileNameFor`)
+// that read scope/profile config but NEVER the canvas-db. Split out of
+// subject.ts so CLI consumers (`sys context prompt-review`) can build a subject from an
+// API-fetched node without pulling subject.ts's canvas-db reach (getNode/getRow).
+// The canvas-db assembler (`assembleNodeSubject`, `spineDepth`) stays in
+// subject.ts for broker/daemon-side callers.
+import { projectScopeRoot } from '../scope.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { CrtrError } from '../errors.js';
+import { SCOPE_VOCABULARY } from '../scopes.js';
+export function effectiveScopes(scopes) {
+    return scopes === null || scopes === undefined ? [...SCOPE_VOCABULARY] : [...scopes];
+}
+/** The scope a cwd resolves into: `project` when scope.ts finds a
+ *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
+ *  resolver (`projectScopeRoot`). */
+export function scopeForCwd(cwd) {
+    return projectScopeRoot(cwd) !== null ? 'project' : 'user';
+}
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export function profileNameFor(profileId) {
+    if (profileId === undefined || profileId === null || profileId === '')
+        return null;
+    try {
+        return loadProfileManifest(profileId).manifest.name;
+    }
+    catch (err) {
+        if (err instanceof CrtrError && err.code === 'not_found')
+            return null;
+        console.warn(`[subject] profile "${profileId}" failed to resolve for node subject assembly: ${err.message}`);
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ObjectRow } from '../graph/types.js';
+import { type NodeConfigSubject } from './subject-fields.js';
+export { effectiveScopes, scopeForCwd, profileNameFor } from './subject-fields.js';
+export type { NodeConfigSubject } from './subject-fields.js';
+/** Spine distance from `nodeId` up to its root orchestrator: count the hops
+ *  walking the `parent` chain (canvas-db rows) until a row with no parent (the
+ *  root). The root is depth 0. Cycle-guarded (parents must not cycle, but never
+ *  loop forever) — mirrors `rootOfSpine` in runtime/placement.ts. */
+export declare function spineDepth(nodeId: string): Promise<number>;
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
+export declare function assembleNodeSubject(nodeId: string, repos?: readonly ObjectRow[]): Promise<NodeConfigSubject | null>;

package/dist/core/substrate/subject.js

@@ -0,0 +1,60 @@
+// subject.ts — the CANVAS-DB half of subject assembly: `assembleNodeSubject`
+// (reads NodeMeta rows) and `spineDepth` (walks the parent chain). The PURE
+// derived-field resolvers and the NodeConfigSubject shape live in
+// subject-fields.ts (re-exported here); a CLI consumer that must stay off the
+// canvas-db imports those from subject-fields.ts directly. See design-substrate.md
+// §4 + plan-substrate.md §2.
+import { getNode, getRow } from '../canvas/index.js';
+import { appForNode } from '../canvas/node-agent-paths.js';
+import { openDb } from '../canvas/db.js';
+import { checkoutsForCwd } from '../graph/repo-sync/repos.js';
+import { liveLookups, viewRepos } from '../graph/reader.js';
+import { effectiveScopes, scopeForCwd, profileNameFor } from './subject-fields.js';
+export { effectiveScopes, scopeForCwd, profileNameFor } from './subject-fields.js';
+/** Spine distance from `nodeId` up to its root orchestrator: count the hops
+ *  walking the `parent` chain (canvas-db rows) until a row with no parent (the
+ *  root). The root is depth 0. Cycle-guarded (parents must not cycle, but never
+ *  loop forever) — mirrors `rootOfSpine` in runtime/placement.ts. */
+export async function spineDepth(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    let hops = 0;
+    for (;;) {
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const row = await getRow(cur);
+        if (row === null || row.parent == null)
+            break;
+        cur = row.parent;
+        hops++;
+    }
+    return hops;
+}
+/** The repos eligible for the node's rules: those enclosing its cwd, then the repos of its profile's project paths. */
+async function eligibleRepos(cwd, profileId) {
+    const db = await openDb();
+    const view = await viewRepos(cwd, profileId, async (dir) => await checkoutsForCwd(db, dir), liveLookups(db));
+    return [...view.repos, ...view.projectRepos];
+}
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
+export async function assembleNodeSubject(nodeId, repos) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        return null;
+    return {
+        kind: meta.kind,
+        mode: meta.mode,
+        lifecycle: meta.lifecycle,
+        hasManager: (meta.parent ?? null) !== null,
+        cwd: meta.cwd,
+        scope: scopeForCwd(meta.cwd),
+        orchestration: { depth: await spineDepth(nodeId) },
+        profile: profileNameFor(meta.profile_id),
+        app: meta.grantee ?? await appForNode(nodeId),
+        scopes: effectiveScopes(meta.scopes),
+        repo: (repos ?? await eligibleRepos(meta.cwd, meta.profile_id ?? null)).map((r) => r.name),
+    };
+}