@cynodia/axiom-server 0.7.0-alpha.2 → 0.8.0-alpha.1

package/README.md

@@ -14,13 +14,24 @@ A client requests semantic actions; it never sends operations. Authorization, gu
 argument validation are evaluated here and nowhere else.
 
 Adapters keep the semantics free of infrastructure: `PersistenceAdapter` (in-memory and
-SQLite), `TransportAdapter` (in-process and HTTP), and `ServerHost` for time, identifiers
-and authentication. Nothing in an ApplicationGraph mentions HTTP, SQL or a route.
+SQLite), `TransportAdapter` (in-process and HTTP), `ServerHost` for time, identifiers,
+scheduling and authentication, and `IntegrationAdapter` for external systems. Nothing in
+an ApplicationGraph mentions HTTP, SQL, a route or an SDK.
+
+As of 0.8 this package also owns timed and event-driven execution: it schedules and
+dispatches `TriggerDef`s, records `integration-effect` intent atomically with the state
+write that requested it (the transactional outbox), dispatches an effect's committed
+intents to its `IntegrationAdapter` post-commit with retry, and translates verified
+webhook deliveries into semantic events. See
+[`docs/INTEGRATIONS.md`](https://github.com/cynodia/axiom/blob/main/docs/INTEGRATIONS.md),
+[`docs/EFFECTS.md`](https://github.com/cynodia/axiom/blob/main/docs/EFFECTS.md) and
+[`docs/TRIGGERS.md`](https://github.com/cynodia/axiom/blob/main/docs/TRIGGERS.md).
 
 Main exports: `createAxiomServer`, `createMemoryPersistence`, `createSqlitePersistence`,
 `createServerHost`, `createDeterministicServerHost`, `createDirectTransport`,
 `createHttpTransport`, `createRemoteGateway`, `serveOverHttp`, `serveAxiomApplication`,
-`SERVER_DIAGNOSTIC_CODES`.
+`createFakeIntegrationAdapter`, `createHttpIntegrationAdapter`, `createTriggerRuntime`,
+`createEffectRunner`, `SERVER_DIAGNOSTIC_CODES`.
 
 `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
@@ -34,7 +45,9 @@ 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/server-ir.v1.schema.json   JSON Schema for the frozen v1 IR
+@cynodia/axiom-server/schema/server-ir.v2.schema.json   JSON Schema for v2 (+ group, expression-ref)
+@cynodia/axiom-server/schema/server-ir.v3.schema.json   JSON Schema for v3 (+ integrations, effects, triggers, events)
 @cynodia/axiom-server/schema/protocol.v1.schema.json    JSON Schema for the protocol
 ```
 

package/conformance/manifest.json

@@ -2,7 +2,7 @@
   "conformance": "axiom.conformance.v1",
   "contract": "axiom.server.v1",
   "protocol": "axiom.protocol.v1",
-  "release": "0.7.0-alpha.2",
+  "release": "0.8.0-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",

package/dist/deps.d.ts

@@ -5,7 +5,7 @@
  * 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 type { ActionDef, AnyNode, ApplicationIR, Authority, ConstraintDef, EntityDef, EventDef, Expression, FieldDef, FieldId, IntegrationDef, IntegrationOperationDef, LiteralValue, NodeId, ServerIR, StateDef, TransitionConstraintDef, TriggerDef, TriggerSpec, TypeRef, } from '@cynodia/axiom-core';
+export type { ActionOutcome, ActionResult, EffectIntentRecord, 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/effects.d.ts

@@ -0,0 +1,31 @@
+import type { IntegrationOperationDef, NodeId } from './deps.js';
+import type { ServerHost } from './host.js';
+import type { IntegrationAdapterRegistry } from './integration.js';
+import type { EffectRecord, PersistenceAdapter } from './persistence.js';
+export interface EffectRunnerOptions {
+    adapters: IntegrationAdapterRegistry;
+    integrationOperations: Record<NodeId, IntegrationOperationDef>;
+    persistence: PersistenceAdapter;
+    host: ServerHost;
+    /** Called once an effect reaches `succeeded` or `failed`, to dispatch its declared event. */
+    onTerminal(record: EffectRecord): Promise<void>;
+    report?(event: {
+        kind: 'effect-attempted' | 'effect-succeeded' | 'effect-failed';
+        effectId: string;
+        operationId: NodeId;
+        attempt: number;
+    }): void;
+}
+/**
+ * Dispatches committed effect intents to their integration adapter, post-commit and never
+ * awaited by the invoking request (spec §17,123). Delivery is at-least-once: a retry
+ * policy governs how many attempts a failed effect gets, and every attempt — including the
+ * first — updates durable status through `persistence.recordEffectAttempt`, so a restart
+ * resumes from wherever dispatch left off rather than losing the intent (spec §19,20,96).
+ */
+export interface EffectRunner {
+    /** Dispatches freshly committed effect intents. Fire-and-forget from the caller's view. */
+    dispatch(records: EffectRecord[]): void;
+}
+export declare function createEffectRunner(options: EffectRunnerOptions): EffectRunner;
+//# sourceMappingURL=effects.d.ts.map

package/dist/effects.js

@@ -0,0 +1,83 @@
+function delay(host, ms) {
+    return new Promise((resolve) => {
+        host.scheduleOnce(ms, resolve);
+    });
+}
+export function createEffectRunner(options) {
+    const { adapters, integrationOperations, persistence, host, onTerminal, report } = options;
+    async function run(record) {
+        const operation = integrationOperations[record.operationId];
+        if (!operation) {
+            const failed = {
+                ...record,
+                status: 'failed',
+                lastError: { code: 'UNKNOWN_INTEGRATION_OPERATION', message: `No integration operation ${record.operationId}` },
+            };
+            await persistence.recordEffectAttempt?.(record.id, failed);
+            await onTerminal(failed);
+            return;
+        }
+        const adapter = adapters[operation.integrationId];
+        if (!adapter) {
+            const failed = {
+                ...record,
+                status: 'failed',
+                lastError: { code: 'INTEGRATION_ADAPTER_MISSING', message: `No adapter registered for ${operation.integrationId}` },
+            };
+            await persistence.recordEffectAttempt?.(record.id, failed);
+            await onTerminal(failed);
+            return;
+        }
+        const policy = operation.retry ?? { policy: 'none' };
+        const maxAttempts = policy.policy === 'none' ? 1 : (policy.maxAttempts ?? 3);
+        // Deliberately local to this dispatch, not seeded from `record.attempts`: a record
+        // found `'running'` at startup means a previous process called the adapter and was
+        // never told the outcome (spec §96) — that attempt is unaccounted for, not spent, so
+        // resuming it gets a full fresh budget rather than silently going idle at zero
+        // remaining attempts. `record.attempts` is still carried forward into what gets
+        // persisted, so the historical count across a restart stays honest.
+        let attempt = 0;
+        while (attempt < maxAttempts) {
+            attempt += 1;
+            const persistedAttempts = record.attempts + attempt;
+            await persistence.recordEffectAttempt?.(record.id, { status: 'running', attempts: persistedAttempts });
+            report?.({ kind: 'effect-attempted', effectId: record.id, operationId: record.operationId, attempt: persistedAttempts });
+            const result = await adapter.effect(operation, record.arguments, record.idempotencyKey ? { idempotencyKey: record.idempotencyKey } : {});
+            if (result.ok) {
+                const succeeded = {
+                    ...record,
+                    status: 'succeeded',
+                    attempts: persistedAttempts,
+                    result: result.value,
+                };
+                await persistence.recordEffectAttempt?.(record.id, {
+                    status: 'succeeded',
+                    attempts: persistedAttempts,
+                    result: result.value,
+                });
+                report?.({ kind: 'effect-succeeded', effectId: record.id, operationId: record.operationId, attempt: persistedAttempts });
+                await onTerminal(succeeded);
+                return;
+            }
+            const lastError = { code: result.code, message: result.message, retryable: result.retryable };
+            const exhausted = attempt >= maxAttempts || result.retryable === false;
+            if (exhausted) {
+                const failed = { ...record, status: 'failed', attempts: persistedAttempts, lastError };
+                await persistence.recordEffectAttempt?.(record.id, { status: 'failed', attempts: persistedAttempts, lastError });
+                report?.({ kind: 'effect-failed', effectId: record.id, operationId: record.operationId, attempt: persistedAttempts });
+                await onTerminal(failed);
+                return;
+            }
+            const base = policy.delayMs ?? 1000;
+            const waitMs = policy.policy === 'exponential' ? base * 2 ** (attempt - 1) : base;
+            await delay(host, waitMs);
+        }
+    }
+    return {
+        dispatch(records) {
+            for (const record of records) {
+                void run(record);
+            }
+        },
+    };
+}

package/dist/host.d.ts

@@ -11,10 +11,17 @@ export interface ExecutionContext {
     /** The credential the caller presented, for host-level logging. Never semantic. */
     credential?: Credential;
     requestId?: string;
+    /**
+     * `'system'` for a trigger- or event-originated invocation, which never authenticates a
+     * credential (spec §68) — `principal` is `null` exactly as an anonymous client request's
+     * is, so authorization still evaluates and cannot be silently bypassed (spec §69,104).
+     * Absent, or `'client'`, for an ordinary client request.
+     */
+    source?: 'client' | 'system';
 }
 /** What the authoritative runtime records about an execution, for observability. */
 export interface ServerEvent {
-    kind: 'invoke' | 'snapshot' | 'reject' | 'conflict' | 'replay';
+    kind: 'invoke' | 'snapshot' | 'reject' | 'conflict' | 'replay' | 'trigger-fired' | 'trigger-skipped-overlap' | 'trigger-invocation-failed' | 'effect-requested' | 'effect-attempted' | 'effect-succeeded' | 'effect-failed' | 'event-received' | 'event-dispatched';
     actionId?: NodeId;
     /** The principal's identity field, when the graph declares one. Never the whole record. */
     principal?: LiteralValue;
@@ -26,6 +33,14 @@ export interface ServerEvent {
     diagnostics?: RuntimeDiagnostic[];
     /** States the transaction committed. */
     committed?: NodeId[];
+    /** Set for `trigger-*` and `effect-*` events. */
+    triggerId?: NodeId;
+    /** Set for `effect-*` events. */
+    effectId?: string;
+    operationId?: NodeId;
+    attempt?: number;
+    /** Set for `event-*` events. */
+    eventId?: NodeId;
 }
 /**
  * Everything the authoritative runtime needs from its environment.
@@ -33,6 +48,10 @@ export interface ServerEvent {
  * 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.
  */
+/** A cancellable scheduled callback, returned by `ServerHost.schedule`/`scheduleOnce`. */
+export interface ScheduledTask {
+    cancel(): void;
+}
 export interface ServerHost {
     now(): string;
     uuid(): string;
@@ -46,8 +65,16 @@ export interface ServerHost {
     authenticate?(credential: Credential): Promise<PrincipalRecord | null> | PrincipalRecord | null;
     /** Structured execution information. An application implements no logging of its own. */
     report?(event: ServerEvent): void;
+    /**
+     * Calls `callback` every `everyMs`, for an interval trigger. The runtime never sees a
+     * timer handle, a `Promise` or a Node API — only this call, so time stays a host
+     * capability rather than an accident of implementation (spec §84).
+     */
+    schedule(everyMs: number, callback: () => void): ScheduledTask;
+    /** Calls `callback` once, after `delayMs` — a one-shot delay trigger. */
+    scheduleOnce(delayMs: number, callback: () => void): ScheduledTask;
 }
-/** A host backed by real time and real identifiers, with no authentication. */
+/** A host backed by real time, real identifiers and real timers, 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
@@ -70,5 +97,15 @@ export declare function createServerHost(overrides?: Partial<ServerHost>): Serve
  * 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;
+/**
+ * A deterministic host that also owns a virtual clock: `advance(ms)` moves time forward
+ * and synchronously fires every timer that becomes due, re-scheduling intervals — the test
+ * clock spec §85/§141 require, so a trigger's interval/delay semantics are verifiable
+ * without an actual wait.
+ */
+export interface DeterministicServerHost extends ServerHost {
+    /** Moves virtual time forward by `ms`, firing every timer that becomes due in order. */
+    advance(ms: number): void;
+}
+export declare function createDeterministicServerHost(overrides?: Partial<ServerHost>): DeterministicServerHost;
 //# sourceMappingURL=host.d.ts.map

package/dist/host.js

@@ -1,36 +1,36 @@
-/** A host backed by real time and real identifiers, with no authentication. */
+/** A host backed by real time, real identifiers and real timers, 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)}`,
+        schedule: (everyMs, callback) => {
+            const handle = setInterval(callback, everyMs);
+            return { cancel: () => clearInterval(handle) };
+        },
+        scheduleOnce: (delayMs, callback) => {
+            const handle = setTimeout(callback, delayMs);
+            return { cancel: () => clearTimeout(handle) };
+        },
         ...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;
+    let virtualNow = 0;
+    let nextTimerId = 0;
+    const timers = new Map();
+    function schedule(everyMs, callback) {
+        const id = nextTimerId++;
+        timers.set(id, { dueAt: virtualNow + everyMs, everyMs, callback, cancelled: false });
+        return { cancel: () => timers.delete(id) };
+    }
+    function scheduleOnce(delayMs, callback) {
+        const id = nextTimerId++;
+        timers.set(id, { dueAt: virtualNow + delayMs, callback, cancelled: false });
+        return { cancel: () => timers.delete(id) };
+    }
     return {
         now: () => {
             counter += 1;
@@ -40,6 +40,36 @@ export function createDeterministicServerHost(overrides = {}) {
             counter += 1;
             return `id-${counter}`;
         },
+        schedule,
+        scheduleOnce,
+        advance(ms) {
+            const target = virtualNow + ms;
+            // Firing order is due-time order, so two timers that both become due in this advance
+            // still run in the order they would have on a real clock.
+            while (true) {
+                let next;
+                for (const [id, entry] of timers) {
+                    if (entry.cancelled || entry.dueAt > target) {
+                        continue;
+                    }
+                    if (!next || entry.dueAt < next.entry.dueAt) {
+                        next = { id, entry };
+                    }
+                }
+                if (!next) {
+                    break;
+                }
+                virtualNow = next.entry.dueAt;
+                if (next.entry.everyMs !== undefined) {
+                    next.entry.dueAt += next.entry.everyMs;
+                }
+                else {
+                    timers.delete(next.id);
+                }
+                next.entry.callback();
+            }
+            virtualNow = target;
+        },
         ...overrides,
     };
 }

package/dist/index.d.ts

@@ -12,6 +12,9 @@ export * from './protocol.js';
 export * from './persistence.js';
 export * from './sqlite-persistence.js';
 export * from './host.js';
+export * from './integration.js';
+export * from './effects.js';
+export * from './triggers.js';
 export * from './server.js';
 export * from './transport.js';
 export * from './node-host.js';

package/dist/index.js

@@ -3,6 +3,9 @@ export * from './protocol.js';
 export * from './persistence.js';
 export * from './sqlite-persistence.js';
 export * from './host.js';
+export * from './integration.js';
+export * from './effects.js';
+export * from './triggers.js';
 export * from './server.js';
 export * from './transport.js';
 export * from './node-host.js';

package/dist/integration.d.ts

@@ -0,0 +1,55 @@
+import type { IntegrationOperationDef, NodeId } from './deps.js';
+export interface IntegrationSuccess {
+    ok: true;
+    value: unknown;
+}
+export interface IntegrationFailure {
+    ok: false;
+    code: string;
+    message: string;
+    /** Whether a retry might succeed. Absent means the adapter could not determine it. */
+    retryable?: boolean;
+}
+export type IntegrationResult = IntegrationSuccess | IntegrationFailure;
+/**
+ * Translates a semantic integration operation into provider-specific execution.
+ *
+ * The graph declares the operation's shape; this is where the SDK, the HTTP client, the
+ * credentials and the provider-specific error translation live (spec §28,29) — none of it
+ * ever reaches an `ApplicationGraph`.
+ */
+export interface IntegrationAdapter {
+    query(operation: IntegrationOperationDef, args: Record<string, unknown>, context: {
+        timeoutMs?: number;
+    }): Promise<IntegrationResult>;
+    effect(operation: IntegrationOperationDef, args: Record<string, unknown>, context: {
+        idempotencyKey?: string;
+    }): Promise<IntegrationResult>;
+}
+export type IntegrationAdapterRegistry = Record<NodeId, IntegrationAdapter>;
+/**
+ * Deterministic canned results, for tests and conformance fixtures — semantics must not
+ * depend on a real network call (spec §107).
+ */
+export declare function createFakeIntegrationAdapter(options: {
+    query?(operation: IntegrationOperationDef, args: Record<string, unknown>): IntegrationResult | Promise<IntegrationResult>;
+    effect?(operation: IntegrationOperationDef, args: Record<string, unknown>): IntegrationResult | Promise<IntegrationResult>;
+}): IntegrationAdapter;
+export interface HttpIntegrationOperationConfig {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** A path template, `{paramName}` substituted from the operation's arguments. */
+    path: string;
+    /** Argument keys sent as the JSON body. Absent sends every argument not used in the path. */
+    bodyFields?: string[];
+}
+/**
+ * A generic HTTP adapter, sufficient to prove query/effect/timeout/typed-response/error
+ * mapping over an arbitrary REST service (spec §106) — a lower-level mechanism, not the
+ * canonical integration model (spec §30,31).
+ */
+export declare function createHttpIntegrationAdapter(options: {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    operations: Record<string, HttpIntegrationOperationConfig>;
+}): IntegrationAdapter;
+//# sourceMappingURL=integration.d.ts.map

package/dist/integration.js

@@ -0,0 +1,83 @@
+/**
+ * Deterministic canned results, for tests and conformance fixtures — semantics must not
+ * depend on a real network call (spec §107).
+ */
+export function createFakeIntegrationAdapter(options) {
+    return {
+        async query(operation, args) {
+            if (!options.query) {
+                return { ok: false, code: 'NOT_IMPLEMENTED', message: `No fake query behaviour registered for ${operation.id}` };
+            }
+            return options.query(operation, args);
+        },
+        async effect(operation, args) {
+            if (!options.effect) {
+                return { ok: false, code: 'NOT_IMPLEMENTED', message: `No fake effect behaviour registered for ${operation.id}` };
+            }
+            return options.effect(operation, args);
+        },
+    };
+}
+/**
+ * A generic HTTP adapter, sufficient to prove query/effect/timeout/typed-response/error
+ * mapping over an arbitrary REST service (spec §106) — a lower-level mechanism, not the
+ * canonical integration model (spec §30,31).
+ */
+export function createHttpIntegrationAdapter(options) {
+    async function call(operation, args, timeoutMs) {
+        const config = options.operations[String(operation.id)];
+        if (!config) {
+            return {
+                ok: false,
+                code: 'INTEGRATION_OPERATION_UNCONFIGURED',
+                message: `No HTTP mapping configured for ${operation.id}`,
+            };
+        }
+        const path = config.path.replace(/\{(\w+)\}/g, (_match, key) => encodeURIComponent(String(args[key] ?? '')));
+        const url = new URL(path.replace(/^\//, ''), options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`);
+        const pathKeys = new Set([...config.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]));
+        const bodyKeys = config.bodyFields ?? Object.keys(args).filter((key) => !pathKeys.has(key));
+        const body = {};
+        for (const key of bodyKeys) {
+            body[key] = args[key];
+        }
+        const controller = new AbortController();
+        const timer = timeoutMs !== undefined ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+        try {
+            const response = await fetch(url, {
+                method: config.method,
+                headers: { 'content-type': 'application/json', ...(options.headers ?? {}) },
+                ...(config.method === 'GET' ? {} : { body: JSON.stringify(body) }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    code: `HTTP_${response.status}`,
+                    message: `${config.method} ${url.pathname} returned ${response.status}`,
+                    retryable: response.status >= 500,
+                };
+            }
+            const value = response.status === 204 ? null : await response.json();
+            return { ok: true, value };
+        }
+        catch (error) {
+            const timedOut = error instanceof Error && error.name === 'AbortError';
+            return {
+                ok: false,
+                code: timedOut ? 'INTEGRATION_TIMEOUT' : 'INTEGRATION_UNAVAILABLE',
+                message: error instanceof Error ? error.message : String(error),
+                retryable: true,
+            };
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    return {
+        query: (operation, args, context) => call(operation, args, context.timeoutMs),
+        effect: (operation, args) => call(operation, args, undefined),
+    };
+}

package/dist/node-host.d.ts

@@ -1,7 +1,39 @@
 import type { AxiomServer } from './server.js';
 import type { PrincipalRecord } from './host.js';
 import type { PersistenceAdapter } from './persistence.js';
-import type { ServerIR } from './deps.js';
+import type { NodeId, ServerIR } from './deps.js';
+/**
+ * What a webhook handler gets to verify and decode a delivery: the raw, unparsed request —
+ * signature verification runs over the exact bytes a provider signed, not a re-serialized
+ * JSON parse of them.
+ */
+export interface WebhookRequestInfo {
+    headers: Record<string, string | string[] | undefined>;
+    rawBody: Buffer;
+}
+/**
+ * A registered webhook route: provider-specific verification and decoding, kept entirely
+ * out of application semantics (spec §52-55). `verify` runs first — an unverified request
+ * never reaches `decode`, and no `EventRequest` is ever constructed for it (spec §53).
+ */
+export interface WebhookConfig {
+    verify(request: WebhookRequestInfo): boolean | Promise<boolean>;
+    /**
+     * Translates a verified provider payload into a typed Axiom event. `deliveryId`, when the
+     * provider supplies one, is what a bounded recent-deliveries window dedupes on (spec
+     * §56,99) — a duplicate delivery within that window is acknowledged without dispatching
+     * the event again. There is no claim of durable, unbounded deduplication.
+     */
+    decode(request: WebhookRequestInfo): {
+        eventId: NodeId;
+        payload: unknown;
+        deliveryId?: string;
+    } | Promise<{
+        eventId: NodeId;
+        payload: unknown;
+        deliveryId?: string;
+    }>;
+}
 /**
  * The reference Node host.
  *
@@ -19,6 +51,13 @@ export interface NodeHostOptions {
      * the client and answers it. Omit to run a bare authority.
      */
     page?: string;
+    /**
+     * Webhook routes, keyed by the URL path a provider posts to (e.g. `/webhooks/stripe`).
+     * An application author never declares an HTTP route (spec §54); this is the one place
+     * a deployment registers one, and only to translate provider deliveries into semantic
+     * events — the graph never mentions it.
+     */
+    webhooks?: Record<string, WebhookConfig>;
 }
 export interface RunningNodeHost {
     /** The port actually bound, which matters when `port: 0` was requested. */