ai-workflow-logic 0.2.0 → 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 {
@@ -32,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';
 
@@ -41,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'
@@ -57,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[];
@@ -65,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>;
@@ -87,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[];
@@ -97,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,
@@ -160,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,
@@ -168,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) {
@@ -211,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,
@@ -223,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);
@@ -249,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,
@@ -286,7 +404,7 @@ export async function reconcileAuthoredAIAgentDefinition(
     || 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'
@@ -299,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) {
@@ -312,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;
@@ -330,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;
 }
 
@@ -346,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.');
   }
@@ -355,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) {
@@ -379,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.');
   }
@@ -392,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({
@@ -401,7 +576,7 @@ export function admitAIAgentDefinitionSelection(
     requirement: input.requirement,
     proposalDigest: digest(proposal),
   }));
-  pendingAuthoringAdmissions.set(admission.agentDefinitionRef, admission);
+  pending.set(admission.agentDefinitionRef, admission);
   return admission;
 }
 
@@ -410,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(
@@ -420,6 +599,8 @@ export function freezeSelectedAIAgentTaskBinding(
     );
   }
   return projectFrozenAIAgentTaskBinding(freezeAIWorkflowRunResources({
+    executionResources: input.executionResources,
+    codeExecutions: input.codeExecutions,
     registry: input.registry,
     projection: input.projection,
     task: {
@@ -465,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;
@@ -472,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',
@@ -494,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');
@@ -515,15 +750,19 @@ function isValidAuthoringProposal(
       '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
       && proposal.envelopeVersion === RESOURCE_ENVELOPE_VERSION
       && Number.isSafeInteger(proposal.writerSpecVersion)

package/src/agent-execution-resources.ts

@@ -0,0 +1,160 @@
+import {
+  DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS,
+  type AIAgentCodeResourceProjection,
+  type AIAgentResolvedResourceIdentity,
+  type AIWorkflowAgentResourceProjection,
+} from 'ai-workflow-contract';
+import {
+  composeLayeredResourceRegistry,
+  digestCanonical,
+  resolveEffectiveResourceContentIdentities,
+  type EffectiveResourceRegistry,
+  type ResourceContentIdentity,
+  type ResourceLayerContentIdentityInput,
+  type ResourceRecord,
+  type ResolvedResourceRecord,
+  type ResourceTombstone,
+} from 'halfcode-compiler.xnl/resource-core';
+import { projectAIWorkflowAgentResources } from './agent-resources.js';
+import { resolveAIWorkflowResourceTree, type AIWorkflowResourceResolutionContext } from './resource-resolution.js';
+
+export interface ResolveAIAgentExecutionResourcesRuntime {
+  readonly resolutionContexts: ReadonlyMap<string, AIWorkflowResourceResolutionContext>;
+}
+export interface ResolveAIAgentExecutionResourcesInput {
+  readonly registry: EffectiveResourceRegistry;
+  readonly layers: readonly ResourceLayerContentIdentityInput[];
+}
+declare const executionResourceBrand: unique symbol;
+/** Process-local derived observation; rebuild from authored bytes and exact readers on recovery. */
+export interface AIAgentExecutionResourceObservation {
+  readonly [executionResourceBrand]: true;
+  readonly registry: EffectiveResourceRegistry;
+  readonly projection: AIWorkflowAgentResourceProjection;
+  readonly contentIdentities: ReadonlyMap<string, ResourceContentIdentity>;
+  readonly resolutionIdentities: ReadonlyMap<string, AIAgentResolvedResourceIdentity>;
+  /** Exact native effective records. Custom readerValue semantics remain owned by that Kind. */
+  readonly resolvedResources: ReadonlyMap<string, ResolvedResourceRecord>;
+}
+interface ExecutionAuthority extends ResolveAIAgentExecutionResourcesInput {
+  readonly layerBindings: readonly ResourceLayerContentIdentityInput[];
+}
+const authorities = new WeakMap<AIAgentExecutionResourceObservation, ExecutionAuthority>();
+const codeResolutions = new WeakMap<AIAgentCodeResourceProjection, AIAgentResolvedResourceIdentity>();
+const executionRegistries = new WeakSet<EffectiveResourceRegistry>();
+const executionCodeResources = new WeakSet<ResourceRecord>();
+const nodeReaderSubjects = new Set(DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS.map(reader => reader.subjectFqn));
+
+export function resolveAIAgentExecutionResources(
+  runtime: ResolveAIAgentExecutionResourcesRuntime,
+  input: ResolveAIAgentExecutionResourcesInput,
+): AIAgentExecutionResourceObservation {
+  // Native owner validates registry provenance, exact authored trees, layer order and origins.
+  const contentIdentities = resolveEffectiveResourceContentIdentities(input);
+  if (runtime.resolutionContexts.size !== input.layers.length
+    || input.layers.some(layer => !runtime.resolutionContexts.get(layer.id))) {
+    fail('Reader context keys must exactly match the authored layer ids.');
+  }
+  // Tombstones are facts of the authentic composer result. Reuse the native composer
+  // to replay them, including tombstones that were subsequently shadowed by a layer.
+  const tombstones = new Map<string, ResourceTombstone[]>();
+  for (const entry of input.registry.byId.values()) for (const tombstone of entry.tombstones) {
+    const values = tombstones.get(tombstone.layerId) ?? [];
+    values.push({ resourceId: tombstone.resourceId,
+      ...(tombstone.expectedKind === undefined ? {} : { expectedKind: tombstone.expectedKind }),
+      ...(tombstone.reason === undefined ? {} : { reason: tombstone.reason }) });
+    tombstones.set(tombstone.layerId, values);
+  }
+  const resolvedLayers = input.layers.map(layer => ({
+    id: layer.id,
+    tree: resolveAIWorkflowResourceTree(layer.tree, runtime.resolutionContexts.get(layer.id)!),
+    tombstones: tombstones.get(layer.id) ?? [],
+  }));
+  const registry = composeLayeredResourceRegistry({ layers: resolvedLayers });
+  if (digestCanonical(topology(registry)) !== digestCanonical(topology(input.registry))) {
+    fail('Resolved composition must retain the exact authored layer, origin, shadow and tombstone topology.');
+  }
+  const resolutions: Array<readonly [string, AIAgentResolvedResourceIdentity]> = [];
+  const resolvedResources: Array<readonly [string, ResolvedResourceRecord]> = [];
+  for (const entry of registry.byId.values()) {
+    if (!entry.resource) continue;
+    const layer = resolvedLayers.find(value => value.id === entry.effectiveLayerId);
+    const record = layer?.tree.registry.byKind.get(entry.kind)?.find(value => value.resourceId === entry.resourceId);
+    if (!record || !layer) fail(`Missing native resolution for '${entry.resourceId}'.`);
+    resolvedResources.push([entry.resourceId, record]);
+    // This projector's explicit input protocol is resolved PortableSpec/node. It does
+    // not execute arbitrary Kind reader outputs with different business semantics.
+    if (nodeReaderSubjects.has(record.subjectFqn)
+      && digestCanonical(record.readerValue) !== digestCanonical(record.resolvedSpec)) {
+      fail(`Kind '${record.kind}' requires a reader whose value preserves the resolved node input protocol.`);
+    }
+    resolutions.push([entry.resourceId, Object.freeze({
+      resourceId: record.resourceId, readerId: record.readerId, readerSpecVersion: record.readerSpecVersion,
+      effectiveContentDigest: record.effectiveContentDigest, readerProfileId: layer.tree.readerProfileId,
+      resolutionReceiptDigest: digestCanonical(record.resolution),
+    })]);
+  }
+  const resolutionIdentities = immutableMap(resolutions.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+  const projection = projectAIWorkflowAgentResources(registry);
+  for (const code of projection.codeResources ?? []) {
+    codeResolutions.set(code, resolutionIdentities.get(code.resource.resourceId)!);
+    executionCodeResources.add(code.resource);
+  }
+  const observation = Object.freeze({ registry, projection, contentIdentities, resolutionIdentities,
+    resolvedResources: immutableMap(resolvedResources.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)),
+  }) as AIAgentExecutionResourceObservation;
+  authorities.set(observation, Object.freeze({ registry: input.registry, layers: input.layers,
+    layerBindings: Object.freeze(input.layers.map(layer => Object.freeze({ id: layer.id, tree: layer.tree }))) }));
+  executionRegistries.add(registry);
+  return observation;
+}
+
+/** Internal admission guard; never exported as a public branding operation. */
+export function assertAIAgentExecutionResources(
+  observation: AIAgentExecutionResourceObservation,
+  registry: EffectiveResourceRegistry,
+  layers?: readonly ResourceLayerContentIdentityInput[],
+): AIAgentExecutionResourceObservation {
+  const authority = authorities.get(observation);
+  if (!authority || authority.registry !== registry || (layers !== undefined && authority.layers !== layers)
+    || authority.layers.length !== authority.layerBindings.length
+    || authority.layerBindings.some((layer, index) => authority.layers[index]?.id !== layer.id || authority.layers[index]?.tree !== layer.tree)) {
+    fail('Execution resources require the exact authentic observation for this authored registry and layers.');
+  }
+  return observation;
+}
+
+export function resolutionForAIAgentCodeProjection(projection: AIAgentCodeResourceProjection): AIAgentResolvedResourceIdentity | undefined {
+  const resolution = codeResolutions.get(projection);
+  if (!resolution && executionCodeResources.has(projection.resource)) {
+    fail('Code compilation and restore require the exact execution observation projection.');
+  }
+  return resolution;
+}
+
+/** Prevents discarding reader identities by passing a bridge registry to the old freeze path. */
+export function assertAIAgentFreezeRegistry(registry: EffectiveResourceRegistry): void {
+  if (executionRegistries.has(registry)) fail('Freeze requires the original authored registry and its executionResources observation.');
+}
+
+function topology(registry: EffectiveResourceRegistry): unknown {
+  return { layers: registry.layers, entries: [...registry.byId.values()].map(entry => ({
+    resourceId: entry.resourceId, kind: entry.kind, present: entry.resource !== undefined,
+    origin: entry.effectiveOrigin ?? null, shadowed: entry.shadowed,
+    tombstone: entry.tombstone ?? null, tombstones: entry.tombstones,
+  })) };
+}
+function immutableMap<K, V>(entries: readonly (readonly [K, V])[]): ReadonlyMap<K, V> {
+  const values = new Map(entries);
+  const view: ReadonlyMap<K, V> = Object.freeze({
+    get size() { return values.size; },
+    get: (key: K) => values.get(key), has: (key: K) => values.has(key),
+    keys: () => values.keys(), values: () => values.values(), entries: () => values.entries(),
+    [Symbol.iterator]: () => values[Symbol.iterator](),
+    forEach: (callback: (value: V, key: K, map: ReadonlyMap<K, V>) => void, thisArg?: unknown) => {
+      values.forEach((value, key) => callback.call(thisArg, value, key, view));
+    },
+  });
+  return view;
+}
+function fail(message: string): never { throw new Error(`AI_AGENT_EXECUTION_RESOURCES_UNTRUSTED: ${message}`); }