@legioncodeinc/nectar 0.0.1

package/dist/enricher/store-adapter.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A durable-backed {@link EnricherStore} for the daemon's enricher loop (PRD-016
+ * daemon wiring, hardened by PRD-018g).
+ *
+ * The enricher cycle consumes the SYNCHRONOUS reads of the {@link EnricherStore}
+ * seam (`store.ts`): `listPendingWork`, `countPending`, `getVersion`,
+ * `listVersions`, `priorDescribedVersion`, and the mirror-only `updateVersion`
+ * are all called with no `await` inside `runEnricherCycle`. The durable substrate
+ * (`DeepLakeHiveGraphStore`) is asynchronous, so a store cannot honor the sync
+ * read contract AND do real HTTP I/O at the same time - the exact sync/async
+ * split documented on `AsyncHiveGraphStore` (`hive-graph/store.ts`).
+ *
+ * This adapter bridges the two by holding an in-memory mirror
+ * ({@link EnricherInMemoryStore}) as the working set the cycle reads from, and:
+ *
+ *   - **Durable describe write-back is a VERSION-BUMP APPEND (PRD-018g / NEC-017,
+ *     user-confirmed decision).** `commitVersion` appends a NEW row at `seq+1`
+ *     carrying the description through the injected {@link EnricherHydrateSeam}
+ *     `appendVersion` (collision-safe seq allocation), and is AWAITED by the
+ *     cycle: only on a CONFIRMED durable write does the mirror gain the described
+ *     row (so the latest-is-pending selector stops re-selecting the nectar) and
+ *     the cycle count the file. On failure the mirror is untouched (the nectar
+ *     stays selectable) and `commitVersion` resolves `false`. The retired
+ *     fire-and-forget in-place `UPDATE` (`sql-update.ts`) is no longer used.
+ *
+ *   - **Mirror-only status patches** (`failed`, `skipped-deleted`) go through
+ *     `updateVersion` and write ONLY the mirror: the durable row stays `pending`,
+ *     so a failed row is re-selected after a restart re-hydrates.
+ *
+ *   - **Working-set freshness (PRD-018g / NEC-016):** `refresh` re-seeds the
+ *     mirror from the durable store so version rows appended after boot (a
+ *     `POST /build` brood's `failed`/`pending` rows, teammate-synced rows, the
+ *     watcher's appends) become visible without a daemon restart.
+ */
+import type { HiveGraphVersionRow, Tenancy } from "../hive-graph/model.js";
+import type { PortableProjection } from "../projection/format.js";
+import { type EnricherStore, type EnricherWorkItem } from "./store.js";
+/** The async seams the durable adapter needs: load a tenancy's rows, and append one row back. */
+export interface EnricherHydrateSeam {
+    /** Load EVERY version row for the tenancy (full history, not latest-per-nectar) to seed the mirror. */
+    loadVersions(tenancy: Tenancy): Promise<readonly HiveGraphVersionRow[]>;
+    /**
+     * Durably append `row` as a version-bump at the next collision-safe seq for
+     * its nectar (PRD-018g / NEC-017), resolving the seq actually written. Wired
+     * to `DeepLakeHiveGraphStore.appendVersionAtNextSeq`.
+     */
+    appendVersion(row: HiveGraphVersionRow): Promise<number>;
+    /** Optional fail-soft sink for a durable append rejection (default: swallow). */
+    onWriteBackError?(err: unknown): void;
+}
+/**
+ * A {@link EnricherStore} backed by an in-memory mirror with durable
+ * version-bump append. Construct, `await hydrate(tenancy)` once before starting
+ * the loop (and `refresh(tenancy)` periodically), then hand it to
+ * `createEnricherLoop`.
+ */
+export declare class DeepLakeEnricherStore implements EnricherStore {
+    private readonly mirror;
+    private readonly seam;
+    private hydrated;
+    constructor(seam: EnricherHydrateSeam);
+    /** Seed the mirror from the durable store. Idempotent; a second call re-seeds. */
+    hydrate(tenancy: Tenancy): Promise<void>;
+    /**
+     * Re-seed the mirror from the durable store so post-boot rows become visible
+     * without a restart (PRD-018g / NEC-016 AC-018g.6). Fail-soft: a load failure
+     * is routed to the write-back error sink and leaves the mirror unchanged.
+     */
+    refresh(tenancy: Tenancy): Promise<void>;
+    /** True once {@link hydrate} has seeded the mirror at least once. */
+    get isHydrated(): boolean;
+    listPendingWork(tenancy: Tenancy, batchSize: number): EnricherWorkItem[];
+    countPending(tenancy: Tenancy): number;
+    getVersion(nectar: string, seq: number): HiveGraphVersionRow | undefined;
+    listVersions(nectar: string): readonly HiveGraphVersionRow[];
+    priorDescribedVersion(nectar: string, beforeSeq: number): HiveGraphVersionRow | undefined;
+    /** Mirror-only status patch (failed / skipped-deleted); no durable write (NEC-017). */
+    updateVersion(row: HiveGraphVersionRow): void;
+    /**
+     * Durable version-bump append (PRD-018g / NEC-017 AC-018g.7/.8): append the
+     * described row at the next collision-safe seq, and ONLY on a confirmed durable
+     * write add it to the mirror (so the nectar drops out of the latest-is-pending
+     * selection). A durable failure leaves the mirror untouched - the nectar's
+     * latest stays `pending` and is re-selected next cycle - and resolves `false`.
+     */
+    commitVersion(row: HiveGraphVersionRow): Promise<boolean>;
+    /**
+     * Build a portable projection document from the mirror's latest-described rows
+     * (PRD-018g / NEC-031 trigger #2). Identity rows are synthesized from the
+     * version rows (nectar + tenancy), which is all the projection generator needs;
+     * derived-from provenance is not carried in the enricher mirror and defaults to
+     * absent (a steady-state description update never changes fork provenance).
+     */
+    buildProjectionDoc(tenancy: Tenancy): PortableProjection;
+    private mirrorNectars;
+    private latestDescribed;
+}
+//# sourceMappingURL=store-adapter.d.ts.map

package/dist/enricher/store-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-adapter.d.ts","sourceRoot":"","sources":["../../src/enricher/store-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAgB,mBAAmB,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAIzF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAyB,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9F,iGAAiG;AACjG,MAAM,WAAW,mBAAmB;IAClC,uGAAuG;IACvG,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACxE;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,iFAAiF;IACjF,gBAAgB,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CACvC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,mBAAmB;IAIrC,kFAAkF;IAC5E,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,qEAAqE;IACrE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAIxE,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAItC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIxE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IAI5D,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIzF,uFAAuF;IACvF,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;IAI7C;;;;;;OAMG;IACG,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB;IAUxD,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,eAAe;CAWxB"}

package/dist/enricher/store-adapter.js

@@ -0,0 +1,129 @@
+import { nectarCreatedAt } from "../hive-graph/ulid.js";
+import { buildProjection } from "../projection/generate.js";
+import { EnricherInMemoryStore } from "./store.js";
+/**
+ * A {@link EnricherStore} backed by an in-memory mirror with durable
+ * version-bump append. Construct, `await hydrate(tenancy)` once before starting
+ * the loop (and `refresh(tenancy)` periodically), then hand it to
+ * `createEnricherLoop`.
+ */
+export class DeepLakeEnricherStore {
+    mirror = new EnricherInMemoryStore();
+    seam;
+    hydrated = false;
+    constructor(seam) {
+        this.seam = seam;
+    }
+    /** Seed the mirror from the durable store. Idempotent; a second call re-seeds. */
+    async hydrate(tenancy) {
+        const rows = await this.seam.loadVersions(tenancy);
+        this.mirror.seedVersions(rows);
+        this.hydrated = true;
+    }
+    /**
+     * Re-seed the mirror from the durable store so post-boot rows become visible
+     * without a restart (PRD-018g / NEC-016 AC-018g.6). Fail-soft: a load failure
+     * is routed to the write-back error sink and leaves the mirror unchanged.
+     */
+    async refresh(tenancy) {
+        try {
+            const rows = await this.seam.loadVersions(tenancy);
+            this.mirror.seedVersions(rows);
+        }
+        catch (err) {
+            this.seam.onWriteBackError?.(err);
+        }
+    }
+    /** True once {@link hydrate} has seeded the mirror at least once. */
+    get isHydrated() {
+        return this.hydrated;
+    }
+    listPendingWork(tenancy, batchSize) {
+        return this.mirror.listPendingWork(tenancy, batchSize);
+    }
+    countPending(tenancy) {
+        return this.mirror.countPending(tenancy);
+    }
+    getVersion(nectar, seq) {
+        return this.mirror.getVersion(nectar, seq);
+    }
+    listVersions(nectar) {
+        return this.mirror.listVersions(nectar);
+    }
+    priorDescribedVersion(nectar, beforeSeq) {
+        return this.mirror.priorDescribedVersion(nectar, beforeSeq);
+    }
+    /** Mirror-only status patch (failed / skipped-deleted); no durable write (NEC-017). */
+    updateVersion(row) {
+        this.mirror.updateVersion(row);
+    }
+    /**
+     * Durable version-bump append (PRD-018g / NEC-017 AC-018g.7/.8): append the
+     * described row at the next collision-safe seq, and ONLY on a confirmed durable
+     * write add it to the mirror (so the nectar drops out of the latest-is-pending
+     * selection). A durable failure leaves the mirror untouched - the nectar's
+     * latest stays `pending` and is re-selected next cycle - and resolves `false`.
+     */
+    async commitVersion(row) {
+        try {
+            const seq = await this.seam.appendVersion(row);
+            this.mirror.seedVersion({ ...row, seq });
+            return true;
+        }
+        catch (err) {
+            this.seam.onWriteBackError?.(err);
+            return false;
+        }
+    }
+    /**
+     * Build a portable projection document from the mirror's latest-described rows
+     * (PRD-018g / NEC-031 trigger #2). Identity rows are synthesized from the
+     * version rows (nectar + tenancy), which is all the projection generator needs;
+     * derived-from provenance is not carried in the enricher mirror and defaults to
+     * absent (a steady-state description update never changes fork provenance).
+     */
+    buildProjectionDoc(tenancy) {
+        const sources = [];
+        for (const nectar of this.mirrorNectars()) {
+            const described = this.latestDescribed(nectar, tenancy);
+            if (described === undefined)
+                continue;
+            sources.push({ identity: synthesizeIdentity(described), version: described });
+        }
+        return buildProjection(tenancy, sources);
+    }
+    mirrorNectars() {
+        // listVersions works per nectar; enumerate via the mirror's pending+described
+        // reach by scanning through a wide pending call is not enough, so expose the
+        // set from the mirror directly.
+        return this.mirror.nectars();
+    }
+    latestDescribed(nectar, tenancy) {
+        let best;
+        for (const row of this.mirror.listVersions(nectar)) {
+            if (row.orgId !== tenancy.orgId || row.workspaceId !== tenancy.workspaceId || row.projectId !== tenancy.projectId) {
+                continue;
+            }
+            if (row.describeStatus !== "described")
+                continue;
+            if (best === undefined || row.seq > best.seq)
+                best = row;
+        }
+        return best;
+    }
+}
+/** Synthesize an identity row for a version row (enricher mirror has no identity table). */
+function synthesizeIdentity(version) {
+    return {
+        nectar: version.nectar,
+        kind: "file",
+        createdAt: nectarCreatedAt(version.nectar),
+        derivedFromNectar: "",
+        forkContentHash: "",
+        orgId: version.orgId,
+        workspaceId: version.workspaceId,
+        projectId: version.projectId,
+        lastUpdateDate: version.lastUpdateDate,
+    };
+}
+//# sourceMappingURL=store-adapter.js.map

package/dist/enricher/store-adapter.js.map

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

package/dist/enricher/store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Enricher store seam: pending-work selection + version row updates (PRD-016).
+ */
+import type { HiveGraphVersionRow, Tenancy } from "../hive-graph/model.js";
+export interface EnricherWorkItem {
+    readonly nectar: string;
+    readonly seq: number;
+    readonly row: HiveGraphVersionRow;
+    /** True when retrying a `failed` row solo (PRD-016c). */
+    readonly solo: boolean;
+}
+export interface EnricherStore {
+    listPendingWork(tenancy: Tenancy, batchSize: number): EnricherWorkItem[];
+    countPending(tenancy: Tenancy): number;
+    getVersion(nectar: string, seq: number): HiveGraphVersionRow | undefined;
+    listVersions(nectar: string): readonly HiveGraphVersionRow[];
+    priorDescribedVersion(nectar: string, beforeSeq: number): HiveGraphVersionRow | undefined;
+    /**
+     * Mirror-only, synchronous status patch for a `failed` or `skipped-deleted`
+     * outcome (PRD-018g / NEC-017): updates the in-memory working set in place so
+     * the running cycle sees the new status, WITHOUT a durable write. A failed row
+     * stays `pending` in the durable store so it is re-selected after a restart
+     * (the fire-and-forget in-place durable UPDATE is retired).
+     */
+    updateVersion(row: HiveGraphVersionRow): void;
+    /**
+     * Durable version-bump append for a `described` (or cosmetic-inherited /
+     * re-embedded) row (PRD-018g / NEC-017 AC-018g.7/.8). Appends a NEW row at
+     * `seq+1` carrying the description; `row.seq` is ignored (the store owns seq
+     * allocation, collision-safe). Resolves `true` only when the durable write is
+     * CONFIRMED; on a durable failure it resolves `false`, the working set is left
+     * unchanged (the nectar stays selectable), and the caller must NOT count the
+     * file described.
+     */
+    commitVersion(row: HiveGraphVersionRow): Promise<boolean>;
+}
+/** In-memory enricher store for tests and local dev. */
+export declare class EnricherInMemoryStore implements EnricherStore {
+    /** nectar -> version rows in seq order. */
+    private readonly versions;
+    seedVersion(row: HiveGraphVersionRow): void;
+    seedVersions(rows: readonly HiveGraphVersionRow[]): void;
+    listPendingWork(tenancy: Tenancy, batchSize: number): EnricherWorkItem[];
+    countPending(tenancy: Tenancy): number;
+    getVersion(nectar: string, seq: number): HiveGraphVersionRow | undefined;
+    listVersions(nectar: string): readonly HiveGraphVersionRow[];
+    /** Every nectar with at least one version row in the mirror (projection scan). */
+    nectars(): readonly string[];
+    priorDescribedVersion(nectar: string, beforeSeq: number): HiveGraphVersionRow | undefined;
+    updateVersion(row: HiveGraphVersionRow): void;
+    /**
+     * Version-bump append: allocate `MAX(seq)+1` for the nectar and append `row`
+     * there (PRD-018g / NEC-017). The in-memory store never fails a durable write,
+     * so this always resolves `true`.
+     */
+    commitVersion(row: HiveGraphVersionRow): Promise<boolean>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/enricher/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/enricher/store.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAI3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACzE,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACvC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IACzE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE,CAAC;IAC7D,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAC1F;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC9C;;;;;;;;OAQG;IACH,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,wDAAwD;AACxD,qBAAa,qBAAsB,YAAW,aAAa;IACzD,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IAErE,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;IAU3C,YAAY,CAAC,IAAI,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI;IAIxD,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAkCxE,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAkBtC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAOxE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IAK5D,kFAAkF;IAClF,OAAO,IAAI,SAAS,MAAM,EAAE;IAI5B,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAYzF,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;IAQ7C;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;CAO1D"}

package/dist/enricher/store.js

@@ -0,0 +1,126 @@
+import { inTenancy } from "../hive-graph/model.js";
+import { selectPendingWorkInMemory } from "./pending-query.js";
+/** In-memory enricher store for tests and local dev. */
+export class EnricherInMemoryStore {
+    /** nectar -> version rows in seq order. */
+    versions = new Map();
+    seedVersion(row) {
+        const list = this.versions.get(row.nectar) ?? [];
+        const idx = list.findIndex((v) => v.seq === row.seq);
+        const copy = { ...row };
+        if (idx >= 0)
+            list[idx] = copy;
+        else
+            list.push(copy);
+        list.sort((a, b) => a.seq - b.seq);
+        this.versions.set(row.nectar, list);
+    }
+    seedVersions(rows) {
+        for (const row of rows)
+            this.seedVersion(row);
+    }
+    listPendingWork(tenancy, batchSize) {
+        const flat = [];
+        for (const rows of this.versions.values()) {
+            for (const row of rows) {
+                if (inTenancy(row, tenancy))
+                    flat.push(row);
+            }
+        }
+        const pendingRows = selectPendingWorkInMemory(flat.map((r) => ({
+            nectar: r.nectar,
+            seq: r.seq,
+            describeStatus: r.describeStatus,
+            observedAt: r.observedAt,
+            orgId: r.orgId,
+            workspaceId: r.workspaceId,
+            projectId: r.projectId,
+        })), tenancy, batchSize);
+        const items = [];
+        for (const p of pendingRows) {
+            const row = this.getVersion(p.nectar, p.seq);
+            if (row === undefined)
+                continue;
+            items.push({
+                nectar: p.nectar,
+                seq: p.seq,
+                row,
+                solo: row.describeStatus === "failed",
+            });
+        }
+        return items;
+    }
+    countPending(tenancy) {
+        // Count nectars whose LATEST row is pending/failed, matching the
+        // latest-is-pending selection (PRD-018g / NEC-017) so the depth cannot count
+        // a superseded lower-seq pending row a version-bump append left behind.
+        let count = 0;
+        for (const rows of this.versions.values()) {
+            let latest;
+            for (const row of rows) {
+                if (!inTenancy(row, tenancy))
+                    continue;
+                if (latest === undefined || row.seq > latest.seq)
+                    latest = row;
+            }
+            if (latest !== undefined && (latest.describeStatus === "pending" || latest.describeStatus === "failed")) {
+                count += 1;
+            }
+        }
+        return count;
+    }
+    getVersion(nectar, seq) {
+        const list = this.versions.get(nectar);
+        if (list === undefined)
+            return undefined;
+        const row = list.find((v) => v.seq === seq);
+        return row !== undefined ? { ...row } : undefined;
+    }
+    listVersions(nectar) {
+        const list = this.versions.get(nectar);
+        return list !== undefined ? list.map((v) => ({ ...v })) : [];
+    }
+    /** Every nectar with at least one version row in the mirror (projection scan). */
+    nectars() {
+        return [...this.versions.keys()];
+    }
+    priorDescribedVersion(nectar, beforeSeq) {
+        const list = this.versions.get(nectar);
+        if (list === undefined)
+            return undefined;
+        let best;
+        for (const row of list) {
+            if (row.seq >= beforeSeq)
+                continue;
+            if (row.describeStatus !== "described")
+                continue;
+            if (best === undefined || row.seq > best.seq)
+                best = row;
+        }
+        return best !== undefined ? { ...best } : undefined;
+    }
+    updateVersion(row) {
+        const list = this.versions.get(row.nectar);
+        if (list === undefined)
+            return;
+        const idx = list.findIndex((v) => v.seq === row.seq);
+        if (idx < 0)
+            return;
+        list[idx] = { ...row };
+    }
+    /**
+     * Version-bump append: allocate `MAX(seq)+1` for the nectar and append `row`
+     * there (PRD-018g / NEC-017). The in-memory store never fails a durable write,
+     * so this always resolves `true`.
+     */
+    commitVersion(row) {
+        const list = this.versions.get(row.nectar) ?? [];
+        let max = -1;
+        for (const v of list)
+            if (v.seq > max)
+                max = v.seq;
+        this.seedVersion({ ...row, seq: max + 1 });
+        return Promise.resolve(true);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/enricher/store.js.map

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

package/dist/enricher/tokenize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lightweight language-aware token stream for the meaningful-change heuristic
+ * (PRD-016a). Not a full AST: identifiers, literals, and punctuation are split
+ * into coarse tokens suitable for multiset Jaccard comparison.
+ */
+/** Tokenize source text into a multiset-friendly token list (lowercased). */
+export declare function tokenizeSource(text: string): string[];
+/** Build a multiset frequency map from tokens. */
+export declare function tokenMultiset(tokens: readonly string[]): Map<string, number>;
+//# sourceMappingURL=tokenize.d.ts.map

package/dist/enricher/tokenize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize.d.ts","sourceRoot":"","sources":["../../src/enricher/tokenize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CASrD;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM5E"}

package/dist/enricher/tokenize.js

@@ -0,0 +1,28 @@
+/**
+ * Lightweight language-aware token stream for the meaningful-change heuristic
+ * (PRD-016a). Not a full AST: identifiers, literals, and punctuation are split
+ * into coarse tokens suitable for multiset Jaccard comparison.
+ */
+const TOKEN_RE = /[A-Za-z_][A-Za-z0-9_]*|\d+(?:\.\d+)?|[^\s\w]+/g;
+/** Tokenize source text into a multiset-friendly token list (lowercased). */
+export function tokenizeSource(text) {
+    const tokens = [];
+    const matches = text.match(TOKEN_RE);
+    if (matches === null)
+        return tokens;
+    for (const raw of matches) {
+        const t = raw.trim().toLowerCase();
+        if (t.length > 0)
+            tokens.push(t);
+    }
+    return tokens;
+}
+/** Build a multiset frequency map from tokens. */
+export function tokenMultiset(tokens) {
+    const map = new Map();
+    for (const token of tokens) {
+        map.set(token, (map.get(token) ?? 0) + 1);
+    }
+    return map;
+}
+//# sourceMappingURL=tokenize.js.map

package/dist/enricher/tokenize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize.js","sourceRoot":"","sources":["../../src/enricher/tokenize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,QAAQ,GAAG,gDAAgD,CAAC;AAElE,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,aAAa,CAAC,MAAyB;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error types for the nectar daemon.
+ *
+ * Mirrors honeycomb's `DaemonAlreadyRunningError` contract
+ * (honeycomb/src/daemon/runtime/assemble.ts:672-685) per PRD-002d: a second
+ * `nectar daemon` start throws this BEFORE the socket bind, so port 3854 is
+ * never double-bound. The error carries the PID of the already-running daemon.
+ */
+export declare class DaemonAlreadyRunningError extends Error {
+    readonly existingPid: number;
+    constructor(existingPid: number, lockPath: string);
+}
+/**
+ * Thrown by `start()` when a concurrent `shutdown()` won the race between lock
+ * acquisition and the socket bind completing (daemon-api review M6). The start
+ * unwinds: it closes the socket it just bound and releases the lock it acquired,
+ * so the daemon never ends up listening without holding the lock. The rollback
+ * path treats this as an ordinary start failure.
+ */
+export declare class DaemonStartAbortedError extends Error {
+    constructor();
+}
+/**
+ * Thrown when a runtime configuration value is malformed or out of range
+ * (daemon-api review L6): e.g. `NECTAR_PORT=3854abc` (trailing garbage), a port
+ * outside 1-65535, or a poll interval below the safe floor. Surfaced as a clear
+ * startup error instead of an opaque bind failure or a 1 ms tight poll.
+ */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when `start()` would bind off loopback with {@link allowAllPermission}
+ * as the active gate (PRD-018j / NEC-029): without a real permission gate the API
+ * would be network-reachable with no authentication.
+ */
+export declare class NonLoopbackOpenApiError extends Error {
+    readonly host: string;
+    constructor(host: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAOlD;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAQzB"}

package/dist/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Error types for the nectar daemon.
+ *
+ * Mirrors honeycomb's `DaemonAlreadyRunningError` contract
+ * (honeycomb/src/daemon/runtime/assemble.ts:672-685) per PRD-002d: a second
+ * `nectar daemon` start throws this BEFORE the socket bind, so port 3854 is
+ * never double-bound. The error carries the PID of the already-running daemon.
+ */
+export class DaemonAlreadyRunningError extends Error {
+    existingPid;
+    constructor(existingPid, lockPath) {
+        super(`nectar daemon is already running (pid ${existingPid}); lock held at ${lockPath}`);
+        this.name = "DaemonAlreadyRunningError";
+        this.existingPid = existingPid;
+    }
+}
+/**
+ * Thrown by `start()` when a concurrent `shutdown()` won the race between lock
+ * acquisition and the socket bind completing (daemon-api review M6). The start
+ * unwinds: it closes the socket it just bound and releases the lock it acquired,
+ * so the daemon never ends up listening without holding the lock. The rollback
+ * path treats this as an ordinary start failure.
+ */
+export class DaemonStartAbortedError extends Error {
+    constructor() {
+        super("nectar daemon start was aborted by a concurrent shutdown");
+        this.name = "DaemonStartAbortedError";
+    }
+}
+/**
+ * Thrown when a runtime configuration value is malformed or out of range
+ * (daemon-api review L6): e.g. `NECTAR_PORT=3854abc` (trailing garbage), a port
+ * outside 1-65535, or a poll interval below the safe floor. Surfaced as a clear
+ * startup error instead of an opaque bind failure or a 1 ms tight poll.
+ */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Thrown when `start()` would bind off loopback with {@link allowAllPermission}
+ * as the active gate (PRD-018j / NEC-029): without a real permission gate the API
+ * would be network-reachable with no authentication.
+ */
+export class NonLoopbackOpenApiError extends Error {
+    host;
+    constructor(host) {
+        super(`refusing to start: NECTAR_HOST=${host} binds off loopback but no permission gate is configured; ` +
+            "the API would be reachable without authentication. Use 127.0.0.1 or configure a PermissionGate.");
+        this.name = "NonLoopbackOpenApiError";
+        this.host = host;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,WAAW,CAAS;IAE7B,YAAY,WAAmB,EAAE,QAAgB;QAC/C,KAAK,CACH,yCAAyC,WAAW,mBAAmB,QAAQ,EAAE,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CACH,kCAAkC,IAAI,4DAA4D;YAChG,iGAAiG,CACpG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}