agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/workflow.js

@@ -0,0 +1,651 @@
+import { isAddress } from 'viem';
+import { z } from 'zod';
+import { AtomicAmountSchema, FailureCategorySchema, contentHash } from './index.js';
+import { presentationIssues, ReportCoverageSchema, ReportDatasetSchema, ReportPresentationSchema, ReportSignalSchema, WorkflowPresentationSchema } from './report-presentation.js';
+/**
+ * General creator workflows (`agentex.workflow.v1`). Kept outside index.ts so the fixed first-party manifests, their schemas
+ * and hashes stay byte-for-byte unchanged. A workflow is typed data: declared tools from the platform registry, typed bindings,
+ * deterministic conditions/transforms and report sections. Descriptive text never grants a capability; permissions are derived
+ * only from `tools`, `permissions`, `secrets` and `limits` and are enforced by runtime policy outside nodes.
+ */
+export const WORKFLOW_SCHEMA_ID = 'agentex.workflow.v1';
+export const MODEL_PROVIDER_UNCONFIGURED = 'AI analysis is not available on this server, so AI analysis steps stay switched off and no model is called.';
+/** L04: models a creator may select for an AI analysis node. Mirrors the priced server tariff table (packages/model MODEL_TARIFFS); others are refused. */
+export const WORKFLOW_ALLOWED_MODELS = ['claude-opus-5', 'claude-opus-4-8'];
+export const WorkflowChainKeySchema = z.enum(['ethereum', 'base', 'robinhood', 'solana']);
+export const ToolCapabilitySchema = z.enum(['evm.read', 'solana.read', 'http.read']);
+/** Methods a read capability may ever request. Signing, sending and account-management methods are absent by construction. */
+export const CAPABILITY_METHODS = Object.freeze({
+    // R02: `debug_traceTransaction` (only with the fixed prestate-diff tracer, enforced by the runtime) for transaction flows through the keyed archive endpoint.
+    'evm.read': ['eth_chainId', 'eth_blockNumber', 'eth_getBlockByNumber', 'eth_getBlockByHash', 'eth_getCode', 'eth_getStorageAt', 'eth_call', 'eth_estimateGas', 'eth_getLogs', 'eth_getBalance', 'eth_getTransactionByHash', 'eth_getTransactionReceipt', 'eth_getTransactionCount', 'debug_traceTransaction'],
+    // R02: validator health reads, each filtered to one in-scope vote account or identity by the runtime.
+    'solana.read': ['getGenesisHash', 'getSlot', 'getAccountInfo', 'getMultipleAccounts', 'getBalance', 'getSignaturesForAddress', 'getTransaction', 'getTokenSupply', 'getTokenLargestAccounts', 'simulateTransaction', 'getVoteAccounts', 'getEpochInfo', 'getBlockProduction', 'getRecentPerformanceSamples'],
+    'http.read': ['GET'],
+});
+const CHAIN_CAPABILITIES = { ethereum: ['evm.read', 'http.read'], base: ['evm.read', 'http.read'], robinhood: ['evm.read', 'http.read'], solana: ['solana.read', 'http.read'] };
+const Identifier = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/, 'Use lowercase letters, digits, dots, underscores or hyphens (at most 64 characters)');
+const PropertyIdentifier = z.string().regex(/^[a-z][a-zA-Z0-9_]{0,63}$/, 'Use a camelCase property name').refine((value) => !['constructor', 'prototype', '__proto__'].includes(value), 'Reserved property name');
+const Semver = z.string().regex(/^\d+\.\d+\.\d+$/);
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+const ToolRef = z.string().regex(/^[a-z][a-z0-9._-]{0,63}@\d+\.\d+\.\d+$/);
+const Scalar = z.union([z.string().max(512), z.number().finite(), z.boolean()]);
+const DecimalString = z.string().regex(/^-?(0|[1-9][0-9]{0,77})(\.[0-9]{1,78})?$/, 'Expected an exact decimal number');
+const ValuePath = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,63}(\.[a-zA-Z0-9_]{1,64}){0,3}$/, 'Expected a dotted property path');
+const Hostname = z.string().regex(/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/, 'Expected a lowercase public DNS hostname');
+/** Input names that would collect credentials. Buyer inputs are public research parameters; secrets are server-side references only. */
+const SECRET_NAME = /(private_?key|secret|password|passphrase|mnemonic|seed_?phrase|api_?key|access_?token|auth_?token|credential)/i;
+const SECRET_CONTENT = /-----BEGIN [A-Z ]*PRIVATE KEY|\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{8,}|\bsk-[A-Za-z0-9_-]{16,}|\bAKIA[0-9A-Z]{16}\b|\bxox[abprs]-[A-Za-z0-9-]{8,}|\bgh[pousr]_[A-Za-z0-9]{20,}|\b(?:api[_-]?key|secret|password|mnemonic|private[_-]?key)\s*[:=]\s*\S{6,}/i;
+export const WorkflowFieldSchema = z.strictObject({ type: z.enum(['string', 'evm-address', 'solana-address', 'integer', 'boolean']), description: z.string().max(500), enum: z.array(z.string().max(200)).min(1).max(50).optional() });
+export const WorkflowInputSchemaDefinition = z.strictObject({ type: z.literal('object'), properties: z.record(PropertyIdentifier, WorkflowFieldSchema), required: z.array(PropertyIdentifier).max(32), additionalProperties: z.literal(false) }).superRefine((schema, ctx) => {
+    if (Object.keys(schema.properties).length > 32)
+        ctx.addIssue({ code: 'custom', message: 'At most 32 input properties' });
+    for (const key of schema.required)
+        if (!Object.hasOwn(schema.properties, key))
+            ctx.addIssue({ code: 'custom', path: ['required'], message: `Required input ${key} is not declared` });
+    for (const [key, field] of Object.entries(schema.properties)) {
+        if (SECRET_NAME.test(key))
+            ctx.addIssue({ code: 'custom', path: ['properties', key], message: `Input ${key} looks like a credential. Buyer inputs cannot collect secrets; declare a secret reference instead.` });
+        if (field.enum && field.type !== 'string')
+            ctx.addIssue({ code: 'custom', path: ['properties', key, 'enum'], message: 'Only string inputs can declare an enum' });
+    }
+});
+export const WorkflowBindingSchema = z.discriminatedUnion('source', [
+    z.strictObject({ source: z.literal('input'), path: PropertyIdentifier }),
+    z.strictObject({ source: z.literal('node'), nodeId: Identifier, path: ValuePath.optional() }),
+    z.strictObject({ source: z.literal('literal'), value: Scalar }),
+]);
+export const ConditionOperatorSchema = z.enum(['equals', 'exists', 'gt', 'lt', 'gte', 'lte']);
+export const TransformSchema = z.discriminatedUnion('op', [
+    z.strictObject({ op: z.literal('pick'), from: WorkflowBindingSchema }),
+    z.strictObject({ op: z.literal('compare'), left: WorkflowBindingSchema, operator: ConditionOperatorSchema.exclude(['exists']), right: WorkflowBindingSchema }),
+    z.strictObject({ op: z.literal('threshold'), value: WorkflowBindingSchema, threshold: DecimalString }),
+    z.strictObject({ op: z.literal('format-amount'), amount: WorkflowBindingSchema, decimals: WorkflowBindingSchema }),
+]);
+export const FindingValueTypeSchema = z.enum(['string', 'boolean', 'integer', 'decimal', 'address']);
+const NodeBase = { id: Identifier, label: z.string().max(100).optional(), dependsOn: z.array(Identifier).max(16) };
+export const WorkflowNodeSchema = z.discriminatedUnion('type', [
+    z.strictObject({ ...NodeBase, type: z.literal('input') }),
+    z.strictObject({ ...NodeBase, type: z.literal('tool'), tool: Identifier, arguments: z.record(PropertyIdentifier, WorkflowBindingSchema) }),
+    z.strictObject({ ...NodeBase, type: z.literal('condition'), field: WorkflowBindingSchema, operator: ConditionOperatorSchema, value: Scalar.optional(), whenTrue: Identifier.nullable(), whenFalse: Identifier.nullable() }),
+    z.strictObject({ ...NodeBase, type: z.literal('transform'), transform: TransformSchema }),
+    z.strictObject({ ...NodeBase, type: z.literal('report-section'), section: Identifier, findings: z.array(z.strictObject({ code: Identifier, value: WorkflowBindingSchema })).min(1).max(16) }),
+    z.strictObject({ ...NodeBase, type: z.literal('ai-analysis'), instructions: z.string().min(1).max(2000), inputs: z.record(PropertyIdentifier, WorkflowBindingSchema), maximumTokens: z.number().int().min(1).max(8000), model: z.enum(WORKFLOW_ALLOWED_MODELS).optional() }),
+    z.strictObject({ ...NodeBase, type: z.literal('output'), sections: z.array(Identifier).min(1).max(12) }),
+    /**
+     * Deterministic creator transform source (one ES module exporting `default (input) => JSON`). It is data in the package and is
+     * executed only by the platform's isolated sandbox runner (no network, read-only filesystem, CPU/memory/time caps). Without a
+     * configured runner the node is declared but disabled, exactly like an AI analysis node without a model provider.
+     */
+    z.strictObject({ ...NodeBase, type: z.literal('sandboxed-transform'), inputs: z.record(PropertyIdentifier, WorkflowBindingSchema), source: z.string().min(1).max(16000), timeoutMs: z.number().int().min(500).max(10000) }),
+]);
+export const WorkflowToolDeclarationSchema = z.strictObject({ id: Identifier, version: Semver, capability: ToolCapabilitySchema, chains: z.array(WorkflowChainKeySchema).min(1).max(4), maximumCalls: z.number().int().min(1).max(64) });
+/**
+ * N03/N04: a reviewed remote connector pinned by the version. `id` is the alias tool nodes name, `schemaHash` the approved connector version's
+ * declaration hash, `maximumCalls` the per-run call ceiling and `maximumCostMicrousd` the per-run metered cost ceiling. Absent keeps existing
+ * manifests byte-identical. Connector nodes run only on servers with AGENTEX_CONNECTORS_ENABLED=true, through the connector gateway.
+ */
+export const WorkflowConnectorDeclarationSchema = z.strictObject({ id: Identifier, connectorId: z.uuid(), schemaHash: Hash, maximumCalls: z.number().int().min(1).max(16), maximumCostMicrousd: z.number().int().min(0).max(1_000_000) });
+export const WORKFLOW_CONNECTOR_TOOL_VERSION = '1.0.0';
+/** Evidence and step tool reference of a connector node. Aliases never collide with declared tool ids. */
+export const connectorToolRef = (alias) => `${alias}@${WORKFLOW_CONNECTOR_TOOL_VERSION}`;
+export const CONNECTOR_CALL_METHOD = 'POST';
+export const CONNECTORS_DISABLED = 'Remote connectors are switched off on this server, so workflows that declare connectors cannot be saved, versioned or run.';
+export const WorkflowOutputSchemaDefinition = z.strictObject({
+    sections: z.array(z.strictObject({ id: Identifier, title: z.string().min(1).max(100), required: z.boolean(),
+        findings: z.array(z.strictObject({ code: Identifier, label: z.string().min(1).max(100), valueType: FindingValueTypeSchema })).min(1).max(16) })).min(1).max(12),
+});
+/** Hosted use, source viewing and fork permission are separate rights. Per-run fees pay for platform execution only. */
+export const WorkflowRightsSchema = z.strictObject({
+    hostedUse: z.enum(['owner-only', 'listed-buyers']), sourceView: z.enum(['owner-only', 'public']), fork: z.enum(['not-permitted', 'permitted', 'permitted-with-attribution']),
+    attributionNotice: z.string().max(300).optional(),
+});
+export const AttributionSchema = z.strictObject({ sourceId: Identifier, sourceVersionHash: Hash, author: z.string().min(1).max(100), license: z.string().min(1).max(100), notice: z.string().max(300) });
+export const WorkflowManifestSchema = z.strictObject({
+    schemaVersion: z.literal('1.0'), id: Identifier, version: Semver, name: z.string().min(1).max(100), description: z.string().min(1).max(2000),
+    author: z.strictObject({ id: Identifier, name: z.string().min(1).max(100), ownership: z.enum(['first-party', 'independent']) }),
+    license: z.string().min(1).max(100), visibility: z.enum(['private', 'source-visible', 'source-private']), rights: WorkflowRightsSchema, attribution: z.array(AttributionSchema).max(8),
+    chains: z.array(WorkflowChainKeySchema).min(1).max(4),
+    inputSchema: WorkflowInputSchemaDefinition, outputSchemaId: z.literal(WORKFLOW_SCHEMA_ID), outputSchema: WorkflowOutputSchemaDefinition,
+    tools: z.array(WorkflowToolDeclarationSchema).min(1).max(16),
+    /** N03/N04 reviewed remote connectors pinned by this version (optional; absent keeps older manifests byte-identical). */
+    connectors: z.array(WorkflowConnectorDeclarationSchema).max(4).optional(),
+    permissions: z.strictObject({ addressScope: z.enum(['input-bound', 'input-derived']), domains: z.array(Hostname).max(8), destinations: z.tuple([z.literal('run-report')]) }),
+    modelPolicy: z.discriminatedUnion('mode', [z.strictObject({ mode: z.literal('deterministic'), maximumModelTokens: z.literal(0) }), z.strictObject({ mode: z.literal('bounded-model'), maximumModelTokens: z.number().int().min(1).max(32000),
+            /** L04: per-run model cost cap in micro-USD. Required to price a workflow with AI analysis; quotes and the worker enforce the same cap. Absent keeps older manifests byte-identical. */
+            maximumCostMicrousd: z.number().int().min(1).max(200000).optional() })]),
+    secrets: z.array(z.strictObject({ name: z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/), reference: z.string().regex(/^secret:\/\/[a-z0-9-]{1,40}\/[a-z0-9._-]{1,80}$/, 'Secrets are references such as secret://binding/name, never values'), purpose: z.string().max(200) })).max(8),
+    limits: z.strictObject({ maximumSteps: z.number().int().min(3).max(32), maximumRpcCalls: z.number().int().min(1).max(64), maximumDurationMs: z.number().int().min(1000).max(120000), stepTimeoutMs: z.number().int().min(500).max(60000),
+        maximumOutputBytes: z.number().int().min(1024).max(262144), maximumGraphDepth: z.number().int().min(2).max(16), maximumBlockRange: z.number().int().min(0).max(250_000_000), maximumPages: z.number().int().min(0).max(5), maximumExecutionAtomic: AtomicAmountSchema }),
+    workflow: z.array(WorkflowNodeSchema).min(3).max(32),
+    sampleOutput: z.array(z.strictObject({ section: Identifier, findings: z.record(Identifier, Scalar) })).max(12),
+    testCases: z.array(z.strictObject({ id: Identifier, chain: WorkflowChainKeySchema, values: z.record(PropertyIdentifier, Scalar) })).max(20),
+    /** R01 report archetype and blocks (optional; absent keeps older manifests byte-identical and renders the generic workflow layout). */
+    presentation: WorkflowPresentationSchema.optional(),
+}).superRefine((manifest, ctx) => {
+    const issue = (message, path = []) => ctx.addIssue({ code: 'custom', path, message });
+    const nodes = new Map(manifest.workflow.map((node) => [node.id, node]));
+    const index = new Map(manifest.workflow.map((node, position) => [node.id, position]));
+    const tools = new Map(manifest.tools.map((tool) => [tool.id, tool]));
+    const sections = new Map(manifest.outputSchema.sections.map((section) => [section.id, section]));
+    if (nodes.size !== manifest.workflow.length)
+        issue('Duplicate workflow node id', ['workflow']);
+    if (tools.size !== manifest.tools.length)
+        issue('Duplicate tool id', ['tools']);
+    const connectors = new Map((manifest.connectors ?? []).map((connector) => [connector.id, connector]));
+    if (connectors.size !== (manifest.connectors ?? []).length)
+        issue('Duplicate connector alias', ['connectors']);
+    if (new Set((manifest.connectors ?? []).map((connector) => connector.connectorId)).size !== (manifest.connectors ?? []).length)
+        issue('A connector is pinned more than once', ['connectors']);
+    (manifest.connectors ?? []).forEach((connector, position) => {
+        if (tools.has(connector.id))
+            issue(`Connector alias ${connector.id} collides with a declared tool id`, ['connectors', position, 'id']);
+        if (connector.maximumCalls > manifest.limits.maximumRpcCalls)
+            issue(`Connector ${connector.id} exceeds the workflow call budget`, ['connectors', position, 'maximumCalls']);
+    });
+    if (sections.size !== manifest.outputSchema.sections.length)
+        issue('Duplicate output section id', ['outputSchema', 'sections']);
+    if (new Set(manifest.chains).size !== manifest.chains.length)
+        issue('Duplicate chain', ['chains']);
+    if (manifest.visibility !== 'source-visible' && manifest.rights.sourceView === 'public')
+        issue('Public source viewing requires source-visible visibility', ['rights', 'sourceView']);
+    if (manifest.rights.fork !== 'not-permitted' && manifest.rights.sourceView !== 'public')
+        issue('Fork permission requires publicly viewable source', ['rights', 'fork']);
+    if (manifest.rights.fork === 'permitted-with-attribution' && !manifest.rights.attributionNotice)
+        issue('Attribution-required forks need an attribution notice', ['rights', 'attributionNotice']);
+    if (new Set(manifest.attribution.map((item) => item.sourceVersionHash)).size !== manifest.attribution.length)
+        issue('Duplicate attribution source', ['attribution']);
+    if (manifest.workflow.length > manifest.limits.maximumSteps)
+        issue(`The workflow has ${manifest.workflow.length} nodes but maximumSteps is ${manifest.limits.maximumSteps}`, ['limits', 'maximumSteps']);
+    if (manifest.workflow.filter((node) => node.type === 'input').length !== 1)
+        issue('Workflow must have exactly one input node', ['workflow']);
+    if (manifest.workflow.filter((node) => node.type === 'output').length !== 1)
+        issue('Workflow must have exactly one output node', ['workflow']);
+    for (const section of manifest.outputSchema.sections)
+        if (new Set(section.findings.map((finding) => finding.code)).size !== section.findings.length)
+            issue(`Duplicate finding code in section ${section.id}`, ['outputSchema', 'sections']);
+    const capabilities = new Set(manifest.tools.map((tool) => tool.capability));
+    manifest.tools.forEach((tool, position) => {
+        for (const chain of manifest.chains) {
+            if (!tool.chains.includes(chain))
+                issue(`Tool ${tool.id} cannot execute on declared chain ${chain}`, ['tools', position, 'chains']);
+            else if (!CHAIN_CAPABILITIES[chain].includes(tool.capability))
+                issue(`Capability ${tool.capability} of tool ${tool.id} is impossible on chain ${chain}`, ['tools', position, 'capability']);
+        }
+        if (tool.maximumCalls > manifest.limits.maximumRpcCalls)
+            issue(`Tool ${tool.id} exceeds the workflow call budget`, ['tools', position, 'maximumCalls']);
+    });
+    if (capabilities.has('http.read') !== manifest.permissions.domains.length > 0)
+        issue(capabilities.has('http.read') ? 'An http.read tool needs at least one allowed domain' : 'Domain grants require a declared http.read tool', ['permissions', 'domains']);
+    if (manifest.secrets.length && !capabilities.has('http.read'))
+        issue('Secret references are only usable by declared http.read tools', ['secrets']);
+    if (new Set(manifest.secrets.map((secret) => secret.name)).size !== manifest.secrets.length)
+        issue('Duplicate secret reference name', ['secrets']);
+    const aiNodes = manifest.workflow.filter((node) => node.type === 'ai-analysis');
+    if (aiNodes.length && manifest.modelPolicy.mode !== 'bounded-model')
+        issue('AI analysis nodes need a bounded-model policy', ['modelPolicy']);
+    if (!aiNodes.length && manifest.modelPolicy.mode !== 'deterministic')
+        issue('A bounded-model policy without AI analysis nodes grants an unused model budget', ['modelPolicy']);
+    const declaredModelTokens = aiNodes.reduce((total, node) => total + (node.type === 'ai-analysis' ? node.maximumTokens : 0), 0);
+    if (declaredModelTokens > manifest.modelPolicy.maximumModelTokens)
+        issue(`AI analysis nodes declare ${declaredModelTokens} output tokens but the model policy allows ${manifest.modelPolicy.maximumModelTokens}`, ['modelPolicy', 'maximumModelTokens']);
+    manifest.workflow.forEach((node, position) => { if (node.type === 'sandboxed-transform' && node.timeoutMs > manifest.limits.stepTimeoutMs)
+        issue(`Sandboxed transform ${node.id} timeout exceeds the step timeout`, ['workflow', position, 'timeoutMs']); });
+    const producedSections = new Map();
+    const nodeTarget = (id) => nodes.get(id)?.type;
+    manifest.workflow.forEach((node, position) => {
+        const at = (...rest) => ['workflow', position, ...rest];
+        for (const dependency of node.dependsOn) {
+            if (!nodes.has(dependency))
+                issue(`Node ${node.id} references missing dependency ${dependency}`, at('dependsOn'));
+            else if (['report-section', 'output'].includes(nodeTarget(dependency)) && node.type !== 'output')
+                issue(`Node ${node.id} cannot depend on ${nodeTarget(dependency)} node ${dependency}`, at('dependsOn'));
+        }
+        if (new Set(node.dependsOn).size !== node.dependsOn.length)
+            issue(`Node ${node.id} repeats a dependency`, at('dependsOn'));
+        if (node.type === 'input' && node.dependsOn.length)
+            issue('Input node cannot have dependencies', at('dependsOn'));
+        if (node.type !== 'input' && !node.dependsOn.length)
+            issue(`Node ${node.id} is disconnected from input`, at('dependsOn'));
+        if (node.type === 'tool' && !tools.has(node.tool) && !connectors.has(node.tool))
+            issue(`Undeclared tool ${node.tool}`, at('tool'));
+        // Item 10: fixed http.read URLs must already be inside the granted domains (bound URLs are checked by the runtime policy at call time).
+        if (node.type === 'tool' && tools.get(node.tool)?.capability === 'http.read')
+            for (const [key, binding] of Object.entries(node.arguments)) {
+                if (binding.source !== 'literal' || typeof binding.value !== 'string' || !/url/i.test(key))
+                    continue;
+                let host = null;
+                try {
+                    const url = new URL(binding.value);
+                    if (url.protocol === 'https:' && !url.username && !url.password && !url.port)
+                        host = url.hostname.toLowerCase();
+                }
+                catch {
+                    host = null;
+                }
+                if (host === null)
+                    issue(`Tool ${node.id} argument ${key} must be a credential-free https URL on the default port`, at('arguments', key));
+                else if (!manifest.permissions.domains.includes(host))
+                    issue(`Tool ${node.id} reads ${host}, which is outside the granted domains`, at('arguments', key));
+            }
+        if (node.type === 'condition') {
+            if (node.whenTrue === null && node.whenFalse === null)
+                issue('A condition needs at least one branch target', at());
+            for (const target of [node.whenTrue, node.whenFalse])
+                if (target !== null && !nodes.get(target)?.dependsOn.includes(node.id))
+                    issue(`Condition branch ${target} must exist and depend on ${node.id}`, at());
+            if (node.whenTrue !== null && node.whenTrue === node.whenFalse)
+                issue('Condition branches must differ', at());
+            if (node.operator === 'exists' && node.value !== undefined)
+                issue('An exists condition takes no comparison value', at('value'));
+            if (node.operator === 'equals' && node.value === undefined)
+                issue('Equality condition needs a value', at('value'));
+            if (['gt', 'lt', 'gte', 'lte'].includes(node.operator) && !isDecimal(node.value))
+                issue('Numeric conditions need an exact numeric value', at('value'));
+        }
+        if (node.type === 'report-section') {
+            const section = sections.get(node.section);
+            if (!section)
+                issue(`Report section ${node.section} is not declared in the output schema`, at('section'));
+            else
+                for (const finding of node.findings)
+                    if (!section.findings.some((item) => item.code === finding.code))
+                        issue(`Finding ${finding.code} is not declared in section ${node.section}`, at('findings'));
+            if (producedSections.has(node.section))
+                issue(`Section ${node.section} is produced by more than one node`, at('section'));
+            producedSections.set(node.section, node.id);
+            if (new Set(node.findings.map((finding) => finding.code)).size !== node.findings.length)
+                issue(`Duplicate finding in ${node.id}`, at('findings'));
+        }
+        if (node.type === 'output') {
+            for (const id of node.sections)
+                if (nodeTarget(id) !== 'report-section' || !node.dependsOn.includes(id))
+                    issue(`Output section ${id} must be a report-section dependency`, at('sections'));
+            if (node.dependsOn.some((id) => !node.sections.includes(id)))
+                issue('Output may depend only on its report sections', at('dependsOn'));
+        }
+        for (const binding of workflowBindings(node)) {
+            if (binding.source === 'node') {
+                if (!node.dependsOn.includes(binding.nodeId))
+                    issue(`Binding to ${binding.nodeId} must name an explicit dependency of ${node.id}`, at());
+                else if (!['tool', 'condition', 'transform', 'ai-analysis', 'sandboxed-transform'].includes(nodeTarget(binding.nodeId) ?? ''))
+                    issue(`Node ${binding.nodeId} produces no bindable value`, at());
+            }
+            if (binding.source === 'input' && !Object.hasOwn(manifest.inputSchema.properties, binding.path))
+                issue(`Unknown input property ${binding.path}`, at());
+            if (binding.source === 'literal' && typeof binding.value === 'string' && (/^0x[a-fA-F0-9]{64}$/.test(binding.value) || SECRET_CONTENT.test(binding.value)))
+                issue('Literal values cannot embed 32-byte secrets or credentials; bind them as inputs or secret references', at());
+        }
+        if (node.type === 'transform' && node.transform.op === 'threshold' && !isDecimal(node.transform.threshold))
+            issue('Threshold must be an exact decimal', at('transform'));
+        if (node.type === 'condition' && typeof node.value === 'string' && (/^0x[a-fA-F0-9]{64}$/.test(node.value) || SECRET_CONTENT.test(node.value)))
+            issue('Condition values cannot embed 32-byte secrets or credentials; bind them as inputs', at('value'));
+    });
+    for (const section of manifest.outputSchema.sections)
+        if (section.required && !producedSections.has(section.id))
+            issue(`Required section ${section.id} has no report-section node`, ['outputSchema', 'sections']);
+    const output = manifest.workflow.find((node) => node.type === 'output');
+    if (output?.type === 'output')
+        for (const section of manifest.outputSchema.sections) {
+            const producer = producedSections.get(section.id);
+            if (producer && !output.sections.includes(producer))
+                issue(`Section ${section.id} is not included in the output`, ['workflow', index.get(output.id), 'sections']);
+        }
+    const visiting = new Set();
+    const depths = new Map();
+    let cycle = false;
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            if (!cycle)
+                issue('Workflow contains a cycle', ['workflow']);
+            cycle = true;
+            return manifest.limits.maximumGraphDepth + 1;
+        }
+        const cached = depths.get(id);
+        if (cached !== undefined)
+            return cached;
+        visiting.add(id);
+        const depth = 1 + Math.max(0, ...(nodes.get(id)?.dependsOn ?? []).filter((dependency) => nodes.has(dependency)).map(visit));
+        visiting.delete(id);
+        depths.set(id, depth);
+        return depth;
+    };
+    for (const id of nodes.keys())
+        visit(id);
+    if (!cycle && Math.max(0, ...depths.values()) > manifest.limits.maximumGraphDepth)
+        issue('Workflow exceeds maximum graph depth', ['limits', 'maximumGraphDepth']);
+    const used = new Set();
+    const ancestors = (id) => { if (used.has(id))
+        return; used.add(id); for (const dependency of nodes.get(id)?.dependsOn ?? [])
+        ancestors(dependency); };
+    if (output)
+        ancestors(output.id);
+    for (const node of manifest.workflow)
+        if (!used.has(node.id))
+            issue(`Node ${node.id} does not contribute to the output`, ['workflow', index.get(node.id)]);
+    manifest.sampleOutput.forEach((sample, position) => {
+        const section = sections.get(sample.section);
+        if (!section) {
+            issue(`Sample section ${sample.section} is not declared`, ['sampleOutput', position]);
+            return;
+        }
+        for (const [code, value] of Object.entries(sample.findings)) {
+            const declared = section.findings.find((finding) => finding.code === code);
+            if (!declared)
+                issue(`Sample finding ${code} is not declared in ${sample.section}`, ['sampleOutput', position]);
+            else if (!findingValueMatches(value, declared.valueType))
+                issue(`Sample finding ${code} must be a ${declared.valueType}`, ['sampleOutput', position]);
+        }
+    });
+    manifest.testCases.forEach((testCase, position) => { if (!manifest.chains.includes(testCase.chain))
+        issue(`Test case ${testCase.id} uses an undeclared chain`, ['testCases', position]); });
+    if (manifest.presentation)
+        for (const item of presentationIssues(manifest.presentation, manifest))
+            issue(item.message, item.path);
+    const serialized = JSON.stringify({ ...manifest, secrets: manifest.secrets.map((secret) => ({ ...secret, reference: '' })) });
+    if (SECRET_CONTENT.test(serialized))
+        issue('The package appears to embed a credential. Secrets must be references in private bindings, never values.', []);
+});
+export function workflowBindings(node) {
+    switch (node.type) {
+        case 'tool': return Object.values(node.arguments);
+        case 'condition': return [node.field];
+        case 'report-section': return node.findings.map((finding) => finding.value);
+        case 'ai-analysis':
+        case 'sandboxed-transform': return Object.values(node.inputs);
+        case 'transform': {
+            const t = node.transform;
+            return t.op === 'pick' ? [t.from] : t.op === 'compare' ? [t.left, t.right] : t.op === 'threshold' ? [t.value] : [t.amount, t.decimals];
+        }
+        default: return [];
+    }
+}
+export const isWorkflowManifest = (manifest) => manifest !== null && typeof manifest === 'object' && manifest.outputSchemaId === WORKFLOW_SCHEMA_ID;
+/** Exact decimal helpers. Never floating point: numbers are only accepted when they are safe integers or already exact finite literals. */
+export function isDecimal(value) {
+    return (typeof value === 'number' && Number.isFinite(value) && /^-?\d+(\.\d+)?$/.test(String(value))) || (typeof value === 'string' && /^-?(0|[1-9][0-9]{0,77})(\.[0-9]{1,78})?$/.test(value));
+}
+function scaled(value, scale) {
+    const text = String(value);
+    const negative = text.startsWith('-');
+    const [whole, fraction = ''] = (negative ? text.slice(1) : text).split('.');
+    const result = BigInt(whole + fraction.padEnd(scale, '0'));
+    return negative ? -result : result;
+}
+/** Compares two exact decimals; returns -1, 0 or 1. */
+export function compareDecimal(left, right) {
+    const scale = Math.max(String(left).split('.')[1]?.length ?? 0, String(right).split('.')[1]?.length ?? 0);
+    const a = scaled(left, scale);
+    const b = scaled(right, scale);
+    return a === b ? 0 : a > b ? 1 : -1;
+}
+/** Formats an unsigned atomic integer with `decimals` places exactly, trimming only trailing fractional zeros. */
+export function formatExactAmount(atomic, decimals) {
+    if (!/^(0|[1-9][0-9]{0,77})$/.test(String(atomic)) || !Number.isSafeInteger(decimals) || decimals < 0 || decimals > 255)
+        throw new RangeError('Expected an unsigned atomic integer and 0-255 decimals');
+    const digits = String(atomic).padStart(decimals + 1, '0');
+    const whole = digits.slice(0, digits.length - decimals);
+    const fraction = decimals ? digits.slice(-decimals).replace(/0+$/, '') : '';
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+export function findingValueMatches(value, type) {
+    if (type === 'boolean')
+        return typeof value === 'boolean';
+    if (type === 'string')
+        return typeof value === 'string';
+    if (type === 'integer')
+        return (typeof value === 'number' && Number.isSafeInteger(value)) || (typeof value === 'string' && /^-?(0|[1-9][0-9]{0,77})$/.test(value));
+    if (type === 'decimal')
+        return isDecimal(value);
+    return typeof value === 'string' && (isAddress(value) || /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value));
+}
+/** Run input envelope. `values` are validated against the pinned manifest's input schema by `parseWorkflowRunInput`. */
+export const WorkflowRunInputSchema = z.strictObject({ workflow: z.literal(WORKFLOW_SCHEMA_ID), chain: WorkflowChainKeySchema, values: z.record(PropertyIdentifier, Scalar) });
+export function parseWorkflowRunInput(raw, manifest) {
+    const input = WorkflowRunInputSchema.parse(raw);
+    const issues = [];
+    const add = (path, message) => issues.push({ code: 'custom', path, message, input: undefined });
+    if (!manifest.chains.includes(input.chain))
+        add(['chain'], `Chain ${input.chain} is outside the version's declared chains`);
+    const { properties, required } = manifest.inputSchema;
+    for (const key of required)
+        if (input.values[key] === undefined || input.values[key] === '')
+            add(['values', key], `${key} is required`);
+    for (const [key, value] of Object.entries(input.values)) {
+        const field = properties[key];
+        if (!field) {
+            add(['values', key], `Unknown input ${key}`);
+            continue;
+        }
+        const ok = field.type === 'boolean' ? typeof value === 'boolean' : field.type === 'integer' ? typeof value === 'string' && /^(0|[1-9][0-9]{0,77})$/.test(value)
+            : field.type === 'evm-address' ? typeof value === 'string' && isAddress(value) : field.type === 'solana-address' ? typeof value === 'string' && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value)
+                : typeof value === 'string' && value.length <= 200 && (!field.enum || field.enum.includes(value));
+        if (!ok)
+            add(['values', key], `${key} must be a valid ${field.type}${field.enum ? ` (${field.enum.join(', ')})` : ''}`);
+        if (field.type === 'evm-address' && ['solana'].includes(input.chain))
+            add(['values', key], `${key} is an EVM address but the selected chain is Solana`);
+        if (field.type === 'solana-address' && input.chain !== 'solana')
+            add(['values', key], `${key} is a Solana address but the selected chain is EVM`);
+    }
+    if (issues.length)
+        throw new z.ZodError(issues);
+    return input;
+}
+/**
+ * F02 evidence envelope produced by every registry tool. It mirrors `agentex.tool-evidence.v1` in packages/tools/src/evidence.ts,
+ * which owns construction (`makeToolEvidence`); keep both definitions identical. Ids derive from the artifact hash, so neither a
+ * tool, a node nor a model can invent or reuse one. Contracts keep a copy so reports validate without tool implementations.
+ */
+export const TOOL_EVIDENCE_VERSION = 'agentex.tool-evidence.v1';
+const Exact = z.string().regex(/^(0|[1-9][0-9]{0,77})$/);
+export const ToolSnapshotSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('evm-block'), chainId: z.number().int().positive(), blockNumber: Exact, blockHash: z.string().regex(/^0x[a-f0-9]{64}$/), timestamp: Exact.nullable() }),
+    // New Solana reads use `confirmed` commitment (instant-read rule); `finalized` parses evidence captured before the rule.
+    z.strictObject({ kind: z.literal('solana-slot'), genesisHash: z.string().min(32).max(44), slot: Exact, commitment: z.enum(['finalized', 'confirmed']), exactness: z.enum(['observed-context', 'lower-bound']) }),
+    z.strictObject({ kind: z.literal('http-retrieval'), retrievedAt: z.iso.datetime() }),
+    z.strictObject({ kind: z.literal('offline-input'), inputHash: Hash }),
+]);
+export const ToolEvidenceCompletenessSchema = z.enum(['complete-for-request', 'truncated', 'empty-result', 'unavailable', 'error']);
+const ToolEvidenceFields = {
+    schemaVersion: z.literal(TOOL_EVIDENCE_VERSION), id: z.string().regex(/^ev-[a-f0-9]{32}$/, 'Evidence ids are content-derived (ev- and 32 hex characters).'), tool: ToolRef, capability: ToolCapabilitySchema,
+    source: z.strictObject({ kind: z.enum(['rpc', 'http', 'offline']), provider: z.string().min(1).max(253).regex(/^[a-zA-Z0-9.:-]+$/), method: z.string().min(1).max(64), documentationUrl: z.url().nullable() }),
+    chain: z.string().regex(/^[a-z][a-z0-9-]{1,31}$/),
+    scope: z.strictObject({
+        subjects: z.array(z.string().min(1).max(128)).max(16),
+        window: z.strictObject({ unit: z.enum(['block', 'slot']), from: Exact, to: Exact }).nullable(),
+        page: z.strictObject({ index: z.number().int().min(0).max(1000), size: z.number().int().min(1).max(1000), cursor: z.string().max(128).nullable() }).nullable(),
+    }),
+    request: z.json(), snapshot: ToolSnapshotSchema.nullable(), observedAt: z.iso.datetime(),
+    // New runs record `sequencer-confirmed` (EVM latest block), `confirmed` or `confirmed-lower-bound` (Solana). The `finalized` values parse older evidence.
+    finality: z.enum(['finalized', 'finalized-lower-bound', 'sequencer-confirmed', 'confirmed', 'confirmed-lower-bound', 'unverified', 'not-applicable']),
+    canonicality: z.enum(['verified-at-completion', 'unchecked', 'changed', 'not-applicable']),
+    completeness: ToolEvidenceCompletenessSchema, errorCategory: z.string().regex(/^[a-z][a-z-]{1,63}$/).nullable(),
+    result: z.json(), contentHash: Hash, artifactHash: Hash,
+    privacy: z.enum(['public-chain-data', 'public-web-content', 'private-input']),
+    trust: z.enum(['chain-state', 'provider-assertion', 'untrusted-third-party-content', 'offline-decoding']),
+};
+/** Canonicality is excluded: it is the only field a completion recheck may legitimately change. */
+export function toolArtifactHash(item) { const { id: _id, artifactHash: _artifact, canonicality: _canonicality, ...rest } = item; return contentHash(rest); }
+export const ToolEvidenceItemSchema = z.strictObject(ToolEvidenceFields).superRefine((item, ctx) => {
+    if (contentHash(item.result) !== item.contentHash)
+        ctx.addIssue({ code: 'custom', path: ['contentHash'], message: 'Evidence content hash does not match its captured result.' });
+    if (toolArtifactHash(item) !== item.artifactHash)
+        ctx.addIssue({ code: 'custom', path: ['artifactHash'], message: 'Evidence artifact hash does not match its envelope.' });
+    if (item.id !== `ev-${item.artifactHash.slice(0, 32)}`)
+        ctx.addIssue({ code: 'custom', path: ['id'], message: 'Evidence id is not derived from its artifact hash.' });
+    if ((item.completeness === 'error' || item.completeness === 'unavailable') !== (item.errorCategory !== null))
+        ctx.addIssue({ code: 'custom', path: ['errorCategory'], message: 'Only failed or unavailable evidence carries an error category.' });
+    if ((item.finality === 'finalized' || item.finality === 'confirmed') && item.snapshot?.kind !== 'evm-block' && !(item.snapshot?.kind === 'solana-slot' && item.snapshot.exactness === 'observed-context'))
+        ctx.addIssue({ code: 'custom', path: ['finality'], message: 'Evidence with a confirmation level needs an exact block or observed slot context.' });
+    if (item.finality === 'sequencer-confirmed' && item.snapshot?.kind !== 'evm-block')
+        ctx.addIssue({ code: 'custom', path: ['finality'], message: 'Sequencer-confirmed evidence needs the pinned EVM block.' });
+    if (item.capability === 'http.read' && (item.privacy !== 'public-web-content' || item.trust !== 'untrusted-third-party-content'))
+        ctx.addIssue({ code: 'custom', path: ['trust'], message: 'Web content is always untrusted third-party content.' });
+});
+export const WorkflowErrorCategorySchema = z.enum([...FailureCategorySchema.options, 'permission-denied', 'invalid-arguments', 'invalid-tool-output', 'invented-evidence', 'unregistered-tool', 'model-unconfigured', 'step-timeout', 'condition-unknown', 'model-failed', 'sandbox-unavailable', 'sandbox-failed']);
+const FindingResultSchema = z.discriminatedUnion('status', [
+    z.strictObject({ code: Identifier, label: z.string(), status: z.literal('observed'), value: Scalar, evidenceIds: z.array(z.string()).min(1) }),
+    z.strictObject({ code: Identifier, label: z.string(), status: z.literal('from-input'), value: Scalar, evidenceIds: z.array(z.string()).length(0) }),
+    z.strictObject({ code: Identifier, label: z.string(), status: z.enum(['unknown', 'not-run']), reason: z.string().max(500), evidenceIds: z.array(z.string()) }),
+]);
+export const WorkflowStepSchema = z.strictObject({
+    nodeId: Identifier, type: z.enum(['input', 'tool', 'condition', 'transform', 'report-section', 'ai-analysis', 'output', 'sandboxed-transform']), tool: ToolRef.nullable(),
+    status: z.enum(['succeeded', 'skipped', 'failed', 'disabled']), reason: z.string().max(500).nullable(), branch: z.enum(['true', 'false', 'unknown']).nullable(),
+    rpcCalls: z.number().int().nonnegative(), evidenceIds: z.array(z.string()), elapsedMs: z.number().int().nonnegative(),
+});
+export const WorkflowReportSchema = z.strictObject({
+    schemaVersion: z.literal(WORKFLOW_SCHEMA_ID), agentVersion: Semver, manifestHash: Hash, input: WorkflowRunInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(),
+    requiredSections: z.array(Identifier).max(12),
+    sections: z.array(z.strictObject({ id: Identifier, title: z.string(), status: z.enum(['complete', 'partial', 'skipped', 'failed']), reason: z.string().max(500).nullable(), findings: z.array(FindingResultSchema).max(16) })).max(12),
+    steps: z.array(WorkflowStepSchema).max(32), evidence: z.array(ToolEvidenceItemSchema).max(128),
+    errors: z.array(z.strictObject({ category: WorkflowErrorCategorySchema, message: z.string().max(1000), step: z.string().max(100), evidenceId: z.string().optional() })).max(64),
+    limitations: z.array(z.string().max(1000)).max(16),
+    usage: z.strictObject({ rpcCalls: z.number().int().nonnegative(), maximumRpcCalls: z.number().int().positive(), toolExecutions: z.number().int().nonnegative(), elapsedMs: z.number().int().nonnegative(), modelTokens: z.number().int().nonnegative(), providerCostAtomic: z.null(), providerCostStatus: z.literal('unpriced'),
+        /** Metered model cost of executed AI analysis nodes (micro-USD). Absent on reports without model work. */
+        modelCostMicrousd: z.number().int().nonnegative().optional() }),
+    /** R01: present when the version declares a presentation. Rows and signals cite the evidence of the step that produced them. */
+    presentation: ReportPresentationSchema.optional(), datasets: z.array(ReportDatasetSchema).max(8).optional(), signals: z.array(ReportSignalSchema).max(32).optional(), coverage: z.array(ReportCoverageSchema).max(4).optional(),
+}).superRefine((report, ctx) => {
+    const issue = (message) => ctx.addIssue({ code: 'custom', message });
+    const ids = new Set(report.evidence.map((item) => item.id));
+    if (ids.size !== report.evidence.length)
+        issue('Duplicate evidence id');
+    const owners = new Map();
+    for (const step of report.steps)
+        for (const id of step.evidenceIds) {
+            if (!ids.has(id))
+                issue(`Step ${step.nodeId} references unknown evidence ${id}`);
+            if (step.type !== 'tool')
+                issue(`Only tool executions produce evidence; ${step.nodeId} is a ${step.type} step`);
+            if (owners.has(id))
+                issue(`Evidence ${id} is claimed by more than one step`);
+            owners.set(id, step.nodeId);
+        }
+    for (const item of report.evidence) {
+        if (!owners.has(item.id))
+            issue(`Evidence ${item.id} was not produced by a recorded tool execution`);
+        if (contentHash(item.result) !== item.contentHash)
+            issue('Evidence content hash does not match its captured result');
+        if (item.chain !== report.input.chain)
+            issue('Evidence chain differs from the accepted input chain');
+    }
+    for (const section of report.sections)
+        for (const finding of section.findings)
+            for (const id of finding.evidenceIds)
+                if (!ids.has(id))
+                    issue(`Unknown evidence reference ${id}`);
+    for (const error of report.errors)
+        if (error.evidenceId && !ids.has(error.evidenceId))
+            issue(`Unknown error evidence reference ${error.evidenceId}`);
+    for (const item of [...(report.datasets ?? []), ...(report.signals ?? [])])
+        for (const id of item.evidenceIds)
+            if (!ids.has(id))
+                issue(`Unknown presentation evidence reference ${id}`);
+    if (report.usage.rpcCalls > report.usage.maximumRpcCalls)
+        issue('RPC usage exceeds the immutable budget');
+    const modelRan = report.steps.some((step) => step.type === 'ai-analysis' && (step.status === 'succeeded' || step.status === 'failed'));
+    if (!modelRan && (report.usage.modelTokens > 0 || (report.usage.modelCostMicrousd ?? 0) > 0))
+        issue('Model usage was recorded without an executed AI analysis step');
+    if (report.steps.some((step) => step.type === 'ai-analysis' && step.status === 'succeeded') && report.errors.some((error) => error.category === 'model-unconfigured'))
+        issue('AI analysis cannot succeed while the model provider is unconfigured');
+    if (report.status === 'complete' && report.requiredSections.some((id) => report.sections.find((section) => section.id === id)?.status !== 'complete'))
+        issue('A complete report needs every required section complete');
+});
+export const SANDBOX_UNAVAILABLE = 'Custom code steps are not available on this server, so sandboxed transform steps stay switched off. Creator code only ever runs inside the isolated sandbox.';
+export const MODEL_MINIMUM_OUTPUT_TOKENS = 256;
+/** Effective permissions, derived only from typed fields and server capabilities. Listing text, names and descriptions are never consulted. */
+export function workflowPermissions(manifest, capabilities = {}) {
+    const toolNodes = manifest.workflow.filter((node) => node.type === 'tool');
+    const aiNodes = manifest.workflow.filter((node) => node.type === 'ai-analysis');
+    const sandboxNodes = manifest.workflow.filter((node) => node.type === 'sandboxed-transform');
+    return {
+        capabilities: [...new Set(manifest.tools.map((tool) => tool.capability))].sort(), chains: [...manifest.chains],
+        tools: manifest.tools.map((tool) => ({ ref: `${tool.id}@${tool.version}`, capability: tool.capability, maximumCalls: tool.maximumCalls, executions: toolNodes.filter((node) => node.type === 'tool' && node.tool === tool.id).length })),
+        addressScope: manifest.permissions.addressScope, addressInputs: Object.entries(manifest.inputSchema.properties).filter(([, field]) => field.type.endsWith('-address')).map(([key]) => key),
+        domains: [...manifest.permissions.domains], destinations: [...manifest.permissions.destinations], secrets: manifest.secrets.map((secret) => ({ name: secret.name, reference: secret.reference })),
+        budget: { maximumRpcCalls: manifest.limits.maximumRpcCalls, maximumSteps: manifest.limits.maximumSteps, maximumDurationMs: manifest.limits.maximumDurationMs, stepTimeoutMs: manifest.limits.stepTimeoutMs, maximumBlockRange: manifest.limits.maximumBlockRange, maximumPages: manifest.limits.maximumPages, maximumExecutionAtomic: manifest.limits.maximumExecutionAtomic, maximumModelTokens: manifest.modelPolicy.maximumModelTokens },
+        aiAnalysis: { declared: aiNodes.length, enabled: aiNodes.length > 0 && capabilities.modelAnalysis === true, tools: [],
+            reason: !aiNodes.length ? null : capabilities.modelAnalysis ? 'Bounded model synthesis of captured evidence only: no tools, no network, output tokens capped by the model policy.' : MODEL_PROVIDER_UNCONFIGURED },
+        sandboxedTransforms: { declared: sandboxNodes.length, enabled: sandboxNodes.length > 0 && capabilities.sandboxedTransforms === true, network: 'none',
+            reason: !sandboxNodes.length ? null : capabilities.sandboxedTransforms ? 'Runs in the isolated sandbox: no network, read-only filesystem, CPU, memory and time limits.' : SANDBOX_UNAVAILABLE },
+        connectors: (manifest.connectors ?? []).map((connector) => ({ alias: connector.id, connectorId: connector.connectorId, schemaHash: connector.schemaHash, maximumCalls: connector.maximumCalls, maximumCostMicrousd: connector.maximumCostMicrousd,
+            executions: toolNodes.filter((node) => node.type === 'tool' && node.tool === connector.id).length, enabled: capabilities.connectors === true,
+            reason: capabilities.connectors ? 'Reviewed remote tool behind the connector gateway: pinned approved version, SSRF-safe egress, untrusted output, metered per call.' : CONNECTORS_DISABLED })),
+        signing: false, broadcasting: false,
+    };
+}
+/** Worst-case RPC attempts: every tool execution at its declared ceiling, bounded by the workflow budget. Provider cost stays unpriced. */
+export function estimateWorkflowRpcCost(manifest) {
+    const tools = new Map(manifest.tools.map((tool) => [tool.id, tool]));
+    const connectors = new Map((manifest.connectors ?? []).map((connector) => [connector.id, connector]));
+    // N03: each connector call is one metered operation against the same run RPC budget.
+    const steps = manifest.workflow.flatMap((node) => node.type === 'tool' ? [{ nodeId: node.id, tool: node.tool, maximumCalls: tools.get(node.tool)?.maximumCalls ?? connectors.get(node.tool)?.maximumCalls ?? 0 }] : []);
+    const declared = steps.reduce((total, step) => total + step.maximumCalls, 0);
+    return { steps, declaredMaximum: declared, maximumRpcCalls: Math.min(declared, manifest.limits.maximumRpcCalls), budgetBinding: declared > manifest.limits.maximumRpcCalls, providerCostAtomic: null, providerCostStatus: 'unpriced' };
+}
+/** Blocking reasons for creating an immutable test version or executing. Drafts may still contain disabled declarations. */
+export function workflowExecutionBlockers(manifest, capabilities = {}) {
+    const connectorBlockers = manifest.connectors?.length && !capabilities.connectors ? [`Connectors ${manifest.connectors.map((connector) => connector.id).join(', ')}: ${CONNECTORS_DISABLED}`] : [];
+    return [...connectorBlockers, ...manifest.workflow.flatMap((node) => {
+            if (node.type === 'ai-analysis')
+                return !capabilities.modelAnalysis ? [`Node ${node.id}: ${MODEL_PROVIDER_UNCONFIGURED}`]
+                    : node.maximumTokens < MODEL_MINIMUM_OUTPUT_TOKENS ? [`Node ${node.id}: AI analysis needs at least ${MODEL_MINIMUM_OUTPUT_TOKENS} maximum output tokens.`] : [];
+            if (node.type === 'sandboxed-transform' && !capabilities.sandboxedTransforms)
+                return [`Node ${node.id}: ${SANDBOX_UNAVAILABLE}`];
+            return [];
+        })];
+}
+/** Structured validation for editors: returns every issue with its JSON path, never throws. */
+export function validateWorkflowManifest(raw) {
+    const parsed = WorkflowManifestSchema.safeParse(raw);
+    return parsed.success ? { ok: true, manifest: parsed.data, issues: [] } : { ok: false, issues: parsed.error.issues.map((item) => ({ path: item.path.map(String).join('.'), message: item.message })) };
+}
+/**
+ * Buyer result contract for workflow runs: a non-failed report bound to its manifest in which every required section is complete,
+ * every finding is observed (citing complete captured tool evidence) or taken from input, at least one finding is tool-observed,
+ * and no policy/integrity failure or disabled model step occurred. Returns the unmet conditions; an empty list satisfies it.
+ */
+export function workflowResultContractIssues(raw, manifest) {
+    const parsed = WorkflowReportSchema.safeParse(raw);
+    if (!parsed.success)
+        return ['The report does not match agentex.workflow.v1.'];
+    const report = parsed.data;
+    const issues = [];
+    if (report.status === 'failed')
+        issues.push('The run failed.');
+    if (manifest) {
+        if (contentHash(manifest) !== report.manifestHash || manifest.version !== report.agentVersion)
+            issues.push('The report is not bound to this manifest.');
+        const required = manifest.outputSchema.sections.filter((section) => section.required).map((section) => section.id).sort();
+        if (contentHash(required) !== contentHash([...report.requiredSections].sort()))
+            issues.push('Required sections differ from the manifest.');
+        try {
+            parseWorkflowRunInput(report.input, manifest);
+        }
+        catch {
+            issues.push('The report input is outside the manifest input schema.');
+        }
+    }
+    if (!report.requiredSections.length)
+        issues.push('The output schema declares no required section.');
+    const evidence = new Map(report.evidence.map((item) => [item.id, item]));
+    for (const id of report.requiredSections) {
+        const section = report.sections.find((item) => item.id === id);
+        if (!section || section.status !== 'complete') {
+            issues.push(`Required section ${id} is not complete.`);
+            continue;
+        }
+        for (const finding of section.findings) {
+            if (finding.status !== 'observed' && finding.status !== 'from-input')
+                issues.push(`Finding ${id}.${finding.code} is ${finding.status}.`);
+            else if (finding.status === 'observed' && finding.evidenceIds.some((ref) => !['complete-for-request', 'empty-result'].includes(evidence.get(ref)?.completeness ?? '')))
+                issues.push(`Finding ${id}.${finding.code} cites incomplete evidence.`);
+        }
+    }
+    if (!report.sections.some((section) => section.findings.some((finding) => finding.status === 'observed')))
+        issues.push('No finding is backed by tool evidence.');
+    if (report.evidence.some((item) => item.canonicality === 'changed'))
+        issues.push('Captured evidence changed canonicality.');
+    if (report.errors.some((error) => ['permission-denied', 'invented-evidence', 'invalid-tool-output', 'model-unconfigured', 'unregistered-tool', 'sandbox-unavailable'].includes(error.category)))
+        issues.push('The run recorded a policy, integrity or disabled-capability failure.');
+    return issues;
+}