@legioncodeinc/nectar 0.0.1

package/dist/hive-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: nectar 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 (nectar'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 hive-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 `HIVE_GRAPH_COLUMNS` / `HIVE_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/hive-graph/sql-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.d.ts","sourceRoot":"","sources":["../../src/hive-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"}

package/dist/hive-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: nectar 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 (nectar'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 hive-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 `HIVE_GRAPH_COLUMNS` / `HIVE_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/hive-graph/sql-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.js","sourceRoot":"","sources":["../../src/hive-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/hive-graph/store.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The HiveGraphStore 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 nectar'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 { HiveGraphRow, HiveGraphVersionRow, Tenancy } from "./model.js";
+/** A candidate for re-association: a nectar plus its latest observed version. */
+export interface LatestVersion {
+    readonly identity: HiveGraphRow;
+    readonly version: HiveGraphVersionRow;
+}
+export interface HiveGraphStore {
+    /** Insert a `hive_graph` identity row (mint). Throws if the nectar already exists. */
+    insertIdentity(row: HiveGraphRow): void;
+    /** Fetch an identity row by nectar, or undefined. */
+    getIdentity(nectar: string): HiveGraphRow | undefined;
+    /** Bump a nectar's `last_update_date` (called when a new version is appended). */
+    touchIdentity(nectar: string, lastUpdateDate: string): void;
+    /** Append a `hive_graph_versions` row. The caller supplies seq via `nextSeq`. */
+    appendVersion(row: HiveGraphVersionRow): 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): HiveGraphVersionRow | 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[];
+    /**
+     * Every nectar's latest DESCRIBED version, scoped to the tenancy: for each
+     * nectar that has at least one `describe_status = 'described'` version, the
+     * highest-seq described row. Nectars with no described version are omitted.
+     *
+     * This is the projection scan (PRD-011c / `data/portable-registry.md` §
+     * Generation and regeneration: "latest described version per nectar, scoped to
+     * the project"). The projection builder overlays this onto
+     * {@link listLatestVersions} so an undescribed nectar still keeps a minimal
+     * entry (identity + path + content_hash) while a described one carries the
+     * latest description verbatim.
+     */
+    listLatestDescribedVersions(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;
+    /**
+     * Every `hive_graph` identity row, scoped to `tenancy` - INCLUDING an
+     * identity with zero `hive_graph_versions` rows (which
+     * {@link listLatestVersions} can never surface, since it joins through the
+     * latest version). OPTIONAL and ADDITIVE (PRD-018d): the ladder's crash-repair
+     * sweep (`repairLadderState`) uses this to find an orphan identity left by a
+     * mint crashing between `insertIdentity` and `appendVersion`. Omit on an
+     * adapter that has no cheap way to enumerate bare identities; the sweep skips
+     * orphan-identity healing (only) when this is undefined, and reports the gap
+     * rather than guessing.
+     */
+    listIdentities?(tenancy: Tenancy): HiveGraphRow[];
+    /**
+     * Every distinct nectar that has AT LEAST ONE `hive_graph_versions` row,
+     * scoped to `tenancy` (via the version rows' own tenancy columns, since an
+     * orphan version's nectar may have no `hive_graph` identity row to scope
+     * against). OPTIONAL and ADDITIVE (PRD-018 close-out, CodeRabbit PR-18
+     * finding #8): the ladder's crash-repair sweep (`repairLadderState`) uses
+     * this, together with {@link getIdentity}, to find an orphan VERSION - a
+     * version row whose nectar has no matching identity (the inverse of the
+     * orphan-IDENTITY case {@link listIdentities} already heals) - left by a
+     * durable identity-insert flush that failed after a later version for the
+     * same nectar still landed. Omit on an adapter with no cheap way to
+     * enumerate distinct version nectars; the sweep skips orphan-version
+     * healing (only) when this is undefined.
+     */
+    listVersionNectars?(tenancy: Tenancy): string[];
+}
+/**
+ * The async twin of {@link HiveGraphStore} (PRD-005's Deep Lake adapter).
+ *
+ * `HiveGraphStore` 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 `HiveGraphStore` and not a substitute for it.
+ *
+ * `DeepLakeHiveGraphStore` (`deeplake-store.ts`) implements this interface,
+ * not `HiveGraphStore`. 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 `InMemoryHiveGraphStore`
+ * remains the ladder's only consumer and is unchanged by this addition.
+ */
+export interface AsyncHiveGraphStore {
+    /** Insert a `hive_graph` identity row (mint). Rejects if the nectar already exists. */
+    insertIdentity(row: HiveGraphRow): Promise<void>;
+    /** Fetch an identity row by nectar, or undefined. */
+    getIdentity(nectar: string): Promise<HiveGraphRow | undefined>;
+    /** Bump a nectar's `last_update_date` (called when a new version is appended). */
+    touchIdentity(nectar: string, lastUpdateDate: string): Promise<void>;
+    /** Append a `hive_graph_versions` row. The caller supplies seq via `nextSeq`. */
+    appendVersion(row: HiveGraphVersionRow): 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<HiveGraphVersionRow | undefined>;
+    /** Every nectar's latest version, scoped to the tenancy (soft-filtered by `project_id`). */
+    listLatestVersions(tenancy: Tenancy): Promise<LatestVersion[]>;
+    /**
+     * Every nectar's latest DESCRIBED version, scoped to the tenancy: for each
+     * nectar with at least one `describe_status = 'described'` version, the
+     * highest-seq described row (nectars with no described version omitted). The
+     * async twin of {@link HiveGraphStore.listLatestDescribedVersions}; the
+     * projection scan (PRD-011c) the durable `rebuild-projection` CLI runs against
+     * Deep Lake, overlaid onto {@link listLatestVersions} so undescribed nectars
+     * keep a minimal entry.
+     */
+    listLatestDescribedVersions(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/hive-graph/store.d.ts.map

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

package/dist/hive-graph/store.js

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

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Mint a fresh nectar (26-char ULID). Never derived from content; created once.
+ * Within the same millisecond the random component is incremented (monotonic),
+ * so `mintNectar(t)` called repeatedly at the same `t` yields strictly
+ * increasing ULIDs; a new millisecond re-randomizes it.
+ */
+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 hive_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/hive-graph/ulid.d.ts.map

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

package/dist/hive-graph/ulid.js

@@ -0,0 +1,109 @@
+/**
+ * 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 - MONOTONIC even within a
+ * single millisecond via a same-ms counter (NEC-042 item 6 / AC-018l.13), so two
+ * nectars minted in the same millisecond still sort in creation order - and
+ * registry-free collision resistance so minting is lock-free and parallel-safe.
+ * Node built-ins only (`node:crypto`); no `ulid` package dependency.
+ *
+ * The same-ms counter is the standard `monotonicFactory` behavior: within one
+ * millisecond, the 80-bit random component is INCREMENTED per mint instead of
+ * re-randomized, so the ULIDs are strictly increasing. The encoded timestamp is
+ * always the supplied `nowMs` (never clamped forward), so `nectarTimestampMs`
+ * decodes it exactly; a new millisecond re-randomizes the component.
+ */
+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;
+}
+/** Fresh randomness as `len` base32 symbol indices (0..31). 256 % 32 == 0, so `byte % 32` is unbiased. */
+function freshRandomDigits(len) {
+    const bytes = randomBytes(len);
+    const out = [];
+    for (let i = 0; i < len; i++)
+        out.push(bytes[i] % 32);
+    return out;
+}
+/**
+ * Increment a base32-digit array by one (least-significant last), carrying on a
+ * 31 -> 0 rollover. On a full overflow (every digit was 31, astronomically
+ * unlikely with 80 bits) it falls back to fresh randomness rather than throwing,
+ * so minting never crashes.
+ */
+function incrementDigits(digits) {
+    const out = digits.slice();
+    for (let i = out.length - 1; i >= 0; i--) {
+        const d = out[i];
+        if (d < 31) {
+            out[i] = d + 1;
+            return out;
+        }
+        out[i] = 0;
+    }
+    return freshRandomDigits(out.length);
+}
+function digitsToString(digits) {
+    let out = "";
+    for (const d of digits)
+        out += ENCODING[d];
+    return out;
+}
+/** The last millisecond minted at, and its (possibly incremented) random component, for same-ms monotonicity. */
+let lastMintMs = -1;
+let lastRandomDigits = [];
+/**
+ * Mint a fresh nectar (26-char ULID). Never derived from content; created once.
+ * Within the same millisecond the random component is incremented (monotonic),
+ * so `mintNectar(t)` called repeatedly at the same `t` yields strictly
+ * increasing ULIDs; a new millisecond re-randomizes it.
+ */
+export function mintNectar(nowMs = Date.now()) {
+    const t = Math.floor(nowMs);
+    if (t === lastMintMs) {
+        lastRandomDigits = incrementDigits(lastRandomDigits);
+    }
+    else {
+        lastMintMs = t;
+        lastRandomDigits = freshRandomDigits(RANDOM_LEN);
+    }
+    return encodeTime(t, TIME_LEN) + digitsToString(lastRandomDigits);
+}
+/** 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 hive_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/hive-graph/ulid.js.map

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

package/dist/hivedoctor-registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * hivenectar's registry entry in hivedoctor's daemon registry (PRD-003c).
+ *
+ * hivenectar becomes a supervised daemon by appending ONE entry to hivedoctor's
+ * registry file (`~/.honeycomb/hivedoctor.daemons.json`, the schema PRD-004a
+ * specifies, mirrored read-side in `hivedoctor/src/registry.ts`). That entry
+ * carries hivenectar's `healthUrl`, `pidPath`, `probeIntervalMs`, `startupGraceMs`,
+ * and restart thresholds. At the next hivedoctor boot, hivedoctor reads the
+ * registry and spawns one supervisor instance for hivenectar alongside honeycomb
+ * and thehive.
+ *
+ * Registration is a FILE EDIT at install time (PRD-003c "Registration mechanics"),
+ * never a runtime call: this module does not restart hivedoctor, does not open an
+ * HTTP connection, and does not hot-reload anything. It is idempotent - re-running
+ * the installer replaces hivenectar's own entry (keyed by `name: "hivenectar"`)
+ * rather than appending a duplicate, and every other daemon's entry is preserved
+ * byte-for-byte apart from array position.
+ *
+ * A PRESENT-but-malformed registry file fails loudly (this module never silently
+ * clobbers a broken file it cannot safely parse), mirroring hivedoctor's own
+ * fail-loud posture for a malformed registry (`hivedoctor/src/registry.ts`).
+ * PRD-017a deliberately does NOT change this posture to match hivedoctor's own
+ * fail-soft posture for a malformed registry read - the two are intentionally
+ * different (this writer refuses to clobber a broken install-time file; a
+ * malformed registry read is hivedoctor's own runtime concern, not this one).
+ *
+ * PRD-017a extends this entry with `telemetryDbPath`: the absolute path to
+ * hivenectar's runtime telemetry SQLite database (`telemetry/db.ts`,
+ * `~/.honeycomb/telemetry/hivenectar.sqlite` by default), per hivedoctor's
+ * `ADR-0002-service-registration-static-registry-plus-runtime-sqlite.md`. It is
+ * derived from `config.pidFilePath`'s directory (the same resolved runtime dir
+ * `healthUrl`/`pidPath` already come from), so a test-overridden runtime dir
+ * (`HIVENECTAR_RUNTIME_DIR` / `resolveConfig({ runtimeDir })`) keeps every
+ * per-daemon artifact - pid, lock, and now telemetry DB - colocated, with no
+ * separate `~` round-trip needed here (same rationale as `healthUrl`/`pidPath`).
+ *
+ * Built-ins only: node:fs, node:os, node:path.
+ */
+import type { RuntimeConfig } from "./config.js";
+/** The daemon name hivenectar registers itself under. */
+export declare const HIVENECTAR_DAEMON_NAME: "hivenectar";
+/**
+ * One registry entry, matching the schema hivedoctor's registry loader parses
+ * (PRD-004a / `hivedoctor/src/registry.ts`).
+ */
+export interface HivedoctorRegistryEntry {
+    readonly name: string;
+    readonly healthUrl: string;
+    readonly pidPath: string;
+    readonly probeIntervalMs: number;
+    readonly startupGraceMs: number;
+    readonly restartGiveUpThreshold: number;
+    readonly restartCooldownMs: number;
+    /**
+     * The absolute path to hivenectar's runtime telemetry SQLite database
+     * (PRD-017a), so hivedoctor knows where to poll (read-only) for check-in
+     * status, metrics, and logs. Optional in the type only so a pre-PRD-017
+     * entry a test constructs by hand still type-checks; `buildHivenectarRegistryEntry`
+     * always populates it.
+     */
+    readonly telemetryDbPath?: string;
+}
+/** hivedoctor's per-daemon defaults hivenectar's entry resolves to (PRD-003c table). */
+export declare const DEFAULT_PROBE_INTERVAL_MS = 30000;
+export declare const DEFAULT_STARTUP_GRACE_MS = 60000;
+export declare const DEFAULT_RESTART_GIVE_UP_THRESHOLD = 3;
+export declare const DEFAULT_RESTART_COOLDOWN_MS = 5000;
+/** Thrown when a PRESENT registry file cannot be safely parsed/edited. */
+export declare class HivedoctorRegistryError extends Error {
+    constructor(message: string);
+}
+/** The default registry file location, alongside the other `~/.honeycomb` artifacts. */
+export declare function defaultHivedoctorRegistryPath(home?: string): string;
+/**
+ * Build hivenectar's registry entry from its resolved {@link RuntimeConfig}
+ * (PRD-003c table): `healthUrl`/`pidPath` come from hivenectar's own runtime
+ * config (already home-expanded, so no `~` round-trip is needed here); the
+ * remaining fields are hivedoctor's per-daemon defaults unless overridden.
+ *
+ * `telemetryDbPath` (PRD-017a) defaults to `<runtimeDir>/telemetry/hivenectar.sqlite`,
+ * where `runtimeDir` is `pidFilePath`'s own directory - the same resolved
+ * runtime dir every other per-daemon artifact already lives under, so a
+ * test-overridden runtime dir keeps pid/lock/telemetry colocated automatically.
+ */
+export declare function buildHivenectarRegistryEntry(config: Pick<RuntimeConfig, "host" | "port" | "pidFilePath">, overrides?: Partial<Pick<HivedoctorRegistryEntry, "probeIntervalMs" | "startupGraceMs" | "restartGiveUpThreshold" | "restartCooldownMs" | "telemetryDbPath">>): HivedoctorRegistryEntry;
+export interface RegisterWithHivedoctorOptions {
+    /** hivenectar's runtime config (supplies healthUrl + pidPath). */
+    readonly config: Pick<RuntimeConfig, "host" | "port" | "pidFilePath">;
+    /** Override the registry file path (default: {@link defaultHivedoctorRegistryPath}). */
+    readonly registryPath?: string;
+    /** Override the entry's per-daemon fields (default: hivedoctor's built-in defaults). */
+    readonly overrides?: Partial<Pick<HivedoctorRegistryEntry, "probeIntervalMs" | "startupGraceMs" | "restartGiveUpThreshold" | "restartCooldownMs" | "telemetryDbPath">>;
+}
+export interface RegisterWithHivedoctorResult {
+    /** The path the registry file was written to. */
+    readonly registryPath: string;
+    /** The entry that was written for hivenectar. */
+    readonly entry: HivedoctorRegistryEntry;
+    /** True when the registry file did not exist and was created fresh. */
+    readonly created: boolean;
+    /** True when an existing hivenectar entry was replaced (idempotent re-install). */
+    readonly replaced: boolean;
+}
+/**
+ * Append (or idempotently replace) hivenectar's entry in hivedoctor's registry
+ * file (PRD-003c US-003c.1). Every OTHER daemon's entry is preserved unchanged.
+ * Does NOT restart hivedoctor and does NOT touch anything besides this one file -
+ * the entry takes effect at hivedoctor's next natural boot (PRD-003c Non-Goals).
+ */
+export declare function registerWithHivedoctor(options: RegisterWithHivedoctorOptions): RegisterWithHivedoctorResult;
+//# sourceMappingURL=hivedoctor-registry.d.ts.map