Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Deep vault synthesis (Workspace Insight Suite, t_04e94382).
*
* Topic-scoped, deterministic evidence assembly: every note matching a
* topic is cross-referenced for agreements (positive typed relations
* between matched notes), contradictions (`contradicts` relations),
* stale claims (aged or superseded notes), and knowledge gaps
* (dangling wikilink targets). The dossier states exactly which
* dimensions were checked so an empty section is interpretable as
* "checked, nothing found" - prose synthesis stays with the calling
* agent, never inside core.
*
* Contradiction and gap findings convert into trigger candidates
* (Kernel B) via {@link synthesisCandidates}.
*/
import { requireVaultAdapter } from "../vault-adapter/index.ts";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { sha256Hex } from "../integrity/digest.ts";
import { search } from "../search/search.ts";
import { walkVault } from "../search/walker.ts";
import type { BrainSearchResult, ResolvedSearchConfig } from "../search/types.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
import { extractWikilinkRichBodies, parseWikilinkRich } from "./link-graph/parse-wikilink.ts";
import { fileAgeMs, msToWholeDays } from "./time.ts";
import type { InsightCandidate } from "./triggers/types.ts";
import { checkEntityContamination, type ContaminationEntityLike } from "./truth/contamination.ts";
const POSITIVE_RELATIONS: ReadonlySet<string> = new Set(["related", "extends", "supports"]);
export interface SynthesisNote {
readonly path: string;
readonly title: string | null;
readonly score: number;
}
export interface SynthesisAgreement {
readonly path: string;
readonly relation: string;
readonly target: string;
}
export interface SynthesisContradiction {
readonly path: string;
readonly target: string;
}
export interface SynthesisStaleClaim {
readonly path: string;
readonly ageDays: number;
readonly supersededBy: string | null;
}
export interface SynthesisGap {
readonly target: string;
readonly sources: ReadonlyArray<string>;
}
export interface SynthesisContamination {
/** The note asserting the entity. */
readonly path: string;
/** Canonical entity id mentioned but uncited. */
readonly entity: string;
/** The cited sources that fail to mention it. */
readonly sources: ReadonlyArray<string>;
}
/**
* Stable identity for a single piece of evidence grounding a finding
* (t_40fa4e8d). The identity is deliberately tied to retrievable
* content: `path` names the artifact, `kind` labels what class of
* artifact it is (`note`, `source_page`, `claim`, ...), and
* `contentHash` is a digest of the evidence bytes. A finding whose
* evidence cannot be resolved to concrete content has no identity and
* is gated out of emission.
*
* Exported for reuse by subject diarization (t_28ba3fc4), which builds
* the same identity for stated claims and behavioral-signal lines.
*/
export interface EvidenceIdentity {
/** Vault-relative path (or stable reference) of the grounding artifact. */
readonly path: string;
/** Artifact class label, e.g. `note`, `source_page`, `claim`. */
readonly kind: string;
/** Lowercase hex sha256 of the evidence bytes; ties identity to content. */
readonly contentHash: string;
}
/**
* True when the identity names a concrete, retrievable artifact: a
* non-empty path, a non-empty kind, and a non-empty content hash. The
* emission gate drops any finding whose evidence fails this predicate.
*/
export function hasEvidenceIdentity(
id: EvidenceIdentity | null | undefined,
): id is EvidenceIdentity {
return (
id !== null &&
id !== undefined &&
id.path.trim() !== "" &&
id.kind.trim() !== "" &&
id.contentHash.trim() !== ""
);
}
/** A typed relation that draws a note into the matched body. */
export interface SynthesisRelation {
readonly relation: string;
readonly target: string;
}
/**
* Additive causal context for a finding (t_40fa4e8d): the deterministic
* chain that explains why the note sits in the dossier. No generated
* prose - just the structural facts already gathered by the pass.
*/
export interface SynthesisCausalContext {
/** Typed relations connecting this note to the matched body. */
readonly relations: ReadonlyArray<SynthesisRelation>;
/** The `superseded_by` pointer bearing on the finding, or null. */
readonly supersededBy: string | null;
/** Dangling wikilink targets originating here (unverified links). */
readonly danglingCitations: number;
}
/**
* Decomposed, deterministic confidence components for one finding
* (t_40fa4e8d). Each is computed from data already flowing through the
* synthesis; none involves a model call or language analysis.
*/
export interface SynthesisConfidence {
/** Positive typed relations incident to this note within the matched body. */
readonly support: number;
/** Contradiction relations incident to this note. */
readonly opposition: number;
/** Recency in [0,1]: 1 = touched today, 0 = at/over the stale age. */
readonly freshness: number;
/** Resolvable citations originating in this note. */
readonly coverage: number;
}
/**
* A synthesis finding (t_40fa4e8d): one matched note carried with its
* evidence identity, causal context, and decomposed confidence. Only
* findings that clear the evidence-identity gate are emitted.
*/
export interface SynthesisFinding {
readonly evidence: EvidenceIdentity;
readonly title: string | null;
readonly causalContext: SynthesisCausalContext;
readonly confidence: SynthesisConfidence;
}
/** Why a candidate finding was gated out of emission (visible loss). */
export type SynthesisExclusionReason = "unreadable" | "no_evidence_identity";
/** One gated-out finding: its identifier plus the structural reason. */
export interface SynthesisExcludedFinding {
readonly path: string;
readonly reason: SynthesisExclusionReason;
}
/**
* The single best-formed objection to the dossier's implicit
* conclusion (that the matched notes form a coherent, current body of
* knowledge on the topic). This is NOT generated prose — core stays
* deterministic — but the strongest counter-finding selected by a fixed
* priority and framed as a steelman seed for the calling agent to
* develop. `basis` records which finding class grounds it; `null` is
* returned only when no counter-finding exists and the body is large
* enough that thin evidence is not itself an objection.
*/
export interface SynthesisObjection {
readonly basis: "contradiction" | "superseded" | "stale" | "knowledge_gap" | "thin_evidence";
readonly statement: string;
readonly sourceArtifacts: ReadonlyArray<string>;
}
export interface DeepSynthesisReport {
readonly topic: string;
readonly generatedAt: string;
/** Dimensions this dossier actually checked, in order. */
readonly checked: ReadonlyArray<string>;
readonly notes: ReadonlyArray<SynthesisNote>;
readonly agreements: ReadonlyArray<SynthesisAgreement>;
readonly contradictions: ReadonlyArray<SynthesisContradiction>;
readonly staleClaims: ReadonlyArray<SynthesisStaleClaim>;
readonly gaps: ReadonlyArray<SynthesisGap>;
/**
* Entity-contamination findings (t_e9692750): matched notes whose
* wikilink-cited sources never mention a registered entity the note
* asserts. Empty when the vault has no entity registry, and the
* `entity_contamination` dimension is then omitted from `checked`
* so registry-free vaults stay byte-identical.
*/
readonly contaminated: ReadonlyArray<SynthesisContamination>;
/**
* The strongest objection to the dossier's implicit conclusion, or
* `null` when none could be constructed. Always among the `checked`
* dimensions.
*/
readonly strongestObjection: SynthesisObjection | null;
/**
* Per-note findings (t_40fa4e8d): each matched note that cleared the
* evidence-identity gate, carried with its causal context and
* decomposed confidence. Additive - existing consumers ignore it.
*/
readonly findings: ReadonlyArray<SynthesisFinding>;
/**
* Matched notes gated out of {@link findings} because they lacked an
* evidence identity, each with the structural reason. The loss is
* visible, never silent.
*/
readonly excludedFindings: ReadonlyArray<SynthesisExcludedFinding>;
/** Count of {@link excludedFindings} (mirrors the array length). */
readonly excludedFindingCount: number;
}
export interface DeepSynthesisOptions {
readonly now: Date;
/** Max matched notes considered. Default 30. */
readonly limit?: number;
/** A matched note older than this counts as a stale claim. Default 90. */
readonly staleAgeDays?: number;
/**
* Owner-scope isolation (context-integrity-gates, Unit A). Threaded
* straight into `SearchOptions.agentScope`, so an owner-private page
* is returned only to its own scope and an ownerless page always is.
* Omitted / blank applies no ownership filtering, which keeps an
* unscoped call byte-identical.
*/
readonly agentScope?: string;
/**
* How far this caller reached, minted by the transport
* (`src/core/graph/transport-reach.ts`) and threaded straight into
* {@link SearchOptions.transportReach}, so a page reserved against
* remote reads is withheld here on exactly the same terms it is
* withheld from a direct search. Omitted resolves to the narrowest,
* which is what a lane that established nothing should get.
*/
readonly transportReach?: TransportReach;
}
const CHECKED = Object.freeze([
"matched_notes",
"agreements",
"contradictions",
"stale_claims",
"knowledge_gaps",
"strongest_objection",
]);
/** A body of this many matched notes or fewer is itself an objection. */
const THIN_EVIDENCE_MAX = 1;
/** Evidence-identity kind label for a matched vault note. */
const EVIDENCE_KIND_NOTE = "note";
/**
* Per-note working state gathered in the main scan, consumed by the
* finding pass. `content` is null when the note's bytes could not be
* read - the signal the gate turns into a visible exclusion.
*/
interface NoteAccumulator {
readonly note: BrainSearchResult;
/** The note's page + short-name forms, for incidence matching. */
readonly names: ReadonlySet<string>;
readonly ageDays: number;
readonly supersededBy: string | null;
readonly relations: SynthesisRelation[];
coverage: number;
danglingCitations: number;
content: string | null;
}
function stripMd(path: string): string {
return path.endsWith(".md") ? path.slice(0, -".md".length) : path;
}
/** The page and short-name forms a note answers to as a wikilink target. */
function noteNames(path: string): ReadonlySet<string> {
const page = stripMd(path);
const slash = page.lastIndexOf("/");
return new Set(slash >= 0 ? [page, page.slice(slash + 1)] : [page]);
}
/**
* Recency in [0,1]: 1 the day a note is touched, decaying linearly to 0
* at the stale-age horizon and staying 0 beyond it. Rounded to four
* decimals so the value is byte-stable across runs.
*/
function computeFreshness(ageDays: number, horizonDays: number): number {
if (horizonDays <= 0) return 0;
const raw = 1 - ageDays / horizonDays;
const clamped = raw < 0 ? 0 : raw > 1 ? 1 : raw;
return Math.round(clamped * 10000) / 10000;
}
/**
* Select the single strongest counter-finding and frame it as a
* steelman seed. Deterministic: a direct contradiction is the sharpest
* objection, then a superseded claim, then the oldest aged claim, then
* a missing load-bearing note. With no counter-finding, a one-note body
* is itself the objection (too thin to trust); a larger consistent body
* yields `null`, and an empty topic has nothing to object to.
*/
function buildStrongestObjection(params: {
readonly notePaths: ReadonlyArray<string>;
readonly contradictions: ReadonlyArray<SynthesisContradiction>;
readonly staleClaims: ReadonlyArray<SynthesisStaleClaim>;
readonly gaps: ReadonlyArray<SynthesisGap>;
}): SynthesisObjection | null {
const { notePaths, contradictions, staleClaims, gaps } = params;
if (contradictions.length > 0) {
const c = contradictions[0]!;
return Object.freeze({
basis: "contradiction" as const,
statement: `The strongest case against this synthesis: \`${c.path}\` explicitly contradicts \`${c.target}\`. If that counter-note holds, the topic's consensus does not.`,
sourceArtifacts: Object.freeze([c.path, `[[${c.target}]]`]),
});
}
const superseded = staleClaims.find((s) => s.supersededBy !== null);
if (superseded !== undefined) {
return Object.freeze({
basis: "superseded" as const,
statement: `The strongest case against this synthesis: \`${superseded.path}\` has been superseded by \`${superseded.supersededBy}\`, so any conclusion resting on it may already be obsolete.`,
sourceArtifacts: Object.freeze([superseded.path, `[[${superseded.supersededBy}]]`]),
});
}
if (staleClaims.length > 0) {
const oldest = staleClaims.reduce((a, b) => (b.ageDays > a.ageDays ? b : a));
return Object.freeze({
basis: "stale" as const,
statement: `The strongest case against this synthesis: \`${oldest.path}\` is ${oldest.ageDays} days old with no recent corroboration; its claims may no longer hold.`,
sourceArtifacts: Object.freeze([oldest.path]),
});
}
if (gaps.length > 0) {
const g = gaps[0]!;
return Object.freeze({
basis: "knowledge_gap" as const,
statement: `The strongest case against this synthesis: it leans on \`[[${g.target}]]\`, a referenced note that does not exist, leaving a load-bearing claim unverified.`,
sourceArtifacts: Object.freeze([...g.sources]),
});
}
if (notePaths.length >= 1 && notePaths.length <= THIN_EVIDENCE_MAX) {
return Object.freeze({
basis: "thin_evidence" as const,
statement: `The strongest case against this synthesis: it rests on a single matched note — too little evidence to treat the conclusion as settled.`,
sourceArtifacts: Object.freeze([...notePaths]),
});
}
return null;
}
export async function deepSynthesis(
config: ResolvedSearchConfig,
topic: string,
opts: DeepSynthesisOptions,
): Promise<DeepSynthesisReport> {
// A dossier over vault notes: a vault-adapter feature (design D14 item 8).
const vault = requireVaultAdapter(config.vault, "deep synthesis");
const limit = opts.limit ?? 30;
const staleAgeDays = opts.staleAgeDays ?? 90;
// Fetch raw CHUNK hits well past the note limit: one long document
// can produce many chunks, and capping before the per-document
// dedupe would let it crowd every other note out of the dossier.
const rawLimit = Math.min(100, Math.max(limit * 3, limit));
const outcome = await search(config, {
query: topic,
limit: rawLimit,
keywordOnly: true,
...(opts.agentScope !== undefined ? { agentScope: opts.agentScope } : {}),
...(opts.transportReach !== undefined ? { transportReach: opts.transportReach } : {}),
});
// Dedupe chunk hits into per-document notes (best score wins), THEN
// apply the note limit.
const byPath = new Map<string, BrainSearchResult>();
for (const result of outcome.results) {
const seen = byPath.get(result.path);
if (seen === undefined || result.score > seen.score) byPath.set(result.path, result);
}
const matched = [...byPath.values()]
.toSorted((a, b) => (a.score !== b.score ? b.score - a.score : a.path < b.path ? -1 : 1))
.slice(0, limit);
// Known pages across the vault: gap detection needs the full set,
// not just the matched slice. The name->relPath map additionally
// lets the contamination check resolve a cited wikilink target back
// to the source file it names (first deterministic match wins).
const knownTargets = new Set<string>();
const pageByName = new Map<string, string>();
for (const file of walkVault(config)) {
const page = stripMd(file.relPath);
knownTargets.add(page);
if (!pageByName.has(page)) pageByName.set(page, file.relPath);
const slash = page.lastIndexOf("/");
const short = slash >= 0 ? page.slice(slash + 1) : page;
knownTargets.add(short);
if (!pageByName.has(short)) pageByName.set(short, file.relPath);
}
// Entity-contamination substrate (t_e9692750): the dimension only
// exists when the vault HAS a registry, so registry-free vaults
// produce byte-identical reports.
let guardEntities: ReadonlyArray<ContaminationEntityLike> = [];
try {
guardEntities = buildEntityIndex(vault).entities;
} catch {
guardEntities = [];
}
// Agreement edges stay scoped to the matched-topic set: a positive
// relation to an off-topic note is not evidence about THIS topic.
// Contradiction edges deliberately stay unscoped - the counterpart
// of a topical claim often uses different vocabulary and would never
// match the query, and those are exactly the finds a synthesis is
// for.
const matchedTargets = new Set<string>();
for (const note of matched) {
const page = stripMd(note.path);
matchedTargets.add(page);
const slash = page.lastIndexOf("/");
matchedTargets.add(slash >= 0 ? page.slice(slash + 1) : page);
}
const agreements: SynthesisAgreement[] = [];
const contradictions: SynthesisContradiction[] = [];
const staleClaims: SynthesisStaleClaim[] = [];
// Declared here rather than beside the finding pass below because the
// age measurement is the first thing that can gate a note out.
const excludedFindings: SynthesisExcludedFinding[] = [];
const gapSources = new Map<string, Set<string>>();
const contaminated: SynthesisContamination[] = [];
const citedContentCache = new Map<string, string>();
// Per-note accumulation for the finding pass (t_40fa4e8d). Support and
// opposition are cross-note incidence counts, so findings are built in
// a second pass once every relation edge is known.
const perNote: NoteAccumulator[] = [];
for (const note of matched) {
const names = noteNames(note.path);
const relations: SynthesisRelation[] = [];
let supersededBy: string | null = null;
for (const rel of note.relations ?? []) {
if (rel.relation === "contradicts") {
contradictions.push(Object.freeze({ path: note.path, target: rel.target }));
relations.push(Object.freeze({ relation: rel.relation, target: rel.target }));
} else if (rel.relation === "superseded_by") {
supersededBy = rel.target;
relations.push(Object.freeze({ relation: rel.relation, target: rel.target }));
} else if (POSITIVE_RELATIONS.has(rel.relation) && matchedTargets.has(rel.target)) {
agreements.push(
Object.freeze({ path: note.path, relation: rel.relation, target: rel.target }),
);
relations.push(Object.freeze({ relation: rel.relation, target: rel.target }));
}
}
// Stale: superseded notes always; otherwise age by mtime.
//
// A note whose mtime cannot be read is gated out here instead of
// being aged 0. Every downstream consumer of `ageDays` reads it as a
// number of days - `staleClaims`, the objection's `oldest`, and
// `computeFreshness`, which would score an unreadable note at
// maximum freshness - and none of those shapes has a null slot.
// Widening three public shapes for a case that in practice coincides
// with an unreadable body was rejected in favour of reporting the
// note through the exclusion vocabulary this module already owns; a
// path that cannot be stat'ed is `unreadable` in exactly its sense.
// The relation edges collected above are kept, as they were before,
// because they came from the search index rather than from disk.
const ageMs = fileAgeMs(join(vault, note.path), opts.now.getTime());
if (ageMs === null) {
excludedFindings.push(Object.freeze({ path: note.path, reason: "unreadable" }));
continue;
}
const ageDays = msToWholeDays(ageMs);
if (supersededBy !== null || ageDays > staleAgeDays) {
staleClaims.push(Object.freeze({ path: note.path, ageDays, supersededBy }));
}
const acc: NoteAccumulator = {
note,
names,
ageDays,
supersededBy,
relations,
coverage: 0,
danglingCitations: 0,
content: null,
};
perNote.push(acc);
// Gaps: wikilink targets referenced by this note that resolve to
// no vault page. A note whose bytes cannot be read is recorded (its
// `content` stays null) so the finding pass reports the loss rather
// than dropping it silently.
let content: string;
try {
content = readFileSync(join(vault, note.path), "utf8");
} catch {
continue;
}
acc.content = content;
const citedRel = new Set<string>();
for (const body of extractWikilinkRichBodies(content)) {
const target = parseWikilinkRich(body).target;
if (target === "") continue;
if (knownTargets.has(target)) {
const rel = pageByName.get(target);
if (rel !== undefined && rel !== note.path) citedRel.add(rel);
continue;
}
const sources = gapSources.get(target) ?? new Set<string>();
sources.add(note.path);
gapSources.set(target, sources);
acc.danglingCitations += 1;
}
acc.coverage = citedRel.size;
// Contamination: a note asserting a registered entity its cited
// sources never mention. Only notes that actually cite something
// are checked - an uncited note claims no provenance.
if (guardEntities.length > 0 && citedRel.size > 0) {
const cited = [...citedRel].toSorted();
const sourceTexts: string[] = [];
for (const rel of cited) {
const cachedText = citedContentCache.get(rel);
if (cachedText !== undefined) {
sourceTexts.push(cachedText);
continue;
}
try {
const text = readFileSync(join(vault, rel), "utf8");
citedContentCache.set(rel, text);
sourceTexts.push(text);
} catch {
// An unreadable source cannot clear an entity; skip it.
}
}
const result = checkEntityContamination({
conclusion: content,
sources: sourceTexts,
entities: guardEntities,
});
for (const violation of result.violations) {
contaminated.push(
Object.freeze({
path: note.path,
entity: violation.entityId,
sources: Object.freeze(cited),
}),
);
}
}
}
// Finding pass (t_40fa4e8d): build one finding per matched note that
// clears the evidence-identity gate; report the rest as a visible loss.
const findings: SynthesisFinding[] = [];
for (const acc of perNote) {
if (acc.content === null) {
excludedFindings.push(Object.freeze({ path: acc.note.path, reason: "unreadable" }));
continue;
}
const evidence: EvidenceIdentity = {
path: acc.note.path,
kind: EVIDENCE_KIND_NOTE,
contentHash: sha256Hex(acc.content),
};
// Defensive gate: the three fields above are always non-empty here, so this
// branch is currently unreachable. It is kept deliberately so that if the
// evidence construction above ever changes (an empty path, a missing hash),
// the finding is dropped as a visible loss rather than emitted identity-less.
if (!hasEvidenceIdentity(evidence)) {
excludedFindings.push(Object.freeze({ path: acc.note.path, reason: "no_evidence_identity" }));
continue;
}
const support = agreements.filter(
(a) => a.path === acc.note.path || acc.names.has(a.target),
).length;
const opposition = contradictions.filter(
(c) => c.path === acc.note.path || acc.names.has(c.target),
).length;
findings.push(
Object.freeze({
evidence: Object.freeze(evidence),
title: acc.note.title,
causalContext: Object.freeze({
relations: Object.freeze([...acc.relations]),
supersededBy: acc.supersededBy,
danglingCitations: acc.danglingCitations,
}),
confidence: Object.freeze({
support,
opposition,
freshness: computeFreshness(acc.ageDays, staleAgeDays),
coverage: acc.coverage,
}),
}),
);
}
contaminated.sort((a, b) => {
if (a.path !== b.path) return a.path < b.path ? -1 : 1;
return a.entity < b.entity ? -1 : a.entity > b.entity ? 1 : 0;
});
const gaps: ReadonlyArray<SynthesisGap> = Object.freeze(
[...gapSources.entries()]
.toSorted((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
.map(([target, sources]) =>
Object.freeze({ target, sources: Object.freeze([...sources].toSorted()) }),
),
);
const strongestObjection = buildStrongestObjection({
notePaths: matched.map((note) => note.path),
contradictions,
staleClaims,
gaps,
});
return Object.freeze({
topic,
generatedAt: opts.now.toISOString(),
checked:
guardEntities.length > 0 ? Object.freeze([...CHECKED, "entity_contamination"]) : CHECKED,
notes: Object.freeze(
matched.map((note) =>
Object.freeze({ path: note.path, title: note.title, score: note.score }),
),
),
agreements: Object.freeze(agreements),
contradictions: Object.freeze(contradictions),
staleClaims: Object.freeze(staleClaims),
gaps,
contaminated: Object.freeze(contaminated),
strongestObjection,
findings: Object.freeze(findings),
excludedFindings: Object.freeze(excludedFindings),
excludedFindingCount: excludedFindings.length,
});
}
/**
* The additive t_40fa4e8d surface of a report, in the snake_case shape
* both the CLI `--json` payload and the MCP structured content emit.
* Shared so the two operator surfaces stay byte-identical: each finding
* carries its evidence identity, causal context, and decomposed
* confidence, and the evidence loss is a visible ledger, never silent.
*/
export function synthesisFindingsJson(report: DeepSynthesisReport): {
findings: ReadonlyArray<{
evidence: { path: string; kind: string; content_hash: string };
title: string | null;
causal_context: {
relations: ReadonlyArray<SynthesisRelation>;
superseded_by: string | null;
dangling_citations: number;
};
confidence: SynthesisConfidence;
}>;
excluded_findings: ReadonlyArray<SynthesisExcludedFinding>;
excluded_finding_count: number;
} {
return {
findings: report.findings.map((f) => ({
evidence: {
path: f.evidence.path,
kind: f.evidence.kind,
content_hash: f.evidence.contentHash,
},
title: f.title,
causal_context: {
relations: f.causalContext.relations,
superseded_by: f.causalContext.supersededBy,
dangling_citations: f.causalContext.danglingCitations,
},
confidence: f.confidence,
})),
excluded_findings: report.excludedFindings,
excluded_finding_count: report.excludedFindingCount,
};
}
/** Contradiction and gap findings as trigger candidates (Kernel B). */
export function synthesisCandidates(report: DeepSynthesisReport): ReadonlyArray<InsightCandidate> {
const out: InsightCandidate[] = [];
for (const finding of report.contradictions) {
out.push(
Object.freeze({
kind: "contradiction" as const,
urgency: "high" as const,
reason: `${finding.path} declares contradicts -> ${finding.target} (topic: ${report.topic})`,
suggestedAction: "Reconcile the two notes or retire the stale claim",
sourceArtifacts: Object.freeze([finding.path, `[[${finding.target}]]`]),
contextSnippets: Object.freeze([`topic: ${report.topic}`]),
cooldownKey: `contradiction:${finding.path}:${finding.target}`,
}),
);
}
for (const gap of report.gaps) {
out.push(
Object.freeze({
kind: "knowledge_gap" as const,
urgency: "medium" as const,
reason: `[[${gap.target}]] is referenced but has no note (topic: ${report.topic})`,
suggestedAction: "Write the missing note or fix the dangling link",
sourceArtifacts: Object.freeze([...gap.sources]),
contextSnippets: Object.freeze([`topic: ${report.topic}`]),
cooldownKey: `knowledge_gap:${gap.target}`,
}),
);
}
return Object.freeze(out);
}