@cynodia/axiom-runtime 0.7.0-alpha.2 → 0.8.0-alpha.1

package/dist/dom.d.ts

@@ -52,6 +52,17 @@ export interface ConfirmationRequest {
     /** A single line for hosts that can only ask a plain question. */
     message: string;
 }
+export interface IntegrationQuerySuccess {
+    ok: true;
+    value: unknown;
+}
+export interface IntegrationQueryFailure {
+    ok: false;
+    code: string;
+    message: string;
+    retryable?: boolean;
+}
+export type IntegrationQueryOutcome = IntegrationQuerySuccess | IntegrationQueryFailure;
 /** Everything the runtime needs from its environment, so nothing is read from globals. */
 export interface HostEnvironment {
     document: DomDocument;
@@ -65,5 +76,15 @@ export interface HostEnvironment {
     uuid(): string;
     storage?: StorageAdapter;
     report?(message: string): void;
+    /**
+     * Executes an integration query operation by id and returns its result.
+     *
+     * Only the authoritative runtime ever calls this, executing an `integration-query`
+     * operation: no client-compiled action ever contains one (integrations default
+     * server-only), so a browser host never needs to implement it.
+     */
+    queryIntegration?(operationId: string, args: Record<string, unknown>, options: {
+        timeoutMs?: number;
+    }): Promise<IntegrationQueryOutcome>;
 }
 //# sourceMappingURL=dom.d.ts.map

package/dist/runtime.d.ts

@@ -36,6 +36,14 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly REMOTE_ACTION_UNAVAILABLE: "REMOTE_ACTION_UNAVAILABLE";
     /** The authority could not be reached. Authoritative state was not loaded. */
     readonly AUTHORITY_UNREACHABLE: "AUTHORITY_UNREACHABLE";
+    /** No host capable of executing an integration query is configured. */
+    readonly INTEGRATION_UNAVAILABLE: "INTEGRATION_UNAVAILABLE";
+    /** An integration query did not answer within its declared timeout. */
+    readonly INTEGRATION_TIMEOUT: "INTEGRATION_TIMEOUT";
+    /** A provider's response did not conform to the operation's declared result type. */
+    readonly INTEGRATION_RESULT_INVALID: "INTEGRATION_RESULT_INVALID";
+    /** An integration query failed. Never carries a provider secret. */
+    readonly INTEGRATION_QUERY_FAILED: "INTEGRATION_QUERY_FAILED";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
 /**
@@ -56,6 +64,24 @@ export interface RuntimeDiagnostic {
     /** Structured context, so an agent never has to read the message. */
     details?: Record<string, unknown>;
 }
+/**
+ * Recorded intent to perform an external effect — appended when an `integration-effect`
+ * operation is reached, and discarded on rollback exactly like a mutation log entry is.
+ * Distinct from `MutationLogEntry`: an effect is not a state mutation (spec §73), and
+ * `outcome` here means whether the **intent was committed**, not whether the external
+ * effect itself succeeded — that is a separate, later question a host answers.
+ */
+export interface EffectIntentRecord {
+    id: string;
+    transactionId?: string;
+    actionId?: NodeId;
+    operationId: NodeId;
+    arguments: Record<string, unknown>;
+    idempotencyKey?: string;
+    succeededEventId?: NodeId;
+    failedEventId?: NodeId;
+    outcome?: 'committed' | 'rolled-back';
+}
 export interface ActionResult {
     ok: boolean;
     diagnostics: RuntimeDiagnostic[];
@@ -175,6 +201,12 @@ export interface AxiomRuntime {
     getActionOutcome(id: NodeId): ActionOutcome | undefined;
     /** Every mutation this runtime has applied, in order, with its semantic location. */
     getMutationLog(): MutationLogEntry[];
+    /**
+     * Every `integration-effect` intent recorded so far, in order — a log distinct from the
+     * mutation log because an effect is not a state mutation. `outcome` reflects whether the
+     * *intent* was committed, not whether the external effect itself has run yet.
+     */
+    getEffectIntents(): EffectIntentRecord[];
     registerNativeOperation(implementationId: string, implementation: NativeImplementation): void;
     /**
      * Invokes an action and waits for its outcome. For a remote action this awaits the
@@ -207,6 +239,18 @@ export interface AxiomRuntime {
         ok: false;
         diagnostic: RuntimeDiagnostic;
     };
+    /**
+     * Evaluates an expression with extra ids bound in scope, keyed by id — how a trigger's
+     * `arguments`/`enabledWhen` resolve `ref()` of the trigger's own id to read an event
+     * payload, the same way a `for-each` body resolves its scope id.
+     */
+    evaluateWithBindings(expression: Expression, bindings: Record<string, unknown>): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        diagnostic: RuntimeDiagnostic;
+    };
 }
 export declare function createAxiomRuntime(options: AxiomRuntimeOptions): AxiomRuntime;
 /** Builds a host bound to the browser globals. Used by generated pages. */

package/dist/runtime.js

@@ -40,6 +40,14 @@ export const RUNTIME_DIAGNOSTIC_CODES = {
     REMOTE_ACTION_UNAVAILABLE: 'REMOTE_ACTION_UNAVAILABLE',
     /** The authority could not be reached. Authoritative state was not loaded. */
     AUTHORITY_UNREACHABLE: 'AUTHORITY_UNREACHABLE',
+    /** No host capable of executing an integration query is configured. */
+    INTEGRATION_UNAVAILABLE: 'INTEGRATION_UNAVAILABLE',
+    /** An integration query did not answer within its declared timeout. */
+    INTEGRATION_TIMEOUT: 'INTEGRATION_TIMEOUT',
+    /** A provider's response did not conform to the operation's declared result type. */
+    INTEGRATION_RESULT_INVALID: 'INTEGRATION_RESULT_INVALID',
+    /** An integration query failed. Never carries a provider secret. */
+    INTEGRATION_QUERY_FAILED: 'INTEGRATION_QUERY_FAILED',
 };
 const MISSING = Symbol('missing');
 function unwrapType(type) {
@@ -125,6 +133,7 @@ export function createAxiomRuntime(options) {
     let started = false;
     let transactionCounter = 0;
     const mutationLog = [];
+    const effectIntentLog = [];
     const inputValidation = options.inputValidation ?? 'immediate';
     const remote = options.remote;
     const remoteActionIds = new Set(ir.remoteActionIds ?? []);
@@ -436,6 +445,11 @@ export function createAxiomRuntime(options) {
                 entry.outcome = outcome;
             }
         }
+        for (const entry of effectIntentLog) {
+            if (entry.transactionId === transaction.id && entry.outcome === undefined) {
+                entry.outcome = outcome;
+            }
+        }
     }
     /**
      * Classifies an evaluation failure. The code says what kind of failure it was, so an
@@ -1068,6 +1082,33 @@ export function createAxiomRuntime(options) {
                 }
                 return;
             }
+            case 'integration-query':
+                // The result was already resolved and bound into the action's scope before this
+                // transaction opened — see `runActionAsync`. Nothing to do here; this case exists
+                // only so the kind is recognized rather than falling to `default`.
+                return;
+            case 'integration-effect': {
+                // Never calls an adapter here: reaching this operation only records intent, in the
+                // same log a mutation is recorded in, discarded on rollback the same way. Dispatch
+                // to the adapter happens only after the surrounding transaction commits.
+                const args = {};
+                for (const [key, argument] of Object.entries(operation.arguments ?? {})) {
+                    args[key] = cloneValue(evaluate(argument, scope));
+                }
+                effectIntentLog.push({
+                    id: host.uuid(),
+                    transactionId: context.transactionId,
+                    ...(context.sourceNodeId ? { actionId: context.sourceNodeId } : {}),
+                    operationId: operation.operationId,
+                    arguments: args,
+                    ...(operation.idempotencyKey
+                        ? { idempotencyKey: toText(evaluate(operation.idempotencyKey, scope)) }
+                        : {}),
+                    ...(operation.succeededEventId ? { succeededEventId: operation.succeededEventId } : {}),
+                    ...(operation.failedEventId ? { failedEventId: operation.failedEventId } : {}),
+                });
+                return;
+            }
             default:
                 result.push({
                     code: RUNTIME_DIAGNOSTIC_CODES.UNSUPPORTED_OPERATION,
@@ -1204,14 +1245,14 @@ export function createAxiomRuntime(options) {
         }
         renderApplication();
     }
-    function runAction(actionId, args = {}) {
+    function runAction(actionId, args = {}, presetBindings) {
         const remoteAction = remoteActionIds.has(actionId) ? ir.actions[actionId] : undefined;
         if (remoteAction) {
             return runRemoteAction(remoteAction, args);
         }
         return collecting((collected) => {
             const started = collected.length;
-            const result = runActionCollecting(actionId, args, collected);
+            const result = runActionCollecting(actionId, args, collected, presetBindings);
             if (ir.actions[actionId]) {
                 // The record is this invocation's own diagnostics, so a later invocation of another
                 // action can never appear to belong to this one.
@@ -1226,9 +1267,87 @@ export function createAxiomRuntime(options) {
             return result;
         });
     }
+    function actionHasIntegrationQuery(action) {
+        return (action.operations ?? []).some((operation) => operation.kind === 'integration-query');
+    }
+    /**
+     * Resolves every top-level `integration-query` operation before the transaction opens,
+     * then runs the action exactly as `runAction` would with the results bound into scope.
+     *
+     * Queries are awaited here, ahead of guards and the transaction — the same "none of this
+     * mutates anything" phase preconditions already occupy — because a query's own validation
+     * scope proves guards can never reference `ref(bindAs)`. `integration-effect` operations
+     * need no async pre-step: they only record intent, synchronously, during the ordinary
+     * operation loop.
+     */
+    async function runActionAsync(actionId, args = {}) {
+        const action = ir.actions[actionId];
+        if (!action || !actionHasIntegrationQuery(action) || remoteActionIds.has(actionId)) {
+            return runAction(actionId, args);
+        }
+        const scope = rootScope();
+        for (const parameter of action.parameters ?? []) {
+            scope.values.set(parameter.id, args[parameter.id] ?? null);
+        }
+        const presetBindings = new Map();
+        for (const operation of action.operations ?? []) {
+            if (operation.kind !== 'integration-query') {
+                continue;
+            }
+            const queryArgs = {};
+            for (const [key, argument] of Object.entries(operation.arguments ?? {})) {
+                queryArgs[key] = evaluate(argument, scope);
+            }
+            let outcome;
+            try {
+                outcome = await host.queryIntegration?.(operation.operationId, queryArgs, {
+                    ...(operation.timeoutMs !== undefined ? { timeoutMs: operation.timeoutMs } : {}),
+                });
+            }
+            catch (error) {
+                outcome = {
+                    ok: false,
+                    code: RUNTIME_DIAGNOSTIC_CODES.INTEGRATION_QUERY_FAILED,
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            if (!outcome) {
+                const diagnostic = {
+                    code: RUNTIME_DIAGNOSTIC_CODES.INTEGRATION_UNAVAILABLE,
+                    message: `${action.name ?? action.id} calls an integration query, but this host cannot perform one`,
+                    severity: 'error',
+                    nodeId: action.id,
+                    actionId: action.id,
+                };
+                report(diagnostic);
+                recordOutcome(actionId, 'failed', [diagnostic]);
+                renderApplication();
+                return { ok: false, diagnostics: [diagnostic] };
+            }
+            if (!outcome.ok) {
+                const diagnostic = {
+                    code: RUNTIME_DIAGNOSTIC_CODES[outcome.code]
+                        ? outcome.code
+                        : RUNTIME_DIAGNOSTIC_CODES.INTEGRATION_QUERY_FAILED,
+                    message: outcome.message,
+                    severity: 'error',
+                    nodeId: action.id,
+                    actionId: action.id,
+                    details: { operationId: String(operation.operationId), retryable: outcome.retryable === true },
+                };
+                report(diagnostic);
+                recordOutcome(actionId, 'failed', [diagnostic]);
+                renderApplication();
+                return { ok: false, diagnostics: [diagnostic] };
+            }
+            scope.values.set(operation.bindAs, outcome.value);
+            presetBindings.set(operation.bindAs, outcome.value);
+        }
+        return runAction(actionId, args, presetBindings);
+    }
     /** Set when the most recent invocation stopped because a confirmation was declined. */
     let cancelled = false;
-    function runActionCollecting(actionId, args, collected) {
+    function runActionCollecting(actionId, args, collected, presetBindings) {
         const action = ir.actions[actionId];
         if (!action) {
             const failure = {
@@ -1243,6 +1362,11 @@ export function createAxiomRuntime(options) {
         for (const parameter of action.parameters ?? []) {
             scope.values.set(parameter.id, args[parameter.id] ?? null);
         }
+        // Integration query results resolved before this transaction opened (see
+        // `runActionAsync`) — bound the same way a parameter is, so `ref(bindAs)` resolves.
+        for (const [id, value] of presetBindings ?? []) {
+            scope.values.set(id, value);
+        }
         const failures = [];
         for (const parameter of action.parameters ?? []) {
             if (parameter.required && !isPresent(scope.values.get(parameter.id))) {
@@ -2323,10 +2447,17 @@ export function createAxiomRuntime(options) {
         getMutationLog() {
             return mutationLog.map((entry) => ({ ...entry }));
         },
+        getEffectIntents() {
+            return effectIntentLog.map((entry) => ({ ...entry }));
+        },
         registerNativeOperation(implementationId, implementation) {
             natives.set(implementationId, implementation);
         },
         async invokeActionAsync(id, args = {}) {
+            const action = ir.actions[id];
+            if (action && actionHasIntegrationQuery(action) && !remoteActionIds.has(id)) {
+                return runActionAsync(id, args);
+            }
             const result = runAction(id, args);
             if (!result.pending) {
                 return result;
@@ -2343,6 +2474,14 @@ export function createAxiomRuntime(options) {
             const outcome = tryEvaluate(expression, rootScope(), {});
             return outcome.ok ? { ok: true, value: outcome.value } : { ok: false, diagnostic: outcome.diagnostic };
         },
+        evaluateWithBindings(expression, bindings) {
+            let scope = rootScope();
+            for (const [id, value] of Object.entries(bindings)) {
+                scope = childScope(scope, id, value);
+            }
+            const outcome = tryEvaluate(expression, scope, {});
+            return outcome.ok ? { ok: true, value: outcome.value } : { ok: false, diagnostic: outcome.diagnostic };
+        },
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.7.0-alpha.2",
+  "version": "0.8.0-alpha.1",
   "description": "Domain-independent runtime that executes an Axiom application graph.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.7.0-alpha.2"
+    "@cynodia/axiom-core": "0.8.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",