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

package/README.md

@@ -6,8 +6,8 @@ Axiom represents application behavior, state, UI structure and presentation as s
 semantic data executed by generic runtimes. An application is a typed graph, not source
 files: the JavaScript and HTML that reach the browser are output, and are never edited.
 
-**Status: experimental / alpha (0.7.0-alpha.x).** The API may change between alpha
-releases. The documentation in `docs/` describes this exact version.
+**Status: experimental / alpha.** The API may change between alpha releases. The
+documentation in `docs/` describes this exact version.
 
 ## Installation
 

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.7.0-alpha.2. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.8.1-alpha.1. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {
@@ -86,7 +86,7 @@ All four failure sources are evaluated; the action does not stop at the first.
 
 ## Operations
 
-Seven kinds, enumerated by `OPERATION_KINDS`. `set`, `insert` and `remove` are the
+Nine kinds, enumerated by `OPERATION_KINDS`. `set`, `insert` and `remove` are the
 mutations; each addresses a [`Location`](LOCATIONS.md).
 
 ### `set`
@@ -179,6 +179,37 @@ The controlled boundary for behavior the operation vocabulary cannot express.
 **Use it only where no semantic primitive exists.** A native operation is opaque to every
 analysis Axiom offers.
 
+### `integration-query`
+
+```ts
+{ kind: 'integration-query', operationId: NodeId, arguments?: Record<string, Expression>, bindAs: NodeId, timeoutMs?: number }
+```
+
+Calls a `mode: 'query'` `IntegrationOperationDef` and binds its result into scope: later
+operations in the same action refer to it as `ref(bindAs)`, the same way a `for-each`'s
+`scopeId` introduces the current member. Resolved **before the transaction opens**, ahead
+of guards — a query is awaited, but never mid-transaction. Never legal inside `for-each`.
+Full model: [`INTEGRATIONS.md`](INTEGRATIONS.md).
+
+### `integration-effect`
+
+```ts
+{
+  kind: 'integration-effect',
+  operationId: NodeId,
+  arguments?: Record<string, Expression>,
+  idempotencyKey?: Expression,
+  succeededEventId?: NodeId,
+  failedEventId?: NodeId,
+}
+```
+
+Calls a `mode: 'effect'` `IntegrationOperationDef`. It **never calls the adapter during the
+transaction**: reaching this operation only records intent, discarded on rollback exactly
+like a mutation is. The adapter runs only after the transaction commits, and the response
+this action's caller gets back never waits for it — "committed, effect pending." Never legal
+inside `for-each`. Full model: [`EFFECTS.md`](EFFECTS.md).
+
 ## Authorization
 
 ```ts

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.7.0-alpha.2. The machine-facing interface. Agents query semantics and apply
+Axiom 0.8.1-alpha.1. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.7.0-alpha.2. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.8.1-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
 declarations before authoring or modifying an Axiom application.
 
 Formal guarantees: [`SEMANTIC_CONTRACT.md`](SEMANTIC_CONTRACT.md). Mistakes that compile:
@@ -31,7 +31,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.7.0'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.8.0'
 graph.addNode<StateDef>({ id, kind: 'state', ... }); // returns NodeId; throws if id exists
 graph.getNode<StateDef>(id);                        // deep clone, or undefined
 graph.updateNode(node);                             // write a modified node back
@@ -477,7 +477,7 @@ reads nothing from globals.
 
 ## Diagnostics
 
-23 runtime codes, all in `RUNTIME_DIAGNOSTIC_CODES`. Match on `code`, never on the message.
+30 runtime codes, all in `RUNTIME_DIAGNOSTIC_CODES`. Match on `code`, never on the message.
 Full table with `details` fields: [`RUNTIME.md`](RUNTIME.md#diagnostic-codes).
 
 ```ts
@@ -493,7 +493,7 @@ if (!result.ok) {
 ## Validation
 
 `validateGraph(graph)` → `{ valid, errors, warnings }`. `valid` is `errors.length === 0`;
-warnings never make a graph invalid. 49 codes in `VALIDATION_CODES`, grouped in
+warnings never make a graph invalid. 72 codes in `VALIDATION_CODES`, grouped in
 [`VALIDATION.md`](VALIDATION.md).
 
 ## Agent API
@@ -529,6 +529,13 @@ authoring an application that crosses the trust boundary.
 11. **IDEMPOTENCY** — a generated request id is unique across runtime instances; records are scoped by principal.
 12. **CHANGES** — `changes` names every observable state whose value moved, and no others.
 13. **PORTABILITY** — `axiom.server.v1` is frozen and language-independent.
+14. **INTEGRATION** — external systems are accessed through typed integration operations.
+15. **QUERY** — an external query is explicit action/trigger execution, never a pure `Expression`.
+16. **EFFECT** — external effects are not rollback-capable state mutations.
+17. **OUTBOX** — effect intent is committed before external execution, atomically with the state write that requested it.
+18. **TRIGGER** — triggers invoke ordinary actions, under the same guards, constraints and authorization.
+19. **EVENT** — events are typed facts; actions perform work.
+20. **SECRET** — credentials never live in graph semantics.
 
 ```ts
 { id: STATE_PRODUCTS, kind: 'state', authority: 'server' }                  // the authority owns it
@@ -590,6 +597,53 @@ through the same action-outcome lifecycle a local refusal uses — so a `diagnos
 presents a server refusal exactly as it presents a local one, and the control that started it
 renders `aria-busy` and refuses a second press until it settles.
 
+## INTEGRATIONS, EFFECTS, TRIGGERS
+
+Full model: [`INTEGRATIONS.md`](INTEGRATIONS.md), [`EFFECTS.md`](EFFECTS.md),
+[`TRIGGERS.md`](TRIGGERS.md), [`EVENTS.md`](EVENTS.md). These are the invariants to know
+before authoring an application that reaches an external system or reacts to time or an
+event.
+
+1. **INTEGRATION INVARIANT** — external systems are accessed through typed integration operations; the graph never carries an SDK, a host name or a secret.
+2. **QUERY INVARIANT** — external queries are explicit execution, resolved before the transaction they feed opens — never a pure `Expression`. `timeoutMs` is enforced by the runtime itself, not left to adapter cooperation; a non-cooperating adapter cannot wedge the invocation past its deadline (spec 8.1 §15-25).
+3. **EFFECT INVARIANT** — external effects are not rollback-capable state mutations. Reaching `integration-effect` only records intent; the adapter runs only after commit. The outcome reaches a follow-up action as a structured envelope (`effectOutcomeEntity` — `EFFECT_ID_FIELD`/`EFFECT_OPERATION_ID_FIELD`/…), never a raw result or a formatted string requiring text parsing to correlate (spec 8.1 §37-41).
+4. **OUTBOX INVARIANT** — effect intent is committed atomically with the state write that requested it, before external execution, so a crash between the two does not lose it.
+5. **TRIGGER INVARIANT** — a trigger invokes an ordinary action, under exactly the guards, constraints, transition constraints and authorization any other caller is subject to. Every invocation this authority runs — client request or trigger tick — is serialized against every other one, so simultaneous same-period triggers commit one at a time identically on the deterministic and the real host (spec 8.1 §26-30).
+6. **EVENT INVARIANT** — an event is a typed fact, validated against its declared payload type before any action sees it; an action is where work happens.
+7. **SECRET INVARIANT** — integration credentials live in host configuration (`AxiomServerOptions.integrations`), never in `ApplicationGraph`.
+8. **INVOCATION SOURCE INVARIANT** — a system-originated invocation (trigger, event, effect outcome) and an anonymous client request are distinct authoritative facts; a client cannot forge the former (`ExecutionContext.source` is server-computed, never read from protocol data), and `ActionDef.invocation.allowedSources` lets an action restrict which it accepts independently of `authorization`'s identity check (spec 8.1 §3-14).
+
+```ts
+{ kind: 'integration', id: INTEGRATION_DEVICE_PROVIDER }
+{
+  kind: 'integration-operation', id: OP_FETCH_STATUS, integrationId: INTEGRATION_DEVICE_PROVIDER,
+  mode: 'query', resultType: primitiveType('string'),
+}
+{
+  kind: 'action', id: ACTION_REFRESH,
+  operations: [
+    { kind: 'integration-query', operationId: OP_FETCH_STATUS, bindAs: SCOPE_STATUS },
+    { kind: 'set', target: stateLocation(STATE_STATUS), value: ref(SCOPE_STATUS) },
+  ],
+}
+{ kind: 'trigger', id: TRIGGER_POLL, actionId: ACTION_REFRESH, when: { kind: 'interval', everyMs: 5000 } }
+```
+
+- `mode: 'query'` may bind its result into scope (`bindAs`) for later operations in the same action; `mode: 'effect'` never runs synchronously and its outcome reaches an action only through a dispatched `succeededEventId`/`failedEventId`.
+- A trigger's target action runs where the action itself runs — server if it writes server state or calls an integration, client only for `route-enter`/`route-leave`. Derived, never declared, exactly like ordinary action authority.
+- A triggered/event-originated invocation runs with `principal: null`, `source: 'system'` — the same as an anonymous client request, never an impersonated user. Authorization still evaluates, and `invocation.allowedSources` is checked before it: `{ invocation: { allowedSources: ['system'] } }` refuses a direct client `InvokeRequest` with `INVOCATION_SOURCE_NOT_ALLOWED`, which is what protects a webhook- or effect-outcome-only action from being forged by a client that guessed its id.
+- `createDeterministicServerHost().advance(ms)` fires due timers deterministically; no trigger test waits on a real clock.
+
+```ts
+agent.listIntegrations() / agent.listIntegrationOperations(id?);
+agent.getActionsUsingIntegration(id) / agent.getEffectsForAction(actionId);
+agent.getTriggersForAction(actionId) / agent.getTimedTriggers();
+agent.getActionsTriggeredByEvent(eventId) / agent.getWebhookEvents();
+agent.getExternalDependencies();   // { integrations, operations } — the deployment manifest
+agent.getSystemOnlyActions() / agent.getTriggersTargetingClientOnlyActions();
+agent.isClientInvocable(actionId) / agent.isSystemOnly(actionId);
+```
+
 Portable artifacts, for a runtime written in another language:
 
 ```
@@ -600,8 +654,9 @@ Portable artifacts, for a runtime written in another language:
 ```
 
 Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZATION_DENIED`
-`CONCURRENCY_CONFLICT` `MALFORMED_REQUEST` `AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE`
-and `REMOTE_ACTION_UNAVAILABLE` on the client.
+`INVOCATION_SOURCE_NOT_ALLOWED` `CONCURRENCY_CONFLICT` `MALFORMED_REQUEST`
+`AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE` and `REMOTE_ACTION_UNAVAILABLE` on the
+client.
 
 ## Metadata classes
 

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.7.0-alpha.2. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.8.1-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -390,8 +390,11 @@ credential belongs to the host, not the graph.
 { kind: 'native', implementationId: 'app.sendEmail' }
 ```
 
-External effects are deliberately unsolved in 0.6. A design involving commands, a
-transactional outbox and idempotency is future work; do not smuggle one in meanwhile.
+Use `IntegrationDef` + an `integration-effect` operation instead — a typed semantic
+operation, dispatched post-commit through the durable outbox, with retry and an
+idempotency key, whose outcome reaches a follow-up action as a structured event rather than
+a side effect nothing can roll back. See [`INTEGRATIONS.md`](INTEGRATIONS.md) and
+[`EFFECTS.md`](EFFECTS.md).
 
 ## 31. Restating what the model already knows
 

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.7.0-alpha.2. How an application crosses the trust boundary.
+Axiom 0.8.1-alpha.1. How an application crosses the trust boundary.
 
 Until 0.5.x an Axiom application executed locally. 0.6 adds an **authority**: a generic
 runtime that owns state, decides mutations and persists them. The same semantic graph
@@ -32,6 +32,14 @@ describes both halves, so there is no backend to write.
 11. **IDEMPOTENCY** — an automatically generated request id is unique across runtime instances, whatever the host's uuid provider does. See [Idempotency](#idempotency).
 12. **CHANGES** — `InvokeResponse.changes` names every observable state whose value moved, and no others. See [Observing authoritative state](#observing-authoritative-state).
 13. **PORTABILITY** — `axiom.server.v1` semantics are language-independent, defined normatively by this document, the [schemas](#machine-readable-contracts) and the [conformance fixtures](#conformance). See [Server IR v1](#server-ir-v1-is-frozen).
+14. **INTEGRATION** — external systems are accessed through typed integration operations, never through `NativeOperation` or a raw request embedded in the graph. See [External systems](#external-systems).
+15. **QUERY** — an external query is explicit action/trigger execution, resolved before the transaction it feeds opens — never a pure `Expression`. See [External systems](#external-systems).
+16. **EFFECT** — an external effect is not a rollback-capable state mutation. It is recorded as intent, and dispatched only after the transaction that requested it commits. See [External effects](#external-effects).
+17. **OUTBOX** — effect intent is committed atomically with the state write that requested it, before the adapter is ever called. See [External effects](#external-effects).
+18. **TRIGGER** — a trigger invokes an ordinary action, under the same guards, constraints, transition constraints and authorization any other caller is subject to. See [Triggers](#triggers).
+19. **EVENT** — an event is a typed fact, validated against its declared payload type before any action sees it; an action is where work happens. See [External events](#external-events).
+20. **SECRET** — integration credentials live in host configuration, never in `ApplicationGraph`. See [External systems](#external-systems).
+21. **INVOCATION SOURCE** — a system-originated invocation (trigger, event, effect outcome) and an anonymous client request are distinct authoritative facts; a client cannot forge the former, and an action may restrict which it accepts independently of caller identity. See [Invocation source](#invocation-source).
 
 ## Authority and persistence are different questions
 
@@ -81,8 +89,49 @@ claim that validation already happened.
 | Forge an action id | resolved from the authority's own IR → `UNKNOWN_SERVER_ACTION` |
 | Send an argument of the wrong shape | checked against the declared type → `ARGUMENT_TYPE_MISMATCH` |
 | Invoke without permission | `authorization`, evaluated on the authority → `AUTHORIZATION_DENIED` |
+| Invoke an action reachable only by a trigger, event or effect outcome | `invocation.allowedSources` → `INVOCATION_SOURCE_NOT_ALLOWED` |
+| Claim to be a trigger, event or effect outcome | `context.source` is server-computed; no protocol field lets a request supply it |
 | Read server-only state | it is not in the client IR, the snapshot or any answer |
 
+## Invocation source
+
+`authorization` answers *who* may invoke an action; invocation source answers *how the
+invocation reached the authority at all* — a distinct question, because the two can diverge.
+An action meant only as a webhook's target, or only as an `integration-effect`'s
+`succeededEventId`/`failedEventId` handler, may declare no `authorization` at all — it was
+never meant to need one, since only the trigger runtime was ever supposed to call it. Before
+this existed, any client that guessed the action's id could invoke it directly, forging a
+fake webhook delivery or a fake effect outcome (spec 8.1 §3-9).
+
+```ts
+{
+  id: ACTION_APPLY_STATUS_CHANGE,
+  kind: 'action',
+  invocation: { allowedSources: ['system'] },   // a client InvokeRequest is refused
+  operations: [ /* … */ ],
+}
+```
+
+`allowedSources` is `['client', 'system']` — both — unless declared otherwise, so every
+existing graph keeps its current behavior. `'system'` covers every trigger kind (interval,
+delay, lifecycle, event) and every effect-outcome dispatch; there is no finer distinction,
+because a trigger invokes an action "through the same semantics as any other caller"
+([TRIGGER](#load-bearing-server-invariants)) and does not get a different one here either.
+
+The source itself is `ExecutionContext.source`, computed by the authority and never read
+from client-supplied protocol data — `InvokeRequest` and `EventRequest` carry no `source`
+field to forge in the first place. A client request is always `'client'`; a trigger-, event-
+or effect-outcome-originated invocation is always `'system'`, with `principal: null` exactly
+as an anonymous client's is, so `authorization` still evaluates and cannot be bypassed by a
+trigger either (spec §69,104) — invocation source and principal are deliberately separate
+questions, and a system invocation is not a stand-in identity.
+
+`checkInvocationSource` runs before `authorization`, before argument-driven work, and before
+any transaction opens: a refusal changes nothing, commits nothing, and dispatches no effect
+or event. `validateGraph` also catches the case a graph author can state statically — a
+trigger targeting an action whose `allowedSources` excludes `'system'` could never succeed —
+with `TRIGGER_TARGET_SOURCE_MISMATCH`.
+
 ## Server IR
 
 ```ts
@@ -311,14 +360,23 @@ Transport-independent by construction. One endpoint, semantic requests:
 ```ts
 { kind: 'snapshot', protocol: 'axiom.protocol.v1', credential?, sinceRevision? }
 { kind: 'invoke',   protocol: 'axiom.protocol.v1', actionId, arguments?, credential?, requestId? }
+{ kind: 'event',    protocol: 'axiom.protocol.v1', eventId, payload, credential? }
 ```
 
 ```ts
-{ kind: 'result',   ok, diagnostics, changes, revision, requestId?, replayed? }
-{ kind: 'snapshot', snapshot: { revision, states, partial? } }
-{ kind: 'error',    diagnostics }
+{ kind: 'result',       ok, diagnostics, changes, revision, requestId?, replayed? }
+{ kind: 'snapshot',     snapshot: { revision, states, partial? } }
+{ kind: 'error',        diagnostics }
+{ kind: 'event-result', ok, diagnostics }
 ```
 
+`event` (spec 0.8) is an **additive** request kind under the same `axiom.protocol.v1`
+identifier, not a new protocol version: unlike a Server IR document, a protocol message
+carries no document-wide vocabulary ceiling a receiver could silently misinterpret. A
+pre-0.8 server's `isServerRequest` check already rejects an unrecognized `kind` as
+malformed rather than misreading it as something else, so an older implementation degrades
+safely without needing to know the new kind exists.
+
 ### `sinceRevision`
 
 A snapshot request may name a revision the caller already holds. The answer is then
@@ -412,6 +470,14 @@ does for a local failure.
 | `CONCURRENCY_CONFLICT` | Another transaction committed the same state first. Nothing was applied. |
 | `MALFORMED_REQUEST` | The request was not an Axiom semantic request, or spoke an unknown protocol. |
 | `AUTHORITY_UNREACHABLE` | The authority could not be reached, timed out, or answered with a transport error. |
+| `EFFECT_FAILED` | An external effect's adapter reported failure after exhausting its retry policy. |
+| `TRIGGER_INVOCATION_FAILED` | A trigger's target action reported failure, or its arguments failed to evaluate. |
+| `EVENT_PAYLOAD_INVALID` | An external event's payload did not conform to its declared `EventDef.payloadType`. |
+| `TRIGGER_OVERLAP_SKIPPED` | An interval trigger's tick fired while its previous invocation was still running, and the default `'skip'` overlap policy discarded it. |
+| `INTEGRATION_ADAPTER_MISSING` | The Server IR requires an integration with no registered adapter — refused at `start()`, never deferred to first invocation. |
+| `EVENT_DISPATCH_DEPTH_EXCEEDED` | An event → action → effect → event chain was stopped before it could recurse unboundedly. |
+| `WEBHOOK_VERIFICATION_FAILED` | A webhook delivery failed provider signature verification and was refused before an event was ever constructed. |
+| `INVOCATION_SOURCE_NOT_ALLOWED` | The action's `invocation.allowedSources` does not include this invocation's source (spec 8.1 §3-9) — refused before `authorization` is even evaluated, because no caller reaching the authority this way may invoke the action at all. |
 
 Two client-side codes belong to the boundary as well:
 
@@ -505,6 +571,8 @@ of them and no others. No fixture is permitted to disagree with the shipped runt
 
 ```
 @cynodia/axiom-server/schema/server-ir.v1.schema.json
+@cynodia/axiom-server/schema/server-ir.v2.schema.json
+@cynodia/axiom-server/schema/server-ir.v3.schema.json
 @cynodia/axiom-server/schema/protocol.v1.schema.json
 ```
 
@@ -523,15 +591,16 @@ page plus the conformance fixtures.
 | --- | --- | --- |
 | `axiom.server.v1` | the frozen 0.6.1 contract, below | 0.6.1 |
 | `axiom.server.v2` | the expression kinds `group` and `expression-ref`, and the `expressionDefs` they resolve against | 0.7.0 |
+| `axiom.server.v3` | integrations, integration operations, events, triggers, and the `integration-query`/`integration-effect` operation kinds | 0.8.0 |
 
-`SERVER_IR_CONTRACTS` enumerates both. The rules:
+`SERVER_IR_CONTRACTS` enumerates all three. The rules:
 
-- **A document declares the oldest contract that can carry it.** `compileToServerIR` computes the label from the vocabulary the document actually uses, so an application that uses nothing from 0.7 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged.
+- **A document declares the oldest contract that can carry it.** `compileToServerIR` computes the label from the vocabulary the document actually uses, so an application that uses nothing from 0.7 or 0.8 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged.
 - **A runtime MUST refuse a contract it does not implement**, and MUST refuse a document whose vocabulary exceeds its declared contract. A v2 runtime executing a v1-labelled document that uses `group` would accept what a conforming v1 runtime elsewhere refuses, and the two would then disagree about the same file. `createAxiomServer` raises rather than executing one.
-- **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref` or `expressionDefs`, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
+- **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref`, `expressionDefs`, an integration, a trigger, an event, or the `integration-query`/`integration-effect` operation kinds, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
 
 There is one JSON Schema per contract, each generated from the runtime's own vocabulary and
-each shipped: `server-ir.v1.schema.json`, `server-ir.v2.schema.json`.
+each shipped: `server-ir.v1.schema.json`, `server-ir.v2.schema.json`, `server-ir.v3.schema.json`.
 
 **`group`.** Partitions a collection: `Collection<A>` → `Collection<Group<K, A>>`. Groups appear
 in the order their key was **first seen** in the source; members keep source order; two keys are
@@ -598,16 +667,111 @@ result is identical to some serial order. Across processes, correctness rests on
 persistence adapter's revision check — the contract guarantees that a commit from a stale
 snapshot is refused, not that two processes coordinate.
 
-## Not in 0.7.0
+## External systems
+
+0.8 adds a typed boundary to systems Axiom does not own: an `IntegrationDef` names a
+capability domain (a shipping provider, a device fleet), and an `IntegrationOperationDef`
+names one typed operation of it, with a declared `mode: 'query' | 'effect'`. The graph
+never mentions an SDK, a host name, an HTTP client or a secret — those are supplied by an
+`IntegrationAdapter`, registered with the authority (`AxiomServerOptions.integrations`),
+keyed by integration id. **Integrations default server-only** (secrets, trust, CORS,
+auditability, deterministic authority): an operation is client-invokable only if it
+declares `clientSafe: true`, and client safety is never inferred from the absence of a
+declared secret.
+
+**A missing adapter fails `start()`, not the first invocation.** Every integration a
+document requires is checked against the registry before any request is accepted
+(`INTEGRATION_ADAPTER_MISSING`).
+
+**A query is explicit execution, never a pure `Expression`.** An `integration-query`
+operation calls its adapter and binds the (type-checked) result into scope as
+`ref(bindAs)`, resolved **before the transaction opens** — ahead of guards, so a query
+never runs mid-transaction and a guard can never reference its result. A malformed
+provider response is rejected at this boundary (`INTEGRATION_RESULT_INVALID`) rather than
+handed to the application as `unknown`. Full model: `docs/INTEGRATIONS.md`.
+
+## External effects
+
+**An external effect is not a rollback-capable state mutation**, and 0.8 does not pretend
+otherwise (spec §15,16). Axiom can roll back a state write; it cannot roll back an email,
+a payment or a shipment request.
+
+Reaching an `integration-effect` operation only **records intent** — appended to the same
+per-transaction log a mutation is, and discarded on rollback the same way. The adapter is
+never called during the transaction. Only once the transaction **commits** — effect intent
+persisted atomically with the state write that requested it, the transactional outbox
+invariant — does an `EffectRunner` dispatch it, and the response the caller receives never
+waits for that: "action committed, effect pending," not "action committed and its effect
+succeeded." A `PersistenceAdapter` that implements `loadPendingEffects`/
+`recordEffectAttempt` (both shipped adapters do) resumes any intent that was committed but
+never reached a terminal status, so a crash between commit and dispatch does not lose it —
+**at-least-once delivery**, not exactly-once. Effect operations may declare `idempotent:
+true` and a `retry` policy (`'none' | 'fixed' | 'exponential'`); an idempotency key,
+computed from `idempotencyKey`, is handed to the adapter on every attempt so a provider can
+deduplicate a retried call.
+
+An effect's outcome is never folded back into the transaction that requested it. Instead,
+its declared `succeededEventId`/`failedEventId` — an ordinary `EventDef` — is dispatched
+through the same event pipeline an external webhook uses, once the outcome is known. There
+is no automatic compensation: a semantic inverse (`refundPayment`) is another explicit
+action, never an implicit `rollback(createPayment)`. Full model: `docs/EFFECTS.md`.
+
+## Triggers
+
+A `TriggerDef` says **when** an action should be invoked — `interval`, `delay`,
+`lifecycle` (`application-start`, `runtime-ready` on the server; `route-enter`,
+`route-leave` on the client) or `event` — without embedding callback code. **A triggered
+action runs through exactly the same semantics any other caller does**: the same guards,
+constraints, transition constraints and authorization. There is no weaker, trigger-specific
+execution path.
+
+Timed and event triggers whose target action is server-authority run **on the authority**,
+continuing whether or not a browser is connected; `application-start`/`runtime-ready`
+triggers run once, in startup order, before requests are accepted (see
+[Startup](#startup)). An interval trigger's default overlap policy is `'skip'`: a tick that
+fires while the previous invocation is still running is discarded, not queued and never run
+concurrently (`TRIGGER_OVERLAP_SKIPPED`); `'queue'` runs one pending tick immediately after.
+
+**Timed and event-originated invocations run under a system context, never an impersonated
+user.** `ExecutionContext.principal` is `null` — exactly what an anonymous client request's
+is — and `.source` is `'system'`, carried only for observability. Authorization still
+evaluates against that; it is never bypassed. An action whose authorization rule can never
+be satisfied by a `null` principal is correctly refused when a trigger invokes it — the
+graph decides, by declaring authorization or not on the actions it targets. Full model:
+`docs/TRIGGERS.md`.
+
+## External events
+
+An `EventDef` is a typed fact — a webhook delivery, an effect's outcome — never work
+itself; a `TriggerDef{when:{kind:'event'}}` is what says what happens next. The semantic
+protocol's `EventRequest` (`kind: 'event'`) carries only `eventId` and `payload`; the
+payload is validated against `EventDef.payloadType` **before any action sees it**
+(`EVENT_PAYLOAD_INVALID` otherwise) — malformed input never reaches trusted code.
+
+**Provider authenticity is verified before an event is even constructed.** A webhook route
+is registered on the Node host (`serveOverHttp({ webhooks })`), never declared by the
+application: `verify` runs over the raw request first, and an unverified delivery never
+reaches `decode` or the semantic layer. A provider `deliveryId`, when supplied, is
+deduplicated against a bounded recent-deliveries window per route — a duplicate within that
+window is acknowledged without dispatching the event again, with no claim of durable,
+unbounded deduplication.
+
+**Event dispatch is depth-guarded**, so a cycle (an event whose triggered effect's own
+success re-fires it) is stopped rather than recursing unboundedly
+(`EVENT_DISPATCH_DEPTH_EXCEEDED`, `MAX_EVENT_DISPATCH_DEPTH` dispatches deep). Full model:
+`docs/EVENTS.md`.
+
+## Not in 0.8.0
 
 Stated plainly rather than left to discovery:
 
-- **Generated values cannot be bound within an action.** An operation cannot name a value an earlier operation produced: `uuid()` evaluated in one `insert` cannot be referred to by a later `insert` in the same action. Give the record an identity the action already has — a parameter, or a field of something it read — or perform the second write in a second action. A semantic binding for this (`bindAs` on an operation, `ref` to it later) needs a lexical lifetime, a type, `for-each` and nested-invoke semantics, serialization and dependency analysis all decided together; doing that hastily would weaken a contract that is now frozen, so it is deferred to 0.7.
+- **Generated values cannot be bound within an action, in general.** An operation cannot name a value an earlier operation produced: `uuid()` evaluated in one `insert` cannot be referred to by a later `insert` in the same action. Give the record an identity the action already has — a parameter, or a field of something it read — or perform the second write in a second action. 0.8 adds exactly one narrow, purpose-built exception: an `integration-query`'s `bindAs` result, resolved before the transaction opens (see [External systems](#external-systems)) — not a general operation-result binding mechanism.
 - **Read authorization per caller or per record.** Visibility is per state.
-
-- **External effects.** A database write rolls back; an email does not. Nothing here makes an external side effect participate in a transaction, and `NativeOperation` MUST NOT be used to smuggle one in. A deliberate effect model — commands, a transactional outbox, idempotency — is future work.
+- **Absolute/cron schedules.** `interval` and `delay` triggers cover "every N milliseconds" and "once after N milliseconds"; a calendar schedule ("every day at 09:00") is not modeled.
+- **Client-side execution of interval, delay and lifecycle triggers.** The browser runtime implements no trigger kind at all. Before spec 8.1 a client-authority trigger silently compiled into `ApplicationIR.triggers` and simply never fired; now `validateGraph`/`compileToIR` reject it with `CLIENT_TRIGGER_UNSUPPORTED` instead, so the gap is a compile-time error rather than a runtime discovery. Only the authoritative runtime executes triggers today.
+- **Durable effect delivery beyond the two shipped `PersistenceAdapter`s.** At-least-once delivery across a restart is real for `createMemoryPersistence` (within the process) and `createSqlitePersistence`; a third adapter earns the same claim only by implementing `loadPendingEffects`/`recordEffectAttempt` itself.
 - **Realtime synchronization**, subscriptions and collaboration. Request/response only.
 - **Query semantics.** Authoritative collections are loaded into runtime state; large-data querying needs its own design.
 - **Relational schema generation**, migrations and ORM behaviour.
 - **Multi-node distributed execution.** Correctness is guaranteed within one authority process.
-- **File storage, background jobs, scheduling.**
+- **File storage, background worker fleets, a general job queue, a saga engine, a workflow language.** Effects and triggers are deliberately not a distributed job system (spec §2).

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.7.0-alpha.2. Two constructs, answering different questions. They are not
+Axiom 0.8.1-alpha.1. Two constructs, answering different questions. They are not
 interchangeable.
 
 | | Question | Sees |