@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,9 +1,9 @@
 import { readForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
 import { resolveProjectForRepositoryPlacement } from '../workspace/workspace-store';
 import type { ScopeRef } from '../../../../packages/kernel/identity/api/index';
-import type { ExperienceRecord, ExperienceStorePort, OutcomeObservation, OutcomeObservationStorePort } from '../../../../packages/kernel/memory/api/index';
-import { getWorkContract, isTerminalWorkContractStatus, type WorkContract } from '../../../../packages/kernel/work/api/index';
-import { controllerSessionAuthorityMatches, getControllerRoundRelay, getControllerSession } from '../../../../packages/kernel/controller/api/index';
+import { recordExperience, recordOutcomeObservation, type ExperienceRecord, type ExperienceStorePort, type OutcomeObservation, type OutcomeObservationStorePort } from '../../../../packages/kernel/memory/api/index';
+import { getWorkContract, isTerminalSemanticWorkState, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { getControllerRoundRelay } from '../../../../packages/kernel/controller/api/index';
 import { readExecutionArtifact } from '../../evidence/artifact-store';
 import { readExecutionEvidence } from '../../evidence/evidence-store';
 import { assertControlPlaneMetadataPayload } from './metadata-payload-policy';
@@ -12,14 +12,45 @@ import { deleteControlPlaneRecordWithinTransaction, listControlPlaneRecords, lis
 
 export const EXPERIENCE_NAMESPACE = 'assistant_experience';
 export const OUTCOME_OBSERVATION_NAMESPACE = 'assistant_outcome_observation';
-export interface ExperienceWriteIdentity { workId: string; controllerId: string; authorityId: string }
+export interface ExperienceWriteIdentity {
+  workId: string;
+  /** Legacy provenance only; never execution or write authority. */
+  controllerId?: string;
+  /** Legacy provenance only; never execution or write authority. */
+  authorityId?: string;
+}
+export interface ClosedRoundLearningAuthority { workId: string; sourceRoundId: string }
+
+interface ExperienceStoreOptions {
+  controllerHome: string;
+  repoId: string;
+  identity?: ExperienceWriteIdentity;
+  closedRoundAuthority?: ClosedRoundLearningAuthority;
+  now?: () => string;
+}
+
+function resolvedProjectForWork(work: WorkContract, controllerHome?: string) {
+  if (!controllerHome) return undefined;
+  const instance = readForgeInstanceIdentity(controllerHome);
+  if (!instance) return undefined;
+  const declaredProject = work.scopeRef?.kind === 'project'
+    ? work.scopeRef.id
+    : work.engineeringContext?.projectContractReceipt?.projectId;
+  return resolveProjectForRepositoryPlacement({
+    controllerHome,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: work.repoId,
+    checkoutId: work.checkoutId,
+    projectId: declaredProject,
+  });
+}
 
 export function experienceScopesForWork(work: WorkContract, controllerHome?: string): ScopeRef[] {
   const scopes: ScopeRef[] = [{ schemaVersion: 1, kind: 'work', id: work.workId }];
-  const declaredProject = work.scopeRef?.kind === 'project' ? work.scopeRef.id : work.engineeringContext?.projectContractReceipt?.projectId;
-  const instance = controllerHome ? readForgeInstanceIdentity(controllerHome) : undefined;
-  const projectId = controllerHome && instance ? resolveProjectForRepositoryPlacement({ controllerHome,
-    forgeInstanceId: instance.instanceId, repositoryId: work.repoId, checkoutId: work.checkoutId, projectId: declaredProject })?.projectId ?? declaredProject : declaredProject;
+  const declaredProject = work.scopeRef?.kind === 'project'
+    ? work.scopeRef.id
+    : work.engineeringContext?.projectContractReceipt?.projectId;
+  const projectId = resolvedProjectForWork(work, controllerHome)?.projectId ?? declaredProject;
   if (projectId) scopes.push({ schemaVersion: 1, kind: 'project', id: projectId });
   if (work.requirementId) scopes.push({ schemaVersion: 1, kind: 'requirement', id: work.requirementId });
   if (work.planId) scopes.push({ schemaVersion: 1, kind: 'plan', id: work.planId });
@@ -28,23 +59,62 @@ export function experienceScopesForWork(work: WorkContract, controllerHome?: str
   return scopes;
 }
 
-function matchesScope(work: WorkContract, scope: ScopeRef, controllerHome: string): boolean {
+/**
+ * Cognitive recall may include portable Workspace guidance shared by sibling
+ * Projects. Raw Controller/Experience writes deliberately remain limited to
+ * experienceScopesForWork so project-local observations cannot bypass
+ * evidence-backed promotion into cross-project memory.
+ */
+export function cognitiveScopesForWork(work: WorkContract, controllerHome?: string): ScopeRef[] {
+  const scopes = experienceScopesForWork(work, controllerHome);
+  const workspaceId = resolvedProjectForWork(work, controllerHome)?.workspaceId;
+  if (workspaceId && !scopes.some(scope => scope.kind === 'workspace' && scope.id === workspaceId)) {
+    scopes.push({ schemaVersion: 1, kind: 'workspace', id: workspaceId });
+  }
+  return scopes;
+}
+
+function matchesExperienceScope(work: WorkContract, scope: ScopeRef, controllerHome: string): boolean {
   return experienceScopesForWork(work, controllerHome).some(candidate => candidate.kind === scope.kind && candidate.id === scope.id);
 }
 
-function canonicalWorkflowEvidenceAvailable(input: { controllerHome: string; repoId: string }, ref: string, scope: ScopeRef, sourceWorkId: string): boolean {
+function matchesCognitiveScope(work: WorkContract, scope: ScopeRef, controllerHome: string): boolean {
+  return cognitiveScopesForWork(work, controllerHome).some(candidate => candidate.kind === scope.kind && candidate.id === scope.id);
+}
+
+function isLegacyOutputLocatorMiss(error: unknown, kind: 'artifact' | 'evidence'): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return kind === 'artifact'
+    ? message.startsWith('ARTIFACT_LOCATOR_NOT_FOUND:')
+    : message.startsWith('EVIDENCE_LOCATOR_NOT_FOUND:');
+}
+
+export function canonicalWorkflowEvidenceAvailable(input: { controllerHome: string; repoId: string }, ref: string, scope: ScopeRef, sourceWorkId: string): boolean {
   try {
     const source = getWorkContract(input, sourceWorkId);
-    if (!source || !matchesScope(source, scope, input.controllerHome)) return false;
+    if (!source || !matchesCognitiveScope(source, scope, input.controllerHome)) return false;
     const linked = source.evidenceRefs.find(item => item.evidenceId === ref || item.artifactId === ref);
     if (linked) {
       if (ref.startsWith('ART-')) {
-        const artifact = readExecutionArtifact(input.controllerHome, input.repoId, ref, 16 * 1024);
+        let artifact;
+        try {
+          artifact = readExecutionArtifact(input.controllerHome, ref, 16 * 1024);
+        } catch (error) {
+          if (!isLegacyOutputLocatorMiss(error, 'artifact')) throw error;
+          artifact = readExecutionArtifact(input.controllerHome, ref, 16 * 1024, { legacyRepoId: input.repoId });
+        }
         return !artifact.truncated && artifact.artifact.kind === 'evidence';
       }
-      if (ref.startsWith('EVD-')) return readExecutionEvidence(input.controllerHome, input.repoId, ref).evidenceId === ref;
+      if (ref.startsWith('EVD-')) {
+        try { return readExecutionEvidence(input.controllerHome, ref).evidenceId === ref; }
+        catch (error) {
+          if (!isLegacyOutputLocatorMiss(error, 'evidence')) throw error;
+          return readExecutionEvidence(input.controllerHome, ref, { legacyRepoId: input.repoId }).evidenceId === ref;
+        }
+      }
     }
     if (source.checkRefs.some(check => check.receipt?.receiptId === ref && ['passed', 'failed'].includes(check.receipt.status))) return true;
+    if (source.engineeringContext?.blockerDispositions?.some(disposition => disposition.receiptId === ref)) return true;
     if (ref.startsWith('workflow-run-') || ref.startsWith('workflow-publication-')) {
       const runs = listControlPlaneRecords<WorkflowRunRecord>(input.controllerHome, { namespace: WORKFLOW_RUN_NAMESPACE, scope: sourceWorkId, limit: 1000 });
       return runs.some(row => row.value.evidenceRef === ref || row.value.publicationReceipt?.receiptId === ref);
@@ -57,23 +127,58 @@ function canonicalWorkflowEvidenceAvailable(input: { controllerHome: string; rep
   } catch { return false; }
 }
 
-function assertMemoryWriteAuthority(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity }, scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void {
+export function workExperienceProvenance(work: Pick<WorkContract, 'workId' | 'semanticRevision'>): string {
+  const revision = Number(work.semanticRevision);
+  return `work:${work.workId}:r${Number.isSafeInteger(revision) && revision > 0 ? revision : 'legacy'}`;
+}
+
+export function assertMemoryWriteAuthority(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity }, scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void {
   const identity = input.identity;
-  if (!identity) throw new Error('EXPERIENCE_CONTROLLER_REQUIRED');
-  const current = getWorkContract(input, identity.workId), source = getWorkContract(input, sourceWorkId);
-  if (!current || isTerminalWorkContractStatus(current.status) || !source || !matchesScope(current, scope, input.controllerHome) || !matchesScope(source, scope, input.controllerHome)) throw new Error('EXPERIENCE_WORK_SCOPE_MISMATCH');
-  const owner = getControllerSession(input, identity.workId);
-  if (!owner || owner.controllerId !== identity.controllerId) throw new Error('EXPERIENCE_CONTROLLER_NOT_OWNER');
-  const relay = getControllerRoundRelay(input, identity.workId);
-  if (relay) {
-    if (relay.status !== 'claimed' || relay.authorityId !== identity.authorityId || relay.claimGeneration !== owner.claimGeneration
-      || sourceRoundId !== `${relay.relayScopeId}:${relay.roundCount}`) throw new Error('EXPERIENCE_ROUND_AUTHORITY_MISMATCH');
-  } else if (!controllerSessionAuthorityMatches(owner, identity.authorityId)
-    || sourceRoundId !== `${identity.workId}:${owner.claimGeneration}`) throw new Error('EXPERIENCE_CLAIM_AUTHORITY_MISMATCH');
+  if (!identity?.workId?.trim()) throw new Error('EXPERIENCE_WORK_IDENTITY_REQUIRED');
+  const current = getWorkContract(input, identity.workId);
+  const source = getWorkContract(input, sourceWorkId);
+  if (!current || isTerminalSemanticWorkState(current.semanticState) || !source
+    || current.workId !== source.workId
+    || !matchesExperienceScope(current, scope, input.controllerHome)
+    || !matchesExperienceScope(source, scope, input.controllerHome)) {
+    throw new Error('EXPERIENCE_WORK_SCOPE_MISMATCH');
+  }
+  if (sourceRoundId !== workExperienceProvenance(source)) {
+    throw new Error('EXPERIENCE_WORK_PROVENANCE_MISMATCH');
+  }
+}
+
+function assertClosedRoundLearningWriteAuthority(
+  input: Pick<ExperienceStoreOptions, 'controllerHome' | 'repoId' | 'closedRoundAuthority'>,
+  scope: ScopeRef,
+  sourceWorkId: string,
+  sourceRoundId: string,
+): void {
+  const authority = input.closedRoundAuthority;
+  if (!authority || authority.workId !== sourceWorkId || authority.sourceRoundId !== sourceRoundId) {
+    throw new Error('EXPERIENCE_CLOSED_ROUND_AUTHORITY_MISMATCH');
+  }
+  const work = getWorkContract(input, authority.workId);
+  if (!work || isTerminalSemanticWorkState(work.semanticState) || !matchesExperienceScope(work, scope, input.controllerHome)) {
+    throw new Error('EXPERIENCE_CLOSED_ROUND_WORK_SCOPE_MISMATCH');
+  }
+  const relay = getControllerRoundRelay(input, authority.workId);
+  if (!relay?.observationWindow?.some(observation => observation.roundRef === sourceRoundId)) {
+    throw new Error('EXPERIENCE_CLOSED_ROUND_NOT_OBSERVED');
+  }
+}
+
+function assertExperienceStoreWriteAuthority(input: ExperienceStoreOptions, scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void {
+  if (input.identity && input.closedRoundAuthority) throw new Error('EXPERIENCE_WRITE_AUTHORITY_AMBIGUOUS');
+  if (input.closedRoundAuthority) {
+    assertClosedRoundLearningWriteAuthority(input, scope, sourceWorkId, sourceRoundId);
+    return;
+  }
+  assertMemoryWriteAuthority(input, scope, sourceWorkId, sourceRoundId);
 }
 
 /** One SQLite writer; nested domain operations share the same transaction. */
-export function controllerExperienceStore(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity; now?: () => string }): ExperienceStorePort {
+export function controllerExperienceStore(input: ExperienceStoreOptions): ExperienceStorePort {
   let transaction: SqliteDatabase | undefined;
   const key = (scope: ScopeRef) => `${scope.kind}:${scope.id}`;
   const work = (id: string) => getWorkContract(input, id);
@@ -86,7 +191,7 @@ export function controllerExperienceStore(input: { controllerHome: string; repoI
       });
     },
     assertWriteAuthority(scope, sourceWorkId, sourceRoundId) {
-      assertMemoryWriteAuthority(input, scope, sourceWorkId, sourceRoundId);
+      assertExperienceStoreWriteAuthority(input, scope, sourceWorkId, sourceRoundId);
     },
     evidenceAvailable(ref, scope, sourceWorkId) {
       return canonicalWorkflowEvidenceAvailable(input, ref, scope, sourceWorkId);
@@ -113,7 +218,21 @@ export function controllerExperienceStore(input: { controllerHome: string; repoI
   };
 }
 
-export function controllerOutcomeObservationStore(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity; now?: () => string }): OutcomeObservationStorePort {
+export function recordClosedRoundExperience(input: {
+  controllerHome: string;
+  repoId: string;
+  authority: ClosedRoundLearningAuthority;
+  record: ExperienceRecord;
+  now?: string;
+}): ExperienceRecord {
+  return recordExperience(
+    controllerExperienceStore({ controllerHome: input.controllerHome, repoId: input.repoId, closedRoundAuthority: input.authority }),
+    input.record,
+    input.now,
+  );
+}
+
+export function controllerOutcomeObservationStore(input: ExperienceStoreOptions): OutcomeObservationStorePort {
   let transaction: SqliteDatabase | undefined;
   const key = (scope: ScopeRef) => `${scope.kind}:${scope.id}`;
   return {
@@ -124,7 +243,7 @@ export function controllerOutcomeObservationStore(input: { controllerHome: strin
         try { return operation(); } finally { transaction = undefined; }
       });
     },
-    assertWriteAuthority(scope, sourceWorkId, sourceRoundId) { assertMemoryWriteAuthority(input, scope, sourceWorkId, sourceRoundId); },
+    assertWriteAuthority(scope, sourceWorkId, sourceRoundId) { assertExperienceStoreWriteAuthority(input, scope, sourceWorkId, sourceRoundId); },
     evidenceAvailable(ref, scope, sourceWorkId) { return canonicalWorkflowEvidenceAvailable(input, ref, scope, sourceWorkId); },
     read(scope, id) {
       const row = transaction ? readControlPlaneRecordWithinTransaction<OutcomeObservation>(transaction, OUTCOME_OBSERVATION_NAMESPACE, key(scope), id)
@@ -146,6 +265,20 @@ export function controllerOutcomeObservationStore(input: { controllerHome: strin
   };
 }
 
+export function recordClosedRoundOutcomeObservation(input: {
+  controllerHome: string;
+  repoId: string;
+  authority: ClosedRoundLearningAuthority;
+  observation: OutcomeObservation;
+  now?: string;
+}): OutcomeObservation {
+  return recordOutcomeObservation(
+    controllerOutcomeObservationStore({ controllerHome: input.controllerHome, repoId: input.repoId, closedRoundAuthority: input.authority }),
+    input.observation,
+    input.now,
+  );
+}
+
 /** Called by central maintenance, never by recall. A 30-day terminal grace preserves diagnosis. */
 export function cleanupExpiredExperiences(controllerHome: string, now = new Date().toISOString(), limit = 100): number {
   const at = Date.parse(now);

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

@@ -1,5 +1,6 @@
 import {
   listControlPlaneRecords,
+  listControlPlaneRecordsWithinTransaction,
   readControlPlaneRecord,
   readControlPlaneRecordWithinTransaction,
   withControlPlaneTransaction,
@@ -7,8 +8,8 @@ import {
   type ControlPlaneRecord,
   type SqliteDatabase,
 } from './sqlite-store';
-import { isRepositoryCompletionReceipt, type WorkContract } from '../facade/types';
 import { REQUIREMENT_STATE_TRANSITIONS, type RequirementState } from '../../../../packages/kernel/goal/api/index';
+import type { ScopeRef } from '../../../../packages/kernel/identity/api/index';
 export { REQUIREMENT_STATES, type RequirementState } from '../../../../packages/kernel/goal/api/index';
 
 export interface Requirement {
@@ -30,6 +31,10 @@ export interface Requirement {
     planIds: string[];
     acceptedAt: string;
   };
+  /** Semantic authored-context revision. Legacy rows normalize to semantic revision 1 until first thin semantic write. */
+  semanticRevision?: number;
+  /** Timestamp of the authored semantic content; mechanical Requirement updates must not change it. */
+  semanticUpdatedAt?: string;
   revision: number;
   createdAt: string;
   updatedAt: string;
@@ -48,9 +53,41 @@ export interface CreateRequirementInput {
   outcomeStatement: string;
   acceptanceCriteria?: string[];
   requiredDeliveryReferences?: string[];
+  /** Authority-derived provenance only; raw transports must not pass arbitrary audit refs. */
+  auditRefs?: string[];
+}
+
+export type SemanticRequirementState = 'open' | 'completed' | 'cancelled';
+
+export interface RequirementSemanticView {
+  requirementId: string;
+  revision: number;
+  semanticScope: ScopeRef;
+  title: string;
+  outcomeStatement: string;
+  acceptanceCriteria: string[];
+  requiredDeliveryReferences: string[];
+  state: SemanticRequirementState;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface RequirementRevisionRecord extends RequirementSemanticView {
+  schemaVersion: 1;
+  recordedAt: string;
+}
+
+export interface ReviseRequirementSemanticInput {
+  expectedRevision: number;
+  title?: string;
+  outcomeStatement?: string;
+  acceptanceCriteria?: string[];
+  requiredDeliveryReferences?: string[];
+  state?: SemanticRequirementState;
 }
 
 const NAMESPACE = 'requirement';
+const REVISION_NAMESPACE = 'requirement_revision';
 const SCOPE = 'controller';
 const SCHEMA_VERSION = 1;
 
@@ -68,6 +105,36 @@ 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 currentRequirementSemanticRevision(requirement: Requirement): number {
+  const semantic = Number(requirement.semanticRevision);
+  return Number.isInteger(semantic) && semantic > 0 ? semantic : 1;
+}
+
+export function semanticRequirementState(requirement: Pick<Requirement, 'state'>): SemanticRequirementState {
+  if (requirement.state === 'done') return 'completed';
+  if (requirement.state === 'cancelled') return 'cancelled';
+  return 'open';
+}
+
+export function requirementSemanticView(requirement: Requirement): RequirementSemanticView {
+  return {
+    requirementId: requirement.requirementId,
+    revision: currentRequirementSemanticRevision(requirement),
+    semanticScope: { schemaVersion: 1, kind: 'requirement', id: requirement.requirementId },
+    title: requirement.title,
+    outcomeStatement: requirement.outcomeStatement,
+    acceptanceCriteria: [...requirement.acceptanceCriteria],
+    requiredDeliveryReferences: [...requirement.requiredDeliveryReferences],
+    state: semanticRequirementState(requirement),
+    createdAt: requirement.createdAt,
+    updatedAt: requirement.semanticUpdatedAt ?? requirement.createdAt,
+  };
+}
+
+function requirementRevisionKey(requirementId: string, revision: number): string {
+  return `${id(requirementId)}:r${revision}`;
+}
+
 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 ?? '');
@@ -95,6 +162,98 @@ export function listRequirements(
   });
 }
 
+/** Exact historical lookup, independent of global revision-list limits. */
+export function getRequirementRevisionRecord(
+  options: RequirementStoreOptions,
+  requirementId: string,
+  revision: number,
+): RequirementRevisionRecord | undefined {
+  if (!Number.isInteger(revision) || revision < 1) return undefined;
+  const record = readControlPlaneRecord<RequirementRevisionRecord>(
+    options.controllerHome, REVISION_NAMESPACE, SCOPE, requirementRevisionKey(requirementId, revision),
+  )?.value;
+  return record ? {
+    ...record,
+    semanticScope: record.semanticScope ?? { schemaVersion: 1, kind: 'requirement', id: record.requirementId },
+  } : undefined;
+}
+
+export function listRequirementRevisionRecords(
+  options: RequirementStoreOptions,
+  requirementId?: string,
+  limit = 200,
+): RequirementRevisionRecord[] {
+  const normalizedId = requirementId ? id(requirementId) : undefined;
+  return listControlPlaneRecords<RequirementRevisionRecord>(options.controllerHome, {
+    namespace: REVISION_NAMESPACE,
+    scope: SCOPE,
+    limit: Math.max(1, Math.min(Math.trunc(limit), 1000)),
+  }).map((record) => record.value)
+    .filter((record) => !normalizedId || record.requirementId === normalizedId)
+    .map((record) => ({
+      ...record,
+      semanticScope: record.semanticScope ?? ({ schemaVersion: 1, kind: 'requirement', id: record.requirementId } as const),
+    }))
+    .sort((left, right) => right.revision - left.revision);
+}
+
+export function reviseRequirementSemantic(
+  options: RequirementStoreOptions,
+  requirementIdInput: string,
+  input: ReviseRequirementSemanticInput,
+): Requirement {
+  const requirementId = id(requirementIdInput);
+  if (!Number.isInteger(input.expectedRevision) || input.expectedRevision < 1) throw new Error('REQUIREMENT_EXPECTED_REVISION_INVALID');
+  return withControlPlaneTransaction(options.controllerHome, (database) => {
+    const current = readWithin(database, requirementId);
+    if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
+    const semanticRevision = currentRequirementSemanticRevision(current.value);
+    if (semanticRevision !== input.expectedRevision) {
+      throw new Error(`REQUIREMENT_REVISION_CONFLICT:${requirementId}:expected=${input.expectedRevision}:actual=${semanticRevision}`);
+    }
+    const at = nowIso(options);
+    const revisionKey = requirementRevisionKey(requirementId, semanticRevision);
+    if (!readControlPlaneRecordWithinTransaction<RequirementRevisionRecord>(database, REVISION_NAMESPACE, SCOPE, revisionKey)) {
+      const archived: RequirementRevisionRecord = { schemaVersion: 1, ...requirementSemanticView(current.value), recordedAt: at };
+      writeControlPlaneRecordWithinTransaction(database, {
+        namespace: REVISION_NAMESPACE, scope: SCOPE, key: revisionKey, schemaVersion: 1,
+        value: archived, action: 'requirement_semantic_revision_archived', expectedRevision: null,
+      });
+    }
+    const requestedState = input.state;
+    if (requestedState === 'open' && (current.value.state === 'done' || current.value.state === 'cancelled')) {
+      throw new Error(`REQUIREMENT_SEMANTIC_REOPEN_FORBIDDEN:${requirementId}:${current.value.state}`);
+    }
+    const legacyState: RequirementState = requestedState === 'completed'
+      ? 'done'
+      : requestedState === 'cancelled'
+        ? 'cancelled'
+        : requestedState === 'open'
+          ? 'active'
+          : current.value.state;
+    const title = input.title === undefined ? current.value.title : String(input.title).trim().slice(0, 500);
+    const outcomeStatement = input.outcomeStatement === undefined ? current.value.outcomeStatement : String(input.outcomeStatement).trim().slice(0, 2_000);
+    if (!title || !outcomeStatement) throw new Error('REQUIREMENT_CONTENT_REQUIRED');
+    const updated: Requirement = {
+      ...current.value,
+      title,
+      outcomeStatement,
+      acceptanceCriteria: input.acceptanceCriteria === undefined ? [...current.value.acceptanceCriteria] : bounded(input.acceptanceCriteria, 50),
+      requiredDeliveryReferences: input.requiredDeliveryReferences === undefined ? [...current.value.requiredDeliveryReferences] : bounded(input.requiredDeliveryReferences, 50),
+      state: legacyState,
+      ...(requestedState ? { needsAttention: false, attentionSummary: undefined } : {}),
+      semanticRevision: semanticRevision + 1,
+      semanticUpdatedAt: at,
+      revision: current.value.revision + 1,
+      updatedAt: at,
+    };
+    return writeControlPlaneRecordWithinTransaction(database, {
+      namespace: NAMESPACE, scope: SCOPE, key: requirementId, schemaVersion: SCHEMA_VERSION,
+      value: updated, action: 'requirement_semantic_revised', expectedRevision: current.revision,
+    }).value;
+  });
+}
+
 export function createRequirement(
   options: RequirementStoreOptions,
   input: CreateRequirementInput,
@@ -109,16 +268,29 @@ export function createRequirement(
     outcomeStatement: String(input.outcomeStatement ?? '').trim().slice(0, 2_000),
     acceptanceCriteria: bounded(input.acceptanceCriteria, 50),
     requiredDeliveryReferences: bounded(input.requiredDeliveryReferences, 50),
+    auditRefs: bounded(input.auditRefs, 50),
     state: 'planned',
     needsAttention: false,
+    semanticRevision: 1,
+    semanticUpdatedAt: at,
     revision: 1,
     createdAt: at,
     updatedAt: at,
-    auditRefs: [],
   };
   if (!requirement.title || !requirement.outcomeStatement) throw new Error('REQUIREMENT_CONTENT_REQUIRED');
   withControlPlaneTransaction(options.controllerHome, (database) => {
     if (readWithin(database, requirementId)) throw new Error(`REQUIREMENT_ALREADY_EXISTS: ${requirementId}`);
+    const exclusiveCandidateRefs = requirement.auditRefs.filter(ref => ref.startsWith('cognitive-requirement-candidate:'));
+    if (exclusiveCandidateRefs.length > 0) {
+      const existing = listControlPlaneRecordsWithinTransaction<Requirement>(database, {
+        namespace: NAMESPACE,
+        scope: SCOPE,
+        limit: 1000,
+      });
+      if (existing.length >= 1000) throw new Error('REQUIREMENT_CANDIDATE_BINDING_LOOKUP_LIMIT');
+      const alreadyBound = existing.find(record => exclusiveCandidateRefs.some(ref => record.value.auditRefs.includes(ref)));
+      if (alreadyBound) throw new Error('REQUIREMENT_CANDIDATE_ALREADY_PROMOTED');
+    }
     writeControlPlaneRecordWithinTransaction(database, {
       namespace: NAMESPACE,
       scope: SCOPE,
@@ -132,6 +304,48 @@ export function createRequirement(
   return requirement;
 }
 
+export function bindRequirementCandidateAuditRef(
+  options: RequirementStoreOptions,
+  requirementIdInput: string,
+  candidateAuditRefInput: string,
+): Requirement {
+  const requirementId = id(requirementIdInput);
+  const candidateAuditRef = String(candidateAuditRefInput ?? '').trim().slice(0, 500);
+  if (!candidateAuditRef.startsWith('cognitive-requirement-candidate:')) {
+    throw new Error('REQUIREMENT_CANDIDATE_AUDIT_REF_INVALID');
+  }
+  return withControlPlaneTransaction(options.controllerHome, (database) => {
+    const records = listControlPlaneRecordsWithinTransaction<Requirement>(database, {
+      namespace: NAMESPACE,
+      scope: SCOPE,
+      limit: 1000,
+    });
+    if (records.length >= 1000) throw new Error('REQUIREMENT_CANDIDATE_BINDING_LOOKUP_LIMIT');
+    const bound = records.find(record => record.value.auditRefs.includes(candidateAuditRef));
+    if (bound && bound.value.requirementId !== requirementId) {
+      throw new Error('REQUIREMENT_CANDIDATE_ALREADY_PROMOTED');
+    }
+    const current = readWithin(database, requirementId);
+    if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
+    if (current.value.auditRefs.includes(candidateAuditRef)) return current.value;
+    const updated: Requirement = {
+      ...current.value,
+      auditRefs: [...new Set([...current.value.auditRefs, candidateAuditRef])].slice(-50),
+      revision: current.value.revision + 1,
+      updatedAt: nowIso(options),
+    };
+    return writeControlPlaneRecordWithinTransaction(database, {
+      namespace: NAMESPACE,
+      scope: SCOPE,
+      key: requirementId,
+      schemaVersion: SCHEMA_VERSION,
+      value: updated,
+      action: 'requirement_candidate_promoted',
+      expectedRevision: current.revision,
+    }).value;
+  });
+}
+
 export function updateRequirement(
   options: RequirementStoreOptions,
   input: {
@@ -167,75 +381,3 @@ export function updateRequirement(
     }).value;
   });
 }
-
-export interface RequirementCompletionInput {
-  requirementId: string;
-  work: Pick<WorkContract,
-    | 'workId'
-    | 'requirementId'
-    | 'status'
-    | 'phase'
-    | 'evidenceState'
-    | 'completionOutcome'
-    | 'completionReceipt'
-  >;
-}
-
-/**
- * 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.
- */
-export function completeRequirementFromWork(
-  options: RequirementStoreOptions,
-  input: RequirementCompletionInput,
-): Requirement {
-  const requirementId = id(input.requirementId);
-  const current = readRequirement(options, requirementId);
-  if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
-  if (current.value.state === 'done') return current.value;
-  if (current.value.state === 'cancelled') throw new Error('REQUIREMENT_CANCELLED');
-
-  const work = input.work;
-  if (work.requirementId !== requirementId) throw new Error('REQUIREMENT_WORK_IDENTITY_MISMATCH');
-  if (work.status !== 'completed') throw new Error('REQUIREMENT_WORK_NOT_COMPLETED');
-  if (work.phase !== 'cleanup') throw new Error('REQUIREMENT_WORK_CLEANUP_REQUIRED');
-  if (work.evidenceState !== 'valid') throw new Error('REQUIREMENT_WORK_EVIDENCE_NOT_VALID');
-  if (!work.completionOutcome) throw new Error('REQUIREMENT_WORK_COMPLETION_OUTCOME_REQUIRED');
-  if (work.completionOutcome === 'superseded') throw new Error('REQUIREMENT_WORK_OUTCOME_NOT_COMPLETED');
-
-  const receipt = work.completionReceipt;
-  if (!receipt) throw new Error('REQUIREMENT_WORK_COMPLETION_RECEIPT_REQUIRED');
-  if (receipt.workId !== work.workId) throw new Error('REQUIREMENT_WORK_RECEIPT_IDENTITY_MISMATCH');
-  if (!isRepositoryCompletionReceipt(receipt)) throw new Error('REQUIREMENT_WORK_REPOSITORY_RECEIPT_REQUIRED');
-  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.auditRefs.includes(receipt.receiptId)) return current.value;
-  return updateRequirement(options, {
-    requirementId,
-    action: 'requirement_delivery_evidence_recorded',
-    mutate: (latest) => {
-      // 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: 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),
-      };
-    },
-  });
-}