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

package/README.md

@@ -5,13 +5,12 @@ framework.
 
 **Status: experimental / alpha.** The API may change between alpha releases.
 
-The machine-facing interface: semantic queries over the graph, field-level dependency
-and mutation-impact analysis, and transactional graph transformations.
+The machine-facing interface: semantic queries over the graph, field-level dependency and
+mutation-impact analysis, presentation and UX queries, and transactional graph
+transformations.
 
-Presentation and UX are queryable too — which action a view presents as primary, which
-controls are destructive, how a form is grouped, what happens on a compact display, which
-screens carry presentation warnings — and transformable: "make this form compact" is one
-semantic change, and an application-wide restyling is a single theme change.
+Main exports: `AgentAPI`, `GraphQueries`, `PresentationQueries`, `Transaction`,
+`ChangeSet`.
 
 ## Installation
 
@@ -25,6 +24,13 @@ Most applications should install the facade package instead, which re-exports th
 npm install @cynodia/axiom@alpha
 ```
 
+
+## Documentation
+
+The canonical operational contract lives in the `docs/` directory of the
+[`@cynodia/axiom`](https://www.npmjs.com/package/@cynodia/axiom) package, and in
+[the repository](https://github.com/cynodia/axiom). Start with `docs/AGENT_REFERENCE.md`.
+
 ## License
 
 MIT

package/dist/presentation-queries.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, Density, DeviceClass, 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 {
@@ -12,10 +12,18 @@ export interface FormSectionSummary {
  * The shape of a form as UX, rather than as a list of children: which parts are sections,
  * which controls are required, where the actions are and which one is primary.
  */
+/**
+ * The **declared** structure of a form: what it contains, not what is on screen right now.
+ *
+ * It is read along the primary render path, so an alternative branch — an empty template,
+ * a conditional's false branch — is not described as part of the form's structure.
+ */
 export interface FormStructure {
     formId: NodeId;
     density: Density;
     submitActionId?: NodeId;
+    /** Set when the form uses a declared `ButtonNode` as its submit control. */
+    submitButtonId?: NodeId;
     sections: FormSectionSummary[];
     /** Inputs that belong to no section. */
     ungroupedInputIds: NodeId[];
@@ -63,6 +71,46 @@ export declare class PresentationQueries extends GraphQueries {
     getFormsWithoutPrimaryAction(): FormNode[];
     /** Nodes carrying renderer-specific presentation that cannot be analyzed. */
     getOpaquePresentationNodes(): UINode[];
+    /** UI nodes that present failures from this action. */
+    getDiagnosticPresentations(actionId: NodeId): DiagnosticNode[];
+    /**
+     * Actions that can refuse but whose refusal no UI node presents.
+     *
+     * An action counts as able to refuse if it declares a guard, a precondition or a
+     * postcondition. Only actions a control actually invokes are reported, since an action
+     * 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[];
     /**
@@ -74,7 +122,14 @@ export declare class PresentationQueries extends GraphQueries {
     getFormStructure(formId: NodeId): FormStructure;
     protected presentationMap(): Record<NodeId, ResolvedPresentation>;
     protected uiNodes(): UINode[];
-    protected descendants(id: NodeId): UINode[];
+    /**
+     * UI nodes beneath this one. `primaryPathOnly` restricts the walk to the arrangement that
+     * appears when every collection has members and every condition holds, which is what
+     * "structure that is on screen together" means.
+     */
+    protected descendants(id: NodeId, options?: {
+        primaryPathOnly?: boolean;
+    }): UINode[];
     protected descendantIds(id: NodeId): NodeId[];
     private actionsWithUxRole;
 }

package/dist/presentation-queries.js

@@ -1,4 +1,5 @@
-import { isUINode, 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 = [
@@ -97,6 +98,104 @@ export class PresentationQueries extends GraphQueries {
         const resolved = this.presentationMap();
         return this.uiNodes().filter((node) => resolved[node.id]?.opaque === true);
     }
+    /** UI nodes that present failures from this action. */
+    getDiagnosticPresentations(actionId) {
+        return this.uiNodes().filter((node) => node.kind === 'diagnostic' && node.actionId === actionId);
+    }
+    /**
+     * Actions that can refuse but whose refusal no UI node presents.
+     *
+     * An action counts as able to refuse if it declares a guard, a precondition or a
+     * postcondition. Only actions a control actually invokes are reported, since an action
+     * nothing invokes has no refusal to explain.
+     */
+    getActionsWithoutDiagnosticPresentation() {
+        const invoked = new Set();
+        for (const node of this.uiNodes()) {
+            if (node.kind === 'button') {
+                invoked.add(node.actionId);
+            }
+            if (node.kind === 'form' && node.submitActionId) {
+                invoked.add(node.submitActionId);
+            }
+        }
+        const presented = new Set(this.uiNodes()
+            .filter((node) => node.kind === 'diagnostic')
+            .map((node) => node.actionId));
+        return this.graph.getNodesByKind('action').filter((action) => {
+            if (!invoked.has(action.id) || presented.has(action.id)) {
+                return false;
+            }
+            const canRefuse = (action.guards ?? []).length > 0 ||
+                (action.preconditions ?? []).length > 0 ||
+                (action.postconditions ?? []).length > 0;
+            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);
@@ -128,13 +227,20 @@ export class PresentationQueries extends GraphQueries {
         const destructiveActionIds = new Set();
         const requiredInputIds = [];
         const allInputIds = [];
-        if (form.submitActionId) {
-            primaryActionIds.add(form.submitActionId);
+        const submitButton = form.submitButtonId
+            ? this.graph.getNode(form.submitButtonId)
+            : undefined;
+        const submitActionId = form.submitActionId ??
+            (submitButton && isUINode(submitButton) && submitButton.kind === 'button'
+                ? submitButton.actionId
+                : undefined);
+        if (submitActionId) {
+            primaryActionIds.add(submitActionId);
         }
-        for (const node of this.descendants(formId)) {
+        for (const node of this.descendants(formId, { primaryPathOnly: true })) {
             const view = resolved[node.id];
             if (view?.uxRole === 'form-section') {
-                const inner = this.descendants(node.id);
+                const inner = this.descendants(node.id, { primaryPathOnly: true });
                 const inputIds = inner.filter((child) => child.kind === 'input').map((child) => child.id);
                 inputIds.forEach((id) => sectionInputs.add(id));
                 sections.push({
@@ -170,7 +276,8 @@ export class PresentationQueries extends GraphQueries {
         return {
             formId,
             density: resolved[formId]?.density ?? 'comfortable',
-            ...(form.submitActionId ? { submitActionId: form.submitActionId } : {}),
+            ...(submitActionId ? { submitActionId } : {}),
+            ...(form.submitButtonId ? { submitButtonId: form.submitButtonId } : {}),
             sections,
             ungroupedInputIds: allInputIds.filter((id) => !sectionInputs.has(id)),
             actionGroupIds,
@@ -186,7 +293,13 @@ export class PresentationQueries extends GraphQueries {
     uiNodes() {
         return this.graph.listNodes().filter((node) => isUINode(node));
     }
-    descendants(id) {
+    /**
+     * UI nodes beneath this one. `primaryPathOnly` restricts the walk to the arrangement that
+     * appears when every collection has members and every condition holds, which is what
+     * "structure that is on screen together" means.
+     */
+    descendants(id, options = {}) {
+        const children = options.primaryPathOnly ? primaryChildIds : uiChildIds;
         const found = [];
         const seen = new Set([id]);
         const visit = (current) => {
@@ -194,7 +307,7 @@ export class PresentationQueries extends GraphQueries {
             if (!node || !isUINode(node)) {
                 return;
             }
-            for (const childId of uiChildIds(node)) {
+            for (const childId of children(node)) {
                 if (seen.has(childId)) {
                     continue;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-agent-api",
-  "version": "0.5.0-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.0-alpha.1"
+    "@cynodia/axiom-core": "0.6.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",