@legioncodeinc/nectar 0.0.1

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

@@ -0,0 +1,133 @@
+/**
+ * The sync/async store bridge (PRD-018b NEC-001).
+ *
+ * The re-association ladder (`ladder.ts`) and the `RegistrationService`
+ * (`service.ts`) are written entirely against the SYNCHRONOUS `HiveGraphStore`
+ * seam: the ladder computes `nextSeq`, reads by path/hash, and appends rows with
+ * no `await` in its control flow. The only durable substrate, Deep Lake
+ * (`deeplake-store.ts`), implements the ASYNC twin `AsyncHiveGraphStore` because
+ * it does real HTTP I/O and cannot honor the synchronous contract. That mismatch
+ * is why the update-on-change pipeline was never wired into the running daemon
+ * (change-detection review C1): even a one-line wiring change was impossible.
+ *
+ * `StoreBridge` closes that gap. It presents the synchronous `HiveGraphStore`
+ * the service consumes, backed by an in-memory mirror (`InMemoryHiveGraphStore`)
+ * so every read the ladder issues is served synchronously and correctly, and it
+ * mirrors each write through to the async durable store in the exact order the
+ * ladder produced them. This is the same shape the brooding path already uses to
+ * reconcile the two interfaces; it is not a new second scheme.
+ *
+ * Three contracts (PRD-018b AC-018b.4):
+ *   - hydration: {@link StoreBridge.hydrate} seeds the mirror from the durable
+ *     store's latest-version-per-nectar (plus identities) at boot, after
+ *     auto-brood settles, so cold catch-up runs against a warm mirror and seq
+ *     numbering continues from the persisted state;
+ *   - write-through ordering: a ladder action applies to the mirror
+ *     synchronously and enqueues the identical durable write onto a single
+ *     serialized queue, so durable writes land in ladder order (never
+ *     interleaved, never reordered);
+ *   - failure surfacing: a durable write that rejects does NOT silently vanish;
+ *     it increments {@link StoreBridge.durableFlushFailures}, records the error,
+ *     and is reported through the injected `onFlushError`. It does not poison the
+ *     queue (later writes still flush) and it never throws back into the
+ *     synchronous ladder (which has already committed the write to the mirror,
+ *     the in-process source of truth). Automatic re-drive of a failed durable
+ *     write is deliberately left to the enricher/brood write-pattern decision
+ *     (PRD-018g) rather than inventing a second scheme here.
+ */
+import type { HiveGraphRow, HiveGraphVersionRow, Tenancy } from "../hive-graph/model.js";
+import type { AsyncHiveGraphStore, HiveGraphStore, LatestVersion } from "../hive-graph/store.js";
+/** The write kinds mirrored through to the durable store, for the failure report label. */
+export type DurableWriteOp = "insertIdentity" | "touchIdentity" | "appendVersion" | "deleteNectar";
+export interface StoreBridgeOptions {
+    /** The durable async store every mirror write is flushed through to (Deep Lake). */
+    readonly durable: AsyncHiveGraphStore;
+    /**
+     * Surfaces a failed durable flush (AC-018b.4). Called once per rejected
+     * durable write with the error and the write kind. The daemon wires this to
+     * `/health` and the log; a failed flush is never silently dropped.
+     */
+    onFlushError?(err: unknown, op: DurableWriteOp): void;
+}
+/**
+ * A synchronous {@link HiveGraphStore} facade over an async durable store. Reads
+ * hit an in-memory mirror; writes apply to the mirror synchronously and are
+ * flushed to the durable store in order. Exposes {@link hydrate} to seed the
+ * mirror and {@link whenFlushed} to await the durable queue draining (used by
+ * the shutdown drain and by tests).
+ */
+export declare class StoreBridge implements HiveGraphStore {
+    private readonly mirror;
+    private readonly durable;
+    private readonly onFlushError;
+    /** The serialized durable-write queue. Every enqueue chains onto this so writes flush in order. */
+    private tail;
+    private pending;
+    private failures;
+    private lastError;
+    /**
+     * Nectars whose durable `insertIdentity` flush has failed (CodeRabbit PR-18
+     * finding #8, layer a). If an identity's durable insert fails but a LATER
+     * `appendVersion`/`touchIdentity`/`deleteNectar` for the same nectar still
+     * flushed durably, `hive_graph_versions` (or a touch) would land with no
+     * matching `hive_graph` row - an orphan the read path can never resolve
+     * (reads join through identities). Every later write for a nectar in this
+     * set is parked (never sent durably) instead, so the orphan is never
+     * created in the first place. Bridge lifetime only; not persisted (a fresh
+     * bridge re-derives it from a fresh `insertIdentity` failure, should one
+     * happen again).
+     */
+    private readonly failedIdentityNectars;
+    constructor(opts: StoreBridgeOptions);
+    /**
+     * Seed the mirror from the durable store's latest-version-per-nectar so the
+     * ladder starts warm (AC-018b.4 hydration): identities and the single latest
+     * version per nectar are enough for every read the ladder issues, and the
+     * mirror's `nextSeq` (MAX(seq)+1) continues correctly from the persisted
+     * seq. Idempotent: a nectar already in the mirror is skipped, so a re-hydrate
+     * never double-appends. Does NOT re-flush anything (the rows are already
+     * durable); it writes only to the mirror.
+     */
+    hydrate(tenancy: Tenancy): Promise<void>;
+    /** Resolves once every durable write enqueued so far has settled (success or surfaced failure). */
+    whenFlushed(): Promise<void>;
+    /** How many durable flushes have failed since construction (surfaced to `/health`). */
+    get durableFlushFailures(): number;
+    /** The most recent durable-flush error, or null when none has failed. */
+    get lastFlushError(): unknown;
+    /** Durable writes enqueued but not yet settled. */
+    get pendingDurableWrites(): number;
+    /**
+     * Chain one durable write onto the serialized queue. The op's rejection is
+     * caught HERE (never rethrown into the synchronous ladder, and never left to
+     * become an unhandled rejection), so the queue keeps draining and every
+     * failure is surfaced exactly once.
+     *
+     * `nectar` is checked against {@link failedIdentityNectars} at RUN time (not
+     * enqueue time): because the queue is strictly serialized, by the time this
+     * op's turn comes up, an earlier `insertIdentity` for the same nectar has
+     * already settled, so the set is guaranteed up to date (CodeRabbit PR-18
+     * finding #8, layer a). Only `appendVersion`/`touchIdentity` are parkable -
+     * they are the writes that would ADD data referencing a still-missing
+     * identity. `deleteNectar` is exempt and always flows through: it is
+     * cleanup, not a write that can orphan anything (the durable `deleteNectar`
+     * contract is itself a no-op when the identity does not exist), and letting
+     * it through is what clears the nectar out of {@link failedIdentityNectars}
+     * again on success.
+     */
+    private enqueue;
+    insertIdentity(row: HiveGraphRow): void;
+    touchIdentity(nectar: string, lastUpdateDate: string): void;
+    appendVersion(row: HiveGraphVersionRow): void;
+    deleteNectar(tenancy: Tenancy, nectar: string): void;
+    getIdentity(nectar: string): HiveGraphRow | undefined;
+    nextSeq(nectar: string): number;
+    latestVersion(nectar: string): HiveGraphVersionRow | undefined;
+    listLatestVersions(tenancy: Tenancy): LatestVersion[];
+    listLatestDescribedVersions(tenancy: Tenancy): LatestVersion[];
+    latestVersionByPath(tenancy: Tenancy, path: string): LatestVersion | undefined;
+    latestVersionByHash(tenancy: Tenancy, contentHash: string): LatestVersion | undefined;
+    listIdentities(tenancy: Tenancy): HiveGraphRow[];
+    listVersionNectars(tenancy: Tenancy): string[];
+}
+//# sourceMappingURL=store-bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-bridge.d.ts","sourceRoot":"","sources":["../../src/registration/store-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGjG,2FAA2F;AAC3F,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,eAAe,GAAG,eAAe,GAAG,cAAc,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC;;;;OAIG;IACH,YAAY,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAAC;CACvD;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAE1E,mGAAmG;IACnG,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAiB;IAClC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;gBAE/C,IAAI,EAAE,kBAAkB;IAKpC;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,mGAAmG;IACnG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,uFAAuF;IACvF,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAED,yEAAyE;IACzE,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,mDAAmD;IACnD,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,OAAO;IAgCf,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAKvC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAK3D,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;IAK7C,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAOpD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIrD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI/B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAI9D,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE;IAIrD,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE;IAI9D,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI9E,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIrF,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,EAAE;IAIhD,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE;CAG/C"}

package/dist/registration/store-bridge.js

@@ -0,0 +1,159 @@
+import { InMemoryHiveGraphStore } from "../hive-graph/memory-store.js";
+/**
+ * A synchronous {@link HiveGraphStore} facade over an async durable store. Reads
+ * hit an in-memory mirror; writes apply to the mirror synchronously and are
+ * flushed to the durable store in order. Exposes {@link hydrate} to seed the
+ * mirror and {@link whenFlushed} to await the durable queue draining (used by
+ * the shutdown drain and by tests).
+ */
+export class StoreBridge {
+    mirror = new InMemoryHiveGraphStore();
+    durable;
+    onFlushError;
+    /** The serialized durable-write queue. Every enqueue chains onto this so writes flush in order. */
+    tail = Promise.resolve();
+    pending = 0;
+    failures = 0;
+    lastError = null;
+    /**
+     * Nectars whose durable `insertIdentity` flush has failed (CodeRabbit PR-18
+     * finding #8, layer a). If an identity's durable insert fails but a LATER
+     * `appendVersion`/`touchIdentity`/`deleteNectar` for the same nectar still
+     * flushed durably, `hive_graph_versions` (or a touch) would land with no
+     * matching `hive_graph` row - an orphan the read path can never resolve
+     * (reads join through identities). Every later write for a nectar in this
+     * set is parked (never sent durably) instead, so the orphan is never
+     * created in the first place. Bridge lifetime only; not persisted (a fresh
+     * bridge re-derives it from a fresh `insertIdentity` failure, should one
+     * happen again).
+     */
+    failedIdentityNectars = new Set();
+    constructor(opts) {
+        this.durable = opts.durable;
+        this.onFlushError = opts.onFlushError ?? (() => { });
+    }
+    /**
+     * Seed the mirror from the durable store's latest-version-per-nectar so the
+     * ladder starts warm (AC-018b.4 hydration): identities and the single latest
+     * version per nectar are enough for every read the ladder issues, and the
+     * mirror's `nextSeq` (MAX(seq)+1) continues correctly from the persisted
+     * seq. Idempotent: a nectar already in the mirror is skipped, so a re-hydrate
+     * never double-appends. Does NOT re-flush anything (the rows are already
+     * durable); it writes only to the mirror.
+     */
+    async hydrate(tenancy) {
+        const latest = await this.durable.listLatestVersions(tenancy);
+        for (const lv of latest) {
+            if (this.mirror.getIdentity(lv.identity.nectar) !== undefined)
+                continue;
+            this.mirror.insertIdentity(lv.identity);
+            this.mirror.appendVersion(lv.version);
+        }
+    }
+    /** Resolves once every durable write enqueued so far has settled (success or surfaced failure). */
+    whenFlushed() {
+        return this.tail.then(() => { });
+    }
+    /** How many durable flushes have failed since construction (surfaced to `/health`). */
+    get durableFlushFailures() {
+        return this.failures;
+    }
+    /** The most recent durable-flush error, or null when none has failed. */
+    get lastFlushError() {
+        return this.lastError;
+    }
+    /** Durable writes enqueued but not yet settled. */
+    get pendingDurableWrites() {
+        return this.pending;
+    }
+    /**
+     * Chain one durable write onto the serialized queue. The op's rejection is
+     * caught HERE (never rethrown into the synchronous ladder, and never left to
+     * become an unhandled rejection), so the queue keeps draining and every
+     * failure is surfaced exactly once.
+     *
+     * `nectar` is checked against {@link failedIdentityNectars} at RUN time (not
+     * enqueue time): because the queue is strictly serialized, by the time this
+     * op's turn comes up, an earlier `insertIdentity` for the same nectar has
+     * already settled, so the set is guaranteed up to date (CodeRabbit PR-18
+     * finding #8, layer a). Only `appendVersion`/`touchIdentity` are parkable -
+     * they are the writes that would ADD data referencing a still-missing
+     * identity. `deleteNectar` is exempt and always flows through: it is
+     * cleanup, not a write that can orphan anything (the durable `deleteNectar`
+     * contract is itself a no-op when the identity does not exist), and letting
+     * it through is what clears the nectar out of {@link failedIdentityNectars}
+     * again on success.
+     */
+    enqueue(op, nectar, run) {
+        this.pending += 1;
+        this.tail = this.tail.then(() => {
+            const parkable = op === "appendVersion" || op === "touchIdentity";
+            if (parkable && this.failedIdentityNectars.has(nectar)) {
+                this.pending -= 1;
+                this.failures += 1;
+                const err = new Error(`durable ${op} for nectar ${nectar} parked: its identity insert already failed durably (would orphan hive_graph_versions)`);
+                this.lastError = err;
+                this.onFlushError(err, op);
+                return;
+            }
+            return run().then(() => {
+                this.pending -= 1;
+                if (op === "deleteNectar")
+                    this.failedIdentityNectars.delete(nectar); // the nectar is gone; nothing left to orphan
+            }, (err) => {
+                this.pending -= 1;
+                this.failures += 1;
+                this.lastError = err;
+                if (op === "insertIdentity")
+                    this.failedIdentityNectars.add(nectar);
+                this.onFlushError(err, op);
+            });
+        });
+    }
+    // ── writes: apply to the mirror, then flush the identical write in order ─────
+    insertIdentity(row) {
+        this.mirror.insertIdentity(row);
+        this.enqueue("insertIdentity", row.nectar, () => this.durable.insertIdentity(row));
+    }
+    touchIdentity(nectar, lastUpdateDate) {
+        this.mirror.touchIdentity(nectar, lastUpdateDate);
+        this.enqueue("touchIdentity", nectar, () => this.durable.touchIdentity(nectar, lastUpdateDate));
+    }
+    appendVersion(row) {
+        this.mirror.appendVersion(row);
+        this.enqueue("appendVersion", row.nectar, () => this.durable.appendVersion(row));
+    }
+    deleteNectar(tenancy, nectar) {
+        this.mirror.deleteNectar(tenancy, nectar);
+        this.enqueue("deleteNectar", nectar, () => this.durable.deleteNectar(tenancy, nectar));
+    }
+    // ── reads: served synchronously from the mirror ──────────────────────────────
+    getIdentity(nectar) {
+        return this.mirror.getIdentity(nectar);
+    }
+    nextSeq(nectar) {
+        return this.mirror.nextSeq(nectar);
+    }
+    latestVersion(nectar) {
+        return this.mirror.latestVersion(nectar);
+    }
+    listLatestVersions(tenancy) {
+        return this.mirror.listLatestVersions(tenancy);
+    }
+    listLatestDescribedVersions(tenancy) {
+        return this.mirror.listLatestDescribedVersions(tenancy);
+    }
+    latestVersionByPath(tenancy, path) {
+        return this.mirror.latestVersionByPath(tenancy, path);
+    }
+    latestVersionByHash(tenancy, contentHash) {
+        return this.mirror.latestVersionByHash(tenancy, contentHash);
+    }
+    listIdentities(tenancy) {
+        return this.mirror.listIdentities(tenancy);
+    }
+    listVersionNectars(tenancy) {
+        return this.mirror.listVersionNectars(tenancy);
+    }
+}
+//# sourceMappingURL=store-bridge.js.map

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

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

package/dist/registration/tlsh.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Step-4 fuzzy fingerprint + distance, pure TypeScript, zero runtime deps (PRD-006d AC-14/AC-17).
+ *
+ * PRD-006d flags the TLSH implementation as "native addon OR WASM build -
+ * DEFAULT - confirm before implementation" and Nectar's ethos is zero
+ * runtime dependencies (Node built-ins only). The native-addon / WASM options
+ * therefore remain a flagged DEFAULT for later; this module ships the in-repo,
+ * pure-TS DEFAULT so step 4 works today with no new dependency.
+ *
+ * The algorithm is a locality-sensitive near-duplicate fingerprint in the TLSH
+ * family (a quartile-bucketed byte-trigram histogram), NOT byte-exact Trend
+ * Micro TLSH. It satisfies the AC's behavior exactly: it produces a fixed-length
+ * fingerprint, a distance between two fingerprints, size-buckets candidates by
+ * +/-20%, and yields a scored confidence. Correctness of the near-duplicate
+ * behavior (identical -> distance 0; a small edit -> small distance; unrelated
+ * -> large distance) is what matters here, per the PRD's own guidance. The
+ * `native addon or WASM` swap keeps the same fingerprint/distance interface, so
+ * it can replace this module later without touching the ladder.
+ *
+ * DELIBERATE SPEC GAP (AC-16): NO confidence threshold is pinned in this module.
+ * The distance-to-confidence mapping uses only the algorithm's theoretical
+ * maximum distance as its normalization denominator (not a tuned cutoff). The
+ * accept/review band edges are supplied by the caller via {@link FuzzyConfig};
+ * the operator default below is explicitly a tunable operator default (tuned
+ * during brooding, PRD-007), NOT a spec-pinned threshold.
+ */
+import type { FuzzyStep } from "./ladder.js";
+/** Fingerprint format tag. Distinguishes this in-repo digest from a byte-exact TLSH string. */
+export declare const FINGERPRINT_PREFIX = "H1";
+/** Theoretical maximum distance; the normalization denominator for confidence (algorithmic, not a threshold). */
+export declare const MAX_DISTANCE: number;
+/**
+ * Compute the locality-sensitive fingerprint of the given content. Deterministic
+ * (no randomness), so identical bytes always produce an identical string.
+ */
+export declare function computeFingerprint(content: string | Uint8Array): string;
+/**
+ * Distance between two fingerprints. 0 for identical content; small for a small
+ * edit; large for unrelated content. Returns {@link MAX_DISTANCE} when either
+ * fingerprint is malformed (treated as maximally distant, never a false match).
+ */
+export declare function fingerprintDistance(a: string, b: string): number;
+/**
+ * Map a fingerprint distance to a [0,1] confidence. `maxDistance` is the
+ * normalization denominator; it defaults to the fixed {@link MAX_DISTANCE} so
+ * existing callers that score two same-order-of-magnitude-sized inputs (or
+ * that pre-compute their own denominator) are unaffected. Step 4 itself always
+ * passes a size-aware denominator via {@link achievableMaxDistance} (NEC-010) -
+ * see that function's docstring for why a fixed denominator over-inflates
+ * confidence for small inputs.
+ */
+export declare function distanceToConfidence(distance: number, maxDistance?: number): number;
+/**
+ * NEC-010 fix: the size-aware achievable maximum total distance for comparing
+ * two contents. Only the body term scales down for small inputs
+ * ({@link achievableBodyDistance}); `LEN_MAX`/`CHK_MAX` stay fixed because the
+ * length code and checksum are stable signals regardless of content size (they
+ * are not trigram-histogram evidence). This is the denominator step 4 feeds
+ * {@link distanceToConfidence} so a tiny input's confidence reflects how much
+ * distance the digest could actually have produced, not the corpus-wide
+ * theoretical maximum.
+ */
+export declare function achievableMaxDistance(sizeA: number, sizeB: number): number;
+/** The +/-20% size-bucket half-width from the corpus (brooding-pipeline.md), an algorithmic optimization, not a threshold. */
+export declare const SIZE_BUCKET_TOLERANCE = 0.2;
+/**
+ * Minimum content length (bytes) for a meaningful fuzzy comparison. Content
+ * shorter than one byte-trigram records no trigram, so distinct tiny contents
+ * would collapse to the same fingerprint (distance 0, perfect confidence) and
+ * could be auto-carried without evidence.
+ *
+ * This is the absolute floor against a distance-0 fingerprint collapse, NOT
+ * the evidence floor the fuzzy step actually gates on - see
+ * {@link MIN_FUZZY_EVIDENCE_BYTES} (NEC-010), which is strictly larger and
+ * supersedes this one for the step-4 abstain decision. Kept as a named
+ * constant for the narrower guarantee it documents.
+ */
+export declare const MIN_FUZZY_BYTES = 3;
+/**
+ * NEC-010 fix (evidence gate, AC-018d.2): the byte floor below which a
+ * content's trigram histogram carries too little evidence for a meaningful
+ * fuzzy comparison, regardless of the computed digest distance. The
+ * change-detection review found that two unrelated ~10-byte files can score
+ * confidence >= 0.879 under the old fixed-`MAX_DISTANCE` mapping - well above
+ * the `highConfidence` default of 0.85 - because so few trigrams exist that
+ * the quartile-coded body is little more than an 8-of-128 occupancy bitmap.
+ * `MIN_FUZZY_BYTES` (3) only blocks a literal fingerprint collapse; this floor
+ * is deliberately much larger (in the review's suggested 50-100 byte
+ * neighborhood) so the fuzzy step abstains outright on any input too small to
+ * carry real signal, INDEPENDENT of {@link achievableMaxDistance}'s
+ * normalization fix (defense in depth: AC-018d.1's ~10-byte case is caught by
+ * both). Content at or above this floor - including every existing
+ * `tlsh.test.ts` fixture (roughly 1000+ bytes) - is unaffected (AC-018d.3).
+ * This is the mapping/gate, not the tunable `highConfidence`/`reviewFloor`
+ * band edges (`DEFAULT_TUNABLE_FUZZY_CONFIG`), which stay operator-tunable.
+ */
+export declare const MIN_FUZZY_EVIDENCE_BYTES = 50;
+/**
+ * The step-4 confidence bands. Supplied by the caller (the daemon config), NOT
+ * pinned by the corpus or PRD-006d. `highConfidence` is the auto-carry floor;
+ * `reviewFloor` is the floor for surfacing to `review-matches`; below it the
+ * file falls through to a fresh mint (step 5).
+ */
+export interface FuzzyConfig {
+    readonly highConfidence: number;
+    readonly reviewFloor: number;
+}
+/**
+ * OPERATOR DEFAULT, tunable during brooding (PRD-007). This is NOT a
+ * spec-pinned threshold: PRD-006d and identity-and-reassociation.md deliberately
+ * pin no number ("configurable, default tuned during brooding"). These values
+ * exist only so the daemon has a runnable fuzzy step out of the box; an operator
+ * overrides them via daemon config, and brooding calibrates them against the
+ * actual codebase's near-duplicate distribution. Do NOT treat these as the spec.
+ */
+export declare const DEFAULT_TUNABLE_FUZZY_CONFIG: FuzzyConfig;
+/**
+ * Build the concrete, pure-TS step-4 fuzzy matcher. Size-buckets the candidates
+ * by +/-20% of the new content's byte length, fingerprints the new content,
+ * scores each in-bucket candidate that carries a fingerprint, and bands the best
+ * score by the injected {@link FuzzyConfig}. The band edges come from `config`;
+ * this function pins none.
+ */
+export declare function createTlshFuzzyStep(config: FuzzyConfig): FuzzyStep;
+//# sourceMappingURL=tlsh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tlsh.d.ts","sourceRoot":"","sources":["../../src/registration/tlsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,aAAa,CAAC;AAE3E,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAWvC,iHAAiH;AACjH,eAAO,MAAM,YAAY,QAA+B,CAAC;AAmBzD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAgCvE;AAoCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAahE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAAqB,GAAG,MAAM,CAKjG;AAiCD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,8HAA8H;AAC9H,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAG1C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAgDlE"}