Manifest compatibility
Normalize manifest v1 for v2 readers and classify source, runtime, wire, and generated-artifact compatibility independently.
MODULE_MANIFEST_VERSION is 2. Existing module source remains valid, but serialized consumers must
negotiate the wire version.
import {
normalizeModuleManifest,
normalizeModuleManifestBundle,
} from "@fabricorg/platform/manifest";
const current = normalizeModuleManifest(inputV1OrV2);A v2 reader accepts v1 and normalizes missing v2 fields to absence. Platform does not promise v2-to-v1 down-conversion. Additive v2.1 semantic fields remain optional and the shipped reader preserves unknown fields, but closed-schema consumers must be tested before release rather than assumed tolerant.
Four compatibility planes
| Plane | Question |
|---|---|
| Source | Does an existing FabricModule still type-check and register? |
| Runtime | Do omitted optional fields preserve the previous execution behavior? |
| Wire | Can a serialized-manifest consumer interpret this manifestVersion? |
| Generated artifact | Does the semantic change preserve a generated consumer's contract? |
Adding an optional source field can be source- and runtime-compatible while still requiring a new wire version. Adding a required entity field, narrowing a schema, changing relation cardinality, removing a state, or changing a semantic state mapping is breaking for affected generated consumers.
Event schemas are classified independently of their numeric schema version. An optional property is compatible; a required property, removal, or type change is breaking; constraint changes require review. A schema-version increase is separately potentially breaking until consumer-version coverage or an upcaster closes the gap. Action execution semantics and view usage semantics are also classified because they alter Host or generated-consumer behavior even though their authoring fields are optional.