Expand description
WorkloadSpec — typed wire format for yubaba workloads.
This crate is the schema source of truth. It has zero dependencies on yubaba; yubaba depends on it, not the other way around. Agents and desktop code that construct specs can link this crate without pulling in yubaba’s containerd client.
Three validation layers live in validate: shape (sync, no I/O),
semantic (reads yubaba state), and environment (deploy-time). The schema
types live at the top level.
@yah:ticket(R222-T3, “Workload schema doesn’t match per-kind on-disk shapes (mesofact-static)”) @yah:assignee(agent:claude) @yah:at(2026-05-18T16:47:03Z) @yah:status(review) @yah:parent(R222) @yah:handoff(“Picked option (a): tagged-enum Workload envelope with per-kind variants. Added Workload { MesofactStatic(MesofactStaticWorkload), Container(WorkloadSpec) } + BuildConfig in workload-spec. WorkloadSpec stays the containerd RPC wire type (now also the kind="container" variant payload). xtask emit-schemas now renders workload.toml.schema.json as a oneOf over kind; schema drift test green. TS export updated. Arch doc ‘workloads — colocated, not registered’ rewritten to describe the envelope + both example kinds; B4 outlook updated to point at Workload.”) @yah:verify(“cargo check -p cloud && cargo test -p cloud && cargo check -p yah && cargo check -p agent-tools && cargo check -p yah –tests && cargo check -p agent-tools –tests”) @yah:verify(“cargo test -p xtask # schema drift test must stay green”) @yah:verify(“cargo run -p workload-spec –bin export-ts # idempotent regen”)
@yah:ticket(R256-F7, “Model mesofact container as two roles: transient build/publish job vs long-lived SSR/SPA runtime”)
@yah:assignee(agent:claude)
@yah:at(2026-05-25T20:08:29Z)
@yah:status(review)
@yah:parent(R256)
@yah:next(“role A — build/publish job: transient task that runs the build and PUTs to the object store, then exits/GC’d; needed whenever there is a build step (SSR or not)”)
@yah:next(“role B — SSR/SPA runtime: long-lived container, only present when the app has realtime/dynamic pages (this is what the ‘only if SSR/SPA’ gate applies to)”)
@yah:next(“decide the fidelity knob: does the build run in-container (matches CI, max fidelity, costs image+cold-start) or on host with yubaba orchestrating only the serving edge?”)
@yah:assumes(“in cloud these are separate: CI/build job produces artifacts, R2+CDN serve them, and a distinct worker serves any SSR — so one merged ‘mesofact container’ is the trap”)
@yah:handoff(“BuildMode enum added to workload-spec with HostSide (default) and InContainer { image } variants. MesofactStaticWorkload gains build_mode: BuildMode (skip_serializing_if default) and ssr_runtime: Option
@yah:ticket(R256-F9, “Almanac as a dependency manifest: orchestrator verifies I/O targets live before run; output invalidates mesofact sources cleanly”)
@yah:assignee(agent:claude)
@yah:at(2026-05-25T21:28:15Z)
@yah:status(review)
@yah:parent(R256)
@yah:next(“almanac is a manifest declaring inputs + outputs + cadence + command — NOT a bash cron; the declared I/O is the contract”)
@yah:next(“before a run the orchestrator verifies declared inputs exist AND output targets (e.g. the mesofact app + its source/object store) are reachable; if not → the run fails or waits/times out rather than producing orphaned output”)
@yah:next(“almanac output invalidates downstream mesofact sources cleanly + deliberately (a declared dependency edge, not a blunt rebuild-everything) — this is the reason it’s a named manifest, not a shell cron”)
@yah:next(“decide the not-ready policy knob: fail-fast vs wait-with-timeout vs requeue”)
@yah:next(“generalizes the OpenRouter refresher (spawn_almanac_refresher), which is the degenerate no-dependency case (output = JSON cache, no app target)”)
@yah:assumes(“precondition enforcement lives in the shared scheduler layer (embedded by camp for dev/sim, yubaba for cloud/ha) — it needs the workload registry + xlb-net discovery to answer ‘is the target up?’, which a bash cron lacks”)
@arch:see(.yah/docs/architecture/A024-vocabulary.md)
@yah:depends_on(R256-F6)
@yah:handoff(“AlmanacTarget (Http/Tcp probe), NotReadyPolicy (WaitWithTimeout default=5s/FailFast/Requeue), Cadence (Once/Every/Cron), and AlmanacManifest types added to workload-spec. Workload enum gains Almanac(AlmanacManifest) variant (kind=‘almanac’). NotReadyPolicy::WaitWithTimeout(5s) is the default — matches sim-tier spinup budget. AlmanacManifest.invalidates: Vec
@yah:relay(R335, “Almanac mirror-binding — scope a feed to the mirror it affects”) @yah:at(2026-05-27T02:19:09Z) @yah:status(open) @arch:see(.yah/docs/working/W058-almanac-mirror-binding.md) @yah:depends_on(R256-F9)
@yah:ticket(R335-S1, “Decide cross-env pollution mechanism: extend R256-F9 manifest vs add per-mirror capability”) @yah:assignee(agent:claude) @yah:at(2026-05-27T02:19:33Z) @yah:kind(spike) @yah:status(review) @yah:phase(P1) @yah:parent(R335) @yah:gotcha(“Build ON R256-F9’s AlmanacManifest (workload-spec/src/lib.rs) — do NOT invent a parallel manifest. R256-F9 is in review.”) @yah:depends_on(R256-F9) @yah:handoff(“Decided. Recorded in almanac-mirror-binding.md §11. KEY FINDING: two almanac paths exist; the live R330 feed uses almanac::FeedConfig (on_change=MesofactRebuild{service,route} — a service id, NOT a MeshIdent), so it never touches AlmanacManifest.invalidates. Verdict on the S1 title: NEITHER extend the manifest nor (yet) add capability is the accident fix — dev->cloud is ALREADY blocked by construction (feed path = process locality + per-mirror reconciler + MinIO/R2 backend split; manifest path = no camp-embedded MeshState, mesh resolution is yubaba-raft-only). Residual holes: /revalidate receiver is UNAUTHENTICATED, and same-tier (two clouds on one R2) has no per-mirror key prefix.”) @yah:next(“FILED: R335-F3 (P1, no yubaba dep) mirror-aware /revalidate receiver — reject feeds not bound to this mirror; satisfies R335-T2; lands with R330-F4.”) @yah:next(“FILED: R335-F4 (P2) per-mirror artifact key prefix in derive_minio_key/publish_to_r2 — closes same-tier collision.”) @yah:next(“FILED: R335-F5 (P3, BLOCKED on yubaba control plane) per-mirror capability gate on /revalidate via yubaba/xlb-net node identity.”)
@yah:ticket(R278-F4, “RolloutPolicy schema in workload-spec (TOML types)”) @yah:assignee(agent:claude) @yah:at(2026-06-01T02:31:25Z) @yah:status(review) @yah:parent(R278) @yah:next(“Add src/rollout.rs with RolloutPolicy, RolloutStrategy, RolloutGate, RolloutStep, RolloutOnFailure”) @yah:next(“Export pub mod rollout from lib.rs”) @yah:next(“Add TS export via ts-rs in export-ts.rs”) @arch:see(.yah/docs/working/W140-yah-yubaba-ci-cd.md) @yah:handoff(“RolloutPolicy, RolloutStrategy, RolloutGate, RolloutStep, RolloutOnFailure added to workload-spec/src/rollout.rs. Exported from lib.rs. toml dev-dep added for round-trip test. Tests: rollout::tests::round_trip_toml + on_failure_default both green.”)
@yah:ticket(R429-T1, “Workload::StaticAsset variant + schema in workload-spec (catalog + aliases)”)
@yah:assignee(agent:claude)
@yah:at(2026-06-03T23:24:20Z)
@yah:status(review)
@yah:phase(P1)
@yah:parent(R429)
@yah:next(“Add Workload::StaticAsset(StaticAssetWorkload) variant alongside the existing MesofactStatic + Container envelopes. Mirror the tagged-enum shape R222-T3 established.”)
@yah:next(“StaticAssetWorkload fields: kind=‘static-asset’ tag, assets: Vec
@yah:ticket(R429-F2, “static-asset reconciler: BLAKE3 verify + S3 PUT against mirror’s object_store + drift”)
@yah:assignee(agent:claude)
@yah:at(2026-06-03T23:24:38Z)
@yah:status(review)
@yah:phase(P2)
@yah:parent(R429)
@yah:next(“New reconciler that handles kind=‘static-asset’ in the same service-sync loop that already runs mesofact-static + container. Same wave-gate semantics, same drift shape.”)
@yah:next(“For each [[asset]] row: hash source file (BLAKE3) and compare to manifest entry. Mismatch → surface as drift, halt push for that asset until rebuild.”)
@yah:next(“Resolve mirror’s object_store provider → R2 bucket + credentials. HEAD cas/filename; if absent or different content-length → PUT. Idempotent on re-run.”)
@yah:next(“Drift detection: list bucket contents under the component’s prefix, compare against catalog filenames. Files in bucket ∖ catalog → report as drift (do NOT delete; that’s the prune verb’s job).”)
@yah:next(“ServicesView’s existing matrix consumes the new drift shape automatically. Confirm SyncGlyph/DriftList render correctly for a static-asset row without UI changes.”)
@yah:next(“MockR2 in tests: HashMap<key, bytes> implementing the S3 surface the reconciler hits. Cover: push first-time, push idempotent, drift catches catalog-vs-bucket mismatch, BLAKE3 mismatch halts push.”)
@yah:next(“Real-R2 integration test gated behind YAH_TEST_R2_BUCKET env var — one round-trip against a scratch bucket; skipped otherwise.”)
@yah:verify(“cargo check –workspace –locked”)
@yah:verify(“cargo test -p
@yah:ticket(R429-T3, “yah service prune verb: candidate enumeration + operator-confirm delete”)
@yah:assignee(agent:claude)
@yah:at(2026-06-03T23:24:52Z)
@yah:status(review)
@yah:phase(P3)
@yah:parent(R429)
@yah:next(“yah service prune yah cloud service prune <name> --env <env> [--dry-run] [--yes] [--format=table|json] at app/yah/cli/src/cloud.rs (ServiceCommands::Prune + handle_service_prune). MCP tools cloud.service_prune_status (read, auto-pass, –dry-run –format=json) and cloud.service_prune (write, –yes –format=json) dispatch through build_command(). New S3 helper sign_s3_get_with_query in local-driver covers ListObjectsV2 (the existing s3_sign helpers don’t handle canonical query strings); ListObjectsV2 response is parsed with a tiny hand-rolled split_tags helper to avoid a quick-xml workspace dep. Tests: 12 prune-module unit tests (live-set union, kind filtering, list response parse for single/empty/truncated/no-token, candidate filtering including catalog manifest sidecar exclusion) + 1 s3_sign helper test + 2 MCP build_command tests. cargo check –workspace clean. cargo test -p cloud –lib: 279 pass (1 pre-existing failure cloud_init::tests::embedded_template_matches_workspace_canonical unrelated, per R419-F4 docstring). cargo test -p yah –lib: 299 pass.”)
@yah:next(“R429-F4 carries the Tauri + DeployPanel UI work — depends_on R429-T3, status=open.”)
@yah:verify(“cargo check –workspace –locked”)
@yah:verify(“cargo test -p cloud –lib reconciler::static_asset_prune # 12 pass”)
@yah:verify(“cargo test -p yah –lib mcp::tools::tests::cloud_service_prune # 2 pass”)
@yah:verify(“yah cloud service prune –help # renders usage with –env/–dry-run/–yes/–format”)
@arch:see(.yah/docs/working/W164-derived-static-assets.md)
@yah:ticket(R438-T2, “AssetEntry XOR: source vs derive + shape_static_asset rules”)
@yah:assignee(agent:claude)
@yah:at(2026-06-04T21:06:51Z)
@yah:status(review)
@yah:phase(P1)
@yah:parent(R438)
@yah:next(“AssetEntry.source: PathBuf → Option
@yah:ticket(R438-T3, “ImageRef digest-pin enforcement at deserialize”)
@yah:assignee(agent:claude)
@yah:at(2026-06-04T21:06:55Z)
@yah:status(review)
@yah:phase(P1)
@yah:parent(R438)
@arch:see(.yah/docs/working/W164-derived-static-assets.md)
@arch:see(.yah/docs/working/W165-mesofact-build-mode-lowering.md)
@yah:handoff(“ImageRef now accepts either a string form (digest-pinned, W164/W165 path) or the legacy struct form (backwards-compat for WorkloadSpec configs). String form requires @sha256:
@yah:ticket(R438-T7, “Golden tests: recipe→ForgeSpec lowering + BuildMode→ForgeSpec lowering parity”)
@yah:assignee(agent:claude)
@yah:at(2026-06-04T21:07:30Z)
@yah:status(review)
@yah:phase(P3)
@yah:parent(R438)
@yah:next(“Golden test: sample transform recipe + asset.derive.transform.params lowers to expected ForgeSpec (argv, image digest, TaskPlacement)”)
@yah:next(“Golden test: MesofactStaticWorkload with build_mode=in_container lowers to expected ForgeSpec”)
@yah:next(“Round-trip parity: same Subprocess + Local + Container quadrant for both consumers; regression-guards argv-substitution and image-pin drop-through”)
@yah:verify(“cargo test -p workload-spec lowering_golden_*”)
@yah:verify(“Golden files versioned; updates require explicit –update flag”)
@arch:see(.yah/docs/working/W164-derived-static-assets.md)
@arch:see(.yah/docs/working/W165-mesofact-build-mode-lowering.md)
@yah:depends_on(R438-T5)
@yah:depends_on(R438-T6)
@yah:handoff(“T7 landed. (1) Extracted pure lowering helpers exposed at pub(crate):\n - mesofact_static::lower_build_to_forge_spec(workload_dir, &BuildConfig, &BuildMode) -> ForgeSpec (run_build now wraps this)\n - static_asset::lower_recipe_step_to_forge_spec(&TransformRecipe, &RecipeStep, substituted_argv) -> ForgeSpec (materialize_transform now calls this for each step)\n(2) New cfg(test) module crates/yah/cloud/src/reconciler/lowering_golden.rs registered from reconciler/mod.rs. Five golden tests:\n - golden_recipe_step_lowers_to_pinned_local_container_subprocess (recipe → ForgeSpec shape: argv, image digest, timeout, label, initiator)\n - golden_recipe_step_with_zero_timeout_lowers_to_none (regression-guards the timeout=0 → None mapping)\n - golden_build_in_container_lowers_to_pinned_local_container_subprocess (BuildMode::InContainer → sh -c shell wrap + pinned image + cwd label)\n - golden_build_host_side_lowers_to_native_quadrant_without_image (BuildMode::HostSide → image=None + TaskRuntime::Native)\n - parity_recipe_and_build_in_container_share_quadrant (THE architectural invariant: both consumers land in the same Subprocess + Local + Container quadrant with sha256-pinned images and Gnome initiators — lets one ForgeExecutor dispatch handle both)\n(3) Test artifacts are hand-coded assertions, not insta/snapshot files — workspace has no insta infra and explicit-Pin tests give clearer diff on drift than auto-update snapshots. The W164/W165 lowering shape is now regression-guarded against silent drift in either consumer. cargo test -p cloud –lib reconciler::lowering_golden: 5 pass. Workspace check clean.”)
@yah:next(“Sign off → archive R438-T7”)
@yah:next(“T8 (worked examples) now has tested lowering primitives to reference”)
@yah:verify(“cargo test -p cloud –lib reconciler::lowering_golden — 5 pass”)
@yah:verify(“cargo test -p cloud –lib reconciler:: — 124 pass; 4 pre-existing R441-B4 adopt_only failures (port 4321 dev-box collision) unrelated”)
@yah:verify(“cargo check –workspace –locked — clean (warnings only)”)
@yah:verify(“Parity test asserts both lowerings produce TaskPlacement{Local, Container} + ForgeCommand::Subprocess + sha256-pinned image — the shared executor dispatch invariant”)
@yah:gotcha(“Test location pivot: original ticket said cargo test -p workload-spec lowering_golden_* but the lowering primitives don’t live in workload-spec — ForgeSpec/TaskPlacement are in task, and the actual lowering helpers are in cloud (both consumers live there). Tests landed in cloud as reconciler::lowering_golden. If a future consumer outside cloud needs the BuildMode lowering, lift lower_build_to_forge_spec up to task::transforms alongside the existing recipe lowering primitives.”)
@yah:gotcha(“No snapshot/insta infra in workspace — ‘Golden files versioned; updates require explicit –update flag’ verify line interpreted as hand-coded explicit assertions instead. Drift surfaces as a single-file test diff on the lowering helper, which is more readable than a .snap diff for the small ForgeSpec shape these tests cover.”)
@yah:ticket(R594-F2, “Ingress workload kind in workload-spec: pinned-per-node appliance on public-ip-tainted machines”) @yah:status(review) @yah:assignee(agent:claude) @yah:at(2026-07-03T06:03:30Z) @yah:phase(P2) @yah:parent(R594) @yah:next(“Add the ingress workload kind to the Workload enum (lib.rs:296) as an appliance in the R572 archetype sense: pinned-per-node, non-drainable, placed by yubaba only on machines carrying a public-ip taint, supervised by kamaji. Depends on R572-F1 (lifecycle archetype discriminator) so the archetype field exists to mark it. Breaking change is fine (pre-release house style); update kamaji-bin server.rs InvalidSpec rejection list deliberately — kamaji MUST accept this kind (it supervises the proxy), unlike MesofactStatic/Almanac/StaticAsset.”) @yah:verify(“cargo test -p yah-workload-spec; cargo check -p yubaba -p kamaji-bin; kamaji admission accepts kind=ingress in a unit fixture”) @yah:gotcha(“RUNS SOLO: workload-spec is the shared-type DAG sink (yah-base) — every lane (yubaba, kamaji, qed, host app) rebuilds on its change. Pause all other wave-2/3 implementer lanes while this is active, and check R572-T2 (cpu_millis, Handoff) + R572-F1 owner state before claiming — same file.”) @yah:depends_on(R572-F1) @yah:tier(Cleric) @yah:handoff(“Modeled the W267 public-ingress appliance as a container-shaped workload (Workload::Container(WorkloadSpec)), not a new Workload variant: mark archetype = Some(LifecycleArchetype::Appliance) (R572-F1, pinned/non-drainable) and declare the public-ip placement requirement via a new annotation-based marker on WorkloadSpec (same zero-blast-radius pattern as existing wants_host_network/HOST_NETWORK_ANNOTATION, chosen specifically to avoid the ~26-call-site churn a new plain field forced for R572-F1’s archetype field, and to avoid an exhaustive-match update in peer-owned kamaji-proto/codec.rs that a new Workload variant would force). Added: WorkloadSpec::requires_taint() -> Option<&str>, const REQUIRES_TAINT_ANNOTATION = "yah.placement.requires-taint", const PUBLIC_IP_TAINT = "public-ip", plus doc comments on Workload::Container recording the modeling decision and its rationale, all in oss/yah-base/crates/workload-spec/src/lib.rs (single file changed). This only declares the requirement as inert metadata — matching taint field on machine TOML is R572-F3 (not yet present) and scheduler enforcement is R572-F5; both out of scope here, noted in the doc comments. Verified kamaji needs NO change: deploy_workload’s match in kamaji-bin/src/server.rs already dispatches any Workload::Container(_) to the containerd backend regardless of tier/annotations (only MesofactStatic/Almanac/StaticAsset hit the InvalidSpec rejection arm), confirmed by reading the code and by the existing deploy_container_without_feature_says_so / deploy_mesofast_static_is_rejected_as_invalid_spec unit tests both still passing unmodified. 2 new unit tests added (ingress_marked_spec_is_appliance_and_carries_public_ip_placement_requirement, ingress_marked_spec_round_trips_through_json_as_a_container_workload). cargo test -p yah-workload-spec –lib: 38/38 pass. cargo test -p yah-workload-spec –test round_trip: 7 pass, exactly the same pre-existing 2 postcard failures (round_trip_full_spec_through_postcard, workload_container_round_trips_through_postcard — R590-B3, unrelated) as before this change, confirmed not increased. cargo check -p yah-workload-spec / -p yubaba / -p kamaji-bin all clean, plus full cargo check –workspace in both oss/kamaji and oss/yubaba clean (only pre-existing unrelated warnings). No peer-owned file touched or needed.”)
@yah:ticket(R590-B10, “forge workload 256MB cgroup memory limit SIGKILLs real builds — rusty-v8 checkout OOMs (bumped to 32GB stopgap)”)
@yah:at(2026-07-12T00:14:52Z)
@yah:status(review)
@yah:assignee(agent:claude)
@yah:parent(R590)
@yah:severity(blocks-on-box-green)
@yah:next(“Proper fix: thread a per-step memory request from the pipeline (QedStep) through ForgeSpec -> WorkloadSpec so a build declares its footprint, instead of a blanket forge default. Also consider: build_oci_spec should treat memory_mb==0 as ‘omit the cgroup limit’ (unlimited) so dedicated build-workers aren’t capped by an arbitrary constant; pair with a node-sized default. Revisit the 32GB stopgap once per-step resources land.”)
@yah:verify(“yah qed run rusty-v8-musl on us-west-002 completes the checkout + gn/ninja compile without an OOM SIGKILL; a small forge task still runs (32GB is a ceiling, not a reservation).”)
@yah:gotcha(“PROVEN live (2026-07-11): with B7 networking fixed, the rusty-v8 build cloned the full V8 tree then git checkout third_party/icu DIED OF SIGNAL 9 (OOM). WorkloadSpec::for_forge set resources.memory_mb=256, which build_oci_spec turns into a hard cgroup memory.limit. /tmp is a RAM-backed tmpfs so the multi-GB source checkout counts against that 256MB too. Bumped for_forge to 32768 (32GB) as a CLI-side stopgap; verified the build proceeds past icu.”)
@yah:handoff(“FIXED + PROVEN LIVE (2026-07-11). WorkloadSpec::for_forge memory_mb 256 -> 32768 (oss/yah-base/crates/workload-spec/src/lib.rs). CLI-only change (spec is client-built), no kamaji redeploy. RESULT: with B7 networking, the rusty-v8 build previously OOM’d (SIGKILL/signal 9) at the icu git-checkout under the 256MB cgroup cap; now it clones the full V8 tree AND proceeds past icu into cargo/gn compilation (Compiling icu_locale_data/icu_calendar_data…) with task RUNNING. Stopgap 32GB ceiling; proper per-step memory request from the pipeline is the follow-up in the ticket body.”)
@yah:ticket(R546-B7, “workload_spec::Workload envelope is externally tagged (missing serde tag=kind) — no flat on-disk workload.toml can parse through it, broke yah cloud apply for EVERY static-asset component”)
@yah:at(2026-07-20T23:52:55Z)
@yah:status(open)
@yah:parent(R546)
@yah:next(“DO NOT simply add #[serde(tag = \"kind\")] without checking postcard: Workload is also a postcard wire type on the kamaji RPC path (kamaji-proto/src/codec.rs matches on it; round_trip tests exist). postcard is non-self-describing and cannot decode internally-tagged enums, so naive tagging risks breaking the kamaji wire. Decide deliberately: (a) tag it and prove the postcard round-trips still pass, or (b) split the types — an on-disk WorkloadManifest with tag=kind, leaving Workload as the untagged wire type.”)
@yah:next(“INTERIM FIX ALREADY LANDED (unblocks publishing): static_asset.rs::load_workload no longer routes through the envelope — it deserializes a small KindProbe { kind }, validates kind == "static-asset", then parses StaticAssetWorkload directly. Same approach seed_derivation_for_target already used successfully. This restored yah cloud apply and got the x86_64 rusty-v8 artifact published to the CDN (HTTP 200). The ENVELOPE itself is still broken for every other caller/kind.”)
@yah:next(“Fix the test/example disagreement: lib.rs ~L2544 should assert the FLAT kind = \"...\" shape that real files use, and examples/parse_whisper_toml.rs should run in CI so this cannot regress silently again.”)
@yah:gotcha(“SEVERITY: this silently broke yah cloud apply for EVERY static-asset component, not just rusty-v8. Verified against the long-published whisper catalog via the repo’s own examples/parse_whisper_toml.rs, which panics with the identical error — so the breakage is general and pre-existing, not caused by the R546 hash edits.”)
@yah:gotcha(“ROOT CAUSE: pub enum Workload (oss/yah-base/crates/workload-spec/src/lib.rs ~L386) derives Deserialize with ONLY #[serde(rename_all = \"kebab-case\")] — there is NO #[serde(tag = \"kind\")], despite its own doc comment stating ‘the kind field on the wire is the serde discriminator’. Without the tag it is EXTERNALLY tagged, so serde wants a map with exactly ONE key (the variant name). Every real workload.toml is FLAT (kind = \"static-asset\" + schema_version + [[asset]] + [aliases]), i.e. a multi-key map -> TomlError: wanted exactly 1 element, more than 1 element, reported confusingly at line 1 col 1.”)
@yah:gotcha(“WHY THE UNIT TEST DIDN’T CATCH IT: the passing test at lib.rs ~L2544 feeds the EXTERNALLY-tagged shape [[static-asset.asset]], which no on-disk file actually uses. So the test asserts the broken encoding and the example (parse_whisper_toml.rs) asserting the REAL encoding was never run in CI. The test and the example disagree; the example is right.”)
@yah:ticket(R626-S3, “Where does desired-state live? Durable per-workload replica count that survives reconcile loops and camp restarts (0↔1 vs scale-to-N)”)
@yah:status(review)
@yah:assignee(agent:bundle-anthropic-glimmerstone)
@yah:at(2026-07-23T17:47:24Z)
@yah:kind(spike)
@yah:phase(P3)
@yah:parent(R626)
@yah:handoff(“DECIDED + LANDED. Desired state lives in the CAMP DAEMON, in a durable camp-local document at replicas, where 0 = stopped — deliberately the SAME axis as workload_spec::WorkloadSpec.replicas so scale-to-N later lifts a ceiling instead of adding a second concept beside a boolean. MAX_SUPPORTED_REPLICAS = 1 today and set_replicas REJECTS anything higher rather than persisting an intent no supervisor can honour (a clamp would silently record something the operator did not ask for). No record = replicas 1: a declared workload runs unless someone said otherwise. updated_at + reason ride along so a stale intent is legible and the UI can say when/why. Writes are tmp-then-rename; reads FAIL OPEN (missing/unreadable/corrupt/newer-schema all mean ‘everything runs’, corrupt file preserved as .corrupt-<epoch_ms>) — fail-closed would mass-stop a camp on one bad byte, and a resurrection is the recoverable failure.”)
@yah:handoff(“LANDED: (1) app/yah/cli/src/desired_state.rs — DesiredStateDoc / WorkloadDesire / DesiredStateStore (load, desired_replicas, is_stopped, stopped_keys, set_replicas, stop, start, forget), 10 unit tests incl. survives-a-camp-restart, per-workload isolation, replicas>1 rejected AND not written, corrupt-file quarantine + fail-open, newer-schema fail-open, and an explicit ‘a stop is not a failure’ guard on the serialized document. (2) camp.rs: deploy_pond_mirrors and reconcile_pond_deploys now consult the store and skip stopped idents — this is THE enforcement point, since camp’s re-assert is the only place ‘stay stopped’ can be honoured. Extracted pond_idents_needing_deploy(declared, registered, stopped) as a pure helper with 5 tests, because the stopped-subtraction is the load-bearing half: a stopped workload is absent from yubaba’s registry ON PURPOSE and is indistinguishable from a failed deploy without the intent record. (3) .yah/.gitignore + app/yah/cli/templates/yah-gitignore-default gain /state. (4) .yah/docs/working/W287-desired-state-for-supervised-workloads.md carries the full rationale, the rejected options, the F4 build-on list, and the scale-to-N scoping.”)
@yah:handoff(“DELIBERATE NON-GOAL: writing intent does NOT actuate. The durable record must land even when the stop call fails, or a failed stop comes back on the next reconcile. Actuation is R626-F4’s job.”)
@yah:next(“R626-F4 is unblocked and now has a concrete spec — see W287 §5. It needs three things this ticket deliberately did not build: (a) a per-ident teardown on yubaba (PondRegistry has only shutdown_all, which drains everything; /pond/deploy and /pond/state are the only pond routes), (b) camp RPC methods workload.stop / workload.start writing through DesiredStateStore, (c) desired-vs-actual reporting.”)
@yah:next(“DO NOT add a Stopped variant to PondPhase (R626-F2’s noted gap). PondPhase is yubaba’s observation of REALITY; intent never crosses that wire by this decision. Camp is the one process holding both halves — render the pair instead: desired=stopped + actual=absent reads ‘deliberately stopped’; desired=running + actual=absent reads ‘down’.”)
@yah:next(“Scale-to-N stays scoped, not committed (W287 §6). WorkloadSpec.replicas makes N look one constant away; it is not. kamaji native.rs:592 rejects replicas>1, and the docker backend names containers by mesh identity (one identity, one container). N needs a placement layer above the single-workload supervisor: per-replica naming (identity==container name is what makes teardown resolve), per-replica host ports (pond publishes fixed ones — two replicas collide), per-replica mesh identity (a load-balanced set is an xlb-net concern), and a placement decision that is yubaba’s job on a fleet. Lifting MAX_SUPPORTED_REPLICAS is the entry point once that layer exists.”)
@yah:next(“Wire DesiredStateStore::forget into the undeclare path so the document doesn’t accumulate intent for mirrors that no longer exist.”)
@yah:verify(“cargo test -p yah –lib desired_state — 15 pass (10 desired_state::tests + 5 camp::r626_s3_desired_state_gate_tests), 0 fail”)
@yah:verify(“cargo check -p yah — clean (note: this camp’s tree is shared and was transiently broken by peers’ in-flight edits in oss/qed, yah-party, and yah-almanac during this run; none touched by this ticket)”)
@yah:verify(“BEHAVIOUR BAR (the one that matters): DesiredStateStore::for_camp(root).stop(ident) followed by a FRESH store over the same root still reports is_stopped — that is exactly a camp restart — and pond_idents_needing_deploy then omits that ident from an EMPTY registry, which is exactly a restarted yubaba. Asserted in camp::r626_s3_desired_state_gate_tests::a_stop_survives_a_camp_restart_end_to_end.”)
@yah:gotcha(“The store is camp-local and GITIGNORED on purpose. If a future ticket wants a stop to be shared/durable in the repo, that is a different decision (declaration vs intent) — re-open W287 §2 rather than moving the file into tracked territory.”)
@yah:gotcha(“Reads fail OPEN. Never ‘harden’ this into fail-closed: an unreadable document would then stop an entire camp, and the failure would be silent (nothing starts) rather than visible (the workload comes back).”)
Modules§
- compose_
import - One-way, lossy compose YAML →
WorkloadSpecimport shim. - control_
plane_ install - Shared install-script builder for a control-plane (yubaba + kamaji) roll.
- forge_
produced - Convention for a remote forge step’s durable produced artifacts.
- rollout
- Rollout policy schema — the typed form of
.yubaba/rollout.toml. - secrets
- Pluggable secret resolver for
crate::SecretRefvalues. - validate
- Shape validators for
WorkloadSpec.
Structs§
- Almanac
Manifest kind = "almanac"manifest — a declared data-pipeline job.- Asset
Derive - Provenance chain for a derived asset: required
fetchstep, optionaltransformstep. Materialized bytes replaceAssetEntry.sourcefor the rest of the static-asset reconcile loop. - Asset
Entry - A single file entry in the static-asset catalog.
- Backoff
Policy - Exponential backoff parameters for
RestartPolicy::OnFailure. - Blake
Hash - BLAKE3 content hash expressed as exactly 64 ASCII hex digits.
- Build
Config - Build step that produces the static artifact published by a
mesofact-staticworkload. - Derive
Lock - W212/R518: the committed derivation lock — the in-tree action-cache
receipt.
input_hashis the input-addressed derivation key computed over the complete declared input set (fetched-input pin ⊕ recipe-file bytes ⊕ invocation params ⊕ schema version);output_blake3is what those inputs produced (== the entry’sblake3). The reconciler skips the entire build (no fetch, no transform, no PUT) when the lock matches the inputs recomputed from the current pins and the bucket already holds the output — the Nix-substituter / Bazel-remote-cache behaviour. Written by the R510 bind path from the reconciler’sdiscovered_input_hash:<filename>output; thegit diffon this block is the receipt that the derivation rolled. - EnvVar
- A single environment variable injected into the container.
- Expose
Spec - Network exposure configuration. The three channels are independent; any combination is valid.
- Fetch
Source - Shared fetch primitive — usable by
asset.derivetoday, and by Almanac’sReleaseSourceafter a follow-up migration (R438-F10). Defined once in workload-spec so both consumers reject the same set of non-permissive licenses. - Healthcheck
- Container health probe configuration.
- Image
Ref - Container image reference identifying a specific image to pull.
- Machine
Id - Opaque identifier for a yubaba-managed machine within the cluster.
- Mesh
Expose - Mesh-internal port exposure and peer access control.
- Mesh
Ident - DNS-segment identity for a workload on the cluster mesh, e.g.
"noisetable-api.pdx". Regex constraint:^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, length ≤ 63. Enforced in shape validation (R090-F2). - Mesofact
Serve Bundle - Serve-time reference to a published W272 bundle (R599-F4) — the
{bundle_digest, runtime, lifecycle}triple amesofact-staticworkload carries when kamaji, not the build reconciler, serves it. - Mesofact
Static Workload kind = "mesofact-static"payload — static-site build colocated with the frontend it deploys.- Millis
- Duration expressed as an integer millisecond count.
- Namespace
Id - Namespace routing/naming axis (W206). A pure naming key that never
affects isolation: it selects the config root, disambiguates service DNS
names within a tenant, prefixes object-store bucket names within a tenant’s
bucket scope, and selects the provider zone (e.g.
noisetable.comvsyah.dev). Two namespaces in the same tenant share networks, mesh-identity space, and PG cluster — they simply cannot collide on workload names or external domains. Specs written before this axis existed deserialize toNamespaceId::singleton. - Operator
Expose - Operator-facing exposure via a Tailscale ACL tag.
- Public
Expose - Public internet exposure via a Cloudflare tunnel route.
- Resource
Limits - Hard resource caps enforced by containerd/cgroups at runtime.
- Secret
Mount - A secret value mounted into the container as an env var or file.
- Static
Asset Workload kind = "static-asset"payload — content-addressed bucket catalog.- Stop
Policy - Graceful shutdown configuration for yubaba’s stop sequence.
- Tenant
Id - Tenant isolation axis (W206). Separates one operator’s workloads from
another’s at the network / DB / mesh-identity level. Orthogonal to
NamespaceId(routing/naming) andTierTag(workload class within a(tenant, namespace)pair). - TierTag
- Tier classification that governs admission control and mesh
allow_fromfiltering. Known values:"public","tenant","private","infra". Custom tiers are allowed per cluster; shape validation warns on unknowns rather than rejecting them (R090-F2). - Transform
Spec - Optional transform applied after a
FetchSourcedownload, lowering to aForgeCommand::Subprocessvia the recipe loader (R438-T4). The transform’s output is content-addressed by the entry’sblake3(the recipe runs only when the cache misses). - Volume
Mount - A volume mount inside the container.
- Workload
Spec - Complete typed description of a containerd workload handed to yubaba over
RPC. This is also the payload of the
kind = "container"variant ofWorkloadon disk.
Enums§
- Almanac
Target - An observable endpoint the almanac scheduler probes to check readiness.
- Build
Mode - Where the build command runs for a
mesofact-staticworkload. - Bundle
Lifecycle - Lifecycle mode for a served bundle (W272 §3).
- Cadence
- When the almanac scheduler triggers a run.
- EnvValue
- Value source for an environment variable.
- Health
Probe - Mechanism used to check container health.
- License
- Closed-set, parse-time-enforced license tag. Mirrors the workspace
permissive-license rule (MIT / Apache-2.0 / BSD-2/3-Clause / ISC). Adding a
variant is an explicit schema change — non-permissive strings
(
"GPL-3.0","AGPL", etc.) fail at serde-deserialize before any shape validator runs. - Lifecycle
Archetype - Explicit lifecycle archetype for a
kind = "container"workload (W244). - Mesh
Lookup - Which aspect of a mesh peer’s address to inject.
- Mesh
Peer - A peer permitted to initiate mesh connections to a workload (W206 / R558-F3).
- NotReady
Policy - What the almanac scheduler does when a precondition check fails.
- Public
Tls - TLS mode for a public endpoint.
- Restart
Policy - What yubaba does when the container exits.
- Schema
Version - Wire-format schema version envelope.
- Secret
Ref - Where yubaba resolves the secret value from.
- Secret
Target - How the secret is surfaced inside the container.
- Volume
Source - Backing source for a volume mount.
- Workload
- On-disk
workload.tomlmanifest. Each variant matches oneServiceComponent.kindvalue; thekindfield on the wire is the serde discriminator.
Constants§
- DEFAULT_
NAMESPACE - Default single-namespace identity for specs that predate the namespace
axis (W206). See
NamespaceId::singleton. - DEFAULT_
TENANT - Default single-tenant identity written to specs that predate the tenant
axis (W206). Its concrete string is arbitrary — what matters is that a
single-tenant cluster only ever sees this one value, so every per-tenant
isolation primitive collapses to a no-op. See
TenantId::singleton. - HOST_
NETWORK_ ANNOTATION - Annotation key requesting a workload share the host network namespace.
See
WorkloadSpec::wants_host_network. - HOST_
NETWORK_ VALUE - Annotation value (for
HOST_NETWORK_ANNOTATION) selecting host networking. Any other value leaves the workload in an isolated netns. - PUBLIC_
IP_ TAINT - Taint name (for
REQUIRES_TAINT_ANNOTATION) identifying machines with a publicly-routable IP — the W267 sovereign-ingress placement requirement. The corresponding taint field on the machine TOML doesn’t exist yet (R572-F3); this constant is the agreed-upon name both sides will use once it does. - REQUIRES_
TAINT_ ANNOTATION - Annotation key declaring that a workload must land only on a node
carrying a specific taint. See
WorkloadSpec::requires_taint.
Traits§
- Workload
Runtime - Shared interface for deploying and managing
WorkloadSpeccontainers.
Functions§
- intra_
tenant_ address - The name by which a workload is addressed within its own tenant (W206 /
R558-F3), given every
(namespace, identity)pair present in that tenant.