@cynodia/axiom-core 0.7.0-alpha.2 → 0.8.0-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,18 @@ 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";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -76,4 +76,18 @@ 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',
 };

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.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {

package/dist/index.d.ts

@@ -7,6 +7,9 @@ export * from './type-ref.js';
 export * from './group.js';
 export * from './expressions.js';
 export * from './nodes.js';
+export * from './integrations.js';
+export * from './events.js';
+export * from './triggers.js';
 export * from './renderer-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.js';

package/dist/index.js

@@ -7,6 +7,9 @@ export * from './type-ref.js';
 export * from './group.js';
 export * from './expressions.js';
 export * from './nodes.js';
+export * from './integrations.js';
+export * from './events.js';
+export * from './triggers.js';
 export * from './renderer-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.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

@@ -216,7 +216,7 @@ export interface ActionDef extends NodeBase {
  * 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;
+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 +290,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

@@ -20,6 +20,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';

package/dist/server-ir.d.ts

@@ -2,6 +2,9 @@ import type { FieldId, NodeId } from './ids.js';
 import type { ActionDef, ConstraintDef, EntityDef, ExpressionDef, StateDef, TransitionConstraintDef } from './nodes.js';
 import type { Expression } from './expressions.js';
 import type { FieldIndexEntry } from './graph.js';
+import type { EventDef } from './events.js';
+import type { IntegrationDef, IntegrationOperationDef } from './integrations.js';
+import type { TriggerDef } from './triggers.js';
 /**
  * The contracts a Server IR may declare. A runtime that does not recognize the value MUST
  * refuse the IR rather than interpret it partially.
@@ -9,13 +12,15 @@ import type { FieldIndexEntry } from './graph.js';
  * `axiom.server.v1` is frozen and stays frozen. 0.7 adds two constructs to the expression
  * vocabulary — `group` and `expression-ref`, with the `expressionDefs` they resolve against
  * — and a document that uses them is **not** a v1 document: a conforming v1 runtime has
- * never heard of them and must refuse it rather than execute half of it. So the vocabulary a
- * document actually uses decides its label.
+ * never heard of them and must refuse it rather than execute half of it. 0.8 adds
+ * integrations, effects, triggers and events, which is a third, independent reason a
+ * document may not be a v1 (or v2) document. So the vocabulary a document actually uses
+ * decides its label.
  *
  * Every existing application therefore still compiles to a byte-identical
  * `axiom.server.v1` document, and the frozen conformance fixtures stay frozen.
  */
-export declare const SERVER_IR_CONTRACTS: readonly ["axiom.server.v1", "axiom.server.v2"];
+export declare const SERVER_IR_CONTRACTS: readonly ["axiom.server.v1", "axiom.server.v2", "axiom.server.v3"];
 export type ServerIRContract = (typeof SERVER_IR_CONTRACTS)[number];
 /** The oldest contract, and the one a document declares unless it needs more. */
 export declare const SERVER_IR_CONTRACT: ServerIRContract;
@@ -31,6 +36,18 @@ export declare const SERVER_IR_V2_EXPRESSION_KINDS: readonly string[];
  * document breaks.
  */
 export declare function requiredServerContract(expressions: readonly Expression[]): ServerIRContract;
+/**
+ * Whether a document's integration/trigger/event vocabulary requires `axiom.server.v3` —
+ * none of it exists in v1 or v2, so any of it present is enough.
+ */
+export declare function usesIntegrationVocabulary(ir: {
+    integrations?: readonly unknown[];
+    integrationOperations?: Record<string, unknown>;
+    events?: readonly unknown[];
+    triggers?: readonly unknown[];
+}): boolean;
+/** The higher of two contracts, ordered by `SERVER_IR_CONTRACTS`. */
+export declare function maxContract(a: ServerIRContract, b: ServerIRContract): ServerIRContract;
 /** Every expression a Server IR document contains, in no particular order. */
 export declare function serverIRExpressions(ir: {
     states: readonly StateDef[];
@@ -38,6 +55,7 @@ export declare function serverIRExpressions(ir: {
     constraints: readonly ConstraintDef[];
     transitionConstraints: readonly TransitionConstraintDef[];
     expressionDefs?: Record<NodeId, ExpressionDef>;
+    triggers?: readonly TriggerDef[];
 }): Expression[];
 /**
  * The normalized form an authority executes: everything required to decide a mutation, and
@@ -80,5 +98,17 @@ export interface ServerIR {
     principalEntityId?: NodeId;
     /** The states a client is permitted to observe, in declaration order. */
     observableStateIds: NodeId[];
+    /**
+     * External capability domains this document calls out to. Absent in `axiom.server.v1`
+     * and `v2` documents, which have no way to reference one. Never carries a secret,
+     * host name or SDK — only the semantic operation shape (spec §5).
+     */
+    integrations?: IntegrationDef[];
+    /** Typed operations the integrations above expose, by id — dispatched by id constantly. */
+    integrationOperations?: Record<NodeId, IntegrationOperationDef>;
+    /** Semantic facts this document's triggers react to. */
+    events?: EventDef[];
+    /** Server-authority triggers only — interval, delay, lifecycle and event triggers whose target action executes here. */
+    triggers?: TriggerDef[];
 }
 //# sourceMappingURL=server-ir.d.ts.map

package/dist/server-ir.js

@@ -6,17 +6,19 @@ import { walkExpression } from './expressions.js';
  * `axiom.server.v1` is frozen and stays frozen. 0.7 adds two constructs to the expression
  * vocabulary — `group` and `expression-ref`, with the `expressionDefs` they resolve against
  * — and a document that uses them is **not** a v1 document: a conforming v1 runtime has
- * never heard of them and must refuse it rather than execute half of it. So the vocabulary a
- * document actually uses decides its label.
+ * never heard of them and must refuse it rather than execute half of it. 0.8 adds
+ * integrations, effects, triggers and events, which is a third, independent reason a
+ * document may not be a v1 (or v2) document. So the vocabulary a document actually uses
+ * decides its label.
  *
  * Every existing application therefore still compiles to a byte-identical
  * `axiom.server.v1` document, and the frozen conformance fixtures stay frozen.
  */
-export const SERVER_IR_CONTRACTS = ['axiom.server.v1', 'axiom.server.v2'];
+export const SERVER_IR_CONTRACTS = ['axiom.server.v1', 'axiom.server.v2', 'axiom.server.v3'];
 /** The oldest contract, and the one a document declares unless it needs more. */
 export const SERVER_IR_CONTRACT = 'axiom.server.v1';
 /** The newest contract this implementation produces and executes. */
-export const SERVER_IR_LATEST_CONTRACT = 'axiom.server.v2';
+export const SERVER_IR_LATEST_CONTRACT = 'axiom.server.v3';
 /** Expression kinds that `axiom.server.v1` does not contain. */
 export const SERVER_IR_V2_EXPRESSION_KINDS = ['group', 'expression-ref'];
 /**
@@ -37,6 +39,20 @@ export function requiredServerContract(expressions) {
     }
     return required;
 }
+/**
+ * Whether a document's integration/trigger/event vocabulary requires `axiom.server.v3` —
+ * none of it exists in v1 or v2, so any of it present is enough.
+ */
+export function usesIntegrationVocabulary(ir) {
+    return ((ir.integrations?.length ?? 0) > 0 ||
+        Object.keys(ir.integrationOperations ?? {}).length > 0 ||
+        (ir.events?.length ?? 0) > 0 ||
+        (ir.triggers?.length ?? 0) > 0);
+}
+/** The higher of two contracts, ordered by `SERVER_IR_CONTRACTS`. */
+export function maxContract(a, b) {
+    return SERVER_IR_CONTRACTS.indexOf(b) > SERVER_IR_CONTRACTS.indexOf(a) ? b : a;
+}
 /** Every expression a Server IR document contains, in no particular order. */
 export function serverIRExpressions(ir) {
     const found = [];
@@ -57,6 +73,12 @@ export function serverIRExpressions(ir) {
     for (const definition of Object.values(ir.expressionDefs ?? {})) {
         found.push(definition.expression);
     }
+    for (const trigger of ir.triggers ?? []) {
+        found.push(...Object.values(trigger.arguments ?? {}));
+        if (trigger.enabledWhen) {
+            found.push(trigger.enabledWhen);
+        }
+    }
     return found;
 }
 function actionExpressions(action) {
@@ -86,6 +108,15 @@ function actionExpressions(action) {
                 case 'native':
                     found.push(...Object.values(operation.inputs ?? {}));
                     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:
             }
         }

package/dist/triggers.d.ts

@@ -0,0 +1,53 @@
+import type { Expression } from './expressions.js';
+import type { NodeId } from './ids.js';
+import type { NodeBase } from './nodes.js';
+/**
+ * What happens when a tick fires while the previous invocation of the same trigger is
+ * still running. `'skip'` (the default) no-ops the tick; `'queue'` runs one pending tick
+ * immediately after the in-flight one finishes. Neither ever runs two invocations of the
+ * same trigger concurrently — overlap is never accidental.
+ */
+export type TriggerOverlapPolicy = 'skip' | 'queue';
+export declare const TRIGGER_OVERLAP_POLICIES: readonly TriggerOverlapPolicy[];
+export type LifecycleEvent = 'application-start' | 'runtime-ready' | 'route-enter' | 'route-leave';
+export declare const LIFECYCLE_EVENTS: readonly LifecycleEvent[];
+export type TriggerKind = 'interval' | 'delay' | 'lifecycle' | 'event';
+export declare const TRIGGER_KINDS: readonly TriggerKind[];
+/**
+ * When a trigger fires. `everyMs`/`afterMs` are plain numbers, never expressions —
+ * scheduling stays static; only `TriggerDef.enabledWhen` is dynamic.
+ */
+export type TriggerSpec = {
+    kind: 'interval';
+    everyMs: number;
+    overlap?: TriggerOverlapPolicy;
+} | {
+    kind: 'delay';
+    afterMs: number;
+} | {
+    kind: 'lifecycle';
+    event: LifecycleEvent;
+    routeId?: NodeId;
+} | {
+    kind: 'event';
+    eventId: NodeId;
+};
+/**
+ * Describes when an action should be invoked, without embedding callback code.
+ *
+ * A trigger invokes the target action through the same semantics as any other caller —
+ * the same guards, constraints, transition constraints and authorization apply. For an
+ * `event`-kind trigger, `arguments` expressions may `ref` the trigger's own id to read the
+ * event's payload, the same way a `for-each`/`map` scope id lets a body read the current
+ * member.
+ */
+export interface TriggerDef extends NodeBase {
+    kind: 'trigger';
+    actionId: NodeId;
+    when: TriggerSpec;
+    /** Keyed by the target action's parameter id. */
+    arguments?: Record<string, Expression>;
+    /** Dynamic enablement — evaluated each time the trigger would otherwise fire. */
+    enabledWhen?: Expression;
+}
+//# sourceMappingURL=triggers.d.ts.map

package/dist/triggers.js

@@ -0,0 +1,8 @@
+export const TRIGGER_OVERLAP_POLICIES = ['skip', 'queue'];
+export const LIFECYCLE_EVENTS = [
+    'application-start',
+    'runtime-ready',
+    'route-enter',
+    'route-leave',
+];
+export const TRIGGER_KINDS = ['interval', 'delay', 'lifecycle', 'event'];

package/dist/types.d.ts

@@ -2,11 +2,14 @@ import type { ActionDef, ConstraintDef, EntityDef, ExpressionDef, GraphEdge, Rou
 import type { NodeId } from './ids.js';
 import type { UINode, UINodeKind } from './ui.js';
 import type { ThemeInput } from './theme.js';
-export type SemanticNodeKind = 'entity' | 'state' | 'action' | 'constraint' | 'transition-constraint' | 'route' | 'expression';
+import type { EventDef } from './events.js';
+import type { IntegrationDef, IntegrationOperationDef } from './integrations.js';
+import type { TriggerDef } from './triggers.js';
+export type SemanticNodeKind = 'entity' | 'state' | 'action' | 'constraint' | 'transition-constraint' | 'route' | 'expression' | 'integration' | 'integration-operation' | 'event' | 'trigger';
 /** Every semantic node kind, enumerated so tests can walk them. */
 export declare const SEMANTIC_NODE_KINDS: readonly SemanticNodeKind[];
 export type NodeKind = SemanticNodeKind | UINodeKind;
-export type AnyNode = EntityDef | StateDef | ActionDef | ConstraintDef | TransitionConstraintDef | RouteDef | ExpressionDef | UINode;
+export type AnyNode = EntityDef | StateDef | ActionDef | ConstraintDef | TransitionConstraintDef | RouteDef | ExpressionDef | IntegrationDef | IntegrationOperationDef | EventDef | TriggerDef | UINode;
 export type NodeOfKind<K extends NodeKind> = Extract<AnyNode, {
     kind: K;
 }>;

package/dist/types.js

@@ -7,4 +7,8 @@ export const SEMANTIC_NODE_KINDS = [
     'transition-constraint',
     'route',
     'expression',
+    'integration',
+    'integration-operation',
+    'event',
+    'trigger',
 ];

package/dist/validate-authority.js

@@ -136,6 +136,35 @@ export function validateAuthority(nodes, principalEntityId) {
             }
         }
     }
+    // An `event` trigger only ever fires where the server dispatches an event, so its
+    // target action must be server-authority. A `route-enter`/`route-leave` trigger only
+    // ever fires from the client router, so its target must be client-authority.
+    for (const node of nodes) {
+        if (node.kind !== 'trigger') {
+            continue;
+        }
+        const target = context.actions.get(node.actionId);
+        if (!target) {
+            continue;
+        }
+        const authority = actionAuthority(target, context);
+        if (node.when.kind === 'event' && authority !== 'server') {
+            errors.push({
+                code: VALIDATION_CODES.triggerWrongAuthority,
+                message: `Trigger ${node.name ?? node.id} fires on an event, which only the server dispatches, but ${target.name ?? target.id} is client-authority`,
+                nodeId: node.id,
+                details: { actionId: target.id, authority },
+            });
+        }
+        if (node.when.kind === 'lifecycle' && (node.when.event === 'route-enter' || node.when.event === 'route-leave') && authority !== 'client') {
+            errors.push({
+                code: VALIDATION_CODES.triggerWrongAuthority,
+                message: `Trigger ${node.name ?? node.id} fires on ${node.when.event}, which only the client router dispatches, but ${target.name ?? target.id} is server-authority`,
+                nodeId: node.id,
+                details: { actionId: target.id, authority },
+            });
+        }
+    }
     // The principal exists only where an authority evaluates. Reading it anywhere a client
     // evaluates would be a rule the client could simply not apply.
     reportPrincipalOnClient(nodes, context, errors);

package/dist/validate.js

@@ -134,6 +134,18 @@ function validateNode(node, context) {
         case 'expression':
             validateExpressionDef(node, context);
             return;
+        case 'integration':
+            validateIntegrationDef(node, context);
+            return;
+        case 'integration-operation':
+            validateIntegrationOperation(node, context);
+            return;
+        case 'event':
+            validateEvent(node, context);
+            return;
+        case 'trigger':
+            validateTrigger(node, context);
+            return;
         default:
             context.errors.push({
                 code: VALIDATION_CODES.danglingNodeRef,
@@ -238,8 +250,9 @@ function validateAction(action, context) {
     for (const postcondition of action.postconditions ?? []) {
         validateExpression(postcondition, action.id, context, local);
     }
+    let scoped = local;
     for (const operation of action.operations ?? []) {
-        validateOperation(operation, action, context, local);
+        scoped = validateOperation(operation, action, context, scoped);
     }
 }
 function validateOperation(operation, action, context, local) {
@@ -266,13 +279,13 @@ function validateOperation(operation, action, context, local) {
                 }
                 validateOperation(nested, action, context, scoped);
             }
-            return;
+            return local;
         }
         case 'set': {
             checkLocation(operation.target, action.id, context, local, true);
             validateExpression(operation.value, action.id, context, local);
             checkAssignment(operation.target, operation.value, action.id, context, local);
-            return;
+            return local;
         }
         case 'insert': {
             checkLocation(operation.target, action.id, context, local, true);
@@ -284,16 +297,16 @@ function validateOperation(operation, action, context, local) {
                     message: `Action ${action.id} inserts into a ${target.kind} location, which is not a collection`,
                     nodeId: action.id,
                 });
-                return;
+                return local;
             }
             if (target?.kind === 'collection') {
                 reportIncompatible(target.itemType, inferExpressionType(operation.value, context.semantics, local.types), action.id, context);
             }
-            return;
+            return local;
         }
         case 'remove':
             checkLocation(operation.target, action.id, context, local, true);
-            return;
+            return local;
         case 'invoke': {
             requireKind(operation.actionId, 'action', action.id, context, VALIDATION_CODES.invalidActionRef);
             const target = context.nodes.get(operation.actionId);
@@ -307,7 +320,7 @@ function validateOperation(operation, action, context, local) {
                     });
                 }
             }
-            return;
+            return local;
         }
         case 'navigate':
             if (operation.routeId) {
@@ -323,7 +336,7 @@ function validateOperation(operation, action, context, local) {
             for (const argument of Object.values(operation.parameters ?? {})) {
                 validateExpression(argument, action.id, context, local);
             }
-            return;
+            return local;
         case 'native':
             for (const input of Object.values(operation.inputs ?? {})) {
                 validateExpression(input, action.id, context, local);
@@ -336,13 +349,61 @@ function validateOperation(operation, action, context, local) {
                     requireKind(effect.stateId, 'state', action.id, context, VALIDATION_CODES.invalidStateRef);
                 }
             }
-            return;
+            return local;
+        case 'integration-query': {
+            requireKind(operation.operationId, 'integration-operation', action.id, context, VALIDATION_CODES.unknownIntegrationOperation);
+            const target = context.nodes.get(operation.operationId);
+            let resultType;
+            if (target?.kind === 'integration-operation') {
+                if (target.mode !== 'query') {
+                    context.errors.push({
+                        code: VALIDATION_CODES.integrationOperationModeMismatch,
+                        message: `Action ${action.id} uses integration-query with ${operation.operationId}, which is an effect operation`,
+                        nodeId: action.id,
+                    });
+                }
+                resultType = target.resultType;
+                checkIntegrationArguments(target, operation.arguments ?? {}, action.id, context);
+            }
+            for (const argument of Object.values(operation.arguments ?? {})) {
+                validateExpression(argument, action.id, context, local);
+            }
+            return resultScope(local, operation.bindAs, resultType, context, action.id);
+        }
+        case 'integration-effect': {
+            requireKind(operation.operationId, 'integration-operation', action.id, context, VALIDATION_CODES.unknownIntegrationOperation);
+            const target = context.nodes.get(operation.operationId);
+            if (target?.kind === 'integration-operation') {
+                if (target.mode !== 'effect') {
+                    context.errors.push({
+                        code: VALIDATION_CODES.integrationOperationModeMismatch,
+                        message: `Action ${action.id} uses integration-effect with ${operation.operationId}, which is a query operation`,
+                        nodeId: action.id,
+                    });
+                }
+                checkIntegrationArguments(target, operation.arguments ?? {}, action.id, context);
+            }
+            for (const argument of Object.values(operation.arguments ?? {})) {
+                validateExpression(argument, action.id, context, local);
+            }
+            if (operation.idempotencyKey) {
+                validateExpression(operation.idempotencyKey, action.id, context, local);
+            }
+            if (operation.succeededEventId) {
+                requireKind(operation.succeededEventId, 'event', action.id, context, VALIDATION_CODES.unknownEvent);
+            }
+            if (operation.failedEventId) {
+                requireKind(operation.failedEventId, 'event', action.id, context, VALIDATION_CODES.unknownEvent);
+            }
+            return local;
+        }
         default:
             context.errors.push({
                 code: VALIDATION_CODES.danglingNodeRef,
                 message: `Unknown operation kind in action ${action.id}`,
                 nodeId: action.id,
             });
+            return local;
     }
 }
 function resolveKnownType(type) {
@@ -530,6 +591,122 @@ function validateRoute(route, context) {
         }
     }
 }
+function validateIntegrationDef(_integration, _context) {
+    // A capability-domain marker with no fields to check beyond the shared node identity
+    // checks already applied — declared explicitly so a new node kind never falls to the
+    // erroring `default:` branch of `validateNode`.
+}
+function validateIntegrationOperation(operation, context) {
+    requireKind(operation.integrationId, 'integration', operation.id, context, VALIDATION_CODES.unknownIntegration);
+    for (const parameter of operation.parameters ?? []) {
+        validateTypeRef(parameter.valueType, operation.id, context);
+    }
+    validateTypeRef(operation.resultType, operation.id, context);
+}
+function validateEvent(event, context) {
+    validateTypeRef(event.payloadType, event.id, context);
+}
+function validateTrigger(trigger, context) {
+    requireKind(trigger.actionId, 'action', trigger.id, context, VALIDATION_CODES.triggerActionNotFound);
+    const action = context.nodes.get(trigger.actionId);
+    if (trigger.when.kind === 'interval' && !(trigger.when.everyMs > 0)) {
+        context.errors.push({
+            code: VALIDATION_CODES.triggerIntervalNotPositive,
+            message: `Trigger ${trigger.id} declares a non-positive interval`,
+            nodeId: trigger.id,
+        });
+    }
+    if (trigger.when.kind === 'delay' && !(trigger.when.afterMs > 0)) {
+        context.errors.push({
+            code: VALIDATION_CODES.triggerIntervalNotPositive,
+            message: `Trigger ${trigger.id} declares a non-positive delay`,
+            nodeId: trigger.id,
+        });
+    }
+    if (trigger.when.kind === 'lifecycle' && trigger.when.routeId) {
+        requireKind(trigger.when.routeId, 'route', trigger.id, context, VALIDATION_CODES.danglingNodeRef);
+    }
+    // An `event` trigger's arguments/enabledWhen may `ref` the trigger's own id to read the
+    // event payload — the same mechanism a `for-each`/`map` scopeId provides.
+    let local = emptyScope();
+    if (trigger.when.kind === 'event') {
+        requireKind(trigger.when.eventId, 'event', trigger.id, context, VALIDATION_CODES.unknownEvent);
+        const event = context.nodes.get(trigger.when.eventId);
+        local = emptyScope(new Set([trigger.id]));
+        if (event?.kind === 'event') {
+            local.types.set(trigger.id, event.payloadType);
+        }
+    }
+    if (trigger.enabledWhen) {
+        validateExpression(trigger.enabledWhen, trigger.id, context, local);
+    }
+    if (action?.kind === 'action') {
+        requireArguments(trigger.actionId, trigger.arguments ?? {}, trigger.id, context, `Trigger ${trigger.id} supplies`);
+        for (const [parameterId, argument] of Object.entries(trigger.arguments ?? {})) {
+            validateExpression(argument, trigger.id, context, local);
+            if (!(action.parameters ?? []).some((p) => p.id === parameterId)) {
+                context.errors.push({
+                    code: VALIDATION_CODES.danglingNodeRef,
+                    message: `Trigger ${trigger.id} passes unknown parameter ${parameterId} to ${trigger.actionId}`,
+                    nodeId: trigger.id,
+                });
+            }
+        }
+    }
+}
+/** Missing required arguments, and arguments the operation declares no parameter for. */
+function checkIntegrationArguments(operation, args, ownerId, context) {
+    const declared = new Set((operation.parameters ?? []).map((parameter) => String(parameter.id)));
+    const missing = (operation.parameters ?? [])
+        .filter((parameter) => parameter.required && !(String(parameter.id) in args))
+        .map((parameter) => String(parameter.id));
+    if (missing.length > 0) {
+        context.errors.push({
+            code: VALIDATION_CODES.integrationArgumentMismatch,
+            message: `${ownerId} calls ${operation.id} without ${missing.join(', ')}`,
+            nodeId: ownerId,
+            details: { operationId: String(operation.id), missing },
+        });
+    }
+    for (const key of Object.keys(args)) {
+        if (!declared.has(key)) {
+            context.errors.push({
+                code: VALIDATION_CODES.integrationArgumentMismatch,
+                message: `${ownerId} supplies unknown argument ${key} to ${operation.id}`,
+                nodeId: ownerId,
+                details: { operationId: String(operation.id), argument: key },
+            });
+        }
+    }
+}
+/**
+ * Extends a scope with an integration query's whole result type — unlike `iterationScope`,
+ * the bound value is not unwrapped to a collection member.
+ */
+function resultScope(scope, scopeId, resultType, context, ownerId) {
+    if (scope.ids.has(scopeId)) {
+        context.errors.push({
+            code: VALIDATION_CODES.scopeShadowing,
+            message: `Scope ${scopeId} in ${ownerId} is already bound by an enclosing scope`,
+            nodeId: ownerId,
+        });
+    }
+    if (context.nodes.has(scopeId)) {
+        context.errors.push({
+            code: VALIDATION_CODES.scopeCollidesWithNode,
+            message: `Scope ${scopeId} in ${ownerId} has the same id as a graph node`,
+            nodeId: ownerId,
+        });
+    }
+    const types = new Map(scope.types);
+    if (resultType) {
+        types.set(scopeId, resultType);
+    }
+    else {
+        types.delete(scopeId);
+    }
+    return { ids: new Set([...scope.ids, scopeId]), types };
+}
 function validateUiNode(node, context) {
     if (node.visibleWhen) {
         validateExpression(node.visibleWhen, node.id, context, new Set());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-core",
-  "version": "0.7.0-alpha.2",
+  "version": "0.8.0-alpha.1",
   "description": "Application Graph, semantic types, locations and validation for Axiom.",
   "license": "MIT",
   "author": "AskTech AS",