@moretea-labs/forge 1.7.2 → 1.8.0

package/src/runtime/control-plane/persistence/operational-prior-store.ts

@@ -0,0 +1,348 @@
+import { createHash } from 'crypto';
+import {
+  OPERATIONAL_SIGNAL_DEFINITIONS,
+  OPERATIONAL_TARGET_DEFINITIONS,
+  reduceOperationalObservations,
+  resolveOperationalShadowPrior,
+  type OperationalObservation,
+  type OperationalShadowPrior,
+} from '../../../../packages/kernel/memory/api/index';
+import { extractProcessCheckShadowObservation } from '../../evidence/operational-shadow';
+import { processCheckCompletionReceipt } from '../../execution/process-runtime/check-receipt';
+import { getProcessRecord } from '../../execution/process-runtime/store';
+import {
+  deleteControlPlaneRecord,
+  deleteControlPlaneRecords,
+  readControlPlaneRecord,
+  writeControlPlaneRecord,
+} from './sqlite-store';
+
+export const OPERATIONAL_MEMORY_NAMESPACE = 'operational_memory_prior';
+export const CHECK_COMPLETION_GRACE_TARGET = 'check_completion_grace' as const;
+export const CHECK_COMPLETION_GRACE_ACTION = 'observed_check' as const;
+export const CHECK_COMPLETION_GRACE_MAX_MS = 250;
+const SCHEMA_VERSION = 1;
+const SIGNAL_ID = 'process_check.terminal_mechanical' as const;
+const CHECK_COMPLETION_GRACE_MAX_SAMPLES = OPERATIONAL_TARGET_DEFINITIONS[CHECK_COMPLETION_GRACE_TARGET].activationThreshold.maxSamples;
+
+type ProcessRecordLoader = typeof getProcessRecord;
+export interface OperationalPriorStoreDependencies {
+  loadProcessRecord?: ProcessRecordLoader;
+  now?: () => Date;
+}
+
+interface CheckCompletionGraceSupport {
+  processId: string;
+  receiptId: string;
+  finishedAt: string;
+}
+
+export interface CheckCompletionGracePriorRecord {
+  schemaVersion: 1;
+  repoId: string;
+  checkId: string;
+  environmentFingerprint: string;
+  targetId: typeof CHECK_COMPLETION_GRACE_TARGET;
+  actionId: typeof CHECK_COMPLETION_GRACE_ACTION;
+  prior: OperationalShadowPrior;
+  support: CheckCompletionGraceSupport[];
+  updatedAt: string;
+}
+
+function nowIso(deps: OperationalPriorStoreDependencies): string {
+  return (deps.now?.() ?? new Date()).toISOString();
+}
+
+function recordKey(checkId: string, environmentFingerprint: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ targetId: CHECK_COMPLETION_GRACE_TARGET, checkId, environmentFingerprint }))
+    .digest('hex')
+    .slice(0, 32);
+}
+
+function boundedText(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= 256;
+}
+
+function validInstant(value: unknown): value is string {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+
+function validRecord(value: unknown): value is CheckCompletionGracePriorRecord {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Partial<CheckCompletionGracePriorRecord>;
+  if (record.schemaVersion !== 1
+    || record.targetId !== CHECK_COMPLETION_GRACE_TARGET
+    || record.actionId !== CHECK_COMPLETION_GRACE_ACTION
+    || !boundedText(record.repoId)
+    || !boundedText(record.checkId)
+    || !boundedText(record.environmentFingerprint)
+    || !validInstant(record.updatedAt)
+    || !Array.isArray(record.support)
+    || record.support.length > CHECK_COMPLETION_GRACE_MAX_SAMPLES
+    || record.support.some((entry) => !entry
+      || !boundedText(entry.processId)
+      || !boundedText(entry.receiptId)
+      || !validInstant(entry.finishedAt))) return false;
+
+  const prior = record.prior;
+  if (!prior || typeof prior !== 'object'
+    || prior.schemaVersion !== 1
+    || prior.mode !== 'shadow'
+    || prior.targetId !== CHECK_COMPLETION_GRACE_TARGET
+    || prior.actionId !== CHECK_COMPLETION_GRACE_ACTION
+    || prior.metricId !== 'latency_ms'
+    || prior.scope?.schemaVersion !== 1
+    || prior.scope.kind !== 'project'
+    || prior.scope.id !== record.repoId
+    || prior.compatibility?.operation !== `check:${record.checkId}`
+    || prior.compatibility.environment !== record.environmentFingerprint
+    || !Number.isFinite(prior.estimate)
+    || !Number.isInteger(prior.sampleCount)
+    || prior.sampleCount < 1
+    || prior.sampleCount > CHECK_COMPLETION_GRACE_MAX_SAMPLES
+    || !Number.isInteger(prior.distinctEvidenceCount)
+    || prior.distinctEvidenceCount < 1
+    || prior.distinctEvidenceCount > prior.sampleCount
+    || !validInstant(prior.latestObservedAt)
+    || !validInstant(prior.replayHorizonEndsAt)
+    || !Array.isArray(prior.supportEvidenceRefs)
+    || prior.supportEvidenceRefs.length !== prior.sampleCount
+    || prior.supportEvidenceRefs.some((entry) => !boundedText(entry))
+    || !Array.isArray(prior.sourceObservationIds)
+    || prior.sourceObservationIds.length !== prior.sampleCount
+    || prior.sourceObservationIds.some((entry) => !boundedText(entry))
+    || (prior.readiness !== 'insufficient_samples' && prior.readiness !== 'shadow_candidate')
+    || record.support.length !== prior.sampleCount) return false;
+  return true;
+}
+
+function retainedUntil(finishedAt: string): string | undefined {
+  const finished = Date.parse(finishedAt);
+  if (!Number.isFinite(finished)) return undefined;
+  return new Date(finished + OPERATIONAL_SIGNAL_DEFINITIONS[SIGNAL_ID].retentionHorizonMs).toISOString();
+}
+
+function replayFromProcesses(input: {
+  controllerHome: string;
+  repoId: string;
+  processIds: readonly string[];
+  expectedSupport?: readonly CheckCompletionGraceSupport[];
+  checkId: string;
+  environmentFingerprint: string;
+  asOf: string;
+}, deps: OperationalPriorStoreDependencies): {
+  replayGap: boolean;
+  prior?: OperationalShadowPrior;
+  support: CheckCompletionGraceSupport[];
+} {
+  const load = deps.loadProcessRecord ?? getProcessRecord;
+  const observations: OperationalObservation[] = [];
+  const support: CheckCompletionGraceSupport[] = [];
+  const expectedSupport = new Map((input.expectedSupport ?? []).map((entry) => [entry.processId, entry] as const));
+  const seen = new Set<string>();
+  for (const processId of input.processIds) {
+    if (!processId || seen.has(processId)) continue;
+    seen.add(processId);
+    const process = load(input.controllerHome, input.repoId, processId);
+    if (!process) return { replayGap: true, support: [] };
+    let receipt;
+    try {
+      receipt = processCheckCompletionReceipt(process);
+    } catch {
+      return { replayGap: true, support: [] };
+    }
+    if (receipt.status !== 'passed' || !receipt.requestId || !receipt.checkEnvironmentFingerprint) {
+      return { replayGap: true, support: [] };
+    }
+    if (receipt.checkId !== input.checkId || receipt.checkEnvironmentFingerprint !== input.environmentFingerprint) {
+      return { replayGap: true, support: [] };
+    }
+    const expected = expectedSupport.get(processId);
+    if (expected && (receipt.receiptId !== expected.receiptId || receipt.finishedAt !== expected.finishedAt)) {
+      return { replayGap: true, support: [] };
+    }
+    const until = retainedUntil(receipt.finishedAt);
+    if (!until) return { replayGap: true, support: [] };
+    observations.push(extractProcessCheckShadowObservation(receipt, {
+      targetId: CHECK_COMPLETION_GRACE_TARGET,
+      actionId: CHECK_COMPLETION_GRACE_ACTION,
+      metricId: 'latency_ms',
+      scope: { schemaVersion: 1, kind: 'project', id: input.repoId },
+      consumerRequestId: receipt.requestId,
+      retainedUntil: until,
+      environmentFingerprint: receipt.checkEnvironmentFingerprint,
+    }));
+    support.push({ processId, receiptId: receipt.receiptId, finishedAt: receipt.finishedAt });
+  }
+  const maxSamples = CHECK_COMPLETION_GRACE_MAX_SAMPLES;
+  const ordered = support
+    .map((entry, index) => ({ entry, observation: observations[index]! }))
+    .sort((a, b) => a.entry.finishedAt.localeCompare(b.entry.finishedAt) || a.entry.processId.localeCompare(b.entry.processId))
+    .slice(-maxSamples);
+  const reduction = reduceOperationalObservations({ observations: ordered.map((item) => item.observation), asOf: input.asOf });
+  const prior = reduction.priors.find((candidate) => candidate.targetId === CHECK_COMPLETION_GRACE_TARGET
+    && candidate.actionId === CHECK_COMPLETION_GRACE_ACTION
+    && candidate.metricId === 'latency_ms'
+    && candidate.compatibility.operation === `check:${input.checkId}`
+    && candidate.compatibility.environment === input.environmentFingerprint);
+  return { replayGap: false, prior, support: ordered.map((item) => item.entry) };
+}
+
+function deleteRecord(
+  controllerHome: string,
+  repoId: string,
+  checkId: string,
+  environmentFingerprint: string,
+  action: string,
+  expectedRevision: number,
+): void {
+  deleteControlPlaneRecord(controllerHome, {
+    namespace: OPERATIONAL_MEMORY_NAMESPACE,
+    scope: repoId,
+    key: recordKey(checkId, environmentFingerprint),
+    action,
+    expectedRevision,
+  });
+}
+
+export function ingestCheckCompletionGraceProcess(input: {
+  controllerHome: string;
+  repoId: string;
+  processId: string;
+}, deps: OperationalPriorStoreDependencies = {}): { stored: boolean; readiness?: OperationalShadowPrior['readiness']; sampleCount?: number } {
+  const load = deps.loadProcessRecord ?? getProcessRecord;
+  const process = load(input.controllerHome, input.repoId, input.processId);
+  if (!process) return { stored: false };
+  let receipt;
+  try {
+    receipt = processCheckCompletionReceipt(process);
+  } catch {
+    return { stored: false };
+  }
+  // The active consumer learns only exact successful latency. Failed receipts are
+  // intentionally excluded because a raw Process receipt does not itself prove
+  // acceptance-vs-infrastructure failure semantics.
+  if (receipt.status !== 'passed' || !receipt.requestId || !receipt.checkEnvironmentFingerprint) return { stored: false };
+  const checkId = receipt.checkId;
+  const environmentFingerprint = receipt.checkEnvironmentFingerprint;
+  const key = recordKey(checkId, environmentFingerprint);
+  const existing = readControlPlaneRecord<CheckCompletionGracePriorRecord>(input.controllerHome, OPERATIONAL_MEMORY_NAMESPACE, input.repoId, key);
+  const previousIds = existing && validRecord(existing.value) ? existing.value.support.map((entry) => entry.processId) : [];
+  const asOf = nowIso(deps);
+  let replay = replayFromProcesses({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    processIds: [...previousIds, input.processId],
+    expectedSupport: existing && validRecord(existing.value) ? existing.value.support : undefined,
+    checkId,
+    environmentFingerprint,
+    asOf,
+  }, deps);
+  let expectedRevision = existing?.revision ?? null;
+  if (replay.replayGap && existing) {
+    deleteRecord(input.controllerHome, input.repoId, checkId, environmentFingerprint, 'operational_memory_replay_gap', existing.revision);
+    expectedRevision = null;
+    replay = replayFromProcesses({
+      controllerHome: input.controllerHome,
+      repoId: input.repoId,
+      processIds: [input.processId],
+      checkId,
+      environmentFingerprint,
+      asOf,
+    }, deps);
+  }
+  if (replay.replayGap || !replay.prior) return { stored: false };
+  const value: CheckCompletionGracePriorRecord = {
+    schemaVersion: SCHEMA_VERSION,
+    repoId: input.repoId,
+    checkId,
+    environmentFingerprint,
+    targetId: CHECK_COMPLETION_GRACE_TARGET,
+    actionId: CHECK_COMPLETION_GRACE_ACTION,
+    prior: replay.prior,
+    support: replay.support,
+    updatedAt: asOf,
+  };
+  const unchanged = existing && validRecord(existing.value)
+    && JSON.stringify(existing.value.prior) === JSON.stringify(value.prior)
+    && JSON.stringify(existing.value.support) === JSON.stringify(value.support);
+  if (!unchanged) {
+    writeControlPlaneRecord(input.controllerHome, {
+      namespace: OPERATIONAL_MEMORY_NAMESPACE,
+      scope: input.repoId,
+      key,
+      schemaVersion: SCHEMA_VERSION,
+      value,
+      action: 'operational_memory_replay_materialize',
+      expectedRevision,
+    });
+  }
+  return { stored: true, readiness: replay.prior.readiness, sampleCount: replay.prior.sampleCount };
+}
+
+function resolveCheckCompletionGraceWaitMsUnsafe(input: {
+  controllerHome: string;
+  repoId: string;
+  checkId: string;
+  environmentFingerprint: string;
+}, deps: OperationalPriorStoreDependencies): number | undefined {
+  const key = recordKey(input.checkId, input.environmentFingerprint);
+  const stored = readControlPlaneRecord<CheckCompletionGracePriorRecord>(input.controllerHome, OPERATIONAL_MEMORY_NAMESPACE, input.repoId, key);
+  if (!stored) return undefined;
+  if (!validRecord(stored.value)
+    || stored.value.repoId !== input.repoId
+    || stored.value.checkId !== input.checkId
+    || stored.value.environmentFingerprint !== input.environmentFingerprint
+    || stored.value.support.some((entry) => !entry || typeof entry.processId !== 'string' || typeof entry.receiptId !== 'string' || typeof entry.finishedAt !== 'string')) {
+    deleteRecord(input.controllerHome, input.repoId, input.checkId, input.environmentFingerprint, 'operational_memory_invalid_record', stored.revision);
+    return undefined;
+  }
+  const asOf = nowIso(deps);
+  const replay = replayFromProcesses({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    processIds: stored.value.support.map((entry) => entry.processId),
+    expectedSupport: stored.value.support,
+    checkId: input.checkId,
+    environmentFingerprint: input.environmentFingerprint,
+    asOf,
+  }, deps);
+  if (replay.replayGap || !replay.prior) {
+    deleteRecord(input.controllerHome, input.repoId, input.checkId, input.environmentFingerprint, 'operational_memory_replay_gap', stored.revision);
+    return undefined;
+  }
+  const retainedEvidenceRefs = new Set(replay.prior.supportEvidenceRefs);
+  const resolved = resolveOperationalShadowPrior({
+    prior: replay.prior,
+    compatibility: { operation: `check:${input.checkId}`, environment: input.environmentFingerprint },
+    retainedEvidenceRefs,
+    asOf,
+  });
+  if (resolved.status !== 'shadow_candidate') return undefined;
+  if (resolved.prior.estimate > CHECK_COMPLETION_GRACE_MAX_MS) return undefined;
+  return CHECK_COMPLETION_GRACE_MAX_MS;
+}
+
+export function resolveCheckCompletionGraceWaitMs(input: {
+  controllerHome: string;
+  repoId: string;
+  checkId: string;
+  environmentFingerprint: string;
+}, deps: OperationalPriorStoreDependencies = {}): number | undefined {
+  try {
+    return resolveCheckCompletionGraceWaitMsUnsafe(input, deps);
+  } catch {
+    // This namespace is a disposable optimization. Corruption, SQLite contention,
+    // replay gaps, or stale derived records must degrade to the canonical wait.
+    return undefined;
+  }
+}
+
+export function dropOperationalMemoryNamespace(controllerHome: string, repoId: string): number {
+  return deleteControlPlaneRecords(controllerHome, {
+    namespace: OPERATIONAL_MEMORY_NAMESPACE,
+    scope: repoId,
+    action: 'operational_memory_drop',
+  });
+}

package/src/runtime/control-plane/persistence/requirement-store.ts

@@ -8,9 +8,8 @@ import {
   type SqliteDatabase,
 } from './sqlite-store';
 import { isRepositoryCompletionReceipt, type WorkContract } from '../facade/types';
-
-export const REQUIREMENT_STATES = ['planned', 'active', 'waiting_for_user', 'done', 'cancelled'] as const;
-export type RequirementState = (typeof REQUIREMENT_STATES)[number];
+import { REQUIREMENT_STATE_TRANSITIONS, type RequirementState } from '../../../../packages/kernel/goal/api/index';
+export { REQUIREMENT_STATES, type RequirementState } from '../../../../packages/kernel/goal/api/index';
 
 export interface Requirement {
   schemaVersion: 1;
@@ -25,6 +24,12 @@ export interface Requirement {
   state: RequirementState;
   needsAttention: boolean;
   attentionSummary?: string;
+  semanticAcceptance?: {
+    reviewer: string;
+    rationale: string;
+    planIds: string[];
+    acceptedAt: string;
+  };
   revision: number;
   createdAt: string;
   updatedAt: string;
@@ -63,6 +68,11 @@ function bounded(values: readonly string[] | undefined, limit: number, maxLength
   return (values ?? []).map((value) => String(value).trim()).filter(Boolean).slice(0, limit).map((value) => value.slice(0, maxLength));
 }
 
+export function isLegacyMachineRequirementWait(requirement: Pick<Requirement, 'state' | 'attentionSummary'>): boolean {
+  return requirement.state === 'waiting_for_user'
+    && /^Work .+ delivered machine-valid evidence \(.+\); ChatGPT\/user semantic acceptance is still required\.$/.test(requirement.attentionSummary ?? '');
+}
+
 function readWithin(database: SqliteDatabase, requirementId: string): ControlPlaneRecord<Requirement> | undefined {
   return readControlPlaneRecordWithinTransaction(database, NAMESPACE, SCOPE, requirementId);
 }
@@ -122,14 +132,6 @@ export function createRequirement(
   return requirement;
 }
 
-const ALLOWED_TRANSITIONS: Readonly<Record<RequirementState, readonly RequirementState[]>> = {
-  planned: ['planned', 'active', 'waiting_for_user', 'cancelled'],
-  active: ['active', 'waiting_for_user', 'done', 'cancelled'],
-  waiting_for_user: ['waiting_for_user', 'planned', 'active', 'done', 'cancelled'],
-  done: ['done', 'cancelled'],
-  cancelled: ['cancelled'],
-};
-
 export function updateRequirement(
   options: RequirementStoreOptions,
   input: {
@@ -143,7 +145,8 @@ export function updateRequirement(
     const current = readWithin(database, requirementId);
     if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
     const next = input.mutate(current.value);
-    if (!ALLOWED_TRANSITIONS[current.value.state].includes(next.state)) {
+    if (next === current.value) return current.value;
+    if (!REQUIREMENT_STATE_TRANSITIONS[current.value.state].includes(next.state)) {
       throw new Error(`REQUIREMENT_STATE_TRANSITION_INVALID: ${current.value.state} -> ${next.state}`);
     }
     if (next.requirementId !== requirementId) throw new Error('REQUIREMENT_ID_IMMUTABLE');
@@ -179,10 +182,11 @@ export interface RequirementCompletionInput {
 }
 
 /**
- * Project machine-complete Work delivery into a Requirement without asserting
- * semantic acceptance. The Requirement waits for an explicit ChatGPT/user
- * decision; a previously audited `done` Requirement is never reopened by
- * historical execution evidence.
+ * Project machine-complete Work delivery evidence into a Requirement without
+ * asserting Requirement-level semantic acceptance. A Work is only one Plan-step
+ * execution fact; it must not move the whole Requirement to waiting_for_user
+ * while sibling/current Plan slices still exist. Requirement acceptance is a
+ * separate lifecycle decision after current Plan/Work authority converges.
  *
  * The legacy function name is retained for compatibility with completion
  * callers. Its authority is evidence projection only, not semantic completion.
@@ -212,20 +216,24 @@ export function completeRequirementFromWork(
   if (receipt.delivery.kind === 'superseded' || receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('REQUIREMENT_WORK_DELIVERY_NOT_PROVEN');
   if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('REQUIREMENT_WORK_CLEANUP_NOT_PROVEN');
 
-  if (current.value.state === 'waiting_for_user' && current.value.auditRefs.includes(receipt.receiptId)) return current.value;
+  if (current.value.auditRefs.includes(receipt.receiptId)) return current.value;
   return updateRequirement(options, {
     requirementId,
     action: 'requirement_delivery_evidence_recorded',
     mutate: (latest) => {
-      // Preserve a concurrent explicit semantic completion; stale execution
-      // evidence is never allowed to move a terminal Requirement backwards.
+      // Preserve concurrent terminal or genuinely user-blocked semantic state.
+      // Older V2 builds generated waiting_for_user from a single Work receipt;
+      // recognize that exact compatibility message and repair it back to active.
       if (latest.state === 'done') return latest;
       if (latest.state === 'cancelled') throw new Error('REQUIREMENT_CANCELLED');
+      const legacyMachineWait = latest.state === 'waiting_for_user'
+        && /^Work .+ delivered machine-valid evidence \(.+\); ChatGPT\/user semantic acceptance is still required\.$/.test(latest.attentionSummary ?? '');
+      const preserveSemanticWait = latest.state === 'waiting_for_user' && !legacyMachineWait;
       return {
         ...latest,
-        state: 'waiting_for_user',
-        needsAttention: false,
-        attentionSummary: `Work ${work.workId} delivered machine-valid evidence (${receipt.receiptId}); ChatGPT/user semantic acceptance is still required.`,
+        state: preserveSemanticWait ? 'waiting_for_user' : 'active',
+        needsAttention: preserveSemanticWait ? latest.needsAttention : false,
+        attentionSummary: preserveSemanticWait ? latest.attentionSummary : undefined,
         auditRefs: Array.from(new Set([...latest.auditRefs, receipt.receiptId])).slice(-50),
       };
     },