@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/controller/domain/controller-round.ts

@@ -0,0 +1,110 @@
+import type { AssistantContextSnapshot, ClosedRoundObservation, ExecutionQualityAdjustmentResult, ExecutionQualityDecision } from './execution-quality';
+import type { ControllerType } from './types';
+
+export const CONTROLLER_ROUND_DISPOSITIONS = [
+  'continue_immediately',
+  'wait',
+  'wait_for_user',
+  'goal_complete',
+] as const;
+export type ControllerRoundDisposition = (typeof CONTROLLER_ROUND_DISPOSITIONS)[number];
+
+export const CONTROLLER_RELAY_ABANDONED_RELEASE_ERROR = 'CONTROLLER_RELAY_CLAIM_RELEASED_WITHOUT_DISPOSITION';
+
+export type ControllerRoundLifecycleStage =
+  | 'dispatching'
+  | 'dispatch_confirmed'
+  | 'controller_claimed'
+  | 'semantic_round_closed';
+
+export type ControllerRoundRelayStatus =
+  | 'pending_release'
+  | 'dispatching'
+  | 'dispatched'
+  | 'claimed'
+  | 'waiting'
+  | 'waiting_for_user'
+  | 'goal_complete'
+  | 'handed_off'
+  | 'blocked'
+  | 'failed';
+
+export type ControllerRoundFailureClass = 'terminal_work' | 'abandoned_release';
+
+export interface ControllerRoundRelayRecord {
+  schemaVersion: 1;
+  repoId: string;
+  relayScopeId: string;
+  originWorkId: string;
+  /** Previous Work when this round was mechanically handed across a Plan successor. */
+  predecessorWorkId?: string;
+  /** Already-admitted successor Work selected by GoalWorkloop; never selected by ControllerRound. */
+  successorWorkId?: string;
+  requirementId?: string;
+  disposition: ControllerRoundDisposition;
+  status: ControllerRoundRelayStatus;
+  /** Durable semantic stage; transport/session state must never substitute for lifecycle authority. */
+  lifecycleStage?: ControllerRoundLifecycleStage;
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  sessionId: string;
+  claimGeneration: number;
+  /** Opaque per-round capability. Rotates when Forge dispatches a new controller round. */
+  authorityId?: string;
+  stateFingerprint: string;
+  /** Round owner appends only at semantic close; oldest entries expire with this bounded record. */
+  observationWindow?: ClosedRoundObservation[];
+  qualityDecisions?: ExecutionQualityDecision[];
+  /** Verified post-adjustment outcomes; these never reset ControllerRound budgets. */
+  qualityAdjustmentResults?: ExecutionQualityAdjustmentResult[];
+  /** Exact bounded assistant context identity delivered for the currently claimed round. */
+  assistantContextSnapshot?: AssistantContextSnapshot;
+  /** Provider-neutral evidence that the exact Controller turn visibly settled. Never a semantic disposition by itself. */
+  controllerTurnCompletionEvidenceId?: string;
+  controllerTurnSettledAt?: string;
+  roundCount: number;
+  repeatedStateCount: number;
+  consecutiveFailures: number;
+  maxRounds: number;
+  maxRepeatedState: number;
+  maxFailures: number;
+  handoffId?: string;
+  reason?: string;
+  /** Opaque provider binding owned by a ControllerHost adapter. */
+  bindingId?: string;
+  /** Stable provider-neutral identity for the exact external dispatch responsibility. */
+  providerDispatchEffectId?: string;
+  /** Monotonic provider-effect attempt within one semantic round authority. */
+  providerDispatchAttempt?: number;
+  /** Monotonic historical provider failures; recovery epochs never erase it. */
+  providerFailureTotal?: number;
+  /** Bounded provider-recovery epoch for the same semantic round. */
+  providerRecoveryEpoch?: number;
+  providerRecoveryEvidenceId?: string;
+  providerFailureEvidenceId?: string;
+  providerEffectReconciliationEvidenceId?: string;
+  providerDispatchStartedAt?: string;
+  /** Canonical provider-dispatch receipt for this semantic round. Trigger occurrences never duplicate this lifecycle truth. */
+  providerDispatchReceiptId?: string;
+  /** Explicit schedule/manual/replan occurrence identity when a prior lineage exists. */
+  occurrenceId?: string;
+  blockedReason?: string;
+  /** Typed failed-lineage classification. lastError remains diagnostic text only. */
+  failureClass?: ControllerRoundFailureClass;
+  lastError?: string;
+  nextRecoveryAt?: string;
+  submittedAt: string;
+  updatedAt: string;
+  dispatchedAt?: string;
+  claimedAt?: string;
+}
+
+export interface ControllerRoundRelayIdentity {
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  sessionId: string;
+}

package/packages/kernel/controller/domain/execution-quality.ts

@@ -0,0 +1,135 @@
+/** Evidence-only hints: neither diagnoses nor authority to change Work or budgets. */
+export interface ExecutionQualitySignal {
+  code: 'repeated_semantic_state' | 'repeated_verification' | 'suspected_regression' | 'repeated_root_cause';
+  fingerprint?: string;
+  evidenceRefs: string[];
+  observation: string;
+}
+export interface VerificationObservation {
+  checkId: string; sourceDigest: string; environment: string; outcome: 'passed' | 'failed'; evidenceRef: string;
+}
+export interface RootCauseObservation {
+  dispositionRef: string; rootCauseId: string; designScope: string; controllerConfirmed: boolean;
+}
+
+export function deriveExecutionQualitySignals(input: {
+  repeatedStateCount: number; maxRepeatedState: number; waiting: boolean; roundRef: string;
+  /** Unknown coverage is not evidence of absent progress. */
+  hasNewVerifiedProgress?: boolean;
+  verifications?: readonly VerificationObservation[];
+  rootCauses?: readonly RootCauseObservation[];
+}): ExecutionQualitySignal[] {
+  const signals: ExecutionQualitySignal[] = [];
+  const threshold = Math.max(1, input.maxRepeatedState - 1);
+  if (!input.waiting && input.hasNewVerifiedProgress === false && input.repeatedStateCount >= threshold) {
+    signals.push({ code: 'repeated_semantic_state', evidenceRefs: [input.roundRef],
+      observation: `${input.repeatedStateCount} repeated semantic fingerprints without new verified evidence or accepted results. Investigate before changing strategy; this does not establish that investigation made no progress.` });
+  }
+  const uniqueChecks = new Map<string, VerificationObservation>();
+  for (const check of input.verifications ?? []) if (!uniqueChecks.has(check.evidenceRef)) uniqueChecks.set(check.evidenceRef, check);
+  const checks = [...uniqueChecks.values()].slice(-32).filter(check =>
+    check.checkId && check.sourceDigest && check.environment && check.evidenceRef
+    && (check.outcome === 'passed' || check.outcome === 'failed'));
+  const buckets = new Map<string, VerificationObservation[]>();
+  for (const check of checks) {
+    const key = JSON.stringify([check.checkId, check.sourceDigest, check.environment]);
+    const list = buckets.get(key) ?? [];
+    if (!list.some(item => item.evidenceRef === check.evidenceRef)) list.push(check);
+    buckets.set(key, list);
+  }
+  for (const list of buckets.values()) {
+    if (list.length >= 3 && list.every(check => check.outcome === list[0]!.outcome)) signals.push({ code: 'repeated_verification',
+      evidenceRefs: list.map(check => check.evidenceRef), observation: 'Same check, exact source, environment and outcome observed at least three times. Repetition may be intentional flaky-test diagnosis.' });
+  }
+  for (let index = 1; index < checks.length; index++) {
+    const current = checks[index]!;
+    const prior = checks.slice(0, index).reverse().find(check => check.checkId === current.checkId && check.environment === current.environment);
+    if (prior?.outcome === 'passed' && current.outcome === 'failed' && prior.evidenceRef !== current.evidenceRef) {
+      signals.push({ code: 'suspected_regression', evidenceRefs: [prior.evidenceRef, current.evidenceRef],
+        observation: prior.sourceDigest === current.sourceDigest
+          ? 'A passing check subsequently failed on the same source and declared environment. Intermittent failure remains a possible explanation; regression is unconfirmed.'
+          : 'A passing check subsequently failed in the same declared environment. Changed source is correlated evidence, not established cause; regression is unconfirmed.' });
+    }
+  }
+  const causes = new Map<string, Set<string>>();
+  for (const cause of (input.rootCauses ?? []).slice(-32)) {
+    if (!cause.controllerConfirmed || !cause.dispositionRef || !cause.rootCauseId || !cause.designScope) continue;
+    const key = JSON.stringify([cause.rootCauseId, cause.designScope]);
+    const refs = causes.get(key) ?? new Set<string>();
+    refs.add(cause.dispositionRef); causes.set(key, refs);
+  }
+  for (const refs of causes.values()) if (refs.size >= 2) signals.push({ code: 'repeated_root_cause', evidenceRefs: [...refs],
+    observation: 'At least two Controller-confirmed blocker dispositions name the same root cause and design scope. Apply the existing return_to_design contract.' });
+  return signals.slice(0, 8);
+}
+
+export interface AssistantContextItemEvidence {
+  kind: 'knowledge' | 'experience';
+  itemId: string;
+  digest?: string;
+  revision?: number;
+  sourceRevision?: string;
+}
+
+export interface AssistantContextSnapshot {
+  digest: string;
+  projectId?: string;
+  items: AssistantContextItemEvidence[];
+  gaps: string[];
+  missingRequiredSources: string[];
+  truncated: boolean;
+}
+
+export interface AssistantContextUsage {
+  kind: AssistantContextItemEvidence['kind'];
+  itemId: string;
+  decision: 'used' | 'rejected';
+  reason: string;
+  /** Model-authored retrieval rejection semantics. Optional only for frozen-client compatibility. */
+  rejectionKind?: 'irrelevant' | 'stale' | 'contradicted';
+}
+
+export interface ClosedRoundObservation {
+  roundRef: string;
+  workId: string;
+  requirementId?: string;
+  planId?: string;
+  designVersion?: string;
+  stateFingerprint: string;
+  evidenceIdentities: string[];
+  acceptedResultIdentities: string[];
+  verifications: VerificationObservation[];
+  rootCauses?: RootCauseObservation[];
+  assistantContext?: AssistantContextSnapshot;
+  assistantContextUsage?: AssistantContextUsage[];
+  waiting: boolean;
+  coverageGaps: string[];
+}
+
+export function deriveClosedRoundQualitySignals(window: readonly ClosedRoundObservation[], input: {
+  repeatedStateCount: number; maxRepeatedState: number; waiting: boolean; roundRef: string;
+}): ExecutionQualitySignal[] {
+  const bounded = window.slice(-8), current = bounded.at(-1), previous = bounded.at(-2);
+  const comparable = current && previous && current.workId === previous.workId && !current.coverageGaps.length && !previous.coverageGaps.length;
+  const hasNewVerifiedProgress = comparable ? current.evidenceIdentities.some(id => !previous.evidenceIdentities.includes(id))
+    || current.acceptedResultIdentities.some(id => !previous.acceptedResultIdentities.includes(id)) : undefined;
+  return deriveExecutionQualitySignals({ ...input, hasNewVerifiedProgress, verifications: bounded.flatMap(round => round.verifications), rootCauses: bounded.flatMap(round => round.rootCauses ?? []) });
+}
+
+export interface ExecutionQualityDecision {
+  fingerprint: string;
+  action: 'no_adjustment' | 'adjustment';
+  reason: string;
+  verificationCondition?: string;
+  /** Kernel-recorded time of the Controller decision. Callers do not supply this authority. */
+  decidedAt?: string;
+}
+
+export interface ExecutionQualityAdjustmentResult {
+  fingerprint: string;
+  outcome: 'improved' | 'not_improved' | 'inconclusive';
+  evidenceRefs: string[];
+  reason: string;
+  /** Kernel-recorded time after all referenced post-adjustment verification receipts exist. */
+  verifiedAt: string;
+}

package/packages/kernel/controller/domain/types.ts

@@ -0,0 +1,56 @@
+/** Canonical Kernel Controller contracts. Provider bindings are opaque to Kernel. */
+export type ControllerType = 'chatgpt' | 'codex' | 'grok' | 'claude' | 'human';
+
+export interface ControllerSession {
+  schemaVersion: 1;
+  workId: string;
+  controllerId: string;
+  controllerType: ControllerType;
+  sessionId: string;
+  /** SHA-256 digest of the non-relay Work-bound controller capability. The plaintext capability is returned only to the claimant. */
+  authorityDigest?: string;
+  /** Authenticated authority that owned the claim; legacy records may omit it. */
+  principalId?: string;
+  /** Controller process/epoch that admitted the transport session. */
+  controllerInstanceId?: string;
+  /** Monotonic ownership fence. It changes only when ownership moves. */
+  claimGeneration?: number;
+  claimedAt: string;
+  leaseExpiresAt: string;
+}
+
+export interface ControllerSessionStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  sessions: ControllerSession[];
+}
+
+
+export interface ControllerBinding {
+  bindingId: string;
+  hostKind: ControllerType;
+  /** Opaque adapter-owned reference. Kernel never parses provider metadata. */
+  adapterRef: string;
+}
+
+export interface ControllerLease {
+  workId: string;
+  controllerId: string;
+  sessionId: string;
+  claimGeneration: number;
+  claimedAt: string;
+  leaseExpiresAt: string;
+}
+
+export interface ControllerRoundContext {
+  workId: string;
+  relayScopeId: string;
+  roundNumber: number;
+  authorityId: string;
+  /** Exact Scheduler occurrence identity when resumed by a durable schedule. */
+  occurrenceId?: string;
+  /** Keep a Work-bound scheduled round on its exact origin Work. */
+  exactOriginWork?: boolean;
+  /** Provider-neutral semantic hint. ControllerHost decides how to render it. */
+  continuationHint?: string;
+}

package/packages/kernel/controller/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

package/packages/kernel/controller/infrastructure/controller-binding-store.ts

@@ -0,0 +1,84 @@
+import { withControllerLock } from '../../../../src/cli/repositories/locks';
+import { readControlPlaneRecord, writeControlPlaneRecord } from '../../../../src/runtime/control-plane/persistence/sqlite-store';
+import type { ControllerBinding } from '../domain/types';
+import { getRetainedControllerSession, type ControllerSessionStoreOptions } from './controller-session-store';
+
+const SESSION_NAMESPACE = 'controller_session_binding';
+const WORK_NAMESPACE = 'controller_work_binding';
+
+export interface ControllerSessionBindingRecord {
+  schemaVersion: 1;
+  repoId: string;
+  workId: string;
+  sessionId: string;
+  binding: ControllerBinding;
+  boundAt: string;
+  updatedAt: string;
+}
+
+/** Durable provider interaction target for a Work. latestSessionId is observation only. */
+export interface ControllerWorkBindingRecord {
+  schemaVersion: 1;
+  repoId: string;
+  workId: string;
+  latestSessionId: string;
+  binding: ControllerBinding;
+  boundAt: string;
+  updatedAt: string;
+}
+
+export function bindControllerSessionBinding(
+  options: ControllerSessionStoreOptions,
+  input: { workId: string; sessionId: string; binding: ControllerBinding },
+): ControllerSessionBindingRecord {
+  const session = getRetainedControllerSession(options, input.workId);
+  if (!session) throw new Error(`CONTROLLER_SESSION_NOT_RETAINED: ${input.workId}`);
+  if (session.sessionId !== input.sessionId) throw new Error(`CONTROLLER_SESSION_BINDING_SESSION_MISMATCH: ${input.workId}`);
+  if (session.controllerType !== input.binding.hostKind) throw new Error(`CONTROLLER_SESSION_BINDING_HOST_MISMATCH: ${input.workId}`);
+  const sessionKey = `${input.workId}:${input.sessionId}`;
+  return withControllerLock(options.controllerHome, { scope: 'task', repoId: options.repoId, taskId: `controller-binding-${input.workId}` }, `controller-binding:${input.workId}`, () => {
+    const currentSession = readControlPlaneRecord<ControllerSessionBindingRecord>(options.controllerHome, SESSION_NAMESPACE, options.repoId, sessionKey);
+    const currentWork = readControlPlaneRecord<ControllerWorkBindingRecord>(options.controllerHome, WORK_NAMESPACE, options.repoId, input.workId);
+    const at = options.now?.() ?? new Date().toISOString();
+    const sessionValue: ControllerSessionBindingRecord = {
+      schemaVersion: 1, repoId: options.repoId, workId: input.workId, sessionId: input.sessionId,
+      binding: { ...input.binding }, boundAt: currentSession?.value.boundAt ?? at, updatedAt: at,
+    };
+    const workValue: ControllerWorkBindingRecord = {
+      schemaVersion: 1, repoId: options.repoId, workId: input.workId, latestSessionId: input.sessionId,
+      binding: { ...input.binding }, boundAt: currentWork?.value.boundAt ?? at, updatedAt: at,
+    };
+    writeControlPlaneRecord(options.controllerHome, {
+      namespace: SESSION_NAMESPACE, scope: options.repoId, key: sessionKey, schemaVersion: 1, value: sessionValue,
+      action: currentSession ? 'controller_session_binding_update' : 'controller_session_binding_create',
+      expectedRevision: currentSession?.revision ?? null,
+    });
+    writeControlPlaneRecord(options.controllerHome, {
+      namespace: WORK_NAMESPACE, scope: options.repoId, key: input.workId, schemaVersion: 1, value: workValue,
+      action: currentWork ? 'controller_work_binding_update' : 'controller_work_binding_create',
+      expectedRevision: currentWork?.revision ?? null,
+    });
+    return sessionValue;
+  });
+}
+
+/** Legacy transport-scoped projection retained for migration/read compatibility. */
+export function getControllerSessionBinding(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  sessionId: string,
+): ControllerSessionBindingRecord | undefined {
+  return readControlPlaneRecord<ControllerSessionBindingRecord>(
+    options.controllerHome, SESSION_NAMESPACE, options.repoId, `${workId}:${sessionId}`,
+  )?.value;
+}
+
+/** Canonical Work-scoped provider interaction target. */
+export function getControllerWorkBinding(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+): ControllerWorkBindingRecord | undefined {
+  return readControlPlaneRecord<ControllerWorkBindingRecord>(
+    options.controllerHome, WORK_NAMESPACE, options.repoId, workId,
+  )?.value;
+}