@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/control-plane/execution/validation.ts

@@ -69,12 +69,12 @@ export function currentPermissionSnapshotVersion(controllerHome: string, repoId:
   return readRepositoryAccessPolicy(controllerHome, repoId).revision;
 }
 
-export function assertWorkHandleLifecycle(handle: WorkHandleState, operation: 'inspect' | 'execute' | 'validate' | 'finalize'): void {
+export function assertWorkHandleLifecycle(handle: WorkHandleState, operation: 'inspect' | 'execute' | 'validate' | 'deliver'): void {
   const allowed: Record<typeof operation, readonly WorkHandleState['state'][]> = {
     inspect: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed', 'failed_terminal_cleanup', 'cleaned'],
     execute: ['prepared', 'editing'],
     validate: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed'],
-    finalize: ['prepared', 'editing', 'validating', 'committed', 'merged', 'failed_terminal_cleanup', 'cleaned', 'failed'],
+    deliver: ['editing', 'committed', 'merged', 'failed'],
   };
   if (!allowed[operation].includes(handle.state)) {
     fail('WORK_HANDLE_LIFECYCLE_INVALID', `${operation} is not valid while handle is ${handle.state}`);
@@ -86,7 +86,7 @@ export function validateWorkHandle(
   handle: WorkHandleState,
   identity: SessionIdentity,
   level: ValidationLevel,
-  operation: 'inspect' | 'execute' | 'validate' | 'finalize',
+  operation: 'inspect' | 'execute' | 'validate' | 'deliver',
 ): ValidatedWorkHandle {
   const session = requireExecutionSession(controllerHome, identity);
   if (handle.principalId !== session.principalId) fail('WORK_HANDLE_PRINCIPAL_MISMATCH', 'work handle belongs to another principal');
@@ -107,9 +107,7 @@ export function validateWorkHandle(
 
   const repository = getRepository(handle.repositoryId, controllerHome, { includeRemoved: true });
   if (repository.removedAt || repository.enabled === false) fail('REPOSITORY_NOT_EXECUTABLE', `repository ${repository.repoId} is disabled or removed`);
-  const worktreeRepository = selectRepositoryCheckout(repository, handle.checkoutId, {
-    allowArchived: operation === 'finalize' && handle.managedWorktree,
-  });
+  const worktreeRepository = selectRepositoryCheckout(repository, handle.checkoutId);
   if (worktreeRepository.activeCheckoutId !== handle.checkoutId) fail('CHECKOUT_NOT_REGISTERED', handle.checkoutId);
 
   const permissionVersion = currentPermissionSnapshotVersion(controllerHome, repository.repoId);
@@ -128,7 +126,7 @@ export function validateWorkHandle(
   const currentBranch = gitText(root, ['branch', '--show-current']);
   const currentHead = gitText(root, ['rev-parse', '--verify', 'HEAD']);
   if (currentBranch !== handle.branch) fail('WORK_HANDLE_BRANCH_CHANGED', `expected ${handle.branch}, found ${currentBranch ?? 'detached'}`);
-  const managedWorkProgress = (operation === 'validate' || operation === 'finalize')
+  const managedWorkProgress = (operation === 'inspect' || operation === 'validate' || operation === 'deliver')
     && handle.managedWorktree
     && Boolean(handle.expectedHead && currentHead)
     && gitSucceeds(root, ['merge-base', '--is-ancestor', handle.expectedHead!, currentHead!]);
@@ -136,7 +134,7 @@ export function validateWorkHandle(
     fail('WORK_HANDLE_HEAD_CHANGED', `expected ${handle.expectedHead}, found ${currentHead ?? 'missing'}`);
   }
   if (managedWorkProgress && currentHead !== handle.expectedHead) {
-    warnings.push('Managed Worktree HEAD advanced from the prepared revision by Work-owned descendant commits; validation/finalization will use the current Work state.');
+    warnings.push('Managed Worktree HEAD advanced from the prepared revision by Work-owned descendant commits; inspection/validation will use the current Work state.');
   }
 
   if (level === 'full') {

package/src/runtime/control-plane/execution/work-authority-reconciler.ts

@@ -1,6 +1,6 @@
 import { listControllerSessions } from '../../../../packages/kernel/controller/api/index';
-import { listSchedules, listActiveOccurrences } from '../../../../packages/kernel/scheduler/api/index';
-import { listWorkContracts, transitionWorkContractPhase, updateWorkContract } from '../../../../packages/kernel/work/api/index';
+import { listSchedules, listActiveOccurrences, scheduleOwnsWork } from '../../../../packages/kernel/scheduler/api/index';
+import { listWorkContracts } from '../../../../packages/kernel/work/api/index';
 import { listActiveLeases } from '../../resources/leases/store';
 import { listProcessRecords } from '../../execution/process-runtime/store';
 import { isManagedProcessActive } from '../../execution/process-runtime/types';
@@ -24,34 +24,24 @@ export interface OwnerlessWorkAuthorityReconcileResult {
   skippedByReason: Record<string, number>;
 }
 
-function scheduleOwnsWork(schedule: ReturnType<typeof listSchedules>[number], workId: string): boolean {
-  if (schedule.action.resourceClaims?.some((claim) => claim.workId === workId)) return true;
-  const args = schedule.action.arguments ?? {};
-  return args.workId === workId || args.work_id === workId;
-}
-
 function skip(counts: Record<string, number>, reason: string): void {
   counts[reason] = (counts[reason] ?? 0) + 1;
 }
 
 /**
- * Retire only exact Work authority that has lost every durable continuation owner.
- *
- * This deliberately does not resurrect the retired repository-wide stale Work
- * reconciler. Liveness is evaluated per Work. Current Plan authority, an active
- * Controller session, Work-bound lease, Schedule/occurrence, or active Process
- * protects the Work. Blocked Work is also retained unless its WorkHandle is
- * already terminal, because blocked may be an intentional user/dependency wait.
+ * Observe exact Work that has lost every durable continuation owner.
  *
- * Retiring authority cancels the Work but keeps its SQLite history. Filesystem
- * cleanup and later physical retention/GC remain separate phases.
+ * Liveness facts are mechanical evidence only. They may drive resource cleanup
+ * or diagnostics, but they never decide semantic Work cancellation/completion.
+ * Open Work remains model/user-owned working context until an explicit semantic
+ * CAS transition closes it.
  */
 export function reconcileOwnerlessWorkAuthorities(
   options: OwnerlessWorkAuthorityReconcileOptions,
 ): OwnerlessWorkAuthorityReconcileResult {
   const nowMs = options.nowMs ?? Date.now();
   const graceMs = Math.max(5 * 60_000, Math.trunc(options.graceMs ?? DEFAULT_OWNERLESS_WORK_GRACE_MS));
-  const works = listWorkContracts({ controllerHome: options.controllerHome, repoId: options.repoId, status: 'active', limit: 100 });
+  const works = listWorkContracts({ controllerHome: options.controllerHome, repoId: options.repoId, state: 'active', limit: 100 });
   const currentPlanIds = new Set(listPlanContracts({ controllerHome: options.controllerHome, repoId: options.repoId, status: 'active', limit: 100 }).map((plan) => plan.planId));
   const activeSessionWorkIds = new Set(listControllerSessions({ controllerHome: options.controllerHome, repoId: options.repoId }).map((session) => session.workId));
   const activeLeaseWorkIds = new Set(listActiveLeases(options.controllerHome, options.repoId).map((lease) => lease.workId).filter((workId): workId is string => Boolean(workId)));
@@ -77,34 +67,15 @@ export function reconcileOwnerlessWorkAuthorities(
 
     const handle = handles.get(work.workId);
     const terminalHandleMismatch = Boolean(handle && TERMINAL_HANDLE_STATES.has(handle.state));
-    if (work.status === 'blocked' && !terminalHandleMismatch) { skip(skippedByReason, 'blocked_wait'); continue; }
+    if (work.dispatchState === 'blocked' && !terminalHandleMismatch) { skip(skippedByReason, 'blocked_wait'); continue; }
     const updatedMs = Date.parse(work.updatedAt);
     if (!Number.isFinite(updatedMs)) { skip(skippedByReason, 'invalid_updated_at'); continue; }
     if (!terminalHandleMismatch && nowMs - updatedMs < graceMs) { skip(skippedByReason, 'grace_period'); continue; }
 
-    const reason = terminalHandleMismatch
-      ? `WorkHandle is already ${handle!.state} while Work remained ${work.status}.`
-      : `Work has no current Plan, Controller session, Work-bound lease, Schedule/occurrence, or active Process after ${Math.round(graceMs / 60_000)} minutes.`;
-    transitionWorkContractPhase(
-      { controllerHome: options.controllerHome, repoId: options.repoId },
-      work.workId,
-      {
-        phase: 'cleanup',
-        status: 'cancelled',
-        state: 'skipped',
-        dispatchState: 'terminal',
-        summary: reason,
-        evidenceRefs: [{
-          title: 'ownerless Work authority retired',
-          summary: reason,
-          detailLevel: 'summary',
-        }, ...work.evidenceRefs],
-      },
-    );
-    updateWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, work.workId, {
-      continuationPrompt: `Runtime maintenance retired ownerless Work authority ${work.workId}. Historical evidence is retained; create or continue current Requirement/Plan authority instead of reviving stale execution state.`,
-    });
-    retired.push(work.workId);
+    // Absence of a runtime owner is not semantic cancellation authority.
+    // Keep the Work open and surface the observation to cleanup/status callers.
+    skip(skippedByReason, terminalHandleMismatch ? 'terminal_handle_semantic_work_open' : 'semantic_work_open_ownerless');
+    continue;
   }
 
   return {

package/src/runtime/control-plane/execution/work-check-evidence.ts

@@ -0,0 +1,137 @@
+import {
+  appendVerificationRecord,
+  appendWorkEvidence,
+  getWorkContract,
+  semanticWorkState,
+  summarizeWorkContract,
+  updateWorkContract,
+  type WorkContractStoreOptions,
+} from '../../../../packages/kernel/work/api/index';
+import { buildFacadeResult } from '../facade/facade-result';
+import { classifyVerificationOutcome, type CheckDefinitionLike } from '../facade/check-normalization';
+import type { FacadeResult, VerificationRecord } from '../facade/types';
+
+export interface RecordWorkCheckEvidenceInput {
+  store: WorkContractStoreOptions;
+  workId: string;
+  checkId: string;
+  availableChecks: readonly CheckDefinitionLike[];
+  sourceRevision?: string;
+  workspaceFingerprint?: string;
+  verificationInputFingerprint?: string;
+  commandFingerprint?: string;
+  receipt?: VerificationRecord['receipt'];
+  infrastructureFailed?: boolean;
+  checkFailed?: boolean;
+  skipped?: boolean;
+}
+
+/**
+ * Attribute one check outcome to semantic Work as durable evidence only.
+ * This cannot advance Work lifecycle, request review, authorize Git, or choose
+ * the model's next semantic action.
+ */
+export function recordWorkCheckEvidence(input: RecordWorkCheckEvidenceInput): FacadeResult {
+  const work = getWorkContract(input.store, input.workId);
+  if (!work) {
+    return buildFacadeResult({
+      status: 'not_found',
+      summary: `WorkContract ${input.workId} not found.`,
+      data: { workId: input.workId },
+    });
+  }
+
+  const classified = classifyVerificationOutcome({
+    checkId: input.checkId,
+    available: input.availableChecks,
+    infrastructureFailed: input.infrastructureFailed,
+    checkFailed: input.checkFailed,
+    skipped: input.skipped,
+  });
+  const resolvedCheckId = classified.normalizedCheckId ?? classified.checkId;
+
+  if (semanticWorkState(work) !== 'open') {
+    const existing = [...work.checkRefs].reverse().find((record) => record.checkId === resolvedCheckId);
+    return buildFacadeResult({
+      status: semanticWorkState(work) === 'completed' ? 'ok' : 'blocked',
+      summary: `WorkContract ${work.workId} is terminal (${semanticWorkState(work)}); check evidence was not rewritten.`,
+      data: {
+        work: summarizeWorkContract(work),
+        verification: {
+          checkId: resolvedCheckId,
+          ...(existing ? { outcome: existing.outcome } : {}),
+          terminal: true,
+          idempotent: true,
+          reexecuted: false,
+          isAcceptanceFailure: existing?.outcome === 'valid_fail',
+          isInfrastructureIssue: existing?.outcome === 'invalid_check_id' || existing?.outcome === 'infrastructure_failure',
+          doesNotRequestTaskChanges: existing?.outcome !== 'valid_fail',
+        },
+      },
+      evidenceRefs: existing?.evidenceRef ? [existing.evidenceRef] : [],
+      warnings: classified.warnings,
+      suggestedNextActions: [],
+    });
+  }
+
+  const receipt = input.receipt
+    && input.receipt.repoId === work.repoId
+    && input.receipt.workId === work.workId
+    && input.receipt.checkId === resolvedCheckId
+    ? input.receipt
+    : undefined;
+  const sourceRevision = receipt && input.sourceRevision?.trim() ? input.sourceRevision.trim() : undefined;
+  const summary = receipt
+    ? `${classified.summary} Durable Process receipt ${receipt.receiptId}.`
+    : classified.summary;
+  const recordedAt = new Date().toISOString();
+  const record: VerificationRecord = {
+    checkId: resolvedCheckId,
+    outcome: classified.outcome,
+    summary,
+    recordedAt,
+    sourceRevision,
+    workspaceFingerprint: receipt && sourceRevision ? input.workspaceFingerprint : undefined,
+    verificationInputFingerprint: receipt && sourceRevision ? input.verificationInputFingerprint : undefined,
+    commandFingerprint: receipt && sourceRevision ? input.commandFingerprint : undefined,
+    startedAt: receipt?.startedAt,
+    completedAt: receipt?.finishedAt,
+    receipt,
+    evidenceRef: {
+      title: `verification:${classified.outcome}`,
+      summary,
+      detailLevel: 'summary',
+    },
+  };
+
+  if (classified.outcome === 'valid_pass' || classified.outcome === 'valid_fail') {
+    const checkRefs = work.checkRefs.map((existing) => (
+      existing.checkId === record.checkId
+      && (existing.outcome === 'invalid_check_id' || existing.outcome === 'infrastructure_failure')
+        ? { ...existing, outcome: 'superseded' as const, summary: `Superseded by ${classified.outcome} at ${recordedAt}` }
+        : existing
+    ));
+    updateWorkContract(input.store, work.workId, { checkRefs });
+  }
+
+  const updated = appendVerificationRecord(input.store, work.workId, record);
+  if (record.evidenceRef) appendWorkEvidence(input.store, work.workId, record.evidenceRef);
+
+  return buildFacadeResult({
+    status: classified.outcome === 'valid_fail' ? 'failed' : 'ok',
+    summary: classified.summary,
+    data: {
+      work: summarizeWorkContract(updated),
+      verification: {
+        checkId: record.checkId,
+        outcome: classified.outcome,
+        isAcceptanceFailure: classified.isAcceptanceFailure,
+        isInfrastructureIssue: classified.isInfrastructureIssue,
+        doesNotRequestTaskChanges: !classified.isAcceptanceFailure,
+      },
+    },
+    warnings: classified.warnings,
+    evidenceRefs: record.evidenceRef ? [record.evidenceRef] : [],
+    suggestedNextActions: [],
+  });
+}

package/src/runtime/control-plane/execution/work-completion-authority.ts

@@ -1,100 +1,45 @@
-import { completeRequirementFromWork } from '../persistence/requirement-store';
 import {
-  appendWorkEvidence,
+  isDirectEditWorkCompletionReceipt,
+  isRepositoryCompletionReceipt,
   recordWorkCompletionReceipt,
   type WorkContractStoreOptions,
 } from '../../../../packages/kernel/work/api/index';
 import type { WorkContract, WorkKind } from '../facade/types';
-import { completePlanStepForWork } from '../facade/plan-contract-store';
-
-export interface WorkRequirementProjectionResult {
-  attempted: boolean;
-  ok: boolean;
-  warning?: string;
-}
-
-export interface WorkPlanProjectionResult {
-  attempted: boolean;
-  ok: boolean;
-  warning?: string;
-}
-
-/**
- * Project one already-terminal Work receipt into Requirement semantic review.
- * Work completion remains authoritative; Requirement projection is downstream
- * and must never turn a durable completion receipt back into a failed Work.
- */
-export function projectRequirementDeliveryFromCompletedWork(
-  options: WorkContractStoreOptions,
-  work: WorkContract,
-): WorkRequirementProjectionResult {
-  if (!work.requirementId || !options.controllerHome) return { attempted: false, ok: true };
-  try {
-    completeRequirementFromWork(
-      { controllerHome: options.controllerHome },
-      { requirementId: work.requirementId, work },
-    );
-    return { attempted: true, ok: true };
-  } catch (error) {
-    const warning = `Work completion remains authoritative; Requirement projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000);
-    try {
-      appendWorkEvidence(options, work.workId, {
-        title: 'requirement completion projection pending',
-        summary: warning,
-        detailLevel: 'summary',
-      });
-    } catch {
-      // The completion receipt is already canonical and durable. Diagnostic
-      // persistence is downstream and cannot invalidate terminal Work state.
-    }
-    return { attempted: true, ok: false, warning };
-  }
-}
 
 /**
- * Project one already-terminal Work receipt into Plan semantic validation.
- * Work completion remains authoritative; Plan projection is downstream and
- * must never turn a durable completion receipt back into a failed Work.
+ * Record physical delivery/effect evidence without changing semantic Work state.
+ * The historical completionReceipt/completionOutcome field names are retained as
+ * storage compatibility only. Model/user completion is work_complete CAS.
  */
-export function projectPlanDeliveryFromCompletedWork(
-  options: WorkContractStoreOptions,
-  work: WorkContract,
-): WorkPlanProjectionResult {
-  if (!work.planId?.trim() || !work.planStepId?.trim() || !options.controllerHome || !options.repoId) {
-    return { attempted: false, ok: true };
-  }
-  try {
-    completePlanStepForWork(
-      { controllerHome: options.controllerHome, repoId: options.repoId },
-      { planId: work.planId, stepId: work.planStepId, work },
-    );
-    return { attempted: true, ok: true };
-  } catch (error) {
-    const warning = `Work completion remains authoritative; Plan projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000);
-    try {
-      appendWorkEvidence(options, work.workId, {
-        title: 'plan step delivery projection pending',
-        summary: warning,
-        detailLevel: 'summary',
-      });
-    } catch {
-      // The completion receipt is already canonical and durable. Diagnostic
-      // persistence is downstream and cannot invalidate terminal Work state.
-    }
-    return { attempted: true, ok: false, warning };
-  }
-}
-
-/** Record the canonical Work completion fact, then update downstream semantic review state. */
-export function completeWorkWithReceipt(
+export function recordWorkDeliveryReceipt(
   options: WorkContractStoreOptions,
   workId: string,
   receipt: NonNullable<WorkContract['completionReceipt']>,
   completionOutcome: NonNullable<WorkContract['completionOutcome']>,
   completionWorkKind?: WorkKind,
 ): WorkContract {
-  const recorded = recordWorkCompletionReceipt(options, workId, receipt, completionOutcome, completionWorkKind);
-  projectRequirementDeliveryFromCompletedWork(options, recorded);
-  projectPlanDeliveryFromCompletedWork(options, recorded);
-  return recorded;
+  return recordWorkCompletionReceipt(options, workId, receipt, completionOutcome, completionWorkKind);
+}
+
+/**
+ * True only when the mechanical delivery/effect has durably settled and no
+ * resource blocker remains. Semantic Work completion is deliberately separate:
+ * an open Work with this evidence still requires explicit work_complete CAS.
+ */
+export function hasSettledWorkDeliveryReceipt(
+  work: Pick<WorkContract, 'completionReceipt' | 'evidenceState'>,
+): boolean {
+  const receipt = work.completionReceipt;
+  if (!receipt) return false;
+  if (isRepositoryCompletionReceipt(receipt) || isDirectEditWorkCompletionReceipt(receipt)) {
+    // Repository delivery authority is current only while exact validation
+    // remains valid. Same-Work repair marks it stale before mutation, preserving
+    // the historical receipt without letting it authorize a different HEAD.
+    return work.evidenceState === 'valid'
+      && receipt.delivery.status === 'integrated'
+      && receipt.delivery.reachable === true
+      && receipt.cleanup.status === 'complete'
+      && receipt.cleanup.blockers.length === 0;
+  }
+  return true;
 }