@legioncodeinc/nectar 0.0.1

package/dist/registration/review-cli.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `nectar review-matches` command logic (PRD-006d AC-18).
+ *
+ * Lists the pending low-confidence step-4 candidates (new path <-> candidate
+ * missing nectar, with confidence / TLSH distance and a diff preview) and lets
+ * the operator accept or reject each:
+ *   - accept -> carry the candidate nectar onto the new path (as a
+ *     high-confidence step 4 would have) and drop the pending entry;
+ *   - reject -> leave the new path minted fresh (it already was, at review time)
+ *     and the missing entry in the set; drop the pending entry;
+ *   - skip  -> leave the entry for a later review.
+ *
+ * DELIBERATE SPEC GAP (AC-18): the accept/reject interaction defaults to
+ * interactive (list -> choose -> confirm). This module takes the per-candidate
+ * decision through an injected `decide` seam so the interactive prompt (wired in
+ * the CLI) is the default while tests supply a scripted decider. NO
+ * `--accept`/`--reject`/`--all` flag grammar is invented; the flag surface
+ * remains a flagged implementation decision.
+ */
+import type { HiveGraphStore } from "../hive-graph/store.js";
+import type { Tenancy } from "../hive-graph/model.js";
+import type { PendingReviewStore, PendingReviewCandidate } from "./review-store.js";
+export type ReviewDecision = "accept" | "reject" | "skip";
+export interface ReviewMatchesDeps {
+    readonly store: HiveGraphStore;
+    readonly tenancy: Tenancy;
+    readonly pendingReviews: PendingReviewStore;
+    /** Per-candidate decision. The interactive prompt (default) or a scripted test decider. */
+    decide(candidate: PendingReviewCandidate, preview: string): Promise<ReviewDecision> | ReviewDecision;
+    /** Output sink (stdout in the CLI, a capture in tests). */
+    out(line: string): void;
+    now(): string;
+    onEnrichQueued?(nectar: string): void;
+}
+export interface ReviewMatchesResult {
+    readonly accepted: number;
+    readonly rejected: number;
+    readonly skipped: number;
+    readonly staleDropped: number;
+}
+export declare function runReviewMatches(deps: ReviewMatchesDeps): Promise<ReviewMatchesResult>;
+//# sourceMappingURL=review-cli.d.ts.map

package/dist/registration/review-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-cli.d.ts","sourceRoot":"","sources":["../../src/registration/review-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C,2FAA2F;IAC3F,MAAM,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;IACrG,2DAA2D;IAC3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,IAAI,MAAM,CAAC;IACd,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAgBD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwG5F"}

package/dist/registration/review-cli.js

@@ -0,0 +1,110 @@
+import { inTenancy } from "../hive-graph/model.js";
+import { carryNectar } from "./ladder.js";
+/** Build a short human-readable preview for one candidate. */
+function buildPreview(store, candidate) {
+    const source = store.latestVersion(candidate.candidateNectar);
+    const lastKnownPath = source?.path ?? "(unknown)";
+    const distance = candidate.distance === null ? "n/a" : String(candidate.distance);
+    return [
+        `candidate ${candidate.id}`,
+        `  new path:        ${candidate.newPath}`,
+        `  maybe nectar:    ${candidate.candidateNectar} (last known at ${lastKnownPath})`,
+        `  confidence:      ${candidate.confidence.toFixed(3)}  (distance ${distance})`,
+        `  new content hash: ${candidate.contentHash}`,
+    ].join("\n");
+}
+export async function runReviewMatches(deps) {
+    const items = deps.pendingReviews.list();
+    if (items.length === 0) {
+        deps.out("No pending matches to review.");
+        return { accepted: 0, rejected: 0, skipped: 0, staleDropped: 0 };
+    }
+    let accepted = 0;
+    let rejected = 0;
+    let skipped = 0;
+    let staleDropped = 0;
+    for (const candidate of items) {
+        const preview = buildPreview(deps.store, candidate);
+        deps.out(preview);
+        const decision = await deps.decide(candidate, preview);
+        switch (decision) {
+            case "accept": {
+                // Verify the candidate nectar exists AND is in this tenancy before carrying;
+                // an accept must never re-associate a nectar from another project (AC-20).
+                const identity = deps.store.getIdentity(candidate.candidateNectar);
+                if (identity === undefined || !inTenancy(identity, deps.tenancy)) {
+                    deps.pendingReviews.remove(candidate.id);
+                    deps.out(`candidate ${candidate.candidateNectar} is not in scope; dropped stale review`);
+                    staleDropped += 1;
+                    break;
+                }
+                // Stale-content guard (PRD-018d NEC-036, AC-018d.8): the candidate's
+                // `contentHash` is a snapshot taken when the review was raised. If the
+                // placeholder mint (`mintedNectar`) has since seen a further edit at
+                // `newPath` (a step-2 append onto that SAME identity, keyed by path),
+                // its latest content hash no longer matches what was queued, so the
+                // recorded hash/size/mtime metadata this accept would carry onto the
+                // identity is outdated. Resolve as stale instead of carrying it.
+                // Checked against the mintedNectar's own version (not "whatever is
+                // currently at newPath") so it is precise even when mintedNectar is a
+                // synthetic id in a test fixture that was never actually minted (in
+                // which case there is nothing to compare and the accept proceeds).
+                const mintedVersion = deps.store.latestVersion(candidate.mintedNectar);
+                if (mintedVersion !== undefined && mintedVersion.contentHash !== candidate.contentHash) {
+                    deps.pendingReviews.remove(candidate.id);
+                    deps.out(`candidate ${candidate.candidateNectar} is stale (content at ${candidate.newPath} changed since queued); dropped stale review`);
+                    staleDropped += 1;
+                    break;
+                }
+                const carried = carryNectar(deps.store, deps.tenancy, deps.now(), candidate.candidateNectar, {
+                    relPath: candidate.newPath,
+                    contentHash: candidate.contentHash,
+                    sizeBytes: candidate.sizeBytes,
+                    mtimeObserved: candidate.mtimeObserved,
+                }, candidate.confidence);
+                deps.pendingReviews.remove(candidate.id);
+                if (carried) {
+                    // Retire the placeholder nectar the ladder minted for newPath at review
+                    // time, so exactly one identity (the carried one) points at newPath and
+                    // there is no duplicate. Only when the carry succeeded, and only for a
+                    // real, in-scope mint that is not the carried nectar itself. The
+                    // tenancy-scoped delete is the sole deletion path.
+                    let retiredNote = "";
+                    const minted = candidate.mintedNectar;
+                    if (minted !== "" && minted !== candidate.candidateNectar) {
+                        const mintIdentity = deps.store.getIdentity(minted);
+                        if (mintIdentity !== undefined && inTenancy(mintIdentity, deps.tenancy)) {
+                            deps.store.deleteNectar(deps.tenancy, minted);
+                            retiredNote = `; retired placeholder mint ${minted}`;
+                        }
+                    }
+                    deps.onEnrichQueued?.(candidate.candidateNectar);
+                    deps.out(`accepted: carried ${candidate.candidateNectar} to ${candidate.newPath}${retiredNote}`);
+                    accepted += 1;
+                }
+                else {
+                    deps.out(`candidate ${candidate.candidateNectar} no longer exists; dropped stale review`);
+                    staleDropped += 1;
+                }
+                break;
+            }
+            case "reject": {
+                deps.pendingReviews.remove(candidate.id);
+                deps.out(`rejected: ${candidate.newPath} keeps its fresh nectar ${candidate.mintedNectar}`);
+                rejected += 1;
+                break;
+            }
+            case "skip": {
+                deps.out(`skipped: ${candidate.newPath} left for later review`);
+                skipped += 1;
+                break;
+            }
+            default: {
+                const _exhaustive = decision;
+                return _exhaustive;
+            }
+        }
+    }
+    return { accepted, rejected, skipped, staleDropped };
+}
+//# sourceMappingURL=review-cli.js.map

package/dist/registration/review-cli.js.map

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

package/dist/registration/review-store.d.ts

@@ -0,0 +1,73 @@
+/** One unreviewed step-4 candidate. Carries everything an accept needs so no disk re-read is required. */
+export interface PendingReviewCandidate {
+    /** Stable id (a minted ULID) so accept/reject can target one entry. */
+    readonly id: string;
+    /** The candidate MISSING nectar the new path may be. */
+    readonly candidateNectar: string;
+    /** The new path (already minted fresh at review time). */
+    readonly newPath: string;
+    readonly confidence: number;
+    readonly distance: number | null;
+    /** The new file's content hash + metadata, so accept can carry without reading disk. */
+    readonly contentHash: string;
+    readonly sizeBytes: number;
+    readonly mtimeObserved: string;
+    /** The fresh nectar minted for `newPath` when the candidate was raised. */
+    readonly mintedNectar: string;
+    readonly createdAt: string;
+}
+export interface PendingReviewStore {
+    add(candidate: PendingReviewCandidate): void;
+    list(): PendingReviewCandidate[];
+    remove(id: string): void;
+}
+export declare class InMemoryPendingReviewStore implements PendingReviewStore {
+    private readonly items;
+    /**
+     * Dedupe/replace by `(candidateNectar, newPath)` (PRD-018d NEC-036/AC-18d.7):
+     * a re-observation of the same target while a candidate for it is already
+     * pending refreshes that candidate in place instead of appending a sibling,
+     * so the queue never grows per re-observation of one path.
+     */
+    add(candidate: PendingReviewCandidate): void;
+    list(): PendingReviewCandidate[];
+    remove(id: string): void;
+}
+/** A JSON-file-backed pending-review queue in the daemon runtime dir. Fail-open on a malformed/missing file. */
+export declare class FilePendingReviewStore implements PendingReviewStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    /** Sibling lock file guarding the read-modify-write critical section in `add`/`remove`. */
+    private lockPath;
+    private read;
+    /**
+     * Atomic write: serialize to a unique temp file in the same directory, then
+     * `renameSync` it over the target (atomic on the same filesystem). A reader
+     * therefore never sees a torn/partial file, and two concurrent writers cannot
+     * interleave bytes (last rename wins). This queue is ephemeral, last-write-wins
+     * operational state (not durable domain state, which lives in Deep Lake, FR-8).
+     * `write()` on its own only guarantees atomicity (no torn file); it is the
+     * callers `add`/`remove` that additionally guarantee no LOST update, by
+     * holding {@link acquireFileLock} across their whole read-then-write
+     * (PRD-018d AC-018d.6). The temp file is cleaned up on failure.
+     */
+    private write;
+    /**
+     * Serialized (PRD-018d AC-018d.6) read-modify-write: the advisory lock makes
+     * this critical section mutually exclusive with any other `add`/`remove`
+     * call on the same file, from this process or another, so a daemon `add()`
+     * racing a CLI `remove()` can no longer resurrect a resolved candidate or
+     * silently drop a fresh one (M5) - whichever call wins the lock re-reads
+     * AFTER acquiring it, so it always sees the other's already-applied write.
+     *
+     * Also dedupes/replaces by `(candidateNectar, newPath)` (AC-018d.7): a
+     * re-observation of the same target refreshes the existing candidate in
+     * place rather than appending a sibling, so the queue does not grow per
+     * re-observation of one path (M6).
+     */
+    add(candidate: PendingReviewCandidate): void;
+    list(): PendingReviewCandidate[];
+    /** Serialized (PRD-018d AC-018d.6) the same way as {@link add}. */
+    remove(id: string): void;
+}
+//# sourceMappingURL=review-store.d.ts.map

package/dist/registration/review-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-store.d.ts","sourceRoot":"","sources":["../../src/registration/review-store.ts"],"names":[],"mappings":"AAsBA,0GAA0G;AAC1G,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7C,IAAI,IAAI,sBAAsB,EAAE,CAAC;IACjC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,qBAAa,0BAA2B,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;IAEnE;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI;IAa5C,IAAI,IAAI,sBAAsB,EAAE;IAIhC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAGzB;AAqGD,gHAAgH;AAChH,qBAAa,sBAAuB,YAAW,kBAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAE7C,2FAA2F;IAC3F,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,IAAI;IAiBZ;;;;;;;;;;OAUG;IACH,OAAO,CAAC,KAAK;IAiBb;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI;IAc5C,IAAI,IAAI,sBAAsB,EAAE;IAIhC,mEAAmE;IACnE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CASzB"}

package/dist/registration/review-store.js

@@ -0,0 +1,243 @@
+/**
+ * The pending-candidate surface for `review-matches` (PRD-006d AC-18).
+ *
+ * The settled handler writes a low-confidence step-4 candidate here (via
+ * `onReviewNeeded`); the `review-matches` command reads them back, lets the
+ * operator accept (carry the nectar) or reject (leave the fresh mint), and
+ * removes each as it is resolved.
+ *
+ * Two implementations:
+ *   - {@link InMemoryPendingReviewStore}: the in-process surface the running
+ *     daemon and the tests use.
+ *   - {@link FilePendingReviewStore}: a JSON file under the daemon runtime dir so
+ *     a separate `review-matches` CLI process can see candidates a daemon queued.
+ *     This is an ephemeral operational queue (like the PID/lock files that share
+ *     the runtime dir), NOT durable domain state, so it does not conflict with
+ *     the Deep-Lake-is-the-only-durable-store rule (FR-8): the durable nectar
+ *     rows live in Deep Lake; this file only tracks unreviewed candidates.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+export class InMemoryPendingReviewStore {
+    items = new Map();
+    /**
+     * Dedupe/replace by `(candidateNectar, newPath)` (PRD-018d NEC-036/AC-18d.7):
+     * a re-observation of the same target while a candidate for it is already
+     * pending refreshes that candidate in place instead of appending a sibling,
+     * so the queue never grows per re-observation of one path.
+     */
+    add(candidate) {
+        for (const [id, existing] of this.items) {
+            if (id !== candidate.id &&
+                existing.candidateNectar === candidate.candidateNectar &&
+                existing.newPath === candidate.newPath) {
+                this.items.delete(id);
+            }
+        }
+        this.items.set(candidate.id, { ...candidate });
+    }
+    list() {
+        return [...this.items.values()].map((c) => ({ ...c }));
+    }
+    remove(id) {
+        this.items.delete(id);
+    }
+}
+function isCandidate(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const c = value;
+    return (typeof c["id"] === "string" &&
+        typeof c["candidateNectar"] === "string" &&
+        typeof c["newPath"] === "string" &&
+        typeof c["confidence"] === "number" &&
+        (c["distance"] === null || typeof c["distance"] === "number") &&
+        typeof c["contentHash"] === "string" &&
+        typeof c["sizeBytes"] === "number" &&
+        typeof c["mtimeObserved"] === "string" &&
+        typeof c["mintedNectar"] === "string" &&
+        typeof c["createdAt"] === "string");
+}
+/** How long an `add()`/`remove()` waits for the advisory lock before giving up. */
+const LOCK_MAX_WAIT_MS = 5000;
+/** Poll interval while waiting for the advisory lock. */
+const LOCK_RETRY_DELAY_MS = 5;
+/**
+ * A lock file whose mtime is older than this is presumed abandoned by a
+ * crashed holder (CodeRabbit PR-18 finding #4): a crash between
+ * {@link acquireFileLock} and the caller's `finally` release used to leave
+ * `${filePath}.lock` behind forever, wedging every later `add()`/`remove()`
+ * to the full {@link LOCK_MAX_WAIT_MS} timeout. A live holder's critical
+ * section (a small JSON read-modify-write) always finishes well within
+ * `LOCK_MAX_WAIT_MS`; 3x that gives comfortable headroom over the slowest
+ * legitimate hold (another racer's full wait plus its own critical section)
+ * before this reclaims the lock as abandoned.
+ */
+const LOCK_STALE_MS = LOCK_MAX_WAIT_MS * 3;
+/** A synchronous, event-loop-blocking sleep (Node allows `Atomics.wait` on the main thread; browsers do not). */
+function sleepSyncMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Acquire an advisory, exclusive-create file lock at `lockPath`, blocking
+ * (synchronously) until it is free or `LOCK_MAX_WAIT_MS` elapses. Mirrors the
+ * daemon's single-instance lock's exclusive-create-is-the-atomic-winner-picker
+ * idiom (`lock.ts` `acquireSingleInstanceLock`), scaled down to a short-lived
+ * critical section instead of a whole-process-lifetime lock: unlike the daemon
+ * lock, this one carries no owner identity and is never force-reclaimed, so
+ * two racing holders can never both believe they hold it (PRD-018d NEC-036 /
+ * AC-018d.6 - this is what turns the read-modify-write in {@link
+ * FilePendingReviewStore.add}/{@link FilePendingReviewStore.remove} into a
+ * SERIALIZED critical section across the daemon and the `review-matches` CLI,
+ * the store's stated two-writer use case).
+ */
+/** True when `lockPath`'s mtime is older than {@link LOCK_STALE_MS} (an abandoned lock). False when it no longer exists (the caller's ENOENT race: another process reclaimed first). */
+function isLockStale(lockPath) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return false; // gone already; the create-retry below will settle it
+    }
+}
+function acquireFileLock(lockPath) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + LOCK_MAX_WAIT_MS;
+    for (;;) {
+        try {
+            closeSync(openSync(lockPath, "wx"));
+            return;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // CodeRabbit PR-18 finding #4: reclaim an abandoned lock by mtime instead
+            // of waiting out the full timeout behind it every time.
+            if (isLockStale(lockPath)) {
+                try {
+                    rmSync(lockPath);
+                }
+                catch (rmErr) {
+                    // ENOENT: another process reclaimed it first between our stat and
+                    // our rm; anything else is a real filesystem problem.
+                    if (rmErr.code !== "ENOENT")
+                        throw rmErr;
+                }
+                continue; // re-attempt the exclusive create immediately
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`timed out waiting for the pending-review lock at ${lockPath}`);
+            }
+            sleepSyncMs(LOCK_RETRY_DELAY_MS);
+        }
+    }
+}
+/** Release the advisory lock. Never throws (a missing lock on release is fine; the goal already holds). */
+function releaseFileLock(lockPath) {
+    try {
+        rmSync(lockPath, { force: true });
+    }
+    catch {
+        // best-effort; nothing more to do if removal itself fails
+    }
+}
+/** A JSON-file-backed pending-review queue in the daemon runtime dir. Fail-open on a malformed/missing file. */
+export class FilePendingReviewStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** Sibling lock file guarding the read-modify-write critical section in `add`/`remove`. */
+    lockPath() {
+        return `${this.filePath}.lock`;
+    }
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, "utf8");
+        }
+        catch {
+            return [];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(isCandidate);
+    }
+    /**
+     * Atomic write: serialize to a unique temp file in the same directory, then
+     * `renameSync` it over the target (atomic on the same filesystem). A reader
+     * therefore never sees a torn/partial file, and two concurrent writers cannot
+     * interleave bytes (last rename wins). This queue is ephemeral, last-write-wins
+     * operational state (not durable domain state, which lives in Deep Lake, FR-8).
+     * `write()` on its own only guarantees atomicity (no torn file); it is the
+     * callers `add`/`remove` that additionally guarantee no LOST update, by
+     * holding {@link acquireFileLock} across their whole read-then-write
+     * (PRD-018d AC-018d.6). The temp file is cleaned up on failure.
+     */
+    write(items) {
+        const dir = dirname(this.filePath);
+        mkdirSync(dir, { recursive: true });
+        const tmp = join(dir, `${basename(this.filePath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+        try {
+            writeFileSync(tmp, `${JSON.stringify(items, null, 2)}\n`, "utf8");
+            renameSync(tmp, this.filePath);
+        }
+        catch (err) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                // best-effort cleanup; surface the original write error below
+            }
+            throw err;
+        }
+    }
+    /**
+     * Serialized (PRD-018d AC-018d.6) read-modify-write: the advisory lock makes
+     * this critical section mutually exclusive with any other `add`/`remove`
+     * call on the same file, from this process or another, so a daemon `add()`
+     * racing a CLI `remove()` can no longer resurrect a resolved candidate or
+     * silently drop a fresh one (M5) - whichever call wins the lock re-reads
+     * AFTER acquiring it, so it always sees the other's already-applied write.
+     *
+     * Also dedupes/replaces by `(candidateNectar, newPath)` (AC-018d.7): a
+     * re-observation of the same target refreshes the existing candidate in
+     * place rather than appending a sibling, so the queue does not grow per
+     * re-observation of one path (M6).
+     */
+    add(candidate) {
+        const lockPath = this.lockPath();
+        acquireFileLock(lockPath);
+        try {
+            const items = this.read().filter((c) => c.id !== candidate.id && !(c.candidateNectar === candidate.candidateNectar && c.newPath === candidate.newPath));
+            items.push({ ...candidate });
+            this.write(items);
+        }
+        finally {
+            releaseFileLock(lockPath);
+        }
+    }
+    list() {
+        return this.read();
+    }
+    /** Serialized (PRD-018d AC-018d.6) the same way as {@link add}. */
+    remove(id) {
+        const lockPath = this.lockPath();
+        acquireFileLock(lockPath);
+        try {
+            this.write(this.read().filter((c) => c.id !== id));
+        }
+        finally {
+            releaseFileLock(lockPath);
+        }
+    }
+}
+//# sourceMappingURL=review-store.js.map

package/dist/registration/review-store.js.map

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