@evo-dev/core 0.0.1-alpha.15 → 0.0.1-alpha.17

package/src/evolution/knowledge/changes.ts

@@ -0,0 +1,453 @@
+import { createHash } from "node:crypto";
+import type {
+  OkfKnowledgeConcept,
+  OkfKnowledgeLifecycleStatus,
+  OkfKnowledgePlanCandidate,
+} from "./index.ts";
+
+export const OKF_KNOWLEDGE_RENDER_CONTRACT_VERSION = 2;
+
+export type OkfKnowledgeChangeClassification =
+  | "create"
+  | "refresh"
+  | "update"
+  | "supersede"
+  | "revoke"
+  | "no_write";
+
+export type OkfKnowledgeChangeOperation = "create" | "update" | "supersede" | "revoke";
+
+export type OkfKnowledgeChangeState =
+  | "pending"
+  | "accepted"
+  | "rejected"
+  | "deferred"
+  | "applied"
+  | "superseded";
+
+export interface OkfKnowledgeRuntimeProjectionV1 {
+  renderContractVersion: number;
+  type: string;
+  title: string;
+  description: string;
+  stableKey: string;
+  claim: string;
+  summary: string;
+  appliesWhen: string[];
+  howToApply: string;
+  guidance: string[];
+  antiCriteria: string[];
+  verification: string[];
+  citations: string[];
+  scopes: {
+    repoTags: string[];
+    roleTags: string[];
+    workflowTags: string[];
+    pathScopes: string[];
+  };
+  relatedConceptLinks: string[];
+  lifecycle: {
+    status: OkfKnowledgeLifecycleStatus;
+    supersedes: string[];
+    supersededBy: string | null;
+    revoked: boolean;
+  };
+}
+
+export interface OkfKnowledgeRuntimeDiffV1 {
+  runtimeFields: string[];
+  metadataFields: string[];
+  summary: string;
+}
+
+export interface OkfKnowledgeChangeClassificationResult {
+  classification: OkfKnowledgeChangeClassification;
+  baseRevision: string | null;
+  candidateRevision: string;
+  baseProjection: OkfKnowledgeRuntimeProjectionV1 | null;
+  candidateProjection: OkfKnowledgeRuntimeProjectionV1;
+  diff: OkfKnowledgeRuntimeDiffV1;
+  reason: string;
+}
+
+export function createOkfKnowledgeRuntimeProjectionFromCandidate(
+  candidate: OkfKnowledgePlanCandidate,
+): OkfKnowledgeRuntimeProjectionV1 {
+  return normalizeRuntimeProjection({
+    renderContractVersion: OKF_KNOWLEDGE_RENDER_CONTRACT_VERSION,
+    type: candidate.okfType,
+    title: candidate.title,
+    description: candidate.description,
+    stableKey: candidate.stableKey,
+    claim: candidate.claim,
+    summary: candidate.bodySections.summary,
+    appliesWhen: candidate.bodySections.appliesWhen,
+    howToApply: candidate.howToApply,
+    guidance: candidate.bodySections.guidance,
+    antiCriteria: uniqueStrings([
+      ...candidate.antiCriteria,
+      ...candidate.bodySections.antiCriteria,
+    ]),
+    verification: candidate.bodySections.verification,
+    citations: candidate.bodySections.citations,
+    scopes: {
+      repoTags: candidate.repoTags,
+      roleTags: candidate.roleTags,
+      workflowTags: candidate.workflowTags,
+      pathScopes: candidate.pathScopes,
+    },
+    relatedConceptLinks: candidate.relatedConceptLinks,
+    lifecycle: {
+      status: candidate.decision === "revoke" ? "revoked" : "active",
+      supersedes: [],
+      supersededBy: null,
+      revoked: candidate.decision === "revoke",
+    },
+  });
+}
+
+export function createOkfKnowledgeRuntimeProjectionFromConcept(
+  concept: OkfKnowledgeConcept,
+): OkfKnowledgeRuntimeProjectionV1 {
+  const sections = parseMarkdownSections(concept.body);
+  const summary = readSectionText(sections, "Summary");
+  const guidance = readSectionList(sections, "Guidance");
+  return normalizeRuntimeProjection({
+    renderContractVersion: OKF_KNOWLEDGE_RENDER_CONTRACT_VERSION,
+    type: concept.type,
+    title: concept.title,
+    description: concept.description,
+    stableKey: concept.stableKey,
+    claim: readSectionText(sections, "Claim") || summary,
+    summary,
+    appliesWhen: readSectionList(sections, "Applies When"),
+    howToApply: readSectionText(sections, "How to Apply") || guidance[0] || "",
+    guidance,
+    antiCriteria: readSectionList(sections, "Anti-Criteria"),
+    verification: readSectionList(sections, "Verification").filter(
+      (item) => item !== "No verification command is stored in this concept.",
+    ),
+    citations: readSectionList(sections, "Citations").filter(
+      (item) => item !== "No external citations stored.",
+    ),
+    scopes: {
+      repoTags: concept.repoTags,
+      roleTags: concept.roleTags,
+      workflowTags: concept.workflowTags,
+      pathScopes: concept.pathScopes,
+    },
+    relatedConceptLinks: readSectionList(sections, "Related Concepts").filter(
+      (item) => item !== "No related concepts yet.",
+    ),
+    lifecycle: {
+      status: concept.lifecycle.status,
+      supersedes: concept.lifecycle.supersedes,
+      supersededBy: concept.lifecycle.supersededBy,
+      revoked: concept.lifecycle.status === "revoked" || concept.lifecycle.revokedAt !== null,
+    },
+  });
+}
+
+export function createOkfKnowledgeRevision(projection: OkfKnowledgeRuntimeProjectionV1): string {
+  return `knowledge-rev-${createHash("sha256")
+    .update(stableJsonStringify(normalizeRuntimeProjection(projection)))
+    .digest("hex")
+    .slice(0, 24)}`;
+}
+
+export function diffOkfKnowledgeRuntimeProjections(
+  base: OkfKnowledgeRuntimeProjectionV1 | null,
+  candidate: OkfKnowledgeRuntimeProjectionV1,
+  metadataFields: string[] = [],
+): OkfKnowledgeRuntimeDiffV1 {
+  const runtimeFields = base === null ? ["concept"] : listChangedProjectionFields(base, candidate);
+  const normalizedMetadataFields = uniqueStrings(metadataFields).sort();
+  const summary =
+    runtimeFields.length === 0
+      ? normalizedMetadataFields.length === 0
+        ? "No effective knowledge change."
+        : `Metadata refresh: ${normalizedMetadataFields.join(", ")}.`
+      : base === null
+        ? "Create a new active knowledge concept."
+        : `Runtime knowledge changed: ${runtimeFields.join(", ")}.`;
+  return {
+    runtimeFields,
+    metadataFields: normalizedMetadataFields,
+    summary,
+  };
+}
+
+export function classifyOkfKnowledgeCandidate(input: {
+  candidate: OkfKnowledgePlanCandidate;
+  existingConcept?: OkfKnowledgeConcept | null;
+  metadataFields?: string[];
+}): OkfKnowledgeChangeClassificationResult {
+  const existing = input.existingConcept ?? null;
+  const baseProjection =
+    existing === null ? null : createOkfKnowledgeRuntimeProjectionFromConcept(existing);
+  let candidateProjection = createOkfKnowledgeRuntimeProjectionFromCandidate(input.candidate);
+  if (baseProjection !== null && existing?.stableKey === input.candidate.stableKey) {
+    candidateProjection =
+      input.candidate.decision === "revoke"
+        ? normalizeRuntimeProjection({
+            ...baseProjection,
+            lifecycle: {
+              ...baseProjection.lifecycle,
+              status: "revoked",
+              revoked: true,
+            },
+          })
+        : {
+            ...candidateProjection,
+            lifecycle: baseProjection.lifecycle,
+          };
+  }
+  const candidateRevision = createOkfKnowledgeRevision(candidateProjection);
+  const baseRevision = baseProjection === null ? null : createOkfKnowledgeRevision(baseProjection);
+  const diff = diffOkfKnowledgeRuntimeProjections(
+    baseProjection,
+    candidateProjection,
+    input.metadataFields ?? ["evidenceRefs", "verifiedAt"],
+  );
+
+  if (input.candidate.decision === "no_write" || input.candidate.decision === "skip") {
+    return {
+      classification: "no_write",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: input.candidate.decisionReason || "Candidate is not eligible for a knowledge write.",
+    };
+  }
+  if (input.candidate.decision === "revoke" && existing === null) {
+    return {
+      classification: "no_write",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: "No active concept uses this stable key, so there is nothing to revoke.",
+    };
+  }
+  if (existing === null) {
+    return {
+      classification: "create",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: "No active concept uses this stable key.",
+    };
+  }
+  if (existing.stableKey !== input.candidate.stableKey) {
+    return {
+      classification: "no_write",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: "Existing concept identity does not match the candidate stable key.",
+    };
+  }
+  if (input.candidate.decision === "revoke") {
+    return {
+      classification: "revoke",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: input.candidate.decisionReason,
+    };
+  }
+  if (shouldSupersede(existing, input.candidate)) {
+    return {
+      classification: "supersede",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: "The candidate changes the concept identity, canonical path, or incompatible scope.",
+    };
+  }
+  if (diff.runtimeFields.length === 0) {
+    return {
+      classification: "refresh",
+      baseRevision,
+      candidateRevision,
+      baseProjection,
+      candidateProjection,
+      diff,
+      reason: "Runtime projection is unchanged; only verification or provenance metadata changed.",
+    };
+  }
+  return {
+    classification: "update",
+    baseRevision,
+    candidateRevision,
+    baseProjection,
+    candidateProjection,
+    diff,
+    reason: diff.summary,
+  };
+}
+
+function shouldSupersede(
+  concept: OkfKnowledgeConcept,
+  candidate: OkfKnowledgePlanCandidate,
+): boolean {
+  const existingTargetPath = concept.sourceLink.replace(/^\/+/u, "");
+  const candidateTargetPath = candidate.targetPath.replace(/^\/+/u, "");
+  if (existingTargetPath !== candidateTargetPath) return true;
+  if (normalizeText(concept.type) !== normalizeText(candidate.okfType)) return true;
+  return (
+    scopesAreIncompatible(concept.repoTags, candidate.repoTags) ||
+    scopesAreIncompatible(concept.roleTags, candidate.roleTags) ||
+    scopesAreIncompatible(concept.workflowTags, candidate.workflowTags)
+  );
+}
+
+function scopesAreIncompatible(left: string[], right: string[]): boolean {
+  if (left.length === 0 || right.length === 0) return false;
+  const normalizedRight = new Set(right.map(normalizeText));
+  return !left.some((value) => normalizedRight.has(normalizeText(value)));
+}
+
+function normalizeRuntimeProjection(
+  value: OkfKnowledgeRuntimeProjectionV1,
+): OkfKnowledgeRuntimeProjectionV1 {
+  return {
+    renderContractVersion: value.renderContractVersion,
+    type: normalizeText(value.type),
+    title: normalizeText(value.title),
+    description: normalizeText(value.description),
+    stableKey: normalizeText(value.stableKey),
+    claim: normalizeMarkdown(value.claim),
+    summary: normalizeMarkdown(value.summary),
+    appliesWhen: normalizeArray(value.appliesWhen),
+    howToApply: normalizeMarkdown(value.howToApply),
+    guidance: normalizeArray(value.guidance),
+    antiCriteria: normalizeArray(value.antiCriteria),
+    verification: normalizeArray(value.verification),
+    citations: normalizeArray(value.citations),
+    scopes: {
+      repoTags: normalizeArray(value.scopes.repoTags),
+      roleTags: normalizeArray(value.scopes.roleTags),
+      workflowTags: normalizeArray(value.scopes.workflowTags),
+      pathScopes: normalizeArray(value.scopes.pathScopes),
+    },
+    relatedConceptLinks: normalizeArray(value.relatedConceptLinks),
+    lifecycle: {
+      status: value.lifecycle.status,
+      supersedes: normalizeArray(value.lifecycle.supersedes),
+      supersededBy:
+        value.lifecycle.supersededBy === null ? null : normalizeText(value.lifecycle.supersededBy),
+      revoked: value.lifecycle.revoked,
+    },
+  };
+}
+
+function listChangedProjectionFields(
+  base: OkfKnowledgeRuntimeProjectionV1,
+  candidate: OkfKnowledgeRuntimeProjectionV1,
+): string[] {
+  const fields: Array<[string, unknown, unknown]> = [
+    ["type", base.type, candidate.type],
+    ["title", base.title, candidate.title],
+    ["description", base.description, candidate.description],
+    ["stableKey", base.stableKey, candidate.stableKey],
+    ["claim", base.claim, candidate.claim],
+    ["summary", base.summary, candidate.summary],
+    ["appliesWhen", base.appliesWhen, candidate.appliesWhen],
+    ["howToApply", base.howToApply, candidate.howToApply],
+    ["guidance", base.guidance, candidate.guidance],
+    ["antiCriteria", base.antiCriteria, candidate.antiCriteria],
+    ["verification", base.verification, candidate.verification],
+    ["citations", base.citations, candidate.citations],
+    ["scopes.repoTags", base.scopes.repoTags, candidate.scopes.repoTags],
+    ["scopes.roleTags", base.scopes.roleTags, candidate.scopes.roleTags],
+    ["scopes.workflowTags", base.scopes.workflowTags, candidate.scopes.workflowTags],
+    ["scopes.pathScopes", base.scopes.pathScopes, candidate.scopes.pathScopes],
+    ["relatedConceptLinks", base.relatedConceptLinks, candidate.relatedConceptLinks],
+    ["lifecycle", base.lifecycle, candidate.lifecycle],
+  ];
+  return fields
+    .filter(([, left, right]) => stableJsonStringify(left) !== stableJsonStringify(right))
+    .map(([field]) => field);
+}
+
+function parseMarkdownSections(body: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  let heading = "";
+  let lines: string[] = [];
+  const flush = () => {
+    if (heading !== "") sections.set(heading, lines.join("\n").trim());
+  };
+  for (const line of body.replace(/\r\n?/gu, "\n").split("\n")) {
+    const match = line.match(/^#\s+(.+?)\s*$/u);
+    if (match?.[1] !== undefined) {
+      flush();
+      heading = match[1];
+      lines = [];
+      continue;
+    }
+    lines.push(line);
+  }
+  flush();
+  return sections;
+}
+
+function readSectionText(sections: Map<string, string>, heading: string): string {
+  return normalizeMarkdown(sections.get(heading) ?? "");
+}
+
+function readSectionList(sections: Map<string, string>, heading: string): string[] {
+  const section = sections.get(heading) ?? "";
+  const items = section
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => /^[-*]\s+/u.test(line))
+    .map((line) => line.replace(/^[-*]\s+/u, ""));
+  if (items.length > 0) return normalizeArray(items);
+  const text = normalizeMarkdown(section);
+  return text === "" ? [] : [text];
+}
+
+function normalizeText(value: string): string {
+  return value.replace(/\s+/gu, " ").trim();
+}
+
+function normalizeMarkdown(value: string): string {
+  return value
+    .replace(/\r\n?/gu, "\n")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+}
+
+function normalizeArray(values: string[]): string[] {
+  return uniqueStrings(values.map(normalizeMarkdown).filter((value) => value !== "")).sort();
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function stableJsonStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJsonStringify).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, child]) => child !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries
+    .map(([key, child]) => `${JSON.stringify(key)}:${stableJsonStringify(child)}`)
+    .join(",")}}`;
+}

package/src/evolution/knowledge/freshness.ts

@@ -0,0 +1,109 @@
+import type { OkfKnowledgeConcept, OkfKnowledgePlanCandidate } from "./index.ts";
+
+export type OkfKnowledgeFreshness = "verified" | "review-due" | "unknown" | "stale";
+
+export interface OkfKnowledgeVerificationSnapshotV1 {
+  schemaVersion: 1;
+  verifiedAt: string;
+  evidenceRefs: string[];
+  repository: null | {
+    projectKey: string;
+    head: string | null;
+    checkedPaths: Array<{
+      path: string;
+      sha256: string;
+    }>;
+  };
+}
+
+export interface OkfKnowledgeFreshnessResult {
+  freshness: OkfKnowledgeFreshness;
+  reason: string;
+}
+
+export function deriveOkfKnowledgeFreshness(input: {
+  concept: OkfKnowledgeConcept;
+  now?: string | Date;
+  repositoryFingerprintChanged?: boolean;
+  verifiedContradiction?: boolean;
+}): OkfKnowledgeFreshnessResult {
+  const now = normalizeNow(input.now);
+  const concept = input.concept;
+  if (
+    input.verifiedContradiction === true ||
+    concept.lifecycle.status === "stale" ||
+    concept.lifecycle.status === "deprecated" ||
+    concept.lifecycle.status === "revoked" ||
+    concept.lifecycle.status === "superseded" ||
+    concept.reviewState === "stale" ||
+    concept.reviewState === "deprecated" ||
+    concept.reviewState === "revoked" ||
+    concept.reviewState === "superseded" ||
+    isDue(concept.lifecycle.staleAfter, now)
+  ) {
+    return {
+      freshness: "stale",
+      reason:
+        input.verifiedContradiction === true
+          ? "Verified evidence contradicts the active claim."
+          : "Lifecycle status or staleAfter excludes this concept from new runtime context.",
+    };
+  }
+  if (concept.verificationSnapshot === null) {
+    return {
+      freshness: "unknown",
+      reason: "No verifiable knowledge snapshot is stored for this legacy concept.",
+    };
+  }
+  if (input.repositoryFingerprintChanged === true || isDue(concept.lifecycle.reviewAfter, now)) {
+    return {
+      freshness: "review-due",
+      reason:
+        input.repositoryFingerprintChanged === true
+          ? "A checked repository path changed after the last verification."
+          : `Review was due at ${concept.lifecycle.reviewAfter}.`,
+    };
+  }
+  return {
+    freshness: "verified",
+    reason: `Verified at ${concept.verificationSnapshot.verifiedAt}.`,
+  };
+}
+
+export function createOkfKnowledgeVerificationSnapshot(input: {
+  candidate: OkfKnowledgePlanCandidate;
+  verifiedAt: string;
+  projectKey: string;
+}): OkfKnowledgeVerificationSnapshotV1 | null {
+  const hasVerification =
+    input.candidate.bodySections.verification.length > 0 ||
+    input.candidate.verificationNotApplicableReason !== undefined;
+  if (!hasVerification) return null;
+  const verifiedAt = normalizeIso(input.verifiedAt);
+  if (verifiedAt === null) return null;
+  return {
+    schemaVersion: 1,
+    verifiedAt,
+    evidenceRefs: [...new Set(input.candidate.evidenceRefs)].sort(),
+    repository: null,
+  };
+}
+
+function normalizeNow(value: string | Date | undefined): Date {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value;
+  if (typeof value === "string") {
+    const normalized = normalizeIso(value);
+    if (normalized !== null) return new Date(normalized);
+  }
+  return new Date();
+}
+
+function isDue(value: string, now: Date): boolean {
+  const normalized = normalizeIso(value);
+  return normalized !== null && Date.parse(normalized) <= now.getTime();
+}
+
+function normalizeIso(value: string): string | null {
+  const time = Date.parse(value);
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}