@legioncodeinc/nectar 0.0.1

package/dist/registration/ignore.js

@@ -0,0 +1,249 @@
+/**
+ * The workspace ignore contract for the file-registration intake (PRD-006a),
+ * extended by PRD-018c (NEC-007) into the ONE shared predicate every leg of
+ * the mission consults.
+ *
+ * Nectar does not maintain its own bespoke ignore list. Per PRD-006a
+ * ("Workspace scope and the ignore contract") and brooding-pipeline.md, the
+ * live-watch intake honors the SAME ignore contract the CodeGraph discovery
+ * uses: git-tracked-set semantics plus a per-repo ignore file. The daemon can
+ * later inject the real CodeGraph predicate; this module provides a pragmatic,
+ * dependency-free default so the intake is correct before that wiring lands.
+ *
+ * The default ({@link createDefaultIgnore}):
+ *   - always skips the version-control and dependency dirs every CodeGraph
+ *     discovery skips (`.git/`, `node_modules/`), and the daemon runtime dir
+ *     (`.honeycomb/`) so the projection/lock/pid churn never triggers a cycle,
+ *   - honors a `.honeycomb/graph-ignore.json`-style per-repo ignore file if one
+ *     is present at the workspace root, matching the CodeGraph's own ignore-file
+ *     convention (no nectar-specific list is invented).
+ *
+ * PRD-018c NEC-007 adds {@link createSharedIgnore}: the default UNION
+ * `.gitignore` semantics, so brooding discovery, the watch intake, and the
+ * resync path all exclude exactly the same set (AC-018c.1). Gitignore
+ * semantics are approximated by a cached `git ls-files --cached --others
+ * --exclude-standard` snapshot (the same "tracked + untracked-but-not-ignored"
+ * set brooding discovery already uses), refreshed on resync rather than
+ * spawned per event, with `git check-ignore` as the per-path fallback for a
+ * cache miss (a path created since the last refresh). Git genuinely absent
+ * degrades to the segment/graph-ignore-only default (silent, matches the walk
+ * fallback); git present but ERRORING is surfaced through `onGitError`,
+ * never silently collapsed (NEC-039).
+ *
+ * `isIgnored` takes a repo-relative, forward-slashed path.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+/** Path segments always dropped, independent of any ignore file. */
+export const ALWAYS_IGNORED_SEGMENTS = [".git", "node_modules", ".honeycomb"];
+/** The per-repo ignore file the CodeGraph discovery convention uses (relative to the workspace root). */
+export const GRAPH_IGNORE_FILE = ".honeycomb/graph-ignore.json";
+function normalize(relPath) {
+    // Trim a trailing slash too, so a declared prefix like "dist/" matches "dist"
+    // and "dist/x" whether or not the ignore file wrote the trailing slash.
+    return relPath
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "");
+}
+/** True if any path segment equals one of the always-ignored dir names. */
+function hasIgnoredSegment(relPath) {
+    const segments = relPath.split("/");
+    for (const seg of segments) {
+        if (ALWAYS_IGNORED_SEGMENTS.includes(seg))
+            return true;
+    }
+    return false;
+}
+/**
+ * Read the per-repo ignore file (a JSON array of prefixes, or `{ "ignore": [...] }`).
+ * Missing or malformed files yield an empty list (fail-open to the built-in
+ * segment rules); a hard read error other than "not found" is swallowed so the
+ * intake never crashes on a bad ignore file.
+ */
+export function loadIgnorePrefixes(root, readFile = defaultReadFile) {
+    let raw;
+    try {
+        raw = readFile(join(root, GRAPH_IGNORE_FILE));
+    }
+    catch {
+        return [];
+    }
+    if (raw === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.ignore)
+            ? parsed.ignore
+            : [];
+    return list.filter((entry) => typeof entry === "string" && entry.length > 0).map(normalize);
+}
+function defaultReadFile(p) {
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Build the default ignore predicate for a workspace root. Combines the built-in
+ * segment rules with any prefixes declared in the repo's `graph-ignore.json`.
+ * A path is ignored if it (a) contains an always-ignored segment, or (b) equals
+ * or sits under one of the declared ignore prefixes.
+ */
+export function createDefaultIgnore(root, readFile = defaultReadFile) {
+    const prefixes = loadIgnorePrefixes(root, readFile);
+    return (relPath) => {
+        const p = normalize(relPath);
+        if (p === "")
+            return true;
+        if (hasIgnoredSegment(p))
+            return true;
+        for (const prefix of prefixes) {
+            if (p === prefix || p.startsWith(`${prefix}/`))
+                return true;
+        }
+        return false;
+    };
+}
+// ── PRD-018c NEC-007/NEC-039: the git side of the shared ignore predicate ────
+/** Args for the tracked+untracked-but-not-ignored snapshot (the same set brooding discovery enumerates). */
+const GIT_SNAPSHOT_ARGS = ["ls-files", "--cached", "--others", "--exclude-standard", "-z"];
+/** Guards a pathological repo's `ls-files` output. */
+const GIT_SNAPSHOT_MAX_BUFFER = 64 * 1024 * 1024;
+/** The real `git ls-files` runner: spawns synchronously, never throws. */
+export const runGitLsFiles = (root) => {
+    let res;
+    try {
+        res = spawnSync("git", [...GIT_SNAPSHOT_ARGS], {
+            cwd: root,
+            encoding: "buffer",
+            maxBuffer: GIT_SNAPSHOT_MAX_BUFFER,
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        return { status: "error", reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (res.error !== undefined) {
+        const code = res.error.code;
+        if (code === "ENOENT")
+            return { status: "absent" }; // git not on PATH
+        // ENOBUFS (output exceeded maxBuffer) and any other spawn-level error mean
+        // git IS present but the call itself failed: loud, never silent (NEC-039).
+        return { status: "error", reason: res.error.message };
+    }
+    if (res.status !== 0) {
+        const stderr = Buffer.isBuffer(res.stderr) ? res.stderr.toString("utf8") : String(res.stderr ?? "");
+        if (/not a git repository/i.test(stderr))
+            return { status: "absent" };
+        return { status: "error", reason: stderr.trim() || `git exited with status ${String(res.status)}` };
+    }
+    if (res.stdout === null)
+        return { status: "error", reason: "git ls-files produced no stdout" };
+    const stdout = Buffer.isBuffer(res.stdout) ? res.stdout.toString("utf8") : String(res.stdout);
+    const paths = stdout
+        .split("\0")
+        .map((p) => p.replace(/\\/g, "/"))
+        .filter((p) => p.length > 0);
+    return { status: "ok", paths };
+};
+export const runGitCheckIgnore = (root, relPath) => {
+    let res;
+    try {
+        res = spawnSync("git", ["check-ignore", "-q", "--", relPath], { cwd: root, windowsHide: true });
+    }
+    catch {
+        return null;
+    }
+    if (res.error !== undefined)
+        return null;
+    // check-ignore: exit 0 = ignored, 1 = not ignored, >1 (typically 128) = fatal error.
+    if (res.status === 0)
+        return true;
+    if (res.status === 1)
+        return false;
+    return null;
+};
+/**
+ * Build the ONE shared ignore predicate for a workspace (PRD-018c AC-018c.1):
+ * {@link createDefaultIgnore}'s segments+graph-ignore UNION gitignore
+ * semantics, approximated by a cached `git ls-files` snapshot with a
+ * per-path `git check-ignore` fallback for cache misses. Call {@link
+ * SharedIgnore.refresh} once per resync to keep the snapshot warm without
+ * spawning git on every watch event.
+ */
+export function createSharedIgnore(root, opts = {}) {
+    const base = createDefaultIgnore(root, opts.readFile);
+    const gitLsFiles = opts.gitLsFiles ?? runGitLsFiles;
+    const gitCheckIgnore = opts.gitCheckIgnore ?? runGitCheckIgnore;
+    const onGitError = opts.onGitError ?? (() => { });
+    /** Tracked+untracked-not-ignored snapshot; null when git is absent or no snapshot has ever succeeded. */
+    let eligible = null;
+    let gitAvailable = false;
+    let lastError = null;
+    function refresh() {
+        const probe = gitLsFiles(root);
+        switch (probe.status) {
+            case "ok":
+                eligible = new Set(probe.paths);
+                gitAvailable = true;
+                lastError = null;
+                return;
+            case "absent":
+                eligible = null;
+                gitAvailable = false;
+                lastError = null;
+                return;
+            case "error":
+                // Git IS present but errored (NEC-039): the failure is ALWAYS
+                // surfaced loudly via `onGitError`, regardless of caching. Whether
+                // gitignore semantics stay "available" depends on whether a prior
+                // successful snapshot is still cached: a still-useful (if stale)
+                // snapshot is never abandoned just because the LATEST refresh failed,
+                // but a workspace with no snapshot at all never silently claims full
+                // gitignore coverage by spawning `check-ignore` for every single
+                // path - it degrades to the segment/graph-ignore-only base instead.
+                gitAvailable = eligible !== null;
+                lastError = probe.reason;
+                onGitError(probe.reason);
+                return;
+            default: {
+                const _exhaustive = probe;
+                return _exhaustive;
+            }
+        }
+    }
+    refresh(); // NEC-007 point 1: warm the cache once at construction.
+    function isGitIgnored(relPath) {
+        if (eligible === null)
+            return false; // no usable snapshot (git absent, or errored with nothing cached yet)
+        if (eligible.has(relPath))
+            return false; // definitely NOT ignored
+        // Cache miss against a real (possibly stale) snapshot: either genuinely
+        // ignored, or created since the last refresh. The per-path fallback keeps
+        // this correct without spawning git for every single event (NEC-007
+        // point 1) - it only runs for paths the last known-good snapshot didn't
+        // already resolve.
+        return gitCheckIgnore(root, relPath) === true;
+    }
+    return {
+        isIgnored: (relPath) => base(relPath) || isGitIgnored(relPath),
+        refresh,
+        isGitAvailable: () => gitAvailable,
+        lastGitError: () => lastError,
+    };
+}
+//# sourceMappingURL=ignore.js.map

package/dist/registration/ignore.js.map

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

package/dist/registration/ladder.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The 5-step re-association ladder (PRD-006d), from ai/identity-and-reassociation.md.
+ *
+ * Evaluated top-down per observed file, first match wins:
+ *   1. (path, mtime, size) exact  -> same nectar, no-op (no content read).
+ *   2. path match, content changed -> same nectar, append a version row.
+ *   3. exact content-hash match to a MISSING file -> carry the nectar (move).
+ *   4. TLSH fuzzy match to a missing file above a threshold -> carry, flag confidence;
+ *      below the high band -> surface for review, do NOT claim, fall through to mint.
+ *   5. nothing matches -> mint a fresh nectar (or a copy, with provenance).
+ *
+ * DELIBERATE SPEC GAP preserved: the fuzzy confidence threshold is NOT pinned
+ * here. Step 4 runs only if a `fuzzy` step is injected, and that injected step
+ * owns the (deliberately unpinned, "tuned during brooding") threshold. The ladder
+ * itself hardcodes no number. Nectars are never deleted or reused (pruning is a
+ * separate, explicit operation, `prune --confirm`, PRD-006d / prune-cli.ts).
+ */
+import type { Tenancy } from "../hive-graph/model.js";
+import type { LatestVersion, HiveGraphStore } from "../hive-graph/store.js";
+/** A file observed on disk, ready to feed the ladder. `readContent` is called only when hashing is needed (not on the step-1 fast path). */
+export interface ObservedFile {
+    readonly relPath: string;
+    readonly sizeBytes: number;
+    readonly mtimeObserved: string;
+    readContent(): string | Uint8Array;
+}
+/**
+ * A missing-file candidate the fuzzy step (step 4) consults. It is a superset of
+ * {@link LatestVersion} (so it still carries `.identity` and `.version`, keeping
+ * every existing injected fuzzy step working) plus the missing nectar's latest
+ * TLSH fingerprint. The fingerprint is read from the PERSISTED
+ * `hive_graph_versions.fingerprint` column of the candidate's latest version,
+ * so step 4 can match against a now-gone file without re-reading it AND survive a
+ * daemon restart: this is how the missing-files set "carries each missing
+ * nectar's latest content hash AND its TLSH fingerprint" (PRD-006b AC /
+ * identity-and-reassociation.md Step 3).
+ */
+export interface FuzzyCandidate extends LatestVersion {
+    /** The candidate's latest TLSH fingerprint, or null when none was cached. */
+    readonly fingerprint: string | null;
+}
+/**
+ * The injected fuzzy-match step (step 4). It owns fingerprinting, distance, the
+ * +/-20% size-bucket optimization, and the deliberately-unpinned confidence
+ * threshold. Given the new content and the missing candidates (each carrying a
+ * fingerprint), it returns a confident carry, a low-confidence review, or none.
+ */
+export interface FuzzyStep {
+    match(content: string | Uint8Array, candidates: readonly FuzzyCandidate[]): FuzzyOutcome;
+}
+export type FuzzyOutcome = {
+    readonly kind: "match";
+    readonly nectar: string;
+    readonly confidence: number;
+    readonly distance?: number;
+} | {
+    readonly kind: "review";
+    readonly nectar: string;
+    readonly confidence: number;
+    readonly distance?: number;
+} | {
+    readonly kind: "none";
+};
+/** A low-confidence step-4 candidate surfaced to `review-matches` (AC-18). Carries everything an accept needs. */
+export interface ReviewCandidate {
+    /** The candidate MISSING nectar a human may confirm the new path is. */
+    readonly nectar: string;
+    /** The new path (already minted fresh at review time; accept re-associates it). */
+    readonly relPath: string;
+    readonly confidence: number;
+    readonly distance: number | null;
+    /** The new file's content hash (so accept can append the carried version row without re-reading disk). */
+    readonly contentHash: string;
+    readonly sizeBytes: number;
+    readonly mtimeObserved: string;
+    /** The fresh nectar minted for `relPath` when the review was raised. */
+    readonly mintedNectar: string;
+}
+/**
+ * The fast-path stat cache (PRD-018c NEC-035 / AC-018c.9): a side structure
+ * (never a hive-graph column) recording each path's freshest observed
+ * mtime/size when step 2 finds the content UNCHANGED (a touch, a branch-switch
+ * mtime bump). `hive_graph_versions.mtimeObserved`/`sizeBytes` are documented
+ * as "not authoritative; a fast-path cache key only" (model.ts) - the version
+ * ROW is never rewritten (append-only stays append-only); this cache is the
+ * "cheap side column" the PRD's fix direction offers as the alternative to an
+ * in-place UPDATE, so it carries no PRD-018g NEC-017 precedent. Step 1 prefers
+ * a cache hit over the stored version row's stat so a touch is remembered
+ * without a new version row, keeping the step-1 fast path fast forever
+ * instead of degrading to a full re-hash on every future observation.
+ */
+export interface StatCache {
+    get(relPath: string): {
+        readonly mtimeObserved: string;
+        readonly sizeBytes: number;
+    } | undefined;
+    set(relPath: string, stat: {
+        readonly mtimeObserved: string;
+        readonly sizeBytes: number;
+    }): void;
+    delete(relPath: string): void;
+}
+/** A simple `Map`-backed {@link StatCache}. One instance persists for the lifetime of a `RegistrationService` (across cycles, not across a daemon restart - a restart re-warms via the store's own version-row stat, just without the touch optimization until the next touch). */
+export declare function createInMemoryStatCache(): StatCache;
+export interface LadderDeps {
+    readonly store: HiveGraphStore;
+    readonly tenancy: Tenancy;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    now(): string;
+    /** Whether a repo-relative path currently exists on disk. Distinguishes move (source gone) from copy (source present). */
+    existsOnDisk(relPath: string): boolean;
+    /** Optional step 4. Omit to disable fuzzy matching entirely (then an edited-moved file mints). */
+    readonly fuzzy?: FuzzyStep;
+    /** Called with a low-confidence step-4 candidate (surfaced to `review-matches`); the ladder then mints. */
+    onReviewNeeded?(candidate: ReviewCandidate): void;
+    /** Called when a version row is appended and warrants (re)description. */
+    onEnrichQueued?(nectar: string): void;
+    /**
+     * PRD-018c NEC-035 / AC-018c.9: the fast-path stat cache. Omit to preserve
+     * pre-018c behavior (a step-2 touch is never remembered, so every future
+     * observation re-hashes).
+     */
+    readonly statCache?: StatCache;
+    /**
+     * PRD-018c NEC-034 / AC-018c.8: true when the workspace filesystem is
+     * case-insensitive (probed once per workspace, never guessed from
+     * `process.platform`). Enables the step-3 case-only-rename guard below.
+     * Omit/false preserves pre-018c case-sensitive behavior exactly.
+     */
+    readonly caseInsensitive?: boolean;
+    /**
+     * PRD-018c EX-4 (change-detection review M7): the set of KNOWN paths
+     * currently missing from disk, computed ONCE per resync/settle cycle
+     * (`service.ts`'s `runCycle`) and passed in here so step 4's candidate scan
+     * is an O(1) set lookup instead of an `existsOnDisk` stat per known path per
+     * new file. Omit to fall back to the pre-018c per-candidate `existsOnDisk`
+     * stat (unit tests calling `reassociate` directly need no change).
+     */
+    readonly missingPaths?: ReadonlySet<string>;
+}
+export type LadderStep = 1 | 2 | 3 | 4 | 5;
+export type LadderAction = "noop" | "append-version" | "carry-nectar" | "mint" | "copy";
+export interface LadderResult {
+    readonly step: LadderStep;
+    readonly action: LadderAction;
+    readonly nectar: string;
+}
+/** Run the ladder for one observed file. Returns which step fired and the nectar it resolved to. */
+export declare function reassociate(file: ObservedFile, deps: LadderDeps): LadderResult;
+/**
+ * Carry an existing nectar onto a new path (the `review-matches` accept path,
+ * AC-18): append a carried version row for `sourceNectar` at `target`. Returns
+ * false if the source nectar no longer exists. This is exactly what a
+ * high-confidence step 4 does, applied on human confirmation instead.
+ *
+ * The carried row's `fingerprint` is left NULL here: the accept path works from
+ * the persisted pending-candidate metadata (hash/size/mtime), not the file
+ * content, so there is nothing to fingerprint. It self-heals on the next
+ * observation of the file (a step-2 edit persists a fresh fingerprint), per the
+ * nullable-column contract.
+ */
+export declare function carryNectar(store: HiveGraphStore, tenancy: Tenancy, now: string, sourceNectar: string, target: {
+    relPath: string;
+    contentHash: string;
+    sizeBytes: number;
+    mtimeObserved: string;
+}, confidence: number | null): boolean;
+/**
+ * PRD-018d (NEC-036): the idempotent crash-repair sweep for the ladder's
+ * multi-write actions.
+ *
+ * Every ladder action that mutates the store is a SEQUENCE of two writes
+ * (mint = `insertIdentity` + `appendVersion`; edit/carry = `appendVersion` +
+ * `touchIdentity`; review-accept = carry + `deleteNectar` of the placeholder,
+ * `review-cli.ts`), with no atomicity across a crash between them (the
+ * sync/async store bridge that would let these be one transaction is
+ * PRD-018b's construction, a Non-Goal here). This sweep heals the three
+ * resulting invariant violations instead, and is idempotent: running it again
+ * on an already-healed store finds nothing to do.
+ *
+ *   1. An orphan identity (a mint that crashed after `insertIdentity`, before
+ *      `appendVersion`): zero version rows. There is no content to construct a
+ *      version from, so the only sound repair is deleting the orphan (the same
+ *      `deleteNectar` review-accept already uses to retire a placeholder -
+ *      this sweep is not a new deletion path, just a new caller of the
+ *      existing one). Requires the OPTIONAL `store.listIdentities` (skipped,
+ *      not guessed at, when the adapter omits it).
+ *   2. A stale `identity.lastUpdateDate` (an edit/carry that crashed after
+ *      `appendVersion`, before `touchIdentity`): the identity's timestamp
+ *      predates its own latest version's `lastUpdateDate`, which feeds prune
+ *      eligibility directly (`prune-cli.ts`). Healed by re-running
+ *      `touchIdentity` with the version's own timestamp.
+ *   3. Two identities both claiming one path as their latest version's `path`
+ *      (a review-accept that crashed after the carry landed, before the
+ *      placeholder delete ran): under normal ladder operation a carry only
+ *      ever targets a path with NO existing identity, so this can only be a
+ *      crash artifact. The carried identity's version always has a strictly
+ *      later `observedAt` than the placeholder's original mint, so the
+ *      survivor is the entry with the latest `observedAt`; every other
+ *      claimant is deleted.
+ */
+export declare function repairLadderState(store: HiveGraphStore, tenancy: Tenancy): RepairReport;
+/** What {@link repairLadderState} healed in one sweep pass. */
+export interface RepairReport {
+    readonly healedOrphanIdentities: number;
+    /** Orphan version rows (no matching identity) healed by reconstructing a minimal identity (CodeRabbit PR-18 finding #8). */
+    readonly healedOrphanVersions: number;
+    readonly healedStaleLastUpdate: number;
+    readonly healedDuplicatePaths: number;
+}
+//# sourceMappingURL=ladder.d.ts.map

package/dist/registration/ladder.d.ts.map

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