@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/context/codegraph-read-provider.ts

@@ -4,6 +4,8 @@ import { createRequire } from 'module';
 import { dirname, join, resolve } from 'path';
 import { createInterface, type Interface as ReadlineInterface } from 'readline';
 import { fileURLToPath } from 'url';
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { createCodegraphCacheLocator, codegraphRepositoryCacheRoot, type CodegraphCacheLocator } from './codegraph-cache-boundary';
 
 const require = createRequire(import.meta.url);
 const SCHEMA_VERSION = 1;
@@ -69,6 +71,8 @@ export interface CodeGraphReadRequest {
   limit?: number;
   maxNodes?: number;
   maxDepth?: number;
+  /** Refresh only the derived CodeGraph index before a required structural read. */
+  refresh?: 'if_stale';
 }
 
 export interface CodeGraphReadProviderResponse {
@@ -169,7 +173,7 @@ export function resolveCodeGraphBundledRuntime(options: { runtimeRoot?: string }
   return { nodeExecutable, sidecarPath, libraryPath, platformPackage, source: 'dependency' };
 }
 
-function minimalEnvironment(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>): NodeJS.ProcessEnv {
+function minimalEnvironment(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>, codegraphDir?: string): NodeJS.ProcessEnv {
   return Object.fromEntries(Object.entries({
     PATH: dirname(runtime.nodeExecutable),
     HOME: process.env.HOME,
@@ -181,6 +185,7 @@ function minimalEnvironment(runtime: ReturnType<typeof resolveCodeGraphBundledRu
     CODEGRAPH_TELEMETRY: '0',
     DO_NOT_TRACK: '1',
     CODEGRAPH_NO_DAEMON: '1',
+    CODEGRAPH_DIR: codegraphDir,
     FORGE_CODEGRAPH_LIBRARY_PATH: runtime.libraryPath,
   }).filter((entry): entry is [string, string] => typeof entry[1] === 'string'));
 }
@@ -289,6 +294,7 @@ export function queryCodeGraphReadProvider(
     ...(typeof request.query === 'string' ? { query: request.query.slice(0, 2_000) } : {}),
     ...(typeof request.nodeId === 'string' ? { nodeId: request.nodeId.slice(0, 1_000) } : {}),
     ...(typeof request.filePath === 'string' ? { filePath: request.filePath.slice(0, 2_000) } : {}),
+    ...(request.refresh === 'if_stale' ? { refresh: 'if_stale' as const } : {}),
     limit: boundedInteger(request.limit, 12, 1, 40),
     maxNodes: boundedInteger(request.maxNodes, 40, 1, 80),
     maxDepth: boundedInteger(request.maxDepth, 2, 1, 5),
@@ -299,16 +305,23 @@ export function queryCodeGraphReadProvider(
   }
 
   const processStartedAt = performance.now();
-  const execution = spawnSync(runtime.nodeExecutable, [runtime.sidecarPath], {
-    cwd: resolve(repoRoot),
-    input,
-    encoding: 'utf8',
-    env: minimalEnvironment(runtime),
-    timeout: boundedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1_000, 60_000),
-    maxBuffer: MAX_RESPONSE_BYTES,
-    windowsHide: true,
-    shell: false,
-  });
+  const resolvedRepoRoot = resolve(repoRoot);
+  const locator = createCodegraphCacheLocator(resolvedRepoRoot, resolveControllerHome(), { createTarget: false });
+  let execution: ReturnType<typeof spawnSync>;
+  try {
+    execution = spawnSync(runtime.nodeExecutable, [runtime.sidecarPath], {
+      cwd: resolvedRepoRoot,
+      input,
+      encoding: 'utf8',
+      env: minimalEnvironment(runtime, locator?.name),
+      timeout: boundedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1_000, 60_000),
+      maxBuffer: MAX_RESPONSE_BYTES,
+      windowsHide: true,
+      shell: false,
+    });
+  } finally {
+    locator?.release();
+  }
   const processMs = performance.now() - processStartedAt;
   if (execution.error) {
     const code = (execution.error as NodeJS.ErrnoException).code === 'ETIMEDOUT' ? 'CODEGRAPH_TIMEOUT' : 'CODEGRAPH_START_FAILED';
@@ -359,6 +372,7 @@ interface PersistentCodeGraphSession {
   closed: boolean;
   idleTimer?: NodeJS.Timeout;
   queue: Promise<void>;
+  locator?: CodegraphCacheLocator;
 }
 
 const persistentSessions = new Map<string, PersistentCodeGraphSession>();
@@ -366,8 +380,8 @@ let persistentSessionSpawns = 0;
 let persistentSessionReuses = 0;
 let persistentSessionRequests = 0;
 
-function persistentRuntimeKey(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>): string {
-  return `${runtime.nodeExecutable}\u0000${runtime.sidecarPath}\u0000${runtime.libraryPath}`;
+function persistentRuntimeKey(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>, cacheMode: 'controller' | 'legacy'): string {
+  return `${runtime.nodeExecutable}\u0000${runtime.sidecarPath}\u0000${runtime.libraryPath}\u0000${cacheMode}`;
 }
 
 function closePersistentSessionNow(session: PersistentCodeGraphSession): void {
@@ -378,6 +392,8 @@ function closePersistentSessionNow(session: PersistentCodeGraphSession): void {
   try { session.reader.close(); } catch {}
   try { session.child.stdin.end(); } catch {}
   try { session.child.kill(); } catch {}
+  session.locator?.release();
+  session.locator = undefined;
 }
 
 function schedulePersistentSessionIdle(session: PersistentCodeGraphSession): void {
@@ -391,24 +407,36 @@ function createPersistentSession(
   repoRoot: string,
   runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>,
 ): PersistentCodeGraphSession {
-  const child = spawn(runtime.nodeExecutable, [runtime.sidecarPath], {
-    cwd: repoRoot,
-    env: { ...minimalEnvironment(runtime), FORGE_CODEGRAPH_PERSISTENT: '1' },
-    stdio: ['pipe', 'pipe', 'pipe'],
-    windowsHide: true,
-    shell: false,
-  });
+  const controllerHome = resolveControllerHome();
+  const cacheMode: 'controller' | 'legacy' = existsSync(codegraphRepositoryCacheRoot(controllerHome, repoRoot)) ? 'controller' : 'legacy';
+  const locator = cacheMode === 'controller'
+    ? createCodegraphCacheLocator(repoRoot, controllerHome, { createTarget: false }) ?? undefined
+    : undefined;
+  let child: ChildProcessWithoutNullStreams;
+  try {
+    child = spawn(runtime.nodeExecutable, [runtime.sidecarPath], {
+      cwd: repoRoot,
+      env: { ...minimalEnvironment(runtime, locator?.name), FORGE_CODEGRAPH_PERSISTENT: '1' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+      shell: false,
+    });
+  } catch (error) {
+    locator?.release();
+    throw error;
+  }
   child.unref();
   const reader = createInterface({ input: child.stdout, crlfDelay: Infinity });
   const session: PersistentCodeGraphSession = {
     repoRoot,
-    runtimeKey: persistentRuntimeKey(runtime),
+    runtimeKey: persistentRuntimeKey(runtime, cacheMode),
     child,
     reader,
     lines: reader[Symbol.asyncIterator](),
     stderr: '',
     closed: false,
     queue: Promise.resolve(),
+    locator,
   };
   child.stderr.on('data', (chunk: Buffer) => {
     if (session.stderr.length >= MAX_STDERR_CHARS) return;
@@ -419,6 +447,8 @@ function createPersistentSession(
     session.closed = true;
     if (session.idleTimer) clearTimeout(session.idleTimer);
     if (persistentSessions.get(repoRoot) === session) persistentSessions.delete(repoRoot);
+    session.locator?.release();
+    session.locator = undefined;
   });
   persistentSessions.set(repoRoot, session);
   persistentSessionSpawns += 1;
@@ -429,7 +459,9 @@ function getPersistentSession(
   repoRoot: string,
   runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>,
 ): PersistentCodeGraphSession {
-  const key = persistentRuntimeKey(runtime);
+  const controllerHome = resolveControllerHome();
+  const cacheMode: 'controller' | 'legacy' = existsSync(codegraphRepositoryCacheRoot(controllerHome, repoRoot)) ? 'controller' : 'legacy';
+  const key = persistentRuntimeKey(runtime, cacheMode);
   const current = persistentSessions.get(repoRoot);
   if (current && !current.closed && current.runtimeKey === key) {
     if (current.idleTimer) clearTimeout(current.idleTimer);
@@ -521,6 +553,7 @@ export async function queryCodeGraphReadProviderAsync(
     ...(typeof request.query === 'string' ? { query: request.query.slice(0, 2_000) } : {}),
     ...(typeof request.nodeId === 'string' ? { nodeId: request.nodeId.slice(0, 1_000) } : {}),
     ...(typeof request.filePath === 'string' ? { filePath: request.filePath.slice(0, 2_000) } : {}),
+    ...(request.refresh === 'if_stale' ? { refresh: 'if_stale' as const } : {}),
     limit: boundedInteger(request.limit, 12, 1, 40),
     maxNodes: boundedInteger(request.maxNodes, 40, 1, 80),
     maxDepth: boundedInteger(request.maxDepth, 2, 1, 5),

package/src/runtime/context/codegraph-sidecar.cjs

@@ -145,8 +145,15 @@ async function handleRequest(request) {
 
   let graph;
   const openStartedAt = performance.now();
+  const refreshIfStale = request.refresh === 'if_stale';
   try {
-    graph = await loaded.CodeGraph.open(request.projectRoot, { sync: false, readOnly: true });
+    // Structural refresh mutates only the Forge-owned derived CodeGraph cache.
+    // Ordinary/auto reads stay strictly read-only so they never acquire hidden
+    // lifecycle authority or pay an indexing latency tax.
+    graph = await loaded.CodeGraph.open(request.projectRoot, {
+      sync: refreshIfStale,
+      readOnly: !refreshIfStale,
+    });
   } catch (error) {
     return failure(operation, 'CODEGRAPH_OPEN_FAILED', error instanceof Error ? error.message : error);
   }

package/src/runtime/context/context-closure.ts

@@ -0,0 +1,268 @@
+import { createHash } from 'crypto';
+import { spawnSync } from 'child_process';
+import { existsSync, readdirSync } from 'fs';
+import { basename, extname, join } from 'path';
+import {
+  validateContextClosureReceipt,
+  type ContextClosureReceipt,
+  ContextClosureSemanticToolResolution,
+  ContextClosureSkillResolution,
+  ProjectEngineeringContract,
+} from '../../../packages/kernel/work/api/index';
+import { loadProjectEngineeringContract } from './project-engineering-contract';
+
+const MAX_CLOSURE_PATHS = 48;
+const MAX_RECENT_CHANGES = 6;
+const MAX_ISSUED_CONTEXT_CLOSURES = 256;
+const issuedContextClosures = new Map<string, { sourceRevision: string; fullDigest: string }>();
+const MATERIAL_SEMANTIC_INTENT = /\b(architecture|ownership|authority|authorization|permission|trust|identity|scope|protocol|cross[- ]?file|refactor|interface|contract|persistence|schema|migration|backup|restore|corruption|concurrency|resource|lease|fenc(?:e|ing)|lifecycle|retention|gc|replay|idempoten(?:cy|t)|receipt|evidence|audit|recovery|failure[- ]?domain|topology|instance|capacity|backpressure|fairness|starvation|security|privacy|secret|portability|release|rollback|writer|transaction|performance)\b/i;
+
+type ContextPackLike = {
+  schemaVersion: number;
+  generatedAt: string;
+  git: { branch: string | null; dirty: boolean };
+  instructionContext: { status: 'none' | 'ready' | 'degraded'; contracts: Array<{ path: string }> };
+  structuralContext: { status: 'disabled' | 'ready' | 'stale' | 'unavailable' | 'degraded' };
+  readiness: { sourceRevision: string | null; rawSource: { status: 'current' | 'partial' | 'unavailable' }; status: 'ready' | 'degraded' | 'insufficient'; unresolvedReasonCodes: string[] };
+  files: Array<{ path: string }>;
+  coverage: { relevantTests: string[]; inspectedFiles: string[] };
+};
+
+function fullReceiptDigest(receipt: ContextClosureReceipt): string {
+  return createHash('sha256').update(JSON.stringify(receipt)).digest('hex');
+}
+
+function recordIssuedContextClosure(receipt: ContextClosureReceipt): ContextClosureReceipt {
+  issuedContextClosures.delete(receipt.receiptId);
+  issuedContextClosures.set(receipt.receiptId, { sourceRevision: receipt.sourceRevision, fullDigest: fullReceiptDigest(receipt) });
+  while (issuedContextClosures.size > MAX_ISSUED_CONTEXT_CLOSURES) {
+    const oldest = issuedContextClosures.keys().next().value as string | undefined;
+    if (!oldest) break;
+    issuedContextClosures.delete(oldest);
+  }
+  return receipt;
+}
+
+/** Runtime-generation provenance fence: content hashes prove integrity; this registry proves rh_context actually issued this exact receipt. */
+export function validateRuntimeIssuedContextClosureReceipt(value: ContextClosureReceipt): ContextClosureReceipt {
+  const receipt = validateContextClosureReceipt(value);
+  const issued = issuedContextClosures.get(receipt.receiptId);
+  if (!issued || issued.sourceRevision !== receipt.sourceRevision || issued.fullDigest !== fullReceiptDigest(receipt)) {
+    throw new Error('CONTEXT_CLOSURE_RECEIPT_NOT_ISSUED_BY_RUNTIME');
+  }
+  // LRU refresh without changing authority semantics.
+  issuedContextClosures.delete(receipt.receiptId);
+  issuedContextClosures.set(receipt.receiptId, issued);
+  return receipt;
+}
+
+type SemanticNavigationLike = {
+  requested: number;
+  results: unknown[];
+  errors: Array<{ code?: unknown; message?: unknown }>;
+  freshness?: string;
+};
+
+export interface BuildContextClosureInput {
+  repoRoot: string;
+  query: string;
+  pack: ContextPackLike;
+  semanticNavigation: SemanticNavigationLike;
+  semanticProviders: Array<{ id: string; languages: readonly string[] }>;
+  workId?: string;
+  activeWorkIds?: string[];
+  includeRecentChanges?: boolean;
+}
+
+function unique(values: Iterable<string>, limit = 64): string[] {
+  return [...new Set([...values].map((value) => value.trim()).filter(Boolean))].slice(0, limit);
+}
+
+function detectedLanguages(repoRoot: string, paths: string[]): string[] {
+  const values = new Set<string>();
+  for (const path of paths) {
+    const ext = extname(path).toLowerCase();
+    if (['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) values.add('typescript');
+    else if (ext === '.swift') values.add('swift');
+    else if (ext === '.rs') values.add('rust');
+    else if (ext === '.go') values.add('go');
+    else if (['.py', '.pyi'].includes(ext)) values.add('python');
+    else if (['.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx'].includes(ext)) values.add('cpp');
+  }
+  if (existsSync(join(repoRoot, 'tsconfig.json')) || existsSync(join(repoRoot, 'package.json'))) values.add('typescript');
+  if (existsSync(join(repoRoot, 'Package.swift'))) values.add('swift');
+  return [...values].sort();
+}
+
+function detectedPlatforms(repoRoot: string, contract: ProjectEngineeringContract | undefined): string[] {
+  const values = new Set<string>(contract?.platforms ?? []);
+  let entries: string[] = [];
+  try { entries = readdirSync(repoRoot).slice(0, 512); } catch { /* bounded best effort */ }
+  if (entries.some((entry) => entry.endsWith('.xcodeproj') || entry.endsWith('.xcworkspace'))) values.add('ios');
+  if (existsSync(join(repoRoot, 'package.json'))) values.add('node');
+  return [...values].sort();
+}
+
+function parseSkillRef(value: string): { id: string; version?: string } {
+  const normalized = value.trim();
+  const splitAt = normalized.lastIndexOf('@');
+  if (splitAt > 0 && splitAt < normalized.length - 1) {
+    return { id: normalized.slice(0, splitAt), version: normalized.slice(splitAt + 1) };
+  }
+  return { id: normalized };
+}
+
+function requiredSkillKinds(languages: string[], platforms: string[]): string[] {
+  const kinds = new Set<string>();
+  if (languages.includes('typescript')) kinds.add('typescript');
+  if (languages.includes('swift')) kinds.add('swift');
+  if (platforms.some((value) => value.toLowerCase() === 'ios')) kinds.add('ios');
+  for (const language of languages) if (!['typescript', 'swift'].includes(language)) kinds.add(language);
+  return [...kinds].sort();
+}
+
+function resolveSkills(contract: ProjectEngineeringContract | undefined, requiredKinds: string[]) {
+  if (requiredKinds.length === 0) return { status: 'not_required' as const, requiredKinds, resolved: [] as ContextClosureSkillResolution[], unresolvedKinds: [] as string[] };
+  const parsed = (contract?.skillRefs ?? []).map(parseSkillRef);
+  const resolved: ContextClosureSkillResolution[] = [];
+  const covered = new Set<string>();
+  for (const skill of parsed) {
+    const lower = skill.id.toLowerCase();
+    const matchedKinds = requiredKinds.filter((kind) => lower.includes(kind.toLowerCase()));
+    if (matchedKinds.length === 0) continue;
+    matchedKinds.forEach((kind) => covered.add(kind));
+    resolved.push({ ...skill, source: 'project_contract', matchedKinds });
+  }
+  const unresolvedKinds = requiredKinds.filter((kind) => !covered.has(kind));
+  const status = unresolvedKinds.length === 0 ? 'ready' as const : resolved.length > 0 ? 'degraded' as const : 'unavailable' as const;
+  return { status, requiredKinds, resolved, unresolvedKinds };
+}
+
+function semanticResultProviderIds(results: unknown[]): string[] {
+  const ids: string[] = [];
+  for (const value of results) {
+    if (!value || typeof value !== 'object') continue;
+    const record = value as Record<string, unknown>;
+    const nested = record.result && typeof record.result === 'object' ? record.result as Record<string, unknown> : undefined;
+    const id = typeof record.providerId === 'string' ? record.providerId : typeof nested?.providerId === 'string' ? nested.providerId : undefined;
+    if (id) ids.push(id);
+  }
+  return unique(ids);
+}
+
+function resolveSemanticTools(input: BuildContextClosureInput, languages: string[], contract: ProjectEngineeringContract | undefined) {
+  const toolingSignals = (contract?.tooling ?? []).map((item) => `${item.id} ${item.purpose ?? ''}`).join(' ');
+  const required = MATERIAL_SEMANTIC_INTENT.test(input.query) || /\b(lsp|language[- ]?service|sourcekit|semantic)\b/i.test(toolingSignals);
+  if (!required) {
+    return { required, status: 'not_required' as const, providers: [] as ContextClosureSemanticToolResolution[], reasonCodes: [] as string[], compilerEvidenceRequired: false };
+  }
+  const applicable = input.semanticProviders.filter((provider) => provider.languages.some((language) => languages.includes(language)));
+  const resultProviderIds = new Set(semanticResultProviderIds(input.semanticNavigation.results));
+  const providers: ContextClosureSemanticToolResolution[] = applicable.map((provider) => ({
+    providerId: provider.id,
+    languages: [...provider.languages].filter((language) => languages.includes(language)),
+    status: resultProviderIds.has(provider.id)
+      ? 'ready'
+      : input.semanticNavigation.requested > 0
+        ? input.semanticNavigation.errors.length > 0 ? 'degraded' : 'registered'
+        : 'registered',
+    evidenceCount: resultProviderIds.has(provider.id) ? 1 : 0,
+  }));
+  const readyLanguages = new Set(providers.filter((provider) => provider.status === 'ready').flatMap((provider) => provider.languages));
+  const unresolvedLanguages = languages.filter((language) => applicable.some((provider) => provider.languages.includes(language)) && !readyLanguages.has(language));
+  const reasonCodes = unique([
+    ...(applicable.length === 0 ? ['semantic.provider_unavailable'] : []),
+    ...(input.semanticNavigation.requested === 0 ? ['semantic.navigation_not_requested'] : []),
+    ...input.semanticNavigation.errors.map((error) => `semantic.${String(error.code ?? 'provider_error').toLowerCase()}`),
+    ...(unresolvedLanguages.length > 0 ? unresolvedLanguages.map((language) => `semantic.${language}_unproven`) : []),
+    ...(input.semanticNavigation.freshness === 'changed_during_query' ? ['semantic.source_changed_during_query'] : []),
+  ]);
+  const status = applicable.length === 0
+    ? 'unavailable' as const
+    : reasonCodes.length === 0 && unresolvedLanguages.length === 0
+      ? 'ready' as const
+      : 'degraded' as const;
+  return { required, status, providers, reasonCodes, compilerEvidenceRequired: status !== 'ready' };
+}
+
+function recentChanges(repoRoot: string, paths: string[]): ContextClosureReceipt['sourceEvidence']['recentChanges'] {
+  const args = ['-C', repoRoot, 'log', `-n${MAX_RECENT_CHANGES}`, '--format=%H%x09%cI%x09%s'];
+  const selected = unique(paths, 12);
+  if (selected.length > 0) args.push('--', ...selected);
+  const result = spawnSync('git', args, { encoding: 'utf8', timeout: 2_000, maxBuffer: 64 * 1024 });
+  if (result.status !== 0 || !result.stdout) return [];
+  return result.stdout.split(/\r?\n/).filter(Boolean).slice(0, MAX_RECENT_CHANGES).map((line) => {
+    const [revision = '', committedAt = '', ...summary] = line.split('	');
+    return { revision, committedAt, summary: summary.join('	').slice(0, 500) };
+  }).filter((entry) => entry.revision.length > 0);
+}
+
+export function buildContextClosureReceipt(input: BuildContextClosureInput): ContextClosureReceipt {
+  const sourceRevision = input.pack.readiness.sourceRevision?.trim();
+  if (!sourceRevision) throw new Error('CONTEXT_CLOSURE_SOURCE_REVISION_REQUIRED');
+  const project = loadProjectEngineeringContract({ repoRoot: input.repoRoot, sourceRevision });
+  const contract = project.status === 'ready' ? project.contract : undefined;
+  const currentPaths = unique([...input.pack.coverage.inspectedFiles, ...input.pack.files.map((file) => file.path)], MAX_CLOSURE_PATHS);
+  const testPaths = unique(input.pack.coverage.relevantTests.length > 0
+    ? input.pack.coverage.relevantTests
+    : currentPaths.filter((path) => /(^|\/)(tests?|__tests__)(\/|$)|\.(test|spec)\./i.test(path)), 24);
+  const languages = detectedLanguages(input.repoRoot, currentPaths);
+  const platforms = detectedPlatforms(input.repoRoot, contract);
+  const skills = resolveSkills(contract, requiredSkillKinds(languages, platforms));
+  const semanticTools = resolveSemanticTools(input, languages, contract);
+  const reasonCodes = unique([
+    ...input.pack.readiness.unresolvedReasonCodes,
+    ...(project.status === 'missing' ? ['project_contract.missing'] : []),
+    ...(skills.status === 'degraded' || skills.status === 'unavailable' ? skills.unresolvedKinds.map((kind) => `skill.${kind}_unresolved`) : []),
+    ...semanticTools.reasonCodes,
+  ], 80);
+  const status = input.pack.readiness.rawSource.status === 'unavailable' || input.pack.readiness.status === 'insufficient'
+    ? 'insufficient' as const
+    : reasonCodes.length > 0 || input.pack.readiness.status === 'degraded'
+      ? 'degraded' as const
+      : 'ready' as const;
+  const core = {
+    sourceRevision,
+    projectContractDigest: project.status === 'ready' ? project.receipt.contentDigest : null,
+    currentPaths,
+    testPaths,
+    languages,
+    platforms,
+    skillIds: skills.resolved.map((skill) => `${skill.id}@${skill.version ?? ''}`),
+    semanticProviders: semanticTools.providers.map((provider) => `${provider.providerId}:${provider.status}`),
+    reasonCodes,
+  };
+  const receiptId = `context_closure_${createHash('sha256').update(JSON.stringify(core)).digest('hex').slice(0, 32)}`;
+  const receipt: ContextClosureReceipt = {
+    schemaVersion: 1,
+    receiptId,
+    sourceRevision,
+    generatedAt: new Date().toISOString(),
+    contextPackSchemaVersion: input.pack.schemaVersion,
+    repository: {
+      branch: input.pack.git.branch,
+      dirty: input.pack.git.dirty,
+      ...(input.workId ? { workId: input.workId } : {}),
+      activeWorkIds: unique(input.activeWorkIds ?? [], 20),
+    },
+    ...(project.status === 'ready' ? { projectContract: project.receipt } : {}),
+    projectContractStatus: project.status,
+    guidance: {
+      status: input.pack.instructionContext.status,
+      paths: unique(input.pack.instructionContext.contracts.map((contractEntry) => contractEntry.path), 24),
+    },
+    detected: { languages, platforms },
+    skills,
+    semanticTools,
+    sourceEvidence: {
+      currentPaths,
+      testPaths,
+      recentChanges: input.includeRecentChanges ? recentChanges(input.repoRoot, currentPaths) : [],
+      rawSourceStatus: input.pack.readiness.rawSource.status,
+      structuralStatus: input.pack.structuralContext.status,
+    },
+    readiness: { status, reasonCodes },
+    provenance: { source: 'rh_context', contextGeneratedAt: input.pack.generatedAt },
+  };
+  return recordIssuedContextClosure(receipt);
+}