@omgbase/core 0.1.0

package/dist/src/core/store/writers.js

@@ -0,0 +1,89 @@
+import { sha256, serializeTreeEntries } from "../hash.js";
+import { mintId } from "../ids.js";
+/** Assign fresh minted ids to a parsed block tree (Stage-1 re-mint path). */
+export function assignIds(blocks) {
+    return blocks.map((b) => ({
+        blockId: mintId("b"),
+        type: b.type,
+        raw: b.raw,
+        trivia: b.trivia,
+        attrs: b.attrs,
+        children: assignIds(b.children),
+    }));
+}
+/** Content-address raw text into blobs; returns hex hash. Dedups. */
+export function putBlob(db, text) {
+    const bytes = Buffer.from(text, "utf8");
+    const hash = sha256(bytes);
+    db.prepare("INSERT OR IGNORE INTO blobs (hash, bytes, size) VALUES (?, ?, ?)").run(hash, bytes, bytes.length);
+    return hash.toString("hex");
+}
+/** Content-address a tree node's entries; returns hex hash. Dedups. */
+export function putTreeNode(db, entries) {
+    const serialized = serializeTreeEntries(entries);
+    const hash = sha256(serialized);
+    db.prepare("INSERT OR IGNORE INTO tree_nodes (hash, entries) VALUES (?, ?)").run(hash, serialized);
+    return hash.toString("hex");
+}
+/**
+ * Encode a list of sibling blocks into a Merkle tree node bottom-up, writing
+ * blobs (raw + trivia) and child tree nodes. Returns the node's hex hash.
+ * Structural sharing: unchanged subtrees produce identical hashes and are not
+ * re-inserted.
+ */
+export function writeBlockTree(db, blocks) {
+    const entries = blocks.map((b) => {
+        const rawHashHex = putBlob(db, b.raw);
+        const triviaHashHex = b.trivia.length > 0 ? putBlob(db, b.trivia) : null;
+        const childTreeHashHex = b.children.length > 0 ? writeBlockTree(db, b.children) : null;
+        return {
+            blockId: b.blockId,
+            rawHashHex,
+            childTreeHashHex,
+            type: b.type,
+            attrs: b.attrs,
+            triviaHashHex,
+        };
+    });
+    return putTreeNode(db, entries);
+}
+/** Append a commit; assigns the per-repo total-order seq. */
+export function newCommit(db, input) {
+    const commitId = mintId("c");
+    const row = db
+        .prepare("SELECT COALESCE(MAX(seq),0)+1 AS seq FROM commits WHERE repo_id = ?")
+        .get(input.repoId);
+    db.prepare(`INSERT INTO commits (commit_id, repo_id, seq, ts, origin, actor, reason, checkpoint_id, ops)
+     VALUES (@commitId, @repoId, @seq, @ts, @origin, @actor, @reason, @checkpointId, @ops)`).run({
+        commitId,
+        repoId: input.repoId,
+        seq: row.seq,
+        ts: input.ts,
+        origin: input.origin,
+        actor: input.actor ?? null,
+        reason: input.reason ?? null,
+        checkpointId: input.checkpointId ?? null,
+        ops: input.ops ?? null,
+    });
+    return { commitId, seq: row.seq };
+}
+/** Append a revision; assigns the per-document monotonic seq. */
+export function writeRevision(db, input) {
+    const revId = mintId("r");
+    const row = db
+        .prepare("SELECT COALESCE(MAX(seq),0)+1 AS seq FROM revisions WHERE doc_id = ?")
+        .get(input.docId);
+    db.prepare(`INSERT INTO revisions (rev_id, doc_id, seq, root_tree, frontmatter_blob, rendered_hash, path, commit_id)
+     VALUES (@revId, @docId, @seq, @rootTree, @frontmatterBlob, @renderedHash, @path, @commitId)`).run({
+        revId,
+        docId: input.docId,
+        seq: row.seq,
+        rootTree: Buffer.from(input.rootTreeHex, "hex"),
+        frontmatterBlob: input.frontmatterBlobHex ? Buffer.from(input.frontmatterBlobHex, "hex") : null,
+        renderedHash: input.renderedHash,
+        path: input.path,
+        commitId: input.commitId,
+    });
+    return { revId, seq: row.seq };
+}
+//# sourceMappingURL=writers.js.map

package/dist/src/core/vec.d.ts

@@ -0,0 +1,10 @@
+/** Cosine similarity of two equal-length embedding vectors. 0 when either is a
+ * zero vector (undefined direction) — the neutral, non-matching score. */
+export declare function cosineFloat32(a: Float32Array, b: Float32Array): number;
+/** Reinterpret a stored/bound BLOB as a Float32 vector (a zero-copy view). */
+export declare function blobToFloat32(buf: Uint8Array): Float32Array;
+/** A Buffer view over a Float32 vector's bytes, for binding as a SQL BLOB. */
+export declare function float32ToBlob(vec: Float32Array): Buffer;
+/** Cosine over two BLOBs (the `cosine` UDF body). NULL-safe: a missing operand
+ * (no embedding row) yields NULL so the score is absent, not a spurious 0. */
+export declare function cosineBytes(a: Uint8Array | null, b: Uint8Array | null): number | null;

package/dist/src/core/vec.js

@@ -0,0 +1,33 @@
+// Vector math shared by the brute-force semantic search (search/vector.ts) and
+// the `cosine` SQLite UDF (store.ts) that OQX's `semantic()` scalar compiles to.
+// Embedding vectors are stored/bound as little-endian Float32 BLOBs.
+/** Cosine similarity of two equal-length embedding vectors. 0 when either is a
+ * zero vector (undefined direction) — the neutral, non-matching score. */
+export function cosineFloat32(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** Reinterpret a stored/bound BLOB as a Float32 vector (a zero-copy view). */
+export function blobToFloat32(buf) {
+    return new Float32Array(buf.buffer, buf.byteOffset, Math.floor(buf.byteLength / 4));
+}
+/** A Buffer view over a Float32 vector's bytes, for binding as a SQL BLOB. */
+export function float32ToBlob(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/** Cosine over two BLOBs (the `cosine` UDF body). NULL-safe: a missing operand
+ * (no embedding row) yields NULL so the score is absent, not a spurious 0. */
+export function cosineBytes(a, b) {
+    if (!a || !b)
+        return null;
+    return cosineFloat32(blobToFloat32(a), blobToFloat32(b));
+}
+//# sourceMappingURL=vec.js.map

package/dist/src/format/adapter.d.ts

@@ -0,0 +1,97 @@
+import type { BlockTree, RawBlock, ExtractedLink } from "../core/parse/types.js";
+export declare const enum AdapterCapability {
+    Parse = "parse",
+    Render = "render",
+    ExtractEdges = "extract_edges",
+    ProjectNodes = "project_nodes",
+    ExtractMetadata = "extract_metadata",
+    ComputeProperties = "compute_properties",
+    StructuralMutation = "structural_mutation",
+    SemanticChunking = "semantic_chunking"
+}
+export interface ProjectedNode {
+    kind: string;
+    name?: string | undefined;
+    value?: string | undefined;
+    blockId: string;
+    spanStart?: number | undefined;
+    spanEnd?: number | undefined;
+    attrs?: Record<string, unknown> | undefined;
+}
+export interface EmbeddingChunk {
+    blockId: string;
+    text: string;
+    context?: string;
+}
+/** The block-scoped context an editable node property is rewritten against. */
+export interface NodeEditContext {
+    /** The block's current raw bytes (what the edit rewrites). */
+    blockRaw: string;
+    /** The node's byte span within blockRaw (null when unrecorded — see spans). */
+    span: {
+        start: number;
+        end: number;
+    } | null;
+    /** The node's current name/value/attrs, for editors that need them. */
+    node: {
+        kind: string;
+        name?: string | undefined;
+        value?: string | undefined;
+        attrs: Record<string, unknown>;
+    };
+}
+/**
+ * The result of a node-property edit: how it maps onto a block `update` op.
+ * `markdown` replaces the block's bytes; `attrs` sets typed block attributes
+ * (e.g. a task's `checked`). Editors return exactly one.
+ */
+export type NodeEditResult = {
+    markdown: string;
+} | {
+    attrs: Record<string, unknown>;
+};
+/** Rewrite one editable property of a node into a block update (node-editability). */
+export type NodeEditor = (ctx: NodeEditContext, newValue: string) => NodeEditResult;
+/**
+ * Per-node-kind editable properties (node-editability). An adapter declares, for
+ * a node kind, which properties can be set and how each compiles down to a block
+ * `update` — so a caller edits a link's text or a task's checkbox surgically
+ * while the write still goes through the block. Nodes stay read-only projections;
+ * this is the affordance layer, not a second source of truth.
+ */
+export type NodeEditors = Record<string, Record<string, NodeEditor>>;
+export interface ReconcileHints {
+    anchorEvidenceKeys?: string[];
+    smallBlockTokens?: number;
+}
+export interface AdapterEdge {
+    srcBlock: string | null;
+    srcField: string | null;
+    predicate: string;
+    dstKind: "document" | "block" | "external" | "collection";
+    target: string;
+    anchor: string | null;
+    provenance: string;
+}
+export interface FormatAdapter {
+    readonly format: string;
+    readonly extensions: string[];
+    readonly capabilities: ReadonlySet<AdapterCapability>;
+    parse(source: string): BlockTree;
+    render?(tree: BlockTree): string;
+    extractEdges?(blocks: RawBlock[], metadata?: Record<string, unknown>): AdapterEdge[];
+    projectNodes?(blocks: RawBlock[]): ProjectedNode[];
+    extractMetadata?(source: string): Record<string, unknown> | null;
+    /**
+     * Computed properties (properties-table §4): engine-derived facts surfaced
+     * as `$`-intrinsics ($title, $tags, ...), distinct from authored frontmatter/
+     * inline keys. Each entry is a $-prefixed key mapped to a scalar or a list of
+     * scalars. Stored as source='computed' property rows.
+     */
+    computeProperties?(blocks: RawBlock[], metadata: Record<string, unknown>): Record<string, unknown>;
+    reconcileHints?(): ReconcileHints;
+    chunkForEmbedding?(blocks: RawBlock[]): EmbeddingChunk[];
+    /** Editable node properties, keyed by node kind then property (node-editability). */
+    nodeEditors?: NodeEditors;
+}
+export type { BlockTree, RawBlock, ExtractedLink };

package/dist/src/format/adapter.js

@@ -0,0 +1,14 @@
+// Format adapter contract. Each format (markdown, yaml, json, …) implements
+// this interface to participate in the omgbase versioned block graph.
+export var AdapterCapability;
+(function (AdapterCapability) {
+    AdapterCapability["Parse"] = "parse";
+    AdapterCapability["Render"] = "render";
+    AdapterCapability["ExtractEdges"] = "extract_edges";
+    AdapterCapability["ProjectNodes"] = "project_nodes";
+    AdapterCapability["ExtractMetadata"] = "extract_metadata";
+    AdapterCapability["ComputeProperties"] = "compute_properties";
+    AdapterCapability["StructuralMutation"] = "structural_mutation";
+    AdapterCapability["SemanticChunking"] = "semantic_chunking";
+})(AdapterCapability || (AdapterCapability = {}));
+//# sourceMappingURL=adapter.js.map

package/dist/src/format/index.d.ts

@@ -0,0 +1,6 @@
+export type { FormatAdapter, AdapterEdge, ProjectedNode, EmbeddingChunk, ReconcileHints, } from "./adapter.js";
+export { AdapterCapability } from "./adapter.js";
+export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat, } from "./registry.js";
+export { markdownAdapter, MARKDOWN_FORMAT } from "./markdown.js";
+export { yamlAdapter, YAML_FORMAT } from "./yaml.js";
+export { jsonAdapter, JSON_FORMAT } from "./json.js";

package/dist/src/format/index.js

@@ -0,0 +1,15 @@
+// Format adapter system. Importing this module registers the built-in adapters.
+export { AdapterCapability } from "./adapter.js";
+export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat, } from "./registry.js";
+export { markdownAdapter, MARKDOWN_FORMAT } from "./markdown.js";
+export { yamlAdapter, YAML_FORMAT } from "./yaml.js";
+export { jsonAdapter, JSON_FORMAT } from "./json.js";
+// Register built-in adapters.
+import { registerAdapter } from "./registry.js";
+import { markdownAdapter } from "./markdown.js";
+import { yamlAdapter } from "./yaml.js";
+import { jsonAdapter } from "./json.js";
+registerAdapter(markdownAdapter);
+registerAdapter(yamlAdapter);
+registerAdapter(jsonAdapter);
+//# sourceMappingURL=index.js.map

package/dist/src/format/json.d.ts

@@ -0,0 +1,3 @@
+import { type FormatAdapter } from "./adapter.js";
+export declare const JSON_FORMAT = "json";
+export declare const jsonAdapter: FormatAdapter;

package/dist/src/format/json.js

@@ -0,0 +1,324 @@
+// JSON format adapter. Decomposes JSON files into blocks with json:-prefixed
+// kinds, extracts $ref/$schema edges, and projects the root object as metadata.
+// Read-only: no StructuralMutation (JSON formatting is not reliably preserved).
+import { AdapterCapability } from "./adapter.js";
+import { normalizeText } from "../core/hash.js";
+export const JSON_FORMAT = "json";
+const K = {
+    object: "json:object",
+    property: "json:property",
+    array: "json:array",
+    item: "json:item",
+    scalar: "json:scalar",
+};
+function span(start, end) {
+    return { start, end };
+}
+function emptyBlock(kind, s, raw) {
+    return {
+        type: kind,
+        span: s,
+        raw,
+        text: normalizeText(raw),
+        attrs: {},
+        children: [],
+        trivia: "",
+        anchors: [],
+        outLinks: [],
+    };
+}
+function parseJsonStructure(source) {
+    let pos = 0;
+    function skipWhitespace() {
+        while (pos < source.length && /\s/.test(source[pos]))
+            pos++;
+    }
+    function parseValue() {
+        skipWhitespace();
+        if (pos >= source.length)
+            return null;
+        const ch = source[pos];
+        if (ch === "{")
+            return parseObject();
+        if (ch === "[")
+            return parseArray();
+        if (ch === '"')
+            return parseString();
+        if (ch === "-" || (ch >= "0" && ch <= "9"))
+            return parseNumber();
+        if (source.startsWith("true", pos)) {
+            const n = { kind: "boolean", start: pos, end: pos + 4, value: true };
+            pos += 4;
+            return n;
+        }
+        if (source.startsWith("false", pos)) {
+            const n = { kind: "boolean", start: pos, end: pos + 5, value: false };
+            pos += 5;
+            return n;
+        }
+        if (source.startsWith("null", pos)) {
+            const n = { kind: "null", start: pos, end: pos + 4, value: null };
+            pos += 4;
+            return n;
+        }
+        return null;
+    }
+    function parseString() {
+        const start = pos;
+        pos++; // skip opening "
+        while (pos < source.length) {
+            if (source[pos] === "\\") {
+                pos += 2;
+                continue;
+            }
+            if (source[pos] === '"') {
+                pos++;
+                break;
+            }
+            pos++;
+        }
+        const raw = source.slice(start, pos);
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            value = raw.slice(1, -1);
+        }
+        return { kind: "string", start, end: pos, value };
+    }
+    function parseNumber() {
+        const start = pos;
+        if (source[pos] === "-")
+            pos++;
+        while (pos < source.length && source[pos] >= "0" && source[pos] <= "9")
+            pos++;
+        if (pos < source.length && source[pos] === ".") {
+            pos++;
+            while (pos < source.length && source[pos] >= "0" && source[pos] <= "9")
+                pos++;
+        }
+        if (pos < source.length && (source[pos] === "e" || source[pos] === "E")) {
+            pos++;
+            if (pos < source.length && (source[pos] === "+" || source[pos] === "-"))
+                pos++;
+            while (pos < source.length && source[pos] >= "0" && source[pos] <= "9")
+                pos++;
+        }
+        const value = Number(source.slice(start, pos));
+        return { kind: "number", start, end: pos, value };
+    }
+    function parseObject() {
+        const start = pos;
+        pos++; // skip {
+        const children = [];
+        skipWhitespace();
+        while (pos < source.length && source[pos] !== "}") {
+            skipWhitespace();
+            const keyNode = parseString();
+            const key = keyNode.value;
+            skipWhitespace();
+            if (pos < source.length && source[pos] === ":")
+                pos++;
+            skipWhitespace();
+            const propStart = keyNode.start;
+            const val = parseValue();
+            const propEnd = val ? val.end : pos;
+            const child = {
+                kind: "object",
+                start: propStart,
+                end: propEnd,
+                key,
+                value: val?.value,
+                children: val?.children,
+            };
+            children.push(child);
+            skipWhitespace();
+            if (pos < source.length && source[pos] === ",")
+                pos++;
+        }
+        if (pos < source.length)
+            pos++; // skip }
+        return { kind: "object", start, end: pos, children };
+    }
+    function parseArray() {
+        const start = pos;
+        pos++; // skip [
+        const children = [];
+        skipWhitespace();
+        let index = 0;
+        while (pos < source.length && source[pos] !== "]") {
+            skipWhitespace();
+            const val = parseValue();
+            if (val) {
+                val.key = String(index);
+                children.push(val);
+            }
+            index++;
+            skipWhitespace();
+            if (pos < source.length && source[pos] === ",")
+                pos++;
+        }
+        if (pos < source.length)
+            pos++; // skip ]
+        return { kind: "array", start, end: pos, children };
+    }
+    return parseValue();
+}
+function jsonNodeToBlocks(node, source) {
+    if (node.kind === "object" && node.children) {
+        return node.children.map((child) => {
+            const raw = source.slice(child.start, child.end);
+            const block = emptyBlock(K.property, span(child.start, child.end), raw);
+            block.attrs = { key: child.key ?? "" };
+            if (child.children) {
+                block.children = child.children.map((sub) => {
+                    const subRaw = source.slice(sub.start, sub.end);
+                    const subBlock = emptyBlock(sub.kind === "object" ? K.object :
+                        sub.kind === "array" ? K.array : K.scalar, span(sub.start, sub.end), subRaw);
+                    subBlock.attrs = { key: sub.key ?? "" };
+                    return subBlock;
+                });
+            }
+            return block;
+        });
+    }
+    if (node.kind === "array" && node.children) {
+        return node.children.map((child, i) => {
+            const raw = source.slice(child.start, child.end);
+            const block = emptyBlock(K.item, span(child.start, child.end), raw);
+            block.attrs = { index: i };
+            return block;
+        });
+    }
+    // Scalar root: single block.
+    return [emptyBlock(K.scalar, span(node.start, node.end), source.slice(node.start, node.end))];
+}
+function buildTree(source) {
+    const root = parseJsonStructure(source);
+    if (!root) {
+        // Unparseable: one opaque block.
+        const block = emptyBlock("json:opaque", span(0, source.length), source);
+        return { source, leadingTrivia: "", children: [block] };
+    }
+    const children = jsonNodeToBlocks(root, source);
+    const leadingTrivia = children.length === 0 ? source : source.slice(0, children[0].span.start);
+    for (let i = 0; i < children.length; i++) {
+        const block = children[i];
+        const next = children[i + 1];
+        const triviaEnd = next ? next.span.start : source.length;
+        block.trivia = source.slice(block.span.end, triviaEnd);
+    }
+    return { source, leadingTrivia, children };
+}
+function isExternalUri(s) {
+    return /^https?:\/\//.test(s);
+}
+function extractJsonEdges(obj, parentKey, edges, seen) {
+    function push(e) {
+        const k = `${e.predicate}|${e.target}|${e.provenance}`;
+        if (seen.has(k))
+            return;
+        seen.add(k);
+        edges.push(e);
+    }
+    if (typeof obj === "string") {
+        if (parentKey === "$ref") {
+            const target = obj.startsWith("#") ? "" : obj.split("#")[0];
+            if (target) {
+                push({
+                    srcBlock: null, srcField: "$ref", predicate: "references",
+                    dstKind: isExternalUri(target) ? "external" : "document",
+                    target, anchor: obj.includes("#") ? obj.split("#")[1] : null,
+                    provenance: "json_ref",
+                });
+            }
+        }
+        else if (parentKey === "$schema") {
+            push({
+                srcBlock: null, srcField: "$schema", predicate: "schema",
+                dstKind: isExternalUri(obj) ? "external" : "document",
+                target: obj, anchor: null, provenance: "json_schema",
+            });
+        }
+        else if ((obj.startsWith("./") || obj.startsWith("../") || obj.startsWith("/")) && !obj.includes(" ")) {
+            push({
+                srcBlock: null, srcField: parentKey, predicate: parentKey,
+                dstKind: "document", target: obj, anchor: null, provenance: "json_ref",
+            });
+        }
+    }
+    else if (Array.isArray(obj)) {
+        for (const item of obj)
+            extractJsonEdges(item, parentKey, edges, seen);
+    }
+    else if (obj && typeof obj === "object") {
+        for (const [k, v] of Object.entries(obj)) {
+            extractJsonEdges(v, k, edges, seen);
+        }
+    }
+}
+export const jsonAdapter = {
+    format: JSON_FORMAT,
+    extensions: [".json"],
+    capabilities: new Set([
+        AdapterCapability.Parse,
+        AdapterCapability.Render,
+        AdapterCapability.ExtractEdges,
+        AdapterCapability.ExtractMetadata,
+        AdapterCapability.ProjectNodes,
+        AdapterCapability.StructuralMutation,
+    ]),
+    parse(source) {
+        return buildTree(source);
+    },
+    render(tree) {
+        const out = [tree.leadingTrivia];
+        for (const block of tree.children) {
+            out.push(block.dirty ? block.raw : block.raw);
+            out.push(block.trivia);
+        }
+        return out.join("");
+    },
+    projectNodes(blocks) {
+        const nodes = [];
+        const walk = (list) => {
+            for (const b of list) {
+                const key = b.attrs.key ?? "";
+                const id = b.blockId ?? "";
+                if (b.type === "json:property" && key === "$ref") {
+                    const val = b.text.replace(/^"[^"]*"\s*:\s*/, "").replace(/^"|"$/g, "").trim();
+                    nodes.push({ kind: "json:ref", name: "$ref", value: val, blockId: id });
+                }
+                if (b.type === "json:property" && key === "$schema") {
+                    const val = b.text.replace(/^"[^"]*"\s*:\s*/, "").replace(/^"|"$/g, "").trim();
+                    nodes.push({ kind: "json:schema", name: "$schema", value: val, blockId: id });
+                }
+                if (b.children.length > 0)
+                    walk(b.children);
+            }
+        };
+        walk(blocks);
+        return nodes;
+    },
+    extractEdges(_blocks, metadata) {
+        if (!metadata)
+            return [];
+        const edges = [];
+        extractJsonEdges(metadata, "", edges, new Set());
+        return edges;
+    },
+    extractMetadata(source) {
+        try {
+            const parsed = JSON.parse(source);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+//# sourceMappingURL=json.js.map

package/dist/src/format/markdown.d.ts

@@ -0,0 +1,5 @@
+import { type FormatAdapter } from "./adapter.js";
+import { assertFullCoverage } from "../core/parse/tree.js";
+export declare const MARKDOWN_FORMAT = "markdown";
+export declare const markdownAdapter: FormatAdapter;
+export { assertFullCoverage };