@legioncodeinc/nectar 0.0.1

package/dist/source-graph/memory-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-memory SourceGraphStore adapter (PRD-005).
+ *
+ * A complete, correct implementation of the store seam backed by plain Maps.
+ * It is the store the file-registration ladder (PRD-006), brooding (PRD-007),
+ * and the search engine (PRD-012) run against in tests and local dev. The Deep
+ * Lake adapter (the durable substrate, reached through hivenectar's own client
+ * per ADR-0002) implements the same interface and is a drop-in replacement; no
+ * consumer changes when it lands.
+ *
+ * "latest version" is always MAX(seq) for a nectar. All reads are tenancy-scoped
+ * (org+workspace+project); project_id is a plain column predicate here, exactly
+ * as the soft-filter contract (PRD-005c) specifies.
+ */
+import type { SourceGraphRow, SourceGraphVersionRow, Tenancy } from "./model.js";
+import type { LatestVersion, SourceGraphStore } from "./store.js";
+export declare class InMemorySourceGraphStore implements SourceGraphStore {
+    private readonly identities;
+    /** nectar -> version rows in append order (seq ascending). */
+    private readonly versions;
+    insertIdentity(row: SourceGraphRow): void;
+    getIdentity(nectar: string): SourceGraphRow | undefined;
+    touchIdentity(nectar: string, lastUpdateDate: string): void;
+    appendVersion(row: SourceGraphVersionRow): void;
+    nextSeq(nectar: string): number;
+    latestVersion(nectar: string): SourceGraphVersionRow | undefined;
+    listLatestVersions(tenancy: Tenancy): LatestVersion[];
+    latestVersionByPath(tenancy: Tenancy, path: string): LatestVersion | undefined;
+    latestVersionByHash(tenancy: Tenancy, contentHash: string): LatestVersion | undefined;
+    deleteNectar(tenancy: Tenancy, nectar: string): void;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/source-graph/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/source-graph/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;IAChE,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IAEvE,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAOzC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAKvD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAK3D,aAAa,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI;IAM/C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ/B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAQhE,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE;IAUrD,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAO9E,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAOrF,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAOrD"}

package/dist/source-graph/memory-store.js

@@ -0,0 +1,81 @@
+import { inTenancy } from "./model.js";
+export class InMemorySourceGraphStore {
+    identities = new Map();
+    /** nectar -> version rows in append order (seq ascending). */
+    versions = new Map();
+    insertIdentity(row) {
+        if (this.identities.has(row.nectar)) {
+            throw new Error(`identity already exists for nectar ${row.nectar}`);
+        }
+        this.identities.set(row.nectar, { ...row });
+    }
+    getIdentity(nectar) {
+        const row = this.identities.get(nectar);
+        return row ? { ...row } : undefined;
+    }
+    touchIdentity(nectar, lastUpdateDate) {
+        const row = this.identities.get(nectar);
+        if (row !== undefined)
+            row.lastUpdateDate = lastUpdateDate;
+    }
+    appendVersion(row) {
+        const list = this.versions.get(row.nectar) ?? [];
+        list.push({ ...row });
+        this.versions.set(row.nectar, list);
+    }
+    nextSeq(nectar) {
+        const list = this.versions.get(nectar);
+        if (list === undefined || list.length === 0)
+            return 0;
+        let max = -1;
+        for (const v of list)
+            if (v.seq > max)
+                max = v.seq;
+        return max + 1;
+    }
+    latestVersion(nectar) {
+        const list = this.versions.get(nectar);
+        if (list === undefined || list.length === 0)
+            return undefined;
+        let latest = list[0];
+        for (const v of list)
+            if (v.seq > latest.seq)
+                latest = v;
+        return { ...latest };
+    }
+    listLatestVersions(tenancy) {
+        const out = [];
+        for (const [nectar, identity] of this.identities) {
+            if (!inTenancy(identity, tenancy))
+                continue;
+            const version = this.latestVersion(nectar);
+            if (version !== undefined)
+                out.push({ identity: { ...identity }, version });
+        }
+        return out;
+    }
+    latestVersionByPath(tenancy, path) {
+        for (const lv of this.listLatestVersions(tenancy)) {
+            if (lv.version.path === path)
+                return lv;
+        }
+        return undefined;
+    }
+    latestVersionByHash(tenancy, contentHash) {
+        for (const lv of this.listLatestVersions(tenancy)) {
+            if (lv.version.contentHash === contentHash)
+                return lv;
+        }
+        return undefined;
+    }
+    deleteNectar(tenancy, nectar) {
+        const identity = this.identities.get(nectar);
+        if (identity === undefined)
+            return; // unknown nectar: no-op
+        if (!inTenancy(identity, tenancy))
+            return; // refuse a cross-project delete (AC-20)
+        this.identities.delete(nectar);
+        this.versions.delete(nectar);
+    }
+}
+//# sourceMappingURL=memory-store.js.map

package/dist/source-graph/memory-store.js.map

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

package/dist/source-graph/model.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The Source Graph domain model (PRD-005).
+ *
+ * Two tables, one purpose each, straight from the corpus
+ * (`library/knowledge/private/data/source-graph-schema.md`):
+ *   - `source_graph`          one row per logical file, keyed by nectar (ULID). Identity + provenance.
+ *   - `source_graph_versions` append-only, keyed by (nectar, content_hash). Content + lazy description.
+ *
+ * These types are the frozen contract the store adapters (PRD-005) and the
+ * file-registration ladder (PRD-006) both build against. Column names match the
+ * DDL exactly so the future Deep Lake adapter maps 1:1.
+ */
+/** Tenancy triple. Scope is org+workspace at the storage layer; project_id is a soft column filter (PRD-005c / decision #3). */
+export interface Tenancy {
+    readonly orgId: string;
+    readonly workspaceId: string;
+    readonly projectId: string;
+}
+/**
+ * True when a row's tenancy columns match `t` exactly on all three of
+ * `orgId`/`workspaceId`/`projectId`. The single scoping predicate re-used by
+ * the in-memory store, the ladder's carry guard, and the delete/prune/review
+ * paths so no identity mutation ever crosses a project boundary (AC-20).
+ */
+export declare function inTenancy(row: {
+    orgId: string;
+    workspaceId: string;
+    projectId: string;
+}, t: Tenancy): boolean;
+/** `source_graph.kind` discriminator. Only `file` is minted in v1; `directory` reserves the namespace (schema doc YAGNI note). */
+export type NectarKind = "file" | "directory";
+/**
+ * `source_graph_versions.describe_status`. Exactly the six values in the schema
+ * doc column table (including `skipped-deleted`, the decisions-doc #14 addition).
+ */
+export type DescribeStatus = "pending" | "described" | "failed" | "skipped-too-large" | "skipped-binary" | "skipped-deleted";
+export declare const DESCRIBE_STATUSES: readonly DescribeStatus[];
+/** A row of `source_graph` (identity + provenance only; no content, no description). */
+export interface SourceGraphRow {
+    /** 26-char ULID, minted once, never derived from content. Primary key. */
+    nectar: string;
+    kind: NectarKind;
+    /** ISO 8601 minting time (the decoded ULID timestamp). */
+    createdAt: string;
+    /** Copy-paste provenance; empty for an originally-minted file. */
+    derivedFromNectar: string;
+    /** Content hash at the fork point; empty unless derived. */
+    forkContentHash: string;
+    orgId: string;
+    workspaceId: string;
+    projectId: string;
+    /** Denormalized "last observed change" timestamp; bumped on every appended version. */
+    lastUpdateDate: string;
+}
+/** A row of `source_graph_versions` (one per observed content state of a nectar). */
+export interface SourceGraphVersionRow {
+    /** FK -> source_graph.nectar. Composite key part 1. */
+    nectar: string;
+    /** sha256 of file content at observation. Composite key part 2. */
+    contentHash: string;
+    /** Monotonic per-nectar version counter (0, 1, 2, ...). "latest" = MAX(seq). */
+    seq: number;
+    /** Repo-relative path (forward slashes) at observation time. Mutable across a nectar's versions -> records moves. */
+    path: string;
+    filename: string;
+    /** Lowercased extension without the dot (`ts`, `md`, `json`). */
+    ext: string;
+    sizeBytes: number;
+    /** File mtime at observation (ISO 8601). Not authoritative; a fast-path cache key only. */
+    mtimeObserved: string;
+    /** LLM-minted, <=80 chars. Empty while pending. */
+    title: string;
+    /** LLM-minted, 1-3 sentences. Empty while pending. */
+    description: string;
+    /** JSON-encoded string array, e.g. '["auth","session"]'. Defaults to '[]'. */
+    concepts: string;
+    /** 768-dim vector over title+description. Null until enriched (or if embeddings off). */
+    embedding: number[] | null;
+    /** Set only on ladder step-4 (TLSH fuzzy) rows: 1 - normalizedTLSHDistance. Null otherwise. */
+    confidence: number | null;
+    /**
+     * TLSH-family fingerprint of the content (the `computeFingerprint` "H1"-prefixed
+     * digest); set on every content-bearing row, consulted by ladder step 4 for
+     * missing files so cold-catch-up fuzzy matching survives a daemon restart. Null
+     * on pre-fingerprint rows (they self-heal on next observation).
+     */
+    fingerprint: string | null;
+    describedAt: string;
+    describeModel: string;
+    describeStatus: DescribeStatus;
+    /** Timestamp the version row was appended (distinct from mtimeObserved). */
+    observedAt: string;
+    orgId: string;
+    workspaceId: string;
+    projectId: string;
+    lastUpdateDate: string;
+}
+/** The embedding contract: 768 dims, tied to the FLOAT4[] column (ADR-0001 / PRD-014). A different dimension is rejected upstream. */
+export declare const EMBED_DIMS = 768;
+/** True if a vector honors the 768-dim contract. Recall's `embed.dim_rejected` guard discards anything else. */
+export declare function isValidEmbedding(vec: number[] | null): boolean;
+//# sourceMappingURL=model.d.ts.map

package/dist/source-graph/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/source-graph/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gIAAgI;AAChI,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAE7G;AAED,kIAAkI;AAClI,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,WAAW,GACX,QAAQ,GACR,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAOtD,CAAC;AAEF,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,+FAA+F;IAC/F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,sIAAsI;AACtI,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,gHAAgH;AAChH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAE9D"}

package/dist/source-graph/model.js

@@ -0,0 +1,36 @@
+/**
+ * The Source Graph domain model (PRD-005).
+ *
+ * Two tables, one purpose each, straight from the corpus
+ * (`library/knowledge/private/data/source-graph-schema.md`):
+ *   - `source_graph`          one row per logical file, keyed by nectar (ULID). Identity + provenance.
+ *   - `source_graph_versions` append-only, keyed by (nectar, content_hash). Content + lazy description.
+ *
+ * These types are the frozen contract the store adapters (PRD-005) and the
+ * file-registration ladder (PRD-006) both build against. Column names match the
+ * DDL exactly so the future Deep Lake adapter maps 1:1.
+ */
+/**
+ * True when a row's tenancy columns match `t` exactly on all three of
+ * `orgId`/`workspaceId`/`projectId`. The single scoping predicate re-used by
+ * the in-memory store, the ladder's carry guard, and the delete/prune/review
+ * paths so no identity mutation ever crosses a project boundary (AC-20).
+ */
+export function inTenancy(row, t) {
+    return row.orgId === t.orgId && row.workspaceId === t.workspaceId && row.projectId === t.projectId;
+}
+export const DESCRIBE_STATUSES = [
+    "pending",
+    "described",
+    "failed",
+    "skipped-too-large",
+    "skipped-binary",
+    "skipped-deleted",
+];
+/** The embedding contract: 768 dims, tied to the FLOAT4[] column (ADR-0001 / PRD-014). A different dimension is rejected upstream. */
+export const EMBED_DIMS = 768;
+/** True if a vector honors the 768-dim contract. Recall's `embed.dim_rejected` guard discards anything else. */
+export function isValidEmbedding(vec) {
+    return vec === null || vec.length === EMBED_DIMS;
+}
+//# sourceMappingURL=model.js.map

package/dist/source-graph/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/source-graph/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAA8D,EAAE,CAAU;IAClG,OAAO,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,IAAI,GAAG,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,CAAC;AACrG,CAAC;AAiBD,MAAM,CAAC,MAAM,iBAAiB,GAA8B;IAC1D,SAAS;IACT,WAAW;IACX,QAAQ;IACR,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC;AAgEF,sIAAsI;AACtI,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAE9B,gHAAgH;AAChH,MAAM,UAAU,gBAAgB,CAAC,GAAoB;IACnD,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC;AACnD,CAAC"}

package/dist/source-graph/paths.d.ts

@@ -0,0 +1,7 @@
+/** Repo-relative, forward-slashed path. `root` is the project root; `absOrRel` may be absolute or already relative. */
+export declare function toRepoRelative(absOrRel: string, root: string): string;
+/** Bare filename (`a.ts`) from a path. */
+export declare function filenameOf(p: string): string;
+/** Lowercased extension without the leading dot (`ts`, `md`, `json`); empty string if none. */
+export declare function extOf(p: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/source-graph/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/source-graph/paths.ts"],"names":[],"mappings":"AASA,uHAAuH;AACvH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrE;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,+FAA+F;AAC/F,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvC"}

package/dist/source-graph/paths.js

@@ -0,0 +1,26 @@
+/**
+ * Path helpers for building version rows (PRD-005 / PRD-006).
+ *
+ * Paths in `source_graph_versions.path` are repo-relative with forward slashes,
+ * regardless of OS. `filename` and `ext` are denormalized from the path for fast
+ * filename-only search and extractor routing (per source-graph-schema.md).
+ */
+import { relative, basename, extname } from "node:path";
+/** Repo-relative, forward-slashed path. `root` is the project root; `absOrRel` may be absolute or already relative. */
+export function toRepoRelative(absOrRel, root) {
+    const rel = relative(root, absOrRel);
+    // If `absOrRel` was already relative to cwd and not under root, `relative` may
+    // return it unchanged; normalize separators either way.
+    const forward = (rel === "" ? absOrRel : rel).replace(/\\/g, "/");
+    return forward.replace(/^\.\//, "");
+}
+/** Bare filename (`a.ts`) from a path. */
+export function filenameOf(p) {
+    return basename(p.replace(/\\/g, "/"));
+}
+/** Lowercased extension without the leading dot (`ts`, `md`, `json`); empty string if none. */
+export function extOf(p) {
+    const ext = extname(p);
+    return ext.startsWith(".") ? ext.slice(1).toLowerCase() : ext.toLowerCase();
+}
+//# sourceMappingURL=paths.js.map

package/dist/source-graph/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/source-graph/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAExD,uHAAuH;AACvH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,IAAY;IAC3D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,+EAA+E;IAC/E,wDAAwD;IACxD,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAClE,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;AAC9E,CAAC"}

package/dist/source-graph/schema.d.ts

@@ -0,0 +1,44 @@
+export type SqlType = "TEXT" | "BIGINT" | "REAL" | "FLOAT4[]";
+export interface ColumnDef {
+    readonly name: string;
+    readonly type: SqlType;
+    /** NOT NULL columns must carry a `default` (the load-time guard). Nullable columns omit it. */
+    readonly notNull: boolean;
+    readonly default?: string | number;
+}
+export interface CatalogTable {
+    readonly name: string;
+    /** Scope is `tenant` for both tables (explicit org/workspace/project columns), mirroring `codebase`. */
+    readonly scope: "tenant";
+    /** How writes reconcile: identity is upserted, versions are append-only. */
+    readonly writePattern: "update-or-insert" | "append-only";
+    readonly columns: readonly ColumnDef[];
+}
+/** `source_graph` (identity + provenance). All TEXT NOT NULL with defaults; `kind` defaults to 'file'. */
+export declare const SOURCE_GRAPH_COLUMNS: readonly ColumnDef[];
+/** `source_graph_versions` (content + description chain). `embedding` + `confidence` + `fingerprint` are nullable. */
+export declare const SOURCE_GRAPH_VERSIONS_COLUMNS: readonly ColumnDef[];
+export declare const SOURCE_GRAPH_TABLE: CatalogTable;
+export declare const SOURCE_GRAPH_VERSIONS_TABLE: CatalogTable;
+/** The `source-graph` catalog group appended to the daemon's CATALOG aggregation. */
+export declare const SOURCE_GRAPH_CATALOG_GROUP: {
+    readonly name: "source-graph";
+    readonly tables: readonly [CatalogTable, CatalogTable];
+};
+/**
+ * The load-time guard (mirrors honeycomb `schema.ts:80-100`): valid identifiers,
+ * no duplicate columns, and every NOT NULL column carries a DEFAULT. Throws on
+ * violation. Returns the table unchanged so it can wrap a definition inline.
+ */
+export declare function assertValidCatalogTable(table: CatalogTable): CatalogTable;
+/**
+ * Render `CREATE TABLE IF NOT EXISTS "<name>" (...) USING deeplake` from a
+ * `CatalogTable`, mirroring honeycomb's `buildCreateTableSql`
+ * (`src/daemon/storage/schema.ts:110-114`). `IF NOT EXISTS` is what makes two
+ * concurrent healers converge: the second create is a harmless no-op, not a
+ * duplicate-table error. The table name is validated through `sqlIdent`;
+ * column names are validated at load by `assertValidCatalogTable`, so they are
+ * safe to interpolate via {@link columnClause}.
+ */
+export declare function buildCreateTableSql(table: CatalogTable): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/source-graph/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/source-graph/schema.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wGAAwG;IACxG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,kBAAkB,GAAG,aAAa,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;CACxC;AAED,0GAA0G;AAC1G,eAAO,MAAM,oBAAoB,EAAE,SAAS,SAAS,EAUpD,CAAC;AAEF,sHAAsH;AACtH,eAAO,MAAM,6BAA6B,EAAE,SAAS,SAAS,EAuB7D,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,YAKhC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,YAKzC,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC;AAIX;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAkBzE;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAI/D"}

package/dist/source-graph/schema.js

@@ -0,0 +1,123 @@
+/**
+ * Source Graph table definitions (PRD-005), transcribed from the DDL in
+ * `library/knowledge/private/data/source-graph-schema.md`.
+ *
+ * These `ColumnDef[]` arrays are the catalog contract the Deep Lake adapter
+ * (`deeplake-store.ts`) registers (mirroring honeycomb's `CatalogTable` /
+ * `ColumnDef` and its load-time guard: valid identifiers, no duplicates, and
+ * every NOT NULL column carries a DEFAULT, except the nullable
+ * `embedding`/`confidence`/`fingerprint`). Both tables self-create on first write via
+ * `deeplake-heal.ts`'s `withHeal`; there is no DDL pre-step.
+ */
+import { sqlIdent, sqlStr } from "./sql-guards.js";
+/** `source_graph` (identity + provenance). All TEXT NOT NULL with defaults; `kind` defaults to 'file'. */
+export const SOURCE_GRAPH_COLUMNS = [
+    { name: "nectar", type: "TEXT", notNull: true, default: "" },
+    { name: "kind", type: "TEXT", notNull: true, default: "file" },
+    { name: "created_at", type: "TEXT", notNull: true, default: "" },
+    { name: "derived_from_nectar", type: "TEXT", notNull: true, default: "" },
+    { name: "fork_content_hash", type: "TEXT", notNull: true, default: "" },
+    { name: "org_id", type: "TEXT", notNull: true, default: "" },
+    { name: "workspace_id", type: "TEXT", notNull: true, default: "" },
+    { name: "project_id", type: "TEXT", notNull: true, default: "" },
+    { name: "last_update_date", type: "TEXT", notNull: true, default: "" },
+];
+/** `source_graph_versions` (content + description chain). `embedding` + `confidence` + `fingerprint` are nullable. */
+export const SOURCE_GRAPH_VERSIONS_COLUMNS = [
+    { name: "nectar", type: "TEXT", notNull: true, default: "" },
+    { name: "content_hash", type: "TEXT", notNull: true, default: "" },
+    { name: "seq", type: "BIGINT", notNull: true, default: 0 },
+    { name: "path", type: "TEXT", notNull: true, default: "" },
+    { name: "filename", type: "TEXT", notNull: true, default: "" },
+    { name: "ext", type: "TEXT", notNull: true, default: "" },
+    { name: "size_bytes", type: "BIGINT", notNull: true, default: 0 },
+    { name: "mtime_observed", type: "TEXT", notNull: true, default: "" },
+    { name: "title", type: "TEXT", notNull: true, default: "" },
+    { name: "description", type: "TEXT", notNull: true, default: "" },
+    { name: "concepts", type: "TEXT", notNull: true, default: "[]" },
+    { name: "embedding", type: "FLOAT4[]", notNull: false },
+    { name: "confidence", type: "REAL", notNull: false },
+    { name: "fingerprint", type: "TEXT", notNull: false },
+    { name: "described_at", type: "TEXT", notNull: true, default: "" },
+    { name: "describe_model", type: "TEXT", notNull: true, default: "" },
+    { name: "describe_status", type: "TEXT", notNull: true, default: "pending" },
+    { name: "observed_at", type: "TEXT", notNull: true, default: "" },
+    { name: "org_id", type: "TEXT", notNull: true, default: "" },
+    { name: "workspace_id", type: "TEXT", notNull: true, default: "" },
+    { name: "project_id", type: "TEXT", notNull: true, default: "" },
+    { name: "last_update_date", type: "TEXT", notNull: true, default: "" },
+];
+export const SOURCE_GRAPH_TABLE = {
+    name: "source_graph",
+    scope: "tenant",
+    writePattern: "update-or-insert",
+    columns: SOURCE_GRAPH_COLUMNS,
+};
+export const SOURCE_GRAPH_VERSIONS_TABLE = {
+    name: "source_graph_versions",
+    scope: "tenant",
+    writePattern: "append-only",
+    columns: SOURCE_GRAPH_VERSIONS_COLUMNS,
+};
+/** The `source-graph` catalog group appended to the daemon's CATALOG aggregation. */
+export const SOURCE_GRAPH_CATALOG_GROUP = {
+    name: "source-graph",
+    tables: [SOURCE_GRAPH_TABLE, SOURCE_GRAPH_VERSIONS_TABLE],
+};
+const IDENT_RE = /^[a-z_][a-z0-9_]*$/;
+/**
+ * The load-time guard (mirrors honeycomb `schema.ts:80-100`): valid identifiers,
+ * no duplicate columns, and every NOT NULL column carries a DEFAULT. Throws on
+ * violation. Returns the table unchanged so it can wrap a definition inline.
+ */
+export function assertValidCatalogTable(table) {
+    if (!IDENT_RE.test(table.name)) {
+        throw new Error(`invalid table name: ${table.name}`);
+    }
+    const seen = new Set();
+    for (const col of table.columns) {
+        if (!IDENT_RE.test(col.name)) {
+            throw new Error(`invalid column identifier: ${table.name}.${col.name}`);
+        }
+        if (seen.has(col.name)) {
+            throw new Error(`duplicate column: ${table.name}.${col.name}`);
+        }
+        seen.add(col.name);
+        if (col.notNull && col.default === undefined) {
+            throw new Error(`NOT NULL column without DEFAULT: ${table.name}.${col.name}`);
+        }
+    }
+    return table;
+}
+/**
+ * Render one column's SQL clause (`<name> <type>[ NOT NULL][ DEFAULT <lit>]`)
+ * from a `ColumnDef`. The identifier is validated through `sqlIdent`; a
+ * string `default` is rendered as a quoted literal via `sqlStr` (the TEXT
+ * columns' defaults, e.g. `''`, `'file'`, `'[]'`, `'pending'`), a numeric
+ * `default` is inlined bare (the BIGINT columns' `0`). `FLOAT4[]`/`REAL`
+ * columns in this catalog are always nullable and carry no default.
+ */
+function columnClause(col) {
+    const name = sqlIdent(col.name);
+    const notNull = col.notNull ? " NOT NULL" : "";
+    let defaultClause = "";
+    if (col.default !== undefined) {
+        defaultClause = typeof col.default === "number" ? ` DEFAULT ${col.default}` : ` DEFAULT '${sqlStr(col.default)}'`;
+    }
+    return `${name} ${col.type}${notNull}${defaultClause}`;
+}
+/**
+ * Render `CREATE TABLE IF NOT EXISTS "<name>" (...) USING deeplake` from a
+ * `CatalogTable`, mirroring honeycomb's `buildCreateTableSql`
+ * (`src/daemon/storage/schema.ts:110-114`). `IF NOT EXISTS` is what makes two
+ * concurrent healers converge: the second create is a harmless no-op, not a
+ * duplicate-table error. The table name is validated through `sqlIdent`;
+ * column names are validated at load by `assertValidCatalogTable`, so they are
+ * safe to interpolate via {@link columnClause}.
+ */
+export function buildCreateTableSql(table) {
+    const safeName = sqlIdent(table.name);
+    const colSql = table.columns.map(columnClause).join(", ");
+    return `CREATE TABLE IF NOT EXISTS "${safeName}" (${colSql}) USING deeplake`;
+}
+//# sourceMappingURL=schema.js.map

package/dist/source-graph/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/source-graph/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAqBnD,0GAA0G;AAC1G,MAAM,CAAC,MAAM,oBAAoB,GAAyB;IACxD,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC5D,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE;IAC9D,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAChE,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACzE,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACvE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC5D,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAClE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAChE,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;CACvE,CAAC;AAEF,sHAAsH;AACtH,MAAM,CAAC,MAAM,6BAA6B,GAAyB;IACjE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC5D,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAClE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;IAC1D,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC1D,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC9D,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACzD,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;IACjE,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACpE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC3D,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACjE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;IAChE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE;IACvD,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE;IACpD,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE;IACrD,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAClE,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACpE,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE;IAC5E,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IACjE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAC5D,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAClE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;IAChE,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;CACvE,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAiB;IAC9C,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,QAAQ;IACf,YAAY,EAAE,kBAAkB;IAChC,OAAO,EAAE,oBAAoB;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAiB;IACvD,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,QAAQ;IACf,YAAY,EAAE,aAAa;IAC3B,OAAO,EAAE,6BAA6B;CACvC,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,CAAC,kBAAkB,EAAE,2BAA2B,CAAC;CACjD,CAAC;AAEX,MAAM,QAAQ,GAAG,oBAAoB,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAmB;IACzD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnB,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,GAAc;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,aAAa,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC;IACpH,CAAC;IACD,OAAO,GAAG,IAAI,IAAI,GAAG,CAAC,IAAI,GAAG,OAAO,GAAG,aAAa,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO,+BAA+B,QAAQ,MAAM,MAAM,kBAAkB,CAAC;AAC/E,CAAC"}

package/dist/source-graph/sql-guards.d.ts

@@ -0,0 +1,99 @@
+/**
+ * SQL-safety escaping helpers for the Deep Lake adapter (PRD-005).
+ *
+ * Ported (not imported) from honeycomb's `src/daemon/storage/sql.ts`, per
+ * ADR-0002: hivenectar reaches Deep Lake over the network through its own
+ * client and never imports the honeycomb runtime in-process, so the escaping
+ * floor is mirrored here rather than shared across the process boundary.
+ *
+ * The Deep Lake HTTP query endpoint binds no parameters: every value is
+ * escaped and interpolated into the statement by hand before it is sent.
+ * There is no parameterized fallback to forget to use, so these helpers ARE
+ * the parameter binding. Every dynamic value the Deep Lake adapter builds
+ * (`schema.ts`'s `buildCreateTableSql`, `deeplake-store.ts`'s query builders)
+ * routes through `sqlStr` / `sqlLike` / `sqlIdent` / `sLiteral` / `eLiteral`.
+ *
+ * These functions are pure, synchronous, side-effect-free, and dependency-free
+ * beyond the language runtime (hivenectar's zero-runtime-dependency rule).
+ */
+/**
+ * Escape a string for use inside a single-quoted SQL literal.
+ *
+ * Order matters: backslashes are doubled FIRST (so the backslash added for a
+ * doubled quote is not itself re-escaped), then single quotes are doubled,
+ * then NUL and the C0/C1 control characters are dropped. The result is the
+ * inner body of the literal; the caller wraps it in quotes (`'${sqlStr(v)}'`,
+ * or via {@link sLiteral}) or uses the `E'...'` form via {@link eLiteral} when
+ * the body carries escape sequences.
+ *
+ * Because every quote is doubled and every backslash is doubled, an injection
+ * payload like `'; DROP TABLE x; --` collapses to one inert literal: the
+ * embedded quote can never close the string early, so no second statement is
+ * ever produced.
+ */
+export declare function sqlStr(value: string): string;
+/**
+ * Escape a string for use inside a `LIKE` / `ILIKE` pattern.
+ *
+ * Escapes the `LIKE` metacharacters (`%` and `_`) so a literal substring
+ * search is never reinterpreted as a wildcard match, alongside the same
+ * quote-doubling and control stripping {@link sqlStr} performs. Not currently
+ * exercised by the source-graph store's equality-only reads, but ported
+ * alongside `sqlStr`/`sqlIdent` so a future prefix/substring query never has
+ * to reach for a hand-rolled escape.
+ */
+export declare function sqlLike(value: string): string;
+/**
+ * Validate a table/column identifier against `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+ * Returns the name UNCHANGED on success; throws on anything else.
+ *
+ * Strict by design: it THROWS rather than sanitizing, because a silently
+ * rewritten identifier would be a worse, harder-to-debug failure than a
+ * rejected one. Callers pass only known schema names (table and column
+ * identifiers from `SOURCE_GRAPH_COLUMNS` / `SOURCE_GRAPH_VERSIONS_COLUMNS`),
+ * so a rejection is always a programmer error worth surfacing.
+ */
+export declare function sqlIdent(name: string): string;
+/**
+ * Build an ordinary single-quoted literal from a value. Thin convenience
+ * around `'${sqlStr(v)}'` so call sites read as a builder call rather than raw
+ * quote assembly. Use for ids, paths, hashes, enum-like values, and dates.
+ * Use {@link eLiteral} instead when the body may carry escape sequences
+ * (free-text title/description/concepts).
+ */
+export declare function sLiteral(value: string): string;
+/**
+ * Build an `E'...'` escape-string literal from a raw text body.
+ *
+ * Free-text bodies that may contain escape sequences (a description or title
+ * with a literal backslash) must use the `E'...'` form so the
+ * doubled-backslash escaping from {@link sqlStr} round-trips to the intended
+ * bytes; a plain `'...'` literal for a body with backslashes would corrupt it.
+ */
+export declare function eLiteral(body: string): string;
+/**
+ * Validate and render a numeric value for bare (unquoted) SQL interpolation.
+ * Throws unless `value` is, at runtime, a finite JavaScript `number` -
+ * TypeScript's `number` type is erased at runtime, so a value that merely
+ * carries the `number` type at compile time (e.g. `row.seq`, `row.sizeBytes`,
+ * `row.confidence`, or one entry of an embedding vector) is not actually
+ * guaranteed to be a safe, quote-free numeric literal unless this is checked
+ * here. Without this guard, a non-numeric value smuggled past the type
+ * system (a string, `NaN`, `Infinity`, or an object) would be interpolated
+ * bare via `String(value)` with no escaping at all - the same injection
+ * shape `sqlStr`/`sqlIdent` close for text and identifiers, just for the
+ * numeric case. Rejects `NaN`/`Infinity`/`-Infinity` too, since those are not
+ * valid bare-numeric SQL tokens.
+ */
+export declare function sqlNum(value: number): string;
+/**
+ * Serialize a `number[]` to a `FLOAT4[]` SQL literal (`ARRAY[...]::float4[]`),
+ * mirroring honeycomb's `serializeFloat4Array` (`src/daemon/storage/vector.ts`).
+ * Every entry is validated via {@link sqlNum} before interpolation - the
+ * dimension contract (`isValidEmbedding`, 768) is a separate application-level
+ * check the caller is still responsible for, but this function does not rely
+ * on the caller to have validated *finiteness*: a non-numeric or non-finite
+ * entry throws here rather than being interpolated bare into the statement.
+ */
+export declare function sqlFloat4Array(vector: readonly number[]): string;
+//# sourceMappingURL=sql-guards.d.ts.map

package/dist/source-graph/sql-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.d.ts","sourceRoot":"","sources":["../../src/source-graph/sql-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK7C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGhE"}