@cynodia/axiom-server 0.6.0-alpha.1

package/dist/deps.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Everything this package uses from the rest of Axiom, re-exported through one module.
+ *
+ * Keeping the imports in one place makes the dependency surface of the authoritative
+ * runtime explicit: it is the semantic engine and nothing else. No transport, no database
+ * driver and no host API appears here.
+ */
+export type { ActionDef, AnyNode, ApplicationIR, Authority, ConstraintDef, EntityDef, Expression, FieldDef, FieldId, LiteralValue, NodeId, ServerIR, StateDef, TransitionConstraintDef, TypeRef, } from '@cynodia/axiom-core';
+export type { ActionOutcome, ActionResult, RuntimeDiagnostic, RuntimeDiagnosticCode, } from '@cynodia/axiom-runtime';
+export { PRINCIPAL, RUNTIME_DIAGNOSTIC_CODES, SERVER_IR_CONTRACT } from './runtime-deps.js';
+//# sourceMappingURL=deps.d.ts.map

package/dist/deps.js

@@ -0,0 +1 @@
+export { PRINCIPAL, RUNTIME_DIAGNOSTIC_CODES, SERVER_IR_CONTRACT } from './runtime-deps.js';

package/dist/host.d.ts

@@ -0,0 +1,57 @@
+import type { FieldId, LiteralValue, NodeId, RuntimeDiagnostic } from './deps.js';
+import type { Credential } from './protocol.js';
+/**
+ * A caller, as the authority sees it: a record keyed by the field ids of the graph's
+ * principal entity. It is never application state — it describes who is asking.
+ */
+export type PrincipalRecord = Record<FieldId, LiteralValue>;
+export interface ExecutionContext {
+    /** The resolved caller, or `null` for an anonymous request. */
+    principal: PrincipalRecord | null;
+    /** The credential the caller presented, for host-level logging. Never semantic. */
+    credential?: Credential;
+    requestId?: string;
+}
+/** What the authoritative runtime records about an execution, for observability. */
+export interface ServerEvent {
+    kind: 'invoke' | 'snapshot' | 'reject' | 'conflict' | 'replay';
+    actionId?: NodeId;
+    /** The principal's identity field, when the graph declares one. Never the whole record. */
+    principal?: LiteralValue;
+    requestId?: string;
+    ok?: boolean;
+    /** Milliseconds spent in the authoritative runtime. */
+    durationMs?: number;
+    revision?: number;
+    diagnostics?: RuntimeDiagnostic[];
+    /** States the transaction committed. */
+    committed?: NodeId[];
+}
+/**
+ * Everything the authoritative runtime needs from its environment.
+ *
+ * The semantic engine reads nothing from globals, exactly as the client runtime does not.
+ * No transport, no database driver and no host API appears in the semantics.
+ */
+export interface ServerHost {
+    now(): string;
+    uuid(): string;
+    /**
+     * Resolves an opaque credential to a caller. Returning `null` means anonymous, which an
+     * authorization rule may still accept or refuse.
+     *
+     * This is authentication, and it is deliberately the host's business. Axiom 0.6 provides
+     * no authentication provider of its own.
+     */
+    authenticate?(credential: Credential): Promise<PrincipalRecord | null> | PrincipalRecord | null;
+    /** Structured execution information. An application implements no logging of its own. */
+    report?(event: ServerEvent): void;
+}
+/** A host backed by real time and real identifiers, with no authentication. */
+export declare function createServerHost(overrides?: Partial<ServerHost>): ServerHost;
+/**
+ * A deterministic host, for conformance runs and tests. `now` and `uuid` count rather than
+ * varying, so an expected result is stable.
+ */
+export declare function createDeterministicServerHost(overrides?: Partial<ServerHost>): ServerHost;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.js

@@ -0,0 +1,28 @@
+/** A host backed by real time and real identifiers, with no authentication. */
+export function createServerHost(overrides = {}) {
+    return {
+        now: () => new Date().toISOString(),
+        uuid: () => typeof globalThis.crypto?.randomUUID === 'function'
+            ? globalThis.crypto.randomUUID()
+            : `id-${Date.now().toString(16)}-${Math.floor(Math.random() * 1e9).toString(16)}`,
+        ...overrides,
+    };
+}
+/**
+ * A deterministic host, for conformance runs and tests. `now` and `uuid` count rather than
+ * varying, so an expected result is stable.
+ */
+export function createDeterministicServerHost(overrides = {}) {
+    let counter = 0;
+    return {
+        now: () => {
+            counter += 1;
+            return `2026-01-01T00:00:${String(counter).padStart(2, '0')}.000Z`;
+        },
+        uuid: () => {
+            counter += 1;
+            return `id-${counter}`;
+        },
+        ...overrides,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The authoritative half of Axiom.
+ *
+ * A client requests semantic actions; this executes them against state it owns, with the
+ * same semantic engine and therefore the same transaction guarantees. HTTP, SQLite and
+ * Node are implementation details of the adapters here — none of them appears in an
+ * ApplicationGraph.
+ */
+export type { ServerIR, ServerIRContract } from '@cynodia/axiom-core';
+export { SERVER_IR_CONTRACT, PRINCIPAL } from '@cynodia/axiom-core';
+export * from './protocol.js';
+export * from './persistence.js';
+export * from './sqlite-persistence.js';
+export * from './host.js';
+export * from './server.js';
+export * from './transport.js';
+export * from './node-host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export { SERVER_IR_CONTRACT, PRINCIPAL } from '@cynodia/axiom-core';
+export * from './protocol.js';
+export * from './persistence.js';
+export * from './sqlite-persistence.js';
+export * from './host.js';
+export * from './server.js';
+export * from './transport.js';
+export * from './node-host.js';

package/dist/node-host.d.ts

@@ -0,0 +1,22 @@
+import type { AxiomServer } from './server.js';
+/**
+ * The reference Node host.
+ *
+ * It is infrastructure, not semantics: it reads a body, hands it to the authority, and
+ * writes the answer back. There is one endpoint, and it is the same endpoint for every
+ * application — no application declares a route, a verb or a handler.
+ */
+export interface NodeHostOptions {
+    server: AxiomServer;
+    port?: number;
+    /** The single semantic endpoint. */
+    path?: string;
+}
+export interface RunningNodeHost {
+    /** The port actually bound, which matters when `port: 0` was requested. */
+    port: number;
+    url: string;
+    close(): Promise<void>;
+}
+export declare function serveOverHttp(options: NodeHostOptions): Promise<RunningNodeHost>;
+//# sourceMappingURL=node-host.d.ts.map

package/dist/node-host.js

@@ -0,0 +1,63 @@
+import { createServer } from 'node:http';
+import { dispatch } from './transport.js';
+const MAX_BODY_BYTES = 1024 * 1024;
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES) {
+            throw new Error('Request body is too large');
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        return null;
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export async function serveOverHttp(options) {
+    const path = options.path ?? '/axiom';
+    await options.server.start();
+    const http = createServer((request, response) => {
+        void (async () => {
+            if (request.method !== 'POST' || (request.url ?? '').split('?')[0] !== path) {
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ kind: 'error', diagnostics: [] }));
+                return;
+            }
+            try {
+                const answer = await dispatch(options.server, await readBody(request));
+                const body = JSON.stringify(answer);
+                response.writeHead(200, { 'content-type': 'application/json' });
+                response.end(body);
+            }
+            catch (error) {
+                response.writeHead(400, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({
+                    kind: 'error',
+                    diagnostics: [
+                        {
+                            code: 'MALFORMED_REQUEST',
+                            message: error instanceof Error ? error.message : String(error),
+                            severity: 'error',
+                        },
+                    ],
+                }));
+            }
+        })();
+    });
+    await new Promise((resolve) => {
+        http.listen(options.port ?? 0, '127.0.0.1', resolve);
+    });
+    const address = http.address();
+    const port = typeof address === 'object' && address ? address.port : (options.port ?? 0);
+    return {
+        port,
+        url: `http://127.0.0.1:${port}${path}`,
+        close: () => new Promise((resolve, reject) => {
+            http.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}

package/dist/persistence.d.ts

@@ -0,0 +1,58 @@
+import type { NodeId } from './deps.js';
+/**
+ * Where committed authoritative state survives.
+ *
+ * The contract is deliberately narrow, and deliberately **atomic**: a semantic Axiom
+ * transaction that writes several states must persist as one unit. It must never be
+ * possible to find an order inserted and one of its two stock debits missing, because that
+ * is one transaction.
+ *
+ * No SQL, no schema and no query language appears in an ApplicationGraph or in this
+ * interface. An adapter stores serialized semantic values against state ids; projecting
+ * them onto a relational schema is deliberately future work.
+ */
+export interface PersistedState {
+    stateId: NodeId;
+    value: unknown;
+    /** Incremented on every committed write to this state. */
+    revision: number;
+}
+export interface PersistenceCommit {
+    /** The states this transaction writes, with the values it proposes. */
+    writes: Array<{
+        stateId: NodeId;
+        value: unknown;
+    }>;
+    /**
+     * The revision each written state had when the transaction began. A mismatch means
+     * something else committed in between, and the commit MUST be refused rather than
+     * overwrite it.
+     */
+    expected: Record<NodeId, number>;
+}
+export interface CommitOutcome {
+    committed: boolean;
+    /** The new revision of the store when committed. */
+    revision: number;
+    /** States whose revision no longer matched, when refused. */
+    conflicts: NodeId[];
+}
+export interface PersistenceAdapter {
+    /** Everything committed so far. Called once, when the authority starts. */
+    load(): Promise<PersistedState[]>;
+    /**
+     * Applies a whole transaction, or none of it. An adapter MUST NOT apply a subset, and
+     * MUST refuse when any expected revision no longer matches.
+     */
+    commit(commit: PersistenceCommit): Promise<CommitOutcome>;
+    /** The current store revision, for conflict detection and observation. */
+    revision(): Promise<number>;
+    close?(): Promise<void>;
+}
+/**
+ * In-memory persistence. It implements the complete authoritative transaction model — the
+ * atomicity and the revision check included — so a conformance run or a test exercises the
+ * same semantics a durable adapter does, deterministically and without a filesystem.
+ */
+export declare function createMemoryPersistence(seed?: PersistedState[]): PersistenceAdapter;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.js

@@ -0,0 +1,38 @@
+/**
+ * In-memory persistence. It implements the complete authoritative transaction model — the
+ * atomicity and the revision check included — so a conformance run or a test exercises the
+ * same semantics a durable adapter does, deterministically and without a filesystem.
+ */
+export function createMemoryPersistence(seed = []) {
+    const values = new Map();
+    for (const entry of seed) {
+        values.set(entry.stateId, { ...entry, value: structuredClone(entry.value) });
+    }
+    let revision = seed.reduce((highest, entry) => Math.max(highest, entry.revision), 0);
+    return {
+        async load() {
+            return [...values.values()].map((entry) => ({ ...entry, value: structuredClone(entry.value) }));
+        },
+        async commit(commit) {
+            const conflicts = commit.writes
+                .map((write) => write.stateId)
+                .filter((stateId) => (values.get(stateId)?.revision ?? 0) !== (commit.expected[stateId] ?? 0));
+            if (conflicts.length > 0) {
+                return { committed: false, revision, conflicts };
+            }
+            // Nothing is written until every expectation has held: all of it, or none.
+            revision += 1;
+            for (const write of commit.writes) {
+                values.set(write.stateId, {
+                    stateId: write.stateId,
+                    value: structuredClone(write.value),
+                    revision,
+                });
+            }
+            return { committed: true, revision, conflicts: [] };
+        },
+        async revision() {
+            return revision;
+        },
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,72 @@
+import type { NodeId, RuntimeDiagnostic } from './deps.js';
+/**
+ * The semantic protocol between a client runtime and an authority.
+ *
+ * A client requests **semantic operations** — "invoke action X with arguments Y" — never a
+ * mutation program. The authority resolves the action from its own IR and decides. Nothing
+ * here mentions HTTP, and nothing in an ApplicationGraph mentions a route or a verb.
+ */
+export declare const PROTOCOL_VERSION = "axiom.protocol.v1";
+/** Opaque credential material. The host, not the semantic runtime, interprets it. */
+export type Credential = string | null;
+export interface SnapshotRequest {
+    kind: 'snapshot';
+    protocol: typeof PROTOCOL_VERSION;
+    credential?: Credential;
+    /** When given, only states changed after this revision are returned. */
+    sinceRevision?: number;
+}
+export interface InvokeRequest {
+    kind: 'invoke';
+    protocol: typeof PROTOCOL_VERSION;
+    actionId: NodeId;
+    /** Keyed by action parameter id. Untyped input: the authority validates it. */
+    arguments?: Record<string, unknown>;
+    credential?: Credential;
+    /**
+     * A caller-chosen key that makes a retry safe. The authority returns the recorded
+     * response for a key it has already executed rather than executing again.
+     */
+    requestId?: string;
+}
+export type ServerRequest = SnapshotRequest | InvokeRequest;
+/** The authoritative value of every observable state the caller may see. */
+export interface StateSnapshot {
+    revision: number;
+    states: Record<NodeId, unknown>;
+}
+export interface InvokeResponse {
+    kind: 'result';
+    protocol: typeof PROTOCOL_VERSION;
+    ok: boolean;
+    /** Axiom diagnostics, unchanged: the same codes and details a local failure produces. */
+    diagnostics: RuntimeDiagnostic[];
+    /** Authoritative values after the transaction settled, for the states it touched. */
+    changes: Record<NodeId, unknown>;
+    revision: number;
+    requestId?: string;
+    /** True when this response was replayed for a repeated `requestId`. */
+    replayed?: boolean;
+}
+export interface SnapshotResponse {
+    kind: 'snapshot';
+    protocol: typeof PROTOCOL_VERSION;
+    snapshot: StateSnapshot;
+}
+/** A failure of the boundary itself, rather than of an application rule. */
+export interface ErrorResponse {
+    kind: 'error';
+    protocol: typeof PROTOCOL_VERSION;
+    diagnostics: RuntimeDiagnostic[];
+}
+export type ServerResponse = InvokeResponse | SnapshotResponse | ErrorResponse;
+/**
+ * How a client reaches an authority. The first implementation is in-process and the second
+ * is HTTP; neither is visible to application semantics, so a later WebSocket, worker or IPC
+ * transport changes nothing in a graph.
+ */
+export interface TransportAdapter {
+    send(request: ServerRequest): Promise<ServerResponse>;
+}
+export declare function isServerRequest(value: unknown): value is ServerRequest;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,16 @@
+/**
+ * The semantic protocol between a client runtime and an authority.
+ *
+ * A client requests **semantic operations** — "invoke action X with arguments Y" — never a
+ * mutation program. The authority resolves the action from its own IR and decides. Nothing
+ * here mentions HTTP, and nothing in an ApplicationGraph mentions a route or a verb.
+ */
+export const PROTOCOL_VERSION = 'axiom.protocol.v1';
+export function isServerRequest(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.protocol === PROTOCOL_VERSION &&
+        (candidate.kind === 'invoke' || candidate.kind === 'snapshot'));
+}

package/dist/runtime-deps.d.ts

@@ -0,0 +1,3 @@
+export { PRINCIPAL, SERVER_IR_CONTRACT } from '@cynodia/axiom-core';
+export { RUNTIME_DIAGNOSTIC_CODES } from '@cynodia/axiom-runtime';
+//# sourceMappingURL=runtime-deps.d.ts.map

package/dist/runtime-deps.js

@@ -0,0 +1,2 @@
+export { PRINCIPAL, SERVER_IR_CONTRACT } from '@cynodia/axiom-core';
+export { RUNTIME_DIAGNOSTIC_CODES } from '@cynodia/axiom-runtime';

package/dist/server.d.ts

@@ -0,0 +1,58 @@
+import type { NodeId, ServerIR } from '@cynodia/axiom-core';
+import type { MutationLogEntry } from '@cynodia/axiom-runtime';
+import type { PersistenceAdapter } from './persistence.js';
+import type { ServerHost } from './host.js';
+import type { ServerRequest, ServerResponse, StateSnapshot } from './protocol.js';
+/**
+ * Diagnostic codes the authority adds to the runtime vocabulary. They describe failures of
+ * the boundary, not of an application rule.
+ */
+export declare const SERVER_DIAGNOSTIC_CODES: {
+    /** The request named an action this authority does not execute. */
+    readonly UNKNOWN_SERVER_ACTION: "UNKNOWN_SERVER_ACTION";
+    /** An argument did not conform to its declared parameter type. */
+    readonly ARGUMENT_TYPE_MISMATCH: "ARGUMENT_TYPE_MISMATCH";
+    /** The caller may not invoke this action. */
+    readonly AUTHORIZATION_DENIED: "AUTHORIZATION_DENIED";
+    /** Another transaction committed the same state first; nothing was applied. */
+    readonly CONCURRENCY_CONFLICT: "CONCURRENCY_CONFLICT";
+    /** The request itself was malformed, or spoke an unknown protocol. */
+    readonly MALFORMED_REQUEST: "MALFORMED_REQUEST";
+    /** The authority could not be reached, or did not answer. */
+    readonly AUTHORITY_UNREACHABLE: "AUTHORITY_UNREACHABLE";
+};
+export type ServerDiagnosticCode = (typeof SERVER_DIAGNOSTIC_CODES)[keyof typeof SERVER_DIAGNOSTIC_CODES];
+export interface AxiomServerOptions {
+    ir: ServerIR;
+    persistence?: PersistenceAdapter;
+    host?: ServerHost;
+    /** How many request ids to remember for idempotent retries. */
+    idempotencyWindow?: number;
+}
+export interface AxiomServer {
+    /** Loads committed state. Must complete before any request is handled. */
+    start(): Promise<void>;
+    /** The one entry point. Every transport funnels through here. */
+    handle(request: ServerRequest): Promise<ServerResponse>;
+    /** Authoritative values of every observable state. */
+    snapshot(): StateSnapshot;
+    getState(id: NodeId): unknown;
+    revision(): number;
+    /** Every mutation this authority has applied, with its outcome. */
+    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