gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/export.ts

@@ -0,0 +1,99 @@
+/** Independent artifact delivery: no planning, execution, chain access or filesystem effects. */
+import { canonicalJson, deepFreeze, nonempty } from '../workflow/lib/canonicalData';
+import { strictData } from './data';
+import { parseDeliveryPlan, type DeliveryPlan } from './plan';
+import { parseObservation, type TransactionObservation, type TrustedFinalizedProgressPort } from './observations';
+export type { TrustedFinalizedProgressPort, TransactionObservation } from './observations';
+export interface DeliveryExportModel {
+    version: 1;
+    schema: 'gate-delivery-export';
+    status: 'artifact-delivered';
+    /** Self-consistency is not host authorization or externally validated release readiness. */
+    plan: DeliveryPlan;
+    fullRange: {
+        start: number;
+        end: number;
+    };
+    actionableRange: {
+        start: number;
+        end: number;
+    } | null;
+    completed: TransactionObservation[];
+    dependencies: {
+        transactionId: string;
+        after: string[];
+    }[];
+}
+/** Require canonical sealed input without silently normalizing quantities, case or ordering. */
+export function immutableDeliveryPlan(raw: unknown): DeliveryPlan {
+    const data = strictData(raw, 'sealed delivery plan'), plan = parseDeliveryPlan(data);
+    if (canonicalJson(data) !== canonicalJson(plan))
+        throw new Error('Expected canonical immutable delivery plan');
+    return plan;
+}
+declare const progressBrand: unique symbol;
+export interface ValidatedDeliveryProgress {
+    readonly [progressBrand]: true;
+}
+const trustedProgress = new WeakMap<object, TransactionObservation[]>();
+const progressPlans = new WeakMap<object, string>();
+/** Explicit trusted I/O boundary, separate from formatting. Only this live result can mark completion. */
+export async function validateDeliveryProgress(input: {
+    plan: unknown;
+    completed?: readonly string[];
+    finalized?: TrustedFinalizedProgressPort;
+}): Promise<ValidatedDeliveryProgress> {
+    const plan = immutableDeliveryPlan(input.plan), references = strictData(input.completed ?? [], 'completed observation references');
+    if (!Array.isArray(references) || references.length > plan.transactions.length)
+        throw new Error('Invalid completed prefix');
+    if (references.length && typeof input.finalized?.readFinalized !== 'function')
+        throw new Error('Completed progress requires trusted finalized provenance');
+    const completed: TransactionObservation[] = [];
+    const seen = new Set<string>();
+    for (const [i, ref] of references.entries()) {
+        nonempty(ref, 'observation reference');
+        if (seen.has(ref))
+            throw new Error('Duplicate completed observation');
+        seen.add(ref);
+        const o = parseObservation(await input.finalized!.readFinalized(ref), plan, i);
+        if (o.observationId !== ref || o.state !== 'finalized-success')
+            throw new Error('Completed prefix requires verified finalized success');
+        completed.push(o);
+    }
+    const token = Object.freeze(Object.create(null)) as ValidatedDeliveryProgress;
+    trustedProgress.set(token, deepFreeze(completed));
+    progressPlans.set(token, plan.planHash);
+    return token;
+}
+/** Pure renderer. No callback, filesystem or chain access; serialized tokens convey no provenance. */
+export function renderDeliveryExport(rawPlan: unknown, progress?: ValidatedDeliveryProgress): {
+    model: DeliveryExportModel;
+    json: string;
+    markdown: string;
+} {
+    const plan = immutableDeliveryPlan(rawPlan);
+    const completed = progress === undefined ? [] : trustedProgress.get(progress);
+    if (!completed || (progress !== undefined && progressPlans.get(progress) !== plan.planHash))
+        throw new Error('Untrusted or mismatched validated progress');
+    const start = completed.length;
+    let end = start;
+    if (start < plan.transactions.length) {
+        const first = plan.transactions[start];
+        while (end < plan.transactions.length && plan.transactions[end].route === first.route && plan.transactions[end].executor === first.executor)
+            end++;
+    }
+    const model: DeliveryExportModel = deepFreeze({ version: 1, schema: 'gate-delivery-export', status: 'artifact-delivered', plan, fullRange: { start: 0, end: plan.transactions.length }, actionableRange: start === end ? null : { start, end }, completed, dependencies: plan.transactions.map((tx, i) => ({ transactionId: tx.transactionId, after: i ? [plan.transactions[i - 1].transactionId] : [] })) });
+    const json = canonicalJson(model);
+    // One complete canonical model in both formats prevents abbreviated calldata or split projections.
+    const markdown = `# Delivery calldata\n\nArtifact delivered. This export does not indicate deployment or grant execution authority.\n\nFull range: [${model.fullRange.start}, ${model.fullRange.end}).\nCurrent actionable range: ${model.actionableRange ? `[${start}, ${end})` : 'none'}. All transactions follow their predecessors.\n\n\`\`\`json\n${json}\n\`\`\`\n`;
+    return deepFreeze({ model, json, markdown });
+}
+/** Convenience wrapper: resolves trusted provenance first, then invokes the pure renderer. */
+export async function exportDelivery(input: {
+    plan: unknown;
+    completed?: readonly string[];
+    finalized?: TrustedFinalizedProgressPort;
+}) {
+    const plan = immutableDeliveryPlan(input.plan);
+    return renderDeliveryExport(plan, await validateDeliveryProgress({ ...input, plan }));
+}