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

package/AGENTS.md

@@ -0,0 +1,68 @@
+# Instructions for AI coding agents
+
+You are consuming **Axiom** as an application framework. This file is routing only; the
+contract lives in `docs/`.
+
+## Read this first
+
+**Read [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md), in full, before writing any
+application code.** It is the compressed operational contract for application authors and it
+ships inside this package.
+
+Then escalate in this order, and only as far as the question requires:
+
+1. **`docs/AGENT_REFERENCE.md`** — the contract. Start here, every time.
+2. **The `.d.ts` declarations in `dist/`** — the API contract. Signatures, unions and
+   branded types are authoritative there.
+3. **The focused document in `docs/`** for the topic — the full contract for one area. See
+   the map in [`README.md`](README.md#documentation-map).
+4. **A minimal public-API probe** — build the smallest graph that isolates the question,
+   call `validateGraph` and read the returned codes. Diagnostics are structured and name
+   what is wrong.
+
+Only if all four leave the question open is reading framework implementation source
+justified. That is framework debugging, not application authoring.
+
+## Do not
+
+- **Do not clone or reverse-engineer the Axiom repository to learn normal usage.** Everything
+  needed to author an application is in this package. There is no published Axiom CLI.
+- **Do not search the web or scrape npm for documentation.** This package is the primary
+  source, and it describes this exact version.
+- **Do not read, edit or patch generated output.** The emitted JavaScript, HTML and CSS are
+  build products. Nothing is authored there.
+- **Do not guess the API from React, Vue, Angular, Svelte or Express conventions.** Axiom has
+  no component, no hook, no JSX, no route handler, no ORM and no callback anywhere in the
+  graph. Guessing from those conventions produces graphs `validateGraph` rejects.
+- **Do not reach for an escape hatch.** There is no `formatter: fn`, no `validator: fn`, no
+  raw-CSS channel and no stored closure. If a capability seems missing, it is expressed as a
+  graph node; look it up rather than working around it.
+
+## Prefer canonical Axiom semantics
+
+Each row is a pointer, not the rule. The rule itself lives in
+[`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) and in the topic document; read it
+there rather than treating this table as a specification.
+
+| Instead of | Use |
+| --- | --- |
+| Mutating an object an expression returned | A `Location`, addressing the writable position |
+| A field name key in a record | The `FieldId` — runtime records are keyed by field id |
+| A hand-written validation function | A `ConstraintDef` or `TransitionConstraintDef` |
+| A hidden control to forbid an operation | A guard or a transition constraint. `hidden` is not `forbidden` |
+| CSS, a colour or a length | A presentation role or token, and a `Theme` |
+| A route handler, controller or SQL statement | `StateDef.authority` plus an `ActionDef` |
+| A callback for new capability | The graph node that expresses it |
+
+## When something fails
+
+`validateGraph` and the runtime both report structured diagnostics with a code and a path.
+Match on the code, never on the message, and look the code up:
+[`docs/VALIDATION.md`](docs/VALIDATION.md) for authoring-time codes,
+[`docs/RUNTIME.md`](docs/RUNTIME.md) for runtime codes. A construct that validates and then
+does nothing is a framework defect, not something to work around — report it.
+
+Mistakes that compile but are wrong are collected in
+[`docs/ANTI_PATTERNS.md`](docs/ANTI_PATTERNS.md). Read it before the **first** attempt, not the
+second: collection nulls, how a `repeat` binds its current item, and addressing a collection
+member by identity rather than index all shape a first draft rather than repairing it.

package/README.md

@@ -1,13 +1,39 @@
 # Axiom
 
-AI-native semantic application framework.
+AI-native semantic application framework. An application is a typed semantic graph, not
+source files.
 
-Axiom represents application behavior, state, UI structure and presentation as structured
-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.
+## AI agents: read this first
+
+**Read [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) before writing any Axiom code.**
+It ships inside this package, so no repository access, web search or framework source
+inspection is needed to obtain the contract.
+
+| | |
+| --- | --- |
+| **What** | A semantic application framework. State, behavior, constraints, UI structure, presentation and authority are structured data executed by generic runtimes. |
+| **Who for** | AI-authored applications. The primary author of an Axiom application is a coding agent; human readability is explicitly not the optimization target. |
+| **Start** | [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) — the compressed operational contract for application authors. |
+| **API contract** | The published `.d.ts` declarations in `dist/`. Authoritative for signatures, unions and branded types. |
+| **Deeper semantics** | The focused documents in `docs/` — [map below](#documentation-map). |
+| **Escalation** | `docs/AGENT_REFERENCE.md` → `.d.ts` → the focused `docs/` document for the topic → a minimal public-API probe. |
+
+Axiom's vocabulary is deliberately unlike React, Vue, Angular, Svelte or Express: there is no
+component, no hook, no JSX, no route handler, no ORM and no callback anywhere in the graph.
+Guessing the API from those conventions produces graphs `validateGraph` rejects, so reading
+the reference first is cheaper than any number of attempts.
+
+**Reading the framework's implementation source should not be necessary to author an
+application.** `docs/` plus the `.d.ts` declarations are intended to be sufficient on their
+own. Source inspection is a legitimate tool for debugging Axiom itself; it is not the way to
+discover normal consumer usage, and cloning the repository for that purpose is a sign the
+documentation above was missed.
+
+Shorter forms of the same routing: [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llms.txt), both
+at this package's root.
 
 **Status: experimental / alpha.** The API may change between alpha releases. The
-documentation in `docs/` describes this exact version.
+documentation in `docs/` describes this exact version, `0.9.0-alpha.2`.
 
 ## Installation
 
@@ -17,6 +43,17 @@ npm install @cynodia/axiom-ui         # semantic UI authoring patterns (build ti
 npm install @cynodia/axiom-server     # only if the application has an authority
 ```
 
+Every release of this project is a pre-release and npm's `latest` tag points at it, so the
+plain command above installs the current version. **There is no `alpha` dist-tag** — the tag
+was removed once it stopped tracking releases, and `npm install @cynodia/axiom@alpha` now
+fails with a 404. Pin the exact version instead when one is needed:
+`npm install @cynodia/axiom@0.9.0-alpha.2`.
+
+These are ES modules compiled to ES2022; import them with `import`, not `require`. There is
+no published Axiom CLI. `@cynodia/axiom-server`'s SQLite persistence adapter additionally
+needs a Node build that provides `node:sqlite` (Node 22 or newer); `isSqliteAvailable()`
+reports its absence rather than failing at import.
+
 ## Canonical mental model
 
 | Concept | Is |
@@ -124,30 +161,39 @@ console.log(app.getState(COUNT)); // 1
 
 `compileToHtml(graph)` emits the same application as one self-contained page.
 
-## Documentation
+## Documentation map
 
-The complete operational contract ships with this package, in `docs/`.
+The complete operational contract ships with this package, in `docs/`. Every path below
+resolves inside the installed package. Read `docs/AGENT_REFERENCE.md` first; reach for a
+focused document when the reference is not specific enough for the question at hand.
 
 | Need to understand | Read |
 | --- | --- |
-| Compressed reference for authoring or modifying an app | `docs/AGENT_REFERENCE.md` |
-| Exact runtime guarantees | `docs/SEMANTIC_CONTRACT.md` |
-| Graph, ids, types, entity value representation | `docs/GRAPH_MODEL.md` |
-| Every expression kind, builtin and scope rule | `docs/EXPRESSIONS.md` |
-| Addressing writable positions | `docs/LOCATIONS.md` |
-| Stored, derived, draft and ephemeral state | `docs/STATE.md` |
-| Actions, operations, transactions, iteration | `docs/ACTIONS_TRANSACTIONS.md` |
-| Constraints and transition constraints | `docs/CONSTRAINTS.md` |
-| Semantic UI nodes and bindings | `docs/UI.md` |
-| Presentation, UX intent, themes, formatting | `docs/PRESENTATION.md` |
-| Runtime API and diagnostic codes | `docs/RUNTIME.md` |
-| Server authority, Server IR, the protocol and persistence | `docs/AUTHORITY.md` |
-| Machine queries and graph transformations | `docs/AGENT_API.md` |
-| Validation codes | `docs/VALIDATION.md` |
-| Mistakes that compile but are wrong | `docs/ANTI_PATTERNS.md` |
-
-Start with `docs/AGENT_REFERENCE.md`. It plus the `.d.ts` declarations are intended to be
-sufficient on their own.
+| **Compressed contract for authoring or modifying an app — start here** | [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) |
+| Exact runtime guarantees, stated formally | [`docs/SEMANTIC_CONTRACT.md`](docs/SEMANTIC_CONTRACT.md) |
+| Mistakes that compile but are wrong | [`docs/ANTI_PATTERNS.md`](docs/ANTI_PATTERNS.md) |
+| Graph, node kinds, ids, types, entity value representation | [`docs/GRAPH_MODEL.md`](docs/GRAPH_MODEL.md) |
+| Every expression kind, builtin, scope, presence and null rule | [`docs/EXPRESSIONS.md`](docs/EXPRESSIONS.md) |
+| Addressing writable positions | [`docs/LOCATIONS.md`](docs/LOCATIONS.md) |
+| Stored, derived, draft and ephemeral state | [`docs/STATE.md`](docs/STATE.md) |
+| Actions, operations, guards, transactions, iteration | [`docs/ACTIONS_TRANSACTIONS.md`](docs/ACTIONS_TRANSACTIONS.md) |
+| Constraints and transition constraints | [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) |
+| Semantic UI nodes, interaction primitives and bindings | [`docs/UI.md`](docs/UI.md) |
+| Presentation, UX intent, themes, value formatting | [`docs/PRESENTATION.md`](docs/PRESENTATION.md) |
+| Runtime API, startup lifecycle and diagnostic codes | [`docs/RUNTIME.md`](docs/RUNTIME.md) |
+| Validation codes and what rejects a graph | [`docs/VALIDATION.md`](docs/VALIDATION.md) |
+| Server authority, the trust boundary, Server IR, the protocol, persistence, deployment | [`docs/AUTHORITY.md`](docs/AUTHORITY.md) |
+| External systems: integration definitions, query operations, adapters, secrets | [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) |
+| External effects: the outbox, retries, delivery guarantees, outcomes | [`docs/EFFECTS.md`](docs/EFFECTS.md) |
+| Typed events, webhooks, the dispatch pipeline | [`docs/EVENTS.md`](docs/EVENTS.md) |
+| Timed and lifecycle execution, event-invoked actions | [`docs/TRIGGERS.md`](docs/TRIGGERS.md) |
+| Live inbound streams: lifecycle, delivery, deduplication, backpressure | [`docs/SUBSCRIPTIONS.md`](docs/SUBSCRIPTIONS.md) |
+| Binary data: `BlobRef`, upload, download, authorization, orphans | [`docs/STORAGE.md`](docs/STORAGE.md) |
+| Machine queries, mutation impact and graph transformations | [`docs/AGENT_API.md`](docs/AGENT_API.md) |
+
+`docs/AGENT_REFERENCE.md` plus the `.d.ts` declarations are intended to be sufficient on
+their own. If they are not, that is a documentation defect worth reporting rather than a
+reason to read framework source.
 
 ## What is in the box
 

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.2. 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.2. 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,11 +1,45 @@
 # Agent reference
 
-Axiom 0.8.2-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.9.0-alpha.2. 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:
 [`ANTI_PATTERNS.md`](ANTI_PATTERNS.md).
 
+## Start here
+
+```bash
+npm install @cynodia/axiom            # graph, compiler, runtime, agent API
+npm install @cynodia/axiom-ui         # semantic UI authoring patterns, build time only
+npm install @cynodia/axiom-server     # only if a StateDef declares server authority
+```
+
+Everything is imported from `@cynodia/axiom`; the four re-exported packages need not be
+installed individually. There is no published CLI.
+
+A complete runnable skeleton — graph, state, action, UI, route, compile, run — is the
+minimal application in [`../README.md`](../README.md). Read this document for the rules;
+copy that for the shape.
+
+**Escalation order.** This document → the `.d.ts` declarations → the focused document for the
+topic → a minimal public-API probe: build the smallest graph that isolates the question, call
+`validateGraph`, read the returned codes. Reading Axiom's own implementation source is for
+debugging the framework, not for authoring an application.
+
+**How much of this to read.** Everything up to and including
+[Agent API](#agent-api) applies to every Axiom application. If no `StateDef` declares
+`authority: 'server'`, the application is client-only and
+[SERVER AUTHORITY](#server-authority) onwards — authority, integrations, effects, triggers,
+subscriptions, storage — describes capability it does not use; skim the headings and stop.
+Read [`ANTI_PATTERNS.md`](ANTI_PATTERNS.md) **before** the first attempt, not the second:
+collection nulls, repeat scope binding and identity-over-index selectors all shape a first
+draft.
+
+**Do not guess from React, Vue, Angular, Svelte or Express.** Axiom has no component, no hook,
+no JSX, no route handler, no ORM and no callback in the graph. There is no `formatter: fn`, no
+`validator: fn`, no raw-CSS channel and no stored closure anywhere; new capability arrives as
+an inspectable node, never as a function you supply.
+
 ## Glossary
 
 One canonical term per concept. These are not interchangeable.
@@ -31,7 +65,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.8.2'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.9.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
@@ -323,6 +357,13 @@ boolean types (`TYPE_MISMATCH`).
 Every kind is in `UI_NODE_KINDS`: `view` `container` `text` `repeat` `field-display` `form`
 `input` `button` `conditional` `diagnostic` `dialog`. Detail: [`UI.md`](UI.md).
 
+Every kind carries the same base, and `visibleWhen` lives here rather than in
+`presentation`:
+
+```ts
+{ id, kind, name?, visibleWhen?: Expression, presentation?: Presentation, metadata? }
+```
+
 - `RepeatNode` binds the current item to **the repeat node's own id**; the template refers to it as `ref(repeatNodeId)`.
 - `InputNode.binding` is `{ location }` — no expression, no field id. An input write goes through the same mutation engine and transaction as an action.
 - `ButtonNode.arguments` is keyed by **action parameter id**.
@@ -412,6 +453,22 @@ presentation: {
 }
 ```
 
+Every value is a closed vocabulary, exported as an array; a token outside it is a validation
+**error**, never a silently ignored value. The four an application reaches for constantly:
+
+| Property | Vocabulary | Array |
+| --- | --- | --- |
+| `layout` | `vertical` `horizontal` `grid` `stack` | `LAYOUT_KINDS` |
+| `gap`, `padding` | `none` `xsmall` `small` `medium` `large` `xlarge` | `SPACING_TOKENS` |
+| `textRole` | `body` `caption` `label` `heading` `title` `display` | `TEXT_ROLES` |
+| `density` | `compact` `comfortable` `spacious` | `DENSITIES` |
+
+`layout: 'horizontal'` is shorthand for `layout: { kind: 'horizontal', gap?, align?, justify?,
+wrap?, columns? }` — a bare token or the object, never a third form. `stack` is a tight
+vertical column, not overlapping children. Every other vocabulary — roles, UX roles, surfaces,
+treatments, icons, control variants, sizing, value formats, device classes —
+is in [`PRESENTATION.md`](PRESENTATION.md); read it before guessing a token.
+
 Resolution precedence, lowest first:
 
 ```text
@@ -668,7 +725,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 +744,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.2. 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.2. 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