akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/commands/improve/recombine.js

@@ -0,0 +1,488 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * #609 — recombine / synthesize pass.
+ *
+ * A whole-corpus synthesis stage that runs AFTER consolidation and is OPT-IN
+ * (default disabled via `IMPROVE_PROCESS_DEFAULTS.recombine`). It clusters
+ * memories by RELATEDNESS (shared tags / graph entities — NEVER embedding
+ * similarity), issues ONE bounded LLM call per cluster to induce a single
+ * cross-episodic generalization, and emits the result as a NORMAL pending
+ * proposal with frontmatter `type: hypothesis` through the existing proposal
+ * queue + quality gate.
+ *
+ * Two-pass contract: the first pass ONLY ever emits `type: hypothesis`
+ * proposals — never a `type: lesson`. Promotion to a lesson happens on a later
+ * confirmation run once the same generalization has been re-induced
+ * `confirmThreshold` times (#625). The confirmation count is persisted in the
+ * `recombine_hypotheses` state.db table (migration 014), keyed by the
+ * deterministic `deriveRecombineLessonRef` value so re-induction of the SAME
+ * member-set maps back to the SAME row. When the count reaches the threshold,
+ * the run emits ONE `type: lesson` promotion proposal through the SAME proposal
+ * queue + quality gate (createProposal + validateProposalFrontmatter), NEVER a
+ * direct stash write, then marks the row promoted (resetting its count) so it is
+ * not re-promoted on every subsequent run. Hypotheses NOT re-induced in a run
+ * have their consecutive streak reset (decay-to-zero).
+ *
+ * NAMESPACE note: the ref stays `lesson:recombined/<slug>-<hash>` for BOTH
+ * passes. The ref is the promotion TARGET asset (a lesson in both the hypothesis
+ * and promoted states), so re-induction must map to the same ref and the ref
+ * cannot encode the proposal type. The hypothesis-vs-lesson distinction is
+ * carried ONLY by the proposal frontmatter `type` field. On promotion the prior
+ * pending `type: hypothesis` proposal for that ref is superseded (rejected) so
+ * the queue never shows two proposals for one ref.
+ *
+ * A justified null (the LLM determines no defensible generalization exists) is
+ * an acceptable outcome: it produces no proposal and records a
+ * `recombine_invoked` event with `outcome: 'null_returned'`.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import recombineSystemPrompt from "../../assets/prompts/recombine-system.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { appendEvent } from "../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { decayUnseenRecombineHypotheses, getRecombineHypothesis, getStateDbPath, markRecombineHypothesisPromoted, openStateDatabase, recordRecombineInduction, } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+import { validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
+import { archiveProposal, createProposal, isProposalSkipped, listProposals } from "../proposal/validators/proposals.js";
+import { isConsolidationEligibleMemoryName } from "./consolidate.js";
+const RECOMBINE_SYSTEM_PROMPT = recombineSystemPrompt;
+const DEFAULT_MIN_CLUSTER_SIZE = 3;
+const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
+const DEFAULT_RELATEDNESS_SOURCE = "tags";
+/** #625 — re-induction count required before a hypothesis promotes to a lesson. */
+const DEFAULT_CONFIRM_THRESHOLD = 2;
+// ── Clustering by relatedness (NOT similarity) ────────────────────────────────
+/**
+ * Build relatedness clusters from the memory pool. Clustering is driven purely
+ * by shared tags / graph entities — it MUST NOT use embedding similarity, so
+ * textually near-identical memories that share no relatedness signal never
+ * cluster together.
+ *
+ * For `relatednessSource`:
+ *   - `"tags"`  — group by each frontmatter tag.
+ *   - `"graph"` — group by shared `graph_file_entities.entity_norm`; falls back
+ *                 to tags when the graph table is empty (fail-open).
+ *   - `"both"`  — union of the tag and entity grouping keys.
+ *
+ * A cluster is a signal whose member set is >= `minClusterSize`. Overlapping
+ * clusters are de-duplicated by member-set identity, and the result is capped
+ * to `maxClustersPerRun` by member-count descending.
+ */
+export function buildRelatednessClusters(entries, opts) {
+    // Only consolidation-eligible memories participate (exclude `.derived`).
+    const memories = entries.filter((e) => e.entry.type === "memory" && isConsolidationEligibleMemoryName(e.entry.name));
+    // signal -> member entries
+    const groups = new Map();
+    const add = (signal, entry) => {
+        const key = signal.trim();
+        if (!key)
+            return;
+        const list = groups.get(key);
+        if (list) {
+            if (!list.includes(entry))
+                list.push(entry);
+        }
+        else {
+            groups.set(key, [entry]);
+        }
+    };
+    const useTags = opts.relatednessSource === "tags" || opts.relatednessSource === "both";
+    // Graph relatedness falls open to tags when no entities are available.
+    const hasEntities = !!opts.entityByEntryId && opts.entityByEntryId.size > 0;
+    const useGraph = (opts.relatednessSource === "graph" || opts.relatednessSource === "both") && hasEntities;
+    const tagsFallback = !useTags && opts.relatednessSource === "graph" && !hasEntities;
+    for (const entry of memories) {
+        if (useTags || tagsFallback) {
+            for (const tag of entry.entry.tags ?? [])
+                add(`tag:${tag}`, entry);
+        }
+        if (useGraph && opts.entityByEntryId) {
+            for (const ent of opts.entityByEntryId.get(entry.id) ?? [])
+                add(`entity:${ent}`, entry);
+        }
+    }
+    // Keep only groups at or above the minimum cluster size.
+    let clusters = [];
+    for (const [signature, members] of groups) {
+        if (members.length >= opts.minClusterSize)
+            clusters.push({ signature, members });
+    }
+    // De-duplicate clusters that share the exact same member set (e.g. a tag and
+    // an entity that co-occur on the same trio). Keep the first by signature.
+    const seenMemberKeys = new Set();
+    clusters = clusters.filter((c) => {
+        const memberKey = c.members
+            .map((m) => m.id)
+            .sort((a, b) => a - b)
+            .join(",");
+        if (seenMemberKeys.has(memberKey))
+            return false;
+        seenMemberKeys.add(memberKey);
+        return true;
+    });
+    // Cap to maxClustersPerRun, largest clusters first (deterministic tiebreak).
+    clusters.sort((a, b) => b.members.length - a.members.length || a.signature.localeCompare(b.signature));
+    return clusters.slice(0, Math.max(0, opts.maxClustersPerRun));
+}
+// ── Prompt + ref derivation ───────────────────────────────────────────────────
+/** Read a memory body (frontmatter stripped) for the cluster prompt. */
+function readBody(entry) {
+    try {
+        const raw = fs.readFileSync(entry.filePath, "utf8");
+        return parseFrontmatter(raw).content.trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Assemble the per-cluster user prompt fed to the recombine LLM. */
+export function buildClusterPrompt(cluster) {
+    const lines = [
+        `Shared signal: ${cluster.signature}`,
+        `Cluster of ${cluster.members.length} related memories:`,
+        "",
+    ];
+    for (const m of cluster.members) {
+        lines.push(`[memory:${m.entry.name}]`);
+        if (m.entry.description)
+            lines.push(`Description: ${m.entry.description}`);
+        const body = readBody(m);
+        if (body)
+            lines.push(body);
+        lines.push("");
+    }
+    lines.push("Induce ONE cross-episodic generalization these memories support, or return an explicit null if none is defensible.");
+    return lines.join("\n");
+}
+/**
+ * Stable lesson ref for a cluster. The hash of the sorted member refs keeps the
+ * ref deterministic across runs (so re-induction maps to the same ref + the
+ * content-hash dedup in createProposal suppresses queue churn).
+ */
+export function deriveRecombineLessonRef(cluster) {
+    const slug = cluster.signature
+        .replace(/^(tag|entity):/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    const memberKey = recombineMemberKey(cluster);
+    const hash = createHash("sha256").update(memberKey, "utf8").digest("hex").slice(0, 8);
+    return `lesson:recombined/${slug || "cluster"}-${hash}`;
+}
+/**
+ * The membership fingerprint of a cluster: its member entryKeys sorted and
+ * joined. Single source of truth shared by {@link deriveRecombineLessonRef}'s
+ * hash and the `recombine_hypotheses.member_key` column, so the table key and
+ * the ref hash always derive from the SAME member set. Adding/removing one
+ * memory yields a different fingerprint → a different ref → a fresh row (the
+ * old streak is correctly NOT inherited).
+ */
+export function recombineMemberKey(cluster) {
+    return cluster.members
+        .map((m) => m.entryKey)
+        .sort()
+        .join("|");
+}
+/** Parse the raw LLM output into a generalization, or `null` for the justified-null path. */
+function parseGeneralization(raw) {
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "null")
+        return null;
+    const parsed = parseEmbeddedJsonResponse(trimmed);
+    if (parsed === undefined || parsed === null)
+        return null;
+    if (typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    const description = typeof obj.description === "string" ? obj.description : "";
+    const body = typeof obj.body === "string" ? obj.body : "";
+    const when_to_use = typeof obj.when_to_use === "string" ? obj.when_to_use : undefined;
+    // An empty object / all-empty fields is treated as a justified null.
+    if (!description && !body)
+        return null;
+    return { description, body, ...(when_to_use ? { when_to_use } : {}) };
+}
+/**
+ * Resolve the production LLM seam from the active improve profile. Returns a
+ * `RecombineLlmFn` that issues one bounded chatCompletion per call, or
+ * `undefined` when no LLM is configured (the pass then makes no calls).
+ */
+function resolveProductionLlmFn(config, signal) {
+    const recombineProcess = config.profiles?.improve?.default?.processes?.recombine;
+    const runnerSpec = resolveImproveProcessRunnerFromProfile(recombineProcess, config);
+    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
+    if (!llmConfig)
+        return undefined;
+    return async (clusterPrompt) => {
+        const messages = [
+            { role: "system", content: RECOMBINE_SYSTEM_PROMPT },
+            { role: "user", content: clusterPrompt },
+        ];
+        try {
+            return await chatCompletion(llmConfig, messages, { signal, enableThinking: false });
+        }
+        catch (e) {
+            warn(`[recombine] LLM call failed: ${String(e)}`);
+            return null;
+        }
+    };
+}
+// ── Main entry point ───────────────────────────────────────────────────────────
+export async function akmRecombine(opts) {
+    const startMs = Date.now();
+    const config = opts.config ?? loadConfig();
+    const stashDir = opts.stashDir ?? resolveStashDir();
+    const sourceRun = opts.sourceRun ?? `recombine-${startMs}`;
+    const eligibilitySource = opts.eligibilitySource ?? "recombine";
+    const minClusterSize = opts.minClusterSize ?? DEFAULT_MIN_CLUSTER_SIZE;
+    const maxClustersPerRun = opts.maxClustersPerRun ?? DEFAULT_MAX_CLUSTERS_PER_RUN;
+    const relatednessSource = opts.relatednessSource ?? DEFAULT_RELATEDNESS_SOURCE;
+    const confirmThreshold = opts.confirmThreshold ?? DEFAULT_CONFIRM_THRESHOLD;
+    const warnings = [];
+    const finish = (over) => ({
+        schemaVersion: 1,
+        ok: true,
+        clustersFormed: 0,
+        proposalsEmitted: 0,
+        lessonsPromoted: 0,
+        nullsReturned: 0,
+        durationMs: Date.now() - startMs,
+        warnings,
+        ...over,
+    });
+    // Budget guard: an already-aborted signal short-circuits before any LLM call.
+    if (opts.signal?.aborted) {
+        return finish({ ok: false, warnings: [...warnings, "aborted-before-start"] });
+    }
+    // Load the memory pool + (optionally) graph entities from the index.
+    let entries = [];
+    let entityByEntryId;
+    let db;
+    try {
+        db = openExistingDatabase();
+        entries = getAllEntries(db, "memory");
+        if (relatednessSource === "graph" || relatednessSource === "both") {
+            try {
+                entityByEntryId = getEntitiesByEntryIds(db, entries.map((e) => e.id));
+            }
+            catch {
+                // Fail open to tag relatedness.
+                entityByEntryId = undefined;
+            }
+        }
+    }
+    catch (e) {
+        warnings.push(`recombine: failed to open index — ${String(e)}`);
+        return finish({ ok: false });
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    const clusters = buildRelatednessClusters(entries, {
+        minClusterSize,
+        maxClustersPerRun,
+        relatednessSource,
+        ...(entityByEntryId ? { entityByEntryId } : {}),
+    });
+    let clustersFormed = 0;
+    let proposalsEmitted = 0;
+    let lessonsPromoted = 0;
+    let nullsReturned = 0;
+    const llmFn = opts.recombineLlmFn ?? resolveProductionLlmFn(config, opts.signal);
+    if (!llmFn) {
+        warnings.push("recombine: no LLM configured — skipping");
+        return finish({ clustersFormed: 0 });
+    }
+    // #625 — open the confirmation-count store once per run via the ctx seam,
+    // reusing a long-lived ctx.db handle when the caller provided one (mirrors
+    // proposals.ts). Only handles WE opened are closed in the finally below.
+    const ownStateDb = opts.ctx?.db ? undefined : openStateDatabase(opts.ctx?.dbPath ?? getStateDbPath());
+    const stateDb = opts.ctx?.db ?? ownStateDb;
+    // Refs re-induced (defensible generalization passed the quality gate) THIS
+    // run — everything else is decayed after the loop.
+    const seenThisRun = new Set();
+    try {
+        for (const cluster of clusters) {
+            if (opts.signal?.aborted) {
+                warnings.push("aborted-mid-run");
+                break;
+            }
+            clustersFormed += 1;
+            const prompt = buildClusterPrompt(cluster);
+            const raw = await llmFn(prompt);
+            const generalization = parseGeneralization(raw);
+            if (!generalization) {
+                nullsReturned += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: deriveRecombineLessonRef(cluster),
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "null_returned",
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            const lessonRef = deriveRecombineLessonRef(cluster);
+            const sourceRefs = cluster.members.map((m) => `memory:${m.entry.name}`);
+            // Quality gate (always-run): the frontmatter description must be present
+            // and non-truncated. This runs BEFORE createProposal on BOTH the
+            // hypothesis and the promotion paths — never bypassed.
+            const fmCheck = validateProposalFrontmatter({ description: generalization.description });
+            if (!fmCheck.ok) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "quality_rejected",
+                        reason: fmCheck.reason,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            // A defensible generalization was produced this run — record it so it is
+            // NOT decayed by the unseen sweep below.
+            seenThisRun.add(lessonRef);
+            // #625 — record the re-induction and read the prior promotion state. The
+            // member key and the ref hash derive from the SAME member set, so
+            // re-induction of an identical cluster maps back to the same row.
+            const nowIso = new Date().toISOString();
+            const priorRow = stateDb ? getRecombineHypothesis(stateDb, lessonRef) : undefined;
+            const alreadyPromoted = priorRow?.promoted_at != null;
+            const count = stateDb
+                ? recordRecombineInduction(stateDb, {
+                    hypothesisRef: lessonRef,
+                    signature: cluster.signature,
+                    memberKey: recombineMemberKey(cluster),
+                    seenAt: nowIso,
+                    run: sourceRun,
+                })
+                : 0;
+            // Promote to a `type: lesson` proposal when the confirmation streak
+            // reaches the threshold AND the hypothesis has not already been promoted.
+            const promote = stateDb != null && !alreadyPromoted && count >= confirmThreshold;
+            const proposalType = promote ? "lesson" : "hypothesis";
+            const frontmatter = {
+                type: proposalType,
+                description: generalization.description,
+                ...(generalization.when_to_use ? { when_to_use: generalization.when_to_use } : {}),
+                source_refs: sourceRefs,
+            };
+            const content = assembleContent(frontmatter, generalization.body);
+            if (promote && stateDb) {
+                // Supersede the prior pending `type: hypothesis` proposal for this ref so
+                // the queue never shows two proposals for one ref. The promoted lesson
+                // proposal has different content (type changed), so content-hash dedup
+                // would otherwise let both co-exist.
+                for (const stale of listProposals(stashDir, { status: "pending", ref: lessonRef }, opts.ctx)) {
+                    if (stale.source === "recombine") {
+                        archiveProposal(stashDir, stale.id, "rejected", "superseded by recombine lesson promotion", opts.ctx);
+                    }
+                }
+            }
+            const proposalResult = createProposal(stashDir, {
+                ref: lessonRef,
+                source: "recombine",
+                sourceRun,
+                payload: { content, frontmatter: { description: generalization.description } },
+                eligibilitySource,
+                // The promotion is a distinct asset (lesson) for the same ref; force
+                // past the duplicate-pending guard (the stale hypothesis was just
+                // superseded, but force keeps the path robust to ordering).
+                ...(promote ? { force: true } : {}),
+            }, opts.ctx);
+            if (isProposalSkipped(proposalResult)) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "skipped",
+                        skipReason: proposalResult.reason,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            if (promote && stateDb) {
+                markRecombineHypothesisPromoted(stateDb, lessonRef, nowIso);
+                lessonsPromoted += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "promoted",
+                        proposalId: proposalResult.id,
+                        confirmationCount: count,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+            }
+            else {
+                proposalsEmitted += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "queued",
+                        proposalId: proposalResult.id,
+                        confirmationCount: count,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+            }
+        }
+        // #625 — decay hypotheses NOT re-induced this run (reset their consecutive
+        // streak) so confirmation is per-consecutive-run and conservative (AC4).
+        if (stateDb) {
+            const decayedCount = decayUnseenRecombineHypotheses(stateDb, sourceRun, [...seenThisRun]);
+            if (decayedCount > 0) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    metadata: { outcome: "decayed", decayedCount, sourceRun },
+                }, opts.ctx);
+            }
+        }
+    }
+    finally {
+        if (ownStateDb)
+            ownStateDb.close();
+    }
+    return finish({ clustersFormed, proposalsEmitted, lessonsPromoted, nullsReturned });
+}
+/** Serialize frontmatter + body into a markdown asset string. */
+function assembleContent(frontmatter, body) {
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (Array.isArray(value)) {
+            lines.push(`${key}: [${value.map((v) => JSON.stringify(v)).join(", ")}]`);
+        }
+        else {
+            lines.push(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+        }
+    }
+    lines.push("---", "", body, "");
+    return lines.join("\n");
+}

package/dist/commands/improve/reflect.js

@@ -383,6 +383,25 @@ function splitFrontmatter(raw) {
         return { fmText: null, body: raw };
     return { fmText: m[1], body: m[2] };
 }
+/**
+ * Strip an LLM-appended duplicate frontmatter block from a body string.
+ *
+ * When the LLM echoes the original source file verbatim after its rewrite,
+ * the resulting body contains a second `---...---` YAML block. We detect it
+ * by requiring BOTH a balanced fence (opening + closing `---`) AND YAML-like
+ * `key: value` content inside, so legitimate Markdown thematic breaks and
+ * code-fence examples are never truncated.
+ */
+function stripAppendedFrontmatter(body) {
+    const fencePattern = /\n---\r?\n([\s\S]*?)\n---\r?\n/;
+    const match = body.match(fencePattern);
+    if (!match)
+        return body;
+    // Only strip when the captured block looks like YAML frontmatter.
+    if (!/^\w[\w-]*:/m.test(match[1]))
+        return body;
+    return body.slice(0, body.indexOf(match[0])).replace(/\s+$/, "");
+}
 /**
  * Reflect post-processor — enforces the safety rails described at the top of
  * this file:
@@ -449,7 +468,7 @@ function sanitizeReflectPayload(payload, sourceContent, targetRef) {
             mergedFm[field] = sourceFm[field];
         }
     }
-    const cleanedBody = rawLlmBody.replace(/^\s+/, "");
+    const cleanedBody = stripAppendedFrontmatter(rawLlmBody.replace(/^\s+/, ""));
     // Size guard — only when source body is meaningfully large. The pure
     // predicate lives in `core/proposal-quality-validators` so the same check
     // also runs inside `runProposalValidators` on `proposal accept`.

package/dist/commands/improve/related-sessions.js

@@ -0,0 +1,120 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * #627 — getRelatedSessions helper.
+ *
+ * Finds session assets related to a seed by SHARED TAGS / GRAPH ENTITIES —
+ * NEVER embedding similarity. Modeled on recombine.ts buildRelatednessClusters:
+ * two sessions relate when they share at least one *topic* tag or graph entity;
+ * two textually near-identical sessions with no shared topic signal do NOT
+ * relate. This makes the helper a pure query-layer relatedness lookup that
+ * makes NO network / embedding calls.
+ *
+ * The generic base tags every session asset carries (`session` + the harness
+ * id, see session-asset.ts) are IGNORED for relatedness — otherwise every
+ * session would trivially relate to every other. Callers should therefore seed
+ * with derived topic tags, but the helper defensively strips the generic base
+ * tags from candidate sessions too.
+ *
+ * Relatedness source:
+ *   - `"tags"`  — score by count of (seedTags ∩ session tags).
+ *   - `"graph"` — score by count of (seedEntities ∩ session graph entities);
+ *                 falls open to tag relatedness when the graph table is empty.
+ *   - `"both"`  — sum of the tag + entity overlap.
+ */
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
+/** Generic base tags every session asset carries — never a relatedness signal. */
+const GENERIC_SESSION_TAGS = new Set(["session"]);
+/**
+ * Build the set of topic tags for a session entry, excluding generic base tags
+ * (`session`) and the harness segment of the entry name (the harness id is the
+ * first path component of `<harness>/<id>` and is also carried as a base tag).
+ */
+function topicTagsForSession(entry) {
+    const harness = entry.entry.name.split("/")[0];
+    const result = new Set();
+    for (const tag of entry.entry.tags ?? []) {
+        if (GENERIC_SESSION_TAGS.has(tag))
+            continue;
+        if (harness && tag === harness)
+            continue;
+        result.add(tag);
+    }
+    return result;
+}
+/**
+ * Find session assets related to a seed by shared tags / graph entities.
+ * Relatedness is signal-based, NOT embedding similarity.
+ */
+export function getRelatedSessions(opts) {
+    const seedTags = (opts.seedTags ?? [])
+        .filter((t) => !GENERIC_SESSION_TAGS.has(t))
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const seedEntities = (opts.seedEntities ?? []).map((e) => e.trim().toLowerCase()).filter(Boolean);
+    const minShared = opts.minShared ?? 1;
+    const limit = opts.limit ?? 5;
+    const relatednessSource = opts.relatednessSource ?? "tags";
+    const excludeRefs = new Set(opts.excludeRefs ?? []);
+    // Empty seed input → nothing to relate to.
+    if (seedTags.length === 0 && seedEntities.length === 0)
+        return [];
+    const seedTagSet = new Set(seedTags);
+    const seedEntitySet = new Set(seedEntities);
+    let db = opts.db;
+    let ownsDb = false;
+    if (!db) {
+        db = openExistingDatabase();
+        ownsDb = true;
+    }
+    try {
+        const sessions = getAllEntries(db, "session");
+        // Resolve graph entities for the candidate sessions when requested. Fail
+        // open to tag relatedness when the graph table is empty (no rows).
+        let entityByEntryId;
+        const wantGraph = relatednessSource === "graph" || relatednessSource === "both";
+        if (wantGraph) {
+            try {
+                entityByEntryId = getEntitiesByEntryIds(db, sessions.map((s) => s.id));
+            }
+            catch {
+                entityByEntryId = undefined;
+            }
+        }
+        const hasEntities = !!entityByEntryId && entityByEntryId.size > 0;
+        // Effective signal selection. "graph" with no entities falls open to tags.
+        const useTags = relatednessSource === "tags" || relatednessSource === "both" || (wantGraph && !hasEntities);
+        const useGraph = wantGraph && hasEntities;
+        const scored = [];
+        for (const session of sessions) {
+            const ref = makeAssetRef(session.entry.type, session.entry.name);
+            if (excludeRefs.has(ref))
+                continue;
+            let sharedCount = 0;
+            if (useTags && seedTagSet.size > 0) {
+                for (const tag of topicTagsForSession(session)) {
+                    if (seedTagSet.has(tag))
+                        sharedCount += 1;
+                }
+            }
+            if (useGraph && seedEntitySet.size > 0 && entityByEntryId) {
+                for (const ent of entityByEntryId.get(session.id) ?? []) {
+                    if (seedEntitySet.has(ent))
+                        sharedCount += 1;
+                }
+            }
+            if (sharedCount >= minShared) {
+                scored.push({ ref, name: session.entry.name, sharedCount });
+            }
+        }
+        // Rank by shared-signal count desc, then ref for a deterministic tiebreak.
+        scored.sort((a, b) => b.sharedCount - a.sharedCount || a.ref.localeCompare(b.ref));
+        return scored.slice(0, Math.max(0, limit));
+    }
+    finally {
+        if (ownsDb && db)
+            closeDatabase(db);
+    }
+}