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

package/dist/api.d.ts

@@ -1,7 +1,8 @@
-import type { ApplicationGraph, ValidationResult } from '@cynodia/axiom-core';
+import type { ApplicationGraph, SchemaDiff, ValidationResult } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import type { ChangeSet } from './changes.js';
+import type { MigrationImpact, SchemaInspection } from './migration.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -21,5 +22,15 @@ export declare class AgentAPI extends PresentationQueries {
         result: ValidationResult;
     };
     history(): ChangeSet[];
+    /** A structural summary of the semantic schema this graph declares (spec11 §89). */
+    inspectSchema(): SchemaInspection;
+    /** The classified semantic diff between a previous schema and this one (spec11 §58). */
+    diffSchema(previous: ApplicationGraph): SchemaDiff;
+    /**
+     * Impact analysis for evolving `previous` into this graph (spec11 §57): the diff, whether
+     * the migration chain covers it, whether data loss is possible, and which queries,
+     * actions, read policies, constraints and UI nodes reference something a migration touches.
+     */
+    migrationImpact(previous: ApplicationGraph): MigrationImpact;
 }
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -1,6 +1,7 @@
-import { validateGraph } from '@cynodia/axiom-core';
+import { diffSchema, validateGraph } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
+import { inspectSchema, migrationImpact } from './migration.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -32,4 +33,20 @@ export class AgentAPI extends PresentationQueries {
     history() {
         return this.changeLog.map((change) => ({ ...change, operations: [...change.operations] }));
     }
+    /** A structural summary of the semantic schema this graph declares (spec11 §89). */
+    inspectSchema() {
+        return inspectSchema(this.graph);
+    }
+    /** The classified semantic diff between a previous schema and this one (spec11 §58). */
+    diffSchema(previous) {
+        return diffSchema(previous, this.graph);
+    }
+    /**
+     * Impact analysis for evolving `previous` into this graph (spec11 §57): the diff, whether
+     * the migration chain covers it, whether data loss is possible, and which queries,
+     * actions, read policies, constraints and UI nodes reference something a migration touches.
+     */
+    migrationImpact(previous) {
+        return migrationImpact(previous, this.graph);
+    }
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/migration.d.ts

@@ -0,0 +1,85 @@
+import { DEFAULT_SCHEMA_VERSION } from '@cynodia/axiom-core';
+import type { ApplicationGraph, SchemaChangeClass, SchemaDiff, SchemaDiffEntry } from '@cynodia/axiom-core';
+/**
+ * Authoring-time schema-evolution inspection for an agent (spec11 §56-58, §93).
+ *
+ * These functions answer, from the graph alone, what an agent needs before proposing or
+ * approving an upgrade: what the schema currently is, what a diff between two versions
+ * changes, whether the migration chain covers it, and which application semantics — queries,
+ * actions, read policies, constraints, UI — reference something a migration touches. The
+ * runtime planner (`planMigration` / `explainMigration` in `@cynodia/axiom-server`) answers
+ * the execution-side questions.
+ */
+export interface SchemaInspection {
+    schemaVersion: number;
+    schemaFingerprint: string;
+    entities: Array<{
+        id: string;
+        identityFieldId: string | null;
+        fieldCount: number;
+        requiredFieldCount: number;
+    }>;
+    persistedStates: Array<{
+        id: string;
+        derived: boolean;
+        authority: 'client' | 'server';
+    }>;
+    relationships: Array<{
+        id: string;
+        from: {
+            entityId: string;
+            fieldId: string;
+        };
+        to: {
+            entityId: string;
+            fieldId: string;
+        };
+        cardinality: 'to-one' | 'to-many';
+    }>;
+    readPolicies: Array<{
+        id: string;
+        entityId: string;
+    }>;
+    migrations: Array<{
+        id: string;
+        fromSchema: number;
+        toSchema: number;
+        operationCount: number;
+        destructiveOperationCount: number;
+    }>;
+    /** Whether a contiguous migration chain connects schema 1 to `schemaVersion`. */
+    chainComplete: boolean;
+}
+/** A structural summary of the schema a graph declares (spec11 §89 `inspectSchema`). */
+export declare function inspectSchema(graph: ApplicationGraph): SchemaInspection;
+/**
+ * The terse semantic diff render of spec11 §58 — `+` added, `-` removed, `~` changed,
+ * never a JSON text diff.
+ */
+export declare function explainSchemaDiff(diff: SchemaDiff): string;
+export interface MigrationImpact {
+    fromVersion: number;
+    toVersion: number;
+    diff: SchemaDiff;
+    verdict: SchemaChangeClass;
+    /** Whether the migration chain in `next` accounts for every data-affecting diff entry. */
+    covered: boolean;
+    uncovered: SchemaDiffEntry[];
+    dataLossPossible: boolean;
+    affectedEntities: string[];
+    affectedFields: string[];
+    affectedQueries: string[];
+    affectedActions: string[];
+    affectedReadPolicies: string[];
+    affectedConstraints: string[];
+    affectedUiNodes: string[];
+    /** Read-policy diff entries — an authorization-semantic change, distinct from a data change (spec11 §42). */
+    authorizationChanges: string[];
+}
+/**
+ * Impact analysis for a proposed upgrade (spec11 §57). Diffs `previous` against `next` and
+ * reports which application semantics reference a field or entity the migration changes.
+ */
+export declare function migrationImpact(previous: ApplicationGraph, next: ApplicationGraph): MigrationImpact;
+export { DEFAULT_SCHEMA_VERSION };
+//# sourceMappingURL=migration.d.ts.map

package/dist/migration.js

@@ -0,0 +1,154 @@
+import { DEFAULT_SCHEMA_VERSION, diffSchema, migrationCoversDiff, schemaFingerprint, schemaProjection, } from '@cynodia/axiom-core';
+function destructiveOps(migration) {
+    return migration.operations.filter((operation) => operation.destructive === true ||
+        operation.kind === 'remove-field' ||
+        operation.kind === 'remove-entity' ||
+        (operation.kind === 'transform-record' && (operation.removesFields?.length ?? 0) > 0)).length;
+}
+/** A structural summary of the schema a graph declares (spec11 §89 `inspectSchema`). */
+export function inspectSchema(graph) {
+    const projection = schemaProjection(graph);
+    const migrations = graph.getNodesByKind('migration');
+    const byFrom = new Map(migrations.map((migration) => [migration.fromSchema, migration]));
+    let chainComplete = true;
+    for (let version = 1; version < projection.schemaVersion; version += 1) {
+        const step = byFrom.get(version);
+        if (!step || step.toSchema !== version + 1) {
+            chainComplete = false;
+            break;
+        }
+    }
+    return {
+        chainComplete,
+        schemaVersion: projection.schemaVersion,
+        schemaFingerprint: schemaFingerprint(graph),
+        entities: projection.entities.map((entity) => ({
+            id: entity.id,
+            identityFieldId: entity.identityFieldId,
+            fieldCount: entity.fields.length,
+            requiredFieldCount: entity.fields.filter((field) => field.required).length,
+        })),
+        persistedStates: projection.states.map((state) => ({
+            id: state.id,
+            derived: state.derived,
+            authority: state.authority,
+        })),
+        relationships: projection.relationships.map((relationship) => ({
+            id: relationship.id,
+            from: relationship.from,
+            to: relationship.to,
+            cardinality: relationship.cardinality,
+        })),
+        readPolicies: projection.readPolicies.map((policy) => ({ id: policy.id, entityId: policy.entityId })),
+        migrations: [...migrations]
+            .sort((a, b) => a.fromSchema - b.fromSchema)
+            .map((migration) => ({
+            id: String(migration.id),
+            fromSchema: migration.fromSchema,
+            toSchema: migration.toSchema,
+            operationCount: migration.operations.length,
+            destructiveOperationCount: destructiveOps(migration),
+        })),
+    };
+}
+/**
+ * The terse semantic diff render of spec11 §58 — `+` added, `-` removed, `~` changed,
+ * never a JSON text diff.
+ */
+export function explainSchemaDiff(diff) {
+    if (diff.entries.length === 0) {
+        return `schema ${diff.fromVersion} → ${diff.toVersion}: no persistence-relevant change`;
+    }
+    const lines = [`schema ${diff.fromVersion} → ${diff.toVersion}  (verdict: ${diff.verdict})`];
+    for (const entry of diff.entries) {
+        const subject = entry.fieldId
+            ? `${entry.entityId ?? '?'}.${entry.fieldId}`
+            : entry.entityId ?? entry.stateId ?? entry.relationshipId ?? entry.readPolicyId ?? '?';
+        lines.push(`  ${entry.mark} ${subject}  [${entry.class}] ${entry.message}`);
+    }
+    return lines.join('\n');
+}
+const UI_KINDS = new Set([
+    'view',
+    'container',
+    'text',
+    'repeat',
+    'field-display',
+    'form',
+    'input',
+    'button',
+    'conditional',
+]);
+/**
+ * Impact analysis for a proposed upgrade (spec11 §57). Diffs `previous` against `next` and
+ * reports which application semantics reference a field or entity the migration changes.
+ */
+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);
+    const touchesChange = (nodeId) => {
+        for (const edge of next.getEdges(nodeId, { kinds: ['reads', 'writes', 'references'] })) {
+            const fieldIds = edge.metadata?.fieldIds ?? [];
+            if (fieldIds.some((id) => changedFields.has(id)))
+                return true;
+            if (changedEntities.has(String(edge.to)))
+                return true;
+        }
+        return false;
+    };
+    const affectedQueries = [];
+    const affectedActions = [];
+    const affectedReadPolicies = [];
+    const affectedConstraints = [];
+    const affectedUiNodes = [];
+    for (const node of next.listNodes()) {
+        const id = String(node.id);
+        if (node.kind === 'query') {
+            if (changedEntities.has(String(node.source)) || touchesChange(id)) {
+                affectedQueries.push(id);
+            }
+        }
+        else if (node.kind === 'action') {
+            if (touchesChange(id))
+                affectedActions.push(id);
+        }
+        else if (node.kind === 'read-policy') {
+            if (changedEntities.has(String(node.entityId)) || touchesChange(id)) {
+                affectedReadPolicies.push(id);
+            }
+        }
+        else if (node.kind === 'constraint' || node.kind === 'transition-constraint') {
+            if (changedEntities.has(String(node.entityId)) || touchesChange(id)) {
+                affectedConstraints.push(id);
+            }
+        }
+        else if (UI_KINDS.has(node.kind)) {
+            if (touchesChange(id))
+                affectedUiNodes.push(id);
+        }
+    }
+    return {
+        fromVersion: diff.fromVersion,
+        toVersion: diff.toVersion,
+        diff,
+        verdict: diff.verdict,
+        covered: coverage.covered,
+        uncovered: coverage.uncovered,
+        dataLossPossible: diff.destructive.length > 0,
+        affectedEntities: [...changedEntities].sort(),
+        affectedFields: [...changedFields].sort(),
+        affectedQueries: affectedQueries.sort(),
+        affectedActions: affectedActions.sort(),
+        affectedReadPolicies: affectedReadPolicies.sort(),
+        affectedConstraints: affectedConstraints.sort(),
+        affectedUiNodes: affectedUiNodes.sort(),
+        authorizationChanges: diff.entries
+            .filter((entry) => entry.authorizationChange)
+            .map((entry) => entry.readPolicyId ?? '?'),
+    };
+}
+export { DEFAULT_SCHEMA_VERSION };

package/dist/queries.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, EventDef, Expression, ExpressionDef, FieldId, FormNode, GraphEdge, IntegrationDef, IntegrationOperationDef, Location, NodeId, StateDef, StorageDef, SubscriptionDef, TransitionConstraintDef, TriggerDef, UINode, ViewNode } from '@cynodia/axiom-core';
+import type { ActionDef, AnyNode, ApplicationGraph, ConstraintDef, EdgeKind, EntityDef, EventDef, Expression, ExpressionDef, FieldId, FormNode, GraphEdge, IntegrationDef, IntegrationOperationDef, Location, NodeId, QueryAggregate, QueryDef, QueryParameter, ReadPolicyDef, RelationshipDef, StateDef, StorageDef, SubscriptionDef, TransitionConstraintDef, TriggerDef, UINode, ViewNode } from '@cynodia/axiom-core';
 export interface SubgraphRequest {
     root: NodeId;
     depth?: number;
@@ -19,6 +19,11 @@ export interface MutationImpact {
     /** Rules that govern how this state may change, whatever writes it. */
     affectedTransitionConstraints: TransitionConstraintDef[];
     affectedViews: ViewNode[];
+    /**
+     * Registered queries a write to this location may invalidate — conservatively, every
+     * query that reads an entity stored in the affected state (spec 0.10 §72-74).
+     */
+    affectedQueries: QueryDef[];
     /**
      * 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
@@ -28,6 +33,47 @@ export interface MutationImpact {
     /** Why the analysis is incomplete, when it is. */
     analysisGaps: string[];
 }
+/** A structured, agent-readable account of what a query does (spec 0.10 §86). */
+export interface QueryExplanation {
+    queryId: NodeId;
+    /** The authoritative source entity. */
+    source: NodeId;
+    parameters: QueryParameter[];
+    /** The requested predicate, in prose-free structural form. Absent means "every row". */
+    filter?: Expression;
+    /** The read policy predicate AND-ed into the effective filter, if one governs the source. */
+    readPolicyPredicate?: Expression;
+    /** Sort keys, most significant first, plus the appended canonical-identity tie-breaker. */
+    sort: Array<{
+        key: Expression;
+        direction: 'asc' | 'desc';
+        nulls: 'first' | 'last';
+    }>;
+    identityTieBreaker?: FieldId;
+    /** Relationship traversals: relationship id, cardinality, bound alias. */
+    relationships: Array<{
+        relationshipId: NodeId;
+        cardinality: 'to-one' | 'to-many';
+        bindAs: NodeId;
+    }>;
+    /** Projected result fields, or `undefined` for a query that returns whole source rows. */
+    projection?: {
+        entityId: NodeId;
+        fields: FieldId[];
+    };
+    aggregates: QueryAggregate[];
+    groupBy: Expression[];
+    pagination: {
+        strategy: 'cursor' | 'offset';
+        maxPageSize: number;
+    };
+    /** Entities the query reads, transitively through its relationships. */
+    entities: NodeId[];
+    /** Fields the query reads across all its clauses. */
+    fields: FieldId[];
+    /** Actions that may invalidate this query when they commit. */
+    invalidatingActions: NodeId[];
+}
 export declare class GraphQueries {
     protected graph: ApplicationGraph;
     constructor(graph: ApplicationGraph);
@@ -95,6 +141,47 @@ export declare class GraphQueries {
      * graph relationships, so an agent never has to read application source to find out.
      */
     getMutationImpact(location: Location): MutationImpact;
+    /** Every registered query the application declares (spec 0.10 §85). */
+    listQueries(): QueryDef[];
+    getQuery(id: NodeId): QueryDef | undefined;
+    /** Every explicit entity-to-entity relationship. */
+    listRelationships(): RelationshipDef[];
+    getRelationship(id: NodeId): RelationshipDef | undefined;
+    /** Relationships that start from or reach an entity. */
+    getRelationshipsForEntity(entityId: NodeId): RelationshipDef[];
+    /** Every row-level read policy. */
+    listReadPolicies(): ReadPolicyDef[];
+    /** The read policy governing an entity's rows, if one is declared. */
+    getReadPolicyForEntity(entityId: NodeId): ReadPolicyDef | undefined;
+    /** The read policy a query's rows are filtered by — named on the query, or over its source. */
+    getReadPolicyForQuery(id: NodeId): ReadPolicyDef | undefined;
+    getQueryParameters(id: NodeId): QueryParameter[];
+    /** Whether this query reduces rows to aggregate scalars rather than returning them. */
+    isAggregateQuery(id: NodeId): boolean;
+    /** The entity a non-aggregate result row conforms to (the projection entity, else the source). */
+    getQueryResultEntity(id: NodeId): NodeId | undefined;
+    /** Every entity a query reads, including relationship targets it traverses. */
+    getQueryEntities(id: NodeId): EntityDef[];
+    private queryReadEntities;
+    /** Relationships a query traverses. */
+    getQueryRelationships(id: NodeId): RelationshipDef[];
+    /** Every field a query reads across its filter, sort, projection, group and aggregate clauses. */
+    getQueryFields(id: NodeId): FieldId[];
+    /**
+     * Actions that may invalidate a query's results when they commit — conservatively, every
+     * action that writes a state holding an entity the query reads, or that mutates a
+     * provider-backed row of one (spec 0.10 §73-74). Over-inclusion is acceptable; a
+     * known-stale result is not (spec §72).
+     */
+    getActionsInvalidatingQuery(id: NodeId): ActionDef[];
+    /** The inverse: every query an action's commit may invalidate. */
+    getQueriesInvalidatedByAction(actionId: NodeId): QueryDef[];
+    /**
+     * A structured explanation of a query — source, effective filter (with the read-policy
+     * conjunct called out), ordering with its identity tie-breaker, projection, pagination,
+     * the entities and fields it reads, and the actions that can invalidate it (spec §86).
+     */
+    explainQuery(id: NodeId): QueryExplanation | undefined;
     private constraintTouches;
     /** Derived states that depend on a state, directly or through other derived states. */
     private derivedStatesFrom;

package/dist/queries.js

@@ -1,4 +1,5 @@
 import { 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'];
 const CONTAINMENT_KINDS = ['contains', 'renders'];
@@ -265,6 +266,7 @@ export class GraphQueries {
             .getNodesByKind('transition-constraint')
             .filter((constraint) => entityIds.has(constraint.entityId));
         const gaps = this.analysisGaps();
+        const affectedQueries = this.listQueries().filter((query) => this.queryReadEntities(query).some((entityId) => entityIds.has(entityId)));
         return {
             location,
             rootStateId,
@@ -274,10 +276,190 @@ export class GraphQueries {
             affectedConstraints,
             affectedTransitionConstraints,
             affectedViews: [...views.values()],
+            affectedQueries,
             analysisComplete: gaps.length === 0,
             analysisGaps: gaps,
         };
     }
+    // ------------------------------------------------- queries, relationships, read policies
+    /** Every registered query the application declares (spec 0.10 §85). */
+    listQueries() {
+        return this.graph.getNodesByKind('query');
+    }
+    getQuery(id) {
+        const node = this.graph.getNode(id);
+        return node?.kind === 'query' ? node : undefined;
+    }
+    /** Every explicit entity-to-entity relationship. */
+    listRelationships() {
+        return this.graph.getNodesByKind('relationship');
+    }
+    getRelationship(id) {
+        const node = this.graph.getNode(id);
+        return node?.kind === 'relationship' ? node : undefined;
+    }
+    /** Relationships that start from or reach an entity. */
+    getRelationshipsForEntity(entityId) {
+        return this.listRelationships().filter((relationship) => relationship.from.entityId === entityId || relationship.to.entityId === entityId);
+    }
+    /** Every row-level read policy. */
+    listReadPolicies() {
+        return this.graph.getNodesByKind('read-policy');
+    }
+    /** The read policy governing an entity's rows, if one is declared. */
+    getReadPolicyForEntity(entityId) {
+        return this.listReadPolicies().find((policy) => policy.entityId === entityId);
+    }
+    /** The read policy a query's rows are filtered by — named on the query, or over its source. */
+    getReadPolicyForQuery(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return undefined;
+        }
+        if (query.readPolicyId) {
+            const policy = this.graph.getNode(query.readPolicyId);
+            return policy?.kind === 'read-policy' ? policy : undefined;
+        }
+        return this.getReadPolicyForEntity(query.source);
+    }
+    getQueryParameters(id) {
+        return this.getQuery(id)?.parameters ?? [];
+    }
+    /** Whether this query reduces rows to aggregate scalars rather than returning them. */
+    isAggregateQuery(id) {
+        const query = this.getQuery(id);
+        return query ? queryIsAggregate(query) : false;
+    }
+    /** The entity a non-aggregate result row conforms to (the projection entity, else the source). */
+    getQueryResultEntity(id) {
+        const query = this.getQuery(id);
+        return query ? queryRowEntityId(query) : undefined;
+    }
+    /** Every entity a query reads, including relationship targets it traverses. */
+    getQueryEntities(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return [];
+        }
+        return this.queryReadEntities(query)
+            .map((entityId) => this.graph.getNode(entityId))
+            .filter((node) => node?.kind === 'entity');
+    }
+    queryReadEntities(query) {
+        const entities = new Set([query.source]);
+        for (const use of query.relationships ?? []) {
+            const relationship = this.getRelationship(use.relationshipId);
+            if (relationship) {
+                entities.add(relationship.to.entityId);
+            }
+        }
+        return [...entities];
+    }
+    /** Relationships a query traverses. */
+    getQueryRelationships(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return [];
+        }
+        return (query.relationships ?? [])
+            .map((use) => this.getRelationship(use.relationshipId))
+            .filter((relationship) => Boolean(relationship));
+    }
+    /** Every field a query reads across its filter, sort, projection, group and aggregate clauses. */
+    getQueryFields(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return [];
+        }
+        const fields = new Set();
+        for (const expression of queryExpressions(query)) {
+            for (const fieldId of expressionFieldIds(expression)) {
+                fields.add(fieldId);
+            }
+        }
+        return [...fields];
+    }
+    /**
+     * Actions that may invalidate a query's results when they commit — conservatively, every
+     * action that writes a state holding an entity the query reads, or that mutates a
+     * provider-backed row of one (spec 0.10 §73-74). Over-inclusion is acceptable; a
+     * known-stale result is not (spec §72).
+     */
+    getActionsInvalidatingQuery(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return [];
+        }
+        const readEntities = new Set(this.queryReadEntities(query));
+        return this.graph.getNodesByKind('action').filter((action) => {
+            for (const edge of this.graph.getOutgoingEdges(action.id, { kinds: WRITE_KINDS })) {
+                if (readEntities.has(edge.to)) {
+                    return true; // a provider-record write links the action straight to the entity
+                }
+                const target = this.graph.getNode(edge.to);
+                if (target?.kind !== 'state') {
+                    continue;
+                }
+                const holds = this.graph
+                    .getOutgoingEdges(target.id, { kinds: ['references'] })
+                    .some((reference) => readEntities.has(reference.to));
+                if (holds) {
+                    return true;
+                }
+            }
+            return false;
+        });
+    }
+    /** The inverse: every query an action's commit may invalidate. */
+    getQueriesInvalidatedByAction(actionId) {
+        return this.listQueries().filter((query) => this.getActionsInvalidatingQuery(query.id).some((action) => action.id === actionId));
+    }
+    /**
+     * A structured explanation of a query — source, effective filter (with the read-policy
+     * conjunct called out), ordering with its identity tie-breaker, projection, pagination,
+     * the entities and fields it reads, and the actions that can invalidate it (spec §86).
+     */
+    explainQuery(id) {
+        const query = this.getQuery(id);
+        if (!query) {
+            return undefined;
+        }
+        const source = this.graph.getNode(query.source);
+        const identityTieBreaker = source?.kind === 'entity' ? source.identityFieldId : undefined;
+        return {
+            queryId: query.id,
+            source: query.source,
+            parameters: query.parameters ?? [],
+            ...(query.filter ? { filter: query.filter } : {}),
+            ...(this.getReadPolicyForQuery(id)
+                ? { readPolicyPredicate: this.getReadPolicyForQuery(id).predicate }
+                : {}),
+            sort: (query.sort ?? []).map((key) => ({
+                key: key.key,
+                direction: sortKeyDirection(key),
+                nulls: key.nulls ?? (sortKeyDirection(key) === 'asc' ? 'last' : 'first'),
+            })),
+            ...(identityTieBreaker ? { identityTieBreaker } : {}),
+            relationships: (query.relationships ?? []).flatMap((use) => {
+                const relationship = this.getRelationship(use.relationshipId);
+                return relationship
+                    ? [{ relationshipId: use.relationshipId, cardinality: relationship.cardinality, bindAs: use.bindAs }]
+                    : [];
+            }),
+            ...(query.projection
+                ? { projection: { entityId: query.projection.entityId, fields: query.projection.fields.map((field) => field.id) } }
+                : {}),
+            aggregates: query.aggregate ?? [],
+            groupBy: query.groupBy ?? [],
+            pagination: {
+                strategy: query.pagination?.strategy ?? 'cursor',
+                maxPageSize: query.pagination?.maxPageSize ?? 100,
+            },
+            entities: this.queryReadEntities(query),
+            fields: this.getQueryFields(id),
+            invalidatingActions: this.getActionsInvalidatingQuery(id).map((action) => action.id),
+        };
+    }
     constraintTouches(constraint, fieldIds) {
         const declared = this.graph
             .getOutgoingEdges(constraint.id, { kinds: ['constrains'] })

package/package.json

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