@evo-dev/core 0.0.1-alpha.19 → 0.0.1-alpha.20

package/src/evolution/knowledge/index.ts

@@ -40,6 +40,16 @@ import {
   createOkfKnowledgeVerificationSnapshot,
   deriveOkfKnowledgeFreshness,
 } from "./freshness.ts";
+import { type OkfKnowledgeSupportRef, isDirectKnowledgeSupport } from "./support.ts";
+
+export type {
+  OkfKnowledgeDelivery,
+  OkfKnowledgeRuntimeEligibility,
+  OkfKnowledgeSourceStatus,
+  OkfKnowledgeSupportKind,
+  OkfKnowledgeSupportRef,
+} from "./support.ts";
+export { resolveOkfKnowledgeRuntimeEligibility } from "./support.ts";
 
 export type OkfKnowledgeDecision =
   | "auto-accept"
@@ -160,6 +170,7 @@ export interface OkfKnowledgePlanCandidate {
   scores: OkfKnowledgeCandidateScores;
   decisionReason: string;
   evidenceRefs: string[];
+  supportRef?: OkfKnowledgeSupportRef;
   reviewState: OkfKnowledgeReviewState;
   verificationNotApplicableReason?: string;
   evalSetRefs?: string[];
@@ -280,6 +291,7 @@ export interface OkfKnowledgeConcept {
   lifecycle: OkfKnowledgeLifecycle;
   lifecyclePersisted: boolean;
   verificationSnapshot: OkfKnowledgeVerificationSnapshotV1 | null;
+  supportRef: OkfKnowledgeSupportRef | null;
   title: string;
   description: string;
   tags: string[];
@@ -391,13 +403,13 @@ export interface ScopedKnowledgeContextPack {
   id: string;
   okfIndexRevision: string;
   scope: ScopedKnowledgeContextPackScope;
-  queryText?: string;
+  queryHash?: string;
   items: ScopedKnowledgeContextPackItem[];
   warnings: string[];
   rawContentStored: false;
 }
 
-export type ContextInjectionTrigger = "team-startup" | "hook-safe-point";
+export type ContextInjectionTrigger = "team-startup" | "hook-safe-point" | "ordinary-session";
 
 export interface ContextInjectionReceipt {
   version: 1;
@@ -405,9 +417,17 @@ export interface ContextInjectionReceipt {
   okfIndexRevision: string;
   scope: ScopedKnowledgeContextPackScope;
   itemIds: string[];
+  queryHash: string | null;
   injectedAt: string;
   hookEventId: string | null;
   trigger: ContextInjectionTrigger;
+  outcome: null | {
+    status: "verified";
+    eventId: string;
+    observedAt: string;
+    summaryHash: string;
+    rawContentStored: false;
+  };
   rawContentStored: false;
 }
 
@@ -963,6 +983,10 @@ function normalizePlanCandidate(value: unknown, path: string): OkfKnowledgePlanC
       readRequiredString(input.decisionReason, `${path}.decisionReason`),
     ),
     evidenceRefs: readStringArray(input.evidenceRefs, `${path}.evidenceRefs`).map(sanitizeOkfText),
+    supportRef:
+      input.supportRef === undefined
+        ? undefined
+        : normalizeKnowledgeSupportRef(input.supportRef, `${path}.supportRef`),
     reviewState: parseOkfReviewState(readRequiredString(input.reviewState, `${path}.reviewState`)),
     verificationNotApplicableReason:
       typeof input.verificationNotApplicableReason === "string"
@@ -1047,6 +1071,7 @@ function validateCandidateContract(
   validateStringArrayValue(candidate.pathScopes, `${path}.pathScopes`, add);
   validateStringArrayValue(candidate.relatedConceptLinks, `${path}.relatedConceptLinks`, add);
   validateStringArrayValue(candidate.evidenceRefs, `${path}.evidenceRefs`, add);
+  validateKnowledgeSupportRefValue(candidate.supportRef, `${path}.supportRef`, add);
   validateOverlayUpdatesValue(candidate.overlayUpdates, `${path}.overlayUpdates`, add);
   validateScoresValue(candidate.scores, `${path}.scores`, add);
   validatePrivacyCheckValue(candidate.privacyCheck, `${path}.privacyCheck`, add);
@@ -1381,6 +1406,33 @@ function normalizeBasis(value: string): "direct" | "inferred" {
   return value;
 }
 
+function normalizeKnowledgeSupportRef(value: unknown, path: string): OkfKnowledgeSupportRef {
+  const input = assertRecordValue(value, path) as Record<string, unknown>;
+  const kind = readRequiredString(input.kind, `${path}.kind`);
+  if (
+    kind !== "user-declaration" &&
+    kind !== "repo-policy" &&
+    kind !== "state-observation" &&
+    kind !== "verified-outcome" &&
+    kind !== "semantic-inference"
+  ) {
+    throw new Error(`${path}.kind is invalid.`);
+  }
+  const observedAt = readRequiredString(input.observedAt, `${path}.observedAt`);
+  if (!Number.isFinite(Date.parse(observedAt))) throw new Error(`${path}.observedAt is invalid.`);
+  const subjectFingerprint =
+    input.subjectFingerprint === null
+      ? null
+      : sanitizeOkfText(readRequiredString(input.subjectFingerprint, `${path}.subjectFingerprint`));
+  return {
+    id: sanitizeOkfText(readRequiredString(input.id, `${path}.id`)),
+    kind,
+    sourceRefId: sanitizeOkfText(readRequiredString(input.sourceRefId, `${path}.sourceRefId`)),
+    subjectFingerprint,
+    observedAt: new Date(observedAt).toISOString(),
+  };
+}
+
 function normalizeEvalSetDecision(value: string): OkfKnowledgeEvalSet["decision"] {
   const normalized = value === "no-write" ? "no_write" : value;
   if (
@@ -1550,6 +1602,45 @@ function validateStringArrayValue(
   });
 }
 
+function validateKnowledgeSupportRefValue(
+  value: unknown,
+  path: string,
+  add: (path: string, code: string, message: string, severity?: "error" | "warning") => void,
+): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) {
+    add(path, "supportRef.object", "Candidate supportRef must be an object.");
+    return;
+  }
+  if (!isNonEmptyString(value.id)) add(`${path}.id`, "supportRef.id", "supportRef id is required.");
+  if (
+    value.kind !== "user-declaration" &&
+    value.kind !== "repo-policy" &&
+    value.kind !== "state-observation" &&
+    value.kind !== "verified-outcome" &&
+    value.kind !== "semantic-inference"
+  ) {
+    add(`${path}.kind`, "supportRef.kind", "supportRef kind is invalid.");
+  }
+  if (!isNonEmptyString(value.sourceRefId)) {
+    add(`${path}.sourceRefId`, "supportRef.sourceRefId", "supportRef sourceRefId is required.");
+  }
+  if (value.subjectFingerprint !== null && !isNonEmptyString(value.subjectFingerprint)) {
+    add(
+      `${path}.subjectFingerprint`,
+      "supportRef.subjectFingerprint",
+      "supportRef subjectFingerprint must be null or a non-empty string.",
+    );
+  }
+  if (!isNonEmptyString(value.observedAt) || !Number.isFinite(Date.parse(value.observedAt))) {
+    add(
+      `${path}.observedAt`,
+      "supportRef.observedAt",
+      "supportRef observedAt must be an ISO timestamp.",
+    );
+  }
+}
+
 function validateOverlayUpdatesValue(
   value: unknown,
   path: string,
@@ -1858,6 +1949,7 @@ export function decideOkfKnowledgeCandidate(
     localActiveTarget &&
     sanitized.targetStore === "okf" &&
     sanitized.basis === "direct" &&
+    isDirectKnowledgeSupport(sanitized.supportRef) &&
     sanitized.metadataOnlyEvidence &&
     hasVerification &&
     hasScopeTags &&
@@ -3101,10 +3193,8 @@ export function mergeAcceptedEvosCasesIntoKnowledgeQuery(
         score: structuredScore + lexical.score,
         title: evosCase.title,
         summary: evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
-        freshness: "verified",
-        runtimeExcerpt: sanitizeOkfText(
-          evosCase.expectedFutureBehavior || evosCase.result.summary || evosCase.title,
-        ).slice(0, 1_200),
+        freshness: "unknown",
+        runtimeExcerpt: null,
         matchReasons:
           lexical.reasons.length === 0
             ? structuredReasons
@@ -3131,16 +3221,24 @@ export async function createScopedKnowledgeContextPack(input: {
   paths?: string[];
   queryText?: string;
   limit?: number;
+  inlineOnly?: boolean;
 }): Promise<ScopedKnowledgeContextPack | null> {
-  const result = await queryScopedOkfKnowledgeContext(input);
-  if (result.items.length === 0) return null;
+  const result = await queryScopedOkfKnowledgeContext({
+    ...input,
+    limit: input.inlineOnly === true ? Math.max(input.limit ?? 3, 50) : input.limit,
+  });
+  const selectedItems =
+    input.inlineOnly === true
+      ? result.items.filter((item) => item.runtimeExcerpt !== null).slice(0, input.limit ?? 3)
+      : result.items;
+  if (selectedItems.length === 0) return null;
   const scope: ScopedKnowledgeContextPackScope = {
     ...(result.projectKey === undefined ? {} : { projectKey: result.projectKey }),
     ...(result.roleId === undefined ? {} : { roleId: result.roleId }),
     ...(result.workflowId === undefined ? {} : { workflowId: result.workflowId }),
     paths: result.paths,
   };
-  const items = result.items.map<ScopedKnowledgeContextPackItem>((item) => ({
+  const items = selectedItems.map<ScopedKnowledgeContextPackItem>((item) => ({
     id: item.id,
     sourceType: item.sourceType,
     sourceLink: item.sourceLink,
@@ -3160,10 +3258,11 @@ export async function createScopedKnowledgeContextPack(input: {
   }));
   const okfIndexRevision = createKnowledgeContextRevision(items);
   const queryText = normalizeKnowledgeQueryText(result.queryText);
+  const queryHash = queryText === undefined ? undefined : sha256Short(queryText);
   const packSeed = stableJsonStringify({
     okfIndexRevision,
     scope,
-    queryText: queryText ?? null,
+    queryHash: queryHash ?? null,
     items: items.map((item) => ({
       id: item.id,
       sourceType: item.sourceType,
@@ -3181,7 +3280,7 @@ export async function createScopedKnowledgeContextPack(input: {
     id: `ctxpack-${sha256Short(packSeed)}`,
     okfIndexRevision,
     scope,
-    ...(queryText === undefined ? {} : { queryText }),
+    ...(queryHash === undefined ? {} : { queryHash }),
     items,
     warnings:
       result.warnings.length === 0
@@ -3200,7 +3299,6 @@ export function formatScopedKnowledgePromptBlock(pack: ScopedKnowledgeContextPac
     `Project: ${pack.scope.projectKey ?? "all"}`,
     `Role: ${pack.scope.roleId ?? "any"}`,
     `Workflow: ${pack.scope.workflowId ?? "any"}`,
-    ...(pack.queryText === undefined ? [] : [`Query: ${sanitizeOkfText(pack.queryText)}`]),
     `Paths: ${pack.scope.paths.length === 0 ? "all" : pack.scope.paths.join(", ")}`,
     "Raw content stored: false",
     "Freshness is determined by EvoDev lifecycle and verification metadata; do not infer validity from timestamps.",
@@ -3266,9 +3364,11 @@ export async function writeContextInjectionReceipt(input: {
     okfIndexRevision: input.pack.okfIndexRevision,
     scope: input.pack.scope,
     itemIds: input.pack.items.map((item) => item.id),
+    queryHash: input.pack.queryHash ?? null,
     injectedAt: input.injectedAt ?? new Date().toISOString(),
     hookEventId: input.hookEventId ?? null,
     trigger: input.trigger,
+    outcome: null,
     rawContentStored: false,
   };
   const path = resolveContextInjectionReceiptPath({
@@ -3280,6 +3380,57 @@ export async function writeContextInjectionReceipt(input: {
   return { path, receipt };
 }
 
+export async function recordContextInjectionOutcome(input: {
+  homeDir: string;
+  sessionKey: string;
+  eventId: string;
+  observedAt: string;
+  summary: string;
+}): Promise<string[]> {
+  const stateDir = resolveEvoDevPaths(input.homeDir).stateDir;
+  const directory = join(
+    stateDir,
+    "context-injections",
+    sanitizeReceiptPathSegment(input.sessionKey),
+  );
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch {
+    return [];
+  }
+  const paths: string[] = [];
+  for (const name of names.filter((item) => item.endsWith(".json")).sort()) {
+    const path = join(directory, name);
+    let receipt: ContextInjectionReceipt;
+    try {
+      receipt = JSON.parse(await readFile(path, "utf8")) as ContextInjectionReceipt;
+    } catch {
+      continue;
+    }
+    if (
+      receipt.version !== 1 ||
+      receipt.rawContentStored !== false ||
+      (receipt.outcome !== null && receipt.outcome !== undefined)
+    ) {
+      continue;
+    }
+    const updated: ContextInjectionReceipt = {
+      ...receipt,
+      outcome: {
+        status: "verified",
+        eventId: sanitizeReceiptPathSegment(input.eventId),
+        observedAt: normalizeTimestamp(input.observedAt),
+        summaryHash: sha256Short(input.summary),
+        rawContentStored: false,
+      },
+    };
+    await writeJson(path, updated, { overwrite: true });
+    paths.push(path);
+  }
+  return paths;
+}
+
 export async function markOkfKnowledgeConceptStale(input: {
   homeDir: string;
   conceptId: string;
@@ -3947,6 +4098,9 @@ function explainAutomaticNoWriteDecision(
   const reasons: string[] = [];
   if (candidate.targetStore !== "okf") reasons.push("target is not user-local OKF");
   if (candidate.basis !== "direct") reasons.push("basis is inferred");
+  if (!isDirectKnowledgeSupport(candidate.supportRef)) {
+    reasons.push("structured direct support is missing");
+  }
   if (!candidate.metadataOnlyEvidence) reasons.push("evidence is not metadata-only");
   if (!hasVerification) reasons.push("verification evidence is missing");
   if (!hasScopeTags) reasons.push("repo or role tags are missing");
@@ -4233,6 +4387,7 @@ function renderOkfConcept(
     `  stableKey: ${yamlString(candidate.stableKey)}`,
     `  reviewState: ${yamlString(reviewState)}`,
     renderLifecycleYaml("  ", lifecycle),
+    renderKnowledgeSupportRefYaml("  ", candidate.supportRef ?? null),
     renderVerificationSnapshotYaml("  ", verificationSnapshot),
     "  source:",
     `    kind: ${yamlString("trace-distillation")}`,
@@ -4511,6 +4666,7 @@ function parseOkfConceptFile(
     lifecycle: lifecycleParsed.lifecycle,
     lifecyclePersisted: lifecycleParsed.persisted,
     verificationSnapshot: parseOkfVerificationSnapshot(frontmatter),
+    supportRef: parseOkfKnowledgeSupportRef(frontmatter),
     title,
     description,
     tags,
@@ -4522,6 +4678,27 @@ function parseOkfConceptFile(
   };
 }
 
+function parseOkfKnowledgeSupportRef(frontmatter: string): OkfKnowledgeSupportRef | null {
+  const block = extractNestedYamlBlock(frontmatter, "evodev", "supportRef");
+  if (block === null) return null;
+  try {
+    return normalizeKnowledgeSupportRef(
+      {
+        id: readIndentedYamlScalar(block, "id"),
+        kind: readIndentedYamlScalar(block, "kind"),
+        sourceRefId: readIndentedYamlScalar(block, "sourceRefId"),
+        subjectFingerprint: readNullableLifecycleString(
+          readIndentedYamlScalar(block, "subjectFingerprint"),
+        ),
+        observedAt: readIndentedYamlScalar(block, "observedAt"),
+      },
+      "evodev.supportRef",
+    );
+  } catch {
+    return null;
+  }
+}
+
 function parseOkfVerificationSnapshot(
   frontmatter: string,
 ): OkfKnowledgeVerificationSnapshotV1 | null {
@@ -5303,6 +5480,21 @@ function renderVerificationSnapshotYaml(
   ].join("\n");
 }
 
+function renderKnowledgeSupportRefYaml(
+  indent: string,
+  supportRef: OkfKnowledgeSupportRef | null,
+): string {
+  if (supportRef === null) return `${indent}supportRef: null`;
+  return [
+    `${indent}supportRef:`,
+    `${indent}  id: ${yamlString(supportRef.id)}`,
+    `${indent}  kind: ${yamlString(supportRef.kind)}`,
+    `${indent}  sourceRefId: ${yamlString(supportRef.sourceRefId)}`,
+    `${indent}  subjectFingerprint: ${yamlNullableString(supportRef.subjectFingerprint)}`,
+    `${indent}  observedAt: ${yamlString(supportRef.observedAt)}`,
+  ].join("\n");
+}
+
 function lifecycleStatusFromReviewState(
   reviewState: OkfKnowledgeReviewState,
 ): OkfKnowledgeLifecycleStatus {

package/src/evolution/knowledge/support.ts

@@ -0,0 +1,135 @@
+export type OkfKnowledgeSupportKind =
+  | "user-declaration"
+  | "repo-policy"
+  | "state-observation"
+  | "verified-outcome"
+  | "semantic-inference";
+
+export interface OkfKnowledgeSupportRef {
+  id: string;
+  kind: OkfKnowledgeSupportKind;
+  sourceRefId: string;
+  subjectFingerprint: string | null;
+  observedAt: string;
+}
+
+export type OkfKnowledgeDelivery = "inline" | "reference" | "blocked";
+export type OkfKnowledgeSourceStatus = "current" | "changed" | "unknown";
+
+export interface OkfKnowledgeRuntimeEligibility {
+  delivery: OkfKnowledgeDelivery;
+  freshness: "verified" | "review-due" | "unknown" | "stale";
+  reason: string;
+}
+
+export function resolveOkfKnowledgeRuntimeEligibility(input: {
+  reviewState: string;
+  lifecycle: {
+    status: string;
+    reviewAfter: string;
+    staleAfter: string;
+  };
+  supportRef: OkfKnowledgeSupportRef | null;
+  now?: string | Date;
+  sourceStatus?: OkfKnowledgeSourceStatus;
+  verifiedContradiction?: boolean;
+}): OkfKnowledgeRuntimeEligibility {
+  const now = normalizeNow(input.now);
+  if (
+    input.verifiedContradiction === true ||
+    input.lifecycle.status === "stale" ||
+    input.lifecycle.status === "deprecated" ||
+    input.lifecycle.status === "revoked" ||
+    input.lifecycle.status === "superseded" ||
+    input.reviewState === "stale" ||
+    input.reviewState === "deprecated" ||
+    input.reviewState === "revoked" ||
+    input.reviewState === "superseded" ||
+    isDue(input.lifecycle.staleAfter, now)
+  ) {
+    return {
+      delivery: "blocked",
+      freshness: "stale",
+      reason:
+        input.verifiedContradiction === true
+          ? "Verified evidence contradicts the active claim."
+          : "Lifecycle state excludes this knowledge from runtime context.",
+    };
+  }
+  if (input.reviewState !== "accepted" && input.reviewState !== "auto-accepted") {
+    return {
+      delivery: "blocked",
+      freshness: "unknown",
+      reason: "Knowledge has not passed an active-compatible review state.",
+    };
+  }
+  if (input.sourceStatus === "changed") {
+    return {
+      delivery: "blocked",
+      freshness: "review-due",
+      reason: "The supporting source changed and requires revalidation.",
+    };
+  }
+  if (isDue(input.lifecycle.reviewAfter, now)) {
+    return {
+      delivery: "reference",
+      freshness: "review-due",
+      reason: `Review was due at ${input.lifecycle.reviewAfter}.`,
+    };
+  }
+  if (input.supportRef === null) {
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "Legacy knowledge has no structured support reference.",
+    };
+  }
+  if (input.supportRef.kind === "semantic-inference") {
+    if (input.reviewState === "accepted") {
+      return {
+        delivery: "inline",
+        freshness: "verified",
+        reason: "A human-accepted inference is runtime-eligible as an explicit decision.",
+      };
+    }
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "Model-inferred knowledge remains on-demand until supported by a direct source.",
+    };
+  }
+  if (
+    (input.supportRef.kind === "repo-policy" || input.supportRef.kind === "state-observation") &&
+    input.sourceStatus !== "current"
+  ) {
+    return {
+      delivery: "reference",
+      freshness: "unknown",
+      reason: "The supporting repository source has not been revalidated for this query.",
+    };
+  }
+  return {
+    delivery: "inline",
+    freshness: "verified",
+    reason: `Runtime-eligible through ${input.supportRef.kind}.`,
+  };
+}
+
+export function isDirectKnowledgeSupport(
+  supportRef: OkfKnowledgeSupportRef | null | undefined,
+): boolean {
+  return (
+    supportRef !== undefined && supportRef !== null && supportRef.kind !== "semantic-inference"
+  );
+}
+
+function normalizeNow(value: string | Date | undefined): Date {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value;
+  if (typeof value === "string" && Number.isFinite(Date.parse(value))) return new Date(value);
+  return new Date();
+}
+
+function isDue(value: string, now: Date): boolean {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp <= now.getTime();
+}