Skip to content

feat: independently versioned components in a single manifest #176

@joshua-temple

Description

@joshua-temple

cascade assumes one versioned unit per repository: a single set of builds and deploys, a
single environment-level version, and a single latest-release record. Repositories that
ship several independently versioned components in one tree cannot model that today, and
retrofitting it after the schema freeze would require a breaking change to the manifest
top level and to the recorded state.

Scope for the v1.0.0 milestone is narrow: reserve only the top-level component schema
shape before the freeze. The generator, state, and runtime behavior are explicitly out of
scope here and land in a later (post-1.0) change. The goal is that a future release can add
per-component versioning without removing or retyping any field that shipped at v1.0.0.

Proposed approach:

  • Define and document a reserved top-level shape for addressable components (for example a
    components map) and a reserved per-component slot in recorded state and in the latest
    release record. This shape reservation is the only part that must land before the v1.0.0
    freeze.
  • Apply parse-and-structural validation for the reserved shape only; no emit behavior yet.
  • Keep the single-component manifest the canonical default; the reserved shape must be
    absent-by-default and non-breaking for every existing manifest.

Acceptance criteria:

  • The reserved component shape parses and validates structurally, with no generator output
    attached to it.
  • Every existing single-component manifest continues to parse, validate, and generate
    identical output.
  • docs/versioning records the reservation so the later implementation is additive.
  • A unit test asserts the reserved shape round-trips and that omitting it changes nothing.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions