@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -0,0 +1,211 @@
+import type { CredentialReference } from '../../../packages/kernel/identity/api/index';
+import type { ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { listControlPlaneRecords, readControlPlaneRecord, writeControlPlaneRecord, type ControlPlaneRecord } from '../control-plane/persistence/sqlite-store';
+import { assertControlPlaneMetadataPayload } from '../control-plane/persistence/metadata-payload-policy';
+import type { RouteContextHints } from '../control-plane/routing/route-policy';
+
+export const CONTEXT_RECORD_NAMESPACE = 'context_record';
+export const MAX_CONTEXT_RECORDS = 1_000;
+export const MAX_CONTEXT_RECORD_BYTES = 16 * 1024;
+export const DEFAULT_CONTEXT_MAX_ITEMS = 16;
+export const MAX_CONTEXT_MAX_ITEMS = 32;
+export const DEFAULT_CONTEXT_MAX_BYTES = 24 * 1024;
+export const MAX_CONTEXT_MAX_BYTES = 64 * 1024;
+export const DEFAULT_CONTEXT_MAX_TOKENS = 4_096;
+export const MAX_CONTEXT_MAX_TOKENS = 8_192;
+
+export type ContextScope = ScopeRef | { schemaVersion: 1; kind: 'global'; id: 'global' };
+export type ContextProvenanceSource = 'user' | 'system' | 'repository' | 'synced' | 'migration';
+
+export type ContextValue =
+  | { type: 'routing_preference'; intent: string; preferredProviderId: string; allowedProviderIds?: string[]; forbiddenProviderIds?: string[] }
+  | { type: 'policy'; statement: string; tags?: string[] }
+  | { type: 'procedure'; title: string; steps: string[]; tags?: string[] }
+  | { type: 'capability_intent'; capabilityId: string; preferredProviderId?: string }
+  | { type: 'credential_reference'; reference: CredentialReference };
+
+export interface ContextRecord {
+  schemaVersion: 1;
+  contextId: string;
+  scope: ContextScope;
+  priority: number;
+  value: ContextValue;
+  provenance: {
+    source: ContextProvenanceSource;
+    recordedAt: string;
+    sourceRef?: string;
+  };
+  expiresAt?: string;
+  updatedAt: string;
+}
+
+export interface ContextResolution {
+  schemaVersion: 1;
+  records: Array<{ record: ContextRecord; storeRevision: number; rank: number }>;
+  routeHints: RouteContextHints;
+  estimatedTokens: number;
+  bytes: number;
+  truncated: boolean;
+}
+
+const SOURCE_RANK: Record<ContextProvenanceSource, number> = { user: 50, system: 40, repository: 30, synced: 20, migration: 10 };
+const SCOPE_RANK: Record<ContextScope['kind'], number> = { global: 0, workspace: 10, project: 20, requirement: 30, plan: 40, plan_step: 45, work: 50 };
+
+function contextScopeKey(scope: ContextScope): string {
+  if (!Object.hasOwn(SCOPE_RANK, scope.kind)) throw new Error('CONTEXT_SCOPE_KIND_INVALID');
+  const id = scope.id.trim();
+  if (!id || id.length > 512 || (scope.kind === 'global' && id !== 'global')) throw new Error('CONTEXT_SCOPE_ID_INVALID');
+  return `${scope.kind}:${id}`;
+}
+
+function boundedStrings(values: readonly string[] | undefined, max = 32): string[] | undefined {
+  if (!values) return undefined;
+  const result = [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort().slice(0, max);
+  return result.length ? result : undefined;
+}
+
+function validateCredentialReference(reference: CredentialReference): void {
+  if (!['env', 'file', 'store', 'keychain', 'secret_ref'].includes(reference.kind)) throw new Error('CONTEXT_CREDENTIAL_REFERENCE_KIND_INVALID');
+  const value = reference.reference.trim();
+  if (!value || value.length > 512) throw new Error('CONTEXT_CREDENTIAL_REFERENCE_INVALID');
+  if (reference.kind === 'env' && !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value)) throw new Error('CONTEXT_CREDENTIAL_ENV_REFERENCE_INVALID');
+}
+
+export function validateContextRecord(record: ContextRecord): ContextRecord {
+  if (record.schemaVersion !== 1) throw new Error('CONTEXT_RECORD_SCHEMA_INVALID');
+  const contextId = record.contextId.trim();
+  if (!contextId || contextId.length > 160) throw new Error('CONTEXT_RECORD_ID_INVALID');
+  contextScopeKey(record.scope);
+  if (!Number.isSafeInteger(record.priority) || record.priority < 0 || record.priority > 1_000) throw new Error('CONTEXT_RECORD_PRIORITY_INVALID');
+  if (!Number.isFinite(Date.parse(record.provenance.recordedAt)) || !Number.isFinite(Date.parse(record.updatedAt))) throw new Error('CONTEXT_RECORD_TIMESTAMP_INVALID');
+  if (record.expiresAt && !Number.isFinite(Date.parse(record.expiresAt))) throw new Error('CONTEXT_RECORD_EXPIRY_INVALID');
+  if (!Object.hasOwn(SOURCE_RANK, record.provenance.source)) throw new Error('CONTEXT_RECORD_PROVENANCE_INVALID');
+  if (record.value.type === 'routing_preference') {
+    if (!record.value.intent.trim() || !record.value.preferredProviderId.trim()) throw new Error('CONTEXT_ROUTING_PREFERENCE_INVALID');
+    record.value.allowedProviderIds = boundedStrings(record.value.allowedProviderIds);
+    record.value.forbiddenProviderIds = boundedStrings(record.value.forbiddenProviderIds);
+  } else if (record.value.type === 'policy') {
+    if (!record.value.statement.trim()) throw new Error('CONTEXT_POLICY_EMPTY');
+    record.value.tags = boundedStrings(record.value.tags, 16);
+  } else if (record.value.type === 'procedure') {
+    if (!record.value.title.trim() || record.value.steps.length < 1 || record.value.steps.length > 32 || record.value.steps.some((step) => !step.trim())) throw new Error('CONTEXT_PROCEDURE_INVALID');
+    record.value.tags = boundedStrings(record.value.tags, 16);
+  } else if (record.value.type === 'capability_intent') {
+    if (!record.value.capabilityId.trim()) throw new Error('CONTEXT_CAPABILITY_INTENT_INVALID');
+  } else if (record.value.type === 'credential_reference') {
+    validateCredentialReference(record.value.reference);
+  } else {
+    throw new Error('CONTEXT_VALUE_TYPE_INVALID');
+  }
+  assertControlPlaneMetadataPayload(record, 'context_record');
+  if (Buffer.byteLength(JSON.stringify(record), 'utf8') > MAX_CONTEXT_RECORD_BYTES) throw new Error('CONTEXT_RECORD_TOO_LARGE');
+  return record;
+}
+
+export function writeContextRecord(input: { controllerHome: string; record: ContextRecord; expectedRevision: number | null }): ControlPlaneRecord<ContextRecord> {
+  const record = validateContextRecord(structuredClone(input.record));
+  return writeControlPlaneRecord(input.controllerHome, {
+    namespace: CONTEXT_RECORD_NAMESPACE,
+    scope: contextScopeKey(record.scope),
+    key: record.contextId,
+    schemaVersion: 1,
+    value: record,
+    action: 'context_record_write',
+    expectedRevision: input.expectedRevision,
+  });
+}
+
+export function readContextRecord(input: { controllerHome: string; scope: ContextScope; contextId: string }): ControlPlaneRecord<ContextRecord> | undefined {
+  return readControlPlaneRecord<ContextRecord>(input.controllerHome, CONTEXT_RECORD_NAMESPACE, contextScopeKey(input.scope), input.contextId.trim());
+}
+
+function estimateTokens(value: string): number {
+  return Math.ceil(value.length / 4);
+}
+
+function scopeMatchRank(scope: ContextScope, requested: readonly ContextScope[]): number | undefined {
+  if (scope.kind === 'global') return 0;
+  const match = requested.find((candidate) => candidate.kind === scope.kind && candidate.id === scope.id);
+  return match ? SCOPE_RANK[scope.kind] : undefined;
+}
+
+function relevance(record: ContextRecord, intent: string | undefined, capabilities: ReadonlySet<string>): number {
+  if (record.value.type === 'routing_preference') return record.value.intent === intent ? 30 : record.value.intent === '*' ? 10 : -1000;
+  if (record.value.type === 'capability_intent') return capabilities.has(record.value.capabilityId) ? 25 : 0;
+  return 0;
+}
+
+export function resolveContextPlane(input: {
+  controllerHome: string;
+  scopes?: readonly ContextScope[];
+  intent?: string;
+  capabilityIds?: readonly string[];
+  now?: string;
+  maxItems?: number;
+  maxBytes?: number;
+  maxTokens?: number;
+}): ContextResolution {
+  const now = input.now ?? new Date().toISOString();
+  const nowEpoch = Date.parse(now);
+  if (!Number.isFinite(nowEpoch)) throw new Error('CONTEXT_RESOLUTION_NOW_INVALID');
+  const scopes = input.scopes ?? [];
+  const capabilities = new Set(input.capabilityIds ?? []);
+  const maxItems = Math.max(1, Math.min(Math.trunc(input.maxItems ?? DEFAULT_CONTEXT_MAX_ITEMS), MAX_CONTEXT_MAX_ITEMS));
+  const maxBytes = Math.max(1_024, Math.min(Math.trunc(input.maxBytes ?? DEFAULT_CONTEXT_MAX_BYTES), MAX_CONTEXT_MAX_BYTES));
+  const maxTokens = Math.max(256, Math.min(Math.trunc(input.maxTokens ?? DEFAULT_CONTEXT_MAX_TOKENS), MAX_CONTEXT_MAX_TOKENS));
+  const candidates = listControlPlaneRecords<ContextRecord>(input.controllerHome, { namespace: CONTEXT_RECORD_NAMESPACE, limit: MAX_CONTEXT_RECORDS })
+    .flatMap((stored) => {
+      try {
+        const record = validateContextRecord(structuredClone(stored.value));
+        if (record.expiresAt && Date.parse(record.expiresAt) <= nowEpoch) return [];
+        const scopeRank = scopeMatchRank(record.scope, scopes);
+        if (scopeRank === undefined) return [];
+        const relevanceRank = relevance(record, input.intent, capabilities);
+        if (relevanceRank < 0) return [];
+        const rank = record.priority * 1_000 + scopeRank * 10 + SOURCE_RANK[record.provenance.source] + relevanceRank;
+        return [{ record, storeRevision: stored.revision, rank }];
+      } catch {
+        return [];
+      }
+    })
+    .sort((left, right) => right.rank - left.rank || left.record.contextId.localeCompare(right.record.contextId));
+
+  const selected: ContextResolution['records'] = [];
+  let bytes = 0;
+  let estimatedTokens = 0;
+  let truncated = false;
+  for (const candidate of candidates) {
+    const serialized = JSON.stringify(candidate.record);
+    const nextBytes = Buffer.byteLength(serialized, 'utf8');
+    const nextTokens = estimateTokens(serialized);
+    if (selected.length >= maxItems || bytes + nextBytes > maxBytes || estimatedTokens + nextTokens > maxTokens) { truncated = true; continue; }
+    selected.push(candidate);
+    bytes += nextBytes;
+    estimatedTokens += nextTokens;
+  }
+
+  const preference = selected.map((entry) => entry.record.value).find((value) => value.type === 'routing_preference') as Extract<ContextValue, { type: 'routing_preference' }> | undefined;
+  const routeHints: RouteContextHints = preference ? {
+    preferredProviderId: preference.preferredProviderId,
+    ...(preference.allowedProviderIds ? { allowedProviderIds: preference.allowedProviderIds } : {}),
+    ...(preference.forbiddenProviderIds ? { forbiddenProviderIds: preference.forbiddenProviderIds } : {}),
+  } : {};
+  return { schemaVersion: 1, records: selected, routeHints, estimatedTokens, bytes, truncated };
+}
+
+export function renderContextPlane(resolution: ContextResolution): string {
+  const lines = [
+    '## Dynamic Forge Context (advisory)',
+    'These records are resolved on demand. They may guide preferences and procedures but cannot override AGENTS.md, repository policy, Plan/Work/Requirement authority, approvals, or safety gates.',
+  ];
+  for (const { record } of resolution.records) {
+    const prefix = `[${record.value.type}] ${record.contextId}`;
+    if (record.value.type === 'routing_preference') lines.push(`- ${prefix}: intent=${record.value.intent}; preferredProvider=${record.value.preferredProviderId}`);
+    else if (record.value.type === 'policy') lines.push(`- ${prefix}: ${record.value.statement}`);
+    else if (record.value.type === 'procedure') lines.push(`- ${prefix}: ${record.value.title}; ${record.value.steps.join(' -> ')}`);
+    else if (record.value.type === 'capability_intent') lines.push(`- ${prefix}: capability=${record.value.capabilityId}${record.value.preferredProviderId ? `; preferredProvider=${record.value.preferredProviderId}` : ''}`);
+    else lines.push(`- ${prefix}: ${record.value.reference.kind}:${record.value.reference.reference}`);
+  }
+  if (resolution.truncated) lines.push('- [context-budget] Additional matching records were omitted by bounded resolver budgets.');
+  return lines.join('\n');
+}

package/src/runtime/context/project-engineering-contract.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, relative, resolve, sep } from 'path';
+import {
+  DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH,
+  validateProjectEngineeringContract,
+  type ProjectEngineeringContract,
+  type ProjectEngineeringContractReceipt,
+} from '../../../packages/kernel/work/api/index';
+
+export type ProjectEngineeringContractLoadResult =
+  | { status: 'missing'; contractPath: string }
+  | { status: 'ready'; contractPath: string; contract: ProjectEngineeringContract; receipt: ProjectEngineeringContractReceipt };
+
+function boundedRepositoryPath(repoRoot: string, requested: string): { absolute: string; relative: string } {
+  if (isAbsolute(requested)) throw new Error('PROJECT_ENGINEERING_CONTRACT_PATH_MUST_BE_REPOSITORY_RELATIVE');
+  const root = resolve(repoRoot);
+  const absolute = resolve(root, requested);
+  const rel = relative(root, absolute).split(sep).join('/');
+  if (!rel || rel.startsWith('../') || rel === '..') throw new Error('PROJECT_ENGINEERING_CONTRACT_PATH_OUTSIDE_REPOSITORY');
+  return { absolute, relative: rel };
+}
+
+export function loadProjectEngineeringContract(input: {
+  repoRoot: string;
+  sourceRevision: string;
+  contractPath?: string;
+  now?: () => string;
+}): ProjectEngineeringContractLoadResult {
+  const sourceRevision = input.sourceRevision.trim();
+  if (!sourceRevision) throw new Error('PROJECT_ENGINEERING_CONTRACT_SOURCE_REVISION_REQUIRED');
+  const path = boundedRepositoryPath(input.repoRoot, input.contractPath ?? DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH);
+  if (!existsSync(path.absolute)) return { status: 'missing', contractPath: path.relative };
+  const raw = readFileSync(path.absolute, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('PROJECT_ENGINEERING_CONTRACT_JSON_INVALID');
+  }
+  const contract = validateProjectEngineeringContract(parsed);
+  return {
+    status: 'ready',
+    contractPath: path.relative,
+    contract,
+    receipt: {
+      schemaVersion: 1,
+      contractPath: path.relative,
+      projectId: contract.projectId,
+      contractId: contract.contractId,
+      contractVersion: contract.contractVersion,
+      sourceRevision,
+      contentDigest: createHash('sha256').update(raw).digest('hex'),
+      provenance: {
+        source: 'repository',
+        loadedAt: (input.now ?? (() => new Date().toISOString()))(),
+      },
+    },
+  };
+}

package/src/runtime/control-plane/bootstrap/capability-provider.ts

@@ -0,0 +1,74 @@
+import type { AssistantPluginManifest } from '../../plugins/types';
+
+export interface BootstrapCapabilityCatalogEntry {
+  id: string;
+  name: string;
+  platforms: NodeJS.Platform[];
+  compatible: boolean;
+  semanticCapabilities?: string[];
+}
+
+export type BootstrapCapabilityProviderStatus = 'ready' | 'repairable' | 'installable' | 'unsupported';
+
+export interface BootstrapCapabilityProviderResolution {
+  capabilityId: string;
+  status: BootstrapCapabilityProviderStatus;
+  providerId?: string;
+  providerName?: string;
+  summary: string;
+}
+
+function manifestProvides(manifest: AssistantPluginManifest, capabilityId: string): boolean {
+  return manifest.capabilities.some((capability) => capability.capabilityId === capabilityId);
+}
+
+export function resolveBootstrapCapabilityProviders(input: {
+  capabilityIntents: readonly string[];
+  installedManifests: readonly AssistantPluginManifest[];
+  catalog: readonly BootstrapCapabilityCatalogEntry[];
+}): BootstrapCapabilityProviderResolution[] {
+  return [...new Set(input.capabilityIntents.map((value) => value.trim()).filter(Boolean))]
+    .sort()
+    .map((capabilityId) => {
+      const installed = input.installedManifests
+        .filter((manifest) => manifestProvides(manifest, capabilityId))
+        .sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+      const ready = installed.find((manifest) => manifest.enabled && manifest.lifecycle.state === 'enabled' && manifest.health.ready);
+      if (ready) {
+        return {
+          capabilityId,
+          status: 'ready' as const,
+          providerId: ready.pluginId,
+          providerName: ready.displayName,
+          summary: `${ready.displayName} provides ${capabilityId} and is ready.`,
+        };
+      }
+      const repairable = installed[0];
+      if (repairable) {
+        return {
+          capabilityId,
+          status: 'repairable' as const,
+          providerId: repairable.pluginId,
+          providerName: repairable.displayName,
+          summary: `${repairable.displayName} provides ${capabilityId} but is ${repairable.health.state}.`,
+        };
+      }
+      const catalog = input.catalog
+        .filter((entry) => entry.compatible && entry.semanticCapabilities?.includes(capabilityId))
+        .sort((left, right) => left.id.localeCompare(right.id))[0];
+      if (catalog) {
+        return {
+          capabilityId,
+          status: 'installable' as const,
+          providerId: catalog.id,
+          providerName: catalog.name,
+          summary: `${catalog.name} can provide ${capabilityId} on this platform.`,
+        };
+      }
+      return {
+        capabilityId,
+        status: 'unsupported' as const,
+        summary: `No installed or compatible official provider advertises ${capabilityId}.`,
+      };
+    });
+}

package/src/runtime/control-plane/bootstrap/control-api.ts

@@ -0,0 +1,57 @@
+import { resolveControllerHome } from '../../../cli/repositories/controller-home';
+import { buildBootstrapSnapshot } from './state-machine';
+import { readBootstrapSnapshot, writeBootstrapSnapshot } from './store';
+import type { BootstrapAction, BootstrapEvaluation, BootstrapSnapshot } from './types';
+
+export interface BootstrapControlAdapter {
+  observe(): Promise<BootstrapEvaluation> | BootstrapEvaluation;
+  /** Optional synchronous observation for product surfaces that are intentionally synchronous. */
+  observeSync?(): BootstrapEvaluation;
+  perform?(action: BootstrapAction): Promise<void> | void;
+}
+
+export function reconcileBootstrapSnapshot(input: { controllerHome: string; evaluation: BootstrapEvaluation; now?: () => Date }): BootstrapSnapshot {
+  const controllerHome = resolveControllerHome(input.controllerHome);
+  const previous = readBootstrapSnapshot(controllerHome);
+  const snapshot = buildBootstrapSnapshot({ controllerHome, evaluation: input.evaluation, previous, now: input.now });
+  return writeBootstrapSnapshot(controllerHome, snapshot);
+}
+
+export function readBootstrapControlState(controllerHome: string): BootstrapSnapshot | undefined {
+  return readBootstrapSnapshot(resolveControllerHome(controllerHome));
+}
+
+export interface BootstrapControlApi {
+  read(): BootstrapSnapshot | undefined;
+  refresh(): Promise<BootstrapSnapshot>;
+  refreshSync(): BootstrapSnapshot;
+  act(actionId: string): Promise<BootstrapSnapshot>;
+}
+
+export function createBootstrapControlApi(input: {
+  controllerHome: string;
+  adapter: BootstrapControlAdapter;
+  now?: () => Date;
+}): BootstrapControlApi {
+  const controllerHome = resolveControllerHome(input.controllerHome);
+  const persist = (evaluation: BootstrapEvaluation): BootstrapSnapshot => reconcileBootstrapSnapshot({ controllerHome, evaluation, now: input.now });
+  const refresh = async (): Promise<BootstrapSnapshot> => persist(await input.adapter.observe());
+  const refreshSync = (): BootstrapSnapshot => {
+    if (!input.adapter.observeSync) throw new Error('BOOTSTRAP_SYNC_OBSERVER_UNAVAILABLE');
+    return persist(input.adapter.observeSync());
+  };
+  return {
+    read: () => readBootstrapSnapshot(controllerHome),
+    refresh,
+    refreshSync,
+    act: async (actionId: string) => {
+      const snapshot = await refresh();
+      const action = snapshot.actions.find((entry) => entry.id === actionId);
+      if (!action) throw new Error(`BOOTSTRAP_ACTION_NOT_FOUND: ${actionId}`);
+      if (action.owner === 'user') throw new Error(`BOOTSTRAP_USER_ACTION_REQUIRED: ${actionId}`);
+      if (!input.adapter.perform) throw new Error(`BOOTSTRAP_ACTION_EXECUTOR_UNAVAILABLE: ${actionId}`);
+      await input.adapter.perform(action);
+      return refresh();
+    },
+  };
+}

package/src/runtime/control-plane/bootstrap/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './state-machine';
+export * from './store';
+export * from './control-api';
+export * from './capability-provider';

package/src/runtime/control-plane/bootstrap/state-machine.ts

@@ -0,0 +1,141 @@
+import { createHash } from 'crypto';
+import type {
+  BootstrapAction,
+  BootstrapBlocker,
+  BootstrapDesiredState,
+  BootstrapEvaluation,
+  BootstrapObservation,
+  BootstrapSnapshot,
+  BootstrapStatus,
+  BootstrapStep,
+} from './types';
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
+}
+
+function byId<T extends { id: string }>(values: readonly T[]): T[] {
+  return [...values].sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function normalizeDesired(value: BootstrapDesiredState): BootstrapDesiredState {
+  return {
+    ...value,
+    controllers: [...new Set([value.primaryController, ...value.controllers])].sort(),
+    capabilityIntents: uniqueSorted(value.capabilityIntents),
+    connectivity: {
+      ...value.connectivity,
+      ...(value.connectivity.endpoint?.trim() ? { endpoint: value.connectivity.endpoint.trim() } : { endpoint: undefined }),
+      ...(value.connectivity.tunnelId?.trim() ? { tunnelId: value.connectivity.tunnelId.trim() } : { tunnelId: undefined }),
+    },
+  };
+}
+
+function normalizedObservations(values: readonly BootstrapObservation[]): BootstrapObservation[] {
+  return byId(values).map((value) => ({
+    ...value,
+    summary: value.summary.trim(),
+    reasonCodes: value.reasonCodes ? uniqueSorted(value.reasonCodes) : undefined,
+  }));
+}
+
+function normalizedActions(values: readonly BootstrapAction[]): BootstrapAction[] {
+  return byId(values).map((value) => ({ ...value, summary: value.summary.trim() }));
+}
+
+function normalizedBlockers(values: readonly BootstrapBlocker[]): BootstrapBlocker[] {
+  return [...values]
+    .sort((left, right) => left.code.localeCompare(right.code))
+    .map((value) => ({ ...value, actionIds: uniqueSorted(value.actionIds) }));
+}
+
+function normalizedSteps(values: readonly BootstrapStep[]): BootstrapStep[] {
+  return byId(values).map((value) => ({
+    ...value,
+    dependsOn: uniqueSorted(value.dependsOn),
+    observationIds: uniqueSorted(value.observationIds),
+    blockerCodes: uniqueSorted(value.blockerCodes),
+    actionIds: uniqueSorted(value.actionIds),
+  }));
+}
+
+function assertUnique(label: string, values: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (!value.trim()) throw new Error(`BOOTSTRAP_INVALID_${label.toUpperCase()}: blank identifier`);
+    if (seen.has(value)) throw new Error(`BOOTSTRAP_DUPLICATE_${label.toUpperCase()}: ${value}`);
+    seen.add(value);
+  }
+}
+
+function assertReferences(evaluation: BootstrapEvaluation): void {
+  assertUnique('observation', evaluation.observations.map((entry) => entry.id));
+  assertUnique('action', evaluation.actions.map((entry) => entry.id));
+  assertUnique('blocker', evaluation.blockers.map((entry) => entry.code));
+  assertUnique('step', evaluation.steps.map((entry) => entry.id));
+  const observations = new Set(evaluation.observations.map((entry) => entry.id));
+  const actions = new Set(evaluation.actions.map((entry) => entry.id));
+  const blockers = new Set(evaluation.blockers.map((entry) => entry.code));
+  const steps = new Set(evaluation.steps.map((entry) => entry.id));
+  for (const step of evaluation.steps) {
+    for (const id of step.observationIds) if (!observations.has(id)) throw new Error(`BOOTSTRAP_OBSERVATION_NOT_FOUND: ${step.id}:${id}`);
+    for (const id of step.actionIds) if (!actions.has(id)) throw new Error(`BOOTSTRAP_ACTION_NOT_FOUND: ${step.id}:${id}`);
+    for (const code of step.blockerCodes) if (!blockers.has(code)) throw new Error(`BOOTSTRAP_BLOCKER_NOT_FOUND: ${step.id}:${code}`);
+    for (const dependency of step.dependsOn) if (!steps.has(dependency)) throw new Error(`BOOTSTRAP_STEP_DEPENDENCY_NOT_FOUND: ${step.id}:${dependency}`);
+  }
+  for (const blocker of evaluation.blockers) {
+    if (!steps.has(blocker.stepId)) throw new Error(`BOOTSTRAP_BLOCKER_STEP_NOT_FOUND: ${blocker.code}:${blocker.stepId}`);
+    for (const actionId of blocker.actionIds) if (!actions.has(actionId)) throw new Error(`BOOTSTRAP_BLOCKER_ACTION_NOT_FOUND: ${blocker.code}:${actionId}`);
+  }
+}
+
+function statusFor(steps: readonly BootstrapStep[], blockers: readonly BootstrapBlocker[]): BootstrapStatus {
+  if (blockers.length > 0 || steps.some((step) => step.state === 'blocked')) return 'blocked';
+  if (steps.length > 0 && steps.every((step) => step.state === 'ready' || step.state === 'skipped')) return 'ready';
+  return 'in_progress';
+}
+
+function fingerprintPayload(evaluation: BootstrapEvaluation): unknown {
+  return {
+    desired: normalizeDesired(evaluation.desired),
+    observations: normalizedObservations(evaluation.observations).map(({ observedAt: _observedAt, ...rest }) => rest),
+    steps: normalizedSteps(evaluation.steps),
+    blockers: normalizedBlockers(evaluation.blockers),
+    actions: normalizedActions(evaluation.actions),
+  };
+}
+
+export function bootstrapStateFingerprint(evaluation: BootstrapEvaluation): string {
+  return createHash('sha256').update(JSON.stringify(fingerprintPayload(evaluation))).digest('hex');
+}
+
+export function buildBootstrapSnapshot(input: {
+  controllerHome: string;
+  evaluation: BootstrapEvaluation;
+  previous?: BootstrapSnapshot;
+  now?: () => Date;
+}): BootstrapSnapshot {
+  assertReferences(input.evaluation);
+  const fingerprint = bootstrapStateFingerprint(input.evaluation);
+  if (input.previous?.stateFingerprint === fingerprint && input.previous.controllerHome === input.controllerHome) return input.previous;
+  const now = (input.now ?? (() => new Date()))().toISOString();
+  const desired = normalizeDesired(input.evaluation.desired);
+  const observations = normalizedObservations(input.evaluation.observations);
+  const steps = normalizedSteps(input.evaluation.steps);
+  const blockers = normalizedBlockers(input.evaluation.blockers);
+  const actions = normalizedActions(input.evaluation.actions);
+  return {
+    schemaVersion: 1,
+    status: statusFor(steps, blockers),
+    revision: (input.previous?.revision ?? 0) + 1,
+    stateFingerprint: fingerprint,
+    controllerHome: input.controllerHome,
+    desired,
+    observations,
+    steps,
+    blockers,
+    actions,
+    createdAt: input.previous?.createdAt ?? now,
+    updatedAt: now,
+  };
+}

package/src/runtime/control-plane/bootstrap/store.ts

@@ -0,0 +1,21 @@
+import { join } from 'path';
+import { resolveControllerHome } from '../../../cli/repositories/controller-home';
+import { readJsonFile, writeJsonAtomic } from '../../shared/json-files';
+import type { BootstrapSnapshot } from './types';
+
+export function bootstrapStatePath(controllerHome: string): string {
+  return join(resolveControllerHome(controllerHome), 'bootstrap', 'state.json');
+}
+
+export function readBootstrapSnapshot(controllerHome: string): BootstrapSnapshot | undefined {
+  const value = readJsonFile<BootstrapSnapshot | undefined>(bootstrapStatePath(controllerHome), undefined);
+  if (!value || value.schemaVersion !== 1 || typeof value.stateFingerprint !== 'string' || !Number.isInteger(value.revision)) return undefined;
+  return value;
+}
+
+export function writeBootstrapSnapshot(controllerHome: string, snapshot: BootstrapSnapshot): BootstrapSnapshot {
+  const previous = readBootstrapSnapshot(controllerHome);
+  if (previous?.stateFingerprint === snapshot.stateFingerprint && previous.revision === snapshot.revision) return previous;
+  writeJsonAtomic(bootstrapStatePath(controllerHome), snapshot);
+  return snapshot;
+}

package/src/runtime/control-plane/bootstrap/types.ts

@@ -0,0 +1,87 @@
+export type BootstrapControllerKind = 'chatgpt' | 'codex' | 'claude' | 'mcp';
+export type BootstrapConnectivityMode = 'auto' | 'local' | 'remote';
+export type BootstrapTransportKind = 'openai-secure-tunnel' | 'https-endpoint' | 'loopback' | 'none';
+export type BootstrapStatus = 'in_progress' | 'blocked' | 'ready';
+export type BootstrapObservationStatus = 'ready' | 'missing' | 'degraded' | 'blocked' | 'unsupported' | 'unknown';
+export type BootstrapStepState = 'pending' | 'blocked' | 'ready' | 'skipped';
+export type BootstrapBlockerKind = 'automatic_retry' | 'user_action' | 'unsupported' | 'failed';
+export type BootstrapActionKind = 'configure' | 'install' | 'repair' | 'authenticate' | 'reconnect' | 'verify';
+export type BootstrapActionOwner = 'forge' | 'user';
+
+export interface BootstrapDesiredState {
+  schemaVersion: 1;
+  primaryController: BootstrapControllerKind;
+  controllers: BootstrapControllerKind[];
+  connectivity: {
+    mode: BootstrapConnectivityMode;
+    preferredTransport?: BootstrapTransportKind;
+    endpoint?: string;
+    tunnelId?: string;
+  };
+  capabilityIntents: string[];
+}
+
+/** Bounded observation. Raw logs, arbitrary objects, and credentials are intentionally absent. */
+export interface BootstrapObservation {
+  id: string;
+  component: 'controller' | 'runtime' | 'connectivity' | 'provider' | 'plugin' | 'package-connector' | 'platform';
+  status: BootstrapObservationStatus;
+  summary: string;
+  reasonCodes?: string[];
+  provider?: string;
+  version?: string;
+  releaseId?: string;
+  endpoint?: string;
+  observedAt: string;
+}
+
+export interface BootstrapAction {
+  id: string;
+  kind: BootstrapActionKind;
+  owner: BootstrapActionOwner;
+  summary: string;
+  command?: string;
+  verification?: string;
+  risk?: string;
+}
+
+export interface BootstrapBlocker {
+  code: string;
+  kind: BootstrapBlockerKind;
+  stepId: string;
+  summary: string;
+  actionIds: string[];
+}
+
+export interface BootstrapStep {
+  id: string;
+  label: string;
+  state: BootstrapStepState;
+  dependsOn: string[];
+  observationIds: string[];
+  blockerCodes: string[];
+  actionIds: string[];
+}
+
+export interface BootstrapSnapshot {
+  schemaVersion: 1;
+  status: BootstrapStatus;
+  revision: number;
+  stateFingerprint: string;
+  controllerHome: string;
+  desired: BootstrapDesiredState;
+  observations: BootstrapObservation[];
+  steps: BootstrapStep[];
+  blockers: BootstrapBlocker[];
+  actions: BootstrapAction[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface BootstrapEvaluation {
+  desired: BootstrapDesiredState;
+  observations: BootstrapObservation[];
+  steps: BootstrapStep[];
+  blockers: BootstrapBlocker[];
+  actions: BootstrapAction[];
+}