# Glossary (/docs/glossary) When the docs disagree with a published package README, the README wins — these definitions are aligned with the public state of each `@pleach/*` package as of the most recent cut. The six clusters below orient you to the substrate; the A-Z reference further down is the lookup table. ## Concept clusters [#concept-clusters] ### Lifecycle [#lifecycle] The four-stage path a turn walks from intent to terminal message. * **Stage lattice** — The four-stage agent graph topology — `anchor-plan | tool-loop | synthesize | post-turn`. See [full entry](#s). * **Anchor-plan** — The first stage — intent detection, plan generation, anchor messages. See [full entry](#a). * **Tool-loop** — The second stage — iterative LLM-decision and tool-execution that may self-loop until the plan resolves. See [full entry](#t). * **Synthesize** — The user-facing final-answer call class, capped at one per turn by default. See [full entry](#s). * **SessionRuntime** — Per-session entry point owning the compiled graph, the channels, and the lifecycle. See [full entry](#s). ### Routing [#routing] How a call class binds to a model family at session start and stays bound. * **CallClass** — One of `utility`, `reasoning`, `converse`, or `synthesize` — discriminates internal calls from user-facing answer composition. See [full entry](#c). * **Family** — Semantic provider origin locking tokenizer, prompt-cache key, tool-call dialect, and refusal pattern at session start. See [full entry](#f). * **Family-strict cascade** — Provider fallback policy walking in-family rungs only; cross-family widening is consumer-initiated. See [full entry](#f). * **Matrix** — The `(ProviderFamily × CallClass)` resolution table — authoritative for what model fires for what call class. See [full entry](#m). * **ProviderSeam** — Per-`CallClass` seam contract for LLM invocation, exactly one per call class per runtime. See [full entry](#p). * **Seam** — Boundary between subsystems with a typed contract; the stream-observer contract lives at the seam boundary. See [full entry](#s). * **Native** — A provider transport that calls the provider's official SDK directly. See [full entry](#n). ### State [#state] The typed reactive slots and persistence backends carrying turn state. * **Channel** — Typed reactive state slot inside the compiled graph with per-kind concurrent-write semantics. See [full entry](#c). * **Checkpointer** — Swappable backend persisting graph state snapshots so the runtime can time-travel via `checkpoint()` / `restore()`. See [full entry](#c). * **Adapter** — Concrete implementation of an interface for a specific vendor — storage adapters, checkpoint savers, and provider transports. See [full entry](#a). * **Fork** — A new `SessionRuntime` sharing its parent's event log up to a cutoff and running independently after. See [full entry](#f). * **Event-granular fork** — Forking a session at any specific event, not only at checkpoint boundaries. See [full entry](#e). ### Audit & determinism [#audit--determinism] The append-only record and the contract that lets it replay byte-identically. * **Event log** — Append-only record of observable events in a session — messages, tool calls, interrupts, exports. See [full entry](#e). * **Determinism** — A recorded session replayed against the same package version and input produces a byte-identical fingerprint stream. See [full entry](#d). * **Replay** — Re-running a recorded turn against the same package version and input; `@pleach/replay` ships strict mode. See [full entry](#r). * **Strict mode** — `@pleach/replay`'s mode that fails on any divergence between recorded and replayed events. See [full entry](#s). * **Hash chain** — `prev_hash` + `row_hash` columns on `harness_event_log`; verification reports the first index where the chain breaks. See [full entry](#h). * **Attestation** — Signed manifest of a Pleach run's metadata — models, prompts, tools, event-chain hash. See [full entry](#a). * **Verification** — Running chain and determinism verifiers over a recorded session. See [full entry](#v). ### Extension [#extension] The consumer contracts for adding tier nodes, observers, contributors, and redaction. * **HarnessPlugin** — Consumer extension contract — registers tier nodes, stream observers, prompt contributors, and redaction gates without rewriting the lattice. See [full entry](#h). * **Stream observer** — Per-chunk dispatch on the inbound provider stream returning `continue`, `amend`, `emit`, or `halt`. See [full entry](#s). * **Redaction gate** — Contract for transforming or dropping data before provider calls, per-message granularity. See [full entry](#r). * **Scrubber** — Redaction-gating step at the `EventLogWriter` write site declaring an event-type allowlist. See [full entry](#s). * **KeyedRegex** — Parameterized regex scrubber consumers extend for custom regulated identifiers like MRN or EIN. See [full entry](#k). * **Facet** — Named accessor grouping related runtime methods — `runtime.tenant.id` replaces `runtime.getTenantId()`. See [full entry](#f). ### Observability [#observability] The spans, OTEL hook, and tenant attribute the substrate emits for trace queries. * **OTEL** — OpenTelemetry — Pleach exposes an OTEL adapter hook so spans cover session boundaries and per-call seams. See [full entry](#o). * **OTel span types** — The four spans emitted — `session.turn`, `llm.invocation`, `graph.stage`, `tool.execution`. See [full entry](#o). * **`pleach.tenant_id`** — OTel attribute set on every emitted span when `runtime.tenant` is configured. See [full entry](#p). * **Tenant** — Scoping unit carried as `organizationId` on every event and every audit row for single-predicate ledger queries. See [full entry](#t). ## A [#a] **Adapter** — A concrete implementation of an interface for a specific vendor. Storage adapters, checkpoint savers, and provider transports are all examples. Adapters live in the package that owns their interface. **Anchor-plan** — The first stage of the four-stage lattice. The turn boots here: intent detection, plan generation, anchor messages. **Attestation** — A signed manifest of a Pleach run's metadata (models used, prompts, tools, event-chain hash). Issued by `@pleach/compliance`. ## B [#b] **BYOK** — Bring Your Own Key. Provider credentials supplied by the consumer rather than by Pleach. Available transports include `byok-native` and `byok-openrouter`. ## C [#c] **Cache backend** — Runtime-side memoization of prepared LLM inputs via the `CacheBackend` contract. Default is `memoryCacheBackend` (1000 entries / 64 MB) since substrate adopted it as always-on. Distinct from provider-side prompt caching. See [Cache](/docs/cache). **Cache key** — The composite key used to look up cached LLM and tool responses. Includes the family, model, call class, and content hashes of the prompt and tool arguments. The fingerprint module (`computeFingerprint`) is the deterministic, platform-uniform hasher that produces the content-hash component — identical inputs on Node, Browser, Edge, and Cloudflare runtimes produce identical fingerprints, which is what lets a recorded turn replay against a different runtime and still hit the same cache entries. **CallClass** — One of `utility`, `reasoning`, `converse`, or `synthesize`. Discriminates internal classification calls from user-facing answer composition. The literal is restricted by lint to seam factories, so it can't be passed around as a runtime string. **Channel** — A typed reactive state slot inside the compiled graph (`LastValue`, `BinaryOperatorAggregate`, `Topic`, `EphemeralValue`, `NamedBarrier`, `DataChannel`). Nodes fire when a subscribed channel advances; concurrent-write semantics are defined per channel kind. **Checkpointer** — A swappable backend that persists graph state snapshots so the runtime can time-travel via `checkpoint()` / `restore()`. Memory, IndexedDB, and Supabase implementations ship in `@pleach/core`. **Content-hash cache** — A cache keyed on the hash of the prompt plus tool arguments, so identical inputs hit identical entries across runs and across streaming / non-streaming invocations. **Content delta** — `content.delta` event type — one chunk of streaming model output. `messageProjection` folds these into the terminal message at end-of-turn. See [Event log projections](/docs/event-log-projections) and [Stream events](/docs/stream-events). ## D [#d] **Determinism** — The property that a recorded Pleach session, replayed against the same package version + the same input, produces a byte-identical fingerprint stream. The contract behind `@pleach/eval` and `@pleach/replay`. ## E [#e] **Event log** — The append-only record of observable events in a session: messages sent, tool calls dispatched and completed, interrupts raised and resolved, exports queued. Distinct from the [audit ledger](#a) — the event log captures *what happened*, the ledger captures *every decision*. **Event-granular fork** — Forking a session at any specific event, not only at checkpoint boundaries. Enables targeted replay against historical runs. ## F [#f] **Facet** — A named accessor that groups related runtime methods. `runtime.tenant.id` replaces `runtime.getTenantId()`. Facets are the canonical accessor pattern; flat methods stay shipped with `@deprecated` JSDoc. See [Facets](/docs/facets). **Family** — Semantic provider origin. One of `anthropic`, `openai`, `google`, `deepseek`, `moonshot`, or `mistral`. Locks tokenizer, prompt-cache key, tool-call dialect, and refusal pattern at session start. **Family-strict cascade** — The provider fallback policy: when a primary model fails, the cascade walks in-family rungs only. Cross- family widening is explicit and consumer-initiated — never silent. **Fork** — A new `SessionRuntime` that shares its parent's event log up to a specified cutoff and runs independently after. **FSL-1.1-Apache-2.0** — The Functional Source License (1.1) with Apache 2.0 as the future license — the current license posture for every shipping `@pleach/*` package. Source-available, usable in production, free of charge during the FSL window; the only restriction is on competing offerings. Auto-transitions to permissive Apache 2.0 two years after first stable publish. See [Pricing](/pricing) for commercial-use guidance and [Versioning](/docs/versioning) for the per-SKU license lock. **Apache-2.0** — The OSI-approved permissive license that `@pleach/*` packages auto-convert to two years after first stable publish under the FSL future-license clause. Permits commercial use, modification, and redistribution with attribution. See the [FSL-1.1-Apache-2.0](#f) entry above for the current license posture. ## G [#g] **GraphProjection** — The fold contract over the event log: an initial state, a reducer `(state, row) → state`, and an optional selector. `runtime.events.fold(projection, opts)` runs it to completion. See [Event log projections](/docs/event-log-projections). ## H [#h] **Hash chain** — `prev_hash` + `row_hash` columns on `harness_event_log`. Each row's `prev_hash` is the previous row's `row_hash`; verification reports the first index where the chain breaks. The `TamperEvidence` plug-point in `@pleach/core/audit` ships a no-op default; the live verifier ships in `@pleach/core/eventLog` as `verifyChainForChat` + `generateProof`. The writer-side stamping lives in `@pleach/core/eventLog` (`chainStep`, `computeRowHash`) behind the `c9PhaseBEnabled` flag. See [Hash chain](/docs/hash-chain). **Harness** — A generic agent runtime that runs the turn loop. `@pleach/core` is a harness — it executes turns but doesn't dictate the topology of your application around it. **HarnessPlugin** — The consumer extension contract. A plugin can register tier nodes, stream observers, prompt contributors, and redaction gates; it cannot rewrite the lattice or bypass the synthesize seam. ## I [#i] **Interrupt** — A pause in the agent loop where the user must approve or modify a pending action. Per-tool granularity, recorded in the event log. The interrupt envelope follows the LangGraph-shape contract documented under [Interrupts](/docs/interrupts), so a host that already speaks the LangGraph approval shape can wire an existing approval UI against the same payload. The ledger records the resolution as an `interruptDecision` row carrying the human's verdict, joinable back to the `turnId` that triggered the pause. ## K [#k] **KeyedRegex** — One of the four bundled scrubbers in `@pleach/compliance`. A parameterized regex scrubber consumers extend for custom regulated identifiers (MRN, EIN, etc.). See [Scrubbers](/docs/scrubbers) and [Compliance](/docs/compliance). ## L [#l] **Lattice** — See [Stage lattice](#s). ## M [#m] **Matrix** — The `(ProviderFamily × CallClass)` model resolution table. Authoritative for what model fires for what call class in what family. Locked at session start, never silently widened. **MCP** — Model Context Protocol. The Anthropic-driven standard for tool integration. `@pleach/mcp` ships an MCP client and server. ## N [#n] **Native** — A provider transport that calls the provider's official SDK directly (e.g. `@anthropic-ai/sdk`). Contrasts with the OpenRouter transport. ## O [#o] **OpenRouter** — A multi-provider routing service. Available as a Pleach transport, including in a BYOK variant. **OTEL** — OpenTelemetry. Pleach exposes an OTEL adapter hook so spans cover session boundaries and per-call seams without re- implementing observability in every consumer. **OTel span types** — The four spans the substrate emits: `session.turn`, `llm.invocation`, `graph.stage`, `tool.execution`. Parent-thread naturally per turn. `runtime.spans.snapshot()` reads them in-process. See [OTel observability](/docs/otel-observability). ## P [#p] **Pleach** — The harness's name. Pleaching is a centuries-old horticultural technique: weave the living branches of adjacent trees together so they grow into a single, structurally coherent hedge. That's the metaphor for the runtime — each LLM call, tool execution, plugin contribution, and channel write is a branch; the lattice + audit ledger + family lock + singleton synthesize seam are how those branches are *pleached* into a structure that carries weight a single `streamText` call cannot. **`pleach.tenant_id`** — OTel attribute set on every emitted span when `runtime.tenant` is configured (or `withTenantHeader` wraps outbound HTTP). The load-bearing field for per-tenant trace queries. See [OTel observability](/docs/otel-observability) and [Tenant facet](/docs/tenant-facet). **Projection** — Synonym for `GraphProjection`. See [GraphProjection](#g). **ProviderFamily** — See [Family](#f). **ProviderSeam** — The per-`CallClass` seam contract for LLM invocation. Exactly one seam per call class per runtime. ## R [#r] **Redaction gate** — The contract for transforming or dropping data before provider calls. Per-message granularity. Distinct from stream observers, which act per-chunk on the response. **Replay** — Re-running a recorded turn against the same package version + the same input. `@pleach/replay` ships a strict mode that fails on any divergence between recorded and replayed events. **RLS** — Row-Level Security. The Postgres feature Pleach's Supabase storage adapter relies on for tenant isolation. **`runtime.tenant`** — The facet exposing the read-only `id` and `subId` properties. Read tenant scope through the facet rather than constructor config. See [Tenant facet](/docs/tenant-facet). ## S [#s] **Sandbox** — A code-execution boundary. The `SandboxProvider` interface lives in `@pleach/coding-agent`; adapters cover hosted sandboxes (Modal, E2B, Daytona) and Vercel's sandboxing surface. **Scrubber** — A redaction-gating step at the `EventLogWriter` write site. Declares an event-type allowlist; redacts matched patterns before persistence. Four ship in `@pleach/compliance`. Hosts register more via `contributeScrubbers`. See [Scrubbers](/docs/scrubbers). **Seam** — A boundary between subsystems with a typed contract. `ProviderSeam` is the canonical example. The stream-observer contract lives at the seam boundary. **SessionRuntime** — The per-session entry point — owns the compiled graph, the channels, the seam-bound provider calls, and the lifecycle. **Singleton synthesize-seam invariant** — Exactly one `ProviderSeam<"synthesize">` per `SessionRuntime`, structurally enforced. The reason: if two synthesize calls fired and the runtime showed one, the audit ledger and the rendered UI would disagree on what the model said. **SKU** — A separately-installable npm package in the `@pleach/*` namespace. The current matrix is documented on the [Packages](/docs/packages) page. **Stage lattice** — The four-stage agent graph topology: `anchor-plan | tool-loop | synthesize | post-turn`. Out-of-lattice edges fail CI. See [Architecture](/docs/architecture) for the deep dive. **Stream observer** — A per-chunk dispatch on the inbound provider stream. Observer factories register through `HarnessPlugin`. Each `onChunk(chunk, ctx)` returns a verdict: `continue`, `amend`, `emit`, or `halt`. Sync-only — replay determinism armor. **Strict mode** — `@pleach/replay`'s mode that fails on any divergence between recorded and replayed events. Throws `ReplayDivergenceError`. **`subTenantId`** — The secondary scoping field on `SessionRuntimeConfig` (nested isolation: tenant → team, or org → sub-account). Flows through alongside `tenantId` to every downstream write site. See [Tenant facet](/docs/tenant-facet). **Synthesize** — One of the four call classes — the user-facing final-answer LLM call. Capped at one per turn by default. ## T [#t] **Tenant** — A scoping unit for multi-tenant deployments. Carried as `organizationId` on the runtime config and as a required field on every event and every `AuditableCall` row, so a tenant-scoped query against the ledger or event log is a single `WHERE organization_id = $1` predicate against an indexed column rather than a join through a session table. The RLS template shipped with the schema bundle parameterizes on the same column for row-level isolation at the Postgres layer. **Tool-loop** — The second stage of the four-stage lattice. The iterative LLM-decision and tool-execution loop. May self-loop until the plan resolves. **Typed record** — One of the five typed, stage-correlated audit-record slots: `InterruptDecisionRecord`, `TokenCostRecord`, `ToolSelectionTrace`, `PlanGenerationRecord`, `SynthesisQualityRecord`. Narrow on the named slot's presence (correlated with `stageId`). See [Typed records](/docs/typed-records). ## V [#v] **Verification** — Running chain and determinism verifiers over a recorded session. Confirms hash-chain integrity and replay determinism. Shipped by `@pleach/compliance` and `@pleach/replay`. ## W [#w] **`withTenantHeader`** — Adapter that wraps a fetch client and stamps a tenant header on outbound HTTP. For hosts behind an upstream gateway that routes by tenant header. See [Tenant facet](/docs/tenant-facet). ## Z [#z] **Zod** — The TypeScript schema validation library. Pleach uses Zod for tool input/output schemas; JSON Schema is available as an escape hatch. ## Where to go next [#where-to-go-next]