@patronage/factory-ci 1.0.0-alpha.24 → 1.0.0-alpha.26

package/README.md

@@ -6,7 +6,9 @@ The CI and deploy building blocks that already repeat across Patronage **factory
 pnpm add -E @patronage/factory-ci
 ```
 
-It is a **pure library**. There is no `bin`: anything invocable belongs to `psf`. There is no `alchemy` or `effect` dependency of any kind — not a dependency, not a peer dependency — so the package can never pull a second copy of either into a consumer's graph. `esbuild` is its own dependency, which is what lets consumers delete their local arrangements for finding one.
+It is a **pure library**. There is no `bin`: anything invocable belongs to `psf`. `esbuild` is its own dependency, which is what lets consumers delete their local arrangements for finding one.
+
+`alchemy` and `effect` are **optional peer dependencies** (ADR 0031). A peer resolves from the consumer's own installation, so this package still cannot pull a second copy of either into a consumer's graph — and a second copy is the thing that breaks both silently, because Alchemy's resource registry and Effect's service tags are identity-sensitive. The package root imports neither; every Alchemy-importing helper ships from the `@patronage/factory-ci/alchemy` subpath. A consumer that never imports that subpath installs neither package and sees no warning.
 
 ## What it is for
 
@@ -61,22 +63,50 @@ workflow({/* caller-owned jobs and topology */}).writeOrLint({
 });
 ```
 
-The **runner is not this package's business**. Jobs, runners, permissions, workflow topology, and deploy policy remain with the caller. The returned values are plain structural objects; this package does not depend on gagen.
-
-Candidate lifecycle support follows the same boundary. Use `FACTORY_CANDIDATE_PULL_REQUEST_TYPES` for the pull-request trigger matrix and `factoryCandidateOrPushCondition()` on each substantive job. With an optional caller-owned path condition, the helper emits the GitHub expression that runs merge-target pushes unconditionally and runs pull-request work only when GitHub's draft boolean says the pull request is a Candidate:
+`factoryWorkflow()` still does not set `runsOn`. This package does not depend on gagen. Job ids, permissions, topology, and deploy policy stay with the caller. Verify runner kinds are this package's business. Name each job's kind (or an override with a non-empty why), pass `.label` into gagen `job()`, and hand the same table to `assertVerifyRunnerPolicy` next to `assertWorkflowShellParses`:
 
 ```ts
+import {
+  assertVerifyRunnerPolicy,
+  assertWorkflowShellParses,
+  factoryVerifyRunner,
+  type FactoryVerifyRunner,
+} from "@patronage/factory-ci";
+
+type VerifyJobId = "changes" | "core";
+
+const verifyRunners: Record<VerifyJobId, FactoryVerifyRunner> = {
+  changes: factoryVerifyRunner("rounding-tax"),
+  core: factoryVerifyRunner("sustained-compute"),
+};
+
+const runsOnFor = (id: VerifyJobId) => verifyRunners[id].label;
+
 const changes = job("changes", {
   if: factoryCandidateOrPushCondition(),
-  // caller-owned runner, permissions, and steps
+  runsOn: runsOnFor("changes"),
 });
 
 const core = job("core", {
   if: factoryCandidateOrPushCondition("needs.changes.outputs.core == 'true'"),
-  // caller-owned topology
+  runsOn: runsOnFor("core"),
+});
+
+const generated = workflow({ jobs: [changes, core] });
+
+assertWorkflowShellParses(generated.toYamlString(), {
+  source: ".github/workflows/verify.ts",
+});
+assertVerifyRunnerPolicy(generated.toYamlString(), {
+  source: ".github/workflows/verify.ts",
+  jobs: verifyRunners,
 });
 ```
 
+`sustained-compute` and `rounding-tax` both resolve to `depot-ubuntu-24.04`. They stay distinct so a short billed-rounding job cannot be confused with a long compute job in the table. `app-token` resolves to `ubuntu-latest`. `deploy-credentials` also resolves to `ubuntu-latest` and is refused inside `assertVerifyRunnerPolicy`, because a Verify workflow has no Cloudflare production secret. HQ deploy keeps a literal `ubuntu-latest` and never calls this assert.
+
+Candidate lifecycle support follows the same boundary. Use `FACTORY_CANDIDATE_PULL_REQUEST_TYPES` for the pull-request trigger matrix and `factoryCandidateOrPushCondition()` on each substantive job. With an optional caller-owned path condition, the helper emits the GitHub expression that runs merge-target pushes unconditionally and runs pull-request work only when GitHub's draft boolean says the pull request is a Candidate. The runner label still comes from the kind table above.
+
 Migration: upgrade `@patronage/factory-ci`, apply the shared trigger types and job condition in the TypeScript workflow source, then regenerate and commit the emitted YAML. Draft `opened` and `synchronize` events will stop running substantive Verify work. Promotion through `ready_for_review`, later non-draft Candidate events, and merge-target pushes continue to run their applicable battery. A skipped draft run is presentation, not proof.
 
 Production impact support follows the same ownership line. A generated deploy workflow declares only its target names and consumes the returned decision step and fail-open `demandedIf(target, decisionJob)` expressions:
@@ -257,7 +287,10 @@ The audit job is `always()` so a failed destroy still runs the stage-wide check.
 ### Merge-freeze writer job
 
 ```ts
-import { factoryMergeFreezeJob } from "@patronage/factory-ci";
+import {
+  factoryMergeFreezeJob,
+  factoryVerifyRunner,
+} from "@patronage/factory-ci";
 
 const freeze = factoryMergeFreezeJob({
   createGithubAppToken: workflowArtifact.actions.createGithubAppToken,
@@ -272,7 +305,7 @@ const jobs = [
     name: freeze.jobName,
     needs: freeze.needs,
     if: freeze.if,
-    runsOn: "ubuntu-latest",
+    runsOn: factoryVerifyRunner("app-token").label,
     permissions: freeze.permissions,
     timeoutMinutes: 10,
     steps: freeze.steps,
@@ -282,7 +315,7 @@ const jobs = [
 
 A consumer's generated merge-target-push Verify workflow is the only producer of `patronage-factory/merge-freeze` generations (#356, ADR 0016 as amended; #429, #872). A red merge-target Verify completes a generation active, a green one completes it inactive, and `pr:ready` reads the generation on the candidate's own base tip. No command, scheduled job, or second workflow writes that check run; the operator override (`demand:waive --demand merge-freeze`) waives the demand for one candidate and never writes here.
 
-`factoryMergeFreezeJob` owns everything a reader trusts: the check name (`FACTORY_MERGE_FREEZE_CHECK_NAME`), the pinned Patronage Factory App identity, the `actions/create-github-app-token` inputs, the `needs.*.result` fold (`FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION`), the merge-target condition (`FACTORY_MERGE_FREEZE_IF`, built from `FACTORY_MERGE_TARGET_REF_CONDITION`), and the job's least-privilege `permissions` (an empty block: the App installation token carries the check-run write, the job uses no `GITHUB_TOKEN` scope, and it never checks out the repository). The caller owns the runner, the timeout, and the `needs` list.
+`factoryMergeFreezeJob` owns everything a reader trusts: the check name (`FACTORY_MERGE_FREEZE_CHECK_NAME`), the pinned Patronage Factory App identity, the `actions/create-github-app-token` inputs, the `needs.*.result` fold (`FACTORY_MERGE_FREEZE_VERIFY_RESULT_EXPRESSION`), the merge-target condition (`FACTORY_MERGE_FREEZE_IF`, built from `FACTORY_MERGE_TARGET_REF_CONDITION`), and the job's least-privilege `permissions` (an empty block: the App installation token carries the check-run write, the job uses no `GITHUB_TOKEN` scope, and it never checks out the repository). The caller owns the runner kind (`app-token` for the Factory App token), the timeout, and the `needs` list.
 
 That `needs` list is the whole trust input: it must name **every authoritative verification leaf**, because the fold is what decides active or inactive. An empty list is refused — a fold over no needed job always reports success, which would report a merge target nothing verified as green.
 
@@ -479,10 +512,183 @@ The **environment capture is the reason this is shared**. The #640 runner compar
 
 **Everything a repository decides stays with the repository**: worker counts, sample counts, slow-list length, output-path conventions, runner labels, artifact upload, and console output. `onSampleStart` / `onSampleComplete` hand the caller each sample so it can print whatever it prints; this package logs nothing. `stdio` for the Vitest child is the caller's too — `"inherit"` by default, so a caller whose own stdout is structured passes `"ignore"`. A reporting hook is a console, not a control: if `onSampleStart` or `onSampleComplete` throws, the sample still runs and the `VitestProfileError` still wins, and the hook's error surfaces only when the sample was otherwise green. `samples` below one is refused outright — it would resolve green having measured nothing and written no artifact. `now`, `runSample`, and `writeResult` are injectable seams for tests.
 
+### Alchemy subpath
+
+```ts
+import { ALCHEMY_SUBPATH, evaluateStack } from "@patronage/factory-ci/alchemy";
+```
+
+`@patronage/factory-ci/alchemy` is the one place in this package that may import `alchemy` or `effect` (ADR 0031). Its source is `src/alchemy/`, it builds as its own entry, and it is the only subpath — there is no per-module subpath.
+
+Install `alchemy` and `effect` yourself before importing it. The published ranges are `>=2.0.0-beta.63 <3` and `>=4.0.0-beta.98 <5`, the same ones `@patronage/alchemy-d1-state` carries, and both are marked optional so an installation that never touches this surface stays quiet.
+
+The published ranges are wide, but the workspace pins one copy: `alchemy` and `effect` are devDependencies here at the same versions `@patronage/alchemy-d1-state` and `software-factory-hq` pin. Without that pin pnpm resolves the peer range to its newest release for this importer alone, which is a second copy of both in the workspace and a lockfile that no longer installs. `evaluateStack` imports both, so `knip` sees them used.
+
+`ALCHEMY_SUBPATH` is the specifier itself. Stage policy, retained-identity asserts, the lifecycle guards, stack evaluation, and the graph invariants ship here. The Alchemy entry helpers named above (`bundleAlchemyEntry`, `executeAlchemyEntry`) stay on the package root, where they belong: they shell out to the consumer's Alchemy CLI and import neither package.
+
+#### Stage policy
+
+```ts
+import {
+  anyStage,
+  LOCAL_PREVIEW_STAGES,
+  stagePolicy,
+} from "@patronage/factory-ci/alchemy";
+
+const policy = stagePolicy({
+  stacks: [
+    { claims: ["bootstrap"], stack: "bootstrap-stack", stages: ["bootstrap"] },
+    { claims: ["telemetry"], stack: "app" },
+    { stack: "audit", stages: ["staging", "prod"] },
+  ],
+  stages: {
+    disposable: anyStage(/^pr-\d+$/u, LOCAL_PREVIEW_STAGES),
+    protected: ["bootstrap", "dev", "prod", "staging", "telemetry"],
+  },
+});
+
+policy.assertDestructiveStage(stage); // throws on a protected stage
+policy.assertStackOwnsStage(stack, stage);
+```
+
+Two projects wrote the same three questions — is this stage protected, is it disposable, and may this stack run it — and each answered them with its own stage names compiled into the answer. `stagePolicy` takes the table and returns the decisions: `isProtectedStage`, `isDisposableStage`, `isKnownStage`, `assertKnownStage`, `assertDestructiveStage`, and `assertStackOwnsStage`. **No project, stack, or stage name appears in this package.**
+
+A `StageMatcher` is a name list, a `RegExp`, or a predicate — the predicate is how a project expresses a stage set it resolves itself, such as one config file per client. `anyStage(...)` composes matchers, and `LOCAL_PREVIEW_STAGES` is the disposable grammar this package already owns (`isLocalPreviewStage`), offered as a matcher rather than assumed, because a project's disposable set is wider than that one grammar.
+
+Stack ownership runs in two independent directions. `stages` restricts a stack to the stages it may run. `claims` reserves stages for one stack. Declaring the same matcher as both pairs a stack and its stages in both directions; declaring `claims` alone reserves a stage without narrowing the stack that owns it. A declared `stacks` registry is exhaustive, so a mistyped stack is refused rather than passing as unconstrained; omit `stacks` to leave ownership unpoliced.
+
+Refusals are `StagePolicyError` with a stable `code` — `UNKNOWN_STAGE`, `AMBIGUOUS_STAGE`, `PROTECTED_STAGE`, `UNKNOWN_STACK`, `STAGE_NOT_OWNED` — so a project maps them onto its own lifecycle failure envelope instead of matching on message text. A stage a table classifies as both protected and disposable is a table defect: every query on it throws `AMBIGUOUS_STAGE` rather than silently picking a side.
+
+What stays with the project: which environment variable authorizes an attended protected operation, what counts as a trusted hosted context, whether an outstanding state-transfer proof blocks a stack, and the shape of its own failure envelope. Those name credentials, issues, and contexts, and none of them is a stage question.
+
+#### Retained identities
+
+```ts
+import {
+  assertRetainedIdentities,
+  parseStateSnapshot,
+} from "@patronage/factory-ci/alchemy";
+
+const scope = { stack: "loop", stage: "prod" };
+
+assertRetainedIdentities({
+  after: parseStateSnapshot(currentState, scope),
+  before: parseStateSnapshot(recordedState, scope),
+  markers: [
+    {
+      field: "databaseId",
+      fqn: "app-db",
+      resourceType: "Cloudflare.D1Database",
+      section: "attr",
+      value: expectedDatabaseId,
+    },
+  ],
+});
+```
+
+A protected stage's value is the physical resources it already owns. An Alchemy deploy that no longer recognises one of them does not fail — it creates a second one and leaves the first orphaned with the data still in it. `assertRetainedIdentities` reads the recorded state before the operation runs and throws `RetainedIdentityError` when an identity is `missing`, `unexpected` (not the `value` the marker names), or `changed` between the two snapshots. Every violation is reported, not just the first.
+
+`parseStateSnapshot` reads `alchemy state export` output — the bulk document, `{ resources: [{ stack, stage, fqn, state }] }`, not the single record `alchemy state get` prints. Run without `--stack` the command exports the whole estate, so one fqn appears once per stage; pass the second argument, `{ stack, stage }`, to narrow the document to the stage the markers are about. A scoped document that still records one fqn twice throws rather than letting a marker match whichever record sorted first. State it cannot read throws, because reading a broken state as an empty one turns a failed read into a passing assert. An evaluated stack graph is a different artifact carrying the same identities; a caller holding one projects it onto `StateSnapshot` at the call site.
+
+Two inputs are refused outright rather than passing: an empty marker list, and a marker with neither a `value` nor a `before` snapshot to compare against. Both would resolve green having asserted nothing.
+
+#### Lifecycle guards
+
+```ts
+import {
+  assertDestroyLeftNothing,
+  credentialPreflight,
+  firstDeployAuthorization,
+  secretNamePolicy,
+} from "@patronage/factory-ci/alchemy";
+```
+
+Four checks that surround an Alchemy run. Paitronage and firedup each built the first one and the last one, and paitronage built all four, so the check repeats and the policy does not: the account, the permission list, the eligible stages, the authorized plans, the state store, and the secret names are all inputs.
+
+`credentialPreflight({ accountId, environment, requiredPermissionGroups, resolveCredential, resourcesFor?, source })` proves the deploy holds the credential it claims to. `source: "hosted"` requires `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` in the environment and requires the account to be the one the deploy allows; `source: "trusted-local"` requires that neither is there, because a local run resolves its credential from the project's own secret manager and an ambient token means the run is not the run it says it is. `resolveCredential` is where that resolution happens — a 1Password read, a hosted environment read, whatever the project uses. The token is then verified against Cloudflare, matched to the reviewed policy document by token id, and reduced to permission-group names, which must equal `requiredPermissionGroups` with nothing missing, extra, or repeated. `resourcesFor` names the exact resource identifiers a group may be scoped to and defaults to the account resource, which is how a zone-scoped group is declared. On the hosted path the resolved token must be the environment token, compared and never named, because that is the token the deploy will use. A `CloudflareCredentialUnavailableError` means Cloudflare could not be asked, or the project's own resolver failed; a resolver failure is reported as one fixed message with no `cause`, because a secret-manager error can quote the value it was reading. Every other failure means the credential is wrong. No error and no result carries a credential value.
+
+`firstDeployAuthorization({ authorizedHashes, planText, sourceSha, stack, stage })` binds the one deploy no earlier state can constrain. The plan text, the target, and the reviewed source hash to one value, and that value must appear on a list the project owns. `sourceSha` is required. A full lowercase 40-character SHA binds the plan to that commit; `null` binds the plan to no commit, and that is the project's explicit choice rather than a field it forgot — an omitted field and a deliberate `null` are different decisions, so only the second one is spellable. Anything else, an empty string included, is refused. It fails closed on an empty list, a list entry that is not a sha256 hash, an empty plan, plan output that is not well-formed, an unlisted plan, and a stack, stage, or source SHA carrying surrounding whitespace — padding would mint a second hash for one target. The refusal names the hash to review, never the plan. `firstDeployPlanHash` computes the same value on its own, for the run that produces a plan for an operator to read.
+
+`assertDestroyLeftNothing({ stack, stage, stateReader })` is the postcondition that a zero exit does not prove: after `destroy`, the state store lists nothing for the stage. The project supplies `stateReader`, because only the project knows which store it configured. A reader that returns anything other than a list of non-blank resource identifiers is a failure, not an empty stage — a check that cannot fail is not a check. A padded stack or stage is refused for the same reason: it addresses a stage the store does not know, which answers empty.
+
+`secretNamePolicy({ names, values })` builds the `redact` function `executeAlchemyEntry` already takes. It is a policy, not a mechanism. The project passes the names; this package ships no secret-name list and infers none from a name pattern. The policy is fail-closed at construction: a declared name with no value, a value under eight characters, or an empty `names` list handed a populated `values` map, throws before there is any output to redact, rather than quietly covering less than the caller believes. Empty names beside empty values is the one pass-through: a project with no secrets in its Alchemy output declares none. Values are trimmed before replacement, so redaction never swallows the line break after a secret, and longer values are replaced first, so a secret containing another secret leaves no fragment.
+
+Four things paitronage does are deliberately not here. The plan-read-only before/after state capture is dropped: `Plan.make` never mutates, so the assertion re-proved a guarantee. Stage eligibility is dropped: which stages may take a first deploy is project policy, and `firstDeployAuthorization` answers only whether this exact plan was authorized. `assertFirstDeployEffects` — the check that a first-deploy plan may only create, never update or delete — stays with the consumer: it reads the plan's own effect shape, which is Alchemy's type and the project's grammar, not a hash. The live zone lookup on the hosted path stays with the consumer for the same reason: which zones an account may deploy into is project policy, and this package makes one Cloudflare call, against the token, not against the account's inventory.
+
+#### `evaluateStack`
+
+```ts
+import { evaluateStack } from "@patronage/factory-ci/alchemy";
+
+const graph = await evaluateStack({
+  name: "hq",
+  program,
+  stage: "placeholder",
+});
+// { resources: [{ id, type, props, upstreamByProp }], bindings: [{ worker, name, type, target? }] }
+```
+
+`evaluateStack` runs a stack program at one stage and returns the graph Alchemy would plan, with no state store and no network. It wraps Alchemy's `Plan.make`: the program registers its resources under a `Stack` service, then the plan builds under `inMemoryState()` at the requested `Stage`. Every provider answers its `read` and `list` probes with "absent", so the cold-adoption probe `Plan.make` makes for a resource with resolved props and no prior state never leaves the process. A stage the program returns from early (paitronage's `placeholder` stage) evaluates to an empty graph.
+
+`program` is the effect the consumer hands `Alchemy.Stack`, not the `Alchemy.Stack(...)` value. The value captures the consumer's real `providers` and `state` layers, and at Alchemy 2.0.0-beta.76 `Cloudflare.providers()` resolves credentials when its layer builds (`Credentials.fromAuthProvider` inside `CloudflareApiLive`), so evaluating the value cannot stay credential-free. Export the program next to the stack:
+
+```ts
+export const program = Effect.gen(function* () {
+  /* ... */
+});
+export default Alchemy.Stack("hq", { providers, state }, program);
+```
+
+Pass `providers` when the program depends on hand-written provider layers. Every provider that layer registers keeps its identity (`stables`, `aliases`, `diff`) and loses its probes; an unregistered resource type still evaluates. Each graph resource carries the `LogicalId`, `Type`, and raw `Props` of its plan node, so a prop may hold an unresolved Alchemy output. `upstreamByProp` names, per top-level prop, the logical ids that prop's value references, which is the only way to read a cross-resource reference out of raw props: an output is a function, so the prop that holds it says nothing on its own. A prop that references nothing carries no key. The references are kept per prop and never pooled into one list, so a caller asking which resources one prop names is never answered with an id a different prop mentioned. Each binding row comes from Alchemy's Worker binding channel: `worker` is the host's logical id, `name` and `type` are the strings Alchemy emits (`d1`, `kv_namespace`, `secrets_store_secret`, and so on), and `target` is the logical id of the resource the row references, when it references one.
+
+The caller's `providers` layer is **built** before its probes are stubbed: `evaluateStack` wraps that layer, and Alchemy's own lookup resolves each provider out of it before `read` and `list` are replaced. So any side effect a layer performs at construction — a credential read, a network call, a file write — is the caller's, and happens. This is why `Cloudflare.providers()` must not be passed: at beta.76 it resolves credentials when its layer builds (`Credentials.fromAuthProvider` inside `CloudflareApiLive`), before there is anything to stub. The no-network guarantee covers evaluation, not layer construction: pass only layers whose construction is inert.
+
+The helper decides nothing about the graph. Invariants over it are separate exports; `assertUrlImpliesAuth` below is the first.
+
+#### `assertUrlImpliesAuth`
+
+```ts
+import { assertUrlImpliesAuth } from "@patronage/factory-ci/alchemy";
+
+assertUrlImpliesAuth(graph, {
+  allowlist: [
+    {
+      reason: "Public marketing site, no data behind it.",
+      worker: "marketing",
+    },
+  ],
+  authBindingName: /_TOKEN$/u,
+});
+```
+
+Every publicly reachable Worker in the graph must declare how it is authenticated. The cheapest way to publish an unauthenticated admin surface is to add `workersDev: true`, a `domain`, or a route to a Worker that never had one: nothing fails, and the only record of the decision is a diff nobody re-read.
+
+A Worker is publicly reachable when the stack **declares** it so — `workersDev` on (the boolean, or a config object that does not turn both the stable URL and version previews off), a `domain`, or a non-empty `routes` list. A route is a hostname pattern on a zone the account owns, so it is as public as a domain is. Alchemy's own default for `workersDev` is on, so a Worker that declares none of the three still gets a `workers.dev` URL, and this check leaves it alone: a rule inferred from a default fires on every Worker in every stack and is waived everywhere within a week. A project that wants the default stated declares `workersDev: false` on the Workers that are private.
+
+A reachable Worker passes on any one of four guards. It enrolls in Cloudflare Access through its own `access` prop. A `Cloudflare.Access.Application` resource declares an `all_workers` destination, or a `worker` destination whose own `upstreamByProp.destinations` names it — an application that also declares a `preview_worker` destination credits nobody, because the graph resolves a destination's worker reference to a logical id but not to the destination holding it, and a preview-only reference protects preview URLs rather than the production one. It carries a `secrets_store_secret` binding whose name `authBindingName` accepts, as a `RegExp` or a predicate. Or `allowlist` names it with a reason; an empty reason fails louder than the bare Worker, because the entry claims a decision nobody made.
+
+What counts as a guard is the project's call: the binding-name matcher and the allowlist are both caller-supplied, and this package ships no worker names and no name pattern. Every offending Worker is named in one `UrlImpliesAuthError`, whose `violations` carry the worker and whether it was unauthenticated or allowlisted without a reason.
+
+The factory's own security review prompt carries the same rule in prose, so a repository with no graph check still gets it read by a reviewer.
+
+### Alchemy fleet baseline
+
+```ts
+import { ALCHEMY_BASELINE, assertAlchemyBaseline } from "@patronage/factory-ci";
+```
+
+`ALCHEMY_BASELINE` is the exact `alchemy` and `effect` pair the fleet moves together on: `{ alchemy: "2.0.0-beta.76", effect: "4.0.0-rc.112" }`. It is a plain constant on the root entry — it imports neither package — so any consumer can read it without installing the `./alchemy` subpath's peers.
+
+`assertAlchemyBaseline({ packageJson })` is a consumer contract helper: it fails when the consumer's own `dependencies` or `devDependencies` pin `alchemy` or `effect` to anything other than the baseline. A package the consumer does not depend on at all is not drift — both are optional peers of the subpath, so a consumer that never imports it, such as this package's own CLI, carries neither and passes. The pin is exact, not a range: the fleet is pre-1.0 and moves together, so a range would let one project drift silently ahead of or behind the rest. `assertAlchemyBaseline` reads only the object it is handed; it never walks the filesystem or reads a lockfile. Call it from a consumer's own contract test, passing that consumer's parsed `package.json`.
+
+The baseline bumps only in a lockstep release: the same commit that bumps `@patronage/factory-ci`'s own `alchemy`/`effect` devDependencies and the `./alchemy` subpath's peer ranges (ADR 0031) also bumps `ALCHEMY_BASELINE`, so the constant a consumer's contract test checks against can never point at a version the subpath itself has moved past.
+
 ### Published-package contract
 
 The tests pack the actual tarball, extract it into a throwaway external consumer, import the built package root without the workspace's `development` condition, assert the exact runtime exports, and exercise the workflow and stage interfaces. This catches source-only successes, stale or missing `dist/`, exports-map mistakes, and accidental tarball growth before the attended release check.
 
+The same consumer proves the ADR 0031 rule from the packed bytes rather than from source: it imports `@patronage/factory-ci/alchemy` with neither `alchemy` nor `effect` installed, and it bundles the packed `dist/index.js` so esbuild's own resolution reports every bare specifier the root graph still needs. Either package appearing in that list fails the build.
+
 ## No configuration surface
 
 Functions take plain typed objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); consumers pass the relevant profile policy directly at generation time.

package/dist/.build-fingerprint.json

@@ -0,0 +1,3 @@
+{
+  "fingerprint": "c63c213989e286a5baa59a9e2e2df1db05b55a0bc94208ecde13fb5a2384e5f0"
+}