@cynodia/axiom-agent-api 0.5.0-alpha.1 → 0.5.2-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, Density, DeviceClass, DiagnosticNode, FormNode, NodeId, 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,16 @@ 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[];
     /** States marked as ephemeral presentation state rather than domain facts. */
     getEphemeralStates(): StateDef[];
     /**
@@ -74,7 +92,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,4 @@
-import { isUINode, resolvePresentationMap, uiChildIds, validateGraph, } from '@cynodia/axiom-core';
+import { isUINode, primaryChildIds, resolvePresentationMap, uiChildIds, validateGraph, } from '@cynodia/axiom-core';
 import { GraphQueries } from './queries.js';
 /** Diagnostic codes produced by the presentation layer. */
 const PRESENTATION_CODES = [
@@ -97,6 +97,40 @@ 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;
+        });
+    }
     /** States marked as ephemeral presentation state rather than domain facts. */
     getEphemeralStates() {
         return this.graph.getNodesByKind('state').filter((state) => state.ephemeral === true);
@@ -128,13 +162,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 +211,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 +228,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 +242,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.5.2-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.5.2-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",