@cynodia/axiom-agent-api 0.5.2-alpha.1 → 0.6.0-alpha.1

package/dist/presentation-queries.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, Density, DeviceClass, DiagnosticNode, FormNode, NodeId, Presentation, PresentationRole, ResolvedPresentation, ResolvedResponsive, StateDef, Theme, UINode, UxRole, ValidationIssue, ViewNode } from '@cynodia/axiom-core';
+import type { ActionDef, Authority, AuthorityContext, Density, DeviceClass, DiagnosticNode, FormNode, NodeId, Expression, Presentation, PresentationRole, ResolvedPresentation, ResolvedResponsive, StateDef, Theme, UINode, UxRole, ValidationIssue, ViewNode } from '@cynodia/axiom-core';
 import { GraphQueries } from './queries.js';
 /** One grouped part of a form, and what it contains. */
 export interface FormSectionSummary {
@@ -81,6 +81,36 @@ export declare class PresentationQueries extends GraphQueries {
      * nothing invokes has no refusal to explain.
      */
     getActionsWithoutDiagnosticPresentation(): ActionDef[];
+    /**
+     * Who may commit this state. Absent metadata means `'client'`, so a 0.5.x graph answers
+     * `'client'` for everything.
+     */
+    getAuthority(stateId: NodeId): Authority | undefined;
+    /** Where this action executes. Derived from what it writes, never declared. */
+    getActionAuthority(actionId: NodeId): Authority | undefined;
+    /** Actions the client must send to the authority rather than execute itself. */
+    getServerActions(): ActionDef[];
+    /** States a client may commit directly. */
+    getClientWritableStates(): StateDef[];
+    /** States only the authority may commit. */
+    getServerWritableStates(): StateDef[];
+    /** States the client never receives at all. */
+    getServerOnlyStates(): StateDef[];
+    /** Actions that write any server-authoritative state, with the states each touches. */
+    getActionsAffectingServerState(): Array<{
+        action: ActionDef;
+        stateIds: NodeId[];
+    }>;
+    /**
+     * The rule deciding whether a caller may invoke this action, or `undefined` when there is
+     * none — in which case every caller may.
+     */
+    getAuthorizationForAction(actionId: NodeId): Expression | undefined;
+    /** Server actions whose invocation no authorization rule restricts. */
+    getUnauthorizedServerActions(): ActionDef[];
+    /** Where a state's committed value survives. */
+    getPersistenceForState(stateId: NodeId): StateDef['persistence'];
+    protected authority(): AuthorityContext;
     /** States marked as ephemeral presentation state rather than domain facts. */
     getEphemeralStates(): StateDef[];
     /**

package/dist/presentation-queries.js

@@ -1,4 +1,5 @@
-import { isUINode, primaryChildIds, resolvePresentationMap, uiChildIds, validateGraph, } from '@cynodia/axiom-core';
+import { actionAuthority, authorityContext, isUINode, primaryChildIds, resolvePresentationMap, stateAuthority, uiChildIds, validateGraph, } from '@cynodia/axiom-core';
+import { statesWrittenBy } from '@cynodia/axiom-core';
 import { GraphQueries } from './queries.js';
 /** Diagnostic codes produced by the presentation layer. */
 const PRESENTATION_CODES = [
@@ -131,6 +132,70 @@ export class PresentationQueries extends GraphQueries {
             return canRefuse;
         });
     }
+    // -------------------------------------------------------------- authority
+    /**
+     * Who may commit this state. Absent metadata means `'client'`, so a 0.5.x graph answers
+     * `'client'` for everything.
+     */
+    getAuthority(stateId) {
+        const state = this.graph.getNode(stateId);
+        return state?.kind === 'state' ? stateAuthority(state) : undefined;
+    }
+    /** Where this action executes. Derived from what it writes, never declared. */
+    getActionAuthority(actionId) {
+        const action = this.graph.getNode(actionId);
+        return action?.kind === 'action' ? actionAuthority(action, this.authority()) : undefined;
+    }
+    /** Actions the client must send to the authority rather than execute itself. */
+    getServerActions() {
+        const context = this.authority();
+        return this.graph
+            .getNodesByKind('action')
+            .filter((action) => actionAuthority(action, context) === 'server');
+    }
+    /** States a client may commit directly. */
+    getClientWritableStates() {
+        return this.graph
+            .getNodesByKind('state')
+            .filter((state) => !state.derivation && stateAuthority(state) === 'client');
+    }
+    /** States only the authority may commit. */
+    getServerWritableStates() {
+        return this.graph
+            .getNodesByKind('state')
+            .filter((state) => !state.derivation && stateAuthority(state) === 'server');
+    }
+    /** States the client never receives at all. */
+    getServerOnlyStates() {
+        return this.graph.getNodesByKind('state').filter((state) => state.serverOnly === true);
+    }
+    /** Actions that write any server-authoritative state, with the states each touches. */
+    getActionsAffectingServerState() {
+        const context = this.authority();
+        const server = new Set(this.getServerWritableStates().map((state) => state.id));
+        return this.getServerActions().map((action) => ({
+            action,
+            stateIds: [...statesWrittenBy(action, context)].filter((id) => server.has(id)),
+        }));
+    }
+    /**
+     * The rule deciding whether a caller may invoke this action, or `undefined` when there is
+     * none — in which case every caller may.
+     */
+    getAuthorizationForAction(actionId) {
+        return this.graph.getNode(actionId)?.authorization;
+    }
+    /** Server actions whose invocation no authorization rule restricts. */
+    getUnauthorizedServerActions() {
+        return this.getServerActions().filter((action) => !action.authorization);
+    }
+    /** Where a state's committed value survives. */
+    getPersistenceForState(stateId) {
+        return this.graph.getNode(stateId)?.persistence;
+    }
+    authority() {
+        return authorityContext(this.graph.listNodes(), this.graph.principalEntityId);
+    }
     /** States marked as ephemeral presentation state rather than domain facts. */
     getEphemeralStates() {
         return this.graph.getNodesByKind('state').filter((state) => state.ephemeral === true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-agent-api",
-  "version": "0.5.2-alpha.1",
+  "version": "0.6.0-alpha.1",
   "description": "Semantic queries and transactional graph transformations for AI agents.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.5.2-alpha.1"
+    "@cynodia/axiom-core": "0.6.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",