@oscharko-dev/keiko-memory-consolidation 0.2.0

package/dist/consolidate.js

@@ -0,0 +1,254 @@
+// runConsolidation: the engine entry point. Pure function; no IO; no clock reads; no
+// randomness. Every impurity is injected via ConsolidationOptions.
+//
+// Design choice pinned here so future contributors do not "fix" it:
+//   updatesProposed is ALWAYS the empty array in v1. Every merge / supersession is routed
+//   through a ReviewItem carrying a ProposedAction; the caller (#211 MemoriaViva UI or a
+//   workflow) materializes the actual MemorySupersession envelope after explicit review. The
+//   updatesProposed slot is reserved for a future model-assisted body-summarisation pass
+//   (issue #212 or follow-up). This preserves the Epic #204 invariant: "consolidation never
+//   mutates accepted memories without preserving provenance and audit history".
+//
+// Cancellation: cancellationSignal is polled BEFORE each cluster is inspected (once per
+// cluster), so the cost is bounded by the cluster count and partial results survive the
+// cancel. The signal is polled once at the very start as well, so a caller that already knows
+// it wants to abort can short-circuit without inspecting any cluster.
+import { validateMemoryRecord, } from "@oscharko-dev/keiko-contracts/memory";
+import { JACCARD_DEFAULT, MAX_AGE_MS_DEFAULT, MAX_CLUSTERS_PER_RUN_DEFAULT, MAX_CLUSTERS_PER_RUN_HARD_LIMIT, MAX_RECORDS_PER_RUN_DEFAULT, MAX_RECORDS_PER_RUN_HARD_LIMIT, STALE_CONFIDENCE_DEFAULT, } from "./_constants.js";
+import { compareEdges, compareRecordsByAge, compareReviewItems } from "./_ordering.js";
+import { CONFLICT_OVERLAP_THRESHOLD, detectConflicts, findConflictPairs } from "./conflicts.js";
+import { scanDuplicateClusters } from "./dedupe.js";
+import { findStaleMemories } from "./stale.js";
+const ELIGIBLE_STATUS = "accepted";
+function isFiniteInRange(n, lo, hi) {
+    return Number.isFinite(n) && n >= lo && n <= hi;
+}
+function isFiniteNonNegative(n) {
+    return Number.isFinite(n) && n >= 0;
+}
+function neverCancel() {
+    return false;
+}
+function validateNumericKnobs(knobs) {
+    if (!isFiniteInRange(knobs.jaccardThreshold, 0, 1))
+        return false;
+    if (!isFiniteInRange(knobs.staleConfidenceThreshold, 0, 1))
+        return false;
+    if (!isFiniteNonNegative(knobs.maxAgeMs))
+        return false;
+    if (!isFiniteInRange(knobs.maxClustersPerRun, 0, MAX_CLUSTERS_PER_RUN_HARD_LIMIT)) {
+        return false;
+    }
+    if (!isFiniteInRange(knobs.maxRecordsPerRun, 0, MAX_RECORDS_PER_RUN_HARD_LIMIT)) {
+        return false;
+    }
+    return Number.isInteger(knobs.maxClustersPerRun) && Number.isInteger(knobs.maxRecordsPerRun);
+}
+function resolveOptions(options) {
+    const knobs = {
+        jaccardThreshold: options.jaccardThreshold ?? JACCARD_DEFAULT,
+        staleConfidenceThreshold: options.staleConfidenceThreshold ?? STALE_CONFIDENCE_DEFAULT,
+        maxAgeMs: options.maxAgeMs ?? MAX_AGE_MS_DEFAULT,
+        maxClustersPerRun: options.maxClustersPerRun ?? MAX_CLUSTERS_PER_RUN_DEFAULT,
+        maxRecordsPerRun: options.maxRecordsPerRun ?? MAX_RECORDS_PER_RUN_DEFAULT,
+    };
+    if (!validateNumericKnobs(knobs))
+        return null;
+    return {
+        nowMs: options.nowMs,
+        newEdgeId: options.newEdgeId,
+        newReviewItemId: options.newReviewItemId,
+        ...knobs,
+        cancellationSignal: options.cancellationSignal ?? neverCancel,
+    };
+}
+function emptyResult(state, recordsInspected = 0, truncated = false) {
+    return {
+        state,
+        edgesProposed: [],
+        updatesProposed: [],
+        staleFlags: [],
+        reviewItems: [],
+        clustersInspected: 0,
+        conflictPairsDetected: 0,
+        recordsInspected,
+        truncated,
+        elapsedMs: 0,
+    };
+}
+function eligibleMemories(memories) {
+    const accepted = [];
+    for (const memory of memories) {
+        const validated = validateMemoryRecord(memory);
+        if (!validated.ok)
+            return null;
+        if (validated.value.status === ELIGIBLE_STATUS) {
+            accepted.push(validated.value);
+        }
+    }
+    return accepted;
+}
+function boundedEligibleMemories(memories, resolved) {
+    const sorted = [...memories].sort(compareRecordsByAge);
+    return {
+        records: sorted.slice(0, resolved.maxRecordsPerRun),
+        truncated: sorted.length > resolved.maxRecordsPerRun,
+    };
+}
+function buildEdge(fromMemoryId, toMemoryId, kind, resolved, provenanceSummary) {
+    return {
+        id: resolved.newEdgeId(),
+        schemaVersion: "1",
+        fromMemoryId,
+        toMemoryId,
+        kind,
+        createdAt: resolved.nowMs,
+        provenanceSummary,
+    };
+}
+function buildDuplicateEdges(older, newer, resolved) {
+    return [
+        buildEdge(older.id, newer.id, "derived-from", resolved, "consolidation: near-duplicate"),
+        buildEdge(older.id, newer.id, "related", resolved, "consolidation: related duplicate"),
+        buildEdge(older.id, newer.id, "temporal-precedes", resolved, "consolidation: temporal link"),
+    ];
+}
+function buildSupersedeReviewEdges(older, newer, resolved) {
+    return [
+        buildEdge(older, newer, "conflicts-with", resolved, "consolidation: proposed conflict"),
+        buildEdge(newer, older, "corrects", resolved, "consolidation: proposed correction"),
+        buildEdge(older, newer, "supersedes", resolved, "consolidation: proposed supersession"),
+    ];
+}
+function buildMergeReviewEdges(winner, losers, resolved) {
+    const edges = [];
+    for (const loser of losers) {
+        edges.push(buildEdge(loser, winner, "derived-from", resolved, "consolidation: proposed merge lineage"), buildEdge(loser, winner, "related", resolved, "consolidation: proposed merge relationship"), buildEdge(loser, winner, "supersedes", resolved, "consolidation: proposed merge supersession"));
+    }
+    return edges;
+}
+function withProposedReviewEdges(item, resolved) {
+    const action = item.proposedAction;
+    if (action === undefined)
+        return item;
+    const proposedEdges = action.kind === "supersede"
+        ? buildSupersedeReviewEdges(action.older, action.newer, resolved)
+        : buildMergeReviewEdges(action.winner, action.losers, resolved);
+    return proposedEdges.length === 0 ? item : { ...item, proposedEdges };
+}
+function processTwoMemberCluster(cluster, resolved) {
+    const conflictItems = detectConflicts([cluster], {
+        nowMs: resolved.nowMs,
+        newReviewItemId: resolved.newReviewItemId,
+    });
+    if (conflictItems.length > 0) {
+        const item = conflictItems[0];
+        return {
+            edges: [],
+            reviewItem: item === undefined ? null : withProposedReviewEdges(item, resolved),
+        };
+    }
+    const older = cluster.members[0];
+    const newer = cluster.members[1];
+    if (older === undefined || newer === undefined) {
+        return { edges: [], reviewItem: null };
+    }
+    return { edges: buildDuplicateEdges(older, newer, resolved), reviewItem: null };
+}
+function processMultiWayCluster(cluster, resolved) {
+    const items = detectConflicts([cluster], {
+        nowMs: resolved.nowMs,
+        newReviewItemId: resolved.newReviewItemId,
+    });
+    const item = items[0];
+    return {
+        edges: [],
+        reviewItem: item === undefined ? null : withProposedReviewEdges(item, resolved),
+    };
+}
+function processCluster(cluster, resolved) {
+    if (cluster.members.length > 2)
+        return processMultiWayCluster(cluster, resolved);
+    if (cluster.members.length === 2)
+        return processTwoMemberCluster(cluster, resolved);
+    return { edges: [], reviewItem: null };
+}
+function consumeClusters(clusters, resolved) {
+    const edges = [];
+    const reviewItems = [];
+    let clustersInspected = 0;
+    const limit = Math.min(clusters.length, resolved.maxClustersPerRun);
+    for (let i = 0; i < limit; i += 1) {
+        if (resolved.cancellationSignal()) {
+            return { state: "canceled", edges, reviewItems, clustersInspected };
+        }
+        const cluster = clusters[i];
+        if (cluster === undefined)
+            continue;
+        const effects = processCluster(cluster, resolved);
+        for (const edge of effects.edges)
+            edges.push(edge);
+        if (effects.reviewItem !== null)
+            reviewItems.push(effects.reviewItem);
+        clustersInspected += 1;
+    }
+    return { state: "completed", edges, reviewItems, clustersInspected };
+}
+function collectStaleFlags(records, resolved) {
+    return findStaleMemories(records, {
+        nowMs: resolved.nowMs,
+        staleConfidenceThreshold: resolved.staleConfidenceThreshold,
+        maxAgeMs: resolved.maxAgeMs,
+    });
+}
+function collectConflictPairs(records, clusters, resolved, consumedState, clusterScanCanceled) {
+    // If the cluster sweep was canceled, do NOT extend work into the conflict-pair sweep —
+    // honour the cancellation boundary so partial results stay partial.
+    if (consumedState === "canceled" || clusterScanCanceled)
+        return [];
+    return findConflictPairs(records, clusters, CONFLICT_OVERLAP_THRESHOLD, {
+        nowMs: resolved.nowMs,
+        newReviewItemId: resolved.newReviewItemId,
+        cancellationSignal: resolved.cancellationSignal,
+    }).map((item) => withProposedReviewEdges(item, resolved));
+}
+// Public entry. Same input + same options => byte-identical result.
+export function runConsolidation(memories, options) {
+    const resolved = resolveOptions(options);
+    if (resolved === null)
+        return emptyResult("failed");
+    if (resolved.cancellationSignal())
+        return emptyResult("canceled");
+    const eligible = eligibleMemories(memories);
+    if (eligible === null)
+        return emptyResult("failed");
+    if (eligible.length === 0)
+        return emptyResult("skipped");
+    const bounded = boundedEligibleMemories(eligible, resolved);
+    if (bounded.records.length === 0 || resolved.maxClustersPerRun === 0) {
+        return emptyResult("skipped", bounded.records.length, bounded.truncated);
+    }
+    const scanned = scanDuplicateClusters(bounded.records, resolved.jaccardThreshold, {
+        cancellationSignal: resolved.cancellationSignal,
+    });
+    if (scanned.canceled && scanned.clusters.length === 0) {
+        return emptyResult("canceled", bounded.records.length, bounded.truncated);
+    }
+    const clusters = scanned.clusters;
+    const consumed = consumeClusters(clusters, resolved);
+    const conflictPairs = collectConflictPairs(bounded.records, clusters, resolved, consumed.state, scanned.canceled);
+    const staleFlags = collectStaleFlags(bounded.records, resolved);
+    const mergedReviewItems = [...consumed.reviewItems, ...conflictPairs].sort(compareReviewItems);
+    return {
+        state: scanned.canceled ? "canceled" : consumed.state,
+        edgesProposed: [...consumed.edges].sort(compareEdges),
+        updatesProposed: [],
+        staleFlags,
+        reviewItems: mergedReviewItems,
+        clustersInspected: consumed.clustersInspected,
+        conflictPairsDetected: conflictPairs.length,
+        recordsInspected: bounded.records.length,
+        truncated: bounded.truncated,
+        elapsedMs: 0,
+    };
+}

package/dist/dedupe.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export interface DuplicateCluster {
+    readonly canonicalId: string;
+    readonly members: readonly MemoryRecord[];
+}
+export interface DuplicateClusterScanOptions {
+    readonly cancellationSignal?: () => boolean;
+}
+export interface DuplicateClusterScanResult {
+    readonly clusters: readonly DuplicateCluster[];
+    readonly canceled: boolean;
+}
+export declare function scanDuplicateClusters(records: readonly MemoryRecord[], jaccardThreshold: number, options?: DuplicateClusterScanOptions): DuplicateClusterScanResult;
+export declare function findDuplicateClusters(records: readonly MemoryRecord[], jaccardThreshold: number): readonly DuplicateCluster[];
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAKzE,MAAM,WAAW,gBAAgB;IAG/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAQD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAoED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CA8B5B;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,gBAAgB,EAAE,MAAM,GACvB,SAAS,gBAAgB,EAAE,CAE7B"}

package/dist/dedupe.js

@@ -0,0 +1,101 @@
+// Near-duplicate clustering. Pure function; deterministic; never mutates input.
+//
+// Algorithm:
+//   1. Partition input by (scopeCoordinateKey, type). Cross-scope and cross-type records
+//      are never merged — this is the load-bearing visibility invariant from #205.
+//   2. Within each partition, build clusters using a union-find-by-iteration sweep:
+//      for each record, find the first existing cluster whose CANONICAL member matches by
+//      one of (exact body, normalized body, bigram-Jaccard at-or-above threshold). If found,
+//      add to that cluster; otherwise open a new singleton cluster. Comparing to the canonical
+//      (oldest) member only — not pairwise to every member — is a cost compromise that holds
+//      because clusters are small in practice and the canonical member is the representative
+//      most likely to share the dominant body shape.
+//   3. Drop singleton clusters (consolidation needs ≥ 2 members to act).
+//   4. Sort members oldest-first (createdAt ASC, id ASC). Sort clusters by canonical (oldest)
+//      member id so the output is byte-stable across input shuffles.
+import { compareRecordsByAge, scopeCoordinateKey } from "./_ordering.js";
+import { jaccardSimilarityPrepared, prepareBody } from "./similarity.js";
+function partitionKey(record) {
+    return `${scopeCoordinateKey(record.scope)}|type:${record.type}`;
+}
+// Returns true when `candidate` should join the existing `cluster`. Compared only to the
+// canonical (oldest) member to keep cluster-add at O(1) per candidate per cluster.
+function clusterAccepts(cluster, candidateBody, jaccardThreshold) {
+    if (candidateBody.normalized === cluster.canonicalBody.normalized)
+        return true;
+    const score = jaccardSimilarityPrepared(candidateBody, cluster.canonicalBody);
+    return score >= jaccardThreshold;
+}
+function tryJoinExistingCluster(partition, candidate, candidateBody, jaccardThreshold) {
+    for (const cluster of partition) {
+        if (clusterAccepts(cluster, candidateBody, jaccardThreshold)) {
+            cluster.members.push(candidate);
+            return true;
+        }
+    }
+    return false;
+}
+function clusterPartition(records, jaccardThreshold, cancellationSignal) {
+    // Order inputs so the OLDEST record in any group of similar records becomes the canonical
+    // member (cluster.canonical). Without this, the canonical would depend on input order — a
+    // determinism break.
+    const ordered = [...records].sort(compareRecordsByAge);
+    const partition = [];
+    for (const record of ordered) {
+        if (cancellationSignal?.() === true) {
+            return { clusters: partition, canceled: true };
+        }
+        const prepared = prepareBody(record.body);
+        if (tryJoinExistingCluster(partition, record, prepared, jaccardThreshold))
+            continue;
+        partition.push({
+            canonical: record,
+            canonicalBody: prepared,
+            members: [record],
+        });
+    }
+    return { clusters: partition, canceled: false };
+}
+function finalizeCluster(cluster) {
+    const sortedMembers = [...cluster.members].sort(compareRecordsByAge);
+    return {
+        canonicalId: cluster.canonical.id,
+        members: sortedMembers,
+    };
+}
+// Public entry point. Returns clusters of size >= 2 only; singletons are filtered out.
+// Output is deterministic for any permutation of `records`.
+export function scanDuplicateClusters(records, jaccardThreshold, options = {}) {
+    const partitions = new Map();
+    for (const record of records) {
+        const key = partitionKey(record);
+        const bucket = partitions.get(key);
+        if (bucket === undefined) {
+            partitions.set(key, [record]);
+        }
+        else {
+            bucket.push(record);
+        }
+    }
+    const clusters = [];
+    let canceled = false;
+    for (const bucket of partitions.values()) {
+        const built = clusterPartition(bucket, jaccardThreshold, options.cancellationSignal);
+        canceled ||= built.canceled;
+        for (const cluster of built.clusters) {
+            if (cluster.members.length >= 2) {
+                clusters.push(finalizeCluster(cluster));
+            }
+        }
+        if (canceled)
+            break;
+    }
+    // Stable cluster ordering: by canonical id (the oldest member's id is unique per cluster).
+    return {
+        clusters: clusters.sort((a, b) => a.canonicalId < b.canonicalId ? -1 : a.canonicalId > b.canonicalId ? 1 : 0),
+        canceled,
+    };
+}
+export function findDuplicateClusters(records, jaccardThreshold) {
+    return scanDuplicateClusters(records, jaccardThreshold).clusters;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { KEIKO_MEMORY_CONSOLIDATION_VERSION } from "./version.js";
+export type { ConsolidationJob, ConsolidationJobState, ConsolidationOptions, ConsolidationResult, ProposedAction, ReviewItem, ReviewReason, StaleFlag, StaleReason, } from "./types.js";
+export { runConsolidation } from "./consolidate.js";
+export { buildConsolidationJob, ConsolidationJobError, transitionJob, type ConsolidationJobErrorCode, } from "./job.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kCAAkC,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,SAAS,EACT,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,KAAK,yBAAyB,GAC/B,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Public surface of @oscharko-dev/keiko-memory-consolidation (Epic #204 child #208).
+// Keeping this file the SOLE entry point prevents downstream packages from reaching into
+// private modules (ADR-0019 trust rule 7). Internal modules (dedupe, stale, conflicts,
+// similarity, _ordering, _constants) are package-private.
+export { KEIKO_MEMORY_CONSOLIDATION_VERSION } from "./version.js";
+export { runConsolidation } from "./consolidate.js";
+export { buildConsolidationJob, ConsolidationJobError, transitionJob, } from "./job.js";

package/dist/job.d.ts

@@ -0,0 +1,11 @@
+import type { ConsolidationJob, ConsolidationJobState } from "./types.js";
+export type ConsolidationJobErrorCode = "invalid-transition";
+export declare class ConsolidationJobError extends Error {
+    readonly code: ConsolidationJobErrorCode;
+    readonly from: ConsolidationJobState;
+    readonly to: ConsolidationJobState;
+    constructor(code: ConsolidationJobErrorCode, from: ConsolidationJobState, to: ConsolidationJobState);
+}
+export declare function buildConsolidationJob(id: string, startedAtMs: number): ConsolidationJob;
+export declare function transitionJob(job: ConsolidationJob, to: ConsolidationJobState, patch?: Partial<Pick<ConsolidationJob, "result" | "completedAt" | "error">>): ConsolidationJob;
+//# sourceMappingURL=job.d.ts.map

package/dist/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAuB,MAAM,YAAY,CAAC;AAE/F,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC;AAE7D,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,yBAAyB,CAAC;IAChD,SAAgB,IAAI,EAAE,qBAAqB,CAAC;IAC5C,SAAgB,EAAE,EAAE,qBAAqB,CAAC;gBAExC,IAAI,EAAE,yBAAyB,EAC/B,IAAI,EAAE,qBAAqB,EAC3B,EAAE,EAAE,qBAAqB;CAQ5B;AAqBD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAEvF;AAKD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,gBAAgB,EACrB,EAAE,EAAE,qBAAqB,EACzB,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC,CAAC,GAC1E,gBAAgB,CAMlB"}

package/dist/job.js

@@ -0,0 +1,82 @@
+// ConsolidationJob value-object lifecycle. NOT a process. The package does not spawn jobs,
+// schedule them, or persist them; callers (a scheduler / UI button / workflow orchestrator)
+// drive the state machine via `buildConsolidationJob` + `transitionJob`. This keeps the layer
+// purely deterministic — id allocation, clock reads, and persistence stay outside.
+//
+// State machine (see ConsolidationJobState in types.ts):
+//
+//   queued --> running     (start)
+//   queued --> canceled    (operator cancels before start)
+//   queued --> skipped     (engine returned state "skipped" before any cluster inspection)
+//   running --> completed  (engine returned "completed")
+//   running --> failed     (engine returned "failed")
+//   running --> canceled   (engine returned "canceled" mid-run)
+//
+// All terminal states (completed, failed, canceled, skipped) are absorbing: any transition
+// out of them throws `ConsolidationJobError("invalid-transition")`. There is no transition
+// queued -> completed: the engine must observe at least the "running" state for the lifecycle
+// to remain auditable.
+export class ConsolidationJobError extends Error {
+    code;
+    from;
+    to;
+    constructor(code, from, to) {
+        super(`ConsolidationJobError(${code}): ${from} -> ${to}`);
+        this.name = "ConsolidationJobError";
+        this.code = code;
+        this.from = from;
+        this.to = to;
+    }
+}
+// Static transition matrix. Encoded as a Readonly<Record<...>> so adding a new state is a
+// compile-time error (every key must be supplied).
+const ALLOWED_TRANSITIONS = {
+    queued: ["running", "canceled", "skipped"],
+    running: ["completed", "failed", "canceled"],
+    completed: [],
+    failed: [],
+    canceled: [],
+    skipped: [],
+};
+function isLegalTransition(from, to) {
+    return ALLOWED_TRANSITIONS[from].includes(to);
+}
+// Constructs a fresh queued job. `startedAt` is recorded eagerly so the caller can compute
+// elapsedMs at the terminal-transition site without a separate clock read in this layer.
+export function buildConsolidationJob(id, startedAtMs) {
+    return { id, state: "queued", startedAt: startedAtMs };
+}
+// Transitions a job to a new state, optionally merging in a result, completedAt, or error.
+// Throws ConsolidationJobError when the transition is illegal. The input job is never
+// mutated — every successful call returns a NEW object.
+export function transitionJob(job, to, patch) {
+    if (!isLegalTransition(job.state, to)) {
+        throw new ConsolidationJobError("invalid-transition", job.state, to);
+    }
+    const next = { ...job, state: to };
+    return applyPatch(next, patch);
+}
+function applyPatch(job, patch) {
+    if (patch === undefined)
+        return job;
+    const merged = { ...job };
+    if (patch.result !== undefined) {
+        return mergeResult(merged, patch.result, patch.completedAt, patch.error);
+    }
+    if (patch.completedAt !== undefined) {
+        return {
+            ...merged,
+            completedAt: patch.completedAt,
+            ...(patch.error !== undefined ? { error: patch.error } : {}),
+        };
+    }
+    if (patch.error !== undefined) {
+        return { ...merged, error: patch.error };
+    }
+    return merged;
+}
+function mergeResult(job, result, completedAt, error) {
+    const withResult = { ...job, result };
+    const withCompletedAt = completedAt !== undefined ? { ...withResult, completedAt } : withResult;
+    return error !== undefined ? { ...withCompletedAt, error } : withCompletedAt;
+}

package/dist/similarity.d.ts

@@ -0,0 +1,10 @@
+export declare function normalizeBody(body: string): string;
+export declare function bigramTokens(normalized: string): Set<string>;
+export interface PreparedBody {
+    readonly normalized: string;
+    readonly tokens: ReadonlySet<string>;
+}
+export declare function prepareBody(body: string): PreparedBody;
+export declare function jaccardSimilarityPrepared(a: PreparedBody, b: PreparedBody): number;
+export declare function jaccardSimilarity(a: string, b: string): number;
+//# sourceMappingURL=similarity.d.ts.map

package/dist/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../src/similarity.ts"],"names":[],"mappings":"AA0BA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAKD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAM5D;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAMtD;AAED,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CASlF;AAKD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/similarity.js

@@ -0,0 +1,65 @@
+// String-similarity primitives used by dedupe and conflict detection. Pure functions, bounded
+// work, no unbounded regex backtracking — `normalizeBody` walks the input once character-by-
+// character so an adversarial input cannot push it beyond O(n).
+//
+// Design choices:
+//   • Character bigrams (not word bigrams) — robust to whitespace drift and short utterances
+//     ("yes" vs "yep" share "ye"). The cost is sensitivity to spelling variants, which is
+//     acceptable for v1 (the Jaccard threshold backs off recall in exchange for precision).
+//   • Set-based Jaccard (not multiset) — collapses repeated bigrams. Same precision intuition.
+//   • Punctuation stripping is char-class based (Unicode-aware via `RegExp` `\p{...}` escapes
+//     in a NON-greedy single-char form so there is no backtracking; the `g` flag walks the
+//     string linearly). Lowercase is locale-independent (`String.prototype.toLowerCase` uses
+//     case-folding without locale; we deliberately do NOT call `toLocaleLowerCase` because the
+//     output must be byte-stable across hosts).
+// Single-character matcher: anything that is NOT a Unicode letter, digit, or whitespace.
+// Strips ASCII punctuation, NUL bytes, control chars, and emoji-adjacent symbols. Uses the
+// `u` flag (Unicode-aware character classes) and a SINGLE quantifier (no nesting) — no ReDoS.
+const PUNCT_OR_CONTROL = /[^\p{L}\p{N}\s]/gu;
+// Whitespace run matcher. `\s+` over a finite input has linear time; no nesting.
+const WHITESPACE_RUN = /\s+/g;
+// Normalizes a memory body for similarity comparison. Output is lowercase, NUL-free, with
+// internal whitespace collapsed to single spaces, leading/trailing whitespace stripped, and
+// ASCII/Unicode punctuation removed. Returns `""` when no normalizable characters survive.
+export function normalizeBody(body) {
+    const lowered = body.toLowerCase();
+    const stripped = lowered.replace(PUNCT_OR_CONTROL, "");
+    const collapsed = stripped.replace(WHITESPACE_RUN, " ");
+    return collapsed.trim();
+}
+// Builds the set of character bigrams of a normalized string. Returns an empty Set for inputs
+// shorter than 2 characters (no bigrams to form). Uses a Set (not an array) so the caller can
+// take set-intersection in O(min(|a|, |b|)) for Jaccard.
+export function bigramTokens(normalized) {
+    const tokens = new Set();
+    for (let i = 0; i + 1 < normalized.length; i += 1) {
+        tokens.add(normalized.slice(i, i + 2));
+    }
+    return tokens;
+}
+export function prepareBody(body) {
+    const normalized = normalizeBody(body);
+    return {
+        normalized,
+        tokens: bigramTokens(normalized),
+    };
+}
+export function jaccardSimilarityPrepared(a, b) {
+    if (a.tokens.size === 0 && b.tokens.size === 0)
+        return 1;
+    if (a.tokens.size === 0 || b.tokens.size === 0)
+        return 0;
+    let intersectionSize = 0;
+    for (const token of a.tokens) {
+        if (b.tokens.has(token))
+            intersectionSize += 1;
+    }
+    const unionSize = a.tokens.size + b.tokens.size - intersectionSize;
+    return intersectionSize / unionSize;
+}
+// Jaccard similarity of two strings over their normalized character-bigram sets. Returns 1 for
+// two empty inputs (vacuously similar — they map to the same equivalence class) and 0 when one
+// side is empty but the other is not (no overlap is possible). Output is in [0, 1].
+export function jaccardSimilarity(a, b) {
+    return jaccardSimilarityPrepared(prepareBody(a), prepareBody(b));
+}

package/dist/stale.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+import type { StaleFlag } from "./types.js";
+export interface StaleOptions {
+    readonly nowMs: number;
+    readonly staleConfidenceThreshold: number;
+    readonly maxAgeMs: number;
+}
+export declare function findStaleMemories(records: readonly MemoryRecord[], options: StaleOptions): readonly StaleFlag[];
+//# sourceMappingURL=stale.d.ts.map

package/dist/stale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale.d.ts","sourceRoot":"","sources":["../src/stale.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,sCAAsC,CAAC;AAGvF,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA6BD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE,YAAY,GACpB,SAAS,SAAS,EAAE,CAUtB"}

package/dist/stale.js

@@ -0,0 +1,54 @@
+// Stale-memory detection. Pure function; deterministic; never mutates input.
+//
+// Three independent reasons may fire per record (a record can be both "expired" AND
+// "low-confidence" simultaneously — each produces its own StaleFlag). The full set per record
+// is enumerated so the caller can route each reason to a distinct review surface.
+//
+// Pinned-exemption invariant: a pinned record NEVER produces a StaleFlag, regardless of
+// validity, confidence, or age. This is an Epic #204 hard rule — pinning is the user's
+// explicit "never auto-degrade this" signal.
+//
+// Terminal-status skip: records in `rejected` or `forgotten` are skipped entirely — they have
+// no active lifecycle for consolidation to touch. `archived` and `superseded` records are NOT
+// skipped here: archival is reversible (status transitions allow `archived → accepted`), and a
+// stale flag on a superseded record may still inform the audit trail. Trading false-positives
+// for absent signal is the safer default; the caller filters by status if needed.
+import { compareStaleFlags } from "./_ordering.js";
+// Records in these statuses are skipped entirely: they have no consolidation work to do.
+// `conflicted` and `proposed` are included because they are pending human review — emitting
+// stale flags for records the reviewer hasn't accepted yet would produce false signal.
+const SKIPPED_STATUSES = new Set(["rejected", "forgotten", "conflicted", "proposed"]);
+function isExpired(record, nowMs) {
+    const { validUntil } = record.validity;
+    return validUntil !== undefined && validUntil <= nowMs;
+}
+function isLowConfidence(record, threshold) {
+    return record.provenance.confidence <= threshold;
+}
+function isAgedOut(record, nowMs, maxAgeMs) {
+    return record.updatedAt + maxAgeMs <= nowMs;
+}
+function collectReasonsFor(record, options) {
+    const reasons = [];
+    if (isExpired(record, options.nowMs))
+        reasons.push("expired");
+    if (isLowConfidence(record, options.staleConfidenceThreshold))
+        reasons.push("low-confidence");
+    if (isAgedOut(record, options.nowMs, options.maxAgeMs))
+        reasons.push("aged-out");
+    return reasons;
+}
+// Public entry. Returns flags sorted by (memoryId ASC, reason ASC) for byte-stable output.
+export function findStaleMemories(records, options) {
+    const flags = [];
+    for (const record of records) {
+        if (record.pinned)
+            continue;
+        if (SKIPPED_STATUSES.has(record.status))
+            continue;
+        for (const reason of collectReasonsFor(record, options)) {
+            flags.push({ memoryId: record.id, reason, detectedAt: options.nowMs });
+        }
+    }
+    return flags.sort(compareStaleFlags);
+}