@indexnetwork/protocol 19.0.0-rc.482.1 → 20.0.0-rc.484.1

package/CHANGELOG.md

@@ -20,6 +20,36 @@ went 6.7.1 → 8.0.2 with no 7.x in between because the whole 7.x line shipped a
 prereleases between the two promotions. To track every change, read `rc`; to
 pin a supported release, use `latest`.
 
+## 20.0.0 - 2026-08-17
+
+### Changed
+
+- **BREAKING**: The communities capability ships as one class, `Networks`,
+  mirroring `Intents`. `NetworkGraphFactory`, `NetworkMembershipGraphFactory`
+  and `IntentNetworkGraphFactory` are no longer exported from the package root;
+  construct `new Networks({ database, indexer })` and call `createGraph()`,
+  `createMembershipGraph()` or `createAssignmentGraph()`. `createNetworkTools`
+  is now `Networks.createTools`. Graph behaviour is unchanged.
+
+  ```typescript
+  // before
+  const indexGraph = new NetworkGraphFactory(database).createGraph();
+  const membershipGraph = new NetworkMembershipGraphFactory(database).createGraph();
+  const assignmentGraph = new IntentNetworkGraphFactory(database, intents).createGraph();
+
+  // after
+  const networks = new Networks({ database, indexer: intents });
+  const indexGraph = networks.createGraph();
+  const membershipGraph = networks.createMembershipGraph();
+  const assignmentGraph = networks.createAssignmentGraph();
+  ```
+
+- `networks/` is flat: the `application/`, `domain/` and `ports/` directories are
+  gone, and `network.module.ts` is the capability's only public surface.
+  `NetworkToolDeps` now comes from that module rather than
+  `networks/ports/communities.tools.port.ts`, and the narrowed indexer port is
+  exported as `IntentNetworkIndexer`.
+
 ## 19.0.0 - 2026-08-17
 
 ### Removed

package/IMPLEMENTATION.md

@@ -148,9 +148,6 @@ import {
   PremiseGraphFactory,
   NegotiationGraphFactory,
   HydeGraphFactory,
-  NetworkGraphFactory,
-  NetworkMembershipGraphFactory,
-  IntentNetworkGraphFactory,
   RadarGraphFactory,
   MaintenanceGraphFactory,
 } from "@indexnetwork/protocol";
@@ -159,8 +156,9 @@ import {
 Each factory takes its typed dependencies in the constructor and exposes a
 `.createGraph()` method that returns a compiled LangGraph ready for `.invoke()`.
 
-The intent lifecycle graph is the exception: it is reached through the `Intents`
-module rather than a factory of its own (see [Intents](#intents) below).
+The intent and community graphs are the exceptions: they are reached through the
+`Intents` and `Networks` module classes rather than factories of their own (see
+[Intents](#intents) and [Networks](#networks) below).
 
 | Factory | Workflow |
 |---|---|
@@ -170,9 +168,6 @@ module rather than a factory of its own (see [Intents](#intents) below).
 | `PremiseGraphFactory` | Decompose and index a user's premises |
 | `NegotiationGraphFactory` | Multi-turn bilateral negotiation flows |
 | `HydeGraphFactory` | Generate hypothetical documents and embed them (cache-aware) |
-| `NetworkGraphFactory` | Manage network/network CRUD |
-| `NetworkMembershipGraphFactory` | Manage network/network member join/leave |
-| `IntentNetworkGraphFactory` | Evaluate and assign/unassign intents to indexes |
 | `RadarGraphFactory` | Build the radar view: flat presenter-card list, optionally intent-scoped |
 | `MaintenanceGraphFactory` | Periodic maintenance (feed health, opportunity expiration) |
 
@@ -213,12 +208,34 @@ first use, so an unused method costs nothing.
 | `Intents.normalizeDescription(description)` | Normalize a description to its persisted form |
 | `Intents.FALLBACK_INTAKE_QUESTION` | The static round-1 question used when generation is unavailable |
 
-`IntentNetworkGraphFactory` takes an `Intents` instance as its evaluator:
+## Networks
+
+Communities ship the same way: one class covering the community lifecycle graph,
+the membership graph, signal↔community assignment, and the agent-facing
+community tools.
 
 ```typescript
-const intentNetworkGraph = new IntentNetworkGraphFactory(database, intents).createGraph();
+import { Networks } from "@indexnetwork/protocol";
+
+const networks = new Networks({
+  database,          // community, roster, and assignment persistence
+  indexer: intents,  // an `Intents` instance — scores a signal against a community
+});
 ```
 
+Both dependencies are optional; each method names what it requires, so a host
+that only registers tools can construct `new Networks()` with nothing.
+
+| Method | Purpose |
+|---|---|
+| `createGraph()` | Compile the community lifecycle graph — create, read, update, delete. Requires `database` |
+| `createMembershipGraph()` | Compile the roster graph — add, list, remove members. Requires `database` |
+| `createAssignmentGraph()` | Compile signal↔community assignment, direct or model-evaluated. Requires `database` and `indexer` |
+| `Networks.createTools(defineTool, deps)` | Register the agent-facing community tools |
+
+Assignment takes an `Intents` instance as its evaluator — the `indexer`
+dependency is narrowed to the single `indexIntent` method it calls.
+
 ## MCP server
 
 The package exports a factory that registers every chat tool over the Model Context Protocol and attaches a canonical `instructions` block (`MCP_INSTRUCTIONS`) that every connecting runtime follows. The factory takes three arguments:

package/dist/index.d.ts

@@ -39,9 +39,8 @@ export { REPORTER_PERSONA_ID, REPORTER_PERSONA, REPORTER_BRIEFING_KICKOFF, } fro
 export { ONBOARDING_PERSONA_ID, ONBOARDING_PERSONA, } from "./agents/index.js";
 export { RadarGraphFactory } from "./opportunities/index.js";
 export { HydeGraphFactory } from "./discovery/index.js";
-export { NetworkGraphFactory } from "./networks/index.js";
-export { NetworkMembershipGraphFactory } from "./networks/index.js";
-export { IntentNetworkGraphFactory } from "./networks/index.js";
+export { Networks } from "./networks/network.module.js";
+export type { IntentNetworkIndexer, NetworksDeps, NetworkToolDeps, } from "./networks/network.module.js";
 export { Intents } from "./intents/intent.module.js";
 export type { FollowUpPlan, FollowUpPlanInput, IntakeAnswer, IntakePack, IntakePackInput, IntakePackQuestion, IntakePackQuestionOption, IntakeRound, IntentIndexerOutput, IntentsDeps, IntentToolDeps, SynthesisInput, SynthesisResult, } from "./intents/intent.module.js";
 export { MaintenanceGraphFactory } from "./maintenance/maintenance.graph.js";

package/dist/index.js

@@ -35,9 +35,10 @@ export { REPORTER_PERSONA_ID, REPORTER_PERSONA, REPORTER_BRIEFING_KICKOFF, } fro
 export { ONBOARDING_PERSONA_ID, ONBOARDING_PERSONA, } from "./agents/index.js";
 export { RadarGraphFactory } from "./opportunities/index.js";
 export { HydeGraphFactory } from "./discovery/index.js";
-export { NetworkGraphFactory } from "./networks/index.js";
-export { NetworkMembershipGraphFactory } from "./networks/index.js";
-export { IntentNetworkGraphFactory } from "./networks/index.js";
+// ─── Networks ─────────────────────────────────────────────────────────────────
+// The whole capability behind one class: the community lifecycle graph, the
+// membership graph, signal assignment, and the agent-facing tools.
+export { Networks } from "./networks/network.module.js";
 // ─── Intents ──────────────────────────────────────────────────────────────────
 // The whole capability behind one class: lifecycle graph, verification,
 // network indexing, guided intake, and the agent-facing tools.

package/dist/networks/{application/indexer.graph.d.ts → indexer.graph.d.ts}

@@ -1,7 +1,14 @@
-import type { IntentNetworkGraphDatabase } from "../ports/index.js";
-import type { DebugMetaAgent } from "../../agents/index.js";
-import type { IntentNetworkIndexer } from "../ports/index.js";
+import type { IntentNetworkGraphDatabase } from "../shared/interfaces/database.interface.js";
+import type { DebugMetaAgent } from "../agents/index.js";
+import type { Intents } from "../intents/intent.module.js";
 import { IntentNetworkGraphState, type AssignmentResult } from "./indexer.state.js";
+/**
+ * The one intents method assignment calls: score a signal against a network.
+ *
+ * Naming the single method rather than accepting the whole capability keeps the
+ * injected surface auditable, and lets a test pass a one-method stub.
+ */
+export type IntentNetworkIndexer = Pick<Intents, "indexIntent">;
 /**
  * Factory class to build and compile the Intent–Network (indexer) Graph.
  *
@@ -12,7 +19,7 @@ import { IntentNetworkGraphState, type AssignmentResult } from "./indexer.state.
  *
  * ## Signal assignment policy
  *
- * The indexer is injected at construction time via the communities ports layer,
+ * The indexer is injected at construction time as {@link IntentNetworkIndexer},
  * which narrows the intents module to the one method used here — this factory
  * never reaches intents internals directly.
  *
@@ -40,9 +47,6 @@ import { IntentNetworkGraphState, type AssignmentResult } from "./indexer.state.
  *   read: readNode → END
  *   delete: unassignNode → END
  * }
- *
- * IND-546: canonical home — previously network/indexer/indexer.graph.ts.
- * Signals dependency consumed via capabilities/signals.facade.ts (through ports).
  */
 /** The graph's channel state, as every node sees it. */
 export type IntentNetworkState = typeof IntentNetworkGraphState.State;

package/dist/networks/{application/indexer.graph.js → indexer.graph.js}

@@ -1,9 +1,9 @@
 import { StateGraph, START, END } from "@langchain/langgraph";
-import { buildNetworkAssignmentDecision } from "../../shared/assignment/network-assignment.policy.js";
-import { protocolLogger } from "../../shared/observability/protocol.logger.js";
-import { timed } from "../../shared/observability/performance.js";
-import { requestContext } from "../../shared/observability/request-context.js";
-import { renderNetworkContext } from "../../shared/network/metadata.renderer.js";
+import { buildNetworkAssignmentDecision } from "../shared/assignment/network-assignment.policy.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+import { timed } from "../shared/observability/performance.js";
+import { requestContext } from "../shared/observability/request-context.js";
+import { renderNetworkContext } from "../shared/network/metadata.renderer.js";
 import { IntentNetworkGraphState } from "./indexer.state.js";
 const logger = protocolLogger("IntentNetworkGraphFactory");
 export class IntentNetworkGraphFactory {
@@ -141,7 +141,7 @@ export async function assignNode(state, deps) {
             const sourceName = intentForIndexing.sourceType
                 ? `${intentForIndexing.sourceType}:${intentForIndexing.sourceId ?? ""}`
                 : undefined;
-            // Score the signal against the network (intents module, injected via ports)
+            // Score the signal against the network (intents module, injected as IntentNetworkIndexer)
             const _traceEmitter = requestContext.getStore()?.traceEmitter;
             const _indexerStart = Date.now();
             _traceEmitter?.({ type: "agent_start", name: "intent-networker" });

package/dist/networks/{application/indexer.state.d.ts → indexer.state.d.ts}

@@ -1,9 +1,7 @@
-import type { DebugMetaAgent } from "../../agents/index.js";
+import type { DebugMetaAgent } from "../agents/index.js";
 /**
  * Intent payload and metadata loaded for network evaluation.
  * Loaded from the database before LLM-based assignment scoring.
- *
- * IND-546: canonical home — previously network/indexer/indexer.state.ts.
  */
 export interface IntentForIndexing {
     id: string;
@@ -15,8 +13,6 @@ export interface IntentForIndexing {
 /**
  * Index and member prompts for a single network (user must be member with autoAssign).
  * Used by the evaluated assignment path in IntentNetworkGraphFactory.
- *
- * IND-546: canonical home — previously network/indexer/indexer.state.ts.
  */
 export interface IndexMemberContext {
     networkId: string;
@@ -26,8 +22,6 @@ export interface IndexMemberContext {
 /**
  * Result of executing an assignment decision.
  * Returned from the assign node as a structured output alongside mutationResult.
- *
- * IND-546: canonical home — previously network/indexer/indexer.state.ts.
  */
 export interface AssignmentResult {
     networkId: string;
@@ -44,13 +38,13 @@ export interface AssignmentResult {
  * Two assignment paths, selected via `skipEvaluation`:
  * - `true` (direct / manual_override): writes the link immediately with a fixed
  *   score of 1 and mode `manual_override`.  No LLM call.
- * - `false` (automatic / evaluated): loads intent + network context, calls
- *   IntentIndexer from the signals public facade, then applies
- *   `buildNetworkAssignmentDecision` to produce the threshold / metadata.
- *   A no-prompt fast path skips the LLM when both prompts are absent.
+ * - `false` (automatic / evaluated): loads intent + network context, calls the
+ *   injected indexer, then applies `buildNetworkAssignmentDecision` to produce
+ *   the threshold / metadata. A no-prompt fast path skips the LLM when both
+ *   prompts are absent.
  *
- * The IntentIndexer is injected as a constructor argument — communities never
- * imports signals internals directly.
+ * The indexer is injected as a constructor argument — communities never imports
+ * signals internals directly.
  *
  * Flow:
  * START → router → {
@@ -58,10 +52,6 @@ export interface AssignmentResult {
  *   read: readNode → END
  *   delete: unassignNode → END
  * }
- *
- * IND-546: canonical home — previously network/indexer/indexer.state.ts.
- * LangGraph state carries IntentIndexerOutput and DebugMetaAgent which are
- * cross-capability types; this file therefore belongs in the application layer.
  */
 export declare const IntentNetworkGraphState: import("@langchain/langgraph").AnnotationRoot<{
     /** User performing the action. Always required. */

package/dist/networks/{application/indexer.state.js → indexer.state.js}

@@ -8,13 +8,13 @@ import { Annotation } from "@langchain/langgraph";
  * Two assignment paths, selected via `skipEvaluation`:
  * - `true` (direct / manual_override): writes the link immediately with a fixed
  *   score of 1 and mode `manual_override`.  No LLM call.
- * - `false` (automatic / evaluated): loads intent + network context, calls
- *   IntentIndexer from the signals public facade, then applies
- *   `buildNetworkAssignmentDecision` to produce the threshold / metadata.
- *   A no-prompt fast path skips the LLM when both prompts are absent.
+ * - `false` (automatic / evaluated): loads intent + network context, calls the
+ *   injected indexer, then applies `buildNetworkAssignmentDecision` to produce
+ *   the threshold / metadata. A no-prompt fast path skips the LLM when both
+ *   prompts are absent.
  *
- * The IntentIndexer is injected as a constructor argument — communities never
- * imports signals internals directly.
+ * The indexer is injected as a constructor argument — communities never imports
+ * signals internals directly.
  *
  * Flow:
  * START → router → {
@@ -22,10 +22,6 @@ import { Annotation } from "@langchain/langgraph";
  *   read: readNode → END
  *   delete: unassignNode → END
  * }
- *
- * IND-546: canonical home — previously network/indexer/indexer.state.ts.
- * LangGraph state carries IntentIndexerOutput and DebugMetaAgent which are
- * cross-capability types; this file therefore belongs in the application layer.
  */
 export const IntentNetworkGraphState = Annotation.Root({
     // --- Core Inputs (from ChatGraph via ToolContext) ---

package/dist/networks/{application/membership.graph.d.ts → membership.graph.d.ts}

@@ -1,5 +1,5 @@
-import type { NetworkMembershipGraphDatabase } from "../ports/index.js";
-import { NetworkMembershipGraphState } from "../domain/index.js";
+import type { NetworkMembershipGraphDatabase } from "../shared/interfaces/database.interface.js";
+import { NetworkMembershipGraphState } from "./membership.state.js";
 /**
  * Factory class to build and compile the Network Membership Graph.
  *
@@ -26,8 +26,6 @@ import { NetworkMembershipGraphState } from "../domain/index.js";
  *
  * Flow:
  * START → routerNode → {addMemberNode | listMembersNode | removeMemberNode} → END
- *
- * IND-546: canonical home — previously network/membership/membership.graph.ts.
  */
 /** The graph's channel state, as every node sees it. */
 export type NetworkMembershipState = typeof NetworkMembershipGraphState.State;

package/dist/networks/{application/membership.graph.js → membership.graph.js}

@@ -1,7 +1,7 @@
 import { StateGraph, START, END } from "@langchain/langgraph";
-import { protocolLogger } from "../../shared/observability/protocol.logger.js";
-import { timed } from "../../shared/observability/performance.js";
-import { NetworkMembershipGraphState } from "../domain/index.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+import { timed } from "../shared/observability/performance.js";
+import { NetworkMembershipGraphState } from "./membership.state.js";
 const logger = protocolLogger("NetworkMembershipGraphFactory");
 export class NetworkMembershipGraphFactory {
     constructor(database) {

package/dist/networks/{domain/membership.state.d.ts → membership.state.d.ts}

@@ -13,8 +13,6 @@
  *
  * Flow:
  * START → routerNode → {addMemberNode | listMembersNode | removeMemberNode} → END
- *
- * IND-546: canonical home — previously network/membership/membership.state.ts.
  */
 export declare const NetworkMembershipGraphState: import("@langchain/langgraph").AnnotationRoot<{
     /** User performing the action (the actor). Always required. */

package/dist/networks/{domain/membership.state.js → membership.state.js}

@@ -14,8 +14,6 @@ import { Annotation } from "@langchain/langgraph";
  *
  * Flow:
  * START → routerNode → {addMemberNode | listMembersNode | removeMemberNode} → END
- *
- * IND-546: canonical home — previously network/membership/membership.state.ts.
  */
 export const NetworkMembershipGraphState = Annotation.Root({
     // --- Core Inputs (from ChatGraph via ToolContext) ---

package/dist/networks/{application/network.graph.d.ts → network.graph.d.ts}

@@ -1,5 +1,5 @@
-import type { NetworkGraphDatabase } from "../ports/index.js";
-import { NetworkGraphState } from "../domain/index.js";
+import type { NetworkGraphDatabase } from "../shared/interfaces/database.interface.js";
+import { NetworkGraphState } from "./network.state.js";
 /**
  * Factory class to build and compile the Network (community) lifecycle graph.
  *
@@ -25,8 +25,6 @@ import { NetworkGraphState } from "../domain/index.js";
  *
  * Flow:
  * START → routerNode → {createNode | readNode | updateNode | deleteNode} → END
- *
- * IND-546: canonical home — previously network/network.graph.ts.
  */
 /** The graph's channel state, as every node sees it. */
 export type NetworkState = typeof NetworkGraphState.State;

package/dist/networks/{application/network.graph.js → network.graph.js}

@@ -1,7 +1,7 @@
 import { StateGraph, START, END } from "@langchain/langgraph";
-import { protocolLogger } from "../../shared/observability/protocol.logger.js";
-import { timed } from "../../shared/observability/performance.js";
-import { NetworkGraphState } from "../domain/index.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+import { timed } from "../shared/observability/performance.js";
+import { NetworkGraphState } from "./network.state.js";
 const logger = protocolLogger("NetworkGraphFactory");
 export class NetworkGraphFactory {
     constructor(database) {