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

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.8.1-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.1-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.1-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:
@@ -31,7 +31,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.8.0'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.8.2'
 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
@@ -496,6 +496,22 @@ if (!result.ok) {
 warnings never make a graph invalid. 72 codes in `VALIDATION_CODES`, grouped in
 [`VALIDATION.md`](VALIDATION.md).
 
+**`validateGraph(graph)` with no options is target-neutral by design** (spec 8.2 §2-4): a
+graph is never rejected for a renderer or trigger runtime nobody named. This means a bare
+`validateGraph(graph).valid === true` does **not** by itself guarantee the graph is
+executable by the browser client — a UI node kind no renderer implements, or a
+client-authority trigger kind the browser trigger runtime does not execute
+(`CLIENT_TRIGGER_UNSUPPORTED`), both validate silently under the no-options call. Use
+`validateForBrowser(graph)` (`@cynodia/axiom-compiler`) for a validate-only check against
+real browser capabilities, or call `compileToIR(graph)` directly — it applies those same
+capabilities and throws `GraphValidationError` on exactly what `validateForBrowser` would
+report as an error. See [Renderability](#renderability) below for the parallel UI-kind gate.
+
+```ts
+validateGraph(graph).valid;          // target-neutral: accepts every UI kind and trigger kind
+validateForBrowser(graph).valid;     // browser-real: same as compileToIR's validation step
+```
+
 ## Agent API
 
 ```ts
@@ -638,7 +654,7 @@ event.
 agent.listIntegrations() / agent.listIntegrationOperations(id?);
 agent.getActionsUsingIntegration(id) / agent.getEffectsForAction(actionId);
 agent.getTriggersForAction(actionId) / agent.getTimedTriggers();
-agent.getActionsTriggeredByEvent(eventId) / agent.getWebhookEvents();
+agent.getActionsTriggeredByEvent(eventId) / agent.getTriggeredEvents();  // graph-static: has a bound trigger, not "was delivered"
 agent.getExternalDependencies();   // { integrations, operations } — the deployment manifest
 agent.getSystemOnlyActions() / agent.getTriggersTargetingClientOnlyActions();
 agent.isClientInvocable(actionId) / agent.isSystemOnly(actionId);
@@ -647,17 +663,106 @@ agent.isClientInvocable(actionId) / agent.isSystemOnly(actionId);
 Portable artifacts, for a runtime written in another language:
 
 ```
-@cynodia/axiom-server/conformance                     the fixture manifest
+@cynodia/axiom-server/conformance                     the fixture manifest (fixture.format, below)
 @cynodia/axiom-server/conformance/<name>.json         one fixture, pure data
-@cynodia/axiom-server/schema/server-ir.v1.schema.json JSON Schema for the IR
+@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
+@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
 ```
 
+This list is generated/tested content, not hand-maintained prose: `packages/demo/test
+/documentation.test.ts` fails if a shipped `schema/*.json` file is missing from it or a
+listed file no longer exists (spec 8.2 §43-45). `runConformanceFixture`/
+`runConformanceSuite` (`@cynodia/axiom-server`) are the public runner over that fixture
+format — see [`AUTHORITY.md`](AUTHORITY.md#conformance) for `fixture.conformance` (the
+fixture-format version) vs `fixture.serverIR.contract` (the per-fixture Server IR contract)
+vs the manifest's own `conformance`/`protocol`/`release` fields — three separate concepts,
+never conflated under one "contract" name (spec 8.2 §9-10).
+
 Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZATION_DENIED`
 `INVOCATION_SOURCE_NOT_ALLOWED` `CONCURRENCY_CONFLICT` `MALFORMED_REQUEST`
 `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
@@ -683,6 +788,19 @@ Capabilities describe **node-kind** support, not partial support: a renderer can
 that it draws a kind but not one of its options. Nothing in the current vocabulary needs that,
 and it is a deliberate future extension rather than an oversight.
 
+The same gate exists for client-authority triggers, since the browser trigger runtime
+implements no `TriggerSpec.kind` at all:
+
+```ts
+validateGraph(graph, { triggerRuntime: BROWSER_TRIGGER_CAPABILITIES });  // CLIENT_TRIGGER_UNSUPPORTED
+compileToIR(graph);                                                     // applies it by default
+```
+
+`CLIENT_TRIGGER_UNSUPPORTED`'s message states the remediation, not only the refusal: move
+the trigger's target action to server authority, or compile for a trigger runtime that
+publishes the kind (`compileToIR(graph, { triggerRuntime })`). Full model:
+[`TRIGGERS.md`](TRIGGERS.md#where-a-trigger-executes).
+
 ## Named expressions
 
 ```ts

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.8.1-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.1-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:
@@ -549,6 +559,26 @@ Running them requires no part of this implementation. That is the point: the Ser
 specification plus these fixtures are the whole contract, so an independent runtime in
 another language can be held to exactly the same standard.
 
+**A public reference runner is exported for the TypeScript reference runtime itself**
+(spec 8.2 §14-16):
+
+```ts
+import { runConformanceFixture, runConformanceSuite } from '@cynodia/axiom-server';
+
+const result = await runConformanceFixture(fixtureJson);   // { name, ok, failures[] }
+```
+
+It imports only `@cynodia/axiom-server` and fixture data — no graph, no compiler, no
+builder — and reports structured pass/fail rather than throwing on an ordinary fixture
+mismatch. `packages/server/test/conformance.test.ts` runs every shipped fixture through
+this exact function, and `npm run conformance:run` (`scripts/run-conformance.mjs`) runs the
+whole suite from a standalone script using nothing but this public API and the manifest —
+the "held to the same standard by an outside caller" claim, demonstrated rather than
+asserted. The fixture **model** (`ConformanceFixture` and friends, `conformance-types.ts`)
+is deliberately kept separate from this **adapter**
+(`conformance-runner.ts`): a non-TypeScript implementation needs only the model's shape and
+the semantics on this page, never this file.
+
 Enumerate the suite from its manifest rather than by listing a directory:
 
 ```
@@ -556,12 +586,24 @@ Enumerate the suite from its manifest rather than by listing a directory:
 @cynodia/axiom-server/conformance/<name>.json → one fixture
 ```
 
-The manifest names the contracts the fixtures are written against (`axiom.conformance.v1`,
-`axiom.server.v1`, `axiom.protocol.v1`), the release, every area covered, and every fixture
-with its file. A runtime that does not implement a contract the manifest names should refuse
-the suite rather than discover the mismatch one assertion at a time. The files are plain JSON
-in a documented package directory, so a non-JavaScript consumer can read them straight out of
-the tarball without Node's module resolver.
+The manifest carries three **separate, non-overlapping** version concepts (spec 8.2 §9-10;
+do not conflate them under one "contract" name):
+
+| Field | Means |
+| --- | --- |
+| `manifest.conformance` | The **fixture-format** version (`axiom.conformance.v1`/`v2`) — the shape of the JSON documents themselves: what top-level keys a fixture may have (`invocations` vs `steps`/`externalAdapters`, and so on). |
+| `manifest.baseContract` | The **oldest** Server IR contract any fixture in this manifest may use — `axiom.server.v1`, always, since new fixtures are added without ever raising this floor. It does **not** describe what the newest fixture needs. |
+| `manifest.fixtures[].contract` | The Server IR contract **that specific fixture** requires — this is what is authoritative for what running it needs. The suite ships fixtures spanning `v1` through `v4` simultaneously, each correctly labelled. |
+| `manifest.release` | The `@cynodia/axiom` package version this snapshot of the suite shipped with — unrelated to either version above. |
+
+Before 8.2 the manifest's top-level field was named `contract` and fixed at
+`axiom.server.v1`, which read as a claim about the whole suite even after `v3`/`v4`
+fixtures were added; it is now named `baseContract` with the meaning above, precisely
+because per-fixture `contract` is what is actually authoritative. A runtime that does not
+implement a contract a fixture names should refuse that fixture rather than discover the
+mismatch mid-assertion. The files are plain JSON in a documented package directory, so a
+non-JavaScript consumer can read them straight out of the tarball without Node's module
+resolver.
 
 Every fixture is executed against the reference runtime by this repository's own test suite,
 and its expectations are exhaustive — a fixture that says which states changed must name all
@@ -573,6 +615,7 @@ of them and no others. No fixture is permitted to disagree with the shipped runt
 @cynodia/axiom-server/schema/server-ir.v1.schema.json
 @cynodia/axiom-server/schema/server-ir.v2.schema.json
 @cynodia/axiom-server/schema/server-ir.v3.schema.json
+@cynodia/axiom-server/schema/server-ir.v4.schema.json
 @cynodia/axiom-server/schema/protocol.v1.schema.json
 ```
 
@@ -592,15 +635,31 @@ page plus the conformance fixtures.
 | `axiom.server.v1` | the frozen 0.6.1 contract, below | 0.6.1 |
 | `axiom.server.v2` | the expression kinds `group` and `expression-ref`, and the `expressionDefs` they resolve against | 0.7.0 |
 | `axiom.server.v3` | integrations, integration operations, events, triggers, and the `integration-query`/`integration-effect` operation kinds | 0.8.0 |
+| `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 three. The rules:
+`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:
 
-- **A document declares the oldest contract that can carry it.** `compileToServerIR` computes the label from the vocabulary the document actually uses, so an application that uses nothing from 0.7 or 0.8 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged.
-- **A runtime MUST refuse a contract it does not implement**, and MUST refuse a document whose vocabulary exceeds its declared contract. A v2 runtime executing a v1-labelled document that uses `group` would accept what a conforming v1 runtime elsewhere refuses, and the two would then disagree about the same file. `createAxiomServer` raises rather than executing one.
-- **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref`, `expressionDefs`, an integration, a trigger, an event, or the `integration-query`/`integration-effect` operation kinds, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
+- **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.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`.
+each shipped: `server-ir.v1.schema.json`, `server-ir.v2.schema.json`, `server-ir.v3.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.1-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 |