@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/{intents → internal/intents}/graph/intent.graph.execute.js

@@ -1,24 +1,26 @@
 /**
  * Intent graph, stage 4 and the read fast path.
  */
-import { normalizeIntentDescription } from "../intent.proposal.js";
+import { buildManualAssignmentMetadata } from "../../shared/assignment/network-assignment.policy.js";
 import { timed } from "../../shared/observability/performance.js";
-import { enforceIntentActionBoundary, generateIntentEmbedding, logger, toSpeechActType } from "./intent.graph.shared.js";
+import { enforceIntentActionBoundary, generateIntentEmbedding, normalizeIntentDescription, isExplicitUpdateRequest, logger, toSpeechActType } from "./intent.graph.shared.js";
 /**
  * Node 4: Executor
  * Executes reconciler actions against the database.
  */
 export async function executorNode(state, deps) {
     return timed("IntentGraph.executor", async () => {
-        const actions = enforceIntentActionBoundary(state.operationMode, state.targetIntentIds, state.actions ?? []);
+        const actions = enforceIntentActionBoundary(isExplicitUpdateRequest(state), state.targetIntentIds, state.actions ?? []);
         if (actions.length === 0) {
             return { executionResults: [] };
         }
         logger.verbose('Executing actions', { count: actions.length });
         const results = [];
+        let transitionResult;
         const scopeEnvelope = state.scopeType && state.scopeId
             ? { scopeType: state.scopeType, scopeId: state.scopeId }
             : {};
+        const networkScopeId = state.scopeType === 'network' ? state.scopeId : undefined;
         const verifiedIntentByPayload = new Map();
         for (const verifiedIntent of state.verifiedIntents) {
             verifiedIntentByPayload.set(verifiedIntent.description, verifiedIntent);
@@ -29,37 +31,43 @@ export async function executorNode(state, deps) {
             try {
                 if (actionType === 'create') {
                     const createAction = action;
-                    const sanitizedPayload = normalizeIntentDescription(createAction.payload);
-                    const matchedVerifiedIntent = verifiedIntentByPayload.get(createAction.payload) ||
-                        verifiedIntentByPayload.get(sanitizedPayload);
-                    // Generate embedding for the intent payload
-                    const flatEmbedding = await generateIntentEmbedding(deps, sanitizedPayload);
+                    const payload = createAction.payload;
+                    const metadata = createAction.metadata;
+                    const flatEmbedding = await generateIntentEmbedding(deps, payload);
                     const created = await deps.database.createIntent({
                         userId: state.userId,
-                        payload: sanitizedPayload,
-                        confidence: createAction.score ? createAction.score / 100 : 1.0,
+                        payload,
+                        confidence: 1.0,
                         inferenceType: 'explicit',
                         sourceType: 'discovery_form',
                         embedding: flatEmbedding,
-                        semanticEntropy: createAction.semanticEntropy ??
-                            matchedVerifiedIntent?.verification?.semantic_entropy ??
-                            null,
-                        referentialAnchor: createAction.referentialAnchor ??
-                            matchedVerifiedIntent?.verification?.referential_anchor ??
-                            null,
-                        felicityAuthority: matchedVerifiedIntent?.verification?.felicity_scores.authority ?? null,
-                        felicitySincerity: matchedVerifiedIntent?.verification?.felicity_scores.sincerity ?? null,
-                        felicityClarity: matchedVerifiedIntent?.verification?.felicity_scores.clarity ?? null,
-                        intentMode: createAction.intentMode ?? null,
-                        speechActType: toSpeechActType(matchedVerifiedIntent?.verification?.classification),
+                        semanticEntropy: metadata?.semanticEntropy ?? null,
+                        referentialAnchor: metadata?.referentialAnchor ?? null,
+                        felicityAuthority: metadata?.felicityAuthority ?? null,
+                        felicitySincerity: metadata?.felicitySincerity ?? null,
+                        felicityClarity: metadata?.felicityClarity ?? null,
+                        intentMode: metadata?.intentMode ?? null,
+                        speechActType: metadata?.speechActType ?? null,
+                    });
+                    const linkedNetworkIds = await linkIntentToNetworks(deps, state, created.id);
+                    results.push({
+                        actionType: 'create',
+                        success: true,
+                        intentId: created.id,
+                        payload,
+                        linkedNetworkIds,
                     });
-                    results.push({ actionType: 'create', success: true, intentId: created.id, payload: sanitizedPayload });
-                    logger.verbose('Created intent', { intentId: created.id });
-                    deps.intentQueue?.addGenerateHydeJob({
+                    logger.verbose('Created intent', { intentId: created.id, linkedNetworkIds });
+                    if (!metadata && deps.intentFollowUp) {
+                        void Promise.resolve().then(() => deps.intentFollowUp.scoreIntent({
+                            intentId: created.id, userId: state.userId, payload,
+                        })).catch((error) => logger.error('Intent rescoring failed; saved intent retained', { intentId: created.id, error }));
+                    }
+                    deps.intentFollowUp?.onIntentSaved({
                         intentId: created.id,
                         userId: state.userId,
                         ...scopeEnvelope,
-                    }).catch((err) => logger.error('Failed to enqueue intent HyDE job', { intentId: created.id, error: err }));
+                    }).catch((err) => logger.error('Failed to run intent follow-up', { intentId: created.id, error: err }));
                 }
                 else if (actionType === 'update') {
                     const updateAction = action;
@@ -94,11 +102,11 @@ export async function executorNode(state, deps) {
                     });
                     logger.verbose('Updated intent', { intentId: updateAction.id });
                     if (updated) {
-                        deps.intentQueue?.addGenerateHydeJob({
+                        deps.intentFollowUp?.onIntentSaved({
                             intentId: updateAction.id,
                             userId: state.userId,
                             ...scopeEnvelope,
-                        }).catch((err) => logger.error('Failed to enqueue intent HyDE job', { intentId: updateAction.id, error: err }));
+                        }).catch((err) => logger.error('Failed to run intent follow-up', { intentId: updateAction.id, error: err }));
                     }
                 }
                 else if (actionType === 'expire') {
@@ -112,9 +120,89 @@ export async function executorNode(state, deps) {
                     });
                     logger.verbose('Archived intent', { intentId: expireAction.id });
                     if (result.success) {
-                        deps.intentQueue?.addDeleteHydeJob({ intentId: expireAction.id }).catch((err) => logger.error('Failed to enqueue intent HyDE delete job', { intentId: expireAction.id, error: err }));
+                        try {
+                            await deps.database.deleteIntentNetworkAssociations(expireAction.id);
+                        }
+                        catch (err) {
+                            logger.error('Failed to delete intent-network associations', { intentId: expireAction.id, error: err });
+                        }
+                        try {
+                            const expiredCount = await deps.database.expireOpportunitiesByIntentActor(expireAction.id);
+                            if (expiredCount > 0) {
+                                logger.verbose('Expired opportunities referencing intent', { intentId: expireAction.id, expiredCount });
+                            }
+                        }
+                        catch (err) {
+                            logger.error('Failed to expire opportunities', { intentId: expireAction.id, error: err });
+                        }
+                        deps.intentFollowUp?.onIntentArchived({ intentId: expireAction.id }).catch((err) => logger.error('Failed to run intent archive follow-up', { intentId: expireAction.id, error: err }));
                     }
                 }
+                else if (actionType === 'transition') {
+                    const transitionAction = action;
+                    const dbResult = await deps.database.transitionIntentLifecycle({
+                        intentId: transitionAction.id,
+                        userId: state.userId,
+                        status: transitionAction.status,
+                        networkScopeId,
+                    });
+                    let outcome;
+                    if (dbResult.kind !== 'success' || dbResult.status === 'PAUSED') {
+                        outcome = dbResult;
+                    }
+                    else {
+                        try {
+                            await deps.intentFollowUp?.onIntentResumed({
+                                intentId: dbResult.id,
+                                userId: state.userId,
+                                lifecycleVersionMs: dbResult.lifecycleVersionMs,
+                            });
+                            outcome = dbResult;
+                        }
+                        catch (err) {
+                            logger.warn('Failed to enqueue resumed intent discovery', {
+                                intentId: dbResult.id,
+                                lifecycleVersionMs: dbResult.lifecycleVersionMs,
+                                changed: dbResult.changed,
+                                error: err,
+                            });
+                            if (!dbResult.changed) {
+                                outcome = { kind: 'enqueue_failed', id: dbResult.id, status: dbResult.status, lifecycleVersionMs: dbResult.lifecycleVersionMs };
+                            }
+                            else {
+                                let authoritative = null;
+                                try {
+                                    authoritative = await deps.database.compensateFailedResume({
+                                        intentId: transitionAction.id,
+                                        userId: state.userId,
+                                        lifecycleVersionMs: dbResult.lifecycleVersionMs,
+                                        networkScopeId,
+                                    });
+                                }
+                                catch (compensationError) {
+                                    logger.error('Failed to compensate resumed intent after enqueue failure', {
+                                        intentId: transitionAction.id,
+                                        lifecycleVersionMs: dbResult.lifecycleVersionMs,
+                                        compensationError,
+                                    });
+                                }
+                                outcome = {
+                                    kind: 'enqueue_failed',
+                                    id: dbResult.id,
+                                    status: (authoritative?.status ?? dbResult.status),
+                                    lifecycleVersionMs: authoritative?.lifecycleVersionMs ?? dbResult.lifecycleVersionMs,
+                                };
+                            }
+                        }
+                    }
+                    transitionResult = outcome;
+                    results.push({
+                        actionType: 'transition',
+                        success: outcome.kind === 'success',
+                        intentId: 'id' in outcome ? outcome.id : transitionAction.id,
+                        error: outcome.kind !== 'success' ? outcome.kind : undefined,
+                    });
+                }
             }
             catch (error) {
                 logger.error('Failed to execute action', { actionType: action.type, error });
@@ -126,9 +214,40 @@ export async function executorNode(state, deps) {
                 });
             }
         }
-        return { executionResults: results };
+        return { executionResults: results, transitionResult };
     });
 }
+/**
+ * Link a freshly created intent to exactly the networks the caller named.
+ *
+ * Nothing is scored or inferred: each id must still be an accepted membership,
+ * which {@link IntentGraphDatabase.assignIntentToNetworkIfMember} checks while
+ * holding the membership row. A network the caller no longer belongs to is
+ * skipped and logged rather than failing the create.
+ *
+ * @returns The subset of ids that ended up linked.
+ */
+async function linkIntentToNetworks(deps, state, intentId) {
+    const requested = state.networkIds ?? [];
+    if (requested.length === 0)
+        return [];
+    const metadata = buildManualAssignmentMetadata({
+        resourceType: 'intent',
+        source: 'intent-create',
+        createdAt: new Date().toISOString(),
+    });
+    const linked = [];
+    for (const networkId of requested) {
+        const outcome = await deps.database.assignIntentToNetworkIfMember(state.userId, intentId, networkId, metadata.finalScore, metadata.metadata);
+        if (outcome.kind === 'assigned' || outcome.kind === 'already_assigned') {
+            linked.push(networkId);
+        }
+        else {
+            logger.warn('Intent network link rejected', { intentId, networkId, outcome: outcome.kind });
+        }
+    }
+    return linked;
+}
 /**
  * Node: Query
  * Fast-path read node — fetches intents from DB based on scope.
@@ -145,14 +264,14 @@ export async function queryNode(state, deps) {
         });
         try {
             // Scope-aware default: caller's intents across all reachable networks.
-            // Triggered when the tool layer passed indexScope and did not pick a
+            // Triggered when the host passed networkScope and did not pick a
             // specific networkId or queryUserId — i.e. "my intents" in a chat
-            // where the agent's reach is more than one index.
+            // where the agent's reach is more than one network.
             if (!state.queryUserId &&
                 !state.networkId &&
-                state.indexScope &&
-                state.indexScope.length > 0) {
-                const intents = await deps.database.getActiveIntentsAcrossIndexes(state.userId, state.indexScope);
+                state.networkScope &&
+                state.networkScope.length > 0) {
+                const intents = await deps.database.getActiveIntentsAcrossNetworks(state.userId, state.networkScope);
                 if (intents.length === 0) {
                     return {
                         readResult: {
@@ -175,37 +294,37 @@ export async function queryNode(state, deps) {
                 };
             }
             // When allUserIntents is true, ignore network scope and return all
-            const effectiveIndexId = state.allUserIntents ? undefined : state.networkId;
-            if (effectiveIndexId) {
+            const effectiveNetworkId = state.allUserIntents ? undefined : state.networkId;
+            if (effectiveNetworkId) {
                 // Verify membership
-                const isMember = await deps.database.isNetworkMember(effectiveIndexId, state.userId);
+                const isMember = await deps.database.isNetworkMember(effectiveNetworkId, state.userId);
                 if (!isMember) {
                     return {
                         readResult: {
                             count: 0,
                             intents: [],
-                            message: "Index not found or you are not a member.",
+                            message: "Network not found or you are not a member.",
                         },
                     };
                 }
                 // Network-scoped read
                 if (!state.queryUserId) {
-                    // All intents in the index (any member can see)
-                    const intents = await deps.database.getNetworkIntentsForMember(effectiveIndexId, state.userId, { limit: 50, offset: 0 });
+                    // All intents in the network (any member can see)
+                    const intents = await deps.database.getNetworkIntentsForMember(effectiveNetworkId, state.userId, { limit: 50, offset: 0 });
                     if (intents.length === 0) {
                         return {
                             readResult: {
                                 count: 0,
                                 intents: [],
                                 message: "No intents in this network yet.",
-                                networkId: effectiveIndexId,
+                                networkId: effectiveNetworkId,
                             },
                         };
                     }
                     return {
                         readResult: {
                             count: intents.length,
-                            networkId: effectiveIndexId,
+                            networkId: effectiveNetworkId,
                             intents: intents.map((i) => ({
                                 id: i.id,
                                 description: i.payload,
@@ -217,9 +336,9 @@ export async function queryNode(state, deps) {
                         },
                     };
                 }
-                // Specific user's intents in the index
+                // Specific user's intents in the network
                 const effectiveUserId = state.queryUserId;
-                const intents = await deps.database.getIntentsInIndexForMember(effectiveUserId, effectiveIndexId);
+                const intents = await deps.database.getIntentsInNetworkForMember(effectiveUserId, effectiveNetworkId);
                 if (intents.length === 0) {
                     return {
                         readResult: {
@@ -228,7 +347,7 @@ export async function queryNode(state, deps) {
                             message: effectiveUserId === state.userId
                                 ? "You don't have any intents in this network yet."
                                 : "No intents for that user in this network.",
-                            networkId: effectiveIndexId,
+                            networkId: effectiveNetworkId,
                         },
                     };
                 }
@@ -237,7 +356,7 @@ export async function queryNode(state, deps) {
                 return {
                     readResult: {
                         count: intents.length,
-                        networkId: effectiveIndexId,
+                        networkId: effectiveNetworkId,
                         intents: intents.map((i) => ({
                             id: i.id,
                             description: i.payload,

package/dist/internal/intents/graph/intent.graph.infer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Intent graph preparation and explicit update inference.
+ */
+import type { DebugMetaAgent } from "../../../protocol/core.js";
+import { type IntentGraphDeps, type IntentState } from "./intent.graph.shared.js";
+/**
+ * Validate that the input shape selects exactly one route. Returns an error
+ * message when it doesn't; undefined when the shape is valid.
+ *
+ * Never infer destruction from a missing field: `targetIntentIds` alone
+ * (no content, no archive, no status) is an input error, not a silent no-op.
+ */
+export declare function validateInputShape(state: IntentState): string | undefined;
+/**
+ * Node 0: Prep
+ * Validates the input route and loads active IDs for existing-intent operations.
+ * Creation does not inspect or reconcile existing intents.
+ */
+export declare function prepNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    trace: {
+        node: string;
+        detail: string;
+    }[];
+    error?: string | undefined;
+    activeIntentIds: string[];
+}>;
+/**
+ * Node 1: Inference
+ * Extracts intents from raw content. Only reached on the content path
+ * (see {@link afterPrepRoute}), so `inputContent` is always defined here.
+ * Passes conversation context for anaphoric resolution.
+ */
+export declare function inferenceNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    inferredIntents: {
+        reasoning: string;
+        type: "goal" | "tombstone";
+        confidence: "low" | "medium" | "high";
+        description: string;
+    }[];
+    agentTimings: DebugMetaAgent[];
+    trace: {
+        node: string;
+        detail: string;
+    }[];
+}>;
+/** Prepare an unprepared create, or reuse host authorization for the final edited text. */
+export declare function preparationNode(state: IntentState, deps: IntentGraphDeps): Promise<{
+    preparationResult: {
+        status: "needs_revision";
+        payload: string;
+        feedback: string;
+        recovery: import("../intent.preparer.js").RecoveryField[];
+    };
+    actions: never[];
+    validationFailures: {
+        category: "vague_or_invalid";
+        message: string;
+    }[];
+    preparation?: undefined;
+    trace?: undefined;
+} | {
+    preparation: import("../intent.preparer.js").PreparedIntent;
+    preparationResult: {
+        status: "ready";
+        payload: string;
+        metadata: import("../intent.admission.js").IntentSemanticMetadata;
+    } | undefined;
+    actions: {
+        type: "create";
+        payload: string;
+        metadata: import("../intent.admission.js").IntentSemanticMetadata | null;
+    }[];
+    trace: {
+        node: string;
+        detail: string;
+    }[];
+    validationFailures?: undefined;
+}>;

package/dist/internal/intents/graph/intent.graph.infer.js

@@ -0,0 +1,122 @@
+/**
+ * Intent graph preparation and explicit update inference.
+ */
+import { timed } from "../../shared/observability/performance.js";
+import { requestContext } from "../../shared/observability/request-context.js";
+import { logger } from "./intent.graph.shared.js";
+/**
+ * Validate that the input shape selects exactly one route. Returns an error
+ * message when it doesn't; undefined when the shape is valid.
+ *
+ * Never infer destruction from a missing field: `targetIntentIds` alone
+ * (no content, no archive, no status) is an input error, not a silent no-op.
+ */
+export function validateInputShape(state) {
+    const hasContent = state.inputContent !== undefined;
+    const hasTargets = !!state.targetIntentIds?.length;
+    const hasArchive = state.archive === true;
+    const hasStatus = state.status !== undefined;
+    const routeCount = [hasContent, hasArchive, hasStatus].filter(Boolean).length;
+    if (routeCount > 1) {
+        return 'Intent graph input selected more than one route: content, archive, and status are mutually exclusive.';
+    }
+    if (hasTargets && !hasContent && !hasArchive && !hasStatus) {
+        return 'targetIntentIds requires inputContent (update), archive, or status.';
+    }
+    if (hasArchive && !hasTargets) {
+        return 'archive requires targetIntentIds.';
+    }
+    if (hasStatus && !hasTargets) {
+        return 'status requires targetIntentIds.';
+    }
+    return undefined;
+}
+/**
+ * Node 0: Prep
+ * Validates the input route and loads active IDs for existing-intent operations.
+ * Creation does not inspect or reconcile existing intents.
+ */
+export async function prepNode(state, deps) {
+    return timed("IntentGraph.prep", async () => {
+        logger.verbose("Starting preparation phase", {
+            hasContent: !!state.inputContent,
+            targetIntentIds: state.targetIntentIds,
+            archive: state.archive,
+            status: state.status,
+            networkId: state.networkId,
+        });
+        const validationError = validateInputShape(state);
+        // Creation never loads existing intents: explicit creation cannot merge them.
+        const activeIntents = state.inputContent !== undefined && !state.targetIntentIds?.length
+            ? []
+            : await deps.database.getActiveIntents(state.userId);
+        logger.verbose("Fetched active intents", {
+            count: activeIntents.length,
+        });
+        return {
+            activeIntentIds: activeIntents.map((intent) => intent.id),
+            ...(validationError ? { error: validationError } : {}),
+            trace: [{
+                    node: "prep",
+                    detail: `Fetched ${activeIntents.length} active intent(s)`,
+                }],
+        };
+    });
+}
+/**
+ * Node 1: Inference
+ * Extracts intents from raw content. Only reached on the content path
+ * (see {@link afterPrepRoute}), so `inputContent` is always defined here.
+ * Passes conversation context for anaphoric resolution.
+ */
+export async function inferenceNode(state, deps) {
+    return timed("IntentGraph.inference", async () => {
+        logger.verbose("Starting inference", {
+            contentPreview: state.inputContent?.substring(0, 50),
+            hasConversationContext: !!state.conversationContext,
+            conversationMessagesCount: state.conversationContext?.length || 0
+        });
+        const agentTimingsAccum = [];
+        const _traceEmitterInferrer = requestContext.getStore()?.traceEmitter;
+        const inferrerStart = Date.now();
+        _traceEmitterInferrer?.({ type: "agent_start", name: "intent-inferrer" });
+        const result = await deps.inferrer.invoke(state.inputContent ?? null, state.userProfile, {
+            conversationContext: state.conversationContext
+        });
+        agentTimingsAccum.push({ name: 'intent.inferrer', durationMs: Date.now() - inferrerStart });
+        _traceEmitterInferrer?.({ type: "agent_end", name: "intent-inferrer", durationMs: Date.now() - inferrerStart, summary: result.intents.length > 0 ? `Extracted ${result.intents.length} intent(s)` : "intent-inferrer completed" });
+        logger.verbose("Inference complete", {
+            inferredCount: result.intents.length,
+        });
+        const descriptions = result.intents.map(i => i.description).slice(0, 3);
+        const truncated = result.intents.length > 3 ? `... +${result.intents.length - 3} more` : "";
+        return {
+            inferredIntents: result.intents,
+            agentTimings: agentTimingsAccum,
+            trace: [{
+                    node: "inference",
+                    detail: result.intents.length === 0
+                        ? "No intents extracted"
+                        : `Extracted ${result.intents.length}: ${descriptions.map(d => `"${d.slice(0, 50)}${d.length > 50 ? '...' : ''}"`).join(", ")}${truncated}`,
+                }],
+        };
+    });
+}
+/** Prepare an unprepared create, or reuse host authorization for the final edited text. */
+export async function preparationNode(state, deps) {
+    const result = state.preparation ? undefined : await deps.preparer.invoke({ payload: state.inputContent }, state.userProfile);
+    if (result?.status === "needs_revision") {
+        return {
+            preparationResult: result,
+            actions: [],
+            validationFailures: [{ category: "vague_or_invalid", message: result.feedback }],
+        };
+    }
+    const preparation = state.preparation ?? { metadata: result.metadata };
+    return {
+        preparation,
+        preparationResult: result,
+        actions: [{ type: "create", payload: state.inputContent, metadata: preparation.metadata }],
+        trace: [{ node: "preparation", detail: state.preparation ? "Reused approved preparation" : "Description passed admission" }],
+    };
+}

package/dist/internal/intents/graph/intent.graph.js

@@ -0,0 +1,108 @@
+/**
+ * Intent graph: prepare/create, or explicitly read, update, archive, and transition.
+ *
+ * Every node is a top-level function in a sibling module, taking the graph
+ * state and an explicit {@link IntentGraphDeps}. This file composes the
+ * dependency bag and wires the edges — nothing else.
+ */
+import { StateGraph, START, END } from "@langchain/langgraph";
+import { ExplicitIntentInferrer } from "../intent.inferrer.js";
+import { SemanticVerifier } from "../intent.verifier.js";
+import { IntentPreparer } from "../intent.preparer.js";
+import { IntentGraphState } from "./intent.graph.state.js";
+import { logger } from "./intent.graph.shared.js";
+import { inferenceNode, preparationNode, prepNode } from "./intent.graph.infer.js";
+import { reconciliationNode, verificationNode } from "./intent.graph.reconcile.js";
+import { executorNode, queryNode } from "./intent.graph.execute.js";
+export { buildExplicitUpdateActions, enforceIntentActionBoundary, isExplicitUpdateRequest } from "./intent.graph.shared.js";
+export class IntentGraphFactory {
+    constructor(database, embedder, intentFollowUp, agents) {
+        this.deps = {
+            database,
+            embedder,
+            intentFollowUp,
+            inferrer: agents?.inferrer ?? new ExplicitIntentInferrer(),
+            verifier: agents?.verifier ?? new SemanticVerifier(),
+            preparer: new IntentPreparer(agents?.verifier),
+        };
+    }
+    createGraph() {
+        const deps = this.deps;
+        return new StateGraph(IntentGraphState)
+            .addNode("prep", (state) => prepNode(state, deps))
+            .addNode("prepareCreation", (state) => preparationNode(state, deps))
+            .addNode("query", (state) => queryNode(state, deps))
+            .addNode("inference", (state) => inferenceNode(state, deps))
+            .addNode("verification", (state) => verificationNode(state, deps))
+            .addNode("reconciler", (state) => reconciliationNode(state))
+            .addNode("executor", (state) => executorNode(state, deps))
+            // The graph routes on the shape of its input (see intent.graph.state.ts):
+            // - READ:      no content/target → prep → query → END (no LLM calls)
+            // - CREATE:    inputContent only → prep → preparation → executor → END
+            // - UPDATE:    inputContent + targetIntentIds → prep → inference → verification → reconciler → executor
+            // - ARCHIVE:   targetIntentIds + archive → prep → reconciler → executor → END (no LLM)
+            // - TRANSITION: targetIntentIds + status → prep → reconciler → executor → END (no LLM)
+            .addEdge(START, "prep")
+            // Create prepares once; update infers; read/archive/status need no models.
+            .addConditionalEdges("prep", afterPrepRoute, {
+            query: "query",
+            inference: "inference",
+            prepareCreation: "prepareCreation",
+            reconciler: "reconciler",
+            __end__: END,
+        })
+            // Query (read mode) always ends
+            .addEdge("query", END)
+            .addEdge("prepareCreation", "executor")
+            // After inference: decide if we need verification (skip if no intents)
+            .addConditionalEdges("inference", shouldRunVerification, {
+            verification: "verification",
+            reconciler: "reconciler",
+        })
+            // Verification always continues to reconciliation
+            .addEdge("verification", "reconciler")
+            // Reconciliation always goes to executor
+            .addEdge("reconciler", "executor")
+            // Executor is always the end
+            .addEdge("executor", END)
+            .compile();
+    }
+}
+/**
+ * After prep: an invalid input shape or a failed precondition ends the
+ * graph; a fully-empty input is a read; archive/status skip straight to
+ * the reconciler (no LLM); otherwise the content path infers.
+ */
+export function afterPrepRoute(state) {
+    if (state.error) {
+        logger.warn('Prep failed with error, short-circuiting to END', { error: state.error });
+        return '__end__';
+    }
+    const hasContent = state.inputContent !== undefined;
+    const hasArchive = state.archive === true;
+    const hasStatus = state.status !== undefined;
+    if (!hasContent && !hasArchive && !hasStatus) {
+        logger.verbose('No content/target - routing to query (read fast path)');
+        return 'query';
+    }
+    if (hasArchive || hasStatus) {
+        logger.verbose('Deterministic route (archive/status) - skipping inference');
+        return 'reconciler';
+    }
+    if (!state.targetIntentIds?.length)
+        return 'prepareCreation';
+    logger.verbose('Explicit update - running inference');
+    return 'inference';
+}
+/**
+ * Determines if verification should run. Skipped when inference produced
+ * no candidates: the (empty) reconciler pass still runs so the graph
+ * reports "nothing to do" consistently.
+ */
+export function shouldRunVerification(state) {
+    if (state.inferredIntents.length === 0) {
+        logger.verbose('No intents to verify - skipping verification, routing to reconciliation');
+        return 'reconciler';
+    }
+    return 'verification';
+}