@cynodia/axiom-agent-api 0.12.0-alpha.1 → 0.13.0-alpha.1

package/dist/api.d.ts

@@ -4,6 +4,7 @@ import { Transaction } from './transaction.js';
 import type { ChangeSet } from './changes.js';
 import type { MigrationImpact, SchemaInspection } from './migration.js';
 import type { DistributedSemanticsInspection } from './distributed.js';
+import type { LiveQueryAnalysis } from './live-query.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -42,5 +43,13 @@ export declare class AgentAPI extends PresentationQueries {
      * `inspectDistributedWork()`.
      */
     inspectDistributedSemantics(serverContract?: string): DistributedSemanticsInspection;
+    /**
+     * The live-query semantics of one `QueryDef` (spec13 §38, §148, §149): whether it can be
+     * observed live and how (incremental deltas, whole resets, or not at all), the conservative
+     * set of committed changes that invalidate it, its row identity field, and what a resume
+     * cursor is bound to. Static over the graph; live runtime state is
+     * `AxiomServer.inspectLiveQueries()`.
+     */
+    analyzeLiveQuery(queryId: string): LiveQueryAnalysis;
 }
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -3,6 +3,7 @@ import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import { inspectSchema, migrationImpact } from './migration.js';
 import { inspectDistributedSemantics } from './distributed.js';
+import { analyzeLiveQuery } from './live-query.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -61,4 +62,14 @@ export class AgentAPI extends PresentationQueries {
     inspectDistributedSemantics(serverContract) {
         return inspectDistributedSemantics(this.graph, serverContract);
     }
+    /**
+     * The live-query semantics of one `QueryDef` (spec13 §38, §148, §149): whether it can be
+     * observed live and how (incremental deltas, whole resets, or not at all), the conservative
+     * set of committed changes that invalidate it, its row identity field, and what a resume
+     * cursor is bound to. Static over the graph; live runtime state is
+     * `AxiomServer.inspectLiveQueries()`.
+     */
+    analyzeLiveQuery(queryId) {
+        return analyzeLiveQuery(this.graph, queryId);
+    }
 }

package/dist/distributed.d.ts

@@ -37,11 +37,26 @@ export interface DistributedSemanticsInspection {
         note: string;
     };
     workClasses: DistributedWorkClassInfo[];
+    /**
+     * How a query result cache stays coherent across authorities (spec12 §32-§34).
+     */
     cacheCoherence: {
         mechanism: 'durable-revision-observation';
         stalenessBoundRevisions: 0;
         requiresBroadcast: false;
     };
+    /**
+     * How a running authority's in-memory `StateDef` view stays coherent with state another
+     * authority committed (spec12.1 §6-§9, §54). The in-memory view is an authority-local
+     * cache; the durable persistence revision is re-observed before every authoritative
+     * operation and the view is reloaded when behind.
+     */
+    stateCoherence: {
+        mechanism: 'durable-revision-observation';
+        stalenessBoundRevisions: 0;
+        requiresBroadcast: false;
+        refreshBeforeAuthoritativeOperation: true;
+    };
     operationalTuning: string[];
 }
 /**

package/dist/distributed.js

@@ -53,7 +53,7 @@ export function inspectDistributedSemantics(graph, serverContract = 'axiom.serve
             orderingScope: 'per-subscription',
             delivery: { guarantee: 'at-least-once', duplicatesPossible: true },
             providerCapabilityRequired: ['distributed-lease', 'fencing', 'durable-subscription-cursor', 'event-dedup'],
-            runtimeStateAvailableFrom: 'AxiomServer.subscriptionLog() + inspectDistributedWork().subscriptionCursors',
+            runtimeStateAvailableFrom: 'AxiomServer.subscriptionLog()',
         });
     }
     return {
@@ -73,6 +73,12 @@ export function inspectDistributedSemantics(graph, serverContract = 'axiom.serve
             stalenessBoundRevisions: 0,
             requiresBroadcast: false,
         },
+        stateCoherence: {
+            mechanism: 'durable-revision-observation',
+            stalenessBoundRevisions: 0,
+            requiresBroadcast: false,
+            refreshBeforeAuthoritativeOperation: true,
+        },
         operationalTuning: [
             'instanceId',
             'leaseDurationMs',

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './changes.js';
 export * from './queries.js';
 export * from './migration.js';
 export * from './distributed.js';
+export * from './live-query.js';
 export * from './presentation-queries.js';
 export * from './transaction.js';
 export * from './api.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './changes.js';
 export * from './queries.js';
 export * from './migration.js';
 export * from './distributed.js';
+export * from './live-query.js';
 export * from './presentation-queries.js';
 export * from './transaction.js';
 export * from './api.js';

package/dist/live-query.d.ts

@@ -0,0 +1,57 @@
+import { type ApplicationGraph, type LiveCapability } from '@cynodia/axiom-core';
+/**
+ * Static, graph-derivable live-query analysis (spec13 §38, §148, §149, §189 Q37/Q38).
+ *
+ * The AgentAPI works over an `ApplicationGraph`, not a running authority, so it answers the
+ * *semantic* questions — can this `QueryDef` be observed live, incrementally or only as whole
+ * resets, what committed changes invalidate it, and what a resume cursor is bound to — not
+ * the live runtime state (that is `AxiomServer.inspectLiveQueries()`).
+ *
+ * Nothing here names a transport. A live query is a persistent semantic observation of a
+ * canonical `QueryDef`; the runtime may poll and the provider may push, but the meaning is
+ * fixed by the graph (spec13 §195).
+ */
+export interface LiveQueryAnalysis {
+    queryId: string;
+    /** `live-capable` (incremental), `live-capable-reset-only` (whole resets), or `not-live-capable`. */
+    capability: LiveCapability;
+    /** Ordered result — a sort-key change produces an explicit `move` (spec13 §16). */
+    ordered: boolean;
+    /** Aggregate / grouped — delivered only as `reset` (spec13 §14, §19). */
+    aggregate: boolean;
+    /** The row identity field the canonical delta model keys on, or `null` for a reset-only query. */
+    identityFieldId: string | null;
+    /**
+     * Conservative static invalidation set (spec13 §26-§31): a committed change to any of these
+     * entities or `StateDef`s may move the result. `broad` means the dependency is not
+     * statically enumerable, so every commit re-evaluates.
+     */
+    dependencies: {
+        entityIds: string[];
+        stateIds: string[];
+        broad: boolean;
+        /** The read policy AND-ed into every evaluation, if one governs the source entity. */
+        readPolicyId: string | null;
+    };
+    /**
+     * What a `axiom.live-query-cursor.v1` resume token is bound to — a mismatch on any of these
+     * is refused fail-closed on reconnect (spec13 §33-§35, §79-§81).
+     */
+    cursorBinding: string[];
+    /** The delivery contract, stated honestly (spec13 §33, §41, §85). */
+    delivery: {
+        guarantee: 'at-least-once-logical';
+        updateIdentity: 'subscriptionId + toRevision';
+        ordering: 'per-subscription-monotonic-by-revision';
+        revisionsMayBeCoalesced: true;
+        cursorAcknowledgement: 'server-sent-no-ack';
+    };
+    /** Present when `capability` is not `live-capable` — why, in one line. */
+    reason?: string;
+}
+/**
+ * Analyze one `QueryDef`'s live-query semantics. Pure over the graph. Throws if `queryId`
+ * does not name a `query` node.
+ */
+export declare function analyzeLiveQuery(graph: ApplicationGraph, queryId: string): LiveQueryAnalysis;
+//# sourceMappingURL=live-query.d.ts.map

package/dist/live-query.js

@@ -0,0 +1,60 @@
+import { queryDependencies, queryLiveCapability, readPolicyForEntity, } from '@cynodia/axiom-core';
+/**
+ * Analyze one `QueryDef`'s live-query semantics. Pure over the graph. Throws if `queryId`
+ * does not name a `query` node.
+ */
+export function analyzeLiveQuery(graph, queryId) {
+    const query = graph
+        .getNodesByKind('query')
+        .find((node) => String(node.id) === String(queryId));
+    if (!query) {
+        throw new Error(`analyzeLiveQuery: no query node "${queryId}"`);
+    }
+    const entities = graph.getNodesByKind('entity');
+    const relationships = graph.getNodesByKind('relationship');
+    const readPolicies = graph.getNodesByKind('read-policy');
+    const stateIds = new Set(graph.getNodesByKind('state').map((state) => String(state.id)));
+    const source = entities.find((entity) => String(entity.id) === String(query.source));
+    const sourceIdentityFieldId = source?.identityFieldId ? String(source.identityFieldId) : undefined;
+    // Mirror the authority's `policyForQuery`: an explicit `readPolicyId` wins, else the policy
+    // that governs the source entity.
+    const policy = query.readPolicyId
+        ? readPolicies.find((candidate) => String(candidate.id) === String(query.readPolicyId))
+        : readPolicyForEntity(readPolicies, query.source);
+    const capability = queryLiveCapability(query, sourceIdentityFieldId);
+    const aggregate = (query.aggregate?.length ?? 0) > 0 || (query.groupBy?.length ?? 0) > 0;
+    const ordered = (query.sort?.length ?? 0) > 0;
+    const deps = queryDependencies(query, policy, relationships, stateIds);
+    const analysis = {
+        queryId: String(query.id),
+        capability,
+        ordered,
+        aggregate,
+        identityFieldId: capability.capability === 'live-capable' && sourceIdentityFieldId ? sourceIdentityFieldId : null,
+        dependencies: {
+            entityIds: [...deps.entityIds].sort(),
+            stateIds: [...deps.stateIds].sort(),
+            broad: deps.broad,
+            readPolicyId: policy ? String(policy.id) : null,
+        },
+        cursorBinding: [
+            'queryId',
+            'argumentsFingerprint',
+            'principalFingerprint',
+            'policyFingerprint',
+            'compatibilityFingerprint (serverContract + schemaFingerprint + semanticFingerprint)',
+            'hmac-sha256 integrity signature',
+        ],
+        delivery: {
+            guarantee: 'at-least-once-logical',
+            updateIdentity: 'subscriptionId + toRevision',
+            ordering: 'per-subscription-monotonic-by-revision',
+            revisionsMayBeCoalesced: true,
+            cursorAcknowledgement: 'server-sent-no-ack',
+        },
+    };
+    if (capability.capability !== 'live-capable') {
+        analysis.reason = capability.reason;
+    }
+    return analysis;
+}

package/package.json

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