@ngockhoale/ukit 3.0.8 → 3.0.10

package/template_project/.claude/ukit/index/route-task.mjs

@@ -26,6 +26,13 @@ import {
   safeTaskId,
   writeResumableRun,
 } from '../runtime/resumable-run.mjs';
+import {
+  POLICY_VERSION as MEMORY_POLICY_VERSION,
+  eligible as memoryRecordEligible,
+  resolveProjectIdentityMirror,
+} from '../runtime/memory-policy.mjs';
+import { resolveRecordFreshness } from '../runtime/memory-freshness.mjs';
+import { resolveMemoryStage } from '../runtime/memory-flags.mjs';
 
 const {
   resolveContext,
@@ -5635,21 +5642,58 @@ async function readDirectoryJsonItems(dirPath) {
   return items.sort((left, right) => left.fileName.localeCompare(right.fileName));
 }
 
-async function detectProjectId(rootDir) {
+// M01-05: project identity is owned by memory-policy.mjs (read-only mirror —
+// never mints, never writes). Legacy project/session items are keyed by the
+// display name, so binding also accepts the alias names (pkg name, basename).
+async function resolveRouteProjectBinding(rootDir) {
+  const identity = await resolveProjectIdentityMirror(rootDir).catch(() => null);
+  const names = new Set();
+  const base = path.basename(rootDir);
+  if (base) names.add(base);
   const pkg = await readJson(path.join(rootDir, 'package.json'), null);
   if (typeof pkg?.name === 'string' && pkg.name.trim()) {
-    return pkg.name.trim();
+    names.add(pkg.name.trim());
   }
+  return {
+    projectId: identity?.projectId ?? null,
+    ambiguous: identity?.ambiguous === true,
+    // Registry-attested aliases only (never raw pkg name) — migrated v1
+    // records carry the legacy name as project_id.
+    aliases: Array.isArray(identity?.aliases) ? identity.aliases : [],
+    names,
+  };
+}
+
+function matchesProjectBinding(item, binding) {
+  const boundId = item.type === 'project' ? item.content?.id : item.content?.projectId;
+  if (boundId == null) return false;
+  if (binding.projectId != null && boundId === binding.projectId) return true;
+  return binding.names.has(boundId);
+}
 
-  return path.basename(rootDir);
+// v2/legacy dedup (M01-05): a record carrying meta.legacyId is the same
+// logical item as `session:<legacyId>`/`project:<legacyId>`; a record whose
+// project_id equals a legacy project item's id is that project's twin. The
+// legacy item wins — it carries the richer structured summary.
+function recordLegacyKey(item) {
+  const record = item.record;
+  if (!record) return null;
+  const legacyId = record.meta?.legacyId;
+  if (typeof legacyId === 'string' && legacyId) {
+    return `session:${legacyId}`;
+  }
+  if (typeof record.project_id === 'string' && record.project_id) {
+    return `project:${record.project_id}`;
+  }
+  return null;
 }
 
-async function listMemoryItems(rootDir) {
+async function listMemoryItems(rootDir, { config, projectId } = {}) {
   const runtimeRoot = path.join(rootDir, '.ukit', 'storage', 'memory');
   const userMemory = (await readJson(path.join(runtimeRoot, 'user.json'), null)) ?? { preferences: {}, rules: [] };
   const projectMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'projects'));
   const sessionMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'sessions'));
-  const recordMemories = await listMemoryV2RecordItems(runtimeRoot);
+  const recordMemories = await listMemoryV2RecordItems(runtimeRoot, { config, projectId });
 
   return [
     {
@@ -5677,7 +5721,18 @@ const MEMORY_V2_RECORD_POOL_LIMIT = 20;
 // Missing/malformed store → [] (same never-throw discipline as
 // readDirectoryJsonItems). Candidates: status 'active' AND (valid_until == null
 // OR valid_until > now), capped at 20 newest by created_at.
-async function listMemoryV2RecordItems(runtimeRoot) {
+// M06 rollout flag (FR-005): eligibility stage 'off' (incl. killSwitch or an
+// unlisted canary project) suppresses v2 record items entirely — identical
+// verdict to src/core/memory/memoryFlags.js via memory-flags.mjs.
+// Accepts either a memory-runtime root or a projectRoot string (tests).
+export async function listMemoryV2RecordItems(runtimeRootOrProjectRoot, { config, projectId } = {}) {
+  const runtimeRoot = typeof runtimeRootOrProjectRoot === 'string'
+    && !runtimeRootOrProjectRoot.endsWith(path.join('.ukit', 'storage', 'memory'))
+    ? path.join(runtimeRootOrProjectRoot, '.ukit', 'storage', 'memory')
+    : runtimeRootOrProjectRoot;
+  if (resolveMemoryStage(config, 'eligibility', { projectId }) === 'off') {
+    return [];
+  }
   const doc = await readJson(path.join(runtimeRoot, 'v2', 'records.json'), null);
   const records = Array.isArray(doc?.records) ? doc.records : [];
   const now = Date.now();
@@ -5691,6 +5746,8 @@ async function listMemoryV2RecordItems(runtimeRoot) {
     .map((record) => ({
       id: `record:${record.id}`,
       type: 'record',
+      // Raw record retained for memory-policy eligible() (M01-05).
+      record,
       content: {
         recordType: record.type,
         text: record.text,
@@ -5700,12 +5757,21 @@ async function listMemoryV2RecordItems(runtimeRoot) {
     }));
 }
 
-function buildPreviousContextSnippet(item) {
+// M05-01 (FR-008): record snippets carry a freshness label — ' [stale]' or
+// ' [unknown]' — resolved via memory-freshness.mjs for the ≤2 rendered items
+// only. `unknown` is rendered only when the record carries evidence that
+// failed verification; no-evidence records stay unlabeled (token cost).
+function buildPreviousContextSnippet(item, freshness = null) {
   const content = item.content ?? {};
   if (item.type === 'record') {
     const text = String(content.text ?? '').trim();
     const truncated = text.length > 120 ? `${text.slice(0, 117)}...` : text;
-    return `[${content.recordType ?? 'record'}] ${truncated}`;
+    const label = freshness?.state === 'stale'
+      ? ' [stale]'
+      : freshness?.state === 'unknown' && Array.isArray(item.record?.evidence) && item.record.evidence.length > 0
+        ? ' [unknown]'
+        : '';
+    return `[${content.recordType ?? 'record'}] ${truncated}${label}`;
   }
 
   if (item.type === 'project') {
@@ -5753,20 +5819,45 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
     return null;
   }
 
-  const projectId = await detectProjectId(rootDir);
-  const items = await listMemoryItems(rootDir);
+  const binding = await resolveRouteProjectBinding(rootDir);
+  // M06 rollout flag (FR-005): the merged config gates the v2 record lane —
+  // 'off'/killSwitch suppresses v2 memory lines identically on all engines.
+  // Shipped defaults are applied first so an absent memoryV2 block keeps the
+  // lane live (mirrors loadRuntimeConfig's default merge in src/).
+  const rawConfig = await readMergedConfig(rootDir);
+  const memoryConfig = {
+    ...rawConfig,
+    memoryV2: {
+      eligibility: { stage: 'default' },
+      writer: { stage: 'default' },
+      index: { stage: 'default' },
+      decision: { stage: 'off' },
+      canaryProjects: [],
+      killSwitch: false,
+      ...(rawConfig?.memoryV2 && typeof rawConfig.memoryV2 === 'object' ? rawConfig.memoryV2 : {}),
+    },
+  };
+  const items = await listMemoryItems(rootDir, { config: memoryConfig, projectId: binding.projectId });
   const queryTokens = tokenize(taskQuery);
+  // v2/legacy dedup: collect the legacy-lane ids first, then drop any record
+  // whose logical twin (meta.legacyId → session:<id>, project_id →
+  // project:<id>) is present — the legacy item carries the richer summary.
+  const legacyIds = new Set(
+    items.filter((item) => item.type !== 'record').map((item) => item.id),
+  );
+  const eligibleCtx = { projectId: binding.projectId, projectAliases: binding.aliases, includeUser: false };
   const rankedItems = items
     .filter((item) => item.type !== 'user')
     .filter((item) => {
-      if (item.type === 'project') {
-        return item.content?.id === projectId;
-      }
-      if (item.type === 'session') {
-        return item.content?.projectId === projectId;
-      }
       if (item.type === 'record') {
-        return item.content?.projectId == null || item.content?.projectId === projectId;
+        // Policy-owned eligibility (M01-05): repo-bound records require
+        // project_id === resolved id; null project_id denied by default.
+        if (!memoryRecordEligible(item.record, eligibleCtx).ok) return false;
+        const legacyKey = recordLegacyKey(item);
+        return !(legacyKey && legacyIds.has(legacyKey));
+      }
+      if (item.type === 'project' || item.type === 'session') {
+        return matchesProjectBinding(item, binding);
       }
       return true;
     })
@@ -5786,12 +5877,23 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
     return null;
   }
 
+  // Freshness is resolved post-limit only — the ≤2 rendered items, never the
+  // pool. Resolver errors degrade to `unknown` and never break routing.
+  const freshnessById = new Map();
+  await Promise.all(rankedItems.map(async (item) => {
+    if (item.type !== 'record') return;
+    try {
+      freshnessById.set(item.id, await resolveRecordFreshness(item.record, { projectRoot: rootDir }));
+    } catch { /* absent → unlabeled */ }
+  }));
+
   return {
-    line: rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | '),
+    line: rankedItems.map((item) => buildPreviousContextSnippet(item, freshnessById.get(item.id))).join(' | '),
     selectedIds: rankedItems.map((item) => item.id),
     fingerprint: buildCompactMachineKey('route-memory-v2', {
       taskQuery: normalize(taskQuery),
-      projectId,
+      projectId: binding.projectId,
+      policyVersion: MEMORY_POLICY_VERSION,
       items: rankedItems.map((item) => ({
         id: item.id,
         timestamp: getMemoryTimestamp(item),

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -184,7 +184,7 @@ function validateValue(question, args) {
   const value = args?.value;
   if (question.kind === 'choice') {
     if (typeof value !== 'string') return 'missing-value';
-    if (!question.candidates.includes(value)) return 'out-of-enum';
+    if (!Array.isArray(question.candidates) || !question.candidates.includes(value)) return 'out-of-enum';
     return { value };
   }
   if (question.kind === 'noul') {
@@ -542,18 +542,33 @@ export async function requestBatch(batch, {
     return outcome('invalid', { fallbackCode: 'empty-batch' });
   }
 
-  const serialized =
-    typeof batch?.statePacket === 'string'
-      ? batch.statePacket
-      : stableStringify(batch?.statePacket ?? {});
-  const questionText = questions
-    .map((q) => `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`)
-    .join(' ');
-  const languageClass = classifyLanguage(`${serialized} ${questionText}`);
-  const checkpoint = resolveCheckpoint(languageClass, config);
-
-  if (stateBudgetExceeded(serialized, languageClass, dp.maxStateTokens)) {
-    return outcome('invalid', { fallbackCode: 'state-too-large', checkpoint });
+  // Language classification covers state + question text; the English
+  // checkpoint is reachable only when the whole request proves English.
+  // Malformed batch input (cyclic state, non-serializable values, internal
+  // budget-gate faults) resolves to a typed 'invalid' outcome instead of
+  // throwing — requestBatch never throws (src/decision/client.js parity).
+  let serialized;
+  let checkpoint;
+  try {
+    serialized =
+      typeof batch?.statePacket === 'string'
+        ? batch.statePacket
+        : stableStringify(batch?.statePacket ?? {});
+    const questionText = questions
+      .map((q) => `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`)
+      .join(' ');
+    const languageClass = classifyLanguage(`${serialized} ${questionText}`);
+    checkpoint = resolveCheckpoint(languageClass, config);
+
+    if (stateBudgetExceeded(serialized, languageClass, dp.maxStateTokens)) {
+      return outcome('invalid', { fallbackCode: 'state-too-large', checkpoint });
+    }
+  } catch (error) {
+    return outcome('invalid', {
+      fallbackCode: 'malformed-question',
+      checkpoint: checkpoint ?? null,
+      detail: error?.message ?? String(error),
+    });
   }
   if (sensitiveGate(serialized, config).blocked) {
     return outcome('blocked-sensitive', { checkpoint });

package/template_project/.claude/ukit/runtime/memory-flags.mjs

@@ -0,0 +1,51 @@
+// memory-flags.mjs — read-only mirror of src/core/memory/memoryFlags.js
+// (SPEC §5 FR-005). Self-contained: mirrors cannot import src/, so the stage
+// resolution is duplicated here and pinned by tests/consistency/
+// memoryFlagsParity.test.js. Receipts are NOT emitted from mirrors — this is
+// a read-only label used to suppress v2 memory lines on 'off'/killSwitch.
+
+const VALID_ROUTE_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Same semantics as resolveConfigStage in src/core/runtimeConfig.js: absent
+// config, absent key, non-object intermediate, or malformed stage value all
+// resolve 'off' — a bad config can never promote a feature.
+function resolveConfigStage(config, path) {
+  const keys = String(path ?? '').split('.');
+  let node = config;
+  for (const key of keys) {
+    if (!isPlainObject(node)) return 'off';
+    node = node[key];
+  }
+  return VALID_ROUTE_STAGES.has(node) ? node : 'off';
+}
+
+/**
+ * resolveMemoryStage(config, plane, { projectId } = {})
+ *   → 'off'|'shadow'|'canary'|'default'
+ * plane: 'eligibility'|'writer'|'index'|'decision'. killSwitch → 'off';
+ * malformed/missing → 'off'; 'canary' + unlisted project → 'off'.
+ */
+export function resolveMemoryStage(config, plane, { projectId } = {}) {
+  const memoryV2 = config?.memoryV2;
+  if (!isPlainObject(memoryV2)) {
+    return 'off';
+  }
+  if (memoryV2.killSwitch === true) {
+    return 'off';
+  }
+  const stage = resolveConfigStage(config, `memoryV2.${plane}.stage`);
+  if (stage === 'canary') {
+    const list = Array.isArray(memoryV2.canaryProjects) ? memoryV2.canaryProjects : [];
+    return projectId != null && list.includes(projectId) ? 'canary' : 'off';
+  }
+  return stage;
+}
+
+/** 'canary'|'default' → the new path is live for this project. */
+export function isMemoryPlaneLive(stage) {
+  return stage === 'canary' || stage === 'default';
+}

package/template_project/.claude/ukit/runtime/memory-freshness.mjs

@@ -0,0 +1,155 @@
+// memory-freshness.mjs — shipped-runtime mirror of
+// src/core/memory/memoryFreshness.js (M05-01, SPEC §5 FR-008).
+//
+// Self-contained: no src/ import, no other runtime dependency. Deliberately
+// watermark-free — the hook path has no cheap ledger/head accessor, so
+// non-file evidence always resolves `unknown` (the safe verdict). Verdict
+// strings are identical to the src resolver; parity is asserted by
+// tests/consistency/memoryFreshnessParity.test.js.
+//
+// Contract:
+//   resolveRecordFreshness(record, { projectRoot, now? })
+//     -> Promise<{ state: 'fresh'|'stale'|'unknown', detail }>  // never rejects
+//   fileFingerprint(absPath) -> Promise<'fs:<mtimeMs>:<size>'|null>
+
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+// Duplicated from src/core/memory/records.js — mirrors cannot import src/.
+const MAX_EVIDENCE = 8;
+
+const FRESH = 'fresh';
+const STALE = 'stale';
+const UNKNOWN = 'unknown';
+
+/**
+ * fileFingerprint(absPath) → 'fs:<mtimeMs>:<size>' or null on any fs error.
+ */
+export async function fileFingerprint(absPath) {
+  try {
+    const st = await fsp.stat(absPath);
+    if (!st.isFile()) return null;
+    return `fs:${st.mtimeMs}:${st.size}`;
+  } catch {
+    return null;
+  }
+}
+
+async function sha1Fingerprint(absPath) {
+  try {
+    const buf = await fsp.readFile(absPath);
+    return `sha1:${crypto.createHash('sha1').update(buf).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve a file-evidence locator against projectRoot. Returns the absolute
+// path when it stays inside projectRoot, else null (unverifiable — never
+// followed). Absolute locators are used as-is but must still land inside
+// projectRoot.
+function resolveLocator(projectRoot, locator) {
+  if (typeof locator !== 'string' || locator.length === 0) return null;
+  const root = path.resolve(projectRoot);
+  const abs = path.resolve(root, locator);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+  return abs;
+}
+
+async function checkFileEvidence(projectRoot, entry) {
+  const abs = resolveLocator(projectRoot, entry.locator);
+  if (abs == null) return { state: UNKNOWN, detail: 'locator-unverifiable' };
+
+  const fp = entry.fingerprint;
+  if (typeof fp === 'string' && fp.startsWith('sha1:')) {
+    const actual = await sha1Fingerprint(abs);
+    if (actual == null) {
+      // Distinguish missing file from unreadable file.
+      const probe = await fileFingerprint(abs);
+      if (probe == null) {
+        try {
+          await fsp.stat(abs);
+          return { state: UNKNOWN, detail: 'file-unverified' }; // exists, unreadable
+        } catch {
+          return { state: STALE, detail: 'file-missing' };
+        }
+      }
+      return { state: UNKNOWN, detail: 'file-unverified' };
+    }
+    return actual === fp
+      ? { state: FRESH, detail: 'file-match' }
+      : { state: STALE, detail: 'file-changed' };
+  }
+
+  let st;
+  try {
+    st = await fsp.stat(abs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: STALE, detail: 'file-missing' };
+    return { state: UNKNOWN, detail: 'file-unverified' };
+  }
+  if (!st.isFile()) return { state: STALE, detail: 'file-missing' };
+
+  if (typeof fp !== 'string' || fp.length === 0) {
+    return { state: UNKNOWN, detail: 'file-unverified' };
+  }
+  if (fp.startsWith('fs:')) {
+    return `fs:${st.mtimeMs}:${st.size}` === fp
+      ? { state: FRESH, detail: 'file-match' }
+      : { state: STALE, detail: 'file-changed' };
+  }
+  // Unrecognized fingerprint scheme — cannot verify.
+  return { state: UNKNOWN, detail: 'file-unverified' };
+}
+
+/**
+ * resolveRecordFreshness(record, { projectRoot, now } = {})
+ *   → Promise<{ state: 'fresh'|'stale'|'unknown', detail: string }>
+ *
+ * Aggregate precedence: any stale → stale; else any unknown → unknown;
+ * else fresh. Never rejects — every per-entry error degrades to `unknown`.
+ * Non-file evidence is always `unknown`/`watermark-missing`: the shipped
+ * runtime carries no watermark source.
+ */
+export async function resolveRecordFreshness(record, { projectRoot, now } = {}) {
+  void now;
+  try {
+    const evidence = Array.isArray(record?.evidence) ? record.evidence : [];
+    if (evidence.length === 0) return { state: UNKNOWN, detail: 'no-evidence' };
+
+    let sawStale = false;
+    let sawUnknown = false;
+    let firstDetail = 'no-evidence';
+
+    for (const entry of evidence.slice(0, MAX_EVIDENCE)) {
+      let verdict;
+      try {
+        if (entry != null && entry.kind === 'file') {
+          verdict = await checkFileEvidence(projectRoot, entry);
+        } else {
+          // No watermark source on the hook path — non-file evidence is
+          // unverifiable by construction.
+          verdict = { state: UNKNOWN, detail: 'watermark-missing' };
+        }
+      } catch {
+        verdict = { state: UNKNOWN, detail: 'file-unverified' };
+      }
+      if (verdict.state === STALE) {
+        if (!sawStale) firstDetail = verdict.detail;
+        sawStale = true;
+      } else if (verdict.state === UNKNOWN) {
+        if (!sawStale && !sawUnknown) firstDetail = verdict.detail;
+        sawUnknown = true;
+      } else if (!sawStale && !sawUnknown) {
+        firstDetail = verdict.detail;
+      }
+    }
+
+    if (sawStale) return { state: STALE, detail: firstDetail };
+    if (sawUnknown) return { state: UNKNOWN, detail: firstDetail };
+    return { state: FRESH, detail: firstDetail };
+  } catch {
+    return { state: UNKNOWN, detail: 'resolver-error' };
+  }
+}