gate-evm-tools 1.0.31 → 1.2.0

package/runtime/delivery/same-fork-baseline.ts

@@ -5,12 +5,13 @@ export interface SameForkInitialPreparation { request: GateToolPreparationReques
 /** Stable initial preparation and full prior layout commitment. Auxiliary compiler randomness is excluded. */
 export function sameForkBaselineDigest(initial: SameForkInitialPreparation, oldLayoutHash: string): string {
   const request = normalizePreparationRequest(initial.request), plan = normalizePreparationPlan(initial.plan);
-  if (request.kind !== 'uups-placeholder-deploy' || plan.kind !== request.kind || plan.requestHash !== hashPreparationRequest(request)
-    || plan.target !== request.target || !/^[a-f0-9]{64}$/.test(oldLayoutHash)) throw new Error('Invalid same-fork initial preparation');
+  if ((request.kind !== 'uups-placeholder-deploy' && request.kind !== 'transparent-deploy') || plan.kind !== request.kind || plan.requestHash !== hashPreparationRequest(request)
+    || plan.proxyKind !== request.proxyKind || plan.target !== request.target || !/^[a-f0-9]{64}$/.test(oldLayoutHash)) throw new Error('Invalid same-fork initial preparation');
   return semanticHash({kind:'same-fork',request,plan,oldLayoutHash});
 }
-export function matchesSameForkInitial(initial: SameForkInitialPreparation, target: string, chainId: string, proxy: string, implementation?: string): boolean {
-  return initial.request.kind === 'uups-placeholder-deploy' && initial.request.target === target && initial.plan.target === target && initial.plan.chainId === chainId
+export function matchesSameForkInitial(initial: SameForkInitialPreparation, target: string, chainId: string, proxy: string, implementation?: string, proxyKind?: 'uups' | 'transparent'): boolean {
+  return (initial.request.kind === 'uups-placeholder-deploy' || initial.request.kind === 'transparent-deploy') && initial.request.target === target && initial.plan.target === target && initial.plan.chainId === chainId
+    && initial.plan.proxyKind === initial.request.proxyKind && (proxyKind === undefined || initial.request.proxyKind === proxyKind)
     && initial.plan.deployments.some(d => d.role === 'proxy' && d.address.toLowerCase() === proxy.toLowerCase())
     && (implementation === undefined || initial.plan.deployments.some(d => d.role === 'implementation' && d.address.toLowerCase() === implementation.toLowerCase()));
 }

package/runtime/delivery/setup.ts

@@ -4,16 +4,20 @@ import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import YAML from 'yaml';
+import { REVIEWED_DELIVERY_OVERRIDES } from './toolchain';
 import { object } from './protocol';
-import { coreMarker, projectRoot, readFile, confinedFile, stat, integratedConfig, readProjectNetworkSnapshots, projectSourcesDirectory } from './project';
-import { configDocument, validateDeliveryTarget, type DeliveryTarget } from './config';
-export { readProjectNetworkSnapshots } from './project';
+import { deliveryProjectMarker, projectRoot, readFile, confinedFile, stat, integratedConfig, readPublicProjectNetworkSnapshots, projectSourcesDirectory } from './project';
+import { configDocument, parseDeliveryPublicTargets, validateDeliveryTarget, type DeliveryTarget } from './config';
+export { readProjectNetworkSnapshots, readPublicProjectNetworkSnapshots } from './project';
 export { loadDeliveryTarget } from './config';
 export { configureDeliveryEnvironment } from './manifest';
 export type { DeliveryTarget, DeliveryTargetConfig } from './config';
 
 const TOOLCHAIN: Record<string, string> = { hardhat: '2.26.3', ethers: '6.15.0', '@nomicfoundation/hardhat-ethers': '3.1.0', typescript: '5.9.3', 'ts-node': '10.9.2' };
-const DEPENDENCIES: Record<string, string> = { 'gate-evm-tools': '1.0.29', '@openzeppelin/hardhat-upgrades': '3.9.1', '@openzeppelin/upgrades-core': '1.44.2', '@openzeppelin/contracts': '5.4.0' };
+// Resolve our identity from the executing package, including an explicitly installed tarball.
+const toolIdentity = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8'));
+if (toolIdentity.name !== 'gate-evm-tools' || typeof toolIdentity.version !== 'string') throw new Error('Invalid GateTool package identity');
+const DEPENDENCIES: Record<string, string> = { 'gate-evm-tools': toolIdentity.version, '@openzeppelin/hardhat-upgrades': '3.9.1', '@openzeppelin/upgrades-core': '1.44.2', '@openzeppelin/contracts': '5.4.0' };
 export interface DeliverySetupOptions {
   workspaceRoot: string;
   projectRoot: string;
@@ -65,10 +69,14 @@ function preflight(input: DeliverySetupOptions): { result: DeliveryInspection; w
   const targets = input.targets.map(validateDeliveryTarget);
   if (new Set(targets.map(target => target.network)).size !== targets.length) throw new Error('Duplicate selected target');
   const root = projectRoot(input.workspaceRoot, input.projectRoot);
-  coreMarker(root);
+  deliveryProjectMarker(root);
   const before = new Map<string, string | undefined>();
   for (const file of ['.gate-template.json', 'package.json', 'hardhat.config.ts', 'config.yaml', 'contractInfo.json']) before.set(file, readFile(root, file));
   const pkg = object(JSON.parse(before.get('package.json') ?? 'null'), 'package.json');
+  const overrides = pkg.overrides === undefined ? {} : object(pkg.overrides, 'package overrides');
+  for (const [name, version] of Object.entries(REVIEWED_DELIVERY_OVERRIDES)) {
+    if (overrides[name] !== undefined && overrides[name] !== version) throw new Error(`Reviewed delivery dependency override conflict: ${name}`);
+  }
   const declarations: Record<string, unknown> = {};
   for (const section of ['dependencies', 'devDependencies']) {
     const entries = pkg[section] === undefined ? {} : object(pkg[section], section);
@@ -89,7 +97,7 @@ function preflight(input: DeliverySetupOptions): { result: DeliveryInspection; w
     const localTool = name === 'gate-evm-tools' && input.toolPackage === undefined && typeof declared === 'string' && /^file:.*\.tgz$/.test(declared);
     if ((name in TOOLCHAIN && declared === undefined) || (declared !== undefined && declared !== version && !localTool)) throw new Error(`Dependency declaration conflict for ${name}: expected ${version}`);
   }
-  const networks = readProjectNetworkSnapshots(root, targets.map(target => target.network));
+  const networks = readPublicProjectNetworkSnapshots(root, targets.map(target => target.network));
   const source = before.get('hardhat.config.ts')!;
   const withPlugin = integratedConfig(source); // Check integration conflicts even when dependencies are missing.
   const doc = configDocument(root);
@@ -106,6 +114,9 @@ function preflight(input: DeliverySetupOptions): { result: DeliveryInspection; w
     confinedFile(root, target.openzeppelin!.manifestDir, 'directory');
     merge([network], target);
   }
+  // Validate the same effective facilities used by input qualification, while keeping inherited
+  // addresses in their profiles so later base edits propagate to non-overridden targets.
+  parseDeliveryPublicTargets(Buffer.from(doc.toString()), Buffer.from(source), targets);
   if (before.get('contractInfo.json') !== undefined) object(JSON.parse(before.get('contractInfo.json')!), 'contractInfo.json');
   const dependencies: DeliveryInspection['dependencies'] = [];
   const projectRequire = createRequire(path.join(root, 'package.json'));
@@ -140,10 +151,11 @@ function preflight(input: DeliverySetupOptions): { result: DeliveryInspection; w
   }
   const writes = new Map<string, string>();
   const missing = Object.entries(required).filter(([name]) => declarations[name] === undefined);
-  if (missing.length) {
+  const missingOverrides = Object.entries(REVIEWED_DELIVERY_OVERRIDES).some(([name]) => overrides[name] === undefined);
+  if (missing.length || missingOverrides) {
     const dev = { ...(pkg.devDependencies as Record<string, unknown> ?? {}) };
     for (const [name, version] of missing) dev[name] = version;
-    writes.set('package.json', JSON.stringify({ ...pkg, devDependencies: dev }, null, 2) + '\n');
+    writes.set('package.json', JSON.stringify({ ...pkg, devDependencies: dev, overrides: { ...overrides, ...REVIEWED_DELIVERY_OVERRIDES } }, null, 2) + '\n');
   }
   if (changedYaml) writes.set('config.yaml', doc.toString());
   if (before.get('contractInfo.json') === undefined) writes.set('contractInfo.json', '{}\n');

package/runtime/delivery/source.ts

@@ -1,7 +1,7 @@
 /** Actual-file source binding only. This API grants no host approval or execution authority. */
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
-import { coreMarker, projectRoot, confinedFile } from './project-files';
+import { deliveryProjectMarker, projectRoot, confinedFile } from './project-files';
 import { object, parseDeliveryRequest, validateDeliveryRpc, type DeliveryRequest, type ChainIdProvider, type ProjectNetworkSnapshot } from './protocol';
 import { loadPlanCodec } from './codec';
 import type { Plan, PlanTask, DefinitionSelection, DefinitionSnapshot, DeepReadonly } from '../vendor/plan-codec/index.cjs';
@@ -37,11 +37,9 @@ export function parseCanonicalPlan(text: string): Plan { return loadPlanCodec().
 export function projectCanonicalDefinitions(text: string, selection: DefinitionSelection): ReturnType<ReturnType<typeof loadPlanCodec>['projectDefinitions']> {
   return loadPlanCodec().projectDefinitions(text, selection);
 }
-const purposeSteps = {
-  'dev-execution': ['deploy', 'check-code'],
-  'prod-qualification': ['deploy-test'],
-  'prod-execution': ['release-prepare', 'release-execute', 'release-verify'],
-};
+export function deploymentPurpose(task: Pick<PlanTask, 'step' | 'scope'>) {
+  return loadPlanCodec().deploymentPurpose(task);
+}
 function sameRelease(actual: unknown, expected: DeliveryRequest['releaseRef']): boolean {
   if (expected === undefined) return actual === undefined;
   if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return false;
@@ -78,7 +76,7 @@ function readSource(input: Omit<DeliverySourceOptions, 'sourceRoots'> & { source
   const request = parseDeliveryRequest(input.request);
   const workspace = projectRoot(input.workspaceRoot, '.');
   const root = projectRoot(workspace, input.projectRoot);
-  coreMarker(root);
+  deliveryProjectMarker(root);
   const bytes = actualSource(workspace, request.sourceRef.path);
   const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
   if (input.sourceRoots === undefined) (require('./input-files') as typeof import('./input-files')).assertUnambiguousHandoff(text);
@@ -89,15 +87,17 @@ function readSource(input: Omit<DeliverySourceOptions, 'sourceRoots'> & { source
   const invocation = entries.find(({ task }) => task.planKey === request.sourceRef.planKey);
   if (!invocation || invocation.task.rev !== request.sourceRef.rev) throw new Error('sourceRef planKey/rev does not match actual handoff');
   if (plan.lanes[invocation.lane].state !== 'enabled' || invocation.task.status === 'cancelled') throw new Error('Invocation task is disabled or cancelled');
+  const requirementIssue = codec.deploymentRequirementIssue(plan, invocation.task);
+  if (requirementIssue) throw new Error(requirementIssue);
   const deployment = object(invocation.task.scope?.deployment, 'invocation scope.deployment');
   if (deployment.projectRoot !== input.projectRoot) throw new Error('Invocation projectRoot mismatch');
   if (deployment.chainFamily !== 'evm' || deployment.framework !== 'hardhat2') throw new Error('Invocation requires an EVM Hardhat2 deployment');
-  if (!purposeSteps[request.purpose].includes(invocation.task.step ?? '')) throw new Error('Invocation purpose/step mismatch');
+  if (deploymentPurpose(invocation.task) !== request.purpose) throw new Error('Invocation purpose mismatch');
   if (deployment.environment !== request.environment || deployment.targetNetwork !== request.network) throw new Error('Invocation environment/targetNetwork mismatch');
   if (!Array.isArray(deployment.allowedActions) || !deployment.allowedActions.includes(request.mode)) throw new Error('Invocation mode is not in allowedActions');
   if (!sameRelease(deployment.releaseRef, request.releaseRef)) throw new Error('Invocation releaseRef mismatch');
   const sourceRoots = input.sourceRoots ?? (request.purpose === 'prod-execution'
-    ? entries.filter(({ task }) => task.step === 'deploy-test'
+    ? entries.filter(({ task }) => deploymentPurpose(task) === 'prod-qualification'
       && (task.scope?.deployment as Record<string, unknown> | undefined)?.projectRoot === input.projectRoot
       && (task.scope?.deployment as Record<string, unknown> | undefined)?.deploymentId === deployment.deploymentId).map(({ task }) => task.planKey)
     : [invocation.task.planKey]);
@@ -109,7 +109,7 @@ function readSource(input: Omit<DeliverySourceOptions, 'sourceRoots'> & { source
   }
   let production: ReturnType<typeof codec.projectDefinitions> | undefined;
   if (request.purpose === 'prod-execution') {
-    const roots = entries.filter(({ task }) => purposeSteps['prod-execution'].includes(task.step ?? '')
+    const roots = entries.filter(({ task }) => deploymentPurpose(task) === 'prod-execution'
       && task.scope?.deployment && (task.scope.deployment as Record<string, unknown>).projectRoot === input.projectRoot
       && sameRelease((task.scope.deployment as Record<string, unknown>).releaseRef, request.releaseRef)).map(({ task }) => task.planKey);
     production = codec.projectDefinitions(text, { roots, mode: 'full' });

package/runtime/delivery/task-identity.ts

@@ -0,0 +1,85 @@
+/** Allocate a round only after its concrete requirement revision is confirmed. */
+import fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { parseCanonicalPlan, projectCanonicalDefinitions, deploymentPurpose } from './source';
+import { projectRoot, deliveryProjectMarker, confinedFile, stat } from './project-files';
+import { readInputBytes, assertUnambiguousHandoff } from './input-files';
+import { withDevelopmentFileLock, atomicDevelopmentWrite, fileBytes } from './materialization';
+import { exactObject, semanticHash, canonicalJson } from '../workflow/lib/canonicalData';
+import { safeId, portablePath, object } from './protocol';
+
+export interface DeploymentRequirementRef { planKey: string; rev: number }
+export function parseDeploymentRequirementRef(raw: unknown): DeploymentRequirementRef {
+  const ref = exactObject(raw, ['planKey', 'rev'], 'requirementRef');
+  safeId(ref.planKey, 'requirementRef.planKey');
+  if (!Number.isSafeInteger(ref.rev) || (ref.rev as number) < 1) throw Error('Invalid requirement revision');
+  return { planKey: ref.planKey as string, rev: ref.rev as number };
+}
+export interface CreateDeliveryTaskOptions {
+  workspaceRoot: string; projectRoot: string; handoff: string; taskId: string;
+  requirementRef: DeploymentRequirementRef; businessSlug: string; referenceDeploymentId?: string;
+}
+/** A reservation creates metadata only. The deployment Agent supplies executable content afterwards. */
+export async function createDeliveryTask(input: CreateDeliveryTaskOptions) {
+  object(input, 'create deployment task', ['workspaceRoot', 'projectRoot', 'handoff', 'taskId', 'requirementRef', 'businessSlug', 'referenceDeploymentId']);
+  const root = projectRoot(input.workspaceRoot, input.projectRoot), workspace = projectRoot(input.workspaceRoot, '.');
+  deliveryProjectMarker(root);
+  portablePath(input.handoff, 'handoff'); safeId(input.taskId, 'taskId');
+  const ref = parseDeploymentRequirementRef(input.requirementRef);
+  if (typeof input.businessSlug !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(input.businessSlug)) throw Error('businessSlug must be a short lowercase business name');
+  if (input.referenceDeploymentId !== undefined) safeId(input.referenceDeploymentId, 'referenceDeploymentId');
+  return withDevelopmentFileLock(root, async () => {
+    const text = readInputBytes(workspace, input.handoff).toString(); assertUnambiguousHandoff(text);
+    const plan = parseCanonicalPlan(text);
+    if (plan.taskId !== input.taskId) throw Error('Requirement taskId mismatch');
+    const requirement = Object.values(plan.tasks).flat().find(t => t.planKey === ref.planKey);
+    if (!requirement || requirement.rev !== ref.rev || requirement.requirementConfirmation?.rev !== ref.rev
+      || requirement.status === 'cancelled' || deploymentPurpose(requirement) !== 'analysis'
+      || (requirement.scope?.deployment as any)?.projectRoot !== input.projectRoot) throw Error('Deployment requirement is unconfirmed or stale');
+    const d = requirement.scope!.deployment as any;
+    if (!d.requiredOperations?.length || !d.developmentNetwork || !Array.isArray(d.releaseTargetNetworks)) throw Error('Confirmed requirement scope is incomplete');
+    const identity = semanticHash({ taskId: input.taskId, projectRoot: input.projectRoot, requirementRef: ref });
+    const requirementHash = semanticHash(projectCanonicalDefinitions(text, { roots: [ref.planKey], mode: 'upstream' }).snapshot);
+    const registry = `.gate-delivery/deployment-requests/${identity}.json`;
+    const requestIdentity = { taskId: input.taskId, requirementRef: ref, requirementHash,
+      referenceDeploymentId: input.referenceDeploymentId ?? null };
+    let record: any;
+    const existing = fileBytes(root, registry);
+    if (existing !== null) {
+      record = JSON.parse(existing);
+      if (canonicalJson(record.requestIdentity) !== canonicalJson(requestIdentity)) throw Error('Confirmed requirement identity conflict');
+      safeId(record.deploymentId, 'reserved deploymentId');
+    } else {
+      const known = new Set(Object.values(plan.tasks).flat().map(t => (t.scope?.deployment as any)?.deploymentId).filter(Boolean));
+      const history = fileBytes(workspace, input.handoff.includes('/') ? `${input.handoff.slice(0, input.handoff.lastIndexOf('/'))}/handoff-ledger.jsonl` : 'handoff-ledger.jsonl');
+      if (history) for (const line of history.split('\n').filter(Boolean)) {
+        const item = JSON.parse(line);
+        for (const entry of item.tasks ?? []) { const id = entry.task?.scope?.deployment?.deploymentId; if (id) known.add(id); }
+      }
+      const date = new Date().toISOString().slice(0, 10).replaceAll('-', '');
+      let deploymentId: string;
+      do { deploymentId = `${input.businessSlug}-${date}-${randomBytes(4).toString('hex')}`; }
+      while (known.has(deploymentId) || stat(confinedFile(root, `scripts/tasks/${deploymentId}`, 'directory')));
+      record = { version: 1, deploymentId, releaseId: `${deploymentId}-release`, requestIdentity, state: 'reserved' };
+      // Publish reservation before creating the package, so a retry uses the same ID.
+      atomicDevelopmentWrite(root, registry, canonicalJson(record) + '\n');
+    }
+    const businessRoot = `scripts/tasks/${record.deploymentId}`;
+    const directory = confinedFile(root, businessRoot, 'directory');
+    const marker = `${businessRoot}/.request.json`;
+    const markerBytes = canonicalJson({ identity }) + '\n';
+    const previousMarker = fileBytes(root, marker);
+    if (stat(directory) && previousMarker !== markerBytes && fs.readdirSync(directory).length) throw Error('Reserved deployment directory is occupied; refusing to overwrite');
+    if (previousMarker !== null && previousMarker !== markerBytes) throw Error('Deployment reservation ownership mismatch');
+    if (previousMarker === null) atomicDevelopmentWrite(root, marker, markerBytes);
+    const metadata = { version: 1, id: record.deploymentId, requirementRef: ref,
+      developmentNetwork: d.developmentNetwork, releaseTargetNetworks: d.releaseTargetNetworks,
+      ...(input.referenceDeploymentId ? { referenceDeploymentId: input.referenceDeploymentId } : {}) };
+    const taskPath = `${businessRoot}/task.yaml`, bytes = canonicalJson(metadata) + '\n';
+    const previous = fileBytes(root, taskPath);
+    if (previous !== null && previous !== bytes) throw Error('Reserved task metadata changed; refusing to overwrite');
+    if (previous === null) atomicDevelopmentWrite(root, taskPath, bytes);
+    if (record.state !== 'complete') atomicDevelopmentWrite(root, registry, canonicalJson({ ...record, state: 'complete' }) + '\n');
+    return { status: 'created' as const, deploymentId: record.deploymentId as string, releaseId: record.releaseId as string, businessRoot, specPath: taskPath, requirementRef: ref };
+  });
+}

package/runtime/delivery/toolchain.ts

@@ -0,0 +1,48 @@
+import { compilerDependencyPins } from './compiler-dependency-pins';
+
+/** Reviewed compiler adapter dependency selections; payload checks remain authoritative.
+ * Range-scoped entries preserve distinct dependency majors. Setup never overrides a conflicting project choice. */
+export const REVIEWED_DELIVERY_OVERRIDES: Record<string, string> = {
+  "axios": "1.20.0",
+  "@aws-sdk/client-lambda": "3.1152.0",
+  "@aws-sdk/core": "3.978.3",
+  "@aws-sdk/credential-provider-env": "3.972.74",
+  "@aws-sdk/credential-provider-http": "3.972.76",
+  "@aws-sdk/credential-provider-ini": "3.973.19",
+  "@aws-sdk/credential-provider-login": "3.972.81",
+  "@aws-sdk/credential-provider-node": "3.972.86",
+  "@aws-sdk/credential-provider-process": "3.972.74",
+  "@aws-sdk/credential-provider-sso": "3.973.18",
+  "@aws-sdk/credential-provider-web-identity": "3.972.80",
+  "@aws-sdk/nested-clients": "3.997.48",
+  "@aws-sdk/signature-v4-multi-region": "3.996.48",
+  "@aws-sdk/token-providers": "3.1150.0",
+  "@aws-sdk/types": "3.974.6",
+  "@smithy/types": "4.19.0",
+  "@smithy/signature-v4": "5.7.4",
+  "@smithy/fetch-http-handler": "5.8.0",
+  "@smithy/credential-provider-imds": "4.5.2",
+  "@smithy/core": "3.36.0",
+  "@smithy/node-http-handler": "4.12.1",
+  "bowser": "2.14.1",
+  "follow-redirects": "1.16.1",
+  "undici@>=5 <6": "5.29.0",
+  "undici@>=6 <7": "6.29.0",
+  "tslib@>=1 <2": "1.14.1",
+  "tslib@>=2 <3": "2.7.0",
+  "semver@>=5 <6": "5.7.2",
+  "semver@>=6 <7": "6.3.1",
+  "semver@>=7 <8": "7.8.5",
+  "ansi-regex@>=6 <7": "6.4.0"
+};
+
+// OZ's compiler adapter follows floating AWS/Smithy ranges. Freeze that reviewed
+// family closure so a fresh npm resolution cannot select unqualified payloads.
+// Other project dependencies keep their original constraints and payload checks.
+for (const key of Object.keys(compilerDependencyPins)) {
+  if (!key.startsWith('@aws-sdk/') && !key.startsWith('@smithy/')) continue;
+  const at = key.lastIndexOf('@'), name = key.slice(0, at), version = key.slice(at + 1);
+  const existing = REVIEWED_DELIVERY_OVERRIDES[name];
+  if (existing && existing !== version) throw new Error('Ambiguous reviewed compiler dependency: ' + name);
+  REVIEWED_DELIVERY_OVERRIDES[name] = version;
+}

package/runtime/delivery/validation.ts

@@ -118,13 +118,16 @@ export function createDeliveryValidation(
         const args = first
           ? (first.constructorArgs ?? [])
           : step.kind === "deploy"
-            ? (step.args ?? [])
+            ? (proxy ? (proxy.constructorArgs ?? []) : (step.args ?? []))
             : (step.constructorArgs ??
               (typeof proxy === "object"
                 ? proxy?.constructorArgs
                 : undefined) ??
               []);
         await argumentsFor(name as string, null, args, true);
+        if (step.kind === "deploy" && proxy?.kind === "transparent" && proxy.initializer !== false) {
+          await argumentsFor(name as string, String(proxy.initializer), step.args ?? [], true);
+        }
         const init = (first?.call ?? step.call) as
           | Record<string, unknown>
           | undefined;
@@ -169,7 +172,9 @@ export function createDeliveryValidation(
                 true,
               )
             : declaredCreate2;
-        if (step.kind === "deploy" && create2) {
+        // Transparent proxy prediction depends on the prepared implementation salt/address.
+        // Its actual constructor and policies are independently checked by preparation semantics.
+        if (step.kind === "deploy" && create2 && proxy?.kind !== "transparent") {
           const a = await read(first ? ERC1967_PROXY : (name as string));
           const constructor = resolve(
             first

package/runtime/vendor/plan-codec/index.cjs

@@ -28,8 +28,11 @@ __export(read_only_exports, {
   SCHEMA_V1: () => SCHEMA_V1,
   SKILL_NAME: () => SKILL_NAME,
   TASK_STATUSES: () => TASK_STATUSES,
+  deploymentPurpose: () => deploymentPurpose,
+  deploymentRequirementIssue: () => deploymentRequirementIssue,
   detectSchema: () => detectSchema,
   parsePlan: () => parsePlan,
+  productionActionAllowed: () => productionActionAllowed,
   projectDefinitions: () => projectDefinitions,
   skillNames: () => skillNames,
   toolRefs: () => toolRefs,
@@ -39,7 +42,7 @@ module.exports = __toCommonJS(read_only_exports);
 
 // builtin-skills/gateflow-plan/scripts/lib/evm-contract.mjs
 var PROJECT_FIELDS = ["chainFamily", "framework", "projectRoot", "templateProfile", "templateVersion", "mode"];
-var DEPLOYMENT_FIELDS = ["chainFamily", "framework", "projectRoot", "deploymentId", "specPath", "sourceCodeRef", "requiredOperations", "developmentNetwork", "releaseTargetNetworks", "environment", "targetNetwork", "allowedActions", "releaseRef"];
+var DEPLOYMENT_FIELDS = ["purpose", "chainFamily", "framework", "projectRoot", "deploymentId", "specPath", "sourceCodeRef", "requiredOperations", "developmentNetwork", "releaseTargetNetworks", "environment", "targetNetwork", "allowedActions", "releaseRef", "requirementRef", "productionRequirementRef", "referenceDeploymentId"];
 var ANALYSIS_STEPS = ["deployment-request", "deployment-plan", "script"];
 var STEP_ACTIONS = {
   deploy: ["simulate", "execute", "reconcile", "verify"],
@@ -49,11 +52,53 @@ var STEP_ACTIONS = {
   "release-execute": ["execute", "export-calldata", "reconcile"],
   "release-verify": ["verify"]
 };
+var PURPOSE_ACTIONS = {
+  "dev-execution": ["simulate", "execute", "reconcile", "verify"],
+  "prod-qualification": ["simulate", "verify"],
+  "prod-execution": ["simulate", "execute", "export-calldata", "reconcile", "verify"]
+};
+function deploymentPurpose(task) {
+  const explicit = task.scope?.deployment?.purpose;
+  if (explicit !== void 0) return explicit;
+  if (ANALYSIS_STEPS.includes(task.step)) return "analysis";
+  if (["deploy", "check-code"].includes(task.step)) return "dev-execution";
+  if (task.step === "deploy-test") return "prod-qualification";
+  if (["release-prepare", "release-execute", "release-verify"].includes(task.step)) return "prod-execution";
+  return void 0;
+}
+function productionActionAllowed(task, intent) {
+  const d = task.scope?.deployment;
+  const action = intent === "prepare" ? "simulate" : intent;
+  return deploymentPurpose(task) === "prod-execution" && d?.environment === "prod" && !!d.releaseRef && Array.isArray(d.allowedActions) && d.allowedActions.includes(action);
+}
 var OPERATIONS = ["deploy", "upgrade", "call", "view", "check", "custom"];
 var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function deploymentRequirementIssue(plan, task) {
+  const d = task.scope?.deployment;
+  if (!d || deploymentPurpose(task) === "analysis") return null;
+  const ref = d.requirementRef;
+  if (!ref) return "部署实施前必须引用本轮已确认的需求（requirementRef）";
+  const request = Object.values(plan.tasks).flat().find((t) => t.planKey === ref.planKey);
+  if (!request || request.status === "cancelled" || deploymentPurpose(request) !== "analysis" || request.scope?.deployment?.projectRoot !== d.projectRoot || request.rev !== ref.rev || request.requirementConfirmation?.rev !== ref.rev) return "本轮部署需求尚未确认或确认修订已失效";
+  const r = request.scope.deployment;
+  if (d.productionRequirementRef !== void 0) {
+    if (!["prod-qualification", "prod-execution"].includes(deploymentPurpose(task))) return "生产补充确认只用于 prod 资格或执行任务";
+    const extra = d.productionRequirementRef;
+    const production = Object.values(plan.tasks).flat().find((t) => t.planKey === extra.planKey);
+    const p = production?.scope?.deployment;
+    if (!production || production.status === "cancelled" || deploymentPurpose(production) !== "analysis" || production.rev !== extra.rev || production.requirementConfirmation?.rev !== extra.rev || p?.projectRoot !== d.projectRoot || p?.deploymentId !== d.deploymentId || JSON.stringify(p.requirementRef) !== JSON.stringify(ref)) return "本轮生产补充需求尚未确认或绑定已失效";
+    if (!task.dependsOn.includes(production.planKey)) return "生产任务必须依赖其补充需求确认任务";
+    if (p.developmentNetwork !== r.developmentNetwork || d.developmentNetwork !== r.developmentNetwork || p.sourceCodeRef !== d.sourceCodeRef || JSON.stringify(p.releaseTargetNetworks) !== JSON.stringify(d.releaseTargetNetworks) || !d.requiredOperations?.every((operation) => p.requiredOperations?.includes(operation) && r.requiredOperations?.includes(operation))) return "生产补充需求只能扩充 prod 网络与参数，不能改变原部署动作或源码";
+    return null;
+  }
+  if (r.developmentNetwork !== d.developmentNetwork || JSON.stringify(r.releaseTargetNetworks) !== JSON.stringify(d.releaseTargetNetworks) || !d.requiredOperations?.every((operation) => r.requiredOperations?.includes(operation))) return "部署动作或网络超出本轮确认范围";
+  return null;
+}
 function validateEvmContracts(plan, fail3) {
   const releases = /* @__PURE__ */ new Map();
   const projects = /* @__PURE__ */ new Map();
+  const requirementRounds = /* @__PURE__ */ new Map();
+  const roundRequirements = /* @__PURE__ */ new Map();
   const object = (value, where, fields) => {
     if (!isObject(value)) fail3(`${where} 必须是对象`);
     for (const field of Object.keys(value)) if (!fields.includes(field)) fail3(`${where}.${field} 是未知字段`);
@@ -101,7 +146,7 @@ function validateEvmContracts(plan, fail3) {
       if (explicitEvmProject || evmProject && (project !== void 0 || task.step === "project-setup")) {
         const p = object(project, `${where}.project`, PROJECT_FIELDS);
         identity(p, `${where}.project`);
-        if (p.templateProfile !== "core") fail3(`${where}.project.templateProfile 必须是 core`);
+        if (p.templateProfile !== "full") fail3(`${where}.project.templateProfile 必须是 full`);
         if (p.templateVersion !== 1) fail3(`${where}.project.templateVersion 必须是 1`);
         if (!["create", "resume"].includes(p.mode)) fail3(`${where}.project.mode 必须是 create 或 resume`);
         const metadata2 = JSON.stringify([p.chainFamily, p.framework, p.templateProfile, p.templateVersion]);
@@ -113,29 +158,38 @@ function validateEvmContracts(plan, fail3) {
       const w = `${where}.deployment`;
       const d = object(task.scope?.deployment, w, DEPLOYMENT_FIELDS);
       identity(d, w);
-      identifier(d.deploymentId, `${w}.deploymentId`);
-      relativePath(d.specPath, `${w}.specPath`);
-      if (task.step !== "deployment-request" || d.sourceCodeRef !== void 0) text(d.sourceCodeRef, `${w}.sourceCodeRef`);
-      if (task.step !== "deployment-request" || d.requiredOperations !== void 0) strings(d.requiredOperations, `${w}.requiredOperations`, OPERATIONS, 1);
-      identifier(d.developmentNetwork, `${w}.developmentNetwork`, true);
-      strings(d.releaseTargetNetworks, `${w}.releaseTargetNetworks`);
-      for (const network of d.releaseTargetNetworks) identifier(network, `${w}.releaseTargetNetworks`, true);
-      if (ANALYSIS_STEPS.includes(task.step)) {
+      const initialAnalysis = d.purpose === "analysis" || d.purpose === void 0 && task.step === "deployment-request";
+      if (!initialAnalysis || d.deploymentId !== void 0) identifier(d.deploymentId, `${w}.deploymentId`);
+      if (!initialAnalysis || d.specPath !== void 0) relativePath(d.specPath, `${w}.specPath`);
+      if (!initialAnalysis || d.sourceCodeRef !== void 0) text(d.sourceCodeRef, `${w}.sourceCodeRef`);
+      if (!initialAnalysis || d.requiredOperations !== void 0) strings(d.requiredOperations, `${w}.requiredOperations`, OPERATIONS, 1);
+      if (!initialAnalysis || d.developmentNetwork !== void 0) identifier(d.developmentNetwork, `${w}.developmentNetwork`, true);
+      if (!initialAnalysis || d.releaseTargetNetworks !== void 0) strings(d.releaseTargetNetworks, `${w}.releaseTargetNetworks`);
+      for (const network of d.releaseTargetNetworks ?? []) identifier(network, `${w}.releaseTargetNetworks`, true);
+      if (d.referenceDeploymentId !== void 0) identifier(d.referenceDeploymentId, `${w}.referenceDeploymentId`);
+      for (const field of ["requirementRef", "productionRequirementRef"]) if (d[field] !== void 0) {
+        const ref2 = object(d[field], `${w}.${field}`, ["planKey", "rev"]);
+        identifier(ref2.planKey, `${w}.${field}.planKey`);
+        if (!Number.isSafeInteger(ref2.rev) || ref2.rev < 1) fail3(`${w}.${field}.rev 必须是正整数`);
+      }
+      const purpose = deploymentPurpose(task);
+      if (d.productionRequirementRef !== void 0 && !["prod-qualification", "prod-execution"].includes(purpose)) fail3(`${w}.productionRequirementRef 只用于 prod 任务`);
+      if (!["analysis", ...Object.keys(PURPOSE_ACTIONS)].includes(purpose)) fail3(`${w} 不支持步骤 ${task.step}；purpose 必须明确部署用途`);
+      if (purpose === "analysis") {
         for (const field of ["environment", "targetNetwork", "allowedActions", "releaseRef"]) {
           if (d[field] !== void 0) fail3(`${w}.${field} 只能用于执行任务`);
         }
         continue;
       }
-      const actions = STEP_ACTIONS[task.step];
-      if (!Object.hasOwn(STEP_ACTIONS, task.step ?? "")) fail3(`${w} 不支持步骤 ${task.step}`);
-      const environment = ["deploy", "check-code"].includes(task.step) ? "dev" : "prod";
+      const actions = d.purpose === void 0 ? STEP_ACTIONS[task.step] : PURPOSE_ACTIONS[purpose];
+      const environment = purpose === "dev-execution" ? "dev" : "prod";
       if (d.environment !== environment) fail3(`${w}.environment 在 ${task.step} 中必须是 ${environment}`);
       identifier(d.targetNetwork, `${w}.targetNetwork`, true);
       if (environment === "dev" ? d.targetNetwork !== d.developmentNetwork : !d.releaseTargetNetworks.includes(d.targetNetwork)) {
         fail3(`${w}.targetNetwork 与已声明的 ${environment} 网络不一致`);
       }
       strings(d.allowedActions, `${w}.allowedActions`, actions, 1);
-      if (!task.step.startsWith("release-")) {
+      if (purpose !== "prod-execution") {
         if (d.releaseRef !== void 0) fail3(`${w}.releaseRef 只用于正式发布任务`);
         continue;
       }
@@ -150,6 +204,18 @@ function validateEvmContracts(plan, fail3) {
       releases.set(releaseKey, metadata);
     }
   }
+  for (const task of Object.values(plan.tasks).flat()) {
+    const d = task.scope?.deployment;
+    if (!d?.requirementRef || deploymentPurpose(task) === "analysis") continue;
+    const requirement = JSON.stringify([d.projectRoot, d.requirementRef.planKey, d.requirementRef.rev]);
+    const round = JSON.stringify([d.projectRoot, d.deploymentId]);
+    const existingRound = requirementRounds.get(requirement);
+    if (existingRound !== void 0 && existingRound !== d.deploymentId) fail3(`任务 ${task.planKey}.scope.deployment 同一需求修订必须复用 deploymentId=${existingRound}，不能因脚本准备、模拟或执行阶段另建部署轮次`);
+    const existingRequirement = roundRequirements.get(round);
+    if (existingRequirement !== void 0 && existingRequirement !== requirement) fail3(`任务 ${task.planKey}.scope.deployment 同一 deploymentId 必须引用同一需求修订；新业务轮次使用新 deploymentId`);
+    requirementRounds.set(requirement, d.deploymentId);
+    roundRequirements.set(round, requirement);
+  }
 }
 
 // builtin-skills/gateflow-plan/scripts/lib/yaml-lite.mjs
@@ -386,8 +452,8 @@ var TASK_STATUSES = ["pending", "running", "blocked", "completed", "failed", "ca
 var FAILURE_CATEGORIES = ["execution_error", "acceptance_failed", "review_rejected", "input_missing"];
 var CONTRACT_FIELDS = ["objective", "acceptance", "dependsOn", "step", "scope", "parameters", "expectedArtifacts", "allowedChanges"];
 var TOOL_FIELDS = ["tools", "toolsOptional", "skills"];
-var DEF_FIELDS = [...CONTRACT_FIELDS, ...TOOL_FIELDS];
-var PROGRESS_FIELDS = ["status", "adoptedRev", "blockedReason", "cancelReason", "result", "previousResult"];
+var DEF_FIELDS = [...CONTRACT_FIELDS, ...TOOL_FIELDS, "executionNotes"];
+var PROGRESS_FIELDS = ["status", "adoptedRev", "blockedReason", "cancelReason", "result", "previousResult", "requirementConfirmation"];
 var TASK_ORDER = ["no", "planKey", "rev", "title", ...DEF_FIELDS, ...PROGRESS_FIELDS];
 var PlanError = class extends Error {
   constructor(message, code = "invalid") {
@@ -508,11 +574,11 @@ function parseResult(v, where) {
   }
   fail2(`${where}.kind 必须是 success 或 failure`);
 }
-var TOOL_REF = /^(?:plugin:[A-Za-z0-9][A-Za-z0-9._-]{0,99}|mcp:[A-Za-z0-9][A-Za-z0-9._-]{0,99}(?:\/[A-Za-z0-9][A-Za-z0-9._-]{0,99})?)$/;
+var TOOL_REF = /^(?:plugin:[A-Za-z0-9][A-Za-z0-9._-]{0,99}|mcp:[A-Za-z0-9][A-Za-z0-9._-]{0,99}(?:\/[A-Za-z0-9][A-Za-z0-9._-]{0,99})?|host:[A-Za-z0-9][A-Za-z0-9._-]{0,99})$/;
 function toolRefs(v, where) {
   const refs = strArray(v, where);
   refs.forEach((ref, i) => {
-    if (!TOOL_REF.test(ref)) fail2(`${where}[${i}] 不是有效的工具引用："${ref}"（plugin:<id> 或 mcp:<服务器>[/<工具>]）`);
+    if (!TOOL_REF.test(ref)) fail2(`${where}[${i}] 不是有效的工具引用："${ref}"（plugin:<id>、mcp:<服务器>[/<工具>] 或 host:<本机 Codex 的 MCP>）`);
   });
   if (new Set(refs).size !== refs.length) fail2(`${where} 有重复的工具`);
   return refs;
@@ -544,6 +610,7 @@ function parseTaskDef(raw, where) {
     t.parameters = raw.parameters;
   }
   if (raw.expectedArtifacts !== void 0) t.expectedArtifacts = strArray(raw.expectedArtifacts, `${where}.expectedArtifacts`);
+  if (raw.executionNotes !== void 0) t.executionNotes = strArray(raw.executionNotes, `${where}.executionNotes`);
   if (raw.allowedChanges !== void 0) t.allowedChanges = strArray(raw.allowedChanges, `${where}.allowedChanges`);
   if (raw.tools !== void 0) t.tools = toolRefs(raw.tools, `${where}.tools`);
   if (raw.toolsOptional !== void 0) t.toolsOptional = toolRefs(raw.toolsOptional, `${where}.toolsOptional`);
@@ -567,6 +634,12 @@ function parseTask(raw, where) {
   }
   if (raw.blockedReason !== void 0) t.blockedReason = str(raw.blockedReason, `${where}.blockedReason`);
   if (raw.cancelReason !== void 0) t.cancelReason = str(raw.cancelReason, `${where}.cancelReason`);
+  if (raw.requirementConfirmation !== void 0) {
+    const c = raw.requirementConfirmation;
+    if (!isObject2(c) || Object.keys(c).some((k) => !["rev", "confirmedAt"].includes(k))) fail2(`${where}.requirementConfirmation 无效`);
+    t.requirementConfirmation = { rev: posInt(c.rev, `${where}.requirementConfirmation.rev`), confirmedAt: str(c.confirmedAt, `${where}.requirementConfirmation.confirmedAt`) };
+    if (c.rev > t.rev || !Number.isFinite(Date.parse(c.confirmedAt))) fail2(`${where}.requirementConfirmation 修订或时间无效`);
+  }
   const result = parseResult(raw.result, `${where}.result`);
   if (result) t.result = result;
   const previous = parseResult(raw.previousResult, `${where}.previousResult`);
@@ -747,7 +820,6 @@ function parsePlan(text) {
 
 // builtin-skills/gateflow-plan/scripts/lib/read-only.mjs
 var DEFINITION_CONTRACT = "gateflow-plan/definition@1";
-var RELEASE_STEPS = /* @__PURE__ */ new Set(["release-prepare", "release-execute", "release-verify"]);
 function freeze(value) {
   if (value && typeof value === "object") {
     Object.values(value).forEach(freeze);
@@ -774,9 +846,11 @@ function projectDefinitions(text, selection) {
     if (selected.has(key2)) return;
     const entry = byKey.get(key2);
     if (!entry) throw new PlanError(`Definition root/dependency missing: ${key2}`);
-    if (selection.mode === "upstream" && RELEASE_STEPS.has(entry.task.step)) throw new PlanError(`Upstream definitions cannot include generated release task: ${key2}`);
+    if (selection.mode === "upstream" && deploymentPurpose(entry.task) === "prod-execution") throw new PlanError(`Upstream definitions cannot include generated release task: ${key2}`);
     selected.add(key2);
     entry.task.dependsOn.forEach(visit);
+    const requirement = entry.task.scope?.deployment?.requirementRef;
+    if (requirement) visit(requirement.planKey);
   };
   roots.forEach(visit);
   const entries = line.filter(({ task }) => selected.has(task.planKey));
@@ -811,8 +885,11 @@ function projectDefinitions(text, selection) {
   SCHEMA_V1,
   SKILL_NAME,
   TASK_STATUSES,
+  deploymentPurpose,
+  deploymentRequirementIssue,
   detectSchema,
   parsePlan,
+  productionActionAllowed,
   projectDefinitions,
   skillNames,
   toolRefs,

package/runtime/vendor/plan-codec/index.d.cts

@@ -11,6 +11,7 @@ export interface PlanTask {
   step?: string; scope?: Record<string, unknown>; parameters?: unknown[]; expectedArtifacts?: string[]; allowedChanges?: string[]
   tools?: string[]; toolsOptional?: string[]; skills?: string[]; status: typeof TASK_STATUSES[number]; adoptedRev?: number
   blockedReason?: string; cancelReason?: string; result?: Record<string, unknown>; previousResult?: Record<string, unknown>
+  requirementConfirmation?: { rev: number; confirmedAt: string }
 }
 export interface PlanLane { name: string; state: 'enabled' | 'disabled'; reason?: string; skill?: string; steps?: { id: string; name: string }[] }
 export interface Plan {
@@ -30,3 +31,8 @@ export function projectDefinitions(text: string, selection: DefinitionSelection)
 export function skillNames(value: unknown, where: string): string[]
 export function toolRefs(value: unknown, where: string): string[]
 export function validateEvmContracts(plan: { flow?: string; lanes: Record<string, { skill?: string }>; tasks: Record<string, { planKey: string; step?: string; scope?: Record<string, unknown> }[]> }, fail: (message: string) => never): void
+
+export type DeploymentPurpose = 'analysis' | 'dev-execution' | 'prod-qualification' | 'prod-execution'
+export function deploymentPurpose(task: {step?: string; scope?: Record<string, unknown>}): DeploymentPurpose | undefined
+export function productionActionAllowed(task: {step?: string; scope?: Record<string, unknown>}, intent: string): boolean
+export function deploymentRequirementIssue(plan: { tasks: Record<string, {planKey:string;rev:number;status:string;step?:string;scope?:Record<string,unknown>;requirementConfirmation?:{rev:number;confirmedAt:string}}[]> }, task: Pick<PlanTask, 'step' | 'scope' | 'dependsOn'>): string | null

package/runtime/vendor/plan-codec/provenance.json

@@ -4,21 +4,22 @@
   "version": 1,
   "schema": "gateflow-plan/v2",
   "definitionContract": "gateflow-plan/definition@1",
-  "sourceCommit": "9b175e7906ca6735aeca92b50ce7cf716d980f17",
+  "sourceCommit": "ee0f90991ca1a94c3f58c8893df16d0c8c41b230",
+  "sourceMode": "working-tree",
   "sources": {
-    "builtin-skills/gateflow-plan/scripts/lib/evm-contract.mjs": "f7498feb2baeeed5022ab4e88e87c2567c786e7839249f5143fd565a5800bb13",
-    "builtin-skills/gateflow-plan/scripts/lib/handoff-v2.mjs": "185dc9fe11fd3d4bfb40a27175ddc27ed6f590d6427bf533d1f0d2aeda25d623",
-    "builtin-skills/gateflow-plan/scripts/lib/read-only.d.mts": "43cebba0e3d08ac5abb87cb34719e2d747aaa7cc8a6136eeccbc9f099758e490",
-    "builtin-skills/gateflow-plan/scripts/lib/read-only.mjs": "bb4b91d518fb9e12114ade0c251a3baba610516351a12fa5a9b501e93bb5f8ea",
+    "builtin-skills/gateflow-plan/scripts/lib/evm-contract.mjs": "c41dd9e6d630ea033001dd0922911bf365ff2baaa894107f6a80a3019eca1c17",
+    "builtin-skills/gateflow-plan/scripts/lib/handoff-v2.mjs": "05c89b794b65d6c73dc2427df8dc1b21f06c377c30f2c3baf8517459b8df56e0",
+    "builtin-skills/gateflow-plan/scripts/lib/read-only.d.mts": "716d1252adf79d5c7e6c3b7ed17984203ae3e1853695dc04fa9e769c9ac24c50",
+    "builtin-skills/gateflow-plan/scripts/lib/read-only.mjs": "1cb928d76ce14b07028efe002e624d91d36168494b5cc2cc0ba35153a311ff3e",
     "builtin-skills/gateflow-plan/scripts/lib/yaml-lite.mjs": "b53b8322b27bb73bbbf2a4254be4698ee43ec79c27828068954afd6d05902784",
-    "scripts/build-plan-codec.mjs": "d78243d5824bff60eb1a0d8cc5f86919bc9f585b9ece0824bf7e22c9653d874d"
+    "scripts/build-plan-codec.mjs": "048e647687da5a55a9f1899af510b9f1b0eb0872876e5eef278ede89c53c5d75"
   },
   "builder": {
     "name": "esbuild",
     "version": "0.21.5"
   },
   "artifacts": {
-    "index.cjs": "4c38b283bab25b7e906a961058bea87c7bcb0c103fefdace4cf46cb76c273adf",
-    "index.d.cts": "43cebba0e3d08ac5abb87cb34719e2d747aaa7cc8a6136eeccbc9f099758e490"
+    "index.cjs": "1014b59dad45b47510602791e426eaf2ee6d58720583670134fa14431b935d0d",
+    "index.d.cts": "716d1252adf79d5c7e6c3b7ed17984203ae3e1853695dc04fa9e769c9ac24c50"
   }
 }

package/runtime/workflow/lib/calls.ts

@@ -252,6 +252,7 @@ export const runContractWriteCalls = async (
         operation: 0,
         ...(zkSync ? { scheme: "zksync-eravm" as const, factoryDeps: [] } : {}),
       });
+      context.calldataReview?.record(planned, { abi: resolved.contract.interface.fragments, method: call.method, args });
       if (planned.executionAction === "replay") {
         context.reporter.result("execution", {
           stepId: planned.stepId,