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
..

title, audience, summary
title audience summary
Domain Model Cards
developer
One card per domain model: purpose, invariants, dimensions, drift traps, and open questions, each claim cited to the migration, file, or decision that enforces it.

Domain Model Cards

Each card in this directory describes one domain model as it is actually built, so a maintainer can modify that model without re-deriving its rules from migrations, specs, and decision documents. The cards are the descriptive home for the as-built models; the normative record — the designed schema, the decision log, the numbered design documents, and the glossary — lives in the synced design/ directory (Decision 141, design/documents/doc-43-schema-topology-and-documentation-division.md). Migrations are the ground truth for as-built claims.

The catalog was motivated by a 2026-07 inventory of the console's domain models, which traced the majority of a 56-finding UX audit to model-attributable causes: rules that lived only in prose, invariants enforced nowhere, and dimensions that were easy to conflate because no single page named them side by side.

The cards

  • Product / catalog — how capabilities are packaged, priced, and sold; the dissolved kind taxonomy and the shape views that replaced it.
  • Payments and Billing — billing accounts, subscriptions, invoices and payments projected from Stripe, scheduled changes as intent, and the reconciler.
  • Plan Ladders and Transitions — ranked tiers, who occupies which rung, the append-only audit, and the conferral functions as sole writers.
  • Entitlements — resource keys, sets and rules, grants as decrees, provisions as delivery, and the materializer.
  • Acts — the act record for actions that write several rows, the plan acts' details, the lifecycle acts that group a person's requests for several instances, the obligations a default change or reorder owes its organizations, and the functions that are the only writers of its tables.
  • Resource Pools — the per-organization container: workspace assignments, the two resolution directions, and pool-grain usage.
  • Providers and Integrations — the registry and its connections, boot-time manifests, resource-key ownership, desired-state delivery, and the shared substrate.
  • Domains Registry — claims as subtree ownership, placements as the only thing that serves, and the anti-abuse ledger.
  • Identity, Organizations, and Workspaces — users vs persons, the containment ladder, org types as policy, and first-login provisioning.

A new domain model is not considered documented until its card exists and is listed here.

Card anatomy

Every card has four sections in this order:

  • Purpose — what the model owns and why it exists, in plain present tense.
  • Where this lives — a map of the model's pieces: each table, view, function, and code file, with one line saying what it is. Locations live here, not scattered through the body.
  • Invariants — the rules the model guarantees, one per numbered entry so reviews can cite "invariant 3". Each entry carries an enforcement tag matching the actual mechanism: [db] means the database schema rejects violations outright; [db-code] means the database functions are written to uphold the rule, so reviews must protect it when they change; [app] means only application code upholds the rule, so new code paths must uphold it too.
  • Dimensions — the orthogonal axes a maintainer must hold simultaneously, each defined where it is named.

Cards describe the model as it is today, for a reader who knows nothing yet. That means: no history, no decision numbers, no change narrative in the body — a card introduces every table, column, view, and concept before or where it first uses it. Drift between design and code, open questions, and other bookkeeping live on the forge tracker, not in the cards.

Style contract

Card prose follows these rules, and edits are reviewed against them:

  • Write for someone with zero context: never assume the reader knows a term, a table, or an internal codename you haven't introduced.
  • Name the agent: state what acted and what it acted on.
  • Give each verb its own object; do not let one object serve two verbs.
  • Connect clauses with explicit causal or temporal words (because, so, when, after) — never with a bare comma.
  • Replace every metaphor or compressed phrase with the literal claim it stands for.
  • Give every count or statistic its denominator.

A change that alters an invariant, dimension, or map entry recorded on a card must update that card in the same change (see openspec/specs/model-catalog/spec.md once this change archives).