mrplex 0.0.1

package/dist/kernel/history.js

@@ -0,0 +1,143 @@
+/**
+ * The `history` namespace (sync/history plan §3) — a top-level read surface
+ * keyed by position in the version log, spanning documents. `history.since` is
+ * the global change feed: it wraps `Storage.versions_since` (the gap-aware
+ * walk, §3.2) and enriches each settled row into a `VersionRef` — deriving
+ * `op` and resolving `prev_path` — so consumers never parse path sigils.
+ */
+import { decodeVersionId, encodeVersionId } from "./version-id.js";
+/** Default feed page size when a caller omits `limit` (§3.3). */
+export const HISTORY_SINCE_DEFAULT_LIMIT = 500;
+/** Default `history.index` page size when a caller omits `limit` (§3.4). */
+export const HISTORY_INDEX_DEFAULT_LIMIT = 1000;
+/**
+ * Safety-window duration (§3.2): a gap's successor visible longer than this is
+ * treated as settled (the hole is burned, cross it); younger means the hole may
+ * still be committing (truncate before it). ~30s dwarfs any real write-tx.
+ */
+export const HISTORY_SAFETY_WINDOW_MS = 30_000;
+/**
+ * Derive the operation a version row represents (§3.3): no prev → create; same
+ * path → update; a new path in the system namespace (a `:deleted/…` tombstone)
+ * → delete; any other new path → move.
+ */
+export function deriveOp(hasPrev, path, prevPath, isSystemPath) {
+    if (!hasPrev)
+        return "create";
+    if (prevPath === path)
+        return "update";
+    if (isSystemPath(path))
+        return "delete";
+    return "move";
+}
+/**
+ * The global change feed. Advances the cursor to the storage safe frontier
+ * regardless of how many refs survive the visibility filter, so a caller with
+ * narrow scope still makes progress rather than stalling on hidden rows.
+ */
+export async function runHistorySince(input, deps) {
+    // "" (or any unparseable cursor) means "from the beginning" → after_id 0.
+    const afterId = input.after_version === "" ? 0 : (decodeVersionId(input.after_version) ?? 0);
+    const { rows, next_id } = await deps.storage.versions_since({
+        after_id: afterId,
+        repo_id: input.repo_id,
+        limit: input.limit,
+        now_ms: input.now_ms,
+        window_ms: input.window_ms,
+    });
+    // Batch-resolve prev paths (both ends of moves/deletes) in one lookup.
+    const prevIds = rows.map((r) => r.prev_id).filter((id) => id !== null);
+    const prevPaths = prevIds.length > 0
+        ? await deps.storage.versions_paths_by_ids(prevIds)
+        : new Map();
+    const refs = [];
+    for (const row of rows) {
+        const prevPath = row.prev_id === null ? null : (prevPaths.get(row.prev_id) ?? null);
+        // Visibility: deliver when the caller can read either endpoint — a delete's
+        // tombstone path may be hidden while its prior path is readable, and vice
+        // versa. Absent scope (canRead always true) sees everything.
+        const visible = deps.canRead(row.repo_id, row.path) ||
+            (prevPath !== null && deps.canRead(row.repo_id, prevPath));
+        if (!visible)
+            continue;
+        refs.push(toRef(row, prevPath, deps));
+    }
+    const nextSince = next_id > afterId ? encodeVersionId(next_id) : input.after_version;
+    return { refs, next_since: nextSince };
+}
+/**
+ * Page the live set as of a safe head `R` (§3.4). On the first call (no
+ * `through_version`) the server captures `R = versions_safe_head(...)` and
+ * echoes it; subsequent pages pass it back. Keyset over current-version id in
+ * `(after, R]`, never offset — a document updated mid-pagination gets a new id
+ * > R, drops out of the remaining pages, and is delivered by
+ * `history.since(R)` afterward. System/hidden paths and out-of-scope rows are
+ * dropped here (the storage page is lightweight and unfiltered), so a raw page
+ * may yield fewer visible items than `limit`; we keep pulling storage pages
+ * until we fill `limit` or reach R.
+ */
+export async function runHistoryIndex(input, deps) {
+    const through = input.through_version !== undefined && input.through_version !== ""
+        ? (decodeVersionId(input.through_version) ?? 0)
+        : await deps.storage.versions_safe_head(input.now_ms, input.window_ms);
+    const throughVersion = encodeVersionId(through);
+    let afterId = input.after_version !== undefined && input.after_version !== ""
+        ? (decodeVersionId(input.after_version) ?? 0)
+        : 0;
+    const items = [];
+    let exhausted = false;
+    while (items.length < input.limit && !exhausted) {
+        const rows = await deps.storage.versions_live_index({
+            repo_id: input.repo_id,
+            through_id: through,
+            after_id: afterId,
+            // Over-fetch a little so heavy exclusion doesn't cause many round-trips.
+            limit: input.limit,
+        });
+        if (rows.length === 0) {
+            exhausted = true;
+            break;
+        }
+        for (const r of rows) {
+            afterId = r.id;
+            if (deps.isExcluded(r.path))
+                continue;
+            if (!deps.canRead(r.path))
+                continue;
+            items.push({
+                path: r.path,
+                version_id: encodeVersionId(r.id),
+                content_hash: r.content_hash ?? "",
+            });
+            if (items.length === input.limit)
+                break;
+        }
+        // A short storage page means we've reached R's boundary.
+        if (rows.length < input.limit)
+            exhausted = true;
+    }
+    // More live rows may remain ≤ R only if the page filled AND we haven't yet
+    // consumed up to R itself. Reaching R (afterId === through) means the keyset
+    // window is exhausted even when the visible page happened to fill exactly.
+    const hasMore = !exhausted && items.length === input.limit && afterId < through;
+    return {
+        items,
+        through_version: throughVersion,
+        ...(hasMore ? { next_after_version: encodeVersionId(afterId) } : {}),
+    };
+}
+function toRef(row, prevPath, deps) {
+    return {
+        version_id: encodeVersionId(row.id),
+        prev_version_id: row.prev_id === null ? null : encodeVersionId(row.prev_id),
+        repo: deps.repoSlug(row.repo_id),
+        path: row.path,
+        prev_path: prevPath,
+        // content_hash is always populated post-M1; pre-backfill rows (null) would
+        // read as an empty string, which a consumer treats as "unknown, fetch".
+        content_hash: row.content_hash ?? "",
+        op: deriveOp(row.prev_id !== null, row.path, prevPath, deps.isSystemPath),
+        created_at: row.created_at,
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/kernel/history.js.map

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

package/dist/kernel/kernel.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Kernel — the only place the read model, error catalog, and slug↔id
+ * translation live. Surfaces (CLI, MCP, REST) call these methods and never
+ * touch the storage layer directly.
+ *
+ * No-auth model (design §8, noauth plan): the kernel trusts every caller.
+ * Every op takes a uniform `ctx: CallContext` first parameter — a plain
+ * caller-supplied value, not a resolved identity. Writes stamp `ctx.author`
+ * (default "mrplex"); reads narrow visibility through `ctx.scope` when present.
+ *
+ * All kernel methods are async (m5-plan WS1). SQLite adapter is
+ * internally synchronous so calls resolve on the next microtask; the
+ * async signature is honesty about the Postgres adapter and the
+ * embedding hook.
+ */
+import { type LinkConfig, type LinkConfigOverride } from "../links/link-config.js";
+import type { Storage } from "../storage/types.js";
+import { type CallContext } from "./context.js";
+import { type UnifiedDiff } from "./diff.js";
+import { type FrontmatterInput } from "./frontmatter-input.js";
+import { type PathConfig, type PathConfigOverride } from "./path-config.js";
+import { type QuerySpec } from "./query/query.js";
+import type { DocGetManyResult, GraphResult, GraphSpec, HistoryIndexPage, HistorySincePage, PathWarning, QueryHit, Repo, Version } from "./wire.js";
+export type HistoryOptions = {
+    limit?: number;
+    before?: string;
+};
+export type SetPathConfigResult = {
+    repo: Repo;
+    warnings: PathWarning[];
+};
+export type LinksBackfillResult = {
+    documents: number;
+    edges: number;
+};
+/**
+ * Result of `repos.set_link_config`: the updated repo plus the re-extraction
+ * report. A config change makes the link index stale, so the op re-extracts
+ * the whole repo under the new config in the same call (§11.2 "Config change
+ * ⇒ re-extraction") — the returned `reindexed` counts document it.
+ */
+export type SetLinkConfigResult = {
+    repo: Repo;
+    reindexed: LinksBackfillResult;
+};
+/** A stale link on the wire — paths, never internal document ids. */
+export type StaleLinkWire = {
+    repo: string;
+    source_path: string;
+    ord: number;
+    written: string;
+    current: string;
+};
+export type RepairResult = {
+    dry_run: boolean;
+    repaired: {
+        path: string;
+        edges: number;
+    }[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+};
+/** Hard cap on named paths per `docs.get_many` call (after dedupe). */
+export declare const GET_MANY_MAX_PATHS = 50;
+export type Kernel = {
+    repos: {
+        list(ctx: CallContext, opts?: {
+            include_system?: boolean;
+        }): Promise<Repo[]>;
+        get(ctx: CallContext, slug: string): Promise<Repo>;
+        create(ctx: CallContext, slug: string): Promise<Repo>;
+        rename(ctx: CallContext, slug: string, new_slug: string): Promise<Repo>;
+        delete(ctx: CallContext, slug: string): Promise<Repo>;
+        set_path_config(ctx: CallContext, slug: string, config: PathConfigOverride | null): Promise<SetPathConfigResult>;
+        set_link_config(ctx: CallContext, slug: string, config: LinkConfigOverride | null): Promise<SetLinkConfigResult>;
+    };
+    docs: {
+        get(ctx: CallContext, repo: string, path: string): Promise<Version>;
+        get_many(ctx: CallContext, repo: string, paths: string[]): Promise<DocGetManyResult>;
+        get_version(ctx: CallContext, repo: string, version_id: string): Promise<Version>;
+        history(ctx: CallContext, repo: string, path: string, opts?: HistoryOptions): Promise<Version[]>;
+        diff(ctx: CallContext, repo: string, path: string, from_version_id: string, to_version_id: string): Promise<UnifiedDiff>;
+        create(ctx: CallContext, repo: string, path: string, input: FrontmatterInput & {
+            body: string;
+        }): Promise<Version>;
+        put(ctx: CallContext, repo: string, prev_version_id: string, path: string, input: Partial<FrontmatterInput> & {
+            body?: string;
+        }): Promise<Version>;
+        delete(ctx: CallContext, repo: string, prev_version_id: string): Promise<Version>;
+    };
+    links: {
+        /** Rebuild the link index for a repo (backfill / config-change). */
+        backfill(ctx: CallContext, repo: string): Promise<LinksBackfillResult>;
+        /** List live docs whose written link text is stale vs. the target's path. */
+        stale(ctx: CallContext, repo: string): Promise<StaleLinkWire[]>;
+        /** Rewrite stale link text as optimistic docs.put; dry_run plans only. */
+        repair(ctx: CallContext, repo: string, opts?: {
+            dry_run?: boolean;
+        }): Promise<RepairResult>;
+    };
+    query(ctx: CallContext, spec: QuerySpec): Promise<QueryHit[]>;
+    /** Neighborhood expansion over the links index (docs/graph-plan.md). */
+    graph(ctx: CallContext, spec: GraphSpec): Promise<GraphResult>;
+    /** Change-log read surface keyed by version-log position (sync/history §3). */
+    history: {
+        /** The global change feed — the longest gap-free run after the cursor. */
+        since(ctx: CallContext, input: HistorySinceQuery): Promise<HistorySincePage>;
+        /** Page the live set as of a safe head R (startup reconciliation). */
+        index(ctx: CallContext, input: HistoryIndexQuery): Promise<HistoryIndexPage>;
+        /** Scoped, document-spanning history walk — subsumes docs.history (§3.5). */
+        list(ctx: CallContext, input: HistoryListQuery): Promise<Version[]>;
+    };
+};
+/** Public input to `history.since` (§3.3). `repo` is an optional slug filter. */
+export type HistorySinceQuery = {
+    after_version: string;
+    repo?: string;
+    limit?: number;
+};
+/** Public input to `history.index` (§3.4). `repo` is required (per-repo scan). */
+export type HistoryIndexQuery = {
+    repo: string;
+    through_version?: string;
+    after_version?: string;
+    limit?: number;
+};
+/**
+ * Public input to `history.list` (§3.5). `path` is a glob (a single literal
+ * path is the old `docs.history`); omitted = the whole repo. `ever` includes
+ * documents that once matched (moved-away / deleted). `since`/`until` are
+ * opaque version-id bounds; `order` defaults to newest-first (presentation).
+ */
+export type HistoryListQuery = {
+    repo: string;
+    path?: string;
+    ever?: boolean;
+    since?: string;
+    until?: string;
+    order?: "asc" | "desc";
+    limit?: number;
+};
+export type KernelConfig = {
+    storage: Storage;
+    serverPathConfig?: PathConfig;
+    /** Server-level link-extraction config (§11.2). Defaults to hardcoded. */
+    serverLinkConfig?: LinkConfig;
+    /**
+     * M4 write-time hook: called with the new version's storage id after
+     * every committed create / put / delete. Awaited in-line so a throw
+     * from the enqueue path fails the kernel call. In practice the
+     * worker's backlog_enqueue is one cheap UPSERT and doesn't throw.
+     */
+    onVersionCommitted?: (version_id: number) => Promise<void> | void;
+    queryEmbed?: (semantic: string) => Promise<{
+        vector: number[];
+        model: string;
+        dim: number;
+    }>;
+};
+export declare function createKernel(config: KernelConfig | Storage): Kernel;