Skip to main content

v2.16.0

Release notes for orun v2.16.0.

This release grows the component catalog into a service catalog: a typed, multi-kind entity model (orun.io/v1) with ownership provenance, a unified relation graph, first-class Compositions, and a live deployment plane — all derived from the same declarative sources orun already compiles. Everything is additive and non-destructive: existing catalogs up-convert transparently on read, and a new advisory orun catalog migrate command shows each component's path to the richer model.

Highlights​

  • A multi-kind entity model. The catalog no longer tracks only components. It resolves a graph of typed entities — Component, API, Resource, System, Domain, Group, Environment, Composition — each carried in a shared orun.io/v1 envelope (metadata, ownership, lifecycle, spec, relations, contracts, integrations, docs, links, provenance, extensions). orun catalog list --kind System (or any other kind) enumerates them.
  • Ownership with provenance. When a component authors no owner, the resolver derives one from CODEOWNERS (last matching rule wins) and records where the answer came from (ownership.source: authored | CODEOWNERS | inherited). Owners are typed refs (group:<name>, user:<name>), and catalog list grows OWNER and SYSTEM columns.
  • One typed relation graph. The resolver emits a single relations.json containing every typed edge in the catalog — dependsOn, partOf, ownedBy, providesApi, consumesApi, runsOn, deployedTo, composedBy — with inverses materialized on read. The change-detection engine consumes the same graph, so "what depends on this?" and "what should this PR run?" are answers to the same question.
  • Compositions are catalog entities. A composition now carries a semver version and a lifecycle.stage (stable | beta | deprecated), appears in the catalog with composes/usedBy relations to the components on its golden path, and can declare effects — the integrations, deployments, resources, and APIs that running it contributes to the graph.
  • A derived live plane. orun catalog describe appends live deployments and latest executions, projected on read from execution history — never persisted into catalog blobs, never stale relative to the runs that produced them.
  • A Catalog surface in the cockpit. The TUI gains a third top-level surface (key 3): a multi-kind entity explorer with kind tabs and per-kind counts, envelope-aware columns (owner, lifecycle stage, version, member counts), and a walkable typed-relation graph with breadcrumbs.
  • Adopt at your own pace. orun catalog migrate is a read-only lint that reports, per component, what keeps it from being a first-class v1 entity. Old v1alpha1 snapshots stay byte-identical on disk and up-convert on read.

The v1 entity model​

Every catalog entity — authored or derived — now resolves into the same envelope. For a component, orun catalog describe <name> renders it in full: identity and lifecycle, ownership (with its source), environments, dependencies, provided/consumed APIs, resources, integrations, vendor extensions, inferred runtime, live deployments, and resolution provenance. --json emits the machine-readable envelope.

Derived kinds are first-class reads, not separate stores:

orun catalog list                      # components (unchanged default)
orun catalog list --kind System        # systems, with member counts
orun catalog list --kind Environment   # environments as entities
orun catalog list --kind Composition   # golden paths in the catalog

Derived entities (System, Domain, Group) carry their member set (spec.members) and a MEMBERS count in list output, so "what belongs to this system?" is a single read rather than a reverse graph walk.

Entity keys are unified across kinds — <namespace>/<repo>/<name> for component-like kinds, group:<name> / user:<name> for owners. The legacy Owner kind is read as Group.

Ownership from CODEOWNERS​

Authored spec.owner always wins. When it is absent, the resolver reads the workspace CODEOWNERS file and assigns the last matching rule's owner, recorded as ownership.source: CODEOWNERS. Ownership flows through every catalog build path (refresh, plan, pre-run), so the computed catalog — and its content-addressed identity — is the same no matter which command produced it.

Composition effects: the golden path feeds the graph​

Authored compositions may declare what running them contributes:

spec:
  version: 2.3.0
  lifecycle: stable
  effects:
    integrations:
      cloudflare:
        product: workers
    provides:
      - default/orun/cloudflare-edge      # Resource entities
    exposes:
      - default/orun/edge-http-api        # API entities
    scorecards:
      satisfies:
        - has-deploy-pipeline

The resolver folds these declarations into the relation graph and the derived entities: a component on the golden path gets its platform integrations, its provided Resources, and its exposed APIs linked into the catalog without authoring them by hand. Effects are authored intent; the live plane records what actually happened.

Pinned-but-deprecated composition versions surface a deprecation warning at resolve time, so golden-path upgrades are visible where they matter — in the plan, not in a wiki.

Cockpit: the Catalog surface​

The cockpit grows a Catalog mode alongside Browse and Activity — press 3, tab-cycle, or run the goto.catalog palette command. Where Browse is the work surface (components you compose and run), Catalog is the knowledge surface:

  • Kind tabs with counts — [ / ] cycle the kinds present in the catalog; the All tab mixes kinds with a glyph per row.
  • Envelope columns per kind — Components lead with OWNER and lifecycle STAGE; Compositions show VERSION and stage; derived kinds show member counts.
  • A walkable graph — ⏎ opens an entity's envelope and its Connections: members and typed relation edges (◂ marks incoming edges), each navigable, with the breadcrumb tracking your path.
  • Same freshness model as Browse — the surface reads catalogs/current and shows the ⟳ stale (⌃r) badge when a refresh would change it.

Browse itself is enriched with envelope ownership and lifecycle on the catalog-served path. See the cockpit overview and orun tui.

Migration: transparent, advisory, never destructive​

  • Reads are version-blind. Every read command (catalog list, describe, tree, history, diff, the cockpit) operates on old v1alpha1 and new v1 catalogs alike. Immutable snapshots keep their original bytes on disk forever; up-conversion happens in memory, on read.
  • orun catalog migrate lints authored component.yaml files for v1 readiness — a legacy apiVersion, a missing owner (none authored and no CODEOWNERS match), a missing lifecycle stage, a missing system — and prints per-file findings plus a ready count. It never rewrites files. --json emits the structured result for CI.
  • Catalog ids move once. The resolver version advanced (now 14) to cover the new model; the first resolve after upgrading is a cache miss that re-stabilizes immediately, exactly as with prior resolve-shape changes.

CLI changes​

Added:

  • orun catalog migrate — read-only v1-readiness lint (--json).
  • orun catalog list --kind <API|Resource|System|Domain|Group|Environment|Composition> — enumerate derived entities; OWNER, SYSTEM, and MEMBERS columns.
  • orun catalog describe — renders the full v1 envelope including integrations, extensions, inferred runtime, live deployments, and provenance; accepts bare names or fully-qualified namespace/repo/name keys (ambiguous bare names exit 4 with candidates).

Unchanged: the default orun catalog list output shape, all source selectors (--source, --catalog-snapshot), and the affected engine's CLI surface.

Compatibility​

  • No breaking changes. Existing component.yaml files resolve as before; the richer authoring surface (system, lifecycle, integrations, links, docs, extensions) is opt-in.
  • Vendor extension blocks must be namespaced (x-<vendor>); namespaced blocks are preserved verbatim through the resolver, and registered extension schemas are validated on round-trip.
  • The examples workspace dogfoods the model end to end: a CODEOWNERS file, an enriched apps/api-edge component, and compositions carrying version, lifecycle, and effects.

Also in this release​

  • The orun-work design epic (specs/orun-work/) — a work plane whose task states derive from delivery truth (PR → in review, merge + gates → done, production deployment → released) — is published as a design document. It builds on the typed relation graph introduced here and is gated to a future release.

References​

  • Service catalog — the entity model, the relation graph, and the live plane.
  • orun catalog — the catalog command group, including migrate and --kind.
  • Compositions — golden paths, versioning, and effects.
  • State model — where entities live in the content-addressed object model.