@tomflow/proflow-execution-runtime 0.1.0

package/dist/deployment/adapter.js

@@ -0,0 +1,265 @@
+import { descriptor } from "./descriptor.js";
+const base = {
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+};
+const unbound = {
+    ...base,
+    ok: false,
+    status: "ACTION_REQUIRED",
+    actionRequired: {
+        action: "bind-runtime",
+        description: "Bind a configured Execution Runtime service",
+    },
+};
+export function createBehaviorAdapter(service) {
+    return {
+        describe: () => ({ result: base, observedEffects: [] }),
+        preflight: () => ({ result: base, observedEffects: [] }),
+        status: () => {
+            const status = service?.status();
+            const ready = status?.readiness === "READY";
+            return {
+                result: service
+                    ? {
+                        ...(ready
+                            ? base
+                            : {
+                                ...base,
+                                ok: false,
+                                status: "ACTION_REQUIRED",
+                                actionRequired: {
+                                    action: "repair-execution-runtime",
+                                    description: "Execution Runtime is not READY",
+                                },
+                            }),
+                        data: status,
+                        checks: [
+                            {
+                                id: "execution-runtime-readiness",
+                                status: ready ? "PASS" : "FAIL",
+                                message: `Execution Runtime readiness is ${status?.readiness ?? "NOT_READY"}`,
+                            },
+                        ],
+                    }
+                    : unbound,
+                observedEffects: [],
+            };
+        },
+        verify: () => {
+            const status = service?.status();
+            const ready = status?.readiness === "READY";
+            return {
+                result: {
+                    ...(service && ready
+                        ? base
+                        : service
+                            ? {
+                                ...base,
+                                ok: false,
+                                status: "ACTION_REQUIRED",
+                                actionRequired: {
+                                    action: "repair-execution-runtime",
+                                    description: "Execution Runtime is not READY",
+                                },
+                            }
+                            : unbound),
+                    checks: [
+                        {
+                            id: "execution-runtime-critical-proofs",
+                            status: ready ? "PASS" : "FAIL",
+                            message: service
+                                ? `Execution Runtime readiness is ${status?.readiness ?? "NOT_READY"}`
+                                : "No configured Execution Runtime process is bound",
+                        },
+                    ],
+                },
+                observedEffects: [],
+            };
+        },
+        doctor: () => ({ result: base, observedEffects: [] }),
+        start: async () => ({
+            result: service ? { ...base, data: await service.start() } : unbound,
+            observedEffects: service
+                ? [...descriptor.effects.map((item) => item.description)]
+                : [],
+        }),
+        stop: async () => {
+            if (service)
+                await service.stop();
+            return {
+                result: service ? base : unbound,
+                observedEffects: service
+                    ? [...descriptor.effects.map((item) => item.description)]
+                    : [],
+            };
+        },
+        uninstall: async () => {
+            if (service)
+                await service.stop();
+            return {
+                result: service ? base : unbound,
+                observedEffects: service
+                    ? descriptor.effects
+                        .filter((item) => item.retention === "remove")
+                        .map((item) => item.description)
+                    : [],
+            };
+        },
+        restart: async () => ({
+            result: service ? { ...base, data: await service.restart() } : unbound,
+            observedEffects: service
+                ? [...descriptor.effects.map((item) => item.description)]
+                : [],
+        }),
+    };
+}
+export const behaviorAdapter = createBehaviorAdapter();
+export async function createServiceProcessBinding(input) {
+    const required = [
+        "databasePath",
+        "projectRoot",
+        "artifactRoot",
+        "browserExecutorConfigPath",
+        "transportCredentialFile",
+        "identity.endpoint",
+        "identity.tokenFile",
+        "modelDecision.endpoint",
+        "modelDecision.credentialFile",
+    ];
+    if (!required.every((key) => input.config[key]))
+        return undefined;
+    const platformHost = input.configByModuleRef.get("platform-host");
+    const advertised = platformHost?.executionBaseUrl;
+    if (!advertised)
+        return undefined;
+    const listener = new URL(advertised);
+    if (listener.protocol !== "http:" || listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const { parseExecutionRuntimeProcessConfig } = await import("../src/service.js");
+    const processConfig = parseExecutionRuntimeProcessConfig({
+        host: listener.hostname,
+        port,
+        databasePath: input.config.databasePath,
+        projectRoot: input.config.projectRoot,
+        artifactRoot: input.config.artifactRoot,
+        browserExecutorConfigPath: input.config.browserExecutorConfigPath,
+        transportCredentialFile: input.config.transportCredentialFile,
+        identity: {
+            endpoint: input.config["identity.endpoint"],
+            tokenFile: input.config["identity.tokenFile"],
+        },
+        modelDecision: {
+            endpoint: input.config["modelDecision.endpoint"],
+            credentialFile: input.config["modelDecision.credentialFile"],
+        },
+    });
+    const probeAdapter = {
+        describe: behaviorAdapter.describe,
+        preflight: behaviorAdapter.preflight,
+        verify: async () => {
+            let ready = false;
+            try {
+                ready = (await fetch(new URL("/ready", listener))).ok;
+            }
+            catch {
+                ready = false;
+            }
+            return {
+                result: ready
+                    ? {
+                        ...base,
+                        checks: [
+                            {
+                                id: "execution-runtime-critical-proofs",
+                                status: "PASS",
+                                message: "Managed Execution Runtime /ready probe passed",
+                            },
+                        ],
+                    }
+                    : {
+                        ...base,
+                        ok: false,
+                        status: "ACTION_REQUIRED",
+                        actionRequired: {
+                            action: "repair-execution-runtime",
+                            description: "Managed Execution Runtime /ready probe failed",
+                        },
+                        checks: [
+                            {
+                                id: "execution-runtime-critical-proofs",
+                                status: "FAIL",
+                                message: "Managed Execution Runtime /ready probe failed",
+                            },
+                        ],
+                    },
+                observedEffects: [],
+            };
+        },
+        doctor: behaviorAdapter.doctor,
+    };
+    return {
+        serviceProcess: {
+            contract: "deployment.service-process.v1",
+            bin: "proflow-execution-runtime",
+            startCommand: "start",
+            config: processConfig,
+        },
+        behaviorAdapter: probeAdapter,
+    };
+}
+export async function createProductionBinding(input) {
+    const required = [
+        "databasePath",
+        "projectRoot",
+        "artifactRoot",
+        "browserExecutorConfigPath",
+        "transportCredentialFile",
+        "identity.endpoint",
+        "identity.tokenFile",
+        "modelDecision.endpoint",
+        "modelDecision.credentialFile",
+    ];
+    if (!required.every((key) => input.config[key]))
+        return undefined;
+    const platformHost = input.configByModuleRef.get("platform-host");
+    const advertised = platformHost?.executionBaseUrl;
+    if (!advertised)
+        return undefined;
+    const listener = new URL(advertised);
+    if (listener.protocol !== "http:" || listener.pathname !== "/")
+        return undefined;
+    const port = listener.port === "" ? 80 : Number(listener.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        return undefined;
+    const [{ createFormalExecutionRuntimeLifecycle }, { parseExecutionRuntimeProcessConfig },] = await Promise.all([
+        import("../src/formal-process.js"),
+        import("../src/service.js"),
+    ]);
+    const service = createFormalExecutionRuntimeLifecycle({
+        config: parseExecutionRuntimeProcessConfig({
+            host: listener.hostname,
+            port,
+            databasePath: input.config.databasePath,
+            projectRoot: input.config.projectRoot,
+            artifactRoot: input.config.artifactRoot,
+            browserExecutorConfigPath: input.config.browserExecutorConfigPath,
+            transportCredentialFile: input.config.transportCredentialFile,
+            identity: {
+                endpoint: input.config["identity.endpoint"],
+                tokenFile: input.config["identity.tokenFile"],
+            },
+            modelDecision: {
+                endpoint: input.config["modelDecision.endpoint"],
+                credentialFile: input.config["modelDecision.credentialFile"],
+            },
+        }),
+    });
+    return { behaviorAdapter: createBehaviorAdapter(service) };
+}

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,105 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "execution-runtime";
+    readonly packageName: "@tomflow/proflow-execution-runtime";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "service";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "execution";
+        readonly summary: "Durable, policy-controlled Execution Core orchestration over SQLite and controlled executor ports.";
+    };
+    readonly provides: readonly [{
+        readonly contractRef: "execution";
+        readonly version: "1.0.0";
+    }];
+    readonly requires: readonly [{
+        readonly contractRef: "execution-local";
+        readonly versionRange: ">=1.0.0 <2.0.0";
+    }];
+    readonly requirements: readonly [{
+        readonly kind: "runtime";
+        readonly runtime: "node";
+        readonly versionRange: ">=24.19.0";
+    }, {
+        readonly kind: "filesystem";
+        readonly path: ".proflow";
+        readonly access: "read-write";
+    }];
+    readonly configSlots: readonly [{
+        readonly key: "databasePath";
+        readonly type: "path";
+        readonly required: true;
+        readonly description: "Execution SQLite database";
+    }, {
+        readonly key: "projectRoot";
+        readonly type: "path";
+        readonly required: true;
+        readonly description: "Canonical project boundary consumed by the local executor";
+    }, {
+        readonly key: "artifactRoot";
+        readonly type: "path";
+        readonly required: true;
+        readonly description: "Execution-owned Artifact/Evidence filesystem root";
+    }, {
+        readonly key: "browserExecutorConfigPath";
+        readonly type: "path";
+        readonly required: true;
+        readonly description: "Absolute configuration path for the formal Browser Reality Bridge composition";
+    }, {
+        readonly key: "transportCredentialFile";
+        readonly type: "path";
+        readonly required: true;
+        readonly sensitive: true;
+        readonly description: "File containing the Execution Runtime transport credential";
+    }, {
+        readonly key: "identity.endpoint";
+        readonly type: "url";
+        readonly required: true;
+        readonly description: "Loopback platform-host execution identity endpoint";
+    }, {
+        readonly key: "identity.tokenFile";
+        readonly type: "path";
+        readonly required: true;
+        readonly sensitive: true;
+        readonly description: "File containing the Execution-to-platform-host identity transport credential";
+    }, {
+        readonly key: "modelDecision.endpoint";
+        readonly type: "url";
+        readonly required: true;
+        readonly description: "Loopback Model Runtime endpoint used by execution.command-risk.v1";
+    }, {
+        readonly key: "modelDecision.credentialFile";
+        readonly type: "path";
+        readonly required: true;
+        readonly sensitive: true;
+        readonly description: "File containing the Execution-to-Model transport credential";
+    }];
+    readonly lifecycle: {
+        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor", "start", "stop", "restart", "uninstall"];
+    };
+    readonly verification: {
+        readonly checks: readonly [{
+            readonly id: "execution-runtime-critical-proofs";
+            readonly description: "Execution Runtime critical proofs pass";
+            readonly lifecycle: "verify";
+        }];
+    };
+    readonly effects: readonly [{
+        readonly kind: "process";
+        readonly description: "Runs the single backend Execution Runtime service";
+        readonly retention: "remove";
+    }, {
+        readonly kind: "filesystem";
+        readonly description: "Persists execution state, output references and evidence in WAL SQLite";
+        readonly retention: "preserve";
+    }];
+    readonly documentation: readonly [{
+        readonly id: "overview";
+        readonly path: "./README.md";
+        readonly description: "Execution Runtime package overview";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,123 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "execution-runtime",
+    packageName: "@tomflow/proflow-execution-runtime",
+    moduleVersion: "0.1.0",
+    kind: "service",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "execution",
+        summary: "Durable, policy-controlled Execution Core orchestration over SQLite and controlled executor ports.",
+    },
+    provides: [{ contractRef: "execution", version: "1.0.0" }],
+    requires: [
+        { contractRef: "execution-local", versionRange: ">=1.0.0 <2.0.0" },
+    ],
+    requirements: [
+        { kind: "runtime", runtime: "node", versionRange: ">=24.19.0" },
+        { kind: "filesystem", path: ".proflow", access: "read-write" },
+    ],
+    configSlots: [
+        {
+            key: "databasePath",
+            type: "path",
+            required: true,
+            description: "Execution SQLite database",
+        },
+        {
+            key: "projectRoot",
+            type: "path",
+            required: true,
+            description: "Canonical project boundary consumed by the local executor",
+        },
+        {
+            key: "artifactRoot",
+            type: "path",
+            required: true,
+            description: "Execution-owned Artifact/Evidence filesystem root",
+        },
+        {
+            key: "browserExecutorConfigPath",
+            type: "path",
+            required: true,
+            description: "Absolute configuration path for the formal Browser Reality Bridge composition",
+        },
+        {
+            key: "transportCredentialFile",
+            type: "path",
+            required: true,
+            sensitive: true,
+            description: "File containing the Execution Runtime transport credential",
+        },
+        {
+            key: "identity.endpoint",
+            type: "url",
+            required: true,
+            description: "Loopback platform-host execution identity endpoint",
+        },
+        {
+            key: "identity.tokenFile",
+            type: "path",
+            required: true,
+            sensitive: true,
+            description: "File containing the Execution-to-platform-host identity transport credential",
+        },
+        {
+            key: "modelDecision.endpoint",
+            type: "url",
+            required: true,
+            description: "Loopback Model Runtime endpoint used by execution.command-risk.v1",
+        },
+        {
+            key: "modelDecision.credentialFile",
+            type: "path",
+            required: true,
+            sensitive: true,
+            description: "File containing the Execution-to-Model transport credential",
+        },
+    ],
+    lifecycle: {
+        supported: [
+            "describe",
+            "preflight",
+            "status",
+            "verify",
+            "doctor",
+            "start",
+            "stop",
+            "restart",
+            "uninstall",
+        ],
+    },
+    verification: {
+        checks: [
+            {
+                id: "execution-runtime-critical-proofs",
+                description: "Execution Runtime critical proofs pass",
+                lifecycle: "verify",
+            },
+        ],
+    },
+    effects: [
+        {
+            kind: "process",
+            description: "Runs the single backend Execution Runtime service",
+            retention: "remove",
+        },
+        {
+            kind: "filesystem",
+            description: "Persists execution state, output references and evidence in WAL SQLite",
+            retention: "preserve",
+        },
+    ],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Execution Runtime package overview",
+        },
+    ],
+};

package/dist/deployment/requirements.d.ts

@@ -0,0 +1,5 @@
+export declare const requirements: {
+    readonly runtime: "node";
+    readonly minimumVersion: "24.19.0";
+    readonly writablePaths: readonly [".proflow"];
+};

package/dist/deployment/requirements.js

@@ -0,0 +1,5 @@
+export const requirements = {
+    runtime: "node",
+    minimumVersion: "24.19.0",
+    writablePaths: [".proflow"],
+};

package/dist/deployment/verification.d.ts

@@ -0,0 +1,3 @@
+export declare const verification: {
+    readonly checks: readonly ["execution-runtime-critical-proofs", "sqlite-integrity-pass", "secret-persistence-scan"];
+};

package/dist/deployment/verification.js

@@ -0,0 +1,7 @@
+export const verification = {
+    checks: [
+        "execution-runtime-critical-proofs",
+        "sqlite-integrity-pass",
+        "secret-persistence-scan",
+    ],
+};

package/dist/src/approval-owner.d.ts

@@ -0,0 +1,40 @@
+import { type ExecuteCapabilityRequest, type ExecutionApprovalRecord } from "@tomflow/proflow-execution-contracts";
+import type { ExecutorPrecondition } from "./executor-port.ts";
+export declare class ExecutionApprovalOwnerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function createExecutionApprovalOwner(input: {
+    databasePath: string;
+    now?: () => Date;
+    idFactory?: () => string;
+}): Readonly<{
+    requestApproval: (value: unknown) => ExecutionApprovalRecord;
+    ensurePendingApproval: (value: {
+        executionRef: string;
+        actorRef: string;
+        expiresAt: string;
+        precondition?: ExecutorPrecondition;
+    }) => ExecutionApprovalRecord;
+    decideApproval: (value: unknown) => ExecutionApprovalRecord;
+    revokeApproval: (value: unknown) => ExecutionApprovalRecord;
+    getApproval: (approvalRef: string) => ExecutionApprovalRecord;
+    listApprovals: (filter?: {
+        executionRef?: string;
+        status?: string;
+    }) => ExecutionApprovalRecord[];
+    validate: (value: {
+        approvalRef: string;
+        executionRef: string;
+        callerRef: string;
+        taskId?: string;
+        capability: string;
+        inputFingerprint: string;
+        request: ExecuteCapabilityRequest;
+        projectRoot?: string;
+        precondition?: ExecutorPrecondition;
+        now: string;
+    }) => boolean;
+    consume: (approvalRef: string) => ExecutionApprovalRecord;
+    close: () => void;
+}>;