API stability and entry points

@velella/ebb exposes a single locked TypeScript entry point at the package root (@velella/ebb), alongside temporary "./*" subpath exports kept for 0.x compatibility and experimental helpers.

What the API report enforces

CI locks the root entry point ("." → src/index.ts) by running npm run api:check (api-extractor run --print-api-report-diff) against api/ebb.api.md.

What that check does enforce:

• Every public runtime export (check, checkAll, rulesFor, replacementFor) and public type exported from @velella/ebb, plus their TypeScript signatures. Any unreviewed signature or export diff fails CI until api/ebb.api.md is updated in the same PR.

What that check does not promise:

• No subpaths are locked. Nothing under @velella/ebb/* is checked by api/ebb.api.md. Tests verify that legacy 0.1.0 subpaths resolve and load, not that internal types or non-root exports stay unchanged.
• No CommonJS support. require("@velella/ebb") maps to src/cjs-error.cts and throws an explicit ESM-only error directing callers to dynamic import("@velella/ebb").
• Pre-1.0 status. While the package version is 0.x, reviewed PRs can still update api/ebb.api.md when needed.
• Field-level @experimental tags. Inside Result / CheckResult and ResultMatch / CheckMatch, asOf and daysLeft carry @experimental JSDoc tags (see Result model) and may still evolve before 1.0; API Extractor records their TypeScript types, not their runtime invariants.

Root and manifest entry points

Entry point	Classification	Locked by api/ebb.api.md	Exports & notes
@velella/ebb	Root public API (ESM only; require throws ESM-only error)	Yes	Runtime: check, checkAll, createEbb, preload, rulesFor, replacementFor. Types: CheckAllEntry, CheckAllError, CheckAllErrorCode, CheckAllItem, CheckAllResult, CheckAllSummary, CheckEvent, CheckMatch, CheckResult, CheckStatus, CreateEbbOptions, EbbErrorCode, EbbInstance, EcosystemDataInput, EcosystemInput, EvidenceSource, Result, ResultEvent, ResultMatch, ResultStatus, Rule, RuleEvent, RulesForOptions.
@velella/ebb/package.json	Package metadata	No	Static JSON package.json via "./package.json".
@velella/ebb/create	Factory entry point	No	Runtime: createEbb. Scoped instance factory.
@velella/ebb/data/load	Data loading & preload	No	Runtime: loadEcosystem, loadEcosystemSync, preload, purlToEcosystems.
@velella/ebb/data/<ecosystem>	Ecosystem data subpaths	No	25 modules (npm, python, etc.) exporting rules (default and named), data, and ecosystem.

Experimental and 0.2.0 subpaths

Resolved through the temporary "./*" export in package.json. These subpaths are experimental until 1.0 and are not tracked by api/ebb.api.md. Prefer importing check, checkAll, rulesFor, and replacementFor from @velella/ebb instead.

Entry point	Main exports / role	Notes
@velella/ebb/check-all	checkAll, isCheckAllError	Use checkAll from @velella/ebb; isCheckAllError and the subpath itself are experimental.
@velella/ebb/replacement	replacementFor	Use replacementFor from @velella/ebb.
@velella/ebb/result-compat	fromLookupProduct	Experimental adapter from legacy LookupResult to Result (see Result model).
@velella/ebb/rules-for	rulesFor	Use rulesFor from @velella/ebb.
@velella/ebb/vers/errors	VersError	Internal VERS error module extracted from vers.
@velella/ebb/vers/schemes	SUPPORTED_SCHEMES, intdotScheme	Internal VERS scheme registry module.
@velella/ebb/index	Same as @velella/ebb via "./*"	Resolves accidentally through the wildcard; import @velella/ebb instead.

Deprecated 0.1.0 subpaths

Every source module shipped in 0.1.0 resolves in 0.x via "./*" so existing consumers keep working without breakage, verified in CI by tests/exports/legacy.test.ts and tests/exports/pack.test.ts. Each subpath's main export carries a @deprecated JSDoc tag pointing editors to @velella/ebb (verified by tests/exports/deprecations.test.ts). None of these subpaths are locked by api/ebb.api.md.

Subpath	Main deprecated export	Replacement / status before 1.0
@velella/ebb/as-of	applyAsOf	check(purl, version, asOf) on @velella/ebb; scan helper stays deprecated for removal in 1.0.
@velella/ebb/bundled-rules	bundledRules	Internal rule loader; subpath deprecated for removal in 1.0.
@velella/ebb/cache-paths	defaultCacheDirectory	Internal cache path helper; deprecated for removal in 1.0.
@velella/ebb/check	check	Import check from @velella/ebb.
@velella/ebb/countdown	runCountdown	Internal CLI/UI helper; deprecated for removal in 1.0.
@velella/ebb/data-bundle	buildDataBundle	Internal data bundle helper; deprecated for removal in 1.0.
@velella/ebb/data-release-log	verifyReleaseLog	Internal release log helper; deprecated for removal in 1.0.
@velella/ebb/data-signature	verifyArtifactSignature	Internal Sigstore helper; deprecated for removal in 1.0.
@velella/ebb/data-source	getActiveData	Data source loader; subpath deprecated for removal in 1.0.
@velella/ebb/data-status	getDataStatus	Data freshness helper; subpath deprecated for removal in 1.0.
@velella/ebb/data-update	updateData	Network cache updater; subpath deprecated for removal in 1.0.
@velella/ebb/domain	LifecycleScan	EvidenceSource is exported from @velella/ebb; subpath deprecated for removal in 1.0.
@velella/ebb/errors	EbbError	EbbErrorCode is exported from @velella/ebb; subpath deprecated for removal in 1.0.
@velella/ebb/export/cle	exportCle	Internal CLE exporter; deprecated for removal in 1.0.
@velella/ebb/forecast	buildForecast	Internal forecast helper; deprecated for removal in 1.0.
@velella/ebb/lookup	lookupProduct	Import check from @velella/ebb.
@velella/ebb/min-support	applyMinSupport	Internal scan helper; deprecated for removal in 1.0.
@velella/ebb/package-files	findPackageFile	Internal package file resolver; deprecated for removal in 1.0.
@velella/ebb/product-name	rankProductsForName	Internal alias/ranking helper; deprecated for removal in 1.0.
@velella/ebb/purl	parsePurl	Internal PURL parser; deprecated for removal in 1.0.
@velella/ebb/registry	validateRegistryV2	Internal registry validator; Rule type is exported from @velella/ebb.
@velella/ebb/required	required	Internal assertion helper; deprecated for removal in 1.0.
@velella/ebb/result	daysLeft	Result, ResultEvent, ResultMatch, and ResultStatus are exported from @velella/ebb; subpath deprecated for removal in 1.0.
@velella/ebb/rule-guards	validateRegistry	Internal registry guard; deprecated for removal in 1.0.
@velella/ebb/rule-lint	lintRuleFiles	Maintainer lint helper; deprecated for removal in 1.0.
@velella/ebb/rule-versions	kubernetesRuleVersion	Internal rule version translator; deprecated for removal in 1.0.
@velella/ebb/vers	versContains	Internal VERS range engine; deprecated for removal in 1.0.
@velella/ebb/vers/gem	gemScheme	Internal RubyGems scheme; deprecated for removal in 1.0.
@velella/ebb/vers/index	versContains	Re-export of @velella/ebb/vers; deprecated for removal in 1.0.
@velella/ebb/vers/maven	mavenScheme	Internal Maven scheme; deprecated for removal in 1.0.
@velella/ebb/vers/nuget	nugetScheme	Internal NuGet scheme; deprecated for removal in 1.0.
@velella/ebb/vers/pep440	pep440Scheme	Internal PEP 440 scheme; deprecated for removal in 1.0.
@velella/ebb/vers/semver	semverScheme	Internal SemVer scheme; deprecated for removal in 1.0.
@velella/ebb/version	VERSION	Package version constant; read @velella/ebb/package.json instead.

Deprecation rule before 1.0

1. Keep 0.1.x subpaths working during 0.x. Every 0.1.0 subpath above continues to resolve via "./*" and load from the packed npm tarball across 0.x releases.
2. Surface @deprecated in editors. TypeScript consumers importing legacy subpaths see @deprecated diagnostics pointing to @velella/ebb; imports from @velella/ebb itself produce none.
3. Remove "./*" in 1.0.0. Only intentionally exposed entry points ("." and "./package.json", plus any explicitly promoted subpaths added with API coverage before release) remain in 1.0.0. Internal modules and deprecated 0.1.x subpaths will stop resolving directly at that major boundary.