Docs / Specification

contract assurance · 80-formal.md · 81-engineering.md · 82-consumer.md · 83-gate.md · guide · card

The gate and the release tag

How contextful-ci checks a change and cuts a release: typed subcommands, the gate’s stages in run order, its parts, folds and shards, its build jobs and footprint budgets, the target ledger the evaluate stage reads, and the signed release tag with the local packaging that follows it. Each operation keeps its assurance clause ids.

automate

Typed subcommands over compiled binaries, and the boundary shell keeps.

• typed-subcommandtestAn automation step carrying a branch, a loop or a retry, or running past 5 lines, is a typed subcommand shelling out to compiled binaries.
  Why

  P7
• subcommand-surfacetestA subcommand exposes typed options, generated help and an entry point a test calls directly.
• one-pathtestThe gate invokes the subcommand a contributor invokes.
  Why

  because a local reproduction and a gate run then execute one code path
• unchecked-shelltestA shell file in the tree that shellcheck rejects raises ShellCheckFailed in the toolchain stage.
  Why

  P7
• test-shellchecktestA gate stage starting a test process over a tree tracking a shell file puts the shellcheck unchecked-shellassurance.automate.unchecked-shellA shell file in the tree that shellcheck rejects raises ShellCheckFailed in the toolchain stage. runs first on that process’s PATH.
  Why

  because a suite asserting a script passes shellcheck otherwise depends on whether the sandbox image ships the linter
• build-time-toolchaintestThe automation toolchain links into no build profile and enters no release artifact.

gate

Stage order, secrets of record, the crate-graph, row-token, egress and dependency rules, the formal stage, build jobs, free disk, footprint budgets and surface checks.

• stage-sequencetestThe gate runs its stages in order — pins, toolchain, schema, test-first, workspace, acceptance, evaluate, features, crate graph, connectors, TypeScript surfaces, formal, unwired, budget — all of both tiers when none is named, else the named subset, which --plan prints.
  Why

  A-assurance#stage-subset-runs
• nightly-tiertestcontextful-ci stages --parts --tier nightly prints the features, formal, unwired and budget parts in run order; stages --parts prints the remaining parts, those a change runs before merge, and gate --stage runs a part of either tier.
  Why

  A-assurance#feature-runs-formal
• stage-subsettestA selected subset runs in the sequence’s order; a stage reading an unselected predecessor’s output, with that output absent, raises StagePredecessorMissing, naming both stages, before any stage runs.
  Why

  A-assurance#stage-subset-runs
• test-first-partstestThe test-first parts require a changed test in each changed source package under test-firstassurance.test.test-firstA change altering Rust source under crates/ or tools/ adds or alters a test under a package's tests/ that fails against the base commit's source; a change without one raises TestNotFirst.; each changed source package’s part checks only its own changed tests against the base.
  Why

  because one base build per package fits the sandbox’s wall clock more reliably
• workspace-partstestThe workspace parts compile the feature-unified workspace untested, run differential CLI tests apart and remaining CLI tests in eight shards under cli-shard-mapassurance.gate.cli-shard-maptools/ci/cli-shards.toml assigns each remaining CLI test, a nested-build group whole, one shard by recorded duration within 9 min per shard; an unmapped test, reported as drift, joins its group or the least-loaded shard, which adds unit tests and doctests., and each other non-acceptance package suite in one of four groups.
  Why

  A-assurance#workspace-fits-stage
• cli-shard-maptesttools/ci/cli-shards.toml assigns each remaining CLI test, a nested-build group whole, one shard by recorded duration within 9 min per shard; an unmapped test, reported as drift, joins its group or the least-loaded shard, which adds unit tests and doctests.
  Why

  A-assurance#workspace-fits-stage
• folded-partsteststages --parts folds pins, toolchain, schema and test-first validation into preflight; each package group’s workspace and evaluate parts into suite.<group>, probes into suite.ci; crate graph, connectors and surfaces into perimeter; members stay runnable alone.
  Why

  because every part pays its own sandbox setup and compile, and a fold pays it once for every member
• compile-onlytestgate --stage <part> --compile-only runs each cargo test invocation the part runs, in its own target directory with --no-run and without its -- arguments, and nothing else; a CLI shard compiles every shard’s invocations.
  Why

  because a compile cache serves a part only when the warming build’s cargo arguments, environment and target directory match the part’s
• compile-groupsteststages --parts --compile-groups lists, in run order, the first part of each distinct compile signature — its ordered --compile-only invocations and target directory — across both tiers unless --tier names one.
  Why

  because the eight CLI shards share one signature, and warming each compiles it eight times
• fold-verdictstestA fold runs each member after an earlier member fails, skips a member reading a failed member’s output, and fails when any member fails.
  Why

  because one fold check replaces a check per member, and one run reports every member’s verdict
• stage-reportstestEach stage prints the environment it leaves and its memory limit, peak and event counts, and a failing stage prints its diagnostics before propagating its exit code.
  Why

  because memory exhaustion is silent, and a kill then reads as a number in the log
• pins-stagetestThe pins stage resolves every pinned artifact identity a run depends on before any compilation.
• evaluate-stagetestThe evaluate stage runs every gate-tier ledger entry and the native case set in the deterministic tier, one part per package group plus a probe part, each reporting the floor and baseline verdicts over its entries.
• schema-stagetestThe schema stage regenerates each derived artifact into a scratch location, compares it byte for byte against the committed copy, and runs contextful-spec lint.
• secret-ciphertexttestIn the schema stage, a key other than DOTENV_PUBLIC_KEY* in a git-tracked .env* file other than .env.example holding a value without the encrypted: prefix, or a tracked .env.keys, raises SecretPlaintext, naming file and key.
  Why

  because a tracked file reaches every clone, and only dotenvx ciphertext is safe there while its private key stays untracked
• secret-scopetestIn the schema stage, a key other than DOTENV_PUBLIC_KEY* in a git-tracked .env* file whose block — the assignments above it, up to the first blank line — opens with no comment carrying text raises SecretScopeMissing, naming file and key.
  Why

  because a provider token cannot report its own grants, so the comment above it is the one record of what it reaches
• formal-stagetestThe nightly formal stage runs check-commandassurance.audit-assumptions.check-commandcontextful formal check elaborates the package, matches every inventory row, audits every footprint, writes the report, and exits non-zero naming the first failing constant., commandassurance.differential-test.commandcontextful formal differential --seed <n> --cases <n> replays the corpus, then runs the generated cases, exiting non-zero on the first disagreement., protocol-checkassurance.model.protocol-checkThe gate evaluates every invariant on each state reached by every step sequence over three nodes and four lease generations; a breaking state raises ProtocolInvariantViolated, printing the shortest sequence reaching it., the protocol differential over 10000 generated cases on both lease paths, and journal-checkassurance.model.journal-checkprotocol journal check evaluates every journal property on each state three callers reach on one key; a breaking state raises JournalInvariantViolated, printing the shortest sequence reaching it.; a non-zero exit from any reds the run.
  Why

  P7
• typescript-surfacestestThe TypeScript surfaces run each declared typecheck, test and build script in one stage; an absent script skips only that script.
• native-test-filestestThe surfaces stage runs every regular native .test.ts file under a direct TypeScript surface’s test/ or tests/ tree through Node’s TypeScript strip runner, and refuses absent passing tests or pinned names.
  Why

  because a package script can omit a pinned test while reporting success
• surface-check-failedtestA surface whose typecheck, unit tests or framework build fails raises SurfaceCheckFailed, naming the surface and the script.
  Why

  P7

affected parts

stages --affected maps a diff to the parts it reaches.

• affected-partstestcontextful-ci stages --parts --base <rev> --affected lists, in run order, the parts of the selected tier the diff from the merge base of <rev> and HEAD reaches, the required tier always including preflight.
  Why

  A-assurance#pull-request-runs
• affected-everytestA change to Cargo.toml, Cargo.lock, a toolchain file, anything under crates/, tools/ or .github/, or any path no other affected clause maps reaches every part of either tier.
  Why

  A-assurance#pull-request-runs
• affected-spectestA change under spec/ or references/ reaches test-first validation, one under spec/ the foundation workspace part, and each clause whose statement or spec/pins.toml entry changed the parts running its pinned test or theorem.
  Why

  A-assurance#pull-request-runs
• affected-spec-inputstestA change to spec/01-topology.md or spec/capabilities.toml reaches crate-graph, to spec/adr/A-assurance.md the formal stage, and to spec/terms/assurance.toml every budget part.
  Why

  because those stages read the file directly, apart from any clause pin
• affected-removedtestA clause the merge base’s lock holds and HEAD’s lacks reaches the evaluate stage.
  Why

  because the evaluate stage refuses a ledger entry naming a clause the lock lacks
• affected-unplacedtestAn unreadable spec lock or pins file, or a changed clause pinned outside every workspace package, reaches every required part.
  Why

  because a pin the listing cannot place runs on a part the listing cannot name
• affected-surfacestestA change under apps/ or packages/ reaches the TypeScript surfaces, acceptance and crate-graph parts.
  Why

  A-assurance#pull-request-runs
• affected-formaltestA change under formal/ other than a lean-toolchain file reaches the formal and evaluate stages, the foundation, CLI and CLI differential workspace parts, and every feature part.
  Why

  A-assurance#pull-request-runs

dependency rules

The crate-graph stage holds the dependency graph and runtime source to their rules.

• crate-graphtestThe crate-graph stage holds run-path crates to reaching read-path crates through the three crossing crates alone; another edge raises CrateGraphViolation, naming both crates.
  Why

  P5
• locked-resolvetestThe crate-graph stage resolves every graph --locked against the committed Cargo.lock, so a lock behind its manifests, or one rewritten before the stage starts, fails the stage before any rule runs; the stage never rewrites it.
  Why

  because a rule held over a graph the lock file does not record passes a build that resolves another
• row-tokentestEvery row-returning function of the store crate takes the enforcement token type, whose constructor is private to the enforcement module; a row path outside a registered relation raises EnforceUnmediatedPath, naming the function.
  Why

  P5
• dependency-denytestThe crate-graph stage runs pinned cargo-deny check bans over each profile’s resolved graph, denying every crate a profile-wide dependency refusal names; a hit raises that refusal’s error, naming the profile and the path.
  Why

  A-assurance#profile-graphs-answer
• deny-profile-graphtestA profile’s graph is the binary resolved with default features off and the profile’s feature on, across every target, excluding development dependencies; the stage prints each profile the binary declares no feature for.
  Why

  A-assurance#profile-graphs-answer
• deny-listtestdeny.toml holds one [bans] entry per crate or feature a profile-wide dependency refusal names, its reason that refusal’s clause id; an entry missing or extra raises DenyListDrift, naming it.
  Why

  because a refusal whose crate the list omits passes every profile graph linking it
• unconfigured-egresstestAn outbound call reachable under the default configuration — usage ping, license check, update probe — raises UnconfiguredEgress in the crate-graph stage, naming the call site.
  Why

  because some deployments run with no external reach, and a call nobody configured moves data outside every grant, zone and audit record
• interpolated-claimtestA source lint over the runtime crates finding a subject claim formatted into SQL text raises EnforceInterpolatedSubjectClaim, naming the file and line.
  Why

  P1

footprint

Build resources and each profile’s artifact size stay within their bounds.

• parallel-jobstestA footprint build’s parallel job count is its build memory — the cgroup memory ceiling, else the physical or container-engine memory — divided by 3 GiB, at least one and at most the processor count.
  Why

  because one optimized C++ unit of the SQL engine peaks near 3 GiB
• free-disktestA stage starting with less than 2 GiB of free disk raises BuildDiskPrecondition and exits 28 before doing work.
  Why

  P7
• edge-budgettestThe edge profile compresses to at most 50 MiB.
• full-budgettestThe full profile compresses to at most 150 MiB.
• control-budgettestThe control profile compresses to at most 60 MiB.
• footprinttestPer nightly run and per profile, the footprint step builds the static-linked Linux target, compresses it, and holds its size to the profile’s budget and its dynamic dependencies to the platform C library.
  Why

  P7
• budget-stagetestThe budget stage runs footprintassurance.gate.footprintPer nightly run and per profile, the footprint step builds the static-linked Linux target, compresses it, and holds its size to the profile's budget and its dynamic dependencies to the platform C library. over every profile, in one nightly-tier part per profile, and the evaluate stage builds no profile.
  Why

  because one link-time-optimized release build of the full profile fills most of one stage’s wall clock
• footprint-exceededtestAn artifact over its profile’s budget, or carrying a dynamic dependency beyond the platform C library, raises FootprintBudgetExceeded, naming the profile.
  Why

  P7

unsettled: Which workload, cadence and drift bound does the idle-resident soak run under, given that a multi-day soak fits no per-change gate? owner: build affects: assurance.gate

unsettled: Which cache hit rate holds test-first and workspace under the per-stage wall clock once the Cargo.lock-keyed build cache serves the gate container (issue 31)? owner: build affects: assurance.gate

measure

The target ledger: each tracked target, the clause it serves, how it is measured and its record per commit.

• ledgertesttestevals/ledger.toml holds one entry per tracked target: an id, an owning clause id, a run-report metric path, a tier, a method naming one integration test, bench target, case set or probe, and a threshold.
• unresolved-entrytestAn entry whose owning clause, method or metric path resolves to nothing raises MeasureEntryUnresolved before any measure runs.
  Why

  P7
• open-entrytestAn entry naming an issue in place of a method reports open and gates nothing, and evals/ledger.md carries every entry’s computed status.
• tiertestA gate-tier entry decides the evaluate stage, a trend-tier entry decides nothing, and contextful-ci measure runs the gate tier alone unless --tier names trend, scheduled or all.
• judged-tiertestAn entry whose metric names a judged figure is scheduled-tier; on another tier it resolves to nothing under unresolved-entryassurance.measure.unresolved-entryAn entry whose owning clause, method or metric path resolves to nothing raises MeasureEntryUnresolved before any measure runs..
  Why

  because a judged figure costs a model call per item and moves with the judge, not with the change
• count-firsttestA gate-tier entry measures a count, a ratio within one run or a size under a locked resolve; a wall-clock or resident-memory figure is trend-tier.
  Why

  because a shared container moves wall-clock figures past any band narrow enough to catch a regression
• recordtestA measure writes one JSON record carrying its entry id, value, sample count, seed and run stamp; a gate-tier method finishing without one raises MeasureRecordMissing.
  Why

  P7
• seededtestEvery generated fixture and randomized schedule derives from the record’s seed, and replaying that seed reproduces a count-valued entry’s value.
  Why

  because a failure that cannot replay cannot be fixed
• seed-mismatchtestA gate or scheduled record whose seed differs from its entry’s declared seed raises MeasureSeedMismatch and counts as red; a trend mismatch leaves no comparable record.
  Why

  because a figure measured under another seed replays nothing the ledger names
• timing-iterationstestA timed batch reports p50 and p95 over 200 repeats of its operation, each after warm-up.
• timing-batchestestA timed figure is the median of 5 repeats of its timed batch.
• trend-directiontestEach trend-tier ledger entry declares higher_is_better or lower_is_better for its metric.
  Why

  A-assurance#tracked-targets-gate
• trend-baselinetestA trend figure compares with the newest earlier successful default-branch report for the same entry and seed under runner-stampassurance.measure.runner-stampThe run block carries the runner's processor model, processor count and memory limit, and a trend figure compares only against a baseline with the same stamp.; absent matching history yields no annotation.
  Why

  A-assurance#tracked-targets-gate
• trend-bandtestA trend figure more than 25 percent worse than its baseline annotates the run report and fails no stage.
• runner-stamptestThe run block carries the runner’s processor model, processor count and memory limit, and a trend figure compares only against a baseline with the same stamp.
• absolute-thresholdtestA threshold is an absolute figure of this system’s own measure, and it tightens only through raise-onlyassurance.baseline.raise-onlyA baseline update runs after every gate and floor passes, moves each improved entry to its measured value, moves none in the worse direction, and adds no path..
• threshold-costtestA gate-tier target that rises under <=, falls under >= or moves under == carries a # cost: comment above its entry that its entry at <rev> lacks, or contextful-ci measure --since <rev> raises MeasureThresholdLoosened.
  Why

  because a loosened gate otherwise reads as a changed number, and the cost it accepts goes unrecorded
• historytestA run on the default branch attaches its run report to the measured commit under refs/notes/measures, and no verdict reads a note.
  Why

  A-assurance#tracked-targets-gate
• run-reporttestcontextful-ci measure-report writes the note line — commit, run id, attempt, exit code, records and trend annotations — with an integer run id, and reads back every earlier note whatever its run id’s JSON type.
  Why

  because earlier notes on refs/notes/measures carry text run ids, and an unreadable note hides every older baseline
• measured-basistestA bound with a measured basis names a trend-tier or scheduled-tier ledger entry id as its benchmark.

Scenarios

• assurance.measure.unresolved-entryassurance.measure.unresolved-entryAn entry whose owning clause, method or metric path resolves to nothing raises MeasureEntryUnresolved before any measure runs.: WHEN an entry names run.journal.entry-keys, THEN the run raises MeasureEntryUnresolvedassurance.measure.unresolved-entryAn entry whose owning clause, method or metric path resolves to nothing raises MeasureEntryUnresolved before any measure runs. and no test runs.
• assurance.measure.trend-bandassurance.measure.trend-bandA trend figure more than 25 percent worse than its baseline annotates the run report and fails no stage.: WHEN a trend p95 moves from 40 ms to 52 ms on a matching runner stamp, THEN the report carries a +30 percent annotation and the stage passes.
• assurance.measure.trend-baselineassurance.measure.trend-baselineA trend figure compares with the newest earlier successful default-branch report for the same entry and seed under runner-stamp; absent matching history yields no annotation.: WHEN a newer failed report follows two successful matches, THEN the trend compares with the newer successful match and the stage passes.
• assurance.measure.run-reportassurance.measure.run-reportcontextful-ci measure-report writes the note line — commit, run id, attempt, exit code, records and trend annotations — with an integer run id, and reads back every earlier note whatever its run id's JSON type.: WHEN the baseline note’s run id is the text contextful-measures_2026-10-14 and the run’s is 42, THEN the report writes 42 and its annotation names that text run id as its baseline.
• assurance.measure.open-entryassurance.measure.open-entryAn entry naming an issue in place of a method reports open and gates nothing, and evals/ledger.md carries every entry's computed status.: WHEN an entry’s method is { issue = 43 }, THEN evals/ledger.md lists it open and the evaluate stage ignores it.

release

The release tag’s version, the refusals guarding it, the signed annotated tag contextful-ci tag creates, and the local packaging the operator runs from it.

• versiontesttestA release tag is v0.<minor>.<patch>: <minor> counts the milestones computing closed in the tagged commit’s spec/status.md plus each store format major and each manifest format past 1, and <patch> counts the existing tags v0.<minor>.*.
  Why

  A-assurance#store-format-major
• store-formattestA commit’s store format is the FormatVersion::CURRENT constant in its crates/contextful-core/src/store/lay_out.rs, and 1.0 where that constant is absent; a constant that does not parse raises TagStoreFormatUnread.
  Why

  A-assurance#store-format-major
• manifest-formattestA commit’s manifest format is the MANIFEST_FORMAT constant in its crates/contextful-core/src/store/sync.rs, and 1 where that constant is absent; a constant that does not parse as an integer raises TagManifestFormatUnread.
  Why

  A-assurance#store-format-major
• annotatedtestcontextful-ci tag creates a signed annotated tag on HEAD naming the closed milestones once every refusal of this operation clears, and never moves or replaces an existing tag.
  Why

  A-assurance#version-tag-names
• dirty-treetestA working tree or index differing from HEAD raises TagTreeDirty.
  Why

  because the gate then judges files the tagged commit does not hold
• off-branchtestA HEAD unreachable from the default branch, origin/HEAD unless --branch names another, raises TagOffDefaultBranch.
  Why

  A-assurance#version-tag-names
• version-regressedtestA computed version below the highest existing v<major>.<minor>.<patch> tag raises TagVersionRegressed, naming both.
  Why

  A-assurance#store-format-major
• format-break-patchtesttestA computed <minor> equal to the highest existing tag’s, while HEAD’s store format major or manifest format differs from that tag’s, raises TagFormatBreakPatch, naming both formats.
  Why

  A-assurance#store-format-major
• format-notestesttestA tag whose store format major exceeds the highest existing tag’s carries the message line Store format <old> → <new>: upgrade every reader, then every writer together., and one whose manifest format exceeds it the same line opening Manifest format.
  Why

  because an older reader refuses a manifest of the newer major, and an older writer refuses the table once a newer writer commits
• workspace-versiontestA [workspace.package] version in HEAD’s Cargo.toml that is absent or differs from the computed version raises TagWorkspaceVersionMismatch, naming both.
  Why

  A-assurance#version-tag-names
• gate-failedtestOnce the other refusals clear, every gate stage runs against HEAD with HEAD~1 as base; a failing stage raises TagGateFailed, naming the stage’s refusal, and no tag is created.
  Why

  A-assurance#version-tag-names
• release-tag-versiontestcontextful-ci release over a HEAD carrying a v* tag, none of which equals v plus the [workspace.package] version, raises ReleaseTagVersionMismatch, naming both, before any build.
  Why

  because a tag cut without contextful-ci tag otherwise ships binaries reporting another version

Scenarios

• assurance.release.versionassurance.release.versionA release tag is v0.<minor>.<patch>: <minor> counts the milestones computing closed in the tagged commit's spec/status.md plus each store format major and each manifest format past 1, and <patch> counts the existing tags v0.<minor>..: WHEN milestones 0 to 7 and 11 compute closed and v0.9.0 exists, THEN the computed version is v0.9.1.
• assurance.release.version-regressedassurance.release.version-regressedA computed version below the highest existing v<major>.<minor>.<patch> tag raises TagVersionRegressed, naming both.: WHEN milestone 11 reopens after v0.9.0, THEN the computed v0.8.0 raises TagVersionRegressedassurance.release.version-regressedA computed version below the highest existing v<major>.<minor>.<patch> tag raises TagVersionRegressed, naming both..
• assurance.release.store-formatassurance.release.store-formatA commit's store format is the FormatVersion::CURRENT constant in its crates/contextful-core/src/store/lay_out.rs, and 1.0 where that constant is absent; a constant that does not parse raises TagStoreFormatUnread.: WHEN 16 milestones compute closed, v0.16.1 declares store format 1.0 and HEAD declares 2.0, THEN the computed version is v0.17.0 and its message carries Store format 1.0 → 2.0.
• assurance.release.manifest-formatassurance.release.manifest-formatA commit's manifest format is the MANIFEST_FORMAT constant in its crates/contextful-core/src/store/sync.rs, and 1 where that constant is absent; a constant that does not parse as an integer raises TagManifestFormatUnread.: WHEN 16 milestones compute closed under store format 2.0, v0.17.0 declares manifest format 1 and HEAD declares 2, THEN the computed version is v0.18.0 and its message carries Manifest format 1 → 2.
• assurance.release.format-break-patchassurance.release.format-break-patchA computed <minor> equal to the highest existing tag's, while HEAD's store format major or manifest format differs from that tag's, raises TagFormatBreakPatch, naming both formats.: WHEN milestone 11 reopens after v0.9.0 while the store format moves from 1.0 to 2.0, THEN the computed v0.9.1 raises TagFormatBreakPatchassurance.release.format-break-patchA computed <minor> equal to the highest existing tag's, while HEAD's store format major or manifest format differs from that tag's, raises TagFormatBreakPatch, naming both formats..

deploy-apps

The one GitHub Actions workflow, its trigger, permission and credential shape, and contextful-ci deploy cloudflare, the command it and an operator run to ship one Cloudflare app.

• workflow-triggertestThe workflow .github/workflows/deploy-cloudflare.yml, written in YAML’s JSON subset, starts on workflow_dispatch alone, with a required app choice listing every app the deploy command ships and an optional ref string.
  Why

  because a deploy then starts only when an operator names one app, never from a push, a schedule or a pull request
• workflow-permissionstestThe workflow grants contents: read alone, runs one job on the ubuntu-24.04 image, pins each uses to a 40-hex commit of actions/checkout or actions/setup-node, and checks out without persisting credentials.
  Why

  because a tag an action’s owner moves runs unreviewed code beside the deploy token
• workflow-credentialstestThe workflow reads exactly the secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, into its deploy step’s environment, and carries no URL, hostname or run of 32 hex digits outside a pinned commit.
  Why

  because the repository is public, and each organization deploys into its own account
• job-timeouttestThe deploy job’s timeout-minutes is at most 90 min.
  Why

  because a full-profile release build with its conformance pass fits that, and a hung deploy holds the token no longer
• one-commandtestThe workflow’s one run step is contextful-ci deploy cloudflare --app "$APP", the command an operator runs locally with the same two environment variables.
  Why

  because a local deploy and a workflow deploy then execute one code path
• workflow-refusedtestAnother file under .github/workflows, or a deploy workflow breaching workflow-triggerassurance.deploy-apps.workflow-triggerThe workflow .github/workflows/deploy-cloudflare.yml, written in YAML's JSON subset, starts on workflow_dispatch alone, with a required app choice listing every app the deploy command ships and an optional ref string., workflow-permissionsassurance.deploy-apps.workflow-permissionsThe workflow grants contents: read alone, runs one job on the ubuntu-24.04 image, pins each uses to a 40-hex commit of actions/checkout or actions/setup-node, and checks out without persisting credentials., workflow-credentialsassurance.deploy-apps.workflow-credentialsThe workflow reads exactly the secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, into its deploy step's environment, and carries no URL, hostname or run of 32 hex digits outside a pinned commit., job-timeoutassurance.deploy-apps.job-timeoutThe deploy job's timeout-minutes is at most 90 min. or one-commandassurance.deploy-apps.one-commandThe workflow's one run step is contextful-ci deploy cloudflare --app "$APP", the command an operator runs locally with the same two environment variables., raises DeployWorkflowRefused in the schema stage, naming the file and the breach.
  Why

  because the token’s reach then stays reviewable in one file every change is checked against
• credentials-absenttestcontextful-ci deploy cloudflare with CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID unset or empty raises DeployCredentialsAbsent, naming the variable, before any command runs.
  Why

  because wrangler otherwise falls back to an interactive login or a cached account
• resourcestestThe command creates each D1 database and R2 bucket the app’s wrangler.example.jsonc binds when absent, named after the Worker and binding, and writes their identifiers only into the untracked wrangler.deploy.jsonc beside it.
  Why

  because an identifier belongs to one account, and the committed template serves every account
• container-imagetestFor an app declaring a container, the command packages the contextful-full x86_64-unknown-linux-musl release inside the Dockerfile’s pinned Alpine builder and prepares each images build context from that archive before wrangler deploy.
  Why

  because the image then carries the exact binary its release metadata and compatibility report name
• builder-jobstestThe builder compiles with the caller’s CARGO_BUILD_JOBS when set, and otherwise with one job per 1536 MiB of the memory docker info reports, at least one.
  Why

  because one job per CPU in a smaller Docker VM gets the C++ compiler killed during the SQL engine and link-time optimization builds
• worktree-mounttestFrom a git worktree, the builder also mounts the common git directory git rev-parse --git-common-dir names, read-only at its own path.
  Why

  because a worktree’s .git file points outside the source mount, and the release records the source commit
• scheduling-policytestThe execution app’s container declares the durable_object scheduling policy and an images map, and its container class starts each instance with that map’s image and the standard-1 instance type.
  Why

  because an account may refuse the default policy, and the container library passes neither image nor instance type to a Durable Object-managed start
• healthtestAfter wrangler deploy, the command repeats an anonymous GET / to the URL wrangler reports until a status in the app’s expected set arrives or --health-wait elapses, printing each status alone; the wait elapsing raises DeployUnhealthy, naming the last status.
  Why

  because wrangler reports success before the Worker answers, and a fresh workers.dev route answers a redirect first
• expected-statustestThe execution app answers GET / with 404, the gateway with 404 or 503, and the console with 200 or 302.
  Why

  because each answer is the app’s unauthenticated default: no route, no configured store, the prerendered page
• quiet-outputtestThe command prints its step names and the health status; wrangler’s output prints only on failure, with each URL and each run of 32 or more hex digits replaced.
  Why

  because a public repository’s Actions logs are public, and wrangler’s output names the account’s subdomain and resource identifiers