@cynodia/axiom-compiler 0.5.2-alpha.1 → 0.6.1-alpha.1

package/README.md

@@ -20,13 +20,13 @@ Main exports: `compileToIR`, `compileToHtml`, `createThemeStylesheet`,
 ## Installation
 
 ```bash
-npm install @cynodia/axiom-compiler@alpha
+npm install @cynodia/axiom-compiler
 ```
 
 Most applications should install the facade package instead, which re-exports this one:
 
 ```bash
-npm install @cynodia/axiom@alpha
+npm install @cynodia/axiom
 ```
 
 

package/dist/codegen.d.ts

@@ -1,7 +1,23 @@
 import type { ApplicationGraph, ApplicationIR, Appearance } from '@cynodia/axiom-core';
 import type { CompileOptions } from './normalize.js';
+/**
+ * How a generated page reaches its authority.
+ *
+ * `true` means the standard semantic endpoint on the current origin, which is what the
+ * reference host serves — so an application with server-authoritative state needs no
+ * endpoint string and no gateway code of its own.
+ */
+export type RemoteOption = boolean | {
+    endpoint?: string;
+    timeoutMs?: number;
+};
 export interface HtmlOptions extends CompileOptions {
     title?: string;
+    /**
+     * Configure the page to talk to an authority. Omitted, it defaults to `true` whenever the
+     * IR contains a remote action, because such a page cannot work without one.
+     */
+    remote?: RemoteOption;
     /**
      * Pins the appearance of the emitted page. Omitted, the theme decides — and a theme set
      * to `system` follows the reader's own preference.

package/dist/codegen.js

@@ -21,6 +21,24 @@ export function compileIRToHtml(ir, options = {}) {
     const title = options.title ?? ir.name;
     const stylesheet = createThemeStylesheet(ir.theme);
     const appearance = options.appearance ?? (ir.theme.appearance === 'system' ? undefined : ir.theme.appearance);
+    // A page with remote actions is not usable without a gateway, so one is configured by
+    // default rather than left for an author to discover.
+    const needsRemote = (ir.remoteActionIds ?? []).length > 0;
+    const remote = options.remote ?? needsRemote;
+    const remoteConfig = remote === false
+        ? null
+        : {
+            endpoint: (remote === true ? undefined : remote.endpoint) ?? '/axiom',
+            ...(remote !== true && remote.timeoutMs !== undefined ? { timeoutMs: remote.timeoutMs } : {}),
+        };
+    const bootstrap = remoteConfig
+        ? [
+            `const __axiomRemote = createHttpRemoteGateway(${JSON.stringify(remoteConfig)});`,
+            'const __axiomApp = createAxiomRuntime({ ir: __AXIOM_IR__, rootElement: __axiomRoot, host: createBrowserHost(), remote: __axiomRemote });',
+        ]
+        : [
+            'const __axiomApp = createAxiomRuntime({ ir: __AXIOM_IR__, rootElement: __axiomRoot, host: createBrowserHost() });',
+        ];
     return [
         '<!DOCTYPE html>',
         `<html lang="en"${appearance ? ` data-axiom-appearance="${appearance}"` : ''}>`,
@@ -38,8 +56,10 @@ export function compileIRToHtml(ir, options = {}) {
         runtimeSource,
         `const __AXIOM_IR__ = ${payload};`,
         'const __axiomRoot = document.getElementById("app");',
-        'const __axiomApp = createAxiomRuntime({ ir: __AXIOM_IR__, rootElement: __axiomRoot, host: createBrowserHost() });',
+        ...bootstrap,
         'globalThis.__AXIOM_APP__ = __axiomApp;',
+        // `start()` is the whole startup sequence: it renders synchronously and then loads
+        // authoritative state when a gateway is configured.
         '__axiomApp.start();',
         '  </script>',
         '</body>',

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './normalize.js';
+export * from './server.js';
 export * from './stylesheet.js';
 export * from './codegen.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './normalize.js';
+export * from './server.js';
 export * from './stylesheet.js';
 export * from './codegen.js';

package/dist/normalize.js

@@ -1,4 +1,4 @@
-import { actionGuards, inferExpressionType, inferLocationType, itemTypeOf, locationFieldIds, locationRootStateId, resolvePresentationMap, semanticContextFromGraph, validateGraph, } from '@cynodia/axiom-core';
+import { actionAuthority, actionGuards, authorityContext, inferExpressionType, inferLocationType, itemTypeOf, locationFieldIds, locationRootStateId, referencedIds, resolvePresentationMap, semanticContextFromGraph, stateAuthority, validateGraph, } from '@cynodia/axiom-core';
 import { isUINode } from '@cynodia/axiom-core';
 export class GraphValidationError extends Error {
     problems;
@@ -43,6 +43,18 @@ export function compileToIR(graph, options = {}) {
             throw new GraphValidationError(result);
         }
     }
+    // The authority boundary decides what may cross into the client at all.
+    const authorityOf = authorityContext(graph.listNodes(), graph.principalEntityId);
+    const hiddenStateIds = new Set();
+    for (const state of authorityOf.states.values()) {
+        if (state.serverOnly) {
+            hiddenStateIds.add(state.id);
+        }
+    }
+    const remoteActionIds = [];
+    const authority = {};
+    /** Nothing that reads state the client may not observe may reach the client. */
+    const readsHiddenState = (expressions) => expressions.some((expression) => referencedIds(expression).some((id) => hiddenStateIds.has(id)));
     const nodes = {};
     const actions = {};
     const uiNodes = {};
@@ -61,10 +73,43 @@ export function compileToIR(graph, options = {}) {
             case 'entity':
                 entities.push(node);
                 break;
-            case 'state':
-                states.push(node);
+            case 'state': {
+                if (hiddenStateIds.has(node.id)) {
+                    // Server-only state is not merely unwritable here; it is absent.
+                    delete nodes[node.id];
+                    break;
+                }
+                authority[node.id] = stateAuthority(node);
+                states.push(stateAuthority(node) === 'server'
+                    ? // The authority owns the value. A seed shipped to the client would be a
+                        // second, unauthoritative source of truth.
+                        { ...node, initialValue: undefined }
+                    : node);
                 break;
+            }
             case 'action': {
+                if (actionAuthority(node, authorityOf) === 'server') {
+                    // A remote action reaches the client as its name, its parameters and nothing
+                    // else: no operations to replay, no guards to fake, no authorization to satisfy.
+                    remoteActionIds.push(node.id);
+                    const remote = {
+                        id: node.id,
+                        kind: 'action',
+                        ...(node.name ? { name: node.name } : {}),
+                        ...(node.parameters ? { parameters: node.parameters } : {}),
+                        ...(node.destructive !== undefined ? { destructive: node.destructive } : {}),
+                        ...(node.requiresConfirmation !== undefined
+                            ? { requiresConfirmation: node.requiresConfirmation }
+                            : {}),
+                        ...(node.confirmationMessage ? { confirmationMessage: node.confirmationMessage } : {}),
+                        ...(node.confirmation ? { confirmation: node.confirmation } : {}),
+                        ...(node.metadata ? { metadata: node.metadata } : {}),
+                        operations: [],
+                    };
+                    actions[node.id] = remote;
+                    nodes[node.id] = remote;
+                    break;
+                }
                 // Guards are authoring sugar: the IR carries conditions and failures aligned.
                 const guards = actionGuards(node);
                 actions[node.id] = {
@@ -76,9 +121,17 @@ export function compileToIR(graph, options = {}) {
                 break;
             }
             case 'constraint':
+                if (readsHiddenState([node.expression])) {
+                    delete nodes[node.id];
+                    break;
+                }
                 constraints.push(node);
                 break;
             case 'transition-constraint':
+                if (readsHiddenState([node.expression])) {
+                    delete nodes[node.id];
+                    break;
+                }
                 transitionConstraints.push(node);
                 break;
             case 'route':
@@ -149,11 +202,14 @@ export function compileToIR(graph, options = {}) {
         constraints,
         transitionConstraints,
         routes,
-        edges: graph.semanticEdges(),
+        // An edge naming a node the client does not receive would tell it that node exists.
+        edges: graph.semanticEdges().filter((edge) => nodes[edge.from] && nodes[edge.to]),
         locationTypes,
         locationRoots,
         locationRequired,
         repeatIdentityFields,
+        authority,
+        remoteActionIds,
         theme,
         presentation,
     };

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import type { ApplicationGraph, ServerIR } from '@cynodia/axiom-core';
+import type { CompileOptions } from './normalize.js';
+/**
+ * Compiles the authoritative half of a graph.
+ *
+ * What an authority needs is not what a client needs, and the difference is the point: the
+ * Server IR carries the rules a client must never be trusted with, and none of the UI,
+ * presentation, theme or routing that decides nothing.
+ *
+ * The result is plain JSON — deterministic, closure-free and free of anything specific to
+ * a language or host — so a conforming runtime in another language can execute it and reach
+ * the same semantic result.
+ */
+export declare function compileToServerIR(graph: ApplicationGraph, options?: CompileOptions): ServerIR;
+export declare function serializeServerIR(ir: ServerIR): string;
+/** Whether a graph has any authoritative half at all. */
+export declare function hasServerAuthority(graph: ApplicationGraph): boolean;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,90 @@
+import { SERVER_IR_CONTRACT, actionAuthority, actionGuards, authorityContext, isObservable, serverStateClosure, stateAuthority, validateGraph, } from '@cynodia/axiom-core';
+import { GraphValidationError } from './normalize.js';
+/**
+ * Compiles the authoritative half of a graph.
+ *
+ * What an authority needs is not what a client needs, and the difference is the point: the
+ * Server IR carries the rules a client must never be trusted with, and none of the UI,
+ * presentation, theme or routing that decides nothing.
+ *
+ * The result is plain JSON — deterministic, closure-free and free of anything specific to
+ * a language or host — so a conforming runtime in another language can execute it and reach
+ * the same semantic result.
+ */
+export function compileToServerIR(graph, options = {}) {
+    if (options.validate !== false) {
+        const result = validateGraph(graph);
+        if (!result.valid) {
+            throw new GraphValidationError(result);
+        }
+    }
+    const nodes = graph.listNodes();
+    const context = authorityContext(nodes, graph.principalEntityId);
+    const needed = serverStateClosure(context);
+    const entities = [];
+    const constraints = [];
+    const transitionConstraints = [];
+    for (const node of nodes) {
+        if (node.kind === 'entity') {
+            entities.push(node);
+        }
+        else if (node.kind === 'constraint') {
+            constraints.push(node);
+        }
+        else if (node.kind === 'transition-constraint') {
+            transitionConstraints.push(node);
+        }
+    }
+    const states = [];
+    const observableStateIds = [];
+    for (const state of context.states.values()) {
+        if (!needed.has(state.id)) {
+            continue;
+        }
+        states.push(state);
+        if (stateAuthority(state) === 'server' && isObservable(state)) {
+            observableStateIds.push(state.id);
+        }
+    }
+    const actions = {};
+    for (const action of context.actions.values()) {
+        if (actionAuthority(action, context) !== 'server') {
+            continue;
+        }
+        // Guards are authoring sugar in both halves: the IR carries conditions and failures
+        // aligned by position, exactly as the client IR does. An authority that read `guards`
+        // and not `preconditions` would silently not check them.
+        const guards = actionGuards(action);
+        actions[action.id] = {
+            ...action,
+            preconditions: guards.map((guard) => guard.condition),
+            failureModes: guards.map((guard) => guard.failureMode ?? { code: 'precondition-failed' }),
+        };
+    }
+    const fields = {};
+    for (const entry of graph.listFields()) {
+        fields[entry.field.id] = entry;
+    }
+    return {
+        contract: SERVER_IR_CONTRACT,
+        id: graph.id,
+        name: graph.name,
+        version: graph.version,
+        entities,
+        fields,
+        states,
+        actions,
+        constraints,
+        transitionConstraints,
+        ...(graph.principalEntityId ? { principalEntityId: graph.principalEntityId } : {}),
+        observableStateIds,
+    };
+}
+export function serializeServerIR(ir) {
+    return JSON.stringify(ir);
+}
+/** Whether a graph has any authoritative half at all. */
+export function hasServerAuthority(graph) {
+    const context = authorityContext(graph.listNodes(), graph.principalEntityId);
+    return [...context.states.values()].some((state) => stateAuthority(state) === 'server');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-compiler",
-  "version": "0.5.2-alpha.1",
+  "version": "0.6.1-alpha.1",
   "description": "Normalizes an Axiom application graph and emits a self-contained page.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,8 +31,8 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.5.2-alpha.1",
-    "@cynodia/axiom-runtime": "0.5.2-alpha.1"
+    "@cynodia/axiom-core": "0.6.1-alpha.1",
+    "@cynodia/axiom-runtime": "0.6.1-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",