@ngockhoale/ukit 3.0.8 → 3.0.10

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

@@ -0,0 +1,286 @@
+// Memory eligibility policy — shipped mirror of src/core/memory/policy.js
+// (M01-04). Self-contained: no src/ imports, no UKit runtime deps, so
+// route-task/reinject hooks enforce the identical policy version.
+// READ-ONLY by contract: resolveProjectIdentityMirror NEVER mints and NEVER
+// writes the registry — minting stays host-side in src/core/memory/
+// projectIdentity.js.
+//
+// Parity is enforced by tests/consistency/memoryPolicyParity.test.js — keep
+// POLICY_VERSION and every verdict identical to src/core/memory/policy.js.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const POLICY_VERSION = 'w1-2';
+
+const REPO_BOUND_SCOPES = Object.freeze(['repo', 'project', 'task', 'session']);
+const UNVERIFIED_PROVENANCE = Object.freeze([
+  'learning-observation',
+  'learning-candidate',
+  'delta-overlay',
+]);
+// Trust tiers that must never surface as a current authoritative fact
+// (TASK-005 / FR-010): candidates and observations are unreviewed input —
+// returning them as eligible is a false-authority breach. 'verified' and
+// 'legacy-unverified' (migrated records) remain admissible.
+const NON_AUTHORITY_TRUST_TIERS = Object.freeze(['candidate', 'observation']);
+const REQUESTED_SCOPES = Object.freeze(['repo', 'user', 'session', 'task', 'all']);
+
+function deny(reason) {
+  return { ok: false, reason };
+}
+
+// hostContext = {projectId: string|null, ambiguous?: boolean, sessionId?, taskId?, branch?}
+// requestedScope ∈ 'repo'|'user'|'session'|'task'|'all' (default 'all').
+// → {scope, projectId, includeUser, denied}
+export function resolveEffectiveScope(hostContext = {}, requestedScope = 'all') {
+  const scope = REQUESTED_SCOPES.includes(requestedScope) ? requestedScope : 'all';
+  const projectId = typeof hostContext.projectId === 'string' ? hostContext.projectId : null;
+  const ambiguous = hostContext.ambiguous === true;
+
+  if (scope === 'user') {
+    return { scope, projectId: null, includeUser: true, denied: false };
+  }
+
+  if (scope === 'all') {
+    // 'all' keeps projectId but does not opt into user records
+    // (user-repo-precedence: user records need explicit opt-in).
+    return { scope, projectId, includeUser: false, denied: false };
+  }
+
+  // repo / task / session require a non-null, non-ambiguous project binding.
+  if (projectId == null || ambiguous) {
+    return { scope, projectId, includeUser: false, denied: true };
+  }
+  return { scope, projectId, includeUser: false, denied: false };
+}
+
+// record per src/core/memory/records.js
+//   (scope, status, project_id, valid_until, provenance, type).
+// context = {projectId, projectAliases?: string[], includeUser, now?}
+// policy  = {legacyNullProjectId: 'deny'|'compat'} — default 'deny'.
+// → {ok: boolean, reason: string}
+export function eligible(record, context = {}, policy = {}) {
+  const now = typeof context.now === 'number' ? context.now : Date.now();
+  const legacyNull = policy.legacyNullProjectId === 'compat' ? 'compat' : 'deny';
+
+  if (record == null || typeof record !== 'object') {
+    return deny('status');
+  }
+  if (record.status !== 'active') {
+    return deny('status');
+  }
+  if (record.valid_until != null && record.valid_until <= now) {
+    return deny('expired');
+  }
+  if (UNVERIFIED_PROVENANCE.includes(record.provenance)) {
+    return deny('unverified-provenance');
+  }
+  if (NON_AUTHORITY_TRUST_TIERS.includes(record.trust_tier)) {
+    return deny('non-authority-trust-tier');
+  }
+
+  if (record.scope === 'user') {
+    if (context.includeUser !== true) {
+      return deny('user-scope-not-included');
+    }
+    return { ok: true, reason: 'ok' };
+  }
+
+  if (REPO_BOUND_SCOPES.includes(record.scope)) {
+    if (context.projectId == null) {
+      return deny('no-project-binding');
+    }
+    if (record.project_id != null && record.project_id !== context.projectId
+        && !(Array.isArray(context.projectAliases)
+          && context.projectAliases.includes(record.project_id))) {
+      return deny('project-mismatch');
+    }
+    if (record.project_id == null && legacyNull !== 'compat') {
+      return deny('null-project-id');
+    }
+  }
+
+  return { ok: true, reason: 'ok' };
+}
+
+// ---- Read-only project identity mirror (SPEC §5 FR-001..003) ----
+// Same resolution order as src/core/memory/projectIdentity.js minus minting:
+// (1) canonical realpath in registry roots; (2) git common-dir binding;
+// (3) alias index — multiple hits → ambiguous deny; otherwise unverified.
+
+function registryPathFor(homeDir) {
+  const home = typeof homeDir === 'string' && homeDir ? homeDir : os.homedir();
+  return path.join(home, '.ukit', 'storage', 'projects', 'registry.json');
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// Tolerant registry read. Missing → empty registry. Corrupt → null sentinel
+// (caller degrades to `unverified`; the file is NEVER overwritten on read).
+async function readRegistry(regPath) {
+  let data;
+  try {
+    data = await readJsonIfExists(regPath);
+  } catch {
+    return null; // corrupt JSON — degrade, never throw, never rewrite
+  }
+  if (data === null) return { schemaVersion: 1, projects: {}, aliasIndex: {} };
+  if (typeof data !== 'object' || typeof data.projects !== 'object' || data.projects === null) {
+    return null;
+  }
+  if (typeof data.aliasIndex !== 'object' || data.aliasIndex === null) {
+    data.aliasIndex = {};
+  }
+  return data;
+}
+
+async function realpathOrNull(target) {
+  try {
+    return await fs.realpath(target);
+  } catch {
+    return null;
+  }
+}
+
+// `.git` dir → itself; `.git` file (`gitdir: <p>`) → `<p>/commondir` (linked
+// worktrees share the main common dir). Null when there is no git binding.
+async function resolveGitCommonDir(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  let stat;
+  try {
+    stat = await fs.stat(gitPath);
+  } catch {
+    return null;
+  }
+
+  if (stat.isDirectory()) {
+    return await realpathOrNull(gitPath);
+  }
+  if (!stat.isFile()) return null;
+
+  let content;
+  try {
+    content = await fs.readFile(gitPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const match = content.match(/^gitdir:\s*(.+)$/m);
+  if (!match) return null;
+  const gitDir = path.resolve(projectRoot, match[1].trim());
+
+  let commonDirRel;
+  try {
+    commonDirRel = (await fs.readFile(path.join(gitDir, 'commondir'), 'utf8')).trim();
+  } catch {
+    commonDirRel = '';
+  }
+  const commonDir = commonDirRel ? path.resolve(gitDir, commonDirRel) : gitDir;
+  return await realpathOrNull(commonDir);
+}
+
+async function aliasesFor(projectRoot, realRoot) {
+  const names = new Set();
+  const base = path.basename(realRoot ?? projectRoot);
+  if (base) names.add(base);
+  const pkg = await readJsonIfExists(path.join(projectRoot, 'package.json')).catch(() => null);
+  if (typeof pkg?.name === 'string' && pkg.name.trim() !== '') {
+    names.add(pkg.name.trim());
+  }
+  return [...names];
+}
+
+function findByRoot(registry, realRoot) {
+  for (const [projectId, entry] of Object.entries(registry.projects)) {
+    if (Array.isArray(entry?.roots) && entry.roots.includes(realRoot)) {
+      return projectId;
+    }
+  }
+  return null;
+}
+
+function findByGitCommonDir(registry, commonDir) {
+  if (!commonDir) return null;
+  for (const [projectId, entry] of Object.entries(registry.projects)) {
+    if (Array.isArray(entry?.gitCommonDirs) && entry.gitCommonDirs.includes(commonDir)) {
+      return projectId;
+    }
+  }
+  return null;
+}
+
+function findByAlias(registry, aliases) {
+  const hits = new Set();
+  for (const name of aliases) {
+    const entry = registry.aliasIndex?.[name];
+    if (entry === 'ambiguous') {
+      hits.add('ambiguous');
+      continue;
+    }
+    if (Array.isArray(entry)) {
+      for (const id of entry) hits.add(id);
+    } else if (typeof entry === 'string' && entry) {
+      hits.add(entry);
+    }
+  }
+  return hits;
+}
+
+/**
+ * Read-only mirror of resolveProjectIdentity (mint:false path only).
+ * Corrupt/missing registry → {projectId:null, source:'unverified'}.
+ * NEVER mints, NEVER writes.
+ *
+ * @returns {Promise<{projectId: string|null, source: 'registry'|'git-common-dir'|'alias'|'unverified', ambiguous: boolean}>}
+ */
+export async function resolveProjectIdentityMirror(projectRoot, { homeDir } = {}) {
+  const unverified = { projectId: null, source: 'unverified', ambiguous: false };
+  const regPath = registryPathFor(homeDir);
+
+  const registry = await readRegistry(regPath);
+  if (registry === null) return unverified; // corrupt — never overwrite on read
+
+  const realRoot = (await realpathOrNull(projectRoot)) ?? path.resolve(projectRoot);
+  const byRoot = findByRoot(registry, realRoot);
+  if (byRoot) {
+    return {
+      projectId: byRoot,
+      source: 'registry',
+      ambiguous: false,
+      aliases: Array.isArray(registry.projects[byRoot]?.aliases)
+        ? registry.projects[byRoot].aliases.filter((a) => typeof a === 'string')
+        : [],
+    };
+  }
+
+  const commonDir = await resolveGitCommonDir(projectRoot);
+  const byGit = findByGitCommonDir(registry, commonDir);
+  if (byGit) {
+    return {
+      projectId: byGit,
+      source: 'git-common-dir',
+      ambiguous: false,
+      aliases: Array.isArray(registry.projects[byGit]?.aliases)
+        ? registry.projects[byGit].aliases.filter((a) => typeof a === 'string')
+        : [],
+    };
+  }
+
+  const aliases = await aliasesFor(projectRoot, realRoot);
+  // Alias is a weak display-name signal only: any hit for a different root
+  // denies (ambiguous) rather than letting a same-named repo inherit an id.
+  const aliasHits = findByAlias(registry, aliases);
+  if (aliasHits.size > 0) {
+    return { projectId: null, source: 'alias', ambiguous: true };
+  }
+
+  return unverified;
+}

package/template_project/.claude/ukit/runtime/output-compression.mjs

@@ -372,6 +372,9 @@ function buildRawOutputText({ command = '', stdout = '', stderr = '', exitCode =
 }
 
 function buildRecoveryHintSummary(summary, rawPath, { tokensBefore = 0 } = {}) {
+  // TASK-003 fix round 1: a failed tee persist returns rawPath='' — never emit a
+  // dangling `- Full output: ` hint that points at nothing.
+  if (!rawPath) return null;
   const recoveryLine = `- Full output: ${rawPath}`;
   const summaryLines = String(summary ?? '')
     .split(/\r?\n/)

package/template_project/.claude/ukit/runtime/reinject-context.mjs

@@ -24,6 +24,12 @@ import {
   readResumableRun,
   resumableRunSourceFingerprint,
 } from './resumable-run.mjs';
+import {
+  eligible as memoryRecordEligible,
+  resolveProjectIdentityMirror,
+} from './memory-policy.mjs';
+import { resolveRecordFreshness } from './memory-freshness.mjs';
+import { resolveMemoryStage } from './memory-flags.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): the reinject-context hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
@@ -320,6 +326,13 @@ function defaultRuntimeConfig() {
       progressiveRetrieval: true,
       maxInjectionTokens: 320,
     },
+    // M06 rollout defaults (FR-001): the shipped default keeps the v2 read
+    // lane live; absent user config must not resolve 'off'.
+    memoryV2: {
+      eligibility: { stage: 'default' },
+      killSwitch: false,
+      canaryProjects: [],
+    },
   };
 }
 
@@ -913,6 +926,13 @@ function getMemoryTimestamp(item) {
 
 function buildMemorySegments(item) {
   const content = item.content ?? {};
+  if (item.type === 'record') {
+    return [
+      { text: content.recordType, weight: 1 },
+      { text: content.text, weight: 3 },
+    ];
+  }
+
   if (item.type === 'project') {
     return [
       { text: content.name, weight: 2 },
@@ -991,21 +1011,95 @@ async function readDirectoryJsonItems(dirPath) {
   return items.sort((left, right) => left.fileName.localeCompare(right.fileName));
 }
 
-async function detectProjectId(projectRoot) {
+// 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 resolveProjectBinding(projectRoot) {
+  const identity = await resolveProjectIdentityMirror(projectRoot).catch(() => null);
+  const names = new Set();
+  const base = path.basename(projectRoot);
+  if (base) names.add(base);
   const pkg = await readJson(path.join(projectRoot, '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);
+}
+
+// v2/legacy dedup (M01-05): meta.legacyId → session:<id>; project_id →
+// project:<id>. The legacy item wins — 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;
+}
 
-  return path.basename(projectRoot);
+const MEMORY_V2_RECORD_POOL_LIMIT = 20;
+
+// v2 lane (M01-05): approved records live in a single records.json document.
+// Missing/malformed store → [] (never-throw, same as readDirectoryJsonItems).
+// Stale snapshots excluded here AND re-checked by eligible() downstream.
+// 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 runtimePaths object or a projectRoot string (tests).
+export async function listMemoryV2RecordItems(runtimePathsOrRoot, { config, projectId } = {}) {
+  const memoryRoot = typeof runtimePathsOrRoot === 'string'
+    ? path.join(runtimePathsOrRoot, '.ukit', 'storage', 'memory')
+    : runtimePathsOrRoot.memoryRoot;
+  if (resolveMemoryStage(config, 'eligibility', { projectId }) === 'off') {
+    return [];
+  }
+  const doc = await readJson(path.join(memoryRoot, 'v2', 'records.json'), null);
+  const records = Array.isArray(doc?.records) ? doc.records : [];
+  const now = Date.now();
+
+  return records
+    .filter((record) => record && typeof record === 'object')
+    .filter((record) => record.status === 'active')
+    .filter((record) => record.valid_until == null || record.valid_until > now)
+    .sort((left, right) => (right.created_at ?? 0) - (left.created_at ?? 0))
+    .slice(0, MEMORY_V2_RECORD_POOL_LIMIT)
+    .map((record) => ({
+      id: `record:${record.id}`,
+      type: 'record',
+      record,
+      content: {
+        recordType: record.type,
+        text: record.text,
+        projectId: record.project_id,
+        updatedAt: record.created_at,
+      },
+    }));
 }
 
-async function listMemoryItems(projectRoot) {
+async function listMemoryItems(projectRoot, { config, projectId } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   const userMemory = (await readJson(runtimePaths.userMemoryPath, null)) ?? { preferences: {}, rules: [] };
   const projectMemories = await readDirectoryJsonItems(runtimePaths.projectsDir);
   const sessionMemories = await readDirectoryJsonItems(runtimePaths.sessionsDir);
-
+  const recordMemories = await listMemoryV2RecordItems(runtimePaths, { config, projectId });
   return [
     {
       id: 'user:user',
@@ -1022,11 +1116,27 @@ async function listMemoryItems(projectRoot) {
       type: 'session',
       content: item.content,
     })),
+    ...recordMemories,
   ];
 }
 
-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;
+    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') {
     const decisions = compactPhraseList((content.decisions ?? []).map((decision) => decision.what), { limit: 1 });
     const rules = compactPhraseList(content.activeRules ?? [], { limit: 1 });
@@ -1089,16 +1199,28 @@ async function buildPreviousContextLines(projectRoot, state, config) {
     return [`- Previous context: ${sharedPreviousContextLine}`];
   }
 
-  const projectId = await detectProjectId(projectRoot);
-  const items = await listMemoryItems(projectRoot);
+  const binding = await resolveProjectBinding(projectRoot);
+  const items = await listMemoryItems(projectRoot, { config, projectId: binding.projectId });
   const queryTokens = tokenize(taskQuery);
+  // v2/legacy dedup (M01-05): drop a record whose logical twin
+  // (meta.legacyId → session:<id>, project_id → project:<id>) exists.
+  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) => (
-      item.type === 'project'
-        ? (item.content?.id === projectId)
-        : (item.type === 'session' ? item.content?.projectId === projectId : true)
-    ))
+    .filter((item) => {
+      if (item.type === 'record') {
+        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;
+    })
     .map((item) => ({ item, score: scoreMemoryItem(item, queryTokens) }))
     .filter((entry) => entry.score > 0)
     .sort((left, right) => (
@@ -1111,8 +1233,17 @@ async function buildPreviousContextLines(projectRoot, state, config) {
   if (rankedItems.length === 0) {
     return [];
   }
+  // Freshness is resolved post-limit only — the ≤2 rendered items, never the
+  // pool. Resolver errors degrade to `unknown` and never break the hook.
+  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 }));
+    } catch { /* absent → unlabeled */ }
+  }));
 
-  return [`- Previous context: ${rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | ')}`];
+  return [`- Previous context: ${rankedItems.map((item) => buildPreviousContextSnippet(item, freshnessById.get(item.id))).join(' | ')}`];
 }
 
 // BUG-C23-13: only run main() on direct CLI invocation — an unguarded bottom