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

package/dist/migration.d.ts

@@ -1,5 +1,5 @@
 import { DEFAULT_SCHEMA_VERSION } from '@cynodia/axiom-core';
-import type { ApplicationGraph, SchemaChangeClass, SchemaDiff, SchemaDiffEntry } from '@cynodia/axiom-core';
+import type { ApplicationGraph, MigrationOperation, SchemaChangeClass, SchemaDiff, SchemaDiffEntry } from '@cynodia/axiom-core';
 /**
  * Authoring-time schema-evolution inspection for an agent (spec11 §56-58, §93).
  *
@@ -57,14 +57,44 @@ export declare function inspectSchema(graph: ApplicationGraph): SchemaInspection
  * never a JSON text diff.
  */
 export declare function explainSchemaDiff(diff: SchemaDiff): string;
+/**
+ * How `covered` was decided (spec11.1 §23-24).
+ *
+ * - `step` — `previous` and `next` are one schema version apart, so coverage is evaluated
+ *   against the operations of the single `N → N+1` migration. This is the authoritative
+ *   check and agrees with `migrationCoversDiff` and `validateGraph`.
+ * - `chain` — `previous` and `next` are more than one version apart. A single endpoint diff
+ *   has no ordinary per-step coverage, so `covered` reports only whether a complete
+ *   migration chain connects the two versions; `steps` lists the migrations it would run.
+ * - `none` — `previous` and `next` declare the same schema version, or a downgrade.
+ */
+export type CoverageMode = 'step' | 'chain' | 'none';
+export interface MigrationCoverageStep {
+    migrationId: string;
+    fromSchema: number;
+    toSchema: number;
+    operationCount: number;
+}
 export interface MigrationImpact {
     fromVersion: number;
     toVersion: number;
     diff: SchemaDiff;
     verdict: SchemaChangeClass;
-    /** Whether the migration chain in `next` accounts for every data-affecting diff entry. */
+    /**
+     * Whether the migration accounts for the data-affecting part of this diff. For a
+     * single-step diff (`coverageMode: 'step'`) this is the authoritative answer and matches
+     * `migrationCoversDiff(diff, thatStep.operations).covered`. For a multi-step diff
+     * (`coverageMode: 'chain'`) it reports only whether a complete chain exists. Always
+     * accompanied by `uncovered` / `unmatched` / `steps` explaining the value (spec11.1 §25).
+     */
     covered: boolean;
+    coverageMode: CoverageMode;
+    /** Data-affecting diff entries with no matching migration operation. */
     uncovered: SchemaDiffEntry[];
+    /** Migration operations in the evaluated step that correspond to no diff entry. */
+    unmatched: MigrationOperation[];
+    /** The migration steps between `fromVersion` and `toVersion`, in order. */
+    steps: MigrationCoverageStep[];
     dataLossPossible: boolean;
     affectedEntities: string[];
     affectedFields: string[];

package/dist/migration.js

@@ -1,4 +1,4 @@
-import { DEFAULT_SCHEMA_VERSION, diffSchema, migrationCoversDiff, schemaFingerprint, schemaProjection, } from '@cynodia/axiom-core';
+import { DEFAULT_SCHEMA_VERSION, diffSchema, migrationCoversDiff, migrationPath, schemaFingerprint, schemaProjection, sortMigrations, } from '@cynodia/axiom-core';
 function destructiveOps(migration) {
     return migration.operations.filter((operation) => operation.destructive === true ||
         operation.kind === 'remove-field' ||
@@ -87,9 +87,46 @@ export function migrationImpact(previous, next) {
     const diff = diffSchema(previous, next);
     const changedFields = new Set(diff.entries.map((entry) => entry.fieldId).filter(Boolean));
     const changedEntities = new Set(diff.entries.map((entry) => entry.entityId).filter(Boolean));
-    const migrations = next.getNodesByKind('migration');
-    const operations = migrations.flatMap((migration) => migration.operations);
-    const coverage = migrationCoversDiff(diff, operations);
+    // Coverage is scoped to the semantic transition being evaluated, NOT the whole chain in
+    // `next` (spec11.1 §22-24). Feeding every historical operation into an endpoint diff
+    // produces false negatives.
+    const migrations = sortMigrations(next.getNodesByKind('migration'));
+    const fromV = diff.fromVersion;
+    const toV = diff.toVersion;
+    const chain = toV > fromV ? migrationPath(migrations, fromV, toV) : [];
+    const steps = (chain ?? []).map((migration) => ({
+        migrationId: String(migration.id),
+        fromSchema: migration.fromSchema,
+        toSchema: migration.toSchema,
+        operationCount: migration.operations.length,
+    }));
+    let coverageMode;
+    let covered;
+    let uncovered = [];
+    let unmatched = [];
+    if (toV <= fromV) {
+        // Same version (nothing to cover) or a downgrade (no reverse path is evaluated here).
+        coverageMode = 'none';
+        covered = toV === fromV;
+    }
+    else if (toV === fromV + 1) {
+        // Single step: evaluate the diff against exactly the `fromV → fromV+1` migration.
+        coverageMode = 'step';
+        const step = migrations.find((migration) => migration.fromSchema === fromV);
+        const result = migrationCoversDiff(diff, step?.operations ?? []);
+        covered = result.covered;
+        uncovered = result.uncovered;
+        unmatched = result.unmatched;
+    }
+    else {
+        // Multi-step: a single endpoint diff has no ordinary step coverage. Report only whether
+        // a complete chain connects the two versions (spec11.1 §24, option B).
+        coverageMode = 'chain';
+        covered = chain !== null;
+        if (chain === null) {
+            uncovered = diff.needsMigration;
+        }
+    }
     const touchesChange = (nodeId) => {
         for (const edge of next.getEdges(nodeId, { kinds: ['reads', 'writes', 'references'] })) {
             const fieldIds = edge.metadata?.fieldIds ?? [];
@@ -136,8 +173,11 @@ export function migrationImpact(previous, next) {
         toVersion: diff.toVersion,
         diff,
         verdict: diff.verdict,
-        covered: coverage.covered,
-        uncovered: coverage.uncovered,
+        covered,
+        coverageMode,
+        uncovered,
+        unmatched,
+        steps,
         dataLossPossible: diff.destructive.length > 0,
         affectedEntities: [...changedEntities].sort(),
         affectedFields: [...changedFields].sort(),

package/package.json

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