Enforce deprecated host-module policy for official plugin releases #227

New issue

Closed

opened 2026-06-02 13:35:06 +00:00 by steve · 0 comments

steve commented

2026-06-02 13:35:06 +00:00

Owner

Problem

The original dual ESM/CJS loader plan said official release validation should
fail when a plugin declares deprecated or private host modules unless an
explicit compatibility override is present. The current runtime validation
already treats private host modules as errors for official plugins, but
deprecated host modules are always warnings. The current spec also describes the
private-module official-release rule without clearly covering deprecated modules
or override policy.

Goal

Bring official plugin release validation, compatibility overrides, and
documentation into alignment for deprecated host-module usage.

Scope

Define the explicit compatibility override mechanism for official plugins that
must temporarily depend on deprecated host modules.
Make deprecated host-module diagnostics fail official release validation when
no override is present.
Preserve warning-only behavior for manual/community plugin installation where
release validation is not enforcing official registry policy.
Update tests and specs to distinguish private, deprecated, supported, and
overridden host-module cases.

Non-goals

Removing deprecated host modules from the compatibility catalogue in this
task.
Reclassifying existing host modules unless required to test the policy.
Changing community/manual plugin install behavior beyond documenting the
release-validation distinction.

Acceptance Criteria

Official registry/runtime validation errors on deprecated host-module
dependencies unless an explicit compatibility override applies.
Official validation continues to error on private host modules.
Manual/community validation continues to surface deprecated/private host
modules as diagnostics suitable for compatibility decisions rather than
unexpectedly blocking local installs.
Tests cover official deprecated-without-override, official
deprecated-with-override, official private, and manual/community deprecated
cases.
spec/src/30-cross-package-contracts/plugin-registry.md documents the
deprecated-host-module policy and override shape.

Implementation Notes

The current deprecated-host-module diagnostic path uses a non-official
severity flag; inspect runtime-validation.ts before adding override
semantics.
Reuse the existing compatibility metadata model if it can express the override
cleanly; avoid introducing a second policy source unless necessary.
If overrides affect generated diagnostics UI, create a separate follow-up
rather than expanding this task.

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-registry.md
packages/api/src/lib/plugin-distribution/runtime-validation.ts
packages/api/src/lib/__tests__/plugin-release-runtime-validation.test.ts
Host-module compatibility catalogue used by runtime validation

Validation Commands

pnpm --filter @lapis-notes/api exec vitest run src/lib/__tests__/plugin-release-runtime-validation.test.ts
pnpm --filter @lapis-notes/api check:all
make spec-lint
mdbook build spec

Follow-up to #221 — [registry] Validate module formats and shared dependencies

Follow-up Tasks

Implementation Summary

Added manifest and release metadata compatibility overrides for deprecated host modules, made official-release deprecated usage an error unless explicitly overridden, preserved private-module errors, and covered validation in API/script tests and specs.

## Problem The original dual ESM/CJS loader plan said official release validation should fail when a plugin declares deprecated or private host modules unless an explicit compatibility override is present. The current runtime validation already treats private host modules as errors for official plugins, but deprecated host modules are always warnings. The current spec also describes the private-module official-release rule without clearly covering deprecated modules or override policy. ## Goal Bring official plugin release validation, compatibility overrides, and documentation into alignment for deprecated host-module usage. ## Scope - Define the explicit compatibility override mechanism for official plugins that must temporarily depend on deprecated host modules. - Make deprecated host-module diagnostics fail official release validation when no override is present. - Preserve warning-only behavior for manual/community plugin installation where release validation is not enforcing official registry policy. - Update tests and specs to distinguish private, deprecated, supported, and overridden host-module cases. ## Non-goals - Removing deprecated host modules from the compatibility catalogue in this task. - Reclassifying existing host modules unless required to test the policy. - Changing community/manual plugin install behavior beyond documenting the release-validation distinction. ## Acceptance Criteria - Official registry/runtime validation errors on deprecated host-module dependencies unless an explicit compatibility override applies. - Official validation continues to error on private host modules. - Manual/community validation continues to surface deprecated/private host modules as diagnostics suitable for compatibility decisions rather than unexpectedly blocking local installs. - Tests cover official deprecated-without-override, official deprecated-with-override, official private, and manual/community deprecated cases. - `spec/src/30-cross-package-contracts/plugin-registry.md` documents the deprecated-host-module policy and override shape. ## Implementation Notes - The current deprecated-host-module diagnostic path uses a non-official severity flag; inspect `runtime-validation.ts` before adding override semantics. - Reuse the existing compatibility metadata model if it can express the override cleanly; avoid introducing a second policy source unless necessary. - If overrides affect generated diagnostics UI, create a separate follow-up rather than expanding this task. ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-registry.md` - `packages/api/src/lib/plugin-distribution/runtime-validation.ts` - `packages/api/src/lib/__tests__/plugin-release-runtime-validation.test.ts` - Host-module compatibility catalogue used by runtime validation ## Validation Commands - `pnpm --filter @lapis-notes/api exec vitest run src/lib/__tests__/plugin-release-runtime-validation.test.ts` - `pnpm --filter @lapis-notes/api check:all` - `make spec-lint` - `mdbook build spec` ## Related Issues - Follow-up to #221 — [[registry] Validate module formats and shared dependencies](../closed/221-registry-validate-module-formats-and-shared-dependencies.md) ## Follow-up Tasks ## Implementation Summary Added manifest and release metadata compatibility overrides for deprecated host modules, made official-release deprecated usage an error unless explicitly overridden, preserved private-module errors, and covered validation in API/script tests and specs.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 13:35:06 +00:00

steve

2026-06-02 13:35:06 +00:00