@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/context/cognitive-skill-canary.ts

@@ -0,0 +1,158 @@
+import type { AssistantContextResolution } from './assistant-context';
+
+export const COGNITIVE_SKILL_CANARY_VERSION = 'forge-cognitive-skill-canary/v1' as const;
+const MIN_PRIMARY_ACTIVATION_SCORE = 1;
+const MIN_PRIMARY_CRITICAL_MATCHES = 2;
+
+export type CognitiveSkillCanaryGate = 'covered' | 'fallback';
+
+export interface CognitiveSkillCanaryProfile {
+  id: string;
+  evaluationGate: CognitiveSkillCanaryGate;
+  semanticSkillIds: readonly string[];
+  criticalConcepts: readonly string[];
+}
+
+export interface CognitiveSkillCanaryClassification {
+  profileId: string;
+  status: CognitiveSkillCanaryGate;
+  evaluationGate: CognitiveSkillCanaryGate;
+  semanticSkillIds: string[];
+  matchedCriticalConcepts: string[];
+  missingCriticalConcepts: string[];
+  primaryMemoryId: string;
+  primaryScore: number;
+}
+
+export const COGNITIVE_SKILL_CANARY_PROFILES: readonly CognitiveSkillCanaryProfile[] = Object.freeze([
+  Object.freeze({
+    id: 'ios-product-self-explaining-interaction',
+    evaluationGate: 'fallback' as const,
+    semanticSkillIds: Object.freeze(['ios-engineering']),
+    criticalConcepts: Object.freeze([
+      'ios.product-design',
+      'product.user-job',
+      'product.interaction.self-explanatory',
+      'product.copy.invisible-rules',
+    ]),
+  }),
+  Object.freeze({
+    id: 'ios-interaction-state-single-owner',
+    evaluationGate: 'covered' as const,
+    semanticSkillIds: Object.freeze(['ios-engineering']),
+    criticalConcepts: Object.freeze([
+      'interaction.state-contract',
+      'state.single-owner',
+      'state.draft-boundary',
+      'external-surface.projection',
+      'single-write-chain',
+    ]),
+  }),
+  Object.freeze({
+    id: 'swiftui-state-ownership-performance',
+    evaluationGate: 'covered' as const,
+    semanticSkillIds: Object.freeze(['ios-engineering', 'swiftui-expert']),
+    criticalConcepts: Object.freeze([
+      'swiftui.state-ownership',
+      'swiftui.data-flow',
+      'swiftui.stable-identity',
+      'async.stale-result',
+    ]),
+  }),
+  Object.freeze({
+    id: 'swiftui-native-accessibility',
+    evaluationGate: 'covered' as const,
+    semanticSkillIds: Object.freeze(['ios-engineering', 'swiftui-expert']),
+    criticalConcepts: Object.freeze([
+      'swiftui.native-controls',
+      'accessibility.semantics',
+      'dynamic-type',
+    ]),
+  }),
+  Object.freeze({
+    id: 'swift-concurrency-isolation',
+    evaluationGate: 'covered' as const,
+    semanticSkillIds: Object.freeze(['swift-concurrency']),
+    criticalConcepts: Object.freeze([
+      'swift.concurrency',
+      'swift.concurrency.isolation',
+      'mainactor.ui-ownership',
+      'structured-concurrency',
+      'sendable.boundary',
+      'task.entry-isolation',
+    ]),
+  }),
+  Object.freeze({
+    id: 'ios-design-system-governance',
+    evaluationGate: 'covered' as const,
+    semanticSkillIds: Object.freeze(['ios-design-system']),
+    criticalConcepts: Object.freeze([
+      'ios.design-system',
+      'design-system.tokens',
+      'design-system.semantic-tokens',
+      'visual.single-source-of-truth',
+      'platform.system-first',
+    ]),
+  }),
+]);
+
+function overlap(concepts: ReadonlySet<string>, required: readonly string[]): string[] {
+  return required.filter((concept) => concepts.has(concept));
+}
+
+export function classifyCognitiveSkillCanary(context: AssistantContextResolution): CognitiveSkillCanaryClassification | undefined {
+  const primary = context.items.find((item) => item.activation);
+  if (!primary?.activation || primary.activation.score < MIN_PRIMARY_ACTIVATION_SCORE) return undefined;
+
+  const primaryConcepts = new Set(primary.activation.concepts);
+  const ranked = COGNITIVE_SKILL_CANARY_PROFILES
+    .map((profile) => {
+      const matched = overlap(primaryConcepts, profile.criticalConcepts);
+      return { profile, matched, ratio: matched.length / profile.criticalConcepts.length };
+    })
+    .filter((candidate) => candidate.matched.length >= MIN_PRIMARY_CRITICAL_MATCHES)
+    .sort((left, right) =>
+      right.ratio - left.ratio
+      || right.matched.length - left.matched.length
+      || left.profile.id.localeCompare(right.profile.id));
+  const selected = ranked[0];
+  if (!selected) return undefined;
+
+  const deliveredConcepts = new Set(context.items.flatMap((item) => item.activation?.concepts ?? []));
+  const matchedCriticalConcepts = overlap(deliveredConcepts, selected.profile.criticalConcepts);
+  const matchedSet = new Set(matchedCriticalConcepts);
+  const missingCriticalConcepts = selected.profile.criticalConcepts.filter((concept) => !matchedSet.has(concept));
+  const status: CognitiveSkillCanaryGate = selected.profile.evaluationGate === 'covered' && missingCriticalConcepts.length === 0
+    ? 'covered'
+    : 'fallback';
+
+  return {
+    profileId: selected.profile.id,
+    status,
+    evaluationGate: selected.profile.evaluationGate,
+    semanticSkillIds: [...selected.profile.semanticSkillIds],
+    matchedCriticalConcepts,
+    missingCriticalConcepts,
+    primaryMemoryId: primary.id,
+    primaryScore: primary.activation.score,
+  };
+}
+
+export function cognitiveSkillCanarySignal(context: AssistantContextResolution): string | undefined {
+  const result = classifyCognitiveSkillCanary(context);
+  if (!result) return undefined;
+  const skills = result.semanticSkillIds.join(',');
+  if (result.status === 'covered') {
+    return `advisory:cognitive_skill_canary:v1:covered:profile=${result.profileId};semantic_skill_read=skip;skills=${skills};procedures=typed_capabilities`;
+  }
+  const reason = result.missingCriticalConcepts.length > 0
+    ? `missing_critical=${result.missingCriticalConcepts.join(',')}`
+    : 'evaluation_gate=not_covered';
+  return `advisory:cognitive_skill_canary:v1:fallback:profile=${result.profileId};semantic_skill_read=retain;skills=${skills};${reason};procedures=typed_capabilities`;
+}
+
+export function applyCognitiveSkillCanary(context: AssistantContextResolution): AssistantContextResolution {
+  const signal = cognitiveSkillCanarySignal(context);
+  if (!signal || context.gaps.includes(signal)) return context;
+  return { ...context, gaps: [...context.gaps, signal] };
+}

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

@@ -0,0 +1,305 @@
+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 canonicalReceiptValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalReceiptValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+      .map(([key, entry]) => [key, canonicalReceiptValue(entry)]),
+  );
+}
+
+function fullReceiptDigest(receipt: ContextClosureReceipt): string {
+  return createHash('sha256').update(JSON.stringify(canonicalReceiptValue(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 resolvedByKey = new Map<string, ContextClosureSkillResolution>();
+  const covered = new Set<string>();
+  const record = (skill: { id: string; version?: string }, matchedKinds: string[]) => {
+    if (matchedKinds.length === 0) return;
+    matchedKinds.forEach((kind) => covered.add(kind));
+    const key = `${skill.id}@${skill.version ?? ''}`;
+    const existing = resolvedByKey.get(key);
+    resolvedByKey.set(key, {
+      ...skill,
+      source: 'project_contract',
+      matchedKinds: [...new Set([...(existing?.matchedKinds ?? []), ...matchedKinds])].sort(),
+    });
+  };
+
+  for (const binding of contract?.skillBindings ?? []) {
+    const declaredKinds = new Set(binding.kinds.map((kind) => kind.toLowerCase()));
+    record(
+      { id: binding.id, ...(binding.version === undefined ? {} : { version: binding.version }) },
+      requiredKinds.filter((kind) => declaredKinds.has(kind.toLowerCase())),
+    );
+  }
+
+  for (const skill of (contract?.skillRefs ?? []).map(parseSkillRef)) {
+    const lower = skill.id.toLowerCase();
+    record(skill, requiredKinds.filter((kind) => lower.includes(kind.toLowerCase())));
+  }
+
+  const resolved = [...resolvedByKey.values()];
+  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.provider === 'string'
+      ? record.provider
+      : typeof record.providerId === 'string'
+        ? record.providerId
+        : typeof nested?.provider === 'string'
+          ? nested.provider
+          : 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);
+}

package/src/runtime/context/context-pack-process.ts

@@ -0,0 +1,103 @@
+import { existsSync, lstatSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { McpPolicy } from '../../../adapters/mcp/types';
+import type {
+  ControllerContextPackOptions,
+  ControllerContextPackProjection,
+} from '../../cli/controller/context/types';
+import { resolveBunExecutable } from '../shared/process-environment';
+import { runBoundedChild } from '../shared/bounded-child-supervisor';
+
+const CONTEXT_PACK_SIDECAR_ENTRYPOINT = 'forge-context-pack' as const;
+const CONTEXT_PACK_TIMEOUT_MS = 60_000;
+const CONTEXT_PACK_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+interface ContextPackSidecarManifestRecord {
+  contextPackEntrypoint?: unknown;
+  contextPackArtifactIdentity?: unknown;
+}
+
+interface ContextPackSidecarResponse {
+  schemaVersion: 1;
+  pack: ControllerContextPackProjection;
+}
+
+function releaseManifestArgument(argv: readonly string[]): string | undefined {
+  const index = argv.indexOf('--release-manifest');
+  const value = index >= 0 ? argv[index + 1]?.trim() : undefined;
+  return value ? resolve(value) : undefined;
+}
+
+export function resolveContextPackSidecarCommand(
+  argv: readonly string[] = process.argv,
+): { executable: string; args: string[]; cwd?: string } {
+  const manifestPath = releaseManifestArgument(argv);
+  if (manifestPath) {
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as ContextPackSidecarManifestRecord;
+    if (parsed.contextPackEntrypoint !== CONTEXT_PACK_SIDECAR_ENTRYPOINT) {
+      throw new Error('CONTEXT_PACK_SIDECAR_MANIFEST_MISSING');
+    }
+    const identity = typeof parsed.contextPackArtifactIdentity === 'string'
+      ? parsed.contextPackArtifactIdentity.trim()
+      : '';
+    if (!/^sha256:[a-f0-9]{64}$/i.test(identity)) {
+      throw new Error('CONTEXT_PACK_SIDECAR_IDENTITY_INVALID');
+    }
+    const executable = join(dirname(manifestPath), CONTEXT_PACK_SIDECAR_ENTRYPOINT);
+    if (!existsSync(executable)) throw new Error('CONTEXT_PACK_SIDECAR_MISSING');
+    const status = lstatSync(executable);
+    if (status.isSymbolicLink() || !status.isFile() || (status.mode & 0o111) === 0) {
+      throw new Error('CONTEXT_PACK_SIDECAR_NOT_EXECUTABLE');
+    }
+    return {
+      executable,
+      args: ['--release-manifest', manifestPath],
+      cwd: dirname(manifestPath),
+    };
+  }
+
+  // Deliberately construct this development path at runtime. A literal new URL()
+  // to a .ts sidecar makes Bun include the sidecar's heavy Context Plane import
+  // graph in the long-lived Runtime bundle.
+  const entry = resolve(process.cwd(), 'adapters', 'mcp', 'runtime-gateway', 'context-pack-sidecar.ts');
+  if (!existsSync(entry)) throw new Error('CONTEXT_PACK_SOURCE_SIDECAR_MISSING');
+  return {
+    executable: resolveBunExecutable(process.execPath, process.env),
+    args: [entry],
+    cwd: process.cwd(),
+  };
+}
+
+export async function buildControllerContextPackInSidecar(input: {
+  repoRoot: string;
+  policy: McpPolicy;
+  options: ControllerContextPackOptions;
+}): Promise<ControllerContextPackProjection> {
+  const command = resolveContextPackSidecarCommand();
+  const envelope = JSON.stringify({
+    schemaVersion: 1,
+    repoRoot: resolve(input.repoRoot),
+    policy: input.policy,
+    options: input.options,
+  });
+  const execution = await runBoundedChild(command.executable, command.args, {
+    cwd: command.cwd ?? input.repoRoot,
+    input: envelope,
+    timeoutMs: CONTEXT_PACK_TIMEOUT_MS,
+    maxOutputBytes: CONTEXT_PACK_MAX_OUTPUT_BYTES,
+  });
+  if (execution.status !== 0 || execution.timedOut || execution.failureCode) {
+    const detail = (execution.stderr || execution.stdout || execution.error || execution.failureCode || 'context-pack sidecar failed').trim();
+    throw new Error(`CONTEXT_PACK_SIDECAR_FAILED: ${detail.slice(0, 2_000)}`);
+  }
+  let response: ContextPackSidecarResponse;
+  try {
+    response = JSON.parse(execution.stdout) as ContextPackSidecarResponse;
+  } catch (error) {
+    throw new Error(`CONTEXT_PACK_SIDECAR_RESPONSE_INVALID: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (response.schemaVersion !== 1 || !response.pack || response.pack.schemaVersion !== 11) {
+    throw new Error('CONTEXT_PACK_SIDECAR_RESPONSE_INVALID: unsupported response');
+  }
+  return response.pack;
+}