Skip to content

feat(lifecycle): lifecycle: block — maturity, deprecation, compatibility, and komposer acceptance - #263

Merged
iAlexeze merged 1 commit into
mainfrom
feat/katalog-lifecycle
Aug 18, 2026
Merged

feat(lifecycle): lifecycle: block — maturity, deprecation, compatibility, and komposer acceptance#263
iAlexeze merged 1 commit into
mainfrom
feat/katalog-lifecycle

Conversation

@iAlexeze

@iAlexeze iAlexeze commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator

Lifecycle in Orkestra has always existed as a convention — deprecation lived in metadata, maturity was implied by version numbers, compatibility was communicated in READMEs. This PR makes it a first-class citizen.

A new top-level lifecycle: block now sits alongside metadata, spec, and gateway on every Katalog. It is the contract the pattern author makes with the platform and with consumers:

lifecycle:
  maturity: beta
  deprecation:
    message: "Replaced by task-runner"
    migratedTo: task-runner:v1.0.0
    timeline:
      from: "2026-09-01"
      to:   "2027-03-01"
  compatibility:
    kubernetes: ">=1.28"
    orkestra: ">=0.7.0"

Maturity is a signal — alpha, beta, stable, deprecated. It appears in ork inspect, warns at ork validate, and can be enforced by a platform floor (policy.lifecycle.minMaturity). A pattern that skips it is treated as stable. A pattern that declares deprecated without a deprecation block gets a warning, not a pass.

Deprecation is enforced. The block travels with the artifact into OCI annotations, surfaces at every touchpoint (ork push, ork validate, ork inspect, ork pull), and blocks ork run when the state is active. The author sees exactly what their consumers will see — before the artifact is uploaded.

The acceptance model is deliberate: a deprecated Katalog cannot self-accept. The field doesn't exist on the Katalog type. Acceptance belongs on the Komposer — the consumer making a traceable, reviewable decision about what they are knowingly importing:

# in your komposer.yaml
lifecycle:
  accept:
    patterns:
      - name: legacy-worker
        author: myorg
        version: "=1.0.0"   # optional — scope to a specific version

Compatibility gives pattern authors a way to declare verified version ranges and gives the platform a way to reject patterns that claim to work on Kubernetes 1.24 when the cluster is already on 1.31.

Policy keeps it extensible. Rather than flattening a maturity floor directly under policy:, it lives at policy.lifecycle.minMaturity — making room for future security policy, registry policy, and user-defined policy can grow alongside it without forcing a schema break.

metadata.deprecation is removed. The old accept: { beforeEol, eol } struct is gone. Registry guide get additional lifecycle story as runnable examples.

…ity, and komposer acceptance

Adds a top-level lifecycle: block to every Katalog and Komposer file:

- lifecycle.maturity: alpha | beta | stable | deprecated — advisory signal;
  ork validate warns for pre-stable imports
- lifecycle.deprecation: message, migratedTo, timeline — surfaced at push,
  validate, inspect, pull, and runtime startup; deprecated Katalogs always
  block ork run unless imported via a Komposer with lifecycle.accept.patterns
- lifecycle.compatibility: kubernetes/orkestra semver ranges; ork validate
  rejects patterns outside the declared range
- lifecycle.accept.patterns (Komposer-only): acknowledges deprecated or
  pre-stable imports by name; optional version scoping
- policy.lifecycle.minMaturity: platform floor; imports below the declared
  maturity level are errors at validate time

metadata.deprecation removed; lifecycle.deprecation is the canonical location.
Katalog-level accept removed entirely — acceptance belongs on the Komposer.

Registry guide steps renumbered: hooks→09, typed-komposer→10, ork-action→11,
deprecation→12; new steps 13–16 cover deprecation-accept, lifecycle-maturity,
lifecycle-compatibility, and komposer-accept.

Schema evolution docs updated with a third layer (Gateway API / serve.fields.values).
lifecycle: concepts page and registry guide corrected and expanded.
@iAlexeze
iAlexeze merged commit 55d6364 into main Aug 18, 2026
8 checks passed
@iAlexeze
iAlexeze deleted the feat/katalog-lifecycle branch August 19, 2026 22:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant