@cynodia/axiom-agent-api 0.16.0-alpha.1 → 0.16.0-alpha.3

package/dist/capabilities.js

@@ -1,3 +1,4 @@
+import { actionOperations } from '@cynodia/axiom-core';
 import { analyzeLiveQuery } from './live-query.js';
 /**
  * Required-runtime-capability analysis (spec16 §30-31, §50-51). A graph declares no host or
@@ -65,7 +66,7 @@ export function analyzeCapabilities(graph) {
         }
     }
     for (const action of actions) {
-        const effectOps = (action.operations ?? []).filter((op) => op.kind === 'integration-effect' || op.kind === 'blob-commit' || op.kind === 'blob-delete');
+        const effectOps = actionOperations(action).filter((op) => op.kind === 'integration-effect' || op.kind === 'blob-commit' || op.kind === 'blob-delete');
         if (effectOps.length > 0) {
             require('effect-execution', `ActionDef ${action.id} creates a logical effect (${effectOps.map((op) => op.kind).join(', ')})`);
         }

package/dist/distributed.js

@@ -1,7 +1,7 @@
-import { authorityCompatibilityKey, schemaFingerprint, semanticFingerprint, } from '@cynodia/axiom-core';
+import { actionOperations, authorityCompatibilityKey, schemaFingerprint, semanticFingerprint, } from '@cynodia/axiom-core';
 const EFFECT_OP_KINDS = new Set(['integration-effect', 'blob-commit', 'blob-delete']);
 function actionsWithEffects(graph) {
-    return graph.getNodesByKind('action').filter((action) => (action.operations ?? []).some((op) => EFFECT_OP_KINDS.has(op.kind)));
+    return graph.getNodesByKind('action').filter((action) => actionOperations(action).some((op) => EFFECT_OP_KINDS.has(op.kind)));
 }
 function scheduledTriggers(graph) {
     return graph.getNodesByKind('trigger').filter((trigger) => trigger.when.kind === 'interval' || trigger.when.kind === 'delay');

package/dist/explain.js

@@ -1,3 +1,4 @@
+import { actionOperations, } from '@cynodia/axiom-core';
 import { GraphQueries } from './queries.js';
 import { analyzeAuthorization } from './authorization.js';
 import { analyzeWorkflow } from './workflow.js';
@@ -36,12 +37,12 @@ export function explainAction(graph, actionId) {
             runsQueries.push(target.id);
         }
     }
-    for (const operation of action.operations ?? []) {
+    for (const operation of actionOperations(action)) {
         if (operation.kind === 'blob-metadata' || operation.kind === 'blob-commit' || operation.kind === 'blob-delete') {
             storagesTouched.add(operation.storageId);
         }
     }
-    const nativeOperations = (action.operations ?? [])
+    const nativeOperations = actionOperations(action)
         .filter((operation) => operation.kind === 'native')
         .map((operation) => ({ implementationId: operation.implementationId, declaredEffects: operation.declaredEffects ?? [] }));
     const analysisGaps = nativeOperations
@@ -92,7 +93,7 @@ export function explainAction(graph, actionId) {
         invokedBy: { triggers: triggers.sort(), workflowSteps: workflowSteps.sort() },
         clientInvocable: queries.isClientInvocable(actionId),
         systemOnly: queries.isSystemOnly(actionId),
-        destructive: action.destructive === true || (action.operations ?? []).some((op) => op.kind === 'remove'),
+        destructive: action.destructive === true || actionOperations(action).some((op) => op.kind === 'remove'),
         analysisComplete: analysisGaps.length === 0,
         analysisGaps,
     };
@@ -169,7 +170,7 @@ export function explainGraph(graph) {
     const queryOps = authz.operations.filter((op) => op.nodeKind === 'query');
     let opaqueBoundaries = 0;
     for (const action of graph.getNodesByKind('action')) {
-        opaqueBoundaries += (action.operations ?? []).filter((op) => op.kind === 'native').length;
+        opaqueBoundaries += actionOperations(action).filter((op) => op.kind === 'native').length;
     }
     return {
         nodeCountsByKind,

package/dist/native-operations.js

@@ -1,8 +1,9 @@
+import { actionOperations, operationChildren } from '@cynodia/axiom-core';
 /** Every `NativeOperation` in the graph, with the action that contains it (spec16 §46). */
 export function listNativeOperations(graph) {
     const found = [];
     for (const action of graph.getNodesByKind('action')) {
-        for (const operation of collectNative(action.operations ?? [])) {
+        for (const operation of collectNative(actionOperations(action))) {
             found.push({
                 actionId: action.id,
                 implementationId: operation.implementationId,
@@ -22,7 +23,9 @@ function collectNative(operations) {
             found.push(operation);
         }
         else if (operation.kind === 'for-each') {
-            found.push(...collectNative(operation.operations ?? []));
+            // A valid for-each may only contain set/insert/remove (validateGraph enforces this),
+            // so this recursion only matters for an already-invalid graph — still total, never a crash.
+            found.push(...collectNative(operationChildren(operation)));
         }
     }
     return found;

package/dist/queries.js

@@ -1,4 +1,4 @@
-import { allowedInvocationSources, isClientInvocable as actionIsClientInvocable, isSystemOnlyAction, isUINode, locationFieldIds, locationRootStateId, locationSelectorFieldIds, referencedIds, } from '@cynodia/axiom-core';
+import { actionOperations, allowedInvocationSources, isClientInvocable as actionIsClientInvocable, isSystemOnlyAction, isUINode, locationFieldIds, locationRootStateId, locationSelectorFieldIds, referencedIds, } from '@cynodia/axiom-core';
 import { expressionFieldIds, queryExpressions, queryIsAggregate, queryRowEntityId, sortKeyDirection, } from '@cynodia/axiom-core';
 const READ_KINDS = ['reads', 'binds', 'derives-from'];
 const WRITE_KINDS = ['writes'];
@@ -64,7 +64,7 @@ export class GraphQueries {
     analysisGaps() {
         const gaps = [];
         for (const action of this.graph.getNodesByKind('action')) {
-            for (const operation of action.operations ?? []) {
+            for (const operation of actionOperations(action)) {
                 if (operation.kind === 'native' && (operation.declaredEffects ?? []).length === 0) {
                     gaps.push(`${action.name ?? action.id} runs the native operation "${operation.implementationId}" without declaring its effects`);
                 }
@@ -82,7 +82,7 @@ export class GraphQueries {
             if (touchesState) {
                 return true;
             }
-            return (action.operations ?? []).some((operation) => 'value' in operation && operation.value.kind === 'object'
+            return actionOperations(action).some((operation) => 'value' in operation && operation.value.kind === 'object'
                 ? operation.value.entityId === entityId
                 : false);
         });
@@ -133,7 +133,7 @@ export class GraphQueries {
         return this.graph
             .getNodesByKind('action')
             .filter((action) => action.destructive === true ||
-            (action.operations ?? []).some((operation) => operation.kind === 'remove'));
+            actionOperations(action).some((operation) => operation.kind === 'remove'));
     }
     /**
      * The neighbourhood of a node, optionally restricted to particular relationships.
@@ -657,7 +657,7 @@ export class GraphQueries {
     getActionsUsingStorage(storageId) {
         return this.graph
             .getNodesByKind('action')
-            .filter((action) => (action.operations ?? []).some((operation) => (operation.kind === 'blob-metadata' ||
+            .filter((action) => actionOperations(action).some((operation) => (operation.kind === 'blob-metadata' ||
             operation.kind === 'blob-commit' ||
             operation.kind === 'blob-delete') &&
             operation.storageId === storageId));

package/dist/tooling-conformance.js

@@ -73,6 +73,41 @@ function fixtureGraph() {
     });
     return g;
 }
+/**
+ * A self-contained entity + query + (optionally referenced) read policies, for the F3
+ * attach/detach/replace fixtures. `declarePolicies` names every `ReadPolicyDef` node to
+ * declare (both, for a "replace" scenario), independent of which one `readPolicyId` points
+ * at, so the diff reflects only the reference change, not a policy node appearing/vanishing.
+ */
+function readPolicyFixtureGraph(readPolicyId, ...declarePolicies) {
+    const g = new ApplicationGraph('ct-read-policy-graph', 'Read Policy Fixture');
+    const entityId = nodeId('read_policy_entity');
+    const identityField = fieldId('read_policy_entity_id');
+    g.addNode({
+        id: entityId,
+        kind: 'entity',
+        identityFieldId: identityField,
+        fields: [{ id: identityField, valueType: primitiveType('string'), required: true }],
+    });
+    for (const policyId of new Set([...(readPolicyId ? [readPolicyId] : []), ...declarePolicies])) {
+        g.addNode({
+            id: nodeId(policyId),
+            kind: 'read-policy',
+            entityId,
+            rowScopeId: nodeId('read_policy_row'),
+            predicate: literal(true),
+        });
+    }
+    g.addNode({
+        id: nodeId('read_policy_query'),
+        kind: 'query',
+        source: entityId,
+        rowScopeId: nodeId('read_policy_query_row'),
+        pagination: { strategy: 'offset', maxPageSize: 50 },
+        ...(readPolicyId ? { readPolicyId: nodeId(readPolicyId) } : {}),
+    });
+    return g;
+}
 export function toolingConformanceFixtures() {
     return [
         {
@@ -145,7 +180,7 @@ export function toolingConformanceFixtures() {
         {
             id: 'semantic-diff-authorization-change-is-tagged',
             category: 'semantic-diff',
-            description: 'detaching a policy from an action is classified as an authorization change',
+            description: 'detaching a policy from an action is classified as an authorization change, additive with its own kind category (spec16pt2 §40)',
             run: () => {
                 const before = fixtureGraph();
                 const after = fixtureGraph();
@@ -155,7 +190,43 @@ export function toolingConformanceFixtures() {
                 const diff = new AgentAPI(after).semanticDiff(before);
                 return diff.entries.find((e) => e.nodeId === String(A_BUMP))?.categories;
             },
-            expected: ['authorization'],
+            expected: ['semantic', 'authorization'],
+        },
+        {
+            id: 'semantic-diff-read-policy-attach-is-authorization',
+            category: 'semantic-diff',
+            description: 'spec16pt2 F3/§34-35: attaching a QueryDef.readPolicyId is classified query + authorization',
+            run: () => {
+                const before = readPolicyFixtureGraph(undefined);
+                const after = readPolicyFixtureGraph('read_policy_owner');
+                const diff = new AgentAPI(after).semanticDiff(before);
+                return diff.entries.find((e) => e.nodeId === 'read_policy_query')?.categories;
+            },
+            expected: ['query', 'authorization'],
+        },
+        {
+            id: 'semantic-diff-read-policy-detach-is-authorization',
+            category: 'semantic-diff',
+            description: 'spec16pt2 F3 exact reproduction: detaching a QueryDef.readPolicyId is classified query + authorization',
+            run: () => {
+                const before = readPolicyFixtureGraph('read_policy_owner');
+                const after = readPolicyFixtureGraph(undefined);
+                const diff = new AgentAPI(after).semanticDiff(before);
+                return diff.entries.find((e) => e.nodeId === 'read_policy_query')?.categories;
+            },
+            expected: ['query', 'authorization'],
+        },
+        {
+            id: 'semantic-diff-read-policy-replace-is-authorization',
+            category: 'semantic-diff',
+            description: 'spec16pt2 §36: replacing one read policy reference for another is classified authorization',
+            run: () => {
+                const before = readPolicyFixtureGraph('read_policy_owner', 'read_policy_other');
+                const after = readPolicyFixtureGraph('read_policy_other', 'read_policy_other');
+                const diff = new AgentAPI(after).semanticDiff(before);
+                return diff.entries.find((e) => e.nodeId === 'read_policy_query')?.categories.includes('authorization');
+            },
+            expected: true,
         },
         {
             id: 'diagnostics-unresolved-reference-is-structured',

package/dist/transaction.js

@@ -1,4 +1,4 @@
-import { ApplicationGraph, createFieldId, createNodeId, isUINode, randomHex, synchronizeEdges, validateGraph, } from '@cynodia/axiom-core';
+import { ApplicationGraph, actionOperations, createFieldId, createNodeId, isUINode, randomHex, synchronizeEdges, validateGraph, } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 export class TransactionError extends Error {
     result;
@@ -157,7 +157,10 @@ export class Transaction extends PresentationQueries {
         const updated = [];
         for (const action of this.graph.getNodesByKind('action')) {
             let changed = false;
-            const operations = (action.operations ?? []).map((operation) => {
+            // spec16pt2 §12-20: a hand-tampered or AI-generated ActionDef.operations can be
+            // malformed (non-array, or hold a malformed entry). `actionOperations` establishes
+            // both before this ever iterates, rather than assuming the declared type holds.
+            const operations = actionOperations(action).map((operation) => {
                 if (!('value' in operation) || operation.value.kind !== 'object') {
                     return operation;
                 }

package/package.json

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