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

package/dist/api.d.ts

@@ -1,12 +1,22 @@
-import type { ApplicationGraph, SchemaDiff, ValidationResult } from '@cynodia/axiom-core';
+import type { ApplicationGraph, SchemaDiff, SemanticDiff, ServerIRContract, ValidationResult } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import type { ChangeSet } from './changes.js';
+import type { GraphChange } from './changes.js';
 import type { MigrationImpact, SchemaInspection } from './migration.js';
 import type { DistributedSemanticsInspection } from './distributed.js';
 import type { LiveQueryAnalysis } from './live-query.js';
 import type { WorkflowAnalysis } from './workflow.js';
 import type { AuthorizationAnalysis } from './authorization.js';
+import type { InventoryQuery, SemanticInventory } from './inventory.js';
+import { explainDependency, transitiveDependencies, transitiveDependents } from './dependencies.js';
+import type { DependencyProvenance, TransitiveDependencyResult } from './dependencies.js';
+import { explainAction, explainQueryFull, explainState, explainWorkflowFull } from './explain.js';
+import type { ActionExplanation, FullQueryExplanation, FullWorkflowExplanation, GraphSummary, StateExplanation } from './explain.js';
+import type { CapabilityAnalysis } from './capabilities.js';
+import type { NativeOperationOccurrence, NativeOperationSummary } from './native-operations.js';
+import type { AuthorizationDecisionExplanation, AuthorizationDecisionRequest } from './authorization-decision.js';
+import type { GraphEditRequest, GraphEditResult } from './graph-edit.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -70,5 +80,61 @@ export declare class AgentAPI extends PresentationQueries {
      * runtime secret. Live decisions are the authority's job (`AUTHORIZATION_DENIED`).
      */
     analyzeAuthorization(): AuthorizationAnalysis;
+    /** Every graph node, by id and kind, with dependency/dependent counts (spec16 §9-11, §113-115). */
+    inventory(query?: InventoryQuery): SemanticInventory;
+    /** Every node transitively reachable from `id` by following outgoing edges (spec16 §12-13). */
+    getTransitiveDependencies(id: Parameters<typeof transitiveDependencies>[1], kinds?: Parameters<typeof transitiveDependencies>[2]): TransitiveDependencyResult;
+    /** Every node that transitively depends on `id` (spec16 §12-13). */
+    getTransitiveDependents(id: Parameters<typeof transitiveDependents>[1], kinds?: Parameters<typeof transitiveDependents>[2]): TransitiveDependencyResult;
+    /** Why a dependency edge exists between two nodes (spec16 §14). */
+    explainDependency(from: Parameters<typeof explainDependency>[1], to: Parameters<typeof explainDependency>[2]): DependencyProvenance | undefined;
+    /** A structured explanation of an `ActionDef`: reads, writes, effects, authorization, invokers (spec16 §17). */
+    explainAction(actionId: Parameters<typeof explainAction>[1]): ActionExplanation | undefined;
+    /** A structured explanation of a `StateDef`: type, persistence, readers, writers, constraints (spec16 §21). */
+    explainState(stateId: Parameters<typeof explainState>[1]): StateExplanation | undefined;
+    /** `explainQuery` plus its authorization surface and live-query capability (spec16 §18). */
+    explainQuery(queryId: Parameters<typeof explainQueryFull>[1]): FullQueryExplanation | undefined;
+    /** `analyzeWorkflow` plus its authorization surface (spec16 §19-20). */
+    explainWorkflow(workflowId: Parameters<typeof explainWorkflowFull>[1]): FullWorkflowExplanation;
+    /** A structural, domain-neutral graph summary: counts, executable roots, security boundaries (spec16 §161-162). */
+    explainGraph(): GraphSummary;
+    /** Required runtime/provider capabilities, with provenance for each (spec16 §30-31, §50-51). */
+    analyzeCapabilities(): CapabilityAnalysis;
+    /** Every `NativeOperation` in the graph — the one boundary static analysis cannot see through (spec16 §46-49). */
+    listNativeOperations(): NativeOperationOccurrence[];
+    /** How many `NativeOperation`s exist, and how many are fully opaque (spec16 §49). */
+    summarizeNativeOperations(): NativeOperationSummary;
+    /**
+     * A concrete authorization decision, evaluated through the same evaluator the authority
+     * uses, with zero mutation and zero effect (spec16 §26, §136-141). Advisory only — the
+     * real operation always re-authorizes on the authority (spec16 §138).
+     */
+    explainAuthorizationDecision(request: AuthorizationDecisionRequest): AuthorizationDecisionExplanation | undefined;
+    /** The Server IR contract this graph currently requires (spec16 §32-33, §122). */
+    requiredServerContract(): ServerIRContract;
+    /**
+     * The canonical semantic difference between `other` and this graph: added/removed/changed
+     * nodes classified into categories, plus compatibility impact — does it move
+     * `semanticFingerprint`, `schemaFingerprint`, or the required Server IR contract
+     * (spec16 §34-38, §150-160).
+     */
+    semanticDiff(other: ApplicationGraph): SemanticDiff;
+    /**
+     * Propose a structured, portable edit set against a private clone: check preconditions,
+     * apply, validate, and compute the semantic diff — all without mutating this graph
+     * (spec16 §79-87). Accept a valid result with {@link acceptEdit}.
+     */
+    proposeEdit(request: GraphEditRequest): GraphEditResult;
+    /**
+     * Commits a previously-proposed, valid candidate into this graph and records it in the
+     * change history — the only way a `proposeEdit` result becomes live (spec16 §145).
+     * Refuses a result that did not validate; re-validates the candidate as a defensive check
+     * against a candidate built by hand.
+     */
+    acceptEdit(result: GraphEditResult, options?: {
+        reason?: string;
+        actor?: string;
+    }): ChangeSet;
 }
+export type { GraphChange };
 //# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -1,4 +1,4 @@
-import { diffSchema, validateGraph } from '@cynodia/axiom-core';
+import { diffSchema, randomHex, requiredServerContractForGraph, semanticDiff as computeSemanticDiff, validateGraph } from '@cynodia/axiom-core';
 import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import { inspectSchema, migrationImpact } from './migration.js';
@@ -6,6 +6,13 @@ import { inspectDistributedSemantics } from './distributed.js';
 import { analyzeLiveQuery } from './live-query.js';
 import { analyzeWorkflow } from './workflow.js';
 import { analyzeAuthorization } from './authorization.js';
+import { semanticInventory } from './inventory.js';
+import { explainDependency, transitiveDependencies, transitiveDependents } from './dependencies.js';
+import { explainAction, explainGraph, explainQueryFull, explainState, explainWorkflowFull } from './explain.js';
+import { analyzeCapabilities } from './capabilities.js';
+import { listNativeOperations, summarizeNativeOperations } from './native-operations.js';
+import { explainAuthorizationDecision } from './authorization-decision.js';
+import { proposeGraphEdit } from './graph-edit.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
@@ -95,4 +102,107 @@ export class AgentAPI extends PresentationQueries {
     analyzeAuthorization() {
         return analyzeAuthorization(this.graph);
     }
+    // ------------------------------------------------------------------ spec16: inspection
+    /** Every graph node, by id and kind, with dependency/dependent counts (spec16 §9-11, §113-115). */
+    inventory(query) {
+        return semanticInventory(this.graph, query);
+    }
+    /** Every node transitively reachable from `id` by following outgoing edges (spec16 §12-13). */
+    getTransitiveDependencies(id, kinds) {
+        return transitiveDependencies(this.graph, id, kinds);
+    }
+    /** Every node that transitively depends on `id` (spec16 §12-13). */
+    getTransitiveDependents(id, kinds) {
+        return transitiveDependents(this.graph, id, kinds);
+    }
+    /** Why a dependency edge exists between two nodes (spec16 §14). */
+    explainDependency(from, to) {
+        return explainDependency(this.graph, from, to);
+    }
+    /** A structured explanation of an `ActionDef`: reads, writes, effects, authorization, invokers (spec16 §17). */
+    explainAction(actionId) {
+        return explainAction(this.graph, actionId);
+    }
+    /** A structured explanation of a `StateDef`: type, persistence, readers, writers, constraints (spec16 §21). */
+    explainState(stateId) {
+        return explainState(this.graph, stateId);
+    }
+    /** `explainQuery` plus its authorization surface and live-query capability (spec16 §18). */
+    explainQuery(queryId) {
+        return explainQueryFull(this.graph, queryId);
+    }
+    /** `analyzeWorkflow` plus its authorization surface (spec16 §19-20). */
+    explainWorkflow(workflowId) {
+        return explainWorkflowFull(this.graph, workflowId);
+    }
+    /** A structural, domain-neutral graph summary: counts, executable roots, security boundaries (spec16 §161-162). */
+    explainGraph() {
+        return explainGraph(this.graph);
+    }
+    /** Required runtime/provider capabilities, with provenance for each (spec16 §30-31, §50-51). */
+    analyzeCapabilities() {
+        return analyzeCapabilities(this.graph);
+    }
+    /** Every `NativeOperation` in the graph — the one boundary static analysis cannot see through (spec16 §46-49). */
+    listNativeOperations() {
+        return listNativeOperations(this.graph);
+    }
+    /** How many `NativeOperation`s exist, and how many are fully opaque (spec16 §49). */
+    summarizeNativeOperations() {
+        return summarizeNativeOperations(this.graph);
+    }
+    /**
+     * A concrete authorization decision, evaluated through the same evaluator the authority
+     * uses, with zero mutation and zero effect (spec16 §26, §136-141). Advisory only — the
+     * real operation always re-authorizes on the authority (spec16 §138).
+     */
+    explainAuthorizationDecision(request) {
+        return explainAuthorizationDecision(this.graph, request);
+    }
+    /** The Server IR contract this graph currently requires (spec16 §32-33, §122). */
+    requiredServerContract() {
+        return requiredServerContractForGraph(this.graph);
+    }
+    /**
+     * The canonical semantic difference between `other` and this graph: added/removed/changed
+     * nodes classified into categories, plus compatibility impact — does it move
+     * `semanticFingerprint`, `schemaFingerprint`, or the required Server IR contract
+     * (spec16 §34-38, §150-160).
+     */
+    semanticDiff(other) {
+        return computeSemanticDiff(other, this.graph);
+    }
+    /**
+     * Propose a structured, portable edit set against a private clone: check preconditions,
+     * apply, validate, and compute the semantic diff — all without mutating this graph
+     * (spec16 §79-87). Accept a valid result with {@link acceptEdit}.
+     */
+    proposeEdit(request) {
+        return proposeGraphEdit(this.graph, request);
+    }
+    /**
+     * Commits a previously-proposed, valid candidate into this graph and records it in the
+     * change history — the only way a `proposeEdit` result becomes live (spec16 §145).
+     * Refuses a result that did not validate; re-validates the candidate as a defensive check
+     * against a candidate built by hand.
+     */
+    acceptEdit(result, options = {}) {
+        if (!result.applied || !result.candidate) {
+            throw new Error('acceptEdit: refusing to accept an edit that did not validate');
+        }
+        const revalidated = validateGraph(result.candidate);
+        if (!revalidated.valid) {
+            throw new Error('acceptEdit: the candidate no longer validates');
+        }
+        this.graph.restore(result.candidate.toJSON());
+        const change = {
+            id: `change_${randomHex(6)}`,
+            timestamp: Date.now(),
+            operations: [],
+            ...(options.reason ? { reason: options.reason } : {}),
+            ...(options.actor ? { actor: options.actor } : {}),
+        };
+        this.changeLog.push(change);
+        return change;
+    }
 }

package/dist/authorization-decision.d.ts

@@ -0,0 +1,33 @@
+import { type ApplicationGraph, type AuthorizationOperation, type NodeId } from '@cynodia/axiom-core';
+/**
+ * Concrete authorization decision explanation (spec16 §26, §136-141), evaluated through the
+ * **same** canonical, security-absence-aware evaluator the authority uses
+ * (`evaluateAuthorizationExpression` / `decideAuthorization`, spec15pt3) — never a second,
+ * tooling-only interpretation (spec16 §197). It performs no mutation, no provider call and no
+ * effect: it is a pure function of the policy expression and the supplied principal /
+ * resource, exactly like an ordinary static analysis (spec16 §133, §136).
+ *
+ * This is advisory. The real operation always re-authorizes on the authority; a prior
+ * tooling result is never a token (spec16 §138).
+ */
+export interface AuthorizationDecisionRequest {
+    actionId?: NodeId;
+    queryId?: NodeId;
+    principal?: Record<string, unknown> | null;
+    resource?: Record<string, unknown> | null;
+}
+export interface AuthorizationPartResult {
+    evaluated: boolean;
+    ok?: boolean;
+    value?: unknown;
+}
+export interface AuthorizationDecisionExplanation {
+    operation: AuthorizationOperation;
+    decision: 'ALLOW' | 'DENY';
+    reason: string;
+    policyId: string | null;
+    policyResult: AuthorizationPartResult | null;
+    legacyResult: AuthorizationPartResult | null;
+}
+export declare function explainAuthorizationDecision(graph: ApplicationGraph, request: AuthorizationDecisionRequest): AuthorizationDecisionExplanation | undefined;
+//# sourceMappingURL=authorization-decision.d.ts.map

package/dist/authorization-decision.js

@@ -0,0 +1,58 @@
+import { decideAuthorization, evaluateAuthorizationExpression, } from '@cynodia/axiom-core';
+function partResult(part) {
+    return { evaluated: true, ok: part.ok, ...(part.ok ? { value: part.value } : {}) };
+}
+export function explainAuthorizationDecision(graph, request) {
+    let operation;
+    let policyId;
+    let legacyExpression;
+    if (request.actionId !== undefined) {
+        const action = graph.getNode(request.actionId);
+        if (!action || action.kind !== 'action')
+            return undefined;
+        operation = 'action.invoke';
+        policyId = action.authorizationPolicy;
+        legacyExpression = action.authorization;
+    }
+    else if (request.queryId !== undefined) {
+        const query = graph.getNode(request.queryId);
+        if (!query || query.kind !== 'query')
+            return undefined;
+        operation = 'query.read';
+        policyId = query.authorizationPolicy;
+    }
+    else {
+        return undefined;
+    }
+    const context = { principal: request.principal ?? null, resource: request.resource ?? null, operation };
+    let policyPart;
+    let policyResult = null;
+    if (policyId !== undefined) {
+        const policy = graph.getNode(policyId);
+        policyPart = policy && policy.kind === 'authorization-policy'
+            ? evaluateAuthorizationExpression(policy.allow, context, 'policy')
+            : { ok: false };
+        policyResult = partResult(policyPart);
+    }
+    let legacyPart;
+    let legacyResult = null;
+    if (legacyExpression !== undefined) {
+        // Static analysis has no running StateDef to resolve a legacy expression's external
+        // refs against, so an id outside the closed PRINCIPAL/RESOURCE/OPERATION scope fails
+        // closed here exactly as it would with no resolver at runtime (spec15pt3).
+        legacyPart = evaluateAuthorizationExpression(legacyExpression, context, 'legacy-action');
+        legacyResult = partResult(legacyPart);
+    }
+    const result = decideAuthorization({
+        ...(policyPart ? { policy: policyPart } : {}),
+        ...(legacyPart ? { legacy: legacyPart } : {}),
+    });
+    return {
+        operation,
+        decision: result.decision,
+        reason: result.reason,
+        policyId: policyId ?? null,
+        policyResult,
+        legacyResult,
+    };
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,24 @@
+import type { ApplicationGraph } from '@cynodia/axiom-core';
+/**
+ * Required-runtime-capability analysis (spec16 §30-31, §50-51). A graph declares no host or
+ * provider; it requires *capability domains* — the closed vocabulary a conforming
+ * `AxiomServer` already reasons about (persistence, coordination, durable workflow storage,
+ * a scheduler, mutation observation for live queries, …). This module answers "what would
+ * a runtime need to execute this graph", with the provenance for each requirement (spec16
+ * §31), never a specific provider brand (spec16 §51).
+ */
+export declare const REQUIRED_CAPABILITIES: readonly ["persistence", "coordination", "mutation-observation", "live-queries", "workflow-store", "event-journal", "scheduler", "effect-execution", "provider-transaction", "blob-storage", "subscription-adapter"];
+export type RequiredCapability = (typeof REQUIRED_CAPABILITIES)[number];
+export interface CapabilityRequirement {
+    capability: RequiredCapability;
+    required: boolean;
+    /** Why this capability is or is not required — structural, not a guess (spec16 §31). */
+    reasons: string[];
+}
+export interface CapabilityAnalysis {
+    requirements: CapabilityRequirement[];
+    /** Only the capabilities this graph actually requires. */
+    requiredCapabilities: RequiredCapability[];
+}
+export declare function analyzeCapabilities(graph: ApplicationGraph): CapabilityAnalysis;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.js

@@ -0,0 +1,90 @@
+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
+ * provider; it requires *capability domains* — the closed vocabulary a conforming
+ * `AxiomServer` already reasons about (persistence, coordination, durable workflow storage,
+ * a scheduler, mutation observation for live queries, …). This module answers "what would
+ * a runtime need to execute this graph", with the provenance for each requirement (spec16
+ * §31), never a specific provider brand (spec16 §51).
+ */
+export const REQUIRED_CAPABILITIES = [
+    'persistence',
+    'coordination',
+    'mutation-observation',
+    'live-queries',
+    'workflow-store',
+    'event-journal',
+    'scheduler',
+    'effect-execution',
+    'provider-transaction',
+    'blob-storage',
+    'subscription-adapter',
+];
+export function analyzeCapabilities(graph) {
+    const reasons = new Map();
+    const require = (capability, reason) => {
+        const list = reasons.get(capability) ?? [];
+        list.push(reason);
+        reasons.set(capability, list);
+    };
+    const actions = graph.getNodesByKind('action');
+    const workflows = graph.getNodesByKind('workflow');
+    const queries = graph.getNodesByKind('query');
+    const triggers = graph.getNodesByKind('trigger');
+    const subscriptions = graph.getNodesByKind('subscription');
+    const storages = graph.getNodesByKind('storage');
+    const serverStates = graph.getNodesByKind('state').filter((s) => (s.authority ?? 'client') === 'server');
+    if (serverStates.length > 0) {
+        require('persistence', `server-authoritative StateDef: ${serverStates.map((s) => s.id).sort().join(', ')}`);
+    }
+    if (queries.length > 0) {
+        require('persistence', `QueryDef reads authoritative data through a DataProvider: ${queries.map((q) => q.id).sort().join(', ')}`);
+        require('provider-transaction', `QueryDef/provider-record mutation requires a transactional provider: ${queries.map((q) => q.id).sort().join(', ')}`);
+    }
+    if (workflows.length > 0) {
+        require('persistence', `WorkflowDef instances are durable state: ${workflows.map((w) => w.id).sort().join(', ')}`);
+        require('coordination', `WorkflowDef instance ownership is a fenced, leased claim: ${workflows.map((w) => w.id).sort().join(', ')}`);
+        require('workflow-store', `WorkflowDef requires a durable WorkflowStore: ${workflows.map((w) => w.id).sort().join(', ')}`);
+        for (const workflow of workflows) {
+            const events = graph.getOutgoingEdges(workflow.id, { kinds: ['references'] }).filter((e) => graph.getNode(e.to)?.kind === 'event');
+            if (events.length > 0) {
+                require('event-journal', `WorkflowDef ${workflow.id} waits on an event, requiring the durable event journal`);
+            }
+        }
+    }
+    const timedTriggers = triggers.filter((t) => t.when.kind === 'interval' || t.when.kind === 'delay');
+    if (timedTriggers.length > 0) {
+        require('scheduler', `timed TriggerDef: ${timedTriggers.map((t) => t.id).sort().join(', ')}`);
+        require('coordination', `a distributed scheduler must fence duplicate firings: ${timedTriggers.map((t) => t.id).sort().join(', ')}`);
+    }
+    for (const query of queries) {
+        const capability = analyzeLiveQuery(graph, query.id).capability;
+        if (capability.capability !== 'not-live-capable') {
+            require('live-queries', `QueryDef ${query.id} is ${capability.capability}`);
+            require('mutation-observation', `QueryDef ${query.id} is live-capable and needs commit revision observation`);
+        }
+    }
+    for (const action of actions) {
+        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(', ')})`);
+        }
+    }
+    if (storages.length > 0) {
+        require('blob-storage', `StorageDef: ${storages.map((s) => s.id).sort().join(', ')}`);
+    }
+    if (subscriptions.length > 0) {
+        require('subscription-adapter', `SubscriptionDef: ${subscriptions.map((s) => s.id).sort().join(', ')}`);
+        require('coordination', `SubscriptionDef cursor ownership is a fenced claim: ${subscriptions.map((s) => s.id).sort().join(', ')}`);
+    }
+    const requirements = REQUIRED_CAPABILITIES.map((capability) => ({
+        capability,
+        required: reasons.has(capability),
+        reasons: reasons.get(capability) ?? [],
+    }));
+    return {
+        requirements,
+        requiredCapabilities: requirements.filter((r) => r.required).map((r) => r.capability),
+    };
+}

package/dist/dependencies.d.ts

@@ -0,0 +1,25 @@
+import type { ApplicationGraph, EdgeKind, GraphEdge, NodeId } from '@cynodia/axiom-core';
+/**
+ * Transitive dependency/dependent analysis and edge provenance (spec16 §12-14). Cycle-safe
+ * — a graph edge can form a cycle (a workflow branch, a mutual `invoke`) and this must still
+ * terminate with a deterministic, canonically-ordered answer (spec16 §13).
+ */
+export interface TransitiveDependencyResult {
+    root: string;
+    /** Ids reachable from the root, canonically sorted, root excluded. */
+    ids: string[];
+}
+/** Every node transitively reachable by following outgoing edges from `root` (spec16 §13). */
+export declare function transitiveDependencies(graph: ApplicationGraph, root: NodeId, kinds?: readonly EdgeKind[]): TransitiveDependencyResult;
+/** Every node that transitively depends on `root`, by following incoming edges (spec16 §13). */
+export declare function transitiveDependents(graph: ApplicationGraph, root: NodeId, kinds?: readonly EdgeKind[]): TransitiveDependencyResult;
+export interface DependencyProvenance {
+    from: string;
+    to: string;
+    edges: GraphEdge[];
+    /** One rendered reason per edge, structural rather than free prose (spec16 §14). */
+    reasons: string[];
+}
+/** Why a dependency edge exists between two nodes, in structural (not fabricated) terms (spec16 §14). */
+export declare function explainDependency(graph: ApplicationGraph, from: NodeId, to: NodeId): DependencyProvenance | undefined;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/dependencies.js

@@ -0,0 +1,61 @@
+function walk(graph, root, kinds, direction) {
+    const seen = new Set([root]);
+    const found = [];
+    let frontier = [root];
+    while (frontier.length > 0) {
+        const next = [];
+        for (const id of frontier) {
+            const edges = direction === 'out'
+                ? graph.getOutgoingEdges(id, kinds ? { kinds } : {})
+                : graph.getIncomingEdges(id, kinds ? { kinds } : {});
+            for (const edge of edges) {
+                const neighbour = direction === 'out' ? edge.to : edge.from;
+                if (!seen.has(neighbour)) {
+                    seen.add(neighbour);
+                    found.push(neighbour);
+                    next.push(neighbour);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return found.sort();
+}
+/** Every node transitively reachable by following outgoing edges from `root` (spec16 §13). */
+export function transitiveDependencies(graph, root, kinds) {
+    return { root: String(root), ids: walk(graph, root, kinds, 'out') };
+}
+/** Every node that transitively depends on `root`, by following incoming edges (spec16 §13). */
+export function transitiveDependents(graph, root, kinds) {
+    return { root: String(root), ids: walk(graph, root, kinds, 'in') };
+}
+function renderReason(graph, edge) {
+    const fromNode = graph.getNode(edge.from);
+    const toNode = graph.getNode(edge.to);
+    const fieldIds = edge.metadata?.fieldIds ?? [];
+    const fields = fieldIds.length > 0 ? ` (fields: ${[...fieldIds].sort().join(', ')})` : '';
+    const fromDesc = fromNode ? `${fromNode.kind} ${edge.from}` : String(edge.from);
+    const toDesc = toNode ? `${toNode.kind} ${edge.to}` : String(edge.to);
+    const verbs = {
+        reads: 'reads',
+        writes: 'writes',
+        invokes: 'invokes',
+        renders: 'renders',
+        binds: 'binds into',
+        'depends-on': 'depends on',
+        'derives-from': 'derives from',
+        constrains: 'constrains',
+        'routes-to': 'routes to',
+        references: 'references',
+        contains: 'contains',
+    };
+    return `${fromDesc} ${verbs[edge.kind] ?? edge.kind} ${toDesc}${fields}`;
+}
+/** Why a dependency edge exists between two nodes, in structural (not fabricated) terms (spec16 §14). */
+export function explainDependency(graph, from, to) {
+    const edges = graph.getOutgoingEdges(from, {}).filter((edge) => edge.to === to);
+    if (edges.length === 0) {
+        return undefined;
+    }
+    return { from: String(from), to: String(to), edges, reasons: edges.map((edge) => renderReason(graph, edge)) };
+}

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.d.ts

@@ -0,0 +1,125 @@
+import { type ApplicationGraph, type NativeEffect, type NodeId, type StatePersistence, type TypeRef } from '@cynodia/axiom-core';
+import type { QueryExplanation } from './queries.js';
+import type { OperationProtection } from './authorization.js';
+import type { WorkflowAnalysis } from './workflow.js';
+import type { LiveQueryAnalysis } from './live-query.js';
+/**
+ * Structured, machine-readable explanations of the semantic nodes an agent most often needs
+ * to reason about before proposing a change (spec16 §17-21, §28-29). Every field here is
+ * derived from the graph's own edges and node data — never from re-reading application
+ * source — and an incomplete answer says so explicitly rather than presenting itself as
+ * exhaustive (spec16 §16, §29, §102, §103).
+ */
+export interface ActionExplanation {
+    actionId: string;
+    name?: string;
+    parameters: Array<{
+        id: string;
+        required: boolean;
+        valueType?: TypeRef;
+    }>;
+    /** States this action may read, and the specific fields where known. */
+    reads: {
+        stateIds: string[];
+        fieldIds: string[];
+    };
+    /** States this action may write, and the specific fields where known. */
+    writes: {
+        stateIds: string[];
+        fieldIds: string[];
+    };
+    /** Other actions this action invokes directly (an `invoke` operation). */
+    invokesActions: string[];
+    /** Integration operations this action calls, split by query/effect mode. */
+    integrationQueries: string[];
+    integrationEffects: string[];
+    /** Registered `QueryDef`s this action runs via a `query` operation. */
+    runsQueries: string[];
+    /** Object stores this action reads, commits into, or deletes from. */
+    storages: string[];
+    /** Native operations embedded in this action, with their declared effects. */
+    nativeOperations: Array<{
+        implementationId: string;
+        declaredEffects: NativeEffect[];
+    }>;
+    /** How `action.invoke` is protected. */
+    authorization: OperationProtection;
+    /** Entity constraints and transition constraints that can refuse this action's write. */
+    constraintsThatMayBlock: {
+        constraints: string[];
+        transitionConstraints: string[];
+    };
+    /** What can cause this action to run other than a direct client invocation. */
+    invokedBy: {
+        triggers: string[];
+        workflowSteps: string[];
+    };
+    clientInvocable: boolean;
+    systemOnly: boolean;
+    destructive: boolean;
+    /** False when a native operation without declared effects prevents a complete answer. */
+    analysisComplete: boolean;
+    analysisGaps: string[];
+}
+export declare function explainAction(graph: ApplicationGraph, actionId: NodeId): ActionExplanation | undefined;
+export interface StateExplanation {
+    stateId: string;
+    name?: string;
+    valueType: TypeRef;
+    derived: boolean;
+    draft: boolean;
+    ephemeral: boolean;
+    authority: 'client' | 'server';
+    serverOnly: boolean;
+    persistence: StatePersistence;
+    hasInitialValue: boolean;
+    /** Nodes that read this state: views, derived state, action conditions and reads. */
+    readers: string[];
+    /** Actions that mutate this state. */
+    writers: string[];
+    /** Entities this state's type holds instances of. */
+    entities: string[];
+    constraints: string[];
+    transitionConstraints: string[];
+}
+export declare function explainState(graph: ApplicationGraph, stateId: NodeId): StateExplanation | undefined;
+export interface FullQueryExplanation extends QueryExplanation {
+    authorization: OperationProtection;
+    liveCapability: LiveQueryAnalysis['capability']['capability'];
+}
+/** `explainQuery` plus the authorization surface and live-query capability (spec16 §18). */
+export declare function explainQueryFull(graph: ApplicationGraph, queryId: NodeId): FullQueryExplanation | undefined;
+export interface FullWorkflowExplanation extends WorkflowAnalysis {
+    startPolicyId: string | null;
+    instanceAccessPolicyId: string | null;
+    actionAuthorization: Array<{
+        actionId: string;
+        protection: OperationProtection;
+    }>;
+    privilegeReviewActions: string[];
+}
+/** `analyzeWorkflow` plus its authorization surface — start policy, instance access, and each step action's protection (spec16 §19). */
+export declare function explainWorkflowFull(graph: ApplicationGraph, workflowId: NodeId): FullWorkflowExplanation;
+export interface GraphSummary {
+    nodeCountsByKind: Record<string, number>;
+    executableRoots: {
+        actions: string[];
+        workflows: string[];
+        queries: string[];
+    };
+    securityBoundaries: {
+        protectedActions: number;
+        publicActions: number;
+        protectedQueries: number;
+        publicQueries: number;
+    };
+    externalCapabilities: {
+        integrations: number;
+        subscriptions: number;
+        storages: number;
+    };
+    opaqueBoundaries: number;
+}
+/** A structural, domain-neutral graph summary (spec16 §161-162): counts and roots, never invented business prose. */
+export declare function explainGraph(graph: ApplicationGraph): GraphSummary;
+//# sourceMappingURL=explain.d.ts.map