@tangle-network/agent-runtime 0.105.0 → 0.106.1

package/dist/{kb-gate-CwHO0vz6.d.ts → kb-gate-C8z2juK8.d.ts}

@@ -1,3 +1,4 @@
+//#region src/mcp/kb-gate.d.ts
 /**
  *
  * `createKbGate` — the valid-only knowledge-base growth gate, distilled from
@@ -22,48 +23,48 @@
  */
 /** @experimental A fact proposed for the KB, with its grounding. */
 interface FactCandidate {
-    /** The atomic claim text. */
-    claim: string;
-    /** Optional extracted value (number or string) the claim asserts. */
-    value?: string | number;
-    /** Verbatim span lifted from the source that backs the claim. */
-    verbatimPassage: string;
-    /** The raw source text the passage must be grounded in. */
-    sourceText: string;
-    /** Where the fact claims to come from — checked for circular/self citations. */
-    citation?: string;
+  /** The atomic claim text. */
+  claim: string;
+  /** Optional extracted value (number or string) the claim asserts. */
+  value?: string | number;
+  /** Verbatim span lifted from the source that backs the claim. */
+  verbatimPassage: string;
+  /** The raw source text the passage must be grounded in. */
+  sourceText: string;
+  /** Where the fact claims to come from — checked for circular/self citations. */
+  citation?: string;
 }
 /** @experimental */
 interface FactJudgeVerdict {
-    accept: boolean;
-    reason?: string;
+  accept: boolean;
+  reason?: string;
 }
 /** @experimental A pluggable fact validator. Throw is NOT allowed — return a
  *  verdict; a thrown judge is a programmer error, not a veto. */
 interface FactJudge {
-    name: string;
-    judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>;
+  name: string;
+  judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>;
 }
 /** @experimental */
 interface KbGateResult {
-    accepted: boolean;
-    /** Name of the judge that vetoed; undefined when accepted. */
-    vetoedBy?: string;
-    reason?: string;
+  accepted: boolean;
+  /** Name of the judge that vetoed; undefined when accepted. */
+  vetoedBy?: string;
+  reason?: string;
 }
 /** @experimental */
 interface CreateKbGateOptions {
-    /** Extra judges appended after the built-in floor (e.g. an LLM judge). */
-    judges?: FactJudge[];
-    /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */
-    minPassageChars?: number;
-    /**
-     * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,
-     * `'cad_params'`, `'requirements'`). A citation naming one is circular
-     * (laundering) — the fact cites a derived artifact, not a real source.
-     * Default `[]` (no circular check unless the consumer declares its kinds).
-     */
-    selfArtifactKinds?: string[];
+  /** Extra judges appended after the built-in floor (e.g. an LLM judge). */
+  judges?: FactJudge[];
+  /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */
+  minPassageChars?: number;
+  /**
+   * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,
+   * `'cad_params'`, `'requirements'`). A citation naming one is circular
+   * (laundering) — the fact cites a derived artifact, not a real source.
+   * Default `[]` (no circular check unless the consumer declares its kinds).
+   */
+  selfArtifactKinds?: string[];
 }
 /**
  *
@@ -74,5 +75,6 @@ interface CreateKbGateOptions {
  * @experimental
  */
 declare function createKbGate(options?: CreateKbGateOptions): (candidate: FactCandidate) => Promise<KbGateResult>;
-
-export { type CreateKbGateOptions as C, type FactCandidate as F, type KbGateResult as K, type FactJudge as a, type FactJudgeVerdict as b, createKbGate as c };
+//#endregion
+export { KbGateResult as a, FactJudgeVerdict as i, FactCandidate as n, createKbGate as o, FactJudge as r, CreateKbGateOptions as t };
+//# sourceMappingURL=kb-gate-C8z2juK8.d.ts.map

package/dist/kb-gate-DpaSwXVx.js

@@ -0,0 +1,80 @@
+//#region src/mcp/kb-gate.ts
+const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+/** Does `value` appear in the (normalized) passage — literally, comma-grouped,
+*  or in billion/million shorthand (the forms a source actually writes). */
+function valueAppears(value, passageNorm) {
+	if (passageNorm.includes(norm(String(value)))) return true;
+	if (typeof value !== "number" || !Number.isFinite(value)) return false;
+	const forms = [value.toLocaleString("en-US")];
+	if (Math.abs(value) >= 1e9) forms.push(`${trimZero(value / 1e9)} billion`);
+	if (Math.abs(value) >= 1e6) forms.push(`${trimZero(value / 1e6)} million`);
+	return forms.some((f) => passageNorm.includes(norm(f)));
+}
+function trimZero(n) {
+	return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(2)));
+}
+/** The always-on floor judges. Order matters: cheapest / most-fundamental first. */
+function builtinJudges(minPassageChars, selfArtifactKinds) {
+	const kinds = selfArtifactKinds.map((k) => k.toLowerCase());
+	return [
+		{
+			name: "passage-non-empty",
+			judge: (c) => c.verbatimPassage.trim().length >= minPassageChars ? { accept: true } : {
+				accept: false,
+				reason: `passage shorter than ${minPassageChars} chars`
+			}
+		},
+		{
+			name: "passage-present",
+			judge: (c) => norm(c.sourceText).includes(norm(c.verbatimPassage)) ? { accept: true } : {
+				accept: false,
+				reason: "verbatim passage not found in source (unbacked fact)"
+			}
+		},
+		{
+			name: "value-in-passage",
+			judge: (c) => c.value === void 0 || valueAppears(c.value, norm(c.verbatimPassage)) ? { accept: true } : {
+				accept: false,
+				reason: `value ${JSON.stringify(c.value)} not present in passage`
+			}
+		},
+		{
+			name: "no-circular-citation",
+			judge: (c) => {
+				if (!c.citation || kinds.length === 0) return { accept: true };
+				const cite = c.citation.toLowerCase();
+				const hit = kinds.find((k) => cite.includes(k));
+				return hit ? {
+					accept: false,
+					reason: `circular citation to self-generated artifact "${hit}"`
+				} : { accept: true };
+			}
+		}
+	];
+}
+/**
+*
+* Build a fail-closed KB gate. The returned function runs the built-in floor
+* (passage-non-empty → passage-present → value-in-passage → no-circular-citation)
+* then any consumer judges, returning on the first veto.
+*
+* @experimental
+*/
+function createKbGate(options = {}) {
+	const judges = [...builtinJudges(options.minPassageChars ?? 12, options.selfArtifactKinds ?? []), ...options.judges ?? []];
+	return async (candidate) => {
+		for (const j of judges) {
+			const verdict = await j.judge(candidate);
+			if (!verdict.accept) return {
+				accepted: false,
+				vetoedBy: j.name,
+				reason: verdict.reason
+			};
+		}
+		return { accepted: true };
+	};
+}
+//#endregion
+export { createKbGate as t };
+
+//# sourceMappingURL=kb-gate-DpaSwXVx.js.map

package/dist/kb-gate-DpaSwXVx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-gate-DpaSwXVx.js","names":[],"sources":["../src/mcp/kb-gate.ts"],"sourcesContent":["/**\n *\n * `createKbGate` — the valid-only knowledge-base growth gate, distilled from\n * physim's KB-research subsystem. A research-in-a-loop delegate (or any KB\n * writer) runs candidate facts through this before persisting, so the KB grows\n * with ONLY grounded facts — hallucinated, unsourced, or laundered claims are\n * vetoed at the gate.\n *\n * Fail-closed by construction: every judge must `accept`; the FIRST veto wins\n * and the fact is rejected. The non-negotiable floor (always on, can't be\n * disabled) is the **passage-present guard** — a fact's `verbatimPassage` MUST\n * literally appear in its `sourceText`. That single check kills the dominant\n * failure mode (a confident claim decoupled from any real source).\n *\n * Pure + dependency-free: it operates on fact candidates, not on a store, so it\n * composes with `@tangle-network/agent-knowledge` or any persistence layer\n * without importing it. The remediation policy (correct-on-veto vs\n * escalate-as-unverified) is the caller's — this returns the verdict; it never\n * drops a fact silently.\n *\n * @experimental\n */\n\n/** @experimental A fact proposed for the KB, with its grounding. */\nexport interface FactCandidate {\n  /** The atomic claim text. */\n  claim: string\n  /** Optional extracted value (number or string) the claim asserts. */\n  value?: string | number\n  /** Verbatim span lifted from the source that backs the claim. */\n  verbatimPassage: string\n  /** The raw source text the passage must be grounded in. */\n  sourceText: string\n  /** Where the fact claims to come from — checked for circular/self citations. */\n  citation?: string\n}\n\n/** @experimental */\nexport interface FactJudgeVerdict {\n  accept: boolean\n  reason?: string\n}\n\n/** @experimental A pluggable fact validator. Throw is NOT allowed — return a\n *  verdict; a thrown judge is a programmer error, not a veto. */\nexport interface FactJudge {\n  name: string\n  judge(candidate: FactCandidate): FactJudgeVerdict | Promise<FactJudgeVerdict>\n}\n\n/** @experimental */\nexport interface KbGateResult {\n  accepted: boolean\n  /** Name of the judge that vetoed; undefined when accepted. */\n  vetoedBy?: string\n  reason?: string\n}\n\n/** @experimental */\nexport interface CreateKbGateOptions {\n  /** Extra judges appended after the built-in floor (e.g. an LLM judge). */\n  judges?: FactJudge[]\n  /** Minimum verbatim-passage length. Default 12 — kills empty/stub passages. */\n  minPassageChars?: number\n  /**\n   * Citation tokens that denote a SELF-generated artifact (e.g. `'spec'`,\n   * `'cad_params'`, `'requirements'`). A citation naming one is circular\n   * (laundering) — the fact cites a derived artifact, not a real source.\n   * Default `[]` (no circular check unless the consumer declares its kinds).\n   */\n  selfArtifactKinds?: string[]\n}\n\nconst norm = (s: string): string => s.toLowerCase().replace(/\\s+/g, ' ').trim()\n\n/** Does `value` appear in the (normalized) passage — literally, comma-grouped,\n *  or in billion/million shorthand (the forms a source actually writes). */\nfunction valueAppears(value: string | number, passageNorm: string): boolean {\n  if (passageNorm.includes(norm(String(value)))) return true\n  if (typeof value !== 'number' || !Number.isFinite(value)) return false\n  const forms = [value.toLocaleString('en-US')]\n  if (Math.abs(value) >= 1e9) forms.push(`${trimZero(value / 1e9)} billion`)\n  if (Math.abs(value) >= 1e6) forms.push(`${trimZero(value / 1e6)} million`)\n  return forms.some((f) => passageNorm.includes(norm(f)))\n}\n\nfunction trimZero(n: number): string {\n  return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(2)))\n}\n\n/** The always-on floor judges. Order matters: cheapest / most-fundamental first. */\nfunction builtinJudges(minPassageChars: number, selfArtifactKinds: string[]): FactJudge[] {\n  const kinds = selfArtifactKinds.map((k) => k.toLowerCase())\n  return [\n    {\n      name: 'passage-non-empty',\n      judge: (c) =>\n        c.verbatimPassage.trim().length >= minPassageChars\n          ? { accept: true }\n          : { accept: false, reason: `passage shorter than ${minPassageChars} chars` },\n    },\n    {\n      // THE anti-hallucination floor — the passage must literally be in the source.\n      name: 'passage-present',\n      judge: (c) =>\n        norm(c.sourceText).includes(norm(c.verbatimPassage))\n          ? { accept: true }\n          : { accept: false, reason: 'verbatim passage not found in source (unbacked fact)' },\n    },\n    {\n      name: 'value-in-passage',\n      judge: (c) =>\n        c.value === undefined || valueAppears(c.value, norm(c.verbatimPassage))\n          ? { accept: true }\n          : { accept: false, reason: `value ${JSON.stringify(c.value)} not present in passage` },\n    },\n    {\n      name: 'no-circular-citation',\n      judge: (c) => {\n        if (!c.citation || kinds.length === 0) return { accept: true }\n        const cite = c.citation.toLowerCase()\n        const hit = kinds.find((k) => cite.includes(k))\n        return hit\n          ? { accept: false, reason: `circular citation to self-generated artifact \"${hit}\"` }\n          : { accept: true }\n      },\n    },\n  ]\n}\n\n/**\n *\n * Build a fail-closed KB gate. The returned function runs the built-in floor\n * (passage-non-empty → passage-present → value-in-passage → no-circular-citation)\n * then any consumer judges, returning on the first veto.\n *\n * @experimental\n */\nexport function createKbGate(\n  options: CreateKbGateOptions = {},\n): (candidate: FactCandidate) => Promise<KbGateResult> {\n  const judges = [\n    ...builtinJudges(options.minPassageChars ?? 12, options.selfArtifactKinds ?? []),\n    ...(options.judges ?? []),\n  ]\n  return async (candidate) => {\n    for (const j of judges) {\n      const verdict = await j.judge(candidate)\n      if (!verdict.accept) {\n        return { accepted: false, vetoedBy: j.name, reason: verdict.reason }\n      }\n    }\n    return { accepted: true }\n  }\n}\n"],"mappings":";AAyEA,MAAM,QAAQ,MAAsB,EAAE,YAAY,CAAC,CAAC,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;;;AAI9E,SAAS,aAAa,OAAwB,aAA8B;CAC1E,IAAI,YAAY,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,GAAG,OAAO;CACtD,IAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO;CACjE,MAAM,QAAQ,CAAC,MAAM,eAAe,OAAO,CAAC;CAC5C,IAAI,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,KAAK,GAAG,SAAS,QAAQ,GAAG,EAAE,SAAS;CACzE,IAAI,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,KAAK,GAAG,SAAS,QAAQ,GAAG,EAAE,SAAS;CACzE,OAAO,MAAM,MAAM,MAAM,YAAY,SAAS,KAAK,CAAC,CAAC,CAAC;AACxD;AAEA,SAAS,SAAS,GAAmB;CACnC,OAAO,OAAO,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,OAAO,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AACtE;;AAGA,SAAS,cAAc,iBAAyB,mBAA0C;CACxF,MAAM,QAAQ,kBAAkB,KAAK,MAAM,EAAE,YAAY,CAAC;CAC1D,OAAO;EACL;GACE,MAAM;GACN,QAAQ,MACN,EAAE,gBAAgB,KAAK,CAAC,CAAC,UAAU,kBAC/B,EAAE,QAAQ,KAAK,IACf;IAAE,QAAQ;IAAO,QAAQ,wBAAwB,gBAAgB;GAAQ;EACjF;EACA;GAEE,MAAM;GACN,QAAQ,MACN,KAAK,EAAE,UAAU,CAAC,CAAC,SAAS,KAAK,EAAE,eAAe,CAAC,IAC/C,EAAE,QAAQ,KAAK,IACf;IAAE,QAAQ;IAAO,QAAQ;GAAuD;EACxF;EACA;GACE,MAAM;GACN,QAAQ,MACN,EAAE,UAAU,KAAA,KAAa,aAAa,EAAE,OAAO,KAAK,EAAE,eAAe,CAAC,IAClE,EAAE,QAAQ,KAAK,IACf;IAAE,QAAQ;IAAO,QAAQ,SAAS,KAAK,UAAU,EAAE,KAAK,EAAE;GAAyB;EAC3F;EACA;GACE,MAAM;GACN,QAAQ,MAAM;IACZ,IAAI,CAAC,EAAE,YAAY,MAAM,WAAW,GAAG,OAAO,EAAE,QAAQ,KAAK;IAC7D,MAAM,OAAO,EAAE,SAAS,YAAY;IACpC,MAAM,MAAM,MAAM,MAAM,MAAM,KAAK,SAAS,CAAC,CAAC;IAC9C,OAAO,MACH;KAAE,QAAQ;KAAO,QAAQ,iDAAiD,IAAI;IAAG,IACjF,EAAE,QAAQ,KAAK;GACrB;EACF;CACF;AACF;;;;;;;;;AAUA,SAAgB,aACd,UAA+B,CAAC,GACqB;CACrD,MAAM,SAAS,CACb,GAAG,cAAc,QAAQ,mBAAmB,IAAI,QAAQ,qBAAqB,CAAC,CAAC,GAC/E,GAAI,QAAQ,UAAU,CAAC,CACzB;CACA,OAAO,OAAO,cAAc;EAC1B,KAAK,MAAM,KAAK,QAAQ;GACtB,MAAM,UAAU,MAAM,EAAE,MAAM,SAAS;GACvC,IAAI,CAAC,QAAQ,QACX,OAAO;IAAE,UAAU;IAAO,UAAU,EAAE;IAAM,QAAQ,QAAQ;GAAO;EAEvE;EACA,OAAO,EAAE,UAAU,KAAK;CAC1B;AACF"}

package/dist/knowledge-Ku-mPP4f.js

@@ -0,0 +1,433 @@
+import { a as persistCandidateOutputArtifact, ct as omitTopLevelDigest, nt as canonicalCandidateBytes, ot as embeddedCandidateArtifact } from "./prepare-B53sPV7M.js";
+import { i as sealAgentCandidateBundle, t as captureAgentCandidateWorkspace } from "./workspace-archive-BosQiotA.js";
+import { t as createAgentImprovementActivationResult } from "./activation-CRjVfOiy.js";
+import { r as researcherProfile } from "./researcher-CoVqNhfI.js";
+import { t as supervise } from "./supervise-BiRutHS9.js";
+import { agentCandidateKnowledgeSchema, sha256DigestSchema } from "@tangle-network/agent-interface";
+import { realpath } from "node:fs/promises";
+import { evaluateKnowledgeBaseReadiness, fromAgentCandidateKnowledgeRef, improveKnowledgeBase, knowledgeImprovementCandidateRef, loadKnowledgeImprovementActivationResult, promoteKnowledgeCandidate, restoreKnowledgeCandidateBaseline, toAgentCandidateKnowledgeRef, withKnowledgeImprovementComparison } from "@tangle-network/agent-knowledge";
+//#region src/knowledge/activation.ts
+/** Apply or restore one local knowledge candidate through the shared activation contract. */
+function createKnowledgeImprovementActivationExecutor(options) {
+	if (!options.identity.trim()) throw new Error("knowledge activation identity is required");
+	return {
+		reconcile: async (transition) => {
+			const inspected = await inspectKnowledgeActivation(options, transition);
+			return inspected.settled ? inspected.result : void 0;
+		},
+		transition: async (transition) => {
+			if (transition.expired) throw new Error("knowledge write transition cannot run after authorization expires");
+			const inspected = await inspectKnowledgeActivation(options, transition);
+			if (inspected.settled) return inspected.result;
+			const mutationOptions = {
+				root: options.root,
+				candidate: inspected.candidate,
+				activation: {
+					activation: transition.activation,
+					attemptedAt: transition.attemptedAt,
+					identity: options.identity,
+					createResult: (receipt) => inspected.create(knowledgeMutationOutcome(receipt, inspected, transition.activation.intent))
+				},
+				...options.ownerId ? { ownerId: options.ownerId } : {},
+				...options.leaseTtlMs === void 0 ? {} : { leaseTtlMs: options.leaseTtlMs },
+				...options.now ? { now: options.now } : {},
+				...options.onState ? { onState: options.onState } : {}
+			};
+			const improvement = transition.activation.intent === "activate-candidate" ? await promoteKnowledgeCandidate(mutationOptions) : await restoreKnowledgeCandidateBaseline(mutationOptions);
+			if (!improvement.activationResult) throw new Error("knowledge mutation did not persist its shared activation result");
+			return options.results.putIfAbsent(improvement.activationResult);
+		}
+	};
+}
+async function inspectKnowledgeActivation(options, transition) {
+	const stored = await options.results.load(transition.activation.digest);
+	if (stored !== void 0) return {
+		settled: true,
+		result: stored
+	};
+	const create = (outcome) => createAgentImprovementActivationResult(transition, {
+		completedAt: completionTime(transition, options.now),
+		outcome
+	});
+	const store = (outcome) => options.results.putIfAbsent(create(outcome));
+	if (transition.kind !== "sealed-candidate") {
+		if (transition.expired) return {
+			settled: true,
+			result: void 0
+		};
+		return {
+			settled: true,
+			result: await store({
+				status: "unsupported",
+				code: "KNOWLEDGE_PROFILE_TRANSITION_UNSUPPORTED",
+				message: "The knowledge adapter accepts only sealed knowledge candidates."
+			})
+		};
+	}
+	const target = supportedKnowledgeTarget(transition, options.identity);
+	if (!target) {
+		if (transition.expired) return {
+			settled: true,
+			result: void 0
+		};
+		return {
+			settled: true,
+			result: await store({
+				status: "unsupported",
+				code: "KNOWLEDGE_TARGET_SET_UNSUPPORTED",
+				message: "The knowledge adapter requires exactly one matching knowledge target."
+			})
+		};
+	}
+	const knowledge = transition.candidateBundle.knowledge;
+	if (!knowledge) {
+		if (transition.expired) return {
+			settled: true,
+			result: void 0
+		};
+		return {
+			settled: true,
+			result: await store({
+				status: "unsupported",
+				code: "KNOWLEDGE_CANDIDATE_MISSING",
+				message: "The measured candidate bundle does not contain a knowledge candidate."
+			})
+		};
+	}
+	const candidate = fromAgentCandidateKnowledgeRef(knowledge.candidate);
+	const expectedDigest = transition.activation.intent === "activate-candidate" ? knowledge.candidate.baseHash : knowledge.candidate.candidateHash;
+	const desiredDigest = transition.activation.intent === "activate-candidate" ? knowledge.candidate.candidateHash : knowledge.candidate.baseHash;
+	if (target.expectedBaseDigest !== expectedDigest || target.desiredDigest !== desiredDigest) {
+		if (transition.expired) return {
+			settled: true,
+			result: void 0
+		};
+		return {
+			settled: true,
+			result: await store({
+				status: "failed",
+				code: "KNOWLEDGE_TARGET_MISMATCH",
+				message: "The activation target does not match the measured knowledge candidate."
+			})
+		};
+	}
+	const durable = await loadKnowledgeImprovementActivationResult({
+		root: options.root,
+		candidate,
+		activation: transition.activation,
+		identity: options.identity
+	});
+	if (durable) return {
+		settled: true,
+		result: await options.results.putIfAbsent(durable)
+	};
+	if (transition.expired) return {
+		settled: true,
+		result: void 0
+	};
+	return {
+		settled: false,
+		target,
+		candidate,
+		expectedDigest,
+		desiredDigest,
+		create
+	};
+}
+function supportedKnowledgeTarget(transition, identity) {
+	if (transition.targets.length !== 1) return void 0;
+	const target = transition.targets[0];
+	return target.surface === "knowledge" && target.identity === identity ? target : void 0;
+}
+function knowledgeMutationOutcome(receipt, inspected, intent) {
+	const expectedTarget = intent === "activate-candidate" ? "candidate" : "baseline";
+	const beforeDigest = prefixedDigest(receipt.beforeHash);
+	const afterDigest = prefixedDigest(receipt.afterHash);
+	if (receipt.target !== expectedTarget || receipt.changed !== (beforeDigest !== afterDigest) || !receipt.changed && (receipt.transactionId !== null || receipt.recovered)) throw new Error("knowledge mutation returned inconsistent state evidence");
+	if (receipt.changed) {
+		if (receipt.transactionId === null || beforeDigest !== inspected.expectedDigest || afterDigest !== inspected.desiredDigest) throw new Error("knowledge activation did not apply its authorized content transition");
+		return {
+			status: "applied",
+			transactionId: receipt.transactionId,
+			targets: [{
+				surface: inspected.target.surface,
+				identity: inspected.target.identity,
+				beforeDigest,
+				afterDigest
+			}]
+		};
+	}
+	if (afterDigest === inspected.desiredDigest) return {
+		status: "already-applied",
+		targets: [targetState(inspected.target, afterDigest)]
+	};
+	if (afterDigest === inspected.expectedDigest) throw new Error("knowledge activation did not attempt its authorized content transition");
+	return {
+		status: "conflict",
+		targets: [targetState(inspected.target, afterDigest)]
+	};
+}
+function targetState(target, currentDigest) {
+	return {
+		surface: target.surface,
+		identity: target.identity,
+		currentDigest
+	};
+}
+function prefixedDigest(hash) {
+	return sha256DigestSchema.parse(`sha256:${hash}`);
+}
+function completionTime(transition, now) {
+	const completedAt = (now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+	return Date.parse(completedAt) < Date.parse(transition.attemptedAt) ? transition.attemptedAt : completedAt;
+}
+//#endregion
+//#region src/knowledge/supervised-update.ts
+/** Standing prompt for a supervisor that grows a shared knowledge base through spawned researchers. */
+const RESEARCH_SUPERVISOR_SYSTEM_PROMPT = [
+	"You are a research supervisor. You do not answer the research question yourself.",
+	"You create and manage researcher workers that improve one shared knowledge base until it is ready.",
+	"",
+	"Each round:",
+	"1. Read the goal and the gaps the readiness check still reports.",
+	"2. Decompose the open work into independent sub-topics.",
+	"3. Spawn one researcher per sub-topic; split by sub-topic, never duplicate work.",
+	"4. Wait for researchers to settle, steer or re-spawn thin sub-topics, then stop when the check passes.",
+	"",
+	"Conserve the shared budget. Prefer a small number of well-scoped researchers over a large fanout that re-covers the same ground."
+].join("\n");
+/** Build the completion check a supervised KB update uses to stop only when the KB is ready. */
+function knowledgeReadinessDeliverable(options) {
+	return {
+		describe: `knowledge base at ${options.root} is ready for: ${options.goal}`,
+		async check() {
+			const result = await options.readiness({
+				root: options.root,
+				goal: options.goal,
+				readinessSpecs: options.readinessSpecs,
+				readinessTaskId: options.readinessTaskId,
+				readiness: options.readinessOptions
+			});
+			return typeof result === "boolean" ? result : result.ready;
+		}
+	};
+}
+/** Create an `improveKnowledgeBase` update callback backed by runtime supervision. */
+function createSupervisedKnowledgeUpdater(options) {
+	return (input) => runSupervisedKnowledgeUpdate({
+		...options,
+		root: input.candidateRoot ?? input.root ?? options.root,
+		goal: input.goal ?? options.goal,
+		findings: input.findings ?? options.findings,
+		metadata: {
+			...options.metadata,
+			...input.metadata
+		}
+	});
+}
+/** Run a runtime supervisor that updates one candidate knowledge base and stops on readiness. */
+async function runSupervisedKnowledgeUpdate(options) {
+	const { profile: workerProfile } = researcherProfile({ harness: options.harness });
+	const baseInstructions = options.supervisorSystemPrompt ?? RESEARCH_SUPERVISOR_SYSTEM_PROMPT;
+	const workerContract = workerProfile.prompt?.systemPrompt;
+	const systemPrompt = workerContract ? `${baseInstructions}\n\nEach researcher worker you spawn follows this contract:\n${workerContract}` : baseInstructions;
+	const profile = {
+		name: "knowledge-research-supervisor",
+		model: options.supervisorModel,
+		systemPrompt
+	};
+	const supervised = await (options.runSupervised ?? supervise)(profile, formatSupervisedKnowledgeTask(options), {
+		...options.superviseOptions,
+		budget: options.budget,
+		backend: options.backend,
+		deliverable: knowledgeReadinessDeliverable(options),
+		makeWorkerAgent: options.makeWorkerAgent,
+		allowedModels: options.allowedModels
+	});
+	return {
+		applied: supervised.kind === "winner",
+		summary: supervised.kind === "winner" ? "research supervisor completed and the knowledge base passed readiness" : `research supervisor stopped without a ready knowledge base: ${supervised.reason}`,
+		supervised,
+		metadata: {
+			supervised: true,
+			root: options.root,
+			goal: options.goal,
+			result: supervised.kind
+		}
+	};
+}
+/** Format the supervisor task with the KB root, readiness requirements, current findings, and metadata. */
+function formatSupervisedKnowledgeTask(options) {
+	return `${[
+		`Goal: ${options.goal}`,
+		`Knowledge base root: ${options.root}`,
+		options.readinessTaskId ? `Readiness task id: ${options.readinessTaskId}` : void 0,
+		options.readinessSpecs?.length ? `Readiness specs:\n${JSON.stringify(options.readinessSpecs, null, 2)}` : void 0,
+		options.findings?.length ? `Current findings:\n${JSON.stringify(options.findings, null, 2)}` : void 0,
+		options.metadata && Object.keys(options.metadata).length > 0 ? `Metadata:\n${JSON.stringify(options.metadata, null, 2)}` : void 0
+	].filter((section) => Boolean(section)).join("\n\n")}\n\nUpdate files under the knowledge base root only. Stop when the readiness check passes.`;
+}
+//#endregion
+//#region src/knowledge/improvement-job.ts
+/** Build the default readiness check backed by `@tangle-network/agent-knowledge` validation and scoring. */
+function createAgentKnowledgeReadinessCheck(options) {
+	return async (input) => {
+		const readiness = await evaluateKnowledgeBaseReadiness({
+			root: input.root,
+			goal: input.goal ?? options.goal,
+			readinessSpecs: input.readinessSpecs ?? options.readinessSpecs,
+			readinessTaskId: input.readinessTaskId ?? options.readinessTaskId,
+			readiness: input.readiness ?? options.readiness,
+			strict: options.strict,
+			kbQuality: options.kbQuality
+		});
+		return {
+			ready: readiness.ready,
+			summary: readiness.summary,
+			metadata: {
+				dimensions: readiness.dimensions,
+				validationOk: readiness.validation.ok,
+				kbQualityOk: readiness.kbQuality.ok,
+				blockingMissing: readiness.readiness?.report.blockingMissingRequirements.length ?? 0
+			}
+		};
+	};
+}
+/** Produce a frozen KB candidate while leaving live knowledge content unchanged. */
+async function runKnowledgeImprovementJob(options) {
+	const { allowedModels, backend, budget, candidateArtifacts, harness, makeWorkerAgent, onMeasurement, readinessCheck, runSupervised, supervisorModel, supervisorSystemPrompt, superviseOptions, ...knowledgeOptions } = options;
+	const startedAtMs = Date.now();
+	const startedAt = new Date(startedAtMs).toISOString();
+	const supervisedSpent = emptySpent();
+	let updateCalls = 0;
+	let updateDurationMs = 0;
+	const readiness = readinessCheck ?? createAgentKnowledgeReadinessCheck(options);
+	const updateKnowledge = createSupervisedKnowledgeUpdater({
+		root: options.root,
+		goal: options.goal,
+		readiness,
+		readinessSpecs: options.readinessSpecs,
+		readinessTaskId: options.readinessTaskId,
+		readinessOptions: options.readiness,
+		budget,
+		backend,
+		makeWorkerAgent,
+		harness,
+		supervisorModel,
+		supervisorSystemPrompt,
+		superviseOptions,
+		allowedModels,
+		runSupervised
+	});
+	const instrumentedUpdateKnowledge = async (input) => {
+		const updateStartedAt = Date.now();
+		updateCalls += 1;
+		const result = await updateKnowledge(input);
+		updateDurationMs += Date.now() - updateStartedAt;
+		addSpent(supervisedSpent, result.supervised);
+		return result;
+	};
+	const resolvedImprovement = await improveKnowledgeBase({
+		...knowledgeOptions,
+		updateKnowledge: instrumentedUpdateKnowledge
+	});
+	let knowledge;
+	if (resolvedImprovement.candidate?.status === "candidate-ready" || resolvedImprovement.candidate?.status === "promoted") knowledge = await freezeKnowledgeCandidatePair(options.root, resolvedImprovement, candidateArtifacts, knowledgeOptions.signal);
+	const finishedAtMs = Date.now();
+	const measurement = {
+		startedAt,
+		finishedAt: new Date(finishedAtMs).toISOString(),
+		durationMs: finishedAtMs - startedAtMs,
+		updateCalls,
+		updateDurationMs,
+		supervisedSpent
+	};
+	await onMeasurement?.(measurement);
+	return {
+		improvement: resolvedImprovement,
+		...knowledge ? { knowledge } : {},
+		measurement,
+		blocked: resolvedImprovement.blocked
+	};
+}
+/** Attach both frozen knowledge inputs to one otherwise-identical bundle pair. */
+function buildKnowledgeImprovementExperimentBundles(bundle, knowledge) {
+	const input = omitTopLevelDigest(bundle);
+	const withSnapshot = (snapshot) => agentCandidateKnowledgeSchema.parse({
+		candidate: knowledge.reference,
+		snapshot,
+		evaluation: knowledge.evaluation
+	});
+	return Object.freeze({
+		baseline: sealAgentCandidateBundle({
+			...input,
+			knowledge: withSnapshot(knowledge.baseline)
+		}),
+		candidate: sealAgentCandidateBundle({
+			...input,
+			knowledge: withSnapshot(knowledge.candidate)
+		})
+	});
+}
+async function freezeKnowledgeCandidatePair(root, improvement, artifacts, signal) {
+	const candidate = knowledgeImprovementCandidateRef(improvement);
+	const candidateRef = toAgentCandidateKnowledgeRef(candidate);
+	return withKnowledgeImprovementComparison({
+		root,
+		candidate
+	}, async (comparison) => {
+		const freeze = async (target) => {
+			const executionId = `knowledge-${candidate.candidateId}-${target}`;
+			return (await captureAgentCandidateWorkspace(await realpath(comparison[target].root), { ...artifacts ? { artifactPersistence: {
+				executionId,
+				outputArtifacts: artifacts,
+				...signal ? { signal } : {}
+			} } : {} })).snapshot;
+		};
+		const evaluation = await captureKnowledgeEvidence(canonicalCandidateBytes({
+			kind: "agent-knowledge-candidate-evaluation",
+			candidate: candidateRef,
+			metric: comparison.evaluation
+		}), "knowledge-evaluation", `knowledge-${candidate.candidateId}`, artifacts, signal);
+		const baseline = await freeze("baseline");
+		const proposed = await freeze("candidate");
+		return Object.freeze({
+			reference: candidateRef,
+			evaluation,
+			baseline,
+			candidate: proposed
+		});
+	});
+}
+async function captureKnowledgeEvidence(bytes, purpose, executionId, artifacts, signal) {
+	if (!artifacts) return embeddedCandidateArtifact(bytes);
+	return persistCandidateOutputArtifact(artifacts, {
+		executionId,
+		purpose,
+		bytes,
+		...signal ? { signal } : {}
+	});
+}
+function emptySpent() {
+	return {
+		iterations: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		usdKnown: true,
+		usd: 0,
+		ms: 0
+	};
+}
+function addSpent(target, result) {
+	const spent = result.spentTotal;
+	target.iterations += spent.iterations;
+	target.inputTokens += spent.tokens.input;
+	target.outputTokens += spent.tokens.output;
+	target.usdKnown = target.usdKnown && spent.usdKnown !== false;
+	target.usd += spent.usd;
+	target.ms += spent.ms;
+}
+//#endregion
+export { createSupervisedKnowledgeUpdater as a, runSupervisedKnowledgeUpdate as c, RESEARCH_SUPERVISOR_SYSTEM_PROMPT as i, createKnowledgeImprovementActivationExecutor as l, createAgentKnowledgeReadinessCheck as n, formatSupervisedKnowledgeTask as o, runKnowledgeImprovementJob as r, knowledgeReadinessDeliverable as s, buildKnowledgeImprovementExperimentBundles as t };
+
+//# sourceMappingURL=knowledge-Ku-mPP4f.js.map