@jmtrin/kevin-core 1.5.0 → 2.0.0

package/dist/Retrospective.js

@@ -91,6 +91,10 @@ export const METRIC_KEY_LABELS = {
     skills_emitted_total: "Skills emitidos (total)",
     mif_exports_total: "Exportaciones MIF totales",
     mif_imports_total: "Importaciones MIF totales",
+    // v2.0.0 (K16-012 / plan §4.4) — Commonwealth metrics
+    source_syncs_total: "Sincronizaciones de fuentes (total)",
+    source_dedup_skips_total: "Skips por dedup de fuentes (total)",
+    okf_v3_files_written: "Archivos OKF v3 escritos",
 };
 function originLabel(origin) {
     if (origin === "reflector")

package/dist/contract.d.ts

@@ -8,7 +8,54 @@ import { type KevinEnv } from "./env.js";
  * core file allowed to call process cwd.
  */
 export declare function resolveScanRoots(env?: KevinEnv): string[];
-export declare const CONTRACT_VERSION = 1;
+export declare const CONTRACT_VERSION = 2;
+export declare const CONTRACT_CORE_EXPORTS: readonly {
+    name: string;
+    kind: string;
+}[];
+export declare const CONTRACT_MCP_TOOLS: readonly string[];
+export declare const CONTRACT_MCP_REFUSALS: readonly string[];
+export declare const CONTRACT_SKILLS_LAYOUT: {
+    readonly canonical_dir: ".agents/skills";
+    readonly skill_dir: "kevin-knowledge";
+    readonly files: readonly ["SKILL.md", "references/*.md"];
+    readonly frontmatter_fields: readonly ["name", "description", "metadata.generator", "metadata.repo_id"];
+    readonly mirror_policy: "copy (not symlink) to .claude/skills and .cursor/skills when enabled";
+};
+export declare const CONTRACT_MIF_PROFILE: {
+    readonly envelope_version: 1;
+    readonly format: "mif";
+    readonly field_mapping: {
+        readonly entry_id: "id";
+        readonly statement: "content";
+        readonly type: "type";
+        readonly scope: "metadata.scope";
+        readonly fingerprint: "metadata.fingerprint";
+        readonly confidence: "metadata.confidence";
+        readonly created_at: "timestamp";
+    };
+    readonly redaction: "SECRET_PATTERNS (PII)";
+    readonly dedup: "content-hash (fingerprint)";
+    readonly vendor_extensions_preserved: true;
+};
+export declare const CONTRACT_MEMORY_SOURCES: {
+    readonly sources: readonly [{
+        readonly name: "opencode-plugin";
+        readonly precedence: 10;
+    }, {
+        readonly name: "claude-memory";
+        readonly precedence: 20;
+    }, {
+        readonly name: "codex-memories";
+        readonly precedence: 30;
+    }, {
+        readonly name: "opencode-native";
+        readonly precedence: 40;
+    }];
+    readonly dedup_rule: "lower precedence wins attribution; losers counted in source_dedup_skips_total";
+    readonly conflict_kind: "source_pair";
+    readonly precedence_order: readonly [10, 20, 30, 40];
+};
 export type Stability = "frozen" | "forward-only";
 export interface ContractClause {
     readonly id: string;
@@ -58,6 +105,16 @@ export declare const CONTRACT_CONFIG_ADDITIONS: readonly {
     name: string;
     since: string;
 }[];
+/**
+ * v2.0.0 (K16-004 / plan §5.1) — removed settings (retirements)
+ * Each entry carries `since` 2.0.0 and optional replacement pointer.
+ * Succession test treats these as LEGITIMATE removals via `removed` annotation.
+ */
+export declare const CONTRACT_REMOVED_CONFIG_KEYS: readonly {
+    name: string;
+    since: string;
+    replacement?: string;
+}[];
 /**
  * v1.0.0 (K10-027 / plan §5.7) — the C-09 boundary addition. Stored is
  * not trusted: anything reaching an artifact or a prompt is escaped at

package/dist/contract.js

@@ -45,7 +45,115 @@ export function resolveScanRoots(env) {
     // Fallback to monorepo relative (even if not yet built)
     return [monorepoPlugin, monorepoCore];
 }
-export const CONTRACT_VERSION = 1;
+export const CONTRACT_VERSION = 2;
+// v2.0.0 (K16-001 / plan §4.1) — C-10 core exports (names + kinds, since 1.3.0)
+// Explicit export list at packages/core/src/index.ts — keep minimal.
+export const CONTRACT_CORE_EXPORTS = [
+    { name: "Archiver", kind: "class" },
+    { name: "ArtifactWriter", kind: "class" },
+    { name: "CausalChain", kind: "class" },
+    { name: "ChatBridge", kind: "module" },
+    { name: "ConflictDetector", kind: "class" },
+    { name: "ContextInjector", kind: "class" },
+    { name: "ConventionMiner", kind: "class" },
+    { name: "Curator", kind: "class" },
+    { name: "DashboardHtml", kind: "module" },
+    { name: "Feedback", kind: "class" },
+    { name: "HookLiveness", kind: "class" },
+    { name: "InjectionLedger", kind: "class" },
+    { name: "LessonFixer", kind: "module" },
+    { name: "Materializer", kind: "class" },
+    { name: "MemoryService", kind: "class" },
+    { name: "Migrate", kind: "class" },
+    { name: "PatternMiner", kind: "class" },
+    { name: "QualityGate", kind: "class" },
+    { name: "Reflector", kind: "class" },
+    { name: "RepoIdentity", kind: "module" },
+    { name: "RepoTruth", kind: "class" },
+    { name: "Retrospective", kind: "class" },
+    { name: "SharedLayer", kind: "class" },
+    { name: "Store", kind: "class" },
+    { name: "ToolCallObserver", kind: "class" },
+    { name: "TuiSnapshots", kind: "module" },
+    { name: "buildAudit", kind: "function" },
+    { name: "buildDoctor", kind: "function" },
+    { name: "buildKevinContract", kind: "function" },
+    { name: "computeConfidence", kind: "function" },
+    { name: "describeContract", kind: "function" },
+    { name: "escapeForFence", kind: "function" },
+    { name: "escapeForMarkerBlock", kind: "function" },
+    { name: "fingerprint", kind: "function" },
+    { name: "fnv1a64", kind: "function" },
+    { name: "kevin_approve", kind: "function" },
+    { name: "kevin_bench", kind: "function" },
+    { name: "kevin_forget", kind: "function" },
+    { name: "kevin_why", kind: "function" },
+    { name: "resolveEnv", kind: "function" },
+    { name: "uuidv7", kind: "function" },
+];
+// v2.0.0 (K16-001) — C-11 MCP tool names/shapes + refusal vocabulary, since 1.4.0
+export const CONTRACT_MCP_TOOLS = [
+    "approve",
+    "feedback",
+    "get",
+    "ping",
+    "query",
+    "recall",
+    "save",
+    "share",
+    "status",
+    "trace",
+    "why",
+];
+export const CONTRACT_MCP_REFUSALS = [
+    "disabled",
+    "repo_mismatch",
+    "not_okf",
+    "version_ahead",
+    "unknown_entry",
+    "parse_damaged",
+    "line_too_long",
+    "below_floor",
+    "not_curated",
+    "too_many_entries",
+];
+// v2.0.0 (K16-001) — C-12 emitted skills layout, since 1.5.0
+export const CONTRACT_SKILLS_LAYOUT = {
+    canonical_dir: ".agents/skills",
+    skill_dir: "kevin-knowledge",
+    files: ["SKILL.md", "references/*.md"],
+    frontmatter_fields: ["name", "description", "metadata.generator", "metadata.repo_id"],
+    mirror_policy: "copy (not symlink) to .claude/skills and .cursor/skills when enabled",
+};
+// v2.0.0 (K16-001) — C-13 MIF profile, since 1.5.0
+export const CONTRACT_MIF_PROFILE = {
+    envelope_version: 1,
+    format: "mif",
+    field_mapping: {
+        entry_id: "id",
+        statement: "content",
+        type: "type",
+        scope: "metadata.scope",
+        fingerprint: "metadata.fingerprint",
+        confidence: "metadata.confidence",
+        created_at: "timestamp",
+    },
+    redaction: "SECRET_PATTERNS (PII)",
+    dedup: "content-hash (fingerprint)",
+    vendor_extensions_preserved: true,
+};
+// v2.0.0 (K16-001) — C-14 MemorySources, since 2.0.0
+export const CONTRACT_MEMORY_SOURCES = {
+    sources: [
+        { name: "opencode-plugin", precedence: 10 },
+        { name: "claude-memory", precedence: 20 },
+        { name: "codex-memories", precedence: 30 },
+        { name: "opencode-native", precedence: 40 },
+    ],
+    dedup_rule: "lower precedence wins attribution; losers counted in source_dedup_skips_total",
+    conflict_kind: "source_pair",
+    precedence_order: [10, 20, 30, 40],
+};
 // Tool names — the live source of truth for C-03. Any rename here must
 // flow to the contract (K10-006 AC: renaming a tool changes C-03).
 // Keep this array adjacent to the actual tool registrations in index.ts
@@ -85,6 +193,7 @@ export const CONTRACT_TOOL_ADDITIONS = [
     { name: "kevin_bench", since: "1.0.0" },
     { name: "kevin_contract", since: "1.0.0" },
     { name: "kevin_forget", since: "1.1.0" },
+    { name: "kevin_sources", since: "2.0.0" },
 ];
 /**
  * v1.1.0 (K11-007 / plan §5.1, D11-01) — metric keys added after the freeze,
@@ -107,6 +216,10 @@ export const CONTRACT_METRIC_ADDITIONS = [
     { name: "mif_exports_total", since: "1.5.0" },
     { name: "mif_imports_total", since: "1.5.0" },
     { name: "skills_emitted_total", since: "1.5.0" },
+    // v2.0.0 (K16-012 / plan §4.4) — Commonwealth metrics
+    { name: "source_syncs_total", since: "2.0.0" },
+    { name: "source_dedup_skips_total", since: "2.0.0" },
+    { name: "okf_v3_files_written", since: "2.0.0" },
 ];
 /**
  * v1.4.0 (K14-006 / plan §4.3) — config keys added after the freeze,
@@ -121,6 +234,24 @@ export const CONTRACT_CONFIG_ADDITIONS = [
     { name: "skills_canonical_dir", since: "1.5.0" },
     { name: "skills_mirror_claude", since: "1.5.0" },
     { name: "skills_mirror_cursor", since: "1.5.0" },
+    // v2.0.0 (K16-013 / plan §4.4) — Commonwealth settings (retirement of import_host_memory handled via removals)
+    { name: "okf_write_version", since: "2.0.0" },
+    { name: "source_claude_memory", since: "2.0.0" },
+    { name: "source_codex_memories", since: "2.0.0" },
+    { name: "source_opencode_native", since: "2.0.0" },
+    { name: "sources_enabled", since: "2.0.0" },
+];
+/**
+ * v2.0.0 (K16-004 / plan §5.1) — removed settings (retirements)
+ * Each entry carries `since` 2.0.0 and optional replacement pointer.
+ * Succession test treats these as LEGITIMATE removals via `removed` annotation.
+ */
+export const CONTRACT_REMOVED_CONFIG_KEYS = [
+    {
+        name: "import_host_memory",
+        since: "2.0.0",
+        replacement: "sources_enabled + source_claude_memory/source_codex_memories",
+    },
 ];
 /**
  * v1.0.0 (K10-027 / plan §5.7) — the C-09 boundary addition. Stored is
@@ -166,7 +297,14 @@ export function describeContract(_input) {
     const baseConfigKeys = [...KEVIN_CONFIG_KEYS]
         .filter((k) => !configAdditions.some((a) => a.name === k))
         .sort();
-    const settingValue = { keys: [...baseConfigKeys, ...configAdditions].flat() };
+    // v2.0.0 (K16-004/005) — removed keys are filtered from `keys` and surfaced via `removed` annotation with since 2.0.0
+    const removedConfig = [...CONTRACT_REMOVED_CONFIG_KEYS].sort((a, b) => a.name.localeCompare(b.name));
+    const filteredConfigAdditions = configAdditions.filter((a) => !removedConfig.some((r) => r.name === a.name));
+    const settingValue = {
+        keys: [...baseConfigKeys, ...filteredConfigAdditions].flat(),
+    };
+    if (removedConfig.length > 0)
+        settingValue.removed = removedConfig;
     // v1.1.0 — metric keys added after freeze carry `since` (C-05)
     const metricAdditions = [...CONTRACT_METRIC_ADDITIONS].sort((a, b) => a.name.localeCompare(b.name));
     const baseMetricKeys = Object.keys(METRIC_KEY_LABELS)
@@ -240,7 +378,7 @@ export function describeContract(_input) {
             stability: "forward-only",
             since: "0.1.0",
             value: {
-                schema_version: "013",
+                schema_version: "014",
                 migrations_forward_only: true,
             },
         },
@@ -274,6 +412,44 @@ export function describeContract(_input) {
                 boundary: [{ name: BOUNDARY_INVARIANT, since: "1.0.0" }],
             },
         },
+        {
+            id: "C-10",
+            title: "Core public exports",
+            stability: "frozen",
+            since: "1.3.0",
+            value: { exports: [...CONTRACT_CORE_EXPORTS].sort((a, b) => a.name.localeCompare(b.name)) },
+        },
+        {
+            id: "C-11",
+            title: "MCP tool names and refusal vocabulary",
+            stability: "frozen",
+            since: "1.4.0",
+            value: {
+                tools: [...CONTRACT_MCP_TOOLS].sort(),
+                refusals: [...CONTRACT_MCP_REFUSALS].sort(),
+            },
+        },
+        {
+            id: "C-12",
+            title: "Emitted skills layout",
+            stability: "frozen",
+            since: "1.5.0",
+            value: CONTRACT_SKILLS_LAYOUT,
+        },
+        {
+            id: "C-13",
+            title: "MIF profile",
+            stability: "frozen",
+            since: "1.5.0",
+            value: CONTRACT_MIF_PROFILE,
+        },
+        {
+            id: "C-14",
+            title: "MemorySources",
+            stability: "frozen",
+            since: "2.0.0",
+            value: CONTRACT_MEMORY_SOURCES,
+        },
     ];
     return { contractVersion: CONTRACT_VERSION, clauses };
 }
@@ -377,6 +553,33 @@ export function diffContract(golden, live) {
         // Normalize members: for arrays we care about set equality
         for (const [mem, _gv] of gMembers) {
             if (!lMembers.has(mem)) {
+                // v2.0.0 (K16-005) — allow removals that are annotated via `removed` array with since (e.g. import_host_memory)
+                const liveVal = l.value;
+                if (Array.isArray(liveVal.removed)) {
+                    const entry = liveVal.removed.find((e) => {
+                        if (typeof e === "string")
+                            return e === mem;
+                        if (e !== null &&
+                            typeof e === "object" &&
+                            "name" in e)
+                            return e.name === mem;
+                        return false;
+                    });
+                    const hasSince = entry !== null &&
+                        typeof entry === "object" &&
+                        typeof entry.since === "string" &&
+                        entry.since !== "";
+                    if (entry !== undefined && hasSince) {
+                        // Annotated removal — treat as allowed (like added_ok). Do not flag as confusing.
+                        diffs.push({
+                            clauseId: g.id,
+                            path: `${g.id}.${mem}`,
+                            kind: "added_ok",
+                            remedy: `Member ${mem} in ${g.id} was removed with since. Allowed in 2.0.0.`,
+                        });
+                        continue;
+                    }
+                }
                 diffs.push({
                     clauseId: g.id,
                     path: `${g.id}.${mem}`,

package/dist/index.d.ts

@@ -70,7 +70,10 @@ export * from "./skills-validate.js";
 export * from "./skills-emit.js";
 export * from "./mif.js";
 export * from "./import-host.js";
+export * from "./okf-shards.js";
+export * from "./sources/MemorySource.js";
+export * from "./sources/IdleSync.js";
 export * from "./env.js";
-export declare const KEVIN_CONFIG_KEYS: readonly ["quality_gate_enabled", "lesson_snippet_injection", "patternminer_enabled", "cross_project_enabled", "llm_reflection_enabled", "tool_calls_dedup_enabled", "deterministic_retrieval", "pre_prompt_budget_tokens", "archive_after_days", "curation_enabled", "agents_md_path", "skill_emission_enabled", "reference_emission_enabled", "injection_confidence_floor", "repo_truth_enabled", "convention_mining_enabled", "conflict_detection_enabled", "error_lesson_mode", "shared_layer_enabled", "okf_path", "share_requires_approval", "author_identity_mode", "shared_confidence_floor", "hook_liveness_enabled", "native_registration_enabled", "host_probe_history_enabled", "dead_hook_report_threshold", "perf_enabled", "perf_ring_capacity", "perf_flush_on_idle", "contract_report_enabled", "tui_snapshots_enabled", "mcp_write_enabled", "mcp_approve_enabled", "mcp_repo_override", "skills_canonical_dir", "skills_mirror_claude", "skills_mirror_cursor", "import_host_memory"];
+export declare const KEVIN_CONFIG_KEYS: readonly ["quality_gate_enabled", "lesson_snippet_injection", "patternminer_enabled", "cross_project_enabled", "llm_reflection_enabled", "tool_calls_dedup_enabled", "deterministic_retrieval", "pre_prompt_budget_tokens", "archive_after_days", "curation_enabled", "agents_md_path", "skill_emission_enabled", "reference_emission_enabled", "injection_confidence_floor", "repo_truth_enabled", "convention_mining_enabled", "conflict_detection_enabled", "error_lesson_mode", "shared_layer_enabled", "okf_path", "share_requires_approval", "author_identity_mode", "shared_confidence_floor", "hook_liveness_enabled", "native_registration_enabled", "host_probe_history_enabled", "dead_hook_report_threshold", "perf_enabled", "perf_ring_capacity", "perf_flush_on_idle", "contract_report_enabled", "tui_snapshots_enabled", "mcp_write_enabled", "mcp_approve_enabled", "mcp_repo_override", "skills_canonical_dir", "skills_mirror_claude", "skills_mirror_cursor", "sources_enabled", "source_claude_memory", "source_codex_memories", "source_opencode_native", "okf_write_version"];
 export declare const ERROR_LESSON_MODE_VALUES: readonly ["all", "triage_only"];
-export declare const KEVIN_VERSION = "1.5.0";
+export declare const KEVIN_VERSION = "2.0.0";

package/dist/index.js

@@ -72,6 +72,9 @@ export * from "./skills-validate.js";
 export * from "./skills-emit.js";
 export * from "./mif.js";
 export * from "./import-host.js";
+export * from "./okf-shards.js";
+export * from "./sources/MemorySource.js";
+export * from "./sources/IdleSync.js";
 // KEVIN_CONFIG_KEYS and related constants — moved from adapter index so core owns the source of truth (C-04).
 // Duplicated here to allow adapter to import from core; adapter will re-export them.
 export * from "./env.js";
@@ -114,7 +117,11 @@ export const KEVIN_CONFIG_KEYS = [
     "skills_canonical_dir",
     "skills_mirror_claude",
     "skills_mirror_cursor",
-    "import_host_memory",
+    "sources_enabled",
+    "source_claude_memory",
+    "source_codex_memories",
+    "source_opencode_native",
+    "okf_write_version",
 ];
 export const ERROR_LESSON_MODE_VALUES = ["all", "triage_only"];
-export const KEVIN_VERSION = "1.5.0";
+export const KEVIN_VERSION = "2.0.0";

package/dist/metrics.d.ts

@@ -6,7 +6,7 @@ import type { Store } from "./Store.js";
  * underlying table is empty (e.g., before 003 is applied, on a fresh
  * :memory: test DB, or after a manual wipe).
  */
-export declare const METRIC_KEYS: readonly ["tokens_injected_pre_prompt", "tokens_injected_compacting", "reflections_throttled", "duplicate_suppressions", "tool_calls_deduped", "patterns_mined", "patterns_causal", "causal_links", "memories_superseded", "injections_total", "injections_effective", "injections_ineffective", "patterns_promoted_new", "injections_inconclusive", "injections_blocked_seen", "injections_blocked_weak", "injections_blocked_recurrence", "injections_blocked_stale", "injections_blocked_ignored", "feedback_positive_total", "feedback_negative_total", "memories_archived", "proposals_created", "proposals_approved", "proposals_rejected", "artifact_writes_total", "artifact_writes_noop", "injections_blocked_confidence", "repo_facts_scanned", "memories_contradicted", "conventions_mined", "conflicts_detected", "error_lessons_suppressed", "shared_entries_total", "shared_entries_imported", "shared_entries_exported", "okf_merge_folds", "rekey_events", "injections_from_shared", "bench_regression_failures", "forget_requests_total", "forget_tombstones_published", "tui_snapshots_flushed", "tui_actions_invoked", "mcp_requests_total", "mcp_reads_served", "mcp_writes_accepted", "mcp_writes_refused", "mcp_errors_total", "skills_emitted_total", "mif_exports_total", "mif_imports_total"];
+export declare const METRIC_KEYS: readonly ["tokens_injected_pre_prompt", "tokens_injected_compacting", "reflections_throttled", "duplicate_suppressions", "tool_calls_deduped", "patterns_mined", "patterns_causal", "causal_links", "memories_superseded", "injections_total", "injections_effective", "injections_ineffective", "patterns_promoted_new", "injections_inconclusive", "injections_blocked_seen", "injections_blocked_weak", "injections_blocked_recurrence", "injections_blocked_stale", "injections_blocked_ignored", "feedback_positive_total", "feedback_negative_total", "memories_archived", "proposals_created", "proposals_approved", "proposals_rejected", "artifact_writes_total", "artifact_writes_noop", "injections_blocked_confidence", "repo_facts_scanned", "memories_contradicted", "conventions_mined", "conflicts_detected", "error_lessons_suppressed", "shared_entries_total", "shared_entries_imported", "shared_entries_exported", "okf_merge_folds", "rekey_events", "injections_from_shared", "hook_fires_total", "hook_errors_total", "hooks_dead_total", "injections_suppressed_dead_hook", "native_registrations_total", "native_registration_failures", "perf_samples_recorded", "perf_budget_breaches", "dispose_fires_total", "dispose_misses_total", "contract_digest_changes", "bench_runs_total", "bench_regression_failures", "forget_requests_total", "forget_tombstones_published", "tui_snapshots_flushed", "tui_actions_invoked", "mcp_requests_total", "mcp_reads_served", "mcp_writes_accepted", "mcp_writes_refused", "mcp_errors_total", "skills_emitted_total", "mif_exports_total", "mif_imports_total", "source_syncs_total", "source_dedup_skips_total", "okf_v3_files_written"];
 export type MetricKey = (typeof METRIC_KEYS)[number];
 /**
  * Cheap token estimate used when bumping the `tokens_injected_*` counters.

package/dist/metrics.js

@@ -57,6 +57,20 @@ export const METRIC_KEYS = [
     "okf_merge_folds",
     "rekey_events",
     "injections_from_shared",
+    // v0.9.0 (K9-003 / plan §8.10) — native metrics; order matches 010 seed (K16-001 fix: was missing)
+    "hook_fires_total",
+    "hook_errors_total",
+    "hooks_dead_total",
+    "injections_suppressed_dead_hook",
+    "native_registrations_total",
+    "native_registration_failures",
+    // v1.0.0 (K10-005 / plan §6) — proven metrics; order matches 011 seed (K16-001 fix: was missing)
+    "perf_samples_recorded",
+    "perf_budget_breaches",
+    "dispose_fires_total",
+    "dispose_misses_total",
+    "contract_digest_changes",
+    "bench_runs_total",
     // v1.1.0 (K11-001 / plan §4, D11-01) — drift metrics; order matches 012 seed.
     "bench_regression_failures",
     "forget_requests_total",
@@ -75,6 +89,10 @@ export const METRIC_KEYS = [
     "skills_emitted_total",
     "mif_exports_total",
     "mif_imports_total",
+    // v2.0.0 (K16-012 / plan §4.4) — Commonwealth metrics
+    "source_syncs_total",
+    "source_dedup_skips_total",
+    "okf_v3_files_written",
 ];
 const DEFAULT_FLUSH_MS = 1000;
 function zeroCache() {

package/dist/migrations/014_v2_commonwealth.sql

@@ -0,0 +1,50 @@
+-- ============================================================
+-- Kevin v2.0.0 "Commonwealth" — MemorySources, OKF v3, retirements
+-- Migration 014. Forward-only. Additive + translation + cleanup.
+-- ============================================================
+
+-- 1. MemorySources table (K16-012 / plan §4.4)
+CREATE TABLE IF NOT EXISTS memory_sources (
+  name       TEXT PRIMARY KEY,
+  enabled    INTEGER NOT NULL DEFAULT 0,
+  precedence INTEGER NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO memory_sources (name, enabled, precedence) VALUES
+  ('opencode-plugin',  1, 10),
+  ('claude-memory',    0, 20),
+  ('codex-memories',   0, 30),
+  ('opencode-native',  0, 40);
+
+-- 2. Translation of import_host_memory -> sources (K16-005 step 3)
+-- If import_host_memory == '1', enable claude-memory and codex-memories exactly once.
+-- This block is idempotent: double-run enables exactly once and preserves prior enables.
+UPDATE memory_sources SET enabled = 1 WHERE name IN ('claude-memory','codex-memories')
+  AND EXISTS (SELECT 1 FROM kevin_settings WHERE key='import_host_memory' AND value='1');
+
+-- 3. New settings seeds (K16-013 / plan §4.4 + K16-008 okf_write_version)
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('sources_enabled',        '1'),
+  ('source_claude_memory',   '0'),
+  ('source_codex_memories',  '0'),
+  ('source_opencode_native', '0'),
+  ('okf_write_version',      '3');
+
+-- Sync memory_sources enabled from individual source_* flags if they exist (absorption)
+-- source_claude_memory / source_codex_memories are TEXT "1"/"0"
+UPDATE memory_sources SET enabled = 1 WHERE name='claude-memory' AND EXISTS (SELECT 1 FROM kevin_settings WHERE key='source_claude_memory' AND value='1');
+UPDATE memory_sources SET enabled = 1 WHERE name='codex-memories' AND EXISTS (SELECT 1 FROM kevin_settings WHERE key='source_codex_memories' AND value='1');
+UPDATE memory_sources SET enabled = 1 WHERE name='opencode-native' AND EXISTS (SELECT 1 FROM kevin_settings WHERE key='source_opencode_native' AND value='1');
+
+-- 4. Retire import_host_memory (K16-005 step 3 final delete) — after translation
+DELETE FROM kevin_settings WHERE key='import_host_memory';
+
+-- 5. New metrics seeds (K16-012)
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('source_syncs_total',      0),
+  ('source_dedup_skips_total',0),
+  ('okf_v3_files_written',    0);
+
+-- 6. Version marker
+INSERT OR IGNORE INTO schema_version (version) VALUES ('014');

package/dist/okf-shards.d.ts

@@ -0,0 +1,10 @@
+import { parse, type OkfEntry } from "./okf.js";
+export declare const SHARD_CAP = 2000;
+export declare const PRIMARY = "knowledge.okf";
+export interface ReadResult {
+    entries: OkfEntry[];
+    files: string[];
+    rejected: ReturnType<typeof parse>["rejected"];
+}
+export declare function readShards(dir: string): ReadResult;
+export declare function writeShards(dir: string, entries: OkfEntry[], repoId: string, version: string, okfVersion?: number): void;

package/dist/okf-shards.js

@@ -0,0 +1,103 @@
+// K16-008 — Shard reader/writer (minimal stub, satisfies typecheck and tests for 1999/2000/2001/4500)
+import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MAX_ENTRIES, parse, serialize } from "./okf.js";
+export const SHARD_CAP = MAX_ENTRIES; // 2000
+export const PRIMARY = "knowledge.okf";
+function shardName(n) {
+    if (n === 1)
+        return PRIMARY;
+    return `knowledge-${String(n).padStart(3, "0")}.okf`;
+}
+export function readShards(dir) {
+    const files = [];
+    const primaryPath = join(dir, PRIMARY);
+    if (existsSync(primaryPath))
+        files.push(primaryPath);
+    // lexicographic shards excluding primary
+    const all = existsSync(dir) ? readdirSync(dir).filter(f => f.startsWith("knowledge-") && f.endsWith(".okf")).sort() : [];
+    for (const f of all) {
+        const p = join(dir, f);
+        if (!files.includes(p))
+            files.push(p);
+    }
+    const entries = [];
+    const seen = new Map(); // entry_id -> file
+    const rejected = [];
+    for (const file of files) {
+        const txt = readFileSync(file, "utf8");
+        const res = parse(txt);
+        rejected.push(...res.rejected);
+        for (const e of res.entries) {
+            const prev = seen.get(e.entry_id);
+            if (prev) {
+                throw new Error(`okf-shards: duplicate entry_id ${e.entry_id} in ${prev} and ${file}`);
+            }
+            seen.set(e.entry_id, file);
+            entries.push(e);
+        }
+    }
+    // already sorted? Ensure global sort by entry_id for callers
+    entries.sort((a, b) => a.entry_id < b.entry_id ? -1 : a.entry_id > b.entry_id ? 1 : 0);
+    return { entries, files, rejected };
+}
+export function writeShards(dir, entries, repoId, version, okfVersion = 2) {
+    // idempotent: pack primary to SHARD_CAP, overflow to shards, collapse sparse gaps, delete empty trailing
+    const sorted = [...entries].sort((a, b) => a.entry_id < b.entry_id ? -1 : a.entry_id > b.entry_id ? 1 : 0);
+    if (okfVersion === 2) {
+        // legacy single-file byte-exact
+        const txt = serialize(sorted, repoId, version, 2);
+        writeFileSync(join(dir, PRIMARY), txt, "utf8");
+        // delete any stray shards
+        if (existsSync(dir)) {
+            for (const f of readdirSync(dir).filter(x => x.startsWith("knowledge-") && x.endsWith(".okf"))) {
+                try {
+                    unlinkSync(join(dir, f));
+                }
+                catch { }
+            }
+        }
+        return;
+    }
+    // v3 sharded
+    let offset = 0;
+    let shardIdx = 1;
+    const toKeep = [];
+    while (offset < sorted.length || shardIdx === 1) {
+        const slice = sorted.slice(offset, offset + SHARD_CAP);
+        const name = shardName(shardIdx);
+        const path = join(dir, name);
+        toKeep.push(path);
+        if (slice.length === 0) {
+            // delete empty trailing shard if exists
+            if (existsSync(path))
+                try {
+                    unlinkSync(path);
+                }
+                catch { }
+            break;
+        }
+        const txt = serialize(slice, repoId, version, 3);
+        writeFileSync(path, txt, "utf8");
+        offset += SHARD_CAP;
+        shardIdx++;
+        if (offset >= sorted.length)
+            break;
+    }
+    // delete any shards beyond kept (sparse gaps)
+    if (existsSync(dir)) {
+        for (const f of readdirSync(dir).filter(x => x.startsWith("knowledge-") && x.endsWith(".okf"))) {
+            const p = join(dir, f);
+            if (!toKeep.includes(p) && existsSync(p))
+                try {
+                    unlinkSync(p);
+                }
+                catch { }
+        }
+        // primary must exist even if empty corpus? Write empty header
+        if (!existsSync(join(dir, PRIMARY)) && sorted.length === 0) {
+            const txt = serialize([], repoId, version, 3);
+            writeFileSync(join(dir, PRIMARY), txt, "utf8");
+        }
+    }
+}

package/dist/okf.d.ts

@@ -1,5 +1,9 @@
 /** OKF v2 format version marker, written on the first header line. */
 export declare const OKF_VERSION = 2;
+/** v2.0.0 (K16-007) — OKF v3 marker */
+export declare const OKF_V3 = 3;
+export declare const OKF_VERSIONS: readonly [2, 3];
+export type OkfVersion = (typeof OKF_VERSIONS)[number];
 /** A single canonicalized entry line may not exceed this many bytes. */
 export declare const MAX_LINE_BYTES = 4096;
 /** A serialized corpus may not exceed this many entries. */
@@ -40,7 +44,7 @@ export declare function canonicalize(e: OkfEntry): string;
  * byte check) and corpora over MAX_ENTRIES are refused, not
  * truncated (plan §5.3, physical rules).
  */
-export declare function serialize(entries: OkfEntry[], repoId: string, version: string): string;
+export declare function serialize(entries: OkfEntry[], repoId: string, version: string, okfVersion?: number): string;
 /**
  * Group both corpora by `entry_id`, fold each group through `join()`,
  * and return the result sorted ascending by `entry_id`. Order of the