oh-my-llmwikimode 1.0.0

package/src/curator/queue.js

@@ -0,0 +1,324 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { parseFrontmatter } from "../wiki/store.js";
+import { scoreConsolidationProposal, scoreLessonCandidate } from "./scoring.js";
+import {
+  CURATOR_REVIEW_STATUS,
+  DEFAULT_BUILT_AT,
+  normalizeCuratorPath,
+  validateAuditRecord,
+  validateConsolidationProposal,
+  validateCuratorQueueCard,
+  validateLessonCandidateArtifact,
+} from "./schema.js";
+
+const ENTRY_PREFIXES = ["inbox/", "problems/", "editorial/lessons/"];
+
+function nowIso(options = {}) {
+  return options.now || new Date().toISOString();
+}
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function atomicWriteJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpFile = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpFile, filePath);
+}
+
+function safeId(value, fallback = "curator") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+function shortHash(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, 12);
+}
+
+function contentHash(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function isInsideDirectory(parentDirectory, candidatePath) {
+  const relativePath = path.relative(parentDirectory, candidatePath);
+  return relativePath !== "" && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+}
+
+function normalizeQueue(queue) {
+  const cards = [];
+  for (const card of Array.isArray(queue?.cards) ? queue.cards : []) {
+    const validation = validateCuratorQueueCard(card);
+    if (validation.valid) cards.push(validation.value);
+  }
+  return {
+    version: 1,
+    cards: [...new Map(cards.map((card) => [card.id, card])).values()]
+      .sort((left, right) => compareStrings(`${left.created_at}:${left.id}`, `${right.created_at}:${right.id}`)),
+    meta: { built_at: queue?.meta?.built_at || DEFAULT_BUILT_AT },
+  };
+}
+
+function createEmptyQueue() {
+  return { version: 1, cards: [], meta: { built_at: DEFAULT_BUILT_AT } };
+}
+
+function writeQueue(wikiRoot, queue, options = {}) {
+  const normalized = normalizeQueue({ ...queue, meta: { built_at: nowIso(options) } });
+  atomicWriteJson(getCuratorPaths(wikiRoot).queueFile, normalized);
+  return normalized;
+}
+
+function result(success, payload = {}) {
+  return { success, ...payload };
+}
+
+function resolveEntry(wikiRoot, entryPath) {
+  const normalizedPath = normalizeCuratorPath(entryPath, "entry path");
+  if (!normalizedPath.endsWith(".md")) return result(false, { error: "Only Markdown wiki entries are supported" });
+  if (!ENTRY_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix))) {
+    return result(false, { error: "Entry must be under inbox/, problems/, or editorial/lessons/" });
+  }
+
+  const rootPath = path.resolve(wikiRoot);
+  const fullPath = path.resolve(rootPath, normalizedPath);
+  if (!isInsideDirectory(rootPath, fullPath)) return result(false, { error: "Entry path escapes wiki root" });
+  if (!fs.existsSync(fullPath)) return result(false, { error: `Entry not found: ${normalizedPath}` });
+  if (fs.lstatSync(fullPath).isSymbolicLink()) return result(false, { error: "Symbolic link entries are not supported" });
+  const realRoot = fs.realpathSync(rootPath);
+  const realFullPath = fs.realpathSync(fullPath);
+  if (!isInsideDirectory(realRoot, realFullPath)) return result(false, { error: "Entry path resolves outside wiki root" });
+
+  return result(true, { path: normalizedPath, fullPath });
+}
+
+function readEntryRef(wikiRoot, entryPath) {
+  const resolved = resolveEntry(wikiRoot, entryPath);
+  if (!resolved.success) return resolved;
+  const content = fs.readFileSync(resolved.fullPath, "utf-8");
+  const { frontmatter } = parseFrontmatter(content);
+  return result(true, {
+    ref: {
+      path: resolved.path,
+      title: frontmatter.title || path.basename(resolved.path, ".md"),
+      status: frontmatter.status || "candidate",
+      source: frontmatter.source || "manual",
+      tags: Array.isArray(frontmatter.tags) ? frontmatter.tags : typeof frontmatter.tags === "string" ? [frontmatter.tags] : [],
+      summary: frontmatter.summary || frontmatter.title || "",
+      created_at: frontmatter.created_at || "",
+      updated_at: frontmatter.updated_at || frontmatter.created_at || "",
+      seen_count: frontmatter.seen_count || 0,
+      backlink_count: frontmatter.backlink_count || 0,
+      confidence_score: typeof frontmatter.confidence_score === "number" ? frontmatter.confidence_score : 1,
+      content_sha256: contentHash(content),
+    },
+  });
+}
+
+function readEntryRefs(wikiRoot, entryPaths) {
+  const refs = [];
+  for (const entryPath of [...new Set(entryPaths)].sort(compareStrings)) {
+    const readResult = readEntryRef(wikiRoot, entryPath);
+    if (!readResult.success) return readResult;
+    refs.push(readResult.ref);
+  }
+  return result(true, { refs });
+}
+
+function appendAudit(wikiRoot, action, entry = {}, options = {}) {
+  const validation = validateAuditRecord({
+    timestamp: nowIso(options),
+    action,
+    actor: options.actor || "system",
+    executed: false,
+    ...entry,
+  });
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const paths = getCuratorPaths(wikiRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  fs.appendFileSync(paths.auditFile, `${JSON.stringify(validation.value)}\n`);
+  return result(true, { audit: validation.value });
+}
+
+function upsertCard(wikiRoot, card, options = {}) {
+  const validation = validateCuratorQueueCard(card);
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const queue = readCuratorQueue(wikiRoot);
+  queue.cards = [...queue.cards.filter((item) => item.id !== validation.value.id), validation.value];
+  return result(true, { queue: writeQueue(wikiRoot, queue, options), card: validation.value });
+}
+
+export function getCuratorPaths(wikiRoot) {
+  const systemDir = path.join(wikiRoot, ".system");
+  const root = path.join(systemDir, "curator");
+  return {
+    systemDir,
+    root,
+    queueFile: path.join(root, "queue.json"),
+    candidatesDir: path.join(root, "lesson-candidates"),
+    proposalsDir: path.join(root, "consolidation-proposals"),
+    auditFile: path.join(root, "audit.jsonl"),
+  };
+}
+
+export function ensureCuratorStructure(wikiRoot) {
+  const paths = getCuratorPaths(wikiRoot);
+  fs.mkdirSync(paths.candidatesDir, { recursive: true });
+  fs.mkdirSync(paths.proposalsDir, { recursive: true });
+  return paths;
+}
+
+export function readCuratorQueue(wikiRoot) {
+  const paths = getCuratorPaths(wikiRoot);
+  if (!fs.existsSync(paths.queueFile)) return createEmptyQueue();
+  try {
+    return normalizeQueue(JSON.parse(fs.readFileSync(paths.queueFile, "utf-8")));
+  } catch {
+    return createEmptyQueue();
+  }
+}
+
+export function suggestLessonCandidate(wikiRoot, request = {}, options = {}) {
+  try {
+    const source = request.source || request.source_path || request.sourcePath;
+    if (!source) return result(false, { error: "suggest-lesson requires --source" });
+    const sourceResult = readEntryRef(wikiRoot, source);
+    if (!sourceResult.success) return sourceResult;
+    const relatedPaths = Array.isArray(request.related) ? request.related : typeof request.related === "string" ? [request.related] : [];
+    const relatedResult = readEntryRefs(wikiRoot, relatedPaths);
+    if (!relatedResult.success) return relatedResult;
+
+    const createdAt = nowIso(options);
+    const title = request.title || `${sourceResult.ref.title} Lesson`;
+    const id = `candidate-${safeId(title, "lesson")}-${shortHash([sourceResult.ref.path, ...relatedResult.refs.map((ref) => ref.path), title].join("|"))}`;
+    const scoringHints = scoreLessonCandidate({ source_refs: [sourceResult.ref], related_refs: relatedResult.refs }, { now: createdAt });
+    const candidateValidation = validateLessonCandidateArtifact({
+      id,
+      title,
+      status: CURATOR_REVIEW_STATUS,
+      source_refs: [sourceResult.ref],
+      related_refs: relatedResult.refs,
+      scoring_hints: scoringHints,
+      proposed_lesson: {
+        title,
+        tags: [...new Set([...sourceResult.ref.tags, ...relatedResult.refs.flatMap((ref) => ref.tags), "lesson-candidate"])].sort(compareStrings),
+        evidence_paths: [sourceResult.ref.path, ...relatedResult.refs.map((ref) => ref.path)],
+        reviewer_note: "Review this local artifact before promoting any lesson.",
+      },
+      boundaries: { executed: false, auto_promote: false, auto_merge: false, auto_delete: false },
+      created_at: createdAt,
+      updated_at: createdAt,
+    });
+    if (!candidateValidation.valid) return result(false, { error: candidateValidation.errors.join("; ") });
+
+    const paths = ensureCuratorStructure(wikiRoot);
+    const fileName = `${safeId(id)}.json`;
+    const filePath = path.join(paths.candidatesDir, fileName);
+    const relativePath = `.system/curator/lesson-candidates/${fileName}`;
+    atomicWriteJson(filePath, candidateValidation.value);
+
+    const sourcePaths = [sourceResult.ref.path, ...relatedResult.refs.map((ref) => ref.path)].sort(compareStrings);
+    const cardResult = upsertCard(wikiRoot, {
+      id: `card-${id}`,
+      kind: "lesson_candidate",
+      title,
+      status: CURATOR_REVIEW_STATUS,
+      artifact_path: relativePath,
+      source_paths: sourcePaths,
+      scoring_hints: scoringHints,
+      created_at: createdAt,
+      updated_at: createdAt,
+    }, options);
+    if (!cardResult.success) return cardResult;
+
+    const auditResult = appendAudit(wikiRoot, "suggest_lesson", {
+      subject_id: id,
+      artifact_path: relativePath,
+      source_paths: sourcePaths,
+    }, options);
+    if (!auditResult.success) return auditResult;
+
+    return result(true, {
+      candidate: candidateValidation.value,
+      queue_card: cardResult.card,
+      audit: auditResult.audit,
+      path: relativePath,
+      executed: false,
+      promoted: false,
+      message: `Lesson candidate artifact created: ${relativePath}`,
+    });
+  } catch (error) {
+    return result(false, { error: error.message });
+  }
+}
+
+export function proposeConsolidation(wikiRoot, request = {}, options = {}) {
+  try {
+    const entries = Array.isArray(request.entries) ? request.entries : typeof request.entries === "string" ? [request.entries] : [];
+    if (entries.length < 2) return result(false, { error: "propose-consolidation requires at least two entries" });
+    const refsResult = readEntryRefs(wikiRoot, entries);
+    if (!refsResult.success) return refsResult;
+    const createdAt = nowIso(options);
+    const title = request.title || `Consolidate ${refsResult.refs.length} wiki entries`;
+    const id = `proposal-${safeId(title, "consolidation")}-${shortHash(refsResult.refs.map((ref) => ref.path).join("|"))}`;
+    const scoringHints = scoreConsolidationProposal({ entry_refs: refsResult.refs }, { now: createdAt });
+    const proposalValidation = validateConsolidationProposal({
+      id,
+      title,
+      status: CURATOR_REVIEW_STATUS,
+      entry_refs: refsResult.refs,
+      rationale: request.rationale || "Reviewer should decide whether these entries should be consolidated.",
+      scoring_hints: scoringHints,
+      boundaries: { executed: false, auto_promote: false, auto_merge: false, auto_delete: false },
+      created_at: createdAt,
+      updated_at: createdAt,
+    });
+    if (!proposalValidation.valid) return result(false, { error: proposalValidation.errors.join("; ") });
+
+    const paths = ensureCuratorStructure(wikiRoot);
+    const fileName = `${safeId(id)}.json`;
+    const filePath = path.join(paths.proposalsDir, fileName);
+    const relativePath = `.system/curator/consolidation-proposals/${fileName}`;
+    atomicWriteJson(filePath, proposalValidation.value);
+    const sourcePaths = refsResult.refs.map((ref) => ref.path).sort(compareStrings);
+
+    const cardResult = upsertCard(wikiRoot, {
+      id: `card-${id}`,
+      kind: "consolidation_proposal",
+      title,
+      status: CURATOR_REVIEW_STATUS,
+      artifact_path: relativePath,
+      source_paths: sourcePaths,
+      scoring_hints: scoringHints,
+      created_at: createdAt,
+      updated_at: createdAt,
+    }, options);
+    if (!cardResult.success) return cardResult;
+
+    const auditResult = appendAudit(wikiRoot, "propose_consolidation", {
+      subject_id: id,
+      artifact_path: relativePath,
+      source_paths: sourcePaths,
+    }, options);
+    if (!auditResult.success) return auditResult;
+
+    return result(true, {
+      proposal: proposalValidation.value,
+      queue_card: cardResult.card,
+      audit: auditResult.audit,
+      path: relativePath,
+      executed: false,
+      merged: false,
+      deleted: false,
+      message: `Consolidation proposal artifact created: ${relativePath}`,
+    });
+  } catch (error) {
+    return result(false, { error: error.message });
+  }
+}

package/src/curator/schema.js

@@ -0,0 +1,237 @@
+import { redactSecrets } from "../security.js";
+
+export const CURATOR_REVIEW_STATUS = "review_required";
+export const CURATOR_CARD_KINDS = ["lesson_candidate", "consolidation_proposal"];
+export const DEFAULT_BUILT_AT = "1970-01-01T00:00:00.000Z";
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function normalizeScalar(value, maxLength = 500) {
+  return redactSecrets(String(value ?? "")
+    .replace(/\r?\n/g, " ")
+    .replace(/\s+/g, " ")
+    .trim())
+    .slice(0, maxLength);
+}
+
+function normalizeId(value, label = "id") {
+  const id = normalizeScalar(value, 120).toLowerCase();
+  if (!/^[a-z0-9][a-z0-9_-]{0,119}$/.test(id)) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+  return id;
+}
+
+function normalizeStringList(value, maxLength = 120) {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+  return [...new Set(values.map((item) => normalizeScalar(item, maxLength)).filter(Boolean))]
+    .sort(compareStrings);
+}
+
+function normalizeBooleanFalse(value, label) {
+  if (value === undefined || value === null || value === false) return false;
+  throw new Error(`${label} must remain false`);
+}
+
+function normalizeScore(value, label) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new Error(`Invalid ${label} score`);
+  return Math.max(0, Math.min(1, Math.round(number * 1000) / 1000));
+}
+
+function validationResult(builder) {
+  try {
+    return { valid: true, value: builder(), errors: [] };
+  } catch (error) {
+    return { valid: false, value: null, errors: [error.message] };
+  }
+}
+
+function normalizeReviewStatus(value) {
+  const status = normalizeScalar(value || CURATOR_REVIEW_STATUS, 80).toLowerCase();
+  if (status !== CURATOR_REVIEW_STATUS) {
+    throw new Error(`Curator artifacts must stay ${CURATOR_REVIEW_STATUS}`);
+  }
+  return CURATOR_REVIEW_STATUS;
+}
+
+function normalizeContentHash(value, label) {
+  const hash = normalizeScalar(value, 80).toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(hash)) {
+    throw new Error(`${label} content_sha256 is required`);
+  }
+  return hash;
+}
+
+function normalizeSourceRef(input, label = "source evidence ref", requireHash = true) {
+  if (!isRecord(input)) throw new Error(`${label} must be an object`);
+  const path = normalizeCuratorPath(input.path, `${label} path`);
+  const ref = {
+    path,
+    title: normalizeScalar(input.title || path, 180),
+    status: normalizeScalar(input.status || "candidate", 80).toLowerCase(),
+    source: normalizeScalar(input.source || "manual", 120).toLowerCase(),
+    tags: normalizeStringList(input.tags, 80),
+    summary: normalizeScalar(input.summary, 240),
+    created_at: normalizeScalar(input.created_at || input.createdAt, 80),
+    updated_at: normalizeScalar(input.updated_at || input.updatedAt, 80),
+    seen_count: Number.isFinite(Number(input.seen_count || input.seenCount)) ? Math.max(0, Math.trunc(Number(input.seen_count || input.seenCount))) : 0,
+    backlink_count: Number.isFinite(Number(input.backlink_count || input.backlinkCount)) ? Math.max(0, Math.trunc(Number(input.backlink_count || input.backlinkCount))) : 0,
+    confidence_score: Number.isFinite(Number(input.confidence_score || input.confidenceScore)) ? normalizeScore(Number(input.confidence_score || input.confidenceScore), "confidence") : 1,
+  };
+  const hash = normalizeScalar(input.content_sha256 || input.contentSha256, 80).toLowerCase();
+  if (hash || requireHash) ref.content_sha256 = normalizeContentHash(hash, label);
+  return ref;
+}
+
+function normalizeSourceRefs(value, label = "source evidence refs", requireHash = true) {
+  const refs = Array.isArray(value) ? value : [];
+  return [...new Map(refs.map((ref) => normalizeSourceRef(ref, label.slice(0, -1), requireHash)).map((ref) => [ref.path, ref])).values()]
+    .sort((left, right) => compareStrings(left.path, right.path));
+}
+
+function normalizeProposedLesson(value = {}) {
+  const proposed = isRecord(value) ? value : {};
+  return {
+    title: normalizeScalar(proposed.title, 180),
+    tags: normalizeStringList(proposed.tags, 80),
+    evidence_paths: normalizeStringList(proposed.evidence_paths || proposed.evidencePaths, 240).map((item) => normalizeCuratorPath(item, "evidence path")),
+    reviewer_note: normalizeScalar(proposed.reviewer_note || proposed.reviewerNote, 500),
+  };
+}
+
+function normalizeBoundaries(value = {}) {
+  const boundaries = isRecord(value) ? value : {};
+  return {
+    executed: normalizeBooleanFalse(boundaries.executed, "executed"),
+    auto_promote: normalizeBooleanFalse(boundaries.auto_promote || boundaries.autoPromote, "auto_promote"),
+    auto_merge: normalizeBooleanFalse(boundaries.auto_merge || boundaries.autoMerge, "auto_merge"),
+    auto_delete: normalizeBooleanFalse(boundaries.auto_delete || boundaries.autoDelete, "auto_delete"),
+  };
+}
+
+export function normalizeCuratorPath(value, label = "path", maxLength = 260) {
+  const normalized = normalizeScalar(value, maxLength).replace(/\\/g, "/");
+  if (!normalized) throw new Error(`Unsafe ${label}: path is required`);
+  if (/^[a-z]:\//i.test(normalized) || normalized.startsWith("/") || normalized.startsWith("//")) {
+    throw new Error(`Unsafe ${label}: absolute paths are not allowed`);
+  }
+  if (normalized.split("/").some((segment) => segment === "..")) {
+    throw new Error(`Unsafe ${label}: traversal is not allowed`);
+  }
+  return normalized;
+}
+
+export function validateScoringHints(input) {
+  return validationResult(() => {
+    const hints = isRecord(input) ? input : {};
+    return {
+      importance: normalizeScore(hints.importance ?? 0, "importance"),
+      recency: normalizeScore(hints.recency ?? 0, "recency"),
+      trust: normalizeScore(hints.trust ?? 0, "trust"),
+      review_only: true,
+      review_status: CURATOR_REVIEW_STATUS,
+    };
+  });
+}
+
+export function validateLessonCandidateArtifact(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Lesson candidate artifact must be an object");
+    const sourceRefs = normalizeSourceRefs(input.source_refs || input.sourceRefs, "source evidence refs", true);
+    if (sourceRefs.length === 0) throw new Error("Lesson candidate requires source evidence refs");
+    const scoring = validateScoringHints(input.scoring_hints || input.scoringHints);
+    if (!scoring.valid) throw new Error(scoring.errors.join("; "));
+    const title = normalizeScalar(input.title, 180);
+    if (!title) throw new Error("Lesson candidate title is required");
+    return {
+      version: 1,
+      id: normalizeId(input.id, "lesson candidate id"),
+      type: "lesson_candidate",
+      title,
+      status: normalizeReviewStatus(input.status),
+      review_required: true,
+      source_refs: sourceRefs,
+      related_refs: normalizeSourceRefs(input.related_refs || input.relatedRefs, "related refs", true),
+      scoring_hints: scoring.value,
+      proposed_lesson: normalizeProposedLesson(input.proposed_lesson || input.proposedLesson),
+      boundaries: normalizeBoundaries(input.boundaries),
+      created_at: normalizeScalar(input.created_at || input.createdAt || DEFAULT_BUILT_AT, 80),
+      updated_at: normalizeScalar(input.updated_at || input.updatedAt || DEFAULT_BUILT_AT, 80),
+    };
+  });
+}
+
+export function validateConsolidationProposal(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Consolidation proposal must be an object");
+    const entryRefs = normalizeSourceRefs(input.entry_refs || input.entryRefs, "entry refs", true);
+    if (entryRefs.length < 2) throw new Error("Consolidation proposal requires at least two entry refs");
+    const scoring = validateScoringHints(input.scoring_hints || input.scoringHints);
+    if (!scoring.valid) throw new Error(scoring.errors.join("; "));
+    const title = normalizeScalar(input.title, 180);
+    if (!title) throw new Error("Consolidation proposal title is required");
+    return {
+      version: 1,
+      id: normalizeId(input.id, "consolidation proposal id"),
+      type: "consolidation_proposal",
+      title,
+      status: normalizeReviewStatus(input.status),
+      review_required: true,
+      entry_refs: entryRefs,
+      rationale: normalizeScalar(input.rationale, 1000),
+      scoring_hints: scoring.value,
+      proposed_actions: [{ action: "review_consolidation", requires_human_review: true }],
+      boundaries: normalizeBoundaries(input.boundaries),
+      created_at: normalizeScalar(input.created_at || input.createdAt || DEFAULT_BUILT_AT, 80),
+      updated_at: normalizeScalar(input.updated_at || input.updatedAt || DEFAULT_BUILT_AT, 80),
+    };
+  });
+}
+
+export function validateCuratorQueueCard(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Curator queue card must be an object");
+    const kind = normalizeScalar(input.kind, 80).toLowerCase();
+    if (!CURATOR_CARD_KINDS.includes(kind)) throw new Error(`Invalid curator card kind: ${input.kind}`);
+    const title = normalizeScalar(input.title, 180);
+    if (!title) throw new Error("Curator queue card title is required");
+    const scoring = validateScoringHints(input.scoring_hints || input.scoringHints);
+    if (!scoring.valid) throw new Error(scoring.errors.join("; "));
+    return {
+      id: normalizeId(input.id, "curator queue card id"),
+      kind,
+      title,
+      status: normalizeReviewStatus(input.status),
+      review_required: true,
+      artifact_path: normalizeCuratorPath(input.artifact_path || input.artifactPath, "artifact path"),
+      source_paths: normalizeStringList(input.source_paths || input.sourcePaths, 260).map((item) => normalizeCuratorPath(item, "source path")),
+      scoring_hints: scoring.value,
+      created_at: normalizeScalar(input.created_at || input.createdAt || DEFAULT_BUILT_AT, 80),
+      updated_at: normalizeScalar(input.updated_at || input.updatedAt || DEFAULT_BUILT_AT, 80),
+    };
+  });
+}
+
+export function validateAuditRecord(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Curator audit record must be an object");
+    const action = normalizeScalar(input.action, 80).toLowerCase();
+    if (!action) throw new Error("Curator audit action is required");
+    return {
+      timestamp: normalizeScalar(input.timestamp || DEFAULT_BUILT_AT, 80),
+      action,
+      actor: normalizeScalar(input.actor || "system", 120),
+      subject_id: normalizeId(input.subject_id || input.subjectId, "audit subject id"),
+      artifact_path: normalizeCuratorPath(input.artifact_path || input.artifactPath, "artifact path"),
+      source_paths: normalizeStringList(input.source_paths || input.sourcePaths, 260).map((item) => normalizeCuratorPath(item, "source path")),
+      executed: normalizeBooleanFalse(input.executed, "executed"),
+    };
+  });
+}

package/src/curator/scoring.js

@@ -0,0 +1,83 @@
+import { CURATOR_REVIEW_STATUS } from "./schema.js";
+
+function clamp(value) {
+  return Math.max(0, Math.min(1, value));
+}
+
+function roundScore(value) {
+  return Math.round(clamp(value) * 1000) / 1000;
+}
+
+function toArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function parseDate(value) {
+  const time = Date.parse(String(value || ""));
+  return Number.isFinite(time) ? time : 0;
+}
+
+function newestTimestamp(refs) {
+  return refs.reduce((latest, ref) => Math.max(latest, parseDate(ref.updated_at || ref.updatedAt), parseDate(ref.created_at || ref.createdAt)), 0);
+}
+
+function sourceTrust(ref) {
+  if (Number.isFinite(Number(ref.confidence_score || ref.confidenceScore))) {
+    return clamp(Number(ref.confidence_score || ref.confidenceScore));
+  }
+  const source = String(ref.source || "manual").toLowerCase();
+  if (source === "manual") return 0.8;
+  if (source === "chat.message") return 0.72;
+  if (source === "auto-memory") return 0.68;
+  if (source === "notebooklm") return 0.74;
+  return 0.6;
+}
+
+function average(values, fallback = 0) {
+  const finiteValues = values.filter((value) => Number.isFinite(value));
+  if (finiteValues.length === 0) return fallback;
+  return finiteValues.reduce((sum, value) => sum + value, 0) / finiteValues.length;
+}
+
+function uniqueTagCount(refs) {
+  const tags = new Set();
+  for (const ref of refs) {
+    for (const tag of toArray(ref.tags)) tags.add(String(tag).toLowerCase());
+  }
+  return tags.size;
+}
+
+function scoreRefs(refs, options = {}) {
+  const now = parseDate(options.now) || Date.now();
+  const latest = newestTimestamp(refs);
+  const ageDays = latest > 0 ? Math.max(0, (now - latest) / 86_400_000) : 365;
+  const seenScore = average(refs.map((ref) => Math.min(5, Number(ref.seen_count || ref.seenCount || 0)) / 5));
+  const backlinkScore = average(refs.map((ref) => Math.min(5, Number(ref.backlink_count || ref.backlinkCount || 0)) / 5));
+  const confidence = average(refs.map(sourceTrust), 0.5);
+  const lessonBonus = refs.every((ref) => String(ref.status || "").toLowerCase() === "lesson") ? 0.05 : 0;
+
+  return {
+    importance: roundScore(0.25 + Math.min(0.25, refs.length * 0.08) + Math.min(0.18, uniqueTagCount(refs) * 0.03) + seenScore * 0.18 + backlinkScore * 0.14),
+    recency: roundScore(1 / (1 + ageDays / 30)),
+    trust: roundScore(confidence + lessonBonus),
+    review_only: true,
+    review_status: CURATOR_REVIEW_STATUS,
+  };
+}
+
+export function scoreLessonCandidate(candidate = {}, options = {}) {
+  const refs = [
+    ...toArray(candidate.source_refs || candidate.sourceRefs),
+    ...toArray(candidate.related_refs || candidate.relatedRefs),
+  ];
+  return scoreRefs(refs, options);
+}
+
+export function scoreConsolidationProposal(proposal = {}, options = {}) {
+  const refs = toArray(proposal.entry_refs || proposal.entryRefs);
+  const score = scoreRefs(refs, options);
+  return {
+    ...score,
+    importance: roundScore(score.importance + Math.min(0.15, refs.length * 0.04)),
+  };
+}