Files
cgalo5758 df4a5e0abf Make every limit a whole number of zero or more, and let an operator hide a limit from members
A limit is now a whole number of zero or more wherever the console reads
one: a rule's value, a contribution and a pool's limit each carry a CHECK
that refuses a negative. The console has no unlimited value. The one place
that read -1 as "no ceiling", the over-usage test of a rule change, now
compares the limit as the number it is. The fold of a pool's limit
saturates at the largest value the column holds instead of wrapping, so a
very high limit times a quantity, or several very high limits added,
cannot turn negative.

core.commit_rule_change refuses a negative value and a hidden limit below
one by name, with the same SQLSTATE as its other refusals. On a modify it
checks that the rule is active before it checks the value, as before.

The page that applies a staged rule change now keeps the errors the form
already computes for each staged row. Before, it parsed a staged value
again without the form's checks, so a request built by hand could store a
negative limit.

A limit rule gains limit_hidden, set in a new Hide limit column of the
Rules table and in the add form. Only a limit rule with a value of one or
more can hide its limit. A pool's limit for a key is hidden when any
active rule funding it hides it; the console works that out when a page
is read, from the rules the fold counts, and stores no copy. While a
limit is hidden and usage is below it, a member's usage row shows the
count with no limit and no bar, a plan card names the resource with no
number, and the FedWiki sites card shows the count alone. Once usage
reaches the limit, the usage row and the sites card show the limit again,
so a member is never stopped by a limit they cannot see; the plan card,
which has no usage, reads the mark from the rule and prints the name
alone. Operator pages always show the number; the organization's pool
table adds "Limit hidden" beside it, and the set's tray and History
state the flag. The mark is not part of what an application receives
and fires no delivery. If reading the mark fails, the page logs it and
shows the limit.

The console never prints the word "unlimited": the lint rule
unlimited-copy refuses it in the console's templates, Go strings and
scripts. Text an operator writes on a product, such as an additional
feature, is printed as given. Before the rule was switched on, the word
appeared in no copy, and in five places outside tests and SQL: four in
internal/entitlements/rule_change.go, the constant unlimitedLimit, its
comment, and the comment and comparison of atOrOver, which went with
the -1 value; and one comment in internal/domains/querier.go on a query
that deliberately takes every row, which stays.

The demo data gains a second numeric key, demo.gadgets, whose limit is
hidden, so the screens show a hidden limit beside a shown one.

Deliberate breaks: 34, run with scripts/mutation-check; 33 caught. The
one not listed as caught, removing rule_type = 'limit' from the two
hidden-limit queries, is equivalent: only limit rules carry
limit_hidden = true, which the CHECK enforces. Two breaks were missed on
the first run and are now caught by tests that stage two changes at once:
removing the pass that keeps a staged row's form errors, and removing the
staged check of a hidden limit below one. The list:
- IsLimitHidden without r.is_active (internal/entitlements/entitlement_set_rules.sql.go): ^TestLimitHiddenIsDerivedFromTheFundingRules$
- ListHiddenLimitKeysByPoolIDs without r.is_active (internal/entitlements/entitlement_set_rules.sql.go): ^TestHiddenLimitKeysAgreesWithIsLimitHidden$
- IsLimitHidden without the stacking-policy clause (internal/entitlements/entitlement_set_rules.sql.go): ^TestLimitHiddenIsDerivedFromTheFundingRules$
- ListHiddenLimitKeysByPoolIDs without the stacking-policy clause (internal/entitlements/entitlement_set_rules.sql.go): ^TestHiddenLimitKeysAgreesWithIsLimitHidden$
- IsLimitHidden without pp.status (internal/entitlements/entitlement_set_rules.sql.go): ^TestLimitHiddenIsDerivedFromTheFundingRules$
- saturatingMul > becomes >= (internal/entitlements/saturate.go): ^TestSaturatingArithmetic$
- saturatingMul in the fold is plain multiplication (internal/entitlements/materialize.go): ^TestMaterializeSaturatesInsteadOfWrapping$
- saturatingAdd in the fold is plain addition (internal/entitlements/materialize.go): ^TestMaterializeSaturatesInsteadOfWrapping$
- CeilingShows ignores usage (internal/entitlements/ceiling.go): ^TestCeilingShows$
- atOrOver reads > not >= (internal/entitlements/rule_change.go): ^TestCeilingShows$|^TestDiffEffects$
- drop the resource_value sign CHECK (scratch) (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignMigrationRefusesANegativeRow$
- drop the contribution sign CHECK (scratch) (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignMigrationRefusesANegativeRow$
- drop the resource_limit sign CHECK (scratch) (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignMigrationRefusesANegativeRow$
- function body misspells limit_hidden on the modify path (scratch) (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignMigrationDownRestoresTheFunction$
- drop the resource_value sign CHECK (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignAndHiddenConstraints$
- drop the contribution sign CHECK (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignAndHiddenConstraints$
- drop the resource_limit sign CHECK (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignAndHiddenConstraints$
- drop the limit_hidden CHECK (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestLimitSignAndHiddenConstraints$
- function: drop the hidden-zero refusal on add (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeRefusesANegativeAndAHiddenZero$
- function: drop the hidden-zero refusal on modify (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeRefusesANegativeAndAHiddenZero$
- function: drop the negative refusal on add (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeRefusesANegativeAndAHiddenZero$
- function: drop the negative refusal on modify (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeRefusesANegativeAndAHiddenZero$
- function: modify reads an absent flag as false (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeRefusesANegativeAndAHiddenZero$
- function: modify reads a JSON null flag as a value (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeReadsANullFlagAsAbsentAndChecksActivityFirst$
- function: modify's UPDATE reads a JSON null flag as a value (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeReadsANullFlagAsAbsentAndChecksActivityFirst$
- function: drop the active-rule check before the refusals (internal/db/migrations/00042_limit_sign_and_hidden.sql): ^TestCommitRuleChangeReadsANullFlagAsAbsentAndChecksActivityFirst$
- staged-row error pass removed (internal/server/operator_entitlement_set_rule_change.go): ^TestApplyRefusesEveryCraftedDeltaOnItsOwnLine$
- staged hidden-zero cross-check removed (internal/server/operator_entitlement_set_rule_change.go): ^TestApplyRefusesEveryCraftedHiddenZeroOnItsOwnLine$
- member panel fails whole when the hidden read fails (internal/server/member_entitlements.go): ^TestAFailedHiddenLimitReadShowsTheCeiling$
- member rows always show the ceiling (internal/server/member_entitlements.go): ^TestHiddenLimitUnderUsageShowsTheCountAlone$|^TestAFlagOnlyChangeIsSeenByTheMemberWithoutAMaterialization$|^TestTwoPlansFundingOneKeyHideItIfEitherHidesItDB$
- plan card prints a hidden rule's number (internal/server/member_plans.go): ^TestPlanFeatures$
- sites card always shows its ceiling (internal/integrations/fedwiki/web/partials.go): ^TestSitesCardHidesAHiddenLimitUnderTheFigure$
- sites card hides a hidden limit at usage too (internal/integrations/fedwiki/web/partials.go): ^TestSitesCardShowsAHiddenLimitAtTheFigure$
- operator pool table never marks a hidden limit (internal/server/operator_enrollment.go): Enrollment|PoolUsage

Deploy notes. Every step runs against the console database.

1. Before stopping the old release, count read-only the rows the new
   CHECKs would refuse (console_reader can run it):

     SELECT 'rule value' AS what, count(*) FROM core.entitlement_set_rules
       WHERE resource_value < 0
     UNION ALL
     SELECT 'contribution', count(*) FROM core.numeric_entitlement_contributions
       WHERE contributed_value < 0
     UNION ALL
     SELECT 'pool limit', count(*) FROM core.numeric_entitlements
       WHERE resource_limit < 0;

   Deploy when all three are 0. Correct a negative rule value in the old
   release, through its set's Rules table, to the number you mean: the
   commit recomputes every pool the rule funds, so the contributions and
   pool limits that came from it clear with it. Then count again.

2. Stop every process of the old release, as for every upgrade.

3. Migrate to 00042 and start the new release. The migration fails at
   the CHECK that finds a negative row and names it; nothing is changed
   until it succeeds.

4. Run scripts/db-reader-role.sql again. Until it runs, console_reader
   cannot read core.entitlement_set_rules.limit_hidden.

Rollback is the previous image on the 00041 schema: the Down drops
limit_hidden and the four CHECKs and restores the previous body of
core.commit_rule_change. Hidden marks are lost; no limit changes.

Closes #164.
2026-11-11 12:22:16 -06:00
..

Test Environment

This directory contains the Docker Compose setup and test data for local development.

LLM agents: read AGENTS.md first. All commands below are run from this test/ directory. If you are working in a git worktree alongside other worktrees of this repo, you must run ./bootstrap-stack.sh before docker compose up to avoid host port collisions. One exception: the FedWiki HTTPS proxy (Caddy on 443) is a cross-stack singleton among stacks that compose it — see "Running multiple isolated stacks" below.

Quick Start

cd test
./bootstrap-stack.sh
docker compose up -d
set -a; . .env; set +a
go run .. start --config mc-config.yaml

That composes the core stack: Postgres, Valkey, Keycloak, Temporal. Every integration (FedWiki, Discourse) sits behind a compose profile and is off by default, so the console boots without them.

To compose one, set the COMPOSE_PROFILES knob — either at bootstrap time:

COMPOSE_PROFILES=fedwiki ./bootstrap-stack.sh

or by editing that one line in the generated test/.env and re-running docker compose up -d. Then uncomment that integration's MC_* block in the same file so the app is configured for it, not merely running beside it. See AGENTS.md.

To run the Go test suite against its own pristine databases (not the app's), use make test from the repo root. See AGENTS.md.

Running multiple isolated stacks (parallel worktrees)

compose.yaml accepts per-stack overrides via .env. The bootstrap-stack.sh helper generates one with a deterministic, collision-free port allocation derived from the worktree's directory name. Run the four Quick Start commands above in worktree A and worktree B — the two stacks coexist on disjoint host ports under separate COMPOSE_PROJECT_NAME namespaces.

Exception — the HTTPS farm is a singleton. This applies only to stacks that select the fedwiki profile; core-only stacks never contend for the port. Browser access to FedWiki sites goes through a Caddy TLS proxy on host port 443 (wiki-security-social sets Secure cookies, which browsers only store over HTTPS). That port is fixed, not slot-allocated, so only one composing stack can serve browser login at a time — a second such stack's caddy container fails to bind 443 while the rest of its services come up normally. A slot-allocated port wouldn't help anyway: better-auth scopes cookies to the shared *.localtest.me domain (per-domain, not per-port — RFC 6265), so parallel stacks would clobber each other's session cookies regardless. Everything non-browser stays fully isolated: member-console's farm API calls use plain HTTP over the slot-allocated FEDWIKI_PORT with a bearer token (no cookies). True per-stack browser isolation needs a per-stack farm domain — tracked as forge issue #48.

To return a worktree to a clean state (containers + volumes + .env + secrets/ + testdata/):

./teardown-stack.sh

See AGENTS.md for the full contract, including the Stripe webhook constraint when running stacks in parallel.

Services

URLs below are the single-stack defaults; after bootstrap-stack.sh the host ports and *.localhost hostnames are per-stack (see the generated .env).

Core services, always composed:

Service URL Credentials
Member Console http://localhost:8081 (via Keycloak)
Keycloak http://keycloak.localhost:8080 admin / admin
Temporal UI http://localhost:8233 (via Keycloak)
PostgreSQL localhost:5432 runtime member_console_runtime / member_console_runtime; migration member_console / member_console
Valkey localhost:6379 —

Integration services, composed only when their profile is selected:

Service Profile URL Credentials
FedWiki (browser) fedwiki https://admin.localtest.me (via Keycloak)
FedWiki API fedwiki http://admin.localtest.me (bearer token, see the MC_FEDWIKI_* block in .env)
Discourse discourse http://discourse.localhost:9292 (via Keycloak)

All credentials above are throwaway test-only values — never reuse any of them in a real deployment.

Browser access to FedWiki is HTTPS via the Caddy proxy (Caddy's internal CA — to trust it for manual browsing, export the root once: docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt). See AGENTS.md for the HTTPS/cert details.

Test Data

Seed identity

The database generates every ID, so a seed never supplies one; it addresses the rows it owns by key (grammar ^[a-z][a-z0-9_]*$) and upserts on that key, which is what makes re-running a seed a no-op. mockshot-seed.sql and mockshot-nuke.sql are the deployment-scale sample-data pair used for screenshots: both work from the mockshot_ organization key prefix and the mockshot: OIDC subject prefix, so the nuke removes exactly what the seed created. The four demo users' Keycloak ids are pinned as literals in seed/keycloak/seed-keycloak.sh, and the demo seeder mirrors them as its persons' OIDC subjects.

The testdata/ directory is named like that so that gopls can ignore it by default. It contains sample data for testing the Member Console, such as:

Keycloak

Keycloak runs with start-dev (an ephemeral H2 database, no persistent volume). It does not import a realm file. Instead, the one-shot keycloak-seed service runs seed/keycloak/seed-keycloak.sh on every docker compose up, which — authenticating as the master-realm bootstrap admin — creates a dedicated test app realm and seeds its clients, roles, protocol mappers, client scopes, and test users over the Keycloak admin API (idempotent). App OIDC runs on test, not Keycloak's master admin realm, so the end-user account console works.

Seeded into the test realm:

  • Clients: member-console, fedwiki, temporal-ui, temporal-authz (plus service accounts)
  • Users: alice (operator), bob, carlos, diana — password password

To change the realm setup, edit seed/keycloak/seed-keycloak.sh — there is no realm export/import step. (An old testdata/keycloak/master-realm.json export remains on disk for reference but is untracked and unused by compose.)

FedWiki

Everything in this section applies only when the fedwiki profile is selected.

FedWiki runtime data lives in data/fedwiki/ (gitignored status/ dirs). Seed data for owner files and access tokens is committed in seed/fedwiki/.

A fedwiki-init container automatically copies seed files into data/fedwiki/ on docker compose up without overwriting existing files (cp -rn). This means:

  • Fresh clone: seed data is copied in automatically, no manual steps needed.
  • Existing setup: your local data is preserved.

To update seed data after making changes (e.g., new tokens or wiki sites):

# Copy the relevant files from data/fedwiki/ to seed/fedwiki/
cp data/fedwiki/<site>/status/owner.json seed/fedwiki/<site>/status/
cp data/fedwiki/<site>/status/user-access-tokens.json seed/fedwiki/<site>/status/