@north-light/crouter 0.3.352 → 0.3.354

package/dist/core/memory/history.d.ts

@@ -1,87 +0,0 @@
-import type { MemoryDoc } from '../memory-resolver.js';
-/** Sidecar tree name under a store's `memory/` dir. Dot-prefixed and holding
- *  only `.jsonl`, so every substrate scan (which filters to `*.md`, and in
- *  `lint`'s case skips dot-dirs outright) passes it over without an exclusion
- *  rule of its own. */
-export declare const HISTORY_DIR = ".history";
-/** File operations only — deliberately not a review lifecycle. */
-export type HistoryOp = 'create' | 'edit' | 'delete' | 'move';
-export interface HistoryActor {
-    cwd: string;
-    node?: string;
-}
-export interface HistoryRecord {
-    op: HistoryOp;
-    at: string;
-    /** Authoring node id; absent for a human at a bare CLI. */
-    node?: string;
-    cwd: string;
-    /** The canonical name this document answered to before a `move`; absent otherwise. */
-    from?: string;
-    /** Why this revision happened. Required on `edit`, absent otherwise. */
-    rationale?: string;
-    /** True when the body was declared a verbatim payload from the principal. */
-    verbatim?: boolean;
-    /** Complete document text before the mutation; empty for `create`. */
-    before: string;
-    /** Complete document text after the mutation; empty for `delete`. */
-    after: string;
-}
-/** The log path for a document, derived from its PHYSICAL path so the history
- *  tree mirrors the doc tree exactly (`memory/area/topic.md` →
- *  `memory/.history/area/topic.jsonl`). `memoryRoot` is the store's `memory/`
- *  dir the doc lives under. */
-export declare function historyLogPathFor(memoryRoot: string, docPath: string): string;
-/** Stamp the runtime-owned fields of a record. Field insertion order IS the
- *  serialized key order — the on-disk shape consumers read. */
-export declare function buildHistoryRecord(input: {
-    op: HistoryOp;
-    actor?: HistoryActor;
-    from?: string;
-    rationale?: string;
-    verbatim?: boolean;
-    before: string;
-    after: string;
-}): HistoryRecord;
-/** Derive a live document's sidecar from its descriptor. The descriptor's
- * physical path is authoritative: canonical names carry a project namespace,
- * while sidecars remain in the owning store's physical tree. */
-export declare function historyLogPathForDoc(doc: Pick<MemoryDoc, 'root' | 'path'>): string;
-export interface DeletedHistoryCandidate {
-    path: string;
-    representation: 'directory-index' | 'leaf-file';
-    winner: boolean;
-}
-export interface DeletedHistoryResolution {
-    logPath: string;
-    candidates: readonly DeletedHistoryCandidate[];
-    collision?: {
-        paths: readonly string[];
-        winner: string;
-    };
-}
-/** Resolve a deleted document's physical history without reintroducing a
- * canonical-name fallback. `localName` is already stripped of the selected
- * project's exact namespace. The directory-index sidecar is deliberately
- * probed first, and therefore wins deterministically if both physical forms
- * survive; callers can expose `candidates`/`collision` for diagnostics. */
-export declare function resolveDeletedHistoryLogPath(storeRoot: string, localName: string): DeletedHistoryResolution | null;
-/** Append one record. Single write of one line — concurrent appends interleave
- *  whole records, and every record stands alone, so no lock is needed. */
-/** Append beneath `root`, the store root the log mirrors. */
-export declare function appendHistoryRecord(root: string, logPath: string, record: HistoryRecord): void;
-/** Every record in a log beneath `root` (the store root it mirrors), oldest
- *  first (append order). Revision numbers are 1-based positions in this array. */
-export declare function readHistoryRecords(root: string, logPath: string): HistoryRecord[];
-export interface ChangeSummary {
-    body_changed: boolean;
-    /** Frontmatter field names whose values differ between the two texts. */
-    frontmatter_changed: string[];
-}
-/** What one record changed, derived from its own two texts. `last-updated` is
- *  excluded: the runtime stamps it on every edit, so listing it says nothing. */
-export declare function summarizeChange(before: string, after: string): ChangeSummary;
-/** Unified diff between two document texts, computed at read time. Dependency
- *  free (an LCS over lines) — memory docs are lint-capped small, so the
- *  quadratic table is never a cost. */
-export declare function unifiedDiff(before: string, after: string, context?: number): string;

package/dist/core/memory/history.js

@@ -1,6 +0,0 @@
-var M=Object.defineProperty;var l=(t,o)=>M(t,"name",{value:o,configurable:!0});import{readdirSync as j}from"node:fs";import{join as x,relative as _}from"node:path";import{appendFileBeneath as A,readTextBeneathIfExists as T}from"../spaces/open-beneath.js";import{envNodeCwd as H,envNodeId as J}from"../../shared/env.js";import{general as D}from"../errors.js";import{parseFrontmatterGeneric as $}from"../frontmatter.js";import{normalizeNameSegment as N}from"./identity.js";const F=".history";function R(t,o){const e=_(t,o);if(e===""||e.startsWith(".."))throw D(`memory document ${o} is not inside its store root ${t}`);return x(t,F,e.replace(/\.md$/i,"")+".jsonl")}l(R,"historyLogPathFor");function Z(t){const o=J(),e=t.actor??{cwd:H()??process.cwd(),...o===void 0?{}:{node:o}};return{op:t.op,at:new Date().toISOString(),...e.node!==void 0?{node:e.node}:{},cwd:e.cwd,...t.from!==void 0?{from:t.from}:{},...t.rationale!==void 0?{rationale:t.rationale}:{},...t.verbatim===!0?{verbatim:!0}:{},before:t.before,after:t.after}}l(Z,"buildHistoryRecord");function tt(t){return R(t.root,t.path)}l(tt,"historyLogPathForDoc");function W(t,o){let e;try{e=j(t,{withFileTypes:!0})}catch{return[]}return e.filter(n=>n.isDirectory()&&N(n.name)===o).sort((n,i)=>n.name===o?-1:i.name===o?1:n.name.localeCompare(i.name)).map(n=>x(t,n.name))}l(W,"matchingDirs");function P(t,o){let e;try{e=j(t,{withFileTypes:!0})}catch{return[]}return e.filter(n=>n.isFile()&&n.name.endsWith(".jsonl")&&N(n.name.slice(0,-6))===o).sort((n,i)=>n.name===`${o}.jsonl`?-1:i.name===`${o}.jsonl`?1:n.name.localeCompare(i.name)).map(n=>x(t,n.name))}l(P,"matchingFiles");function I(t,o,e){let n=[t];for(const i of o)if(n=n.flatMap(a=>W(a,i)),n.length===0)return[];return n.flatMap(i=>P(i,e))}l(I,"historyFilesForSegments");function et(t,o){const e=o.split("/").filter(s=>s!=="").map(N),n=x(t,F),i=I(n,e,"INDEX"),a=e.length===0?[]:I(n,e.slice(0,-1),e[e.length-1]),r=[...i.map(s=>({path:s,representation:"directory-index",winner:!1})),...a.map(s=>({path:s,representation:"leaf-file",winner:!1}))];return r.length===0?null:(r[0].winner=!0,{logPath:r[0].path,candidates:r,...r.length>1?{collision:{paths:r.map(s=>s.path),winner:r[0].path}}:{}})}l(et,"resolveDeletedHistoryLogPath");function nt(t,o,e){A(t,o,JSON.stringify(e)+`
-`)}l(nt,"appendHistoryRecord");function ot(t,o){const e=T(t,o);if(e===null)return[];const n=e.split(`
-`),i=[];for(let a=0;a<n.length;a+=1){const r=n[a];if(r.trim()!=="")try{i.push(JSON.parse(r))}catch{throw D(`corrupt history record at ${o}:${a+1} \u2014 the line is not valid JSON`,{next:"Inspect that line directly; the surrounding records are self-contained and still readable."})}}return i}l(ot,"readHistoryRecords");function rt(t,o){const e=$(t),n=$(o),i=e.data??{},a=n.data??{},r=new Set([...Object.keys(i),...Object.keys(a)]);r.delete("last-updated");const s=[...r].filter(c=>JSON.stringify(i[c])!==JSON.stringify(a[c])).sort((c,f)=>c.localeCompare(f));return{body_changed:e.body!==n.body,frontmatter_changed:s}}l(rt,"summarizeChange");function it(t,o,e=3){const{lines:n,terminated:i}=L(t),{lines:a,terminated:r}=L(o),s=k(E(n,i),E(a,r)),c=[];for(let d=0;d<s.length;d+=1){if(s[d].tag===" ")continue;const p=Math.max(0,d-e),g=Math.min(s.length,d+e+1),u=c[c.length-1];u!==void 0&&p<=u.to?u.to=Math.max(u.to,g):c.push({from:p,to:g})}if(c.length===0)return"";const f=[],w=[];let b=0,O=0;for(const d of s)f.push(b),w.push(O),d.tag!=="+"&&(b+=1),d.tag!=="-"&&(O+=1);const y=[];for(const{from:d,to:p}of c){const g=s.slice(d,p),u=g.filter(h=>h.tag!=="+").length,S=g.filter(h=>h.tag!=="-").length;y.push(`@@ -${u===0?0:f[d]+1},${u} +${S===0?0:w[d]+1},${S} @@`);for(let h=d;h<p;h+=1){const m=s[h];y.push(m.tag+(m.tag==="+"?a[m.index]:n[m.index]));const v=m.tag!=="+"&&!i&&f[h]===n.length-1,C=m.tag!=="-"&&!r&&w[h]===a.length-1;(v||C)&&y.push(B)}}return y.join(`
-`)}l(it,"unifiedDiff");const B="\",K="\0no-newline-at-eof";function E(t,o){return o||t.length===0?t:t.map((e,n)=>n===t.length-1?e+K:e)}l(E,"diffKeys");function L(t){if(t==="")return{lines:[],terminated:!0};const o=t.endsWith(`
-`),e=t.split(`
-`);return o&&e.pop(),{lines:e,terminated:o}}l(L,"toLines");function k(t,o){const e=t.length,n=o.length,i=Array.from({length:e+1},()=>new Array(n+1).fill(0));for(let c=e-1;c>=0;c-=1)for(let f=n-1;f>=0;f-=1)i[c][f]=t[c]===o[f]?i[c+1][f+1]+1:Math.max(i[c+1][f],i[c][f+1]);const a=[];let r=0,s=0;for(;r<e&&s<n;)t[r]===o[s]?(a.push({tag:" ",index:r}),r+=1,s+=1):i[r+1][s]>=i[r][s+1]?(a.push({tag:"-",index:r}),r+=1):(a.push({tag:"+",index:s}),s+=1);for(;r<e;r+=1)a.push({tag:"-",index:r});for(;s<n;s+=1)a.push({tag:"+",index:s});return a}l(k,"diffOps");export{F as HISTORY_DIR,nt as appendHistoryRecord,Z as buildHistoryRecord,R as historyLogPathFor,tt as historyLogPathForDoc,ot as readHistoryRecords,et as resolveDeletedHistoryLogPath,rt as summarizeChange,it as unifiedDiff};

package/dist/core/memory/identity.d.ts

@@ -1,65 +0,0 @@
-/** The filename (and path segment) whose document fronts its directory. */
-export declare const INDEX_SEGMENT = "INDEX";
-/** Strip an optional `NN-` ordering prefix from ONE segment. */
-export declare function normalizeNameSegment(segment: string): string;
-/** Slugify one authored or filesystem label into a canonical segment. */
-export declare function slugCanonicalSegment(raw: string): string;
-/** Slugify a derived label into canonical path segments. Empty segments are
- * intentionally dropped; owner paths use slugCanonicalSegment directly. */
-export declare function slugCanonicalPath(raw: string): string;
-/** Strip the ordering prefix from EVERY segment of a slash-separated name:
- *  `01-spine/00-has-manager` -> `spine/has-manager`. */
-export declare function normalizeDocName(name: string): string;
-/** Split a name into segments, dropping empties from `//`, a leading `/`, or an
- *  empty name. */
-export declare function canonicalSegments(name: string): string[];
-/** The canonical directory containing `name`, or `''` at the top. */
-export declare function canonicalParent(name: string): string;
-/** Remove EXACTLY ONE trailing `INDEX` segment. `a/INDEX` -> `a`; `INDEX` ->
- *  `''` (a store root); `a/INDEX/INDEX` -> `a/INDEX` (the inner segment is an
- *  ordinary directory name). */
-export declare function collapseTrailingIndex(name: string): string;
-export type DocRepresentation = 'leaf-file' | 'directory-index';
-/** Which form a store-relative markdown path takes. */
-export declare function representationForPath(physicalRelativePath: string): DocRepresentation;
-/** Store-local name derived from a store-relative markdown path: ordering
- *  prefixes stripped from every segment and one trailing `INDEX` collapsed.
- *  Empty only for a store root `INDEX.md`. */
-export declare function localNameFromPath(physicalRelativePath: string): string;
-/** The store-relative markdown path a local name occupies in a given form.
- *  Both forms are checked before any create or move, so occupancy never depends
- *  on which one a store happens to use. */
-export declare function physicalRelativePathFor(localName: string, representation: DocRepresentation): 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;
-/** A document's store-local name: its explicit frontmatter `name` when present,
- *  else the path-derived local name. Explicit names are local to their store —
- *  they never carry the store's namespace. */
-export declare function resolveLocalName(fm: Record<string, unknown> | null | undefined, pathDerivedLocalName: string): string;
-/** namespace ⊕ local — the only address. Composition is unconditional: a local
- *  name that already looks namespace-prefixed is composed anyway, so identity
- *  never depends on string coincidence. An empty result means a namespace-less
- *  store root, which has no valid canonical identity. */
-export declare function composeCanonicalName(namespace: string, localName: string): string;
-/** The canonical directory a document's `./` memory-read entries match against:
- *  a directory document anchors at its own name, an ordinary leaf at its
- *  canonical parent. */
-export declare function routingAnchorFor(canonicalName: string, representation: DocRepresentation): string;
-/** The local name a canonical name has inside `namespace`, or `null` when it
- *  falls outside it. Exact on segment boundaries: `a/bc` is not inside `a/b`.
- *  The namespace itself yields `''` — the store root document. */
-export declare function stripNamespace(canonicalName: string, namespace: string): string | null;
-export type IdentityValidation = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
-/** A project store's declared namespace, or an installed plugin's mount prefix:
- *  one or more normalized segments, never ending in `INDEX`. */
-export declare function validateNamespace(namespace: string): IdentityValidation;
-/** An explicit non-root `name:`: a non-empty local name, never ending in
- *  `INDEX` (its directory name is the identity) and never carrying its own
- *  store's namespace. */
-export declare function validateExplicitLocalName(localName: string, namespace?: string): IdentityValidation;

package/dist/core/memory/identity.js

@@ -1 +0,0 @@
-var m=Object.defineProperty;var t=(e,n)=>m(e,"name",{value:n,configurable:!0});const c=/^\d{2}-/,g=/^[A-Za-z0-9._-]+$/,s="INDEX";function u(e){return e.replace(c,"")}t(u,"normalizeNameSegment");function d(e){return u(e.trim().toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/^-+|-+$/g,""))}t(d,"slugCanonicalSegment");function k(e){return e.replace(/\\/g,"/").replace(/\.md$/i,"").split("/").map(d).filter(Boolean).join("/")}t(k,"slugCanonicalPath");function x(e){return e.split("/").map(u).join("/")}t(x,"normalizeDocName");function o(e){return e.split("/").filter(n=>n!=="")}t(o,"canonicalSegments");function h(e){return o(e).slice(0,-1).join("/")}t(h,"canonicalParent");function l(e){const n=o(e);return n[n.length-1]===s&&n.pop(),n.join("/")}t(l,"collapseTrailingIndex");function f(e){return o(e.replace(/\\/g,"/").replace(/\.md$/i,"")).map(u)}t(f,"pathIdentitySegments");function j(e){const n=f(e);return n[n.length-1]===s?"directory-index":"leaf-file"}t(j,"representationForPath");function N(e){return l(f(e).join("/"))}t(N,"localNameFromPath");function S(e,n){const r=o(e).join("/");if(r===""){if(n==="leaf-file")throw new Error("a store root document has no leaf-file representation");return`${s}.md`}return n==="directory-index"?`${r}/${s}.md`:`${r}.md`}t(S,"physicalRelativePathFor");function $(e){const n=e?.name;return typeof n!="string"||n.trim()===""?null:l(x(n.trim()))}t($,"explicitLocalName");function w(e,n){return $(e)??n}t(w,"resolveLocalName");function _(e,n){const r=o(e).join("/"),i=o(n).join("/");return r===""?i:i===""?r:`${r}/${i}`}t(_,"composeCanonicalName");function v(e,n){return n==="directory-index"?o(e).join("/"):h(e)}t(v,"routingAnchorFor");function y(e,n){const r=o(e),i=o(n);for(let a=0;a<i.length;a++)if(r[a]!==i[a])return null;return r.slice(i.length).join("/")}t(y,"stripNamespace");function p(e){for(const n of e.split("/")){if(n==="")return`empty segment in \`${e}\``;if(n==="."||n==="..")return`relative segment \`${n}\` in \`${e}\``;if(!g.test(n))return`segment \`${n}\` is not [A-Za-z0-9._-]`;if(c.test(n))return`segment \`${n}\` carries an \`NN-\` ordering prefix, which is physical-path-only \u2014 use \`${u(n)}\``}return null}t(p,"invalidSegmentReason");function I(e){if(e.trim()!==e)return{ok:!1,reason:"namespace has surrounding whitespace"};if(e==="")return{ok:!1,reason:"namespace is empty"};const n=p(e);return n!==null?{ok:!1,reason:n}:o(e).pop()===s?{ok:!1,reason:`namespace ends in \`${s}\``}:{ok:!0}}t(I,"validateNamespace");function P(e,n=""){if(e.trim()!==e)return{ok:!1,reason:"name has surrounding whitespace"};if(e==="")return{ok:!1,reason:"name is empty"};const r=p(e);if(r!==null)return{ok:!1,reason:r};if(o(e).pop()===s){const i=l(e);return{ok:!1,reason:`name ends in \`${s}\` \u2014 a directory document answers at its directory name${i===""?"":`, so use \`${i}\``}`}}return n!==""&&y(e,n)!==null?{ok:!1,reason:`name repeats its store's namespace \`${n}\` \u2014 explicit names are store-local`}:{ok:!0}}t(P,"validateExplicitLocalName");export{s as INDEX_SEGMENT,h as canonicalParent,o as canonicalSegments,l as collapseTrailingIndex,_ as composeCanonicalName,$ as explicitLocalName,N as localNameFromPath,x as normalizeDocName,u as normalizeNameSegment,S as physicalRelativePathFor,j as representationForPath,w as resolveLocalName,v as routingAnchorFor,k as slugCanonicalPath,d as slugCanonicalSegment,y as stripNamespace,P as validateExplicitLocalName,I as validateNamespace};

package/dist/core/memory/inline-ref-guidance.js

@@ -1,2 +0,0 @@
-var a=Object.defineProperty;var c=(n,t)=>a(n,"name",{value:t,configurable:!0});import{findRefTokens as r}from"./inline-ref-grammar.js";const s="The user explicitly called out specific memories. Read the relevant mentioned memory files:";function u(n,t){const o=new Set,i=[];for(const e of r(n))o.has(e.candidate)||t.has(e.candidate)&&(o.add(e.candidate),i.push(e.candidate));if(i.length===0)return null;const d=i.map(e=>`- crtr memory read ${e}`);return[s,...d].join(`
-`)}c(u,"buildGuidance");export{u as buildGuidance};

package/dist/core/memory/inline-ref-inventory.d.ts

@@ -1,9 +0,0 @@
-import { type MemoryTarget } from '../memory-resolver.js';
-import type { RefMeta } from '../runtime/broker-protocol.js';
-/** Build the inline inventory from exact target-view winners. `refs` carries
- * metadata rows; `names` adds only canonical directory nodes with members for
- * browse links. Gates, rungs, and `slash` do not affect referenceability. */
-export declare function buildRefInventory(target?: MemoryTarget): {
-    refs: RefMeta[];
-    names: Set<string>;
-};

package/dist/core/memory/inline-ref-inventory.js

@@ -1 +0,0 @@
-var d=Object.defineProperty;var c=(n,i)=>d(n,"name",{value:i,configurable:!0});import{ambientMemoryTarget as u,loadMemoryTargetView as h}from"../memory-resolver.js";import{buildMemoryTree as y}from"./tree.js";import{memoryExtensionEffectiveCatalog as D,projectEffectiveMemoryExtensions as b}from"./extensions.js";import{parseSubstrateDoc as g}from"../substrate/schema.js";const f={node:0,project:1,profile:2,user:3,builtin:4};function x(n=u()){const i=h(n,{quiet:!0}),s=new Map;for(const e of i.candidateSets()){const o=e.winner,t=g(o);t!==null&&s.set(e.name,{doc:t,memoryDoc:o})}const r=[];for(const[e,{doc:o,memoryDoc:t}]of s){const p=o.scope!=="builtin"&&b(t.frontmatter?.extensions,D(t)).northlight?.visibility!==!1;r.push({name:e,kind:o.kind,scope:o.scope,shortForm:o.shortForm,gatewayVisible:p})}r.sort((e,o)=>{const t=f[e.scope]-f[o.scope];return t!==0?t:e.name.localeCompare(o.name)});const m=new Set(r.map(e=>e.name)),l=y([...s.values()].map(({memoryDoc:e})=>e)),a=c(e=>{e.name!==""&&(e.childDirectories.length>0||e.childDocuments.length>0)&&m.add(e.name);for(const o of e.childDirectories)a(o)},"addDirectoryNames");return a(l.root),{refs:r,names:m}}c(x,"buildRefInventory");export{x as buildRefInventory};

package/dist/core/memory/lint.d.ts

@@ -1,163 +0,0 @@
-import { type MemoryDoc, type MemoryScope, type MemoryStoreDescriptor, type MemoryTarget } from '../memory-resolver.js';
-export type MemoryLintSeverity = 'error' | 'warning' | 'notice';
-export type MemoryLintRule = 
-/** Frontmatter does not parse as YAML. */
-'yaml'
-/** Substrate frontmatter contract violation. */
- | 'schema'
-/** A plugin-declared `extensions` value is invalid. */
- | 'extension'
-/** Body longer than its delivery entries earn. */
- | 'length'
-/** A body short enough to inline still pays a routing line. */
- | 'short-preview'
-/** A `memory-read` glob that fires on every memory read. */
- | 'broad-memory-read'
-/** A project store the runtime refuses to mount: no/invalid repository-root `namespace:`. */
- | 'store-namespace'
-/** `namespace:` declared anywhere but the repository-root store's root INDEX.md. */
- | 'namespace-placement'
-/** Two owner directories in one repository normalize to one effective prefix. */
- | 'owner-path-collision'
-/** `name:` on a store's root INDEX.md, whose identity is the namespace. */
- | 'root-name'
-/** A root INDEX.md in a store that declares no namespace — no address. */
- | 'root-index-unaddressable'
-/** An explicit non-root `name:` that is not a valid store-local name. */
- | 'local-name'
-/** Two files in ONE store owning the same canonical identity. */
- | 'canonical-collision'
-/** One canonical identity held by several stores (inspection data). */
- | 'cross-store-candidates'
-/** A `[[link]]` that resolves to no document or directory. */
- | 'dangling-link'
-/** A `memory-read` route that matches no canonical name. */
- | 'memory-read-route'
-/** A document no reachability path routes an agent to — no surface delivers
- *  it, no reached document links it, and no reached directory lists it. */
- | 'orphan'
-/** A project store's workspace front door is missing or not its root doc. */
- | 'front-door'
-/** Boot entries in a nested store, which never rides the boot catalog. */
- | 'nested-store-boot'
-/** Reference checks skipped because the store's identities are undetermined. */
- | 'reference-check-deferred';
-/** The rules that decide whether a corpus is COMPATIBLE with exact canonical
- *  identity — what a plugin candidate gate, the builtin build gate, and
- *  migration verification refuse a corpus on, independent of authoring-quality
- *  rules such as length or routing lines. */
-export declare const MEMORY_LINT_IDENTITY_RULES: ReadonlySet<MemoryLintRule>;
-export interface MemoryLintFinding {
-    severity: MemoryLintSeverity;
-    rule: MemoryLintRule;
-    /** The markdown file, store root, or project directory at fault. */
-    path: string;
-    message: string;
-    scope?: MemoryScope;
-    storeRoot?: string;
-    /** The canonical identity the finding is about, when it has one. */
-    name?: string;
-    /** Every physical path sharing a collided identity, read winner first. */
-    paths?: readonly string[];
-}
-export interface MemoryLintResult {
-    /** No `error` findings. */
-    ok: boolean;
-    /** Markdown files examined, including non-document files (`SKILL.md`,
-     *  `MEMORY.md`) that are YAML-checked but never loaded as documents. */
-    checked: number;
-    /** Of `checked`, the files the substrate actually loads as memory
-     *  documents — `checked` minus `SKILL.md`/`MEMORY.md`. */
-    documents: number;
-    storesLinted: number;
-    /** Every finding, in emission order. */
-    findings: readonly MemoryLintFinding[];
-    errors: readonly MemoryLintFinding[];
-    warnings: readonly MemoryLintFinding[];
-    notices: readonly MemoryLintFinding[];
-}
-export interface MemoryLintTargetResult extends MemoryLintResult {
-    /** Every store the target saw, mounted or not, in precedence order. */
-    stores: readonly MemoryStoreDescriptor[];
-    /** Projects the selected profile manages that were checked for a workspace
-     *  front door — zero under a scope filter that excludes project stores. */
-    profileProjects: number;
-}
-/** The length rule. Caps come from the parsed entries — an invalid entry already
- *  fails the schema check, so it simply matches no cap here. `docName` is the
- *  doc's canonical identity; persona layers under `kinds/` are never capped. */
-export declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | null;
-/** Warn when a body short enough to inline still pays a routing line. */
-export declare function lintShortPreviewBody(fm: Record<string, unknown>, body: string): string | null;
-/** Every canonical name a reference may target in a corpus: each document's
- *  exact identity plus every canonical directory, because reading a directory
- *  answers with its own document and its listing. Derived from the canonical
- *  tree, never from string prefixes of a name. */
-export declare function resolvableCanonicalNames(docs: readonly MemoryDoc[]): Set<string>;
-/** The orphan rule. A document is reachable when an agent is routed to it
- *  without knowing its name: a surface delivers it (a `memory-read` surface is
- *  deliberate companion wiring and counts), it is invocable as a slash command,
- *  a reached document's real `[[link]]` names it, or a reached CURATED INDEX
- *  document's listing includes it. The listing edge routes only through a
- *  directory that carries its own non-root index document — a bare directory
- *  has no curator, and a store's root front door is delivered with the whole
- *  boot tree, so treating either listing as a route would reach every doc and
- *  defeat the rule (the same reason the corpus root is never seeded). Curated
- *  BODY LINKS on those docs still route. Reachability is computed over the
- *  WHOLE target view — a doc linked only from another store is still reachable.
- *  `flagStoreRoot` restricts which store's unreachable docs are flagged while
- *  every store still participates in the graph as a potential linker. */
-export declare function lintOrphans(viewDocs: readonly MemoryDoc[], options?: {
-    flagStoreRoot?: string;
-}): MemoryLintFinding[];
-export interface MemoryLintStoreOptions {
-    /** Canonical names a `[[link]]` or route may target — the target view the
-     *  store's documents are read in. Omit to skip reference checks entirely
-     *  (a store linted in isolation, such as the builtin corpus at build time,
-     *  passes only its own names). */
-    resolvable?: ReadonlySet<string>;
-    /** Whether a project store must carry a workspace front door: `required` for
-     *  a profile-managed project, `advisory` (warning) for an unmanaged one that
-     *  was asked about directly, `ignore` otherwise. A front door on any doc but
-     *  the store root is an error under every mode. */
-    frontDoor?: 'required' | 'advisory' | 'ignore';
-    /** A store discovered BELOW the mounted project roots: the boot catalog never
-     *  includes one, so its boot entries are inert. */
-    nestedStore?: boolean;
-}
-/** Lint ONE physical store, whether or not the runtime mounts it. An undeclared
- *  or invalid project store still has its files checked — every store-local rule
- *  holds before a namespace exists — but its references are deferred, because
- *  the identities its links resolve against are undetermined until migration
- *  declares the namespace. */
-export declare function lintMemoryStore(store: MemoryStoreDescriptor, options?: MemoryLintStoreOptions): MemoryLintResult;
-export interface MemoryLintDocumentOptions {
-    /** Canonical names a `[[link]]` or route may target. Omit to skip reference
-     *  checks — the caller pays for the corpus index only when the document
-     *  actually carries a reference to resolve. */
-    resolvable?: ReadonlySet<string>;
-    /** The store sits below the mounted project roots, so its boot entries are
-     *  inert. Omit when the document carries no boot entry: the rule cannot fire. */
-    nestedStore?: boolean;
-}
-/** Lint ONE document, by absolute path, in the store that holds it. Runs every
- *  file-level rule the store sweep runs, and the store-level front-door rule
- *  this one file can violate on its own. It does NOT run the rules that need
- *  the whole store (canonical collisions, missing front-door coverage), so it
- *  never replaces `crtr memory lint` — it catches what an author just typed. */
-export declare function lintMemoryDocument(store: MemoryStoreDescriptor, filePath: string, options?: MemoryLintDocumentOptions): MemoryLintResult;
-export interface MemoryLintTargetOptions {
-    /** Whose view to lint. Default: the ambient process (cwd + CRTR_PROFILE_ID +
-     *  CRTR_NODE_ID). */
-    target?: MemoryTarget;
-    /** Restrict to one source class. Front-door coverage applies only to an
-     *  unfiltered or project-scoped view. */
-    scope?: MemoryScope;
-    /** Also lint `.crouter/memory` stores discovered below the mounted project
-     *  roots. Default true: they are addressable, so they are lintable. */
-    includeDescendants?: boolean;
-}
-/** Lint every store a target sees, then the diagnostics only the merged view
- *  produces: references resolved against the view's canonical names, and equal
- *  canonical identities held by several stores. */
-export declare function lintMemoryTarget(options?: MemoryLintTargetOptions): MemoryLintTargetResult;

package/dist/core/memory/lint.js

@@ -1,2 +0,0 @@
-var J=Object.defineProperty;var w=(e,t)=>J(e,"name",{value:t,configurable:!0});import{envNodeId as Q,envProfileId as Z}from"../../shared/env.js";import{basename as ee,join as L,matchesGlob as te,relative as W,sep as A}from"node:path";import{pathExists as oe,realpathOrSelf as D}from"../fs-utils.js";import{readFileBeneath as ne,walkFilesBeneath as re}from"../spaces/open-beneath.js";import{parseFrontmatterGeneric as se}from"../frontmatter.js";import{descendantStoreRoots as ie}from"../nested-stores.js";import{projectScopeRoots as ae}from"../scope.js";import{associateRepository as x}from"./repository-association.js";import{loadProfileManifest as ce}from"../profiles/manifest.js";import{loadMemoryTargetView as de,loadStoreMemoryDocs as F,openProjectMemoryStore as B}from"../memory-resolver.js";import{buildMemoryTree as N}from"./tree.js";import{canonicalSegments as E,collapseTrailingIndex as q,INDEX_SEGMENT as $,localNameFromPath as C,normalizeDocName as G,validateExplicitLocalName as le}from"./identity.js";import{lintSubstrateFrontmatter as me,parsedSubstrateSurfaces as j}from"../substrate/frontmatter-validation.js";import{memoryExtensionValidationCatalog as fe,validateMemoryExtensionValues as ue}from"./extensions.js";import{docLinkNames as z}from"./doc-link-grammar.js";const Ce=new Set(["store-namespace","namespace-placement","owner-path-collision","root-name","root-index-unaddressable","local-name","canonical-collision","dangling-link","memory-read-route"]);function M(e,t,r,s){const i=e.filter(a=>a.severity==="error");return{ok:i.length===0,checked:t,documents:r,storesLinted:s,findings:e,errors:i,warnings:e.filter(a=>a.severity==="warning"),notices:e.filter(a=>a.severity==="notice")}}w(M,"makeResult");const P=1e3,V=1e3,O=3e3,he=30,T="Keep the load-bearing core here and split the depth into [[linked]] reference docs carrying no surfaces at all (the listing and the link are how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off \u201Cfurther evidence\u201D, examples, or references \u2014 a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole \u2014 `lint-ignore: length` in the frontmatter \u2014 only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.";function _(e,t){const r=e["lint-ignore"];return r===t||Array.isArray(r)&&r.includes(t)}w(_,"ignoresRule");function X(e){const t=e.trim();return t===""?0:t.split(/\s+/).length}w(X,"countBodyWords");function pe(e,t,r){if(_(e,"length")||r==="kinds"||r.startsWith("kinds/"))return null;const s=j(e),i=X(t);if(s.some(c=>c.on==="boot"&&c.at==="content")&&i>P)return`body is ${i} words but a boot entry at \`content\` inlines every word into every agent's system prompt \u2014 capped at ${P} words (boot preview gets ${O}; name entries are never capped). ${T}`;const a=[...new Set(s.filter(c=>c.on!=="boot"&&c.at==="content").map(c=>c.on))];return a.length>0&&i>V?`body is ${i} words, over the ${V}-word cap for a \`content\` entry on ${a.join("/")} (the whole body delivers every time the entry fires; name entries are never capped). ${T}`:s.some(c=>c.on==="boot"&&c.at==="preview")&&i>O?`body is ${i} words, over the ${O}-word cap for boot preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; boot content is capped at ${P} words; name entries are never capped). ${T}`:null}w(pe,"lintBodyLength");function ye(e,t){const r=X(t);if(r>=he)return null;const s=[...new Set(j(e).filter(a=>a.at==="preview").map(a=>a.on))];if(s.length===0)return null;const i=s.length===1?"entry delivers":"entries deliver";return`body is ${r} words but the ${s.join("/")} ${i} \`preview\`; use \`at: content\` so agents receive the whole rule without a separate memory read`}w(ye,"lintShortPreviewBody");function we(e){const t=new Set,r=w(s=>{s.name!==""&&t.add(s.name);for(const i of s.childDirectories)r(i);for(const i of s.childDocuments)t.add(i.name)},"walk");return r(N(e).root),t}w(we,"resolvableCanonicalNames");function ge(e,t={}){const r=N(e),s=new Map,i=w(o=>{o.name!==""&&s.set(o.name,o);for(const d of o.childDirectories)i(d);for(const d of o.childDocuments)s.set(d.name,d)},"indexWalk");i(r.root);const a=new Set,c=[],u=w(o=>{o===""||a.has(o)||!s.has(o)||(a.add(o),c.push(o))},"enqueue");for(const o of e){const d=o.frontmatter??{};(j(d).length>0||d.slash===!0)&&u(o.name)}for(;c.length>0;){const o=s.get(c.shift()),d=o.document;if(d!==null)for(const p of z(d.body))s.has(p)&&u(p);if(!(d===null||d.localName==="")){for(const p of o.childDirectories)p.document?.frontmatter?.unlisted!==!0&&u(p.name);for(const p of o.childDocuments)p.document.frontmatter?.unlisted!==!0&&u(p.name)}}const h=[];for(const o of e)t.flagStoreRoot!==void 0&&o.store.storeRoot!==t.flagStoreRoot||a.has(o.name)||o.scope==="builtin"||o.plugin!==void 0||o.localName!==""&&(o.name==="kinds"||o.name.startsWith("kinds/")||_(o.frontmatter??{},"orphan")||h.push({severity:"warning",rule:"orphan",path:o.path,name:o.name,scope:o.scope,...o.store.storeRoot===""?{}:{storeRoot:o.store.storeRoot},message:`\`${o.name}\` is unreachable: no surface delivers it, no reached document links it, and no reached directory lists it \u2014 it is findable only by deliberate search. Give it a surface, link it from a reached doc (a cluster index, or its directory's own ${$}.md), or accept it with \`lint-ignore: orphan\`.`}));return h}w(ge,"lintOrphans");const Y='the store\'s root INDEX.md is the workspace front door: give it `surfaces: [{on: workspace-open, at: content}, {on: read, match: "./**", at: content}]` (run `crtr memory write -h` first)',ve=/[*?[\]{}]/;function K(e,t){try{return te(e,t)}catch{return!1}}w(K,"safeGlob");function Re(e,t){const r=e.startsWith("./")?e.slice(2):e,s=e.startsWith("./")?`${t}/${r}`:r;return E(G(s)).join("/")}w(Re,"literalRouteTarget");function be(e,t,r){if(!e.startsWith("./")){for(const a of r)if(K(a,e))return!0;return!1}const s=e.slice(2),i=t===""?"":`${t}/`;for(const a of r)if(a.startsWith(i)&&K(a.slice(i.length),s))return!0;return!1}w(be,"routeMatchesAny");function U(e){const t=E(e),r=t[t.length-1]===$,s=q(e),i=E(s).pop()??e;return`${r?` A directory's own document answers at the directory name, so name \`${s}\` instead.`:""} Run \`crtr memory find ${i}\` for the canonical name, or drop the reference.`}w(U,"missingNameDiagnostic");const $e=new Set(["SKILL.md","MEMORY.md"]);function I(e,t={}){const r=[],s={scope:e.scope,...e.storeRoot===""?{}:{storeRoot:e.storeRoot}},i=w((l,y,n,m,f={})=>{r.push({severity:l,rule:y,path:n,message:m,...s,...f})},"add"),a=e.mountStatus==="ready";e.mountFailure==="collision"?i("error","owner-path-collision",e.namespacePath??e.storeRoot,e.diagnostic??`project memory stores have owner directories that normalize to the same effective prefix \`${e.namespace}\` \u2014 rename one owner directory`):(e.mountStatus==="undeclared"||e.mountStatus==="invalid")&&i("error","store-namespace",e.namespacePath??e.storeRoot,e.diagnostic??"project memory store does not mount"),(e.mountStatus==="undeclared"||e.mountStatus==="invalid")&&t.resolvable!==void 0&&i("notice","reference-check-deferred",e.storeRoot,"links and `memory-read` routes are not checked here: the canonical identities they resolve against are undetermined until this store declares its namespace");const c=e.scope==="project"&&e.plugin===void 0,u=t.frontDoor??"ignore",h=[],o=F(e,!0).filter(l=>!l.physicalRelativePath.split("/").some(y=>y.startsWith("."))),d=new Map(o.map(l=>[l.path,l]));let p=0,v=0;const R=e.mountFailure==="symlink"?[]:re(e.storeRoot,e.storeRoot,l=>l.endsWith(".md"),l=>l.startsWith("."));for(const l of R){const y=W(e.storeRoot,l).split(A).join("/");y!==""&&(p+=1,H({store:e,file:l,relPath:y,doc:d.get(l),isProjectStore:c,mounted:a,...t.resolvable===void 0?{}:{resolvable:t.resolvable},nestedStore:t.nestedStore===!0,add:i,frontDoors:h})==="document"&&(v+=1))}const g=new Map;for(const l of o){const y=g.get(l.name);y?y.push(l):g.set(l.name,[l])}for(const[l,y]of g){if(y.length<2)continue;const n=y.map(m=>m.path);i("error","canonical-collision",n[0],`${y.length} files in this store own canonical name \`${l}\` (${n.join(", ")}); \`${y[0].physicalRelativePath}\` is the deterministic read winner. Recover the collision with \`crtr memory move ${l} --to <new-free-name>\`; move selects the first physical path in stable lexical order, and no filesystem surgery is needed.`,{name:l,paths:n})}if(c){for(const n of h)n.root||i("error","front-door",n.path,`a project store's workspace front door is its root ${$}.md, not this doc \u2014 a {on: workspace-open, at: content} entry here delivers a second whole document at every workspace open; fold it into the root document or lower this entry`);const l=(e.ownerRelativePath??"")==="",y=h.some(n=>n.root&&n.complete);if(l&&!y&&u!=="ignore"){const n=e.ownerDir??e.storeRoot,m=u==="required"?`the selected profile manages this project but its store has no workspace front door \u2014 ${Y}`:`this project store has no workspace front door, so agents open the workspace blind \u2014 ${Y}`;i(u==="required"?"error":"warning","front-door",n,m)}}return M(r,p,v,1)}w(I,"lintMemoryStore");function H(e){const{store:t,file:r,relPath:s,doc:i,isProjectStore:a,mounted:c,resolvable:u,add:h}=e;let o,d;try{({data:o,body:d}=se(ne(t.storeRoot,r).toString("utf8")))}catch(g){return h("error","yaml",r,`invalid YAML frontmatter: ${(g instanceof Error?g.message:String(g)).split(`
-`)[0]}`),"yaml-error"}if($e.has(ee(r)))return"non-document";const p=C(s)==="",v=i===void 0?{}:{name:i.name},R=me(o);if(R!==null&&h("error","schema",r,R,v),o!==null){const g=a&&t.ownerRelativePath==="";if(o.namespace!==void 0&&!(p&&g)){const l=p&&a&&t.ownerRelativePath!==void 0&&t.ownerRelativePath!==""?`\`namespace:\` belongs only on the repository-root store's ${$}.md (${t.namespacePath??t.storeRoot}) \u2014 a nested store's prefix is derived from its path under ${t.repositoryRoot??t.ownerDir??t.storeRoot}`:`\`namespace:\` belongs only on a project store's root ${$}.md, where it declares the whole store's prefix \u2014 drop it here (an explicit \`name:\` is store-LOCAL and never carries a namespace)`;h("error","namespace-placement",r,l,v)}p&&o.name!==void 0&&h("error","root-name",r,`a store's root ${$}.md carries no \`name:\` \u2014 its identity answers at \`${t.namespace}\`; drop the field`,v)}if(i===void 0)return p&&!a&&h("error","root-index-unaddressable",r,`a root ${$}.md has no canonical name in a ${t.scope} store, which declares no namespace \u2014 only a project store's root document answers at its namespace, so rename this file to a named document (\`<topic>.md\`) or fold its content into the docs it introduces`),"document";if(o!==null){if(!p&&o.name!==void 0){const n=o.name;if(typeof n!="string"||n.trim()==="")h("error","local-name",r,`invalid name: ${JSON.stringify(n)} (expected a non-empty store-local name)`,v);else{const m=le(n.trim(),t.namespace);if(!m.ok){const f=Se(G(n.trim()),t.namespace,s);h("error","local-name",r,`invalid name \`${n}\`: ${m.reason} \u2014 ${f}`,v)}}}for(const n of ue(o.extensions,fe(i)))h("error","extension",r,`${n.path}: ${n.message}`,v);const g=pe(o,d,i.name);g!==null&&h("error","length",r,g,v);const l=ye(o,d);l!==null&&h("warning","short-preview",r,l,v);const y=j(o);if(e.nestedStore&&y.some(n=>n.on==="boot")&&h("warning","nested-store-boot",r,"nested-store docs never ride the boot catalog, so its boot surfaces entries are inert \u2014 drop them",v),a&&y.some(n=>n.on==="workspace-open"&&n.at==="content")){const n=y.some(m=>m.on!=="read"||m.at!=="content"?!1:m.match?.includes("./**")===!0);e.frontDoors.push({path:r,root:p,complete:n})}for(const n of y)n.on==="memory-read"&&ke(n,i,o,u,c,h)}if(u!==void 0&&c)for(const g of z(d))u.has(g)||h("error","dangling-link",r,`dangling doc link [[${g}]]: no memory document or directory in this target view has that exact canonical name.${U(g)}`,v);return"document"}w(H,"lintDocumentFile");function Ge(e,t,r={}){const s=[],i={scope:e.scope,...e.storeRoot===""?{}:{storeRoot:e.storeRoot}},a=w((d,p,v,R,g={})=>{s.push({severity:d,rule:p,path:v,message:R,...i,...g})},"add"),c=W(e.storeRoot,t).split(A).join("/"),u=F(e,!0).find(d=>d.path===t),h=[],o=H({store:e,file:t,relPath:c,doc:u,isProjectStore:e.scope==="project"&&e.plugin===void 0,mounted:e.mountStatus==="ready",...r.resolvable===void 0?{}:{resolvable:r.resolvable},nestedStore:r.nestedStore===!0,add:a,frontDoors:h});for(const d of h)d.root||a("error","front-door",d.path,`a project store's workspace front door is its root ${$}.md, not this doc \u2014 a {on: workspace-open, at: content} entry here delivers a second whole document at every workspace open; fold it into the root document or lower this entry`);return M(s,1,o==="document"?1:0,1)}w(Ge,"lintMemoryDocument");function Se(e,t,r){let s=q(e);if(t!==""){const i=E(t),a=E(s);i.every((c,u)=>a[u]===c)&&(s=a.slice(i.length).join("/"))}return s===""?`remove the field: this document's identity would be the store root's, which only the root ${$}.md owns`:s===C(r)?`drop the field \u2014 its physical path already derives \`${s}\``:`use \`name: ${s}\``}w(Se,"suggestedLocalName");function ke(e,t,r,s,i,a){for(const c of e.match??[]){if((c==="**"||c==="*")&&!_(r,"broad-memory-read")){a("warning","broad-memory-read",t.path,`memory-read glob \`${c}\` fires on every memory read \u2014 scope it to a name subtree`,{name:t.name});continue}if(!(s===void 0||!i)){if(!ve.test(c)){const u=Re(c,t.routingAnchor);s.has(u)||a("error","memory-read-route",t.path,`memory-read route \`${c}\` names \`${u}\`, which is no document or directory in this target view, so the entry can never fire.${U(u)}`,{name:t.name});continue}be(c,t.routingAnchor,s)||a("warning","memory-read-route",t.path,`memory-read glob \`${c}\`${c.startsWith("./")?` (anchored at \`${t.routingAnchor}\`)`:""} matches no canonical name in this target view \u2014 a project document's name carries its store's namespace, so an unqualified subtree glob no longer matches`,{name:t.name})}}}w(ke,"lintMemoryReadEntry");function De(){return{cwd:process.cwd(),profileId:Z()||null,nodeId:Q()||null}}w(De,"ambientTarget");function ze(e={}){const t=e.target??De(),r=e.includeDescendants??!0,s=de(t,{...e.scope===void 0?{}:{scope:e.scope},includeDescendants:r,quiet:!0}),i=we(s.docs),a=new Set(r?ie(ae(t.cwd,t.profileId)).map(n=>D(L(n,"memory"))):[]),c=e.scope===void 0||e.scope==="project",u=new Set,h=new Set;if(c&&t.profileId!==null&&t.profileId!=="")try{const{manifest:n}=ce(t.profileId);for(const m of n.projects){const f=D(m.path);u.add(f);const S=x(f);h.add(S.ok?S.association.repositoryRoot:f)}}catch{}const o=D(t.cwd),d=[];let p=0,v=0,R=0;const g=new Set;for(const n of s.stores){const m=n.ownerDir===void 0?null:D(n.ownerDir),f=n.repositoryRoot??m;f!=null&&g.add(f);const k=n.ownerRelativePath!==void 0&&n.ownerRelativePath!==""||!c||m===null?"ignore":h.has(f??m)?"required":u.size===0&&m===o?"advisory":"ignore",b=I(n,{resolvable:i,frontDoor:k,nestedStore:a.has(D(n.storeRoot))});d.push(...b.findings),p+=b.checked,v+=b.documents,R+=b.storesLinted}if(c){for(const f of u){const S=x(f),k=S.ok?S.association.repositoryRoot:f;if(g.has(k))continue;const b=I(B(k),{resolvable:i,frontDoor:"required"});d.push(...b.findings),p+=b.checked,v+=b.documents,R+=b.storesLinted,g.add(k)}const n=x(o),m=n.ok?n.association.repositoryRoot:o;if(u.size===0&&!g.has(m)&&oe(L(t.cwd,".crouter"))){const f=I(B(t.cwd),{resolvable:i,frontDoor:"advisory"});d.push(...f.findings),p+=f.checked,v+=f.documents,R+=f.storesLinted}}const l=N(s.docs),y=w(n=>{const m=n.documentCandidates;m.length>1&&new Set(m.map(f=>f.root)).size>1&&d.push({severity:"notice",rule:"cross-store-candidates",path:m[0].path,name:n.name,paths:m.map(f=>f.path),message:`canonical name \`${n.name}\` is held by ${m.length} stores; this target view reads ${m[0].path} (${m[0].scope}) and the later candidates stay reachable with \`crtr memory read ${n.name} --dir <project>\``});for(const f of n.childDirectories)y(f);for(const f of n.childDocuments)y(f)},"walk");return y(l.root),e.scope===void 0&&d.push(...ge(s.docs)),{...M(d,p,v,R),stores:s.stores,profileProjects:u.size}}w(ze,"lintMemoryTarget");export{Ce as MEMORY_LINT_IDENTITY_RULES,pe as lintBodyLength,Ge as lintMemoryDocument,I as lintMemoryStore,ze as lintMemoryTarget,ge as lintOrphans,ye as lintShortPreviewBody,we as resolvableCanonicalNames};

package/dist/core/memory/mutation-domain.d.ts

@@ -1,113 +0,0 @@
-import { type MemoryCandidateSet, type MemoryDoc, type MemoryStoreDescriptor } from '../memory-resolver.js';
-import { type DocRepresentation } from './identity.js';
-import { type MemoryExtensionCatalog } from './extensions.js';
-import type { MemoryExtensionScalar } from '../../types.js';
-export declare function requireMountedStore(store: MemoryStoreDescriptor): MemoryStoreDescriptor;
-/** Normalize and validate a full canonical name: ordering prefixes are
- *  physical-path-only, a trailing `INDEX` is never an address, and the segment
- *  charset is fixed. */
-export declare function requireCanonicalName(rawName: string): string;
-/** The store-local name a full canonical name has inside one exact store, or a
- *  usage error when it falls outside that store's namespace. `''` names the
- *  store's own root document — a project store answers at its namespace. */
-export declare function requireLocalNameInStore(store: MemoryStoreDescriptor, rawName: string): string;
-export interface MemoryPlacement {
-    store: MemoryStoreDescriptor;
-    /** Full canonical name — the address the document answers at. */
-    canonicalName: string;
-    /** Store-local name, `''` for the store's own root document. */
-    localName: string;
-    representation: DocRepresentation;
-    /** Store-relative markdown path. */
-    physicalRelativePath: string;
-    /** Absolute path of the `.md` file. */
-    path: string;
-}
-/** Where a NEW document (a `write`, a `move` destination) physically lands in
- *  one exact store, after proving the canonical identity is free.
- *
- *  Both physical forms carry the same identity, so occupancy is checked against
- *  the loaded identities AND both `<local>.md` and `<local>/INDEX.md` — a file
- *  whose explicit `name:` points elsewhere still owns its path. The chosen form
- *  is `<local>/INDEX.md` when the canonical directory already has descendants
- *  in this store (the document fronts a directory that exists), else
- *  `<local>.md`; descendants created later never relocate it, because either
- *  form validly owns the identity. Pass `storeDocs` when the caller already
- *  loaded the store, and `source` when planning a move, whose own identity and
- *  file are being vacated. */
-export declare function planNewDocumentPlacement(store: MemoryStoreDescriptor, rawName: string, storeDocs?: readonly MemoryDoc[], source?: MemoryDoc): MemoryPlacement;
-/** The document a mutation acts on, refusing an identity two files in ONE
- *  store both own. Reads stay answerable (`<name>/INDEX.md` deterministically
- *  wins), but a mutation would silently pick one of two files, so it stops with
- *  both paths. Candidates in OTHER stores are ordinary alternates — precedence
- *  picked the winner and `--dir` reaches the rest. */
-export declare function requireUnambiguousDoc(set: MemoryCandidateSet): MemoryDoc;
-/** Move and delete are the only mutation recovery path for a same-store
- *  collision. The exact-store winner remains the ordinary target; only the
- *  selected store's candidates are ordered by their physical path. */
-export interface MutationDocSelection {
-    doc: MemoryDoc;
-    collisionPaths: readonly string[];
-}
-export declare function selectMutationDoc(set: MemoryCandidateSet): MutationDocSelection;
-/** Remove a just-removed file's now-empty parent directories up to (never
- *  including) its store root, so removing the last entry under an `area/`
- *  prefix does not orphan an empty directory. `pathSegments` counts the
- *  PHYSICAL store-relative path (`doc.physicalRelativePath.split('/').length`),
- *  never the canonical name, which carries the store's namespace on top of it —
- *  the same count addresses a `.history/<path>.jsonl` sidecar. Stops at the
- *  first non-empty ancestor. Every directory resolves beneath `root`, the store root. */
-export declare function pruneEmptyParents(root: string, filePath: string, pathSegments: number): void;
-/** Map a STORE-LOCAL name (`topic`, `area/topic`, `INDEX`) to its file path
- *  under a memory dir, guarding against traversal/absolute escapes. Physical
- *  mapping only: it composes no namespace and collapses no `INDEX`, so a
- *  canonical name reaches it through `planNewDocumentPlacement`. */
-export declare function memoryFilePath(memoryDir: string, name: string): string;
-export declare function coerceGate(raw: string): Record<string, unknown>;
-/** Coerce one `--surface` value into a validated surfaces entry. Strict where
- *  the runtime parser is tolerant: a flag that would be silently dropped or
- *  trimmed at render time is an authoring mistake and fails HERE. The entry is
- *  returned in canonical key order with a single glob kept as a bare string,
- *  so the stored YAML stays as compact as the flag that authored it. */
-export declare function coerceSurface(raw: string): Record<string, unknown>;
-/** Serialize a substrate frontmatter record + body into a complete `.md`
- *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
- *  package — the same one the parser uses — so nested gate maps and surfaces
- *  entry lists round-trip), in canonical field order with preserved extras last. */
-export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;
-/** Everything after the closing frontmatter fence, byte for byte — leading blank
- *  lines and indentation intact. Source without a fence is all body. */
-export declare function literalBodySegment(source: string): string;
-/** Serialize a document WITHOUT touching the body. `bodySegment` is everything
- *  after the closing frontmatter fence (leading blank line included), emitted
- *  byte for byte. This is the revision path: `edit` saves what it was given, so
- *  an unchanged doc round-trips identically and a supplied body reaches disk
- *  untransformed. Creation uses `serializeMemoryDoc`, which normalizes a first
- *  body into the canonical shape. */
-export declare function serializeMemoryDocLiteral(frontmatter: Record<string, unknown>, bodySegment: string): string;
-export declare function coerceLintIgnore(raw: unknown): string | string[] | undefined;
-export interface RequestedExtensionSet {
-    path: string;
-    namespace: string;
-    field: string;
-    value: MemoryExtensionScalar;
-}
-interface RequestedExtensionPath {
-    path: string;
-    namespace: string;
-    field: string;
-}
-/** Resolve declarations at the same scope and path a document will use. The
- * catalog intentionally includes disabled plugins: they still authorize typed
- * edits to values that stay inert until their plugin is enabled again. */
-export declare function memoryExtensionCatalogForDoc(doc: Pick<MemoryDoc, 'scope' | 'path'>): MemoryExtensionCatalog;
-/** Parse every requested extension mutation before the caller constructs any
- * frontmatter. Set values are deliberately declaration-typed rather than YAML. */
-export declare function parseRequestedExtensionChanges(setRaw: readonly string[] | undefined, unsetRaw: readonly string[] | undefined, catalog: MemoryExtensionCatalog): {
-    sets: RequestedExtensionSet[];
-    unsets: RequestedExtensionPath[];
-};
-/** Apply only requested extension paths. Existing unknown namespaces remain
- * untouched; an unset prunes the empty namespace and empty root mapping. */
-export declare function applyExtensionChanges(frontmatter: Record<string, unknown>, sets: readonly RequestedExtensionSet[], unsets: readonly RequestedExtensionPath[]): void;
-export {};

package/dist/core/memory/mutation-domain.js

@@ -1,12 +0,0 @@
-var O=Object.defineProperty;var f=(e,t)=>O(e,"name",{value:t,configurable:!0});import{dirname as y,join as g}from"node:path";import{stringify as $,parse as b}from"yaml";import{usage as s}from"../errors.js";import{existsBeneath as A,readdirBeneath as k,rmdirBeneath as J}from"../spaces/open-beneath.js";import{pathExists as P,realpathOrSelf as x}from"../fs-utils.js";import{loadStoreMemoryDocs as q}from"../memory-resolver.js";import{canonicalSegments as D,physicalRelativePathFor as v,stripNamespace as C,validateExplicitLocalName as L}from"./identity.js";import{memoryExtensionValidationCatalog as F}from"./extensions.js";import{SURFACE_EVENTS as S,SURFACE_RUNGS as w}from"../substrate/schema.js";import{SUPPRESSIBLE_RULES as R}from"../substrate/frontmatter-validation.js";function T(e){if(e.scope!=="project"||e.mountStatus==="ready")return e;const t=e.ownerDir??e.storeRoot;if(e.mountStatus==="absent")throw s(`no memory store at ${e.storeRoot}`,{next:`Initialize it with \`crtr memory write <namespace> --dir ${t}\`, which declares the repository namespace.`});const n=e.repositoryRoot??t;throw s(e.diagnostic??`project memory store at ${e.storeRoot} does not declare a namespace`,{next:`Run \`crtr sys migrate --dir ${n}\`.`})}f(T,"requireMountedStore");function j(e){const t=D(e.trim()).join("/");if(t==="")throw s("memory document name required");const n=L(t);if(!n.ok)throw s(`invalid memory document name \`${e}\`: ${n.reason}`,{received:e,next:"Pass the full canonical name (a project document is <namespace>/<local name>); run `crtr memory find <leaf>` to look one up."});return t}f(j,"requireCanonicalName");function M(e,t){T(e);const n=j(t);if(e.namespace==="")return n;const o=C(n,e.namespace);if(o===null)throw s(`\`${n}\` is not in the namespace of the store at ${e.storeRoot} (\`${e.namespace}\`)`,{memory:n,next:`Every document there answers at \`${e.namespace}/<local name>\`; the store's own document answers at \`${e.namespace}\`.`});return o}f(M,"requireLocalNameInStore");function te(e,t,n,o){const i=M(e,t),r=j(t),a=n??q(e,!0),l=o===void 0?null:x(o.path),c=a.find(h=>h.name===r&&x(h.path)!==l);if(c!==void 0)throw s(`${r} already exists in ${e.storeRoot}`,{memory:r,path:c.path,next:`Revise it with \`crtr memory edit ${r}\`, which records the change, or move it with \`crtr memory move\`.`});const p=(i===""?["directory-index"]:["directory-index","leaf-file"]).map(h=>g(e.storeRoot,v(i,h))).filter(h=>P(h)&&x(h)!==l);if(p.length>0)throw s(`${r} cannot be created: ${p.join(" and ")} already exists`,{memory:r,path:p.join(", "),next:"Both `<name>.md` and `<name>/INDEX.md` carry that identity. Read the existing file, then edit, move, or delete it."});const u=i===""||a.some(h=>h.localName.startsWith(`${i}/`))?"directory-index":"leaf-file",d=v(i,u);return{store:e,canonicalName:r,localName:i,representation:u,physicalRelativePath:d,path:g(e.storeRoot,d)}}f(te,"planNewDocumentPlacement");function ne(e){const t=e.winner,n=e.candidates.filter(o=>o.store.storeRoot===t.store.storeRoot);if(n.length>1)throw s(`${e.name} is owned by ${n.length} files in one store: ${n.map(o=>o.path).join(" and ")}`,{memory:e.name,path:n.map(o=>o.path).join(", "),next:`Recover the collision with \`crtr memory move ${e.name} --to <new-free-name>\`; it selects the first physical path in stable lexical order. Do not remove files by hand; \`crtr memory lint\` reports every such collision.`});return t}f(ne,"requireUnambiguousDoc");function oe(e){const n=[...e.candidates.filter(o=>o.store.storeRoot===e.winner.store.storeRoot)].sort((o,i)=>{const r=o.physicalRelativePath.localeCompare(i.physicalRelativePath);return r!==0?r:o.path.localeCompare(i.path)});return{doc:n[0]??e.winner,collisionPaths:n.length>1?n.map(o=>o.path):[]}}f(oe,"selectMutationDoc");function re(e,t,n){let o=t;for(let r=0;r<n;r+=1)o=y(o);let i=y(t);for(;i!==o&&i.startsWith(o)&&A(e,i)&&k(e,i).length===0;)J(e,i),i=y(i)}f(re,"pruneEmptyParents");function ie(e,t){const n=t.split("/").filter(o=>o.length>0);if(n.length===0)throw s("memory document name required");if(n.some(o=>o==="."||o===".."))throw s(`invalid memory document name: ${t}`);return g(e,...n)+".md"}f(ie,"memoryFilePath");function U(e){const t=b(e);return t!==null&&typeof t=="object"&&!Array.isArray(t)?t:`expected an object, got ${JSON.stringify(t)}`}f(U,"parseYamlObject");function ae(e){const t=U(e);if(typeof t=="string")throw s(`--gate must be a YAML/JSON object (field\u2192matcher map): ${t}. Example: --gate '{kind: design}' or --gate '{orchestration.depth: {gte: 2}}'`);return t}f(ae,"coerceGate");const _=new Set(["on","match","match-frontmatter","gate","at"]);function se(e){const t=b(e);if(t===null||typeof t!="object"||Array.isArray(t))throw s(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?, gate?}, got ${JSON.stringify(t)}. Example: --surface '{on: read, match: "src/**", at: content}'`);const n=t;for(const c of Object.keys(n))if(!_.has(c))throw s(`--surface: unknown key \`${c}\` (an entry carries only on, match, match-frontmatter, gate, at)`);const o=n.on;if(typeof o!="string"||!S.includes(o))throw s(`--surface: invalid \`on\`: ${JSON.stringify(o)} (expected ${S.join("|")})`);const i=n.at;if(typeof i!="string"||!w.includes(i))throw s(`--surface: invalid \`at\`: ${JSON.stringify(i)} (expected ${w.join("|")})`);let r;if(n.match!==void 0){if(o==="boot"||o==="workspace-open")throw s(`--surface: \`match\` is meaningless on \`${o}\` \u2014 the entry's presence is the match; drop it`);if(typeof n.match=="string"){const c=n.match.trim();if(c==="")throw s("--surface: `match` must be a non-empty glob or a non-empty glob list");r=c}else if(Array.isArray(n.match)){const c=n.match.map(m=>typeof m=="string"?m.trim():"");if(c.length===0||c.some(m=>m===""))throw s("--surface: `match` must be a non-empty glob or a non-empty glob list");r=c.length===1?c[0]:c}else throw s(`--surface: invalid \`match\`: ${JSON.stringify(n.match)} (expected a glob string or list)`)}const a=n["match-frontmatter"];if(a!==void 0){if(o!=="read")throw s("--surface: `match-frontmatter` is a `read`-event predicate only");if(a===null||typeof a!="object"||Array.isArray(a))throw s(`--surface: invalid \`match-frontmatter\`: ${JSON.stringify(a)} (expected a field\u2192matcher object)`)}if((o==="read"||o==="memory-read"||o==="command"||o==="pre-command")&&r===void 0&&a===void 0)throw s(`--surface: a \`${o}\` entry requires \`match\`${o==="read"?" or `match-frontmatter`":""}`);const l=n.gate;if(l!==void 0&&(l===null||typeof l!="object"||Array.isArray(l)))throw s(`--surface: invalid \`gate\`: ${JSON.stringify(l)} (expected a field\u2192matcher object)`);return{on:o,...r!==void 0?{match:r}:{},...a!==void 0?{"match-frontmatter":a}:{},...l!==void 0?{gate:l}:{},at:i}}f(se,"coerceSurface");const N=["kind","privacy","when-and-why-to-read","short-form","unlisted","surfaces","gate","slash","rationale","lint-ignore","last-updated","origin"];function ce(e,t){const n={};for(const r of N)e[r]!==void 0&&(n[r]=e[r]);for(const r of Object.keys(e))!(r in n)&&e[r]!==void 0&&(n[r]=e[r]);const o=$(n).replace(/\n+$/,""),i=t.replace(/^\n+/,"").replace(/\s+$/,"");return`---
-${o}
----
-
-${i}
-`}f(ce,"serializeMemoryDoc");const B=/^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;function fe(e){const t=e.match(B);return t?e.slice(t[0].length):e}f(fe,"literalBodySegment");function me(e,t){const n={};for(const i of N)e[i]!==void 0&&(n[i]=e[i]);for(const i of Object.keys(e))!(i in n)&&e[i]!==void 0&&(n[i]=e[i]);return`---
-${$(n).replace(/\n+$/,"")}
----
-${/^\r?\n/.test(t)?"":`
-`}${t}`}f(me,"serializeMemoryDocLiteral");function le(e){if(e===void 0)return;const t=Array.isArray(e)?e:[e];if(t.length===0||t.some(n=>typeof n!="string"||!R.includes(n)))throw s(`invalid lint-ignore: ${JSON.stringify(e)} (suppressible rules: ${R.map(n=>`\`${n}\``).join(", ")})`);return t.length===1?t[0]:t}f(le,"coerceLintIgnore");function pe(e){return F(e)}f(pe,"memoryExtensionCatalogForDoc");function ue(e){return e.type!=="enum"?e.type:`enum (${e.values.join("|")})`}f(ue,"declarationValueDescription");function de(e){return typeof e=="string"?JSON.stringify(e):String(e)}f(de,"extensionHelpValue");function E(e,t){const n=/^extensions\.([^.]+)\.([^.]+)$/.exec(e);return n===null?`${t} requires the full path extensions.<plugin>.<field>: ${e}`:{path:e,namespace:n[1],field:n[2]}}f(E,"parseExtensionPath");function I(e,t,n){if(n.type==="boolean")return t==="true"?!0:t==="false"?!1:`${e} expects boolean true or false, received ${JSON.stringify(t)}`;if(n.type==="number"){if(!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(t))return`${e} expects finite numeric syntax, received ${JSON.stringify(t)}`;const o=Number(t);return Number.isFinite(o)?o:`${e} expects a finite number, received ${JSON.stringify(t)}`}return n.type==="enum"&&!n.values.includes(t)?`${e} expects one of ${n.values.join("|")}, received ${JSON.stringify(t)}`:t}f(I,"parseExtensionValue");function he(e,t,n){const o=[],i=[],r=[],a=new Set,l=new Set;for(const c of e??[]){const m=c.indexOf("=");if(m<0){o.push(`--extension requires extensions.<plugin>.<field>=VALUE: ${c}`);continue}const p=E(c.slice(0,m),"--extension");if(typeof p=="string"){o.push(p);continue}if(a.has(p.path)){o.push(`duplicate --extension path: ${p.path}`);continue}a.add(p.path);const u=n[p.namespace]?.[p.field];if(u===void 0){o.push(`${p.path} is not declared by an installed plugin`);continue}const d=I(p.path,c.slice(m+1),u);if(typeof d=="string"&&u.type!=="string"&&u.type!=="enum"){o.push(d);continue}if(typeof d=="string"&&u.type==="enum"&&!u.values.includes(d)){o.push(`${p.path} expects one of ${u.values.join("|")}, received ${JSON.stringify(d)}`);continue}i.push({...p,value:d})}for(const c of t??[]){const m=E(c,"--unset-extension");if(typeof m=="string"){o.push(m);continue}if(l.has(m.path)){o.push(`duplicate --unset-extension path: ${m.path}`);continue}if(l.add(m.path),n[m.namespace]?.[m.field]===void 0){o.push(`${m.path} is not declared by an installed plugin`);continue}r.push(m)}for(const c of a)l.has(c)&&o.push(`${c} was requested in both --extension and --unset-extension`);if(o.length>0)throw s(`invalid plugin memory extension request:
-- ${o.join(`
-- `)}`,{received:[...e??[],...t??[]].join(", "),next:"Run `crtr memory write -h` or `crtr memory edit -h` for the installed field catalog and value syntax."});return{sets:i,unsets:r}}f(he,"parseRequestedExtensionChanges");function ye(e,t,n){if(t.length===0&&n.length===0)return;const o=e.extensions;if(o!==void 0&&(o===null||typeof o!="object"||Array.isArray(o)))throw s("existing extensions frontmatter must be a mapping before extension fields can be changed",{received:JSON.stringify(o),next:"Repair the extensions mapping, or make a core-field-only edit that preserves it unchanged."});const i={...o??{}};for(const r of t){const a=i[r.namespace];if(a!==void 0&&(a===null||typeof a!="object"||Array.isArray(a)))throw s(`existing ${`extensions.${r.namespace}`} frontmatter must be a mapping before ${r.path} can change`,{received:JSON.stringify(a),next:"Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged."});i[r.namespace]={...a??{},[r.field]:r.value}}for(const r of n){const a=i[r.namespace];if(a===void 0)continue;if(a===null||typeof a!="object"||Array.isArray(a))throw s(`existing ${`extensions.${r.namespace}`} frontmatter must be a mapping before ${r.path} can change`,{received:JSON.stringify(a),next:"Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged."});const l={...a};delete l[r.field],Object.keys(l).length===0?delete i[r.namespace]:i[r.namespace]=l}Object.keys(i).length===0?delete e.extensions:e.extensions=i}f(ye,"applyExtensionChanges");export{ye as applyExtensionChanges,ae as coerceGate,le as coerceLintIgnore,se as coerceSurface,fe as literalBodySegment,pe as memoryExtensionCatalogForDoc,ie as memoryFilePath,he as parseRequestedExtensionChanges,te as planNewDocumentPlacement,re as pruneEmptyParents,j as requireCanonicalName,M as requireLocalNameInStore,T as requireMountedStore,ne as requireUnambiguousDoc,oe as selectMutationDoc,ce as serializeMemoryDoc,me as serializeMemoryDocLiteral};