mrplex 0.0.1

package/dist/storage/types.d.ts

@@ -0,0 +1,448 @@
+/**
+ * Storage layer types — adapter-agnostic. Kernel operations run on top of these.
+ *
+ * Integer ids are internal (design §3.3) and never cross the wire — the kernel
+ * translates rows into Version envelopes with opaque `version_id` strings and
+ * slug-based references.
+ *
+ * All Storage methods are async. SQLite adapter methods complete
+ * synchronously and resolve on the next microtask; Postgres adapter
+ * methods await real I/O. The uniform signature keeps kernel code
+ * dialect-agnostic (design §7.2, m5-plan WS1).
+ */
+import type { SearchPlan } from "./search-plan.js";
+export type RepoRow = {
+    id: number;
+    slug: string;
+    path_config: string | null;
+    /** Per-repo link-extraction override JSON (§11.2). Null = inherit. */
+    link_config: string | null;
+    created_at: string;
+};
+export type DocumentRow = {
+    id: number;
+    repo_id: number;
+};
+export type FrontmatterJson = Record<string, unknown>;
+export type VersionRow = {
+    id: number;
+    document_id: number;
+    repo_id: number;
+    prev_id: number | null;
+    next_id: number | null;
+    path: string;
+    frontmatter_raw: string;
+    frontmatter: FrontmatterJson;
+    body: string;
+    author: string;
+    created_at: string;
+    /**
+     * SHA-256 (bare hex) of canonical content (sync/history plan §2). Derived and
+     * server-owned — computed in-tx by `version_insert`, never part of the insert
+     * input. Null only on pre-backfill rows written before migration 0002.
+     */
+    content_hash: string | null;
+};
+export type VersionInsertInput = {
+    document_id: number;
+    repo_id: number;
+    prev_id: number | null;
+    path: string;
+    frontmatter_raw: string;
+    frontmatter: FrontmatterJson;
+    body: string;
+    author: string;
+    created_at: string;
+};
+export type HistoryOptions = {
+    limit?: number;
+    before?: string;
+};
+/**
+ * Options for the scoped history walk (sync/history plan §3.5). A forward
+ * id-ordered walk over the versions of documents selected by a path glob,
+ * bounded by version-id cursors. `path_regexes` are anchored regex sources
+ * (the gitignore-glob compilation used everywhere); empty = every document in
+ * the repo. `ever: false` anchors on the *live* set (docs whose CURRENT path
+ * matches); `ever: true` includes any document that *ever* had a matching path
+ * (whole chains). `after_id`/`until_id` are version-id bounds (exclusive lower,
+ * inclusive upper). `order` picks id ascending (oldest-first) or descending.
+ */
+export type VersionsListOptions = {
+    repo_id: number;
+    path_regexes: readonly string[];
+    ever: boolean;
+    after_id?: number;
+    until_id?: number;
+    order: "asc" | "desc";
+    limit: number;
+};
+/**
+ * Options for the gap-aware forward feed walk (sync/history plan §3.2–3.3).
+ * `after_id` is the resume cursor (0 = from the beginning); `repo_id` filters
+ * the output without affecting gap detection (gaps are global). `now_ms` and
+ * `window_ms` drive the safety window — the adapter supplies wall-clock now;
+ * `window_ms` is the caller's tolerance for treating a gap's successor as
+ * "settled long enough that the hole is burned, not pending."
+ */
+export type VersionsSinceOptions = {
+    after_id: number;
+    repo_id?: number;
+    limit: number;
+    now_ms: number;
+    window_ms: number;
+};
+/**
+ * Result of `versions_since`: the settled rows in `(after_id, next_id]`
+ * (repo-filtered, ascending by id) and the resume cursor `next_id`. Every id
+ * ≤ `next_id` is final and gap-free; `next_id === after_id` means nothing is
+ * safe to deliver yet (caught up, or stalled at a hot gap — the client just
+ * polls again).
+ */
+export type VersionsSinceResult = {
+    rows: VersionRow[];
+    next_id: number;
+};
+/**
+ * Chunks (design §3.2, §5.3). One row per chunk of a version's body.
+ * `embedding` is null while the row is pending embedding (rare in
+ * practice — chunk rows are only inserted alongside their vectors).
+ * Content-hash dedup key is (model, text_hash). Embeddings are
+ * exchanged with the storage layer as Float32Array — the adapter owns
+ * the on-disk representation (byte layout is private to each engine).
+ */
+export type ChunkRow = {
+    version_id: number;
+    ix: number;
+    text: string;
+    text_hash: string;
+    model: string;
+    embedding: Float32Array | null;
+};
+export type ChunkUpsertInput = {
+    ix: number;
+    text: string;
+    text_hash: string;
+    model: string;
+    /**
+     * Query vector. Callers passing fresh vectors use `readonly number[]`
+     * (that's what the embed hook returns); callers reusing a dedup-hit
+     * vector pass the Float32Array they got back from chunks_by_hash so
+     * the adapter round-trips it without re-encoding.
+     */
+    embedding: readonly number[] | Float32Array;
+};
+export type VectorSearchHit = {
+    version_id: number;
+    chunk_ix: number;
+    score: number;
+};
+/**
+ * Links derived index (design §11.2). One row per outbound STATIC edge
+ * from a source document's CURRENT version, doc-keyed. The kernel extracts
+ * + resolves edges and hands the adapter the resolved shape below;
+ * extraction/resolution logic (markdown parsing, path normalization) lives
+ * in src/links, never in the storage layer.
+ */
+/**
+ * A resolved outbound edge, ready to persist. `target_id` is the bound
+ * document identity or null when dangling (the named path has no live
+ * document yet). `target_norm` is the folded, anchor-stripped resolution
+ * key used to rebind danglers case-insensitively (§3.5.1).
+ */
+export type LinkEdgeInput = {
+    ord: number;
+    field: string;
+    target_raw: string;
+    target_norm: string;
+    target_id: number | null;
+};
+/** A stored link edge row (read shape — backfill, links.stale, tests). */
+export type LinkRow = {
+    repo_id: number;
+    source_id: number;
+    ord: number;
+    field: string;
+    target_raw: string;
+    target_norm: string;
+    target_id: number | null;
+};
+/**
+ * A distinct resolved adjacency triple for the graph read surface
+ * (docs/graph-plan.md WS1). `ord`, `target_raw`, and `target_norm` never
+ * leave storage on this path: adjacency reads collapse multiple occurrences
+ * of the same `(source, target, field)` to one row (`SELECT DISTINCT`) and
+ * exclude dangling edges (`target_id IS NULL`). Both endpoints are document
+ * ids; the kernel maps them to paths and applies scope.
+ */
+export type AdjacentLink = {
+    source_id: number;
+    target_id: number;
+    field: string;
+};
+/**
+ * Embedding backlog (design §3.2, §5.3). One row per version awaiting
+ * (or having failed) embedding. `attempts` counts failed tries; a fresh
+ * enqueue resets `attempts` and `next_retry_at` so a superseding write
+ * doesn't inherit an old backoff.
+ */
+export type BacklogRow = {
+    version_id: number;
+    attempts: number;
+    last_error: string | null;
+    next_retry_at: string | null;
+};
+export type BacklogStatus = {
+    pending: number;
+    due: number;
+    failing: number;
+    oldest_next_retry_at: string | null;
+    recent_errors: readonly {
+        version_id: number;
+        last_error: string;
+    }[];
+    models: readonly {
+        model: string;
+        chunk_count: number;
+    }[];
+};
+export type Storage = {
+    close(): Promise<void>;
+    migrate(): Promise<void>;
+    /**
+     * Serializable transaction. Nested tx flattens into the outer via
+     * savepoints. Contract: never await foreign I/O inside `fn` — the
+     * tx holds locks and the adapter's REPEATABLE READ retry loop (PG)
+     * must be able to replay the whole body. Kernel tx bodies only call
+     * storage.
+     */
+    tx<T>(fn: () => Promise<T>): Promise<T>;
+    repos_list(): Promise<RepoRow[]>;
+    repos_create(input: {
+        slug: string;
+        created_at: string;
+    }): Promise<RepoRow>;
+    repos_rename(id: number, new_slug: string): Promise<RepoRow>;
+    repos_set_path_config(id: number, path_config: string | null): Promise<RepoRow>;
+    repos_set_link_config(id: number, link_config: string | null): Promise<RepoRow>;
+    repos_by_slug(slug: string): Promise<RepoRow | null>;
+    repos_by_id(id: number): Promise<RepoRow | null>;
+    documents_create(repo_id: number): Promise<DocumentRow>;
+    /**
+     * Insert a new version and advance the chain atomically (design §7.2.2 #1):
+     * new row goes in; `prev.next_id` is updated to the new row's id; both happen
+     * in one tx. The two partial unique indexes on `versions` enforce the
+     * "one current per document" and "one live per (repo, path)" invariants
+     * at the storage layer (design §7.2.2 #2).
+     */
+    version_insert(input: VersionInsertInput): Promise<VersionRow>;
+    version_by_id(id: number): Promise<VersionRow | null>;
+    version_current(repo_id: number, path: string): Promise<VersionRow | null>;
+    /**
+     * Current-version rows for a batch of live paths in `repo_id`. Lookup is by
+     * `path_norm` (same folding as `version_current`); paths with no live row are
+     * simply absent.
+     */
+    versions_current_by_paths(repo_id: number, paths: readonly string[]): Promise<VersionRow[]>;
+    version_history(document_id: number, opts?: HistoryOptions): Promise<VersionRow[]>;
+    /**
+     * Scoped, document-spanning history walk (sync/history plan §3.5). Selects
+     * documents by path glob (via `path_regexes`), then returns their version
+     * rows interleaved by id, bounded by `after_id`/`until_id` cursors. See
+     * `VersionsListOptions` for the `ever` (live vs. whole-corpus) distinction.
+     */
+    versions_list(opts: VersionsListOptions): Promise<VersionRow[]>;
+    /**
+     * The gap-aware forward feed walk (sync/history plan §3.2–3.3): the longest
+     * safe contiguous run of version rows after `opts.after_id`, filtered to
+     * `opts.repo_id` when given. Returns settled rows only (never crosses a hot
+     * gap) plus the resume cursor `next_id`. See `versions-since.ts` for the
+     * safety-window logic both adapters share.
+     */
+    versions_since(opts: VersionsSinceOptions): Promise<VersionsSinceResult>;
+    /**
+     * Batch id → path lookup (sync/history plan §3.3): the feed derives each
+     * ref's `prev_path` (both ends of a move/delete) from its `prev_id` without
+     * hydrating whole prev rows. Ids not present are simply absent from the map.
+     */
+    versions_paths_by_ids(ids: readonly number[]): Promise<Map<number, string>>;
+    /**
+     * The safe head `R` (sync/history plan §3.4): the raw version id the feed
+     * would hand out as `next_since` at the live tip — everything ≤ R is visible
+     * and final. Computed with the same safety-window machinery as the feed, but
+     * anchored at the tip rather than a cursor, so `history.index` scans through
+     * a settled boundary while `history.since(R)` covers the rest with no gaps.
+     * Returns 0 when the log is empty.
+     */
+    versions_safe_head(now_ms: number, window_ms: number): Promise<number>;
+    /**
+     * One keyset page of the live set for `history.index` (§3.4): live rows
+     * (`next_id IS NULL`) in `repo_id` whose current version id is in
+     * `(after_id, through_id]`, ascending by id, capped at `limit`. Lightweight
+     * tuples only — the kernel applies system/hidden exclusion and scope.
+     */
+    versions_live_index(opts: {
+        repo_id: number;
+        through_id: number;
+        after_id: number;
+        limit: number;
+    }): Promise<{
+        id: number;
+        path: string;
+        content_hash: string | null;
+    }[]>;
+    /**
+     * Content-hash backfill (sync/history plan §2.6). Fetch one batch of rows
+     * with `content_hash IS NULL` (id-ascending, id > `after_id`, capped at
+     * `limit`), optionally scoped to `repo_id`. Returns the raw fields the shared
+     * hash function needs; the kernel computes hashes and writes them via
+     * `versions_set_content_hash`. Keyset by id so batches don't re-scan.
+     */
+    versions_missing_content_hash(opts: {
+        repo_id?: number;
+        after_id: number;
+        limit: number;
+    }): Promise<{
+        id: number;
+        frontmatter_raw: string;
+        body: string;
+    }[]>;
+    /** Set `content_hash` for a batch of version ids (backfill writer, §2.6). */
+    versions_set_content_hash(updates: readonly {
+        id: number;
+        content_hash: string;
+    }[]): Promise<void>;
+    /**
+     * All currently-live versions in a repo (i.e. rows where next_id IS NULL).
+     * Used by `repos.set_path_config` to produce the advisory PathWarning[]
+     * scan (§3.5.3). Riding the partial-index on (repo_id, path) where
+     * next_id is null, so O(live-set) per repo.
+     */
+    versions_live_by_repo(repo_id: number): Promise<VersionRow[]>;
+    fts_index(version_id: number, body: string): Promise<void>;
+    /**
+     * Replace document `source_id`'s outbound edges wholesale (delete +
+     * insert) in one shot. `repo_id` scopes the rows (links are repo-local).
+     * Called on every create/put that advances the doc's current version.
+     * Passing an empty `edges` clears the doc's outbound rows.
+     */
+    links_replace(repo_id: number, source_id: number, edges: readonly LinkEdgeInput[]): Promise<void>;
+    /** Clear a document's outbound edges (on delete). Inbound rows stay put. */
+    links_clear(source_id: number): Promise<void>;
+    /**
+     * Bind dangling edges in `repo_id` whose folded target matches
+     * `target_norm` to `document_id`. Called when a document appears at a
+     * path (create / move-in / restore) so waiting danglers resolve — the
+     * identity-bound counterpart to "backlinks survive renames" (§11.2).
+     * Bind-only: already-bound edges are never touched, and edges are never
+     * unbound (a move produces zero inbound churn; a delete leaves inbound
+     * rows bound and lets visibility filtering hide them — §11.2). A source's
+     * edge is never bound to the source itself (self-links are noise and are
+     * excluded, `source_id <> document_id`). Returns the number of edges
+     * newly bound.
+     */
+    links_resolve_dangling(repo_id: number, target_norm: string, document_id: number): Promise<number>;
+    /** A document's outbound edges (backfill, links.stale, tests). */
+    links_by_source(source_id: number): Promise<LinkRow[]>;
+    /** Every link row in a repo, ordered by (source_id, ord) (tests, verify). */
+    links_by_repo(repo_id: number): Promise<LinkRow[]>;
+    /**
+     * Outbound adjacency for a batch of source documents: distinct
+     * `(source_id, target_id, field)` triples where `source_id` is in the
+     * batch. Dangling edges (`target_id IS NULL`) are excluded in SQL. Used by
+     * the graph read surface (docs/graph-plan.md WS1); the kernel applies
+     * scope/filter visibility to the endpoints. `ord` never leaves storage.
+     */
+    links_adjacent_out(repo_id: number, source_ids: readonly number[]): Promise<AdjacentLink[]>;
+    /**
+     * Inbound adjacency for a batch of target documents: distinct
+     * `(source_id, target_id, field)` triples where `target_id` is in the
+     * batch (resolved edges only). The counterpart to links_adjacent_out.
+     */
+    links_adjacent_in(repo_id: number, target_ids: readonly number[]): Promise<AdjacentLink[]>;
+    /**
+     * Current-version rows for a batch of document ids (graph read surface).
+     * Only live rows (`next_id IS NULL`) in `repo_id`; ids not currently live
+     * are simply absent. The kernel needs the paths + frontmatter to project
+     * documents and to apply scope to graph endpoints.
+     */
+    versions_current_by_documents(repo_id: number, document_ids: readonly number[]): Promise<VersionRow[]>;
+    /**
+     * Document ids of live versions in `repo_id` whose path matches ANY of the
+     * given anchored regex sources (`^…$`, the gitignore-glob compilation used
+     * everywhere). Path matching happens in SQL (SQLite `regexp()` UDF, Postgres
+     * `~`) so the graph root-resolution path never materializes the whole repo.
+     * An empty `path_regexes` returns [].
+     */
+    versions_live_document_ids_matching(repo_id: number, path_regexes: readonly string[]): Promise<number[]>;
+    /**
+     * Composed query — the kernel orchestrator (§5) hands over a structured
+     * `SearchPlan` (repo ids + parsed CEL AST + scope regex sources + sigil
+     * exclusions + optional text + candidate whitelist + limit); the adapter
+     * compiles the plan into engine-specific SQL. Ordering per §5.1:
+     * text-score if `text` is present, else `$created_at DESC`.
+     *
+     * m5-plan WS2 pushed compilation behind the adapter so the kernel emits
+     * no SQL strings.
+     */
+    versions_search(plan: SearchPlan): Promise<VersionRow[]>;
+    /**
+     * Chunks + vectors (design §3.2, §5.3, §7.2.2). Written by the
+     * backlog worker; read by kernel.query's `semantic` branch.
+     *
+     * `chunks_upsert` replaces all chunks for `version_id` in one tx.
+     * All vectors in the input must share `model` and the same
+     * dimensionality; the adapter refuses mixed-dim writes (m4-plan §1,
+     * §5.3 "refuse mixed-dim writes to the chunks table").
+     */
+    chunks_upsert(version_id: number, model: string, chunks: readonly ChunkUpsertInput[]): Promise<void>;
+    /**
+     * Content-hash dedup lookup (§5.3). Returns one row per hash present
+     * in the input list for the given model, with its stored vector so
+     * the worker can reuse it without calling the hook.
+     */
+    chunks_by_hash(model: string, text_hashes: readonly string[]): Promise<{
+        text_hash: string;
+        embedding: Float32Array;
+    }[]>;
+    chunks_by_version(version_id: number): Promise<ChunkRow[]>;
+    /**
+     * Distinct (model, chunk_count) pairs across the chunks table — for
+     * `embed status`. `chunk_count` counts rows, not distinct hashes.
+     */
+    chunks_model_summary(): Promise<{
+        model: string;
+        chunk_count: number;
+    }[]>;
+    /**
+     * Brute-force k-NN over current-version chunks with vectors matching
+     * `model`. §7.2.1 pins v1 at brute-force — indexed ANN (HNSW/IVFFlat
+     * for pgvector) is a fast-follow.
+     *
+     * `k` limits distinct-version results, not chunk hits. The adapter
+     * owns the version-collapse (best chunk per version) AND the vector
+     * serialization (float32 vs float64, LE vs BE, etc.). Kernel callers
+     * pass a plain JS number array — no dialect-specific encoding leaks
+     * into the query layer.
+     */
+    vector_search(repo_ids: readonly number[], model: string, embedding: readonly number[], k: number): Promise<VectorSearchHit[]>;
+    backlog_enqueue(version_id: number): Promise<void>;
+    /** Rows due now (next_retry_at IS NULL or <= now), oldest first. */
+    backlog_dequeue(now: string, limit: number): Promise<BacklogRow[]>;
+    backlog_retain(input: {
+        version_id: number;
+        attempts: number;
+        last_error: string;
+        next_retry_at: string;
+    }): Promise<void>;
+    backlog_delete(version_id: number): Promise<void>;
+    backlog_status(now: string): Promise<BacklogStatus>;
+};
+export type OpenConfig = {
+    /** Database url — sqlite:./path.db or postgres://… */
+    database: string;
+};
+export type StorageAdapter = {
+    scheme: string;
+    open(config: OpenConfig): Promise<Storage>;
+};

package/dist/storage/types.js

@@ -0,0 +1,14 @@
+/**
+ * Storage layer types — adapter-agnostic. Kernel operations run on top of these.
+ *
+ * Integer ids are internal (design §3.3) and never cross the wire — the kernel
+ * translates rows into Version envelopes with opaque `version_id` strings and
+ * slug-based references.
+ *
+ * All Storage methods are async. SQLite adapter methods complete
+ * synchronously and resolve on the next microtask; Postgres adapter
+ * methods await real I/O. The uniform signature keeps kernel code
+ * dialect-agnostic (design §7.2, m5-plan WS1).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/storage/versions-since.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The gap-aware forward walk — the brain of the change feed (sync/history
+ * plan §3.2). Pure logic shared by both storage adapters so SQLite and
+ * Postgres compute an identical safe frontier.
+ *
+ * `versions.id` is an exact cursor iff writes are serialized. Always true on
+ * SQLite (single writer). On Postgres, concurrent writers create
+ * commit-visibility skew and `nextval` burns ids on rollback, so gaps are
+ * routine — each is either *pending* (in-flight, will appear) or *burned*
+ * (never will), indistinguishable except by age.
+ *
+ * The feed therefore returns the longest safe contiguous run after the cursor,
+ * not "everything since." Gap rule, keyed on the **successor's** age: if id 100
+ * is missing and its successor 101 has been visible longer than the window,
+ * 100 is burned → cross it; if 101 is younger than the window, 100 may be a
+ * sibling still committing → truncate the page before 101. The page ends at
+ * the first hot gap, the scan boundary (treated as a safe tip), or the output
+ * limit — whichever comes first.
+ *
+ * Gaps are only meaningful on the **global** id sequence: a repo filter
+ * naturally skips ids taken by other repos, so the walk runs over global rows
+ * (id + repo + age) and the repo filter is applied to the output only.
+ */
+/**
+ * Upper bound on the lightweight global scan per poll. Large enough that a
+ * repo-filtered `limit` page is almost always satisfied in one scan, bounded
+ * so a cold `after_id=0` poll over a huge log stays cheap. Truncating the scan
+ * never crosses a gap — it only under-delivers, and the next poll continues
+ * from the returned cursor.
+ */
+export declare const GLOBAL_SCAN_CAP = 10000;
+/**
+ * How many recent rows to inspect when computing the safe head `R`. Only the
+ * newest rows can hold an unsettled (hot) gap — anything older than the safety
+ * window is burned-and-settled — so a small tail suffices regardless of log
+ * size. Comfortably exceeds any plausible in-flight concurrent-write count.
+ */
+export declare const SAFE_HEAD_TAIL = 1000;
+/** A lightweight row for the frontier walk — no body/frontmatter needed. */
+export type FrontierRow = {
+    id: number;
+    repo_id: number;
+    created_at_ms: number;
+};
+export type FrontierResult = {
+    /**
+     * Inclusive upper-bound id for the page: every id in `(after_id, upper_id]`
+     * is settled and final. Also the resume cursor (`next_since`). Equals
+     * `after_id` when nothing is safe to deliver yet, so a caught-up or
+     * hot-gap-stalled poll simply doesn't advance.
+     */
+    upper_id: number;
+};
+/**
+ * Walk `light` (global rows with id > after_id, ascending) and return the
+ * inclusive `upper_id` through which the feed is gap-free. Rows matching
+ * `repo_id` (or all rows when it is undefined) are counted toward `limit`; the
+ * page caps at the id of the `limit`-th match when a further match exists
+ * within the safe region, otherwise at the safe frontier so an empty tail is
+ * skipped and the cursor keeps advancing.
+ */
+export declare function safeFrontier(light: readonly FrontierRow[], after_id: number, repo_id: number | undefined, limit: number, now_ms: number, window_ms: number): FrontierResult;
+/**
+ * The safe head `R` (§3.4) from a bounded tail of recent rows. `tail` is the
+ * last rows by id, ascending (id + age; repo irrelevant here). We anchor the
+ * walk at `tail[0].id - 1` so the tail's first row isn't mistaken for a leading
+ * gap: everything below the tail is older than any realistic safety window, so
+ * its gaps are burned and already settled. Within the tail, the walk crosses
+ * burned gaps and stops before the first hot one — exactly the id the feed
+ * would hand out as `next_since` at the tip. Empty tail → 0.
+ */
+export declare function safeHeadFromTail(tail: readonly FrontierRow[], now_ms: number, window_ms: number): number;

package/dist/storage/versions-since.js

@@ -0,0 +1,92 @@
+/**
+ * The gap-aware forward walk — the brain of the change feed (sync/history
+ * plan §3.2). Pure logic shared by both storage adapters so SQLite and
+ * Postgres compute an identical safe frontier.
+ *
+ * `versions.id` is an exact cursor iff writes are serialized. Always true on
+ * SQLite (single writer). On Postgres, concurrent writers create
+ * commit-visibility skew and `nextval` burns ids on rollback, so gaps are
+ * routine — each is either *pending* (in-flight, will appear) or *burned*
+ * (never will), indistinguishable except by age.
+ *
+ * The feed therefore returns the longest safe contiguous run after the cursor,
+ * not "everything since." Gap rule, keyed on the **successor's** age: if id 100
+ * is missing and its successor 101 has been visible longer than the window,
+ * 100 is burned → cross it; if 101 is younger than the window, 100 may be a
+ * sibling still committing → truncate the page before 101. The page ends at
+ * the first hot gap, the scan boundary (treated as a safe tip), or the output
+ * limit — whichever comes first.
+ *
+ * Gaps are only meaningful on the **global** id sequence: a repo filter
+ * naturally skips ids taken by other repos, so the walk runs over global rows
+ * (id + repo + age) and the repo filter is applied to the output only.
+ */
+/**
+ * Upper bound on the lightweight global scan per poll. Large enough that a
+ * repo-filtered `limit` page is almost always satisfied in one scan, bounded
+ * so a cold `after_id=0` poll over a huge log stays cheap. Truncating the scan
+ * never crosses a gap — it only under-delivers, and the next poll continues
+ * from the returned cursor.
+ */
+export const GLOBAL_SCAN_CAP = 10000;
+/**
+ * How many recent rows to inspect when computing the safe head `R`. Only the
+ * newest rows can hold an unsettled (hot) gap — anything older than the safety
+ * window is burned-and-settled — so a small tail suffices regardless of log
+ * size. Comfortably exceeds any plausible in-flight concurrent-write count.
+ */
+export const SAFE_HEAD_TAIL = 1000;
+/**
+ * Walk `light` (global rows with id > after_id, ascending) and return the
+ * inclusive `upper_id` through which the feed is gap-free. Rows matching
+ * `repo_id` (or all rows when it is undefined) are counted toward `limit`; the
+ * page caps at the id of the `limit`-th match when a further match exists
+ * within the safe region, otherwise at the safe frontier so an empty tail is
+ * skipped and the cursor keeps advancing.
+ */
+export function safeFrontier(light, after_id, repo_id, limit, now_ms, window_ms) {
+    let expected = after_id + 1;
+    let frontier = after_id; // last globally-contiguous, settled id
+    let cutoff = after_id; // id of the last matching row we admit
+    let matched = 0;
+    let capped = false;
+    for (const r of light) {
+        if (r.id > expected) {
+            // A gap precedes r; r is the successor. Young successor → the missing
+            // ids may still be committing → stop before r (hot gap). Old successor
+            // → the gap is burned → cross it.
+            if (now_ms - r.created_at_ms < window_ms)
+                break;
+        }
+        const matches = repo_id === undefined || r.repo_id === repo_id;
+        if (matches && matched === limit) {
+            // A (limit+1)-th deliverable row sits within the safe region: cap the
+            // page at the limit-th match so the client fetches the rest next poll.
+            capped = true;
+            break;
+        }
+        frontier = r.id;
+        expected = r.id + 1;
+        if (matches) {
+            matched++;
+            cutoff = r.id;
+        }
+    }
+    return { upper_id: capped ? cutoff : frontier };
+}
+/**
+ * The safe head `R` (§3.4) from a bounded tail of recent rows. `tail` is the
+ * last rows by id, ascending (id + age; repo irrelevant here). We anchor the
+ * walk at `tail[0].id - 1` so the tail's first row isn't mistaken for a leading
+ * gap: everything below the tail is older than any realistic safety window, so
+ * its gaps are burned and already settled. Within the tail, the walk crosses
+ * burned gaps and stops before the first hot one — exactly the id the feed
+ * would hand out as `next_since` at the tip. Empty tail → 0.
+ */
+export function safeHeadFromTail(tail, now_ms, window_ms) {
+    if (tail.length === 0)
+        return 0;
+    const anchor = tail[0].id - 1;
+    return safeFrontier(tail, anchor, undefined, tail.length, now_ms, window_ms).upper_id;
+}
+//# sourceMappingURL=versions-since.js.map

package/dist/storage/versions-since.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions-since.js","sourceRoot":"","sources":["../../src/storage/versions-since.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAmBnC;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,KAA6B,EAC7B,QAAgB,EAChB,OAA2B,EAC3B,KAAa,EACb,MAAc,EACd,SAAiB;IAEjB,IAAI,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC5B,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC,uCAAuC;IAChE,IAAI,MAAM,GAAG,QAAQ,CAAC,CAAC,uCAAuC;IAC9D,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC;YACpB,sEAAsE;YACtE,uEAAuE;YACvE,kCAAkC;YAClC,IAAI,MAAM,GAAG,CAAC,CAAC,aAAa,GAAG,SAAS;gBAAE,MAAM;QAClD,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC;QAC/D,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YACjC,sEAAsE;YACtE,uEAAuE;YACvE,MAAM,GAAG,IAAI,CAAC;YACd,MAAM;QACR,CAAC;QACD,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;QAChB,QAAQ,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACpB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;YACV,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAA4B,EAC5B,MAAc,EACd,SAAiB;IAEjB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,GAAI,IAAI,CAAC,CAAC,CAAiB,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/C,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC;AACxF,CAAC"}

package/dist/storage-postgres/adapter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Postgres adapter (m5-plan WS4).
+ *
+ * Contract:
+ *   - Kernel calls are async; storage owns SQL emission.
+ *   - `tx()` wraps `begin isolation level repeatable read` and reuses the
+ *     same PoolClient inside via AsyncLocalStorage. Nested tx uses
+ *     savepoints. On 40001/40P01 the whole tx body retries with jittered
+ *     backoff up to 3 times.
+ *   - int8 parser: PG returns bigints as strings by default; a custom
+ *     parser converts them to JS numbers with a SafeInteger guard so id
+ *     drift is loud, not silent.
+ *   - Vectors serialize as pgvector's `'[…]'` literal; on read they
+ *     arrive as a string and parse back to Float32Array.
+ */
+import type { StorageAdapter } from "../storage/types.js";
+export declare const postgresAdapter: StorageAdapter;