Skip to main content

Module deploy

Module deploy 

Source
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§

CanaryClearance
A canary was cleared without graduating: the journaled payload of a crate::record::RunEventKind::CanaryCleared event, and the move DeploymentPointer::cleared_canary applies. Naming the cleared revision is the point — a bare “slot emptied” would leave the experiment’s end unattributable.
CanaryDeclaration
A canary was declared on an environment’s pointer: the journaled payload of a crate::record::RunEventKind::CanaryDeclared event, and the move DeploymentPointer::canaried applies. The binding journals whole — revision and fraction — because the seeded draw an audit replays is a function of exactly these fields.
CanaryDeployment
A canary binding on a deployment pointer: one revision bound to a declared fraction of new runs while active serves the rest — the crate::learn::CanaryBinding shape with a revision in the slot.
DeploymentPointer
The serving revision of one environment: an immutable-pointer move away from any revision that ever served — the R0.8 crate::learn::VersionPointer shape applied to revisions.
DeploymentResolved
The journaled admission resolution (R0.12 wave 3): the output of a crate::record::RunEventKind::DeploymentResolved event, journaled at admission into the run’s own journal — the crate::registry::ConfigResolution precedent lifted from configuration to deployments.
DeploymentRevision
An immutable, content-addressed declaration of what may serve.
EnvSecretAct
A secret was set or rotated: the journaled payload of an crate::record::RunEventKind::EnvSecretSet event on the deployment evidence chain. Metadata only — the bytes live only in the sealed envelope and can never appear here.
EnvSecretDenial
A secret resolution was refused on scope: the journaled payload of an crate::record::RunEventKind::EnvSecretDenied event — the crate::capsule::CapsuleDenial discipline (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.
EnvSecretRecord
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).
EnvSecretRevocation
A secret was revoked by deletion: the journaled payload of an crate::record::RunEventKind::EnvSecretRevoked event. 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.
EnvironmentDeclaration
An environment was declared: the journaled payload of a crate::record::RunEventKind::EnvironmentDeclared event. The rule in force journals with the declaration, so an audit reads the declaration that governed a promotion, not a later edit.
GateCheckRecord
One gate check, journaled: the core mirror of rusty-eval’s GateCheck, serde-mapped at the seam so the runtime never links the eval crate (the workspace’s dependency direction is rusty-eval → runtime, never the reverse — the crate::learn::EvaluationThresholds precedent). metric is 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.
GateDecisionRecord
A gate decision, journaled: the payload of a crate::record::RunEventKind::GateDecisionRecorded event 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.
GateDeclaration
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 RevisionGateEvaluator seam before any pointer moves.
GateEvaluation
The gate evaluation the RevisionGateEvaluator seam 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.
RegistryPin
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.
RevisionContent
What a revision binds: the content the address covers.
RevisionId
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 (the CandidateId precedent).
RevisionPromotion
A revision was promoted into an environment: the journaled payload of a crate::record::RunEventKind::RevisionPromoted event, and the move DeploymentPointer::promoted applies. previous is 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.
RevisionRegistration
A revision was registered: the journaled payload of a crate::record::RunEventKind::RevisionRegistered event on the deployment evidence chain. The revision carries its own author and content address; the tenant rides alongside because the chain is deployment-wide (the crate::artifact::ArtifactRelease precedent — audit metadata, not scoping).
RevisionRollback
A serving revision was rolled back: the journaled payload of a crate::record::RunEventKind::RevisionRolledBack event, and the move DeploymentPointer::rolled_back applies. Byte-exact by construction: to is 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.
ShadowRunStarted
A shadow run started: the journaled payload of a crate::record::RunEventKind::ShadowRunStarted event in the shadow run’s own journal. Naming the source run and pinning role: shadow makes 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.
ShadowVerdict
A shadow run’s verdict: the journaled payload of a crate::record::RunEventKind::ShadowVerdict event, 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.
StoredEnvSecret
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§

DeployError
The deployment plane’s typed refusals. A refused declaration, move, or resolution changes nothing — the crate::learn::LearnError discipline: refused operations are contract outcomes surfaced to the caller, never silent no-ops.
GateVerdict
A gate’s verdict. Two states and no third: a gate that cannot say allow says block — unevaluable comparisons fail closed (the ComparisonAvailable precedent in rusty-eval).
ShadowRunOutcome
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§

RevisionGateEvaluator
The release-gate seam: core owns the contract, the server composes the evaluator over rusty-eval (the crate::learn::CandidateEvaluator precedent — 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. None when 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: sha256 over the canonical serialization of its content — the crate::learn::derive_candidate_id discipline, 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 DeploymentResolved names for the bound revision’s pin set: sha256 over 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_id rule 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.