nodedex 0.1.0

package/dist/middleware/reflect/stage-audit-graph.d.ts

@@ -0,0 +1,115 @@
+import type Database from "better-sqlite3";
+import { cosineSim } from "../../engine/vector-math.js";
+import type { WorkspaceDB, Block } from "../../store/database.js";
+import type { StageAuditTickResult, PipelineFlagType } from "./types.js";
+/** Jaccard similarity of two concept sets: |A∩B| / |A∪B|. 0 when both empty. */
+export declare function jaccard(a: string[], b: string[]): number;
+/** Count shared concepts (case-insensitive). */
+export declare function sharedConceptCount(a: string[], b: string[]): number;
+/** Count distinct shared SIGNIFICANT tokens between two essences (descriptions).
+ *  The recall net for drifted-concept fork pairs: two roots about the same domain
+ *  share domain words in their descriptions even when their concept tags drift
+ *  (measured: home-coffee-roasting vs ...-activities had 0 concept overlap but
+ *  share "coffee"+"roasting" in essence). Keys on the DESCRIPTION (meaning), not
+ *  the label (name-vs-meaning). Pure / testable. */
+export declare function sharedEssenceTokens(a: string, b: string): number;
+export { cosineSim };
+export interface AuditBlock {
+    id: string;
+    label: string;
+    type: string;
+    concepts: string[];
+    project_id: string | null;
+    source_excerpt: string | null;
+    /** Per-type identity value from content.unique{} — the "is this the same
+     *  thing" signal (per [[feedback-identity-is-unique-not-label]]). Normalized
+     *  (trim + lowercase) for cross-conversation comparison. "" when none. */
+    primary_value: string;
+    /** Root description / block essence — a TEXT recall signal for drifted-concept
+     *  project-dup pairs that concept-jaccard misses (the recognizer-validated gap). */
+    essence: string;
+    /** Stored embedding (label+essence+concepts), parsed. null when not yet embedded —
+     *  the embedding-recall branch skips such pairs (falls back to exact/token). */
+    embedding: number[] | null;
+}
+export declare function toAuditBlock(b: Block): AuditBlock;
+export interface BlockDupJudgeOpts {
+    /** Min shared CLAIM tokens (primary_value) to flag as a candidate. */
+    claimMin: number;
+    /** Whether the embedding-recall (drift) branch is active. */
+    embedOn: boolean;
+    /** Min cosine for the embedding-recall branch (applied to SAME-TYPE pairs only). */
+    embedMin: number;
+}
+export type BlockDupSignal = 'primary_value_exact' | 'primary_value_overlap' | 'essence_embedding';
+export interface BlockDupVerdict {
+    /** True when the pair is a same-scope dup CANDIDATE. RECALL only — the
+     *  flag-reviewer is the precision judge (merge/leave). */
+    isCandidate: boolean;
+    /** Same project_id (the hard structural merge-guard). false → never a candidate. */
+    sameScope: boolean;
+    /** Which recall signal fired (null when not a candidate). */
+    signal: BlockDupSignal | null;
+    /** Shared primary_value tokens (recorded for the flag criteria). */
+    claimTokens: number;
+    /** Cosine on the stored embeddings; 0 when not computed/applicable. */
+    embedSim: number;
+}
+/** Read the block-dup judge config once, from the SAME env readers the periodic
+ *  AUDIT uses, so the inline recognize-before-write path can never drift apart
+ *  from the AUDIT scan. */
+export declare function blockDupJudgeOpts(): BlockDupJudgeOpts;
+/**
+ * DO: decide whether two blocks are a same-scope duplicate CANDIDATE — exact
+ *   primary_value, primary_value token-overlap, or (opt-in) near-identical
+ *   same-type essence embedding (the drift net).
+ * SERVE: compounding — one piece of residue should be ONE block. This is the
+ *   RECALL stage; the flag-reviewer is the precision judge.
+ * CARRY: identity is unique{} primary_value, NOT label/essence; same-scope
+ *   (project_id) is the merge guard — a cross-scope same-claim pair is a
+ *   scope_disagreement (never merged), so it can never be a candidate here.
+ *
+ * Pure: no DB, no LLM. The supersedes-skip + flag idempotency are caller-side
+ * (they need the DB). This is the ONE implementation shared by the periodic
+ * AUDIT (runStageAuditTick) and the inline path (dedupNewBlocksInline) — so the
+ * two seams detect identically (Rule 5 spirit: one detection, two timings).
+ */
+export declare function judgeBlockDupPair(a: AuditBlock, b: AuditBlock, opts: BlockDupJudgeOpts): BlockDupVerdict;
+/** True if a supersedes/superseded_by relation exists between the pair (either
+ *  direction). Used by the block_dup detector to SKIP pairs already in a
+ *  replacement chain (the recap "reconfirmed → abandoned" case): the supersede
+ *  mechanism already collapsed them, re-flagging is redundant. Deliberately
+ *  NARROWER than hasRelationBetween — a `supports`/`contradicts` edge between two
+ *  same-claim blocks is NOT a dedup and must NOT suppress the flag (the 50ms-SLA
+ *  pair carries a `supports` edge yet is still an un-merged duplicate). */
+export declare function hasSupersedesBetween(raw: Database.Database, idA: string, idB: string): boolean;
+/** True if a flag of this type already exists for the pair (either direction),
+ *  reviewed OR not. Prevents re-flagging a known pair on every tick (incl.
+ *  re-spending reviewer $$ on a pair already verdicted 'leave'). */
+export declare function flagAlreadyExists(raw: Database.Database, flag_type: PipelineFlagType, idA: string, idB: string): boolean;
+export interface RunStageAuditOpts {
+    db: WorkspaceDB;
+    /** Round-robin start offset into the block list (for paging across ticks
+     *  when the graph exceeds maxPairsPerTick). Default 0.  */
+    startOffset?: number;
+}
+/**
+ * One Stage AUDIT tick: scan blocks pairwise, write flags for the 3 audit
+ * patterns. Bounded by maxPairsPerTick. Idempotent — never re-flags a pair
+ * already in pipeline_flags for that type.
+ *
+ * Returns per-tick result for telemetry + log + the next-tick offset.
+ *
+ * Per-pair precedence to avoid double-flagging the same pair:
+ *   both type='project'  → project_dup_candidate only (skip scope/island)
+ *   else same source_excerpt + different project → scope_disagreement
+ *   else strong concept overlap + no link → island_candidate
+ */
+export declare function runStageAuditTick(opts: RunStageAuditOpts): StageAuditTickResult;
+/** Start the Stage AUDIT timer. Idempotent; returns true if started. */
+export declare function startStageAuditTimer(db: WorkspaceDB): boolean;
+/** Stop the Stage AUDIT timer. Used on shutdown + by tests. */
+export declare function stopStageAuditTimer(): void;
+/** For tests only — reports whether the timer is currently running. */
+export declare function _isStageAuditTimerRunningForTests(): boolean;
+//# sourceMappingURL=stage-audit-graph.d.ts.map

package/dist/middleware/reflect/stage-audit-graph.d.ts.map

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