@cynodia/axiom-agent-api 0.3.1-alpha.1 → 0.4.1-alpha.1

package/dist/queries.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, Expression, FieldId, FormNode, GraphEdge, Location, NodeId, StateDef, UINode, ViewNode } from '@cynodia/axiom-core';
+import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, Expression, FieldId, FormNode, GraphEdge, Location, NodeId, StateDef, TransitionConstraintDef, UINode, ViewNode } from '@cynodia/axiom-core';
 export interface SubgraphRequest {
     root: NodeId;
     depth?: number;
@@ -16,7 +16,17 @@ export interface MutationImpact {
     directWriters: AnyNode[];
     dependentDerivedStates: StateDef[];
     affectedConstraints: ConstraintDef[];
+    /** Rules that govern how this state may change, whatever writes it. */
+    affectedTransitionConstraints: TransitionConstraintDef[];
     affectedViews: ViewNode[];
+    /**
+     * False when something in the graph cannot be analyzed — a native operation that does
+     * not declare its effects, for instance. An incomplete answer says so rather than
+     * presenting itself as exhaustive.
+     */
+    analysisComplete: boolean;
+    /** Why the analysis is incomplete, when it is. */
+    analysisGaps: string[];
 }
 export declare class GraphQueries {
     protected graph: ApplicationGraph;
@@ -33,6 +43,15 @@ export declare class GraphQueries {
     /** States whose value type mentions the entity. */
     getStatesForEntity(entityId: NodeId): StateDef[];
     getConstraintsForEntity(entityId: NodeId): ConstraintDef[];
+    /** Rules governing how instances of this entity may change. */
+    getTransitionConstraintsForEntity(entityId: NodeId): TransitionConstraintDef[];
+    /** Every rule that protects a location, whichever path attempts the write. */
+    getRulesProtecting(location: Location): {
+        constraints: ConstraintDef[];
+        transitionConstraints: TransitionConstraintDef[];
+    };
+    /** Parts of the graph whose reads and writes cannot be derived. */
+    private analysisGaps;
     /** Actions that write a state holding the entity, or that construct instances of it. */
     getActionsForEntity(entityId: NodeId): ActionDef[];
     /** Every UI node that binds or displays one of the entity's fields. */

package/dist/queries.js

@@ -45,6 +45,32 @@ export class GraphQueries {
     getConstraintsForEntity(entityId) {
         return this.graph.getNodesByKind('constraint').filter((constraint) => constraint.entityId === entityId);
     }
+    /** Rules governing how instances of this entity may change. */
+    getTransitionConstraintsForEntity(entityId) {
+        return this.graph
+            .getNodesByKind('transition-constraint')
+            .filter((constraint) => constraint.entityId === entityId);
+    }
+    /** Every rule that protects a location, whichever path attempts the write. */
+    getRulesProtecting(location) {
+        const impact = this.getMutationImpact(location);
+        return {
+            constraints: impact.affectedConstraints,
+            transitionConstraints: impact.affectedTransitionConstraints,
+        };
+    }
+    /** Parts of the graph whose reads and writes cannot be derived. */
+    analysisGaps() {
+        const gaps = [];
+        for (const action of this.graph.getNodesByKind('action')) {
+            for (const operation of action.operations ?? []) {
+                if (operation.kind === 'native' && (operation.declaredEffects ?? []).length === 0) {
+                    gaps.push(`${action.name ?? action.id} runs the native operation "${operation.implementationId}" without declaring its effects`);
+                }
+            }
+        }
+        return gaps;
+    }
     /** Actions that write a state holding the entity, or that construct instances of it. */
     getActionsForEntity(entityId) {
         const stateIds = new Set(this.getStatesForEntity(entityId).map((state) => state.id));
@@ -203,6 +229,10 @@ export class GraphQueries {
                 views.set(view.id, view);
             }
         }
+        const affectedTransitionConstraints = this.graph
+            .getNodesByKind('transition-constraint')
+            .filter((constraint) => entityIds.has(constraint.entityId));
+        const gaps = this.analysisGaps();
         return {
             location,
             rootStateId,
@@ -210,7 +240,10 @@ export class GraphQueries {
             directWriters,
             dependentDerivedStates,
             affectedConstraints,
+            affectedTransitionConstraints,
             affectedViews: [...views.values()],
+            analysisComplete: gaps.length === 0,
+            analysisGaps: gaps,
         };
     }
     constraintTouches(constraint, fieldIds) {
@@ -245,7 +278,8 @@ export class GraphQueries {
     }
     nodesWithFieldEdge(fieldId, kinds) {
         const found = new Map();
-        for (const edge of this.graph.listEdges()) {
+        // Derived relationships, so an answer never depends on edges having been written.
+        for (const edge of this.graph.semanticEdges()) {
             if (!kinds.includes(edge.kind) || !edgeFieldIds(edge).includes(fieldId)) {
                 continue;
             }

package/package.json

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