gate-evm-tools 1.0.31 → 1.2.0

package/runtime/delivery/development.ts

@@ -6,8 +6,9 @@ import ts from 'typescript';
 import {existingCodeCoverage,requiredExistingAddresses} from './existing-code';
 import {yieldCompilerIo} from './compiler-io';
 import {openDeliveryConfiguration} from './configuration';
+import {aggregateInputHash} from './execution-identity';
 import {getCreate2Address} from 'ethers';
-import {artifactIdentity,BytecodeChecker,prepareEvmManifestCandidate,mergeEvmManifestCandidate,parseTargetManifest,hashStorageLayout,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
+import {TRANSPARENT_PROXY_ARTIFACT,verifyTransparentAdmin,artifactIdentity,BytecodeChecker,prepareEvmManifestCandidate,mergeEvmManifestCandidate,parseTargetManifest,hashStorageLayout,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
 import {canonicalData,canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
 import {typedValue,parseTypedValue} from '../workflow/lib/typedValue';
 import type {VerificationObservation,TypedValue} from '../workflow/lib/evidencePorts';
@@ -68,7 +69,7 @@ export function expectedDevelopmentAssertions(collection:Pick<DeliveryCollection
 export function mergeDevelopmentRegistration(input:{
  registry:unknown;metadata:unknown;base:{registry:ContractInfo;metadata:DeploymentInfo};
  target:string;deploymentId:string;executionId:string;recordPath:string;updatedAt:string;
- changes:readonly (DeploymentChange&{address:string;proxyKind?:'uups'})[];preparations:readonly PreparationEntry[];
+ changes:readonly (DeploymentChange&{address:string;proxyKind?:'uups'|'transparent'})[];preparations:readonly PreparationEntry[];
 }):{registry:ContractInfo;metadata:DeploymentInfo} {
  const {base,target}=input,registry=validateContractInfo(input.registry),metadata=validateDeploymentInfo(input.metadata);
  registry[target]??={};metadata.networks[target]??={};
@@ -78,14 +79,14 @@ export function mergeDevelopmentRegistration(input:{
   const previous=resolveDeployment(registry,target,c.instanceId);
   if(previous&&previous.key!==c.contractInfoKey){
    const entry=input.preparations.find(p=>p.stepId===c.stepId),request=entry?.prepared.request;
-   if(c.kind!=='upgrade'||c.proxyKind!=='uups'||entry?.change.kind!=='upgrade'||request?.kind!=='uups-upgrade'||entry.prepared.plan.kind!=='uups-upgrade'
+   if(c.kind!=='upgrade'||!['uups','transparent'].includes(c.proxyKind??'')||entry?.change.kind!=='upgrade'||!request||!(request.kind==='uups-upgrade'||request.kind==='transparent-upgrade')||entry.prepared.plan.kind!==request.kind
     ||entry.change.instanceId!==c.instanceId||entry.change.contractInfoKey!==c.contractInfoKey||entry.change.actualContract!==c.actualContract
     ||previous.address.toLowerCase()!==request.proxy.toLowerCase()||previous.address.toLowerCase()!==c.address.toLowerCase()||c.proxyAddress?.toLowerCase()!==request.proxy.toLowerCase())throw Error('Contract candidate key conflict');
    delete registry[target][previous.key];
   }
   if(previous&&previous.address.toLowerCase()!==c.address.toLowerCase()&&c.previousAddress?.toLowerCase()!==previous.address.toLowerCase())throw Error('Contract candidate address conflict');
   registry[target][c.contractInfoKey]=c.address;
-  metadata.networks[target][c.instanceId]={contractInfoKey:c.contractInfoKey,address:c.address,actualContract:c.actualContract,...(c.proxyKind?{proxyKind:c.proxyKind,implementationAddress:c.implementationAddress}:{}),source:{kind:'deployment',deploymentId:input.deploymentId,executionId:input.executionId,recordPath:input.recordPath},updatedAt:input.updatedAt};
+  metadata.networks[target][c.instanceId]={contractInfoKey:c.contractInfoKey,address:c.address,actualContract:c.actualContract,...(c.proxyKind?{proxyKind:c.proxyKind,implementationAddress:c.implementationAddress,...(c.proxyKind==='transparent'?{proxyAdminAddress:c.proxyAdminAddress,proxyAdminOwner:c.proxyAdminOwner}:{})}:{}),source:{kind:'deployment',deploymentId:input.deploymentId,executionId:input.executionId,recordPath:input.recordPath},updatedAt:input.updatedAt};
  }
  return {registry:validateContractInfo(registry),metadata:validateDeploymentInfo(metadata)};
 }
@@ -107,7 +108,7 @@ export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptio
  same(preparations.map(p=>({stepId:p.stepId,preparationHash:p.preparationHash,transactionIds:p.mappings.map(m=>m.transactionId),derivedKeys:p.derivedKeys})),plan.deploymentBindings,'Sealed preparation bindings');
  if(!plan.transactions.length)throw Error('Development acceptance requires actual transactions');
  const rows=aggregate.inputs.targets;
- const computed=semanticHash({version:1,business:aggregate.inputs.business,sourceDefinitions:aggregate.inputs.sourceDefinitions,runtime:aggregate.inputs.runtime,files:aggregate.inputs.files,targets:rows.map(row=>({target:row.target,configuration:row.configuration.configurationRuntimeHash,sourceConfiguration:row.sourceConfiguration.configurationRuntimeHash,compiler:row.compiler.stableDigest,custom:row.custom}))});
+ const computed=aggregateInputHash(aggregate);
  same(plan.deploymentId,aggregate.inputs.business.deploymentId,'Business deployment identity');same(computed,aggregate.inputsHash,'Aggregate input hash');same(plan.inputsHash,computed,'Plan inputs');same(plan.sourceDefinitionHash,aggregate.sourceDefinitionHash,'Plan source');same(semanticHash(aggregate.inputs.sourceDefinitions),aggregate.sourceDefinitionHash,'Source hash');
  const hre=options.hre,provider={request:(method:string,params:readonly unknown[])=>hre.network.provider.request({method,params:[...params]})};
  if(options.execution.context.finality.kind==='confirmations'&&BigInt(options.execution.context.finality.depth)<BigInt(Math.max(1,target.finality.confirmations)))throw Error('Development finality below configured policy');
@@ -160,6 +161,7 @@ export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptio
   if(preparations.length)return;
   const coverage=pureCoverage(),checker=new BytecodeChecker(hre,{},'evm');
   for(const row of coverage.expected){const code=await hre.ethers.provider.getCode(row.address),local=await checker.getLocalBytecode(row.contract);if(code==='0x'||!checker.compareBytecode(code,local.bytecode,local.abi,local.immutableReferences).matches)throw Error('Existing development code mismatch');}
+  for(const alias of coverage.aliases){const m=base.metadata.networks[plan.target]?.[alias];if(m?.proxyKind==='transparent'){if(!m.proxyAdminAddress||!m.proxyAdminOwner)throw Error('Missing frozen existing Transparent admin');await verifyTransparentAdmin({hre:hre as any,proxy:m.address,admin:m.proxyAdminAddress,owner:m.proxyAdminOwner});}}
   for(const m of coverage.manifests){if(byteHash(readInputBytes(root,m.file))!==m.hash)throw Error('Existing UUPS manifest changed');const storage=await provider.request('eth_getStorageAt',[m.proxy,'0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc','latest']);if(typeof storage!=='string'||storage.slice(-40).toLowerCase()!==m.implementation.slice(2))throw Error('Existing UUPS implementation changed');}
  }
  await assertArtifacts();await assertExistingCode();
@@ -183,16 +185,16 @@ export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptio
    for(const deployment of p.deployments){
     if(deployment.initCodeHash&&'factory' in r&&getCreate2Address(r.factory,deployment.salt,deployment.initCodeHash).toLowerCase()!==deployment.address.toLowerCase())throw Error('Prepared CREATE2 address mismatch');
     const code=await hre.ethers.provider.getCode(deployment.address);if(code==='0x')throw Error('Prepared deployment has no actual code');
-    const name=deployment.role==='proxy'?'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy':p.contract;
+    const name=deployment.role==='proxy'?(p.proxyKind==='transparent'?TRANSPARENT_PROXY_ARTIFACT:'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy'):p.contract;
     const local=await checker.getLocalBytecode(name),comparison=checker.compareBytecode(code,local.bytecode,local.abi,local.immutableReferences);if(!comparison.matches)throw Error(`Prepared deployed code mismatch: ${name}`);
    }
    const deployed=p.deployments.find(d=>d.role==='proxy')?.address??('proxy' in r?r.proxy:p.deployments.find(d=>d.role==='contract')?.address);
    if(!deployed)throw Error('Prepared deployment address missing');
-   const change={...entry.change,address:deployed,...(p.proxyKind==='uups'?{proxyAddress:deployed,proxyKind:'uups'}:{})};changes.set(change.instanceId,change);
+   const change={...entry.change,address:deployed,...(p.proxyKind?{proxyAddress:deployed,proxyKind:p.proxyKind}:{})};changes.set(change.instanceId,change);
   }
-  for(const change of changes.values())if(change.proxyKind==='uups'){
+  for(const change of changes.values())if(change.proxyKind==='uups'||change.proxyKind==='transparent'){
    const entry=[...preparations].reverse().find(p=>p.change.instanceId===change.instanceId)!;
-   const candidate=await prepareEvmManifestCandidate({root,scheme:'evm',network:plan.target,target:plan.target,proxy:change.address,contract:entry.prepared.plan.contract,constructorArgs:change.constructorArgs??[],skipTxHash:true,hre,compile:false});
+   const candidate=await prepareEvmManifestCandidate({root,scheme:'evm',network:plan.target,target:plan.target,proxy:change.address,proxyKind:change.proxyKind,proxyAdminAddress:change.proxyAdminAddress,proxyAdminOwner:change.proxyAdminOwner,contract:entry.prepared.plan.contract,constructorArgs:change.constructorArgs??[],skipTxHash:true,hre,compile:false});
    const expectedImplementation=entry.prepared.plan.deployments.find(d=>d.role==='implementation')?.address??change.implementationAddress;
    if(!expectedImplementation||candidate.implementation.toLowerCase()!==expectedImplementation.toLowerCase())throw Error('Final UUPS implementation mismatch');
    same(candidate.artifact,entry.prepared.plan.artifact,'UUPS artifact');change.implementationAddress=candidate.implementation;candidates.push(candidate);
@@ -225,7 +227,7 @@ export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptio
    }
    files.push(...manifests.values());return commitDevelopmentFilesLocked({root,executionId:plan.executionId,identity,files},options.onFileCommitted);
   });
-  for(const candidate of state.candidates){const manifest=parseTargetManifest(fs.readFileSync(candidate.paths.file)),entry=manifest.impls[candidate.versionKey];if(!entry||![entry.address,...(entry.allAddresses??[])].some(a=>a.toLowerCase()===candidate.implementation)||hashStorageLayout(entry.layout)!==candidate.layoutHash||!manifest.proxies.some(p=>p.address.toLowerCase()===candidate.proxy&&p.kind==='uups'))throw Error('Committed target manifest mismatch');}
+  for(const candidate of state.candidates){const manifest=parseTargetManifest(fs.readFileSync(candidate.paths.file)),entry=manifest.impls[candidate.versionKey];if(!entry||![entry.address,...(entry.allAddresses??[])].some(a=>a.toLowerCase()===candidate.implementation)||hashStorageLayout(entry.layout)!==candidate.layoutHash||!manifest.proxies.some(p=>p.address.toLowerCase()===candidate.proxy&&p.kind===candidate.proxyKind))throw Error('Committed target manifest mismatch');}
   return {journal:result,changes:state.changes,manifests:!preparations.length?pureCoverage().manifests:state.candidates.map(c=>({file:path.relative(root,c.paths.file),hash:byteHash(fs.readFileSync(c.paths.file)),layoutHash:c.layoutHash,proxy:c.proxy,implementation:c.implementation}))};
  }
  return Object.freeze({plan,
@@ -242,7 +244,7 @@ export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptio
    const assertions=await verifyBusiness(),finalized=result.snapshot.transactions.map(t=>t.observation!);
    const materialization=await materialize(finalized,assertions);
    const registry=fileBytes(root,'contractInfo.json')!,metadata=fileBytes(root,'deploymentInfo.json')!,effective:Record<string,Record<string,string>>={[plan.target]:{}},expectedCode:ExpectedDevelopmentCode[]=[];
-   for(const c of materialization.changes){effective[plan.target][c.contractInfoKey]=c.address;const alias=c.contractInfoKey.includes(':')?c.contractInfoKey.split(':')[0]:c.contractInfoKey;expectedCode.push({key:alias,contract:c.actualContract,address:c.implementationAddress??c.address});if(c.proxyKind==='uups')expectedCode.push({key:`${alias}_Proxy`,contract:'ERC1967Proxy',address:c.address});}
+   for(const c of materialization.changes){effective[plan.target][c.contractInfoKey]=c.address;const alias=c.contractInfoKey.includes(':')?c.contractInfoKey.split(':')[0]:c.contractInfoKey;expectedCode.push({key:alias,contract:c.actualContract,address:c.implementationAddress??c.address});if(c.proxyKind)expectedCode.push({key:`${alias}_Proxy`,contract:c.proxyKind==='transparent'?'TransparentUpgradeableProxy':'ERC1967Proxy',address:c.address});if(c.proxyKind==='transparent')expectedCode.push({key:`${alias}_ProxyAdmin`,contract:'ProxyAdmin',address:c.proxyAdminAddress});}
    if(!preparations.length){const coverage=pureCoverage();Object.assign(effective,coverage.effective);expectedCode.push(...coverage.expected);}
    const acceptancePath=`.gate-delivery/development/${plan.executionId}.acceptance.json`,priorAcceptance=fileBytes(root,acceptancePath);
    if(priorAcceptance!==null){

package/runtime/delivery/execution-identity.ts

@@ -0,0 +1,32 @@
+/** Environment labels are evidence; actual source, dependency and compiler inputs remain binding. */
+import type { RuntimeEvidence } from './configuration-runtime';
+import { parseCustomInputClosure, type CustomInputClosure } from './closure-format';
+import { semanticHash } from '../workflow/lib/canonicalData';
+import type { DeliveryAggregate } from './aggregate';
+
+export function runtimeExecutionInput(runtime: RuntimeEvidence): Omit<RuntimeEvidence, 'node'> {
+  const { node: _environment, ...inputs } = runtime;
+  return inputs;
+}
+
+export function compilerExecutionInput<T extends { node: string; platform: string; arch: string; abi: string }>(toolchain: T): Omit<T, 'node' | 'platform' | 'arch' | 'abi'> {
+  const { node: _node, platform: _platform, arch: _arch, abi: _abi, ...inputs } = toolchain;
+  return inputs;
+}
+
+/** Only resolver version and its derived exact hash are omitted; all actual edges/emitted bytes stay. */
+export function customExecutionInput(raw: CustomInputClosure | null): unknown {
+  if (raw === null) return null;
+  const { closureHash: _exactHash, resolver, ...inputs } = parseCustomInputClosure(raw);
+  const { version: _nodeVersion, ...policy } = resolver;
+  return { ...inputs, resolver: policy };
+}
+
+/** Collection, dev execution and historical validation share the same preimage. */
+export function aggregateInputHash(a: Pick<DeliveryAggregate, 'inputs'>): string {
+  return semanticHash({ version: 1, business: a.inputs.business, sourceDefinitions: a.inputs.sourceDefinitions,
+    runtime: runtimeExecutionInput(a.inputs.runtime), files: a.inputs.files,
+    targets: a.inputs.targets.map(row => ({ target: row.target, configuration: row.configuration.configurationRuntimeHash,
+      sourceConfiguration: row.sourceConfiguration.configurationRuntimeHash, compiler: row.compiler.stableDigest,
+      custom: customExecutionInput(row.custom) })) });
+}

package/runtime/delivery/existing-code.ts

@@ -1,5 +1,5 @@
 /** Pure-call coverage from the accepted registration and owned compiler witness. No deployments are invented. */
-import {artifactIdentity,parseTargetManifest,hashStorageLayout} from 'gate-evm-tools/workflow';
+import {TRANSPARENT_PROXY_ARTIFACT,PROXY_ADMIN_ARTIFACT,transparentAdminAddress,artifactIdentity,parseTargetManifest,hashStorageLayout} from 'gate-evm-tools/workflow';
 import {canonicalJson,semanticHash} from '../workflow/lib/canonicalData';
 import {validateContractInfo} from '../workflow/lib/deployments';
 import {validateDeploymentInfo} from '../workflow/lib/deploymentInfo';
@@ -26,10 +26,11 @@ export function existingCodeCoverage(input:{target:string;addresses:string[];reg
   const [key]=matches[0],alias=key.split(':')[0],m=metadata[alias],contract=m?.actualContract??key.split(':').at(-1)!;
   if(m&&(m.contractInfoKey!==key||m.address.toLowerCase()!==address))throw Error('Existing code metadata registration mismatch');
   aliases.push(alias);effective[input.target][key]=address;
-  if(m?.proxyKind&&m.proxyKind!=='uups')throw Error('Unsupported existing proxy kind');
-  if(m?.proxyKind==='uups'){
-   const implementation=m.implementationAddress!.toLowerCase();add(alias,contract,implementation);add(`${alias}_Proxy`,'ERC1967Proxy',address);
-   const owned=input.manifests.flatMap(file=>{const manifest=parseTargetManifest(Buffer.from(file.contents));const proxies=manifest.proxies.filter(p=>p.address.toLowerCase()===address),impls=Object.entries(manifest.impls).filter(([,v])=>v&&[v.address,...(v.allAddresses??[])].some(a=>a.toLowerCase()===implementation));return proxies.length===1&&proxies[0].kind==='uups'&&impls.length===1?[{file:file.path,hash:byteHash(file.contents),layoutHash:hashStorageLayout(impls[0][1]!.layout),proxy:address,implementation}]:[];});
+  if(m?.proxyKind&&m.proxyKind!=='uups'&&m.proxyKind!=='transparent')throw Error('Unsupported existing proxy kind');
+  if(m?.proxyKind==='uups'||m?.proxyKind==='transparent'){
+   const implementation=m.implementationAddress!.toLowerCase();add(alias,contract,implementation);add(`${alias}_Proxy`,m.proxyKind==='transparent'?TRANSPARENT_PROXY_ARTIFACT:'ERC1967Proxy',address);
+   if(m.proxyKind==='transparent'){if(m.proxyAdminAddress?.toLowerCase()!==transparentAdminAddress(address)||!m.proxyAdminOwner)throw Error('Missing existing Transparent admin identity');add(`${alias}_ProxyAdmin`,PROXY_ADMIN_ARTIFACT,m.proxyAdminAddress);}
+   const owned=input.manifests.flatMap(file=>{const manifest=parseTargetManifest(Buffer.from(file.contents));const proxies=manifest.proxies.filter(p=>p.address.toLowerCase()===address),impls=Object.entries(manifest.impls).filter(([,v])=>v&&[v.address,...(v.allAddresses??[])].some(a=>a.toLowerCase()===implementation));return proxies.length===1&&proxies[0].kind===m.proxyKind&&impls.length===1?[{file:file.path,hash:byteHash(file.contents),layoutHash:hashStorageLayout(impls[0][1]!.layout),proxy:address,implementation}]:[];});
    if(owned.length!==1)throw Error('Missing unique sealed existing UUPS manifest');manifests.push(owned[0]);
   }else add(alias,contract,address);
  }
@@ -39,6 +40,6 @@ export function existingCodeCoverage(input:{target:string;addresses:string[];reg
 /** Called only by the owned worker while the actual compiler artifact reader is installed. */
 export async function collectExistingCodeArtifacts(input:{target:string;addresses:string[];registry:unknown;metadata:unknown;readArtifact(name:string):Promise<unknown>}){
  const registry=validateContractInfo(input.registry)[input.target]??{},metadata=validateDeploymentInfo(input.metadata).networks[input.target]??{},names=new Set<string>();
- for(const address of new Set(input.addresses.map(a=>a.toLowerCase()))){const entries=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(entries.length!==1)throw Error('Existing code target requires unique frozen registration');const [key]=entries[0],m=metadata[key.split(':')[0]];names.add(m?.actualContract??key.split(':').at(-1)!);if(m?.proxyKind==='uups')names.add('@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy');}
+ for(const address of new Set(input.addresses.map(a=>a.toLowerCase()))){const entries=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(entries.length!==1)throw Error('Existing code target requires unique frozen registration');const [key]=entries[0],m=metadata[key.split(':')[0]];names.add(m?.actualContract??key.split(':').at(-1)!);if(m?.proxyKind==='uups'||m?.proxyKind==='transparent'){names.add(m.proxyKind==='transparent'?TRANSPARENT_PROXY_ARTIFACT:'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy');if(m.proxyKind==='transparent')names.add(PROXY_ADMIN_ARTIFACT);}}
  for(const name of names)await input.readArtifact(name);
 }

package/runtime/delivery/inputs.ts

@@ -11,6 +11,8 @@ import { resolveDeliveryParameters, consumeDeliveryParameters, type ResolvedDeli
 import { validateDeploySaveAs, type WorkflowStep } from '../workflow/lib/parameters';
 import { canonicalJson, deepFreeze, semanticHash, exactObject, nonempty } from '../workflow/lib/canonicalData';
 import type { DeepReadonly } from './source';
+import { parseDeploymentRequirementRef } from './task-identity';
+import { resolveParameterTargets } from './parameter-defaults';
 
 export interface DeliveryInputOptions {
   workspaceRoot: string;
@@ -83,20 +85,29 @@ export function openDeliveryInputs(raw: DeliveryInputOptions): DeliveryInputHand
     files.push({ path: relative, digest: inputDigest(bytes) });
     return parseInputDocument(bytes, format);
   };
-  const task = exactObject(read('task.yaml', 'yaml'), ['version', 'id', 'developmentNetwork', 'releaseTargetNetworks'], 'task.yaml');
+  const task = object(read('task.yaml', 'yaml'), 'task.yaml', ['version', 'id', 'developmentNetwork', 'releaseTargetNetworks', 'requirementRef', 'productionRequirementRef', 'referenceDeploymentId']);
   if (task.version !== 1 || task.id !== deploymentId) throw new Error('Task version/deployment identity mismatch');
+  same(parseDeploymentRequirementRef(task.requirementRef), scope.requirementRef, 'Task requirementRef');
+  same(task.referenceDeploymentId ?? null, scope.referenceDeploymentId ?? null, 'Task referenceDeploymentId');
   same(task.developmentNetwork, scope.developmentNetwork, 'Task developmentNetwork');
-  same(task.releaseTargetNetworks, scope.releaseTargetNetworks, 'Task releaseTargetNetworks');
+  const release = task.releaseTargetNetworks as string[];
+  if (!Array.isArray(release) || new Set(release).size !== release.length) throw Error('Invalid task releaseTargetNetworks');
+  for (const network of release) if(typeof network !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(network) || ['__proto__','prototype','constructor'].includes(network)) throw Error('Invalid release target');
+  if (input.request.environment === 'dev') {
+    if (!(scope.releaseTargetNetworks as string[]).every(network => release.includes(network))) throw Error('Task removed a development-declared release target');
+  } else {
+    same(release, scope.releaseTargetNetworks, 'Task releaseTargetNetworks');
+    same(task.productionRequirementRef === undefined ? null : parseDeploymentRequirementRef(task.productionRequirementRef), scope.productionRequirementRef ?? null, 'Task productionRequirementRef');
+  }
   const manifest = object(read('manifest.yaml', 'yaml'), 'manifest.yaml', ['id', 'description', 'steps']);
   if (manifest.id !== deploymentId) throw new Error('Manifest deployment identity mismatch');
   if (manifest.description !== undefined) nonempty(manifest.description, 'manifest description');
   const steps = parseSteps(manifest.steps);
   const schema = object(read('parameters.schema.json', 'json'), 'parameters schema');
-  const values = exactObject(read('parameters.yaml', 'yaml'), ['params'], 'parameters.yaml');
-  const params = object(values.params, 'target parameters');
-  const provenance = exactObject(read('parameters.provenance.json', 'json'), ['version', 'producers', 'targets'], 'parameters provenance');
-  if (provenance.version !== 1) throw new Error('Unsupported provenance version');
-  const definitions = object(provenance.producers, 'producers'), observations = object(provenance.targets, 'provenance targets');
+  const dev = scope.developmentNetwork as string;
+  const all = [dev, ...release];
+  const { params, observations, definitions } = resolveParameterTargets(
+    read('parameters.yaml', 'yaml'), read('parameters.provenance.json', 'json'), all);
   for (const [id, raw] of Object.entries(definitions)) {
     safeId(id, 'producer ID');
     const definition = exactObject(raw, ['version', 'module'], 'producer');
@@ -104,10 +115,6 @@ export function openDeliveryInputs(raw: DeliveryInputOptions): DeliveryInputHand
     const module = portablePath(definition.module, 'producer module');
     if (!module.startsWith(`${businessRoot}/`)) throw new Error('Producer module is outside deployment business root');
   }
-  const dev = scope.developmentNetwork as string, release = scope.releaseTargetNetworks as string[];
-  const all = [dev, ...release];
-  for (const name of [...Object.keys(params), ...Object.keys(observations)]) if (!all.includes(name)) throw new Error('Unknown parameter target');
-  for (const value of Object.values(observations)) exactObject(value, ['manual', 'computed'], 'target provenance');
   const selected = input.selection === 'development' ? [dev] : input.selection === 'release' ? release : all;
   // Both the digest and every public projection use these exact buffers. Reopening
   // for projection would permit an A→B→A edit to bind B's values to A's digest.

package/runtime/delivery/journal.ts

@@ -14,7 +14,7 @@ import type { DerivedBindings } from './bindings';
 import { matchesSameForkInitial, sameForkBaselineDigest } from './same-fork-baseline';
 export interface PreparationEntry extends PreparationInput { requestHash: string; gateToolPlanHash: string; mappings: PreparationMapping[]; preparationHash: string }
 export interface JournalIdentity { target: string; chainId: string; expectedStepIds: readonly string[] }
-const addressKeys = ['address', 'proxyAddress', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'factory', 'multicall', 'expectedAddress', 'predictedAddress', 'previousAddress'];
+const addressKeys = ['address', 'proxyAddress', 'proxyAdminAddress', 'proxyAdminOwner', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'factory', 'multicall', 'expectedAddress', 'predictedAddress', 'previousAddress'];
 const stringKeys = ['stepId', 'instanceId', 'actualContract', 'contractInfoKey', 'strategy', 'proxyKind', 'implementationSalt', 'salt', 'redeployReason'];
 // Prepared changes cannot carry runtime reuse observations, receipts, candidate lifecycle, sync or success markers.
 const changeKeys = [...addressKeys, ...stringKeys, 'kind', 'constructorArgs', 'leadingZeroBytes', 'gateTool'];
@@ -42,10 +42,10 @@ function normalizeInput(raw: unknown, identity: JournalIdentity): PreparationInp
   if (!requestPath.endsWith(`/${stepId}-request.json`) || !planPath.endsWith(`/${stepId}-plan.json`)) throw new Error('Preparation step/ref mismatch');
   if (request.scheme !== 'evm' || plan.scheme !== 'evm') throw new Error('Delivery preparation must use EVM');
   if (plan.requestHash !== hashPreparationRequest(request) || plan.kind !== request.kind || plan.network !== request.network || plan.target !== request.target || plan.contract !== request.contract || plan.target !== identity.target || plan.chainId !== identity.chainId) throw new Error('Preparation request/plan identity mismatch');
-  if (change.stepId !== stepId || (change.kind === 'upgrade') !== (plan.kind === 'uups-upgrade') || change.actualContract !== plan.artifact.contractName || (plan.contract.includes(':') && plan.contract !== `${plan.artifact.sourceName}:${plan.artifact.contractName}`)) throw new Error('Preparation change/step/artifact identity mismatch');
+  if (change.stepId !== stepId || (change.kind === 'upgrade') !== (plan.kind === 'uups-upgrade' || plan.kind === 'transparent-upgrade') || change.actualContract !== plan.artifact.contractName || (plan.contract.includes(':') && plan.contract !== `${plan.artifact.sourceName}:${plan.artifact.contractName}`)) throw new Error('Preparation change/step/artifact identity mismatch');
   if (canonicalJson(plan.transactions.map(t => t.purpose)) !== canonicalJson(expectedTransactionPurposes(plan))) throw new Error('Preparation transaction purposes/order mismatch');
   if (!sameAddress(change.factory, request.factory) || change.contractInfoKey !== contractInfoKey(change.instanceId, change.actualContract)) throw new Error('Prepared factory/registry identity mismatch');
-  if (change.strategy !== (plan.kind === 'uups-upgrade' ? 'gate-tool' : 'create2')) throw new Error('Invalid prepared strategy');
+  if (change.strategy !== ((plan.kind === 'uups-upgrade' || plan.kind === 'transparent-upgrade') ? 'gate-tool' : 'create2')) throw new Error('Invalid prepared strategy');
   const role = (name: string) => { const matches = plan.deployments.filter(d => d.role === name); if (matches.length !== 1) throw new Error(`Missing/duplicate preparation ${name}`); return matches[0]; };
   const optionalAddress = (key: keyof DeploymentChange, expected: string) => {
     if (Object.hasOwn(change, key) && !sameAddress(change[key], expected)) throw new Error(`Prepared ${key} does not match its canonical address`);
@@ -61,17 +61,21 @@ function normalizeInput(raw: unknown, identity: JournalIdentity): PreparationInp
   if (Object.hasOwn(change, 'constructorArgs') && canonicalJson(change.constructorArgs) !== canonicalJson(request.constructorArgs)) throw new Error('Prepared constructorArgs differ from canonical request');
   if (request.kind === 'create2-deploy') {
     const deployment = role('contract');
-    rejectFields('proxyAddress', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'implementationSalt');
+    rejectFields('proxyAddress', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'implementationSalt', 'proxyAdminAddress', 'proxyAdminOwner');
     if (change.proxyKind !== undefined || deployment.salt !== request.salt || change.salt !== request.salt || !sameAddress(change.predictedAddress, deployment.address)) throw new Error('Prepared CREATE2 request/deployment mismatch');
     optionalAddress('address', deployment.address);
     deploymentPolicy(request.addressPolicy, deployment.address);
   } else {
     const implementation = role('implementation');
-    if (change.proxyKind !== 'uups' || !sameAddress(change.implementationAddress, implementation.address) || implementation.salt !== request.implementationSalt) throw new Error('Prepared implementation mismatch');
+    if (change.proxyKind !== request.proxyKind || !sameAddress(change.implementationAddress, implementation.address) || implementation.salt !== request.implementationSalt) throw new Error('Prepared implementation mismatch');
     optionalAddress('preparedImplementationAddress', implementation.address);
-    if (request.kind === 'uups-placeholder-deploy') {
+    if(request.proxyKind==='transparent'){
+      if(!sameAddress(change.proxyAdminAddress,plan.proxyAdmin?.address)||!sameAddress(change.proxyAdminOwner,request.proxyAdminOwner)||!sameAddress(plan.proxyAdmin?.owner,request.proxyAdminOwner))throw Error('Prepared Transparent ProxyAdmin mismatch');
+    }else rejectFields('proxyAdminAddress','proxyAdminOwner');
+    if (request.kind === 'uups-placeholder-deploy' || request.kind === 'transparent-deploy') {
       const proxy = role('proxy');
-      if (proxy.salt !== request.proxySalt || change.salt !== request.proxySalt || !sameAddress(change.predictedAddress, proxy.address) || !sameAddress(change.placeholderImplementationAddress, request.placeholderImplementation)) throw new Error('Prepared proxy mismatch');
+      if (proxy.salt !== request.proxySalt || change.salt !== request.proxySalt || !sameAddress(change.predictedAddress, proxy.address) || (request.kind==='uups-placeholder-deploy'&&!sameAddress(change.placeholderImplementationAddress, request.placeholderImplementation))) throw new Error('Prepared proxy mismatch');
+      if(request.kind==='transparent-deploy')rejectFields('placeholderImplementationAddress');
       optionalAddress('address', proxy.address);
       optionalAddress('proxyAddress', proxy.address);
       deploymentPolicy(request.proxyAddressPolicy, proxy.address);
@@ -132,9 +136,9 @@ export function parsePreparationJournal(raw: unknown, transactions: readonly Rel
   if (canonicalJson(entries.map(e => e.stepId)) !== canonicalJson(identity.expectedStepIds)) throw new Error('missing, extra or duplicate preparation steps');
   for (const [index, entry] of entries.entries()) {
     const {request,plan} = entry.prepared;
-    if (request.kind === 'uups-upgrade' && plan.validation.kind === 'uups-upgrade' && plan.validation.sameForkBaselineDigest !== undefined) {
+    if ((request.kind === 'uups-upgrade' || request.kind === 'transparent-upgrade') && (plan.validation.kind === 'uups-upgrade' || plan.validation.kind === 'transparent-upgrade') && plan.validation.sameForkBaselineDigest !== undefined) {
       const validation = plan.validation;
-      const prior = entries.slice(0,index).filter(e => matchesSameForkInitial(e.prepared,request.target,plan.chainId,request.proxy,validation.currentImplementation));
+      const prior = entries.slice(0,index).filter(e => matchesSameForkInitial(e.prepared,request.target,plan.chainId,request.proxy,validation.currentImplementation,request.proxyKind));
       if (prior.length !== 1 || sameForkBaselineDigest(prior[0].prepared,validation.oldLayoutHash) !== validation.sameForkBaselineDigest) throw new Error('Same-fork upgrade requires its exact prior initial preparation');
     }
   }
@@ -189,7 +193,7 @@ export class PreparationJournal implements PreparationSink {
   assertUpgradeBaseline(proxy: string): boolean {
     const matches = this.inputs.filter(i => matchesSameForkInitial(i.prepared,this.identity.target,this.identity.chainId,proxy));
     if (!matches.length) return false;
-    if (matches.length !== 1 || !this.qualifiedSameFork?.(matches[0].prepared)) throw new Error('Same-fork UUPS upgrade requires a complete validated immutable OZ layout baseline; unsupported without that evidence');
+    if (matches.length !== 1 || !this.qualifiedSameFork?.(matches[0].prepared)) throw new Error('Same-fork proxy upgrade requires a complete validated immutable OZ layout baseline; unsupported without that evidence');
     return true;
   }
   seal(transactions: readonly ReleaseExecutionTransaction[], derived: DerivedBindings): PreparationEntry[] {

package/runtime/delivery/parameter-defaults.ts

@@ -0,0 +1,75 @@
+/** Expand task-owned defaults before schema/provenance validation. Never a production override port. */
+import { ownPath, pointerPart } from './data';
+import { object } from './protocol';
+import { canonicalJson, exactObject } from '../workflow/lib/canonicalData';
+
+type Observations = { manual: Record<string, unknown>; computed: Record<string, unknown> };
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+function observations(raw: unknown): Observations {
+  const value = exactObject(raw, ['manual', 'computed'], 'target provenance');
+  return { manual: object(value.manual, 'manual observations'), computed: object(value.computed, 'computed observations') };
+}
+function leaves(value: unknown, path = '', result = new Map<string, unknown>()): Map<string, unknown> {
+  const entries = value !== null && typeof value === 'object' ? Object.entries(value) : [];
+  if (!entries.length) result.set(path, value);
+  else for (const [key, child] of entries) leaves(child, `${path}/${pointerPart(key)}`, result);
+  return result;
+}
+function merge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries([...new Set([...Object.keys(base), ...Object.keys(override)])].map(key => [key,
+    !Object.hasOwn(override, key) ? base[key]
+      : Object.hasOwn(base, key) && record(base[key]) && record(override[key]) ? merge(base[key], override[key])
+        : override[key],
+  ]));
+}
+/** Only leaves actually inherited from defaults may inherit default observations. Arrays replace as a unit. */
+function inheritedLeaves(base: unknown, override: unknown, path = '', result = new Set<string>()): Set<string> {
+  if (!record(base) || !record(override)) return result;
+  for (const [key, value] of Object.entries(base)) {
+    const child = `${path}/${pointerPart(key)}`;
+    if (!Object.hasOwn(override, key)) for (const pointer of leaves(value, child).keys()) result.add(pointer);
+    else if (record(value) && record(override[key])) inheritedLeaves(value, override[key], child, result);
+  }
+  // The empty root/container is itself a schema leaf.
+  if (!Object.keys(base).length && !Object.keys(override).length) result.add(path);
+  return result;
+}
+
+export function resolveParameterTargets(rawValues: unknown, rawProvenance: unknown, networks: readonly string[]): {
+  params: Record<string, unknown>; observations: Record<string, Observations>; definitions: Record<string, unknown>;
+} {
+  const values = object(rawValues, 'parameters.yaml', ['defaults', 'params']);
+  const params = object(ownPath(values, ['params'], 'target parameters'), 'target parameters');
+  const provenance = object(rawProvenance, 'parameters provenance', ['version', 'producers', 'defaults', 'targets']);
+  if (provenance.version !== 1) throw new Error('Unsupported provenance version');
+  const definitions = object(provenance.producers, 'producers'), targets = object(provenance.targets, 'provenance targets');
+  for (const name of [...Object.keys(params), ...Object.keys(targets)])
+    if (!networks.includes(name)) throw new Error('Unknown parameter target');
+  const observed = Object.fromEntries(Object.entries(targets).map(([name, value]) => [name, observations(value)]));
+  if (!Object.hasOwn(values, 'defaults')) {
+    if (Object.hasOwn(provenance, 'defaults')) throw new Error('Default provenance requires parameter defaults');
+    return { params, observations: observed, definitions };
+  }
+  const defaults = object(values.defaults, 'parameter defaults');
+  const shared = Object.hasOwn(provenance, 'defaults') ? observations(provenance.defaults) : { manual: {}, computed: {} };
+  const defaultLeaves = leaves(defaults);
+  for (const kind of ['manual', 'computed'] as const) for (const [path, raw] of Object.entries(shared[kind])) {
+    if (!defaultLeaves.has(path)) throw new Error(`Unused default parameter observation at ${path}`);
+    const observation = exactObject(raw, kind === 'manual' ? ['source', 'value'] : ['producer', 'version', 'inputs', 'output'], 'default observation');
+    if (canonicalJson(observation[kind === 'manual' ? 'value' : 'output']) !== canonicalJson(defaultLeaves.get(path)))
+      throw new Error(`Default observation mismatch at ${path}`);
+  }
+  const effective = Object.fromEntries(networks.map(name => {
+    const override = Object.hasOwn(params, name) ? object(params[name], 'network parameter overrides') : {};
+    return [name, merge(defaults, override)];
+  }));
+  const effectiveObservations = Object.fromEntries(networks.map(name => {
+    const override = Object.hasOwn(params, name) ? params[name] : {};
+    const inherited = inheritedLeaves(defaults, override), local = Object.hasOwn(observed, name) ? observed[name] : { manual: {}, computed: {} };
+    return [name, Object.fromEntries((['manual', 'computed'] as const).map(kind => [kind, {
+      ...Object.fromEntries(Object.entries(shared[kind]).filter(([path]) => inherited.has(path))), ...local[kind],
+    }])) as Observations];
+  }));
+  return { params: effective, observations: effectiveObservations, definitions };
+}

package/runtime/delivery/parameters.ts

@@ -324,6 +324,24 @@ export function resolveDeliveryParameters(
   const body = { version: 1 as const, ...input, provenance };
   return deepFreeze({ ...body, identity: semanticHash(body) });
 }
+/** Read-only migration check, never a producer receipt or production authority. */
+export function validateHistoricalParameterExtension(previous: ResolvedDeliveryParameters, current: ParameterInputs): ResolvedDeliveryParameters {
+  consumeDeliveryParameters(previous, previous.identity);
+  const input = strictData({schema: current.schema, target: current.target, values: current.values,
+    sources: current.sources ?? {}, manual: current.manual ?? {}, computed: current.computed ?? {}});
+  if (input.target !== previous.target) throw Error('Historical parameter target changed');
+  // A historical consumer cannot rerun or grant authority to a newly introduced producer.
+  for (const [pointer, observation] of Object.entries(input.computed)) {
+    if (canonicalJson(observation) !== canonicalJson(previous.computed[pointer] ?? null)) throw Error('Historical computed parameter changed; new development acceptance required');
+  }
+  const provenance = attest(input);
+  for (const leaf of previous.provenance) {
+    const next = provenance.find(candidate => candidate.path === leaf.path);
+    if (!next || canonicalJson(next) !== canonicalJson(leaf)) throw Error(`Historical parameter value/provenance changed: ${leaf.path}`);
+  }
+  const body = {version: 1 as const, ...input, provenance};
+  return deepFreeze({...body, identity: semanticHash(body)});
+}
 /** Consume a previously trusted identity; no fill-in, override, or producer invocation. */
 export function consumeDeliveryParameters(
   raw: ResolvedDeliveryParameters,

package/runtime/delivery/planning.ts

@@ -1,4 +1,6 @@
 import { yieldCompilerIo } from './compiler-io';
+import { createCalldataInvocation, reviewTransaction, parseCalldataReviews, type CalldataTransactionReview } from './calldata-review';
+import { preparationCalldataReviews } from './calldata-preparations';
 import {assertOwnedTargetWorker} from './aggregate-bootstrap';
 import type { ReferenceObservation } from "./references";
 import { createDeliveryValidation } from "./validation";
@@ -67,6 +69,7 @@ export interface DeliveryRuntimeEvidence {
 }
 export interface DeliveryCollection {
   plan: DeliveryPlan;
+  calldata: CalldataTransactionReview[];
   preparations: PreparationEntry[];
   verification: VerificationObservation[];
   runtimeEvidence: DeliveryRuntimeEvidence;
@@ -95,14 +98,14 @@ export interface DeliveryPlanningOptions {
   identities: PlanningIdentityPort;
   steps: readonly WorkflowStep[];
   derivationSeed: string;
-  expected?: Pick<DeliveryCollection, "plan" | "preparations" | "verification">;
+  expected?: Pick<DeliveryCollection, "plan" | "preparations" | "verification"> & Partial<Pick<DeliveryCollection, 'calldata'>>;
   completedTransactions?: CompletedExecutionTransaction[];
   customSession?: CustomPlanningInputSession;
 }
 export interface StagedDeliveryCollection {
   readonly payload: Omit<DeliveryPlanBody,'inputsHash'>;
   readonly invariantHash:string;
-  readonly snapshot: {payload:Omit<DeliveryPlanBody,'inputsHash'>;preparations:PreparationEntry[];verification:VerificationObservation[];runtimeEvidence:Omit<DeliveryRuntimeEvidence,'forkAudit'>&{forkAudit:Omit<ForkAuditEvidence,'planHash'|'evidenceHash'>}};
+  readonly snapshot: {payload:Omit<DeliveryPlanBody,'inputsHash'>;calldata:CalldataTransactionReview[];preparations:PreparationEntry[];verification:VerificationObservation[];runtimeEvidence:Omit<DeliveryRuntimeEvidence,'forkAudit'>&{forkAudit:Omit<ForkAuditEvidence,'planHash'|'evidenceHash'>}};
   assertUnchanged(): Promise<void>;
   bind(inputsHash:string): DeliveryCollection;
   close():void;
@@ -224,6 +227,7 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
     });
     const verification = new VerificationJournal([]);
     const pendingObservations: DeliveryRuntimeEvidence["pendingUupsReuse"] = [];
+    const callReviews = new Map<string, CalldataTransactionReview>();
     const operationIds = new DeliveryOperationIdentities();
     const references: DeliveryRuntimeEvidence["references"] = [];
     const customBindings: CustomEvidence[] = [],
@@ -249,6 +253,10 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
       bindings,
       preparations,
       verification,
+      calldataReview: { record(tx, intent) {
+        if (callReviews.has(tx.transactionId)) throw Error('Duplicate calldata ABI intent');
+        callReviews.set(tx.transactionId, reviewTransaction(tx, createCalldataInvocation({ ...intent, data: tx.data })));
+      } },
       executionPlanner: planner,
       transactionIdentity: operationIds,
       transactionObserver: audit,
@@ -326,6 +334,12 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
       derivedBindings = bindings.seal();
     const prepared = preparations.seal(transactions, derivedBindings),
       observations = verification.seal();
+    for (const review of await preparationCalldataReviews(prepared, transactions, context.runtime.hre.artifacts)) {
+      if (callReviews.has(review.transactionId)) throw Error('Duplicate calldata preparation intent');
+      callReviews.set(review.transactionId, review);
+    }
+    const calldata = parseCalldataReviews(transactions.map(tx => callReviews.get(tx.transactionId)), transactions);
+    if (input.expected?.calldata && canonicalJson(parseCalldataReviews(input.expected.calldata, transactions)) !== canonicalJson(calldata)) throw Error('Replayed calldata ABI intent differs');
     const {inputsHash:knownHash,...base}=header;
     const payload = deepFreeze({
       ...base,
@@ -359,7 +373,7 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
       throw new Error("Replayed verification evidence differs");
     session?.closeReads();
     const interval=await audit.capture({transactions,completedTransactions:input.completedTransactions??[]});
-    const stagedSnapshot=deepFreeze({payload,preparations:prepared,verification:observations,runtimeEvidence:{pendingUupsReuse:pendingObservations,forkAudit:interval.snapshot,references}});
+    const stagedSnapshot=deepFreeze({payload,calldata,preparations:prepared,verification:observations,runtimeEvidence:{pendingUupsReuse:pendingObservations,forkAudit:interval.snapshot,references}});
     const invariantHash=semanticHash(stagedSnapshot);
     let state:'staged'|'bound'|'failed'|'closed'='staged';
     const open=()=>{if(state!=='staged')throw new Error('Staged collection closed or already bound');};
@@ -368,7 +382,7 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
       const plan=sealDeliveryPlan({...payload,inputsHash});
       if(expected&&plan.planHash!==expected.planHash)throw new Error('Replayed delivery plan differs from expected plan');
       const forkAudit=interval.bind(plan.planHash);
-      const result=deepFreeze(canonicalData({plan,preparations:prepared,verification:observations,
+      const result=deepFreeze(canonicalData({plan,calldata,preparations:prepared,verification:observations,
         runtimeEvidence:{pendingUupsReuse:pendingObservations,forkAudit,references}}) as unknown as DeliveryCollection);
       if(collectionInvariantHash(result)!==invariantHash)throw new Error('Binding changed staged collection payload');
       state='bound';return result;
@@ -393,5 +407,5 @@ async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promi
 export function collectionInvariantHash(collection:DeliveryCollection):string {
   const {inputsHash:_,planHash:__,...payload}=collection.plan;
   const {planHash:___,evidenceHash:____,...forkAudit}=collection.runtimeEvidence.forkAudit;
-  return semanticHash({payload,preparations:collection.preparations,verification:collection.verification,runtimeEvidence:{...collection.runtimeEvidence,forkAudit}});
+  return semanticHash({payload,calldata:collection.calldata,preparations:collection.preparations,verification:collection.verification,runtimeEvidence:{...collection.runtimeEvidence,forkAudit}});
 }

package/runtime/delivery/preparation.ts

@@ -2,6 +2,7 @@
 import { Interface, concat, getCreate2Address } from "ethers";
 import {
   artifactIdentity,
+  TRANSPARENT_PROXY_ARTIFACT, PROXY_ADMIN_ARTIFACT, PROXY_ADMIN_INTERFACE, transparentAdminAddress,
   type GateToolArtifact,
   type GateToolPreparationPlanV1,
   type GateToolPreparationRequestV1,
@@ -173,10 +174,24 @@ export async function validatePreparationSemantics(
       artifact,
       request.constructorArgs,
       request.implementationSalt,
-      request.kind === "uups-upgrade"
+      (request.kind === "uups-upgrade" || request.kind === "transparent-upgrade")
         ? request.implementationAddressPolicy
         : undefined,
     );
+    if(request.kind === 'transparent-deploy' || request.kind === 'transparent-upgrade'){
+      if(request.call)validateAbiArguments(artifact.abi,request.call.method,request.call.args);
+      const data=request.call?new Interface(artifact.abi).encodeFunctionData(request.call.method,request.call.args):'0x';
+      await read(PROXY_ADMIN_ARTIFACT);
+      const proxy=request.kind==='transparent-deploy'
+        ?role('proxy',deliveryArtifact(await read(TRANSPARENT_PROXY_ARTIFACT)),[implementation,request.proxyAdminOwner,data],request.proxySalt,request.proxyAddressPolicy)
+        :request.proxy.toLowerCase();
+      const admin=transparentAdminAddress(proxy);
+      if(plan.proxyKind!=='transparent'||plan.proxyAdmin?.address!==admin||plan.proxyAdmin?.owner!==request.proxyAdminOwner.toLowerCase()
+        ||(request.kind==='transparent-upgrade'&&request.proxyAdmin.toLowerCase()!==admin))throw Error('Actual Transparent admin identity differs from preparation');
+      if(request.kind==='transparent-upgrade')transactions.push({id:'upgrade-proxy',purpose:'upgrade-proxy',to:admin,value:'0',operation:0,
+        data:PROXY_ADMIN_INTERFACE.encodeFunctionData('upgradeAndCall',[proxy,implementation,data]).toLowerCase()});
+      if(request.kind==='transparent-deploy'&&deployments.find(d=>d.role==='proxy')?.status==='reused'&&deployments.some(d=>d.status==='required'))throw Error('Invalid actual Transparent reuse roles');
+    } else {
     const proxy =
       request.kind === "uups-placeholder-deploy"
         ? role(
@@ -215,6 +230,7 @@ export async function validatePreparationSemantics(
       });
     else if (deployments.some((d) => d.status === "required"))
       throw new Error("Invalid actual UUPS reuse roles");
+    }
   }
   if (
     canonicalJson(deployments) !== canonicalJson(plan.deployments) ||

package/runtime/delivery/production-environment.ts

@@ -1,6 +1,7 @@
 /** Remove signing authority, retaining independent model/RPC API configuration. */
 export function productionChildEnvironment(input:NodeJS.ProcessEnv):NodeJS.ProcessEnv {
  const out={...input};
- for(const key of Object.keys(out))if(/(^|_)(PRIVATE_KEY|MNEMONIC|SEED_PHRASE)$/.test(key)||/^GATEFLOW_(OPERATOR_TOKEN|PRODUCTION_|MAC_SECURE_SIGNER_)/.test(key)||/^GATE_(CUSTODY|SIGNER)_/.test(key))delete out[key];
+ // Also discard the retired alias if it remains in a caller's environment; it is never a signer input.
+ for(const key of Object.keys(out))if(/(^|_)(PRIVATE_KEY|WALLET_CREDENTIAL|MNEMONIC|SEED_PHRASE)$/.test(key)||key==='CUSTODY_API_BASE_URL'||/^GATEFLOW_(OPERATOR_TOKEN|PRODUCTION_|MAC_SECURE_SIGNER_)/.test(key)||/^GATE_(CUSTODY|SIGNER)_/.test(key))delete out[key];
  return out;
 }