# Ownership boundaries (/docs/ownership) This page answers one question per row: *if I want to change behavior X, whose surface is X, and is it a config field, a plugin hook, or a fork?* It complements the other orientation docs without duplicating them — [Packages](/docs/packages) describes what each SKU does, [Which SKU do I need?](/docs/which-sku) maps tasks to install lists, and this page draws the boundary between the SKU's locked surface and your host code. Every row sorts into one of three columns: | Column | What it means | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Owned by the SKU** | Fixed by the package. The audit gates refuse builds that try to alter it. Your only path here is upstream contribution. | | **You configure** | A typed config field, a plugin hook, or a registered registry. Supported, additive, no forking required. | | **You must supply** | Required at construction. The SKU throws or short-circuits without it. | Two structural pins hold across every SKU: * **The four-stage lattice** — `anchor-plan → tool-loop → synthesize → post-turn`. Every node in every SKU belongs to one of the four stages; see [Graph](/docs/graph) for the gate and [Node catalog](/docs/graph-node-catalog) + [Edge catalog](/docs/graph-edge-catalog) for the enumerated surface. * **The audit row** — one `AuditableCall` row per LLM call, keyed by `turnId`. Every SKU writes through the same row shape; see [`AuditableCall` row](/docs/auditable-call-row) for the schema. You can't disable, replace, or bypass either pin from any extension path. They're substrate, not policy. ## `@pleach/core` — the substrate [#pleachcore--the-substrate] The lattice and the audit ledger. Every other SKU plugs in through `HarnessPlugin`; `@pleach/core` is the only package whose absence breaks the build. | Owned by the SKU | You configure | You must supply | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Four-stage lattice](/docs/graph#the-lattice-gate) | `llmExecutor` — your LLM provider call | At least one LLM provider | | [Channel kinds and reducers](/docs/channels) | `toolExecutor` — tool dispatch | A storage adapter (or the in-memory default) | | [Singleton synthesize seam](/docs/graph#singleton-synthesize-seam) | `subagentExecutor` — subagent runtime construction | The `SessionRuntime` config object | | [`AuditableCall` row shape](/docs/auditable-call-row) | `plugins[]` — a `HarnessPlugin[]` for [extra graph nodes](/docs/graph-node-catalog#plugin-path--add-a-node-alongside-the-canonical-set), tool registration, stream observers | | | [Checkpoint format](/docs/checkpointing) | The 43-name [Node catalog](/docs/graph-node-catalog) — register a subset by omitting the matching executor | | | [`StreamEvent` shapes](/docs/stream-events) | `storage` — a `StorageAdapter` for session persistence | | | [Determinism contract](/docs/determinism) — five substrate rules | `metaToolNames` — names the substrate should treat as meta-tools | | | [Family lock](/docs/family-lock) | `setHarnessModuleLoader` — [host-adapter seam](/docs/host-adapter) for hosts mid-migration | | The canonical decision tree: [Runtime construction](/docs/runtime-construction). The full plugin extension surface: [Plugin contract](/docs/plugin-contract). ## `@pleach/compliance` — scrubbing, hash chain, GDPR [#pleachcompliance--scrubbing-hash-chain-gdpr] PII/PHI redaction, tamper-evident hash chain over the audit ledger, GDPR-style soft-delete (erasure tombstones). | Owned by the SKU | You configure | You must supply | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | | [Hash-chain middleware](/docs/compliance/hashchain-middleware) — the chained-hash format | Per-turn scrubber set via `ComplianceRuntime` | A `ComplianceRuntime` instance | | [GDPR erasure](/docs/compliance/gdpr-erasure) — tombstone shape | Custom [Scrubbers](/docs/scrubbers) (PII, PHI, PCI patterns) | Storage that supports the tombstone write pattern | | Attestation envelope shape ([Attestation](/docs/attestation)) | Detector regexes per data class | | | The `@pleach/compliance-contract` typed surface | The [audit gates](/docs/audit-gates) the hash chain enforces | | `@pleach/compliance` writes through the same audit row `@pleach/core` defines — it doesn't introduce a second ledger. See [Compliance](/docs/compliance). ## `@pleach/gateway` — multi-tenant routing + cost attribution [#pleachgateway--multi-tenant-routing--cost-attribution] Per-tenant model routing, BYOK provider keys, rate limiting, cost event emission. | Owned by the SKU | You configure | You must supply | | ------------------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------- | | [Cost event](/docs/gateway/cost-events) row shape | [BYOK provider keys](/docs/gateway/byok) per tenant | A `GatewayClient` instance | | Routing logic (cost-aware, family-locked) | [Rate limits](/docs/gateway/rate-limit) per tenant or per key | Tenant identifier on every request | | Per-tenant tenant facet — [Tenant facet](/docs/tenant-facet) | [OTel destination](/docs/gateway/otel) for cost rollup | | | | [Migration from `@pleach/core`](/docs/gateway/migration-from-core) routing | | Per-tenant cost attribution rolls up through the same `AuditableCall` row — `tenantId` is a column, not a side-table. See [Gateway](/docs/gateway) and [Multi-tenant](/docs/multi-tenant). ## `@pleach/observe` — hosted observability + Export Bridge [#pleachobserve--hosted-observability--export-bridge] OTel-instrumented spans across the lattice. Read [Observe](/docs/observe) for the SKU framing. | Owned by the SKU | You configure | You must supply | | ---------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | Span structure across the four stages | Destinations — Postgres, Supabase, OTel collector, custom webhook | An OTel collector, Postgres, or destination of your choice | | Trace ID propagation through `AuditableCall` | Per-tenant routing of spans | | | Cost rollup integration with `@pleach/gateway` | Retention rules at the destination | | `@pleach/observe` is destination-flexible. The library writes audit rows through existing `@pleach/core` `ProviderDecisionLedger` adapters; the destination is yours. ## `@pleach/eval` — deterministic replay + diff [#pleacheval--deterministic-replay--diff] Regression testing against the audit ledger. Replays past turns through the same node graph and diffs the output. | Owned by the SKU | You configure | You must supply | | ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------- | | Deterministic replay engine | [Eval parity](/docs/eval/parity) thresholds | A `ReplayClient` instance from `@pleach/replay` | | Diff format over `AuditableCall` rows | Replay-time seam binding | Source audit rows to replay against | | Lifecycle hook reads — `onToolCompleted`, `onMessageAdded` | Per-eval node-graph subset | | `@pleach/eval` consumes `@pleach/replay`'s `ReplayClient` via DI. The split lifecycle hooks let it read the same ledger every SKU writes through. See [`@pleach/eval`](/docs/eval). ## `@pleach/replay` — event-granular session forking [#pleachreplay--event-granular-session-forking] Forks a session from any checkpoint or any event. The substrate carrier for `@pleach/eval` but usable independently. | Owned by the SKU | You configure | You must supply | | -------------------------------------------------- | -------------------------------------------------------- | ----------------------------- | | Fork algorithm (event-granular, not turn-granular) | Checkpoint storage backend (via core's `StorageAdapter`) | A source session to fork from | | [Lineage](/docs/lineage) record format | Per-fork seam re-binding | | | Replay determinism contract — node-level | | | See [Replay](/docs/replay) and [Time travel](/docs/time-travel). ## `@pleach/mcp` — MCP server + client [#pleachmcp--mcp-server--client] Wraps Pleach sessions as Model Context Protocol servers, and consumes external MCP servers as Pleach tools. | Owned by the SKU | You configure | You must supply | | --------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------- | | MCP transport (Streamable HTTP per protocol `2025-06-18`) | Tool exposure — which Pleach tools become MCP tools | The session config that backs the server | | Resource and prompt handlers | Resource list | | | Tools/list, tools/call, ping, notifications handlers | External MCP servers to consume as tools | | See [`@pleach/mcp`](/docs/mcp) and [MCP integration](/docs/mcp-integration). ## `@pleach/tools` + `@pleach/base-tools` — tool primitives [#pleachtools--pleachbase-tools--tool-primitives] Generic tool primitives (`@pleach/tools`) and a curated base set (`@pleach/base-tools`). | Owned by the SKU | You configure | You must supply | | ------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- | | Tool interface — name, schema, executor | Tool registration through `SessionRuntimeConfig.toolRegistry` | The tool's executor function | | Structured-parse and filesystem primitives | Per-tool seam binding | Permissions and sandbox boundaries for filesystem/shell tools | | Tool result row shape — feeds the post-tool chain | Tool result post-processing through plugin nodes | | Pleach's tool contract is the same shape regardless of whether the tool comes from `@pleach/base-tools`, your own code, or an MCP server. See [Tools](/docs/tools). ## `@pleach/coding-agent` + `@pleach/sandbox` — sandboxed code execution [#pleachcoding-agent--pleachsandbox--sandboxed-code-execution] A coding-agent recipe (`@pleach/coding-agent`) plus the sandbox primitives it sits on (`@pleach/sandbox`). | Owned by the SKU | You configure | You must supply | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------ | | Sandbox lifecycle — boot, exec, snapshot, teardown | [Sandbox provider](/docs/coding-agent/sandbox-providers) (Vercel Sandbox, Docker, custom) | Sandbox provider credentials | | [File tools](/docs/coding-agent/file-tools) — read, write, patch | [Multi-synthesize](/docs/coding-agent/multi-synthesize) parameters | The repo or workspace to mount | | [Long-session](/docs/coding-agent/long-session) checkpointing | Per-task tool subset | | | [SWE-bench recipe](/docs/coding-agent/swe-bench-recipe) — eval shape | | | See [`@pleach/coding-agent`](/docs/coding-agent). ## `@pleach/react` — React hooks + components [#pleachreact--react-hooks--components] Hook surface for client-side chat UI. Server-side runtime construction is in [`@pleach/core`](/docs/core); this package owns the React-specific shape. | Owned by the SKU | You configure | You must supply | | ------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------- | | `useChat`, `useSession`, `useStream` hook shapes | UI components, layout, styling | A backend route that proxies to the runtime (typically `createPleachRoute`) | | `HarnessProvider` context shape | Hook subscription behavior | | | [Building chat UI](/docs/building-chat-ui) component patterns | | | See [`@pleach/react`](/docs/react). ## `@pleach/langchain` — LangChain / LangGraph adapter [#pleachlangchain--langchain--langgraph-adapter] Adapter that lets a LangChain agent run as a Pleach node, and lets a Pleach session feed a LangGraph. | Owned by the SKU | You configure | You must supply | | ------------------------------------------------------------------ | ------------------------- | --------------------------------- | | Adapter shapes both directions | Per-call adapter wiring | A LangChain or LangGraph instance | | State-mapping between LangChain `BaseMessage` and Pleach `Message` | Tool-translation strategy | | See [`@pleach/langchain`](/docs/langchain) and [Migrating from LangChain](/docs/migrating-from-langchain). ## Transport packages — `@pleach/transport-bedrock`, `@pleach/transport-azure-openai`, `@pleach/transport-vertex` [#transport-packages--pleachtransport-bedrock-pleachtransport-azure-openai-pleachtransport-vertex] Provider-side transport adapters for AWS Bedrock, Azure OpenAI, and Google Vertex. | Owned by the SKU | You configure | You must supply | | -------------------------------------- | ------------------------ | --------------------- | | The transport's wire-shape translation | Per-region endpoints | Provider credentials | | Provider-specific retry and backoff | Model identifier mapping | Account or project ID | | Streaming envelope adaptation | | | See [`@pleach/transport-bedrock`](/docs/transport-bedrock), [`@pleach/transport-azure-openai`](/docs/transport-azure-openai), [`@pleach/transport-vertex`](/docs/transport-vertex). ## Cross-SKU concerns [#cross-sku-concerns] A few surfaces span multiple SKUs. The boundary on those is structural — the SKUs each own a slice but the contract is shared. ### The audit ledger row [#the-audit-ledger-row] Every SKU writes through one `AuditableCall` row shape, keyed by `turnId`. See [`AuditableCall` row](/docs/auditable-call-row). | SKU | Writes | Reads | | -------------------- | ------------------------------------------------------------- | -------------------------------- | | `@pleach/core` | The row itself; `nodeId`, `stageId`, `tokenUsage`, `toolName` | — | | `@pleach/compliance` | `hashChainPrev`, `hashChainSelf`, scrubber tombstones | Self-validates the chain at read | | `@pleach/gateway` | `tenantId`, `providerKey`, `costEvent` | Per-tenant rollup | | `@pleach/observe` | OTel span IDs threaded onto the row | Whole row for span construction | | `@pleach/eval` | — | Whole row for replay | | `@pleach/replay` | `lineageParent` for forked sessions | Source row for the fork | ### Cost rollup [#cost-rollup] Two SKUs participate. `@pleach/core` rolls token usage per turn; `@pleach/gateway` rolls cost per tenant by joining the `AuditableCall` row to its `costEvent` extension. See [Cost events](/docs/gateway/cost-events). ### Storage [#storage] `@pleach/core` defines the `StorageAdapter` interface; every SKU that persists data uses it. See [Storage](/docs/storage) for the adapter shape and the bundled implementations. ### Determinism [#determinism] The five substrate-level rules are in [Determinism](/docs/determinism). Every SKU that registers a node must satisfy them — same input state, same partial-state output. ## Quick lookup — "I want to change X" [#quick-lookup--i-want-to-change-x] | You want to | Surface | Path | | -------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Add a node to the canonical graph | `@pleach/core` | Plugin — `HarnessPlugin.extraGraphNodes()`. See [Node catalog — plugin path](/docs/graph-node-catalog#plugin-path--add-a-node-alongside-the-canonical-set) | | Remove a node from the canonical graph | `@pleach/core` | Config — omit the gated executor. See [Node catalog — config omission](/docs/graph-node-catalog#config-omission--remove-a-gated-node) | | Wire a fully custom topology | `@pleach/core` | Custom builder — raw `StateGraph`. See [Node catalog — custom builder](/docs/graph-node-catalog#custom-builder--full-control) | | Add a new edge inside the lattice | `@pleach/core` | Plugin or custom builder; lattice gate still binds. See [Edge catalog](/docs/graph-edge-catalog#plugin-path--edges-around-a-plugin-registered-node) | | Change the four-stage lattice itself | `@pleach/core` | Upstream contribution only. See [Edge catalog — removing an allowed pattern](/docs/graph-edge-catalog#removing-an-allowed-pattern) | | Swap the LLM provider | `@pleach/core` | Config — `llmExecutor`. See [Providers](/docs/providers) | | Add a tool | `@pleach/core` + `@pleach/tools` | Config — `toolRegistry` or `contributeTools` plugin hook. See [Tools](/docs/tools) | | Scrub PII from prompts | `@pleach/compliance` | Configured `Scrubber` set. See [Scrubbers](/docs/scrubbers) | | Verify the audit chain hasn't been tampered with | `@pleach/compliance` | [Hash-chain middleware](/docs/compliance/hashchain-middleware) | | Route per-tenant on a different provider key | `@pleach/gateway` | [BYOK](/docs/gateway/byok) | | Send spans to Datadog / Honeycomb / your collector | `@pleach/observe` | Destination config — see [Observe](/docs/observe) | | Replay a past turn and diff | `@pleach/eval` + `@pleach/replay` | Lifecycle hooks. See [Eval and replay](/docs/eval-and-replay) | | Fork a session at an event | `@pleach/replay` | `ReplayClient.forkAt(eventId)`. See [Replay](/docs/replay) | | Expose Pleach as an MCP server | `@pleach/mcp` | MCP transport config. See [`@pleach/mcp`](/docs/mcp) | | Run a coding agent against a repo | `@pleach/coding-agent` + `@pleach/sandbox` | Sandbox provider config. See [`@pleach/coding-agent`](/docs/coding-agent) | | Build a chat UI in React | `@pleach/react` | Hook surface. See [Building chat UI](/docs/building-chat-ui) | | Stream from AWS Bedrock / Azure OpenAI / Vertex | matching transport SKU | Transport package config. See [Transport — Bedrock](/docs/transport-bedrock), [Azure](/docs/transport-azure-openai), [Vertex](/docs/transport-vertex) | | Migrate from LangChain | `@pleach/langchain` | Adapter. See [Migrating from LangChain](/docs/migrating-from-langchain) | | Change the `AuditableCall` row shape | `@pleach/core` | Upstream contribution only. The row shape is a cross-SKU contract | | Change the determinism rules | `@pleach/core` | Upstream contribution only. See [Determinism](/docs/determinism) | ## Where to go next [#where-to-go-next]