ai-workflow-logic 0.1.11 → 0.2.1

package/src/agent-definition-selection.ts

@@ -12,6 +12,9 @@ import type {
   AIWorkflowDefinitionResourceKind,
   FrozenAIAgentTaskBinding,
   SelectedAIAgentDefinitionAdmission,
+  CompiledAIAgentCodeExecution,
+  ReviseExistingAIAgentDefinitionAdmission,
+  ReviseExistingAIAgentDefinitionDecision,
 } from 'ai-workflow-contract';
 import { AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION } from 'ai-workflow-contract';
 import {
@@ -22,6 +25,7 @@ import {
   type ResourceAuthoringTransactionPort,
 } from 'halfcode-compiler.xnl/authoring-runtime';
 import {
+  RESOURCE_ENVELOPE_VERSION,
   resolveEffectiveResourceContentIdentities,
   sha256Digest,
   type EffectiveResourceRegistry,
@@ -31,8 +35,10 @@ import {
   type Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
 import { sourceRegistryForAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+import { assertAIAgentExecutionResources, type AIAgentExecutionResourceObservation } from './agent-execution-resources.js';
 import {
   freezeAIWorkflowRunResources,
+  frozenAIAgentTaskAgentContentDigest,
   projectFrozenAIAgentTaskBinding,
 } from './run-freeze.js';
 
@@ -40,6 +46,7 @@ export type AIAgentDefinitionSelectionErrorCode =
   | 'AI_AGENT_REQUIREMENT_INVALID'
   | 'AI_AGENT_CANDIDATE_PROJECTION_UNTRUSTED'
   | 'AI_AGENT_CANDIDATE_CONTENT_IDENTITY_MISSING'
+  | 'AI_AGENT_SELECTION_OWNER_MISMATCH'
   | 'AI_AGENT_AUTHORING_RECEIPT_INVALID'
   | 'AI_AGENT_AUTHORING_RECEIPT_STALE'
   | 'AI_AGENT_AUTHORING_RECEIPT_RESOURCE_MISMATCH'
@@ -56,6 +63,9 @@ export class AIAgentDefinitionSelectionError extends Error {
 }
 
 export interface ProjectAIAgentDefinitionCandidatesInput {
+  readonly executionResources?: AIAgentExecutionResourceObservation;
+  /** Reuse one owner for all observations of the same resource host. */
+  readonly selectionOwner?: AIAgentDefinitionSelectionOwner;
   readonly registry: EffectiveResourceRegistry;
   readonly projection: AIWorkflowAgentResourceProjection;
   readonly layers: readonly ResourceLayerContentIdentityInput[];
@@ -64,18 +74,24 @@ export interface ProjectAIAgentDefinitionCandidatesInput {
 export interface ReconcileAuthoredAIAgentDefinitionInput
   extends ProjectAIAgentDefinitionCandidatesInput {
   readonly candidateSet: AIAgentDefinitionCandidateSet;
-  readonly authoringAdmission: AuthorNewAIAgentDefinitionAdmission;
+  readonly authoringAdmission: AuthorNewAIAgentDefinitionAdmission | ReviseExistingAIAgentDefinitionAdmission;
   readonly receipt: ResourceAuthoringReceipt;
   readonly receiptAuthority: Pick<ResourceAuthoringTransactionPort, 'loadReceipt'>;
 }
 
 export interface AdmitAIAgentDefinitionSelectionInput {
+  readonly selectionOwner?: AIAgentDefinitionSelectionOwner;
   readonly requirement: AIAgentTaskRequirementProjection;
   readonly candidateSet: AIAgentDefinitionCandidateSet;
   readonly decision: AIAgentDefinitionSelectionDecision;
+  /** Required for revise-existing; an authentic immutable proof from the previous execution. */
+  readonly previousExecution?: FrozenAIAgentTaskBinding;
 }
 
 export interface FreezeSelectedAIAgentTaskBindingInput {
+  readonly executionResources?: AIAgentExecutionResourceObservation;
+  readonly selectionOwner?: AIAgentDefinitionSelectionOwner;
+  readonly codeExecutions?: readonly CompiledAIAgentCodeExecution[];
   readonly registry: EffectiveResourceRegistry;
   readonly projection: AIWorkflowAgentResourceProjection;
   readonly contentIdentities: ReadonlyMap<string, ResourceContentIdentity>;
@@ -86,6 +102,9 @@ export interface FreezeSelectedAIAgentTaskBindingInput {
 }
 
 interface CandidateSetAuthority {
+  readonly executionResources?: AIAgentExecutionResourceObservation;
+  readonly selectionOwner?: AIAgentDefinitionSelectionOwner;
+  readonly generation: number;
   readonly registry: EffectiveResourceRegistry;
   readonly projection: AIWorkflowAgentResourceProjection;
   readonly layers: readonly ResourceLayerContentIdentityInput[];
@@ -96,13 +115,70 @@ interface AuthoringAdmissionAuthority {
   readonly candidateSet: AIAgentDefinitionCandidateSet;
   readonly requirement: AIAgentTaskRequirementProjection;
   readonly proposalDigest: Sha256Digest;
+  readonly before?: {
+    readonly authorityDigest: Sha256Digest;
+    readonly effectiveOrigin: ResourceOrigin;
+    readonly authorityResourceIds: readonly string[];
+  };
 }
 
 const authenticRequirements = new WeakSet<object>();
 const candidateSetAuthorities = new WeakMap<object, CandidateSetAuthority>();
 const selectedAdmissionAuthorities = new WeakMap<object, CandidateSetAuthority>();
 const authoringAdmissionAuthorities = new WeakMap<object, AuthoringAdmissionAuthority>();
-const pendingAuthoringAdmissions = new Map<`resource://${string}`, object>();
+declare const selectionOwnerBrand: unique symbol;
+
+/** Process-local state dependency. It is not a resource identity or a serializable receipt. */
+export interface AIAgentDefinitionSelectionOwner {
+  readonly [selectionOwnerBrand]: true;
+}
+
+interface SelectionOwnerState {
+  readonly pending: Map<`resource://${string}`, object>;
+  readonly receiptAuthority: Pick<ResourceAuthoringTransactionPort, 'loadReceipt'>;
+  generation: number;
+}
+
+export interface CreateAIAgentDefinitionSelectionOwnerInput {
+  readonly receiptAuthority: Pick<ResourceAuthoringTransactionPort, 'loadReceipt'>;
+}
+
+const selectionOwnerStates = new WeakMap<AIAgentDefinitionSelectionOwner, SelectionOwnerState>();
+// This association prevents removing/changing the explicit owner on the same observation.
+// Pending state lives with the stable owner, never with this per-observation guard.
+const registryOwners = new WeakMap<EffectiveResourceRegistry, {
+  readonly owner: AIAgentDefinitionSelectionOwner;
+  readonly generation: number;
+}>();
+
+export function createAIAgentDefinitionSelectionOwner(
+  input: CreateAIAgentDefinitionSelectionOwnerInput,
+): AIAgentDefinitionSelectionOwner {
+  const owner = Object.freeze({}) as AIAgentDefinitionSelectionOwner;
+  selectionOwnerStates.set(owner, { pending: new Map(), generation: 0, receiptAuthority: input.receiptAuthority });
+  return owner;
+}
+
+function ownerMatches(
+  authority: CandidateSetAuthority,
+  owner: AIAgentDefinitionSelectionOwner | undefined,
+): boolean {
+  return authority.selectionOwner === owner
+    && registryOwners.get(authority.registry)?.owner === owner
+    && (owner === undefined || selectionOwnerStates.has(owner));
+}
+
+function isSuperseded(authority: CandidateSetAuthority): boolean {
+  if (!authority.selectionOwner) return false;
+  const generation = selectionOwnerStates.get(authority.selectionOwner)!.generation;
+  return authority.generation !== generation
+    || registryOwners.get(authority.registry)?.generation !== generation;
+}
+
+function pendingFor(authority: CandidateSetAuthority): SelectionOwnerState['pending'] | undefined {
+  return authority.selectionOwner === undefined
+    ? undefined : selectionOwnerStates.get(authority.selectionOwner)?.pending;
+}
 
 export function normalizeAIAgentTaskRequirement(
   value: AIAgentTaskRequirement,
@@ -159,6 +235,18 @@ export function projectAIAgentDefinitionCandidates(
   input: ProjectAIAgentDefinitionCandidatesInput,
 ): AIAgentDefinitionCandidateSet {
   assertProjectionAuthority(input);
+  const ownerState = input.selectionOwner === undefined ? undefined : selectionOwnerStates.get(input.selectionOwner);
+  const registeredOwner = registryOwners.get(input.registry);
+  if ((input.selectionOwner !== undefined && !ownerState)
+    || (registeredOwner && registeredOwner.owner !== input.selectionOwner)) {
+    throw new AIAgentDefinitionSelectionError(
+      'AI_AGENT_SELECTION_OWNER_MISMATCH',
+      'Candidate projection requires the authentic selection owner already bound to this registry observation.',
+    );
+  }
+  if (input.selectionOwner && !registeredOwner) {
+    registryOwners.set(input.registry, { owner: input.selectionOwner, generation: ownerState!.generation });
+  }
   const contentIdentities = resolveEffectiveResourceContentIdentities({
     registry: input.registry,
     layers: input.layers,
@@ -167,7 +255,7 @@ export function projectAIAgentDefinitionCandidates(
     registry: input.registry,
     layers: input.layers,
   }), 'registry revision');
-  const candidates = input.projection.agentDefinitions
+  const candidates = (input.executionResources?.projection ?? input.projection).agentDefinitions
     .map((agent): AIAgentDefinitionCandidate => {
       const identity = contentIdentities.get(agent.resource.resourceId);
       if (!identity) {
@@ -210,6 +298,9 @@ export function projectAIAgentDefinitionCandidates(
     candidateSetDigest: candidateSetDigest(registryRevision, candidates),
   }) satisfies AIAgentDefinitionCandidateSet;
   candidateSetAuthorities.set(candidateSet, Object.freeze({
+    executionResources: input.executionResources,
+    selectionOwner: input.selectionOwner,
+    generation: registryOwners.get(input.registry)?.generation ?? 0,
     registry: input.registry,
     projection: input.projection,
     layers: input.layers,
@@ -222,21 +313,42 @@ export async function reconcileAuthoredAIAgentDefinition(
 ): Promise<AIAgentDefinitionCandidateSet> {
   const authoringAuthority = authoringAdmissionAuthorities.get(input.authoringAdmission as object);
   const authority = candidateSetAuthorities.get(input.candidateSet);
+  if (!authority || !input.selectionOwner || !ownerMatches(authority, input.selectionOwner)
+    || authoringAuthority?.candidateSetAuthority.selectionOwner !== input.selectionOwner) {
+    throw new AIAgentDefinitionSelectionError(
+      'AI_AGENT_SELECTION_OWNER_MISMATCH',
+      'Authoring reconciliation requires the same explicit owner as its pending admission and current observation.',
+    );
+  }
+  const ownerState = selectionOwnerStates.get(input.selectionOwner)!;
+  if (input.receiptAuthority !== ownerState.receiptAuthority) {
+    throw new AIAgentDefinitionSelectionError(
+      'AI_AGENT_SELECTION_OWNER_MISMATCH',
+      'Authoring reconciliation requires the receipt authority explicitly bound to this selection owner.',
+    );
+  }
+  if (isSuperseded(authority)) {
+    throw new AIAgentDefinitionSelectionError(
+      'AI_AGENT_AUTHORING_RECEIPT_STALE',
+      'Authoring reconciliation cannot restore a superseded registry observation.',
+    );
+  }
   if (!authority
     || authority.registry !== input.registry
     || authority.projection !== input.projection
+    || authority.executionResources !== input.executionResources
     || authority.layers !== input.layers
     || !authoringAuthority
     || candidateSetAuthorities.get(authoringAuthority.candidateSet)
       !== authoringAuthority.candidateSetAuthority
     || authoringAuthority.requirement.requirementDigest
       !== input.authoringAdmission.requirementDigest
-    || pendingAuthoringAdmissions.get(input.authoringAdmission.agentDefinitionRef)
+    || ownerState.pending.get(input.authoringAdmission.agentDefinitionRef)
       !== input.authoringAdmission
     || authoringAuthority.proposalDigest !== digest(input.authoringAdmission.proposal)) {
     throw new AIAgentDefinitionSelectionError(
       'AI_AGENT_CANDIDATE_PROJECTION_UNTRUSTED',
-      'Authoring reconciliation requires the exact author-new admission and candidate projection for this registry observation.',
+      'Authoring reconciliation requires the exact pending admission and candidate projection for this registry observation.',
     );
   }
   validateReceiptShapeAndDigest(input.receipt);
@@ -248,6 +360,13 @@ export async function reconcileAuthoredAIAgentDefinition(
     );
   }
   validateReceiptShapeAndDigest(durableReceipt);
+  if (isSuperseded(authority)
+    || ownerState.pending.get(input.authoringAdmission.agentDefinitionRef) !== input.authoringAdmission) {
+    throw new AIAgentDefinitionSelectionError(
+      'AI_AGENT_AUTHORING_RECEIPT_STALE',
+      'The pending admission or registry observation was superseded while loading the durable receipt.',
+    );
+  }
   const proposal = input.authoringAdmission.proposal;
   const currentRevision = asDigest(deriveResourceAuthoringRegistryRevision({
     registry: input.registry,
@@ -281,14 +400,16 @@ export async function reconcileAuthoredAIAgentDefinition(
     || input.receipt.catalogId !== proposal.catalogId
     || input.receipt.resourceId !== proposal.resourceId
     || input.receipt.kind !== proposal.kind
-    || input.receipt.apiVersion !== proposal.apiVersion
+    || input.receipt.envelopeVersion !== proposal.envelopeVersion
+    || input.receipt.writerSpecVersion !== proposal.writerSpecVersion
     || input.receipt.sourceShape !== proposal.sourceShape
     || input.receipt.documentUri !== proposal.documentUri
-    || input.receipt.authorityDigestBefore !== null
+    || input.receipt.authorityDigestBefore !== (authoringAuthority.before?.authorityDigest ?? null)
     || input.receipt.authorityDigestAfter !== sha256Digest(proposal.authorityText)
     || input.receipt.registryRevisionBefore !== proposal.expected.registryRevision
     || input.receipt.kind !== 'AIAgentDefinition'
-    || resource.metadata.apiVersion !== input.receipt.apiVersion
+    || resource.metadata.envelopeVersion !== input.receipt.envelopeVersion
+    || resource.metadata.specVersion !== input.receipt.writerSpecVersion
     || resource.sourceShape !== input.receipt.sourceShape
     || resource.documentUri !== input.receipt.documentUri
     || !identity
@@ -296,6 +417,8 @@ export async function reconcileAuthoredAIAgentDefinition(
     || identity.contentDigest !== input.receipt.contentDigest
     || !effectiveOrigin
     || !sameReceiptOrigin(effectiveOrigin, input.receipt.effectiveOrigin)
+    || (authoringAuthority.before !== undefined
+      && canonicalJson(authorityResourceIds) !== canonicalJson(authoringAuthority.before.authorityResourceIds))
     || canonicalJson(authorityResourceIds) !== canonicalJson([...input.receipt.authorityResourceIds].sort(compareCodeUnits))
     || !candidate
     || candidate.contentDigest !== input.receipt.contentDigest) {
@@ -309,6 +432,15 @@ export async function reconcileAuthoredAIAgentDefinition(
     planDigest: asDigest(input.receipt.planDigest, 'receipt plan digest'),
     transactionId: input.receipt.transactionId,
     receiptDigest: asDigest(input.receipt.receiptDigest, 'receipt digest'),
+    ...(input.authoringAdmission.status === 'revision-request' ? {
+      revision: Object.freeze({
+        candidateRef: input.authoringAdmission.candidate.agentDefinitionRef,
+        candidateDigest: input.authoringAdmission.candidate.candidateDigest,
+        contentDigest: input.authoringAdmission.candidate.contentDigest,
+        registryRevision: input.authoringAdmission.candidate.registryRevision,
+        feedback: input.authoringAdmission.feedback,
+      }),
+    } : {}),
   }) satisfies AIAgentDefinitionAuthoringEvidence;
   const candidates = Object.freeze(input.candidateSet.candidates.map((value) => {
     if (value !== candidate) return value;
@@ -327,8 +459,10 @@ export async function reconcileAuthoredAIAgentDefinition(
     candidates,
     candidateSetDigest: candidateSetDigest(input.candidateSet.registryRevision, candidates),
   }) satisfies AIAgentDefinitionCandidateSet;
-  candidateSetAuthorities.set(reconciled, authority);
-  pendingAuthoringAdmissions.delete(input.authoringAdmission.agentDefinitionRef);
+  if (authoringAuthority.before) ownerState.generation += 1;
+  registryOwners.set(input.registry, { owner: input.selectionOwner, generation: ownerState.generation });
+  candidateSetAuthorities.set(reconciled, Object.freeze({ ...authority, generation: ownerState.generation }));
+  ownerState.pending.delete(input.authoringAdmission.agentDefinitionRef);
   return reconciled;
 }
 
@@ -343,7 +477,11 @@ export function admitAIAgentDefinitionSelection(
     return rejection('requirement-stale', 'The decision is not bound to the current normalized task requirement.');
   }
   const candidateSetAuthority = candidateSetAuthorities.get(input.candidateSet);
+  if (candidateSetAuthority && !ownerMatches(candidateSetAuthority, input.selectionOwner)) {
+    return rejection('selection-owner-mismatch', 'Selection requires the same explicit owner as its candidate observation.');
+  }
   if (!candidateSetAuthority
+    || isSuperseded(candidateSetAuthority)
     || input.decision.candidateSetDigest !== input.candidateSet.candidateSetDigest) {
     return rejection('candidate-set-stale', 'The decision is not bound to the current authentic candidate set.');
   }
@@ -352,11 +490,10 @@ export function admitAIAgentDefinitionSelection(
     const candidate = input.candidateSet.candidates.find(({ agentDefinitionRef }) =>
       agentDefinitionRef === decision.candidateRef);
     if (!candidate) return rejection('candidate-missing', 'The selected candidate is absent from the current set.');
-    if (pendingAuthoringAdmissions.has(candidate.agentDefinitionRef)
-      && candidate.authoringEvidence === undefined) {
+    if (pendingFor(candidateSetAuthority)?.has(candidate.agentDefinitionRef)) {
       return rejection(
         'authoring-in-progress',
-        'An in-flight author-new transition must reconcile its durable Halfcode receipt before this definition is selectable.',
+        'An in-flight authoring transition must reconcile its durable Halfcode receipt before this definition is selectable.',
       );
     }
     if (candidate.candidateDigest !== decision.candidateDigest) {
@@ -376,6 +513,47 @@ export function admitAIAgentDefinitionSelection(
     selectedAdmissionAuthorities.set(admission, candidateSetAuthority);
     return admission;
   }
+  if (!input.selectionOwner) {
+    return rejection('selection-owner-required', 'Authoring requires an explicit stable selection owner shared across registry refreshes.');
+  }
+  const pending = pendingFor(candidateSetAuthority)!;
+  if (input.decision.mode === 'revise-existing') {
+    const decision = input.decision;
+    const candidate = input.candidateSet.candidates.find(({ agentDefinitionRef }) => agentDefinitionRef === decision.candidateRef);
+    if (!candidate) return rejection('candidate-missing', 'The revision candidate is absent from the current set.');
+    if (candidate.candidateDigest !== decision.candidateDigest) {
+      return rejection('candidate-digest-mismatch', 'The revision candidate digest is stale or forged.');
+    }
+    if (!matchesRevisionFeedback(input, decision, candidate)) {
+      return rejection('revision-feedback-invalid', 'Revision feedback must match the exact candidate, requirement, observation and authentic prior execution.');
+    }
+    const before = revisionAuthority(candidateSetAuthority, candidate);
+    if (!before || !isValidAuthoringProposal(decision.proposal, decision.candidateRef, input.candidateSet, before.authorityDigest)
+      || decision.proposal.documentUri !== before.effectiveOrigin.documentUri) {
+      return rejection('authoring-proposal-invalid', 'Revision requires an exact native update/present proposal against the effective authority digest and document.');
+    }
+    if (pending.has(candidate.agentDefinitionRef)) {
+      return rejection('authoring-in-progress', 'An authoring request for this exact Agent definition is already in flight.');
+    }
+    const proposal = cloneAuthoringProposal(decision.proposal);
+    const admission = Object.freeze({
+      schemaVersion: AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION,
+      status: 'revision-request' as const,
+      requirementDigest: input.requirement.requirementDigest,
+      candidateSetDigest: input.candidateSet.candidateSetDigest,
+      agentDefinitionRef: candidate.agentDefinitionRef,
+      candidate,
+      feedback: Object.freeze({ ...decision.feedback }),
+      proposal,
+      reason: decision.reason,
+    }) satisfies ReviseExistingAIAgentDefinitionAdmission;
+    authoringAdmissionAuthorities.set(admission, Object.freeze({
+      candidateSetAuthority, candidateSet: input.candidateSet, requirement: input.requirement,
+      proposalDigest: digest(proposal), before,
+    }));
+    pending.set(candidate.agentDefinitionRef, admission);
+    return admission;
+  }
   if (!isValidAuthoringProposal(input.decision.proposal, input.decision.agentDefinitionRef, input.candidateSet)) {
     return rejection('authoring-proposal-invalid', 'The author-new decision is not one exact Halfcode create proposal for the current registry.');
   }
@@ -389,7 +567,7 @@ export function admitAIAgentDefinitionSelection(
     proposal,
     reason: stringValue(input.decision.reason, 'decision.reason'),
   }) satisfies AuthorNewAIAgentDefinitionAdmission;
-  if (pendingAuthoringAdmissions.has(admission.agentDefinitionRef)) {
+  if (pending.has(admission.agentDefinitionRef)) {
     return rejection('authoring-in-progress', 'An authoring request for this exact Agent definition is already in flight.');
   }
   authoringAdmissionAuthorities.set(admission, Object.freeze({
@@ -398,7 +576,7 @@ export function admitAIAgentDefinitionSelection(
     requirement: input.requirement,
     proposalDigest: digest(proposal),
   }));
-  pendingAuthoringAdmissions.set(admission.agentDefinitionRef, admission);
+  pending.set(admission.agentDefinitionRef, admission);
   return admission;
 }
 
@@ -407,8 +585,12 @@ export function freezeSelectedAIAgentTaskBinding(
 ): FrozenAIAgentTaskBinding {
   const authority = selectedAdmissionAuthorities.get(input.admission as object);
   if (!authority
+    || !ownerMatches(authority, input.selectionOwner)
+    || isSuperseded(authority)
+    || pendingFor(authority)?.has(input.admission.candidate.agentDefinitionRef)
     || authority.registry !== input.registry
     || authority.projection !== input.projection
+    || authority.executionResources !== input.executionResources
     || input.contentIdentities.get(resourceId(input.admission.candidate.agentDefinitionRef))?.contentDigest
       !== input.admission.candidate.contentDigest) {
     throw new AIAgentDefinitionSelectionError(
@@ -417,6 +599,8 @@ export function freezeSelectedAIAgentTaskBinding(
     );
   }
   return projectFrozenAIAgentTaskBinding(freezeAIWorkflowRunResources({
+    executionResources: input.executionResources,
+    codeExecutions: input.codeExecutions,
     registry: input.registry,
     projection: input.projection,
     task: {
@@ -462,6 +646,20 @@ function isValidDecision(value: AIAgentDefinitionSelectionDecision): boolean {
       exactRef(decision.agentDefinitionRef, 'decision.agentDefinitionRef');
       return true;
     }
+    if (decision.mode === 'revise-existing') {
+      exactKeys(decision, ['schemaVersion', 'mode', 'requirementDigest', 'candidateSetDigest',
+        'candidateRef', 'candidateDigest', 'feedback', 'proposal', 'reason'], 'decision');
+      exactRef(decision.candidateRef, 'decision.candidateRef');
+      const feedback = closedRecord(decision.feedback, 'decision.feedback');
+      exactKeys(feedback, ['observationRef', 'attemptRef', 'verificationRef', 'requirementDigest',
+        'candidateSetDigest', 'candidateDigest', 'previousExecutionFingerprint'], 'decision.feedback');
+      for (const key of ['observationRef', 'attemptRef', 'verificationRef'] as const) {
+        nonEmptyString(feedback[key], `decision.feedback.${key}`);
+      }
+      return isDigest(decision.candidateDigest)
+        && ['requirementDigest', 'candidateSetDigest', 'candidateDigest', 'previousExecutionFingerprint']
+          .every((key) => isDigest(feedback[key]));
+    }
     return false;
   } catch {
     return false;
@@ -469,6 +667,7 @@ function isValidDecision(value: AIAgentDefinitionSelectionDecision): boolean {
 }
 
 function assertProjectionAuthority(input: ProjectAIAgentDefinitionCandidatesInput): void {
+  if (input.executionResources) assertAIAgentExecutionResources(input.executionResources, input.registry, input.layers);
   if (sourceRegistryForAIWorkflowAgentResourceProjection(input.projection) !== input.registry) {
     throw new AIAgentDefinitionSelectionError(
       'AI_AGENT_CANDIDATE_PROJECTION_UNTRUSTED',
@@ -491,10 +690,49 @@ function isCompatible(
     && containsAll(candidate.messageSourceRefs, requirement.requiredMessageSourceRefs);
 }
 
+function matchesRevisionFeedback(
+  input: AdmitAIAgentDefinitionSelectionInput,
+  decision: ReviseExistingAIAgentDefinitionDecision,
+  candidate: AIAgentDefinitionCandidate,
+): boolean {
+  try {
+    const execution = input.previousExecution;
+    return execution !== undefined
+      && frozenAIAgentTaskAgentContentDigest(execution) === candidate.contentDigest
+      && execution.task.agentDefinitionRef === candidate.agentDefinitionRef
+      && execution.semanticFingerprint === decision.feedback.previousExecutionFingerprint
+      && decision.feedback.requirementDigest === input.requirement.requirementDigest
+      && decision.feedback.candidateSetDigest === input.candidateSet.candidateSetDigest
+      && decision.feedback.candidateDigest === candidate.candidateDigest;
+  } catch {
+    return false;
+  }
+}
+
+function revisionAuthority(
+  authority: CandidateSetAuthority,
+  candidate: AIAgentDefinitionCandidate,
+): AuthoringAdmissionAuthority['before'] {
+  const id = resourceId(candidate.agentDefinitionRef);
+  const entry = authority.registry.byId.get(id);
+  const identity = resolveEffectiveResourceContentIdentities(authority).get(id);
+  if (!entry?.resource || entry.resource.kind !== 'AIAgentDefinition'
+    || entry.resource.sourceShape !== 'single-file' || !entry.effectiveOrigin
+    || !identity || identity.contentDigest !== candidate.contentDigest) return undefined;
+  return Object.freeze({
+    authorityDigest: asDigest(identity.authorityDigest, 'previous authority digest'),
+    effectiveOrigin: Object.freeze({ ...entry.effectiveOrigin }),
+    authorityResourceIds: Object.freeze([...authority.registry.byId.values()]
+      .filter((value) => value.resource && sameOrigin(value.effectiveOrigin, entry.effectiveOrigin))
+      .map(({ resourceId }) => resourceId).sort(compareCodeUnits)),
+  });
+}
+
 function isValidAuthoringProposal(
   value: ResourceAuthoringProposal,
   definitionRef: `resource://${string}`,
   candidateSet: AIAgentDefinitionCandidateSet,
+  authorityDigestBefore?: Sha256Digest,
 ): boolean {
   try {
     const proposal = closedRecord(value, 'proposal');
@@ -504,24 +742,31 @@ function isValidAuthoringProposal(
       'catalogId',
       'resourceId',
       'kind',
-      'apiVersion',
+      'envelopeVersion',
+      'writerSpecVersion',
       'sourceShape',
       'documentUri',
       'authorityText',
       'expected',
     ], 'proposal');
     const expected = closedRecord(proposal.expected, 'proposal.expected');
-    exactKeys(expected, ['state', 'registryRevision'], 'proposal.expected');
+    exactKeys(expected, authorityDigestBefore === undefined
+      ? ['state', 'registryRevision'] : ['state', 'registryRevision', 'authorityDigest'], 'proposal.expected');
     return proposal.schemaVersion === RESOURCE_AUTHORING_SCHEMA_VERSION
-      && proposal.operation === 'create'
+      && proposal.operation === (authorityDigestBefore === undefined ? 'create' : 'update')
       && proposal.kind === 'AIAgentDefinition'
       && proposal.sourceShape === 'single-file'
-      && expected.state === 'absent'
+      && expected.state === (authorityDigestBefore === undefined ? 'absent' : 'present')
+      && (authorityDigestBefore === undefined || (expected.authorityDigest === authorityDigestBefore
+        && sha256Digest(stringValue(proposal.authorityText, 'proposal.authorityText')) !== authorityDigestBefore))
       && expected.registryRevision === candidateSet.registryRevision
       && definitionRef === resourceRef(nonEmptyString(proposal.resourceId, 'proposal.resourceId'))
-      && !candidateSet.candidates.some(({ agentDefinitionRef }) => agentDefinitionRef === definitionRef)
+      && (authorityDigestBefore !== undefined
+        || !candidateSet.candidates.some(({ agentDefinitionRef }) => agentDefinitionRef === definitionRef))
       && nonEmptyString(proposal.catalogId, 'proposal.catalogId').length > 0
-      && nonEmptyString(proposal.apiVersion, 'proposal.apiVersion').length > 0
+      && proposal.envelopeVersion === RESOURCE_ENVELOPE_VERSION
+      && Number.isSafeInteger(proposal.writerSpecVersion)
+      && Number(proposal.writerSpecVersion) > 0
       && /^vfs:\/\/@\/.+\.xnl$/u.test(nonEmptyString(proposal.documentUri, 'proposal.documentUri'))
       && stringValue(proposal.authorityText, 'proposal.authorityText').length > 0;
   } catch {
@@ -536,7 +781,8 @@ function cloneAuthoringProposal(value: ResourceAuthoringProposal): ResourceAutho
     catalogId: value.catalogId,
     resourceId: value.resourceId,
     kind: value.kind,
-    apiVersion: value.apiVersion,
+    envelopeVersion: value.envelopeVersion,
+    writerSpecVersion: value.writerSpecVersion,
     sourceShape: value.sourceShape,
     documentUri: value.documentUri,
     authorityText: value.authorityText,
@@ -555,7 +801,8 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
       'catalogId',
       'resourceId',
       'kind',
-      'apiVersion',
+      'envelopeVersion',
+      'writerSpecVersion',
       'sourceShape',
       'documentUri',
       'authorityDigestBefore',
@@ -572,6 +819,9 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
     if (receipt.schemaVersion !== RESOURCE_AUTHORING_SCHEMA_VERSION
       || (receipt.operation !== 'create' && receipt.operation !== 'update')
       || receipt.sourceShape !== 'single-file'
+      || receipt.envelopeVersion !== RESOURCE_ENVELOPE_VERSION
+      || !Number.isSafeInteger(receipt.writerSpecVersion)
+      || Number(receipt.writerSpecVersion) <= 0
       || (receipt.authorityDigestBefore !== null && !isDigest(receipt.authorityDigestBefore))
       || !isDigest(receipt.planDigest)
       || !isDigest(receipt.authorityDigestAfter)
@@ -587,7 +837,7 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
       || (origin.logicalPath !== undefined && typeof origin.logicalPath !== 'string')) {
       throw new Error('invalid receipt fields');
     }
-    for (const field of ['transactionId', 'catalogId', 'resourceId', 'kind', 'apiVersion', 'documentUri'] as const) {
+    for (const field of ['transactionId', 'catalogId', 'resourceId', 'kind', 'envelopeVersion', 'documentUri'] as const) {
       nonEmptyString(receipt[field], `receipt.${field}`);
     }
     for (const field of ['layerId', 'packageId', 'documentUri'] as const) {