@cynodia/axiom 0.8.2-alpha.1 → 0.9.0-alpha.1

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.8.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.9.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {
@@ -210,6 +210,40 @@ like a mutation is. The adapter runs only after the transaction commits, and the
 this action's caller gets back never waits for it — "committed, effect pending." Never legal
 inside `for-each`. Full model: [`EFFECTS.md`](EFFECTS.md).
 
+### `blob-metadata`
+
+```ts
+{ kind: 'blob-metadata', storageId: NodeId, blobKey: Expression, bindAs: NodeId }
+```
+
+Reads a stored object's metadata from a `StorageDef` and binds the `BlobRef` into scope —
+query-like in exactly the sense `integration-query` is, and resolved in the same
+pre-transaction phase. It returns the reference, never the bytes. A key that names nothing,
+or names a still-staged upload, **fails the invocation** rather than binding a plausible
+empty record. Never legal inside `for-each`. Full model: [`STORAGE.md`](STORAGE.md).
+
+### `blob-commit`
+
+```ts
+{ kind: 'blob-commit', storageId: NodeId, blobKey: Expression, succeededEventId?: NodeId, failedEventId?: NodeId }
+```
+
+Promotes a staged upload to a stored object. Effect-like, and for the same reason every
+effect is: an object store cannot join an Axiom transaction. Reaching it records intent,
+committed atomically with the state that references the object and dispatched only once that
+state is durable. A rolled-back transaction dispatches nothing and leaves the upload staged.
+Never legal inside `for-each`.
+
+### `blob-delete`
+
+```ts
+{ kind: 'blob-delete', storageId: NodeId, blobKey: Expression, succeededEventId?: NodeId, failedEventId?: NodeId }
+```
+
+Removes a stored object, post-commit. The state that stopped referencing it commits first; if
+the external deletion then fails, state is still correct and the orphan is visible in
+`server.blobLog()`. Never legal inside `for-each`.
+
 ## Authorization
 
 ```ts

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.8.2-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.9.0-alpha.1. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts
@@ -160,6 +160,33 @@ agent.getPersistenceForState(stateId)
 Authority is derived from what an action writes, so these answers cannot disagree with what
 the graph does. See [`AUTHORITY.md`](AUTHORITY.md).
 
+## External-world queries
+
+```ts
+agent.listIntegrations() / agent.listIntegrationOperations(integrationId?)
+agent.getActionsUsingIntegration(integrationId) / agent.getEffectsForAction(actionId)
+agent.getTriggersForAction(actionId) / agent.getTimedTriggers()
+agent.getActionsTriggeredByEvent(eventId) / agent.getTriggeredEvents()
+agent.getExternalDependencies()              // { integrations, operations }
+
+agent.listSubscriptions()
+agent.getSubscriptionsForIntegration(integrationId)
+agent.getEventForSubscription(subscriptionId)
+agent.getActionsReachableFromSubscription(subscriptionId)
+agent.getExternalEventSources()              // { subscriptions, events, integrations }
+
+agent.listStorages()
+agent.getActionsUsingStorage(storageId)
+agent.getStoragesWithoutAccessRules()        // stores that serve and accept nothing
+```
+
+All of these are **graph-static**: they answer what the application *can* reach, not what a
+running authority has done. `getActionsReachableFromSubscription` is the one to reach for
+before changing a live feed — it follows the subscription's event through every bound
+trigger, so "what can this feed actually change" needs no traversal by the consumer. Runtime
+answers come from `AxiomServer.subscriptionLog()` and `blobLog()` instead; see
+[`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md) and [`STORAGE.md`](STORAGE.md).
+
 ## Transactions
 
 Every change is staged on a private copy. The graph an agent or a runtime can observe is

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.8.2-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.9.0-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:
@@ -668,7 +668,8 @@ Portable artifacts, for a runtime written in another language:
 @cynodia/axiom-server/schema/server-ir.v1.schema.json JSON Schema for axiom.server.v1 (frozen)
 @cynodia/axiom-server/schema/server-ir.v2.schema.json JSON Schema for axiom.server.v2
 @cynodia/axiom-server/schema/server-ir.v3.schema.json JSON Schema for axiom.server.v3
-@cynodia/axiom-server/schema/server-ir.v4.schema.json JSON Schema for axiom.server.v4 (latest)
+@cynodia/axiom-server/schema/server-ir.v4.schema.json JSON Schema for axiom.server.v4
+@cynodia/axiom-server/schema/server-ir.v5.schema.json JSON Schema for axiom.server.v5 (latest)
 @cynodia/axiom-server/schema/protocol.v1.schema.json  JSON Schema for the protocol
 ```
 
@@ -686,6 +687,82 @@ Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZ
 `AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE` and `REMOTE_ACTION_UNAVAILABLE` on the
 client.
 
+## SUBSCRIPTIONS AND STORAGE
+
+Full model: [`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md), [`STORAGE.md`](STORAGE.md). The external
+world reaching *in*, and binary data, which 0.8 had no vocabulary for.
+
+The external-interaction model is exactly three directions. Anything else is one of them
+wearing a different name.
+
+| Direction | Shape | Vocabulary |
+| --- | --- | --- |
+| Query | Ask; wait for a finite answer. | `integration-query`, `blob-metadata` |
+| Effect | Tell; no answer joins the transaction. | `integration-effect`, `blob-commit`, `blob-delete` |
+| Subscription | The world tells you, while you are listening. | `SubscriptionDef` → `EventDef` |
+
+1. **SUBSCRIPTION INVARIANT** — a long-lived external source is a `SubscriptionDef`, never a client, a socket or a callback in the graph. A delivery becomes an `EventDef` payload and enters the existing `EventDef → TriggerDef → ActionDef` pipeline; there is no second event system.
+2. **RAW-I/O INVARIANT** — OS I/O primitives are not graph vocabulary. No `readFile(path)`, `openSocket(host, port)`, `exec(command)`, `spawn(process)`, file descriptor, Node stream or POSIX path exists or will. They live inside an adapter, which is exactly what lets a Rust runtime implement the same graph with different primitives.
+3. **DELIVERY INVARIANT** — at-least-once; effectively-once where `delivery.deduplicateBy` names an external identity, and that deduplication survives a restart when the persistence adapter is durable. Per-subscription ordering is guaranteed; cross-subscription ordering is guaranteed to be **nothing**.
+4. **BACKPRESSURE INVARIANT** — the queue is always bounded (`maxQueued`, default 64) and the default policy (`block`) cannot lose an event. A policy that may discard one (`drop-oldest`/`drop-newest`) is declared in the graph and reports `SUBSCRIPTION_DELIVERY_DROPPED` every time. Loss is never silent and never a default.
+5. **SHUTDOWN INVARIANT** — after `server.stop()`, no delivery reaches application state. A stopped subscription answers `stopped` to everything, including deliveries already in flight.
+6. **BLOB INVARIANT** — bytes never enter the graph, the Server IR or canonical state. A `BlobRef` (`blobRefEntity()` — key, media type, size, filename?, checksum?) is what state holds, and it discloses nothing about the provider.
+7. **BLOB AUTHORIZATION INVARIANT** — possession of a key is not permission. `StorageDef.readAuthorization` is evaluated with the caller bound to `PRINCIPAL` and the `BlobRef` bound to `ref(<storageId>)`; a store with no rule serves nothing. A key that names nothing is refused identically to one the caller may not read.
+8. **STAGED-COMMIT INVARIANT** — an object store does not join an Axiom transaction, and nothing pretends it does. An upload lands `staged`; `blob-commit` promotes it post-commit. A refused transaction leaves a sweepable staged object, never a state referencing bytes that were never claimed. A failed `blob-delete` leaves state correct and the orphan visible in `blobLog()`.
+
+```ts
+{ kind: 'subscription', id: SUB_STATUS, integrationId: INTEGRATION, source: 'device-status',
+  eventId: EVENT_STATUS_CHANGED,
+  lifecycle: { autoStart: true, required: false, reconnect: { policy: 'exponential', maxAttempts: 5, delayMs: 1000 } },
+  delivery: { maxQueued: 32, backpressure: 'block', deduplicateBy: F_DELIVERY_ID, maxAttempts: 1, onFailure: 'report' } }
+
+{ kind: 'storage', id: STORAGE_LOGS, blobEntityId: ENTITY_BLOB,
+  readAuthorization: <Expression>, uploadAuthorization: <Expression>,
+  acceptedMediaTypes: ['text/plain'], maxSizeBytes: 8388608 }
+
+{ kind: 'blob-metadata', storageId: STORAGE_LOGS, blobKey: <Expression>, bindAs: SCOPE_BLOB }
+{ kind: 'blob-commit',   storageId: STORAGE_LOGS, blobKey: <Expression> }
+{ kind: 'blob-delete',   storageId: STORAGE_LOGS, blobKey: <Expression> }
+```
+
+Lifecycle: `inactive → starting → active → reconnecting → failed`, plus `stopped`. Startup
+decides what activates; application code never calls `start()`. A failed source leaves the
+application running unless `lifecycle.required`.
+
+Subscription vs. webhook vs. polling — three different things, do not conflate them:
+
+| | What it is | Vocabulary |
+| --- | --- | --- |
+| Webhook | Externally initiated finite request; each delivery enters independently. | host `webhooks` → `EventRequest` |
+| Subscription | Standing semantic interest in a long-lived source. | `SubscriptionDef` |
+| Polling | You ask, repeatedly, on a schedule. | `interval` `TriggerDef` → `integration-query` |
+
+Upload is `POST /axiom/blob/<storageId>` and download is `GET /axiom/blob/<storageId>/<key>`
+— one host transport for every Axiom application. Application-authored upload/download
+routes: zero.
+
+```ts
+agent.listSubscriptions() / agent.getSubscriptionsForIntegration(id);
+agent.getEventForSubscription(id) / agent.getActionsReachableFromSubscription(id);
+agent.getExternalEventSources();   // { subscriptions, events, integrations }
+agent.listStorages() / agent.getActionsUsingStorage(id) / agent.getStoragesWithoutAccessRules();
+
+server.subscriptionLog() / server.subscriptionStatus(id);   // state, counters, last delivery, last failure
+server.blobLog();                                           // storage effects and their outcomes
+server.stageBlob(storageId, principal, upload);
+server.authorizeBlobRead(storageId, key, principal);
+server.authorizeBlobUpload(storageId, principal, { mediaType, size });
+```
+
+Adapters: `SubscriptionAdapter` (`createScriptedSubscriptionAdapter` is the deterministic
+fake) and `BlobStorageAdapter` (`createMemoryBlobStore`). A declared subscription or store
+with no registered adapter fails `start()` rather than staying silently inert.
+
+Diagnostics: `SUBSCRIPTION_ADAPTER_MISSING` `SUBSCRIPTION_START_FAILED`
+`SUBSCRIPTION_DELIVERY_DROPPED` `SUBSCRIPTION_DELIVERY_FAILED` `BLOB_STORE_MISSING`
+`BLOB_NOT_FOUND` `BLOB_ACCESS_DENIED` `BLOB_TOO_LARGE` `BLOB_MEDIA_TYPE_REJECTED`
+`BLOB_OPERATION_FAILED` `BLOB_STORAGE_UNAVAILABLE` `BLOB_METADATA_FAILED`.
+
 ## Metadata classes
 
 ```ts

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.8.2-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.9.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -405,3 +405,97 @@ a side effect nothing can roll back. See [`INTEGRATIONS.md`](INTEGRATIONS.md) an
 
 // RIGHT — declare `required: true` on the FieldDef and let the renderer mark it.
 ```
+
+## 32. OS I/O primitives are not graph vocabulary
+
+```ts
+// WRONG — every one of these. None exists, and none will.
+readFile(path); writeFile(path); openSocket(host, port); exec(command); spawn(process);
+openSerialPort(device);
+{ kind: 'native', implementationId: 'app.readAttachment', inputs: { path: literal('/var/uploads/x') } }
+```
+
+An `ApplicationGraph` exposes no filesystem path, no socket, no stream, no file descriptor
+and no subprocess. That is not squeamishness about I/O — the Node host uses all of them
+freely. It is that a graph naming one stops being:
+
+| | Why |
+| --- | --- |
+| **portable** | A Rust runtime, or a browser, has different primitives — or none. |
+| **analyzable for authority** | "What can this action reach?" has no answer once `exec` is in the vocabulary. |
+| **secure** | A path is a capability the graph hands out; a key checked against a declared rule is not. |
+| **deterministically testable** | A conformance fixture cannot script a real socket. |
+| **introspectable** | `getExternalDependencies()` can enumerate typed operations. It cannot enumerate what a shell command does. |
+
+Low-level I/O is permitted, and expected, **inside an adapter**:
+
+```
+PrinterIntegration.print()   → adapter implementation → TCP
+VideoIntegration.transcode() → adapter implementation → ffmpeg subprocess
+DeviceStream subscription    → adapter implementation → serial port, MQTT, WebSocket
+DiagnosticLogs storage       → adapter implementation → local directory, or S3
+```
+
+The graph says *what the interaction means*; the adapter decides *how*. Replace Node with
+Rust, MQTT with a WebSocket, or a local directory with S3, and the graph does not change —
+which is the test that the abstraction is at the right level.
+
+Use [`INTEGRATIONS.md`](INTEGRATIONS.md), [`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md) or
+[`STORAGE.md`](STORAGE.md) instead.
+
+## 33. `setInterval` + `fetch` for polling, or a client in application code
+
+```ts
+// WRONG — all four, in application code.
+setInterval(() => fetch('/api/devices').then(apply), 5000);
+const socket = new WebSocket('wss://…');
+const client = mqtt.connect('mqtt://…');
+socket.onmessage = (event) => applyStatus(JSON.parse(event.data));
+```
+
+Each of these puts scheduling, transport and a callback-driven mutation path into the
+application, where nothing can analyze, test or authorize them.
+
+| Instead of | Declare |
+| --- | --- |
+| `setInterval` + `fetch` | `TriggerDef{when:{kind:'interval'}}` → `integration-query` |
+| `new WebSocket` / an MQTT client | `SubscriptionDef` → `EventDef` → `TriggerDef` |
+| `socket.onmessage = handler` | The trigger's target action. Deliveries never invoke a callback. |
+| A hand-rolled webhook route | The host's `webhooks` option → `EventRequest` |
+
+## 34. A client-authored subscription event
+
+```ts
+// WRONG — an action a subscription's trigger invokes, left open to clients.
+{ kind: 'action', id: ACTION_APPLY_STATUS, /* no `invocation` */ operations: [ … ] }
+```
+
+Any anonymous client that guesses the id can then assert whatever the live feed asserts.
+Declare `invocation: { allowedSources: ['system'] }`: a client-sourced call is refused with
+`INVOCATION_SOURCE_NOT_ALLOWED` before identity is even consulted.
+
+## 35. base64 bytes in canonical state
+
+```ts
+// WRONG — the attachment's contents in the record, in the Server IR, in every snapshot.
+{ id: F_DOCUMENT_ATTACHMENT, valueType: primitiveType('string') }  // "data:application/pdf;base64,…"
+```
+
+Every read, every snapshot, every persisted write and every `changes` map then carries the
+whole object. Store a `BlobRef` (`blobRefEntity()`) and let the bytes move through the
+host's own upload and download transport — see [`STORAGE.md`](STORAGE.md). A 5MB attachment
+leaves the record exactly as large as a 5-byte one.
+
+## 36. An application-authored upload or download route
+
+```ts
+// WRONG — a route the graph does not know about, guarding data the graph does own.
+express.post('/upload', (request, response) => { /* … */ });
+express.get('/files/:key', (request, response) => response.sendFile(`/var/uploads/${request.params.key}`));
+```
+
+The second is also a path traversal waiting to happen, and neither can be reached by
+`validateGraph`, by `AgentAPI`, or by a conformance fixture. `POST /axiom/blob/<storageId>`
+and `GET /axiom/blob/<storageId>/<key>` already exist, for every Axiom application, with
+`StorageDef.uploadAuthorization` and `StorageDef.readAuthorization` enforced by the
+authority. Application-authored upload/download routes: zero.

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.8.2-alpha.1. How an application crosses the trust boundary.
+Axiom 0.9.0-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
@@ -477,6 +477,16 @@ does for a local failure.
 | `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. |
+| `SUBSCRIPTION_ADAPTER_MISSING` | The Server IR declares a subscription whose integration has no registered `SubscriptionAdapter`. Startup refuses, rather than leaving a declared live source permanently inactive. |
+| `SUBSCRIPTION_START_FAILED` | A subscription's source could not be established, after every attempt its declared reconnect policy allows. |
+| `SUBSCRIPTION_DELIVERY_DROPPED` | A delivery was discarded by a declared lossy backpressure policy. Loss is always declared and never silent. |
+| `SUBSCRIPTION_DELIVERY_FAILED` | A delivery's triggered action failed after every permitted attempt. |
+| `BLOB_STORE_MISSING` | The Server IR declares a `StorageDef` with no registered `BlobStorageAdapter`. |
+| `BLOB_NOT_FOUND` | No object with that key, or the key names a still-staged upload. |
+| `BLOB_ACCESS_DENIED` | The caller may not read, download or upload this object. Also the answer for a key that names nothing at all, so the endpoint is not an oracle for enumerating keys. |
+| `BLOB_TOO_LARGE` | An upload exceeded the store's declared `maxSizeBytes`. |
+| `BLOB_MEDIA_TYPE_REJECTED` | An upload's media type is not in the store's declared `acceptedMediaTypes`. |
+| `BLOB_OPERATION_FAILED` | A `blob-commit` or `blob-delete` failed at the store, after its retry policy. |
 | `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:
@@ -626,8 +636,9 @@ page plus the conformance fixtures.
 | `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 |
 | `axiom.server.v4` | `ActionDef.invocation.allowedSources` invocation-source restriction, and the structured effect-outcome envelope (`effectOutcomeEntity`, `EFFECT_ID_FIELD` and its sibling reserved fields) that every effect dispatch uses from 8.1 onward | 0.8.1 |
+| `axiom.server.v5` | `SubscriptionDef` and `StorageDef`, and the `blob-metadata`/`blob-commit`/`blob-delete` operation kinds — the inbound external-I/O direction and binary object storage | 0.9.0 |
 
-`SERVER_IR_CONTRACTS` enumerates all four, and is the single source of truth this table is
+`SERVER_IR_CONTRACTS` enumerates all five, and is the single source of truth this table is
 tested against — `packages/demo/test/documentation.test.ts` fails if a contract in
 `SERVER_IR_CONTRACTS` has no row here, or a row here names a contract the code does not
 declare (spec 8.2 §7-8). The rules:
@@ -635,11 +646,20 @@ declare (spec 8.2 §7-8). 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 or 0.8 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged. `usesV4Semantics` computes the v4 case specifically: an action's `invocation.allowedSources` genuinely restricting the default two-source set, or any `integration-operation` with `mode: 'effect'` (since every effect dispatch uses the structured v4 envelope) — a document that merely mentions `invocation` without restricting it only needs `axiom.server.v2`, the same tier `group`/`expression-ref` occupy.
 - **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 — including refusing a document that **understates** its own contract (`understatedContract`).
 - **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref`, `expressionDefs`, an integration, a trigger, an event, the `integration-query`/`integration-effect` operation kinds, `invocation`, or the structured effect-outcome envelope, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
-- **`axiom.server.v4` is the latest contract as of 0.8.2** (`SERVER_IR_LATEST_CONTRACT`). 0.8.2 is polish-only — documentation, effect observability timing, fixture coverage and AgentAPI aliasing — and introduces no incompatible IR vocabulary change, so no `axiom.server.v5` was created (spec 8.2 §55-56).
+- **`axiom.server.v5` is the latest contract as of 0.9.0** (`SERVER_IR_LATEST_CONTRACT`). `usesExternalIOVocabulary` computes it from the document: any `subscriptions`, any `storages`, or any of the three blob operation kinds. The reason it is an incompatible change rather than an additive one is exact — a v4 runtime that ignored `subscriptions` would start an application whose declared live event source never activates, and one that ignored a `blob-commit` would leave state referencing an object that stays staged forever. Both are silent divergence, which is what a contract label exists to prevent.
 
 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`, `server-ir.v3.schema.json`,
-`server-ir.v4.schema.json`.
+`server-ir.v4.schema.json`, `server-ir.v5.schema.json`.
+
+**`SubscriptionDef`, `StorageDef` and the blob operations.** Their normative semantics —
+lifecycle states and transitions, at-least-once delivery, per-subscription ordering and the
+explicit absence of cross-subscription ordering, bounded queues and every backpressure policy,
+deduplication and its restart durability, poison-delivery bounds, staged-then-committed object
+lifecycle, and the authorization rule a store evaluates before serving a byte — are documented
+in [`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md) and [`STORAGE.md`](STORAGE.md), and are executable in
+the `subscription-*` and `blob-*` conformance fixtures. An independent implementer needs those
+two documents, the v5 schema and those fixtures, and no TypeScript.
 
 **`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

package/docs/CONSTRAINTS.md

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

package/docs/EFFECTS.md

@@ -1,10 +1,13 @@
 # Effects
 
-Axiom 0.8.2-alpha.1. External effects are not rollback-capable state mutations. This file
+Axiom 0.9.0-alpha.1. External effects are not rollback-capable state mutations. This file
 is the delivery model; [`AUTHORITY.md`](AUTHORITY.md#external-effects) is the load-bearing
 statement of why, and [`INTEGRATIONS.md`](INTEGRATIONS.md) is the operation vocabulary this
 builds on.
 
+Storage effects — `blob-commit` and `blob-delete` — ride this same outbox rather than a
+second durability system; see [`STORAGE.md`](STORAGE.md).
+
 ## The operation
 
 ```ts

package/docs/EVENTS.md

@@ -1,8 +1,11 @@
 # Events
 
-Axiom 0.8.2-alpha.1. An event is a typed fact — something that happened — never work
+Axiom 0.9.0-alpha.1. An event is a typed fact — something that happened — never work
 itself. [`AUTHORITY.md`](AUTHORITY.md#external-events) is the load-bearing statement;
-this file is the vocabulary and the webhook delivery mechanism.
+this file is the vocabulary and the webhook delivery mechanism. A **subscription** is the
+other way an external fact becomes an `EventDef` payload — see
+[`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md), which also states the distinction between a webhook,
+a subscription and polling.
 
 ## The model
 

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.8.2-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.9.0-alpha.1. An expression describes **what value is computed**. It is a tree of
 plain data, never source text and never a callback. Evaluation is pure: an expression MUST
 NOT change state.
 

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.8.2-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.9.0-alpha.1. The `ApplicationGraph` is the authoritative representation of an
 application. Everything else — the IR, the page, the DOM — is derived from it and is never
 edited.
 

package/docs/INTEGRATIONS.md

@@ -1,9 +1,13 @@
 # Integrations
 
-Axiom 0.8.2-alpha.1. How an application declares and calls an external system, without
+Axiom 0.9.0-alpha.1. How an application declares and calls an external system, without
 embedding a transport, an SDK or a secret in the graph. The authority boundary this
 depends on is [`AUTHORITY.md`](AUTHORITY.md#external-systems); this file is the vocabulary.
 
+This covers the two **outbound** directions — query and effect. The inbound one, a
+long-lived source that delivers to you, is [`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md); binary
+object storage is [`STORAGE.md`](STORAGE.md).
+
 ## The model
 
 ```ts

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.8.2-alpha.1.
+Axiom 0.9.0-alpha.1.
 
 ```text
 Expression = a value

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.8.2-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.9.0-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
 node. It names roles, tokens and device classes. It never names a colour, a length, a media
 query or a CSS property.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.8.2-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.9.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing
@@ -226,6 +226,8 @@ interface RuntimeDiagnostic {
 | `INTEGRATION_TIMEOUT` | An integration query did not answer within its declared `timeoutMs`. | `integration-query` | `operationId` |
 | `INTEGRATION_RESULT_INVALID` | A provider's response did not conform to the operation's declared `resultType`. | `integration-query` | `operationId` |
 | `INTEGRATION_QUERY_FAILED` | An integration query failed for any other reason. Never carries a provider secret. | `integration-query` | `operationId`, `retryable` |
+| `BLOB_STORAGE_UNAVAILABLE` | No host capable of reaching an object store is configured. Only the authoritative runtime ever reaches one. | `blob-metadata` | `storageId` |
+| `BLOB_METADATA_FAILED` | A `blob-metadata` lookup failed: no such key, a still-staged object, or the store refused. The store's own code is in `details.code` rather than replacing the diagnostic code — a provider's vocabulary is not Axiom's. | `blob-metadata` | `storageId`, `code` |
 | `UI_NODE_MISSING` | A child id that is not a UI node in the IR. | render | — |
 | `UNSUPPORTED_UI_NODE` | An unknown UI node kind. | render | — |
 | `PERSISTED_STATE_UNREADABLE` | **Warning.** A stored value could not be parsed; the initial value was used. | startup | — |

package/docs/SEMANTIC_CONTRACT.md

@@ -1,6 +1,6 @@
 # Semantic contract
 
-Axiom 0.8.2-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.9.0-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
 does not teach. Where this file and any specification in `../specs/` disagree, this file
 describes the implementation and is authoritative.
 

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.8.2-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.9.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/STORAGE.md

@@ -0,0 +1,253 @@
+# Storage and blobs
+
+Axiom 0.9.0-alpha.1. How an application stores, references, serves and deletes binary data —
+an attachment, a document, a photograph, a diagnostic log — with no filesystem path, no
+upload route and no download route anywhere in it.
+
+[`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md) is the other half of 0.9; [`EFFECTS.md`](EFFECTS.md)
+is the outbox machinery this reuses rather than duplicating.
+
+## The abstraction
+
+A **stored object addressed by an opaque key**. Never a path, an inode or a descriptor.
+
+That is what lets the same graph run against a local directory in development, an S3-like
+store in production and an in-memory store in a test without a single edit — and it is why
+`readFile(path)` is not, and will not become, graph vocabulary. See
+[`ANTI_PATTERNS.md`](ANTI_PATTERNS.md#os-io-primitives-are-not-graph-vocabulary).
+
+**Bytes never enter the graph, the Server IR or canonical state.** What state holds is a
+`BlobRef`. Transfer of the bytes is out of band, through the host's own transport.
+
+## BlobRef
+
+```ts
+graph.addNode<EntityDef>(blobRefEntity(ENTITY_BLOB));
+```
+
+An ordinary entity, built once per graph, with reserved field ids:
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `BLOB_KEY_FIELD` | string | yes | The opaque key. The identity field. |
+| `BLOB_MEDIA_TYPE_FIELD` | string | yes | The object's media type. |
+| `BLOB_SIZE_FIELD` | number | yes | Bytes. |
+| `BLOB_FILENAME_FIELD` | string | no | The name it was uploaded under. |
+| `BLOB_CHECKSUM_FIELD` | string | no | A digest, when the store computes one. |
+
+Those five fields are the **whole** public contract. A `BlobRef` crossing to a client carries
+no bucket, container, region, account, path, provider name or lifecycle bookkeeping. Field ids
+are graph-global, so one graph declares one blob entity and every store and every attachment
+field references it.
+
+Store it wherever an attachment belongs:
+
+```ts
+// Document { id, title, attachment: BlobRef }
+{ id: F_DOCUMENT_ATTACHMENT, valueType: optionalType(entityType(ENTITY_BLOB)) }
+```
+
+A `BlobRef` is ordinary authoritative state: it persists, it survives a restart, it is
+observable, and its identity is stable enough to hold in a record.
+
+**Checksums are offered, never required.** Content addressing is a legitimate storage model
+and a poor universal one, so a store that computes a digest publishes it and one that does
+not omits it.
+
+## StorageDef
+
+```ts
+interface StorageDef {
+  id: NodeId;
+  kind: 'storage';
+  blobEntityId: NodeId;
+  readAuthorization?: Expression;
+  uploadAuthorization?: Expression;
+  acceptedMediaTypes?: string[];
+  maxSizeBytes?: number;
+  retry?: { policy: 'none' | 'fixed' | 'exponential'; maxAttempts?: number; delayMs?: number };
+}
+```
+
+`StorageDef` is to blobs what `IntegrationDef` is to operations: the semantic capability,
+never the provider. No bucket, endpoint, region, credential or directory appears here or
+anywhere else in a graph — a `BlobStorageAdapter` supplies all of it. A local filesystem
+adapter is perfectly legitimate; its paths are host configuration.
+
+## Authorization
+
+**Possession of a key is not permission.** `readAuthorization` is evaluated by the authority
+before a single byte is served, with the caller bound to `PRINCIPAL` and the requested
+`BlobRef` bound to `ref(<this storage's id>)`:
+
+```ts
+graph.addNode<StorageDef>({
+  id: STORAGE_DIAGNOSTICS,
+  kind: 'storage',
+  blobEntityId: ENTITY_BLOB,
+  // Readable only while some device actually references it.
+  readAuthorization: some(ref(STATE_DEVICES), SCOPE, binary('eq',
+    field(field(ref(SCOPE), F_DEVICE_LOG), BLOB_KEY_FIELD),
+    field(ref(STORAGE_DIAGNOSTICS), BLOB_KEY_FIELD))),
+  uploadAuthorization: binary('eq', field(ref(PRINCIPAL), F_ROLE), literal('operator')),
+});
+```
+
+MUST: a store with **no** rule serves nothing and accepts nothing. The safe default for a
+missing access rule is refusal, so an author who forgets one gets a closed door.
+
+A key that names nothing and a key the caller may not read are answered **identically**
+(`BLOB_ACCESS_DENIED`), deliberately: distinguishing them would turn the endpoint into an
+oracle a hostile client could enumerate keys with.
+
+Delete goes through an action, so an action's ordinary `authorization` governs it.
+
+## Operations
+
+| Operation | Shape | When it runs |
+| --- | --- | --- |
+| `blob-metadata` | query-like | Resolved **before** the transaction opens, binds the `BlobRef` into scope via `bindAs`. |
+| `blob-commit` | effect-like | Recorded as intent; dispatched **after** the transaction commits. |
+| `blob-delete` | effect-like | The same. |
+
+None is legal inside a `for-each`. All three make their action server-authority, exactly as an
+integration operation does.
+
+```ts
+{ kind: 'blob-metadata', storageId: STORAGE, blobKey: <Expression>, bindAs: SCOPE }
+{ kind: 'blob-commit',   storageId: STORAGE, blobKey: <Expression>, succeededEventId?, failedEventId? }
+{ kind: 'blob-delete',   storageId: STORAGE, blobKey: <Expression>, succeededEventId?, failedEventId? }
+```
+
+`blob-metadata` returns the `BlobRef` and never the bytes. A key that names nothing, or names
+a still-staged object, **fails the invocation** rather than binding a plausible empty record —
+`BLOB_METADATA_FAILED`, with the store's own code in `details.code`.
+
+There is no `list`. Add one only when a real application scenario requires it.
+
+## Lifecycle: staged, then committed
+
+An object has two lifecycle values:
+
+| | Meaning |
+| --- | --- |
+| `staged` | It exists and has a key. **Nothing references it.** |
+| `stored` | A committed transaction claimed it, through `blob-commit`. |
+
+This exists because **external object storage does not participate in an Axiom transaction**,
+and pretending otherwise would be a lie. The consequences are stated rather than hidden:
+
+**Storage succeeds, state commit fails.** The upload is already staged. The transaction that
+meant to reference it rolls back, so the `blob-commit` intent is discarded with every other
+effect of that transaction and the object stays `staged`. `BlobStorageAdapter.listStaged()`
+enumerates them, so an orphan is a sweepable staged object rather than a committed object
+nothing points at.
+
+**State deletion succeeds, blob deletion fails.** The transaction committed: the record no
+longer references the object, and that is correct. The `blob-delete` effect then failed, and
+it is visible in `server.blobLog()` with its status and `lastError`. State correctness and
+external cleanup remain **separately observable** rather than falsely coupled — the alternative
+would be rolling back correct state because a remote store was briefly unreachable.
+
+Orphan policy, therefore: **staged upload + commit, plus a host-side sweep of staged objects.**
+Nothing pretends the store joined the transaction.
+
+## Upload
+
+```
+user selects a file
+      ↓
+POST /axiom/blob/<storageId>          ← the host's transport, identical for every application
+      ↓  (uploadAuthorization, acceptedMediaTypes, maxSizeBytes all checked here)
+BlobRef                                ← staged
+      ↓
+action argument
+      ↓
+authoritative state + blob-commit
+```
+
+Application-authored upload routes: **zero**. `POST /axiom/blob/<storageId>` is the endpoint
+for every Axiom application there will ever be, exactly as `POST /axiom` is the semantic one.
+The request body is the bytes; `content-type` is the media type; the optional
+`x-axiom-filename` header carries the filename. The response is `{ kind: 'blob', ref }`.
+
+Programmatically, the same path is `server.stageBlob(storageId, principal, upload)`.
+
+## Download
+
+```
+GET /axiom/blob/<storageId>/<key>
+```
+
+Application-authored download routes: **zero**. The authority evaluates the store's
+`readAuthorization` against the caller, then the host streams the bytes with the object's
+media type and, when it has one, a `content-disposition` naming the stored filename. The
+opaque key is never offered as a filename.
+
+Programmatically: `server.authorizeBlobRead(storageId, key, principal)`.
+
+## Blobs are never base64 in state
+
+MUST NOT: encode an object's contents into a `LiteralValue`, a state value, an action
+argument or the Server IR. A 5MB attachment leaves the record it is attached to exactly as
+large as a 5-byte one, because what the record holds is five scalars.
+
+## Adapters
+
+```ts
+interface BlobStorageAdapter {
+  stage(upload): Promise<BlobStoreResult<StoredBlob>>;
+  commit(key): Promise<BlobStoreResult<StoredBlob>>;
+  metadata(key): Promise<BlobStoreResult<StoredBlob>>;
+  read(key): Promise<BlobStoreResult<{ blob: StoredBlob; data: Uint8Array }>>;
+  delete(key): Promise<BlobStoreResult<null>>;
+  listStaged?(olderThanMs?): Promise<StoredBlob[]>;
+}
+```
+
+Registered per `StorageDef.id` on `createAxiomServer({ blobStores })` or
+`serveAxiomApplication({ blobStores })`. A declared store with no adapter fails `start()`.
+
+`stage` is the only write path, deliberately: there is no point at which a store could be
+told to write an object that the transaction referencing it might still refuse.
+
+`createMemoryBlobStore()` implements the complete lifecycle deterministically, with seeding
+and per-operation failure injection for tests and conformance fixtures.
+
+## Idempotency and retries
+
+Storage effects ride the **same** transactional outbox integration effects do: committed
+atomically with the state that references the object, dispatched post-commit, retried under
+`StorageDef.retry`, and reported through `server.blobLog()` (a filtered view of
+`effectLog()`). There is no second durability system.
+
+## Observability
+
+```ts
+server.blobLog();  // EffectRecord[] whose `storage` is set
+```
+
+Each carries `storage.operation` (`'commit'` / `'delete'`), `storage.key`, `status`,
+`attempts` and `lastError`. An uncommitted upload and a failed external deletion are both
+visible here; neither is a silent orphan.
+
+## Contract
+
+Storage vocabulary requires `axiom.server.v5`, computed from the document. See
+[`AUTHORITY.md`](AUTHORITY.md#contract-identifiers).
+
+## Diagnostic codes
+
+| Code | Meaning |
+| --- | --- |
+| `UNKNOWN_STORAGE` | (validation) A `storageId` or `blobEntityId` that does not resolve. |
+| `INVALID_BLOB_ENTITY` | (validation) The named entity is not the `blobRefEntity()` shape. |
+| `INVALID_BLOB_OPERATION` | (validation) A blob operation that cannot execute as written. |
+| `BLOB_STORE_MISSING` | No adapter is registered for the store. |
+| `BLOB_NOT_FOUND` | No object with that key, or the key names a still-staged upload. |
+| `BLOB_ACCESS_DENIED` | The caller may not read, download or upload. Also the answer for a key that names nothing. |
+| `BLOB_TOO_LARGE` | The upload exceeds `maxSizeBytes`. |
+| `BLOB_MEDIA_TYPE_REJECTED` | The media type is not in `acceptedMediaTypes`. |
+| `BLOB_OPERATION_FAILED` | A `blob-commit` or `blob-delete` failed at the store after its retry policy. |
+| `BLOB_STORAGE_UNAVAILABLE` | (runtime) The host provides no object storage at all. |
+| `BLOB_METADATA_FAILED` | (runtime) A `blob-metadata` lookup failed; the store's own code is in `details.code`. |

package/docs/SUBSCRIPTIONS.md

@@ -0,0 +1,315 @@
+# Subscriptions
+
+Axiom 0.9.0-alpha.1. How an application receives a stream of external events — an MQTT
+topic, a WebSocket feed, a queue consumer, a filesystem watcher, a serial port — without a
+client, a socket or a callback anywhere in the graph.
+
+[`INTEGRATIONS.md`](INTEGRATIONS.md) is the outbound half (query and effect); this is the
+inbound one. [`AUTHORITY.md`](AUTHORITY.md) is the trust boundary all three sit behind.
+
+## The three directions
+
+Axiom's whole external-interaction model is three directions and no more:
+
+| | Shape | Vocabulary |
+| --- | --- | --- |
+| **Query** | Ask, and wait for a finite answer. | `integration-query` on an `IntegrationOperationDef{mode:'query'}` |
+| **Effect** | Tell the world to do something. No answer joins the transaction. | `integration-effect` on an `IntegrationOperationDef{mode:'effect'}` |
+| **Subscription** | The world tells *you*, for as long as you are listening. | `SubscriptionDef` → `EventDef` |
+
+Storage is not a fourth direction: a metadata lookup is a query, a commit or a delete is an
+effect. See [`STORAGE.md`](STORAGE.md).
+
+## The model
+
+```ts
+interface SubscriptionDef {
+  id: NodeId;
+  kind: 'subscription';
+  integrationId: NodeId;
+  source?: string;
+  arguments?: Record<string, Expression>;
+  eventId: NodeId;
+  lifecycle?: {
+    autoStart?: boolean;
+    required?: boolean;
+    reconnect?: { policy: 'none' | 'fixed' | 'exponential'; maxAttempts?: number; delayMs?: number };
+  };
+  delivery?: {
+    maxQueued?: number;
+    backpressure?: 'block' | 'reject' | 'drop-oldest' | 'drop-newest';
+    deduplicateBy?: FieldId;
+    deduplicationWindow?: number;
+    maxAttempts?: number;
+    onFailure?: 'report' | 'pause';
+  };
+}
+```
+
+`integrationId` names the capability domain whose adapter maintains the source. `source` is
+a **semantic** name — `'device-status'`, `'inbound-orders'` — that the adapter maps to a
+topic, a URL, a queue or a device; the graph never learns which. Absent, the subscription's
+own id is the name.
+
+```ts
+graph.addNode<SubscriptionDef>({
+  id: SUBSCRIPTION_DEVICE_STATUS,
+  kind: 'subscription',
+  name: 'live device status',
+  integrationId: INTEGRATION_DEVICE_PROVIDER,
+  source: 'device-status',
+  eventId: EVENT_DEVICE_STATUS_CHANGED,
+  delivery: { deduplicateBy: F_CHANGE_DELIVERY_ID, maxQueued: 32 },
+});
+```
+
+## The pipeline
+
+There is no second event system. A delivery enters the one that already exists:
+
+```
+external source → SubscriptionAdapter → SubscriptionDef → EventDef → TriggerDef → ActionDef
+```
+
+MUST NOT: invoke an application callback, register a handler, or mutate state from the
+adapter. An adapter's only semantic act is calling `deliver`.
+
+## Rules
+
+- A `SubscriptionDef` MUST name an `EventDef` that at least one `TriggerDef{when:{kind:'event'}}`
+  is bound to. A live source feeding nothing is `SUBSCRIPTION_EVENT_UNREACHABLE`.
+- A `SubscriptionDef` MUST appear in a graph with server-authoritative state, or it is
+  `SUBSCRIPTION_WITHOUT_AUTHORITY` — nothing would activate it.
+- Subscriptions are **server-only**. `compileToIR` strips them from the client IR exactly as
+  it strips integrations. There is no client-side subscription and none is compiled inert;
+  `validateForBrowser` and `compileToIR` therefore agree by construction.
+- `arguments` are evaluated **once, at activation**, in the root scope. A live source is not
+  re-negotiated per message, so nothing per-delivery is in scope there.
+- A subscription-originated action runs with `source: 'system'`. Declare
+  `invocation: { allowedSources: ['system'] }` on it — see **Security** below.
+
+## Lifecycle
+
+Six states, and only these transitions:
+
+```
+inactive ──start──▶ starting ──ok──▶ active ──stop──▶ stopped
+                       │               │
+                       │ fail          │ transport lost
+                       ▼               ▼
+                    failed ◀─exhausted─ reconnecting ──ok──▶ active
+```
+
+| State | Meaning |
+| --- | --- |
+| `inactive` | Declared, but `lifecycle.autoStart: false` — startup did not activate it. |
+| `starting` | The first activation attempt is in flight. |
+| `active` | The source is established and deliveries are being accepted. |
+| `reconnecting` | The transport was lost, or an attempt failed; the reconnect policy is running. |
+| `failed` | The reconnect policy is spent, or `onFailure: 'pause'` stopped it. Terminal for this process. |
+| `stopped` | `server.stop()`. Accepts nothing, ever again. |
+
+**Startup owns activation.** `AxiomServer.start()` activates every `autoStart` subscription,
+after persistence has loaded and pending effects have resumed. Application code MUST NOT —
+and cannot — call `subscription.start()`: there is no such method.
+
+**A failed source does not stop the application.** `lifecycle.required` is false by default,
+so an unreachable feed leaves the application serving requests with that subscription
+observably `reconnecting` then `failed`. Set `required: true` only when the application is
+not meaningfully running without the source; `start()` then rejects.
+
+**Restart recreates from the graph.** A live connection is not persisted. The graph is the
+declaration of desired subscription state, so a restarted process reactivates every
+`autoStart` subscription from the Server IR alone.
+
+**Reconnect policy is Axiom's; reconnect mechanics are the adapter's.** An adapter reports a
+lost transport through `connectionLost()`; how many attempts, how far apart and when to give
+up come from `lifecycle.reconnect`, so the answer does not change with the provider. Default:
+exponential, 5 attempts, 1000ms base.
+
+**A transport failure is not a domain event.** It moves the lifecycle state and reports a
+diagnostic. It becomes an `EventDef` only if an author deliberately declares one for it.
+
+## Delivery guarantees
+
+**Delivery is at-least-once.** A provider that redelivers, a reconnect that replays, and a
+crash between dispatch and commit can each present the same external event twice. Axiom does
+not claim exactly-once, because it cannot deliver it across all three.
+
+**Deduplication makes it effectively-once where an external identity exists.**
+`delivery.deduplicateBy` names a field of the event's payload entity carrying the provider's
+own delivery identity — a message id, an offset, a delivery tag. A repeated value is
+acknowledged and never dispatched. It is deliberately a payload field and not an Axiom
+transaction id: the provider decides what identifies a delivery, and Axiom cannot invent one
+that survives a redelivery it did not cause.
+
+**Deduplication survives a restart** when the persistence adapter implements `hasDelivery`
+and `recordDelivery` — `createMemoryPersistence` does. Without them the window is
+in-process only and does **not** survive a restart; that is a real limitation, not a
+guarantee to build on.
+
+Deduplication is bounded by `deduplicationWindow` (default 512). A redelivery older than the
+window is dispatched again.
+
+## Ordering
+
+| | Guaranteed? |
+| --- | --- |
+| Deliveries of **one** subscription | **Yes** — dispatched one at a time, in accepted order, each in its own transaction. |
+| Deliveries of **two** subscriptions | **No.** None. They are independent sources. |
+| A delivery against a client request or a trigger tick | Only that each takes its own serialized turn. No relative order. |
+
+Two subscriptions do enter the same serialized authority queue, so their *commits* never
+interleave — but nothing orders their *arrival*, and a consumer MUST NOT build on an
+accident of interleaving.
+
+## Transactions
+
+Each accepted delivery enters authoritative execution through **one** transaction boundary.
+Multiple deliveries never share a transaction: the runtime awaits each dispatch before taking
+the next off the queue.
+
+If the triggered action fails, its transaction rolls back like any other — but the external
+provider cannot un-send the event. What happens next is `delivery.maxAttempts` (default 1,
+i.e. no retry) and then `delivery.onFailure`.
+
+## Backpressure
+
+The queue is **bounded**, always. `maxQueued` defaults to 64.
+
+| `backpressure` | When the queue is full | Loses events? |
+| --- | --- | --- |
+| `block` (default) | The adapter's `deliver` call does not resolve until there is room. | **No** |
+| `reject` | The delivery is refused; the source still holds it. | **No** |
+| `drop-oldest` | The oldest queued delivery is discarded. | **Yes** |
+| `drop-newest` | The arriving delivery is discarded. | **Yes** |
+
+The default cannot lose an authoritative event: an adapter that awaits `deliver` applies real
+backpressure to its own transport instead of buffering without limit. The two dropping modes
+are legitimate for a genuinely lossy source — a sensor feed where only the newest reading
+matters — and both report `SUBSCRIPTION_DELIVERY_DROPPED` and increment
+`SubscriptionRecord.dropped`. **Loss is always declared and never silent.**
+
+## Poison deliveries
+
+A delivery whose action keeps failing is bounded by `delivery.maxAttempts` and then handled by
+`delivery.onFailure`:
+
+| `onFailure` | Behaviour |
+| --- | --- |
+| `report` (default) | Count it as `failed`, answer the adapter `failed`, take the next delivery. |
+| `pause` | The above, then stop the subscription — state `failed`. |
+
+Neither ever retries without bound. There is no dead-letter queue: Axiom does not invent a
+workflow system, and an adapter that needs one translates a `failed` outcome into its
+provider's own.
+
+## Acknowledgement
+
+`deliver` resolves with a `DeliveryOutcome` describing what became of the delivery, and the
+adapter translates it into whatever its provider needs — an `ack`, a `nack`, an offset
+commit, or nothing:
+
+| Status | Meaning | Typical translation |
+| --- | --- | --- |
+| `applied` | Dispatched; its action committed. | ack / commit offset |
+| `duplicate` | Already seen; not dispatched again. | ack |
+| `rejected` | The payload did not conform to the `EventDef`. | ack, or dead-letter |
+| `failed` | Dispatched; the action failed after every permitted attempt. | nack, or dead-letter |
+| `dropped` | Discarded under a declared lossy policy. | ack |
+| `refused` | Refused by backpressure; the source still holds it. | nack |
+| `stopped` | The subscription is no longer running. | nack |
+
+Ack vocabulary lives in the adapter contract and MUST NOT appear in an `ApplicationGraph`:
+every provider spells it differently, and a graph that named one would stop being portable.
+
+## Payload validation
+
+A delivered payload is **untrusted data**, even though the adapter is trusted infrastructure.
+It is validated against the target `EventDef.payloadType` **before** anything else. An invalid
+payload:
+
+- does not dispatch the event,
+- does not invoke any action,
+- does not mutate authoritative state,
+- reports `EVENT_PAYLOAD_INVALID` and increments `SubscriptionRecord.rejected`.
+
+## Security
+
+- A client **cannot** forge a delivery. There is no protocol message that delivers into a
+  subscription; a delivery exists only inside the authority, from an adapter.
+- A client **cannot** invoke a subscription-only action. Declare
+  `invocation: { allowedSources: ['system'] }` and `INVOCATION_SOURCE_NOT_ALLOWED` refuses a
+  client-sourced call before identity is consulted.
+- An external source **cannot** bypass authorization, preconditions, constraints, transition
+  constraints or rollback. A subscription-originated action runs through exactly the same
+  `invokeCore` a client request does, under `principal: null`.
+- After shutdown, **no** delivery reaches state. `stop()` moves every subscription to
+  `stopped`, and a stopped subscription answers `stopped` to everything.
+
+## Observability
+
+```ts
+server.subscriptionLog();                    // SubscriptionRecord[]
+server.subscriptionStatus(SUBSCRIPTION_ID);  // SubscriptionRecord | undefined
+```
+
+`SubscriptionRecord` carries `state`, `source`, `attempts`, `received`, `applied`,
+`rejected`, `failed`, `dropped`, `queued`, `lastDeliveryAt` and `lastFailure`. That is the
+whole operational picture — configured, active, reconnecting, failed, arriving, being
+refused — and it is host observability, not an application-authored health route.
+
+## Adapters
+
+```ts
+interface SubscriptionAdapter {
+  start(context: SubscriptionContext): Promise<SubscriptionHandle>;
+}
+```
+
+Registered per integration id on `createAxiomServer({ subscriptions })` or
+`serveAxiomApplication({ subscriptions })`. A declared subscription with no registered
+adapter fails `start()`, rather than staying silently inactive.
+
+Sockets, `EventEmitter`s, Node streams, subprocesses, serial ports and provider SDKs are all
+permitted **inside** an adapter and nowhere above it. One adapter may multiplex many
+subscriptions over one connection: nothing in Axiom assumes `SubscriptionDef` and TCP session
+correspond.
+
+`createScriptedSubscriptionAdapter(scripts, host)` is the deterministic fake — connect
+success and failure, deliveries, duplicates, delayed deliveries, disconnection and
+reconnection, all as data against a virtual clock, with no network and no wall-clock wait.
+The same script shape appears in the portable conformance fixtures.
+
+## Subscription vs. webhook vs. polling
+
+| | What it is | How it reaches Axiom |
+| --- | --- | --- |
+| **Webhook** | An externally initiated **finite request**. Each delivery independently enters Axiom. | The host verifies it, then sends one `EventRequest`. See [`EVENTS.md`](EVENTS.md). |
+| **Subscription** | Axiom maintains a standing **semantic interest** in a long-lived source. Deliveries occur while it is active. | The adapter calls `deliver` while the subscription is `active`. |
+| **Polling** | Axiom asks, repeatedly, on a schedule. | `TriggerDef{when:{kind:'interval'}}` → `integration-query`. See [`TRIGGERS.md`](TRIGGERS.md). |
+
+Do not hide polling behind subscription syntax: a source you have to ask is a query on a
+timer, and saying so keeps the graph honest about what it does to the provider.
+
+`TriggerDef` keeps timer and lifecycle semantics; `SubscriptionDef` keeps external long-lived
+sources. Neither replaces the other.
+
+## Contract
+
+Subscription vocabulary requires `axiom.server.v5`, computed from the document — a graph that
+uses none of it compiles to the byte-identical older document it always did. See
+[`AUTHORITY.md`](AUTHORITY.md#contract-identifiers).
+
+## Diagnostic codes
+
+| Code | Meaning |
+| --- | --- |
+| `SUBSCRIPTION_EVENT_UNREACHABLE` | (validation) The event has no trigger bound to it. |
+| `SUBSCRIPTION_WITHOUT_AUTHORITY` | (validation) The graph has no server-authoritative state. |
+| `SUBSCRIPTION_INVALID_POLICY` | (validation) A queue below one, no attempts, an unknown backpressure policy, or a `deduplicateBy` that is not a field of the payload entity. |
+| `SUBSCRIPTION_ADAPTER_MISSING` | No adapter is registered for the integration. |
+| `SUBSCRIPTION_START_FAILED` | The source could not be established after every reconnect attempt. |
+| `SUBSCRIPTION_DELIVERY_DROPPED` | A delivery was discarded under a declared lossy policy. |
+| `SUBSCRIPTION_DELIVERY_FAILED` | A delivery's action failed after every permitted attempt. |
+| `EVENT_PAYLOAD_INVALID` | The payload did not conform to the `EventDef.payloadType`. |

package/docs/TRIGGERS.md

@@ -1,10 +1,16 @@
 # Triggers
 
-Axiom 0.8.2-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 0.9.0-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
 embedding callback code. `docs/AUTHORITY.md`
 [§ Triggers](AUTHORITY.md#triggers) is the load-bearing statement of the execution model;
 this file is the vocabulary.
 
+A trigger covers time (`interval`, `delay`), the application lifecycle, and a dispatched
+event. It does **not** cover a long-lived external source: that is a
+[`SubscriptionDef`](SUBSCRIPTIONS.md), whose deliveries become `EventDef` payloads that
+`event` triggers then react to. Keep the two separate — an interval trigger driving an
+`integration-query` is polling, and polling is not a subscription.
+
 ## The model
 
 ```ts

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.8.2-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.9.0-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
 All eleven share `UIBase`:

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.8.2-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.9.0-alpha.1. Validation is authoring-time structural checking. It is not the same
 as runtime constraint evaluation — see [`CONSTRAINTS.md`](CONSTRAINTS.md) for the four
 layers of correctness.
 
@@ -134,6 +134,19 @@ Full model: [`INTEGRATIONS.md`](INTEGRATIONS.md), [`EFFECTS.md`](EFFECTS.md),
 | `INVALID_INVOCATION_SOURCE` | `ActionDef.invocation.allowedSources` is present but empty — the action could never be invoked at all. |
 | `CLIENT_TRIGGER_UNSUPPORTED` | A client-authority trigger of a kind the intended trigger runtime does not execute — before 8.1 this validated and compiled anyway, and simply never fired (spec 8.1 §31-36). The browser trigger runtime executes no kind today. Only raised when a `triggerRuntime` is actually named — `validateGraph(graph)` with no options is target-neutral and never raises it; `validateForBrowser(graph)`/`compileToIR(graph)` name the real browser capabilities and do (spec 8.2 §2-6). The message states the remediation: move the target action to server authority, or compile for a trigger runtime that publishes the kind. |
 
+### Subscriptions and object storage
+
+Full model: [`SUBSCRIPTIONS.md`](SUBSCRIPTIONS.md) and [`STORAGE.md`](STORAGE.md).
+
+| Code | Raised when |
+| --- | --- |
+| `SUBSCRIPTION_EVENT_UNREACHABLE` | A `SubscriptionDef` whose `eventId` no `TriggerDef{when:{kind:'event'}}` is bound to. Every delivery would be validated and then discarded — a live source feeding nothing. |
+| `SUBSCRIPTION_WITHOUT_AUTHORITY` | A `SubscriptionDef` in a graph with no server-authoritative state. Subscriptions are authority-side; nothing would ever activate it. |
+| `SUBSCRIPTION_INVALID_POLICY` | A delivery or lifecycle policy that cannot be executed as written: `maxQueued` below one, `maxAttempts` below one, an unknown backpressure policy, or a `deduplicateBy` that is not a field of the event's payload entity. |
+| `UNKNOWN_STORAGE` | A blob operation's `storageId`, or a `StorageDef.blobEntityId`, that does not resolve. |
+| `INVALID_BLOB_ENTITY` | A `StorageDef.blobEntityId` naming an entity that is not the canonical `blobRefEntity()` shape. The message names the missing fields. |
+| `INVALID_BLOB_OPERATION` | A blob operation that cannot execute as written. |
+
 ### UI and routing
 
 | Code | Raised when | Severity |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom",
-  "version": "0.8.2-alpha.1",
+  "version": "0.9.0-alpha.1",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -32,10 +32,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.8.2-alpha.1",
-    "@cynodia/axiom-runtime": "0.8.2-alpha.1",
-    "@cynodia/axiom-compiler": "0.8.2-alpha.1",
-    "@cynodia/axiom-agent-api": "0.8.2-alpha.1"
+    "@cynodia/axiom-core": "0.9.0-alpha.1",
+    "@cynodia/axiom-runtime": "0.9.0-alpha.1",
+    "@cynodia/axiom-compiler": "0.9.0-alpha.1",
+    "@cynodia/axiom-agent-api": "0.9.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"