Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/rulesets/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# FlareDispatch required checks

`contextful-gate.proposed.json` is a disabled repository ruleset for `main`. It requires the `flare-dispatch/contextful-gate` parent and the 24 child contexts returned by `contextful-ci stages --parts`; the parent covers fanout and join failures, and a missing child blocks merge.
`contextful-gate.proposed.json` is a disabled repository ruleset for `main`. It requires the `flare-dispatch/contextful-gate` parent and the 29 static child contexts returned by `contextful-ci stages --parts`; per-package `test-first.<package>` children vary by change and stay outside the static list; the parent covers fanout and join failures, and a missing child blocks merge.

The list is static while the CLI stage list is derived from the repository. A change to `contextful-ci stages --parts` requires the same change to the proposed ruleset before enforcement. The corpus states the remote obligation in `assurance.gate.remote-check`; local pins prove only CLI behavior, while FlareDispatch owns the webhook and check-run implementation.

The proposal carries `enforcement: disabled` and no `integration_id`. [GitHub's required-check rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-status-checks-to-pass-before-merging) admit a specific GitHub App as the expected source after its checks exist. The active ruleset requires all 24 contexts to report terminal conclusions on a fresh pull-request head and the operator's App ID in each required context; that tenant-specific ID stays outside the repository.
The proposal carries `enforcement: disabled` and no `integration_id`. [GitHub's required-check rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-status-checks-to-pass-before-merging) admit a specific GitHub App as the expected source after its checks exist. The active ruleset requires all 29 static contexts to report terminal conclusions on a fresh pull-request head and the operator's App ID in each required context; that tenant-specific ID stays outside the repository.
7 changes: 6 additions & 1 deletion .github/rulesets/contextful-gate.proposed.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@
{ "context": "flare-dispatch/check:pins" },
{ "context": "flare-dispatch/check:toolchain" },
{ "context": "flare-dispatch/check:schema" },
{ "context": "flare-dispatch/check:test-first" },
{ "context": "flare-dispatch/check:test-first.validate" },
{ "context": "flare-dispatch/check:workspace.compile" },
{ "context": "flare-dispatch/check:workspace.cli" },
{ "context": "flare-dispatch/check:workspace.cli-formal" },
{ "context": "flare-dispatch/check:workspace.foundation" },
{ "context": "flare-dispatch/check:workspace.runtime" },
{ "context": "flare-dispatch/check:workspace.read" },
Expand All @@ -29,9 +30,13 @@
{ "context": "flare-dispatch/check:evaluate" },
{ "context": "flare-dispatch/check:features.packages" },
{ "context": "flare-dispatch/check:features.binary-none" },
{ "context": "flare-dispatch/check:features.formal-none" },
{ "context": "flare-dispatch/check:features.binary-all" },
{ "context": "flare-dispatch/check:features.formal-all" },
{ "context": "flare-dispatch/check:features.binary-data-plane" },
{ "context": "flare-dispatch/check:features.formal-data-plane" },
{ "context": "flare-dispatch/check:features.binary-contextful-edge" },
{ "context": "flare-dispatch/check:features.formal-contextful-edge" },
{ "context": "flare-dispatch/check:crate-graph" },
{ "context": "flare-dispatch/check:connectors" },
{ "context": "flare-dispatch/check:surfaces" },
Expand Down
20 changes: 12 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,21 +121,25 @@ The gate measures commits, so commit before running it.

The FlareDispatch GitHub App dispatches `contextful-ci gate` from same-repository
pull-request heads. Its `contextful-gate` run publishes the
`flare-dispatch/contextful-gate` parent and 24 child check-runs:
`flare-dispatch/check:<stage>` for each of `pins`, `toolchain`, `schema`, `test-first`,
`flare-dispatch/contextful-gate` parent, 29 static child check-runs, and one
test-first child per changed source package:
`flare-dispatch/check:<stage>` for each of `pins`, `toolchain`, `schema`,
`workspace`, `acceptance`, `evaluate`, `features`, `crate-graph`, `connectors`,
`surfaces`, `formal` and `budget`. The features and budget stages dispatch one check per
part, `flare-dispatch/check:features.<part>` and `flare-dispatch/check:budget.<profile>`, so
each fits the sandbox's wall clock; `contextful-ci stages --parts` prints the list, and
`surfaces`, `formal` and `budget`. The test-first, features and budget stages dispatch one check per
part, `flare-dispatch/check:test-first.validate` and `flare-dispatch/check:test-first.<package>`, `flare-dispatch/check:features.<part>` and `flare-dispatch/check:budget.<profile>`, so
each fits the sandbox's wall clock; `contextful-ci stages --parts --base <rev>` prints the list, and
`--stage <stage>.<part>` runs one part. A selected subset runs in that order and refuses a
stage whose predecessor's output is absent; `--predecessors` runs those too. A local run and
the remote check invoke the identical command. `contextful-ci`'s suite asserts 24
dispatchable parts. FlareDispatch runs `contextful-measures` nightly against the default
the remote check invoke the identical command. `contextful-ci`'s suite asserts 29
static dispatchable parts. FlareDispatch runs `contextful-measures` nightly against the default
branch and attaches its report to `refs/notes/measures`. A `v*` tag starts
`contextful-release`, with `contextful-release-cell` for the ten cells in
`contextful-ci release --plan`, `contextful-release-formula` for formulae and
SHA256SUMS, and three independently tagged container images. The disabled
ruleset proposal under `.github/rulesets/` lists the parent and all 24 children.
ruleset proposal under `.github/rulesets/` lists the parent and all 29 static children.

The CLI differential module runs in `workspace.cli-formal` and `features.formal-<set>`;
`workspace.cli` and `features.binary-<set>` run the remaining CLI tests.

### Landing without a remote verdict

Expand Down
10 changes: 6 additions & 4 deletions spec/81-engineering.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Target directories, the engine-linked invocation, linked query functions, build
*because every engine-linked test binary embeds the bundled engine, and full debug information multiplies each past a sandbox's disk*
- `release-profile` — Release builds compile with thin link-time optimization, one codegen unit per crate and symbols stripped, and unwind on panic.
*because the run keeper survives a panicking job only by unwinding to its guard*
- `profile-build` — The features stage tests each package under every feature set its manifest lists in `feature-runs`, in parts dispatched as one check each: the other packages, and each binary run — none, all and each listed set.
- `profile-build` — The features stage tests each package under every feature set its manifest lists in `feature-runs`: other packages share one check; each binary feature run has separate checks for differential tests and all remaining tests.
*because one cold build of the binary under one feature set fills most of a stage's wall clock, and a listed set reaches what none and all miss*
- `container-image` — The repository's `Dockerfile` builds one profile, `contextful-full` unless `PROFILE` names another, as a static `linux/amd64` binary, and ships it in a shell-free runtime image as a non-root user over a declared store volume.
- `targets` — All three profiles cross-compile to `x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl`; edge and full also build for `aarch64-apple-darwin` and `x86_64-apple-darwin`.
Expand Down Expand Up @@ -184,15 +184,17 @@ Stage order, secrets of record, the crate-graph, row-token, egress and dependenc
- `stage-sequence` — The gate runs its stages in order — pins, toolchain, schema, test-first, workspace, acceptance, evaluate, features, crate graph, connectors, TypeScript surfaces, formal, budget — and a subset is selectable by name.
- `stage-subset` — A 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.
*A-assurance*
- `remote-check` — The FlareDispatch pull-request webhook dispatches every part from `contextful-ci stages --parts`, each as `flare-dispatch/check:<part>` on the head commit.
- `remote-check` — The FlareDispatch pull-request webhook dispatches every part from `contextful-ci stages --parts --base <base-sha>`, each as `flare-dispatch/check:<part>` on the head commit.
*A-assurance*
- `windows-checks` — Windows native checks run only as optional diagnostics and contribute no required merge or release verdict.
*A-assurance*
- `workspace-parts` — Remote workspace checks compile the feature-unified workspace without running tests, run the CLI suite in its own check, and run each other non-acceptance package suite in exactly one of four groups.
- `test-first-parts` — Remote validation requires a changed test in each changed source package under {{assurance.test.test-first}}; each changed source package checks only its own changed tests against the base in a separate dispatch.
*because one base build per package fits the sandbox's wall clock more reliably*
- `workspace-parts` — Remote workspace checks compile the feature-unified workspace without running tests, run differential and remaining CLI tests separately, and run each other non-acceptance package suite in exactly one of four groups.
*A-assurance*
- `remote-predecessors` — Each dispatched part invokes `contextful-ci gate --predecessors --stage <part> --base <base-sha>`, so no check reads another check's sandbox.
*A-assurance*
- `fork-dispatch` — FlareDispatch dispatches only a pull-request head pushed to this repository; a fork receives none of the 24 required stage checks.
- `fork-dispatch` — FlareDispatch dispatches only a pull-request head pushed to this repository; a fork receives none of the required stage checks.
*because a dispatch runs untrusted code in the organization's compute account, and absent required checks fail closed*
- `stage-reports` — Each 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.
*because memory exhaustion is silent, and a kill then reads as a number in the log*
Expand Down
6 changes: 3 additions & 3 deletions spec/adr/A-assurance.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,16 +144,16 @@ Revisit: an external consumer needs a compatibility promise on a public surface,

Context: the feature-unified workspace suite exceeds the 1800 s sandbox cap on a cold remote build. Criteria: every package suite runs, the feature union compiles, and each dispatched command runs locally too.

Decision: `assurance.gate.workspace-parts` dispatches one compile part over the full union and runs the CLI suite from its compiled artifacts. Four other parts partition the remaining non-acceptance package suites. The unsplit local workspace stage retains its one cargo invocation under `assurance.build.one-engine-build`.
Decision: `assurance.gate.workspace-parts` compiles the full union without execution and runs differential and remaining CLI tests in separate checks. Four other parts partition the remaining non-acceptance package suites. Binary feature checks use the same test partition. The unsplit local workspace stage retains its one cargo invocation under `assurance.build.one-engine-build`.

| Option | Lost on | Cost |
| --- | --- | --- |
| One union compile with CLI suite and four other suite groups *(chosen)* | — | Remote sandboxes rebuild shared dependencies; five checks replace one. |
| One union compile, two CLI partitions and four other suite groups *(chosen)* | — | Remote sandboxes rebuild shared dependencies; seven workspace checks replace one. |
| A lock-keyed shared build cache | Operability | A cache bucket and credential become part of the gate; a cold lock still exceeds the cap. |
| One check for the full workspace | Stage wall clock | A cold sandbox times out before it reports a verdict. |
| A higher step timeout | Platform limit | Workflow steps admit at most 30 minutes. |

Consequences: the five remote checks cover the same package set as the unsplit local stage. The compile part reuses CLI artifacts before its sandbox exits; other parts compile their dependencies independently.
Consequences: seven remote workspace checks cover the same package set as the unsplit local stage. Every binary feature set retains all tests across its two checks. Each CLI partition compiles independently; reference-program builds occupy only the differential partition.

## One decision module compiles native and to WebAssembly

Expand Down
2 changes: 1 addition & 1 deletion spec/cards/assurance.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Generated by `contextful-spec state` from the contract's files and `spec/terms/a
| `automate` | Typed subcommands over compiled binaries, and the boundary shell keeps. | 5 |
| `test` | Assertion construction, guard validation, suite placement, test-first and acceptance tests, and the connector test kit. | 16 |
| `build` | Target directories, the engine-linked invocation, linked query functions, build targets, release artifacts and the dependency allowlist. | 20 |
| `gate` | Stage order, secrets of record, the crate-graph, row-token, egress and dependency rules, the formal stage, the container's ceilings, disk, footprint budgets and surface checks. | 39 |
| `gate` | Stage order, secrets of record, the crate-graph, row-token, egress and dependency rules, the formal stage, the container's ceilings, disk, footprint budgets and surface checks. | 40 |
| `evaluate` | The read-path quality harness: case format, deterministic metrics and floors, judged dimensions, the reader and the judge. | 29 |
| `baseline` | Holding a run against committed baselines and absolute floors, intervals, golden custody and case generation. | 23 |
| `measure` | The target ledger: each tracked target, the clause it serves, how it is measured and its record per commit. | 18 |
Expand Down
Loading