satz language

The complete specification of Satz, the language an estate is written in.

1. The layers

satz is four layers, and each one is a strictly stronger statement about the estate than the one below it. HCL holds the resources. Satz decides which resources exist and under whose policy. Claims say which control each resource is for. Evidence checks that the control is actually in force — live, by value.

In the Satz layer, org policies are ordinary resources in versioned packs. A semantic upstream change to a pack the estate includes forks the pack and repoints the estate, checked by transpile identity. Declining a control is a deviates claim with its reason. hcl { … } warns on every transpile until it is marked hcl trust "<reason>".

2. HCL is the foundation

HCL is the language of the IaC layer: the assembly code that OpenTofu (the preferred tool) or Terraform executes against provider plugins from Google and others. Satz compiles to it. It does not wrap it, rename it, or hide it.

Satz has no provider documentation of its own. The OpenTofu registry and the HashiCorp registry are the documentation. Resource type names are the provider's, to the underscore. Attribute names are the provider's, to the underscore — across six real resource pairs from fleet estates (bucket, org policy, IAM grants, conditional grant, log metric + alert policy, folder/project hierarchy) not one attribute name differs. What you know about google_storage_bucket from the registry page is what you write.

2.1 One resource, both ways

The audit-log bucket from the shipped organization-audit-logsink pack, as written and as emitted:

google_storage_bucket {
  org_audit_logs {
    project                     = "${{google_project.logsink_project.project_id}}"
    name                        = logsink_bucket_name
    location                    = logsink_bucket_location
    storage_class               = "NEARLINE"
    uniform_bucket_level_access = true
    public_access_prevention    = "enforced"
    lifecycle_rule = [
      {
        action { type = "Delete" }
        condition { age = logsink_retention_days }
      },
    ]
  }
}

resource "google_storage_bucket" "org_audit_logs" {
  provider = google.google
  project = "${google_project.logsink_project.project_id}"
  name = "acme-organization-audit-bucket"
  location = "europe-west3"
  storage_class = "NEARLINE"
  uniform_bucket_level_access = true
  public_access_prevention = "enforced"

  lifecycle_rule {
    action {
      type = "Delete"
    }

    condition {
      age = 400
    }
  }
}

Every attribute — project, name, location, storage_class, uniform_bucket_level_access, public_access_prevention, lifecycle_rule, action.type, condition.age — is the provider's name. Where the text differs:

2.2 The complete list of transformations

Nine syntactic ones — and, below them, the short list of attributes the emitter derives for you. Beside them, three things the compile does before emission: each expands a list into labelled bodies (§6.4), private is read from a body and never emitted (§6.17), and depends_on edges are derived where a resource must wait for another (§6.5). If it is not on these lists, Satz did not change it.

1. resource "T" "L" { → T { L { } }. Label quoted only when it is not an identifier; - → _ in the emitted address.
2. provider = … is emitted, never written.
3. A bare identifier is a param and is emitted as its resolved literal — never var.x (params also become variables in variables.tf with values in terraform.tfvars, for reference; resources do not point at them).
4. "{param}" in a string interpolates; ${{…}} → ${…}.
5. A list of objects x = [ {…}, {…} ] emits repeated x { } blocks. A single block x { } is unchanged.
6. labels { k = "v" } (block syntax) → labels = { "k" = "v" } (map attribute).
7. IAM grants — the one shape that is not 1:1: "member" = [roles…] emits one *_iam_member resource per (member, role, condition), with a hashed label and role / member / org_id-or-project synthesized. A type scoped by neither the organisation nor its node writes that scope in the map (bucket = …, service_account_id = …), and it namespaces the grant.
8. Hierarchy is the parent reference: a google_folder inside a folder emits parent = google_folder.<outer>.name; a google_project inside a folder emits folder_id = …; a top-level folder gets parent = "organizations/<id>".
9. Org policy name is written as the bare constraint (compute.managed.requireOsLogin) and emitted as the full organizations/<id>/policies/<constraint> — the one attribute whose value is expanded.

Derived, never written (each is a consequence of context, not a rewrite):

• a project without billing_account gets billing_account_infra; a project without name gets its project_id;
• a google_cloud_identity_group label becomes group_key { id = "<label>@{customer_domain}" }, parent = "customers/{customer_id}", the discussion-forum labels, and lifecycle { ignore_changes = [initial_group_config] } (merged with a declared lifecycle); its member / manager / owner lists become google_cloud_identity_group_membership resources (§6.4);
• project_service = [ … ] explodes into one google_project_service per service; each project gets its own provider alias, scoped to it (§6.8);
• an org policy's structured parameters { … } is JSON-encoded into the string the provider wants;
• the backend is chosen by deployment_mode (§6.8); "import-id" becomes an import block in imports.tf (§6.7); param names are kebab-cased in variables.tf / terraform.tfvars.

Everything else is the provider's, unchanged.

3. What Satz adds on top

The layers diagram reads bottom-up; this section reads the same way. Each addition is one line or a few, shown against the shipped CIS pack.

Include a pack — the CIS baseline, one line:

use "presets/cis/CIS-GCP-Foundation-4.0.satz" when use_cis_baseline

Tune it without forking — the pack declares a default, the estate binds it. An estate whose contact addresses are on a different domain than its organisation binds:

params {
  essential_contacts_allowed_domains = ["@example.net"]
}

Decline one control it provides — no fork, one line; if upstream removes the policy, the suppress matches nothing and the transpile fails:

suppress google_org_policy_policy "compute-managed-requireOsLogin"

Record the reason — the control then reads ⚠ deviation in every report, not ✓ or ✗:

claim "cis-gcp" "4.0" "4.4" deviates {
  resources     = ["google_org_policy_policy.compute_managed_requireOsLogin"]
  reason        = "A service here depends on metadata SSH keys; enforcing OS Login breaks it."
  duty_reassess = "Re-assess when that service supports OS Login."
}

Include a bare list as a map's content, or conditionally (tests/smoke/yaml/showcase.satz):

use "showcase-policies.satz" as google_org_policy_policy
use "showcase-optional.satz" when want_optional

4. What makes the layers possible

Each layer exists because a handful of language features make it expressible.

Params with interpolation are why a pack can be pristine and still fit a customer. Outer beats inner; everything globally unique derives from customer_shortname, everything org-scoped from customer_organization_id.

Schema-typed resources are what the fold relies on. Block keys are matched exactly against the loaded provider schemas, so the compiler tells a resource map from a nested attribute block without guessing, and an unknown type — or an argument a type does not have — is a parse-time error, not a plan-time one.

use and the ⊕ fold are why an estate is a composition rather than a copy. Two files defining the same address differently is a conflict naming both locations — composition is something the compiler checks.

suppress is why customisation stays small: subtractive, one line, and a hard error when it matches nothing.

claim / deviates are why the controls layer is language, not a sidecar: read from the same compile, naming emitted addresses.

hcl trust is why raw HCL is visible: it warns on every transpile until the block carries a reason.

Provenance by suffix is what lets a fleet take pack updates: the filename says who owns the file, the tooling enforces it, and the diff file is regenerated on every merge.

5. How much shorter, measured

Three numbers — the first two measured across the fleet — counting code lines (blank and comment-only lines removed on both sides):

The first row is what is maintained per organisation: a sixth of what runs. The high end (~10×) are the estates that use the most pristine packs; the low end (~3×) are estates with forked or inlined packs.

The second row explains the first. Packs are not short — they carry their params' reasoning as comments and their control claims and questions in-file, none of which emits HCL — and the third row is the extreme case: the CIS pack is about twice as long as the policies it produces, because 164 of its code lines are claims and 60 are questions.

What changes for common tasks:

6. Language reference

Two complete estates compile in CI on every pull request and every push to main and are the examples the sections below cite instead of carrying loose snippets:

• the smallest complete estate — tests/corpus/override-chain/main.satz (18 lines: header, params, terraform, one use, one use … when with a declared-false switch) with pack.satz and optional.satz beside it; snapshot-gated (tests/corpus/override-chain/expected.sorted.txt).
• the showcase — tests/smoke/yaml/showcase.satz with showcase-pack.satz, showcase-policies.satz, showcase-optional.satz: comments of all three kinds, params of every shape, terraform + providers, use in all three positions (as, when), two suppress forms, a group with a member and an "import-id", grants incl. a conditional one, folder → project → bucket nesting with a list-of-objects block, a bucket-scoped grant in both forms (labelled and member map with its own scope), hcl trust, questions including a required choice, one that is not and one whose empty answer means something, and claims of all three kinds with duties and an interpretation; its exports, an interface … common, use interface, all … under, a private statement, a request point and an each over it are the interface plane's features (§6.17, §6.4). scripts/smoke.sh transpiles it, validates the HCL and checks each feature's effect.

Every snippet in this section is either one of those files or compiles the same way (terraform { backend { … } } is required by the emitter — the snippets omit it for brevity where they are fragments of a larger estate).

Where HCL is shown, it is the emitted text.

6.1 Lexical structure

Line endings — a CRLF line ending is a line ending: a file checked out with CRLF compiles, formats and compares exactly as its LF twin, triple-quoted strings and hcl { } bodies included. Every file satz writes has LF line endings.

Comments

# hash to end of line
// slashes to end of line
/* block comment,
   may span lines */

Identifiers — [A-Za-z_][A-Za-z0-9_.]*, conventionally snake_case; the dot is for dotted pack names (pack monitoring.audit_logsink), a resource address in private <type>.<label> and all … under <type>.<label>, and each.<field> inside an each. Used for param names, block keywords, resource types, map keys and param references.

Numbers and booleans — bare literals (400, 1.5, -1; no exponent) and true / false.

Strings — single-line, double-quoted; multi-line, triple-quoted (the only form that may contain a raw newline; {param} interpolates in both forms — the doubled-brace escape is under Interpolation below):

"europe-west3"

"""
first line
second line
"""

Escapes (single-line only): \n, \", \\. Any other escape is an error.

Interpolation — {param_name} inside a string splices a param's value. The name is [A-Za-z0-9_]+, terminated by }; inside an each it may be each.<field> (§6.4), and any other dotted name is an unknown param. Interpolation works in values and keys, in an action's args and execute_args, and in a suppress label and role. Every other statement string — a use path, a claim's header, reason, interpretation, duties, gcloud, gcloud_check and risk, a question's texts, an export's or interface's name, an action's name and run — is literal, and {…} in one is refused: no interpolation allowed.

parent = "organizations/{customer_organization_id}"
email  = "essential-contacts-all@{customer_domain}"

Literal braces are doubled, because Terraform's ${…} and JSON policy parameters both contain braces:

parameters = "{{\"allowedDomains\" : [\"@{customer_domain}\"]}}"
             ↑↑ literal { }                      ↑ interpolated param

value = "${{google_project.x.project_id}}"   # a literal Terraform reference

{x} interpolates a param; {{ is a literal brace. A lone } is literal text; only { must be doubled.

A reference must name something the estate emits. Every ${{…}} is checked against what was actually emitted — including a project's expanded services and an exploded grant, which are emitted addresses that were never written as blocks. A reference naming nothing is a compile error that says where it was written and lists the labels of that type that do exist:

references to resources this estate does not emit (1)

error    written-reference  satz/main.satz:26
    google_service_account_iam_member.onboarding_user writes
    `${google_service_account.onbaording.name}`
      emitted `google_service_account` labels: onboarding

1 error

Without the check, Terraform catches most typos one cycle later, pointing at generated HCL instead of the Satz line, and cannot catch a typo that names a different real resource. Suppressing a resource that something else references is the same error: the estate does not emit it.

A whole-value reference is recorded as a reference. When a value is nothing but one reference — service_account_id = "${{google_service_account.onb.name}}" — the emission manifest records it as a reference, so satz adopt follows it to the resource it names and report-compliance scopes a witness through it. When the reference is embedded in a longer string — "principalSet://…/projects/${{google_project.mgmt.number}}/…" — it is not a reference to a resource but a string that mentions one, and its value is only known after apply. Those are reported as unresolvable, naming the reference, rather than matched against live state as if the ${…} text were literal.

6.2 File structure

file    := [ header ] { item }
header  := ("estate" | "pack") IDENT [ "version" STRING ]
         | "interface" STRING                          # a generated interface file (§6.17)
item    := "params" "{" { param } "}"
         | "inputs" "{" { param } "}"
         | "use" STRING [ "as" IDENT ] [ "when" IDENT ]
         | "claim" STRING STRING STRING COVERAGE "{" { claim-entry } "}"
         | "question" [ "oneof" ] IDENT "{" { question-entry } "}"
         | "suppress" IDENT STRING [ "role" STRING ]
         | "hcl" [ "trust" STRING ] "{" … "}"
         | "action" STRING "{" { action-entry } "}"
         | "notice" IDENT "{" { notice-entry } "}"        # a pack only
         | "offers" STRING "{" { offers-entry } "}"      # the map only
         | export
         | "interface" STRING [ "common" ] "{" { export | use-interface } "}"
         | "private" IDENT "." IDENT
         | "request" IDENT "{" "key" "=" STRING "fields" "=" "[" { STRING } "]" "description" "=" STRING "}"
         | block

export  := "export" STRING "=" ( value | "all" IDENT [ "under" IDENT "." IDENT ] )
           [ "attach" "[" { STRING } "]" ] [ "description" STRING ]
use-interface := "use" "interface" ( STRING | "[" { STRING } "]" ) [ "when" IDENT ]

block   := KEY [ KEY ] "{" { entry } "}"
entry   := KEY "=" value | block | "use" STRING [ "as" IDENT ] [ "when" IDENT ]
         | "each" IDENT "by" IDENT "{" { entry } "}"

An item stands at the top level of a file and nowhere else (an export also inside an interface block). A use is the one statement that is also an entry: it stands in google_folder { … } and in a resource type map (§6.9).

Header

estate acme                        # a customer estate
pack   monitoring.audit_logsink version "1.1"

• estate — one customer organisation. Usually one per repo.
• pack — a reusable unit. version is the pack's own revision, in-file, never in the filename (framework versions live in claims and are independent of it: several pack revisions may implement the same standard).

The header is a name and a version: another word on its line is an error.

The header is optional in fragment files that are only ever used.

6.3 Params

Params are declarations with defaults:

params {
  customer_organization_id = "123456789012"
  customer_shortname       = "acme"
  retention_days           = 400
  versioning_enabled       = true
  extra_members            = []
  audit_bucket_name        = "{customer_shortname}-audit-001"
  log_bucket_name          = audit_bucket_name # bare identifier = param reference
}

Resolution rules:

1. A value bound by the using document wins over the file's own default (outer beats inner — that is what makes a pack configurable).
2. Params may reference each other regardless of declaration order; the compiler sorts by dependency.
3. The namespace is one document-ordered space: packs see every earlier file's params; there is no per-pack scope. A pack's default may therefore reference another pack's param, and that is the right way to wire two packs that share a value — the CIS alert pack defaults its project to the audit-logsink pack's logsink_project_id, so an estate using both sets nothing, and renaming the logsink project moves the alerts with it; a repeated literal would keep pointing at the old name. Used without the pack that declares the name, the reference stops with unknown param, and the estate has to bind the value.
4. Overriding a list replaces it — Satz has no list concatenation — so an estate that adds to a pack's list repeats the entries it keeps. A PACK adds to one instead of replacing it, through contributes_<param>, below.

contributes_<param> — a pack's entries in another file's list

A param named contributes_<param> is not a param: it is a contribution, the entries a pack adds to the list param <param> that another file declares.

pack billing_export version "1.0"

params {
  contributes_allowed_policy_member_subjects = [
    "serviceAccount:billing-export-bigquery@system.gserviceaccount.com",
  ]
}

What it does:

• The entries are added after whatever <param> holds — the estate's binding, else the default of the file that declares it. The list stays the estate's; a contribution only adds.
• A pack behind a false use … when gate contributes nothing, like everything else it declares. Switching the pack off takes its entries out.
• An entry the list already holds is not added twice, whoever wrote it.
• The merge happens before the compile walks the estate, so where the contributing use line stands decides nothing.
• It is no value of its own: it is never a variable, never in terraform.tfvars, and no question may ask it — what a customer answers is <param>.
• Where no file the estate uses declares <param>, the entries are dropped. The pack graph carries the requirement as a data edge, and satz packs names it.

What a pack writes it as is checked where it is written: it belongs in a pack, its value is a list, and a file that declares <param> itself writes the entries into that default instead. A <param> that is not a list is refused, naming the contributing file.

satz packs <estate> prints each pack's contributions, so every entry in a list has a pack beside it; a pack's own page under presets/docs/ lists them under Contributes.

What the compiler does with them: every param becomes a typed variable in variables.tf (underscores → hyphens) with its resolved value in terraform.tfvars, for anyone reading the HCL — but a resource that references a param is emitted with the literal, never var.x. The type follows the value: a string, a number or a bool is its own type; a list or a map of scalars is list(string) or map(string); a list or a map holding lists or objects is any, because its elements need not share one shape — the CIS baseline's cis_sa_key_creation_rules is a list of rules, and an exemption rule carries a condition the enforcing rule does not.

# variables.tf
variable "audit-bucket-name" { type = string }
variable "retention-days"    { type = number }
variable "extra-members"     { type = list(string) }
variable "sa-key-rules"      { type = any }

# terraform.tfvars
audit-bucket-name = "acme-audit-001"
log-bucket-name   = "acme-audit-001"      # the alias resolved fully

# main.tf — the resource carries the value
resource "google_storage_bucket" "probe" {
  provider = google.google
  name = "acme-audit-001"
  location = "EU"
}

A pack's params are its contract, and the comment travels with the default. From the shipped CIS pack:

params {
  // essentialcontacts.managed.allowedContactDomains: the DOMAINS whose
  // addresses may be set as essential contacts (each entry `@domain`).
  // Default = the customer's own domain. Some customers keep contacts on a
  // different domain, or on several; the param is a list, so neither case
  // forks the pack.
  essential_contacts_allowed_domains = [
    "@{customer_domain}",
  ]
}

inputs — a template's contract, the values a reader binds

inputs {
  // the four-digit cost centre the project is billed to
  cost_centre = "4711"
  stage       = "dev"
}

google_project {
  shop {
    project_id = "${{interface.customer_shortname}}-shop-{stage}"
    labels     = { cost_centre = cost_centre }
  }
}

(tests/smoke/yaml/showcase.satz; the template examples/acme/simple-project/.)

An input is a param with one more meaning: it is the contract of a template, bound by whoever instantiates it. It is declared like a param, in the same namespace (a name in both blocks is refused), and holds a string, a number, a bool or a list of them — what a variable holds; an object is refused. The value in the block is the example value.

• For everything that judges, an input is its value. The fold, the manifest, the prerequisite check and the interface rules read the bound value — the example until a reader binds one — so a template compiles and checks as it stands.
• The emission writes the variable. variables.tf declares variable "<name>", its name as written and its description the comment lines directly above the input, with the type its value has; terraform.tfvars carries the bound value as <name> = …; and every resource that reads the input reads var.<name> — bare where the input is the whole value (labels = { cost_centre = var.cost_centre }), inside a template where text holds it (project_id = "${local.interface_static.customer_shortname}-shop-${var.stage}"). A google_project whose id reads an input gets a provider alias that reads it too. A team working in OpenTofu alone edits terraform.tfvars, or passes -var, and the HCL follows; the Satz file is unchanged.
• Bound two ways. A using document's params { … } binds a pack's input as it binds any param — a thin estate, params { cost_centre = "4711" } use "simple-project.satz", is the committed form. satz transpile <template> --input cost_centre=4711 (repeatable; --plan and --apply run on the result) binds one for the run, winning over every file: a string is taken as written, a number, a bool or a list read as Satz writes one (--input regions='["europe-west3"]'), checked against the input's kind. A name no file declares in an inputs block is refused, listing the inputs.
• An input decides no structure. Refused, each at its line: an input read in a key or a label (a Terraform resource name), in a grant's member, role or scope (a binding's address derives from them), as the list of an each or the param of a when (they decide what the estate holds), in an export (an interface carries values), in a question (a reader binds an input, nobody is asked), in a request point, in an action's args, in a suppress, in one of satz's own keys ("import-id", private, lifecycle, provider, project_service — satz reads those, not the plan), in the terraform block (a backend takes no variable), and by a param (x = "{cost_centre}": the param would fix the example value where the HCL reads the variable). The providers block may read one.
• A pack's inputs are its contract in the canonical form: an input's default or its being an input moving is a pack change, and the pack's page lists its inputs with their examples and descriptions.

6.4 Blocks, entries and resources

block   := KEY [ NAME ] "{" { entry } "}"
entry   := KEY "=" value                  attribute
         | KEY "{" { entry } "}"          nested mapping
         | KEY NAME "{" { entry } "}"     named map entry
         | "use" STRING [ … ]             include inside this mapping
         | "each" IDENT "by" IDENT "{" { entry } "}"
                                          one labelled body per entry of a list param
KEY     := IDENT | STRING                 (a string key may interpolate)
NAME    := IDENT | STRING
value   := STRING | NUMBER | true | false | IDENT
         | "[" [ value { "," value } [ "," ] ] "]"
         | "{" { entry } "}"

List items are separated by commas, newlines or nothing at all — the comma is optional and a trailing one is allowed; satz fmt writes commas.

The resource types are the ones the provider schemas declare, matched exactly: google_org_policy_policy, google_folder, google_project. A key the loaded schemas do not know is a hard error. That applies to types nested inside a google_project { … } or google_folder { … } body as well, which are otherwise indistinguishable from a nested attribute block such as labels { … } — the schema is what tells the two apart.

The keys inside a resource body are the schema's too, level by level: an argument or block the provider does not have is a parse error naming the file, the line and the key. A block's own body is checked the same way (spec { … } of an org policy, condition { … } under its rules); what an attribute carries is a value, so the keys of a labels map are the estate's own. Ten keys are satz's rather than the provider's and are written in any body they belong to:

The only bare block keywords are Satz's own: estate, pack, params, terraform, providers, use, suppress, claim, question, action, notice, offers, hcl, export, interface, private, request — and each, an entry of a resource type map (§6.4). private = true inside a body is the table's attribute, not the statement. terraform and providers are blocks and use also stands inside a block (§6.9); the rest are statements, written at the top level of a file, and an error as the key of a block anywhere else.

Simple — one org policy:

google_org_policy_policy {
  "compute-managed-requireOsLogin" {
    name   = "compute.managed.requireOsLogin"
    parent = "organizations/{customer_organization_id}"
    spec {
      rules = [{ enforce = "TRUE" }]
    }
  }
}

resource "google_org_policy_policy" "compute_managed_requireOsLogin" {
  provider = google.google
  name = "organizations/123456789012/policies/compute.managed.requireOsLogin"
  parent = "organizations/123456789012"

  spec {
    rules {
      enforce = "TRUE"
    }
  }
}

The label has a hyphen, so it is quoted; the address has an underscore, and that address — google_org_policy_policy.compute_managed_requireOsLogin — is what a claim names.

A policy on a custom constraint names it the same way — name = "custom.cisCloudSqlDeletionProtection" — and when the estate declares that constraint (google_org_policy_custom_constraint with the same name), the emitted policy carries depends_on on it, so the apply creates the constraint first: the API refuses a policy on a constraint that does not exist yet.

The policies on one parent apply one at a time. The Org Policy API refuses a write to a parent's policies while another is in flight (409 CONCURRENT_POLICY_CHANGES), and tofu writes ten resources at once. So every google_org_policy_policy carries depends_on on the policy before it on the same parent, in address order — whichever pack or file declared it. Policies on different parents, and every other resource, still apply in parallel; depends_on changes no plan.

Nested blocks — a bucket with a nested block, a single block, and a repeated block:

google_storage_bucket {
  audit_logs {
    name                        = audit_bucket_name
    location                    = "EU"
    uniform_bucket_level_access = true
    versioning { enabled = true }
    retention_policy { retention_period = 34560000 }
    lifecycle_rule = [
      {
        action { type = "Delete" }
        condition { age = 730 }
      },
      {
        action { type = "SetStorageClass" storage_class = "COLDLINE" }
        condition { age = 90 }
      },
    ]
  }
}

resource "google_storage_bucket" "audit_logs" {
  provider = google.google
  name = "acme-audit-001"
  location = "EU"
  uniform_bucket_level_access = true

  versioning {
    enabled = true
  }

  retention_policy {
    retention_period = 34560000
  }

  lifecycle_rule {
    action {
      type = "Delete"
    }

    condition {
      age = 730
    }
  }

  lifecycle_rule {
    action {
      type = "SetStorageClass"
      storage_class = "COLDLINE"
    }

    condition {
      age = 90
    }
  }
}

A repeated block is a list of objects. lifecycle_rule { … } written twice in one body is an error naming both lines. The list form is the only one. Resource-type maps (google_…) may repeat — two google_org_policy_policy { … } groups in one file are one map, folded by address.

google_cloud_identity_group is a Satz abstraction that shares a Terraform type name: it is expanded into a group resource (deriving group_key, parent = customers/<id> and the discussion_forum/security labels) rather than passed through. Every group block also carries lifecycle { ignore_changes = [initial_group_config] } (merged with a lifecycle you declare): initial_group_config is create-only and a live group does not report it, so without this an adopted group would plan as "must be replaced" — destroyed and recreated with its memberships.

each — one labelled body per entry of a list

params {
  event_topics = [
    { name = "orders" retention = "86400s" },
    { name = "billing" retention = "604800s" },
  ]
}

google_pubsub_topic {
  each event_topics by name {
    name                       = "{customer_shortname}-{each.name}"
    project                    = infra_project_name
    message_retention_duration = each.retention
  }
}

each <list param> by <field> { … } stands inside a resource type map — a type's map, google_folder { … } or google_project { … }, at the top level or in a folder's or a project's body — and writes one labelled body per entry of the list. The label is the entry's <field>; in the body, {each.x} in a string or a key is the field's text and a bare each.x is its value, a list or an object included. The example writes google_pubsub_topic.orders and google_pubsub_topic.billing: the HCL two hand-written bodies give, with no for_each in it, so adoption, claims, attach points and the interface read them as any other resource. Resources nested in the body are expanded with it; a label that must differ per entry is a quoted key, "{each.name}_iac" { … }.

each <list> by <field> when <field> { … } writes the body only for the entries that carry the second field with a value: an entry without it, or with "", an empty list or object, or false, is skipped. when not <field> writes it for exactly those entries. Two each over one list, one when and one when not, write every entry once — a body that names a resource only some entries have, beside one that names none:

google_pubsub_subscription {
  each event_topics by name when subscription {
    name    = "{each.subscription}"
    project = infra_project_name
    topic   = "${{google_pubsub_topic.{each.name}.id}}"
  }
}

A field an entry may leave out takes a default from the list's request point, defaults = { <field> = <value> } (§6.17), so a body reads it from every entry.

The list is the param as the compile sees it, a pack's contributes_<param> entries included (ADR 0051), so a project's or a pack's entry expands like the estate's own. A label is the entry's field, never its place in the list: reordering the list moves nothing, and renaming an entry's label moves that resource, as renaming a written label does. A folder's or a project's label reaches the HCL with - as _ (§2.2), so payments-app is the address google_project.payments_app.

Refused, at the each line: a list param no file declares, a param that is no list, an entry that is no object, one without the field or whose field is no label (a letter, then letters, digits, _ and -), two entries with one label, {each.x} of a field the entry lacks or of a list or an object inside a string, a use or a second each inside the body, each in a resource body, when with no field after it, and {each.x} outside an each. At the top level of a file each writes interfaces, not resources (§6.17). A label an each writes that the map also writes by hand is one address declared twice. each without by, or each { … }, is a label named each.

6.5 IAM grants

Grant resources take a member → roles shape. The member is the key, usually interpolated; a role is a string, or an object when it carries a condition:

google_organization_iam_member {
  "group:gcp-org-admins@{customer_domain}" = [
    "roles/resourcemanager.organizationAdmin",
    "roles/iam.organizationRoleAdmin",
  ]
  "group:gcp-auditors@{customer_domain}" = [
    {
      role = "roles/storage.objectViewer"
      condition {
        title      = "audit-objects-only"
        expression = "resource.name.startsWith(\"projects/_/buckets/x/objects/y\")"
      }
    },
  ]
}

resource "google_organization_iam_member" "iam_group_gcp_auditors_example_com_96115764c9f71ca9" {
  role = "roles/storage.objectViewer"
  member = "group:gcp-auditors@example.com"
  org_id = "123456789012"

  condition {
    title = "audit-objects-only"
    expression = "resource.name.startsWith(\"projects/_/buckets/x/objects/y\")"
  }

  provider = google.google
}

resource "google_organization_iam_member" "iam_group_gcp_org_admins_example_com_3fb0828564be6711" {
  role = "roles/iam.organizationRoleAdmin"
  member = "group:gcp-org-admins@example.com"
  org_id = "123456789012"
  provider = google.google
}

resource "google_organization_iam_member" "iam_group_gcp_org_admins_example_com_21d2774f810ee5df" {
  role = "roles/resourcemanager.organizationAdmin"
  member = "group:gcp-org-admins@example.com"
  org_id = "123456789012"
  provider = google.google
}

One resource per (member, role, condition). org_id comes from customer_organization_id; inside a google_project { … } it is project = google_project.<label>.project_id and a per-project provider alias instead. The condition is hashed into the address, so the same role to the same member under two conditions is two resources. Emission order is by address, not by source order.

A member that names a service account the estate declares waits for it. When the member is serviceAccount:<account_id>@<project>.iam.gserviceaccount.com of a google_service_account in the same estate, the grant carries depends_on = [google_service_account.<label>], so the apply creates the account before the grant and destroys the grant before the account. Without it tofu runs both at once: the API refuses a member that does not exist yet, and an account deleted first leaves deleted:serviceAccount:… bindings behind. A group membership whose member key names such an account waits for it the same way.

A member that names a group the estate declares waits for it the same way. When the member is group:<key>@<customer_domain> of a google_cloud_identity_group in the same estate, the grant carries depends_on = [google_cloud_identity_group.<label>], and so does a membership whose member key names that group. Without it a fresh organisation fails on apply: the grants run beside the group creations, the IAM API refuses a member that does not exist yet, and the first refusal stops the groups still queued from being created at all.

A resource waits for the service that enables the API it needs. Every resource type satz can emit is served by an API (google_billing_budget by billingbudgets.googleapis.com, google_monitoring_alert_policy by monitoring.googleapis.com), and the emitted resource carries depends_on on each google_project_service in the estate that enables one — bounded to the two projects that can matter: the project the resource lives in, and the infra project the default provider bills its calls to. google_project_service itself is never ordered behind another service, and no edge is added into a service block's own dependency closure, so the project a service is declared on and the folder above it never wait for it. Without the ordering tofu runs both at once and the apply dies on an API that was about to be switched on. A resource whose API no google_project_service enables gets no edge — the compile reports that instead, because a dependency on nothing is not a thing.

The API has to be on the project the call is BILLED to. The estate's google provider carries user_project_override = true with billing_project = infra_project_name, so Google requires the service enabled on the infra project whatever the resource's own scope is — a budget hangs off the billing account and an org policy off the organisation, and both still need their API there. A resource written inside a google_project { … } is served by that project's alias, which is billed to the project itself, so its API has to be on that project. The project's own project_service entries are served by the provider around the project, so serviceusage.googleapis.com for them belongs on the infra project. The compile checks each API on the project the resource's provider bills to, read from the emitted providers.tf, against that project's project_service list; a provider that names no billing_project is named in a note and its resources are not checked.

Every *_iam_member type takes the member map. The organisation's scope comes from customer_organization_id, a project's or folder's from the node the map is written in, and every other type writes its scope in the map — one key that cannot be a member, because a member is always <type>:<value> (or one of the two reserved forms allUsers and allAuthenticatedUsers):

google_storage_bucket_iam_member {
  bucket = "${{google_storage_bucket.audit_logs.name}}"
  "group:gcp-auditors@{customer_domain}" = [
    "roles/storage.objectViewer",
  ]
}

google_service_account_iam_member {
  service_account_id = "${{google_service_account.onboarding.name}}"
  "serviceAccount:{svc_iac_account}@{infra_project_name}.iam.gserviceaccount.com" = [
    "roles/iam.workloadIdentityUser",
  ]
}

The scope namespaces the grant, so a second map for a second bucket is a second grant even when the member and role are identical; and it enters the emitted label, so the two never collide. One scope per map — repeat the map for the next one. Order inside the map does not matter: the scope is read before the members. A misspelt scope attribute is a compile error naming the type's real one, and a scope on a type that already has one (org_id on an organisation grant, project on a map inside a project) is refused. google_billing_account_iam_member is the exception: its billing_account_id is estate-wide, pinned once and defaulting to billing_account_infra, not per-map.

each inside a grant map writes one map per entry of a list param: the scope attribute and the member keys read the entry ({each.<field>} in a key or a string, a bare each.<field> as a value), and a list param stands for the roles. The grants take their addresses from the scope and the members, so two entries that name one scope and one member merge into one grant; the entry's label names nothing. The showcase grants a group on every topic of event_topics with one map:

google_pubsub_topic_iam_member {
  each event_topics by name {
    topic = "${{google_pubsub_topic.{each.name}.id}}"
    "group:gcp-developers@{customer_domain}" = [
      "roles/pubsub.subscriber",
    ]
  }
}

The same grant as a labelled resource is equally valid, and is the form to use for a single edge or when the scope differs per member:

google_storage_bucket_iam_member {
  audit_viewer {
    bucket = "${{google_storage_bucket.audit_logs.name}}"
    role   = "roles/storage.objectViewer"
    member = "group:gcp-auditors@{customer_domain}"
  }
}

Memberships stay out of packs: packs define groups, humans grant membership.

6.6 Folders and hierarchy

Nesting is the parent reference — parent and folder_id follow from the block a resource stands in:

google_folder {
  workloads {
    display_name = "Workloads"
    google_folder {
      team_alpha {
        display_name = "Team Alpha"
        google_project {
          alpha_prod {
            name       = "{customer_shortname}-alpha-prod"
            project_id = "{customer_shortname}-alpha-prod-001"
            labels { env = "prod" }
          }
        }
      }
    }
  }
}

resource "google_folder" "workloads" {
  display_name = "Workloads"
  parent = "organizations/123456789012"
  provider = google.google
}

resource "google_folder" "team_alpha" {
  display_name = "Team Alpha"
  parent = google_folder.workloads.name
  provider = google.google
}

resource "google_project" "alpha_prod" {
  project_id = "acme-alpha-prod-001"
  name = "acme-alpha-prod"
  provider = google.google
  folder_id = google_folder.team_alpha.name
  labels = {
    "env" = "prod"
  }
}

Read the two { } bodies inside alpha_prod against each other: google_folder { … } is a schema type, so it emits a resource; labels { … } is an attribute, so it emits labels = { … }. Same syntax; the schema decides.

A project may say its parent instead of standing in it (tests/smoke/yaml/showcase.satz, "a project whose parent is SAID"):

params {
  archive_project_folder = "google_folder.infra.name"
}

google_project {
  archive {
    name       = "corp-archive"
    project_id = "{customer_shortname}-archive-001"
    folder_id  = archive_project_folder
  }
}

resource "google_project" "archive" {
  project_id = "corp-archive-001"
  name = "corp-archive"
  provider = google.google
  billing_account = "012345-6789AB-CDEF01"
  folder_id = google_folder.infra.name
}

folder_id takes a reference to a folder the estate declares (google_folder.<label>.name) or the id of one that already exists ("123456789012"), and org_id takes the organisation's id. A value that is empty says nothing: the node the block stands in decides, which at the top level is the organisation. That is how a pack carries its own parent in a param — the default says nothing, and an estate that names a folder gets the same project wherever the pack's use line stands.

6.7 Adoption of existing resources

"import-id" records the live id so the tool adopts rather than creates. It is the only adoption surface in the language — the result of resolving a live resource, declarative and visible in tofu plan — and it is honoured on every resource the compiler emits:

google_folder {
  workloads {
    "import-id"  = "folders/123456789"
    display_name = "workloads"
    google_project {
      infra {
        "import-id" = "acme-infra-001"
        project_id  = "acme-infra-001"
        project_service = [
          "logging.googleapis.com",
          { service = "storage.googleapis.com" "import-id" = "acme-infra-001/storage.googleapis.com" },
        ]
      }
    }
  }
}

google_organization_iam_member {
  "group:gcp-org-admins@{customer_domain}" = [
    "roles/viewer",
    { role = "roles/browser" "import-id" = "123456789012 roles/browser group:gcp-org-admins@example.com" },
  ]
}

google_cloud_identity_group {
  gcp_auditors {
    "import-id" = "groups/00abc"
    member = [
      "user:a@{customer_domain}",
      { id = "user:b@{customer_domain}" "import-id" = "groups/00abc/memberships/111" },
    ]
  }
}

Every "import-id" becomes one import { to = <address> id = "…" } block in hcl/imports.tf, addressed exactly as the resource is emitted (hashed labels for bindings and memberships included), and is stripped from the resource body. Where the resource is an entry rather than a block — a role in a grant list, a service in project_service, a member of a group — the entry takes its object form and carries the id there. An IAM binding declared with and without an id (a pack's grant that the estate adopts) is one resource; two different ids for the same binding is an error.

You rarely write these by hand: satz adopt <estate> resolves the live ids of everything the estate declares — folders by display name under their parent, groups by email, org policies by constraint (activating managed constraints with --activate), any other GCP-assigned id through Cloud Asset Inventory under the resource's own scope on the row's match_on attributes (contacts by email, alert policies by display name), user-chosen ids from the import_id templates in presets/import-config.yaml, IAM grants only when the live IAM policy of what they are granted on holds them — and --execute writes them back: an "import-id" line into a block, the object form into a list entry. A grant the live policy does not hold is created by apply and gets no id. Derived ids are written too; tofu plan verifies each through its import block. It does not rewrite an entry it cannot find in the source (an interpolated member), and does not edit a pristine pack — packs are upstream-owned, so their resources come back as hints (--execute --import, or fork the pack). A resolution with more than one live candidate is reported as ambiguous and left for you to pin.

6.8 Estate configuration blocks

terraform and providers are configuration, not resources. terraform is required — an estate without it does not compile (Missing 'terraform' block). A backend may list both local and gcs; the emitter writes the ONE that deployment_mode selects ("local" / "cloud", see the migrate command; an estate with no deployment_mode is "local"), never both. Any other value is an error at the line that binds it, and the compile refuses. So is "cloud" without a value for svc_iac_account or infra_project_name: cloud mode runs as the account the two name, and the error names the one missing. The mode also decides which identity the estate's live commands run as, so whoami, migrate and every command that runs as the estate refuse the same value with the same reason:

terraform {
  backend {
    local { path = "terraform.tfstate" }
    gcs {
      bucket = infra_bucket_name
      prefix = "hcl/state"
    }
  }
}

providers {
  "google" {
    project               = infra_project_name
    region                = default_region
    alias                 = "google"
    user_project_override = true
    billing_project       = infra_project_name
  }
}

Every google_project gets a provider alias. Beside the blocks the estate writes, the emitter adds one provider "google" per project entity, aliased project_<label>, and every resource written inside that google_project { … } carries provider = google.project_<label>. It is the estate's google provider scoped to that project: the same region the estate's google block names — an estate whose block names none gets an alias that names none, and a regional resource in it writes its own — the same impersonate_service_account in cloud mode, and the project itself as project and as the quota project (user_project_override = true with billing_project = <that project>), so the APIs those resources need are the ones enabled on the project they live in.

6.9 use — composition

use "presets/cis/CIS-GCP-Foundation-4.0.satz" # a pack that carries its own types
google_essential_contacts_contact { use "presets/essential-contacts-organization.satz" } # inside a map
use "presets/essential-contacts-organization.satz" as google_essential_contacts_contact # as: same thing
use "showcase-optional.satz" when want_optional # conditionally

A use stands at the top level of a file, in google_folder { … } or in a resource type map. The position decides what the used file's entries are read as and what scopes the resources it declares:

use "…" as google_x is the third row written flat: the file's entries are the content of a google_x map standing where the use stands. It is valid at the top level and in google_folder { … }; inside a resource type map the map's type is the key, and an as naming another type is an error. google_project { … } takes projects and no use.

The body of a folder and the body of a project hold the estate's own resources, and take no use. A pack is used at the top level, where it declares the same resources whatever else the estate holds; a pack that creates a project names the folder that project is created in with a param of its own (logsink_project_folder, mdc_mgmt_project_folder). A use in a node's body is refused, naming the node and the param to bind:

`use "presets/monitoring/organization-audit-logsink.satz"` stands in the body of `google_folder.infra_folder`, which holds the estate's own resources — a pack is used at the top level of a file. Move the line to the top level. A pack that creates a project names the folder it is created in with a param of its own — `logsink_project_folder` in `presets/monitoring/organization-audit-logsink.satz`, `mdc_mgmt_project_folder` in `presets/integrations/microsoft-defender-for-cloud.satz` — so bind that param to `google_folder.infra_folder.name` in the estate's `params { … }`. Every other pack emits the same resources wherever its line stands

A file declares no kind. It is judged by whether its entries fit the position of its use: a pack that declares its own resource types — the CIS baseline and its extensions, most of the library — is used at the top level, and a file that is a bare list of labels, like the contacts pack above or showcase-policies.satz, is used inside the map of its type. An entry that does not fit is an error at the use line, naming the entry's line in the used file:

use "presets/cis/cmek.satz" inside `google_folder { … }`: presets/cis/cmek.satz:58 does not belong there — `google_org_policy_policy { … }` opens a map of its own, and directly inside `google_folder { … }` every key is a name — it is read as a folder named `google_org_policy_policy`. A file used inside `google_folder { … }` holds named folders. This one declares its own resource types, so it is written bare, at the top level: `use "presets/cis/cmek.satz"`

Each pack states its own line in its header comment, and presets/docs/ prints it.

The statements of a used file reach the estate from every position. Its params join the estate's parameter namespace, where the estate's own binding wins; its questions go to the interview; its claims to the compliance plane; its notices and actions join the estate's; its hcl blocks pass through to main.tf beside the resources; its exports, interfaces, request points and offers entries join the estate's after the use … when guard. None of them is emitted as part of the map the use stands in — a bare list with a params block and a question is the content of a resource type map, and the map receives its labelled bodies alone. A file that holds statements and no entry (presets/estate-core.satz, presets/estate-map.satz) is used at the top level; inside google_folder { … } or a resource type map it is refused, because it brings nothing that position takes. suppress and private are read from the estate's own file: a used file that carries one is refused.

An organisation-level resource type is written at the top level of a file, and reaches the organisation from wherever that file is used. A folder, a project, an organisation grant, a Cloud Identity group and a billing grant each hang off something above the project — the organisation, a folder, the Cloud Identity customer, the billing account — so the position of the use does not place them. That is what lets ONE file declare a project together with the groups that go with it:

// team-platform.satz
google_project {
  acme_platform_001 {
    project_id      = "acme-platform-001"
    billing_account = billing_account_infra
  }
}

google_cloud_identity_group {
  "platform-admins" { display_name = "Platform Admins" }
}

google_organization_iam_member {
  "group:platform-admins@example.com" = ["roles/monitoring.viewer"]
}

use "team-platform.satz" creates the project under the organisation, and the group and the grant reach the organisation and the Cloud Identity customer. To create the project in a folder, the file gives it a folder_id — a param of the pack, bound by the estate to google_folder.<label>.name. A resource whose type takes a project lands in the project it stands in — an org policy written inside a project's body gets parent = "projects/<id>".

The same type written INSIDE a project's body is refused. A project is the bottom of the resource hierarchy, so nothing above it is placed by standing in its body; written there it would reach the organisation anyway, which reads as "in this project" and is not:

`google_organization_iam_member { … }` stands in the body of a `google_project`, and it belongs to the organisation — not to the project. It is written at the top level of a file, the file that declares the project included: one file declares a project together with the organisation-level resources that go with it, and those reach the organisation from wherever that file is `use`d

A folder's body takes them, because a folder has children: a group or an organisation grant written in one reaches the organisation exactly once, however many folders declare it.

A statement is written at the top level of a file. Directly inside a resource type map, google_folder { … }, google_project { … }, or the body of a folder or a project, a block whose key is a statement keyword is an error (a use is the one statement that is also an entry, and stands where §6.9 says):

`params` is a Satz statement: it is written at the top level of a file, where it goes to the estate's parameter namespace. Directly inside `google_essential_contacts_contact { … }` it is read as a resource `google_essential_contacts_contact.params`. Move it to the top level of the file; one that really is called `params` is written quoted, `"params" { … }`

The same holds for a resource type map written directly inside a map of names (google_x { google_y { … } }, google_folder { google_x { … } }): there every key is a label or a folder name, so the map is refused. Nested blocks of a resource's own body are the provider's — action { type = "Delete" } inside a lifecycle_rule is an attribute block, not the action statement.

• Path is a plain string, never interpolated. Resolved relative to the using file first, then the configured include_dirs.
• when <param> — the file is pulled in only if the param is truthy. A skipped file contributes nothing: no resources, no params, no claims, no questions.

A use cycle is an error naming the chain; when on a param no file declares is an error, not false; an attribute at the top level of a used file is an error.

In the showcase: showcase-pack.satz declares pack_bucket_location = "EU" and a bucket that uses it; the estate binds pack_bucket_location = "europe-west3" and uses the pack bare, so the bucket emits with europe-west3 (remove the estate's param and it emits "EU"). showcase-policies.satz is a bare list of three policy labels, keyed by use "showcase-policies.satz" as google_org_policy_policy; one of the three is then removed by suppress (§6.10) and one is the subject of a deviates claim (§6.11). showcase-optional.satz sits behind when want_optional, declared false, and contributes nothing — the smoke run asserts its bucket is absent.

Composition is a fold: two files may contribute to the same resource map and the results merge. Two files defining the same address differently is a conflict and a hard error naming both source locations.

6.10 suppress — the subtractive channel

An estate declines something a pack provides, without forking the pack:

suppress google_org_policy_policy "compute-managed-requireOsLogin"
suppress google_organization_iam_member "group:sec@{customer_domain}" role "roles/browser"

• Type is the full Terraform type name; the label may interpolate.
• role "<role>" narrows the suppression to one edge of a grant instead of the whole member.
• A grant inside a folder or project is addressed by its node: a bare member ("group:x@…") suppresses that member on EVERY node that grants it; a node-qualified label ("shared/prod::group:x@…", the folder/project labels joined by /) suppresses it on that one node. A grant that writes its own scope is addressed the same way, by that scope: suppress google_storage_bucket_iam_member "bucket=acme-audit::group:x@…".
• role on an address that is in conflict (⊥) is an error: suppress the whole member, or resolve the conflict.

Against the estate above, the first line removes the policy from main.tf and nothing else changes. Suppressions apply before conflict detection, so suppressing a conflicted address resolves the conflict.

A suppression that matches nothing is a hard error:

suppress google_org_policy_policy "compute-managed-noSuchPolicy" matches nothing — stale suppression (typo or upstream rename)

When upstream renames or removes a resource, every estate that suppresses it fails on the next transpile, so the stale line is removed rather than kept.

6.11 claim — the compliance plane

Claims are language syntax, read directly from the source by require and report-compliance. They leave no trace in main.tf.

claim "cis-gcp" "4.0" "1.4" implements {
  resources = [
    "google_org_policy_policy.iam_managed_disableServiceAccountKeyCreation",
    "google_org_policy_policy.iam_managed_disableServiceAccountKeyUpload",
  ]
  interpretation       = "Service account keys cannot be created or uploaded."
  duty_rotate_existing = "Existing user-managed keys must be removed by hand."
  gcloud_check = [
    "gcloud org-policies describe iam.managed.disableServiceAccountKeyCreation --organization=ORGANIZATION_ID --effective",
  ]
  risk = "A user-managed service account key is a long-lived credential that works from anywhere once it is copied out of the platform."
}

claim FRAMEWORK VERSION CONTROL COVERAGE "{" { claim-entry } "}"
COVERAGE    := "implements" | "contributes" | "deviates"
claim-entry := "resources" "=" "[" { STRING } "]"
             | "interpretation" "=" STRING
             | "reason" "=" STRING            (deviates only, required)
             | "duty_" IDENT "=" STRING
             | "gcloud" "=" "[" STRING { "," STRING } "]"
             | "gcloud_check" "=" "[" STRING { "," STRING } "]"
             | "risk" "=" STRING

• The three header strings are plain — no interpolation; control ids are static.
• resources are emitted Terraform addresses. A claim whose witnesses are not emitted is a broken claim (‼), never reported as satisfied.
• An org policy's verdict is its UNCONDITIONAL rule. A conditional rule is an exemption — "enforced everywhere except where this tag is bound" — and is reported beside the verdict rather than replacing it. A policy with several unconditional rules, or a list constraint, yields no verdict at all.
• A claim asserts what its witnesses DO. An implements claim naming an org policy that carries enforce = "FALSE" or spec { reset = true } is a contradicted claim (‼): the witness exists and discharges nothing. A deviates claim naming a policy that enforces is contradicted the same way — it discloses a non-conformance the estate does not have. contributes asserts nothing about the value, and a policy whose effect has no single answer — a list constraint, several rules — is never contradicted.
• duty_<name> records a manual duty; underscores become hyphens in reports (duty_validate_then_lock → validate-then-lock).
• implements discharges the control; contributes is a necessary part.
• gcloud, gcloud_check and risk state the measure without satz: the gcloud commands that meet the control the way the claim's resources do, the commands that show whether it is met, and one sentence on what goes wrong without it. Each list holds one command per entry; a multi-line command, such as a heredoc that writes a policy file, is one triple-quoted entry. Placeholders are uppercase words — ORGANIZATION_ID, PROJECT_ID — because a claim's strings do not interpolate. An empty list is refused; a claim without a route leaves the attribute out. They emit nothing and decide no verdict: require and report-compliance carry them in the measures of each control, and a changed text never forks an estate's pack.

The catalog the claim is judged against is data (presets/catalogs/cis-gcp-4.0.yaml): control ids, this project's own paraphrases, and an automatability (technical / partial / organizational) — never framework prose, which is licence-restricted.

A duty is where the claim records what code cannot do. From the shipped pack:

claim "cis-gcp" "4.0" "4.4" implements {
  resources         = ["google_org_policy_policy.compute_managed_requireOsLogin"]
  interpretation    = "OS Login is required, so VM SSH access is governed by IAM rather than metadata keys."
  duty_existing_vms = "Enforcing OS Login can cut existing SSH access patterns; verify before enabling on an org with running VMs."
}

Until that duty is attested (§8), the control reads ◐ partial (open duty) — witnesses present, human step outstanding.

deviates — declining a control

claim "cis-gcp" "4.0" "4.4" deviates {
  resources     = ["google_org_policy_policy.compute_managed_requireOsLogin"]
  reason        = "A service here depends on metadata SSH keys; enforcing OS Login breaks it."
  duty_reassess = "Re-assess when that service supports OS Login."
}

reason is mandatory on a deviation and rejected on the other kinds. Leave it out and the compile stops:

claim … deviates: reason = "…" is required (a deviation is a disclosed decision, and the report carries the reason)

Witnesses are optional here — the resource may be present-but-not-enforcing, or absent because the estate suppressed it — but any witness the claim does declare must still be emitted, so deleting the policy outright reports a broken claim, not a deviation. A deviation renders as ⚠ with its reason, is counted separately, and does not fail the require gate. It outranks the claims it contradicts and can be declared by a pack fork or by the estate itself.

6.12 hcl — raw passthrough

hcl {
  resource "google_compute_address" "legacy" {
    name   = "legacy-ip"
    region = "europe-west3"
  }
}

hcl trust "reviewed 2026-08-24, provider gap for static IPs" {
  resource "google_compute_address" "legacy_trusted" {
    name   = "legacy-ip-2"
    region = "europe-west3"
  }
}

The body is captured verbatim, is never interpolated, and bypasses the fold, so the compliance plane cannot see into it. Every transpile says so:

warning  hcl-passthrough  satz/main.satz:14
    raw HCL passthrough (4 lines) emitted verbatim — opaque to the compliance plane; no claim
    can cover it. Add `hcl trust "<reason>" { … }` once reviewed.

info     hcl-passthrough  satz/main.satz:21
    raw HCL passthrough (4 lines) — trusted: reviewed 2026-08-24, provider gap for static IPs

1 warning, 1 info

and so does the output:

# --- raw HCL passthrough from satz/main.satz:21 ---
# Opaque to the compliance plane: no claim covers what is written here.
# trusted: reviewed 2026-08-24, provider gap for static IPs
resource "google_compute_address" "legacy_trusted" {
  name   = "legacy-ip-2"
  region = "europe-west3"
}

The compiler enforces the opacity: the compliance plane reads the emission manifest — the resources the compiler itself built — never the rendered main.tf, and the passthrough is appended to the text after emission. A resource that exists only inside hcl { … } therefore deploys but is not a witness; a claim that names it reports ‼ broken claim, exactly as if the resource were missing.

Running a script from inside the apply

Because the body is verbatim Terraform, the passthrough is also the way to put a script in the dependency graph — the one thing action cannot do:

hcl trust "SCC enablement has no provider resource (google 7.14.1)" {
  resource "terraform_data" "scc_services" {
    triggers_replace = [var.customer_organization_id]
    provisioner "local-exec" {
      command = "${path.module}/../presets/scc/scc-enable-all.sh --organization ${var.customer_organization_id} --apply"
    }
  }
}

This orders the script against satz-emitted resources through ordinary HCL references, which nothing else here can. It also has costs: tofu plan cannot show what the script will do, a failure taints state and has to be cleaned up by hand, the script runs on whichever machine runs apply, and the block is invisible to the compliance plane like any other passthrough. Use it only when a step has to happen between two resources in one apply; otherwise declare an action, which run-actions prints, selects by name and runs in the operator's terminal.

6.13 action — a step with no provider resource

Some cloud steps cannot be declared at all. Security Command Center service enablement is one: provider 7.14.1 has 35 google_scc_* / google_securityposture_* types and none of them is service enablement or tier activation, so no language satz compiles can express it. The step is still part of the deployment.

action names such a step, binds it to a script, and builds its arguments from the estate's own parameters:

action "scc-services" {
  reason       = "SCC service enablement has no provider resource (google 7.14.1)"
  run          = "scc-enable-all.sh"
  args         = ["--organization", "{customer_organization_id}"]
  execute_args = ["--apply"]
  phase        = "before-apply"
}

The library ships this action as a pack: use "presets/scc/scc-service-enablement.satz" binds it. The declaration above is that pack's, with its reason shortened.

Which phase, and what phase does not do

The two values answer one question: does this step have to happen before the estate exists, or after?

before-apply — a prerequisite. The step has to be true before the apply can succeed, so it cannot wait for it. Enablement is one: the SCC pack above turns the services on ahead of the resources that depend on them.

after-apply — the step needs what the apply created. It cannot run earlier, because the thing it operates on does not exist yet. A per-project setting with no provider binding is the plain case — it cannot be applied to a project the apply has not created:

action "seed-project-settings" {
  reason       = "the setting has no provider resource, and the project it targets is created by this estate"
  run          = "../scripts/seed-settings.sh"
  args         = ["--project", "{infra_project_name}"]
  execute_args = ["--apply"]
  phase        = "after-apply"
}

after-apply is the default, so the second form needs no phase line at all; write it when it helps a reader, and write before-apply whenever the step is a prerequisite.

What phase does not do: it does not run anything around satz apply. satz apply does not run actions and does not check that a before-apply action ran. The value orders the run (before-apply first, then declaration order) and selects with --phase before-apply|after-apply; the operator runs each phase around the apply:

satz run-actions estate.satz --phase before-apply --execute
satz apply
satz run-actions estate.satz --phase after-apply --execute

Nothing here runs while compiling. The output of transpile depends only on its sources, so the corpus snapshots, check-presets and the auto-fork transpile-identity check compare like with like, and compiling a cloned estate runs no script. An action is inert until satz run-actions is invoked.

An action emits nothing and can carry no claim. It is not in main.tf, not in the emission manifest, and no claim can name it — the same opacity hcl has, with execution on top. satz records that the step exists and never says what it did; nothing about an action reaches report-compliance.

Every compile of an estate that declares one says so, and unlike hcl trust, a reason does not downgrade the warning, because an action executes a script:

warning  action  presets/scc/enable.satz:12  scc-services
    `satz run-actions` will execute enable.sh — a pack declares it
      reason: SCC service enablement has no provider resource (google 7.14.1)

info     action
    --no-pack-actions ignores pack-declared actions, --no-actions disables all execution, `satz
    silence add action --reason "…"` leaves these findings out of the output.

1 warning, 1 info

A pack may declare an action, and the warning says when one did. The two switches exist because get-presets downloads packs from a public repository. A downloaded script arrives without its executable bit, and satz does not set it; the error names the chmod +x to run once the script has been read. A .py action needs no bit, because uv reads the file.

Names are unique across the estate. Two actions answering to one name is a hard error naming both files, the rule the ⊕ fold already applies to a repeated address. An action inside a pack that use … when switched off is never collected at all.

When an action runs, and how

Only satz run-actions executes one — not transpile, not plan, not apply. phase orders the run and selects with --phase; it does not make anything happen around an apply.

When run-actions does run, in this order:

1. The estate is compiled first. If it does not compile, nothing runs: the command lines are built from its params.
2. {param} resolves against the finished namespace. An unknown param is a hard error, never an empty argument.
3. The executable is located relative to the directory of the file that declared it, then against the include dirs — the same search a use path gets.
4. Every action is located and checked before any one is spawned — it exists, and it can run: a script satz spawns directly is executable, and uv is on PATH for a .py one. A missing +x on the fourth script stops the run before the first three change the organisation.
5. Each is spawned, in phase order (before-apply, then after-apply) and declaration order within a phase — the estate's own actions first, then use-visit order.
6. A non-zero exit stops the run and satz exits with that code. The remaining actions do not run.

Writing a script for an action

Write an action in Python, unless a shell script is genuinely simpler for the job. satz ships for Windows as well, and a .sh action is refused there before the spawn — the message names the bash … to run it by hand from Git Bash or WSL. A .py action runs on every platform, from one file.

What satz provides to a script:

Put the form that reads in args and the flag that writes in execute_args: run-actions --check then runs the script's own dry run, and only --execute lets it write. Whether the args form has side effects is up to the script; satz cannot see what a script does.

A script written to that contract. tests/smoke/scripts/showcase-action.py is this shape with a few extra echoes the smoke matrix asserts on, and CI runs it on every pull request and every push to main:

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///
import argparse
import os
import sys

# Dry run unless the estate's execute_args said otherwise. The flag is the
# script's own, not satz's: satz only decides whether to pass it.
p = argparse.ArgumentParser()
p.add_argument("--organization", required=True)
p.add_argument("--apply", action="store_true")
a = p.parse_args()

print(f"action {os.environ['SATZ_ACTION']} ({os.environ['SATZ_MODE']}) on organizations/{a.organization}")
if not a.apply:
    print("DRY RUN — re-run with --execute to write.")
    sys.exit(0)

# … the work. A non-zero exit here stops the whole run.

presets/scc/scc-enable-all.sh has the same shape — dry run by default, --apply to write, non-zero on any failed call. It lives under presets/ rather than scripts/ because get-presets downloads only presets/**, and the action must find its script in the estate's copy of the presets. See docs/housekeeping.md.

6.14 question — what to ask, and what the answer costs

A pack declares its params, its claims — and what a human must be asked before those params can be filled. Metadata: a question emits nothing, never enters the fold, and never reaches the emission manifest.

params {
  customer_shortname         = ""
  default_region             = "europe-west3"
  deploys_regional_resources = true
}

question customer_shortname {
  prompt   = "Short name identifying this customer"
  why      = "Project ids, bucket names and group prefixes derive from it, and those ids are globally unique."
  reversal = recreate
  blast    = none
}

question default_region {
  prompt    = "Which region should regional resources default to?"
  reversal  = state_surgery
  blast     = low
  recommend = "europe-west3"
  ask_when  = deploys_regional_resources // optional: only ask when that param is true
}

Two costs. reversal is what changing the answer does to the estate — edit, state_surgery or recreate. blast is what it does to the running organisation — none, low or high. They are independent: enforcing OS Login is one boolean to reverse and cuts every existing SSH path. An answer is only safely deferred when both are low.

why is required where reversal = recreate or blast = high, so that when satz refuses or warns it can quote the pack's own sentence rather than a generic one — the same rule that makes reason mandatory on a deviates claim.

An empty answer that means something. A question whose param may be "" says what "" means with empty = "…". The empty value is then an answer like any other: satz questions shows it with its meaning, satz interview offers it, --accept-defaults and satz_interview's accept_defaults bind it, and a bound "" counts as answered for the gate. Without empty, a "" the estate binds for a param whose pack default is also "" is a value nobody has given, and the question stays open. empty belongs to a question about one param; a choice's "none" is its empty answer.

params {
  team_folder_name = ""
}

question team_folder_name {
  prompt   = "Display name of a folder for the team"
  reversal = edit
  blast    = none
  empty    = "no team folder"
}

recommend is the answer the pack would give. The interview prints it where it differs from what is on offer; what Enter accepts, and what --accept-defaults binds, stays the params default — so a pack can recommend switching on a service that costs money without any bulk run switching it on.

A question must be declared in the file that declares its param. Questions are absorbed after the use … when guard, exactly like claims — so a question that gates a pack cannot live in the gated pack, or it would be invisible until the answer was already yes. satz refuses it at parse time.

An exclusive choice

params {
  group_model_flat  = true
  group_model_split = false
}

question oneof group_model {
  prompt   = "Which security-group model does this customer run?"
  why      = "Splitting network authority out later means a new group, membership moves and re-granted roles."
  reversal = state_surgery
  blast    = low
  required = true // exactly one, rather than at most one
  option group_model_flat { label = "Flat — network authority sits with project admins" }
  option group_model_split { label = "Split — a separate network-admins group" why = "For a distinct network team." }
}

The options name existing boolean params, so an answer set stays a plain param map and a question never becomes a second way to set a value. satz refuses two true branches, naming the choice and both params.

A choice that is not required has one more answer: none of its options. satz interview offers it as 0) none, the MCP tool satz_interview takes "none", and either binds every option false; while no option is on, none is what the choice offers. So a required choice needs two options and one that is not required needs one — the option and none are its two answers:

params {
  notice_pubsub = false
}

question oneof notice {
  prompt   = "How do the projects hear that a value changed?"
  reversal = edit
  blast    = low
  option notice_pubsub { label = "Pub/Sub — a message on a topic" }
}

required is checked at compile and only when the choice applies — a required choice whose ask_when param is false has no missing answer. satz questions never refuses a required choice with no branch set: it reports it as unanswered and blocking, which is what an interview needs in order to ask it.

Composition follows from that: a choice between two packs is two booleans plus the use … when that already exists.

Where they show up

• satz questions <estate> --format … --out <file> — every question its packs contribute with its state: answered when the estate's own params {} binds the param (accepting a default is an answer, written as the default), unanswered with the default the pack offers or blocking when none is possible, not-applicable when its ask_when is false. --unanswered is the worklist, --format markdown the decisions sheet and --format xlsx the workbook a customer fills in. Offline and schema-free: an interview happens before anyone runs update-schema.
• bootstrap and transpile --apply refuse while a question is unanswered; --dry-run and --plan warn. satz interview asks and writes the answers — satz interview.
• satz doc-packs gives each pack a Questions section.
• A question's prompt becomes the description of the generated variables.tf variable — the pack already wrote the one-line sentence.
• check-presets reports a pack whose questions changed as questions, not as drift: what the pack emits is byte-identical, so the estate is not forked, and the change — a recreate → edit downgrade included — is still listed. Questions are canonicalised separately from the body for that reason.

6.15 notice — the command a pack asks for once it is on

A pack that needs one step taken after it goes into an estate names it here. satz shows the notice when the pack is switched on, and keeps showing it until the estate binds the notice's param true.

pack showcase_pack version "1.0"

params {
  pack_bucket_location = "EU"
  pack_bucket_adopted  = false
}

notice pack_bucket_adopted {
  text     = "The bucket may already exist in the project — creating it again fails. Import what is live first."
  run      = "satz adopt <estate> --execute --import"
  severity = error
}

The binding is the acknowledgement. The pack declares the param false; the estate binds it true when the command has run, in its own params {} — the same record an answer is (§6.14, ADR 0006). Git says who and when, a second operator and CI read the same state, and there is no local file beside the estate.

A notice belongs in a pack, and its param is the notice's alone. It is declared in the same file, as false, and no question asks it — an acknowledgement is not a customer decision. The param is never emitted: it is in no variables.tf and no terraform.tfvars, so binding it moves nothing in the plan. satz pack-graph refuses a library where another pack declares or reads it, or where a notice sits on the day-0 pack or the map, which nothing switches on.

Where they show up

• When the pack is switched on — a yes in satz interview, satz add-pack, or merge-presets bringing the pack in — the notice is printed once, and the MCP tools satz_interview and satz_add_pack return it in notices.
• Until it is acknowledged the compile warns at the estate's use line of the pack — a notice finding whose subject is the param and whose fix: line is the pack's run, with the estate's file name where the pack wrote <estate> — and every command that writes to the organisation — transpile --apply, bootstrap, run-actions --execute, migrate — refuses while a severity = error notice is open. --plan and --dry-run compile, print the finding and go on.
• satz adopt --execute --import acknowledges the notices that name it when the run covers every resource type and nothing failed: it binds their params itself.
• satz packs lists each pack's notices with their state, and satz doc-packs gives a pack a Notices section.
• check-presets reports a pack whose notices changed as questions, not as drift: a notice emits nothing, so a reworded one never forks an estate.

6.16 offers — what the library offers an estate

presets/estate-map.satz — the map, pack estate_map — carries one offers entry per pack in the library. The entry says what an estate's line for that pack looks like and where it goes; the entries' order is the order the packs can be adopted.

offers "presets/essential-contacts-organization.satz" {
  when  = use_essential_contacts
  phase = "once the estate runs as the service account — one contact for Google's notices"
  block = "google_essential_contacts_contact"
}

offers "presets/monitoring/organization-audit-logsink.satz" {
  when  = use_audit_logsink
  phase = """once the estate runs as the service account — the audit archive, which every later
logging pack points at"""
}

offers "presets/cis/cloud-sql-dry-run.satz" {
  when     = cis_cloud_sql_hardening_dry_run
  excludes = ["presets/cis/cloud-sql.satz"]
}

An entry emits nothing and the compile never reads one. An offers entry anywhere but in pack estate_map is refused at parse time.

satz pack-graph reads the entries and writes presets/pack-graph.json: every library file as a node, and the edges between them. Most edges are derived from the packs — a param one pack reads or contributes to and another declares (data), a gate a pack declares for another (gate), an ask_when (asks), the options of one question oneof (excludes) — so requires and excludes on an entry name only what the packs cannot show, and pack-graph refuses a declared edge it derives. A data edge from a READ also puts the reading pack's line after the declaring pack's; one from a contribution does not, because a contribution is merged before the compile walks anything. Several requires on packs that exclude one another are one requirement: any of them meets it.

The estate commands read that file from the estate's presets_dir, and one pack logic answers them all (src/packs.rs). init and interview --create write the pack menu from it. satz packs reports every node as the estate has it: the gate's answer and default, the line — active, ungated (active without when <gate>), commented, absent, forked (naming the .local fork) or misplaced (outside the block the graph places it in) — whether the pack deploys, what it requires and what requires it; a use the graph does not know is unmanaged. satz add-pack and satz remove-pack switch a pack on or off by its gate or its path. A yes in the interview switches a line on as add-pack does, and merge-presets writes the lines the estate lacks from the graph of its pristine source. An active line of a gated pack that has no when is a compile finding naming the line to write (workflows). Every line satz writes goes where the graph's order puts it: after the line of the pack before it in the same place, inside the block the graph names, after the estate-core line — or, in an estate without one, after its top-level params.

A gate's value is the estate's own binding, else the default in the file that declares it while that file is used. What a pack needs is read from the edges: its requires are one requirement, each gate edge one, the map one when the map declares its gate, and each set of data params one. Any pack of a requirement meets it; a data requirement is also met when the estate binds the params the pack reads, or every param of the pack whose default reads them — the runner grant with ci_runner_service_account bound to a runner that another estate runs. An asks edge decides when a question is asked and is no requirement.

The compile reports, from the same logic: a gate the estate itself binds true whose line is commented or absent — skipping a line written by_hand, and counting a pack as used when an excludes neighbour on the same gate is. A default in the map or in a pack is the library's proposal and not this estate's answer, so a skeleton that has answered nothing compiles clean at every validation level and satz packs is where the proposals are read. Then: an active line of a gated pack without its when, where the gate is declared; a pack that deploys while something it needs is off; and, as an error before the fold, two packs on two gates that exclude one another both deploying — a dry-run twin beside its enforcing pack named as the decision it is. A compile that stops on unknown param adds the requirement that is off, inside the refusal itself, so the file and line it names stay with it and an editor marks that line. With no graph there, the compile notes it once and skips those checks.

check-presets reports a map whose entries changed like one whose questions changed: the map emits the same, so the estate is not forked, and the change is listed.

6.17 export and interface — what the estate publishes to the projects beside it

A project is an estate that depends on parts of another estate's interface. It has its own repository or folder, config, state and pipeline, and it may be maintained by a different team; it is written in HCL or in Satz. The estate whose interface it reads is the central estate. On this page and everywhere in satz's documentation and messages, "project" alone always means such an estate; a GCP project is always written "Google project" or google_project.

export names a value projects read; interface groups the ones one project reads. Each export is an output of the root module (hcl/outputs.tf, read with tofu output) and a value of the generated interfaces under interfaces/, beside hcl/ (workflows: projects beside the estate).

export "customer_domain"      = customer_domain description "The customer's primary domain"
export "infra_project_id"     = "${{google_project.infra.project_id}}" description "The infrastructure project"
export "infra_folder"         = "${{google_folder.infra.name}}" description "The infrastructure folder, folders/<number>"
export "infra_project_number" = "${{google_project.infra.number}}"
export "audit_bucket_url"     = "${{google_storage_bucket.audit_logs.url}}"
export "regions"              = [default_region, "europe-west4"]

export "folders" = all google_folder description "Every folder, by label"
export "buckets" = all google_storage_bucket

interface "audit" common {
  export "audit_bucket_name" = "${{google_storage_bucket.audit_logs.name}}" description "The audit log bucket"
}

interface "archive" {
  use interface "audit"
  export "archive_project_id"     = "${{google_project.archive.project_id}}" attach ["google_project_iam_member"] description "The project's Google project"
  export "archive_project_number" = "${{google_project.archive.number}}"
}

(tests/smoke/yaml/showcase.satz.)

• An export outside every interface block is a core export. Every interface carries it, so each project's own interface is complete on its own, and the interface core carries the core exports alone.
• An export inside interface "<name>" { … } belongs to that interface — and to every interface that uses it. The block holds export statements and use interface lines, and nothing else. The name is a folder name: lowercase letters, digits and -, starting with a letter; core and common are refused. An interface declared in two files is one interface, and their exports merge; one file declares it once.
• Common or one project's. An interface is common when the block says so — interface "<name>" common { … } — or when a pack declares it outside an each; core is common too. The common interfaces are the library: interfaces/common/ holds it alone, and every project's folder carries it whole. Every other interface is one project's own, and only that project's folder carries it. A common interface uses only common ones: one that uses a project's interface is refused, naming both, because every project's folder would carry that project's values.
• use interface "<name>" [when <param>], or `use interface ["", ""] [when ]`, inside an interface block puts the exports of the named interfaces into this interface too, and those of every interface they use in turn. A shared set — the network values a pack publishes as `interface "network"` — is declared once, and each project whose interface uses it receives it. `when` gates the line as it gates a pack line: a false param brings nothing, and a param no file declares is an error. The name is an interface some file of the estate declares, never a path, so no tool that reads `use ""` lines treats it as a pack. Refused: a name no file declares (listing those that are), `core` (every interface carries it), a cycle (naming the chain), and two exports of one name reaching one interface from two interfaces (naming both files). An interface of `use interface` lines alone is an interface of its own. The README's `From` column names the interface each value comes from; in the root module each export stays one output, `__` of the interface that declares it.
• The export's name is the output's name: lowercase letters, digits and _, starting with a letter, and no __. A project written in HCL reads it as module.satz.<name>, one written in Satz as "${{interface.<name>}}". An interface's export may not take a core export's name: every interface carries both, and the compile refuses it naming both files.
• The value is a param, a literal, a list of them, or a string that carries ${{type.label.attribute}} references to resources the estate emits. An object is refused. A reference names something the estate emits, or the compile refuses it at the export's line, listing the labels of that type that are emitted; ${{…}} that is not a type.label.attribute of a google_* resource is refused.
• all <resource type>, on one line, in place of a value publishes every resource of that type the estate emits, as one map keyed by satz's resource label (the <label> of <type>.<label>): a project reads module.satz.folders["infra"], and a new folder is a new key without a new export. Each value is the attribute presets/interface-lookups.yaml names for the type under all — a folder's name (folders/<number>, looked up), a Google project's project_id, a bucket's name, a service account's email, a network's or a topic's id — static where satz writes it, a lookup where the cloud knows it. A type the table has no row for is refused, listing the rows; a type the estate emits none of is an empty map. The README lists the map's keys. all <type> under <folder or project> (all google_project under google_folder.team_a) keeps the resources placed under that folder or project, at any depth — through folder_id, parent or project, by reference or by the project id — and refuses an address that is no folder or project of the estate. A resource whose body says private = true is left out of the map and out of everything written for a project, and an export whose value names it is refused: the state bucket and the IaC service account of the estate satz init writes carry it. private <type>.<label>, a statement of the estate's own file, does the same for any resource — a pack's too, without forking the pack; one the estate does not emit is an error, and a used file that carries one is refused. A label is a key projects index by, so a pack version that renames one is a breaking change for them.
• description "…" follows the value on the same statement and becomes the output's description and the README's.
• attach ["<resource type>", …] follows the value too, before or after the description, and makes the export an attach point: the attachment resource types a project may create in its own state against the exported object — a google_compute_shared_vpc_service_project on a host project, a google_access_context_manager_service_perimeter_resource on a perimeter, a google_<node>_iam_member on a node. A type presets/attach-points.yaml has no row for is refused, listing the rows. The compile refuses the estate's own authoritative form of a membership a project attaches to: a perimeter whose status.resources the estate sets or whose lifecycle does not ignore status[0].resources, and a google_<node>_iam_policy or google_<node>_iam_binding on the node a member grant attaches to. The README's capability table lists each export with what it takes; satz check-consumer holds a project's HCL to it, and a project estate's own compile holds its resources to it (workflows).

// Generated by satz v<version> from `showcase.satz` (estate `showcase`) — do not edit: …
interface "archive"

central {
  estate        = "showcase"
  organizations = ["organizations/123456789012"]
}

output "archive_project_id" {
  value       = "corp-archive-001"
  attach      = ["google_project_iam_member"]
  targets     = ["google_project.archive"]
  description = "The project's Google project"
}

output "infra_folder" {
  value       = "${{data.google_active_folder.infra.name}}"
  targets     = ["google_folder.infra"]
  description = "The infrastructure folder, folders/<number>"
}

lookup "data.google_active_folder.infra" {
  reads      = "google_folder.infra"
  permission = "resourcemanager.folders.list on the parent"
  arguments {
    display_name = "Infrastructure"
    parent       = "organizations/123456789012"
  }
}

managed "google_project.archive" {
  ids = ["sha256:b402f051c263375f95b33ce0ce55df688ebb77c5e09c8310e162fe56c3178989"]
  keys {
    project_id = "sha256:b402f051c263375f95b33ce0ce55df688ebb77c5e09c8310e162fe56c3178989"
  }
}

use "vendor/archive/archive/satz/interface.satz"

google_project {
  archive_work {
    name            = "corp-archive-work"
    project_id      = "corp-archive-work-001"
    folder_id       = "${{interface.infra_folder}}"
    billing_account = billing_account_infra
  }
}

google_project_iam_member {
  archive_readers {
    project = "${{interface.archive_project_id}}"
    role    = "roles/viewer"
    member  = "group:gcp-auditors@example.com"
  }
}

each event_topics by name {
  interface "{each.name}-events" {
    use interface "audit"
    export "topic" = "${{google_pubsub_topic.{each.name}.id}}" description "The project's Pub/Sub topic"
  }
}

request event_topics {
  key         = "name"
  fields      = ["name", "retention"]
  patterns    = { name = "[a-z][a-z0-9-]*" retention = "[0-9]+s" }
  description = "A Pub/Sub topic in the infrastructure project"
}

request projects: entry `payments` has `owner_group` = "payments-owners", which the request point's pattern `[^@: ]+@[^@: ]+` does not match

satz require cis-gcp-4.0 C0example.satz --config ~/estates/acme --format text --out -

require cis-gcp 4.0 — goal view for …/acme/satz/C0example.satz

  ◐ 1.1   Corporate login credentials only              — open duties: legacy-superseded, review-allowlist
  ✓ 1.4   Only GCP-managed service account keys         — google_org_policy_policy.iam_managed_disableServiceAccountKeyCreation, google_org_policy_policy.iam_managed_disableServiceAccountKeyUpload
  ✓ 2.2   Sinks for all log entries                     — google_logging_organization_sink.organization_audit_gcs, google_storage_bucket.org_audit_logs, google_storage_bucket_iam_member.org_audit_sink_writer
  ◐ 2.3   Retention on the log bucket                   — no implements claim included
  ✓ 3.1   Default network does not exist                — google_org_policy_policy.compute_skipDefaultNetworkCreation
  ◐ 4.4   OS Login enabled                              — open duties: existing-vms
  ✓ 5.2   Uniform bucket-level access enabled           — google_org_policy_policy.storage_uniformBucketLevelAccess

18 satisfied, 5 partial, 0 deviation(s), 0 unmet, 0 broken claim(s), 0 contradicted claim(s). Goal view judges the DECLARED estate; live verification is the evidence report.

  ⚠ 4.4   OS Login enabled                              — DEVIATION (CIS_GCP_Foundation_4_0) Deliberate: an operational service in this organisation depends on metadata SSH keys, which enforcing OS Login would break. The constraint is declared and managed here, with enforce = FALSE, so the decision is visible in the estate rather than absent from it. open: identify-service, reassess
  ⚠ 4.6   IP forwarding not enabled on instances        — DEVIATION (CIS_GCP_Foundation_4_0) Deliberate: workloads in this organisation require IP forwarding, so the constraint is declared and managed with enforce = FALSE rather than left undeclared. open: identify-workloads, reassess

7 satisfied, 3 partial, 2 deviation(s), 11 unmet, 0 broken claim(s), 0 contradicted claim(s). …
Deviations are disclosed decisions with a stated reason, not gaps — they do not fail this gate.

  ✗ 1.4   Only GCP-managed service account keys         — unmet. Provides: CIS_GCP_Foundation_4_0
  ✗ 2.2   Sinks for all log entries                     — unmet (no pack in the library provides it)

satz report-compliance cis-gcp-4.0 C0example.satz --config ~/estates/acme \
  --format markdown --out evidence/cis-4.0.md
satz report-compliance C0example.satz --config ~/estates/acme \
  --format markdown --out evidence/held-to.md

validate-then-lock:
  by:   "Jane Doe"
  date: "2026-08-20"
  note: "bucket lock applied after 30-day pipeline validation"

params {
  compliance_frameworks = ["cis-gcp-5.0", "iso27001-2022"]
}

unterminated interpolation '{custome'
empty interpolation {} (use {{}} for a literal brace)
newline in single-line string (use """ for multi-line)
unterminated block comment
malformed number `1.2.3`
unknown param 'no_such_param'
params: `a` is declared twice — line 3 and line 7; the second binding would be ignored, so delete the one that is not meant
a second `estate` header (f) — the file is already `e`
use ... as: given twice
`lifecycle_rule` is given twice in this block (first at line 12) — a repeated key would silently last-win; write a list (`lifecycle_rule = [ … ]`) or remove one
block `folder`: unknown resource type. Satz names Terraform types in full — write `google_folder`.
`x` is an attribute at the top level of the file — attributes live inside a resource block
pack header: `content` is not a header word — the header is `pack <name> [version "…"]`; delete `content`
`hcl` is a Satz statement: it is written at the top level of a file, never inside a block — move it out
use "presets/estate-core.satz" inside `google_essential_contacts_contact { … }`: that file holds no entry — only `export`, `params`, `question`, which reach the estate from any position. A file used inside `google_essential_contacts_contact { … }` holds labelled `google_essential_contacts_contact` bodies. Write this one at the top level of the estate: `use "presets/estate-core.satz"`
use "x.satz": x.satz:3 is a `suppress`, which is read from the estate alone — in a used file it is never applied. Write it in the estate, or take the resource out of the used file
use … when want_cs: unknown param `want_cs` — a `when` on a param nobody declares would silently drop the pack
use … as google_cloud_identity_group inside `google_org_policy_policy { … }`: the pack is this map's content; move the `use` to the folder or top level to re-key it
use "old-pack.yaml": a pack is Satz — satz v0.71.0 is the last release that converts the pre-Satz YAML dialect
use "x.satz": file not found
cyclic `use`: main.satz → a.satz → b.satz → a.satz
`terraform` is declared twice — one block per estate
google_org_policy_policy.p is declared twice in this file with different bodies (first at line 7)
grant: unknown key `description` in a conditional grant object — the keys are `role`, `condition`, "import-id"
claim: resources = [...] is required (a claim ships its witnesses)
claim … deviates: reason = "…" is required (a deviation is a disclosed decision, and the report carries the reason)
suppress google_org_policy_policy "x" matches nothing — stale suppression (typo or upstream rename)
suppress … role on google_organization_iam_member "group:x@example.com": the address is in conflict (⊥); suppress the whole member or resolve the conflict first
<type>.<label>: 2 disagreeing definitions — a.satz:12, b.satz:40   (under `composition conflicts`, at each site)
`deployment_mode = "boot"`: the mode is "local" (the state in a file) or "cloud" (the state in the gcs bucket), and no backend is emitted for anything else
`deployment_mode = "cloud"` without a value for `svc_iac_account`: cloud mode runs every live call and `tofu` as `{svc_iac_account}@{infra_project_name}.iam.gserviceaccount.com`, so the estate binds both — bind it in `params {}`, or keep `deployment_mode = "local"`
transpile: estate.yaml is written in the pre-Satz YAML dialect, which satz does not read. satz v0.71.0 is the last release that converts it

satz import organizations/123456789012 --generate-unmapped

import {
  to = google_dns_managed_zone.corp
  id = "projects/acme-infra-001/managedZones/corp"
}

generate-unmapped: 4 unmapped resource(s) the provider can be asked for, 1 it cannot:
  not generated  //aiplatform.googleapis.com/projects/acme-infra-001/locations/europe-west3/datasets/9 — no import-config
                 row names asset type aiplatform.googleapis.com/Dataset, so there is no Terraform
                 type to import as

generate-unmapped: 33 written, 1 written incomplete, 1 refused, 0 unaccounted for:
  written        //dns.googleapis.com/projects/acme-net/managedZones/1234567890 = google_dns_managed_zone.corp
  incomplete     //cloudasset.googleapis.com/organizations/123456789012/feeds/estate = google_cloud_asset_organization_feed.estate
      │ Error: Missing required argument
      │ The argument "billing_project" is required, but no definition was found.
  refused        //compute.googleapis.com/projects/acme-net/zones/europe-west3-b/instanceSettings/InstanceSettings = google_compute_instance_settings.instancesettings
      │ Error: Cannot import non-existent remote object

transpile: estate.yaml is written in the pre-Satz YAML dialect, which satz does not read.
satz v0.71.0 is the last release that converts it:

    cargo install --git https://github.com/tjirsch/satz --tag v0.71.0 --locked
    satz import estate.yaml --kind estate            # --kind pack for a pack
    cargo install --git https://github.com/tjirsch/satz --locked
    satz fmt estate.satz
    satz merge-presets --estate estate.satz