test(extension-contract): publish derived-module compatibility manifest, test kit, and semantic-version gates #741

Parent epic: #738
Depends on: #739, #740
Related completed foundations: #685, #692, #695, #700

Context

Build-time assembly solves how a derived repository contributes reviewed modules, but it does not by itself prove that the derived application remains compatible with a newer AWCMS-Mini release. Without an explicit contract, repositories can drift on module contract versions, capability versions, migrations, OpenAPI/AsyncAPI schemas, permission keys, and generated inventory.

Objective

Publish a machine-readable compatibility manifest and reusable external test kit so a derived repository can fail early when its declared AWCMS-Mini range, module contract, capability bindings, migrations, or API/event assumptions are incompatible.

Scope

• Define and version a JSON or YAML schema for a derived-application compatibility manifest.
• Minimum manifest fields:
  • compatible AWCMS-Mini semantic-version range;
  • module-contract version;
  • application key/version;
  • contributed modules and migration namespaces/ranges;
  • required/provided capability keys with contract versions;
  • required deployment profiles/features;
  • consumed API/event contract versions where relevant.
• Add a reusable command such as bun run extension:check that can run in the base fixture and in an external derived repository.
• Validate:
  • base version range;
  • module contract compatibility;
  • capability version/provider resolution;
  • duplicate module/migration identifiers;
  • migration ordering and immutable historical checksums;
  • stale OpenAPI/AsyncAPI/generated reference assumptions;
  • prohibited Core override or direct base-registry edit;
  • declared offline/LAN versus full-online requirements.
• Produce a deterministic machine-readable compatibility report suitable for CI artifacts and release evidence.
• Add a sample external derived-app fixture with both compatible and intentionally incompatible test cases.
• Document compatibility, deprecation, and support-window policy, including how breaking capability changes are versioned.

Security and architecture requirements

• No package download, remote code execution, runtime discovery, or tenant-controlled manifest execution.
• Manifest parsing is schema-bounded and treats all strings as data.
• Compatibility output contains no secrets, local credentials, or production hostnames.
• A green compatibility check does not bypass RLS/ABAC/security review; it validates contracts, not business correctness.

Acceptance criteria

• Manifest schema and versioning policy are documented and validated.
• Incompatible AWCMS-Mini range fails before build.
• Unsupported module-contract or capability version fails with an actionable path.
• Duplicate migration identifier/range and changed historical migration checksum fail.
• Stale API/event/generated-reference assumptions are detected.
• A compatible external fixture passes without editing base registry files.
• At least five incompatible fixtures prove the gates fail for distinct reasons.
• Report output is deterministic, machine-readable, and safe for CI artifacts.
• The command runs locally/offline with no SaaS dependency.
• Derived-app guide, release process, module contract, contributor workflow, and relevant skills are updated.
• CI runs the compatibility fixture and bun run check passes.