goldenmatch 0.7.0 → 0.8.0

package/CLAUDE.md

@@ -0,0 +1,68 @@
+# goldenmatch (TypeScript)
+
+npm package `goldenmatch`. Three-wave parity port of the Python sibling at `packages/python/goldenmatch/`. Currently at **v0.7.0** (parity with Python v1.12).
+
+## Wave history
+| npm | Python parity | Headline |
+|-----|---------------|----------|
+| 0.4.0 | v1.6.0 | Learning Memory + scorer ground truth |
+| 0.5.0 | v1.7 + v1.8 | AutoConfigController, ComplexityProfile, RunHistory, StopReason telemetry |
+| 0.6.0 | v1.9 + v1.10 | 5 complexity indicators + indicator-aware refit rules; scorer selection aligned with Python |
+| 0.7.0 | v1.11 + v1.12 | NegativeEvidenceField + Path Y (exact-MK post-filter) |
+
+Each wave's spec/plan: `docs/superpowers/specs/2026-05-10-ts-parity-arc-design.md` + per-wave plans.
+
+## Commands
+```bash
+cd packages/typescript/goldenmatch
+pnpm --filter goldenmatch test      # vitest (841 tests at v0.7.0)
+pnpm --filter goldenmatch typecheck # tsc --noEmit (strict)
+pnpm --filter goldenmatch build     # tsup (5 entry points)
+npx vitest run tests/parity/        # parity-only suite
+```
+
+## Edge-safety rule
+`src/core/**` MUST NOT import `node:*`. Node-only code lives in `src/node/`. Memory backed by SQLite is `src/node/memory/`; the edge-safe interface is `src/core/memory/`. This is enforced by build separation, not by lint — verify when adding new imports.
+
+## Strict TS
+`noUncheckedIndexedAccess` + `exactOptionalPropertyTypes`. Idioms:
+- Bounded-loop indices: use `arr[i]!` after a length check.
+- Optional props: `...(x !== undefined ? { field: x } : {})` — never spread `undefined`.
+- Optional peer deps (sqlite, sentence-transformers): `await import("pkg-name" as string)` — the `as string` cast prevents tsup from resolving at build time.
+
+## Parity contract
+- **Scorer output:** 4-decimal tolerance vs Python (`tests/parity/scorer-ground-truth.test.ts`).
+- **Hash bytes:** SHA-256 truncated to 16 hex via Web Crypto. UTF-8 mandatory. Hash input = values joined by `|` (NOT `<col>=<val>`). `__row_id__` excluded from `record_hash` so corrections survive row reordering.
+- **Cross-language fixtures:** committed under `tests/parity/fixtures/`. Regen via `packages/python/goldenmatch/tests/parity/memory/gen_memory_fixtures.py --rebuild-db` and the wave-specific emitters in `packages/python/goldenmatch/scripts/emit_ts_parity_fixtures.py`. Determinism clamp: pinned UUIDs, pinned `created_at` (no `datetime.now()`).
+- **Negative-evidence parity** (v0.7.0): 6 fixture datasets exercising Path Y filtering on exact MKs + weighted-MK NE. Live in `tests/parity/negative-evidence-fixtures.json`.
+- **Controller parity** (v0.5.0): structural-only on 4 of 6 fixtures, byte-equal on 2. Python-side `ModuleNotFoundError` on polars/sklearn in the divergent 4 — TS doesn't replicate that import wart.
+
+## Public API surface (v0.7.0)
+- `dedupeFile`, `dedupe`, `matchFile`, `match` — all return Promises.
+- `autoConfigureRows` (sync, single-pass) and `autoConfigureRowsIterate` (Promise, full controller).
+- `AutoConfigController`, `RunHistory`, `ComplexityProfile`, `HealthVerdict`, `StopReason`.
+- `NegativeEvidenceField`, `applyNegativeEvidence`, `applyNegativeEvidenceToExactPairs`, `promoteNegativeEvidence`.
+- Memory mirror: `getMemory`, `addCorrection`, `learn`, `memoryStats`.
+- MCP tool count: 24 (19 base + 5 memory). Description literal at `src/node/mcp/server.ts:6` — keep in sync via the existing regex test.
+
+## Build outputs
+- tsup with 5 entry points: `index`, `core/index`, `node/index`, `cli`, `node/backends/score-worker` (piscina worker).
+- Build artifacts to `dist/` (gitignored).
+- Test count discipline: bump when adding parity datasets so future audits can diff.
+
+## Config-types invariants
+- **No `make*` factory functions** for config types — test fixtures use full literals. Required fields:
+  - `MatchkeyField`: `field` + `transforms` + `scorer` + `weight`
+  - `BlockingKeyConfig`: `fields` + `transforms`
+  - `BlockingConfig`: `strategy` + `keys` + `maxBlockSize` + `skipOversized`
+- **Scorer names are snake_case** (same as Python): `token_sort`, `record_embedding`, `soundex_match`, `ensemble`, `exact`, `jaro_winkler`, `levenshtein`.
+- **`DOMAIN_EXTRACTED_COLS`** (in `src/core/domain.ts`) has only 3 entries (`__brand__`, `__model__`, `__version__`); Python's has 12. Don't assume parity when porting domain features.
+
+## Vitest gotchas
+- Default timeout 5s. Heavier integration tests (PPRL multi-level, postflight end-to-end) need `{ timeout: 15000 }`. CI concurrent load has bitten this (cost a release: v0.3.0 → v0.3.1).
+
+## Publish workflow
+- `.github/workflows/publish-goldenmatch-js.yml` at monorepo root. Triggers on `goldenmatch-js-v*` tag or `workflow_dispatch` with `ref` input.
+- Tag MUST point at a commit that has the workflow file, otherwise the trigger doesn't fire (root CLAUDE.md "Workflow trigger ordering" gotcha).
+- Uses `NPM_TOKEN` secret. Trusted publishing not configured.
+- The tag-version-must-match-package.json check (in the workflow) means you cannot tag multiple versions at the same commit. Each release commit has its own version bump and tag.

package/dist/core/index.cjs

@@ -11661,6 +11661,267 @@ init_corrections();
 init_learner();
 init_hash();
 
+// src/core/identity/types.ts
+function canonRecordPair(a, b) {
+  return a <= b ? [a, b] : [b, a];
+}
+
+// src/core/identity/new-entity-id.ts
+function newEntityId() {
+  const tsMs = BigInt(Date.now()) & (1n << 48n) - 1n;
+  const randBytes = randomBytes(10);
+  const randA = BigInt(randBytes[0] & 15) << 8n | BigInt(randBytes[1]);
+  let lo = 0n;
+  for (let i = 2; i < 10; i++) {
+    lo = lo << 8n | BigInt(randBytes[i]);
+  }
+  lo = lo & (1n << 62n) - 1n;
+  const high = tsMs << 16n | 0x7n << 12n | randA;
+  const low = 0b10n << 62n | lo;
+  return formatUuid(high, low);
+}
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(out);
+    return out;
+  }
+  for (let i = 0; i < n; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+function formatUuid(high, low) {
+  const hh = high.toString(16).padStart(16, "0");
+  const ll = low.toString(16).padStart(16, "0");
+  return hh.slice(0, 8) + "-" + hh.slice(8, 12) + "-" + hh.slice(12, 16) + "-" + ll.slice(0, 4) + "-" + ll.slice(4, 16);
+}
+
+// src/core/identity/in-memory-store.ts
+var InMemoryIdentityStore = class {
+  identities = /* @__PURE__ */ new Map();
+  records = /* @__PURE__ */ new Map();
+  edges = [];
+  events = [];
+  aliases = /* @__PURE__ */ new Map();
+  nextEdgeId = 1;
+  nextEventId = 1;
+  async upsertIdentity(node) {
+    const existing = this.identities.get(node.entityId);
+    if (existing) {
+      this.identities.set(node.entityId, {
+        ...node,
+        createdAt: existing.createdAt,
+        updatedAt: node.updatedAt
+      });
+    } else {
+      this.identities.set(node.entityId, { ...node });
+    }
+  }
+  async getIdentity(entityId) {
+    const n = this.identities.get(entityId);
+    return n ? { ...n } : null;
+  }
+  async listIdentities(opts = {}) {
+    const all = Array.from(this.identities.values()).filter((n) => opts.dataset === void 0 || n.dataset === opts.dataset).filter((n) => opts.status === void 0 || n.status === opts.status).sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+    const offset = opts.offset ?? 0;
+    const limit = opts.limit ?? 100;
+    return all.slice(offset, offset + limit).map((n) => ({ ...n }));
+  }
+  async countIdentities(dataset) {
+    if (dataset === void 0) return this.identities.size;
+    let n = 0;
+    for (const node of this.identities.values()) {
+      if (node.dataset === dataset) n++;
+    }
+    return n;
+  }
+  async retireIdentity(entityId, mergedInto) {
+    const node = this.identities.get(entityId);
+    if (!node) return;
+    const next = {
+      ...node,
+      status: mergedInto ? "merged_into" : "retired",
+      mergedInto: mergedInto ?? null,
+      updatedAt: /* @__PURE__ */ new Date()
+    };
+    this.identities.set(entityId, next);
+  }
+  async upsertRecord(rec) {
+    const existing = this.records.get(rec.recordId);
+    if (existing) {
+      this.records.set(rec.recordId, {
+        ...rec,
+        firstSeenAt: existing.firstSeenAt,
+        lastSeenAt: rec.lastSeenAt
+      });
+    } else {
+      this.records.set(rec.recordId, { ...rec });
+    }
+  }
+  async getRecord(recordId) {
+    const r = this.records.get(recordId);
+    return r ? { ...r } : null;
+  }
+  async getRecordsForEntity(entityId) {
+    return Array.from(this.records.values()).filter((r) => r.entityId === entityId).sort((a, b) => a.firstSeenAt.getTime() - b.firstSeenAt.getTime()).map((r) => ({ ...r }));
+  }
+  async findEntityByRecord(recordId) {
+    return this.records.get(recordId)?.entityId ?? null;
+  }
+  async lookupEntityIds(recordIds) {
+    const out = /* @__PURE__ */ new Map();
+    for (const rid of recordIds) {
+      const eid = this.records.get(rid)?.entityId;
+      if (eid) out.set(rid, eid);
+    }
+    return out;
+  }
+  async addEdge(edge) {
+    const [a, b] = canonRecordPair(edge.recordAId, edge.recordBId);
+    const runKey = edge.runName ?? "";
+    for (const e of this.edges) {
+      if (e.entityId === edge.entityId && e.recordAId === a && e.recordBId === b && (e.runName ?? "") === runKey) {
+        return e.edgeId;
+      }
+    }
+    const stored = {
+      ...edge,
+      recordAId: a,
+      recordBId: b,
+      edgeId: this.nextEdgeId++
+    };
+    this.edges.push(stored);
+    return stored.edgeId;
+  }
+  async edgesForEntity(entityId) {
+    return this.edges.filter((e) => e.entityId === entityId).sort((a, b) => a.recordedAt.getTime() - b.recordedAt.getTime()).map((e) => ({ ...e }));
+  }
+  async findConflicts(dataset) {
+    return this.edges.filter((e) => e.kind === "conflicts_with").filter((e) => dataset === void 0 || e.dataset === dataset).sort((a, b) => b.recordedAt.getTime() - a.recordedAt.getTime()).map((e) => ({ ...e }));
+  }
+  async emitEvent(event) {
+    const stored = { ...event, eventId: this.nextEventId++ };
+    this.events.push(stored);
+    return stored.eventId;
+  }
+  async history(entityId, limit) {
+    const filtered = this.events.filter((e) => e.entityId === entityId).sort((a, b) => (a.eventId ?? 0) - (b.eventId ?? 0));
+    return (limit ? filtered.slice(0, limit) : filtered).map((e) => ({ ...e }));
+  }
+  async hasRunEvent(entityId, runName, kind) {
+    return this.events.some(
+      (e) => e.entityId === entityId && e.runName === runName && e.kind === kind
+    );
+  }
+  async addAlias(alias) {
+    this.aliases.set(`${alias.alias}|${alias.kind}|${alias.dataset ?? ""}`, { ...alias });
+  }
+  async resolveAlias(alias, kind = "external_id") {
+    for (const [key, val] of this.aliases.entries()) {
+      const parts = key.split("|");
+      if (parts[0] === alias && parts[1] === kind) return val.entityId;
+    }
+    return null;
+  }
+  async close() {
+  }
+};
+
+// src/core/identity/query.ts
+async function getEntity(store, entityId, eventLimit = 100) {
+  const node = await store.getIdentity(entityId);
+  if (!node) return null;
+  const [records, edges, events] = await Promise.all([
+    store.getRecordsForEntity(entityId),
+    store.edgesForEntity(entityId),
+    store.history(entityId, eventLimit)
+  ]);
+  return { node, records, edges, events };
+}
+async function findByRecord(store, recordId) {
+  const eid = await store.findEntityByRecord(recordId);
+  if (!eid) return null;
+  return getEntity(store, eid);
+}
+async function listEntities(store, opts = {}) {
+  return store.listIdentities(opts);
+}
+async function manualMerge(store, keepEntityId, absorbEntityId, opts = {}) {
+  const winner = await store.getIdentity(keepEntityId);
+  const loser = await store.getIdentity(absorbEntityId);
+  if (!winner || !loser) throw new Error("Both entity_ids must exist");
+  if (winner.status !== "active") throw new Error("Winner must be active");
+  const now2 = /* @__PURE__ */ new Date();
+  const losersRecords = await store.getRecordsForEntity(absorbEntityId);
+  for (const r of losersRecords) {
+    await store.upsertRecord({ ...r, entityId: keepEntityId, lastSeenAt: now2 });
+  }
+  await store.retireIdentity(absorbEntityId, keepEntityId);
+  const runName = opts.runName ?? "manual";
+  await store.emitEvent({
+    eventId: null,
+    entityId: keepEntityId,
+    kind: "manual_merge",
+    payload: { absorbed: absorbEntityId, reason: opts.reason ?? null },
+    runName,
+    dataset: winner.dataset,
+    recordedAt: now2
+  });
+  await store.emitEvent({
+    eventId: null,
+    entityId: absorbEntityId,
+    kind: "manual_merge",
+    payload: { merged_into: keepEntityId, reason: opts.reason ?? null },
+    runName,
+    dataset: loser.dataset,
+    recordedAt: now2
+  });
+  return { keep: keepEntityId, absorbed: absorbEntityId, at: now2.toISOString() };
+}
+async function manualSplit(store, entityId, recordIds, opts = {}) {
+  const parent = await store.getIdentity(entityId);
+  if (!parent) throw new Error(`Entity ${entityId} not found`);
+  if (recordIds.length === 0) throw new Error("recordIds must be non-empty");
+  const now2 = /* @__PURE__ */ new Date();
+  const newId = newEntityId();
+  await store.upsertIdentity({
+    entityId: newId,
+    status: "active",
+    mergedInto: null,
+    goldenRecord: null,
+    confidence: null,
+    dataset: parent.dataset,
+    createdAt: now2,
+    updatedAt: now2
+  });
+  const moved = [];
+  for (const rid of recordIds) {
+    const rec = await store.getRecord(rid);
+    if (!rec || rec.entityId !== entityId) continue;
+    await store.upsertRecord({ ...rec, entityId: newId, lastSeenAt: now2 });
+    moved.push(rid);
+  }
+  const runName = opts.runName ?? "manual";
+  await store.emitEvent({
+    eventId: null,
+    entityId,
+    kind: "manual_split",
+    payload: { split_to: newId, records: moved, reason: opts.reason ?? null },
+    runName,
+    dataset: parent.dataset,
+    recordedAt: now2
+  });
+  await store.emitEvent({
+    eventId: null,
+    entityId: newId,
+    kind: "manual_split",
+    payload: { split_from: entityId, records: moved, reason: opts.reason ?? null },
+    runName,
+    dataset: parent.dataset,
+    recordedAt: now2
+  });
+  return { newEntityId: newId, moved, at: now2.toISOString() };
+}
+
 // src/core/pprl/protocol.ts
 init_transforms();
 init_scorer();
@@ -11757,6 +12018,7 @@ exports.BudgetTracker = BudgetTracker;
 exports.CrossEncoderHttpError = CrossEncoderHttpError;
 exports.CrossEncoderModel = CrossEncoderModel;
 exports.HIGH_TRUST_SOURCES = HIGH_TRUST_SOURCES;
+exports.InMemoryIdentityStore = InMemoryIdentityStore;
 exports.InMemoryStore = InMemoryStore;
 exports.ReviewQueue = ReviewQueue;
 exports.StreamProcessor = StreamProcessor;
@@ -11792,6 +12054,7 @@ exports.buildLineage = buildLineage;
 exports.buildMst = buildMst;
 exports.buildMultiPassBlocks = buildMultiPassBlocks;
 exports.buildStaticBlocks = buildStaticBlocks;
+exports.canonRecordPair = canonRecordPair;
 exports.compareClusters = compareClusters;
 exports.complexityHealth = complexityHealth;
 exports.computeClusterConfidence = computeClusterConfidence;
@@ -11819,12 +12082,14 @@ exports.evaluatePairs = evaluatePairs;
 exports.explainCluster = explainCluster;
 exports.explainPair = explainPair;
 exports.extractFeatures = extractFeatures;
+exports.findByRecord = findByRecord;
 exports.findExactMatches = findExactMatches;
 exports.findExactMatchesOne = findExactMatchesOne;
 exports.findFuzzyMatches = findFuzzyMatches;
 exports.gatePairs = gatePairs;
 exports.getClusterPairScores = getClusterPairScores;
 exports.getEmbedder = getEmbedder;
+exports.getEntity = getEntity;
 exports.getLastControllerRun = getLastControllerRun;
 exports.getMatchkeys = getMatchkeys;
 exports.indelDistance = indelDistance;
@@ -11838,6 +12103,7 @@ exports.levenshteinDistance = levenshteinDistance;
 exports.levenshteinSimilarity = levenshteinSimilarity;
 exports.lineageFromJson = lineageFromJson;
 exports.lineageToJson = lineageToJson;
+exports.listEntities = listEntities;
 exports.llmClusterPairs = llmClusterPairs;
 exports.llmExplainPair = llmExplainPair;
 exports.llmScorePairs = llmScorePairs;
@@ -11859,10 +12125,13 @@ exports.makePreflightReport = makePreflightReport;
 exports.makeProfileMeta = makeProfileMeta;
 exports.makeScoredPair = makeScoredPair;
 exports.makeScoringProfile = makeScoringProfile;
+exports.manualMerge = manualMerge;
+exports.manualSplit = manualSplit;
 exports.match = match;
 exports.matchOne = matchOne;
 exports.mergeField = mergeField;
 exports.metaphone = metaphone;
+exports.newEntityId = newEntityId;
 exports.normalizedSignalVector = normalizedSignalVector;
 exports.pairKey = pairKey;
 exports.parseConfig = parseConfig;