gate-evm-tools 1.0.28 → 1.0.31

package/runtime/workflow/lib/pendingDeploymentReuse.ts

@@ -1,12 +1,11 @@
+import { assertPendingUupsPreparation, assertPendingUupsCurrentState, planDeployment, sameAddress } from "./pendingUupsBinding";
 import fs from "fs";
 import path from "path";
 import type { Provider } from "ethers";
 import {
   canonicalPreparationJson,
-  hashPreparationRequest,
   normalizePreparationPlan,
   normalizePreparationRequest,
-  type GateToolPreparationPlanV1,
 } from "gate-evm-tools/workflow";
 import { readJsonFile } from "./config";
 import {
@@ -18,7 +17,6 @@ import {
   type DeploymentChange,
   type PendingDeploymentReuseEvidence,
 } from "./deploymentRecords";
-import { getERC1967Implementation } from "./erc1967";
 import { loadReleaseExecutionPlan } from "./executionPlan";
 import { readParameterLockExecution } from "./lock";
 import { loadOperatorExecutionResult } from "./operatorExecution";
@@ -55,12 +53,6 @@ const isRecord = (value: unknown): value is Record<string, unknown> => (
   !!value && typeof value === "object" && !Array.isArray(value)
 );
 
-const sameAddress = (left: unknown, right: unknown): boolean => (
-  typeof left === "string"
-  && typeof right === "string"
-  && left.toLowerCase() === right.toLowerCase()
-);
-
 const sameFingerprint = (left: ReleaseFingerprint, right: ReleaseFingerprint): boolean => (
   left.manifestHash === right.manifestHash
   && left.artifactHash === right.artifactHash
@@ -90,17 +82,6 @@ const pendingCandidateFiles = (root: string): string[] => fs.readdirSync(root)
   .filter((name) => /^contractInfo\.pending\.[A-Za-z0-9][A-Za-z0-9_-]{0,199}\.json$/.test(name))
   .map((name) => path.join(root, name));
 
-const planDeployment = (
-  plan: GateToolPreparationPlanV1,
-  role: "implementation" | "proxy",
-) => {
-  const matches = plan.deployments.filter((deployment) => deployment.role === role);
-  if (matches.length !== 1) {
-    throw new Error(`GateTool plan must contain exactly one ${role} deployment`);
-  }
-  return matches[0];
-};
-
 const assertSuccessfulVerification = (
   input: PendingUupsReuseInput,
   executionId: string,
@@ -283,28 +264,8 @@ const verifyCandidate = async (
   ));
   const implementation = planDeployment(plan, "implementation");
   const proxy = planDeployment(plan, "proxy");
-  if (
-    plan.kind !== "uups-placeholder-deploy"
-    || plan.scheme !== input.scheme
-    || plan.network !== input.network
-    || plan.target !== input.network
-    || request.kind !== "uups-placeholder-deploy"
-    || request.scheme !== input.scheme
-    || request.network !== input.network
-    || request.target !== input.network
-    || hashPreparationRequest(request) !== plan.requestHash
-    || !sameAddress(request.factory, input.factory)
-    || request.proxySalt.toLowerCase() !== input.proxySalt.toLowerCase()
-    || request.implementationSalt.toLowerCase() !== change.implementationSalt!.toLowerCase()
-    || !sameAddress(request.placeholderImplementation, input.placeholderImplementationAddress)
-    || !sameAddress(proxy.address, change.address)
-    || proxy.salt.toLowerCase() !== input.proxySalt.toLowerCase()
-    || !sameAddress(implementation.address, change.implementationAddress)
-    || implementation.salt.toLowerCase() !== change.implementationSalt!.toLowerCase()
-    || !/^[0-9a-f]{64}$/.test(plan.artifact.digest)
-  ) {
-    throw new Error("Pending GateTool evidence does not match the current UUPS deployment");
-  }
+  if (plan.network !== input.network || request.network !== input.network) throw new Error("Pending GateTool network differs from the legacy target");
+  assertPendingUupsPreparation(input, change, request, plan);
 
   const executionPlan = loadReleaseExecutionPlan({
     root: input.root,
@@ -344,20 +305,7 @@ const verifyCandidate = async (
     }
   }
 
-  const proxyCode = await input.provider.getCode(proxy.address, input.blockTag);
-  const implementationCode = await input.provider.getCode(implementation.address, input.blockTag);
-  const currentImplementation = await getERC1967Implementation(
-    input.provider,
-    proxy.address,
-    input.blockTag,
-  );
-  if (
-    !proxyCode || proxyCode === "0x"
-    || !implementationCode || implementationCode === "0x"
-    || !sameAddress(currentImplementation, implementation.address)
-  ) {
-    throw new Error("Pending deployment does not match current on-chain UUPS state");
-  }
+  await assertPendingUupsCurrentState(input, proxy.address, implementation.address);
 
   const deploymentRecordPath = path.join(
     input.taskDir,

package/runtime/workflow/lib/pendingUupsBinding.ts

@@ -0,0 +1,43 @@
+import type { Provider } from 'ethers';
+import { hashPreparationRequest, type GateToolPreparationPlanV1, type GateToolPreparationRequestV1 } from 'gate-evm-tools/workflow';
+import type { DeploymentChange, PendingDeploymentReuseEvidence } from './deploymentRecords';
+import { getERC1967Implementation } from './erc1967';
+export interface PendingUupsBindingInput {
+  taskId: string; network: string; stepId: string; instanceId: string; actualContract: string;
+  contractInfoKey: string; scheme: 'evm' | 'zksync-eravm'; factory: string; multicall: string;
+  proxySalt: string; expectedAddress?: string; placeholderImplementationAddress: string;
+  provider: Pick<Provider, 'getCode' | 'getStorage'>; blockTag?: number;
+}
+export interface PendingReuseBinding { executionId: string; target: string; planHash: string; artifactDigest: string; observationIds: string[] }
+export interface PendingUupsResolution {
+  implementationAddress: string; implementationSalt: string; proxyAddress: string; artifactDigest: string;
+  legacyEvidence?: PendingDeploymentReuseEvidence;
+  binding?: PendingReuseBinding;
+}
+export interface PendingUupsResolverPort { resolve(input: PendingUupsBindingInput): Promise<PendingUupsResolution | undefined> }
+export const sameAddress = (left: unknown, right: unknown): boolean => typeof left === 'string' && typeof right === 'string' && left.toLowerCase() === right.toLowerCase();
+export function planDeployment(plan: GateToolPreparationPlanV1, role: 'implementation' | 'proxy') {
+  const matches = plan.deployments.filter(d => d.role === role);
+  if (matches.length !== 1) throw new Error(`GateTool plan must contain exactly one ${role} deployment`);
+  return matches[0];
+}
+/** Common semantic predicate; no lock, filesystem, finalSimulation or recorder lifecycle. */
+export function assertPendingUupsPreparation(input: PendingUupsBindingInput, change: DeploymentChange, request: GateToolPreparationRequestV1, plan: GateToolPreparationPlanV1): void {
+  const implementation = planDeployment(plan, 'implementation'), proxy = planDeployment(plan, 'proxy');
+  if (change.stepId !== input.stepId || change.instanceId !== input.instanceId || change.kind !== 'deploy' || change.actualContract !== input.actualContract || change.contractInfoKey !== input.contractInfoKey || change.strategy !== 'create2' || change.proxyKind !== 'uups'
+    || !sameAddress(change.factory, input.factory) || !sameAddress(change.multicall, input.multicall) || change.salt?.toLowerCase() !== input.proxySalt.toLowerCase() || !sameAddress(change.placeholderImplementationAddress, input.placeholderImplementationAddress)
+    || (input.expectedAddress && !sameAddress(input.expectedAddress, proxy.address))
+    || plan.kind !== 'uups-placeholder-deploy' || plan.scheme !== input.scheme || plan.target !== input.network
+    || request.kind !== 'uups-placeholder-deploy' || request.scheme !== input.scheme || request.target !== input.network
+    || request.network !== plan.network || plan.contract !== request.contract || plan.artifact.contractName !== input.actualContract
+    || hashPreparationRequest(request) !== plan.requestHash || !sameAddress(request.factory, input.factory)
+    || request.proxySalt.toLowerCase() !== input.proxySalt.toLowerCase() || request.implementationSalt.toLowerCase() !== change.implementationSalt?.toLowerCase()
+    || !sameAddress(request.placeholderImplementation, input.placeholderImplementationAddress)
+    || !sameAddress(proxy.address, change.address ?? change.predictedAddress) || proxy.salt.toLowerCase() !== input.proxySalt.toLowerCase()
+    || !sameAddress(implementation.address, change.implementationAddress) || implementation.salt.toLowerCase() !== change.implementationSalt?.toLowerCase()
+    || !/^[0-9a-f]{64}$/.test(plan.artifact.digest)) throw new Error('Pending GateTool evidence does not match the current UUPS deployment');
+}
+export async function assertPendingUupsCurrentState(input: Pick<PendingUupsBindingInput, 'provider' | 'blockTag'>, proxy: string, implementation: string): Promise<void> {
+  const [proxyCode, implementationCode, current] = await Promise.all([input.provider.getCode(proxy, input.blockTag), input.provider.getCode(implementation, input.blockTag), getERC1967Implementation(input.provider, proxy, input.blockTag)]);
+  if (!proxyCode || proxyCode === '0x' || !implementationCode || implementationCode === '0x' || !sameAddress(current, implementation)) throw new Error('Pending deployment does not match current on-chain UUPS state');
+}

package/runtime/workflow/lib/plan.ts

@@ -0,0 +1,334 @@
+import fs from "fs";
+import path from "path";
+import YAML from "yaml";
+
+/**
+ * Read and write `handoff.md`, the plan-level carrier shared by the GateFlow
+ * entry point and the Codex command line.
+ *
+ * This is deliberately NOT the execution-level `handoff.json`: that one records
+ * deployment evidence and is validated byte for byte by the deployment gates.
+ * The plan layer says what is to be done; the execution layer proves what was.
+ * Keeping them in separate files is the point -- neither should have to carry
+ * the other's fields.
+ *
+ * Nothing here trusts the file. A plan that moves between two runtimes is
+ * exactly where a crafted document would be worth writing, so the parse is
+ * strict, the forbidden-field list is checked recursively, and the writer is
+ * the only sanctioned producer of the deterministic parts.
+ */
+
+export const PLAN_SCHEMA = "gateflow-plan/v1";
+export const PLAN_FILE = "handoff.md";
+export const SECTIONS = ["development", "audit", "deployment"] as const;
+export type PlanSection = (typeof SECTIONS)[number];
+
+export const TASK_STATUSES = ["pending", "ready", "running", "completed", "failed", "cancelled"] as const;
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+
+/** Local bindings. A plan changes entry point, so none of these can travel. */
+const FORBIDDEN_FIELDS = [
+  "sessionid", "runtimerunid", "stageid", "attemptid", "workspacepath",
+  "authorizationid", "executionlock", "localstate", "planid", "workspacerelativepath",
+];
+
+export interface PlanTask {
+  planKey: string;
+  title: string;
+  objective: string;
+  acceptance: string[];
+  dependsOn: string[];
+  status: TaskStatus;
+  scope?: Record<string, unknown>;
+  parameters?: unknown[];
+  expectedArtifacts?: string[];
+  allowedChanges?: string[];
+}
+
+export interface Plan {
+  schema: string;
+  taskId: string;
+  revision: number;
+  title: string;
+  sections: Record<PlanSection, "enabled" | "disabled">;
+  updatedAt: string;
+  tasks: Record<PlanSection, PlanTask[]>;
+}
+
+const SAFE_KEY = /^[a-z0-9][a-z0-9-]{0,199}$/;
+
+function fail(message: string): never {
+  throw new Error(`handoff.md: ${message}`);
+}
+
+function normalizeFieldName(key: string): string {
+  return key.replace(/[_-]/g, "").toLowerCase();
+}
+
+/** Recursive, because a forbidden name is just as bad nested as at the top. */
+function assertNoForbiddenFields(value: unknown, where: string): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoForbiddenFields(item, `${where}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_FIELDS.includes(normalizeFieldName(key))) {
+      fail(`${where}.${key} is a local binding and cannot travel between entry points`);
+    }
+    assertNoForbiddenFields(child, `${where}.${key}`);
+  }
+}
+
+const ABSOLUTE = /^(?:\/|\\|[A-Za-z]:[\\/]|~\/)/;
+
+function assertNoSecretsOrPaths(value: unknown, where: string): void {
+  if (typeof value === "string") {
+    if (ABSOLUTE.test(value)) fail(`${where} must not be an absolute path`);
+    if (/-----BEGIN .*PRIVATE KEY-----/.test(value)) fail(`${where} must not contain a private key`);
+    if (/\bBearer\s+\S+/.test(value)) fail(`${where} must not contain a bearer token`);
+    if (/[?&](?:api[_-]?key|token|secret)=\S+/i.test(value)) fail(`${where} must not contain a credentialed URL`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoSecretsOrPaths(item, `${where}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) assertNoSecretsOrPaths(child, `${where}.${key}`);
+}
+
+/**
+ * Check caller input before it is reduced to known fields. The CLI builds
+ * tasks from a whitelist, so a forbidden name dropped there would never reach
+ * the parser's check -- it would vanish silently instead of being refused.
+ */
+export function assertPortableInput(value: unknown, where: string): void {
+  assertNoForbiddenFields(value, where);
+  assertNoSecretsOrPaths(value, where);
+}
+
+function nonEmptyString(value: unknown, where: string): string {
+  if (typeof value !== "string" || !value.trim()) fail(`${where} must be a non-empty string`);
+  return value;
+}
+
+function stringArray(value: unknown, where: string, options: { min?: number } = {}): string[] {
+  if (!Array.isArray(value)) fail(`${where} must be an array`);
+  const items = value.map((item, index) => nonEmptyString(item, `${where}[${index}]`));
+  if (options.min !== undefined && items.length < options.min) {
+    fail(`${where} must contain at least ${options.min} item(s)`);
+  }
+  return items;
+}
+
+function parseTask(raw: unknown, where: string): PlanTask {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) fail(`${where} must be an object`);
+  const value = raw as Record<string, unknown>;
+  const planKey = nonEmptyString(value.planKey, `${where}.planKey`);
+  if (!SAFE_KEY.test(planKey)) {
+    fail(`${where}.planKey must be lower-case alphanumeric with hyphens: "${planKey}"`);
+  }
+  const status = nonEmptyString(value.status ?? "pending", `${where}.status`);
+  if (!(TASK_STATUSES as readonly string[]).includes(status)) {
+    fail(`${where}.status must be one of ${TASK_STATUSES.join(", ")}`);
+  }
+  const task: PlanTask = {
+    planKey,
+    title: nonEmptyString(value.title, `${where}.title`),
+    objective: nonEmptyString(value.objective, `${where}.objective`),
+    acceptance: stringArray(value.acceptance, `${where}.acceptance`, { min: 1 }),
+    dependsOn: value.dependsOn === undefined ? [] : stringArray(value.dependsOn, `${where}.dependsOn`),
+    status: status as TaskStatus,
+  };
+  if (value.scope !== undefined) task.scope = value.scope as Record<string, unknown>;
+  if (value.parameters !== undefined) {
+    if (!Array.isArray(value.parameters)) fail(`${where}.parameters must be an array`);
+    task.parameters = value.parameters;
+  }
+  if (value.expectedArtifacts !== undefined) {
+    task.expectedArtifacts = stringArray(value.expectedArtifacts, `${where}.expectedArtifacts`);
+  }
+  if (value.allowedChanges !== undefined) {
+    task.allowedChanges = stringArray(value.allowedChanges, `${where}.allowedChanges`);
+  }
+  assertNoForbiddenFields(task, where);
+  assertNoSecretsOrPaths(task, where);
+  return task;
+}
+
+/** Dependency rules are enforced across the whole plan, not per task. */
+function assertDependencyGraph(tasks: PlanTask[]): void {
+  const byKey = new Map(tasks.map((task) => [task.planKey, task]));
+  if (byKey.size !== tasks.length) {
+    const seen = new Set<string>();
+    for (const task of tasks) {
+      if (seen.has(task.planKey)) fail(`duplicate planKey "${task.planKey}"`);
+      seen.add(task.planKey);
+    }
+  }
+  for (const task of tasks) {
+    if (task.dependsOn.includes(task.planKey)) fail(`task "${task.planKey}" depends on itself`);
+    for (const dependency of task.dependsOn) {
+      if (!byKey.has(dependency)) {
+        fail(`task "${task.planKey}" depends on unknown task "${dependency}"`);
+      }
+    }
+  }
+  // Iterative colouring; a cycle here means the plan must be re-cut, not patched.
+  const state = new Map<string, "visiting" | "done">();
+  const visit = (key: string, trail: string[]): void => {
+    const current = state.get(key);
+    if (current === "done") return;
+    if (current === "visiting") fail(`dependency cycle: ${[...trail, key].join(" -> ")}`);
+    state.set(key, "visiting");
+    for (const dependency of byKey.get(key)!.dependsOn) visit(dependency, [...trail, key]);
+    state.set(key, "done");
+  };
+  for (const task of tasks) visit(task.planKey, []);
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
+const TASK_BLOCK = /```gateflow-task\n([\s\S]*?)\n```/g;
+
+export function parsePlan(text: string): Plan {
+  const match = text.match(FRONTMATTER);
+  if (!match) fail("missing YAML frontmatter");
+  let meta: Record<string, unknown>;
+  try {
+    meta = YAML.parse(match[1]) as Record<string, unknown>;
+  } catch (error) {
+    fail(`frontmatter is not valid YAML: ${(error as Error).message}`);
+  }
+  if (!meta || typeof meta !== "object") fail("frontmatter must be a mapping");
+  assertNoForbiddenFields(meta, "frontmatter");
+  assertNoSecretsOrPaths(meta, "frontmatter");
+
+  if (meta.schema !== PLAN_SCHEMA) fail(`schema must be "${PLAN_SCHEMA}"`);
+  const taskId = nonEmptyString(meta.taskId, "frontmatter.taskId");
+  if (!SAFE_KEY.test(taskId)) fail("frontmatter.taskId must be lower-case alphanumeric with hyphens");
+  const revision = meta.revision;
+  if (!Number.isInteger(revision) || (revision as number) < 1) fail("frontmatter.revision must be a positive integer");
+  const title = nonEmptyString(meta.title, "frontmatter.title");
+
+  // Each heading exactly once, in the fixed order.
+  const body = text.slice(match[0].length);
+  const headings = [...body.matchAll(/^## (.+)$/gm)].map((item) => item[1].trim());
+  if (headings.length !== SECTIONS.length || SECTIONS.some((section, index) => headings[index] !== section)) {
+    fail(`body must contain exactly these headings in order: ${SECTIONS.map((s) => `## ${s}`).join(", ")}`);
+  }
+
+  const tasks = {} as Record<PlanSection, PlanTask[]>;
+  const sections = {} as Record<PlanSection, "enabled" | "disabled">;
+  SECTIONS.forEach((section, index) => {
+    const start = body.indexOf(`## ${section}`) + `## ${section}`.length;
+    const end = index + 1 < SECTIONS.length ? body.indexOf(`## ${SECTIONS[index + 1]}`) : body.length;
+    const chunk = body.slice(start, end);
+    const declared = meta.sections;
+    const fromFrontmatter = declared && typeof declared === "object" && !Array.isArray(declared)
+      ? (declared as Record<string, unknown>)[section]
+      : undefined;
+    const inline = chunk.match(/^\s*(enabled|disabled)\s*$/m)?.[1];
+    const state = (fromFrontmatter ?? inline) as string | undefined;
+    if (state !== "enabled" && state !== "disabled") {
+      fail(`section "${section}" must declare "enabled" or "disabled"`);
+    }
+    sections[section] = state;
+    const parsed = [...chunk.matchAll(TASK_BLOCK)].map((block, order) => {
+      let value: unknown;
+      try {
+        value = JSON.parse(block[1]);
+      } catch (error) {
+        fail(`section "${section}" task ${order + 1} is not valid JSON: ${(error as Error).message}`);
+      }
+      return parseTask(value, `section "${section}" task ${order + 1}`);
+    });
+    if (state === "disabled" && parsed.length > 0) {
+      fail(`section "${section}" is disabled but carries ${parsed.length} task(s)`);
+    }
+    tasks[section] = parsed;
+  });
+
+  const all = SECTIONS.flatMap((section) => tasks[section]);
+  if (all.length === 0) fail("plan contains no tasks in any enabled section");
+  assertDependencyGraph(all);
+
+  return {
+    schema: PLAN_SCHEMA,
+    taskId,
+    revision: revision as number,
+    title,
+    sections,
+    updatedAt: nonEmptyString(meta.updatedAt ?? new Date(0).toISOString(), "frontmatter.updatedAt"),
+    tasks,
+  };
+}
+
+export function renderPlan(plan: Plan): string {
+  const frontmatter = YAML.stringify({
+    schema: PLAN_SCHEMA,
+    taskId: plan.taskId,
+    revision: plan.revision,
+    title: plan.title,
+    sections: plan.sections,
+    updatedAt: plan.updatedAt,
+  }).trimEnd();
+  const body = SECTIONS.map((section) => {
+    const blocks = plan.tasks[section]
+      .map((task) => `\n\`\`\`gateflow-task\n${JSON.stringify(task, null, 2)}\n\`\`\``)
+      .join("\n");
+    return `## ${section}\n\n${plan.sections[section]}${blocks}`;
+  }).join("\n\n");
+  return `---\n${frontmatter}\n---\n\n${body}\n`;
+}
+
+export function readPlanFile(root: string, relative: string = PLAN_FILE): Plan {
+  const file = path.join(root, relative);
+  if (!fs.existsSync(file)) fail(`not found at ${relative}`);
+  return parsePlan(fs.readFileSync(file, "utf8"));
+}
+
+function writeAtomic(file: string, contents: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, contents);
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+}
+
+export function writePlanFile(root: string, plan: Plan, relative: string = PLAN_FILE): string {
+  const file = path.join(root, relative);
+  writeAtomic(file, renderPlan(plan));
+  return file;
+}
+
+export const emptyPlan = (taskId: string, title: string, sections: Record<PlanSection, "enabled" | "disabled">): Plan => ({
+  schema: PLAN_SCHEMA,
+  taskId,
+  revision: 1,
+  title,
+  sections,
+  updatedAt: new Date().toISOString(),
+  tasks: { development: [], audit: [], deployment: [] },
+});
+
+/** Deterministic summary for callers that only need to report what changed. */
+export function planSummary(plan: Plan): Record<string, unknown> {
+  const all = SECTIONS.flatMap((section) => plan.tasks[section]);
+  return {
+    taskId: plan.taskId,
+    revision: plan.revision,
+    sections: plan.sections,
+    taskCount: all.length,
+    tasks: SECTIONS.flatMap((section) => plan.tasks[section].map((task) => ({
+      planKey: task.planKey,
+      section,
+      status: task.status,
+      dependsOn: task.dependsOn,
+    }))),
+  };
+}