# Quickstart: the Assure GitHub Action > **First run checklist.** Tick all five before the first run. > > - [ ] The collection role exists, with `CONNECT` on your database (section 2). > - [ ] The runner can read the server's configuration files, or has copies it can read (section 6). Managed PostgreSQL: skip this line. > - [ ] The connection string works from the runner: `psql '' -c 'SELECT current_user'` prints `assure_collector` (section 3). > - [ ] The job that runs Assure has `id-token: write` under `permissions:`, or an API key is stored as the repository secret `ASSURE_API_KEY` (section 1). > - [ ] `profile` is left at its default, `postgresql-observed-baseline`. **Served today:** five profiles. `postgresql-observed-baseline`: intent-free, from a connection or an artefacts directory. `postgresql-declared-model`: an artefacts directory (`raw/declaration.json`) or a connection with `.assure/declaration.json`. `http-observed-baseline`: an artefacts folder holding an endpoint manifest and captured response heads; the Action produces the scope binding and passes the identity key by pipe. `mysql-declared-model`: a MySQL server, from a mysql:// connection plus your declaration file (`declaration`), or an artefacts directory holding `raw/submission.json`; reports are withheld (`profile_unqualified`) until the writer is qualified for MySQL. `python-auth-declared-model`: a Python (Flask) repository, free, from the checkout in one step; the Action proposes a drafted declaration in a pull request the merge accepts; FastAPI, Django and standard-library http.server repositories with your declaration. Known-vulnerability scanners check your code against a list of what has broken before. Assure checks whether the way your code meets the foundational software it runs on stays inside a regime that can be shown safe and reliable, and says exactly what it could and could not establish. Assure is the check that reads green only when nothing it examined is disproven. It tells you the bounds of what it has established, and why it matters. In an age where machines generate code at a volume nobody can read, Assure shows that each change maintains its baseline security and reliability, and stays true to any formalised requirements. Supported PostgreSQL majors: 14 to 18. Real-run evidence: 17 and 18. **Rules the collector keeps, and rules it withholds.** The collector this Action ships keeps a `pg_hba.conf` rule with a quoted name, an `@file` list or a regular-expression user (`/^...`) as written, and the check reads it. A rule or setting it still has to withhold, such as a rule with an unclosed quote, becomes a marker line that names its own line number and reason. The check reads that rule or setting as not observed, and the summary lists it as `not observed: line N ()`. Files collected earlier with the earlier collector, given as `artefacts`, still stop at such a rule with exit 3 (`collector_refused`): that collector withheld it whole, and Assure cannot read it. The message names the file and the line. Collect again with this Action. If you cannot: remove quotes a name does not need; write an `@file` list's names inline; use a `+group` role in place of a list; list a regular-expression user's roles by name. Otherwise, send Symbolia the file name and the line number through your Symbolia contact, so the shape is counted. The Action collects facts in your GitHub Actions runner and sends them to `api.symbolia.ai` over TLS with a key: one it gets for this run from your workflow's GitHub identity, or your own API key. The check runs on Symbolia's server; the Action writes the verdict, job summary and annotations in your runner. On a `pull_request` event the Action also posts the result as one comment on the pull request, "Assure: N rules broken by this change", with what is broken and the fix, what still holds, and what was not checked yet. It is rendered from the verdict, with no model. A run that is refused before a verdict posts the same comment with the refusal, one next step, and each promise of the requirements file it sent reading `not established`, the refusal named as the reason. Each later run on the pull request updates the same comment. The Action posts it with the workflow's own token, so the job needs `pull-requests: write` under `permissions:` (keep `contents: read` beside it); the jobs on this page grant it. Without that permission the comment is not posted, the job log carries one notice naming the line to add, and the verdict, the job summary and the exit code are unchanged. ## What is sent, and what is never read The Action sends the collector's output: catalog facts (roles, memberships, object ACLs, policies, functions, schemas, settings and similar) and, when the runner can read them, your configuration files. What leaves the runner: - settings and rules as written, without comment text: every comment in your configuration files, including commented-out settings, is replaced in the runner with `# `, and every line keeps its place. A line PostgreSQL cannot parse (an unclosed quote) becomes ``, which the check still counts as a broken line; if the check would read it as a working setting or rule, the Action stops, exits 2 (`bad_input`) and names the file and the line, and you fix the line and run again. A `pg_hba.conf` rule or `postgresql.conf` setting the collector had to withhold whole is a marker line the check reads as not observed, and the summary lists it as `not observed: line N ()`. A marker whose line number is not its own, or whose reason is not one the collector writes, stops the upload with exit 2 (`bad_input`), and a collection that mixes this collector's output with the earlier collector's stops with exit 3 (`collector_refused`). In files from the earlier collector, a rule or setting that collector withheld whole stops the upload with exit 3 (`collector_refused`) (section 9). The collector's record of which lines it withheld (`COLLECTION-SIDECAR.json`) must come with its output, with the `REDACTION-MANIFEST.json` from the same run: without them, a file that holds a withheld line cannot be checked, and the upload stops the same way; - policy expressions with every string literal withheld: each quoted literal becomes `''` in the runner, and so does each literal in your declaration's `declared_predicate` (`raw/declaration.json` in an artefacts directory, `.assure/postgresql-declared-model.json` or `.assure/declaration.json` with a connection); except a setting name written as a standard-quoted `'name'` directly after `current_setting(`, which is sent as written; - no secret-bearing value: the collector withholds every one whole before anything is written, and checks its own output for those values. The job log and the job summary state how many comments and literals were withheld. For a profile whose inputs name no PostgreSQL configuration or `pg_hba.conf` file, such as the HTTP profile, nothing is withheld: the files are sent as read, and the line says "nothing to withhold — the withholding pass covers PostgreSQL configuration and pg_hba files and the SQL literals in the catalog snapshot and the declaration, and this profile's inputs name none of them". [DATA.md](/docs/data) lists every item, including what is still sent as written, such as role names and client addresses. The collector never reads table contents, password hashes, key material or other sessions' statements. It reads the connection string of a subscription and withholds it whole before anything is written. The Action sends only files the profile reads. It fetches each profile's list of file names and size limits from the API first, and checks every file against that list in the runner. A file with another name, or over its limit, stays in the runner. The server deletes the collected facts when the check ends. On the Premium tier a sealed copy is kept for the formal shadow (see [DATA.md](/docs/data)). It keeps the verdict for 30 days. Both data-sending inputs are opt-in: with no inputs the Action asks for no report, so no verdict record goes to a third-party model, and uploads no `requirements.md`; set `report: true` to ask for the report, and name the file in the `requirements` input (for example `requirements: requirements.md`) to send its text. In `mode: api` the Action sends the text of the file you name (within 65536 bytes, 256 lines and 8192 bytes per line), your repository name and the commit (on a pull request, its head commit); the server keeps them with the check for 30 days. Setting `requirements` to `none` stops the requirements text only: the repository and the commit are still sent and kept with the check for 30 days. The Action reads the requirements text from the files your workflow checked out; the commit it sends is a label for the run, not the source of the text. On `pull_request` the checkout is the merge commit GitHub made, and on `pull_request_target` it is the base branch, while the commit sent is the pull request's head commit. The requirements text comes from the checked-out workspace, not fetched from the named commit. A pull request workflow may read a merge tree, and `pull_request_target` may read the base branch, while the metadata names the pull request head. Align the checkout with the commit you intend to check; caller/runner provenance is not a GitHub attestation. ## What the runner needs - Outbound HTTPS to `api.symbolia.ai` (port 443). - A network path to your database, for a check with `connection`. - Python 3.14 and, for `connection`, the PostgreSQL client (`psql`). ## 1. Get an API key The Action can get one for each run itself, and you store nothing. Give the job that runs Assure the permission `id-token: write`. The Action then asks GitHub for this workflow's identity token, made for Assure, and exchanges it at `POST /v1/auth/oidc` for a key that lives for this run only (at most one hour). A sign-in key never rotates into a longer-lived key (`POST /v1/keys/rotate` refuses it `rotate_too_early`); the next run signs in again. Your Assure account is your GitHub owner (the user or organisation that owns the repository), on the free plan the first time it signs in. The key is masked in the job log before it is used. Naming one permission sets every other permission to none, so keep `contents: read` beside it, or `actions/checkout` fails on a private repository. The permission lets the job ask GitHub for an identity token for this repository; it gives no write access to the repository. The smallest job, for files you collected and committed in `collected/` (section 9); put it under `jobs:` in a workflow that runs on `pull_request` and on `push` to your default branch: ```yaml permissions: contents: read id-token: write pull-requests: write steps: - name: Check out the repository uses: actions/checkout@ - name: Set up Python 3.14 uses: actions/setup-python@ with: python-version: "3.14" - name: Assure check uses: Symbolia-Assurance/assure-action@beta with: artefacts: collected ``` With no `api-key` and no `id-token: write`, the Action stops before it collects or sends anything, with `bad_input` (exit 2) and a reason that names the line to add. A sign-in the API refuses is `unauthenticated` (exit 2), and `detail.identity` in the failure file names the check that failed; run the job again. ### Or store a key from Symbolia Ask Symbolia for a key. It starts with `asr_`, and you receive it once. A key you pass is used, and the Action does not ask GitHub for an identity token. In your repository, open **Settings → Secrets and variables → Actions → New repository secret**: - Name: `ASSURE_API_KEY` - Value: the key. The Action masks the key in the job log before it prints anything. It sends the key only in the `Authorization` header to the API, over TLS, and never follows a redirect. ## 2. Create a collection role The Action connects as a role you create for it. Give that role read access to settings and statistics, and nothing more. Run this as a superuser or a role that can create roles: ```sql CREATE ROLE assure_collector LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS PASSWORD ''; GRANT pg_read_all_settings, pg_read_all_stats TO assure_collector; GRANT CONNECT ON DATABASE TO assure_collector; ``` In these statements `` is the name of the database to check, or `postgres` for a local server that holds no other database. The `CONNECT` grant matters when your database revokes `CONNECT` from `PUBLIC` (for example `REVOKE ALL ON DATABASE FROM PUBLIC`). Without it, the first run stops with `collector_cannot_connect` and the reason `permission denied for database`. Where `PUBLIC` still has `CONNECT`, the grant changes nothing. The collector also reads the catalog of each other database that allows connections, such as `postgres` and `template1` (see [DATA.md](/docs/data)). Where `PUBLIC` has no `CONNECT` on one of them, that database is recorded as a gap (`permission denied for database`) and the collection is marked incomplete; to have it read, grant `CONNECT ON DATABASE ` to the same role. On a server with thousands of databases, those past the pass's bounds (time and size, see DATA.md) are recorded as gaps the same way, without being read. Then allow the role to log in from the runner. Add a line to `pg_hba.conf` and reload the server: ``` host assure_collector /32 scram-sha-256 ``` Rules for this role: - Create a new role. Use it for nothing else. The checker leaves the collection role out of every reading, so a role your site also uses would hide its own results. - Grant it only these two roles. The collector refuses a broader role: `pg_monitor` or `pg_stat_scan_tables` in `collection-privileges` stops the Action with exit 2 (`bad_input`) before anything runs, and a role that belongs to either stops it with exit 3 (`collector_refused`). The collector also refuses to run if the role is a superuser, has `CREATEDB`, `CREATEROLE`, `REPLICATION` or `BYPASSRLS`, or belongs to any other role. - Allow it to log in through `pg_hba.conf` from the runner's address. The collector runs a fixed, published set of `SELECT` queries. It writes nothing to your database. The collector asks for a read-only session. A pooler may not pass the request on. The collector runs only fixed SELECT statements either way. The collector records whether the session was read-only, and the job summary says so (section 8). ## 3. Store the connection as a secret Add a second repository secret: - Name: `ASSURE_PG_CONNECTION` - Value: a libpq connection string or URI, for example: ``` host=db.example.internal port=5432 dbname=app user=assure_collector password= sslmode=require ``` `sslmode=require` encrypts the connection but does not check the server's certificate. It works with the self-signed certificate that the Debian and Ubuntu packages set up. `sslmode=verify-full` also checks that the certificate is signed by an authority the runner trusts and names the host you connect to. It is the stronger choice. It needs a certificate the runner trusts: a self-signed server certificate fails it. Give the authority's certificate with `sslrootcert`: ``` host=db.example.internal port=5432 dbname=app user=assure_collector password= sslmode=verify-full sslrootcert=/path/to/root.crt ``` Test the string from the runner before the first run. Leave the password out and type it at the prompt, so it stays out of your shell history: ``` psql 'host=db.example.internal port=5432 dbname=app user=assure_collector sslmode=require' -c 'SELECT current_user' ``` It prints `assure_collector`. If it does not, the Action cannot connect either. The Action passes the connection to `psql` through environment variables. The connection stays in your runner: it is never sent to the API, put on a command line or logged. ## 4. Add the workflow Create `.github/workflows/assure.yml`: ```yaml name: Assure on: pull_request: push: branches: - main workflow_dispatch: schedule: - cron: "0 3 * * 1" permissions: contents: read jobs: check: runs-on: ubuntu-latest permissions: contents: read id-token: write pull-requests: write steps: - name: Set up Python 3.14 uses: actions/setup-python@ with: python-version: "3.14" - name: Install the PostgreSQL client run: command -v psql || (sudo apt-get update && sudo apt-get install -y postgresql-client) - name: Assure check id: assure uses: Symbolia-Assurance/assure-action@beta with: profile: postgresql-observed-baseline connection: ${{ secrets.ASSURE_PG_CONNECTION }} collection-role: assure_collector collection-privileges: pg_read_all_settings,pg_read_all_stats fail-on: fails output: assure-verdict.json - name: Keep the verdict if: always() uses: actions/upload-artifact@ with: name: assure-verdict path: ${{ steps.assure.outputs.verdict-path }} ``` Use `@beta` on the `Symbolia-Assurance/assure-action` line. It moves to each new release when Symbolia publishes, so you get fixes without editing your workflow. A moving ref runs what Symbolia last published; every release is first served by production and reviewed before merge, and each release also has an immutable tag `v0.1.0-beta.N`. To freeze, pin a full 40-character commit SHA of `Symbolia-Assurance/assure-action` in place of `@beta`; in a clone, `git -C assure-action rev-parse HEAD` prints it. Pin every third-party action to the full commit SHA of the release you trust. The `source:` line of `skills/assure/VERSION` names another commit: the Assure source commit the Action was built from. It is not a commit of the Action repository, so it never goes in a `uses:` line. The `pin:` line of `skills/assure/VERSION` says the same: the build cannot know which Action commit you pin, so it names none. This workflow runs on every pull request, on every push to `main`, when you start it by hand, and once a week. Change `main` if your default branch has another name. A pull request from a fork gets no repository secrets from GitHub, so `api-key` is empty there and the Action stops with `bad_input` (exit 2). GitHub gives such a run no identity token either. With `id-token: write` under `permissions:` (section 1), you can leave out the `api-key` line. The template above already does: it signs in with the workflow's GitHub identity, so you store no key. To use a stored key instead, pass it to the step: ```yaml - name: Assure check id: assure uses: Symbolia-Assurance/assure-action@beta with: api-key: ${{ secrets.ASSURE_API_KEY }} ``` **A PostgreSQL your CI already starts.** When your workflow runs PostgreSQL as a service container and loads your schema, check that server: add the same `services:` block and schema step to this job, then create the collection role (section 2) in a step before the check, with a password that exists only in CI. Give the connection inline, for example `connection: host=localhost port=5432 dbname=postgres user=assure_collector password=`. That password guards a database that lives only for the length of the job, so it is not a secret; for any other database, pass `connection` from a secret (the inputs table). Leave out `data-dir` and `config-dirs`: the runner cannot read the container's files, so each configuration file reads as a recorded gap (section 6, option c). This workflow uses the intent-free profile, which needs no declaration. To check against a declaration you write, use `postgresql-declared-model` with collected files (section 9). The runner must reach your database and `api.symbolia.ai`. For a database on a private network, use a self-hosted runner inside that network with outbound HTTPS. Checks are free, so the workflow runs `mode: api` from the start. To list problems before the first check, you can run the Action once by hand with `mode: lint`, from a workflow that runs only on `workflow_dispatch`: it reads the same files, sends them to `POST /v1/lint` and lists every problem it finds in your files, profile, scope, `requirements.md` and HTTP heads. Never commit `mode: lint` to the workflow that runs on pull requests: a lint run checks nothing and exits 0 when it finds no problem. The Action collects and checks your files in the runner as for a check, then asks the API to read them. Each problem is a `::warning` annotation and a line in the job summary; the lint record is written to `output`. The outputs are `outcome` (`lint`), `exit-code` (0 when nothing was found, else 2) and `lint-findings` (how many problems it found). It never runs a check and nothing is charged, but it counts against your rate limits. Fix what it lists, then run with `mode: api`. ## Reading your first result The first line of the job summary, and the Action's last log line, starts with a colour, then says how much was read, "N of 8 machines read, M refused", and the bounds of the result. A machine is one part of the check, such as client authentication or row-level security. A refused machine was not read, and the summary lists it under "Machines not read" with its reason. When a scope limit names machines the checker could not reach, they are out of scope, not refused, and the count ends ", n out of scope", for example "5 of 5 machines read, 3 out of scope": an out-of-scope machine leaves both counts, and the summary names the limit. - **green** (exit 0): within these bounds, nothing disproven. For example "green: 7 of 8 machines read, 1 refused; declared premises: none (observed profile); version pins: major 18; nothing disproven; established: 3 of 40; deviations: 1; vacuous: 13; not established: 23 — top action: state it in requirements.md". A deviation is counted on its own. When no obligation on the machines read holds, the line says so in words: "nothing could be established (0 of N obligations hold); not established: n — top action: \". One line follows for each obligation that could not be established, "\: \ — \: \". Green never means more than this. - **red**: something is disproven, for example "red: ...; disproven: \ — \, \, \"; with more than one, "disproven: k, first \ — …", and the free summary (`GET /v1/checks/{id}/summary`) lists the same k under `disproven`, each with `platform_owned`. It exits 1 when your `fail-on` names the status (`fails` by default) and the disproof is yours to fix. A `fails` reading whose findings are all platform-owned keeps the colour red with exit 0 and `policy.reason` `platform_owned`: the disproof is someone else's to fix. A `fails` reading on a read machine is red whatever `fail-on` says. A status you name in `fail-on` also turns the reading red and sets the exit. When your `fail-on` leaves a disproven status out, the exit is 0 and the line ends "(exit 0 by your fail-on: ...)". A status you chose to stop on that is not a verdict (for example `fail-on: not_observed`) is red with exit 1 and reads "stopped by your choice: not observed — \", never "disproven". - **yellow** (exit 3): nothing could be read at all, "yellow: could not look: \; \", for example "yellow: could not look: the input could not be represented; re-collect with the pinned collector". The summary prints the reason and the file it names under it. A typed outcome that stopped the check before any reading also exits 3. Yellow is a check run's `action_required` where a check run is published with `checks: write`; this Action publishes none, so it falls back to exit 3, which fails the job. On the free plan, one upgrade line sits above that first line, at the very top of the summary: it names Premium and links to a checkout page already filled in with your account. When your free balance is spent, the line starts with one sentence that says so. Under the first line, one sentence says what it means in plain words. For a green PostgreSQL run: "Nothing in your database configuration contradicts what is known about safe PostgreSQL setups. 21 of 41 checks could not be completed, mostly because they depend on what the system is for, which has not been stated. That is a gap in what we could see; your database configuration is unchanged by it." For red, the consequence of what was disproven and where; for yellow, that nothing below is a finding and what to do. Each disproven or deviating obligation is listed under "Why it matters" with its statement and its consequence ("Consequence not yet stated for \." until the profile states one). When you name a file in the `requirements` input, the first line adds "requirements: h hold, n not established[, d disproven]", the summary lists each requirement under the not-established list with its sentence, "R3 — "\" — not established — missing method — \", and the outputs `requirements-not-established` and `requirements-disproven` count them. A disproven requirement turns the run red ([VERDICTS.md](/docs/verdicts), section 10). A requirement checked with `http-observed-baseline` cannot hold today: the HTTP check does not yet carry a verified method and path for each endpoint, so a matched HTTP requirement reads not established with the reason class `missing_identity_binding`. `mode: local` does not read `requirements.md`: requirements are checked in `mode: api` only, and a local run that finds one says so in one notice. [FIRST-LINE-SAMPLES.md](/docs/first-line-samples) shows one first line for each colour, word for word, with the meaning sentence for each colour and profile. `FIXTURES.md`, in `docs/customer/` of the Assure repository (a document the Action tree does not ship), lists for each profile the committed fixtures, the first line a development check of each one reads, sample verdicts (one with refused machines) and a sample declaration for each declared profile. A refused machine bounds the result and is named; a status you name in `fail-on` on its rows stops the job as on a read machine, and a reading the checker kept on it is read as not observed. `allow-partial` is still accepted and no longer changes anything. Under the first line, the summary lists every reading under its status, each with its text: why it holds, why it fails, or what could not be read. The verdict file holds the same readings with their premises ([VERDICTS.md](/docs/verdicts)). The Action keeps it at the `output` path; the workflow above uploads it as the `assure-verdict` artifact. If a reading looks wrong, send a `wrong_reading` note through the [feedback route](/docs/quickstart-action#deliberate-feedback), within the customer's permission, naming the check id, obligation and expected reading. Never send your configuration files or your connection string. Never send your API key in the note. ## Upgrade to Premium (USD 20 a month) Accounts start on the free plan. Premium (`usd_20`, USD 20 a month) adds checks of your app's sign-in and session routes, not only the database; paid formalisation of requirements no method states yet; and one monthly pool of USD 20 of usage that reports, formalisation and proof search share. To pay, open the Premium Payment Link with your account id appended as `client_reference_id`, as the upgrade line at the top of a free account's job summary does: `https://buy.stripe.com/?client_reference_id=`. You can read your exact link before your first run: on the free plan, `GET /v1/usage` carries `upgrade`, `{"url": "…", "line": "…"}`, the same link and sentence a free account's verdict carries. When the payment completes, your account moves to Premium; no other step is needed. A paid plan's answer never carries `upgrade`, and while Symbolia has set no Payment Link no answer does: then ask Symbolia for a checkout link. ## 5. Inputs | Input | Default | Meaning | |---|---|---| | `api-key` | none | Your Assure API key. Pass it from a secret. Leave it out when the job has `id-token: write` under `permissions:`: the Action then signs in with the workflow's GitHub identity (section 1). | | `api-url` | `https://api.symbolia.ai` | The API address. The published API is `https://` only. Plain `http://` is accepted only for a loopback host (`127.0.0.1`, `::1` or `localhost`), for a local test server. | | `mode` | `api` | `api`: the check runs on the Assure API. `lint`: a pre-flight that sends the same files to `POST /v1/lint` and runs no check; nothing is charged. | | `profile` | `postgresql-observed-baseline` | The checker profile to run. | | `connection` | none | libpq connection string or URI. Pass it from a secret. | | `artefacts` | none | A directory of collected files. Use this or `connection`, never both. For `http-observed-baseline` with `scope-binding` empty, the directory holding your endpoint manifest (`manifest.json` and the response heads it names): the Action binds the endpoints and collects them itself. | | `collection-role` | the user in `connection` | The role's name inside the database. The collector checks it against `current_user`. Set it when a connection pooler's login name differs (section 6). | | `collection-privileges` | `pg_read_all_settings,pg_read_all_stats` | The roles you granted to the collection role: one or both of these two. | | `data-dir` | none | A path where the runner can read the server's data directory. Used with `connection`. | | `config-dirs` | none | Directories that hold the server's configuration files outside the data directory, one per line or separated by colons. Used with `connection`. | | `fail-on` | `fails` | Which statuses fail the job (section 7). The API checks it against the profile and applies it. `unresolved-security` adds strict (section 7). | | `allow-partial` | `false` | Accepted for compatibility; it no longer changes the exit (section 7). Any other word is `bad_input`. | | `scope` | none | A JSON file of selected ids, for a profile whose scope you select. Both PostgreSQL profiles take none. | | `scope-binding` | none | A JSON file holding the whole `scope_binding` object, for a profile that binds its scope: the token map under the profile's map name, and any record the profile lists. The Action checks its keys before collecting. Both PostgreSQL profiles take none. For `http-observed-baseline`, leave it empty and the Action makes it. | | `identity-key` | `pipe` | For `http-observed-baseline`: how the endpoint identity key reaches the identity producer. Only `pipe`. The Action makes a fresh key for each job, passes it to the producer and then the collector on a pipe, and keeps nothing, so no key is an input, an environment variable or a file and nothing persists between runs; that is fine while no accepted scope exists, since a later comparison with an accepted scope will need a key kept across runs. Any other value is masked and refused before anything is read. | | `accepted-scope-ref` | none | Refused for now, before anything is collected or sent: no accepted scope record can be resolved yet. Leave it empty. | | `report` | unset | Opt-in: with `true` in `mode: api`, the API writes the plain-language report of the check's claim tree after a verdict ("The report"). `report: false` skips it, and `mode: local` never asks for one. Any other word, or `true` with `mode: local`, is `bad_input`. | | `feedback` | `''` | One deliberate JSON string or workflow-written JSON file path; off by default. Sent once after an API check with a server check id, without retry. | | `allow-overage` | `false` | With the report on, `true` lets a report beyond your account's monthly allowance run, within its overage budget, and its overage is charged at cost x 1.2 ("The report"). Any other word is `bad_input`. | | `requirements` | unset | A requirements file to send with the check. The upload is opt-in: with the input empty, the Action sends no requirements text and prints no notice, even with a `requirements.md` at the repository root; name it (`requirements: requirements.md`) to send it. A file you name that is missing, unreadable or a symbolic link, or one beyond 65536 bytes, 256 lines (a final newline ends the last line) or 8192 bytes per line, or not UTF-8 text, is `bad_input` (exit 2) before anything is collected or sent. The text travels as a request field, never as a collected file. The Action also sends the repository and the commit as their provenance: `GITHUB_REPOSITORY`, and on a pull request the head commit of the pull request (`GITHUB_SHA` is then a merge commit GitHub made), else `GITHUB_SHA`. `mode: api` only. `none` sends no requirements text and prints no notice (a file named `none` is then reached as `./none`). Only `none` in lower case is the sentinel: `NONE` names a file, and on a file system that ignores case, such as the default on macOS, a file named `none` answers to it. | | `compile-requirements` | `true` | Each requirements line that does not match one of the profile's statements word for word, and only those lines, is sent to Claude Haiku, which proposes the statements it asks for; the server checks the proposal and decides the line, and the job summary says how many lines were read. `false` sends no line to the model and matches every line exactly ([DATA.md](/docs/data) says what is sent and kept). Any other word is `bad_input`. | | `fresh-check` | `false` | `true` sends a random `Idempotency-Key`, so the same bundle is checked, and charged, again (section 9). By default the key comes from the content of the request, and a repeat of the same request gets the stored verdict back. Any other word is `bad_input`. | | `output` | `assure-verdict.json` | Where to write the verdict file. | | `python` | `python3` | The Python 3.14 interpreter to use. | ## 6. Managed PostgreSQL and configuration files Some facts live in configuration files: `postgresql.conf` and the files it includes, `postgresql.auto.conf`, `pg_hba.conf`, `pg_ident.conf` and `postmaster.opts`. The collector finds them through the server's own settings and reads them from the runner's filesystem. With a connection and no data directory, the runner cannot read those files. This is the usual case for managed PostgreSQL. A reading that needs a fact from a file then reads **not observed**. Where the checker cannot represent the input without the file, as with a missing `pg_hba.conf` or `postgresql.conf`, the readings that use it read **representation**. When `pg_hba.conf` was not collected but the collection role can read `pg_hba_file_rules` (the server's own parse of the file), the checker reads the client-authentication rules from that view and cites `raw/catalog_snapshot.json#pg_hba_file_rules`; a collected `pg_hba.conf` wins over the view. The client-authentication and TLS obligations are the ones most affected. To read the files, run the Action on a self-hosted runner that can read them: - `data-dir`: the server's data directory, as the runner sees it. - `config-dirs`: directories that hold configuration files outside the data directory. The Debian and Ubuntu packages keep them in `/etc/postgresql//`: ```yaml data-dir: /var/lib/postgresql/18/main config-dirs: /etc/postgresql/18/main ``` Give one directory per line, or separate them with colons. A path that holds a colon cannot be given here. The collector reads files only inside `data-dir` and `config-dirs`. The collector does not copy some include targets. It records each one as "not copied", and the readings that need it read **not observed** or **representation**. These are an absolute `include_dir` in `postgresql.conf`, any absolute include in `pg_hba.conf` or `pg_ident.conf` (an `include`, `include_if_exists` or `include_dir` line on PostgreSQL 16 and later, or an `@file` name), and a relative include that leads above the directory of the main file (`postgresql.conf`, `pg_hba.conf` or `pg_ident.conf`). An absolute `include` or `include_if_exists` in `postgresql.conf` is copied. ### Letting the runner read the server's configuration files The collector asks the server where each file is (`config_file`, `hba_file`, `ident_file`, `data_directory`) and reads each file at that path. One path is moved: a file inside the server's data directory is read from `data-dir` instead. A file outside the data directory, such as Debian's `/etc/postgresql/18/main/pg_hba.conf`, is read at the server's own path, which must lie inside `config-dirs`. By default the runner cannot read these files. The data directory is mode 0700, and `pg_hba.conf` and `pg_ident.conf` are 0640, owned by `postgres`. There are three ways forward. The examples use Debian or Ubuntu, PostgreSQL 18 and a runner user named `runner`. **(a) Run on the database host, with the runner in the `postgres` group.** Put the data directory in PostgreSQL's group-access mode (the same as `initdb --allow-group-access`), with the server stopped, and add the runner user to the group: ``` sudo systemctl stop postgresql@18-main sudo chmod 0750 /var/lib/postgresql/18/main sudo chmod -R g+rX /var/lib/postgresql/18/main sudo systemctl start postgresql@18-main sudo usermod -aG postgres runner ``` Restart the runner service so the new group applies. With the data directory at 0750 when the server starts, PostgreSQL writes `postgresql.auto.conf` and `postmaster.opts` group-readable (0640) from then on; `pg_hba.conf` and `pg_ident.conf` are already 0640 `postgres:postgres`. Inputs: `data-dir: /var/lib/postgresql/18/main` and `config-dirs: /etc/postgresql/18/main`. This gives every file, always current. The cost: the group also reads every table file in the data directory. Prefer (b). **(b) Give the runner copies, or read access to these files only.** Copy the files inside the data directory to a directory the runner reads, and pass it as `data-dir`. Leave the files under `/etc` where they are, and give the runner read access to the two that it cannot read: ``` sudo install -d -m 0750 -o root -g runner /srv/assure-pgdata sudo install -p -m 0640 -o root -g runner /var/lib/postgresql/18/main/postgresql.auto.conf /var/lib/postgresql/18/main/postmaster.opts /srv/assure-pgdata/ sudo setfacl -m u:runner:r /etc/postgresql/18/main/pg_hba.conf /etc/postgresql/18/main/pg_ident.conf ``` Inputs: `data-dir: /srv/assure-pgdata` and `config-dirs: /etc/postgresql/18/main`. In the Debian layout, `postgresql.conf` and the `conf.d` include directory are usually readable by every user; check with `ls -l`. `-p` keeps each copy's modification time. The runner reads these configuration files and nothing else. The cost: the copies go stale. Copy again after `ALTER SYSTEM` (which rewrites `postgresql.auto.conf`) and after a server restart (which rewrites `postmaster.opts`), and set the ACL again if an editor replaces `pg_hba.conf`. Copying the files to some other directory and naming it in `config-dirs` does not work: the collector looks for each file at the path the server reports. For a runner on another host, put the copies at the same paths the server uses, and the data-directory files in the `data-dir` copy. Run this on the runner host, in a directory that holds copies of the server's files: ``` sudo install -d -m 0750 -o root -g runner /etc/postgresql/18/main /etc/postgresql/18/main/conf.d /srv/assure-pgdata sudo install -p -m 0640 -o root -g runner postgresql.conf pg_hba.conf pg_ident.conf /etc/postgresql/18/main/ sudo install -p -m 0640 -o root -g runner conf.d/*.conf /etc/postgresql/18/main/conf.d/ sudo install -p -m 0640 -o root -g runner postgresql.auto.conf postmaster.opts /srv/assure-pgdata/ ``` When the server keeps every configuration file in its data directory (the layout `initdb` writes), copy all of them, with any include directory at its relative path, into the `data-dir` copy, and leave out `config-dirs`. **(c) Managed PostgreSQL.** The runner has no access to the server's files. Leave out `data-dir` and `config-dirs`. Every reading that needs a file reads **not observed** or **representation**, with the file named. The readings from the catalog still come back. ### Managed PostgreSQL and connection poolers Some managed services put a connection pooler in front of the server, and the pooler routes on the login name. Supabase's pooler, for example, takes the login name `assure_collector.`; inside the database the role is `assure_collector`. - The `user` in `connection` is the login name. Keep it as the service gives it. - `collection-role` is the role's name inside the database. The collector checks it against `current_user` and `session_user`. When it is not set, it is the user in `connection`. When the two differ, the Action logs in with the login name and the collector checks the role. If you leave `collection-role` unset behind such a pooler, the collector refuses with `collection_role_mismatch` (`collector_refused`, exit 3), and the reason says which name to set. On Supabase, the `postgres` role cannot grant `pg_read_all_settings` or `pg_read_all_stats`. It can grant `pg_monitor`, and the collector this Action ships refuses `pg_monitor` as broader than it needs (section 2). So this Action version cannot collect from a Supabase database. Use the session pooler. Assure has run through Supabase's session pooler on port 5432. The collector runs each query in its own `psql` process, one short session per query; a transaction pooler has not been tested. The collector asks for a read-only session. A pooler may not pass the request on: through Supabase's session pooler the session was not read-only. The collector runs only fixed SELECT statements either way. The job summary states whether the session was read-only (section 8). The runner cannot read a managed server's configuration files, so the readings that need them read **not observed** or **representation**, as above. ## 7. The fail-on policy and exit codes `fail-on` is a comma list of words, or the single word `never`. The Action sends it as you wrote it. The API checks every word against the profile and applies it. A word the profile cannot emit is `bad_input`, and the reason lists the words that profile accepts. `GET /v1/profiles` lists them too. The words a profile accepts: - any status the profile can emit except `holds` and `vacuous`; - `not_collected`: every status the profile uses for a fact it could not read or represent; - `never`, on its own: readings never fail the job, except a prove-class obligation that is not proven (exit 1, `not_proven`). | Profile | Statuses you can name | `not_collected` stands for | |---|---|---| | `postgresql-declared-model` | `fails`, `representation`, `missing_method`, `missing_premise`, `not_evaluated` | `representation`, `missing_method`, `missing_premise`, `not_evaluated` | | `postgresql-observed-baseline` | `fails`, `deviates`, `representation`, `missing_method`, `not_observed`, `missing_baseline`, `needs_intent` | `representation`, `missing_method`, `not_observed`, `missing_baseline` | `needs_intent` is outside `not_collected`: it marks a norm that depends on what the system is for, which is out of scope by design. Name it on its own to fail on it. Examples: - `fails` (the default): the job fails when any obligation reads fails. - `fails,deviates`: the job also fails on a deviation from vendor guidance or from the Assure baseline (observed profile). - `fails,not_collected`: the job also fails when a needed fact was not collected or could not be represented. - `never`: readings never fail the job, except a prove-class obligation that is not proven, which exits 1 (`not_proven`). A typed outcome still does. - `unresolved-security` (strict, never the default): `fails`, and also every obligation the checker marks `security: true` that is not resolved, that is, has no verdict on a machine that was read. Such an obligation turns the run red with "unresolved by your choice (strict): \ — \; \", and each obligation that could not be established is also a notice annotation. The observed PostgreSQL profile marks 37 of its 41 obligations `security: true` (authentication, authorisation, privilege, definer context, replication and transport); there strict stops the job on any of them that has no verdict, and the first line says "strict: n of m security obligations observable at this pin". The declared PostgreSQL profile marks 4 of its 40 obligations `security: true` (M5 RLS-1 to RLS-4, the row-level security rows); there an unresolved RLS row on a machine that was read turns the run red, and the first line says "strict: 4 of 4 security obligations observable at this pin". The HTTP profile marks none, so there strict is a no-op and the first line says "strict: no obligations marked". Only the security obligations the pinned collector can observe count in n and m: an obligation the profile marks `observable_at_pin: false` is listed as not established, "not observable at collector pin \", and the first line says "strict: n of m security obligations observable at this pin". An intent-bound obligation (`class: intent_bound`) depends on what the system is for, which no collector observes. All security obligations without a verdict bind under strict, including one the pin cannot observe; the report names each and why. An intent-bound one is named "unresolved by your choice (strict)", reads "depends on what the system is for" and has the action "state it in requirements.md". n and m count observability only: an intent-bound obligation never counts in them and is never listed as not observable at the collector pin; m counts the intent-free security obligations. Each obligation has a class its profile declares, never settable per run, and `GET /v1/profiles` lists it: `refute` (green unless disproven) or `prove` (red unless proven). A prove-class obligation that does not read holds on a machine that was read turns the run red, "not proven: \ — input not observed" when its input could not be read, else "not proven: \ — \; \", and the first line states "prove-class obligations: p (unproven: u)". Every obligation of today's profiles is refute-class. The Action exits with the verdict's own policy exit, `policy.exit` in the verdict file. `policy.reason` says why, in one word. The job summary states the policy and this run's exit in plain words. | Code | `policy.reason` | Meaning | |---|---|---| | 0 | `nothing_disproven` | Green: nothing is disproven within the bounds the first line states. Machines or endpoints that could not be read, and a run with no verdict, are named there and do not change the exit. | | 0 | `never` | `fail-on` is `never`. The first line keeps the colour the readings give. A prove-class obligation that is not proven still exits 1 (`not_proven`). | | 0 | `platform_owned` | Red, but every disproof your `fail-on` names is platform-owned (its `findings` all carry `owner_class` `platform` or `extension`), so it is excluded from the exit as someone else's to fix; the first line ends "(exit 0: platform-owned)". | | 1 | `disproven` | Red: a reading on a machine that was read has a status you fail on. A disproof your `fail-on` leaves out stays red with exit 0 and the same reason. | | 1 | `not_proven` | Red: a prove-class obligation is not proven. | | 1 | `unresolved_strict` | Red: under strict, an obligation marked `security: true` is unresolved. | | 1 | `stopped_by_choice` | Red: a reading has a status that is not a verdict and that your `fail-on` names (`not_observed`, or a status `not_collected` stands for). The job stopped on a status you named in fail-on; the colour above says whether anything is disproven. | | 2 | | Bad input, or an API key that is missing, unknown or revoked (`unauthenticated`). Red. Fix the inputs, the files or the key. | | 3 | `could_not_look` | Yellow: nothing could be read at all: the input-integrity gate stopped the check, no machine was read, or no selected endpoint was observed. | | 3 | | A typed outcome. The failure file holds the reason and what to do. | A reading with a status you fail on gives exit 1 whatever could not be read, with one exclusion. A `fails` reading sets exit 1 only when at least one of its `findings` has `owner_class` `app` or `unknown`, or it carries no `findings` at all: one whose findings are all `platform` or `extension` is platform-owned and excluded from the exit (`platform_owned`). A `fails` reading on a read machine is red whatever `fail-on` says. A status you name in `fail-on` also turns the reading red and sets the exit. `allow-partial` no longer changes the exit. The input-integrity gate gives 3 under every policy except `never`. A vacuous reading only says that a domain was empty. A run whose only verdicts are vacuous reads "No verdicts" in the summary, and its first line says "nothing could be established". The first line counts the machines read out of every machine the profile checks, "5 of 8 machines read, 3 refused" (", K refused" only when a machine was refused): a machine that gave no reading at all is listed as refused with the reason "no readings for this machine". When Assure worked the list out from the readings because the checker did not report it, the count ends "(inferred)". The bounds follow: "declared premises: n" (premises you declared; "none (observed profile)" for an observed profile that has none) and "version pins: major 18" (the server's observed major; "none" when the readings name none). Under the meaning sentence, the summary answers three questions in three short sentences, "Usable readings: u of n. Coverage complete: yes or no. Job stops: no (exit 0 by your fail-on), or yes (exit 1).", followed by the collection time and the loaded state when the collector records them, and lists the obligations the profile version cannot yet check (representation, missing method) under their own heading, "Unsupported by this profile version: n". If the checker itself fails, the result is the typed outcome `checker_error` (exit 3) under every policy, `never` included. For an API check, read the result's `charged`: failures after the checker started, including `checker_error`, `checker_timeout`, `checker_cpu_limit` and `checker_memory_limit`, are charged unless the answer states an explicit no-charge decision. A refusal before admission, the checker's own internal error (`checker_error` whose `detail.rule` is `internal_error`), a server restart, and a malformed `python-auth-declared-model` bundle refused by its free pipeline are not charged. Local verdicts and failures say `charged: false`; that field is a check accounting flag, not an amount spent. A request refused before the checker starts is never charged, and neither is a check cut short by a server restart; it still counts against your rate limits. A result is returned whenever one can be produced: when the checker's output for one machine is malformed, that machine is listed under "Machines not read" with its reason (`malformed_output: ...`, or `server_fault: ...` when the server could not write it) and the other machines keep their readings. When no result can be produced, the failure's `detail.malformation` says what was malformed: a fixed kind, the file, the line, the field and the expected form, never your text. The Action sets five outputs: `verdict-path`, `outcome`, `exit-code`, `colour` (`green`, `red` or `yellow`; a failure is `red` for bad input or a bad key, exit 2, and `yellow` otherwise) and `not-established` (how many obligations could not be established; empty for a failure). When a requirements file was sent, it adds `requirements-not-established` and `requirements-disproven`. On the observed profile, when the Action writes `assure-requirements-draft.md`, it adds `requirements-draft`, that file's path (empty when nothing was drafted). ## 8. Where the results appear - **The verdict file.** JSON at the `output` path, schema `assure.serve.verdict/v1`. It holds every reading with its premises. See [VERDICTS.md](/docs/verdicts). - **The job summary.** A table of counts by status, then one line per obligation. It appears on the run page. When the collector recorded the collection session, the summary ends with two lines, as the server reported them for that session: - `The collection session was read-only: yes`, `no` or `not recorded`; - `TLS to the server: yes (, , bits)`, `no` or `not recorded`. Behind a connection pooler they describe the pooler's session to the server, not your runner's connection to the pooler. The job log carries the same two lines. - **The declaration proposal.** On the observed profile (`postgresql-observed-baseline`), the Action writes `assure-declaration-proposal.json` beside the verdict file. It is a declaration drafted from your own catalog snapshot, in the runner, from the files already collected and withheld; nothing more is sent. Its `declaration` object validates as `raw/declaration.json` for `postgresql-declared-model`. Each value names where it came from in `sources`, and a key the snapshot gives no basis for is marked `unread` and left out. The keys in `confirm` are judgements: check each one, then merge the pull request Assure opens for it, or commit it as `.assure/postgresql-declared-model.json` (or `.assure/declaration.json`) in the checkout (`raw/declaration.json` in an artefacts directory), and the next check reads it (the declared reading below) to decide the rows that need intent. Inside a git checkout with nothing at `.assure/postgresql-declared-model.json` or `.assure/declaration.json` (a link at either path is not committed intent and is passed over), or with a file at `.assure/postgresql-declared-model.json` whose JSON differs from this run's draft, and a workflow token, the Action proposes (in `mode: api` and `mode: local` alike) the draft at `.assure/postgresql-declared-model.json` in a pull request of its own from `assure/declaration-proposal` (as for `postgresql-declared-model`: drafted from the collector's own snapshot before the withholding, so the draft holds your own literals and reads the same after you merge it); the job needs `contents: write` and `pull-requests: write` for it. Its body leads with "Assure drafted `.assure/postgresql-declared-model.json` from the collected catalog snapshot. Merging it commits the declaration; the next check then also reads `postgresql-declared-model` beside this reading, to decide the N rows that need intent.", N being the rows that need intent, then each key to confirm with where it was read. With `contents: read` (the jobs above, or a pull request from a fork) the push is refused with no warning (one plain log line), and the files and the section below stay as they are. When the branch is pushed but the pull request cannot be opened (no `pull-requests: write`), the summary says `not proposed (…); the draft is below` and shows the draft as withheld (the `declaration` object of `assure-declaration-proposal.json`), so a literal of your policies never reaches the job summary. When withholding left that draft unchanged (no literal of your policies in it), a "Commit this draft" link sits above it: GitHub's new-file page on the branch the proposal targets with the draft prefilled at `.assure/postgresql-declared-model.json`, byte for byte; otherwise no link is shown. The job summary adds one section, "Assure drafted a declaration from your database: N leaves proposed, M to confirm — commit it as .assure/declaration.json (with a connection; raw/declaration.json in an artefacts directory) and run postgresql-declared-model to decide K rows that need intent.", and each `needs_intent` row's next step names Assure's pull request and the file. Once Assure's pull request is open, the section says "merge Assure's proposal pull request; the next check then also reads postgresql-declared-model beside this reading, to decide K rows that need intent." instead, and no longer says "A proposal changes no reading": it says that the verdict, its file and the exit never change and that the pull request adds no output. The proposal changes no reading or exit of this run; the one output it adds is `requirements-draft`. No file is written when the collector's sidecar names no server major from 14 to 18. - **The declared reading.** On `postgresql-observed-baseline` with a declaration committed at `.assure/postgresql-declared-model.json` (where its proposal pull request puts it) or `.assure/declaration.json` in the checkout, the Action also checks `postgresql-declared-model` on the same collected bundle with that file as `raw/declaration.json` (the first of the two present, in that order; the line and the section name the file read), its `declared_predicate` string literals withheld in the same numbering as the snapshot's before the check reads or sends it (the log says "Assure: declared check: Withheld in the runner …", then "Assure: declared reading: postgresql-declared-model, with" and the file read, once the check returns a verdict); the bundle is not withheld a second time (in `mode: api` a second submitted check, charged as a second check; the summary then says "two checks charged"). No workflow input changes: the declared check runs under the words of your `fail-on` that `postgresql-declared-model` accepts (an observed-only word such as `deviates` or `needs_intent` is left out; with none left, `fails`), and its exit is informational. The job summary's first line (on the free plan, the line under the upgrade line) and the verdict's first notice (the first `::notice` after the check) then read both, for example ``**Assure: decided 27 of 69 rows across both readings** (postgresql-observed-baseline 19 of 55; postgresql-declared-model 8 of 26, with `.assure/declaration.json`)``. N counts the row ids decided (holds, fails or deviates) in either reading, never a row a reading kept on a machine it reports refused (that row reads not observed, as on every surface); M counts the ids in either. The section "### Declared reading (postgresql-declared-model, with `.assure/declaration.json`)" (with the path read) holds that verdict's summary, its headings one level deeper. The verdict file, the outputs, `colour` and the exit stay the observed reading's: the declared reading is informational until you set `profile: postgresql-declared-model`. A declared check that is refused or fails, or a declaration that cannot be read (not a regular file; a link at the path is passed over, as if absent), keeps the observed verdict and exit and reads "declared reading: not measured (the reason)" in that section, never a count. - **The requirements draft.** Beside it, `assure-requirements-draft.md` holds the goals the proposed declaration lets Assure check, one plain sentence each (for example "Each user sees only their own data."), then lists the keys the snapshot gives no basis for. When no table was proposed as protected, or one was left out because its own policy opens every row, a `## Templates` section offers two fill-in lines: row-level security on each user-data table with a policy keyed on the caller (RLS-1 and RLS-2) and the ownership check on inserts and updates (RLS-3), with `` (the open tables suggested) and `` (for example `auth.uid() = id`) for you to fill in; the snapshot carries no column names, so Assure cannot pick the tables itself. Keep a filled line as a goal (`- ` and the sentence) and the Action sends it as those checks; state the same tables and predicate as `protected_tables` and `declared_predicate` in the declaration, or those checks are not established. `assure-requirements-typed.json` beside it holds the checks under each goal: each goal pinned by its sentence's sha256 to the exact statements the check establishes, each with a specific sentence (for example "Only postgres may hold superuser.") and the snapshot rows it came from. Confirm each goal, then commit the draft as `requirements.md` and the typed file beside it, unchanged. In api mode the Action sends each goal you kept as written as its checks, and the job summary reads each goal back: "holds for N of M checks", with how many are not decided yet, or "broken:" with the specific sentences that fail. A goal you change is checked as written, and the summary names the lines changed since they were compiled. The Action uploads `assure-requirements-draft.md` as the `assure-requirements-draft` artifact of your own workflow run, in GitHub's artifact storage; the "Declaration proposal" section of the job summary links the run's artifacts. A second check in the same workflow run replaces that artifact, and an upload that fails is reported in the job log without failing the Action: the Action's exit stays the verdict's. Assure does not receive it. - **Annotations.** The first line is the first notice annotation. With a declared reading, that first line is the both-readings line above and the observed first line is the next notice. Each `fails` reading is an error annotation. Each `deviates` reading is a warning annotation; on `postgresql-observed-baseline` an M6 one (such as SD-1-OB) also names up to five of the functions it read, with their count and login roles. Under strict, each obligation that could not be established is a notice annotation. At most 50 of each appear. When no obligation reaches a verdict, the summary says "No verdicts" and the first line says "nothing could be established". It never means "no issues". Text from the checker or your files is shown as plain text. A web address in it appears as code, never as a link. ## The report The report is opt-in: set `report: true` in `mode: api` to ask for it; unset or `report: false` skips it. It is a plain-language report of the claim tree behind a verdict: what was checked, what holds, what fails and why, and what the check could not decide. `mode: local` never asks for one. Every plan served today includes the report: a free account draws it from the USD 1 free balance granted with its key or at its GitHub sign-in, and without that grant the API refuses it with `allowance_exhausted`; `tier_excludes` is reserved for a plan that excludes the report. A language model writes it from the verdict's record alone, never from your files. A deterministic check then reads it against the record, and a report that fails a fact rule of that check is withheld. A report that passes every fact rule is served as written, even when it misses a style target. Reports are written for `postgresql-declared-model` verdicts today; for other profiles the report is withheld and says so. - **Written.** The job summary carries the first line, then the report, then a line naming the report page. The page shows the claim tree with each rule's check id, status, reason and evidence. Open it with your API key in the `Authorization` header. The `report-url` output holds its address. - **Withheld or refused.** The job summary carries the usual summary and one more line: "The report was withheld: \." A refused report adds one warning annotation, never an error. The report never changes the verdict, the verdict file or the exit code. The first line and the verdict file stay the record. The `report-status` output reads `written`, `withheld`, `refused`, or `running` when the report was still being written as the Action stopped waiting; the summary and `report-url` then name its page, to open later. [DATA.md](/docs/data) says what is sent to the writer and how long a report is kept. **What a report costs.** Premium and Pro each have one monthly pool, USD 20 and USD 200 of usage a month, at the same rate as overage (cost x 1.2), which reports share with formalisation and proof search. On Premium and Pro the default report draws that monthly pool first, then any top-up. Overage is off until you set a budget: past the pool and your top-up, a report is refused until the reset, even with `allow-overage`. With a budget, the part beyond the pool is charged at cost x 1.2, up to that budget. The free plan has a balance of USD 1, granted once: per verified email for an account with an API key, and per GitHub owner at its GitHub sign-in; reports and requirement compiling share it, and it does not renew. A report is paid from it at its real cost, and reports stop while the balance is below zero. A recharge clears what is owed, and the rest goes to your account's top-up. A report within the allowance or the balance is not charged. The part of a report's cost beyond it is charged at cost x 1.2. Before a report runs, the API holds its expected cost (the high end of its quote) against your allowance and top-up, so two reports never share the same cover. A report that would go beyond the allowance runs only when your account has an overage budget and you set `allow-overage: true`, or when your account's top-up covers the hold. Otherwise the API refuses it with `allowance_exhausted`: nothing runs and nothing is charged, and the summary reads "Report: allowance exhausted: USD q needed; set allow-overage or top up", or, when your account has no overage budget, "Report: allowance exhausted: USD q needed; top up, or ask Symbolia to set an overage budget", or, when your budget is spent for the month, "Report: allowance exhausted: USD q needed; ask Symbolia to raise your overage budget, or top up". Without `allow-overage`, a report is never charged more than its hold, even when the model cost more. A free report beyond what is left of the balance is refused `allowance_exhausted` whatever `allow-overage` says. One job's quote can be at most USD 50 unless you ask Symbolia to raise your account's job ceiling; the quote comes first. A report whose quote is above it is refused `job_ceiling`, even with `allow-overage`. Each plan also has a daily report cap (`daily_report_cap`), which counts the reports that ran. While Assure is in beta a withheld report is not charged. Asking again for a report you already have returns the same record at no cost. The summary adds one line, "Report: cost USD x.xxx, charged USD y.yyy, allowance remaining USD z.zz", and the outputs `report-cost-usd`, `report-charge-usd` and `report-allowance-remaining` hold the same figures. A run that repeats an earlier request gets the earlier check and its stored report back, so the report line and the `report-cost-usd`, `report-charge-usd` and `report-allowance-remaining` outputs repeat the first run's figures, though this run charged nothing. The API does not yet mark a repeat, so to add up what you were charged, read `GET /v1/usage`, not these outputs. **Allowance notices.** When a usage line reaches 75, 90 or 100 % of its monthly allowance since your last check, the job summary adds one line, for example "Report allowance: 90 % used (USD 4.50 of 5.00); resets 1 Nov; past the limit: metered at cost x 1.2". With no overage budget, or a budget of 0, it reads "past the limit: hard stop (overage budget USD 0.00)", and a report beyond the allowance and your top-up is refused until the reset. The overage budget limits only the part of a charge that your top-up does not cover, so a top-up stays spendable under a budget of 0. The free report balance does not renew, so its line reads "does not renew" where a monthly line reads its reset, adds ", and USD x is owed" when the balance is below zero, and ends "past the limit: reports stop". ## 9. Using collected files instead of a connection You can collect on one machine and check from another. Set `artefacts` to a directory that holds a `raw/` folder (or to the `raw/` folder itself). Leave `connection` empty. The directory must hold files under the names the profile reads. The API lists them for each profile (`GET /v1/profiles`). Files with other names stay in the runner and are listed in a notice. A symbolic link at an expected name is refused. Give the collector's output directory as it wrote it. The collector writes `raw/` and, beside it, `COLLECTION-SIDECAR.json` and `TIMING.json`. The Action takes those two files from beside `raw/` (or from inside `raw/`, if you moved them there) and sends them as `raw/COLLECTION-SIDECAR.json` and `raw/TIMING.json`. If both places hold a copy and the copies differ, the Action stops with `bad_input`. Do not leave out `COLLECTION-SIDECAR.json`: it is the collector's record of which lines it withheld whole and why. A configuration file that holds a line the earlier collector withheld (`# [collect_pg: line withheld, ...]`) cannot be checked without it, so the Action stops with `collector_refused` and sends nothing: a collector output without its sidecar cannot be checked. Keep `REDACTION-MANIFEST.json` too. The collector writes it beside `raw/` in the same run as the sidecar. It records the digest of each file as the collector wrote it, and what the collector withheld. When a file holds a withheld line, the Action uses it in the runner to check that the sidecar belongs to these files: the file must be unchanged since collection, and the manifest and the sidecar must record the same withheld lines. If the manifest is missing, records a different digest for such a file, or disagrees with the sidecar, the Action stops with `collector_refused` and sends nothing. Records from another run are caught only when a file that holds a withheld line differs, byte for byte, from that run's file. Records kept from an earlier run of the same server pass if the withheld lines sit at the same places with the same marker, even where a line that was a comment is now a rule. So always use the sidecar and manifest written by the same collector run as `raw/`. The manifest stays in your runner; it is never sent. With the collector this Action ships, a withheld rule or setting is a marker line that names its own line number and reason, so records from another run cannot hide it: the check reads that line as not observed whatever the records say. That collector's sidecar is recognised by its own fields; a collection that mixes its output with the earlier collector's stops with `collector_refused`. The earlier collector withheld a `pg_hba.conf` rule with a quoted name, an `@file` list or a regular-expression user whole, so its files stop there with `collector_refused`; collect again with this Action. Line continuation in `pg_hba.conf` (a line ending in `\`) depends on the server's major version. If `raw/declaration.json` gives a major on the other side of 16 from the one the sidecar records, and a `pg_hba.conf` line ends in `\`, the Action stops with `bad_input`. Set the declaration's `major` to the server's major. The declared profile, `postgresql-declared-model`, reads your declaration from `raw/declaration.json` (and optionally `raw/clients.json`) beside the collected files. [DECLARATIONS.md](/docs/declarations) explains how to write it, validate it for free locally, and review its assumptions and coverage gaps: ```yaml - name: Assure check from collected files uses: Symbolia-Assurance/assure-action@beta with: api-key: ${{ secrets.ASSURE_API_KEY }} profile: postgresql-declared-model artefacts: collected fail-on: fails ``` ### Bringing the folder to the runner The Action reads `artefacts` from the runner's working directory. Put the folder there before the Assure step, in one of three ways: - **Committed to your repository.** Add a step with `actions/checkout`, pinned to a full commit SHA. The complete workflow is below. - **Made by an earlier job.** That job uploads the folder with `actions/upload-artifact`; the job that runs the Action fetches it with `actions/download-artifact` in place of the checkout step. - **Collected in the same job.** Fetch the collector and run it in a step before the Assure step, as in "Running the collector yourself". The runner must then reach your database. Committing the folder puts what it holds into your repository's history: role names, ACLs, `pg_hba.conf` rules with client addresses, and the other items `DATA.md` lists as sent as written. Commit it only where everyone who can read the repository may read those. A complete workflow for the intent-free profile, with the collector's output committed as `collected/`: ```yaml name: Assure on: pull_request: push: branches: - main workflow_dispatch: permissions: contents: read jobs: check: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Check out the repository uses: actions/checkout@ - name: Set up Python 3.14 uses: actions/setup-python@ with: python-version: "3.14" - name: Assure check from collected files id: assure uses: Symbolia-Assurance/assure-action@beta with: api-key: ${{ secrets.ASSURE_API_KEY }} profile: postgresql-observed-baseline artefacts: collected fail-on: fails output: assure-verdict.json - name: Keep the verdict if: always() uses: actions/upload-artifact@ with: name: assure-verdict path: ${{ steps.assure.outputs.verdict-path }} ``` For the declared profile, set `profile: postgresql-declared-model` and commit your declaration as `collected/raw/declaration.json`. For a folder made by an earlier job, this step takes the place of the checkout step: ```yaml - name: Fetch the collected files uses: actions/download-artifact@ with: name: collected path: collected ``` The earlier job uploads the whole folder as the collector wrote it, under the name `collected`. The job that runs the Action names the collecting job in `needs:`, so it starts only after the upload; without it the two jobs run at the same time and the download finds nothing: ```yaml check: needs: collect runs-on: ubuntu-latest ``` ### Running the collector yourself The collector is `action/collector/collect_pg.py` in the `Symbolia-Assurance/assure-action` repository. Use it at the same ref as your `uses:` line. Fetch it on a machine that can reach the server and has Python 3.14 and `psql`: ```sh git clone https://github.com/Symbolia-Assurance/assure-action assure-action git -C assure-action checkout beta ``` Set the standard libpq variables for the server (`PGHOST`, `PGPORT`, `PGDATABASE`, `PGPASSWORD`, `PGSSLMODE`). Find the data directory first: ask the server with `psql -c 'SHOW data_directory'` ("A server on your own machine", below), and give that directory, as this machine sees it, in place of ``. Then run: ```sh python3.14 -B assure-action/action/collector/collect_pg.py --out collected \ --role assure_collector \ --privileges pg_read_all_settings,pg_read_all_stats \ --data-dir '' \ --role-created-for-run yes ``` | Flag | Meaning | |---|---| | `--out` | A new or empty directory for the output. Required. Any other directory is refused with exit 3 before anything is read. | | `--role` | The collection role's name inside the database (section 2). Required. | | `--privileges` | The roles granted to it, comma separated: `pg_read_all_settings`, `pg_read_all_stats` or both. Required. `pg_monitor` or `pg_stat_scan_tables` here is refused with exit 2. | | `--data-dir` | The server's data directory, as this machine sees it. Required, and it must be a directory that exists. When this machine cannot read the server's files, give an empty directory: every configuration file then reads as a recorded gap, as it does for the Action without `data-dir`. | | `--extra-root` | A directory outside the data directory that holds configuration files, such as `/etc/postgresql/18/main`. Once per directory. The collector reads configuration files only inside `--data-dir` and these directories. | | `--psql` | The `psql` command to run, when it is not `psql` on the path. | | `--role-created-for-run` | `yes` or `no`: whether you created the role for this run. The collector records your answer in `COLLECTION-SIDECAR.json`; left out, it records that you did not say. The collector itself creates, alters and grants nothing. | | `--login-user` | The login name, when a connection pooler's login name differs from the role (section 6). Left out, it is `--role`. | The collector logs in as `--login-user`, or as `--role` when that is not given. The collector never asks for a password: give it in `PGPASSWORD`, or in a password file `psql` reads. It prints one line of JSON and exits with one of four codes: | Exit | Meaning | |---|---| | 0 | Collected; every input was observed. | | 1 | Collected with gaps. `COLLECTION-SIDECAR.json` lists each one under `entries` with its status (`unreadable`, `missing` or `unsupported`), and `gap_count` counts them. Give the output as `artefacts`: each gap reads **not observed** with the place it was looked for. | | 2 | Invalid arguments. Nothing was read and nothing was written. The printed line, or the usage text before it, names the argument. | | 3 | A typed refusal. The printed line gives its `type` and its `reason`. A refusal during the collection removes everything the run wrote and leaves `REFUSAL.json`, with the same type and reason, as the only file in `--out`. A refusal before the collection, such as a `--out` that is not new or empty, writes no `REFUSAL.json`. | With the two roles of section 2, a collection usually ends with exit 1: the role cannot read the catalog views that only a superuser may read, `pg_hba_file_rules` and `pg_file_settings` and, from PostgreSQL 15, `pg_ident_file_mappings`, and each view it cannot read is a gap with the status `unreadable`. The collector still reads the configuration files themselves inside `--data-dir` and `--extra-root`. The refusals name the reason in their `type`: for example `collection_role_superuser`, `collection_role_not_read_only` or `collection_role_not_least_privilege` for a role section 2 does not allow, `collection_role_mismatch` when the role you connect as is not `--role`, `unsupported_major` outside PostgreSQL 14 to 18, and `redaction_selfcheck_failed` when its own check found a withheld value in its output. Recreate the role as in section 2, or fix what the reason names, and run it again into an empty directory. ### A server on your own machine For a PostgreSQL server on the machine you collect on, ask the server where its files are, as the user you normally connect as: ```sh psql -c 'SHOW data_directory' psql -c 'SHOW config_file' psql -c 'SHOW hba_file' ``` Give the data directory as `--data-dir`. When `config_file` or `hba_file` lies outside it, give that file's directory as `--extra-root`. Homebrew on Apple silicon keeps the data directory at `/opt/homebrew/var/postgresql@`, and Postgres.app at `~/Library/Application Support/Postgres/var-`; check with `SHOW` all the same. Read the `pg_hba.conf` that `SHOW hba_file` names. Where its `local` lines say `trust`, the role needs no password; create it without one: ```sql CREATE ROLE assure_collector LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS; GRANT pg_read_all_settings, pg_read_all_stats TO assure_collector; GRANT CONNECT ON DATABASE TO assure_collector; ``` In these statements `` is the name of the database to check, or `postgres` for a local server that holds no other database. Otherwise create it with a password as in section 2. The collector never asks for a password, so set `PGPASSWORD` for the collector's run only, and `unset PGPASSWORD` afterwards. Test the role first; it prints `assure_collector`: ```sh psql -U assure_collector -d -c 'SELECT current_user' ``` When `psql` is not on the path, as with a Homebrew server whose client is not linked, tell the collector where it is: `--psql /opt/homebrew/opt/postgresql@/bin/psql`. When you have finished collecting, drop the role, as the user that created it: ```sql REVOKE CONNECT ON DATABASE FROM assure_collector; DROP ROLE assure_collector; ``` To collect again later, create it again. ### Collecting again after a change A check on collected files reads the server as it was when you collected. After you change the server (a setting, a `pg_hba.conf` rule, a role or a grant), collect again. `--out` must be a new or empty directory, so remove the old output first, then run the collector as above and commit the new folder: ```sh rm -rf collected python3.14 -B assure-action/action/collector/collect_pg.py --out collected \ --role assure_collector \ --privileges pg_read_all_settings,pg_read_all_stats \ --data-dir '' \ --role-created-for-run yes ``` Keep `raw/`, `COLLECTION-SIDECAR.json` and `REDACTION-MANIFEST.json` from the one new run together. Running the workflow again without collecting again sends the same files: it gets the stored verdict of the first run back, and it says nothing about the change. The Action makes one check per distinct request. It derives its `Idempotency-Key` from the content of the request: a digest of the bundle's files, the profile, the selected scope and its binding, the requirements text, the repository and the commit sent with it, and the `allow-partial` word as sent. A later run whose request is the same, byte for byte, gets the stored verdict of the first run back, and it is not charged again. A changed byte in any file is a new check. So is a new commit or a changed `requirements.md`, even when the files are the same. A changed `fail-on` is the same check: `fail-on` is applied at render on the stored verdict, so each run's exit follows its own `fail-on`, and nothing is charged again. The Action sends `fail-on` in one canonical form in both modes, its words in lower case, without spaces, each once and sorted, so `fails,deviates`, `fails, deviates` and `deviates,fails` are one policy. A collection from a connection is never the same twice: the collector records when it collected and how long each query took. An HTTP check is never the same twice either: the Action makes a fresh identity key for each job, so the endpoint tokens differ from run to run. A stored verdict comes back when `artefacts` holds a collected bundle with the same files as an earlier run on the same commit, for example when you run a job again. A stored failure comes back the same way only when it was charged. A failure that was not charged, a timeout, an unexpected server fault or a restart keeps no key, so running the job again checks again. To check the same bundle again on purpose, set `fresh-check: true`: the Action then sends a random key, and the check runs and is charged again. The server keeps a key for as long as the verdict it points to (30 days). When the verdict is the stored one, the job summary says so under its first line, with the time of the first check, and that nothing was charged this run. A report that comes back stored sets `report-charge-usd` to 0, and its line names what the first check was charged. ## 10. Typed outcomes When the Action cannot produce a verdict, it writes a failure file at the `output` path (schema `assure.serve.failure/v1`) with `outcome`, `charged`, `reason` and `action`. In `mode: api`, `charged` is the one the server's failure envelope stated, copied as is. It is `false` when nothing reached the server (refused before a check was sent, or `mode: local`, which never contacts the API and charges nothing), and `null` when a check reached the server but the Action could not read what it charged (for example `api_unreachable` after the 202, or an older server whose envelope has no `charged`): read `GET /v1/checks/{id}` with the check id in the file. A `mode: local` verdict file says `charged` is `false` too. It also writes the reason to the job summary and one error annotation. When the API gave a check id, the failure file carries it. The last line of the summary says what left your runner: - "No check was sent." The Action stopped in your runner. Nothing was sent. - "The API refused the request for the profile list before anything was collected; nothing from your system was sent." The Action asks the API for the profile list first. A wrong or revoked key, or a rate limit, is refused there, before the Action collects or sends anything. - "The API refused the request before a check started; the collected files were sent and not kept." - "Check \. The check was sent; the API refused the poll for its result." - "Check \." The check reached the server. Report this id to Symbolia. - "No check id came back from the API." The request may have left your runner; no check id came back. | Outcome | Exit | What it means | What to do | |---|---|---|---| | `bad_input` | 2 | An input is missing or malformed, a required file is absent, both `connection` and `artefacts` were set, `api-key` is missing, or `api-url` is not `https://` (plain `http://` only for a loopback host). | Read the reason and fix the input. | | `oversize_input` | 2 | A required file, a checkout source file, the file count or the total size is over the limit (for `artefacts` and local directory collection, a file matching only an optional input is dropped and listed on the ignored line instead). | Remove files the profile does not read. Limits: 4 MiB per file, 2048 files, 8 MiB for the encoded request body. | | `unknown_profile` | 2 | The API serves no profile with that name. | Use a profile the API lists. | | `unauthenticated` | 2 | The API key is missing, unknown or revoked. | Check the `ASSURE_API_KEY` secret, or ask Symbolia for a new key. | | `key_expired` | 2 | The API key is past its expiry date. | Ask Symbolia for a new key and put it in the `ASSURE_API_KEY` secret. | | `rate_limited` | 3 | Too many checks in a minute or a day. The Action waits the API's `Retry-After` when it is at most 60 seconds and sends the same request again, for up to 300 seconds of waits on each request. | Run again later. | | `credit_exhausted` | 3 | The account's free credit is spent. | Contact Symbolia. | | `server_busy` | 3 | The API's queue stayed full, or the first send of the check was still being checked when the Action sent it again (issue #2601): the Action sends the check again after each refusal, three times in all, or more while the API names a `Retry-After` of at least 1 s and those waits add up to at most 300 s (five 60 s waits); between sends it waits the API's `Retry-After` when it is at most 60 s, or a longer one within the same 300 s; the 300 s the Action waits for the check itself starts when the queue admits it. The sign-in stops after three attempts. | Run again in a minute. | | `api_unreachable` | 3 | The runner could not reach the API: three attempts, then, on the check's send and on the poll of a sent check, retries with backoff (1, 2, 4, 8, then 15 s) while those waits stay within 300 s; the reason names the attempts and the seconds waited. | Check outbound HTTPS from the runner to `api.symbolia.ai`. | | `api_error` | 3 | The API answered in a way the Action does not accept, after three attempts where a retry applies; a 5xx without a failure envelope on the check's send or on the poll of a sent check is retried like `api_unreachable`, for up to 300 s of waits. | Run again later. If it repeats, report the check id to Symbolia. | | `engine_digest_mismatch` | 3 | The server's engine does not match its pin, so it runs no check. | Report it to Symbolia. | | `not_found` | 3 | The API holds no check with that id for this account. | Run the check again. | | `server_fault` | 3 | A record the API keeps for this account no longer reads as it was written. No check ran and nothing was charged. | Report the check id to Symbolia. | | `collector_cannot_connect` | 3 | The first query could not reach the database, or `psql` is missing. | Check the secret, the network path from the runner and `pg_hba.conf`. Install `postgresql-client`. | | `collector_refused` | 3 | The collector refused the collection. Some refusals come before it reads anything: the role is too broad (a superuser, or a member of `pg_monitor` or `pg_stat_scan_tables`; the reason says what to grant), the major is outside 14 to 18, or the role name does not match (behind a connection pooler, the reason says which name to set as `collection-role`; section 6). Others come after it has read: its self-check found a withheld secret value in its own output. The Action also refuses in the runner when a collection mixes this collector's output with the earlier collector's; when files from the earlier collector hold a whole `pg_hba.conf` rule (a quoted name, an `@file` list or a regular-expression user) or `postgresql.conf` setting line that collector withheld; and when a file holds a line the collector withheld but its `COLLECTION-SIDECAR.json` is missing or has no record of that file, or its `REDACTION-MANIFEST.json` is missing, records a different digest for that file, or disagrees with the sidecar. The reason names the file, the lines and the collector's reason, never a line's text. In every refusal it keeps no collected data, and nothing is sent. | Read the reason. For a role refusal, recreate the collection role as in section 2. For a missing or mismatched `COLLECTION-SIDECAR.json` or `REDACTION-MANIFEST.json`, give `raw/`, the sidecar and the manifest from one collector run as it wrote them (section 9). For a withheld `pg_hba.conf` rule in the earlier collector's files: collect again with this Action. If you cannot: remove quotes a name does not need, write an `@file` list's names inline, use a `+group` role in place of a list, or list a regular-expression user's roles by name. Otherwise, send Symbolia the file name and the line number through your Symbolia contact, so the shape is counted. | | `profile_not_servable` | 3 | The server holds no qualified checker for this profile, or the checker it holds cannot import a module the server tree lacks (`detail.rule: pipeline_import`; not charged). | Use a served profile. For `pipeline_import`, nothing on your side opens it; Symbolia redeploys. | | `profile_refused` | 3 | The checker refused the collected input with a stated reason, for example because the major version was not observed. | Read the reason. Check that collection completed. | | `checker_error` | 3 | The checker failed in an unexpected way, for example a crash. A check the server restarted during also reads `checker_error`; its reason says to submit it again. | Report the check id to Symbolia, or submit the check again when the reason says so. | | `checker_timeout` | 3 | The check ran longer than its time cap, or did not finish within 300 seconds of waiting; the `rate_limited` waits before the API admitted it are not counted. | Run again. If it repeats, report the check id to Symbolia. | | `checker_cpu_limit` | 3 | The check used more than its CPU time limit. | Run again. If it repeats, report the check id to Symbolia. | | `checker_memory_limit` | 3 | The check used more than its memory limit. | Run again. If it repeats, report the check id to Symbolia. | A collection with gaps is still a verdict. Each gap reads **not observed** with the place it was looked for. `tier_excludes` never ends a job. With the report on, it would mean your account's plan does not include the report; no plan served today excludes it, and a free account without its USD 1 report grant is refused `allowance_exhausted` instead. Either way the verdict, its summary and its exit stand, and the summary says the report was withheld. Set `report: false`, or ask Symbolia to grant the free report balance or move you to a paid plan. `rotate_too_early` never ends a job. It is only answered by the API's key rotation route (`POST /v1/keys/rotate`), which the Action never calls: the key was asked to rotate before its last 7 days, and it still works. `billing_unavailable` never ends a job. It is only answered by the API's billing routes, which the Action never calls: billing is not configured on that server, or Stripe could not be reached. The verdict, its summary and its exit stand. `tier_required` never ends a job. It is only answered by the API's paid formalisation routes, which the Action never calls: paid formalisation is on Premium (USD 20 a month) and above. The verdict, its summary and its exit stand. `allowance_exhausted` never ends a job either. With the report on, it means your plan's allowance is not set or is spent for the month, and nothing pays for the report (overage is off until you set a budget): the verdict, its summary and its exit stand, and the summary names the USD needed. Ask Symbolia to set an overage budget and set `allow-overage: true`, or to top up your account. On the free plan, it means your report balance is spent, and the summary says so. `overage_ceiling` never ends a job: this month's report overage billed later, beyond your top-up, would pass a monthly overage limit set on your account, so the report does not run, even with `allow-overage`. Your top-up is spent before any overage, whatever the limit. `job_ceiling` never ends a job: the report's quote is above your account's job ceiling, so the report does not run, even with `allow-overage`; the summary names the quote and the ceiling. `daily_report_cap` never ends a job: your account has had its reports for the day (UTC). Nothing runs and nothing is charged for any of them. ## 11. Profiles - `postgresql-declared-model` checks your server against a declaration you supply in `raw/declaration.json` (and optionally `raw/clients.json`). With `artefacts`, add your declaration under `raw/`. With `connection` (in `mode: api`) the Action collects as for the observed profile and reads `.assure/postgresql-declared-model.json` (else `.assure/declaration.json`, where an earlier proposal was merged) from the checkout (`GITHUB_WORKSPACE`) and places it in the collected bundle as `raw/declaration.json` before the withholding pass and the bundle limits, so its `declared_predicate` string literals are withheld exactly as an artefacts directory's are, with the same numbering as the snapshot; a link, a linked `.assure/` directory, or a file that is not a regular readable file is refused (`bad_input`). The `declaration` input stays refused with a PostgreSQL connection. When the checkout has none and the collector's sidecar names a server major from 14 to 18, the Action drafts one from the collected catalog snapshot (drafted before the withholding, so the draft holds your own literals and reads the same after you merge it), sends the draft, writes `assure-declaration-proposal.json` beside the verdict file (the `mode: api` verdict path) and opens one pull request of its own on `assure/declaration-proposal` proposing `.assure/postgresql-declared-model.json` (it never commits to your branches; the workflow needs `contents: write` and `pull-requests: write`); merging it is the acceptance. Until then the result is bounded by an unaccepted draft and the step output says `declaration=unaccepted-draft`, as on a pull request whose declaration is not yet on the base branch. With no server major to draft from, and in `mode: local`, a connection with this profile still reads `bad_input` for the missing `raw/declaration.json`. - `postgresql-observed-baseline` reads your server and compares it with observed facts and pinned public baselines. You declare nothing. - `http-observed-baseline` reads the response heads you captured for the HTTP endpoints you select (section 12). - `mysql-declared-model` checks a MySQL server against a `mysql://` connection and your declaration file (`declaration`), or against an artefacts directory holding `raw/submission.json`. Seven machines read it, M1 to M4, M6, M7 and M8, and the check contacts no server. A report is withheld with `profile_unqualified` until the report writer is qualified for MySQL. What each profile claims, and what it does not, is in [SCOPE.md](/docs/scope) and, for `http-observed-baseline`, in section 12. What is collected and where it goes is in [DATA.md](/docs/data). ## 12. Checking HTTP endpoints `http-observed-baseline` checks one HEAD response per endpoint you select against the HTTP obligations Assure holds (response framing, transport policy, cookies and similar). Live collection against real endpoints is not in this release: the Action reads response heads you captured, offline. `connection` is refused for this profile, before anything is read. Give the Action an artefacts folder that holds: - `manifest.json`, with these ten keys exactly: `"schema_version": "http-fixture-001"`, `"mode": "offline_fixture"`, `endpoints`, and the seven flags at the values shown below (`execution_authorized`, `hardware_authorized`, `industrial_release_authorized`, `release_allowed`, `physical_validation` and `self_approved` false; `simulation` true). Any other key, a missing key or another value makes the Action stop before anything is sent (`MANIFEST-INVALID`). `endpoints` is a list of 1 to 16 objects with exactly these keys: `id` (`endpoint-NNN`, three digits), `scope_token` (a lower-case name you choose, distinct per endpoint), `scheme`, `host`, `port`, `path`, `response_file` (the head file's name in the folder) and `complete` (`true` when you captured the whole head); - one file per endpoint holding the raw response head as received: the status line and every header line, each ending in CRLF, and the empty line that ends the head. A complete `manifest.json` for two endpoints: ```json { "schema_version": "http-fixture-001", "mode": "offline_fixture", "endpoints": [ {"id": "endpoint-001", "scope_token": "checkout", "scheme": "https", "host": "shop.example.test", "port": 443, "path": "/checkout", "response_file": "head-001.txt", "complete": true}, {"id": "endpoint-002", "scope_token": "login", "scheme": "https", "host": "shop.example.test", "port": 443, "path": "/login", "response_file": "head-002.txt", "complete": true} ], "execution_authorized": false, "hardware_authorized": false, "industrial_release_authorized": false, "release_allowed": false, "physical_validation": false, "simulation": true, "self_approved": false } ``` ```yaml - name: Assure check uses: Symbolia-Assurance/assure-action@beta with: api-key: ${{ secrets.ASSURE_API_KEY }} profile: http-observed-baseline artefacts: http-fixture ``` The inputs: `profile: http-observed-baseline`; `artefacts`, the folder above. `scope` is optional: a JSON file listing the endpoint ids to check, which must name exactly the manifest's ids (the Action stops before collecting otherwise). Leave `scope-binding` unset so the Action produces it: before collection it runs the identity producer and then the collector over your manifest, and sends their record as the scope binding with the endpoint tokens. `identity-key` stays `pipe`, its default: the Action makes a fresh key for each job and passes it on a pipe, so no key is an input, an environment variable or a file. A `scope` file, when you give one, is a JSON list of the manifest's ids, for example `["endpoint-001", "endpoint-002"]`. Each run of an HTTP check is a new check, charged as one: the Action makes a fresh identity key for each job, and no key is kept from one run to the next, so a new collection is new work. The verdict's `observed_facts` holds, for each observed endpoint, the facts its readings used (the status code and the HSTS, CSP and cookie attributes, never a cookie value or a redirect URL), so you can explain a reading without collecting again. ### Capturing the response heads Capture each head with `curl`, one HEAD request over HTTP/1.1, and write it to the file the manifest names: ```sh mkdir -p http-fixture curl -sS --http1.1 -I https://shop.example.test/checkout > http-fixture/head-001.txt curl -sS --http1.1 -I https://shop.example.test/login > http-fixture/head-002.txt head -n 1 http-fixture/head-001.txt ``` `-I` sends a HEAD request and writes the head as received, every line ending in CRLF, with the empty line that ends it. `--http1.1` matters: the first line of each head must be an HTTP/1.1 status line, such as `HTTP/1.1 200 OK`. A head whose first line is another version, such as `HTTP/2 200` from a capture without `--http1.1`, or `HTTP/1.0 200 OK` from a server that answers in HTTP/1.0, is recorded as not observed. Without `-L`, `curl` does not follow a redirect, so a `3xx` head is the endpoint's own answer. The `host` in each manifest endpoint must be the same host as the URL you capture with `curl`. Set `complete` to `true` for each head you captured this way. A complete workflow for the HTTP profile captures the heads in the job. Commit `http-fixture/manifest.json` alone; one step per endpoint runs `curl` and writes that endpoint's head beside it. Every run then checks fresh heads, and no captured head is committed to your repository. ```yaml name: Assure HTTP on: pull_request: push: branches: - main schedule: - cron: "17 3 * * *" workflow_dispatch: permissions: contents: read jobs: http: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Check out the repository uses: actions/checkout@ - name: Set up Python 3.14 uses: actions/setup-python@ with: python-version: "3.14" - name: Capture the head of /checkout run: curl -sS --http1.1 -I https://shop.example.test/checkout > http-fixture/head-001.txt - name: Capture the head of /login run: curl -sS --http1.1 -I https://shop.example.test/login > http-fixture/head-002.txt - name: Assure check id: assure uses: Symbolia-Assurance/assure-action@beta with: api-key: ${{ secrets.ASSURE_API_KEY }} profile: http-observed-baseline artefacts: http-fixture fail-on: fails output: assure-verdict.json - name: Keep the verdict if: always() uses: actions/upload-artifact@ with: name: assure-verdict path: ${{ steps.assure.outputs.verdict-path }} ``` Each run is a new check, even when the heads are the same as the last run's, byte for byte: the Action makes a fresh identity key for each job, so the endpoint tokens it sends differ from run to run (section 9). You can instead commit the captured heads with the manifest and leave out the capture steps. Use this offline route when you must reproduce a check on a fixture that does not change, for example heads you captured once to keep as a record. Every reading summary carries the profile's three scope notes: - Readings cover one HEAD request per operator-selected endpoint. - Evidence freshness and response authenticity are unverified; same-selection replay is not excluded. - Per-endpoint coverage qualifications are not displayed in this report. A full read of the two `https` endpoints above has the first line "green: 2 of 2 endpoints observed; 4 of 5 machines read, 1 refused; declared premises: 12; version pins: none; nothing disproven; established: 3 of 12; vacuous: 3; not established: 6 — top action: collect the facts HTTP-TLS10-NEGOTIATION reads": the TLS machine (M2) is refused with "no usable observed machine premise", because a captured head carries no TLS session. That is a bound of the result, so the run exits 0. For `http://` endpoints M2 reads vacuous and the first line is "green: 2 of 2 endpoints observed; 5 of 5 machines read; declared premises: 12; version pins: none; nothing disproven; established: 3 of 12; vacuous: 6; not established: 3 — top action: declare redirects in raw/HTTP-INTENT.json beside the collected files (docs/customer/VERDICTS.md); requirements.md cannot state an HTTP requirement in this release". A head that carries both `Content-Length` and `Transfer-Encoding` fails `HTTP-FRAMING-CL-TE`, and under the default `fail-on: fails` the job exits 1, red. Those three not-established rows are HTTP-REDIRECT-POLICY, HTTP-RESPONSE-POLICY-ADEQUACY and HTTP-COOKIE-POLICY: an `HTTP-INTENT.json` you write beside `manifest.json` (issue #2381; its shape is in docs/customer/VERDICTS.md) is sent as `raw/HTTP-INTENT.json` and decides each row whose key it carries (`redirects`, `response_headers`, `cookies`) instead of reading it `needs_intent`. Choose endpoints that answer HEAD with 2xx or 3xx; a 4xx or 5xx endpoint hides policy checks for the whole run and the verdict's `warnings` names them. No HTTP requirement can be stated in this release: a `requirements.md` sentence on this profile cannot hold. HTTP-REDIRECT-POLICY, HTTP-RESPONSE-POLICY-ADEQUACY and HTTP-COOKIE-POLICY ask for the `HTTP-INTENT.json` key that decides each (issue #2381); the other readings inform and ask nothing of you. The policy exits are those of section 7. `policy.reason` takes exactly one of these eight values, the serving core's closed list, in the source's order (the policy decides them in the order docs/customer/VERDICTS.md section 9 gives): - `never` (0, as the readings give) when your `fail-on` is `never`; a prove-class obligation that is not proven still exits 1 as `not_proven`. - `could_not_look` (3, yellow) when nothing could be read at all: the input gate stopped the check, no machine was read, or no selected unit was observed. - `disproven` (1, red) when a reading on a read machine has a status your `fail-on` names; a disproof your `fail-on` leaves out keeps this reason, red, with exit 0. - `not_proven` (1, red) when a prove-class obligation has no `holds` on a machine that was read, under every `fail-on`. - `unresolved_strict` (1, red) when under `fail-on: unresolved-security`, an obligation marked `security: true` is unresolved. - `stopped_by_choice` (1, red) when a reading has a status that is not a verdict and that your `fail-on` names, such as `not_observed`. - `nothing_disproven` (0, green) when nothing is disproven, whatever endpoints or machines could not be read. - `platform_owned` (0, red) when every disproof your `fail-on` names is platform-owned, someone else's to fix. A `fails` reading whose findings are all platform-owned keeps the colour red with exit 0 and `policy.reason` `platform_owned`: the disproof is someone else's to fix. ## 13. Checking MySQL from a submission `mysql-declared-model` checks a MySQL server against a `mysql://` connection and your declaration file, or against an artefacts directory holding `raw/submission.json`. **With a connection (the collector runs in your runner):** set `connection` to a `mysql://user:pw@host:port/` URI or a keyword/value string (`mysql host=… port=… user=… password=…`), `profile` to `mysql-declared-model`, and `declaration` to the path of your declaration file (`symbolia.mysql-declaration.v0`). The password reaches the collector by environment only (`MYSQL_PWD`), never on a command line. `collection-role` defaults to the user in the connection. Write a `/` in the user name or password as `%2F` (percent-encoding); the port is digits only, 1 to 65535. ```yaml - uses: Symbolia-Assurance/assure-action@beta with: connection: ${{ secrets.MYSQL_URL }} declaration: assure/mysql-declaration.json profile: mysql-declared-model api-key: ${{ secrets.ASSURE_API_KEY }} ``` **With artefacts (you collect yourself):** give the Action an artefacts folder that holds one file, `raw/submission.json`. Its schema is `symbolia.mysql-declared-input.v0`. It carries `collection`, `declared_policy`, `grant_tables`, `mysql_user`, `system_variables`, `replication_channels`, `version` and `configuration_sha256`, with `material` set to `mysql` and the seven flags at their standing values (`execution_authorized`, `hardware_authorized`, `industrial_release_authorized`, `release_allowed`, `physical_validation` and `self_approved` false; `simulation` true). The check reads the file and contacts no server. Seven machines read it: M1, M2, M3, M4, M6, M7 and M8. A machine whose section the submission lacks reads `representation`, with the machine's own reason. A submission that holds a secret, such as a password or a key, is refused before anything is read, and the refusal names the path and the kind, never the value. A report for this profile is withheld with `profile_unqualified` until the report writer is qualified for MySQL. `/v1/profiles` lists the profile's 50 obligations with the states each can take (`holds`, `not_established`, `disproven`, from what its machine can produce), a `requirements.md` line that quotes an obligation binds to it, and the report page names the MySQL areas. The report stays withheld until the writer qualifies for MySQL. Formalisation is not offered for this profile. ## 14. Checking a Python (Flask) repository `python-auth-declared-model` checks how a Flask app signs people in and guards its routes. It reads your code as text and never runs it. The check is free and contacts no server of yours. A whole workflow. It grants `id-token: write` so the Action signs in with your workflow's GitHub identity and you store no key, and `contents: write` and `pull-requests: write` so the Action can open its proposal (below). Set `profile`; leave `artefacts` and `connection` empty: ```yaml name: Assure on: pull_request: push: branches: - main permissions: contents: write id-token: write pull-requests: write jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - name: Set up Python 3.14 uses: actions/setup-python@ with: python-version: "3.14" - name: Assure check id: assure uses: Symbolia-Assurance/assure-action@beta with: profile: python-auth-declared-model - name: Keep the verdict if: always() uses: actions/upload-artifact@ with: name: assure-verdict path: ${{ steps.assure.outputs.verdict-path }} ``` The Action reads the checked-out repository: its tracked Python files and `requirements.md`, at most 2000 Python files of 512 KiB each, within 2048 upload entries including manifests and an 8 MiB encoded request body. It writes `raw/REPOSITORY.json` (each file's bytes, sha256 and git mode, the commit and the tree id) itself. **The declaration arrives as a proposal.** The check reads your app against a declaration at `.assure/declaration.json`: your app objects, the session key that means "signed in", your guard decorators, the views that sign people in, raise privilege and sign out, and the routes that are public on purpose. On the first run there is none, so the Action sends the bounded repository bytes to the free declaration proposal route, whose drafter uses the checker's own readers, and runs the check on the returned draft. When the repository's Python files import FastAPI or Django and no other web framework, the Action asks the route for that stack's draft (`stack: python/fastapi` or `python/django`) and the pull request says which stack it was drafted for; any other repository is drafted as Flask. A field the bytes do not give remains unread in the proposal for you to review. When your Flask app loads its configuration by name (`from_pyfile`, `from_object`, `from_envvar`) from a file or module the check reads as outside the repository (flaskr's `app.config.from_pyfile("config.py")` with no `instance/config.py`, or `from_envvar`; a `from_pyfile` or `from_object` name that is not a literal is not read, and drafts nothing), the draft proposes `instance_config: "constants-only"` as a field to confirm, read at that call: keep it only if that configuration assigns constants. Assure never commits to your branches; it opens one pull request proposing each profile's draft at its own path under .assure/; merging it is the acceptance. The pull request, `Assure: proposed intent — review and merge to accept`, comes from Assure's own branch `assure/declaration-proposal` into your base branch (the pull request's base, or your default branch on a push), and changes only the drafts' files: python-auth's `.assure/declaration.json` and `postgresql-declared-model`'s `.assure/postgresql-declared-model.json`, side by side when both profiles run on one repository, its description holding one section per file. Its description and the job summary list each field to confirm with the file and line it was read from. A later run updates the same pull request, keeping the other profile's file, in the shallow checkout `actions/checkout` leaves too; it never opens a second one. Its description opens by naming the file this run is proposing. A branch on an older base tip, or one holding a file its description does not name (a proposal opened before one pull request carried both profiles), is rebuilt from the base branch's tip, carrying over each draft under `.assure/` whose section its description holds (with that section); a file it does not name is left behind. Which profiles draft intent: `python-auth-declared-model` drafts `.assure/declaration.json`; `postgresql-declared-model` reads the declaration supplied with the run, and drafts one only on its own connection run with no `.assure/declaration.json` in the checkout, proposing it in Assure's pull request (the job summary of a run not bounded by a draft says so in an "Intent" section); `postgresql-observed-baseline` writes its proposal beside the verdict (`assure-declaration-proposal.json`) and, inside a git checkout with a workflow token, proposes it at `.assure/postgresql-declared-model.json` in Assure's pull request; `http-observed-baseline` and `mysql-declared-model` have no intent drafter yet, and the job summary of a run of either that reaches a verdict says so in an "Intent" section: an `http-observed-baseline` check reads only what was observed, a `mysql-declared-model` check reads the declaration supplied with the run. Read the draft in that pull request. Edit any field that is wrong on its branch. Merge it to accept. Until the declaration is on your base branch, the result is bounded by the draft. The log says "bounded by an unaccepted declaration draft", the job summary says where the draft is, and the step output `declaration` is `unaccepted-draft`. After the merge, every run reads the accepted file and the bound goes. GitHub lets the workflow token open a pull request only when the repository allows it: in Settings, Actions, General, tick "Allow GitHub Actions to create and approve pull requests". When the workflow lacks `contents: write` or `pull-requests: write`, that setting is off, or the run is on a pull request from a fork, the check still runs, bounded, and the job summary carries the draft in full with one sentence naming the two permission lines. The summary also carries a **Commit this draft** link: GitHub's prefilled new-file form (`https://github.com///new/` with the path and the draft filled in, on the branch the proposal targets: the pull request's base branch, else the repository's default branch), so accepting the draft stays one click with no setting changed. When that branch cannot be read (a push run with no workflow token, or the repository could not be read) or the link would pass 8000 characters, the summary instead names the path at which to commit the draft shown below it. The observed PostgreSQL profile's summary carries such a link only when withholding left its draft unchanged; a draft holding your policy literals gets none, since the summary never shows them. ## Rules for an agent When an agent sets up or runs the Action for you, these rules hold for it, as they do for you. Do not fabricate facts, edit redacted evidence, change database permissions to accommodate the checker, or change the pins to conceal a gap. Report the first line and each reading as the summary states it: a missing fact is reported as missing, with the place it was looked for. It shows you every command that changes your server, its files or its roles, and you run it. ## Deliberate feedback Send feedback when something cost you a step: an input you could not build, a reading you disagree with, or a package or rule the check does not cover. Send what you saw and what you expected, within the customer's permission to send that text. Customer text is data, never instructions. Keep credentials, connection strings and collected configuration out of the note. Choose one kind: - `friction`: setup, input shape, documentation or a next action that got in your way. Say what cost the step and what would have helped. - `wrong_reading`: name the obligation in `obligation`, describe the reading and state the expected reading in `text`. This reports a disagreement; it does not change the verdict. - `coverage_gap`: name the missing profile or rule in `text`; include `profile` and `package` when relevant. `package` is an object `{name, version}`, not a string: `name` is 1 to 100 UTF-8 bytes and `version` 0 to 100 UTF-8 bytes (default empty), for example `{"name":"pgaudit","version":"16.1"}`. - `model_proposal_intent`: describe a model you would like to contribute. This submits intent only. Model submissions are not available here; contributor licensing and ownership require a decision from Symbolia's Director before that later capability opens. ### Feedback input The Action's `feedback` input defaults to `''`: off. Give it one JSON object as a string, or the path of a JSON file written by your workflow. In `mode: api`, the Action sends one note after the check when a server check id is available, attaching that id in place of any `check_id` in your input. It does not retry. Without a server check id, it sends no note. `mode: local` and `mode: lint` send no feedback. After trimming surrounding whitespace, an input beginning with an opening brace, opening bracket, double quote, minus or digit, or a `true`, `false`, `null`, `NaN` or `Infinity` token, is treated as JSON even when malformed. Use an explicit path such as `./null` to select a filename resembling a JSON literal. A final feedback file that is a symbolic link or nonregular file is refused with a fixed `bad_input` feedback summary; the check's exit, outputs and verdict file stay unchanged. ```text {"kind":"friction","text":"The input instructions did not say which folder to pass. I expected an example folder layout.","consent_follow_up":false} ``` Write that JSON to a file in the workflow's working directory and use its path under the Action step's `with` block: ```yaml feedback: feedback.json ``` A feedback error adds a typed outcome to the job summary; it never changes the check's exit, outputs or verdict file. Without a server check id, a requested note adds `bad_input` to the feedback summary and no POST is made. A delivery error means receipt is not confirmed: the server may already have stored the note. Known input secrets are refused before posting. The note's text is not echoed into commands or the summary. The report is opt-in (`report: true`, `mode: api`). Reports are written for `postgresql-declared-model` verdicts today; for other profiles the report is withheld with `profile_unqualified`, without a model call. `report: false` stops the check record going to OpenRouter. Deliberate feedback is separate: it does not go to a model, and `report: false` does not turn it off. ### Feedback API `POST /v1/feedback` accepts one UTF-8 JSON object, with no duplicate keys, non-finite numbers or extra keys. Authenticate with the same API key as checks, in the `Authorization: Bearer` header. Send `Content-Type: application/json` and one `Content-Length`; no transfer encoding or query parameters. | Field | Required | Form | |---|---|---| | `kind` | yes | One of the four kinds above. | | `text` | yes | 1 to 4,096 UTF-8 bytes; valid Unicode, no control characters except newline and tab. | | `check_id` | no | 32 lower-case hexadecimal characters, or null. The direct API accepts an unknown id. | | `profile` | no | 1 to 64 characters: first a letter or digit, then letters, digits, underscores, dots or hyphens; or null. | | `profile_wanted` | no | 1 to 64 characters: first a letter or digit, then letters, digits, underscores, dots or hyphens; or null. The profile a `coverage_gap` note wishes existed; the digest counts notes by it. | | `obligation` | no | 1 to 64 letters, digits, underscores, dots or hyphens; or null. | | `package` | no | An object with required `name` (1 to 100 UTF-8 bytes), optional `version` (0 to 100 UTF-8 bytes, default empty), and no other keys; or null. No control characters. | | `agent` | no | An object with optional `model_id` and `client` (each 0 to 100 UTF-8 bytes, default empty), and no other keys; or null. No control characters. | | `consent_follow_up` | no | Boolean; false by default. Null also means false. True permits follow-up about this note. | Every field in one body, as the route accepts it: ```text {"kind":"coverage_gap","text":"No rule reads the pgaudit settings. I expected a reading of pgaudit.log.","check_id":"0123456789abcdef0123456789abcdef","profile":"postgresql-declared-model","profile_wanted":"postgresql-pgaudit","obligation":null,"package":{"name":"pgaudit","version":"16.1"},"agent":{"model_id":"example-model-1","client":"example-agent/1.0"},"consent_follow_up":false} ``` A refusal of the body's fields (an unknown key, a missing `kind` or `text`, a wrong type or form) is `bad_input` (400) whose `detail.accepted_fields` lists the nine keys above, sorted, and whose `detail.kinds` lists the four kinds, so one refusal names the whole accepted shape. `detail.shapes` gives each key's form: `package` is `{name, version}`, `agent` is `{model_id, client}`, `kind` lists the four kinds, `consent_follow_up` is `boolean` and every other key is `text`; `detail.example` is one minimal valid body, the friction example this section prints. The reason for an unknown key names that key; no value is ever echoed. A refusal of one named field also carries `detail.malformation.pointer`, that field's JSON pointer (such as `/check_id`); a body that is not one JSON object carries none. A value or key that carries an Assure API key (`asr_`, an 8-hex key id, `_` and a 43-character secret) is refused `bad_input` and nothing is stored: a value's refusal names its field, and such a key is never named. A body that is not UTF-8, is not JSON or repeats a key is refused before its fields are read: `bad_input` (400) with `detail.malformation.kind` `body_not_utf8` or `body_not_json`, and without `accepted_fields`, `kinds`, `shapes` or `example`. The request body limit is 16,384 bytes. Feedback is free on every plan, with no charge or usage ledger row. Each POST uses the same per-account minute rate window as checks; a repeat still uses that window. Up to 100 new notes per account per UTC day are accepted. Within one account and UTC day, the same kind, check id and exact text returns the first note with `duplicate` set to `true`, without a new row or another daily slot. Changing other metadata alone does not change that identity. A rate refusal is `rate_limited` (429) with `Retry-After`; a daily refusal names `window` set to `day` and the wait until midnight UTC. POST returns 200 with `schema`, `id`, `received_at`, `kind`, `check_id`, `profile`, `obligation`, `package`, `sha256`, `duplicate`, `related`, `routed` and the response flags; it does not echo the text. `check_id`, `profile` and `obligation` are the stored row's values (null when not sent) and `sha256` is the stored row's deduplication SHA-256, the hash of `kind|check_id|text` rather than of the text alone, so a record can cite the note without trusting its own request body; on a duplicate they are the first row's. `related` lists this account's other notes of the same kind and profile whose `status` is not `merged` or `declined`, among its notes of the newest 7 UTC-day files, newest first and at most 10, each as `id`, `kind`, `profile`, `status` and `match` (`kind+profile`), so a second note on one gap can see the first; when the note has no profile it lists the open notes of the same kind of any profile, null included, each with `match` `kind`. `routed` says where the note goes next: `digest`, the daily agent feedback digest that reads it (`Agent feedback digest YYYY-MM-DD`, the note's UTC day), `status_route`, the `GET /v1/feedback/{id}` route that answers its state, and `next`, one sentence naming both. `GET /v1/feedback/{id}` returns 200 with the stored row, including text, the account and key ids, timestamp, metadata, the deduplication SHA-256, `check_known`, `rows_unreadable` and response flags. `check_known` records whether that account held a verdict for the supplied check id at submission time; it is not a live lookup. `rows_unreadable` counts unreadable lines in that note's UTC-day file, including zero. `status` is the note's state as Symbolia acts on it: `received` until then, `in_pr` with the pull request number `pr`, `merged` with `release`, the engine commit that ships the change, or `declined` with a `reason`; `updated_at` is when it was set. When the state cannot be read just now it reads `unavailable` with a `reason`, and the note still answers. A malformed, absent or another account's id returns the same `not_found` (404). Neither route accepts query parameters. Notes are kept for 12 months, with retention and removal on request handled by the operator. The daily digest reads notes without changing them: counts by kind, counts by profile wanted with distinct account counts, packages by kind with distinct account counts, bounded text from every kind for triage regardless of consent, notes consenting to follow-up, and friction notes by check id. Consent controls follow-up only; it does not hide a submitted note from triage. Account ids appear as stable short hashes. Customer text appears only in fenced data blocks marked `DATA>`, with control and format characters removed and display length bounded. The digest reports skipped or unreadable files and unreadable rows, including zero. When the feedback collection cannot be accessed, the digest stops with an error instead of reporting an empty day. Feedback is not read by the checker or report writer. No automatic demand-ledger entry or model proposal is created.