Expand description
The deployment control plane’s core contracts (R0.12 Operations Plane, wave 3): revisions, environments, and the per-environment deployment pointer, plus the journaled payloads of every control-plane act and the environment-scoped secret records.
The governing decision, from the design: the heavy machinery is
reused, so the new entities stay small. A DeploymentRevision is
the crate::learn::Candidate discipline turned toward deployments —
immutable, content-addressed (derive_revision_id, the
crate::learn::derive_candidate_id rule), authored (human:{id}
attribution) — carrying the graph/assistant identity, the
graph_hash the checkpoint header already computes, and a frozen
pin set: the registry surfaces the revision binds, resolved to
candidate ids at revision creation from a declared source
environment. The freeze is deliberate and priced in the design’s
honest edges: a revision evaluated against a recorded dataset must be
the same thing the gate evaluated when it canaries, and pins resolved
at admission would make that evidence a moving target. The weight —
every registry promotion that should reach prod requires a new
revision — is the price of evaluable deployments, paid knowingly.
An Environment is R0.11’s tag promoted to a first-class record:
a name (the dev / staging / prod convention, deployment-declared
rather than enumerated), the gate and approval declarations that will
govern promotions into it (wired in wave 4; declared here so the rule
in force is data, not code), and creation metadata. What an
environment is not — the R0.11 tag discipline applied one level up:
not a separate process, not an isolated store, not a trust boundary.
Environments are logical surfaces over one deployment’s stores and one
binary’s admission path.
The DeploymentPointer is the R0.8
crate::learn::VersionPointer shape applied to revisions: one
pointer per environment under the surface key deployment:{env}, an
active full-traffic revision, and a canary binding one revision to
a declared fraction of new runs. Promotion moves active and clears
any canary — a full promotion supersedes the experiment it graduated
from. Rollback re-points active to the previously serving revision:
byte-exact, because the restored revision is the immutable record that
served before, not a reconstruction. Canary admission is the seeded
draw (deployment_admission) over the pointer surface — the draw
machinery reused verbatim; only the surface it draws over is new.
Environment-scoped secrets are custody, not brokerage (R0.11’s line,
re-argued by the environment dimension): named, tenant-scoped,
environment-tagged values stored as ciphertext envelopes on both
backends (the broker’s construction — the store side only ever holds
StoredEnvSecret), journaled as metadata — never bytes — on the
deployment evidence chain. A request outside the holder’s environment
is a typed, journaled EnvSecretDenial: scoping is enforcement, not
convention.
Wave 4 turns the declared rules into enforced ones. The gate an
Environment declares is evaluated through the
RevisionGateEvaluator seam — core owns the contract, never the
evaluator, so the runtime keeps its distance from rusty-eval (the
workspace’s dependency direction) — and the decision journals as a
GateDecisionRecord before the pointer move it governs, allowed
or refused: a gate whose refusals leave no evidence is a gate an
audit cannot tell apart from never having run. Approval-required
environments gate promotion behind a token scoped to the revision’s
own promotion effect id (revision_promotion_effect_id) — a token
minted for one revision admits no other, so an approval is a fact
about a specific deploy, not a standing permission. Canary declare
and clear are journaled acts (CanaryDeclaration,
CanaryClearance) on the same chain, so the experiment’s whole
lifecycle — declared, drawn against, graduated or cleared — reads
from one evidence trail. And a shadow run replays a recorded run’s
twin against a candidate revision behind the shadow admission
boundary, journaling its start (ShadowRunStarted), every refusal
the boundary served or not, and its ShadowVerdict: divergence as
evidence, with no path to the world.
Structs§
- Canary
Clearance - A canary was cleared without graduating: the journaled payload of a
crate::record::RunEventKind::CanaryClearedevent, and the moveDeploymentPointer::cleared_canaryapplies. Naming the cleared revision is the point — a bare “slot emptied” would leave the experiment’s end unattributable. - Canary
Declaration - A canary was declared on an environment’s pointer: the journaled
payload of a
crate::record::RunEventKind::CanaryDeclaredevent, and the moveDeploymentPointer::canariedapplies. The binding journals whole — revision and fraction — because the seeded draw an audit replays is a function of exactly these fields. - Canary
Deployment - A canary binding on a deployment pointer: one revision bound to a
declared fraction of new runs while
activeserves the rest — thecrate::learn::CanaryBindingshape with a revision in the slot. - Deployment
Pointer - The serving revision of one environment: an immutable-pointer move
away from any revision that ever served — the R0.8
crate::learn::VersionPointershape applied to revisions. - Deployment
Resolved - The journaled admission resolution (R0.12 wave 3): the output of a
crate::record::RunEventKind::DeploymentResolvedevent, journaled at admission into the run’s own journal — thecrate::registry::ConfigResolutionprecedent lifted from configuration to deployments. - Deployment
Revision - An immutable, content-addressed declaration of what may serve.
- EnvSecret
Act - A secret was set or rotated: the journaled payload of an
crate::record::RunEventKind::EnvSecretSetevent on the deployment evidence chain. Metadata only — the bytes live only in the sealed envelope and can never appear here. - EnvSecret
Denial - A secret resolution was refused on scope: the journaled payload of an
crate::record::RunEventKind::EnvSecretDeniedevent — thecrate::capsule::CapsuleDenialdiscipline (attributable to a declaration, not a stack trace) applied to environment scope. Names the scope requested and the scope the holder holds, because the difference between the two is exactly what a scope audit reads. - EnvSecret
Record - The public record of one environment secret: metadata by construction, safe to serve and journal. Rotation is replacement beneath the stable scoped name — what a run’s evidence pins is the scoped name, not the value of the moment (the broker’s “rotate a credential without redeploying” argument applied to static material).
- EnvSecret
Revocation - A secret was revoked by deletion: the journaled payload of an
crate::record::RunEventKind::EnvSecretRevokedevent. Deletion is the only revocation path — there is no disable flag to forget, and the tombstone is the evidence the scope once held a value. - Environment
- An environment: R0.11’s promotion tag as a first-class record.
- Environment
Declaration - An environment was declared: the journaled payload of a
crate::record::RunEventKind::EnvironmentDeclaredevent. The rule in force journals with the declaration, so an audit reads the declaration that governed a promotion, not a later edit. - Gate
Check Record - One gate check, journaled: the core mirror of
rusty-eval’sGateCheck, serde-mapped at the seam so the runtime never links the eval crate (the workspace’s dependency direction isrusty-eval→ runtime, never the reverse — thecrate::learn::EvaluationThresholdsprecedent).metricis the eval metric’s own serde form (snake_case-tagged), carried as a string so a new eval metric needs no core release to journal. - Gate
Decision Record - A gate decision, journaled: the payload of a
crate::record::RunEventKind::GateDecisionRecordedevent on the deployment evidence chain. The decision journals before the pointer move it governs — and journals when it refuses, so the chain holds the gate’s refusals, not only its permissions. - Gate
Declaration - The gate declaration governing promotions into an environment: the
gate policy’s name and the dataset version the gate replays. Names
only — the declaration, not the evaluator: the rule in force when a
promotion happens is data an audit reads, not code it infers. Wave 4
evaluates it through the
RevisionGateEvaluatorseam before any pointer moves. - Gate
Evaluation - The gate evaluation the
RevisionGateEvaluatorseam returns: the verdict and every check behind it, naming the policy and dataset version it ran under. The seam’s contract requires the evaluator to name back the declaration it was handed — an evaluation that cannot say what it evaluated is not evidence about this promotion. - Registry
Pin - One frozen pin: a registry surface bound to the candidate id that served it in the revision’s source environment at creation. The pin names a candidate — content-addressed, immutable — so the pin set can never drift beneath a recorded revision: what the gate evaluated is what canaries, byte for byte.
- Revision
Content - What a revision binds: the content the address covers.
- Revision
Id - A content-addressed revision identity: lowercase hex SHA-256 over the
revision’s canonical content (
derive_revision_id). Transparent newtype so the type system — not convention — keeps revision ids distinct from candidate ids, memory addresses, and other digest strings (theCandidateIdprecedent). - Revision
Promotion - A revision was promoted into an environment: the journaled payload of
a
crate::record::RunEventKind::RevisionPromotedevent, and the moveDeploymentPointer::promotedapplies.previousis recorded because it is the rollback path’s whole story: the transition history on the chain is what a byte-exact rollback re-derives, never a reconstruction. - Revision
Registration - A revision was registered: the journaled payload of a
crate::record::RunEventKind::RevisionRegisteredevent on the deployment evidence chain. The revision carries its own author and content address; the tenant rides alongside because the chain is deployment-wide (thecrate::artifact::ArtifactReleaseprecedent — audit metadata, not scoping). - Revision
Rollback - A serving revision was rolled back: the journaled payload of a
crate::record::RunEventKind::RevisionRolledBackevent, and the moveDeploymentPointer::rolled_backapplies. Byte-exact by construction:tois derived from the chain’s transition history — the immutable revision that served before — so the restored serving state is a fact about what happened, not a guess at what should. - Shadow
RunStarted - A shadow run started: the journaled payload of a
crate::record::RunEventKind::ShadowRunStartedevent in the shadow run’s own journal. Naming the source run and pinningrole: shadowmakes the twin-pair discipline data the journal carries: the shadow’s evidence names what it shadows, and its role can never be confused with the acting twin’s. - Shadow
Verdict - A shadow run’s verdict: the journaled payload of a
crate::record::RunEventKind::ShadowVerdictevent, and the answer the shadow exists to give — what the candidate tried to do to the world, what the recorded world served back, and where the candidate diverged from the run it shadows. - Stored
EnvSecret - What both store backends hold for one environment secret: the metadata record plus the sealed value. Plaintext on neither backend, ever — a Postgres dump of this row contains no secret (the broker’s custody shape, verbatim).
Enums§
- Deploy
Error - The deployment plane’s typed refusals. A refused declaration, move,
or resolution changes nothing — the
crate::learn::LearnErrordiscipline: refused operations are contract outcomes surfaced to the caller, never silent no-ops. - Gate
Verdict - A gate’s verdict. Two states and no third: a gate that cannot say
allowsaysblock— unevaluable comparisons fail closed (theComparisonAvailableprecedent inrusty-eval). - Shadow
RunOutcome - How a shadow run ended.
Constants§
- MAX_
SECRET_ NAME_ LEN - The longest an environment-secret name may be. Names ride in scoped
keys (
{name}@{environment}), journal payloads, and store primary keys, so a bound keeps a configuration typo from minting an unbounded key. - REVISION_
PROMOTION_ EFFECT_ KIND - The effect kind a revision promotion is admitted under: distinct
from the learn plane’s
candidate_promotion, because the acts are distinct — promoting a candidate changes what the registry points at; promoting a revision changes what an environment serves.
Traits§
- Revision
Gate Evaluator - The release-gate seam: core owns the contract, the server composes
the evaluator over
rusty-eval(thecrate::learn::CandidateEvaluatorprecedent — the runtime declares what a gate must answer; the composition that answers it lives one crate out, where the eval dependency is allowed).
Functions§
- deployment_
admission - The revision an environment’s pointer binds for
run_id: the canary when this run’s seeded draw admits, else the full-traffic revision.Nonewhen the pointer serves nothing — a pointer serving nothing binds nothing, and admission refuses the run rather than guessing. - deployment_
surface - The pointer surface key for one environment:
deployment:{env}. One prefix for every deployment pointer, so pointer listings and the canary draw’s seed material read without string surgery. - derive_
revision_ id - The content address of a revision:
sha256over the canonical serialization of its content — thecrate::learn::derive_candidate_iddiscipline, so two registrations of the same declaration converge on one id and a tampered revision fails its own address. - pin_
set_ digest - The digest a journaled
DeploymentResolvednames for the bound revision’s pin set:sha256over the canonical pin list. The revision’s own address already covers the pins — one derivation, two homes — so the audit walk reads the pin-set commitment out of the resolution event without fetching the revision. - revision_
promotion_ effect_ id - The promotion effect id for a revision into an environment: the
approval-token scope for approval-required environments, derived by
the
crate::learn::promotion_effect_idrule over the deployment surface. Scoped to the revision’s own content address, so a token minted for one revision admits no other — an approval is a fact about a specific deploy, not a standing permission. - scoped_
secret_ name - The scoped id of an environment secret:
{name}@{environment}— the scope is part of the secret’s identity, so the staging database URL and the prod database URL are two secrets that can never be interchangeable. The sealed envelope authenticates this id as associated data, so a ciphertext transplanted between scopes fails to open. - validate_
secret_ name - The secret naming rules, enforced at set time: non-empty, bounded
(
MAX_SECRET_NAME_LEN), no leading or trailing whitespace, no control characters, no@(the scope separator — a name carrying it would make scoped ids ambiguous), and no/(the tenant id-prefix separator). The registry artifact naming rule, applied to secrets.