@aionis/manifest 0.1.1

package/dist/execute/moduleRuntime.js

@@ -0,0 +1,352 @@
+import { validateExecutionModuleManifest } from "../contracts.js";
+import { AIONIS_MANIFEST_EXECUTION_RESULT_VERSION, } from "./types.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getPathValue(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!isObject(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+export function resolveExecutionInput(plan, outputs, step) {
+    if (step.input)
+        return step.input;
+    if (!step.input_ref)
+        return {};
+    if (step.input_ref === "ctx")
+        return plan.context.merged;
+    if (step.input_ref.startsWith("ctx.")) {
+        return getPathValue(plan.context.merged, step.input_ref.slice(4).split(".")) ?? null;
+    }
+    if (step.input_ref in outputs)
+        return outputs[step.input_ref];
+    const [rootRef, ...rest] = step.input_ref.split(".");
+    if ((rootRef === "run" || rootRef === "out") && rest.length > 1) {
+        const candidate = `${rootRef}.${rest[0]}`;
+        if (candidate in outputs) {
+            return getPathValue(outputs[candidate], rest.slice(1)) ?? null;
+        }
+    }
+    return null;
+}
+function missingDependency(step, outputs) {
+    for (const dependency of step.depends_on) {
+        if (!(dependency in outputs))
+            return dependency;
+    }
+    return null;
+}
+function contractPath(path, segment) {
+    return path === "$" ? `$.${segment}` : `${path}.${segment}`;
+}
+function validateValueAgainstContract(value, contract, path = "$") {
+    switch (contract.kind) {
+        case "any":
+            return [];
+        case "string":
+            return typeof value === "string" ? [] : [`Expected string at '${path}'.`];
+        case "number":
+            return typeof value === "number" ? [] : [`Expected number at '${path}'.`];
+        case "boolean":
+            return typeof value === "boolean" ? [] : [`Expected boolean at '${path}'.`];
+        case "null":
+            return value === null ? [] : [`Expected null at '${path}'.`];
+        case "array": {
+            if (!Array.isArray(value))
+                return [`Expected array at '${path}'.`];
+            if (!contract.items)
+                return [];
+            return value.flatMap((item, index) => validateValueAgainstContract(item, contract.items, `${path}[${index}]`));
+        }
+        case "object": {
+            if (!isObject(value))
+                return [`Expected object at '${path}'.`];
+            const errors = [];
+            const properties = contract.properties ?? {};
+            const required = new Set(contract.required ?? []);
+            for (const key of required) {
+                if (!(key in value))
+                    errors.push(`Missing required property '${key}' at '${path}'.`);
+            }
+            for (const [key, propertyContract] of Object.entries(properties)) {
+                if (!(key in value))
+                    continue;
+                errors.push(...validateValueAgainstContract(value[key], propertyContract, contractPath(path, key)));
+            }
+            if (contract.additional_properties === false) {
+                for (const key of Object.keys(value)) {
+                    if (!(key in properties))
+                        errors.push(`Unexpected property '${key}' at '${path}'.`);
+                }
+            }
+            return errors;
+        }
+    }
+}
+function missingModuleCapabilities(manifest, capabilities) {
+    return (manifest.required_capabilities ?? []).filter((capability) => !capabilities[capability]);
+}
+function isModuleOutcome(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        "kind" in value &&
+        value.kind === "module_result" &&
+        "output" in value);
+}
+export function createExecutionRuntimeCapabilities(overrides = {}) {
+    return {
+        direct_execution: true,
+        deterministic_replay: false,
+        state_persistence: false,
+        memory_publish: false,
+        handoff_recover: false,
+        module_registry: true,
+        evidence_capture: false,
+        ...overrides,
+    };
+}
+export class StaticModuleRegistry {
+    #modules;
+    constructor(modules) {
+        this.#modules = new Map(modules.map((definition) => {
+            validateExecutionModuleManifest(definition.manifest);
+            return [definition.manifest.module, definition];
+        }));
+    }
+    has(moduleName) {
+        return this.#modules.has(moduleName);
+    }
+    get(moduleName) {
+        return this.#modules.get(moduleName);
+    }
+    getManifest(moduleName) {
+        return this.#modules.get(moduleName)?.manifest;
+    }
+    list() {
+        return [...this.#modules.values()];
+    }
+    listManifests() {
+        return this.list().map((definition) => definition.manifest);
+    }
+}
+export class ModuleRegistryExecutionRuntime {
+    runtime_id;
+    #registry;
+    #capabilities;
+    constructor(args) {
+        this.runtime_id = args.runtime_id;
+        this.#registry = args.registry;
+        this.#capabilities = createExecutionRuntimeCapabilities(args.capabilities);
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    async execute(plan) {
+        const outputs = {};
+        const artifacts = [];
+        const evidence = [];
+        const nodeResults = [];
+        const errors = [];
+        for (const step of plan.executions) {
+            const unmetDependency = missingDependency(step, outputs);
+            if (unmetDependency) {
+                const message = `Execution '${step.execution_id}' is blocked on missing dependency '${unmetDependency}'.`;
+                nodeResults.push({
+                    execution_id: step.execution_id,
+                    module: step.module,
+                    tool: step.tool,
+                    agent: step.agent,
+                    status: "failed",
+                    input_ref: step.input_ref,
+                    output_ref: step.output_ref,
+                    error: message,
+                });
+                errors.push(message);
+                continue;
+            }
+            if (!step.module) {
+                const message = `Execution '${step.execution_id}' has no module and cannot run on runtime '${this.runtime_id}'.`;
+                nodeResults.push({
+                    execution_id: step.execution_id,
+                    module: step.module,
+                    tool: step.tool,
+                    agent: step.agent,
+                    status: "failed",
+                    input_ref: step.input_ref,
+                    output_ref: step.output_ref,
+                    error: message,
+                });
+                errors.push(message);
+                continue;
+            }
+            const definition = this.#registry.get(step.module);
+            if (!definition) {
+                const message = `Module '${step.module}' is not supported by runtime '${this.runtime_id}'.`;
+                nodeResults.push({
+                    execution_id: step.execution_id,
+                    module: step.module,
+                    tool: step.tool,
+                    agent: step.agent,
+                    status: "failed",
+                    input_ref: step.input_ref,
+                    output_ref: step.output_ref,
+                    error: message,
+                });
+                errors.push(message);
+                continue;
+            }
+            const missingCapabilities = missingModuleCapabilities(definition.manifest, this.#capabilities);
+            if (missingCapabilities.length > 0) {
+                const message = `Module '${step.module}' requires unsupported runtime capabilities: ${missingCapabilities.join(", ")}.`;
+                nodeResults.push({
+                    execution_id: step.execution_id,
+                    module: step.module,
+                    tool: step.tool,
+                    agent: step.agent,
+                    status: "failed",
+                    input_ref: step.input_ref,
+                    output_ref: step.output_ref,
+                    error: message,
+                });
+                errors.push(message);
+                continue;
+            }
+            const input = resolveExecutionInput(plan, outputs, step);
+            if (definition.manifest.input_contract) {
+                const inputErrors = validateValueAgainstContract(input, definition.manifest.input_contract);
+                if (inputErrors.length > 0) {
+                    const message = `Input contract validation failed for module '${step.module}': ${inputErrors.join(" ")}`;
+                    nodeResults.push({
+                        execution_id: step.execution_id,
+                        module: step.module,
+                        tool: step.tool,
+                        agent: step.agent,
+                        status: "failed",
+                        input_ref: step.input_ref,
+                        output_ref: step.output_ref,
+                        error: message,
+                    });
+                    errors.push(message);
+                    continue;
+                }
+            }
+            const context = {
+                plan,
+                step,
+                outputs,
+                runtime_id: this.runtime_id,
+            };
+            const rawResult = await definition.handler(input, context);
+            const normalized = isModuleOutcome(rawResult)
+                ? rawResult
+                : {
+                    kind: "module_result",
+                    output: rawResult,
+                    artifacts: [],
+                    evidence: [],
+                };
+            const output = normalized.output;
+            const producedArtifacts = normalized.artifacts ?? [];
+            const producedEvidence = normalized.evidence ?? [];
+            if (definition.manifest.output_contract) {
+                const outputErrors = validateValueAgainstContract(output, definition.manifest.output_contract);
+                if (outputErrors.length > 0) {
+                    const message = `Output contract validation failed for module '${step.module}': ${outputErrors.join(" ")}`;
+                    nodeResults.push({
+                        execution_id: step.execution_id,
+                        module: step.module,
+                        tool: step.tool,
+                        agent: step.agent,
+                        status: "failed",
+                        input_ref: step.input_ref,
+                        output_ref: step.output_ref,
+                        error: message,
+                    });
+                    errors.push(message);
+                    continue;
+                }
+            }
+            if (definition.manifest.artifact_contract) {
+                const artifactErrors = producedArtifacts.flatMap((value, index) => validateValueAgainstContract(value, definition.manifest.artifact_contract, `artifacts[${index}]`));
+                if (artifactErrors.length > 0) {
+                    const message = `Artifact contract validation failed for module '${step.module}': ${artifactErrors.join(" ")}`;
+                    nodeResults.push({
+                        execution_id: step.execution_id,
+                        module: step.module,
+                        tool: step.tool,
+                        agent: step.agent,
+                        status: "failed",
+                        input_ref: step.input_ref,
+                        output_ref: step.output_ref,
+                        error: message,
+                    });
+                    errors.push(message);
+                    continue;
+                }
+            }
+            if (definition.manifest.evidence_contract) {
+                const evidenceErrors = producedEvidence.flatMap((value, index) => validateValueAgainstContract(value, definition.manifest.evidence_contract, `evidence[${index}]`));
+                if (evidenceErrors.length > 0) {
+                    const message = `Evidence contract validation failed for module '${step.module}': ${evidenceErrors.join(" ")}`;
+                    nodeResults.push({
+                        execution_id: step.execution_id,
+                        module: step.module,
+                        tool: step.tool,
+                        agent: step.agent,
+                        status: "failed",
+                        input_ref: step.input_ref,
+                        output_ref: step.output_ref,
+                        error: message,
+                    });
+                    errors.push(message);
+                    continue;
+                }
+            }
+            if (step.output_ref)
+                outputs[step.output_ref] = output;
+            artifacts.push(...producedArtifacts.map((value) => ({
+                execution_id: step.execution_id,
+                module: step.module,
+                value,
+            })));
+            evidence.push(...producedEvidence.map((value) => ({
+                execution_id: step.execution_id,
+                module: step.module,
+                value,
+            })));
+            nodeResults.push({
+                execution_id: step.execution_id,
+                module: step.module,
+                tool: step.tool,
+                agent: step.agent,
+                status: "success",
+                input_ref: step.input_ref,
+                output_ref: step.output_ref,
+                output,
+                artifacts: producedArtifacts,
+                evidence: producedEvidence,
+            });
+        }
+        return {
+            execution_result_version: AIONIS_MANIFEST_EXECUTION_RESULT_VERSION,
+            runtime_id: this.runtime_id,
+            executed_at: new Date().toISOString(),
+            plan_version: plan.plan_version,
+            doc_id: plan.doc?.id ?? null,
+            status: errors.length > 0 ? "failed" : "success",
+            outputs,
+            artifacts,
+            evidence,
+            node_results: nodeResults,
+            expected_outputs: plan.expected_outputs,
+            warnings: [],
+            errors,
+            diagnostics: plan.diagnostics,
+        };
+    }
+}

package/dist/execute/types.d.ts

@@ -0,0 +1,113 @@
+import type { Diagnostic } from "../diagnostics/types.js";
+import type { AionisValue } from "../ir/types.js";
+import type { ExecutionPlanStep, ExecutionPlanV1 } from "../plan/types.js";
+export declare const AIONIS_MANIFEST_EXECUTION_RESULT_VERSION: "aionis_manifest_execution_result_v1";
+export type AionisManifestRunInputKind = "source" | "compile-envelope" | "plan";
+export interface ExecutionNodeResult {
+    execution_id: string;
+    module?: string;
+    tool?: string;
+    agent?: string;
+    status: "success" | "failed" | "skipped";
+    input_ref?: string;
+    output_ref?: string;
+    output?: AionisValue;
+    artifacts?: AionisValue[];
+    evidence?: AionisValue[];
+    error?: string;
+}
+export interface ExecutionArtifactRecord {
+    execution_id: string;
+    module?: string;
+    value: AionisValue;
+}
+export interface ExecutionEvidenceRecord {
+    execution_id: string;
+    module?: string;
+    value: AionisValue;
+}
+export type ExecutionRuntimeCapability = "direct_execution" | "deterministic_replay" | "state_persistence" | "memory_publish" | "handoff_recover" | "module_registry" | "evidence_capture";
+export interface ExecutionRuntimeCapabilities {
+    direct_execution: boolean;
+    deterministic_replay: boolean;
+    state_persistence: boolean;
+    memory_publish: boolean;
+    handoff_recover: boolean;
+    module_registry: boolean;
+    evidence_capture: boolean;
+}
+export interface ExecutionModuleContext {
+    plan: ExecutionPlanV1;
+    step: ExecutionPlanStep;
+    outputs: Record<string, AionisValue>;
+    runtime_id: string;
+}
+export type ExecutionModuleValueContractKind = "any" | "string" | "number" | "boolean" | "null" | "array" | "object";
+export interface ExecutionModuleValueContract {
+    kind: ExecutionModuleValueContractKind;
+    description?: string;
+    properties?: Record<string, ExecutionModuleValueContract>;
+    required?: string[];
+    items?: ExecutionModuleValueContract;
+    additional_properties?: boolean;
+}
+export interface ExecutionModuleManifest {
+    module: string;
+    version: string;
+    title?: string;
+    description?: string;
+    deterministic?: boolean;
+    required_capabilities?: ExecutionRuntimeCapability[];
+    input_contract?: ExecutionModuleValueContract;
+    output_contract?: ExecutionModuleValueContract;
+    artifact_contract?: ExecutionModuleValueContract;
+    evidence_contract?: ExecutionModuleValueContract;
+}
+export interface ExecutionModuleOutcome {
+    kind: "module_result";
+    output: AionisValue;
+    artifacts?: AionisValue[];
+    evidence?: AionisValue[];
+}
+export type ExecutionModuleHandler = (input: AionisValue, context: ExecutionModuleContext) => Promise<AionisValue | ExecutionModuleOutcome> | AionisValue | ExecutionModuleOutcome;
+export interface ExecutionModuleDefinition {
+    manifest: ExecutionModuleManifest;
+    handler: ExecutionModuleHandler;
+}
+export interface ExecutionModuleRegistry {
+    has(moduleName: string): boolean;
+    get(moduleName: string): ExecutionModuleDefinition | undefined;
+    getManifest(moduleName: string): ExecutionModuleManifest | undefined;
+    list(): ExecutionModuleDefinition[];
+    listManifests(): ExecutionModuleManifest[];
+}
+export interface ExecutionResultV1 {
+    execution_result_version: typeof AIONIS_MANIFEST_EXECUTION_RESULT_VERSION;
+    runtime_id: string;
+    executed_at: string;
+    plan_version: ExecutionPlanV1["plan_version"];
+    doc_id: string | null;
+    status: "success" | "failed";
+    outputs: Record<string, AionisValue>;
+    artifacts: ExecutionArtifactRecord[];
+    evidence: ExecutionEvidenceRecord[];
+    node_results: ExecutionNodeResult[];
+    expected_outputs: string[];
+    warnings: string[];
+    errors: string[];
+    diagnostics: Diagnostic[];
+}
+export interface ExecutionRuntime {
+    runtime_id: string;
+    capabilities(): ExecutionRuntimeCapabilities;
+    execute(plan: ExecutionPlanV1): Promise<ExecutionResultV1>;
+}
+export interface ExecuteAionisManifestOptions {
+    runtime?: ExecutionRuntime;
+}
+export interface AionisManifestRunRequest {
+    inputKind: AionisManifestRunInputKind;
+    registryPath: string;
+    cwd?: string;
+    compact?: boolean;
+}

package/dist/execute/types.js

@@ -0,0 +1 @@
+export const AIONIS_MANIFEST_EXECUTION_RESULT_VERSION = "aionis_manifest_execution_result_v1";

package/dist/execute-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/execute-cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { AionisManifestExecutionResultSchema } from "./contracts.js";
+import { AionisManifestExecutionError, compileAndExecuteAionisManifest, executeCompileEnvelope, executeExecutionPlan, } from "./execute.js";
+class CliUsageError extends Error {
+}
+function printHelp() {
+    process.stdout.write([
+        "execute-aionis-manifest",
+        "",
+        "Usage:",
+        "  execute-aionis-manifest <input-file> [--input-kind source|compile-envelope|plan] [--out <path>] [--compact]",
+        "",
+        "Options:",
+        "  --input-kind <kind>   Select source, compile-envelope, or plan input. Default: source",
+        "  --out <path>          Write output JSON to a file instead of stdout",
+        "  --compact             Print compact JSON instead of pretty JSON",
+        "  --help                Show this message",
+        "",
+    ].join("\n"));
+}
+function parseArgs(argv) {
+    let inputPath = null;
+    const flags = {
+        inputKind: "source",
+        out: null,
+        compact: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--help" || token === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (token === "--compact") {
+            flags.compact = true;
+            continue;
+        }
+        if (token === "--input-kind") {
+            const next = argv[i + 1];
+            if (!next)
+                throw new CliUsageError("Missing value for --input-kind.");
+            if (!["source", "compile-envelope", "plan"].includes(next)) {
+                throw new CliUsageError(`Unsupported input kind '${next}'.`);
+            }
+            flags.inputKind = next;
+            i += 1;
+            continue;
+        }
+        if (token === "--out") {
+            const next = argv[i + 1];
+            if (!next)
+                throw new CliUsageError("Missing value for --out.");
+            flags.out = next;
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            throw new CliUsageError(`Unknown flag '${token}'.`);
+        }
+        if (inputPath)
+            throw new CliUsageError("Only one input file may be provided.");
+        inputPath = token;
+    }
+    return { inputPath, flags };
+}
+async function writeOutput(pathname, contents) {
+    await mkdir(dirname(pathname), { recursive: true });
+    await writeFile(pathname, contents, "utf8");
+}
+async function main() {
+    const { inputPath, flags } = parseArgs(process.argv.slice(2));
+    if (flags.help) {
+        printHelp();
+        return;
+    }
+    if (!inputPath)
+        throw new CliUsageError("An input file path is required.");
+    const resolvedInput = resolve(process.cwd(), inputPath);
+    const source = await readFile(resolvedInput, "utf8");
+    const result = flags.inputKind === "source"
+        ? await compileAndExecuteAionisManifest(source)
+        : flags.inputKind === "compile-envelope"
+            ? await executeCompileEnvelope(JSON.parse(source))
+            : await executeExecutionPlan(JSON.parse(source));
+    const parsed = AionisManifestExecutionResultSchema.parse(result);
+    const rendered = flags.compact ? JSON.stringify(parsed) : `${JSON.stringify(parsed, null, 2)}\n`;
+    if (flags.out) {
+        await writeOutput(resolve(process.cwd(), flags.out), rendered);
+    }
+    else {
+        process.stdout.write(rendered);
+    }
+    if (parsed.status === "failed") {
+        process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    if (error instanceof CliUsageError || error instanceof AionisManifestExecutionError) {
+        process.stderr.write(`${error.message}\n`);
+        if (error instanceof CliUsageError)
+            printHelp();
+        process.exitCode = error instanceof CliUsageError ? 2 : 1;
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/execute.d.ts

@@ -0,0 +1,6 @@
+import type { ExecuteAionisManifestOptions, ExecutionResultV1 } from "./execute/types.js";
+export declare class AionisManifestExecutionError extends Error {
+}
+export declare function compileAndExecuteAionisManifest(source: string, options?: ExecuteAionisManifestOptions): Promise<ExecutionResultV1>;
+export declare function executeCompileEnvelope(value: unknown, options?: ExecuteAionisManifestOptions): Promise<ExecutionResultV1>;
+export declare function executeExecutionPlan(value: unknown, options?: ExecuteAionisManifestOptions): Promise<ExecutionResultV1>;

package/dist/execute.js

@@ -0,0 +1,46 @@
+import { validateCompileEnvelope, ExecutionPlanSchema } from "./contracts.js";
+import { compileAionisManifest } from "./compile.js";
+import { LocalExecutionRuntime } from "./execute/localRuntime.js";
+import { buildExecutionPlanV1 } from "./plan/buildExecutionPlan.js";
+export class AionisManifestExecutionError extends Error {
+}
+function resolveRuntime(options) {
+    return options?.runtime ?? new LocalExecutionRuntime();
+}
+function planFromCompileResult(result) {
+    return result.plan;
+}
+function asExecutionPlan(value) {
+    return value;
+}
+function asAionisManifestIr(value) {
+    return value;
+}
+function asExecutionGraph(value) {
+    return value ?? null;
+}
+function planFromEnvelope(value) {
+    const envelope = validateCompileEnvelope(value);
+    if (envelope.artifacts.plan)
+        return asExecutionPlan(envelope.artifacts.plan);
+    if (!envelope.artifacts.ir) {
+        throw new AionisManifestExecutionError(`Execution requires a plan or IR artifact. Re-run compile-aionis-manifest with --emit all, --emit ir, or --emit plan; current selected_artifact is '${envelope.selected_artifact}'.`);
+    }
+    return buildExecutionPlanV1({
+        ir: asAionisManifestIr(envelope.artifacts.ir),
+        graph: asExecutionGraph(envelope.artifacts.graph),
+        diagnostics: envelope.diagnostics,
+    });
+}
+export function compileAndExecuteAionisManifest(source, options = {}) {
+    const result = compileAionisManifest(source);
+    return executeExecutionPlan(planFromCompileResult(result), options);
+}
+export function executeCompileEnvelope(value, options = {}) {
+    return executeExecutionPlan(planFromEnvelope(value), options);
+}
+export function executeExecutionPlan(value, options = {}) {
+    const plan = asExecutionPlan(ExecutionPlanSchema.parse(value));
+    const runtime = resolveRuntime(options);
+    return runtime.execute(plan);
+}

package/dist/graph/buildExecutionGraph.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from "../diagnostics/types.js";
+import type { ExecutionGraph } from "./types.js";
+import type { AionisManifestIR } from "../ir/types.js";
+export interface GraphBuildResult {
+    value: ExecutionGraph | null;
+    diagnostics: Diagnostic[];
+}
+export declare function buildExecutionGraph(ir: AionisManifestIR): GraphBuildResult;