@cynodia/axiom-core 0.7.0-alpha.2 → 0.8.1-alpha.1

package/README.md

@@ -9,14 +9,18 @@ The Application Graph and its semantic model: nodes, fields, structured types,
 expressions, **locations** (addressable writable positions), edge derivation, validation
 and type inference. It also owns the presentation and UX layer — semantic roles, layout and
 spacing tokens, device classes, value formats and the `Theme` — with presentation
-resolution and validation.
+resolution and validation. As of 0.8 it also owns the vocabulary for external
+integrations, effects, triggers and events: `IntegrationDef`, `IntegrationOperationDef`,
+`EventDef`, `TriggerDef`, and the `integration-query`/`integration-effect` operation
+kinds — see [`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md).
 
 Presentation lives here because it is part of the canonical graph: it is intent, not
 styling, and it names no colour, length or CSS property.
 
 Main exports: `ApplicationGraph`, `TypeRef` builders, expression builders, `Location`
 builders, `Presentation`, `Theme`, `resolvePresentationMap`, `validateGraph`,
-`VALIDATION_CODES`, `ApplicationIR`.
+`VALIDATION_CODES`, `ApplicationIR`, `ServerIR`, `IntegrationDef`, `IntegrationOperationDef`,
+`EventDef`, `TriggerDef`.
 
 ## Installation
 

package/dist/authority.d.ts

@@ -43,6 +43,8 @@ export interface AuthorityContext {
 export declare function authorityContext(nodes: readonly AnyNode[], principalEntityId?: NodeId): AuthorityContext;
 /** Every state a set of expressions reads, following derived state transitively. */
 export declare function statesReadBy(expressions: readonly Expression[], context: AuthorityContext): Set<NodeId>;
+/** Whether an action calls out to an integration anywhere in its top-level operations. */
+export declare function actionUsesIntegration(action: ActionDef): boolean;
 /** The states an action writes, following `for-each`, `invoke` and declared native effects. */
 export declare function statesWrittenBy(action: ActionDef, context: AuthorityContext, visited?: Set<NodeId>): Set<NodeId>;
 /** The states an action reads: its guards, its values, its selectors, its authorization. */

package/dist/authority.js

@@ -112,10 +112,23 @@ function operationExpressions(operation) {
                 found.push(...locationExpressions(operation.resultTarget));
             }
             break;
+        case 'integration-query':
+            found.push(...Object.values(operation.arguments ?? {}));
+            break;
+        case 'integration-effect':
+            found.push(...Object.values(operation.arguments ?? {}));
+            if (operation.idempotencyKey) {
+                found.push(operation.idempotencyKey);
+            }
+            break;
         default:
     }
     return found;
 }
+/** Whether an action calls out to an integration anywhere in its top-level operations. */
+export function actionUsesIntegration(action) {
+    return (action.operations ?? []).some((operation) => operation.kind === 'integration-query' || operation.kind === 'integration-effect');
+}
 /** The states an action writes, following `for-each`, `invoke` and declared native effects. */
 export function statesWrittenBy(action, context, visited = new Set()) {
     const found = new Set();
@@ -152,6 +165,12 @@ export function statesWrittenBy(action, context, visited = new Set()) {
                         }
                     }
                     break;
+                case 'integration-query':
+                case 'integration-effect':
+                    // Neither writes Axiom state directly: a query's result is a transaction-local
+                    // scope binding, and an effect's outcome reaches state only through a follow-up
+                    // action invoked from its success/failure event.
+                    break;
                 default:
             }
         }
@@ -194,6 +213,12 @@ export function statesReadByAction(action, context, visited = new Set()) {
  * cannot disagree with what the action actually does.
  */
 export function actionAuthority(action, context) {
+    // Integrations default server-only (spec §65: secrets, trust, CORS, auditability,
+    // deterministic authority), so an action that calls one is unconditionally server —
+    // independent of what it writes.
+    if (actionUsesIntegration(action)) {
+        return 'server';
+    }
     for (const stateId of statesWrittenBy(action, context)) {
         const state = context.states.get(stateId);
         if (state && stateAuthority(state) === 'server') {

package/dist/derive-edges.js

@@ -143,6 +143,27 @@ export function deriveEdges(nodes) {
                 // bindings, no caller scope. Its parameters resolve to nothing here by design.
                 reads(node.id, node.expression, new Map());
                 break;
+            case 'integration-operation':
+                link(node.id, node.integrationId, 'references');
+                break;
+            case 'trigger':
+                link(node.id, node.actionId, 'invokes');
+                if (node.when.kind === 'event') {
+                    link(node.id, node.when.eventId, 'references');
+                }
+                if (node.when.kind === 'lifecycle' && node.when.routeId) {
+                    link(node.id, node.when.routeId, 'depends-on');
+                }
+                for (const argument of Object.values(node.arguments ?? {})) {
+                    reads(node.id, argument, rootScope);
+                }
+                if (node.enabledWhen) {
+                    reads(node.id, node.enabledWhen, rootScope);
+                }
+                break;
+            case 'integration':
+            case 'event':
+                break;
             default:
         }
     }
@@ -415,6 +436,27 @@ function linkOperations(actionId, operations, linker, scope) {
                     }
                 }
                 break;
+            case 'integration-query':
+                linker.link(actionId, operation.operationId, 'references');
+                for (const argument of Object.values(operation.arguments ?? {})) {
+                    linker.reads(actionId, argument, scope);
+                }
+                break;
+            case 'integration-effect':
+                linker.link(actionId, operation.operationId, 'references');
+                for (const argument of Object.values(operation.arguments ?? {})) {
+                    linker.reads(actionId, argument, scope);
+                }
+                if (operation.idempotencyKey) {
+                    linker.reads(actionId, operation.idempotencyKey, scope);
+                }
+                if (operation.succeededEventId) {
+                    linker.link(actionId, operation.succeededEventId, 'references');
+                }
+                if (operation.failedEventId) {
+                    linker.link(actionId, operation.failedEventId, 'references');
+                }
+                break;
             default:
         }
     }

package/dist/diagnostics.d.ts

@@ -88,5 +88,24 @@ export declare const VALIDATION_CODES: {
     readonly serverOnlyStateObserved: "SERVER_ONLY_STATE_OBSERVED";
     readonly invalidPrincipalEntity: "INVALID_PRINCIPAL_ENTITY";
     readonly missingActionArgument: "MISSING_ACTION_ARGUMENT";
+    /** An `IntegrationOperationDef.integrationId`, or an operation's `operationId`, that does not resolve. */
+    readonly unknownIntegration: "UNKNOWN_INTEGRATION";
+    readonly unknownIntegrationOperation: "UNKNOWN_INTEGRATION_OPERATION";
+    /** An `integration-query` operation naming an effect, or an `integration-effect` naming a query. */
+    readonly integrationOperationModeMismatch: "INTEGRATION_OPERATION_MODE_MISMATCH";
+    /** A missing required argument, or an argument the operation declares no parameter for. */
+    readonly integrationArgumentMismatch: "INTEGRATION_ARGUMENT_MISMATCH";
+    readonly triggerActionNotFound: "TRIGGER_ACTION_NOT_FOUND";
+    readonly triggerIntervalNotPositive: "TRIGGER_INTERVAL_NOT_POSITIVE";
+    /** An event id that does not resolve to an `EventDef` — a trigger's `eventId`, or an effect's success/failure event. */
+    readonly unknownEvent: "UNKNOWN_EVENT";
+    /** An `event` trigger targeting a client-authority action, or a `route-enter`/`route-leave` trigger targeting a server-authority one. */
+    readonly triggerWrongAuthority: "TRIGGER_WRONG_AUTHORITY";
+    /** A trigger — which always invokes with `source: 'system'` — targets an action whose `invocation.allowedSources` excludes `'system'`; the trigger could never succeed. */
+    readonly triggerTargetSourceMismatch: "TRIGGER_TARGET_SOURCE_MISMATCH";
+    /** `ActionDef.invocation.allowedSources` is present but empty — the action could never be invoked at all. */
+    readonly invalidInvocationSource: "INVALID_INVOCATION_SOURCE";
+    /** A client-authority trigger of a kind the intended trigger runtime does not execute — it would validate and compile but never fire (spec 8.1 §31-36). */
+    readonly clientTriggerUnsupported: "CLIENT_TRIGGER_UNSUPPORTED";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -76,4 +76,24 @@ export const VALIDATION_CODES = {
     serverOnlyStateObserved: 'SERVER_ONLY_STATE_OBSERVED',
     invalidPrincipalEntity: 'INVALID_PRINCIPAL_ENTITY',
     missingActionArgument: 'MISSING_ACTION_ARGUMENT',
+    // Integrations, effects, triggers and events.
+    /** An `IntegrationOperationDef.integrationId`, or an operation's `operationId`, that does not resolve. */
+    unknownIntegration: 'UNKNOWN_INTEGRATION',
+    unknownIntegrationOperation: 'UNKNOWN_INTEGRATION_OPERATION',
+    /** An `integration-query` operation naming an effect, or an `integration-effect` naming a query. */
+    integrationOperationModeMismatch: 'INTEGRATION_OPERATION_MODE_MISMATCH',
+    /** A missing required argument, or an argument the operation declares no parameter for. */
+    integrationArgumentMismatch: 'INTEGRATION_ARGUMENT_MISMATCH',
+    triggerActionNotFound: 'TRIGGER_ACTION_NOT_FOUND',
+    triggerIntervalNotPositive: 'TRIGGER_INTERVAL_NOT_POSITIVE',
+    /** An event id that does not resolve to an `EventDef` — a trigger's `eventId`, or an effect's success/failure event. */
+    unknownEvent: 'UNKNOWN_EVENT',
+    /** An `event` trigger targeting a client-authority action, or a `route-enter`/`route-leave` trigger targeting a server-authority one. */
+    triggerWrongAuthority: 'TRIGGER_WRONG_AUTHORITY',
+    /** A trigger — which always invokes with `source: 'system'` — targets an action whose `invocation.allowedSources` excludes `'system'`; the trigger could never succeed. */
+    triggerTargetSourceMismatch: 'TRIGGER_TARGET_SOURCE_MISMATCH',
+    /** `ActionDef.invocation.allowedSources` is present but empty — the action could never be invoked at all. */
+    invalidInvocationSource: 'INVALID_INVOCATION_SOURCE',
+    /** A client-authority trigger of a kind the intended trigger runtime does not execute — it would validate and compile but never fire (spec 8.1 §31-36). */
+    clientTriggerUnsupported: 'CLIENT_TRIGGER_UNSUPPORTED',
 };

package/dist/effect-outcome.d.ts

@@ -0,0 +1,43 @@
+import type { FieldId, NodeId } from './ids.js';
+import type { EntityDef } from './nodes.js';
+import type { TypeRef } from './type-ref.js';
+/**
+ * Reserved field ids for an `integration-effect`'s `succeededEventId`/`failedEventId`
+ * payload — spec 8.1 §37-41's structured envelope, replacing the 0.8.0 shape (the raw
+ * adapter result for success, a formatted `"<code>: <message>"` string for failure) that
+ * forced a follow-up action to parse text to correlate a failure back to the effect that
+ * caused it.
+ *
+ * One shape covers both outcomes (spec §40's "structured `EffectOutcome` envelope for both
+ * success/failure"), rather than a distinct entity per outcome: field ids are unique across
+ * a whole graph — like `GROUP_KEY_FIELD`/`GROUP_ITEMS_FIELD` — so two entities could not both
+ * declare `effectId`/`operationId`/`integrationId` without colliding. A success dispatch
+ * populates `result`; a failure dispatch populates `code`/`message`/`retryable`; neither
+ * ever populates both, and none of `result`/`code`/`message`/`retryable` is `required`, so
+ * either shape validates.
+ *
+ * Unlike `GROUP_KEY_FIELD`/`GROUP_ITEMS_FIELD`, these are not runtime-enforced reservations
+ * — a payload is validated as an ordinary `entity` type, the same as any other event. They
+ * are a naming convention plus the builder below, so every application's effect outcome
+ * events share one shape an agent only has to learn once.
+ */
+export declare const EFFECT_ID_FIELD: FieldId;
+export declare const EFFECT_INTEGRATION_ID_FIELD: FieldId;
+export declare const EFFECT_OPERATION_ID_FIELD: FieldId;
+export declare const EFFECT_CODE_FIELD: FieldId;
+export declare const EFFECT_MESSAGE_FIELD: FieldId;
+export declare const EFFECT_RETRYABLE_FIELD: FieldId;
+export declare const EFFECT_IDEMPOTENCY_KEY_FIELD: FieldId;
+export declare const EFFECT_CORRELATION_ID_FIELD: FieldId;
+export declare const EFFECT_RESULT_FIELD: FieldId;
+/**
+ * The canonical entity shape for an `integration-effect`'s `succeededEventId` and
+ * `failedEventId` payload alike. Declare it once with
+ * `graph.addNode(effectOutcomeEntity(ENTITY_ID, resultType))` and reference it from both
+ * `EventDef`s with `entityType(ENTITY_ID)`. `resultType` is the effect operation's own
+ * declared result type — if a graph's effect operations return incompatible result types,
+ * they need either a common supertype here or their own outcome entity each (field ids are
+ * graph-global, so at most one `effectOutcomeEntity` may share a given result shape).
+ */
+export declare function effectOutcomeEntity(id: NodeId, resultType: TypeRef): EntityDef;
+//# sourceMappingURL=effect-outcome.d.ts.map

package/dist/effect-outcome.js

@@ -0,0 +1,57 @@
+import { fieldId } from './ids.js';
+import { primitiveType } from './type-ref.js';
+/**
+ * Reserved field ids for an `integration-effect`'s `succeededEventId`/`failedEventId`
+ * payload — spec 8.1 §37-41's structured envelope, replacing the 0.8.0 shape (the raw
+ * adapter result for success, a formatted `"<code>: <message>"` string for failure) that
+ * forced a follow-up action to parse text to correlate a failure back to the effect that
+ * caused it.
+ *
+ * One shape covers both outcomes (spec §40's "structured `EffectOutcome` envelope for both
+ * success/failure"), rather than a distinct entity per outcome: field ids are unique across
+ * a whole graph — like `GROUP_KEY_FIELD`/`GROUP_ITEMS_FIELD` — so two entities could not both
+ * declare `effectId`/`operationId`/`integrationId` without colliding. A success dispatch
+ * populates `result`; a failure dispatch populates `code`/`message`/`retryable`; neither
+ * ever populates both, and none of `result`/`code`/`message`/`retryable` is `required`, so
+ * either shape validates.
+ *
+ * Unlike `GROUP_KEY_FIELD`/`GROUP_ITEMS_FIELD`, these are not runtime-enforced reservations
+ * — a payload is validated as an ordinary `entity` type, the same as any other event. They
+ * are a naming convention plus the builder below, so every application's effect outcome
+ * events share one shape an agent only has to learn once.
+ */
+export const EFFECT_ID_FIELD = fieldId('field_effect_id');
+export const EFFECT_INTEGRATION_ID_FIELD = fieldId('field_effect_integration_id');
+export const EFFECT_OPERATION_ID_FIELD = fieldId('field_effect_operation_id');
+export const EFFECT_CODE_FIELD = fieldId('field_effect_code');
+export const EFFECT_MESSAGE_FIELD = fieldId('field_effect_message');
+export const EFFECT_RETRYABLE_FIELD = fieldId('field_effect_retryable');
+export const EFFECT_IDEMPOTENCY_KEY_FIELD = fieldId('field_effect_idempotency_key');
+export const EFFECT_CORRELATION_ID_FIELD = fieldId('field_effect_correlation_id');
+export const EFFECT_RESULT_FIELD = fieldId('field_effect_result');
+/**
+ * The canonical entity shape for an `integration-effect`'s `succeededEventId` and
+ * `failedEventId` payload alike. Declare it once with
+ * `graph.addNode(effectOutcomeEntity(ENTITY_ID, resultType))` and reference it from both
+ * `EventDef`s with `entityType(ENTITY_ID)`. `resultType` is the effect operation's own
+ * declared result type — if a graph's effect operations return incompatible result types,
+ * they need either a common supertype here or their own outcome entity each (field ids are
+ * graph-global, so at most one `effectOutcomeEntity` may share a given result shape).
+ */
+export function effectOutcomeEntity(id, resultType) {
+    return {
+        id,
+        kind: 'entity',
+        fields: [
+            { id: EFFECT_ID_FIELD, valueType: primitiveType('string'), required: true },
+            { id: EFFECT_INTEGRATION_ID_FIELD, valueType: primitiveType('string'), required: true },
+            { id: EFFECT_OPERATION_ID_FIELD, valueType: primitiveType('string'), required: true },
+            { id: EFFECT_RESULT_FIELD, valueType: resultType },
+            { id: EFFECT_CODE_FIELD, valueType: primitiveType('string') },
+            { id: EFFECT_MESSAGE_FIELD, valueType: primitiveType('string') },
+            { id: EFFECT_RETRYABLE_FIELD, valueType: primitiveType('boolean') },
+            { id: EFFECT_IDEMPOTENCY_KEY_FIELD, valueType: primitiveType('string') },
+            { id: EFFECT_CORRELATION_ID_FIELD, valueType: primitiveType('string') },
+        ],
+    };
+}

package/dist/events.d.ts

@@ -0,0 +1,13 @@
+import type { NodeBase } from './nodes.js';
+import type { TypeRef } from './type-ref.js';
+/**
+ * A semantic fact that occurred — a webhook delivery, an effect's outcome. An event is
+ * not work: it names something that happened, with a typed payload, and it is `TriggerDef`
+ * that says what happens next. Nothing resolves an event payload as `unknown`; it is
+ * validated against `payloadType` before it reaches any action.
+ */
+export interface EventDef extends NodeBase {
+    kind: 'event';
+    payloadType: TypeRef;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/graph.js

@@ -23,7 +23,7 @@ export class ApplicationGraph {
     /** Bumped by every change, so the derived edge index can never serve stale data. */
     revision = 0;
     semanticIndex;
-    constructor(id, name, version = '0.7.0') {
+    constructor(id, name, version = '0.8.1') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {

package/dist/index.d.ts

@@ -7,7 +7,12 @@ export * from './type-ref.js';
 export * from './group.js';
 export * from './expressions.js';
 export * from './nodes.js';
+export * from './integrations.js';
+export * from './effect-outcome.js';
+export * from './events.js';
+export * from './triggers.js';
 export * from './renderer-capabilities.js';
+export * from './trigger-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.js';
 export * from './types.js';

package/dist/index.js

@@ -7,7 +7,12 @@ export * from './type-ref.js';
 export * from './group.js';
 export * from './expressions.js';
 export * from './nodes.js';
+export * from './integrations.js';
+export * from './effect-outcome.js';
+export * from './events.js';
+export * from './triggers.js';
 export * from './renderer-capabilities.js';
+export * from './trigger-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.js';
 export * from './types.js';

package/dist/integrations.d.ts

@@ -0,0 +1,57 @@
+import type { NodeId } from './ids.js';
+import type { NodeBase } from './nodes.js';
+import type { TypeRef } from './type-ref.js';
+/**
+ * An external capability domain — a shipping provider, a device fleet, a payments
+ * processor. It names the capability, never the SDK, host name, secret or HTTP client
+ * that eventually implements it: those are supplied by a host adapter, never by the
+ * graph.
+ */
+export interface IntegrationDef extends NodeBase {
+    kind: 'integration';
+}
+/**
+ * A query observes an external system and does not intentionally mutate it. An effect
+ * may mutate or otherwise cause an irreversible external consequence. The distinction is
+ * load-bearing: a query's result may be used mid-transaction, while an effect is never
+ * rollback-capable and is dispatched only after the transaction that requested it commits.
+ */
+export type IntegrationOperationMode = 'query' | 'effect';
+export declare const INTEGRATION_OPERATION_MODES: readonly IntegrationOperationMode[];
+export type RetryPolicyKind = 'none' | 'fixed' | 'exponential';
+export declare const RETRY_POLICY_KINDS: readonly RetryPolicyKind[];
+export interface RetryPolicy {
+    policy: RetryPolicyKind;
+    maxAttempts?: number;
+    delayMs?: number;
+}
+export interface IntegrationOperationParameter {
+    id: NodeId;
+    name?: string;
+    valueType: TypeRef;
+    required?: boolean;
+}
+/**
+ * A typed semantic operation an integration exposes.
+ *
+ * Its result must conform to `resultType` — a provider response that does not is rejected
+ * at the adapter/runtime boundary, never handed to the application as `unknown`.
+ */
+export interface IntegrationOperationDef extends NodeBase {
+    kind: 'integration-operation';
+    integrationId: NodeId;
+    mode: IntegrationOperationMode;
+    parameters?: IntegrationOperationParameter[];
+    resultType: TypeRef;
+    /**
+     * Whether this operation may be invoked from client-executed code. Absent means
+     * server-only, which is the default for every integration (spec §65): client safety is
+     * never inferred from the absence of a declared secret, only declared explicitly.
+     */
+    clientSafe?: boolean;
+    /** Whether invoking this effect twice with the same idempotency key has one effect. */
+    idempotent?: boolean;
+    /** Retry policy for a failed effect. Absent means `'none'`. Meaningless for a query. */
+    retry?: RetryPolicy;
+}
+//# sourceMappingURL=integrations.d.ts.map

package/dist/integrations.js

@@ -0,0 +1,2 @@
+export const INTEGRATION_OPERATION_MODES = ['query', 'effect'];
+export const RETRY_POLICY_KINDS = ['none', 'fixed', 'exponential'];

package/dist/ir.d.ts

@@ -7,6 +7,7 @@ import type { TypeRef } from './type-ref.js';
 import type { Authority } from './authority.js';
 import type { ResolvedPresentation } from './presentation.js';
 import type { Theme } from './theme.js';
+import type { TriggerDef } from './triggers.js';
 export interface RouteSegment {
     kind: 'static' | 'parameter';
     value: string;
@@ -92,5 +93,13 @@ export interface ApplicationIR {
      * second renderer remains possible.
      */
     presentation: Record<NodeId, ResolvedPresentation>;
+    /**
+     * Client-authority triggers only — `interval`/`delay`/`lifecycle('application-start' |
+     * 'runtime-ready')` triggers whose target action executes locally, plus
+     * `lifecycle('route-enter' | 'route-leave')` triggers, which are inherently a client
+     * concept. No `event`-kind trigger, no integration, and no secret ever reaches this IR
+     * (spec §80).
+     */
+    triggers: TriggerDef[];
 }
 //# sourceMappingURL=ir.d.ts.map

package/dist/nodes.d.ts

@@ -174,6 +174,27 @@ export interface ActionGuard {
     condition: Expression;
     failureMode?: FailureMode;
 }
+/**
+ * `'client'` is an ordinary `InvokeRequest`; `'system'` is a trigger-, event- or
+ * effect-outcome-originated invocation. Server-computed and client-unforgeable — see
+ * `ExecutionContext.source` in `@cynodia/axiom-server`.
+ */
+export type InvocationSource = 'client' | 'system';
+export declare const INVOCATION_SOURCES: readonly InvocationSource[];
+/** Both sources, the default when `ActionDef.invocation` is absent (spec 8.1 §5). */
+export declare const DEFAULT_ALLOWED_INVOCATION_SOURCES: readonly InvocationSource[];
+/**
+ * Restricts who may invoke an action, independently of `authorization`'s identity check.
+ *
+ * `authorization` answers "may this caller invoke this action"; `invocation` answers "may
+ * an invocation reaching the authority this way invoke this action at all" — the trust
+ * boundary a trigger-only or effect-outcome-only action needs, since otherwise any anonymous
+ * client that knows its id can invoke it directly (spec 8.1 §3-9).
+ */
+export interface ActionInvocationPolicy {
+    /** Absent means both — identical to omitting `invocation` entirely. */
+    allowedSources?: readonly InvocationSource[];
+}
 /**
  * Behaviour expressed as data, executed as a transaction.
  *
@@ -210,13 +231,21 @@ export interface ActionDef extends NodeBase {
     authorization?: Expression;
     /** What the confirmation says, when a plain message is not enough. */
     confirmation?: ConfirmationPresentation;
+    /** Restricts which invocation sources may reach this action. Absent means both. */
+    invocation?: ActionInvocationPolicy;
 }
 /**
  * The conditions an action checks, however they were written. `guards` pairs each
  * condition with its failure; the older parallel arrays are matched by position.
  */
 export declare function actionGuards(action: ActionDef): ActionGuard[];
-export type Operation = SetOperation | InsertOperation | RemoveOperation | ForEachOperation | InvokeOperation | NavigateOperation | NativeOperation;
+/** The invocation sources this action accepts — both, unless `invocation` restricts it. */
+export declare function allowedInvocationSources(action: ActionDef): readonly InvocationSource[];
+/** Whether an ordinary client `InvokeRequest` may name this action at all. */
+export declare function isClientInvocable(action: ActionDef): boolean;
+/** Whether this action accepts only trigger-, event- or effect-outcome-originated calls. */
+export declare function isSystemOnlyAction(action: ActionDef): boolean;
+export type Operation = SetOperation | InsertOperation | RemoveOperation | ForEachOperation | InvokeOperation | NavigateOperation | NativeOperation | IntegrationQueryOperation | IntegrationEffectOperation;
 export type OperationKind = Operation['kind'];
 /** Every operation kind the runtime is required to execute. */
 export declare const OPERATION_KINDS: readonly OperationKind[];
@@ -290,6 +319,44 @@ export interface NavigateOperation {
     /** Keyed by route parameter id. */
     parameters?: Record<string, Expression>;
 }
+/**
+ * Executes an integration query and binds its result into scope for later operations in
+ * the same action.
+ *
+ * A query is awaited mid-transaction — its result may inform the mutations that follow —
+ * but evaluating it is not an ordinary Expression, because it is not deterministic over
+ * semantic state alone. `bindAs` introduces a scope the way a `for-each`'s `scopeId` does:
+ * later operations refer to the whole result as `ref(bindAs)`. Never legal inside
+ * `for-each`.
+ */
+export interface IntegrationQueryOperation {
+    kind: 'integration-query';
+    /** The `IntegrationOperationDef` to call. Must declare `mode: 'query'`. */
+    operationId: NodeId;
+    arguments?: Record<string, Expression>;
+    bindAs: NodeId;
+    timeoutMs?: number;
+}
+/**
+ * Records intent to perform an external effect. It never calls the adapter during the
+ * transaction: reaching this operation only appends an effect intent, discarded on
+ * rollback exactly like a mutation is. Dispatch to the adapter happens only after the
+ * surrounding transaction commits — the outbox invariant (spec §18) — so an effect is
+ * never rollback-capable and never mid-transaction. Never legal inside `for-each`.
+ *
+ * `succeededEventId`/`failedEventId`, when declared, are dispatched through the ordinary
+ * event pipeline once the effect's outcome is known — an effect's result is never folded
+ * back into the transaction that requested it.
+ */
+export interface IntegrationEffectOperation {
+    kind: 'integration-effect';
+    /** The `IntegrationOperationDef` to call. Must declare `mode: 'effect'`. */
+    operationId: NodeId;
+    arguments?: Record<string, Expression>;
+    idempotencyKey?: Expression;
+    succeededEventId?: NodeId;
+    failedEventId?: NodeId;
+}
 export type NativeEffect = {
     kind: 'reads-state';
     stateId: NodeId;

package/dist/nodes.js

@@ -1,3 +1,6 @@
+export const INVOCATION_SOURCES = ['client', 'system'];
+/** Both sources, the default when `ActionDef.invocation` is absent (spec 8.1 §5). */
+export const DEFAULT_ALLOWED_INVOCATION_SOURCES = INVOCATION_SOURCES;
 /**
  * The conditions an action checks, however they were written. `guards` pairs each
  * condition with its failure; the older parallel arrays are matched by position.
@@ -11,6 +14,19 @@ export function actionGuards(action) {
         ...(action.failureModes?.[index] ? { failureMode: action.failureModes[index] } : {}),
     }));
 }
+/** The invocation sources this action accepts — both, unless `invocation` restricts it. */
+export function allowedInvocationSources(action) {
+    return action.invocation?.allowedSources ?? DEFAULT_ALLOWED_INVOCATION_SOURCES;
+}
+/** Whether an ordinary client `InvokeRequest` may name this action at all. */
+export function isClientInvocable(action) {
+    return allowedInvocationSources(action).includes('client');
+}
+/** Whether this action accepts only trigger-, event- or effect-outcome-originated calls. */
+export function isSystemOnlyAction(action) {
+    const sources = allowedInvocationSources(action);
+    return sources.includes('system') && !sources.includes('client');
+}
 /** Every operation kind the runtime is required to execute. */
 export const OPERATION_KINDS = [
     'set',
@@ -20,6 +36,8 @@ export const OPERATION_KINDS = [
     'invoke',
     'navigate',
     'native',
+    'integration-query',
+    'integration-effect',
 ];
 export function isMutationOperation(operation) {
     return operation.kind === 'set' || operation.kind === 'insert' || operation.kind === 'remove';