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.
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.shbeforedocker compose upto avoid host port collisions. One exception: the FedWiki HTTPS proxy (Caddy on443) 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/