@cynodia/axiom-server 0.6.0-alpha.1 → 0.6.2-alpha.1

package/README.md

@@ -18,16 +18,33 @@ SQLite), `TransportAdapter` (in-process and HTTP), and `ServerHost` for time, id
 and authentication. Nothing in an ApplicationGraph mentions HTTP, SQL or a route.
 
 Main exports: `createAxiomServer`, `createMemoryPersistence`, `createSqlitePersistence`,
-`createServerHost`, `createDirectTransport`, `createHttpTransport`, `createRemoteGateway`,
-`serveOverHttp`, `SERVER_DIAGNOSTIC_CODES`.
+`createServerHost`, `createDeterministicServerHost`, `createDirectTransport`,
+`createHttpTransport`, `createRemoteGateway`, `serveOverHttp`, `serveAxiomApplication`,
+`SERVER_DIAGNOSTIC_CODES`.
 
-`conformance/*.json` ships with this package: portable fixtures — a Server IR, the state to
-start from, invocations and expected results — that any conforming runtime can be held to.
+`serveAxiomApplication` is the whole deployment story: it serves the generated page at `GET /`
+and the semantic endpoint at `POST /axiom`, from one process, for any Axiom application. No
+route, controller, handler or SQL statement is written by an application author.
+
+### Portable artifacts
+
+`axiom.server.v1` is a frozen, language-independent contract, and this package ships what an
+implementation in another language needs to conform to it:
+
+```
+@cynodia/axiom-server/conformance                       the fixture manifest
+@cynodia/axiom-server/conformance/<name>.json           one fixture: IR, state, invocations, expectations
+@cynodia/axiom-server/schema/server-ir.v1.schema.json   JSON Schema for the IR
+@cynodia/axiom-server/schema/protocol.v1.schema.json    JSON Schema for the protocol
+```
+
+The fixtures are pure data. Running them requires no part of this implementation — which is
+the point: the semantic contract, the schemas and these files are the whole specification.
 
 ## Installation
 
 ```bash
-npm install @cynodia/axiom-server@alpha
+npm install @cynodia/axiom-server
 ```
 
 This package is **not** re-exported by the `@cynodia/axiom` facade, because it imports

package/conformance/authorization.json

@@ -727,6 +727,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "AUTHORIZATION_DENIED"
         ]
@@ -740,6 +741,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "AUTHORIZATION_DENIED"
         ]
@@ -753,7 +755,11 @@
         "param_stock": 1
       },
       "expect": {
-        "ok": true
+        "ok": true,
+        "changedStates": [
+          "state_parts",
+          "state_total"
+        ]
       }
     }
   ],

package/conformance/constraint-rolls-back.json

@@ -738,6 +738,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "CONSTRAINT_VIOLATION"
         ]

package/conformance/for-each-provisional.json

@@ -735,7 +735,11 @@
         ]
       },
       "expect": {
-        "ok": true
+        "ok": true,
+        "changedStates": [
+          "state_parts",
+          "state_total"
+        ]
       }
     }
   ],

package/conformance/guard-refuses.json

@@ -727,6 +727,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "PRECONDITION_FAILED"
         ],
@@ -743,6 +744,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "PRECONDITION_FAILED"
         ],

package/conformance/idempotent-retry.json

@@ -727,7 +727,12 @@
         "param_qty": 3
       },
       "expect": {
-        "ok": true
+        "ok": true,
+        "changedStates": [
+          "state_parts",
+          "state_ledger",
+          "state_total"
+        ]
       }
     },
     {
@@ -739,7 +744,12 @@
       },
       "expect": {
         "ok": true,
-        "replayed": true
+        "replayed": true,
+        "changedStates": [
+          "state_parts",
+          "state_ledger",
+          "state_total"
+        ]
       }
     }
   ],

package/conformance/manifest.json

@@ -0,0 +1,143 @@
+{
+  "conformance": "axiom.conformance.v1",
+  "contract": "axiom.server.v1",
+  "protocol": "axiom.protocol.v1",
+  "release": "0.6.2-alpha.1",
+  "description": "Portable conformance fixtures for the Axiom Server IR. Each entry is a self-contained JSON document: the Server IR, the state to start from, the principals, the invocations to perform and the results required. Running them needs no part of this implementation.",
+  "areas": [
+    "action guards",
+    "argument validation",
+    "authorization",
+    "concurrent mutation",
+    "constraints",
+    "derived state",
+    "expression evaluation",
+    "failure modes",
+    "for-each provisional writes",
+    "idempotency",
+    "mutation",
+    "persistence",
+    "restart",
+    "rollback",
+    "transition constraints"
+  ],
+  "fixtures": [
+    {
+      "name": "mutation-commits",
+      "file": "mutation-commits.json",
+      "covers": [
+        "expression evaluation",
+        "mutation",
+        "derived state"
+      ],
+      "description": "An action within its guards commits every write, and derived state follows.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 1
+    },
+    {
+      "name": "guard-refuses",
+      "file": "guard-refuses.json",
+      "covers": [
+        "action guards",
+        "failure modes"
+      ],
+      "description": "A guard that does not hold refuses the invocation, naming its failure mode.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 2
+    },
+    {
+      "name": "constraint-rolls-back",
+      "file": "constraint-rolls-back.json",
+      "covers": [
+        "constraints",
+        "rollback",
+        "for-each provisional writes"
+      ],
+      "description": "Iteration N sees the writes of iterations before it, so two lines for one part are counted together — and the invariant then rolls the whole action back.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 1
+    },
+    {
+      "name": "for-each-provisional",
+      "file": "for-each-provisional.json",
+      "covers": [
+        "for-each provisional writes"
+      ],
+      "description": "The same two-line shape, within stock: 10 − 4 − 4, not 10 − 4 twice.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 1
+    },
+    {
+      "name": "transition-constraint",
+      "file": "transition-constraint.json",
+      "covers": [
+        "transition constraints"
+      ],
+      "description": "A rule about how state may change refuses a raise, and permits a fall.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 2
+    },
+    {
+      "name": "authorization",
+      "file": "authorization.json",
+      "covers": [
+        "authorization"
+      ],
+      "description": "Authorization is evaluated on the authority, with the caller bound to PRINCIPAL.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 3
+    },
+    {
+      "name": "argument-validation",
+      "file": "argument-validation.json",
+      "covers": [
+        "argument validation"
+      ],
+      "description": "Untrusted arguments are checked against declared parameter types.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 4
+    },
+    {
+      "name": "idempotent-retry",
+      "file": "idempotent-retry.json",
+      "covers": [
+        "persistence",
+        "idempotency"
+      ],
+      "description": "A repeated request id is answered from the record, not executed again.",
+      "concurrent": false,
+      "restartAndReassert": false,
+      "invocations": 2
+    },
+    {
+      "name": "concurrent-invocations",
+      "file": "concurrent-invocations.json",
+      "covers": [
+        "concurrent mutation"
+      ],
+      "description": "Three callers each want four of a stock of five. Exactly one may commit; the rest are refused by the guard against authoritative state.",
+      "concurrent": true,
+      "restartAndReassert": false,
+      "invocations": 3
+    },
+    {
+      "name": "restart",
+      "file": "restart.json",
+      "covers": [
+        "persistence",
+        "restart"
+      ],
+      "description": "Committed state is restored exactly on restart, and a rolled-back write never reappears.",
+      "concurrent": false,
+      "restartAndReassert": true,
+      "invocations": 2
+    }
+  ]
+}

package/conformance/mutation-commits.json

@@ -730,7 +730,8 @@
         "ok": true,
         "changedStates": [
           "state_parts",
-          "state_ledger"
+          "state_ledger",
+          "state_total"
         ]
       }
     }

package/conformance/restart.json

@@ -727,7 +727,12 @@
         "param_qty": 3
       },
       "expect": {
-        "ok": true
+        "ok": true,
+        "changedStates": [
+          "state_parts",
+          "state_ledger",
+          "state_total"
+        ]
       }
     },
     {
@@ -737,7 +742,8 @@
         "param_qty": 99
       },
       "expect": {
-        "ok": false
+        "ok": false,
+        "changedStates": []
       }
     }
   ],

package/conformance/transition-constraint.json

@@ -727,6 +727,7 @@
       },
       "expect": {
         "ok": false,
+        "changedStates": [],
         "diagnosticCodes": [
           "TRANSITION_CONSTRAINT_VIOLATION"
         ]
@@ -740,7 +741,11 @@
         "param_stock": 4
       },
       "expect": {
-        "ok": true
+        "ok": true,
+        "changedStates": [
+          "state_parts",
+          "state_total"
+        ]
       }
     }
   ],

package/dist/host.d.ts

@@ -53,5 +53,22 @@ export declare function createServerHost(overrides?: Partial<ServerHost>): Serve
  * A deterministic host, for conformance runs and tests. `now` and `uuid` count rather than
  * varying, so an expected result is stable.
  */
+/**
+ * The host model the conformance suite runs against.
+ *
+ * `now()` and `uuid()` are the only two places semantics can depend on something outside the
+ * graph, so a portable fixture needs both pinned. The model is one counter, shared, starting
+ * at zero and incremented **before** each value is produced, so the nth host call in an
+ * execution — whichever of the two it is — is always the same value:
+ *
+ * ```
+ * uuid()  → "id-<n>"
+ * now()   → "2026-01-01T00:00:<n, two digits>.000Z"
+ * ```
+ *
+ * A runtime in another language reproduces this exactly by counting host calls in execution
+ * order. The counter is per host instance, and a fixture that restarts the authority keeps
+ * the same host — a restart does not rewind it.
+ */
 export declare function createDeterministicServerHost(overrides?: Partial<ServerHost>): ServerHost;
 //# sourceMappingURL=host.d.ts.map

package/dist/host.js

@@ -12,6 +12,23 @@ export function createServerHost(overrides = {}) {
  * A deterministic host, for conformance runs and tests. `now` and `uuid` count rather than
  * varying, so an expected result is stable.
  */
+/**
+ * The host model the conformance suite runs against.
+ *
+ * `now()` and `uuid()` are the only two places semantics can depend on something outside the
+ * graph, so a portable fixture needs both pinned. The model is one counter, shared, starting
+ * at zero and incremented **before** each value is produced, so the nth host call in an
+ * execution — whichever of the two it is — is always the same value:
+ *
+ * ```
+ * uuid()  → "id-<n>"
+ * now()   → "2026-01-01T00:00:<n, two digits>.000Z"
+ * ```
+ *
+ * A runtime in another language reproduces this exactly by counting host calls in execution
+ * order. The counter is per host instance, and a fixture that restarts the authority keeps
+ * the same host — a restart does not rewind it.
+ */
 export function createDeterministicServerHost(overrides = {}) {
     let counter = 0;
     return {

package/dist/node-host.d.ts

@@ -1,4 +1,7 @@
 import type { AxiomServer } from './server.js';
+import type { PrincipalRecord } from './host.js';
+import type { PersistenceAdapter } from './persistence.js';
+import type { ServerIR } from './deps.js';
 /**
  * The reference Node host.
  *
@@ -11,6 +14,11 @@ export interface NodeHostOptions {
     port?: number;
     /** The single semantic endpoint. */
     path?: string;
+    /**
+     * The generated browser page. When given, `GET /` serves it — so one process hands out
+     * the client and answers it. Omit to run a bare authority.
+     */
+    page?: string;
 }
 export interface RunningNodeHost {
     /** The port actually bound, which matters when `port: 0` was requested. */
@@ -19,4 +27,41 @@ export interface RunningNodeHost {
     close(): Promise<void>;
 }
 export declare function serveOverHttp(options: NodeHostOptions): Promise<RunningNodeHost>;
+/**
+ * One graph, one process: the generated page and the authority that answers it.
+ *
+ * This is the whole deployment story for an application with server-authoritative state.
+ * The caller supplies the two compiled artifacts — the Server IR and the page — plus how to
+ * authenticate a credential and where to keep state. It defines no route, no verb and no
+ * handler, because there are none to define: `GET /` is the page and `POST /axiom` is the
+ * semantic endpoint, for every Axiom application there will ever be.
+ *
+ * ```ts
+ * const running = await serveAxiomApplication({
+ *   serverIR: compileToServerIR(graph),
+ *   page: compileToHtml(graph),
+ *   persistence: createSqlitePersistence({ file: 'app.db' }),
+ *   authenticate: (credential) => users.get(credential ?? '') ?? null,
+ *   port: 3000,
+ * });
+ * ```
+ */
+export interface AxiomApplicationOptions {
+    serverIR: ServerIR;
+    /** The generated browser page, exactly as `compileToHtml` produced it. */
+    page: string;
+    persistence?: PersistenceAdapter;
+    /** Resolves opaque credential material to a principal record, or null for anonymous. */
+    authenticate?: (credential: string | null) => PrincipalRecord | null | Promise<PrincipalRecord | null>;
+    port?: number;
+    /** The semantic endpoint. Change it only if something else already owns `/axiom`. */
+    path?: string;
+}
+export interface RunningAxiomApplication extends RunningNodeHost {
+    /** The page's address, which is what a person opens. */
+    pageUrl: string;
+    /** The authority itself, for tests and administrative inspection. */
+    server: AxiomServer;
+}
+export declare function serveAxiomApplication(options: AxiomApplicationOptions): Promise<RunningAxiomApplication>;
 //# sourceMappingURL=node-host.d.ts.map

package/dist/node-host.js

@@ -1,5 +1,7 @@
 import { createServer } from 'node:http';
 import { dispatch } from './transport.js';
+import { createAxiomServer } from './server.js';
+import { createServerHost } from './host.js';
 const MAX_BODY_BYTES = 1024 * 1024;
 async function readBody(request) {
     const chunks = [];
@@ -22,7 +24,15 @@ export async function serveOverHttp(options) {
     await options.server.start();
     const http = createServer((request, response) => {
         void (async () => {
-            if (request.method !== 'POST' || (request.url ?? '').split('?')[0] !== path) {
+            const target = (request.url ?? '').split('?')[0];
+            if (options.page !== undefined && request.method === 'GET' && (target === '/' || target === '/index.html')) {
+                // The generated page and the endpoint it talks to, from one process. Nothing here is
+                // application-specific: every Axiom application is served by exactly this handler.
+                response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+                response.end(options.page);
+                return;
+            }
+            if (request.method !== 'POST' || target !== path) {
                 response.writeHead(404, { 'content-type': 'application/json' });
                 response.end(JSON.stringify({ kind: 'error', diagnostics: [] }));
                 return;
@@ -61,3 +71,19 @@ export async function serveOverHttp(options) {
         }),
     };
 }
+export async function serveAxiomApplication(options) {
+    const server = createAxiomServer({
+        ir: options.serverIR,
+        ...(options.persistence ? { persistence: options.persistence } : {}),
+        ...(options.authenticate
+            ? { host: createServerHost({ authenticate: options.authenticate }) }
+            : {}),
+    });
+    const running = await serveOverHttp({
+        server,
+        page: options.page,
+        ...(options.port === undefined ? {} : { port: options.port }),
+        ...(options.path === undefined ? {} : { path: options.path }),
+    });
+    return { ...running, pageUrl: `http://127.0.0.1:${running.port}/`, server };
+}

package/dist/protocol.d.ts

@@ -13,7 +13,15 @@ export interface SnapshotRequest {
     kind: 'snapshot';
     protocol: typeof PROTOCOL_VERSION;
     credential?: Credential;
-    /** When given, only states changed after this revision are returned. */
+    /**
+     * Ask for an incremental snapshot: a revision this caller already holds.
+     *
+     * The response then omits every observable state the authority can **prove** has not
+     * changed since that revision, and sets `partial`. Omission always means unchanged;
+     * inclusion never promises changed. A value that is not a non-negative safe integer is a
+     * malformed request; a value the authority cannot reason about — ahead of its own
+     * revision — is answered with a complete snapshot, which is always a valid answer.
+     */
     sinceRevision?: number;
 }
 export interface InvokeRequest {
@@ -30,10 +38,19 @@ export interface InvokeRequest {
     requestId?: string;
 }
 export type ServerRequest = SnapshotRequest | InvokeRequest;
-/** The authoritative value of every observable state the caller may see. */
+/**
+ * The authoritative value of the observable states the caller may see.
+ *
+ * Complete unless `partial` is set. A complete snapshot names every observable state; a
+ * partial one names those that may have changed since the `sinceRevision` that was asked
+ * for, and a state it does not name is unchanged since then. `revision` is the authority's
+ * current revision either way, so a client can use it as the next `sinceRevision`.
+ */
 export interface StateSnapshot {
     revision: number;
     states: Record<NodeId, unknown>;
+    /** Present and true only for the answer to a `sinceRevision` request. */
+    partial?: boolean;
 }
 export interface InvokeResponse {
     kind: 'result';

package/dist/server.d.ts

@@ -42,17 +42,5 @@ export interface AxiomServer {
     mutationLog(): MutationLogEntry[];
     stop(): Promise<void>;
 }
-/**
- * The authoritative runtime.
- *
- * It executes the **same semantic engine** the client runs, given an IR that contains no UI
- * and no routes. That is deliberate rather than convenient: transaction boundaries,
- * provisional writes, `for-each` ordering, constraint and transition evaluation, rollback
- * and the mutation log are not reimplemented here, so a graph cannot behave differently
- * merely because execution moved to the authority.
- *
- * Requests are serialized. One action runs at a time, and its persistence commit completes
- * before the next begins, so two callers cannot both commit from the same snapshot.
- */
 export declare function createAxiomServer(options: AxiomServerOptions): AxiomServer;
 //# sourceMappingURL=server.d.ts.map