Skip to content
Back to skills

Constraints

ASecurity

Which constraints forge db seed can satisfy — CHECKs over one or several columns, UNIQUE, ranked bounds, and status-lifecycle rules written as one-way implications rather than biconditionals, with what the seeder does with a guard it cannot place.

  • 10 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 13, 2026
ai-agentsgosqlawstestingdatabase

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill constraints --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Constraints?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Constraints
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-constraints-forge/badge)](https://www.skillsdirectory.com/skills/reliant-labs-constraints-forge)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: constraints
description: Which constraints forge db seed can satisfy — CHECKs over one or several columns, UNIQUE, ranked bounds, and status-lifecycle rules written as one-way implications rather than biconditionals, with what the seeder does with a guard it cannot place.
---

# Constraints

Values **forge** synthesizes are satisfied by construction, not validated after
the fact — forge derived the CHECK from your proto field rules, so it generates
inside it. Synthesized strings are fitted to `char_length` / `varchar(n)` caps,
numbers to range CHECKs, enum columns draw from the CHECK vocabulary, and a
single-column UNIQUE column draws **without replacement** so it never collides
(a deeper value pool does not fix a colliding draw — drawing without
replacement does).

A column with a **regex** CHECK — the one a `string.email` or a `string.pattern`
field rule projects into — is seeded from the pattern itself, so the value
matches whatever you declared and does so whatever the column is called:

```sql
CREATE TABLE accounts (
    contact TEXT NOT NULL CHECK (contact ~ '^[^@\s]+@[^@\s]+\.[^@\s]+$'),
    reference TEXT NOT NULL CHECK (reference ~ '^SKU-[0-9]{4}$')
);
-- seeds  contact = 'user1@example.com', …   reference = 'SKU-0001', 'SKU-0002', …
```

The email CHECK is the one pattern seeded by its meaning rather than its
shape: the shape alone gives `1@1.1`, which satisfies the CHECK and fails the
form's `.email()` validator, so a seeded row could not be saved from its own
edit page. `example.com` is reserved for exactly this.

Anything genuinely unsatisfiable is resolved at **plan** time, before a single
INSERT: a UNIQUE column backed by a 5-value CHECK vocabulary can never carry 20
rows, so its table caps at 5 and the plan says so — the same cap a 1-1 foreign
key already gets.

A **cross-column ordering** CHECK (`expires_at > issued_at`) is placed: the pass
ranks the columns and assigns each a value above its lower bound, so the rows
satisfy it by arithmetic rather than by luck.

A **discriminated union** — a top-level `OR` of `AND`-groups, each pinning a
discriminator column and constraining its siblings from there — is placed too,
by picking one branch per row and satisfying it whole:

```sql
CHECK (
    (kind = 'wallet_credit'    AND amount_cents    IS NOT NULL AND amount_cents > 0
                               AND compute_minutes IS NULL)
 OR (kind = 'compute_minutes'  AND compute_minutes IS NOT NULL AND compute_minutes > 0
                               AND amount_cents    IS NULL)
);
-- seeds  row 0: kind='wallet_credit',   amount_cents=1,    compute_minutes=NULL
--        row 1: kind='compute_minutes', amount_cents=NULL, compute_minutes=2  …
```

Branches are taken **round-robin by row**, so every arm of the union appears in
the dataset — a table with only `wallet_credit` rows cannot exercise the other
redemption path at all. The matcher is narrow on purpose: the terms it reads are
`col = <literal>`, `col IS [NOT] NULL` and `col <op> <number>`. A nested `OR`, a
`NOT`, a function call, or a comparison between two columns is refused by name,
as is a union whose columns another mechanism owns (a key, a foreign key, a
UNIQUE column) or that a second multi-column constraint also spans.

## Write a status-lifecycle rule as an implication, never a biconditional

"An approved estimate has an approval timestamp" has two spellings in SQL, and
only one of them seeds. This is the single highest-cost authoring choice in this
document, so it is worth the paragraph.

```sql
-- YES: a one-way implication. Any number of these over the same column seed.
CONSTRAINT estimates_sent_has_stamp
    CHECK (status <> 'ESTIMATE_STATUS_SENT'     OR sent_at     IS NOT NULL),
CONSTRAINT estimates_approved_has_stamp
    CHECK (status <> 'ESTIMATE_STATUS_APPROVED' OR approved_at IS NOT NULL),
CONSTRAINT estimates_rejected_has_stamp
    CHECK (status <> 'ESTIMATE_STATUS_REJECTED' OR rejected_at IS NOT NULL)

-- NO: a biconditional. Not placeable — not even one of them.
CONSTRAINT estimates_approved_iff
    CHECK ((status = 'ESTIMATE_STATUS_APPROVED') = (approved_at IS NOT NULL))
```

The implication is a **status guard**: an exempting arm (`<>`, `NOT IN`, or the
positive `IN (…)` complement) followed by what must hold when the row is *not*
exempt. Forge reads the guarded column's vocabulary from its single-column
`CHECK (status IN (…))`, rewrites each guard into positive branches, and MERGES
every guard over that column into one union with a branch per status value
carrying the consequents of every guard that value triggers. Because they are
merged rather than placed one at a time, they are not rivals to each other and
the count does not matter — three over one column seed exactly as cleanly as
one.

A biconditional has no top-level `OR`, so it is neither a guard nor a
discriminated union; no pass can read it, and `status` and `approved_at` are
then drawn independently. Measured across six salts, a single biconditional had
its INSERT rejected on **all six** — `apply` is one transaction, so that is the
whole dev dataset, every time, not an occasional unlucky run.

The mixing rule is the part that surprises people: **one biconditional also
takes the well-formed guards down with it.** It still spans `status`, so the
merged guard union refuses for a constraint it cannot prove itself jointly
satisfiable with, and two perfectly good implications go unplaced alongside it:

> seed plan: estimates constraints `"estimates_rejected_has_stamp"`,
> `"estimates_sent_has_stamp"` over status are well-formed and would seed, but
> `"estimates_approved_iff"` also spans status and states a status rule as a
> biconditional — fix that ONE constraint and they get placed too. Until then
> seeded rows satisfy them only by chance

Forge names the blocker and the two innocents separately on purpose: repairing
the well-formed pair while leaving the biconditional in place produces an
identical refusal, which is what makes this failure read as "the rewrite does
not work."

The guarded column must carry a readable vocabulary — a single-column
`CHECK (status IN (…))` — or there is no value set to draw the un-guarded branch
from and forge refuses by name rather than inventing domain facts. Entities born
from proto enums get this automatically (`TEXT` + `CHECK (col IN (...))`); a
hand-written migration with a bare `TEXT status` is refused even with perfect
implications.

**You are not giving up the other half of the rule — you are moving it to the
writer that owns it.** An implication states "approved ⇒ stamped"; the mirror
("not approved ⇒ NULL stamp") is a single-writer lifecycle invariant, so enforce
it in the RPC that owns the status transition, which is where it belongs anyway.
Do the reverse — weakening or deleting constraints round after round until the
seeder stops complaining — and a dev-tooling limit has permanently weakened a
production schema. That is the failure this section exists to prevent: it has
happened, over four rounds, ending with a constraint deleted outright.

**A `BYTEA` column varies per row** (`sample_<column>_<row>`, hex-encoded), so a
`key_hash BYTEA NOT NULL UNIQUE` carries the full row target instead of capping
its table at one row. A `length(col) = N` CHECK is honored, and the row
discriminator survives the truncation.

**A partial unique index is read as the weaker statement it is.**
`UNIQUE (user_id) WHERE revoked_at IS NULL` means one *active* key per user, not
one key per user, so it does not cap the table — as long as forge can show the
predicate false of every row it writes. A predicate it cannot read keeps the
strict reading (the column is treated as plain `UNIQUE`), which is the safe
direction.

A **derivation** (`total_cents = subtotal_cents + tax_cents`) is not placeable
and the plan says so by name, because three independently synthesized values
make an equality true only by coincidence. It is not a seeding problem to work
around — the schema is asserting a rule it never implements. Declare it instead
(`GENERATED ALWAYS AS (…) STORED`, see `db/constraints`) and the column stops
being seeded at all, because postgres owns it. **Do not pin the columns to
`{min: 0, max: 0}` in `vocab.yaml` to force the CHECK to hold** — that trades a
warning for a demo database where every money column reads zero.

`apply` runs as one transaction: it seeds every table or leaves the database
untouched, so a failed run is always safe to retry and never leaves a
half-populated dev database behind.

**The same planner builds your test factories — in MINIMAL mode.** The dev
dataset fills every column and rotates through every union branch; the
regenerated `New<Entity>` / `New<CreateRequest>` factories (see `testing`) write
only what the schema requires — keys, NOT NULL columns without a usable
DEFAULT, NOT NULL references — leave the rest to DEFAULT or NULL, and take the
guard branch that keeps the status at its DEFAULT. So the implications above,
and a column made `GENERATED`, are safe to add to the birth migration right
after scaffolding: the next `forge generate` re-derives every test row.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.