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

package/dist/api.d.ts

@@ -3,6 +3,7 @@ import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import type { ChangeSet } from './changes.js';
 import type { MigrationImpact, SchemaInspection } from './migration.js';
+import type { DistributedSemanticsInspection } from './distributed.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -32,5 +33,14 @@ export declare class AgentAPI extends PresentationQueries {
      * actions, read policies, constraints and UI nodes reference something a migration touches.
      */
     migrationImpact(previous: ApplicationGraph): MigrationImpact;
+    /**
+     * The distributed-authority semantics of this application (spec12 §56, §57): its
+     * framework-owned async work classes and the guarantee that applies to each, its
+     * compatibility identity, cache coherence, and the operational knobs — with the semantic
+     * guarantee, the runtime-state source, the provider capability and the tuning kept
+     * separate. Static over the graph; live runtime state is `AxiomServer.authority()` /
+     * `inspectDistributedWork()`.
+     */
+    inspectDistributedSemantics(serverContract?: string): DistributedSemanticsInspection;
 }
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -2,6 +2,7 @@ import { diffSchema, validateGraph } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import { inspectSchema, migrationImpact } from './migration.js';
+import { inspectDistributedSemantics } from './distributed.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -49,4 +50,15 @@ export class AgentAPI extends PresentationQueries {
     migrationImpact(previous) {
         return migrationImpact(previous, this.graph);
     }
+    /**
+     * The distributed-authority semantics of this application (spec12 §56, §57): its
+     * framework-owned async work classes and the guarantee that applies to each, its
+     * compatibility identity, cache coherence, and the operational knobs — with the semantic
+     * guarantee, the runtime-state source, the provider capability and the tuning kept
+     * separate. Static over the graph; live runtime state is `AxiomServer.authority()` /
+     * `inspectDistributedWork()`.
+     */
+    inspectDistributedSemantics(serverContract) {
+        return inspectDistributedSemantics(this.graph, serverContract);
+    }
 }

package/dist/distributed.d.ts

@@ -0,0 +1,52 @@
+import { type ApplicationGraph, type AuthorityCompatibilityKey } from '@cynodia/axiom-core';
+/**
+ * Static, graph-derivable distributed-authority inspection (spec12 §56, §57).
+ *
+ * The AgentAPI works over an `ApplicationGraph`, not a running authority, so it answers the
+ * *semantic* questions — which framework-owned async work this application has, and what
+ * distributed guarantee applies to each — not the live runtime state (that is
+ * `AxiomServer.authority()` / `inspectDistributedWork()`).
+ *
+ * Every answer separates the four things spec12 §56 says must never be conflated:
+ * `semanticGuarantee` (fixed by the framework), `runtimeStateAvailableFrom` (where to read
+ * the live state), `providerCapabilityRequired` (what a provider must advertise), and
+ * `operationalTuning` (knobs that never change a guarantee).
+ */
+export interface DeliveryContract {
+    logicalCreation: 'exactly-once';
+    physicalExecution: 'at-least-once' | 'exactly-once-if-provider-idempotent';
+    completionTransition: 'exactly-once';
+}
+export interface DistributedWorkClassInfo {
+    workClass: 'effect' | 'schedule-firing' | 'subscription-delivery';
+    /** The graph nodes that produce this class of work. */
+    sources: string[];
+    ownership: 'leased-per-work-item-fenced';
+    orderingScope: 'none' | 'per-subscription';
+    delivery: DeliveryContract | {
+        guarantee: 'at-least-once';
+        duplicatesPossible: true;
+    };
+    providerCapabilityRequired: string[];
+    runtimeStateAvailableFrom: string;
+}
+export interface DistributedSemanticsInspection {
+    /** No application API activates this; a capable shared provider does (spec12 §88). */
+    activation: 'automatic-when-coordination-provider-and-durable-persistence-shared';
+    compatibility: AuthorityCompatibilityKey & {
+        note: string;
+    };
+    workClasses: DistributedWorkClassInfo[];
+    cacheCoherence: {
+        mechanism: 'durable-revision-observation';
+        stalenessBoundRevisions: 0;
+        requiresBroadcast: false;
+    };
+    operationalTuning: string[];
+}
+/**
+ * Summarize the distributed-authority semantics of an application (spec12 §56). Pure over
+ * the graph. `serverContract` defaults to `axiom.server.v7` (0.12 adds no IR vocabulary).
+ */
+export declare function inspectDistributedSemantics(graph: ApplicationGraph, serverContract?: string): DistributedSemanticsInspection;
+//# sourceMappingURL=distributed.d.ts.map

package/dist/distributed.js

@@ -0,0 +1,85 @@
+import { 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)));
+}
+function scheduledTriggers(graph) {
+    return graph.getNodesByKind('trigger').filter((trigger) => trigger.when.kind === 'interval' || trigger.when.kind === 'delay');
+}
+/**
+ * Summarize the distributed-authority semantics of an application (spec12 §56). Pure over
+ * the graph. `serverContract` defaults to `axiom.server.v7` (0.12 adds no IR vocabulary).
+ */
+export function inspectDistributedSemantics(graph, serverContract = 'axiom.server.v7') {
+    const effects = actionsWithEffects(graph);
+    const schedules = scheduledTriggers(graph);
+    const subscriptions = graph.getNodesByKind('subscription');
+    const workClasses = [];
+    if (effects.length > 0) {
+        workClasses.push({
+            workClass: 'effect',
+            sources: effects.map((action) => String(action.id)),
+            ownership: 'leased-per-work-item-fenced',
+            orderingScope: 'none',
+            delivery: {
+                logicalCreation: 'exactly-once',
+                physicalExecution: 'at-least-once', // 'exactly-once-if-provider-idempotent' per operation
+                completionTransition: 'exactly-once',
+            },
+            providerCapabilityRequired: ['distributed-lease', 'fencing', 'atomic-work-claim', 'durable-retry'],
+            runtimeStateAvailableFrom: 'AxiomServer.inspectDistributedWork().effects',
+        });
+    }
+    if (schedules.length > 0) {
+        workClasses.push({
+            workClass: 'schedule-firing',
+            sources: schedules.map((trigger) => String(trigger.id)),
+            ownership: 'leased-per-work-item-fenced',
+            orderingScope: 'none',
+            delivery: {
+                logicalCreation: 'exactly-once',
+                physicalExecution: 'at-least-once',
+                completionTransition: 'exactly-once',
+            },
+            providerCapabilityRequired: ['distributed-lease', 'fencing', 'atomic-work-claim'],
+            runtimeStateAvailableFrom: 'AxiomServer.inspectDistributedWork().schedules',
+        });
+    }
+    if (subscriptions.length > 0) {
+        workClasses.push({
+            workClass: 'subscription-delivery',
+            sources: subscriptions.map((subscription) => String(subscription.id)),
+            ownership: 'leased-per-work-item-fenced',
+            orderingScope: 'per-subscription',
+            delivery: { guarantee: 'at-least-once', duplicatesPossible: true },
+            providerCapabilityRequired: ['distributed-lease', 'fencing', 'durable-subscription-cursor', 'event-dedup'],
+            runtimeStateAvailableFrom: 'AxiomServer.subscriptionLog() + inspectDistributedWork().subscriptionCursors',
+        });
+    }
+    return {
+        activation: 'automatic-when-coordination-provider-and-durable-persistence-shared',
+        compatibility: {
+            ...authorityCompatibilityKey({
+                schemaVersion: graph.schemaVersion,
+                schemaFingerprint: schemaFingerprint(graph),
+                serverContract,
+                semanticFingerprint: semanticFingerprint(graph),
+            }),
+            note: 'Two authorities may execute the same durable work iff these four fields are equal (fail closed).',
+        },
+        workClasses,
+        cacheCoherence: {
+            mechanism: 'durable-revision-observation',
+            stalenessBoundRevisions: 0,
+            requiresBroadcast: false,
+        },
+        operationalTuning: [
+            'instanceId',
+            'leaseDurationMs',
+            'renewIntervalMs',
+            'workerConcurrency',
+            'claimBatchSize',
+            'pollIntervalMs',
+        ],
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

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