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

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

Safety

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/* 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 asking for it to be named. The named-barrel pipeline takes requests.

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