@legioncodeinc/nectar 0.0.1

package/dist/source-graph/sql-guards.js

@@ -0,0 +1,129 @@
+/**
+ * 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 function sqlStr(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/'/g, "''")
+        .replace(/\0/g, "")
+        // Drop C0 controls except \t (0x09) \n (0x0A) \r (0x0D), plus DEL (0x7f).
+        .replace(/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
+}
+/**
+ * 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 function sqlLike(value) {
+    return value
+        .replace(/[\\%_]/g, "\\$&")
+        .replace(/'/g, "''")
+        .replace(/\0/g, "")
+        .replace(/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
+}
+/**
+ * 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 function sqlIdent(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid SQL identifier: ${JSON.stringify(name)}`);
+    }
+    return name;
+}
+/**
+ * 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 function sLiteral(value) {
+    return `'${sqlStr(value)}'`;
+}
+/**
+ * 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 function eLiteral(body) {
+    return `E'${sqlStr(body)}'`;
+}
+/**
+ * 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 function sqlNum(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Invalid SQL numeric value: ${JSON.stringify(value)}`);
+    }
+    return String(value);
+}
+/**
+ * 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 function sqlFloat4Array(vector) {
+    const numbersLit = vector.map((v) => sqlNum(v)).join(",");
+    return `ARRAY[${numbersLit}]::float4[]`;
+}
+//# sourceMappingURL=sql-guards.js.map

package/dist/source-graph/sql-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.js","sourceRoot":"","sources":["../../src/source-graph/sql-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,KAAK;SACT,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACnB,0EAA0E;SACzE,OAAO,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;SAClB,OAAO,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB;IACtD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO,SAAS,UAAU,aAAa,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,101 @@
+/**
+ * The SourceGraphStore seam (PRD-005).
+ *
+ * The interface both the in-memory adapter (PRD-005, this project, tests + local
+ * dev) and the future Deep Lake adapter (the real substrate, per ADR-0002 reached
+ * through hivenectar's own client) implement. The file-registration ladder
+ * (PRD-006) is written entirely against this interface, so it is testable with the
+ * in-memory adapter and unchanged when the Deep Lake adapter lands.
+ *
+ * All reads/writes are tenancy-scoped (org+workspace at the layer, project_id as a
+ * column filter, per PRD-005c). "latest version" always means MAX(seq) for a nectar.
+ */
+import type { SourceGraphRow, SourceGraphVersionRow, Tenancy } from "./model.js";
+/** A candidate for re-association: a nectar plus its latest observed version. */
+export interface LatestVersion {
+    readonly identity: SourceGraphRow;
+    readonly version: SourceGraphVersionRow;
+}
+export interface SourceGraphStore {
+    /** Insert a `source_graph` identity row (mint). Throws if the nectar already exists. */
+    insertIdentity(row: SourceGraphRow): void;
+    /** Fetch an identity row by nectar, or undefined. */
+    getIdentity(nectar: string): SourceGraphRow | undefined;
+    /** Bump a nectar's `last_update_date` (called when a new version is appended). */
+    touchIdentity(nectar: string, lastUpdateDate: string): void;
+    /** Append a `source_graph_versions` row. The caller supplies seq via `nextSeq`. */
+    appendVersion(row: SourceGraphVersionRow): void;
+    /** The next monotonic seq for a nectar (0 if it has no versions yet). */
+    nextSeq(nectar: string): number;
+    /** The latest (MAX seq) version row for a nectar, or undefined. */
+    latestVersion(nectar: string): SourceGraphVersionRow | undefined;
+    /**
+     * Every nectar's latest version, scoped to the tenancy. The ladder derives the
+     * known-paths set, the missing-files set, and the by-latest-hash copy index from this.
+     */
+    listLatestVersions(tenancy: Tenancy): LatestVersion[];
+    /** The latest version whose current path equals `path` (ladder steps 1-2), scoped. */
+    latestVersionByPath(tenancy: Tenancy, path: string): LatestVersion | undefined;
+    /**
+     * A nectar whose latest version content_hash equals `contentHash` (ladder step 3
+     * exact-move, and the copy-event index), scoped. Returns the first match.
+     */
+    latestVersionByHash(tenancy: Tenancy, contentHash: string): LatestVersion | undefined;
+    /**
+     * Delete a nectar (its identity row + every version row), scoped to `tenancy`.
+     * This is the SOLE nectar-deletion path (`prune --confirm`, PRD-006d); the
+     * re-association ladder never deletes or reuses nectars. A no-op if the nectar
+     * does not exist OR its identity is outside `tenancy` (a cross-project delete
+     * is refused, never applied, per AC-20).
+     */
+    deleteNectar(tenancy: Tenancy, nectar: string): void;
+}
+/**
+ * The async twin of {@link SourceGraphStore} (PRD-005's Deep Lake adapter).
+ *
+ * `SourceGraphStore` is synchronous by design: the in-memory adapter backs it
+ * with plain `Map`s, and the file-registration ladder (`registration/ladder.ts`)
+ * calls it synchronously throughout, with no `await` anywhere in the ladder's
+ * control flow. A real Deep Lake adapter does its work over HTTP and cannot
+ * honor that synchronous contract, so this is a SEPARATE interface with the
+ * same method names and semantics, each wrapped in a `Promise` — not a
+ * variant of `SourceGraphStore` and not a substitute for it.
+ *
+ * `DeepLakeSourceGraphStore` (`deeplake-store.ts`) implements this interface,
+ * not `SourceGraphStore`. Wiring the ladder to run against an async store is
+ * out of scope for PRD-005's adapter work: that would mean either making the
+ * ladder's own control flow async (touching `registration/ladder.ts`, which
+ * this task does not touch) or adapting between the two seams at the call
+ * site. Either is a future PRD's decision once a caller actually needs the
+ * durable adapter wired into the live worker loop; today `InMemorySourceGraphStore`
+ * remains the ladder's only consumer and is unchanged by this addition.
+ */
+export interface AsyncSourceGraphStore {
+    /** Insert a `source_graph` identity row (mint). Rejects if the nectar already exists. */
+    insertIdentity(row: SourceGraphRow): Promise<void>;
+    /** Fetch an identity row by nectar, or undefined. */
+    getIdentity(nectar: string): Promise<SourceGraphRow | undefined>;
+    /** Bump a nectar's `last_update_date` (called when a new version is appended). */
+    touchIdentity(nectar: string, lastUpdateDate: string): Promise<void>;
+    /** Append a `source_graph_versions` row. The caller supplies seq via `nextSeq`. */
+    appendVersion(row: SourceGraphVersionRow): Promise<void>;
+    /** The next monotonic seq for a nectar (0 if it has no versions yet). */
+    nextSeq(nectar: string): Promise<number>;
+    /** The latest (MAX seq) version row for a nectar, or undefined. */
+    latestVersion(nectar: string): Promise<SourceGraphVersionRow | undefined>;
+    /** Every nectar's latest version, scoped to the tenancy (soft-filtered by `project_id`). */
+    listLatestVersions(tenancy: Tenancy): Promise<LatestVersion[]>;
+    /** The latest version whose current path equals `path`, scoped. */
+    latestVersionByPath(tenancy: Tenancy, path: string): Promise<LatestVersion | undefined>;
+    /** A nectar whose latest version content_hash equals `contentHash`, scoped. First match. */
+    latestVersionByHash(tenancy: Tenancy, contentHash: string): Promise<LatestVersion | undefined>;
+    /**
+     * Delete a nectar (identity + versions), scoped to `tenancy`. The SOLE
+     * deletion path (`prune --confirm`); a no-op when the nectar does not exist or
+     * its identity is outside `tenancy` (a cross-project delete is refused, AC-20).
+     * The tenancy predicate makes the Deep Lake adapter inherit the same guard the
+     * in-memory adapter enforces, so no delete crosses a project boundary.
+     */
+    deleteNectar(tenancy: Tenancy, nectar: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/source-graph/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,OAAO,EACR,MAAM,YAAY,CAAC;AAEpB,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IAE1C,qDAAqD;IACrD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAExD,kFAAkF;IAClF,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5D,mFAAmF;IACnF,aAAa,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAEhD,yEAAyE;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC,mEAAmE;IACnE,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;IAEjE;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,CAAC;IAEtD,sFAAsF;IACtF,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAE/E;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAEtF;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,qBAAqB;IACpC,yFAAyF;IACzF,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD,qDAAqD;IACrD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAEjE,kFAAkF;IAClF,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE,mFAAmF;IACnF,aAAa,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD,yEAAyE;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC,mEAAmE;IACnE,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;IAE1E,4FAA4F;IAC5F,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAE/D,mEAAmE;IACnE,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAExF,4FAA4F;IAC5F,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAE/F;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D"}

package/dist/source-graph/store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/source-graph/store.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,9 @@
+/** Mint a fresh nectar (26-char ULID). Never derived from content; created once. */
+export declare function mintNectar(nowMs?: number): string;
+/** Decode a nectar's embedded 48-bit timestamp back to milliseconds since epoch. */
+export declare function nectarTimestampMs(nectar: string): number;
+/** The nectar's creation time as an ISO 8601 string (for source_graph.created_at). */
+export declare function nectarCreatedAt(nectar: string): string;
+/** Shape check: 26 chars, all in the Crockford alphabet. */
+export declare function isValidNectar(value: string): boolean;
+//# sourceMappingURL=ulid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../../src/source-graph/ulid.ts"],"names":[],"mappings":"AAkCA,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,KAAK,GAAE,MAAmB,GAAG,MAAM,CAE7D;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASxD;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIpD"}

package/dist/source-graph/ulid.js

@@ -0,0 +1,61 @@
+/**
+ * ULID minting for nectars (PRD-005 / PRD-006, per ai/identity-and-reassociation.md).
+ *
+ * A nectar is a 26-char ULID: 48-bit millisecond timestamp + 80 bits of
+ * randomness, Crockford base32, uppercase. Two load-bearing properties (per the
+ * corpus): lexicographic sortability by creation time, and registry-free
+ * collision resistance so minting is lock-free and parallel-safe. Node built-ins
+ * only (`node:crypto`); no `ulid` package dependency.
+ */
+import { randomBytes } from "node:crypto";
+/** Crockford base32 alphabet (excludes I, L, O, U). 32 symbols, 5 bits each. */
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_LEN = 10; // 10 chars * 5 bits = 50 bits, covers the 48-bit ms timestamp
+const RANDOM_LEN = 16; // 16 chars * 5 bits = 80 bits of randomness
+function encodeTime(ms, len) {
+    let now = Math.floor(ms);
+    let out = "";
+    for (let i = 0; i < len; i++) {
+        out = ENCODING[now % 32] + out;
+        now = Math.floor(now / 32);
+    }
+    return out;
+}
+function encodeRandom(len) {
+    // 256 is divisible by 32, so byte % 32 is unbiased across 0..31.
+    const bytes = randomBytes(len);
+    let out = "";
+    for (let i = 0; i < len; i++)
+        out += ENCODING[bytes[i] % 32];
+    return out;
+}
+/** Mint a fresh nectar (26-char ULID). Never derived from content; created once. */
+export function mintNectar(nowMs = Date.now()) {
+    return encodeTime(nowMs, TIME_LEN) + encodeRandom(RANDOM_LEN);
+}
+/** Decode a nectar's embedded 48-bit timestamp back to milliseconds since epoch. */
+export function nectarTimestampMs(nectar) {
+    const timeChars = nectar.slice(0, TIME_LEN);
+    let ms = 0;
+    for (const ch of timeChars) {
+        const idx = ENCODING.indexOf(ch);
+        if (idx === -1)
+            throw new Error(`invalid ULID time char: ${ch}`);
+        ms = ms * 32 + idx;
+    }
+    return ms;
+}
+/** The nectar's creation time as an ISO 8601 string (for source_graph.created_at). */
+export function nectarCreatedAt(nectar) {
+    return new Date(nectarTimestampMs(nectar)).toISOString();
+}
+/** Shape check: 26 chars, all in the Crockford alphabet. */
+export function isValidNectar(value) {
+    if (value.length !== TIME_LEN + RANDOM_LEN)
+        return false;
+    for (const ch of value)
+        if (ENCODING.indexOf(ch) === -1)
+            return false;
+    return true;
+}
+//# sourceMappingURL=ulid.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../../src/source-graph/ulid.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,gFAAgF;AAChF,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AACpD,MAAM,QAAQ,GAAG,EAAE,CAAC,CAAC,8DAA8D;AACnF,MAAM,UAAU,GAAG,EAAE,CAAC,CAAC,4CAA4C;AAEnE,SAAS,UAAU,CAAC,EAAU,EAAE,GAAW;IACzC,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,GAAG,GAAG,QAAQ,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC;QAC/B,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,iEAAiE;IACjE,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,QAAQ,CAAE,KAAK,CAAC,CAAC,CAAY,GAAG,EAAE,CAAC,CAAC;IACzE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAC,QAAgB,IAAI,CAAC,GAAG,EAAE;IACnD,OAAO,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;AAChE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC5C,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;QACjE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC3D,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,GAAG,UAAU;QAAE,OAAO,KAAK,CAAC;IACzD,KAAK,MAAM,EAAE,IAAI,KAAK;QAAE,IAAI,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACtE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/telemetry/checkin.d.ts

@@ -0,0 +1,66 @@
+import type { PipelineStatus } from "../health.js";
+import { type Timer } from "../poll-loop.js";
+import type { SqliteDatabaseLike } from "./db.js";
+/**
+ * SIGNED OFF 2026-07-02 (decision #33, `PRD-DECISIONS-AND-DEFAULTS.md`),
+ * amended from the original 10s. doctor polls each service's SQLite
+ * roughly every 1s (ADR-0001); nectar's own heartbeat is a separate,
+ * slower write interval (last-seen only needs to look "fresh enough" relative
+ * to doctor's staleness threshold, not to match its poll rate 1:1). 5s
+ * halves the worst-case delay before a stale last_seen reveals a dead daemon
+ * while still avoiding a write per poll tick.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+export interface CheckinWriterOptions {
+    readonly db: SqliteDatabaseLike;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    now?(): string;
+}
+/** Writes/refreshes the single-row `service_status` runtime record. */
+export declare class CheckinWriter {
+    private readonly db;
+    private readonly nowFn;
+    private bindingTime;
+    constructor(opts: CheckinWriterOptions);
+    /** The binding time recorded by the most recent {@link checkin}, or null before the first check-in. */
+    get currentBindingTime(): string | null;
+    /**
+     * A fresh binding (AC-017a.2.1, AC-017a.3.2): a NEW binding_time, an initial
+     * last_seen equal to it, and the current health. Called once per daemon
+     * start (a restart is observed as a new binding_time while the registry
+     * entry and DB path stay stable).
+     */
+    checkin(health: PipelineStatus): void;
+    /** Advance last_seen (and refresh health) without changing binding_time (AC-017a.3.1). */
+    heartbeat(health: PipelineStatus): void;
+    private upsert;
+}
+export interface CheckinServiceOptions {
+    readonly writer: CheckinWriter;
+    /** The current health value, sourced from the SAME `PipelineStatus` `/health` reports (AC-017a.2.2). */
+    readonly health: () => PipelineStatus;
+    readonly intervalMs?: number;
+    /** Injected timer for deterministic tests (mirrors `PollLoop`'s seam). */
+    readonly timer?: Timer;
+}
+/**
+ * Owns the check-in-then-heartbeat lifecycle: one `checkin()` on `start()`,
+ * then a `heartbeat()` on a fixed interval until `stop()`. This is the piece
+ * `daemon.ts` starts/stops alongside the worker and the HTTP server.
+ */
+export declare class CheckinService {
+    private readonly writer;
+    private readonly health;
+    private readonly intervalMs;
+    private readonly timer;
+    private handle;
+    private running;
+    constructor(opts: CheckinServiceOptions);
+    get isRunning(): boolean;
+    /** Check in (a fresh binding_time) and arm the heartbeat. Idempotent. */
+    start(): void;
+    /** Disarm the heartbeat. Idempotent. */
+    stop(): void;
+    private scheduleNext;
+}
+//# sourceMappingURL=checkin.d.ts.map

package/dist/telemetry/checkin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkin.d.ts","sourceRoot":"","sources":["../../src/telemetry/checkin.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,0DAA0D;IAC1D,GAAG,CAAC,IAAI,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,WAAW,CAAuB;gBAE9B,IAAI,EAAE,oBAAoB;IAKtC,uGAAuG;IACvG,IAAI,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAEtC;IAED;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAMrC,0FAA0F;IAC1F,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKvC,OAAO,CAAC,MAAM;CAiBf;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,wGAAwG;IACxG,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,qBAAqB;IAOvC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAab,wCAAwC;IACxC,IAAI,IAAI,IAAI;IAQZ,OAAO,CAAC,YAAY;CAWrB"}

package/dist/telemetry/checkin.js

@@ -0,0 +1,142 @@
+/**
+ * The runtime status check-in writer (PRD-017a), per doctor's
+ * `ADR-0002-service-registration-static-registry-plus-runtime-sqlite.md`.
+ *
+ * `service_status` (id=1, latest-wins) carries binding time, last-seen, and
+ * health - the churning runtime layer doctor merges with the static
+ * registry entry (`doctor-registry.ts`). Two writers:
+ *   - `checkin()`   a FRESH binding: a new binding_time, an initial last_seen
+ *                   equal to it, and the current health (AC-017a.2.1).
+ *   - `heartbeat()` advances last_seen (and refreshes health) WITHOUT touching
+ *                   binding_time, so doctor can tell "quiet but alive" from
+ *                   "dead" purely from the age of last_seen (AC-017a.3.1).
+ *
+ * `deeplake_connected`/`deeplake_last_comm` are left NULL: nectar has no
+ * in-process "am I currently connected to Deep Lake" signal today (the
+ * `DeepLakeHiveGraphStore` is a stateless per-call HTTP client, not a live
+ * connection) - a documented approximation, not a fabricated value. A future
+ * PRD that adds real connectivity tracking can populate these columns without
+ * a schema change (see PRD-017 evidence).
+ *
+ * Every write is fail-soft (AC-7 / AC-017a): a locked file, a permissions
+ * error, or a missing directory is caught and dropped, never propagated into
+ * daemon boot or the nectar pipeline.
+ */
+import { NECTAR_DAEMON_NAME } from "../doctor-registry.js";
+import { realTimer } from "../poll-loop.js";
+/**
+ * SIGNED OFF 2026-07-02 (decision #33, `PRD-DECISIONS-AND-DEFAULTS.md`),
+ * amended from the original 10s. doctor polls each service's SQLite
+ * roughly every 1s (ADR-0001); nectar's own heartbeat is a separate,
+ * slower write interval (last-seen only needs to look "fresh enough" relative
+ * to doctor's staleness threshold, not to match its poll rate 1:1). 5s
+ * halves the worst-case delay before a stale last_seen reveals a dead daemon
+ * while still avoiding a write per poll tick.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+/** Writes/refreshes the single-row `service_status` runtime record. */
+export class CheckinWriter {
+    db;
+    nowFn;
+    bindingTime = null;
+    constructor(opts) {
+        this.db = opts.db;
+        this.nowFn = opts.now ?? (() => new Date().toISOString());
+    }
+    /** The binding time recorded by the most recent {@link checkin}, or null before the first check-in. */
+    get currentBindingTime() {
+        return this.bindingTime;
+    }
+    /**
+     * A fresh binding (AC-017a.2.1, AC-017a.3.2): a NEW binding_time, an initial
+     * last_seen equal to it, and the current health. Called once per daemon
+     * start (a restart is observed as a new binding_time while the registry
+     * entry and DB path stay stable).
+     */
+    checkin(health) {
+        const now = this.nowFn();
+        this.bindingTime = now;
+        this.upsert(now, now, health);
+    }
+    /** Advance last_seen (and refresh health) without changing binding_time (AC-017a.3.1). */
+    heartbeat(health) {
+        if (this.bindingTime === null)
+            this.bindingTime = this.nowFn();
+        this.upsert(this.bindingTime, this.nowFn(), health);
+    }
+    upsert(bindingTime, lastSeen, health) {
+        try {
+            this.db
+                .prepare(`INSERT INTO service_status (id, name, binding_time, last_seen, health, deeplake_connected, deeplake_last_comm)
+           VALUES (1, ?, ?, ?, ?, NULL, NULL)
+           ON CONFLICT(id) DO UPDATE SET
+             name = excluded.name,
+             binding_time = excluded.binding_time,
+             last_seen = excluded.last_seen,
+             health = excluded.health`)
+                .run(NECTAR_DAEMON_NAME, bindingTime, lastSeen, health);
+        }
+        catch {
+            // fail-soft (AC-7 / AC-017a): a status write error never blocks boot or the pipeline.
+        }
+    }
+}
+/**
+ * Owns the check-in-then-heartbeat lifecycle: one `checkin()` on `start()`,
+ * then a `heartbeat()` on a fixed interval until `stop()`. This is the piece
+ * `daemon.ts` starts/stops alongside the worker and the HTTP server.
+ */
+export class CheckinService {
+    writer;
+    health;
+    intervalMs;
+    timer;
+    handle = null;
+    running = false;
+    constructor(opts) {
+        this.writer = opts.writer;
+        this.health = opts.health;
+        this.intervalMs = Math.max(1, opts.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS);
+        this.timer = opts.timer ?? realTimer;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** Check in (a fresh binding_time) and arm the heartbeat. Idempotent. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        try {
+            // `this.health()` is caller-supplied and can throw; the writer is fail-soft
+            // but the sampler is not, so guard the whole sample-then-write here too.
+            this.writer.checkin(this.health());
+        }
+        catch {
+            // fail-soft (AC-7 / AC-017a): telemetry must never block daemon boot.
+        }
+        this.scheduleNext();
+    }
+    /** Disarm the heartbeat. Idempotent. */
+    stop() {
+        this.running = false;
+        if (this.handle !== null) {
+            this.timer.clear(this.handle);
+            this.handle = null;
+        }
+    }
+    scheduleNext() {
+        if (!this.running)
+            return;
+        this.handle = this.timer.set(() => {
+            try {
+                this.writer.heartbeat(this.health());
+            }
+            catch {
+                // fail-soft: one bad health sample must not kill the heartbeat loop.
+            }
+            this.scheduleNext();
+        }, this.intervalMs);
+    }
+}
+//# sourceMappingURL=checkin.js.map

package/dist/telemetry/checkin.js.map

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

package/dist/telemetry/db.d.ts

@@ -0,0 +1,34 @@
+/** The subdirectory of the runtime dir the telemetry database lives under. */
+export declare const TELEMETRY_DIR_NAME = "telemetry";
+/** The telemetry database's filename, matching doctor's per-service naming (`<name>.sqlite`). */
+export declare const TELEMETRY_DB_FILE_NAME = "nectar.sqlite";
+/** Derive the telemetry DB path from a resolved runtime dir (keeps it alongside the pid/lock files). */
+export declare function telemetryDbPathForRuntimeDir(runtimeDir: string): string;
+/** The default telemetry DB path: `~/.honeycomb/telemetry/nectar.sqlite`. */
+export declare function defaultTelemetryDbPath(home?: string): string;
+/**
+ * The minimal `node:sqlite` `DatabaseSync` surface this module uses, declared
+ * structurally so callers (and tests) can inject a fake without a hard
+ * `import("node:sqlite")` type dependency.
+ */
+export interface SqliteStatementLike {
+    run(...params: unknown[]): {
+        changes: number | bigint;
+    };
+    get(...params: unknown[]): Record<string, unknown> | undefined;
+    all(...params: unknown[]): Array<Record<string, unknown>>;
+}
+export interface SqliteDatabaseLike {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatementLike;
+    close(): void;
+}
+/**
+ * Open (or create) the telemetry database at `dbPath` in WAL mode, creating all
+ * three tables (idempotent, additive) if absent. Throws on any failure (missing
+ * `node:sqlite`, an unwritable directory, a corrupt file, ...); the caller
+ * (`index.ts`'s `createTelemetry`) catches and degrades to a no-op rather than
+ * ever propagating into daemon boot or the nectar pipeline.
+ */
+export declare function openTelemetryDb(dbPath: string): SqliteDatabaseLike;
+//# sourceMappingURL=db.d.ts.map

package/dist/telemetry/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/telemetry/db.ts"],"names":[],"mappings":"AA6BA,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAC9C,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD,wGAAwG;AACxG,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAkB,GAAG,MAAM,CAEvE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACxD,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/D,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAC;IAC1C,KAAK,IAAI,IAAI,CAAC;CACf;AAiBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CA2BlE"}