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 one remaining wildcard and what it costs you.

Snapshot is for @pleach/core@0.1.0 — 180 named entries as of 2026-09-06. The canonical list lives in the package's package.json and is watched by audit:package-export-validation upstream, and mirrored on this site by audit:docs-vs-contract's export-map check, which fails any specifier below that would throw ERR_PACKAGE_PATH_NOT_EXPORTED.

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.

Substrate runtime

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.

Persistence + state

Event log + projections

Audit, attestation, scrub

Prompts + prompt-builder

| @pleach/core/context | Context-window budget — computeContextBudget, resolveCompactionThreshold, estimateMessageTokens, and the DEFAULT_COMPACTION_TRIGGER_TOKENS / DEFAULT_COMPACTION_RATIO / DEFAULT_CONTEXT_WINDOW_TOKENS defaults. One shared token budget across prompt + history, which is what the context gauge reads. | stable |

Model pipeline

Safety

Access control + export

Lineage + fingerprint + observability

Strategies + streaming

Providers

Graph + planning + execution

Tools + plugins + meta

Re-exports

Runtime registries + auth + utils

Wildcard

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

@pleach/core shipped a bare ./* wildcard during the named-barrel narrowing project, so the published surface wouldn't lag the source tree. That hatch is closed. Every path a consumer should reach for is now a named entry in the table above, and the only wildcard left is ./internal/* — deliberately scoped, so the internal/ segment in the specifier tells you what you're doing.

If a deep import stopped resolving, one of three things is true:

1. It was promoted to a named barrel. Check the table above first — this is the common case. @pleach/core/graph/topology, @pleach/core/graph/seams, and @pleach/core/graph/planning are all named; the bare @pleach/core/graph is not.
2. It's reachable from the root barrel. StateGraph, Annotation, AnnotationRoot, CompiledGraph, Send, and isSend re-export from @pleach/core itself.
3. It has no published home yet. START, END, buildDefaultAgentGraph, and DEFAULT_TURN_FLAGS are declared in the package but reachable through no exports entry today. Compose a StateGraph directly, or open an issue against pleachhq/core asking for the barrel. The named-barrel pipeline takes requests.

graph/* stays deliberately un-barrelled beyond the four named entries. The internal graph topology is not a public API — don't build one on top of it.

Internal surfaces

Dual-format builds

Each named subpath ships three artifacts:

{
  "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

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.

Where to go next