mrplex 0.0.1

package/dist/kernel/errors.js

@@ -0,0 +1,55 @@
+/**
+ * Kernel error catalog. Every kernel-emitted error has a stable `code` and
+ * a JSON-serializable `data` payload — design §4.3.
+ *
+ * M0 surfaces only the read-time subset; writes and auth land in M1.
+ */
+export class KernelError extends Error {
+    code;
+    data;
+    constructor(code, data, message) {
+        super(message ?? code);
+        this.code = code;
+        this.data = data;
+        this.name = "KernelError";
+    }
+}
+/**
+ * Runtime set matching KernelErrorCode. Used by the remote MCP client to
+ * validate an incoming `code` string before rehydrating a KernelError —
+ * otherwise a rogue server could inject unknown codes and break clients
+ * that switch exhaustively.
+ */
+export const KERNEL_ERROR_CODES = new Set([
+    "repo_not_found",
+    "doc_not_found",
+    "version_not_found",
+    "version_not_in_document",
+    "slug_invalid",
+    "path_invalid",
+    "frontmatter_invalid",
+    "filter_invalid",
+    "link_config_invalid",
+    "stale_prev",
+    "create_conflict",
+    "path_taken",
+    "slug_taken",
+    "forbidden",
+    "precondition_required",
+    "payload_too_large",
+    "semantic_unavailable",
+]);
+/** Type guard — check whether an arbitrary string is a known catalog code. */
+export function isKernelErrorCode(code) {
+    return KERNEL_ERROR_CODES.has(code);
+}
+export const repoNotFound = (slug) => new KernelError("repo_not_found", { slug });
+export const docNotFound = (repo, path) => new KernelError("doc_not_found", { repo, path });
+export const versionNotFound = (versionId) => new KernelError("version_not_found", { version_id: versionId });
+export const versionNotInDocument = (versionId, repo, path) => new KernelError("version_not_in_document", { version_id: versionId, repo, path });
+// `forbidden` (§8.4): the scope claim supplied with this call excludes the
+// target. Still HTTP 403; still omits resource details so out-of-claim and
+// nonexistent look identical (shells can hand mrplex errors to their untrusted
+// callers unfiltered). `unauthorized` is gone — the engine trusts every caller.
+export const forbidden = () => new KernelError("forbidden", {});
+//# sourceMappingURL=errors.js.map

package/dist/kernel/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/kernel/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH,MAAM,OAAO,WAAyC,SAAQ,KAAK;IAE/C;IACA;IAFlB,YACkB,IAAqB,EACrB,IAAO,EACvB,OAAgB;QAEhB,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QAJP,SAAI,GAAJ,IAAI,CAAiB;QACrB,SAAI,GAAJ,IAAI,CAAG;QAIvB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAiC,IAAI,GAAG,CAAkB;IACvF,gBAAgB;IAChB,eAAe;IACf,mBAAmB;IACnB,yBAAyB;IACzB,cAAc;IACd,cAAc;IACd,qBAAqB;IACrB,gBAAgB;IAChB,qBAAqB;IACrB,YAAY;IACZ,iBAAiB;IACjB,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,uBAAuB;IACvB,mBAAmB;IACnB,sBAAsB;CACvB,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAuB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,EAAE,CACxD,IAAI,WAAW,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAEnD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAiB,EAAE,EAAE,CACnD,IAAI,WAAW,CAAC,mBAAmB,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,SAAiB,EAAE,IAAY,EAAE,IAAY,EAAE,EAAE,CACpF,IAAI,WAAW,CAAC,yBAAyB,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAEpF,2EAA2E;AAC3E,2EAA2E;AAC3E,+EAA+E;AAC/E,gFAAgF;AAChF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC"}

package/dist/kernel/frontmatter-input.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonicalize the two frontmatter input forms into the pair stored on
+ * `versions`. Design §3.2:
+ *
+ *   Writes supply exactly ONE of:
+ *     • frontmatter_raw  — verbatim YAML source; parsed → JSON for the index
+ *     • frontmatter      — structured JSON; serialized → canonical YAML
+ *   The other is derived. Supplying both → `frontmatter_invalid`.
+ *
+ * On read, the raw form is what `Accept: text/markdown` returns — so a
+ * write via `frontmatter_raw` round-trips byte-exact. A write via
+ * `frontmatter` (structured) does NOT preserve comments/key order from any
+ * prior version; the caller opted into that by choosing the structured form.
+ */
+import { type FrontmatterJson } from "../markdown/frontmatter.js";
+export type FrontmatterInput = {
+    frontmatter?: FrontmatterJson;
+    frontmatter_raw?: string;
+};
+export type CanonicalFrontmatter = {
+    frontmatter: FrontmatterJson;
+    frontmatter_raw: string;
+};
+/**
+ * Take a write's frontmatter input and produce the canonical (raw, parsed)
+ * pair. Enforces the §3.2 "exactly one" rule and surfaces YAML errors as
+ * `frontmatter_invalid`.
+ *
+ * If neither is supplied, throws `frontmatter_invalid` (callers that want
+ * "carry over from prev" should pass prev's frontmatter_raw explicitly).
+ */
+export declare function canonicalizeFrontmatter(input: FrontmatterInput): CanonicalFrontmatter;

package/dist/kernel/frontmatter-input.js

@@ -0,0 +1,85 @@
+/**
+ * Canonicalize the two frontmatter input forms into the pair stored on
+ * `versions`. Design §3.2:
+ *
+ *   Writes supply exactly ONE of:
+ *     • frontmatter_raw  — verbatim YAML source; parsed → JSON for the index
+ *     • frontmatter      — structured JSON; serialized → canonical YAML
+ *   The other is derived. Supplying both → `frontmatter_invalid`.
+ *
+ * On read, the raw form is what `Accept: text/markdown` returns — so a
+ * write via `frontmatter_raw` round-trips byte-exact. A write via
+ * `frontmatter` (structured) does NOT preserve comments/key order from any
+ * prior version; the caller opted into that by choosing the structured form.
+ */
+import { stringify as stringifyYaml } from "yaml";
+import { extractSystemProperties, parse as parseFrontmatter, } from "../markdown/frontmatter.js";
+import { INTRINSIC_SIGIL } from "./constants.js";
+import { KernelError } from "./errors.js";
+/**
+ * Take a write's frontmatter input and produce the canonical (raw, parsed)
+ * pair. Enforces the §3.2 "exactly one" rule and surfaces YAML errors as
+ * `frontmatter_invalid`.
+ *
+ * If neither is supplied, throws `frontmatter_invalid` (callers that want
+ * "carry over from prev" should pass prev's frontmatter_raw explicitly).
+ */
+export function canonicalizeFrontmatter(input) {
+    const hasRaw = input.frontmatter_raw !== undefined;
+    const hasStruct = input.frontmatter !== undefined;
+    if (hasRaw && hasStruct) {
+        throw new KernelError("frontmatter_invalid", {
+            reason: "supply exactly one of frontmatter | frontmatter_raw, not both",
+        });
+    }
+    if (!hasRaw && !hasStruct) {
+        throw new KernelError("frontmatter_invalid", {
+            reason: "one of frontmatter | frontmatter_raw is required",
+        });
+    }
+    if (hasRaw) {
+        // Strip system properties (`$*`) before parsing/storing. Surfaces that
+        // support the $version round-trip already peel it off; this is
+        // belt-and-braces so no surface can accidentally poison storage with
+        // reserved keys.
+        const raw = stripSystemProps(input.frontmatter_raw);
+        try {
+            const parsed = parseFrontmatter(raw);
+            return { frontmatter: parsed, frontmatter_raw: raw };
+        }
+        catch (err) {
+            throw new KernelError("frontmatter_invalid", {
+                reason: err.message,
+            });
+        }
+    }
+    // Structured branch — serialize to canonical YAML.
+    const structuredInput = input.frontmatter;
+    if (structuredInput === null ||
+        typeof structuredInput !== "object" ||
+        Array.isArray(structuredInput)) {
+        throw new KernelError("frontmatter_invalid", {
+            reason: "structured frontmatter must be a map",
+        });
+    }
+    const structured = stripSystemKeys(structuredInput);
+    // Empty map → empty raw (round-trips as "no frontmatter block" via the
+    // markdown/frontmatter.split rule).
+    if (Object.keys(structured).length === 0) {
+        return { frontmatter: structured, frontmatter_raw: "" };
+    }
+    const rawFromStructured = stringifyYaml(structured);
+    return { frontmatter: structured, frontmatter_raw: rawFromStructured };
+}
+function stripSystemProps(raw) {
+    return extractSystemProperties(raw).raw;
+}
+function stripSystemKeys(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (!k.startsWith(INTRINSIC_SIGIL))
+            out[k] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=frontmatter-input.js.map

package/dist/kernel/frontmatter-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-input.js","sourceRoot":"","sources":["../../src/kernel/frontmatter-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAEL,uBAAuB,EACvB,KAAK,IAAI,gBAAgB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAY1C;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAuB;IAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,KAAK,SAAS,CAAC;IACnD,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC;IAElD,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,qBAAqB,EAAE;YAC3C,MAAM,EAAE,+DAA+D;SACxE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,WAAW,CAAC,qBAAqB,EAAE;YAC3C,MAAM,EAAE,kDAAkD;SAC3D,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,uEAAuE;QACvE,+DAA+D;QAC/D,qEAAqE;QACrE,iBAAiB;QACjB,MAAM,GAAG,GAAG,gBAAgB,CAAC,KAAK,CAAC,eAAyB,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACrC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC;QACvD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,WAAW,CAAC,qBAAqB,EAAE;gBAC3C,MAAM,EAAG,GAAa,CAAC,OAAO;aAC/B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,MAAM,eAAe,GAAG,KAAK,CAAC,WAA8B,CAAC;IAC7D,IACE,eAAe,KAAK,IAAI;QACxB,OAAO,eAAe,KAAK,QAAQ;QACnC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,EAC9B,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,qBAAqB,EAAE;YAC3C,MAAM,EAAE,sCAAsC;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,MAAM,UAAU,GAAG,eAAe,CAAC,eAAe,CAAC,CAAC;IACpD,uEAAuE;IACvE,oCAAoC;IACpC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,iBAAiB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACpD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;AAC1C,CAAC;AAED,SAAS,eAAe,CAAC,GAAoB;IAC3C,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,eAAe,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/kernel/graph.d.ts

@@ -0,0 +1,34 @@
+/**
+ * kernel.graph — the graph read surface (docs/graph-plan.md).
+ *
+ * A read-only BFS neighborhood expansion over the repo-local `links` derived
+ * index. Given a root set, expand outward under a direction lens, honoring
+ * scope and `filter` as *visibility* (traversal happens inside the visible
+ * subgraph), and return documents, distinct induced links, a behavioral
+ * frontier, and truncation metadata.
+ *
+ * The whole thing is expressed in the system's own vocabulary — documents and
+ * links — with no node/edge layer. See §5 for the pinned decisions.
+ *
+ * Visibility reuse: rather than re-implement scope/sigil/filter evaluation,
+ * every visibility check runs through the existing `versions_search` path via
+ * a `SearchPlan`. `$degrees` is bound per round by rewriting the parsed filter
+ * to an integer constant (degrees.ts), so both dialect compilers stay unaware
+ * of it. This is the "reuse the SearchPlan path" mandate of §4.3.
+ */
+import type { Storage } from "../storage/types.js";
+import { type ClaimMatcher } from "./auth/scope.js";
+import { type PathConfig } from "./path-config.js";
+import type { GraphResult, GraphSpec } from "./wire.js";
+export declare const DEFAULT_DEGREES = 1;
+export declare const MAX_DEGREES = 5;
+export declare const DEFAULT_MAX_DOCUMENTS = 100;
+export declare const HARD_MAX_DOCUMENTS = 500;
+export declare const LINKS_CEILING = 5000;
+export type GraphDeps = {
+    storage: Storage;
+    serverPathConfig: PathConfig;
+    /** Effective path config for the target repo (for exact root normalization). */
+    pathConfig: PathConfig;
+};
+export declare function runGraph(claims: ClaimMatcher[] | null, spec: GraphSpec, deps: GraphDeps): Promise<GraphResult>;