mrplex 0.0.1

package/dist/kernel/casefold.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Case & Unicode folding for path/slug IDENTITY — design §3.5.1 amendment
+ * (case-folding-plan.md WS1).
+ *
+ * `normalizeKey` computes the derived key that drives case-insensitive,
+ * Unicode-normalized uniqueness and by-key lookups. Storage stays
+ * case- and form-preserving (we store the author's exact bytes); this
+ * key is an index artifact, never surfaced on the wire (§3.3-style
+ * internal-only, decision 7).
+ *
+ * THE ONE AUTHORITY. Both storage adapters receive the pre-computed key
+ * from the kernel — neither calls SQL `lower()`, `COLLATE NOCASE`, or
+ * `citext`. That is deliberate: SQLite's `lower()` is ASCII-only without
+ * ICU, while Postgres's is locale-aware, so a functional index would
+ * silently diverge on non-ASCII input and break the §7.2 adapter-parity
+ * guarantee. Folding in JS, here, keeps the two engines identical.
+ *
+ * Strength (decision 4): **NFC + locale-invariant lowercase.** This folds
+ * all accented Latin/Greek/Cyrillic and the common case, and makes NFC/NFD
+ * spellings of the same text compare equal. It deliberately does NOT fold
+ * the German ß→ss, ligatures (fi→fi), or Greek final-sigma — those need the
+ * full Unicode default case-fold table, an additive upgrade later (the key
+ * is recomputed by a backfill, so strengthening it is non-breaking beyond a
+ * re-index). casefold.test.ts pins the exact boundary.
+ *
+ * `toLowerCase()` (NOT `toLocaleLowerCase()`) is used on purpose: a locale
+ * fold would map Turkish `I`→`ı`, making document identity depend on the
+ * server's locale. Identity must be locale-independent.
+ */
+/**
+ * Fold a path or slug to its identity key. Idempotent, total, pure.
+ *
+ *   normalizeKey("Alice.md")        === "alice.md"
+ *   normalizeKey("café.md" as NFD)  === normalizeKey("café.md" as NFC)
+ *   normalizeKey(normalizeKey(x))   === normalizeKey(x)
+ */
+export declare function normalizeKey(s: string): string;

package/dist/kernel/casefold.js

@@ -0,0 +1,44 @@
+/**
+ * Case & Unicode folding for path/slug IDENTITY — design §3.5.1 amendment
+ * (case-folding-plan.md WS1).
+ *
+ * `normalizeKey` computes the derived key that drives case-insensitive,
+ * Unicode-normalized uniqueness and by-key lookups. Storage stays
+ * case- and form-preserving (we store the author's exact bytes); this
+ * key is an index artifact, never surfaced on the wire (§3.3-style
+ * internal-only, decision 7).
+ *
+ * THE ONE AUTHORITY. Both storage adapters receive the pre-computed key
+ * from the kernel — neither calls SQL `lower()`, `COLLATE NOCASE`, or
+ * `citext`. That is deliberate: SQLite's `lower()` is ASCII-only without
+ * ICU, while Postgres's is locale-aware, so a functional index would
+ * silently diverge on non-ASCII input and break the §7.2 adapter-parity
+ * guarantee. Folding in JS, here, keeps the two engines identical.
+ *
+ * Strength (decision 4): **NFC + locale-invariant lowercase.** This folds
+ * all accented Latin/Greek/Cyrillic and the common case, and makes NFC/NFD
+ * spellings of the same text compare equal. It deliberately does NOT fold
+ * the German ß→ss, ligatures (fi→fi), or Greek final-sigma — those need the
+ * full Unicode default case-fold table, an additive upgrade later (the key
+ * is recomputed by a backfill, so strengthening it is non-breaking beyond a
+ * re-index). casefold.test.ts pins the exact boundary.
+ *
+ * `toLowerCase()` (NOT `toLocaleLowerCase()`) is used on purpose: a locale
+ * fold would map Turkish `I`→`ı`, making document identity depend on the
+ * server's locale. Identity must be locale-independent.
+ */
+/**
+ * Fold a path or slug to its identity key. Idempotent, total, pure.
+ *
+ *   normalizeKey("Alice.md")        === "alice.md"
+ *   normalizeKey("café.md" as NFD)  === normalizeKey("café.md" as NFC)
+ *   normalizeKey(normalizeKey(x))   === normalizeKey(x)
+ */
+export function normalizeKey(s) {
+    // Fold case, then re-normalize: `toLowerCase()` can, for a few code
+    // points, emit a sequence that isn't NFC, which would break the
+    // idempotency contract (normalizeKey∘normalizeKey === normalizeKey).
+    // The trailing NFC pass makes the output a stable fixed point.
+    return s.normalize("NFC").toLowerCase().normalize("NFC");
+}
+//# sourceMappingURL=casefold.js.map

package/dist/kernel/casefold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"casefold.js","sourceRoot":"","sources":["../../src/kernel/casefold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,oEAAoE;IACpE,gEAAgE;IAChE,qEAAqE;IACrE,+DAA+D;IAC/D,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC"}

package/dist/kernel/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cross-cutting kernel constants. Kept small on purpose — this is not a
+ * grab-bag. Only things with more than one caller and no better home.
+ */
+/**
+ * Intrinsic sigil — the leading character that marks an identifier as
+ * server-owned rather than user-authored. Single source of truth.
+ *
+ * Two surfaces share it:
+ *
+ *   • Query filter syntax — `$path`, `$updated_at`, `$body`, and other
+ *     intrinsics recognized by the CEL parser (see ../kernel/query/cel-parse.ts).
+ *   • Frontmatter system properties — `$version` and (future) `$author`,
+ *     `$updated_at`, etc., injected into GET responses and stripped on
+ *     write (see ../markdown/frontmatter.ts).
+ *
+ * Not to be confused with `PathConfig.system_sigils` in wire.ts, which
+ * governs a different reservation entirely (path-segment prefixes like
+ * `.` / `:` gating hidden and deleted namespaces).
+ */
+export declare const INTRINSIC_SIGIL = "$";

package/dist/kernel/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Cross-cutting kernel constants. Kept small on purpose — this is not a
+ * grab-bag. Only things with more than one caller and no better home.
+ */
+/**
+ * Intrinsic sigil — the leading character that marks an identifier as
+ * server-owned rather than user-authored. Single source of truth.
+ *
+ * Two surfaces share it:
+ *
+ *   • Query filter syntax — `$path`, `$updated_at`, `$body`, and other
+ *     intrinsics recognized by the CEL parser (see ../kernel/query/cel-parse.ts).
+ *   • Frontmatter system properties — `$version` and (future) `$author`,
+ *     `$updated_at`, etc., injected into GET responses and stripped on
+ *     write (see ../markdown/frontmatter.ts).
+ *
+ * Not to be confused with `PathConfig.system_sigils` in wire.ts, which
+ * governs a different reservation entirely (path-segment prefixes like
+ * `.` / `:` gating hidden and deleted namespaces).
+ */
+export const INTRINSIC_SIGIL = "$";
+//# sourceMappingURL=constants.js.map

package/dist/kernel/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/kernel/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC"}

package/dist/kernel/context.d.ts

@@ -0,0 +1,70 @@
+/**
+ * CallContext — the uniform first parameter to every kernel op (design §8,
+ * noauth plan §1).
+ *
+ * mrplex is a full-trust kernel: any caller that can reach it can do anything.
+ * There is no resolved identity, no token, no admin bit. What a caller supplies
+ * per call is:
+ *
+ *   • `author` — an opaque string stamped on the versions it writes. The engine
+ *     attaches no semantics (the `Full Name <email>` convention is caller-side).
+ *     Defaults to "mrplex". Sanity-validated only (non-empty, no control chars,
+ *     length-capped) — never parsed.
+ *   • `scope` — optional read-visibility narrowing. Absent = everything visible.
+ *     Present = the call sees only what the claims grant (silent filtering on
+ *     `query`; `forbidden` on a targeted read outside the claim). This is the
+ *     one enforcement seam a fronting shell cannot replicate from outside, so
+ *     it stays in the engine — exposed as a plain input, not derived from a
+ *     token.
+ */
+/**
+ * A territory claim. `repo` is a slug, glob, or "*" — evaluated against the
+ * repos existing at call time, every call (no issuance snapshot, no id
+ * binding). `paths` is a gitignore-style path glob list (§8.2 semantics).
+ *
+ * Deliberately direction-neutral: a claim names repos/paths, not a direction.
+ * Meaning comes from where it sits — `ctx.scope` is read visibility; the
+ * auth-shell reuses the same type for its shell-enforced write matcher.
+ */
+export type ScopeClaim = {
+    repo: string | string[];
+    paths?: string | string[];
+};
+export type CallContext = {
+    /** Writes: opaque author string. Default "mrplex". */
+    author?: string;
+    /** Reads: visibility claims. Absent = everything visible. */
+    scope?: ScopeClaim[];
+};
+/** Identity stamped on a write when the caller supplies no author. */
+export declare const DEFAULT_AUTHOR = "mrplex";
+/**
+ * Structurally validate an already-parsed value as `ScopeClaim[]`. This is the
+ * single validation path shared by every surface that accepts a scope — the
+ * `X-Mrplex-Scope` header (via [[parseScopeClaims]]), the `POST /query` body
+ * `scope` field, the MCP query tool-arg, and the CLI `--scope` flag. Routing
+ * all of them here means a claim missing `repo` (or with wrong types) is a loud
+ * `filter_invalid`, not a silent `deny_all` empty result (see the note in
+ * kernel/auth/scope.ts on how `normalizeClaims` treats a repo-less claim).
+ *
+ * Throws `KernelError("filter_invalid")` on bad input so surfaces map it to a
+ * 4xx uniformly rather than a 500.
+ */
+export declare function validateScopeClaims(parsed: unknown): ScopeClaim[];
+/**
+ * Parse a JSON string into `ScopeClaim[]`. Used to decode the `X-Mrplex-Scope`
+ * header and the CLI `--scope` flag. Throws `KernelError("filter_invalid")` on
+ * malformed input so a bad claim is a loud client error, not a silent
+ * full-access fallback.
+ */
+export declare function parseScopeClaims(json: string): ScopeClaim[];
+/**
+ * Resolve + validate the author for a write. Opaque: we sanity-check only
+ * (non-empty, no control characters, length-capped) and never parse the value.
+ * An empty/absent author yields the default "mrplex".
+ *
+ * Throws `KernelError("filter_invalid")` on bad input — the author is reachable
+ * verbatim from the `X-Mrplex-Author` header, so a control-char or over-length
+ * value is a client mistake and must stay in the 4xx band, not surface as a 500.
+ */
+export declare function resolveAuthor(ctx: CallContext): string;

package/dist/kernel/context.js

@@ -0,0 +1,114 @@
+/**
+ * CallContext — the uniform first parameter to every kernel op (design §8,
+ * noauth plan §1).
+ *
+ * mrplex is a full-trust kernel: any caller that can reach it can do anything.
+ * There is no resolved identity, no token, no admin bit. What a caller supplies
+ * per call is:
+ *
+ *   • `author` — an opaque string stamped on the versions it writes. The engine
+ *     attaches no semantics (the `Full Name <email>` convention is caller-side).
+ *     Defaults to "mrplex". Sanity-validated only (non-empty, no control chars,
+ *     length-capped) — never parsed.
+ *   • `scope` — optional read-visibility narrowing. Absent = everything visible.
+ *     Present = the call sees only what the claims grant (silent filtering on
+ *     `query`; `forbidden` on a targeted read outside the claim). This is the
+ *     one enforcement seam a fronting shell cannot replicate from outside, so
+ *     it stays in the engine — exposed as a plain input, not derived from a
+ *     token.
+ */
+import { KernelError } from "./errors.js";
+/** Identity stamped on a write when the caller supplies no author. */
+export const DEFAULT_AUTHOR = "mrplex";
+const MAX_AUTHOR_LENGTH = 512;
+/** True if `s` contains any C0/C1 control character (incl. tab/newline). */
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c <= 0x1f || (c >= 0x7f && c <= 0x9f))
+            return true;
+    }
+    return false;
+}
+/**
+ * Structurally validate an already-parsed value as `ScopeClaim[]`. This is the
+ * single validation path shared by every surface that accepts a scope — the
+ * `X-Mrplex-Scope` header (via [[parseScopeClaims]]), the `POST /query` body
+ * `scope` field, the MCP query tool-arg, and the CLI `--scope` flag. Routing
+ * all of them here means a claim missing `repo` (or with wrong types) is a loud
+ * `filter_invalid`, not a silent `deny_all` empty result (see the note in
+ * kernel/auth/scope.ts on how `normalizeClaims` treats a repo-less claim).
+ *
+ * Throws `KernelError("filter_invalid")` on bad input so surfaces map it to a
+ * 4xx uniformly rather than a 500.
+ */
+export function validateScopeClaims(parsed) {
+    if (!Array.isArray(parsed)) {
+        throw new KernelError("filter_invalid", { reason: "scope must be an array of claims" });
+    }
+    const isStrOrStrList = (v) => typeof v === "string" || (Array.isArray(v) && v.every((x) => typeof x === "string"));
+    for (const entry of parsed) {
+        if (typeof entry !== "object" || entry === null) {
+            throw new KernelError("filter_invalid", { reason: "scope claim must be an object" });
+        }
+        const e = entry;
+        if (!isStrOrStrList(e.repo)) {
+            throw new KernelError("filter_invalid", {
+                reason: "scope claim `repo` must be a string or string[]",
+            });
+        }
+        if (e.paths !== undefined && !isStrOrStrList(e.paths)) {
+            throw new KernelError("filter_invalid", {
+                reason: "scope claim `paths` must be a string or string[]",
+            });
+        }
+    }
+    return parsed;
+}
+/**
+ * Parse a JSON string into `ScopeClaim[]`. Used to decode the `X-Mrplex-Scope`
+ * header and the CLI `--scope` flag. Throws `KernelError("filter_invalid")` on
+ * malformed input so a bad claim is a loud client error, not a silent
+ * full-access fallback.
+ */
+export function parseScopeClaims(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new KernelError("filter_invalid", {
+            reason: "scope must be valid JSON (a ScopeClaim array)",
+        });
+    }
+    return validateScopeClaims(parsed);
+}
+/**
+ * Resolve + validate the author for a write. Opaque: we sanity-check only
+ * (non-empty, no control characters, length-capped) and never parse the value.
+ * An empty/absent author yields the default "mrplex".
+ *
+ * Throws `KernelError("filter_invalid")` on bad input — the author is reachable
+ * verbatim from the `X-Mrplex-Author` header, so a control-char or over-length
+ * value is a client mistake and must stay in the 4xx band, not surface as a 500.
+ */
+export function resolveAuthor(ctx) {
+    const raw = ctx.author;
+    if (raw === undefined || raw === "")
+        return DEFAULT_AUTHOR;
+    if (typeof raw !== "string") {
+        throw new KernelError("filter_invalid", { reason: "author must be a string" });
+    }
+    if (raw.length > MAX_AUTHOR_LENGTH) {
+        throw new KernelError("filter_invalid", {
+            reason: `author exceeds ${MAX_AUTHOR_LENGTH} characters`,
+        });
+    }
+    if (hasControlChar(raw)) {
+        throw new KernelError("filter_invalid", {
+            reason: "author must not contain control characters",
+        });
+    }
+    return raw;
+}
+//# sourceMappingURL=context.js.map

package/dist/kernel/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/kernel/context.ts"],"names":[],"mappings":"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"}

package/dist/kernel/deletion.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Deletion path builder — design §3.4.
+ *
+ *   path/to/document.md   @ v45129   →   :deleted/path/to/document-v45129.md
+ *
+ * The version-id suffix goes before the file extension so type detection,
+ * syntax highlighting, and globs like `**\/*.md` keep working on trashed docs.
+ * The extension is "everything from the final segment's last '.'" — with the
+ * key caveat that a leading dot doesn't count. So:
+ *
+ *   README                   → README-v45129
+ *   .gitignore               → .gitignore-v45129
+ *   notes/foo.tar.gz         → notes/foo.tar-v45129.gz
+ *   notes/a-v42.md           → notes/a-v42-v45129.md   (uniqueness still holds:
+ *                                                       version_ids are unique
+ *                                                       and the suffix is
+ *                                                       always appended)
+ */
+/**
+ * Split the final segment of a path into `(basename, extension)` per the
+ * "final dot, but not a leading dot" rule from §3.4.
+ *
+ * Returned extension includes its leading dot (e.g. `.md`), or is `""` when
+ * there is no extension.
+ */
+export declare function splitExtension(finalSegment: string): {
+    basename: string;
+    extension: string;
+};
+/**
+ * Insert a version-id suffix before the extension of the final path segment.
+ * Does NOT prepend the deletion sigil — that's `deletionPath`'s job.
+ */
+export declare function withVersionSuffix(path: string, versionIdString: string): string;
+/**
+ * The kernel-emitted path for a deletion move. `<systemSigil>` is the
+ * canonical (first-entry) system sigil from the effective path config
+ * (design §3.5.4 — set for input, first for output).
+ *
+ * Example:
+ *   deletionPath(":", "notes/foo.md", "v45129") = ":deleted/notes/foo-v45129.md"
+ */
+export declare function deletionPath(systemSigil: string, originalPath: string, versionIdString: string): string;
+/**
+ * Rough classifier used by `docs.delete` idempotency (§4.1 rule 4): true if
+ * ANY segment of the path starts with one of the accepted system sigils.
+ * (The design-wide primitive lives in validation.pathHasSigilSegment; this
+ * shim keeps the naming intent-facing at the call site.)
+ */
+export declare function pathIsInSystemNamespace(path: string, systemSigils: readonly string[]): boolean;

package/dist/kernel/deletion.js

@@ -0,0 +1,83 @@
+/**
+ * Deletion path builder — design §3.4.
+ *
+ *   path/to/document.md   @ v45129   →   :deleted/path/to/document-v45129.md
+ *
+ * The version-id suffix goes before the file extension so type detection,
+ * syntax highlighting, and globs like `**\/*.md` keep working on trashed docs.
+ * The extension is "everything from the final segment's last '.'" — with the
+ * key caveat that a leading dot doesn't count. So:
+ *
+ *   README                   → README-v45129
+ *   .gitignore               → .gitignore-v45129
+ *   notes/foo.tar.gz         → notes/foo.tar-v45129.gz
+ *   notes/a-v42.md           → notes/a-v42-v45129.md   (uniqueness still holds:
+ *                                                       version_ids are unique
+ *                                                       and the suffix is
+ *                                                       always appended)
+ */
+import { PATH_SEPARATOR } from "./validation.js";
+/**
+ * Split the final segment of a path into `(basename, extension)` per the
+ * "final dot, but not a leading dot" rule from §3.4.
+ *
+ * Returned extension includes its leading dot (e.g. `.md`), or is `""` when
+ * there is no extension.
+ */
+export function splitExtension(finalSegment) {
+    // A leading dot doesn't count as an extension separator — .gitignore is
+    // basename `.gitignore`, extension "".
+    const searchFrom = finalSegment.startsWith(".") ? 1 : 0;
+    const dot = finalSegment.lastIndexOf(".");
+    if (dot < searchFrom || dot === finalSegment.length - 1) {
+        // Either no dot at all (dot === -1 < searchFrom), or the only dot is the
+        // leading one, or the dot is trailing (bare "foo." would be basename
+        // "foo." — but §3.5 disallows most weird chars anyway).
+        if (dot === -1 || dot < searchFrom) {
+            return { basename: finalSegment, extension: "" };
+        }
+        return { basename: finalSegment.slice(0, dot), extension: finalSegment.slice(dot) };
+    }
+    return { basename: finalSegment.slice(0, dot), extension: finalSegment.slice(dot) };
+}
+/**
+ * Insert a version-id suffix before the extension of the final path segment.
+ * Does NOT prepend the deletion sigil — that's `deletionPath`'s job.
+ */
+export function withVersionSuffix(path, versionIdString) {
+    const segments = path.split(PATH_SEPARATOR);
+    const last = segments[segments.length - 1] ?? "";
+    const { basename, extension } = splitExtension(last);
+    segments[segments.length - 1] = `${basename}-${versionIdString}${extension}`;
+    return segments.join(PATH_SEPARATOR);
+}
+/**
+ * The kernel-emitted path for a deletion move. `<systemSigil>` is the
+ * canonical (first-entry) system sigil from the effective path config
+ * (design §3.5.4 — set for input, first for output).
+ *
+ * Example:
+ *   deletionPath(":", "notes/foo.md", "v45129") = ":deleted/notes/foo-v45129.md"
+ */
+export function deletionPath(systemSigil, originalPath, versionIdString) {
+    return `${systemSigil}deleted/${withVersionSuffix(originalPath, versionIdString)}`;
+}
+/**
+ * Rough classifier used by `docs.delete` idempotency (§4.1 rule 4): true if
+ * ANY segment of the path starts with one of the accepted system sigils.
+ * (The design-wide primitive lives in validation.pathHasSigilSegment; this
+ * shim keeps the naming intent-facing at the call site.)
+ */
+export function pathIsInSystemNamespace(path, systemSigils) {
+    if (path === "")
+        return false;
+    const segments = path.split(PATH_SEPARATOR);
+    for (const segment of segments) {
+        for (const sigil of systemSigils) {
+            if (segment.startsWith(sigil))
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=deletion.js.map

package/dist/kernel/deletion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deletion.js","sourceRoot":"","sources":["../../src/kernel/deletion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,YAAoB;IAIjD,wEAAwE;IACxE,uCAAuC;IACvC,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,GAAG,GAAG,UAAU,IAAI,GAAG,KAAK,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,yEAAyE;QACzE,qEAAqE;QACrE,wDAAwD;QACxD,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,UAAU,EAAE,CAAC;YACnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IACtF,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,eAAuB;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,QAAQ,IAAI,eAAe,GAAG,SAAS,EAAE,CAAC;IAC7E,OAAO,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAmB,EACnB,YAAoB,EACpB,eAAuB;IAEvB,OAAO,GAAG,WAAW,WAAW,iBAAiB,CAAC,YAAY,EAAE,eAAe,CAAC,EAAE,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,YAA+B;IACnF,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/kernel/diff.d.ts

@@ -0,0 +1,36 @@
+/**
+ * docs.diff — the one v1 read primitive deferred from M3 (m4-plan WS5).
+ *
+ * Produces a unified diff over the byte-exact serialized documents (§3.2
+ * — one canonical representation via frontmatter.join). Both versions
+ * must belong to the same document at `(repo, path)`; otherwise the
+ * `version_not_in_document` error we reserved back in M1 finally fires.
+ *
+ * Read scope is checked on the lookup path AND both version paths
+ * (m4-plan §5 decision 10) — a doc renamed out of the caller's scope
+ * doesn't leak history through diff.
+ */
+import type { Storage } from "../storage/types.js";
+import { KernelError } from "./errors.js";
+export type UnifiedDiff = {
+    repo: string;
+    path: string;
+    from_version_id: string;
+    to_version_id: string;
+    patch: string;
+};
+export type DiffDeps = {
+    storage: Storage;
+    resolveReadRepo: (slug: string) => Promise<{
+        id: number;
+        slug: string;
+    }>;
+    authorizeReadPath: (repoSlug: string, path: string) => void;
+};
+export declare function runDiff(input: {
+    repo: string;
+    path: string;
+    from_version_id: string;
+    to_version_id: string;
+}, deps: DiffDeps): Promise<UnifiedDiff>;
+export { KernelError };

package/dist/kernel/diff.js

@@ -0,0 +1,61 @@
+/**
+ * docs.diff — the one v1 read primitive deferred from M3 (m4-plan WS5).
+ *
+ * Produces a unified diff over the byte-exact serialized documents (§3.2
+ * — one canonical representation via frontmatter.join). Both versions
+ * must belong to the same document at `(repo, path)`; otherwise the
+ * `version_not_in_document` error we reserved back in M1 finally fires.
+ *
+ * Read scope is checked on the lookup path AND both version paths
+ * (m4-plan §5 decision 10) — a doc renamed out of the caller's scope
+ * doesn't leak history through diff.
+ */
+import { createTwoFilesPatch } from "diff";
+import { join as joinFrontmatter } from "../markdown/frontmatter.js";
+import { KernelError, docNotFound, versionNotFound, versionNotInDocument } from "./errors.js";
+import { decodeVersionId } from "./version-id.js";
+export async function runDiff(input, deps) {
+    const repo = await deps.resolveReadRepo(input.repo);
+    deps.authorizeReadPath(repo.slug, input.path);
+    const current = await deps.storage.version_current(repo.id, input.path);
+    if (!current)
+        throw docNotFound(input.repo, input.path);
+    const documentId = current.document_id;
+    const from = await decodeAndFetch(deps.storage, input.from_version_id);
+    const to = await decodeAndFetch(deps.storage, input.to_version_id);
+    if (from.document_id !== documentId) {
+        throw versionNotInDocument(input.from_version_id, input.repo, input.path);
+    }
+    if (to.document_id !== documentId) {
+        throw versionNotInDocument(input.to_version_id, input.repo, input.path);
+    }
+    if (from.repo_id !== repo.id || to.repo_id !== repo.id) {
+        throw versionNotInDocument(input.from_version_id, input.repo, input.path);
+    }
+    deps.authorizeReadPath(repo.slug, from.path);
+    deps.authorizeReadPath(repo.slug, to.path);
+    const fromText = serializeVersion(from);
+    const toText = serializeVersion(to);
+    const patch = createTwoFilesPatch(`${from.path}@${input.from_version_id}`, `${to.path}@${input.to_version_id}`, fromText, toText);
+    return {
+        repo: input.repo,
+        path: input.path,
+        from_version_id: input.from_version_id,
+        to_version_id: input.to_version_id,
+        patch,
+    };
+}
+async function decodeAndFetch(storage, versionId) {
+    const id = decodeVersionId(versionId);
+    if (id === null)
+        throw versionNotFound(versionId);
+    const row = await storage.version_by_id(id);
+    if (!row)
+        throw versionNotFound(versionId);
+    return row;
+}
+function serializeVersion(v) {
+    return joinFrontmatter({ frontmatter_raw: v.frontmatter_raw, body: v.body });
+}
+export { KernelError };
+//# sourceMappingURL=diff.js.map

package/dist/kernel/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/kernel/diff.ts"],"names":[],"mappings":"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"}

package/dist/kernel/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 type KernelErrorCode = "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";
+export declare class KernelError<D = Record<string, unknown>> extends Error {
+    readonly code: KernelErrorCode;
+    readonly data: D;
+    constructor(code: KernelErrorCode, data: D, message?: string);
+}
+/**
+ * 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 declare const KERNEL_ERROR_CODES: ReadonlySet<KernelErrorCode>;
+/** Type guard — check whether an arbitrary string is a known catalog code. */
+export declare function isKernelErrorCode(code: string): code is KernelErrorCode;
+export declare const repoNotFound: (slug: string) => KernelError<{
+    slug: string;
+}>;
+export declare const docNotFound: (repo: string, path: string) => KernelError<{
+    repo: string;
+    path: string;
+}>;
+export declare const versionNotFound: (versionId: string) => KernelError<{
+    version_id: string;
+}>;
+export declare const versionNotInDocument: (versionId: string, repo: string, path: string) => KernelError<{
+    version_id: string;
+    repo: string;
+    path: string;
+}>;
+export declare const forbidden: () => KernelError<{}>;