# Subpath exports (/docs/subpath-exports)
`@pleach/core` ships an ESM-first export map with both `import`
and `require` entries (the package is `type: module`; CommonJS
consumers get `.cjs` builds). Below: the named subpaths consumers
should rely on, plus the wildcard escape hatch and what it costs
you.
Snapshot is for `@pleach/core@1.x`. The canonical list lives in
the package's `package.json` and is watched by
`audit:package-export-validation` upstream.
## Named subpaths [#named-subpaths]
`stable` means the path is named in the published `exports` map and
watched by the upstream package-export audit. Removal or rename goes
through a deprecation cycle. Each subpath ships ESM (`.js`), CJS
(`.cjs`), and types (`.d.ts`) — see [Dual-format builds](#dual-format-builds).
### Substrate runtime [#substrate-runtime]
| Import | Ships | Stability |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core` | Root barrel — `SessionRuntime`, factories, runtime types | stable |
| `@pleach/core/SessionRuntime` | `SessionRuntime` class, direct entry (barrel sidesteps tree-shaking) | stable |
| `@pleach/core/runtime` | Process-scoped registries + module-loader indirection | stable |
| `@pleach/core/runtime/createPleachRuntime` | `createPleachRuntime`, `TurnOrchestrator`, host-injection types | stable |
| `@pleach/core/quickstart` | Zero-config starter surface — `createPleachRoute` (fetch-handler factory), `useChat` (Pleach-native React hook), `` (unstyled, accessible), `defaultPlugin`, `createBenchmarkPlugin`, `providerDetection` (`detectProvider`, `detectAvailableProviders`, `DEFAULT_PROVIDER_ENV_VARS`, `DEFAULT_PROVIDER_PRIORITY`). What `npx pleach init` scaffolds against. See [The quickstart subpath](/docs/getting-started#the-quickstart-subpath). | stable |
### Type subpaths [#type-subpaths]
Narrowed deep-path type entries landed via the pa3prep cluster 15 sweep —
type-only deep paths were promoted from wildcard reach to named entries so
consumers don't pay the wildcard's instability cost on contracts.
| Import | Ships | Stability |
| -------------------------------------- | ------------------------------------ | --------- |
| `@pleach/core/types` | Public type definitions (re-exports) | stable |
| `@pleach/core/types/command` | `Command` + `isCommand` brand | stable |
| `@pleach/core/types/dynamicAppModules` | Dynamic-app-module type registry | stable |
| `@pleach/core/types/generic` | Generic runtime types | stable |
| `@pleach/core/types/singleTurn` | Single-turn body contract types | stable |
| `@pleach/core/types/strategies` | Strategy registration types | stable |
### Persistence + state [#persistence--state]
| Import | Ships | Stability |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core/sessions` | Session-state adapters — `MemoryAdapter`, `IndexedDBAdapter`, `SupabaseAdapter` | stable |
| `@pleach/core/checkpointing` | Checkpoint savers — `MemorySaver`, `IndexedDBSaver`, `SupabaseSaver` | stable |
| `@pleach/core/sync` | Version-vector sync utilities | stable |
| `@pleach/core/store` | KV store — `BaseStore`, `MemoryStore`, `SupabaseStore`, `MemoryNamespaces` | stable |
| `@pleach/core/cache` | In-memory cache backend (`createMemoryCacheBackend`) + content-hash deriver (`deriveContentHashKey`, `canonicalizeKeyInput`, `ContentHashKeyInput` — re-exported by `@pleach/replay/cache`) | stable |
| `@pleach/core/schema` | Generated row-shape types + SQL bundle | stable |
| `@pleach/core/schema/postgres/*.sql` | Raw SQL migrations (asset import) | stable |
### Event log + projections [#event-log--projections]
| Import | Ships | Stability |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `@pleach/core/eventLog` | `EventLogWriter`, `EventLogClient`, `hydrateFromEvents`, `GraphProjection` | stable |
| `@pleach/core/manifest` | Chat-manifest — `createDefaultChatManifestProvider` (the `[Session Manifest]` ledger + section render), checkpoint/reload persistence (`stampManifestIntoState`, `restoreManifestFromState`), and `chatManifestProjection` / `foldChatManifest` (the manifest as an event-log projection) | experimental |
### Audit, attestation, scrub [#audit-attestation-scrub]
| Import | Ships | Stability |
| ------------------------------------ | ------------------------------------------------------------------------ | --------- |
| `@pleach/core/audit` | `AuditableCall` ledger primitives + no-op plug-points | stable |
| `@pleach/core/attestation` | Attestation module — signer, verifier, canonical envelope | stable |
| `@pleach/core/attestation/keyStores` | Pluggable key-store backends (memory, env, KMS adapters) | stable |
| `@pleach/core/attestation/testing` | Test fixtures + harness for attestation flows | stable |
| `@pleach/core/scrubbers` | C8 redaction surface — `SCRUBBABLE_FIELDS` allowlist + scrubber registry | stable |
### Prompts + prompt-builder [#prompts--prompt-builder]
| Import | Ships | Stability |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core/prompts` | C12 prompt-contribution contract — `PromptContributionRegistry`, `PromptContribution`, 41 Phase H universal templates | stable |
| `@pleach/core/prompts/examples` | Reference prompt contributors | stable |
| `@pleach/core/prompt-builder` | Phase F generic composition — `composeBudgetedPrompt` + diagnostics | stable |
| `@pleach/core/prompt-builder/sections` | Section primitives | stable |
| `@pleach/core/prompt-builder/examples` | Reference section assemblies | stable |
### Safety [#safety]
| Import | Ships | Stability |
| ------------------------------ | --------------------------------------------------------------------- | --------- |
| `@pleach/core/safety` | `SafetyPolicyRegistry`, `composeSafetyContent`, contribution registry | stable |
| `@pleach/core/safety/examples` | Reference safety contributors | stable |
### Lineage + fingerprint + observability [#lineage--fingerprint--observability]
| Import | Ships | Stability |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `@pleach/core/lineage` | `LineageTracker` + 6 lineage types (Layer-4 lineage primitives) | stable |
| `@pleach/core/fingerprint` | `computeFingerprint` — platform-uniform pure hash | stable |
| `@pleach/core/otel` | OpenTelemetry no-op + adapter seams | stable |
| `@pleach/core/inspector` | `inspectRuntime`, `InspectionReport`, `CapabilityReport`, `PluginReport`, `CapabilityDescriptor`, the 35 known-capability list (31 modern + 4 deprecated) | stable |
| `@pleach/core/harness` | Turn-report folding for the headless self-observation loop (the `harness` chatinit flag + `pleach dev` plugin-test harness) — `foldTurnReport`, `foldTurnReportFromEvents`, `createHarnessCapture`, `projectInspector`, `diffReports`, `evaluateAssertions`, `buildReportMarkdown` (`{ verbose }` for the audit-ledger/runtime-log/tool-card sections), `TurnReport`. Also the answer-quality battery `detectEdgeCases` (+ `EdgeCaseFinding`, `hasSubstantiveAnswerBody`, `PLAN_NARRATION_PATTERNS`), the default `defaultAnswerSufficiencyBackstop`, and the headless-diagnostics pub/sub (`getDiagnosticsBus`, `DiagnosticsBus`). See [Playground & DevTools](/docs/playground-and-devtools). | stable |
| `@pleach/core/instrumentation` | UX-parity probes + observer-vs-legacy divergence telemetry | stable, internal-leaning |
### Strategies + streaming [#strategies--streaming]
| Import | Ships | Stability |
| ----------------------------------------------------- | ---------------------------------------------------------------------- | --------- |
| `@pleach/core/strategies` | Strategy barrel — fabrication detector + named detectors + guard types | stable |
| `@pleach/core/strategies/fabricationDetector` | Direct fabrication detector entry | stable |
| `@pleach/core/strategies/fabricationDetectors` | Named fabrication detector cohort | stable |
| `@pleach/core/strategies/fabricationGuardTypes` | Guard type contracts | stable |
| `@pleach/core/strategies/hallucinationDetector` | Hallucinated tool-call detector | stable |
| `@pleach/core/streaming` | Producer side — `StreamManager`, `asyncEventChannel` | stable |
| `@pleach/core/streaming/dsmlSanitizer` | DSML sanitizer (chunk-time amend observer) | stable |
| `@pleach/core/streaming/bracketNarratedToolExtractor` | Bracket-narrated tool-call extractor | stable |
| `@pleach/core/streaming/hallucinatedToolDetector` | Hallucinated tool-call detector entry | stable |
| `@pleach/core/streaming/streamDegenerationGuards` | Stream degeneration guard primitives | stable |
| `@pleach/core/finalization` | Finalization barrel | stable |
| `@pleach/core/finalization/finalizeContent` | `finalizeContent` direct entry | stable |
### Providers [#providers]
| Import | Ships | Stability |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core/providers` | Provider-failure taxonomy + reasoning-only recovery precondition — `FailureCategory`, `FailureClassification`, `BillingDisposition`, `ModelUnavailableReason`, `classifyEmptyStream`. The seam recovery arm keys on these; the reasoning-model set + provider string→category matchers stay host-injected (`SessionRuntimeConfig.reasoningRecovery`). See [Providers § Reasoning-only completion recovery](/docs/providers#reasoning-only-completion-recovery). | stable |
### Graph + planning + execution [#graph--planning--execution]
| Import | Ships | Stability |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core/graph/planning` | Planning substrate — plan-channel utilities | stable |
| `@pleach/core/engine` | `RetryPolicy`, `AbortComposer`, `SuperstepRunner`, `createPromiseBarrier`, `shouldTriggerNode` | stable |
| `@pleach/core/channels` | Typed state containers — `LastValue`, `BinaryOperatorAggregate`, `Topic`, `EphemeralValue`, `NamedBarrier` | stable |
| `@pleach/core/detectors` | Detector primitives — `syntheticExpansionDetector` | stable |
### Tools + plugins + meta [#tools--plugins--meta]
| Import | Ships | Stability |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `@pleach/core/tools` | `ToolRegistryWrapper`, `ToolBatchExecutor`, catalog re-exports | stable |
| `@pleach/core/tools/execution` | Tool-execution pipeline stages + resolved-tools registry (`recordRegistryResolvedTool`, `getRegistryResolvedToolNames`, `hasRegistryResolvedTool`, `resetRegistryResolvedTools`) | stable |
| `@pleach/core/plugins` | `PluginManager` + `HarnessPlugin` interface | stable |
| `@pleach/core/async` | Long-running task orchestration — `AsyncTaskManager`, executor contract, task reducer | stable |
| `@pleach/core/plans` | Plan substrate — `PlanManager`, plan/step/revision types | stable |
| `@pleach/core/subagents` | Concurrent subagent execution — `SubagentManager`, `LightweightRuntime` | stable |
| `@pleach/core/memory` | Auto-extracted user facts + per-agent memory scoping | stable |
| `@pleach/core/query` | Read-side query helpers | stable |
### Re-exports [#re-exports]
| Import | Ships | Stability |
| ----------------------- | ------------------------------------------------------------------- | --------- |
| `@pleach/core/react` | Re-export of `@pleach/react` — hooks + `HarnessProvider` + DevTools | stable |
| `@pleach/core/adapters` | Storage + streaming adapters | stable |
### Runtime registries + auth + utils [#runtime-registries--auth--utils]
| Import | Ships | Stability |
| ------------------------------------- | ------------------------------------------------------------------------ | ------------------------ |
| `@pleach/core/runtimeRegistry` | Process-scoped runtime registry | stable |
| `@pleach/core/guestInterruptBus` | Guest interrupt bus (registry seam) | stable |
| `@pleach/core/guestInterruptCallback` | Guest interrupt callback (registry seam) | stable |
| `@pleach/core/auth` | Auth providers — `ApiKeyAuth`, `BearerTokenAuth`, `AuthProvider` | stable |
| `@pleach/core/utils` | UUIDv7, typed `EventEmitter`, SHA-256 integrity helpers | stable |
| `@pleach/core/mock` | Offline-development substitutes for external services (dev + test paths) | stable, internal-leaning |
### Wildcard [#wildcard]
| Import | Ships | Stability |
| ---------------- | ------------------------------- | ------------ |
| `@pleach/core/*` | Deep paths not yet barrel-named | **unstable** |
`stable` means: the path is named in the published `exports` map
and watched by the upstream package-export audit. Removal or rename
goes through a deprecation cycle.
## The wildcard surface [#the-wildcard-surface]
Paths matched by `@pleach/core/*` resolve today, but renames and
removals can land in a minor release. They are watched in
WARN-DRIFT mode (non-blocking) — not promoted to FAIL until a path
is named. Treat them as a temporary hatch, not a contract.
`@pleach/core/*` resolves to deep paths under the package's `dist/`
that aren't behind a named barrel yet. It exists so the published
surface doesn't lag the source tree during the named-barrel
narrowing project tracked in the upstream `pa3prep/` ledger.
The upstream `audit:package-export-validation` job watches the
wildcard's reach:
* **WARN-DRIFT (default)** — every wildcard hit not in the
published snapshot at `scripts/audit/package-export-snapshot.json`
is reported. Non-blocking per D-PA3P-3 so source-tree changes
don't break the build.
* **`:strict` (publish-day)** — promotes WARN-DRIFT to FAIL on any
unresolved import, plus walks the declared exports surface. Run
before any `@pleach/core@1.x` rehearsal cut.
* **`:update-snapshot`** — regenerates the snapshot when wildcard
reach is intentionally widened or narrowed.
Three rules of thumb when reaching into the wildcard:
1. **It works today.** Deep paths under `@pleach/core/graph/...`,
`@pleach/core/replay/types`, and similar resolve against the
published artifact.
2. **It will move.** As named barrels land, wildcard paths get
superseded. The pa3prep cluster sweeps promote groups of paths
to named entries at a time — type-only deep paths landed via
cluster 15 (`./types/*` cohort), and each future cluster
narrows the wildcard's reach further.
3. **`graph/*` is indefinite.** The internal graph topology is
deliberately not behind a stable barrel. Don't build a public
API on top of it.
If a wildcard path is load-bearing for you, open an issue against
[pleachhq/core](https://github.com/pleachhq/core/issues) asking
for it to be named. The named-barrel pipeline takes requests.
## Internal surfaces [#internal-surfaces]
Paths under `@pleach/core/internal/…` are implementation details,
not a supported public API. The `internal/` segment is the signal:
they resolve today, but they are **not `stable`** — they can move or
change shape between releases with no deprecation cycle. Don't build
against them; use the public alternatives below.
| Path | What it is | Public alternative |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@pleach/core/internal/strategies/streamSingleTurn/helpers` (+ its `safeStringifyArgs`, `parseToolArgs`, `forceSynthesisEchoDispatch`, `imperativeProviderAttemptCallback` direct entries) | The `streamSingleTurn` body's own helper barrel — typed contracts (`TurnAccumulator`, `OrchestratorMessage`, `ProviderFallbackConfig`, `ToolDefinition`) plus runtime utilities the default body uses inline. See [streamSingleTurn § The helpers barrel](/docs/stream-single-turn#the-helpers-barrel-internal). | Public types via the named type subpaths — e.g. `ToolDefinition` from `@pleach/core/types/generic`. A custom body registers through the module-loader seam, not by importing these helpers. |
| `@pleach/core/internal/tools/execution/registryResolvedTools` | Resolved-tools registry surface. | `@pleach/core/tools/execution` re-exports the supported functions (`recordRegistryResolvedTool`, `getRegistryResolvedToolNames`, `hasRegistryResolvedTool`, `resetRegistryResolvedTools`). |
## Dual-format builds [#dual-format-builds]
Each named subpath ships three artifacts:
```json
{
"import": "./dist/sessions/index.js",
"require": "./dist/sessions/index.cjs",
"types": "./dist/sessions/index.d.ts"
}
```
ESM consumers resolve `.js`; CommonJS consumers resolve `.cjs`;
TypeScript reads the `.d.ts`. Bundlers respect `sideEffects: false`
on the package — tree-shaking the runtime is supported and gives
roughly a 30% bundle reduction in apps that only import a handful
of named subpaths.
## First-publish packaging contract [#first-publish-packaging-contract]
Every `@pleach/*` package adopts the same baseline at its first 1.x
publish. Dual ESM/CJS emit, types-first `exports` ordering per the
Node resolution spec, dir-style tsup entries, and DTS produced by
`tsc --build` against the public surface.
Tarballs ship without sourcemaps. Peer-dep ranges tighten at the 1.x
cut. Each package carries a `NOTICE`, a `CHANGELOG.md`, npm
provenance attestation, and a `sideEffects` declaration that matches
what its modules actually do.
Consumers benefit from knowing the shape: install or import failures
debug faster when the resolution order is predictable. Forkers and
vendored installs need to hold the line — diverging from the contract
breaks the audit gates upstream that enforce it.
For the full write-up — field-by-field `package.json` requirements,
the audit job names, and the migration recipe for pre-1.x packages —
see [Publishing contract](/docs/publishing-contract).
## Where to go next [#where-to-go-next]