@cynodia/axiom-runtime 0.9.0-alpha.2 → 0.11.0-alpha.1

package/dist/dom.d.ts

@@ -96,5 +96,12 @@ export interface HostEnvironment {
      * server-only.
      */
     readBlobMetadata?(storageId: string, key: string): Promise<IntegrationQueryOutcome>;
+    /**
+     * Runs a registered `QueryDef` by id and returns its result, for a `query` operation
+     * inside an action (spec 0.10 §40). Resolved before the transaction opens, exactly like
+     * `queryIntegration`. Only the authoritative runtime implements it — a `query` operation
+     * makes its action server-authority, so no client-compiled action ever contains one.
+     */
+    runQuery?(queryId: string, args: Record<string, unknown>): Promise<IntegrationQueryOutcome>;
 }
 //# sourceMappingURL=dom.d.ts.map

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
 export * from './remote.js';
+export * from './query-state.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
 export * from './remote.js';
+export * from './query-state.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/mutation/mutation-engine.js

@@ -49,6 +49,12 @@ export function createMutationEngine(options) {
                     return { affectedStates: [resolved.rootStateId], affectedLocations: [resolved.path] };
                 }
                 case 'remove': {
+                    if (operation.target.kind === 'provider-record') {
+                        // The authority rewrites a provider-record target to a `collection-item` over a
+                        // staging collection before this engine runs (spec 0.10 §38). Reaching here
+                        // means that rewrite did not happen.
+                        throw new Error('A provider-record remove target is authority-only');
+                    }
                     const collection = resolveLocation(operation.target.collection, scope, runtime);
                     const current = collection.read();
                     const items = Array.isArray(current) ? current : [];

package/dist/mutation/resolve-location.js

@@ -42,6 +42,12 @@ function toPath(location, scope, runtime) {
                 };
             return { rootStateId: parent.rootStateId, segments: [...parent.segments, segment] };
         }
+        case 'provider-record':
+            // A `provider-record` location addresses canonical data that no `StateDef` holds. The
+            // authority rewrites it to a `collection-item` over an in-transaction staging state
+            // before this engine ever sees it (spec 0.10 §38); reaching here means that rewrite
+            // did not happen — a client runtime, which holds no data provider.
+            throw new Error(`A provider-record location cannot be resolved without a data provider; it is authority-only`);
         default:
             throw new Error(`Unknown location kind "${location.kind}"`);
     }

package/dist/query-state.d.ts

@@ -0,0 +1,79 @@
+import type { NodeId, RuntimeDiagnostic } from './runtime-types.js';
+import type { RemoteQueryRequest, RemoteQueryResult } from './remote.js';
+/**
+ * The canonical client-side lifecycle of a demand-driven read (spec 0.10 §57-60, §76).
+ *
+ * An application never maintains four booleans per list. It reads one `QueryView`:
+ *
+ * ```
+ * idle ──load──▶ loading ──ok──▶ ready ──refresh/loadMore──▶ refreshing ──ok──▶ ready
+ *                   │              ▲                              │
+ *                   │ fail         └──────────── ok ──────────────┘
+ *                   ▼                                             │ fail
+ *                 error ◀────────────── fail (data kept) ─────────┘
+ * ```
+ *
+ * The two failure edges differ, deliberately (spec §58, §60):
+ *
+ * - a **first load** that fails goes to `error` with **no data** — the caller can tell
+ *   "loading" from "ready with zero rows";
+ * - a **refresh** that fails goes to `error` but **keeps the last successful data** visible,
+ *   so a transient failure never flashes the UI empty.
+ */
+export type QueryLifecycleState = 'idle' | 'loading' | 'ready' | 'refreshing' | 'error';
+export declare const QUERY_LIFECYCLE_STATES: readonly QueryLifecycleState[];
+export interface QueryPageData {
+    items: Array<Record<string, unknown>>;
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+export interface QueryAggregateData {
+    rows: Array<{
+        key?: unknown[];
+        values: Record<string, unknown>;
+    }>;
+}
+export interface QueryView {
+    status: QueryLifecycleState;
+    /** The rows of a row query — the last **successful** result, kept across a failed refresh. */
+    page?: QueryPageData;
+    /** The rows of an aggregate query. */
+    aggregate?: QueryAggregateData;
+    /** The diagnostic from the most recent failure, cleared on the next success. */
+    diagnostic?: RuntimeDiagnostic;
+    /** Convenience: `status === 'refreshing'` — data is visible but a fetch is in flight. */
+    readonly refreshing: boolean;
+    /** Convenience: there is a successful result to show, whatever the status. */
+    readonly hasData: boolean;
+}
+/** The parameters that identify one active query — its id and its arguments. */
+export interface QueryKey {
+    queryId: NodeId;
+    arguments?: Record<string, unknown>;
+}
+export type QueryFetcher = (request: RemoteQueryRequest) => Promise<RemoteQueryResult>;
+/**
+ * Holds the `QueryView` for every active query and drives the transitions. It performs no
+ * I/O itself — a `QueryFetcher` (normally the remote gateway's `query`) does that — so it
+ * is testable without a transport and reusable by any client runtime.
+ */
+export interface QueryStore {
+    /** The current view for a key. Returns the shared idle view for a key never loaded. */
+    get(key: QueryKey): QueryView;
+    /** First load (or a re-load of an errored key). No-op if already loading/ready/refreshing. */
+    load(key: QueryKey, options?: {
+        pageSize?: number;
+    }): Promise<QueryView>;
+    /** Re-fetch page one, keeping the current data visible while it runs (spec §59). */
+    refresh(key: QueryKey, options?: {
+        pageSize?: number;
+    }): Promise<QueryView>;
+    /** Fetch and append the next page. Only meaningful for a `ready` row query with `hasMore`. */
+    loadMore(key: QueryKey): Promise<QueryView>;
+    /** Drop a key's state entirely, back to `idle`. */
+    reset(key: QueryKey): void;
+    /** Notified after every transition, with the key that changed. */
+    subscribe(listener: (key: QueryKey) => void): () => void;
+}
+export declare function createQueryStore(fetcher: QueryFetcher): QueryStore;
+//# sourceMappingURL=query-state.d.ts.map

package/dist/query-state.js

@@ -0,0 +1,120 @@
+export const QUERY_LIFECYCLE_STATES = [
+    'idle',
+    'loading',
+    'ready',
+    'refreshing',
+    'error',
+];
+function keyString(key) {
+    return `${String(key.queryId)}::${JSON.stringify(key.arguments ?? {})}`;
+}
+function decorate(base) {
+    return {
+        ...base,
+        get refreshing() {
+            return base.status === 'refreshing';
+        },
+        get hasData() {
+            return base.page !== undefined || base.aggregate !== undefined;
+        },
+    };
+}
+const IDLE = decorate({ status: 'idle' });
+export function createQueryStore(fetcher) {
+    const views = new Map();
+    const listeners = new Set();
+    const set = (key, view) => {
+        views.set(keyString(key), view);
+        for (const listener of listeners) {
+            listener(key);
+        }
+        return view;
+    };
+    const current = (key) => views.get(keyString(key)) ?? IDLE;
+    async function fetchInto(key, starting, request, onSuccess) {
+        const previous = current(key);
+        set(key, decorate({
+            status: starting,
+            ...(previous.page ? { page: previous.page } : {}),
+            ...(previous.aggregate ? { aggregate: previous.aggregate } : {}),
+        }));
+        let result;
+        try {
+            result = await fetcher(request);
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                diagnostics: [
+                    {
+                        code: 'AUTHORITY_UNREACHABLE',
+                        message: error instanceof Error ? error.message : String(error),
+                        severity: 'error',
+                    },
+                ],
+                revision: 0,
+            };
+        }
+        if (!result.ok) {
+            // A failed first load keeps nothing; a failed refresh keeps the last good data.
+            return set(key, decorate({
+                status: 'error',
+                ...(starting === 'refreshing' && previous.page ? { page: previous.page } : {}),
+                ...(starting === 'refreshing' && previous.aggregate ? { aggregate: previous.aggregate } : {}),
+                ...(result.diagnostics[0] ? { diagnostic: result.diagnostics[0] } : {}),
+            }));
+        }
+        return set(key, onSuccess(previous, result));
+    }
+    return {
+        get: current,
+        load(key, options) {
+            const status = current(key).status;
+            if (status === 'loading' || status === 'ready' || status === 'refreshing') {
+                return Promise.resolve(current(key));
+            }
+            return fetchInto(key, 'loading', { queryId: key.queryId, arguments: key.arguments, ...(options?.pageSize ? { pageSize: options.pageSize } : {}) }, (_previous, result) => readyView(result));
+        },
+        refresh(key, options) {
+            const previous = current(key);
+            const starting = previous.hasData ? 'refreshing' : 'loading';
+            return fetchInto(key, starting, { queryId: key.queryId, arguments: key.arguments, ...(options?.pageSize ? { pageSize: options.pageSize } : {}) }, (_previous, result) => readyView(result));
+        },
+        loadMore(key) {
+            const previous = current(key);
+            if (previous.status !== 'ready' || !previous.page?.hasMore || !previous.page.nextCursor) {
+                return Promise.resolve(previous);
+            }
+            return fetchInto(key, 'refreshing', { queryId: key.queryId, arguments: key.arguments, cursor: previous.page.nextCursor }, (prev, result) => {
+                if (!result.page) {
+                    return readyView(result);
+                }
+                return decorate({
+                    status: 'ready',
+                    page: {
+                        items: [...(prev.page?.items ?? []), ...result.page.items],
+                        nextCursor: result.page.nextCursor,
+                        hasMore: result.page.hasMore,
+                    },
+                });
+            });
+        },
+        reset(key) {
+            views.delete(keyString(key));
+            for (const listener of listeners) {
+                listener(key);
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function readyView(result) {
+    return decorate({
+        status: 'ready',
+        ...(result.page ? { page: result.page } : {}),
+        ...(result.aggregate ? { aggregate: result.aggregate } : {}),
+    });
+}

package/dist/remote.d.ts

@@ -23,6 +23,30 @@ export interface HttpRemoteGatewayOptions {
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
 }
+/** What a client hands the gateway to run a registered query (spec 0.10 §54). */
+export interface RemoteQueryRequest {
+    queryId: NodeId;
+    arguments?: Record<string, unknown>;
+    cursor?: string;
+    pageSize?: number;
+    offset?: number;
+}
+export interface RemoteQueryResult {
+    ok: boolean;
+    diagnostics: RuntimeDiagnostic[];
+    page?: {
+        items: Array<Record<string, unknown>>;
+        nextCursor: string | null;
+        hasMore: boolean;
+    };
+    aggregate?: {
+        rows: Array<{
+            key?: unknown[];
+            values: Record<string, unknown>;
+        }>;
+    };
+    revision: number;
+}
 /**
  * Builds the gateway a client runtime is configured with.
  *
@@ -44,6 +68,7 @@ export declare function createHttpRemoteGateway(options?: HttpRemoteGatewayOptio
         diagnostics: RuntimeDiagnostic[];
         changes: Record<NodeId, unknown>;
     }>;
+    query(request: RemoteQueryRequest): Promise<RemoteQueryResult>;
     snapshot(): Promise<{
         states: Record<NodeId, unknown>;
     }>;

package/dist/remote.js

@@ -88,6 +88,35 @@ export function createHttpRemoteGateway(options = {}) {
                 };
             }
         },
+        async query(request) {
+            try {
+                const answer = await send({
+                    kind: 'query',
+                    queryId: request.queryId,
+                    ...(request.arguments ? { arguments: request.arguments } : {}),
+                    ...(request.cursor ? { cursor: request.cursor } : {}),
+                    ...(request.pageSize !== undefined ? { pageSize: request.pageSize } : {}),
+                    ...(request.offset !== undefined ? { offset: request.offset } : {}),
+                });
+                if (answer.kind === 'query-result') {
+                    return {
+                        ok: answer.ok === true,
+                        diagnostics: answer.diagnostics ?? [],
+                        ...(answer.page ? { page: answer.page } : {}),
+                        ...(answer.aggregate ? { aggregate: answer.aggregate } : {}),
+                        revision: answer.revision ?? 0,
+                    };
+                }
+                return { ok: false, diagnostics: answer.diagnostics ?? [], revision: 0 };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    diagnostics: [unreachable(error instanceof Error ? error.message : String(error))],
+                    revision: 0,
+                };
+            }
+        },
         async snapshot() {
             // A failed snapshot must reject: `start()` distinguishes "not loaded" from "empty",
             // and swallowing the failure here would erase that difference.

package/dist/runtime.d.ts

@@ -48,6 +48,10 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly BLOB_STORAGE_UNAVAILABLE: "BLOB_STORAGE_UNAVAILABLE";
     /** A `blob-metadata` lookup failed: no such key, a staged object, or the store refused. */
     readonly BLOB_METADATA_FAILED: "BLOB_METADATA_FAILED";
+    /** A `query` operation ran where no data provider is reachable — a client runtime, or a server with none registered. */
+    readonly QUERY_RESOLVER_UNAVAILABLE: "QUERY_RESOLVER_UNAVAILABLE";
+    /** A `query` operation's registered query failed to execute. Never carries a provider secret. */
+    readonly QUERY_OPERATION_FAILED: "QUERY_OPERATION_FAILED";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
 /**

package/dist/runtime.js

@@ -52,6 +52,10 @@ export const RUNTIME_DIAGNOSTIC_CODES = {
     BLOB_STORAGE_UNAVAILABLE: 'BLOB_STORAGE_UNAVAILABLE',
     /** A `blob-metadata` lookup failed: no such key, a staged object, or the store refused. */
     BLOB_METADATA_FAILED: 'BLOB_METADATA_FAILED',
+    /** A `query` operation ran where no data provider is reachable — a client runtime, or a server with none registered. */
+    QUERY_RESOLVER_UNAVAILABLE: 'QUERY_RESOLVER_UNAVAILABLE',
+    /** A `query` operation's registered query failed to execute. Never carries a provider secret. */
+    QUERY_OPERATION_FAILED: 'QUERY_OPERATION_FAILED',
 };
 const MISSING = Symbol('missing');
 function unwrapType(type) {
@@ -737,6 +741,20 @@ export function createAxiomRuntime(options) {
                 return toText(values[0]).toLowerCase();
             case 'to-string':
                 return toText(values[0]);
+            case 'trim':
+                return toText(values[0]).trim();
+            case 'substring-before': {
+                const text = toText(values[0]);
+                const separator = toText(values[1]);
+                const index = separator === '' ? -1 : text.indexOf(separator);
+                return index < 0 ? text : text.slice(0, index);
+            }
+            case 'substring-after': {
+                const text = toText(values[0]);
+                const separator = toText(values[1]);
+                const index = separator === '' ? -1 : text.indexOf(separator);
+                return index < 0 ? '' : text.slice(index + separator.length);
+            }
             case 'now':
                 return host.now();
             case 'uuid':
@@ -1088,6 +1106,7 @@ export function createAxiomRuntime(options) {
             }
             case 'integration-query':
             case 'blob-metadata':
+            case 'query':
                 // The result was already resolved and bound into the action's scope before this
                 // transaction opened — see `runActionAsync`. Nothing to do here; this case exists
                 // only so the kind is recognized rather than falling to `default`.
@@ -1294,7 +1313,9 @@ export function createAxiomRuntime(options) {
         });
     }
     function actionHasAsyncQuery(action) {
-        return (action.operations ?? []).some((operation) => operation.kind === 'integration-query' || operation.kind === 'blob-metadata');
+        return (action.operations ?? []).some((operation) => operation.kind === 'integration-query' ||
+            operation.kind === 'blob-metadata' ||
+            operation.kind === 'query');
     }
     /**
      * Resolves every top-level `integration-query` operation before the transaction opens,
@@ -1365,6 +1386,49 @@ export function createAxiomRuntime(options) {
                 presetBindings.set(operation.bindAs, blobOutcome.value);
                 continue;
             }
+            if (operation.kind === 'query') {
+                // A registered query, resolved before the transaction — the same pre-transaction
+                // phase `integration-query` occupies, and for the same reason: its result may inform
+                // the mutations that follow, but running it is not a pure expression.
+                const queryArgs = {};
+                for (const [key, argument] of Object.entries(operation.arguments ?? {})) {
+                    queryArgs[key] = evaluate(argument, scope);
+                }
+                let queryOutcome;
+                try {
+                    queryOutcome = await host.runQuery?.(String(operation.queryId), queryArgs);
+                }
+                catch (error) {
+                    queryOutcome = {
+                        ok: false,
+                        code: RUNTIME_DIAGNOSTIC_CODES.QUERY_OPERATION_FAILED,
+                        message: error instanceof Error ? error.message : String(error),
+                    };
+                }
+                if (!queryOutcome) {
+                    return failWith({
+                        code: RUNTIME_DIAGNOSTIC_CODES.QUERY_RESOLVER_UNAVAILABLE,
+                        message: `${action.name ?? action.id} runs a query, but no data provider is reachable here`,
+                        severity: 'error',
+                        nodeId: action.id,
+                        actionId: action.id,
+                        details: { queryId: String(operation.queryId) },
+                    });
+                }
+                if (!queryOutcome.ok) {
+                    return failWith({
+                        code: RUNTIME_DIAGNOSTIC_CODES.QUERY_OPERATION_FAILED,
+                        message: queryOutcome.message,
+                        severity: 'error',
+                        nodeId: action.id,
+                        actionId: action.id,
+                        details: { queryId: String(operation.queryId), code: queryOutcome.code },
+                    });
+                }
+                scope.values.set(operation.bindAs, queryOutcome.value);
+                presetBindings.set(operation.bindAs, queryOutcome.value);
+                continue;
+            }
             if (operation.kind !== 'integration-query') {
                 continue;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.9.0-alpha.2",
+  "version": "0.11.0-alpha.1",
   "description": "Domain-independent runtime that executes an Axiom application graph.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.9.0-alpha.2"
+    "@cynodia/axiom-core": "0.11.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",