@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/execution/process-runtime/check-facade.ts

@@ -1,8 +1,9 @@
 /**
  * Lightweight run_check facade.
  *
- * Short checks complete via Process Runtime and return results directly.
- * Long checks return a Managed Process handle for the same OS process.
+ * Ordinary checks execute through an in-memory lightweight handle and return
+ * within the interactive budget without creating Process/Lease state. Checks
+ * with real Work/Edit/verification consumers keep persisted Process receipts.
  * Multi-phase and release checks require explicit external Controller handling.
  */
 
@@ -15,6 +16,12 @@ import {
 } from '../../../cli/controller/check-runner';
 import { claimsForCheck, scopeResourceClaims, toProcessClaims } from './resource-claims';
 import { spawnManagedProcess, waitForProcess, getProcessHandle } from './runtime';
+import {
+  getLightweightProcessHandle,
+  isLightweightProcessId,
+  startLightweightControllerCheck,
+  waitForLightweightProcess,
+} from './lightweight-managed';
 import type { ProcessHandle } from './types';
 import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
@@ -37,10 +44,14 @@ export interface RunCheckFacadeInput {
    */
   leaseWaitMs?: number;
   requestId?: string;
+  /** Stable caller-owned semantic identity for safely reattaching the same request before rebuilding ephemeral execution inputs. */
+  requestSemanticFingerprint?: string;
   workId?: string;
   commandId?: string;
   /** Force durable workflow (release / multi-phase). */
   forceDurable?: boolean;
+  /** Internal-only: allow an already-authorized external Work Controller to execute a durable-class check through persisted Process Runtime. */
+  allowDurableCheckExecution?: boolean;
   signal?: AbortSignal;
   /** Immutable resolved identity — required; never inferred from main/active/cwd. */
   executionIdentity: ResolvedExecutionIdentity;
@@ -143,8 +154,9 @@ export async function runCheckViaProcessRuntime(
     };
   }
 
-  // Most checks are builds/tests; return their existing Process handle at once.
-  // Only predictable shell primitives keep a short synchronous admission.
+  // The wait budget is an interaction preference, not a persistence reason.
+  // Ordinary checks stay in memory; only a real durable evidence consumer may
+  // allocate Process/Lease state.
   const interactiveWaitMs = durationAwareInteractiveWaitMs(
     check.command,
     input.interactiveWaitMs,
@@ -156,6 +168,14 @@ export async function runCheckViaProcessRuntime(
       ? Math.max(1_000, Math.trunc(input.timeoutMs))
       : check.timeoutMs,
   );
+  const durableVerificationBinding = Boolean(
+    input.workId
+    || input.verificationSnapshot
+    || input.verificationBinding?.executionSessionId
+    || input.verificationBinding?.editSessionId
+    || input.verificationBinding?.issueId
+    || input.verificationBinding?.taskId,
+  );
   if (!input.executionIdentity) {
     throw new Error('EXECUTION_IDENTITY_REQUIRED: run_check requires an immutable executionIdentity');
   }
@@ -170,6 +190,27 @@ export async function runCheckViaProcessRuntime(
       `CHECKOUT_ROUTE_MISMATCH: check checkout ${input.checkoutId} differs from identity ${executionIdentity.checkoutId}`,
     );
   }
+  if (!durableVerificationBinding) {
+    const lightweight = await startLightweightControllerCheck({
+      controllerHome: input.controllerHome,
+      repoId: input.repoId,
+      repoRoot: input.repoRoot,
+      checkId: input.checkId,
+      interactiveWaitMs,
+      timeoutMs,
+      workId: input.workId,
+      commandId: input.commandId ?? input.requestId,
+    });
+    const handle = lightweight.handle;
+    return {
+      mode: handle.completed ? 'direct' : 'managed',
+      checkId: input.checkId,
+      check,
+      process: handle,
+      ok: handle.completed ? handle.ok : undefined,
+      durableSideEffects: emptyEffects,
+    };
+  }
   const claims = scopeResourceClaims(
     claimsForCheck(
       input.checkId,
@@ -252,6 +293,9 @@ export async function waitForCheckProcess(
   processId: string,
   timeoutMs?: number,
 ): Promise<ProcessHandle> {
+  if (isLightweightProcessId(processId)) {
+    return waitForLightweightProcess(controllerHome, repoId, processId, { timeoutMs });
+  }
   return waitForProcess(controllerHome, repoId, processId, { timeoutMs });
 }
 
@@ -260,6 +304,9 @@ export function getCheckProcessHandle(
   repoId: string,
   processId: string,
 ): ProcessHandle | undefined {
+  if (isLightweightProcessId(processId)) {
+    return getLightweightProcessHandle(controllerHome, repoId, processId);
+  }
   return getProcessHandle(controllerHome, repoId, processId);
 }
 

package/src/runtime/execution/process-runtime/check-result.ts

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { processLogDir } from './store';
+import type { ManagedProcessRecord } from './types';
 
 export interface PersistedCheckResultReceipt {
   schemaVersion: 1;
@@ -51,3 +52,55 @@ export function readPersistedCheckResultReceipt(path: string | undefined): Persi
     return undefined;
   }
 }
+
+export type PersistedCheckTerminalEvidenceState =
+  | 'matched'
+  | 'process_runtime_failed_before_result'
+  | 'missing'
+  | 'mismatch';
+
+export interface PersistedCheckTerminalEvidence {
+  state: PersistedCheckTerminalEvidenceState;
+  failureClass?: PersistedCheckResultReceipt['failureClass'];
+  warning?: string;
+  infrastructureReason?: string;
+}
+
+/**
+ * Classify one terminal Check Process using the structured result emitted by
+ * the check-runner sidecar. A Process Runtime/admission failure can terminate
+ * before that result exists (for example PROCESS_LEASE_CONFLICT); such a
+ * Process is infrastructure failure, never evidence that repository checks
+ * rejected the candidate. Missing/mismatched result identity also fails closed
+ * as infrastructure rather than manufacturing acceptance evidence.
+ */
+export function classifyPersistedCheckTerminalEvidence(
+  record: ManagedProcessRecord,
+  expectedCheckId: string,
+): PersistedCheckTerminalEvidence {
+  const structured = readPersistedCheckResultReceipt(record.origin?.checkResultReceiptPath);
+  const structuredMatches = Boolean(
+    structured
+    && record.checkExecution
+    && structured.checkId === expectedCheckId
+    && structured.cacheKey === record.checkExecution.cacheKey,
+  );
+  if (structuredMatches) {
+    return { state: 'matched', failureClass: structured?.failureClass };
+  }
+  if (!structured && record.error?.message?.trim()) {
+    const reason = record.error.message.trim().slice(0, 512);
+    return {
+      state: 'process_runtime_failed_before_result',
+      warning: `check process failed before structured result receipt: ${reason}`,
+      infrastructureReason: reason,
+    };
+  }
+  if (structured) {
+    return {
+      state: 'mismatch',
+      warning: 'check result receipt did not match the terminal Process semantic identity',
+    };
+  }
+  return { state: 'missing', warning: 'check result receipt is missing for the terminal Check Process' };
+}

package/src/runtime/execution/process-runtime/check-scheduling.ts

@@ -0,0 +1,114 @@
+import type { ControllerCheck } from '../../../cli/controller/check-runner';
+import type { ResourceClaimSpec } from '../jobs/types';
+import { resourceClaimsConflict } from '../../resources/claims/conflicts';
+import { claimsForCheck } from './resource-claims';
+
+export interface CheckExecutionWave {
+  wave: number;
+  checkIds: string[];
+  parallelSafe: boolean;
+}
+
+export interface CheckExecutionConflict {
+  leftCheckId: string;
+  rightCheckId: string;
+  resources: Array<{
+    left: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+    right: Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>;
+  }>;
+}
+
+interface ScheduledCheck {
+  check: ControllerCheck;
+  claims: ResourceClaimSpec[];
+}
+
+function conflictingResources(left: ScheduledCheck, right: ScheduledCheck): CheckExecutionConflict['resources'] {
+  const conflicts: CheckExecutionConflict['resources'] = [];
+  for (const leftClaim of left.claims) {
+    for (const rightClaim of right.claims) {
+      if (!resourceClaimsConflict(leftClaim, rightClaim)) continue;
+      conflicts.push({
+        left: { resourceKey: leftClaim.resourceKey, mode: leftClaim.mode },
+        right: { resourceKey: rightClaim.resourceKey, mode: rightClaim.mode },
+      });
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * Produce deterministic execution waves from the exact same resource-claim model
+ * used by Process Runtime. Checks in one wave may overlap; waves run in order.
+ * This is advisory scheduling metadata, not a second lease authority.
+ */
+export function buildCheckExecutionSchedule(input: {
+  checks: ControllerCheck[];
+  requestedCheckIds: string[];
+  repoId: string;
+  checkoutId?: string;
+}): {
+  waves: CheckExecutionWave[];
+  conflicts: CheckExecutionConflict[];
+  invalidCheckIds: string[];
+  maxParallel: number;
+  guidance: string[];
+  claimsByCheck: Array<{ checkId: string; claims: Array<Pick<ResourceClaimSpec, 'resourceKey' | 'mode'>> }>;
+} {
+  const byId = new Map(input.checks.map((check) => [check.id, check]));
+  const requested = [...new Set(input.requestedCheckIds.filter(Boolean))];
+  const invalidCheckIds = requested.filter((checkId) => !byId.has(checkId));
+  const scheduled: ScheduledCheck[] = requested.flatMap((checkId) => {
+    const check = byId.get(checkId);
+    if (!check) return [];
+    return [{
+      check,
+      claims: claimsForCheck(check.id, check.command, input.repoId, input.checkoutId, check.effects),
+    }];
+  });
+
+  const conflicts: CheckExecutionConflict[] = [];
+  for (let leftIndex = 0; leftIndex < scheduled.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < scheduled.length; rightIndex += 1) {
+      const left = scheduled[leftIndex]!;
+      const right = scheduled[rightIndex]!;
+      const resources = conflictingResources(left, right);
+      if (resources.length === 0) continue;
+      conflicts.push({ leftCheckId: left.check.id, rightCheckId: right.check.id, resources });
+    }
+  }
+
+  const waves: ScheduledCheck[][] = [];
+  for (const entry of scheduled) {
+    const compatible = waves.find((wave) => wave.every((other) => conflictingResources(entry, other).length === 0));
+    if (compatible) compatible.push(entry);
+    else waves.push([entry]);
+  }
+
+  const projectedWaves = waves.map((wave, index) => ({
+    wave: index + 1,
+    checkIds: wave.map((entry) => entry.check.id),
+    parallelSafe: wave.length > 1,
+  }));
+  const maxParallel = projectedWaves.reduce((max, wave) => Math.max(max, wave.checkIds.length), 0);
+  const guidance: string[] = [];
+  if (projectedWaves.length > 1) {
+    guidance.push('Run check waves in order; only checks within the same wave are resource-compatible for overlap.');
+  } else if (maxParallel > 1) {
+    guidance.push('Requested checks are resource-compatible and may run concurrently for this checkout.');
+  } else if (maxParallel === 1) {
+    guidance.push('Run the requested check as one focused verification unit.');
+  }
+
+  return {
+    waves: projectedWaves,
+    conflicts,
+    invalidCheckIds,
+    maxParallel,
+    guidance,
+    claimsByCheck: scheduled.map((entry) => ({
+      checkId: entry.check.id,
+      claims: entry.claims.map((claim) => ({ resourceKey: claim.resourceKey, mode: claim.mode })),
+    })),
+  };
+}