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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evo-dev/core",
-  "version": "0.0.1-alpha.15",
+  "version": "0.0.1-alpha.16",
   "type": "module",
   "repository": {
     "type": "git",

package/src/config/settings.ts

@@ -15,13 +15,21 @@ export interface PluginSettings {
 }
 
 export interface MemorySettings {
-  autoAccept: boolean;
+  reviewKnowledgeUpdates: boolean;
   runtimeInjection: boolean;
   staleReview: boolean;
   lexicalIndex: boolean;
   sessionMemory: SessionMemoryPolicySnapshot;
 }
 
+type LegacyMemorySettingsInput = Partial<MemorySettings> & {
+  /**
+   * Deprecated compatibility input. This flag was never connected to OKF activation and is
+   * intentionally omitted from canonical settings output.
+   */
+  autoAccept?: boolean;
+};
+
 export interface EvolutionSettings {
   automation: {
     knowledge: boolean;
@@ -70,7 +78,7 @@ export type SettingsInput = Partial<{
   doctor: Partial<EvoDevSettings["doctor"]>;
   hooks: unknown;
   teamRuntime: Partial<TeamRuntimeSettings>;
-  memory: Partial<MemorySettings>;
+  memory: LegacyMemorySettingsInput;
   evolution: Partial<{
     automation: Partial<EvolutionSettings["automation"]>;
   }>;
@@ -130,7 +138,7 @@ export function createDefaultTeamRuntimeSettings(): TeamRuntimeSettings {
 
 export function createDefaultMemorySettings(): MemorySettings {
   return {
-    autoAccept: true,
+    reviewKnowledgeUpdates: true,
     runtimeInjection: true,
     staleReview: true,
     lexicalIndex: true,
@@ -294,11 +302,14 @@ function parseEvolutionSettings(value: unknown, path: string): EvolutionSettings
 function parseMemorySettings(value: unknown, path: string): MemorySettings {
   const input = expectRecord(value, path);
   const defaults = createDefaultMemorySettings();
+  if (input.autoAccept !== undefined) {
+    expectBoolean(input.autoAccept, `${path}.autoAccept`);
+  }
   return {
-    autoAccept:
-      input.autoAccept === undefined
-        ? defaults.autoAccept
-        : expectBoolean(input.autoAccept, `${path}.autoAccept`),
+    reviewKnowledgeUpdates:
+      input.reviewKnowledgeUpdates === undefined
+        ? defaults.reviewKnowledgeUpdates
+        : expectBoolean(input.reviewKnowledgeUpdates, `${path}.reviewKnowledgeUpdates`),
     runtimeInjection:
       input.runtimeInjection === undefined
         ? defaults.runtimeInjection

package/src/evolution/candidates/index.ts

@@ -437,6 +437,56 @@ export async function updateEvolutionRepoProposalReviewState(input: {
   );
 }
 
+export async function supersedeEvolutionRepoProposal(input: {
+  homeDir: string;
+  proposalId: string;
+  projectKey?: string;
+  expectedReviewState?: EvolutionRepoProposal["reviewState"];
+  reason: string;
+  now?: string | Date;
+}): Promise<{ path: string; record: EvolutionRepoProposal; changed: boolean }> {
+  return await withEvolutionReviewDecisionLock(
+    { homeDir: input.homeDir, kind: "repo-proposal", itemId: input.proposalId },
+    async () => {
+      const record = await readEvolutionRepoProposalById(input);
+      const paths = resolveEvolutionPaths({
+        homeDir: input.homeDir,
+        projectKey: record.projectKey,
+        runId: record.provenance.runId,
+      });
+      const path = join(paths.repoProposalsDir, `${record.id}.json`);
+      if (record.reviewState === "superseded") return { path, record, changed: false };
+      if (
+        input.expectedReviewState !== undefined &&
+        record.reviewState !== input.expectedReviewState
+      ) {
+        throw new Error("Repo proposal review state changed before supersession was applied.");
+      }
+      if (record.reviewState !== "pending" && record.reviewState !== "deferred") {
+        throw new Error("Only pending or deferred repo proposals can be superseded.");
+      }
+      const reason = input.reason.trim();
+      if (reason === "" || reason.length > 500) {
+        throw new Error("Repo proposal supersession reason must be 1-500 characters.");
+      }
+      const changedAt = normalizeTimestamp(input.now);
+      const next: EvolutionRepoProposal = {
+        ...record,
+        reviewState: "superseded",
+        reviewStateChangedAt: changedAt,
+        supersession: {
+          policy: "session-proposal-v2",
+          reason: sanitizeText(reason),
+          supersededAt: changedAt,
+        },
+      };
+      validateEvolutionRepoProposal(next);
+      await writeRepoProposalAndIndex({ homeDir: input.homeDir, proposal: next, changedAt });
+      return { path, record: next, changed: true };
+    },
+  );
+}
+
 export async function updateEvolutionRepoProposalImprovementEval(input: {
   homeDir: string;
   proposalId: string;

package/src/evolution/evidence/session-memory/retention.ts

@@ -312,7 +312,8 @@ function hasPendingDerivedReview(
       (proposal) =>
         proposal.provenance.runId === runId &&
         proposal.reviewState !== "rejected" &&
-        proposal.reviewState !== "applied",
+        proposal.reviewState !== "applied" &&
+        proposal.reviewState !== "superseded",
     )
   ) {
     return true;

package/src/evolution/knowledge/change-store.ts

@@ -0,0 +1,558 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveEvoDevPaths } from "../../config/paths.ts";
+import type {
+  OkfKnowledgeChangeOperation,
+  OkfKnowledgeChangeState,
+  OkfKnowledgeRuntimeDiffV1,
+  OkfKnowledgeRuntimeProjectionV1,
+} from "./changes.ts";
+import type { OkfKnowledgeFreshness } from "./freshness.ts";
+import type { OkfKnowledgeEvalSet, OkfKnowledgePlanCandidate } from "./index.ts";
+
+export interface OkfKnowledgeChangeCandidateV1 {
+  schemaVersion: 1;
+  kind: "okf-knowledge-change-candidate";
+  id: string;
+  projectKey: string;
+  runId: string;
+  operation: OkfKnowledgeChangeOperation;
+  state: OkfKnowledgeChangeState;
+  stableKey: string;
+  targetPath: string;
+  base: null | {
+    conceptId: string;
+    sourceLink: string;
+    revision: string;
+    runtimeProjection: OkfKnowledgeRuntimeProjectionV1;
+  };
+  candidate: {
+    revision: string;
+    planCandidate: OkfKnowledgePlanCandidate;
+    evalSets: OkfKnowledgeEvalSet[];
+  };
+  diff: OkfKnowledgeRuntimeDiffV1;
+  freshness: {
+    before: OkfKnowledgeFreshness | null;
+    after: OkfKnowledgeFreshness;
+    reason: string;
+  };
+  provenance: {
+    evidenceWindowId: string;
+    evidenceRefs: string[];
+    createdAt: string;
+    rawContentStored: false;
+  };
+  decision: null | {
+    state: "accepted" | "rejected" | "deferred";
+    reason: string | null;
+    decidedAt: string;
+  };
+  updatedAt: string;
+}
+
+export interface OkfKnowledgeChangeHistoryEntryV1 {
+  schemaVersion: 1;
+  kind: "okf-knowledge-change-history";
+  changeId: string;
+  projectKey: string;
+  operation: OkfKnowledgeChangeOperation;
+  fromState: OkfKnowledgeChangeState | null;
+  toState: OkfKnowledgeChangeState;
+  baseRevision: string | null;
+  candidateRevision: string;
+  runtimeFields: string[];
+  reason: string | null;
+  changedAt: string;
+  rawContentStored: false;
+}
+
+export class OkfKnowledgeChangeLockError extends Error {
+  readonly code = "KNOWLEDGE_CHANGE_LOCK_BUSY";
+
+  constructor() {
+    super("Knowledge change is currently being reviewed by another process.");
+    this.name = "OkfKnowledgeChangeLockError";
+  }
+}
+
+interface KnowledgeChangePaths {
+  rootDir: string;
+  projectDir: string;
+  candidatesDir: string;
+  historyPath: string;
+  locksDir: string;
+}
+
+const KNOWLEDGE_CHANGE_LOCK_STALE_MS = 5 * 60 * 1000;
+
+export function createOkfKnowledgeChangeCandidate(input: {
+  projectKey: string;
+  runId: string;
+  operation: OkfKnowledgeChangeOperation;
+  stableKey: string;
+  targetPath: string;
+  base: OkfKnowledgeChangeCandidateV1["base"];
+  candidateRevision: string;
+  planCandidate: OkfKnowledgePlanCandidate;
+  evalSets?: OkfKnowledgeEvalSet[];
+  diff: OkfKnowledgeRuntimeDiffV1;
+  freshness: OkfKnowledgeChangeCandidateV1["freshness"];
+  evidenceWindowId: string;
+  evidenceRefs: string[];
+  createdAt: string;
+}): OkfKnowledgeChangeCandidateV1 {
+  const projectKey = sanitizePathSegment(input.projectKey, "project key");
+  const createdAt = normalizeTimestamp(input.createdAt);
+  const seed = [
+    projectKey,
+    input.runId,
+    input.operation,
+    input.stableKey,
+    input.base?.revision ?? "none",
+    input.candidateRevision,
+  ].join("\0");
+  return {
+    schemaVersion: 1,
+    kind: "okf-knowledge-change-candidate",
+    id: `knowledge-change-${createHash("sha256").update(seed).digest("hex").slice(0, 24)}`,
+    projectKey,
+    runId: sanitizeText(input.runId),
+    operation: input.operation,
+    state: "pending",
+    stableKey: sanitizeText(input.stableKey),
+    targetPath: sanitizeTargetPath(input.targetPath),
+    base: input.base,
+    candidate: {
+      revision: input.candidateRevision,
+      planCandidate: input.planCandidate,
+      evalSets: input.evalSets ?? [],
+    },
+    diff: {
+      runtimeFields: [...new Set(input.diff.runtimeFields)].sort(),
+      metadataFields: [...new Set(input.diff.metadataFields)].sort(),
+      summary: sanitizeText(input.diff.summary),
+    },
+    freshness: {
+      before: input.freshness.before,
+      after: input.freshness.after,
+      reason: sanitizeText(input.freshness.reason),
+    },
+    provenance: {
+      evidenceWindowId: sanitizeText(input.evidenceWindowId),
+      evidenceRefs: [...new Set(input.evidenceRefs.map(sanitizeText))].sort(),
+      createdAt,
+      rawContentStored: false,
+    },
+    decision: null,
+    updatedAt: createdAt,
+  };
+}
+
+export async function writeOkfKnowledgeChangeCandidate(input: {
+  homeDir: string;
+  change: OkfKnowledgeChangeCandidateV1;
+}): Promise<{ path: string; change: OkfKnowledgeChangeCandidateV1 }> {
+  validateOkfKnowledgeChangeCandidate(input.change);
+  const paths = resolveKnowledgeChangePaths(input.homeDir, input.change.projectKey);
+  const path = join(paths.candidatesDir, `${input.change.id}.json`);
+  await mkdir(paths.candidatesDir, { recursive: true, mode: 0o700 });
+  try {
+    const existing = await readOkfKnowledgeChangeCandidate({
+      homeDir: input.homeDir,
+      changeId: input.change.id,
+      projectKey: input.change.projectKey,
+    });
+    if (JSON.stringify(existing.change) !== JSON.stringify(input.change)) {
+      throw new Error(
+        `Knowledge change id already exists with different content: ${input.change.id}`,
+      );
+    }
+    return existing;
+  } catch (error) {
+    if (!isNotFoundError(error)) throw error;
+  }
+  await atomicWriteJson(path, input.change);
+  await appendOkfKnowledgeChangeHistory({
+    homeDir: input.homeDir,
+    change: input.change,
+    fromState: null,
+    reason: null,
+  });
+  return { path, change: input.change };
+}
+
+export async function listOkfKnowledgeChangeCandidates(input: {
+  homeDir: string;
+  projectKey?: string;
+  state?: OkfKnowledgeChangeState;
+}): Promise<OkfKnowledgeChangeCandidateV1[]> {
+  const rootDir = join(
+    resolveEvoDevPaths(input.homeDir).stateDir,
+    "evolution",
+    "knowledge-changes",
+  );
+  const projectKeys =
+    input.projectKey === undefined
+      ? await listDirectoryNames(rootDir)
+      : [sanitizePathSegment(input.projectKey, "project key")];
+  const changes: OkfKnowledgeChangeCandidateV1[] = [];
+  for (const projectKey of projectKeys) {
+    const paths = resolveKnowledgeChangePaths(input.homeDir, projectKey);
+    for (const name of await listJsonFileNames(paths.candidatesDir)) {
+      const value = JSON.parse(await readFile(join(paths.candidatesDir, name), "utf8")) as unknown;
+      const change = parseOkfKnowledgeChangeCandidate(value);
+      if (input.state === undefined || change.state === input.state) changes.push(change);
+    }
+  }
+  return changes.sort((left, right) => {
+    const updated = right.updatedAt.localeCompare(left.updatedAt);
+    return updated === 0 ? left.id.localeCompare(right.id) : updated;
+  });
+}
+
+export async function readOkfKnowledgeChangeCandidate(input: {
+  homeDir: string;
+  changeId: string;
+  projectKey?: string;
+}): Promise<{ path: string; change: OkfKnowledgeChangeCandidateV1 }> {
+  const changeId = sanitizeChangeId(input.changeId);
+  if (input.projectKey !== undefined) {
+    const paths = resolveKnowledgeChangePaths(input.homeDir, input.projectKey);
+    const path = join(paths.candidatesDir, `${changeId}.json`);
+    const change = parseOkfKnowledgeChangeCandidate(
+      JSON.parse(await readFile(path, "utf8")) as unknown,
+    );
+    return { path, change };
+  }
+  const matches = await listOkfKnowledgeChangeCandidates({ homeDir: input.homeDir });
+  const filtered = matches.filter((change) => change.id === changeId);
+  if (filtered.length === 0) throw createNotFoundError(`Knowledge change not found: ${changeId}`);
+  if (filtered.length > 1) throw new Error(`Knowledge change id is ambiguous: ${changeId}`);
+  const change = filtered[0] as OkfKnowledgeChangeCandidateV1;
+  const paths = resolveKnowledgeChangePaths(input.homeDir, change.projectKey);
+  return { path: join(paths.candidatesDir, `${change.id}.json`), change };
+}
+
+export async function replaceOkfKnowledgeChangeCandidate(input: {
+  homeDir: string;
+  previous: OkfKnowledgeChangeCandidateV1;
+  next: OkfKnowledgeChangeCandidateV1;
+  reason: string | null;
+}): Promise<{ path: string; change: OkfKnowledgeChangeCandidateV1 }> {
+  validateOkfKnowledgeChangeCandidate(input.previous);
+  validateOkfKnowledgeChangeCandidate(input.next);
+  if (input.previous.id !== input.next.id || input.previous.projectKey !== input.next.projectKey) {
+    throw new Error("Knowledge change identity cannot be replaced.");
+  }
+  const paths = resolveKnowledgeChangePaths(input.homeDir, input.next.projectKey);
+  const path = join(paths.candidatesDir, `${input.next.id}.json`);
+  const current = parseOkfKnowledgeChangeCandidate(
+    JSON.parse(await readFile(path, "utf8")) as unknown,
+  );
+  if (
+    current.state !== input.previous.state ||
+    current.updatedAt !== input.previous.updatedAt ||
+    current.candidate.revision !== input.previous.candidate.revision
+  ) {
+    throw new Error("Knowledge change was modified by another decision.");
+  }
+  await atomicWriteJson(path, input.next);
+  await appendOkfKnowledgeChangeHistory({
+    homeDir: input.homeDir,
+    change: input.next,
+    fromState: input.previous.state,
+    reason: input.reason,
+  });
+  return { path, change: input.next };
+}
+
+export async function withOkfKnowledgeChangeLock<T>(input: {
+  homeDir: string;
+  projectKey: string;
+  stableKey: string;
+  conceptId: string | null;
+  run: () => Promise<T>;
+}): Promise<T> {
+  const paths = resolveKnowledgeChangePaths(input.homeDir, input.projectKey);
+  await mkdir(paths.locksDir, { recursive: true, mode: 0o700 });
+  const lockKey = createHash("sha256")
+    .update(`${input.stableKey}\0${input.conceptId ?? "new"}`)
+    .digest("hex")
+    .slice(0, 32);
+  const lockPath = join(paths.locksDir, `${lockKey}.lock`);
+  const lockToken = randomUUID();
+  try {
+    await writeFile(
+      lockPath,
+      `${JSON.stringify({ pid: process.pid, token: lockToken, acquiredAt: new Date().toISOString() })}\n`,
+      { encoding: "utf8", flag: "wx", mode: 0o600 },
+    );
+  } catch (error) {
+    if (isAlreadyExistsError(error)) {
+      if (await recoverStaleKnowledgeChangeLock(lockPath)) {
+        return await withOkfKnowledgeChangeLock(input);
+      }
+      throw new OkfKnowledgeChangeLockError();
+    }
+    throw error;
+  }
+  try {
+    return await input.run();
+  } finally {
+    if ((await readKnowledgeChangeLockToken(lockPath)) === lockToken) {
+      await rm(lockPath, { force: true });
+    }
+  }
+}
+
+export function parseOkfKnowledgeChangeCandidate(value: unknown): OkfKnowledgeChangeCandidateV1 {
+  validateOkfKnowledgeChangeCandidate(value);
+  return value;
+}
+
+function validateOkfKnowledgeChangeCandidate(
+  value: unknown,
+): asserts value is OkfKnowledgeChangeCandidateV1 {
+  if (!isRecord(value)) throw new Error("Invalid knowledge change candidate.");
+  if (value.schemaVersion !== 1 || value.kind !== "okf-knowledge-change-candidate") {
+    throw new Error("Invalid knowledge change candidate contract.");
+  }
+  for (const field of ["id", "projectKey", "runId", "stableKey", "targetPath", "updatedAt"]) {
+    if (typeof value[field] !== "string" || value[field].trim() === "") {
+      throw new Error(`Invalid knowledge change ${field}.`);
+    }
+  }
+  if (!["create", "update", "supersede", "revoke"].includes(String(value.operation))) {
+    throw new Error("Invalid knowledge change operation.");
+  }
+  if (
+    !["pending", "accepted", "rejected", "deferred", "applied", "superseded"].includes(
+      String(value.state),
+    )
+  ) {
+    throw new Error("Invalid knowledge change state.");
+  }
+  if (!isRecord(value.candidate) || typeof value.candidate.revision !== "string") {
+    throw new Error("Invalid knowledge change candidate revision.");
+  }
+  if (!isRecord(value.diff) || !Array.isArray(value.diff.runtimeFields)) {
+    throw new Error("Invalid knowledge change diff.");
+  }
+  if (!isRecord(value.provenance) || value.provenance.rawContentStored !== false) {
+    throw new Error("Knowledge change provenance must remain metadata-only.");
+  }
+}
+
+async function appendOkfKnowledgeChangeHistory(input: {
+  homeDir: string;
+  change: OkfKnowledgeChangeCandidateV1;
+  fromState: OkfKnowledgeChangeState | null;
+  reason: string | null;
+}): Promise<void> {
+  const paths = resolveKnowledgeChangePaths(input.homeDir, input.change.projectKey);
+  await mkdir(dirname(paths.historyPath), { recursive: true, mode: 0o700 });
+  const entry: OkfKnowledgeChangeHistoryEntryV1 = {
+    schemaVersion: 1,
+    kind: "okf-knowledge-change-history",
+    changeId: input.change.id,
+    projectKey: input.change.projectKey,
+    operation: input.change.operation,
+    fromState: input.fromState,
+    toState: input.change.state,
+    baseRevision: input.change.base?.revision ?? null,
+    candidateRevision: input.change.candidate.revision,
+    runtimeFields: input.change.diff.runtimeFields,
+    reason: input.reason === null ? null : sanitizeText(input.reason),
+    changedAt: input.change.updatedAt,
+    rawContentStored: false,
+  };
+  await appendFile(paths.historyPath, `${JSON.stringify(entry)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+function resolveKnowledgeChangePaths(homeDir: string, projectKey: string): KnowledgeChangePaths {
+  const safeProjectKey = sanitizePathSegment(projectKey, "project key");
+  const evolutionStateDir = join(resolveEvoDevPaths(homeDir).stateDir, "evolution");
+  const rootDir = join(evolutionStateDir, "knowledge-changes");
+  const projectDir = join(rootDir, safeProjectKey);
+  return {
+    rootDir,
+    projectDir,
+    candidatesDir: join(projectDir, "candidates"),
+    historyPath: join(projectDir, "history.jsonl"),
+    locksDir: join(evolutionStateDir, ".knowledge-review-locks"),
+  };
+}
+
+async function readKnowledgeChangeLockToken(path: string): Promise<string | null> {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8")) as unknown;
+    return isRecord(value) && typeof value.token === "string" ? value.token : null;
+  } catch {
+    return null;
+  }
+}
+
+async function recoverStaleKnowledgeChangeLock(path: string): Promise<boolean> {
+  const [metadata, owner] = await Promise.all([
+    stat(path).catch(() => null),
+    readKnowledgeChangeLockOwner(path),
+  ]);
+  if (metadata === null) return true;
+  const expired = Date.now() - metadata.mtimeMs > KNOWLEDGE_CHANGE_LOCK_STALE_MS;
+  const ownerGone = owner?.pid !== null && owner?.pid !== undefined && !isProcessAlive(owner.pid);
+  const unknownOwnerExpired = owner?.pid === null || owner === null ? expired : false;
+  if (!ownerGone && !unknownOwnerExpired) return false;
+  const quarantinePath = `${path}.stale.${randomUUID()}`;
+  try {
+    await rename(path, quarantinePath);
+  } catch (error) {
+    if (isNotFoundError(error)) return true;
+    throw error;
+  }
+  await rm(quarantinePath, { force: true });
+  return true;
+}
+
+async function readKnowledgeChangeLockOwner(
+  path: string,
+): Promise<{ pid: number | null; token: string | null } | null> {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8")) as unknown;
+    if (!isRecord(value)) return null;
+    return {
+      pid:
+        typeof value.pid === "number" && Number.isSafeInteger(value.pid) && value.pid > 0
+          ? value.pid
+          : null,
+      token: typeof value.token === "string" ? value.token : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isRecord(error) && error.code === "EPERM";
+  }
+}
+
+async function atomicWriteJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await rename(temporaryPath, path);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+
+async function listDirectoryNames(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+async function listJsonFileNames(path: string): Promise<string[]> {
+  try {
+    return (await readdir(path, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNotFoundError(error)) return [];
+    throw error;
+  }
+}
+
+function sanitizePathSegment(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!/^[a-zA-Z0-9._-]+$/u.test(normalized) || normalized === "." || normalized === "..") {
+    throw new Error(`Invalid knowledge change ${label}.`);
+  }
+  return normalized;
+}
+
+function sanitizeChangeId(value: string): string {
+  const normalized = sanitizePathSegment(value, "id");
+  if (!normalized.startsWith("knowledge-change-")) {
+    throw new Error("Invalid knowledge change id.");
+  }
+  return normalized;
+}
+
+function sanitizeTargetPath(value: string): string {
+  const normalized = value.trim().replace(/\\/gu, "/").replace(/^\/+/u, "");
+  if (
+    normalized === "" ||
+    normalized.startsWith("../") ||
+    normalized.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new Error("Invalid knowledge change target path.");
+  }
+  return normalized;
+}
+
+function sanitizeText(value: string): string {
+  return [...value]
+    .filter((character) => {
+      const code = character.charCodeAt(0);
+      return code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127);
+    })
+    .join("")
+    .trim();
+}
+
+function normalizeTimestamp(value: string): string {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) throw new Error("Invalid knowledge change timestamp.");
+  return new Date(time).toISOString();
+}
+
+function createNotFoundError(message: string): Error & { code: "ENOENT" } {
+  return Object.assign(new Error(message), { code: "ENOENT" as const });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    isRecord(error) &&
+    (error.code === "ENOENT" ||
+      (typeof error.message === "string" &&
+        error.message.startsWith("Knowledge change not found:")))
+  );
+}
+
+function isAlreadyExistsError(error: unknown): boolean {
+  return isRecord(error) && error.code === "EEXIST";
+}