[wfaithfull]

M10 step 7, implementing DESIGN.md §5.7 "Quotas on readers' vectors" (§14 items 46, 47).

Schema

• New column graphs.reader_vector_quota, with a CHECK (>= 0) constraint.
• New table warren.vector_quotas:
  • registered with pg_extension_config_dump;
  • revoked from PUBLIC;
  • rows are deleted with their graph.
• New index on warren.vectors (graph_id, created_by).
• Both the 0.5.0→0.6.0 upgrade script and the 0.6.0 install script carry these changes.

Functions

• warren.set_vector_quota(name, bytes, role DEFAULT NULL)
  • The graph's owner only. It takes the graph's row lock, then re-checks ownership.
  • A NULL role sets the graph's default quota. NULL bytes removes the quota.
  • Role '-' is refused with 22023. Setting a quota for an oid that names no role is refused with 42704; removing a dropped role's quota is allowed.
• warren.vector_usage(name): the owner sees every role's usage; a reader sees only its own row.
• info now includes reader_vector_quota.

Enforcement

Every persisted vector write goes through Vectors::save, which calls quota::admit first. That covers every vector-writing function and the library's results. The lock, the usage read and the decision live in catalog::quota.

• Members of the owner role are exempt and take no lock.
• Every other write proceeds in this order:
  1. Take a transaction-scoped, advisory-type lock on (graph, role), on the leader, with pg_warren's own objsubid.
  2. Read the quota.
  3. Sum the role's usage under the latest snapshot, including what this transaction has already written.
  4. Refuse with 53400 only if usage after the write would be over the quota and higher than before it.
• So replacing a vector with one no larger always succeeds, and a quota lowered below current usage only blocks growth.
• reassign_owned charges the vectors it moves to the new role's quota, on every graph where neither the new role nor the caller is exempt, and refuses with 53400 past it.

Scope

A quota bounds a role's vectors on another owner's graph. It does not bound total catalog storage: create_graph, and the quotient contract creates for its caller, both give the caller storage it is exempt on. Per-role storage overall is option 46c, which is deferred. This is documented in DESIGN §5.7, §14 item 46 and docs/semantics.md.

Dropped roles

• drop_owned and the DROP OWNED event trigger delete a role's quota rows only:
  • on graphs whose owner the caller is a member of;
  • or everywhere, for the extension owner or a superuser.
• So a reader cannot delete its own quota. Any rows left behind are listed by orphans() and removed by drop_orphans, or by the graph's owner.

Tests

• Unit tests for the pure quota decision.
• pg_tests:
  • a write over the quota is refused;
  • a replacement no larger than the old vector succeeds;
  • the owner is exempt;
  • a quota lowered below usage blocks only growth;
  • the latest snapshot sees the transaction's own writes;
  • reassign_owned past the new role's quota is refused, and a move to the owner is not counted;
  • drop_owned and DROP OWNED of oneself keep the role's quota row.
• Harness vector_quota_race (dblink) covers:
  • a second writer that waits for the lock, then is refused;
  • a REPEATABLE READ writer;
  • a quota committed while another write of the same role is still uncommitted;
  • a reassign_owned queued behind a writer.
• Coverage of quotas added to dump.py and upgrade.py.
• A security review's exploit probes for the reassign_owned and drop_owned bypasses are now refused.

Run locally

• pgrx tests: PG 15, 16 and 18 pass. PG 17 isn't set up on this machine; CI covers it.
• run.py: 52 of 52 pass, plain and --trusted.
• dump.py and upgrade.py pass.
• fmt, clippy -D warnings and rustdoc are clean.

CLAUDE.md: the module list now includes vector::quota and catalog::quota, and the parallel-labels rule follows DESIGN §9.3.

🤖 Generated with Claude Code

https://claude.ai/code/session_012Rxfe2L3iVjSwSBPdUu1Ke