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

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.
• Anchor-plan — The first stage — intent detection, plan generation, anchor messages. See full entry.
• Tool-loop — The second stage — iterative LLM-decision and tool-execution that may self-loop until the plan resolves. See full entry.
• Synthesize — The user-facing final-answer call class, capped at one per turn by default. See full entry.
• SessionRuntime — Per-session entry point owning the compiled graph, the channels, and the lifecycle. See full entry.

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.
• Family — Semantic provider origin locking tokenizer, prompt-cache key, tool-call dialect, and refusal pattern at session start. See full entry.
• Family-strict cascade — Provider fallback policy walking in-family rungs only; cross-family widening is consumer-initiated. See full entry.
• Matrix — The (ProviderFamily × CallClass) resolution table — authoritative for what model fires for what call class. See full entry.
• ProviderSeam — Per-CallClass seam contract for LLM invocation, exactly one per call class per runtime. See full entry.
• Seam — Boundary between subsystems with a typed contract; the stream-observer contract lives at the seam boundary. See full entry.
• Native — A provider transport that calls the provider's official SDK directly. See full entry.

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.
• Checkpointer — Swappable backend persisting graph state snapshots so the runtime can time-travel via checkpoint() / restore(). See full entry.
• Adapter — Concrete implementation of an interface for a specific vendor — storage adapters, checkpoint savers, and provider transports. See full entry.
• Fork — A new SessionRuntime sharing its parent's event log up to a cutoff and running independently after. See full entry.
• Event-granular fork — Forking a session at any specific event, not only at checkpoint boundaries. See full entry.

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.
• Determinism — A recorded session replayed against the same package version and input produces a byte-identical fingerprint stream. See full entry.
• Replay — Re-running a recorded turn against the same package version and input; @pleach/replay ships strict mode. See full entry.
• Strict mode — @pleach/replay's mode that fails on any divergence between recorded and replayed events. See full entry.
• Hash chain — prev_hash + row_hash columns on harness_event_log; verification reports the first index where the chain breaks. See full entry.
• Attestation — Signed manifest of a Pleach run's metadata — models, prompts, tools, event-chain hash. See full entry.
• Verification — Running chain and determinism verifiers over a recorded session. See full entry.

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.
• Stream observer — Per-chunk dispatch on the inbound provider stream returning continue, amend, emit, or halt. See full entry.
• Redaction gate — Contract for transforming or dropping data before provider calls, per-message granularity. See full entry.
• Scrubber — Redaction-gating step at the EventLogWriter write site declaring an event-type allowlist. See full entry.
• KeyedRegex — Parameterized regex scrubber consumers extend for custom regulated identifiers like MRN or EIN. See full entry.
• Facet — Named accessor grouping related runtime methods — runtime.tenant.id replaces runtime.getTenantId(). See full entry.

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.
• OTel span types — The four spans emitted — session.turn, llm.invocation, graph.stage, tool.execution. See full entry.
• pleach.tenant_id — OTel attribute set on every emitted span when runtime.tenant is configured. See full entry.
• Tenant — Scoping unit carried as organizationId on every event and every audit row for single-predicate ledger queries. See full entry.

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

BYOK — Bring Your Own Key. Provider credentials supplied by the consumer rather than by Pleach. Available transports include byok-native and byok-openrouter.

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.

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 and Stream events.

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

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 — 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

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.

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 for commercial-use guidance and 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 entry above for the current license posture.

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.

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.

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

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, 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

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 and Compliance.

L

Lattice — See Stage lattice.

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

Native — A provider transport that calls the provider's official SDK directly (e.g. @anthropic-ai/sdk). Contrasts with the OpenRouter transport.

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.

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 and Tenant facet.

Projection — Synonym for GraphProjection<T>. See GraphProjection.

ProviderFamily — See Family.

ProviderSeam — The per-CallClass seam contract for LLM invocation. Exactly one seam per call class per runtime.

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.

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.

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 page.

Stage lattice — The four-stage agent graph topology: anchor-plan | tool-loop | synthesize | post-turn. Out-of-lattice edges fail CI. See 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.

Synthesize — One of the four call classes — the user-facing final-answer LLM call. Capped at one per turn by default.

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.

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

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.

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