@indexnetwork/protocol 4.3.1-rc.299.1 → 4.3.2-rc.300.1

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to `@indexnetwork/protocol` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+See [STABILITY.md](./STABILITY.md) for the public-contract and tier definitions.
+
+> History before `2.0.0` was reconstructed from git and is summarized rather than
+> itemized. From `2.0.0` onward, keep this file updated as part of every release
+> (bump `package.json` and the `[Unreleased]` section before promoting to `main`).
+
+## [Unreleased]
+
+### Changed
+- Reframed `README.md` as the public-facing Index Network Protocol document and moved package integration details into `IMPLEMENTATION.md`.
+- Included protocol documentation files in the published package tarball so README links remain available to package consumers.
+
+## [4.3.0] - 2026-06-21
+
+### Added
+- `STABILITY.md` defining the public contract, stability tiers (Stable vs
+  `@experimental`), SemVer policy, and the deprecation path.
+- Port-contract doc-comments on the `ChatSessionReader`, `DiscoveryRunStore`/
+  `DiscoveryRunQueue`, `EnrichmentRunStore`/`EnrichmentRunQueue`, and `Embedder`
+  interfaces (ownership scoping, null-vs-empty-array, lifecycle idempotency).
+- Tier annotations and an entry-point header in `src/index.ts`.
+
+### Changed
+- Replaced all `export type *` wildcard re-exports in `src/index.ts` with explicit
+  named exports so the public surface is fully enumerated and reviewable. No
+  symbols added or removed — the exported surface is unchanged.
+- Expanded `README.md` to document the full public surface (graph factories,
+  agents, MCP, tools) and link the stability policy.
+
+## [4.2.0] - 2026-06-19
+
+### Added
+- Opportunity legibility: cards explain *why* an opportunity surfaced.
+- Negotiation trace links on surfaced opportunities.
+
+## [4.1.0] - 2026-06
+
+### Added
+- Canonical user-context / enrichment MCP tools; `discoverySource` rename
+  (IND-372, IND-371, IND-374).
+- Context-derived `read_user_profiles` payload (IND-364).
+
+### Changed
+- Category A prompt consumers repointed at the global `user_context` (IND-361).
+- Premise pipeline ownership: dedup, LLM validity, richer provenance (IND-359).
+
+## [4.0.0] - 2026-06-18
+
+### Changed
+- **BREAKING:** Eliminated the "profile" concept — the pipeline, files, service,
+  controller, adapter, and exported types were renamed to `enrichment`
+  (`ProfileDocument` → `UserIdentity`, `read_user_profiles` returns a flat
+  identity+context payload, questioner `profile` mode → `enrichment`). Update any
+  imports of the removed `Profile*` exports. (IND-368)
+
+### Removed
+- **BREAKING:** `user_profiles` table and the profile generate/aggregate/save path
+  retired (IND-365).
+
+## [3.6.0] - 2026-06-12
+
+### Added
+- `read_pending_questions` MCP tool, registered in the tool registry.
+
+## [2.0.1] - 2026-06
+
+### Fixed
+- Post-`2.0.0` fixes and stabilization.
+
+## [2.0.0] - 2026-06-08
+
+### Changed
+- **BREAKING:** Removed `configureProtocol` startup call — model configuration is
+  read from the environment and `ModelConfig` is injected per-request via
+  `ToolContext`. See README for migration.
+
+## [1.0.0 - 1.23.3] - 2026-04 to 2026-06
+
+Pre-2.0 line: established the adapter-injected LangGraph architecture (chat,
+intent, opportunity, negotiation, premise, enrichment domains), the MCP server,
+the matching/opportunity/premise eval harnesses, premise source tracking and
+cascade retraction, network-scoped agents, and the agent registry. Reconstructed
+from git history; not itemized.
+
+[Unreleased]: https://github.com/indexnetwork/protocol/compare/v4.3.0...HEAD
+[4.3.0]: https://github.com/indexnetwork/protocol/compare/v4.2.0...v4.3.0
+[4.2.0]: https://github.com/indexnetwork/protocol/compare/v4.1.0...v4.2.0
+[4.1.0]: https://github.com/indexnetwork/protocol/compare/v4.0.0...v4.1.0
+[4.0.0]: https://github.com/indexnetwork/protocol/compare/v3.6.0...v4.0.0
+[3.6.0]: https://github.com/indexnetwork/protocol/compare/v2.0.1...v3.6.0
+[2.0.1]: https://github.com/indexnetwork/protocol/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/indexnetwork/protocol/releases/tag/v2.0.0

package/IMPLEMENTATION.md

@@ -0,0 +1,255 @@
+# @indexnetwork/protocol Implementation Guide
+
+This guide covers the technical package surface for implementers embedding the canonical Index Network Protocol implementation. For the public protocol overview, see [README.md](./README.md).
+
+The package implements LangGraph-based workflows for signal processing, opportunity discovery, negotiation, and chat — decoupled from any specific infrastructure via adapter injection.
+
+## Stability & versioning
+
+This package follows [Semantic Versioning](https://semver.org/). The **only**
+supported entry point is the package root (`import { ... } from "@indexnetwork/protocol"`);
+deep imports are not part of the contract. Every symbol is re-exported explicitly from
+`src/index.ts` and tagged with a stability tier:
+
+- **Stable** — interfaces, graph factories, agents, `createChatTools`, the
+  tool/runtime helpers, and shared schemas. Breaking changes require a major bump.
+- **Experimental** (`@experimental`) — advanced graph-state types and internal
+  helpers; may change in a minor release.
+
+See [STABILITY.md](./STABILITY.md) for the full policy and the deprecation path,
+and [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Install
+
+```bash
+npm install @indexnetwork/protocol
+```
+
+## Setup
+
+### 1. Configure the LLM
+
+The package reads `OPENROUTER_API_KEY` (required), `CHAT_MODEL`, and `CHAT_REASONING_EFFORT` from environment variables. No startup call is needed.
+
+To override the chat model or reasoning effort when using the built-in chat runtime (`ChatGraphFactory` / `ChatAgent`), pass `modelConfig` on `ToolContext`. `ChatAgent` reads these fields when the chat graph runs; the tools themselves do not consume `modelConfig`:
+
+```typescript
+import { createChatTools } from "@indexnetwork/protocol";
+
+const tools = await createChatTools({
+  // ... other deps ...
+  modelConfig: {
+    chatModel: "google/gemini-2.5-flash",       // optional — has a default
+    chatReasoningEffort: "low",                  // optional: minimal | low | medium | high | xhigh
+  },
+});
+```
+
+`apiKey` and `baseURL` can also be overridden this way. All other protocol agents (evaluators, generators, etc.) rely on `OPENROUTER_API_KEY` set in the environment regardless of `modelConfig`.
+
+### 2. Implement the adapters
+
+The package defines interfaces — your application provides the concrete implementations.
+
+**Required** (always needed by `createChatTools`):
+
+| Interface | Responsibility |
+|---|---|
+| `ChatGraphCompositeDatabase` | Core data access (users, intents, indexes/networks, opportunities) |
+| `UserDatabase` / `SystemDatabase` | Context-bound databases built by `createUserDatabase` / `createSystemDatabase` |
+| `Embedder` | Vector embeddings for semantic search |
+| `Scraper` | Web content extraction |
+| `Cache` / `HydeCache` | Result caching (HyDE may share the general cache) |
+| `IntegrationAdapter` | OAuth and external tool actions |
+| `IntentGraphQueue` | Background intent processing queue |
+| `ContactServiceAdapter` | Contact management |
+| `ChatSessionReader` | Load conversation history |
+| `ProfileEnricher` | Enrich profiles from external sources |
+| `NegotiationGraphDatabase` | Negotiation state persistence |
+
+**Optional** (enable specific capabilities; omit to run without that feature):
+
+| Interface | Responsibility |
+|---|---|
+| `AgentDatabase` | Agent registry CRUD (agents, transports, permissions) |
+| `AgentDispatcher` | Resolves and invokes personal agents during negotiation turns — required to register the negotiation tools |
+| `McpAuthResolver` | Resolves `{ userId, agentId }` from an incoming MCP HTTP request (MCP server only) |
+| `DeliveryLedger` | Commits OpenClaw opportunity-delivery rows |
+| `DiscoveryRunStore` / `DiscoveryRunQueue` | Persist and execute async MCP discovery runs |
+| `EnrichmentRunStore` / `EnrichmentRunQueue` | Persist and execute async MCP enrichment runs |
+| `MintConnectLink` | Mints short connect links for opportunity accepts |
+| `ChatSummaryReader` | Read-through chat-session digest |
+| `ChatMessageWriter` | Writes user messages into the most-recent chat session (MCP elicitation) |
+| `QuestionGeneratorReader` / `QuestionerDatabase` | Decision-question generation and persistence |
+| `NegotiationSummaryReader` | Negotiation-digest summarization (falls back to deterministic digests) |
+
+All interfaces are exported from the package root — import them with `import type { ... } from "@indexnetwork/protocol"`.
+
+### 3. Create tools
+
+Pass your adapter implementations to `createChatTools` to get a set of LangChain-compatible tools bound to a user session:
+
+```typescript
+import { createChatTools } from "@indexnetwork/protocol";
+
+const tools = await createChatTools({
+  userId: "user-uuid",
+
+  // ── Required adapters ──
+  database,             // ChatGraphCompositeDatabase
+  embedder,             // Embedder
+  scraper,              // Scraper
+  cache,                // Cache
+  hydeCache,            // HydeCache
+  integration,          // IntegrationAdapter
+  intentQueue,          // IntentGraphQueue
+  contactService,       // ContactServiceAdapter
+  chatSession,          // ChatSessionReader
+  enricher,             // ProfileEnricher
+  negotiationDatabase,  // NegotiationGraphDatabase
+  integrationImporter,  // bulk contact import
+  createUserDatabase,   // (db, userId) => UserDatabase
+  createSystemDatabase, // (db, userId, indexScope, embedder?) => SystemDatabase
+
+  // ── Optional scoping ──
+  networkId: "optional-network-uuid", // scope tools to a specific index/network
+  sessionId: "chat-session-id",       // enables draft opportunities with conversation context
+
+  // ── Optional capabilities (enable when the host supports them) ──
+  agentDatabase,        // AgentDatabase — agent registry
+  agentDispatcher,      // AgentDispatcher — routes negotiation turns to personal agents
+  deliveryLedger,       // DeliveryLedger — OpenClaw delivery commits
+  discoveryRuns,        // DiscoveryRunStore (+ discoveryRunQueue) — async MCP discovery
+  enrichmentRuns,       // EnrichmentRunStore (+ enrichmentRunQueue) — async MCP enrichment runs
+  mintConnectLink,      // short connect links for opportunity accepts
+  modelConfig,          // override chat model / reasoning effort (see above)
+});
+
+// tools is an array of LangChain Tool objects ready to bind to an agent
+```
+
+`createChatTools` accepts a single `ToolContext` object. The required adapters
+above are always needed; the optional capabilities default to a degraded-but-
+functional mode when omitted (e.g. without `agentDispatcher` the negotiation
+tools are not registered, and without `discoveryRuns` MCP discovery runs
+synchronously).
+
+## Graphs
+
+For direct graph invocation (bypassing the tool layer), a `*GraphFactory` class is exported for each workflow:
+
+```typescript
+import {
+  ChatGraphFactory,
+  IntentGraphFactory,
+  OpportunityGraphFactory,
+  EnrichmentGraphFactory,
+  PremiseGraphFactory,
+  NegotiationGraphFactory,
+  HydeGraphFactory,
+  NetworkGraphFactory,
+  NetworkMembershipGraphFactory,
+  IntentNetworkGraphFactory,
+  HomeGraphFactory,
+  MaintenanceGraphFactory,
+} from "@indexnetwork/protocol";
+```
+
+Each factory takes its typed dependencies in the constructor and exposes a
+`.createGraph()` method that returns a compiled LangGraph ready for `.invoke()`.
+
+| Factory | Workflow |
+|---|---|
+| `ChatGraphFactory` | ReAct chat loop — LLM calls tools, responds to the user |
+| `IntentGraphFactory` | Clarify, infer, verify felicity, reconcile, and persist intents |
+| `OpportunityGraphFactory` | HyDE-based discovery: search, evaluate (valency), rank, persist |
+| `EnrichmentGraphFactory` | Enrich users (scrape + embed) and decompose into premises |
+| `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 index/network CRUD |
+| `NetworkMembershipGraphFactory` | Manage index/network member join/leave |
+| `IntentNetworkGraphFactory` | Evaluate and assign/unassign intents to indexes |
+| `HomeGraphFactory` | Categorize and curate home-feed content |
+| `MaintenanceGraphFactory` | Periodic maintenance (feed health, opportunity expiration) |
+
+## 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:
+
+```typescript
+import { createMcpServer, type McpAuthResolver } from "@indexnetwork/protocol";
+
+const authResolver: McpAuthResolver = {
+  async resolveIdentity(req) {
+    // Look up the API key in `x-api-key` and return { userId, agentId? }.
+    // `agentId` should come from Better Auth token metadata so downstream
+    // tool handlers can attribute every call to a concrete agent identity.
+    return resolveFromApiKey(req);
+  },
+};
+
+const server = createMcpServer(
+  deps,
+  authResolver,
+  {
+    // Per-request factory for scoped user/system databases.
+    create: (userId, indexScope) => createScopedDeps(userId, indexScope),
+  },
+);
+```
+
+On every tool call the server:
+
+1. Extracts the HTTP request from the MCP `ServerContext`.
+2. Calls `authResolver.resolveIdentity(req)` to get `{ userId, agentId }`.
+3. Gates access: MCP callers without a resolved `agentId` are blocked from every tool except `register_agent`, `read_docs`, and `scrape_url` until they register.
+4. Builds per-request scoped databases via `scopedDepsFactory` and invokes the tool handler through the shared runtime.
+
+### Runtime controls
+
+MCP tools are bounded by `ToolInvocationRuntime`:
+
+| Class | Default | Class override |
+|---|---:|---|
+| `fast` | 10 s | `MCP_TOOL_TIMEOUT_FAST_MS` |
+| `bounded_slow` | 45 s | `MCP_TOOL_TIMEOUT_BOUNDED_SLOW_MS` |
+| `async_candidate` | 50 s | `MCP_TOOL_TIMEOUT_ASYNC_CANDIDATE_MS` |
+
+Per-tool timeout overrides use `MCP_TOOL_TIMEOUT_<TOOL_NAME>_MS`, such as `MCP_TOOL_TIMEOUT_DISCOVER_OPPORTUNITIES_MS`. Tool outputs are capped by `MCP_TOOL_MAX_OUTPUT_BYTES` (default `1000000`) or `MCP_TOOL_MAX_OUTPUT_<TOOL_NAME>_BYTES`; inbound MCP request bodies are capped by the backend with `MCP_MAX_REQUEST_BYTES` (default `1000000`). Runtime failures return JSON text envelopes with stable `code` values: `TOOL_TIMEOUT`, `TOOL_CANCELLED`, or `TOOL_OUTPUT_TOO_LARGE`.
+
+For MCP callers, `discover_opportunities` is async: it returns a `discoveryRunId` immediately, and clients poll `get_discovery_run` or request cancellation with `cancel_discovery_run`. Non-MCP chat/web paths stay synchronous.
+
+### `MCP_INSTRUCTIONS`
+
+The instructions string is the single canonical behavioral contract for every runtime that connects to Index Network — voice, entity model, discovery-first rule, output rules, and the **Negotiation turn mode** block that tells a silent subagent how to handle a live negotiation turn when its session key is prefixed `index:negotiation:`. Plugin skills and bootstrap scripts do **not** redefine this guidance; they defer to whatever ships in `MCP_INSTRUCTIONS`.
+
+### Negotiation-facing tools
+
+Personal agents participate in bilateral negotiation via a small set of MCP tools:
+
+| Tool | Purpose |
+|---|---|
+| `get_negotiation` | Fetch the full turn history and assessment seed for a negotiation |
+| `list_negotiations` | List negotiations awaiting a response from this agent's user |
+| `respond_to_negotiation` | Submit a turn (propose / counter / accept / reject / question) |
+
+## Publishing
+
+Publishing is handled via CI:
+
+```bash
+# dev pushes publish an rc prerelease
+git push <remote> dev
+
+# main pushes publish the stable release if the package version is new
+git push <remote> main
+```
+
+`dev` publishes prerelease versions derived from `package.json` using npm's `rc` tag, for example `3.6.3-rc.123.1`. `main` publishes the base version from `package.json` to `latest` only when that version is not already on npm.
+
+Or publish manually from `packages/protocol/`:
+
+```bash
+npm publish --access public
+```

package/README.md

@@ -1,253 +1,427 @@
-# @indexnetwork/protocol
+# Index Network Protocol
 
-The agent orchestration layer for Index Network. Implements LangGraph-based workflows for intent processing, opportunity discovery, and chat — decoupled from any specific infrastructure via adapter injection.
+## Status
 
-## Stability & versioning
+This document describes the public protocol model for Index Network: the entities, state transitions, agent obligations, privacy boundaries, and discovery semantics that define interoperable participation in the network.
 
-This package follows [Semantic Versioning](https://semver.org/). The **only**
-supported entry point is the package root (`import { ... } from "@indexnetwork/protocol"`);
-deep imports are not part of the contract. Every symbol is re-exported explicitly from
-`src/index.ts` and tagged with a stability tier:
+The canonical reference implementation is published as `@indexnetwork/protocol`. Implementation details, package installation, exported APIs, adapter contracts, graph factories, and release mechanics are documented separately in [IMPLEMENTATION.md](./IMPLEMENTATION.md). Public API stability is defined in [STABILITY.md](./STABILITY.md).
 
-- **Stable** — interfaces, graph factories, agents, `createChatTools`, the
-  tool/runtime helpers, and shared schemas. Breaking changes require a major bump.
-- **Experimental** (`@experimental`) — advanced graph-state types and internal
-  helpers; may change in a minor release.
+Normative terms such as **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are used in their ordinary protocol-documentation sense.
 
-See [STABILITY.md](./STABILITY.md) for the full policy and the deprecation path,
-and [CHANGELOG.md](./CHANGELOG.md) for release history.
+## Abstract
 
-## Install
+Index Network is a private, intent-driven discovery protocol for agent-mediated opportunity discovery.
 
-```bash
-npm install @indexnetwork/protocol
-```
+Participants express **signals**: structured statements of what they seek, offer, are open to, or can credibly support. Agents interpret those signals against participant **context**, constrain discovery to bounded **communities**, evaluate candidate overlaps, negotiate fit when appropriate, and surface **opportunities** only through consent-gated state transitions.
 
-## Setup
+The protocol is designed for high-signal human and agent coordination. It is not a public people database, keyword search engine, advertising channel, or automated introduction machine. Its purpose is to discover meaningful overlap while preserving context, scope, and human approval.
 
-### 1. Configure the LLM
+## Protocol overview
 
-The package reads `OPENROUTER_API_KEY` (required), `CHAT_MODEL`, and `CHAT_REASONING_EFFORT` from environment variables. No startup call is needed.
+```mermaid
+flowchart LR
+    Participant[Participant] --> Agent[Authorized agent]
+    Participant --> Context[Context]
+    Participant --> Signal[Signal]
 
-To override the chat model or reasoning effort when using the built-in chat runtime (`ChatGraphFactory` / `ChatAgent`), pass `modelConfig` on `ToolContext`. `ChatAgent` reads these fields when the chat graph runs; the tools themselves do not consume `modelConfig`:
+    Premises[Premises] --> Context
+    Context --> Scope[Effective scope]
+    Signal --> Scope
+    Community[Community membership and norms] --> Scope
+    AgentScope[Agent permissions] --> Scope
 
-```typescript
-import { createChatTools } from "@indexnetwork/protocol";
+    Scope --> CandidateGeneration[Candidate generation]
+    CandidateGeneration --> Evaluation[Evaluation]
+    Evaluation -->|plausible but uncertain| Opportunity[Draft or negotiating opportunity]
+    Evaluation -->|clear fit| Opportunity[Draft or pending opportunity]
+    Opportunity -->|needs agent clarification| Negotiation[Bounded negotiation]
+    Negotiation -->|fit established| Opportunity
+    Negotiation -->|human judgment required| Questions[Structured questions]
+    Questions --> Participant
+    Participant --> Signal
 
-const tools = await createChatTools({
-  // ... other deps ...
-  modelConfig: {
-    chatModel: "google/gemini-2.5-flash",       // optional — has a default
-    chatReasoningEffort: "low",                  // optional: minimal | low | medium | high | xhigh
-  },
-});
+    Opportunity --> Consent{Participant consent?}
+    Consent -->|yes| Connection[Connection]
+    Consent -->|no| Terminal[Declined or expired]
 ```
 
-`apiKey` and `baseURL` can also be overridden this way. All other protocol agents (evaluators, generators, etc.) rely on `OPENROUTER_API_KEY` set in the environment regardless of `modelConfig`.
+The graph is intentionally consent-centered: agents can construct context, discover candidates, evaluate fit, and negotiate constraints, but relationship-forming transitions require participant approval before a connection is opened.
 
-### 2. Implement the adapters
+## Design goals
 
-The package defines interfaces — your application provides the concrete implementations.
+1. **Intent as the primary primitive** — discovery begins from a participant's current signal, not from static identity alone.
+2. **Bounded visibility** — communities define the scope in which signals and context may be evaluated.
+3. **Semantic discovery** — matching is based on role fit, constraints, complementarity, and contextual relevance rather than exact keyword overlap.
+4. **Explainable surfacing** — every surfaced opportunity SHOULD include a legible reason: why these participants, why now, and what the next action might be.
+5. **Consent at relationship boundaries** — agents MAY discover and negotiate, but MUST NOT create or accept a relationship without explicit participant approval.
+6. **Agent interoperability** — first-party agents, personal agents, community agents, and external MCP clients SHOULD be able to participate under the same behavioral contract.
 
-**Required** (always needed by `createChatTools`):
+## Non-goals
 
-| Interface | Responsibility |
-|---|---|
-| `ChatGraphCompositeDatabase` | Core data access (users, intents, indexes/networks, opportunities) |
-| `UserDatabase` / `SystemDatabase` | Context-bound databases built by `createUserDatabase` / `createSystemDatabase` |
-| `Embedder` | Vector embeddings for semantic search |
-| `Scraper` | Web content extraction |
-| `Cache` / `HydeCache` | Result caching (HyDE may share the general cache) |
-| `IntegrationAdapter` | OAuth and external tool actions |
-| `IntentGraphQueue` | Background intent processing queue |
-| `ContactServiceAdapter` | Contact management |
-| `ChatSessionReader` | Load conversation history |
-| `ProfileEnricher` | Enrich profiles from external sources |
-| `NegotiationGraphDatabase` | Negotiation state persistence |
-
-**Optional** (enable specific capabilities; omit to run without that feature):
-
-| Interface | Responsibility |
+The protocol does not attempt to be:
+
+- a global directory of people,
+- a public search index,
+- a social feed ranking protocol,
+- a marketplace listing format,
+- a replacement for human judgment,
+- or a mechanism for bypassing consent, membership, or community boundaries.
+
+## Terminology
+
+| Term | Definition |
 |---|---|
-| `AgentDatabase` | Agent registry CRUD (agents, transports, permissions) |
-| `AgentDispatcher` | Resolves and invokes personal agents during negotiation turns — required to register the negotiation tools |
-| `McpAuthResolver` | Resolves `{ userId, agentId }` from an incoming MCP HTTP request (MCP server only) |
-| `DeliveryLedger` | Commits OpenClaw opportunity-delivery rows |
-| `DiscoveryRunStore` / `DiscoveryRunQueue` | Persist and execute async MCP discovery runs |
-| `EnrichmentRunStore` / `EnrichmentRunQueue` | Persist and execute async MCP enrichment runs |
-| `MintConnectLink` | Mints short connect links for opportunity accepts |
-| `ChatSummaryReader` | Read-through chat-session digest |
-| `ChatMessageWriter` | Writes user messages into the most-recent chat session (MCP elicitation) |
-| `QuestionGeneratorReader` / `QuestionerDatabase` | Decision-question generation and persistence |
-| `NegotiationSummaryReader` | Negotiation-digest summarization (falls back to deterministic digests) |
-
-All interfaces are exported from the package root — import them with `import type { ... } from "@indexnetwork/protocol"`.
-
-### 3. Create tools
-
-Pass your adapter implementations to `createChatTools` to get a set of LangChain-compatible tools bound to a user session:
-
-```typescript
-import { createChatTools } from "@indexnetwork/protocol";
-
-const tools = await createChatTools({
-  userId: "user-uuid",
-
-  // ── Required adapters ──
-  database,             // ChatGraphCompositeDatabase
-  embedder,             // Embedder
-  scraper,              // Scraper
-  cache,                // Cache
-  hydeCache,            // HydeCache
-  integration,          // IntegrationAdapter
-  intentQueue,          // IntentGraphQueue
-  contactService,       // ContactServiceAdapter
-  chatSession,          // ChatSessionReader
-  enricher,             // ProfileEnricher
-  negotiationDatabase,  // NegotiationGraphDatabase
-  integrationImporter,  // bulk contact import
-  createUserDatabase,   // (db, userId) => UserDatabase
-  createSystemDatabase, // (db, userId, indexScope, embedder?) => SystemDatabase
-
-  // ── Optional scoping ──
-  networkId: "optional-network-uuid", // scope tools to a specific index/network
-  sessionId: "chat-session-id",       // enables draft opportunities with conversation context
-
-  // ── Optional capabilities (enable when the host supports them) ──
-  agentDatabase,        // AgentDatabase — agent registry
-  agentDispatcher,      // AgentDispatcher — routes negotiation turns to personal agents
-  deliveryLedger,       // DeliveryLedger — OpenClaw delivery commits
-  discoveryRuns,        // DiscoveryRunStore (+ discoveryRunQueue) — async MCP discovery
-  enrichmentRuns,       // EnrichmentRunStore (+ enrichmentRunQueue) — async MCP enrichment runs
-  mintConnectLink,      // short connect links for opportunity accepts
-  modelConfig,          // override chat model / reasoning effort (see above)
-});
-
-// tools is an array of LangChain Tool objects ready to bind to an agent
+| **Participant** | A human principal represented in the network. A participant may act directly or through one or more agents. |
+| **Agent** | A software actor authorized to act for a participant or community within a declared scope. |
+| **Signal** | A participant's actionable expression of intent: what they seek, offer, need, are building, are exploring, or can support. |
+| **Premise** | An atomic contextual claim about a participant, used to ground what signals are plausible or relevant. |
+| **Context** | A synthesized representation of premises, history, constraints, and community-specific relevance. |
+| **Community** | A bounded discovery scope with membership, purpose, norms, and relevance criteria. |
+| **Membership** | The relationship between a participant and a community. Agents receive community authority through separate scoped permissions. |
+| **Candidate** | A possible counterpart or opportunity component identified during discovery but not yet surfaced. |
+| **Opportunity** | A candidate overlap that has passed evaluation and may be shown to one or more participants. |
+| **Negotiation** | A bounded agent-to-agent exchange used to test fit, constraints, timing, or consent before surfacing or advancing an opportunity. |
+| **Connection** | A participant-approved communication channel or introduction resulting from an accepted opportunity. |
+
+Some implementation APIs may expose historical names such as `intent`, `index`, `network`, `latent`, `pending`, `accepted`, `rejected`, `negotiating`, or `stalled`. Public-facing agents SHOULD translate stable participant states into protocol terms such as **signal**, **community**, **draft**, **sent**, **connected**, and **declined**, while treating negotiating or stalled states as internal process state unless the participant needs to act on them.
+
+## Object relationship model
+
+```mermaid
+erDiagram
+    PARTICIPANT ||--o{ AGENT : authorizes
+    PARTICIPANT ||--o{ SIGNAL : expresses
+    PARTICIPANT ||--o{ PREMISE : asserts
+    PARTICIPANT ||--o{ CONTEXT : represented_by
+    PARTICIPANT ||--o{ MEMBERSHIP : holds
+    AGENT ||--o{ AGENT_PERMISSION : receives
+    COMMUNITY ||--o{ MEMBERSHIP : contains
+    COMMUNITY ||--o{ AGENT_PERMISSION : scopes
+    COMMUNITY ||--o{ SIGNAL : scopes
+    COMMUNITY ||--o{ CONTEXT : lenses
+    SIGNAL ||--o{ CANDIDATE : generates
+    CONTEXT ||--o{ CANDIDATE : generates
+    CANDIDATE ||--o| OPPORTUNITY : promotes_to
+    OPPORTUNITY ||--o{ NEGOTIATION : may_require
+    OPPORTUNITY ||--o| CONNECTION : accepted_as
+
+    PARTICIPANT {
+      string principal
+      string consent_source
+    }
+    AGENT {
+      string authorization
+      string effective_scope
+    }
+    COMMUNITY {
+      string purpose
+      string membership_policy
+    }
+    SIGNAL {
+      string constraints
+      string lifecycle_state
+    }
+    OPPORTUNITY {
+      string explanation
+      string lifecycle_state
+    }
 ```
 
-`createChatTools` accepts a single `ToolContext` object. The required adapters
-above are always needed; the optional capabilities default to a degraded-but-
-functional mode when omitted (e.g. without `agentDispatcher` the negotiation
-tools are not registered, and without `discoveryRuns` MCP discovery runs
-synchronously).
-
-## Graphs
-
-For direct graph invocation (bypassing the tool layer), a `*GraphFactory` class is exported for each workflow:
-
-```typescript
-import {
-  ChatGraphFactory,
-  IntentGraphFactory,
-  OpportunityGraphFactory,
-  EnrichmentGraphFactory,
-  PremiseGraphFactory,
-  NegotiationGraphFactory,
-  HydeGraphFactory,
-  NetworkGraphFactory,
-  NetworkMembershipGraphFactory,
-  IntentNetworkGraphFactory,
-  HomeGraphFactory,
-  MaintenanceGraphFactory,
-} from "@indexnetwork/protocol";
+This model is conceptual rather than storage-prescriptive. Implementations MAY choose different table names or internal representations, but MUST preserve the same attribution, scope, and consent semantics.
+
+## System model
+
+### Principals
+
+The protocol distinguishes human principals from software actors.
+
+- A **participant** is the source of consent and personal context.
+- An **agent** is an authorized actor. Every agent action MUST be attributable to a participant, a community, or both.
+- A **community** may define local discovery norms, but it does not override participant consent.
+
+### Scope
+
+All discovery is scope-bound. A protocol operation MUST resolve an effective scope before cross-participant discovery, candidate generation, or opportunity evaluation. Implementations MAY read the requesting participant's own signals or context while preparing that operation.
+
+A scope may include:
+
+- a participant's personal community,
+- one or more shared communities,
+- an agent's assigned community scope,
+- or a narrower request-time scope selected by the participant.
+
+Agents MUST NOT use access to one community to infer, reveal, or act on information from another community unless the effective scope explicitly permits it.
+
+Effective scope is the intersection of all applicable authority boundaries:
+
+```mermaid
+flowchart TD
+    Request[Request-time scope] --> Intersect[Intersect scopes]
+    ParticipantMemberships[Participant memberships] --> Intersect
+    AgentPermissions[Agent permissions] --> Intersect
+    CommunityPolicy[Community rules where implemented] --> Intersect
+    PersonalCommunity[Personal community boundary] --> Intersect
+
+    Intersect --> Empty{Empty intersection?}
+    Empty -->|yes| Deny[Deny discovery]
+    Empty -->|no| EffectiveScope[Effective scope]
+    EffectiveScope --> Reads[Permitted reads]
+    EffectiveScope --> Writes[Permitted writes]
+    EffectiveScope --> Evaluation[Permitted evaluation]
+
+    Reads --> Audit[Attributable audit trail]
+    Writes --> Audit
+    Evaluation --> Audit
 ```
 
-Each factory takes its typed dependencies in the constructor and exposes a
-`.createGraph()` method that returns a compiled LangGraph ready for `.invoke()`.
+A broader credential MUST NOT expand a narrower request. A narrower agent permission MUST clamp a broader participant membership. Community-specific policy checks MAY further reduce effective scope where an implementation defines them.
 
-| Factory | Workflow |
+### Public and private surfaces
+
+The protocol separates internal state from participant-facing language.
+
+Internal records MAY contain IDs, embeddings, scores, graph state, and tool names. Participant-facing responses MUST NOT expose these implementation details unless an identifier is directly actionable by the participant, such as a conversation identifier needed to open an accepted connection.
+
+## Core objects
+
+### Signal
+
+A signal is an actionable statement of direction. It may represent a need, offer, collaboration interest, hiring intent, funding goal, research direction, introduction request, or other future-oriented constraint.
+
+A signal SHOULD contain enough specificity to support discovery. Underspecified signals SHOULD enter clarification before they are persisted or used for broad discovery.
+
+Signals have the following conceptual lifecycle:
+
+| State | Meaning |
 |---|---|
-| `ChatGraphFactory` | ReAct chat loop — LLM calls tools, responds to the user |
-| `IntentGraphFactory` | Clarify, infer, verify felicity, reconcile, and persist intents |
-| `OpportunityGraphFactory` | HyDE-based discovery: search, evaluate (valency), rank, persist |
-| `EnrichmentGraphFactory` | Enrich users (scrape + embed) and decompose into premises |
-| `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 index/network CRUD |
-| `NetworkMembershipGraphFactory` | Manage index/network member join/leave |
-| `IntentNetworkGraphFactory` | Evaluate and assign/unassign intents to indexes |
-| `HomeGraphFactory` | Categorize and curate home-feed content |
-| `MaintenanceGraphFactory` | Periodic maintenance (feed health, opportunity expiration) |
-
-## 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:
-
-```typescript
-import { createMcpServer, type McpAuthResolver } from "@indexnetwork/protocol";
-
-const authResolver: McpAuthResolver = {
-  async resolveIdentity(req) {
-    // Look up the API key in `x-api-key` and return { userId, agentId? }.
-    // `agentId` should come from Better Auth token metadata so downstream
-    // tool handlers can attribute every call to a concrete agent identity.
-    return resolveFromApiKey(req);
-  },
-};
-
-const server = createMcpServer(
-  deps,
-  authResolver,
-  {
-    // Per-request factory for scoped user/system databases.
-    create: (userId, indexScope) => createScopedDeps(userId, indexScope),
-  },
-);
-```
+| **Proposed** | A participant or agent supplied raw intent-like input. |
+| **Clarifying** | The protocol requires additional constraints before discovery. |
+| **Active** | The signal is valid, scoped, and eligible for discovery. |
+| **Updated** | The participant refined or replaced constraints. |
+| **Archived / expired** | The signal should no longer produce new opportunities. |
 
-On every tool call the server:
+A signal MUST NOT be treated as active if it is outside the participant's authority, obviously insincere, unsafe to act on, or too vague to evaluate.
 
-1. Extracts the HTTP request from the MCP `ServerContext`.
-2. Calls `authResolver.resolveIdentity(req)` to get `{ userId, agentId }`.
-3. Gates access: MCP callers without a resolved `agentId` are blocked from every tool except `register_agent`, `read_docs`, and `scrape_url` until they register.
-4. Builds per-request scoped databases via `scopedDepsFactory` and invokes the tool handler through the shared runtime.
+### Premise and context
 
-### Runtime controls
+A premise is a small claim about a participant: background, role, current work, capability, location, affiliation, constraint, or declared preference. Premises ground discovery by determining whether a signal is plausible and which communities or counterparts are relevant.
 
-MCP tools are bounded by `ToolInvocationRuntime`:
+Context is derived from premises. Context MAY be global to a participant or specific to a community. Community-specific context SHOULD emphasize facts relevant to that community's purpose and suppress irrelevant detail.
 
-| Class | Default | Class override |
-|---|---:|---|
-| `fast` | 10 s | `MCP_TOOL_TIMEOUT_FAST_MS` |
-| `bounded_slow` | 45 s | `MCP_TOOL_TIMEOUT_BOUNDED_SLOW_MS` |
-| `async_candidate` | 50 s | `MCP_TOOL_TIMEOUT_ASYNC_CANDIDATE_MS` |
+Premise and context updates SHOULD cause downstream discovery representations to refresh. Stale context SHOULD NOT be used when fresher participant-approved context exists.
 
-Per-tool timeout overrides use `MCP_TOOL_TIMEOUT_<TOOL_NAME>_MS`, such as `MCP_TOOL_TIMEOUT_DISCOVER_OPPORTUNITIES_MS`. Tool outputs are capped by `MCP_TOOL_MAX_OUTPUT_BYTES` (default `1000000`) or `MCP_TOOL_MAX_OUTPUT_<TOOL_NAME>_BYTES`; inbound MCP request bodies are capped by the backend with `MCP_MAX_REQUEST_BYTES` (default `1000000`). Runtime failures return JSON text envelopes with stable `code` values: `TOOL_TIMEOUT`, `TOOL_CANCELLED`, or `TOOL_OUTPUT_TOO_LARGE`.
+### Community
 
-For MCP callers, `discover_opportunities` is async: it returns a `discoveryRunId` immediately, and clients poll `get_discovery_run` or request cancellation with `cancel_discovery_run`. Non-MCP chat/web paths stay synchronous.
+A community is a bounded discovery environment. It defines who can participate, what kinds of signals are relevant, and which discovery operations are legitimate.
 
-### `MCP_INSTRUCTIONS`
+A community SHOULD have:
 
-The instructions string is the single canonical behavioral contract for every runtime that connects to Index Network — voice, entity model, discovery-first rule, output rules, and the **Negotiation turn mode** block that tells a silent subagent how to handle a live negotiation turn when its session key is prefixed `index:negotiation:`. Plugin skills and bootstrap scripts do **not** redefine this guidance; they defer to whatever ships in `MCP_INSTRUCTIONS`.
+- a purpose or prompt,
+- membership rules,
+- agent permissions,
+- relevance expectations,
+- and privacy expectations.
 
-### Negotiation-facing tools
+The participant's personal community represents trusted contacts and direct relationships. It is not equivalent to a public audience.
 
-Personal agents participate in bilateral negotiation via a small set of MCP tools:
+### Opportunity
 
-| Tool | Purpose |
-|---|---|
-| `get_negotiation` | Fetch the full turn history and assessment seed for a negotiation |
-| `list_negotiations` | List negotiations awaiting a response from this agent's user |
-| `respond_to_negotiation` | Submit a turn (propose / counter / accept / reject / question) |
+An opportunity is an evaluated overlap between participants. It is not merely a candidate returned by retrieval. It must be specific enough to explain and safe enough to surface.
+
+An opportunity SHOULD include:
+
+- participating roles,
+- the relevant signal or context on each side,
+- a concise explanation of fit,
+- a recommended next action,
+- lifecycle state,
+- and visibility rules for each participant.
+
+Opportunity states are participant-facing as follows:
+
+| State | Participant-facing term | Meaning |
+|---|---|---|
+| **Draft** | Draft | The protocol found a plausible opportunity, but it has not been sent to the other side. |
+| **Sent** | Sent | One side has sent or received the opportunity and a response is pending. |
+| **Connected** | Connected | Required participants accepted and a conversation or introduction may proceed. |
+| **Declined** | Declined | A participant rejected the opportunity. |
+| **Expired** | Expired | The opportunity is no longer actionable. |
+
+A conforming agent MUST NOT present a received opportunity as **Connected** without explicit approval from the receiving participant. The reference implementation enforces actor authorization and valid source statuses for acceptance, while current-approval capture is handled by the agent or user-interface flow invoking the transition.
+
+### Opportunity lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: candidate promoted
+    Draft --> Sent: sender approves send
+    Draft --> Connected: direct acceptance or connection link
+    Draft --> Declined: sender declines
+    Draft --> Expired: TTL or invalidated
+
+    Sent --> Connected: recipient explicitly accepts
+    Sent --> Declined: recipient declines
+    Sent --> Expired: TTL or invalidated
 
-## Publishing
+    Connected --> [*]
+    Declined --> [*]
+    Expired --> [*]
 
-Publishing is handled via CI:
+    note right of Draft
+      Plausible but not sent.
+      Only visible under role and scope rules.
+    end note
 
-```bash
-# dev pushes publish an rc prerelease
-git push <remote> dev
+    note right of Sent
+      One side is waiting.
+      Acceptance requires participant approval.
+    end note
 
-# main pushes publish the stable release if the package version is new
-git push <remote> main
+    note right of Connected
+      Relationship boundary crossed.
+      Conversation or introduction may proceed.
+    end note
 ```
 
-`dev` publishes prerelease versions derived from `package.json` using npm's `rc` tag, for example `3.6.3-rc.123.1`. `main` publishes the base version from `package.json` to `latest` only when that version is not already on npm.
+## Discovery procedure
+
+A conforming discovery flow has seven phases.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant P as Participant
+    participant A as Agent
+    participant PR as Protocol runtime
+    participant C as Community scope
+    participant N as Counterparty agent
+
+    P->>A: Provide context and signal
+    A->>PR: Admit signal and construct context
+    PR->>C: Resolve effective scope
+    C-->>PR: Permitted communities
+    PR->>PR: Generate candidates inside scope
+    PR->>PR: Evaluate role fit and constraints
+    alt Fit is clear
+        PR-->>A: Draft opportunity with explanation
+    else Fit is uncertain
+        PR->>N: Start bounded negotiation
+        N-->>PR: Propose, counter, accept, reject, or question
+        PR-->>A: Draft opportunity or structured question
+    end
+    A->>P: Explain strongest reason and ask for approval
+    P-->>A: Approve, decline, or refine signal
+    A->>PR: Advance lifecycle only if approved
+```
+
+### 1. Context construction
+
+The protocol collects participant-provided or participant-authorized material and turns it into premises and context. Context construction MUST preserve provenance and SHOULD prefer participant-approved information over inferred information.
+
+### 2. Signal admission
+
+The protocol evaluates a proposed signal for specificity, sincerity, authority, and safety. If the signal is too broad, ambiguous, or missing critical constraints, the agent SHOULD ask focused clarification questions before running discovery.
+
+### 3. Scope resolution
+
+The protocol determines the effective communities in which the signal can operate. Scope resolution MUST intersect participant membership, agent permissions, and request-time constraints. If the intersection is empty, discovery MUST NOT proceed.
+
+### 4. Candidate generation
+
+The protocol generates candidates by comparing signals and context inside the effective scope. Candidate generation MAY use multiple strategies, including signal-to-signal, context-to-signal, premise-to-premise, semantic retrieval, and directed target construction.
+
+Candidate generation is not surfacing. Candidate data MUST remain internal until evaluation and visibility checks pass.
+
+### 5. Evaluation
+
+The protocol evaluates candidates for role fit, constraint satisfaction, credibility, reciprocity, timing, and explainability. A candidate SHOULD be rejected or retained as internal evidence if the protocol cannot produce a clear reason for surfacing it.
+
+### 6. Negotiation
+
+When fit is plausible but uncertain, agents MAY negotiate. Negotiation MUST be bounded. It SHOULD clarify constraints, test mutual relevance, and decide among a small set of actions: propose, counter, accept, reject, or ask a question. Implementations MAY persist an opportunity before negotiation completes and then update its public state from the negotiation outcome.
+
+If negotiation requires human judgment, the agent SHOULD stop and ask the participant a small number of structured questions rather than fabricating preferences.
+
+### 7. Surfacing and acceptance
+
+The protocol surfaces the opportunity according to role and lifecycle visibility. Participant-facing presentation SHOULD include the strongest reason for relevance and a clear next action. Sending, accepting, or connecting MUST require participant consent at the relevant boundary.
+
+## Agent requirements
 
-Or publish manually from `packages/protocol/`:
+A conforming agent MUST:
 
-```bash
-npm publish --access public
+- act only within its authenticated participant and community scope,
+- preserve participant consent at send, accept, and connection boundaries,
+- avoid exposing internal IDs, raw tool results, embeddings, scores, or database field names,
+- distinguish known facts from inferred context,
+- ask for clarification when required information is missing,
+- use the protocol vocabulary in participant-facing output,
+- avoid fabricating participants, opportunities, constraints, or outcomes,
+- and provide concise explanations for surfaced opportunities.
+
+A conforming agent SHOULD:
+
+- surface the top one to three relevant points by default,
+- prefer first names unless disambiguation is required,
+- explain why an opportunity is relevant before asking for action,
+- treat silence, timeouts, or failed negotiation as uncertainty rather than consent,
+- and record enough trace information for later audit by authorized operators.
+
+A conforming agent MUST NOT:
+
+- describe discovery as public search,
+- use community access to leak out-of-scope participant information,
+- accept a received opportunity without explicit current approval,
+- present internal confidence scores as objective truth,
+- or continue negotiation after a terminal decision.
+
+## Privacy and safety invariants
+
+The following invariants define the protocol's trust boundary:
+
+1. **Scope invariant** — discovery reads and writes MUST remain inside the effective scope.
+2. **Consent invariant** — relationship-forming transitions MUST be participant-approved.
+3. **Attribution invariant** — every agent action MUST be attributable to an authorized principal.
+4. **Legibility invariant** — surfaced opportunities SHOULD be explainable in participant-facing language.
+5. **Minimization invariant** — participant-facing output SHOULD reveal only what is needed for the next decision.
+6. **No-fabrication invariant** — agents MUST NOT invent facts to complete an opportunity narrative.
+7. **Terminality invariant** — declined, expired, or otherwise terminal opportunities SHOULD NOT produce further automatic advancement unless explicitly reopened or changed through an authorized protocol action.
+
+## Interoperability
+
+The reference implementation exposes the protocol to agents through a Model Context Protocol (MCP) server and typed package APIs. MCP is the preferred interoperability surface for external agents because it provides tool discovery, runtime instructions, identity resolution, and bounded tool invocation.
+
+```mermaid
+flowchart LR
+    ExternalAgent[External agent] -->|MCP tools| McpServer[Index Network MCP server]
+    FirstPartyAgent[First-party agent] -->|typed runtime| Runtime[Protocol runtime]
+    PersonalAgent[Personal agent] -->|MCP tools or REST polling| McpServer
+
+    McpServer --> Identity[Identity resolution]
+    Identity --> AgentGate[Agent registration and scope]
+    AgentGate --> ScopedDeps[Scoped protocol dependencies]
+    ScopedDeps --> Runtime
+
+    Runtime --> Tools[Protocol tools]
+    Tools --> Graphs[Discovery, context, signal, negotiation graphs]
+    Graphs --> Results[Bounded results]
+    Results --> Runtime
+    Runtime --> ParticipantOutput[Participant-facing output rules]
 ```
+
+
+Implementations MAY expose additional transports, but they SHOULD preserve the same protocol semantics:
+
+- authenticated principal resolution,
+- scoped access,
+- consent-gated opportunity transitions,
+- structured discovery and negotiation operations,
+- and participant-facing output rules.
+
+## Reference implementation
+
+The canonical TypeScript implementation is `@indexnetwork/protocol`.
+
+- [IMPLEMENTATION.md](./IMPLEMENTATION.md) — package installation, adapters, graph factories, MCP server usage, and publishing.
+- [STABILITY.md](./STABILITY.md) — public API contract and SemVer policy.
+- [CHANGELOG.md](./CHANGELOG.md) — release history.

package/STABILITY.md

@@ -0,0 +1,92 @@
+# Stability & Versioning Policy
+
+`@indexnetwork/protocol` is a published, versioned package consumed by the Index
+Network backend and by external integrators. This document defines what the
+public contract **is**, which parts are stable, and what counts as a breaking
+change. It is the reference behind the tier annotations in `src/index.ts`.
+
+## The public contract
+
+- The **only** supported entry point is the package root:
+  `import { ... } from "@indexnetwork/protocol"`.
+- Deep imports (`@indexnetwork/protocol/dist/...` or `/src/...`) are **not** part
+  of the contract and may change or disappear in any release — do not rely on them.
+- The contract is exactly the set of symbols re-exported from `src/index.ts`.
+  Exports are listed explicitly (no `export *` wildcards), so the surface is
+  reviewable and additions are always intentional.
+
+## Stability tiers
+
+Each section of the barrel carries one of two tiers.
+
+### Stable
+
+Covered by SemVer below. Breaking changes require a **major** bump.
+
+| Barrel section | What it is |
+|---|---|
+| **Public API** | `createChatTools`, model config helpers, tool/runtime helpers (`ToolContext`, `ToolDeps`, `invokeToolRuntime`, …), `requestContext`. |
+| **Interfaces** | Every `*.interface.ts` port you implement to inject infrastructure (databases, embedder, cache, scraper, queues, integration, agent dispatcher, …). |
+| **Shared schemas** | Zod schemas + inferred types that cross the boundary (questions, identity, network-assignment, chat-context, …). |
+| **Graph factories** | `*GraphFactory` classes (`ChatGraphFactory`, `OpportunityGraphFactory`, `NegotiationGraphFactory`, …). |
+| **Agents** | Structured LLM agents (`UserContextGenerator`, `IndexNegotiator`, `OpportunityEvaluator`, …). |
+| **MCP** | `createMcpServer` and its supporting types. |
+
+### Experimental
+
+Marked `@experimental` in `src/index.ts`. May change in a **minor** release without
+a major bump. Use at your own risk and pin a version if you depend on them.
+
+| Area | What it is |
+|---|---|
+| **States** | Advanced graph-state shapes (`UserNegotiationContext`, `NegotiationTurn`, `NegotiationGraphLike`, …) exposed for advanced graph consumers. |
+| **Internal helpers** | Low-level support utilities re-exported for the backend's own use (selection/eval/evidence helpers) that are not part of the recommended integration surface. |
+
+> Most symbols in the barrel are consumed by the Index Network backend itself; a
+> symbol being absent from the backend's imports does **not** make it dead — it may
+> serve external integrators. Removal therefore follows the deprecation path below,
+> never an ad-hoc delete.
+
+## SemVer policy
+
+This package follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+**MAJOR** — incompatible changes to the Stable surface:
+- Removing or renaming a stable export.
+- Adding a required method/field to an implemented interface, or tightening a
+  return type (e.g. `T | null` → `T` is fine; `T` → `T | null` is breaking).
+- Changing the runtime behavior a documented port contract guarantees
+  (ownership scoping, null-vs-throw semantics, lifecycle idempotency).
+
+**MINOR** — backward-compatible additions:
+- New exports; new **optional** interface members; new graph factories/agents.
+- Any change to an `@experimental` symbol.
+
+**PATCH** — backward-compatible fixes:
+- Bug fixes, performance, prompt/model tuning, doc and type-comment changes that
+  do not alter the contract.
+
+### Port-contract semantics count
+
+Interface ports document invariants in their TSDoc/banner comments — ownership
+scoping (return `null` for missing **or** non-owned rows), null-vs-empty-array
+conventions, and lifecycle idempotency (`mark*` transitions are no-ops once
+terminal). These guarantees are part of the Stable contract: breaking them is a
+**major** change even if the TypeScript signature is unchanged.
+
+## Deprecation path
+
+1. Mark the symbol `@deprecated` in TSDoc with the replacement and target removal version.
+2. Note it under `### Deprecated` in `CHANGELOG.md`.
+3. Keep it working for at least one minor release.
+4. Remove only in a subsequent **major** release.
+
+## Release & publish
+
+- Pushes to `dev` publish an `-rc.<n>` prerelease under the npm `rc` tag.
+- Pushes to `main` publish the stable version under `latest` when the
+  `package.json` version is new (already-published versions are skipped).
+- Bump `package.json` and update `CHANGELOG.md` **before** promoting to `main`.
+
+See `.github/workflows/publish.yml` for the automation and `CHANGELOG.md` for the
+release history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "4.3.1-rc.299.1",
+  "version": "4.3.2-rc.300.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "IMPLEMENTATION.md",
+    "STABILITY.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",