Skip to content
Back to skills

Shape

ASecurity

What an environment DECLARES, as a value — `forge env shape`, the projection it prints, why it never carries a secret value, and the declaration `forge env build` / `forge env deploy` record on the control plane so the console works with no daemon online.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentrustgoapidatabasefrontend

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill shape --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Shape?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Shape
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-shape/badge)](https://www.skillsdirectory.com/skills/reliant-labs-shape)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: deploy/shape
description: What an environment DECLARES, as a value — `forge env shape`, the projection it prints, why it never carries a secret value, and the declaration `forge env build` / `forge env deploy` record on the control plane so the console works with no daemon online.
---

# The declared shape

`forge env render <env>` prints the objects an environment renders — megabytes
of YAML on a real environment. `forge env shape <env>` prints what they ARE.

```
forge env shape prod            # the human summary
forge env shape prod --json     # {project, env, kind, shape, provenance}
```

The projection is small on purpose: it is meant to be stored per environment,
read per view, and compared as a set, so "what changed" is answerable without
re-rendering anything.

| Field | What it holds |
|---|---|
| `kind` | `persistent` \| `self_managed` \| `local` — a legacy summary DERIVED from what the env binds; being retired (see below) |
| `workloads` | every workload of every runtime, with its cluster and the release artifact its image comes from |
| `secrets` | each declared secret by NAME, its provider, and the workloads that read it |
| `domains` | every hostname the env binds — a Gateway's host, its listeners' overrides, each route's override |
| `clusters` | every kubectl context the env deploys to |
| `objects` | one entry per rendered object per cluster it lands on: identity, `hash`, `config_hash`, images, and whether it holds data or an external address |
| `delivery_policy` | what the env's releases must prove before they ship (signing, trusted builder, vulnerability gate, approvals, ...), every control with its mode. Absent means every control at its control-plane default (`signing` and `flux_verify` audit), so an env that declares nothing records nothing; a self-hosted env that declares one records `signing`/`flux_verify` off: `deploy/delivery-policy` |

## The two hashes answer different questions

`hash` is the object after secret redaction: what a drift check compares the
live object against. `config_hash` is the same object with every release-bound
image digest normalized to its artifact key — so two shapes with equal
`config_hash`es differ, at most, in which release they pin. That makes
"promote a new release" and "the KCL moved" one comparison instead of a
re-render and a YAML diff.

## It never carries a secret value

Declared secrets appear as names and providers. A rendered `kind: Secret` has
every `data` / `stringData` value replaced by the hash of that value BEFORE
the object is hashed, so no part of the shape — and no hash input — is ever a
copy of the secret. The hash still moves when a value moves, which keeps "a
secret changed" visible without recording what it changed to.

This matters because a shape is stored indefinitely and readable by everyone
in the org: a value in one is a permanent leak, not something a redeploy
fixes.

## Read-only, and checked rather than promised

No cluster is contacted, no image is built, nothing is pushed. forge cannot
promise the render is side-effect-free — KCL evaluates `file.write` during
evaluation, and forge has no hook to suppress a project's own writes — so it
scans the project before and after, and a render that wrote anything FAILS,
naming the paths. A declaration derived from an impure render is one nobody
can reproduce, which is the whole value of recording it.

Helm charts are deliberately not templated: a declaration must be derivable
with no network and no `helm` on PATH, and a chart's objects belong to the
platform dependency rather than to this project's declaration. Use
`forge env render` for those.

## Placement is per workload; the kind is a legacy summary

Every workload, frontend and database declares where it runs by its runtime
binding, and that binding is the only placement fact. One env holds any mix —
an `OnCluster` API beside an `OnHosted` static site is one env, one release and
one deploy. `forge env status --json` lists every part under `placements[]`
with its placement (`hosted`, `cluster`, `bucket`, `firebase`, `compose`,
`host`, `build-only`) and who applies it (`platform`, `hub`, `forge`,
`machine`, `none`). The all-envs document's schema and assembly are
`forge/pkg/topology`: a control plane serving the same picture from its own
records runs that code, so its report and the CLI's never disagree.

One `forge env deploy` runs the parts forge applies, the hosted parts and the
frontends forge ships in the order their declared `release_dependencies`
give. `{peer: contract}` on a part says "I consume `peer`'s `contract`". That
claim decides which parts must ship in one release, and it orders the deploy
only when the two parts run in different placements, where `peer`'s placement
goes first:

| `peer` is… | Ordering effect |
|---|---|
| in another placement (a cluster API, a hosted SPA) | `peer`'s placement deploys first |
| in the same placement | none: a compatibility claim, so two parts may name each other (an API and a gateway sharing a NATS contract) |
| a `build-only` artifact (an image the release carries, such as a daemon base image) | none: it is never deployed, and the cut already carries it |
| no component at all | refused before anything ships |

A frontend that declares no `release_dependencies` waits for every server
workload in another placement; `{}` means independent. A cycle through
different placements (a hosted part and a cluster part each waiting for the
other) is refused before anything ships.

`kind` is still recorded, as a summary the control plane is retiring:

| What the env binds | Kind | Its secrets |
|---|---|---|
| no `control_plane` | `local` | provider-defined |
| something `OnHosted` | `persistent` | write-only |
| nothing hosted, something `OnCluster` | `self_managed` | write-only |
| every workload `OnHost` / `OnCompose` | `local` | readable |

The `self_managed` / `local` split is what keeps "runs on my laptop" and
"runs on my own cluster" apart: a cluster env's secrets are never readable
back. An env that gains a hosted part beside its cluster parts is the SAME
env — the diff lists the new part, never a kind error. The design is
`docs/design/per-workload-placement.md` in the forge repository.

## `lifecycle` is DECLARED, and it is a different question

`kind` above is derived from what the env binds. `lifecycle` is declared by
the env itself, and it says WHO APPLIES it:

| `Bundle.lifecycle` | Means |
|---|---|
| unset | **A REAL ENVIRONMENT that declared nothing.** Direct apply works today and prints one notice; it will be refused (F-REFUSE-DIRECT) for an env that declares none of this, `applier` or `hub_converges`. |
| `"local"` | A developer's OWN cluster — the `forge env up` inner loop. |
| `"ephemeral"` | A THROWAWAY per-run cluster (CI / e2e), deleted inside the run, so nothing could converge it. |

`lifecycle` has siblings for the opposite case, a real env that **forge** applies while it moves onto the hub:

```kcl
_bundle = forge.Bundle {
    project = "acme"
    lifecycle = "local"      # dev: your own k3d cluster, applied to directly
    cluster_target = _k3d
}
```

Unset is the safe default deliberately: an env whose author declared nothing
is treated as production, not as scratch. The scaffolded `dev` env declares
`local`; `staging` and `prod` declare nothing, which is correct for them.

The two fields are easy to conflate because both use the word "local", and
they are not the same claim. `kind` local means nothing is hosted;
`lifecycle` local means forge may apply directly. A hosted env can still be
a throwaway cluster, and an env with no control plane at all can still be a
real environment nobody should apply to by hand — which is exactly why the
derived field could not be reused here.

**It is checked, not trusted.** A declared lifecycle may only target a k3d
cluster forge itself stands up — declared in `Bundle.clusters`, or named by
k3d's `k3d-<name>` context convention (the `deploy/k3d.yaml` cluster). EVERY
placement counts, not just the workloads': `cluster_target`, a pinned
Gateway's or route's cluster, a `forge.HelmChart`'s, a raw `forge.Manifests`
group's, a placed `forge.RenderedSecret`'s. An env is only as local as its
least local target, so a cloud env cannot declare itself local to keep direct
apply: the render fails, naming the offending context.

`forge env shape --json` and `forge env status --json` both report
`lifecycle` (on `env status`: top-level `lifecycle` for one env, `environments[].lifecycle` for the all-envs view; empty string when unset), and a direct cluster apply to an env that declares none of `lifecycle`, `applier` or `hub_converges` prints
one notice saying direct apply will be refused once F-REFUSE-DIRECT lands. That
is the fields' whole effect today — they refuse nothing — and declaring one now
is what makes retiring direct apply a flag flip rather than a migration.

## `applier = "forge"`: forge applies a real env, until its units move

`lifecycle` says the clusters are scratch. The opposite case is a **real** env
that forge applies (an operator or CI running `forge env deploy`) because it has
not moved onto the Flux path yet. That is a **transitional state, not a
destination**: every real env, the platform's own included, ends up converged by
the control plane's hub from the recorded bundle, and forge's direct apply
narrows to dev and ephemeral envs. `applier = "forge"` is where that move
starts, and `hub_converges` is how it is made.

```kcl
control_plane = forge.ControlPlane {}
applier = "forge"          # nothing has moved yet
```

| effect | how |
|---|---|
| exempt from F-REFUSE-DIRECT | `DirectApplyAllowed` is true; no notice is printed |
| no unit hub-converged | `hubConverged = false` is recorded however fully the clusters are bound to connected clusters; binding says WHERE an env lands, not who puts it there |
| recorded in the shape | `shape.applier = "forge"` in `forge env shape --json`; an env that declares nothing records nothing, so "undeclared" and "forge applies it for now" stay distinguishable |

`applier = "flux"` is the other declared value: an env with **no** control plane
that a Flux forge installs in its own cluster reconciles (`shape.applier =
"flux"`; direct apply is refused). It is opt-in and has its own page:
deploy/flux.

Declaring both `applier` and `lifecycle` is refused at render: they answer one
question opposite ways. Unlike `lifecycle` it is **not** checked against the
clusters, because a real cluster is exactly what it is for.

## `hub_converges`: moving an env onto the hub one delivery unit at a time

An env is made of delivery units (`Bundle.delivery_units`, plus `base` for
everything that names none). `hub_converges` lists the ones the hub converges;
`forge env deploy` applies every other unit directly.

```kcl
delivery_units = [
    forge.DeliveryUnit {name = "reliant", after = []}
    forge.DeliveryUnit {name = "daemon-substrate", after = ["reliant"]}
    forge.DeliveryUnit {name = "infra", after = ["daemon-substrate"]}
    forge.DeliveryUnit {name = "control-plane", after = ["infra"]}
    forge.DeliveryUnit {name = "hub-base", after = ["control-plane"]}
]
hub_converges = ["reliant"]                      # stage 1
# hub_converges = ["reliant", "daemon-substrate"]  # stage 2 ... every unit last
```

| the env declares | split |
|---|---|
| `hub_converges = [u, …]` | exactly those units are the hub's, the rest are forge's. Never augmented |
| `hub_converges = []` or `applier = "forge"` | no unit is the hub's |
| neither | forge's old inference: a plain env with every cluster bound to a connected cluster, nothing hosted, and no frontend forge ships, is the hub's as a whole |
| both `applier` and a non-empty `hub_converges` | refused at render: drop `applier` once the first unit moves |

What changes when a unit is listed:

- `forge env deploy` stops applying that unit's objects. Pruning, PDB cleanup and
  CRD pruning still read the **full** render, so a skipped Deployment is never
  mistaken for an orphan and deleted; the rollout wait skips it too (it is the
  hub's to roll).
- The bundle build refuses unsafe objects (`flux-safe`) **in that unit** and warns
  about the rest.
- The shape records `units: [{name, applier}]`, and the env's declaration tells the
  control plane `hubConvergedUnits`. `hubConverged` (the old env-level flag, still
  read by control planes that predate units) is `true` only once **every** unit
  has moved, so an older control plane can never converge a unit forge still
  applies.
- Each apply records which units forge applied and which it left to the hub on
  its `apply` gate (`units_forge`, `units_hub`).
- A frontend (`OnFirebase`, `OnBucket`) belongs to no unit: forge ships it from
  this machine, **after** the promotion is recorded, whatever the list says.

Adopting a unit of a live env also needs its trees created suspended and their
managed fields handed to Flux; that is the adoption runbook's job, and
`hub_converges` is the switch it ends on. To move a unit back, remove it from the
list: the hub orphans its trees and forge applies it again.

### Bound vs live, per tree

`forge env status <env>` (and the deploy plan) shows each **tree** of the bound
bundle (one per cluster × unit × phase): who applies it, the revision the
promotion **binds** it to, the revision the hub's reconciler reports it
**applied**, and what the two add up to (`converged`, `behind`, `failed`,
`unobserved`, `forge-applied`).

Promotion is **intent** and convergence is **observed**. The binding is never
moved late to make the two agree, so a tree that is bound to the new release and
live at the old one reads `behind`; that is the information. A control plane that
reports convergence per cluster rather than per tree is shown as such: each tree
carries its cluster's reading and says so. Nothing is invented where the control
plane reports nothing: the tree reads `unobserved`.

## Recording it is what makes the console work offline

`forge env build <env>` and `forge env deploy <env>` record this same
projection on the control plane for any env that declares one — the build
does it BEFORE building or cutting anything, so a build that fails half-way
has still said what the env is. `--plan` and `--dry-run` record nothing.

That one idempotent write is what lets a console answer "what kind, which
secrets, which provider" for an environment with no daemon online and no
checkout anywhere, and what makes a never-deployed env read as "declared, not
built yet" instead of as absent.

Two things ride with it. The shape itself, and `declared_by`: the provenance
of the render — commit, branch, dirty flag, tree hash, and the forge version,
because a render is a function of (forge, KCL, config) and the same commit
rendered by two forge versions is two different artifacts. The worktree PATH
is stripped before anything leaves the machine; it names a person's home
directory.

An ensure that has NOT rendered the env — `forge secret set`, a promote —
sends no shape at all, and an absent shape leaves the stored one untouched.
That is load-bearing rather than tidy: an inferred shape from a command that
could not render would erase the declaration a build recorded.

## The released bundle names every env the source declares

A control plane can derive the release/environment topology (the console's
roster, the all-envs `forge env status --json` document) from what it
records. What it cannot see is an env that never recorded anything on it: one
added under `deploy/kcl/` and never built, and every env with no
`control_plane` (a file ledger). So a **released** bundle recorded on a control plane carries the
project's declared-environment catalog (`declared_envs`): one entry per
`deploy/kcl/<env>/main.k` at the release's commit, with its `lifecycle`,
`destination` and `control_plane_kind`. The console reads it from the newest
released bundle and lists those envs as "declared, outside the control plane".

- **Names and closed vocabularies only.** No values, no paths, no free text. An
  env whose KCL does not render is listed by name with `render_error:
  render_failed | render_timeout`, never the error message.
- **It never fails a build.** Every env renders once per build invocation, in
  parallel, under a two-minute budget. A directory whose name is not an env
  name is left out with a note.
- **Feature-negotiated.** It is written only to a control plane that names
  `doc-declared-envs` in its capabilities, and never into an unreleased or
  machine-ledger bundle. Those bundles' digests do not change.

The shape gains two placement facts under the `shape-placement` feature, both
omitted when empty:
- `workloads[].unit`: a cluster workload's delivery unit, recorded only for an
  env that declares a unit split. With `units[]` it says whether the hub or
  forge applies the workload.
- `host_infra`: the env declares host infrastructure.

A shape recorded before these existed says nothing about them. A reader treats
a split env's cluster-workload applier as unknown, not as forge. A control plane
that does not name `shape-placement` is sent neither field. The machine ledger
decodes every feature, so a local bundle of an env with host infra or a unit
split gets a new digest once, on its first build after upgrading. Nothing
compares local digests across forge versions: a release's bundle of record is
matched by its objects.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.