@legioncodeinc/nectar 0.0.1

package/dist/worker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The hiveantennae worker harness.
+ *
+ * Per PRD-002b the worker is a lease-based harness driving the four operating
+ * modes (brooding / live watch / cold catch-up / projection sync) over a durable
+ * queue. The concrete queue + handlers land with later PRDs (006 re-association,
+ * 007 brooding, 011 projection, 016 enricher); this harness is the real,
+ * testable engine those handlers plug into. It exposes `runOnce()` (the
+ * deterministic unit a test asserts against), `start()`/`stop()` (the continuous
+ * adaptive poll loop), and a pluggable job source so no mode is hardcoded.
+ */
+import { type Timer } from "./poll-loop.js";
+/** nectar's own job kinds (distinct from honeycomb's memory_* kinds). */
+export type JobKind = "brood" | "reassociate" | "enrich" | "projection-sync";
+export interface Job {
+    readonly id: string;
+    readonly kind: JobKind;
+    readonly payload?: unknown;
+}
+/** A handler does the stage's work and returns on success / throws on failure. It never touches the queue. */
+export type JobHandler = (job: Job) => Promise<void> | void;
+/**
+ * The job source the worker leases from. Returns the next runnable job, or null
+ * when nothing is leasable. Later PRDs back this with the durable Deep Lake
+ * queue; tests back it with an in-memory array.
+ */
+export interface JobSource {
+    lease(kinds: readonly JobKind[]): Promise<Job | null> | Job | null;
+    complete(id: string): Promise<void> | void;
+    fail(id: string, reason: string): Promise<void> | void;
+}
+export interface WorkerOptions {
+    readonly source: JobSource;
+    readonly handlers: Partial<Record<JobKind, JobHandler>>;
+    readonly pollIntervalMs: number;
+    readonly ceilingMs?: number;
+    readonly timer?: Timer;
+    readonly onError?: (err: unknown) => void;
+}
+export declare class HiveantennaeWorker {
+    private readonly source;
+    private readonly handlers;
+    private readonly kinds;
+    private readonly loop;
+    private readonly onError;
+    constructor(opts: WorkerOptions);
+    get isRunning(): boolean;
+    /**
+     * Lease exactly one job (filtered to this worker's own kinds), route it to its
+     * handler, and complete/fail through the source. Returns true if a job ran,
+     * false if the queue was idle. A handler throw becomes `source.fail` (never a
+     * swallowed catch); a crash mid-handler leaves the lease for the queue's
+     * reaper (crash-safety, PRD-002b).
+     */
+    runOnce(): Promise<boolean>;
+    /** Start the continuous adaptive poll loop. Idempotent. */
+    start(): void;
+    /** Stop the loop. Idempotent; an in-flight job is allowed to finish. */
+    stop(): void;
+    /**
+     * Resolve once any in-flight job tick has settled. `shutdown()` awaits this
+     * (under a bounded timeout) after `stop()` so an in-flight store/describe write
+     * is drained rather than killed mid-flight (PRD-018a NEC-033).
+     */
+    whenIdle(): Promise<void>;
+}
+/** A no-op job source: leases nothing. The daemon boots with this until the Deep Lake queue (PRD-005/006) lands. */
+export declare const emptyJobSource: JobSource;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAY,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEtD,yEAAyE;AACzE,MAAM,MAAM,OAAO,GACf,OAAO,GACP,aAAa,GACb,QAAQ,GACR,iBAAiB,CAAC;AAEtB,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,8GAA8G;AAC9G,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,IAAI,EAAE,aAAa;IAc/B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IA2BjC,2DAA2D;IAC3D,KAAK,IAAI,IAAI;IAIb,wEAAwE;IACxE,IAAI,IAAI,IAAI;IAIZ;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAED,oHAAoH;AACpH,eAAO,MAAM,cAAc,EAAE,SAI5B,CAAC"}

package/dist/worker.js

@@ -0,0 +1,91 @@
+/**
+ * The hiveantennae worker harness.
+ *
+ * Per PRD-002b the worker is a lease-based harness driving the four operating
+ * modes (brooding / live watch / cold catch-up / projection sync) over a durable
+ * queue. The concrete queue + handlers land with later PRDs (006 re-association,
+ * 007 brooding, 011 projection, 016 enricher); this harness is the real,
+ * testable engine those handlers plug into. It exposes `runOnce()` (the
+ * deterministic unit a test asserts against), `start()`/`stop()` (the continuous
+ * adaptive poll loop), and a pluggable job source so no mode is hardcoded.
+ */
+import { PollLoop } from "./poll-loop.js";
+export class HiveantennaeWorker {
+    source;
+    handlers;
+    kinds;
+    loop;
+    onError;
+    constructor(opts) {
+        this.source = opts.source;
+        this.handlers = opts.handlers;
+        this.kinds = Object.keys(opts.handlers);
+        this.onError = opts.onError ?? (() => { });
+        this.loop = new PollLoop({
+            tick: () => this.runOnce(),
+            floorMs: opts.pollIntervalMs,
+            ceilingMs: opts.ceilingMs,
+            timer: opts.timer,
+            onError: this.onError,
+        });
+    }
+    get isRunning() {
+        return this.loop.isRunning;
+    }
+    /**
+     * Lease exactly one job (filtered to this worker's own kinds), route it to its
+     * handler, and complete/fail through the source. Returns true if a job ran,
+     * false if the queue was idle. A handler throw becomes `source.fail` (never a
+     * swallowed catch); a crash mid-handler leaves the lease for the queue's
+     * reaper (crash-safety, PRD-002b).
+     */
+    async runOnce() {
+        const job = await this.source.lease(this.kinds);
+        if (job === null)
+            return false;
+        const handler = this.handlers[job.kind];
+        if (handler === undefined) {
+            // Foreign/unknown kind: fail loudly rather than silently complete.
+            await this.source.fail(job.id, `no handler for kind '${job.kind}'`);
+            return true;
+        }
+        try {
+            await handler(job);
+        }
+        catch (err) {
+            this.onError(err);
+            const reason = err instanceof Error ? err.message : String(err);
+            await this.source.fail(job.id, reason);
+            return true;
+        }
+        // Completion is deliberately OUTSIDE the handler try: a transient
+        // source.complete() failure is a queue problem, not a job failure. Routing
+        // it to source.fail() after the handler already committed its side effects
+        // could duplicate work or corrupt queue state, so let it propagate instead.
+        await this.source.complete(job.id);
+        return true;
+    }
+    /** Start the continuous adaptive poll loop. Idempotent. */
+    start() {
+        this.loop.start();
+    }
+    /** Stop the loop. Idempotent; an in-flight job is allowed to finish. */
+    stop() {
+        this.loop.stop();
+    }
+    /**
+     * Resolve once any in-flight job tick has settled. `shutdown()` awaits this
+     * (under a bounded timeout) after `stop()` so an in-flight store/describe write
+     * is drained rather than killed mid-flight (PRD-018a NEC-033).
+     */
+    async whenIdle() {
+        await this.loop.whenIdle();
+    }
+}
+/** A no-op job source: leases nothing. The daemon boots with this until the Deep Lake queue (PRD-005/006) lands. */
+export const emptyJobSource = {
+    lease: () => null,
+    complete: () => { },
+    fail: () => { },
+};
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,QAAQ,EAAc,MAAM,gBAAgB,CAAC;AAsCtD,MAAM,OAAO,kBAAkB;IACZ,MAAM,CAAY;IAClB,QAAQ,CAAuC;IAC/C,KAAK,CAAqB;IAC1B,IAAI,CAAW;IACf,OAAO,CAAyB;IAEjD,YAAY,IAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAc,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC;YACvB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE;YAC1B,OAAO,EAAE,IAAI,CAAC,cAAc;YAC5B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAE/B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,mEAAmE;YACnE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,wBAAwB,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;YACpE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,kEAAkE;QAClE,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2DAA2D;IAC3D,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,wEAAwE;IACxE,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;CACF;AAED,oHAAoH;AACpH,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI;IACjB,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;IAClB,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;CACf,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@legioncodeinc/nectar",
+  "version": "0.0.1",
+  "description": "Nectar: a semantic memory layer over a source tree. The hiveantennae daemon mints a stable identity (a nectar) and an LLM-minted description for every file, served through the hybrid recall Honeycomb already uses.",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "//publishConfig": "PRD-001c: minimum fix needed for a valid scoped-package publish, mirroring honeycomb/doctor. `access: public` is required because scoped packages default to restricted; `provenance` pairs with release.yaml's `id-token: write` OIDC identity.",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "nectar": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --experimental-sqlite --test \"test/**/*.test.ts\"",
+    "start": "node --experimental-sqlite dist/cli.js daemon",
+    "daemon": "node --experimental-sqlite dist/cli.js daemon",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "nectar",
+    "honeycomb",
+    "semantic-memory",
+    "code-graph",
+    "daemon"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}