hecks 2.8.0 → 3.0.0

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -1,26 +1,16 @@
-# A TOOLING-INTERNAL DOMAIN, not a business one — never attached via
-# `uses_framework`, never seen by an end-user domain. `bin/project_deploy`
-# boots this directory directly (Ports::Loading.bootstrap + load_domain,
-# the same pipeline lib/hecks/runtime/loader.rb uses, minus a
-# `.world`/`.hecksagon` this domain has no need for) and dispatches one
-# command against it before generating anything from a domain's own
-# `deployed_to("AwsLambda")` settings.
+# The Deploy chapter: what `deployed_to(...)` may declare, and the commands that generate, check and
+# compare a deploy recipe, project the OIDC manifests and provision a tenant.
 #
-# WHY THIS EXISTS: `world.bluebook`'s `Wiring`/`Setting` is a DELIBERATELY
-# open, untyped map — "a verb's schema is not even contained in the file
-# being parsed" (syntax.bluebook's own header on this). That's the right
-# call for `Wiring` itself (an adapter verb's shape genuinely isn't the
-# world language's business), but it leaves `deployed_to`'s ACTUAL shape
-# validated nowhere — `bin/project_deploy` used to check it by hand
-# (`deploy_settings[:adapter] == "AwsLambda" or abort ...`,
-# `fetch(:region) { abort ... }`), the exact raw-Ruby-refusal pattern
-# every other kind of bluebook mistake in this codebase does NOT use.
-# This closes that gap the same way any other rule gets enforced here:
-# as a real command, real invariants, a real corpus-testable refusal —
-# not a hand-written abort string discovered only by running the script.
+# `hecks deploy project` and `hecks deploy provision` boot it directly; the Hecks domain attaches it, so
+# each command below is also `hecks deploy <verb>`. The targets validate the `deployed_to` shape
+# that `world.bluebook`'s untyped `Setting` map leaves open. Each run below records that it was
+# requested before its DeployToolchain port is asked, and what came of it after. No command
+# declares a role: the chapter boots standing alone, without Governance to check one against.
 Hecks.bluebook "Deploy" do
+  vision "Generate, check and compare deploy recipes, project OIDC manifests and provision tenants."
+
   aggregate "LambdaTarget" do
-    description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before bin/project_deploy generates anything from it."
+    description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before hecks deploy project generates anything from it."
 
     identified_by :domain
 
@@ -41,77 +31,39 @@ Hecks.bluebook "Deploy" do
       invariant("a region is named") { !value.to_s.empty? }
     end
 
-    # "Postgres" (a plain AWS::RDS::DBInstance, Embryonaut's own live
-    # choice — bin/project_deploy's Ruby-side default when a domain's
-    # own deployed_to("AwsLambda") names none, so every domain
-    # declared before this attribute existed keeps generating the
-    # identical template it always has) or "Aurora" (Aurora Serverless
-    # v2, Postgres-compatible — the SAME `Adapters::Postgres`/
-    # `tokio_postgres` code on both the Ruby and rust/host sides
-    # either way; this only changes which CloudFormation resource
-    # bin/project_deploy emits, never a runtime adapter).
-    # "Shared" — no RDS/VPC of this domain's own at all; it borrows
-    # another already-deployed domain's instance instead (the
-    # storehouse), isolated from that domain's own data by a native
-    # Postgres SCHEMA (this domain's own lowercase name), not a
-    # separate database. Requires a sibling `owner "OtherDomain"`
-    # setting inside the SAME deployed_to("AwsLambda") block, naming
-    # which already-deployed domain owns the shared instance —
-    # bin/project_deploy checks for that setting itself (Ruby-level,
-    # the same as `pg_version`/`google_oauth_present` below it), not
-    # here: which domain owns the instance is a deploy-time fact, not
-    # a business invariant this validated aggregate's job to hold.
+    # "Postgres" (plain RDS, the default when `deployed_to` names none) or "Aurora"
+    # (Serverless v2);
+    # only the emitted CloudFormation resource differs, never the runtime adapter. "Shared" borrows
+    # another domain's instance under its own Postgres schema and needs an `owner` setting, which
+    # `hecks deploy project` checks, since the owning domain is a deploy-time fact.
     value_object "Database" do
       attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
     end
 
-    # "None" (the default — nothing changes for a domain that names
-    # neither this nor drops a `lambda_handler.rb`, e.g. Banking) or
-    # "Rust" — the domain's OWN Lambda (rust/host) also serves a public
-    # web UI in-process (rust/host/src/web.rs), reading HECKS_IR_PATH
-    # (a plain-JSON sidecar bin/project_wasm writes beside the .wasm
-    # artifact) and dispatching through the SAME in-process
-    # dispatch::handle/read the internal {"verb"}/{"read"} path already
-    # uses — no second Lambda, no VPC Interface Endpoint, no Ruby.
-    # Deliberately NOT "Ruby" as a third member here: a Ruby WebFunction
-    # is the pre-existing, SEPARATE `lambda_handler.rb`-file-presence
-    # mechanism (Embryonaut's own), untouched by this attribute —
-    # bin/project_deploy refuses generation outright if a domain
-    # declares `web "Rust"` AND has a `lambda_handler.rb`, rather than
-    # silently picking one.
+    # "None" (default) or "Rust": the domain's own Lambda (rust/host) also serves a public web UI
+    # in-process (rust/host/src/web.rs). "Ruby" is not a member: a Ruby WebFunction comes from a
+    # `lambda_handler.rb` file, and `hecks deploy project` refuses `web "Rust"` alongside one.
     value_object "Web" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
 
-    # 128-10240 MB — AWS Lambda's own real ceiling and floor, not a
-    # number this domain invented. A typo here used to fail deep inside
-    # a real `sam deploy`, sometimes minutes in; now it refuses before
-    # a single file is generated.
+    # 128-10240 MB, AWS Lambda's own floor and ceiling.
     value_object "Memory" do
       attribute :value, Integer
       invariant("memory is at least 128 MB") { value >= 128 }
       invariant("memory is at most 10240 MB") { value <= 10240 }
     end
 
-    # 900s — Lambda's own real ceiling.
+    # Lambda's own ceiling of 900s.
     value_object "Timeout" do
       attribute :value, Integer
       invariant("a timeout is positive") { value.positive? }
       invariant("a timeout fits Lambda's own 900s ceiling") { value <= 900 }
     end
 
-    # ALL FOUR REQUIRED — deliberately, not `optional: true` +
-    # `default:`. Confirmed directly against CommandInterpreter's own
-    # `normalize_args`/`coerce_declared_arguments` (interpreting.rb):
-    # `next unless normalized.key?(attribute.name)` skips coercion
-    # entirely for an absent key, so a command-level `default:` is
-    # honored ONLY at the JSON/Rust-codegen boundary (`scalar_from_json_
-    # expr`'s own domain), never by Ruby's own direct dispatch — a
-    # `default:` here would be quietly false advertising. "What memory
-    # defaults to when unspecified" stays exactly where it already
-    # lived (bin/project_deploy's own `fetch(:memory, 512)`); this
-    # command validates a FULLY-RESOLVED target, and bin/project_deploy
-    # resolves the default before ever dispatching.
+    # All required, no `default:`: command-level defaults apply only at the JSON/Rust-codegen
+    # boundary, not Ruby's direct dispatch (interpreting.rb `normalize_args`). Defaults are
+    # resolved by `hecks deploy project` before it dispatches.
     command "Declare" do
       goal "Validate one domain's AwsLambda deploy target before anything is generated from it"
 
@@ -133,13 +85,10 @@ Hecks.bluebook "Deploy" do
     end
   end
 
-  # A sibling of `LambdaTarget`, not a shared shape with it — value objects
-  # are not shared across aggregates in this DSL (`Tenant`'s own
-  # `DomainName`/`Realm`/`Schema` below already make the same point), so
-  # this aggregate carries its own copies of `DomainName`/`Region`/
-  # `Database`/`Web` rather than reaching into `LambdaTarget`'s.
+  # A sibling of `LambdaTarget` with its own value objects, since value objects are not
+  # shared across aggregates.
   aggregate "FargateTarget" do
-    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before bin/project_deploy generates anything from it."
+    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before hecks deploy project generates anything from it."
 
     identified_by :domain
 
@@ -161,60 +110,40 @@ Hecks.bluebook "Deploy" do
       invariant("a region is named") { !value.to_s.empty? }
     end
 
-    # A positive integer, nothing more — AWS's real cpu/memory
-    # combinations (256 cpu units needs 512-2048 MB of `memory`, say)
-    # are a pairing `ECS` itself enforces at deploy time; encoding that
-    # whole table here would duplicate AWS's own rules for no benefit
-    # this generator needs. This only catches a typo (zero, negative)
-    # before a single file is generated, the same floor `Memory`/`Port`
-    # below hold for their own ranges.
+    # Positive only: ECS enforces AWS's cpu/memory pairings at deploy time, so this just
+    # catches a typo.
     value_object "Cpu" do
       attribute :value, Integer
       invariant("cpu is positive") { value.positive? }
     end
 
-    # Fargate's own valid range, not Lambda's 128-10240 MB —
-    # `LambdaTarget`'s own `Memory` value object (above) is scoped to
-    # that aggregate alone, so this is a distinct value object under the
-    # same name rather than a shared one. A plain sanity floor and
-    # ceiling, not AWS's own cpu-paired table (see `Cpu`'s own comment).
+    # Fargate's own range, not Lambda's 128-10240 MB. A sanity floor and ceiling, not AWS's
+    # cpu-paired table (see `Cpu`).
     value_object "Memory" do
       attribute :value, Integer
       invariant("memory is positive") { value.positive? }
       invariant("memory is at most 122880 MB") { value <= 122880 }
     end
 
-    # Same shape and reasoning as `LambdaTarget`'s own `Database` —
-    # "Postgres"/"Aurora" provision this domain's own RDS instance;
-    # "Shared" borrows another already-deployed domain's instance,
-    # isolated by a native Postgres schema. See that value object's own
-    # comment for the full reasoning; it applies unchanged here.
+    # As `LambdaTarget`'s `Database`.
     value_object "Database" do
       attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
     end
 
-    # Same shape and reasoning as `LambdaTarget`'s own `Web` — "Rust"
-    # means the domain's own task also serves its public web UI
-    # in-process, over the port this aggregate's own `Port` attribute
-    # declares.
+    # As `LambdaTarget`'s `Web`; "Rust" serves the web UI in-process on this aggregate's `Port`.
     value_object "Web" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
 
-    # The container port the task listens on and the target group
-    # routes to — a real TCP port, not an arbitrary integer.
+    # The container port the task listens on and the target group routes to.
     value_object "Port" do
       attribute :value, Integer
       invariant("a port is at least 1") { value >= 1 }
       invariant("a port is at most 65535") { value <= 65535 }
     end
 
-    # All seven required, for the identical reason `LambdaTarget.Declare`
-    # requires all of its own attributes — see that command's own
-    # comment on `normalize_args`/`coerce_declared_arguments`. This
-    # validates a fully-resolved target, after `bin/project_deploy`'s own
-    # defaulting (`cpu`/`memory`/`port` each fall back to a Ruby-side
-    # default before this ever dispatches), not instead of it.
+    # All seven required for the same reason as `LambdaTarget.Declare`; this validates a
+    # target already resolved by `hecks deploy project`'s defaults.
     command "Declare" do
       goal "Validate one domain's AwsFargate deploy target before anything is generated from it"
 
@@ -238,41 +167,27 @@ Hecks.bluebook "Deploy" do
     end
   end
 
-  # `bin/project_tenant`'S OWN VALIDATED SHAPE — same split LambdaTarget
-  # draws with `bin/project_deploy`: this aggregate validates, that
-  # script GENERATES/ACTS (writes `environments/<slug>.world`, ensures
-  # the Postgres schema, boots once to prove it). Deliberately NOT a
-  # saga/process manager with durable runtime state — every step
-  # `bin/project_tenant` takes is already idempotent by construction
-  # (`CREATE SCHEMA IF NOT EXISTS` — PostgresEra#connect_for's own,
-  # File.write of the overlay — a plain overwrite, `Hecks.boot` itself),
-  # the same "generator script, not a business process" shape
-  # `bin/project_deploy` already is; a saga's own resumability earns
-  # its cost coordinating a real distributed transaction across
-  # multiple ports with real failure boundaries (Payments::Payment's
-  # own PaymentGateway, say) — three local, idempotent, single-process
-  # steps have no such boundary to resume across. A durable, reactable
-  # RUNTIME fact ("this tenant exists, is active, is suspended") is a
-  # different, later, business-facing thing — deliberately not built
-  # here, and deliberately not named Deploy::Tenant to avoid colliding
-  # with this validation-only aggregate should it ever land.
+  # The validated shape of `hecks deploy provision`, which does the generating and provisioning.
+  # Not a saga: each of its steps is idempotent and local, so there is nothing to resume.
   aggregate "Tenant" do
-    description "One tenant's validated identity — which realm and Postgres schema `bin/project_tenant` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
+    description "One tenant's validated identity — which realm and Postgres schema `hecks deploy provision` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
 
     identified_by :slug
 
-    attribute :slug,   Slug
-    attribute :domain, DomainName
-    attribute :realm,  Realm
-    attribute :schema, Schema
-
-    # LOWERCASE, NO SPACES — a slug becomes both the `environments/
-    # <slug>.world` filename and (by convention, not enforced here —
-    # `schema` is its own, separately-declared field precisely so a
-    # tenant CAN choose a different schema name than its slug)
-    # ordinarily the schema name too.
+    attribute :slug,      Slug
+    attribute :domain,    DomainName
+    attribute :realm,     Realm
+    attribute :schema,    Schema
+    attribute :database,  DatabaseName,  optional: true
+    attribute :adapter,   AdapterName,   optional: true
+    attribute :directory, DirectoryPath, optional: true
+    attribute :output,    Report,        optional: true
+    attribute :refusal,   Report,        optional: true
+
+    # Lowercase, no spaces: a slug becomes the `environments/<slug>.world` filename and, by
+    # convention only, the schema name (`schema` is separate so a tenant can differ).
     value_object "Slug" do
-      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
       invariant("a tenant slug is named") { !value.to_s.empty? }
     end
 
@@ -286,39 +201,583 @@ Hecks.bluebook "Deploy" do
       invariant("a tenant realm is named") { !value.to_s.empty? }
     end
 
-    # POSTGRES'S OWN REAL IDENTIFIER RULES, loosely — lowercase (this
-    # adapter never quotes a mixed-case identifier back out consistently
-    # once created), letters/digits/underscores, starting with a letter.
-    # NOT a byte-length ceiling too (Postgres's own real 63-byte
-    # NAMEDATALEN limit) — the expression grammar invariants compile
-    # through admits a narrow arithmetic/comparison subset, not
-    # arbitrary method dispatch (`bytesize` included; found live,
-    # writing this: `Bluebook::Expression::Evaluator` tries to resolve
-    # a dotted chain as a FIELD lookup, not a method call, the same
-    # "admits + but not -, no parentheses" narrowness
-    # embryonaut_bluebooks/payments' own Refund command already
-    # documents). Postgres itself refuses a too-long identifier loudly
-    # on its own; not worth fighting the expression grammar for a
-    # corner case this rare.
+    # Lowercase, letters/digits/underscores, starting with a letter. Postgres's 63-byte
+    # identifier limit is not checked: the invariant expression grammar has no `bytesize`, and
+    # Postgres refuses a too-long identifier itself.
     value_object "Schema" do
-      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
       invariant("a schema is named") { !value.to_s.empty? }
     end
 
-    command "Declare" do
-      goal "Validate one tenant's shape before bin/project_tenant provisions its schema and overlay world"
+    # A database name or a `postgres://` URL, whichever the overlay's `database` setting takes.
+    value_object "DatabaseName" do
+      attribute :value, String, pattern: '\A[^\t\n\r]+\z'
+    end
+
+    # The persistence adapter the overlay binds; PostgresEra when a request names none.
+    value_object "AdapterName" do
+      attribute :value, String, pattern: '\A[A-Z][A-Za-z0-9]*\z'
+    end
+
+    # The domain's own directory on disk, where `environments/<slug>.world` is written.
+    value_object "DirectoryPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
 
-      attribute :slug,   Slug
-      attribute :domain, DomainName
-      attribute :realm,  Realm
-      attribute :schema, Schema
+    value_object "Report" do
+      attribute :value, String
+    end
 
+    lifecycle :status, default: "requested" do
+      transition "Reprovision" => "requested",   from: %w[provisioned refused]
+      transition "Complete"    => "provisioned", from: "requested"
+      transition "Abandon"     => "refused",     from: "requested"
+    end
+
+    # `hecks deploy provision <directory> slug=s domain= realm= schema= database= [adapter=]`.
+    # The only command that creates a tenant: its slug, schema and realm are validated by the value
+    # objects' patterns and invariants, then the overlay is written through the TenantProvisioning
+    # port; the adapter answers PostgresEra when `adapter` is left out. `dry_run?` on this verb
+    # validates a declaration without recording it.
+    command "Provision" do
+      goal "Validate one tenant, write its environment overlay world, and register it"
+
+      attribute :directory, DirectoryPath
+      attribute :slug,      Slug
+      attribute :domain,    DomainName
+      attribute :realm,     Realm
+      attribute :schema,    Schema
+      attribute :database,  DatabaseName
+      attribute :adapter,   AdapterName, optional: true
+
+      sets :directory
       sets :slug
       sets :domain
       sets :realm
       sets :schema
+      sets :database
+      sets :adapter
+
+      emits "TenantProvisionRequested"
+    end
+
+    # A tenant's slug names its record, so provisioning it again is its own command; the overlay
+    # is rewritten with the database and adapter given now.
+    command "Reprovision" do
+      goal "Write a provisioned or refused tenant's environment overlay world again"
+
+      reference_to Tenant
+      attribute :directory, DirectoryPath
+      attribute :database,  DatabaseName
+      attribute :adapter,   AdapterName, optional: true
+
+      sets :directory
+      sets :database
+      sets :adapter
+
+      emits "TenantReprovisionRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the tenant's overlay was written, and where"
+
+      reference_to Tenant
+      attribute :output, Report
+
+      sets :output
+
+      emits "TenantRecorded"
+    end
+
+    command "Abandon" do
+      goal "Record that the tenant could not be provisioned, and why"
+
+      reference_to Tenant
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "ProvisioningAbandoned"
+    end
+
+    query "Provisioning" do
+      description "What provisioning one tenant did: its status, and the reason when it was refused."
+      attribute :slug, Slug
+      where(slug: :slug)
+      order_by :slug
+    end
+
+    query "Unprovisioned" do
+      description "Every tenant whose provisioning was refused."
+      where(status: "refused")
+      order_by :slug
+    end
+  end
+
+  # `TenantProvisioned` also reaches Tenancy's `RegisterProvisionedTenant` where that chapter is
+  # attached, so a provisioned tenant becomes a fact there.
+  policy "ProvisionWhenRequested" do
+    on      "Tenant.TenantProvisionRequested"
+    trigger Tenant::TenantProvisioning::WriteOverlay, with: { database: :database, directory: :directory }
+  end
+
+  policy "ReprovisionWhenRequested" do
+    on      "Tenant.TenantReprovisionRequested"
+    trigger Tenant::TenantProvisioning::WriteOverlay, with: { database: :database, directory: :directory }
+  end
+
+  policy "RecordTheTenant" do
+    on      "Tenant.TenantProvisioned"
+    trigger Tenant::Complete, with: { output: :output }
+  end
+
+  policy "RecordTheRefusedTenant" do
+    on      "Tenant.ProvisioningRefused"
+    trigger Tenant::Abandon, with: { refusal: :refusal }
+  end
+
+  aggregate "Recipe" do
+    description "One generation of a domain's deploy recipe: the template, scripts and Makefile written from its deployed_to target."
+
+    attribute :domain,      DomainPath
+    attribute :run,         RunKey
+    attribute :tenant,      TenantSlug,      optional: true
+    attribute :schema,      SchemaName,      optional: true
+    attribute :out,         Location,        optional: true
+    attribute :environment, EnvironmentName, optional: true
+    attribute :output,      Report,          optional: true
+    attribute :refusal,     Report,          optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # A domain directory, whose `bluebook/` holds the `.world` that declares `deployed_to`.
+    value_object "DomainPath" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a domain is named by its path") { !value.to_s.empty? }
+    end
+
+    # A tenant of a shared-database domain: its stack is the domain's own, suffixed with the slug.
+    value_object "TenantSlug" do
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
+    end
+
+    value_object "SchemaName" do
+      attribute :value, String, pattern: '\A[a-z][a-z0-9_]*\z'
+    end
+
+    # Where the recipe is written, for a domain that lives in a client's repository.
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # An `environments/<name>.world` overlay of the domain, which must exist.
+    value_object "EnvironmentName" do
+      attribute :value, String, pattern: '\A[A-Za-z][A-Za-z0-9_]*\z'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "projected", from: "requested"
+      transition "Fault"    => "faulted",   from: "requested"
+    end
+
+    # `hecks deploy project <domain> [tenant=] [schema=] [out=] [environment=]`. A schema override
+    # needs its tenant; the generator says so, and a domain with no `deployed_to` target, or one
+    # whose settings conflict, is faulted with the generator's own sentence.
+    command "Project" do
+      goal "Generate a domain's AWS deploy recipe from its declared deployed_to target"
+
+      attribute :domain,      DomainPath
+      attribute :run,         RunKey
+      attribute :tenant,      TenantSlug,      optional: true
+      attribute :schema,      SchemaName,      optional: true
+      attribute :out,         Location,        optional: true
+      attribute :environment, EnvironmentName, optional: true
+
+      sets :domain
+      sets :run
+      sets :tenant
+      sets :schema
+      sets :out
+      sets :environment
+
+      emits "ProjectionRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the recipe was written, and where"
+
+      reference_to Recipe
+      attribute :output, Report
+
+      sets :output
+
+      emits "RecipeProjected"
+    end
+
+    command "Fault" do
+      goal "Record that the recipe could not be generated, and why"
+
+      reference_to Recipe
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "RecipeFaulted"
+    end
+
+    query "Outcome" do
+      description "What one generation did: its status, and the files written or the reason it stopped."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every generation that could not write its recipe."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "GenerateWhenRequested" do
+    on      "Recipe.ProjectionRequested"
+    trigger Recipe::DeployToolchain::Generate, with: { run: :run }
+  end
+
+  policy "RecordTheRecipe" do
+    on      "Recipe.RecipeAnswered"
+    trigger Recipe::Complete, with: { output: :output }
+  end
+
+  policy "RecordTheFaultedRecipe" do
+    on      "Recipe.RecipeRefused"
+    trigger Recipe::Fault, with: { refusal: :refusal }
+  end
+
+  aggregate "MakefileCheck" do
+    description "One lint of generated deploy Makefiles for prod-touching recipes that hide failure."
+
+    attribute :run,       RunKey
+    attribute :makefiles, PathList, optional: true
+    attribute :report,    Report,   optional: true
+    attribute :refusal,   Report,   optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # Makefile paths, comma separated; three generated fixture domains when absent.
+    value_object "PathList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Pass" => "clean",   from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # A pattern match over Make and shell text, not a static analyzer: the findings are the
+    # linter's own sentences, one per violation, and a run that finds any is flagged.
+    command "Lint" do
+      goal "Lint generated deploy Makefiles for recipes that hide the failure of a command that touches prod"
+
+      attribute :makefiles, PathList, optional: true
+      attribute :run,       RunKey
+
+      sets :makefiles
+      sets :run
 
-      emits "TenantDeclared"
+      emits "LintRequested"
     end
+
+    command "Pass" do
+      goal "Record that no recipe hides a failure"
+
+      reference_to MakefileCheck
+      attribute :report, Report
+
+      sets :report
+
+      emits "LintPassed"
+    end
+
+    command "Flag" do
+      goal "Record that a recipe hides a failure, or that the lint could not run, and what it said"
+
+      reference_to MakefileCheck
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "LintFlagged"
+    end
+
+    query "Verdict" do
+      description "What one lint found: its status, and the report or the violations."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every lint that left a violation or could not run."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "LintWhenRequested" do
+    on      "MakefileCheck.LintRequested"
+    trigger MakefileCheck::DeployToolchain::Scan, with: { run: :run }
+  end
+
+  policy "RecordTheCleanLint" do
+    on      "MakefileCheck.LintAnswered"
+    trigger MakefileCheck::Pass, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedLint" do
+    on      "MakefileCheck.LintRefused"
+    trigger MakefileCheck::Flag, with: { refusal: :refusal }
+  end
+
+  aggregate "TemplateComparison" do
+    description "One offline comparison of two CloudFormation templates, by logical id."
+
+    attribute :before,  Location
+    attribute :after,   Location
+    attribute :run,     RunKey
+    attribute :json,    Switch, optional: true
+    attribute :strict,  Switch, optional: true
+    attribute :report,  Report, optional: true
+    attribute :refusal, Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a template is named by its path") { !value.to_s.empty? }
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Match"  => "matching", from: "requested"
+      transition "Drift"  => "drifted",  from: "requested"
+      transition "Refuse" => "refused",  from: "requested"
+    end
+
+    # `hecks deploy diff <before> after=<template> [--json] [--strict]`. `--strict` also counts
+    # cosmetic differences (comments, key order); `--json` writes the report as JSON.
+    command "Diff" do
+      goal "Compare two CloudFormation templates and report what differs by logical id"
+
+      attribute :before, Location
+      attribute :after,  Location
+      attribute :run,    RunKey
+      attribute :json,   Switch, optional: true
+      attribute :strict, Switch, optional: true
+
+      sets :before
+      sets :after
+      sets :run
+      sets :json
+      sets :strict
+
+      emits "ComparisonRequested"
+    end
+
+    command "Match" do
+      goal "Record that the templates agree"
+
+      reference_to TemplateComparison
+      attribute :report,    Report
+      attribute :different, Switch
+
+      given("the templates agree") { !different.value }
+
+      sets :report
+
+      emits "TemplatesMatched"
+    end
+
+    command "Drift" do
+      goal "Record that the templates differ, and how"
+
+      reference_to TemplateComparison
+      attribute :report,    Report
+      attribute :different, Switch
+
+      given("the templates differ") { different.value }
+
+      sets :report
+
+      emits "TemplatesDrifted"
+    end
+
+    command "Refuse" do
+      goal "Record that a template could not be read, and why"
+
+      reference_to TemplateComparison
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "ComparisonRefused"
+    end
+
+    query "Verdict" do
+      description "What one comparison found: its status, and the report or the reason it could not run."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Drifted" do
+      description "Every comparison in which the templates differ."
+      where(status: "drifted")
+      order_by :run
+    end
+  end
+
+  policy "CompareWhenRequested" do
+    on      "TemplateComparison.ComparisonRequested"
+    trigger TemplateComparison::DeployToolchain::Compare, with: { run: :run }
+  end
+
+  policy "RecordTheMatch" do
+    on      "TemplateComparison.ComparisonAnswered"
+    trigger TemplateComparison::Match, with: { report: :report, different: :different }
+  end
+
+  policy "RecordTheDrift" do
+    on      "TemplateComparison.ComparisonAnswered"
+    trigger TemplateComparison::Drift, with: { report: :report, different: :different }
+  end
+
+  policy "RecordTheRefusedComparison" do
+    on      "TemplateComparison.ComparisonUnreadable"
+    trigger TemplateComparison::Refuse, with: { refusal: :refusal }
+  end
+
+  aggregate "OidcManifest" do
+    description "One projection of each domain's OIDC client and scope manifest into its oidc.json."
+
+    attribute :run,     RunKey
+    attribute :domains, DomainList, optional: true
+    attribute :output,  Report,     optional: true
+    attribute :refusal, Report,     optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # Domain directories, comma separated; every domain of the checkout when absent.
+    value_object "DomainList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "projected", from: "requested"
+      transition "Fault"    => "faulted",   from: "requested"
+    end
+
+    command "ProjectOidc" do
+      goal "Write each domain's OIDC client and scope manifest beside it as oidc.json"
+
+      attribute :domains, DomainList, optional: true
+      attribute :run,     RunKey
+
+      sets :domains
+      sets :run
+
+      emits "OidcProjectionRequested"
+    end
+
+    command "Complete" do
+      goal "Record which manifests were written"
+
+      reference_to OidcManifest
+      attribute :output, Report
+
+      sets :output
+
+      emits "OidcProjected"
+    end
+
+    command "Fault" do
+      goal "Record that the manifests could not be projected, and why"
+
+      reference_to OidcManifest
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "OidcFaulted"
+    end
+
+    query "Outcome" do
+      description "What one projection did: its status, and the manifests written or the reason it stopped."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every projection that could not write its manifests."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ProjectWhenRequested" do
+    on      "OidcManifest.OidcProjectionRequested"
+    trigger OidcManifest::DeployToolchain::Manifest, with: { run: :run }
+  end
+
+  policy "RecordTheManifests" do
+    on      "OidcManifest.ManifestAnswered"
+    trigger OidcManifest::Complete, with: { output: :output }
+  end
+
+  policy "RecordTheFaultedManifests" do
+    on      "OidcManifest.ManifestRefused"
+    trigger OidcManifest::Fault, with: { refusal: :refusal }
   end
 end