member-console/status/issues.md

Issues

Tracked items structured for eventual migration to Gitea issues. Resolved/closed items are archived in archive/issues-resolved.md.

Cross-cutting audits

2026-08-22 first-contact UX re-walk (10g) — 19 findings, maintainer-triaged fix-all

Labels: audit, ux, first-contact

The 10g re-walk ran per first-contact-ux-process.md (v1): five naive browser/docs walkthroughs, two outside models (Kimi K3, DeepSeek), 48-screen dual-state evidence sweep, eight model-card honesty audits, three independent heuristic reviews, and a code-verification pass that reclassified three of four headline mysteries as environment artifacts before they could mislead. Synthesis: ux-walks-2026-08/findings-2026-08.md — 19 deduplicated findings UX-1…UX-19 (four severity-4). Maintainer triage 2026-08-22: everything ships inside M10 (no won't-fix bucket exercised; one reframe — the IdP realm name stays untouched, the app instead gets a configurable deployment name applied to both surfaces). Work is sliced into five 10g changes; see the 10g row in milestones.md.

Entity slugs should not exist — survey and eradicate

Labels: design, schema, ux, 10g

Filed 2026-08-22 (maintainer direction during 10g triage). Slugs are neither unique IDs nor useful display values, and to the maintainer's knowledge they appear nowhere in the upstream design (membcons-db) — they are a local invention that leaks database-shaped strings into the UI (org rows badged mockshot-1260, members shown hosted-website pills). Direction: eradicate entity slugs; entities are identified by UUID and presented by name.

Actual footprint (surveyed 2026-08-22): four real slug columns — core.organizations, core.workspaces, core.resource_pools, core.providers — plus two slug-shaped text keys not named slug: core.plan_ladders.ladder_key (the hosted-website badge) and core.org_types.org_type (load-bearing in code as personal/system). The change must distinguish three classes: (1) UI display of slugs — remove outright (overlaps the ux-ia-naming work); (2) redundant slug columns on orgs/workspaces/pools — drop if the survey confirms nothing load-bearing (FedWiki site naming and operator lookup both need checking); (3) code-identity keys (providers.slug, org_type, ladder_key, resource keys) — these are registry/natural keys, not vanity slugs; converting them is a separate, riskier decision the design phase must argue explicitly. Verify the no-slugs-upstream claim against data-model v16 during the survey; if upstream does define any, that becomes a design-feedback note, not a local rewrite.

2026-07-02 adversarial UX audit — 56 confirmed findings (16 high)

Labels: audit, ux, bug

An adversarial operator/member UX audit (8 code-auditor agents over every operator and member flow; findings adversarially verified and deduped by a skeptic judge — 70 raw → 56 confirmed / 3 rejected) landed 56 confirmed findings: 16 high, 21 medium, 19 low, dominated by lying copy, silent breakage, and dead ends. Headline highs: trial-days are collected, stored, and displayed but never honored anywhere in the billing chain; revoking an addon/usage/one-time grant ends the org's plan attachment while the addon keeps delivering; upgrading after a scheduled cancel keeps the cancellation armed (member pays for a switch, then loses the subscription at period end); checkout has no already-subscribed guard, so a stale tab creates a second concurrent Stripe subscription; a second entitlement rule for the same resource key turns the set into a poison pill that aborts all future materialization; the org-type backfill mass-downgrades orgs not exactly at the default rank-0 tier behind confirm copy claiming attachments are unchanged; and the ladder/set Active toggles are complete no-ops — inactive ladders still sell and provision.

Full findings: audit-2026-07-02-operator-ux.md. Note the audit ran against the tree before that day's fixes (live-poll readiness, ladder append-at-end, db-error translation, multi-price), so each finding needs triage; the highs should be triaged into milestone phases (10e hardening / 10g first-contact UX, or dedicated changes).

2026-07-03 update: remediated (10h, committed). All 56 findings executed per the triage: 43 quick-fixes, 4 de-advertisements, the custom-domain interim hide (real remedy 10d), and 7 interim guards for structural-defers (17, 18, 19, 24, 25, 50; 56 verified as-is). The 7 structural real fixes still gate on 10i model cards — the deferred remainder is inventoried in the next issue. Verified: build/vet/lint clean, full DB-backed suite green, and the operator-walkthrough browser e2e suite green against the live stack. Two adjacent defects found and fixed during verification: the request-timeout middleware crashed the whole process on any request outliving its deadline mid-write (concurrent header-map write; replaced with http.TimeoutHandler), and the per-package test DB helpers assembled a truncated migration source list that mis-numbered fedwiki's goose versions against an app-migrated database (canonicalized in internal/migrate.Sources()).

Deferred-remediation debt from the 2026-07-02 audit — 11 postponed items

Labels: audit, debt, tracking

10h resolved the audit's symptoms; these items were deliberately postponed and each stays open until its real remedy lands. Four are de-advertised affordances (hidden or re-scoped instead of built — each needs either the real build or a conscious decision to drop the feature), and seven are interim guards whose real fixes gate on the 10i model cards for their root-cause model. The custom-domain hide is not debt in this sense — it is scheduled work tracked as milestone phase 10d.

De-advertised — hidden/re-scoped until built (or consciously dropped):

1. Trial period days (payments-billing) — the price form no longer offers trial days; the value was collected, stored, and displayed but never honored anywhere in the billing chain. Real work: build trials in the payments model (Stripe trial_period_days through checkout, fulfillment, and entitlement timing) — or drop the column.
2. 'Replace' stacking policy (entitlements-materialization) — removed from the rule form's stacking dropdown and rejected server-side; it contributed 0 to materialized limits. Real work: define replace semantics in the materialization model, or retire the enum value. Update 2026-08-22: authoring is now additive-only (schema-hardening), so no non-additive rule of any kind can be created; the semantics question moved into "Stacking policies need a design exploration".
3. Entitlement-set Active toggle (entitlements-materialization) — re-scoped to its real, enforced meaning ("Show in operator pickers"); it never affected delivery. Real work: set-retirement semantics — what happens to products selling, and pools provisioned from, a retired set.
4. Ladder Active toggle (plan-transitions) — fully hidden 2026-07-03 (edit-form toggle, list column, and topology badge removed; UpdatePlanLadder preserves the stored value). It was a complete no-op: inactive ladders still sold and provisioned. Real work: ladder retirement — an inactive ladder must stop selling to members and provisioning new orgs; re-surface the control only then.

Interim guards — real fixes gate on 10i model cards. (2026-08-21: the cards exist (docs/models/), so every gate below is settled — each open item now names the card that carries its root-cause model. Items 8 and 9 were already resolved 2026-07-11.)

5. Synchronous workflow waits (fedwiki-lifecycle) — guard: a 6s wait budget then an honest "still working" response + list refresh (plus the http.TimeoutHandler rewrite). Real work: a pending-state lifecycle — persist in-flight site operations and render them as first-class states instead of blocking requests on Temporal. Card gate: the provider-resource lifecycle sits adjacent to the provider-integration card (per-instance lifecycle dimension); the pending-state design is unblocked.
6. Entitlement lapse hides live sites (fedwiki-lifecycle) — guard: transient lookup failures render a try-again notice and sites stay listed; genuine no-entitlement shows a warning above the still-listed sites. Real work: lapse wind-down UX (what members see and can do when entitlements lapse) in the lifecycle model. Card gate: the entitlements card pins the lapse mechanics (boolean lapse-to-false, provision suspension vs end); the UX design is unblocked.
7. Rule deletion never re-materializes (entitlements-materialization) — guard: the delete-rule confirm now states honestly that existing pools keep their current limits. Real work: re-materialization semantics for rule changes (when do existing pools re-evaluate?). Card gate: the entitlements card pins materialization's transactional contract, and its ledger entry ("Rule changes never reach existing pools") is the same item sharpened — design the fan-out there.
8. Backfill vs. enrolled orgs (plan-transitions) — guard: backfill is initiate-only (pools with any active plan attachment are counted but never transitioned; the NULL-default end-to-baseline path is disabled). Real work: reapply semantics — what "backfill" should mean for orgs already on a plan, including deliberate mass moves off a plan type. 2026-07-11 resolved by org-type-default-change-flow: the standalone backfill dissolved into a select → preview → commit flow whose classification gives every population a decided disposition — plan-less pools initiate, outgoing-default holders are explicitly grandfathered (operator-attributed legacy grants, transfer-superseded) or migrated (end + floor-guarded re-apply), other-source positions are never touched, and clearing the default to NULL is a defined end-to-baseline commit. The interim guard comment and SkippedActive punt are deleted; the restoration vacancy guard is broadened to floor semantics (any live plan position blocks it) across revoke/expiry/cancellation.
9. Non-plan grant revoke (product-kind) — guard: grants whose product sits on no ladder revoke via RevokeGrantAndRematerialize instead of Transition(End) (which ended the org's plan). Real work: the product-kind model — route all kind discrimination through billing.product_kinds (see the read-discipline issue below) and give each kind its own revoke path. 2026-07-11 resolved structurally by doc41-conferral-uniformity (upstream Doc 41): revocation is decree-first + core.end_conferral resolved by source — "whatever's on the ladder" is no longer expressible, and the interim guard and RevokeGrantAndRematerialize are deleted.
10. Workspace status semantics (workspace-identity) — guard: badge color maps from status and SwitchWorkspace refuses non-active workspaces. Real work: define the workspace lifecycle (what suspended/archived mean, who transitions them, member-facing behavior). Card gate: the identity card pins the as-built truth (free-text status, switch guard as sole reader) and its ledger carries the unchecked-status gap; the lifecycle design is unblocked.
11. Member self-serve workspace creation (workspace-identity) — guard: the Create Workspace affordance stays hidden behind the existing count>1 gate (hidden, not lying). Real work: decide the creation policy in the workspace-identity model, then relax the gate in server.go. Card gate: the identity card pins workspace creation as-built (default-pool attachment, the swallowed-lookup trap in the pools ledger); the policy decision is unblocked.

Entitlements & plan transitions

Transition primitive: multi-axis & departed-ladder gaps (transition-primitive audit, 2026-06-24)

2026-07-11: both gaps closed by doc41-conferral-uniformity. Gap 1's named fix direction ("give End an explicit scope, not newest-pool-wide") landed as core.end_conferral resolving strictly by source arc, DB-enforced via the per-source live-uniqueness indexes; gap 2 landed as the reconcile diff (desired-by-product vs live provisions; departed products are ended via end_conferral). The Transition primitive itself is retired behind the enclosed core.confer function family.

Surfaced 2026-06-24 by a deliberate read-only audit of entitlements.Transition and its callers, run after fixing the two reapplyDefaultsForPool-delegation bugs (transition-end-reapply-narrowing, transition-downgrade-honors-target). The primitive and the Stripe reconcile path were built for today's single-axis, 2-rung, evergreen catalog; two latent gaps appear only once the multi-axis model (member-ladder-aware-catalog) or multi-item subscriptions go live. None has a live trigger today. Cross-verified against code; bundled here since they share a root (per-ladder/per-axis scoping) and a single consumer (multi-axis rollout). Four other candidate gaps were checked and verified clear (see bottom). (A third audit finding — the Extend spec self-contradiction — was resolved by transition-extend-replace-semantics.)

1. Transition(End) ends an arbitrary attachment on multi-axis pools. resolveCurrentAttachment for an End target returns rows[0] of GetActiveAttachmentsByPool (internal/entitlements/queries/pool_provision_ladders.sql — ORDER BY activated_at DESC, no axis filter), and Transition ends only that one (transitions.go:176-183, :305-313). The End target carries no subscription/provision/axis identifier. endSubscriptionEntitlement (internal/fulfillment/reconcile.go:410-435) computes hasActive for a specific subscription's provision but then calls Transition{End:true} with only poolID — so on a pool with >1 active attachment it can end the wrong axis (the most-recently-activated one). Grant-expiry (internal/workflows/entitlements/activities.go:95) and operator revoke pass bare End:true too. Latent (live pools have ≤1 attachment, so rows[0] is unambiguous). Fix direction: give End an explicit attachment/subscription scope (end the attachment for this provision/axis), not "newest pool-wide." High-severity blocker for multi-axis rollout.

2. Reconcile converges present subscription items but never ends departed ladders. reconcileItems (internal/fulfillment/reconcile.go:266) loops only sub.Items.Data (create/update); nothing ends entitlements for an item/ladder no longer on the subscription. Whole-subscription cancel is handled (endSubscriptionEntitlement), but partial removal is not. Three manifestations, one root cause: (a) a removed item that was the sole occupant of a ladder orphans its active attachment; (b) a cross-ladder paid→paid switch (new price tiers into a different ladder) classifies as initiate on the new ladder while the old ladder's attachment is never ended → two active attachments; (c) stale billing.subscription_items rows accrue (cosmetic). Masked today because live subscriptions are single-item/single-ladder and a same-ladder price swap is an in-place modify that supersedes correctly. Fix direction: reconcile should diff present-vs-prior ladders and end attachments for departed ones (pairs with #1's scoped-End). Tracks against member-ladder-aware-catalog.

Verified clear during the same audit (recorded so they aren't re-investigated): (i) the classification switch's default "same-rank, different-product" branch is unreachable — billing.plan_ladder_tiers has UNIQUE (plan_ladder_id, rank) (00012_plan_ladders.sql:32), so two products can't share a rank on one ladder; it's defensive dead code. (ii) Transition(End) with no current attachment correctly drops to baseline / reapplies the default, and the new end-at-default no-remint guard is correctly gated on prior != nil. (iii) A cross-ladder non-end target leaving both ladders active is intended (multi-axis = one active plan per axis), not a leak — it only matters if a cross-ladder replace/switch semantics is ever wanted (bundles, service migration). (iv) Reconcile is idempotent under double-fire (pg_advisory_xact_lock, same-target no-op, drift guards).

Doc 41 rollout notes (doc41-conferral-uniformity, 2026-07-11)

Labels: entitlements, billing, upstream-membcons-db, ops

Three notes from implementing upstream Doc 41 (Decisions 134–139):

1. Purchase arc is dormant. core.confer implements the purchase source per Doc 41 (exclusive arc, live-uniqueness index on purchase_id), but member-console has no purchase-record flow — pool_provisions.purchase_id remains a loose slot with no purchases table and no Go caller. When one-time purchases ship, they get a caller of the same primitive, not a new pathway.
2. Billing residue is a named upstream open question (Doc 41 §11.2/§12): a grant superseding a subscription-held position correctly ends the position, but the subscription keeps billing for a tier the pool no longer holds. Doc 41 deliberately does not reach into billing; downstream mitigation is the issuance-form advisory warning the operator before conferring over a subscription-sourced position. Revisit when the design team logs the follow-up decision.
3. Rollback is snapshot-based. Migrations 00004–00006 carry mechanical Down sections (views, rename, functions, grants), but the data normalizations (reason buckets, set-direct repoint, provision product_id backfill) are one-way; the rollback unit for a bad window is the pre-migration snapshot plus the previous binary. The old binary cannot run against the migrated schema — its direct position-table DML fails loudly (enclosure), which is the intended fail-closed posture.

Design gap: grants.status lifecycle vs operational delivery is undocumented

Labels: design-feedback, documentation, upstream-membcons-db

design/entitlements/model.md defines grants.status ∈ {active, expired, revoked} and pool_provisions.status ∈ {active, suspended, ended} independently, including the "Pool Provision Status" table at §pool_provisions that maps grant lifecycle events to provision lifecycle outcomes. What it never states is the converse invariant: a grant whose provision is ended by a Transition or Extend stays grants.status='active' indefinitely — grants.status only changes through explicit revocation or time-based expiry. The grants table is a ledger; operational delivery lives one layer down on the provision and ladder-attachment status fields, and the GiST exclusion constraint on pool_provision_ladders guarantees at-most-one active provision per (pool, ladder).

This silence cost real bugs in member-console: both the operator per-org composite and the member-facing entitlements Sources panel were filtering grants by status='active' and treating the result as "currently delivering," producing visible UI lies (5+ "active" Public Plan rows for a pool the schema guarantees has exactly one active provision). Fixed downstream by adding ListGrantsWithDeliveryByOrgID (LEFT JOIN with derived delivery_state) and ListDeliveringGrantsByOrgID (INNER JOIN on active provisions), and documenting the rule in docs/operator-ux-conventions.md §9a.

Upstream ask: add a short paragraph to design/entitlements/model.md §grants (or §pool_provisions) explicitly naming the lifecycle-vs-delivery split — something like "grants.status reflects only formal lifecycle events (revoke / expire). Asking 'which grants currently deliver entitlements to a pool?' requires joining to pool_provisions with status='active', not filtering on grants.status. A grant remains active after its provision is ended by Transition or Extend; this is intentional and preserves the audit trail." The companion spec (openspec/specs/entitlements/spec.md §Grants) likewise has nothing on this invariant and would benefit from a one-paragraph requirement codifying it.

2026-07-11 update: the downstream half closes when doc41-conferral-uniformity archives — its entitlements delta codifies grants-as-ledger (delivery answered from provisions) as a spec requirement. The upstream half is committed by Doc 41 §7.3 (documentation sync incl. extends_grant_id and the status-vocabulary correction); keep this open until the model.md paragraph actually lands in the design repo.

Per-org disposition overrides in default-change / reorder / removal previews

Labels: enhancement, plan-transitions, operator-ux

The consequence previews for org-type default changes, tier reorder, and tier removal all apply one disposition to the whole outgoing-default population: every affected org is either grandfathered/kept or migrated. Mixed dispositions — grandfather some orgs, migrate the rest — were deferred from org-type-default-change-flow (archived 2026-07-12, see its Open Questions). If wanted later: the commit payload grows a per-org override list and the preview grows per-row controls (the count-first disclosure lists already render one row per org), with no change to the enactment shapes — enactOrgDisposition already operates per org. Deferred 2026-07-11; promoted here from the archived change so it stays findable.

Billing, Stripe & purchasability

Product retirement and Stripe-mapping visibility in operator UI

Labels: design-feedback, billing, ux The operator product UI today has no archive/delete affordance — products that go out of fashion accumulate. Two facts shape what the right answer is:

1. Local products are 1:1 mapped to Stripe products via stripe.product_mappings(product_id, stripe_product_id, sync_status). Deleting a local product silently breaks that mapping; even if the operator is OK with the local row going away, the Stripe-side product (which Stripe never deletes — it archives) and the mapping row need a coherent story.
2. M6a already plans a lifecycle_status column on billing.products (draft / published / retired). That is the right primitive: published products are sellable; retired products cannot be granted to new orgs but existing grants survive; draft products are operator-visible only.

What 7b/7c should do:

• Surface the Stripe mapping in the product UI — operators need to see which local product maps to which Stripe product, and the sync status of that mapping. Today this relationship is invisible from the panel.
• Replace any future "delete product" affordance with a "retire product" action that flips lifecycle_status to retired (gated on whether any active grants exist; prevent retire if so, or offer a clear cascade preview).
• Same logic applies to entitlement sets that are referenced by products and to plan ladders that have orgs enrolled.

Discovered during M7 phase 7a (2026-05-08).

Multi-currency money on the operator overview: largest bucket shown, no conversion

Labels: billing, operator-ui, enhancement

The overview's Monthly recurring headline and Open invoices outstanding caption (overview-money-and-teams, 2026-07-27) sum money per currency and display only the largest currency bucket, acknowledging the rest in the caption ("plus N more currencies"). That is honest but incomplete for a deployment that genuinely bills in several currencies: the headline understates total recurring value.

Doing better means converting, and converting needs infrastructure this codebase deliberately doesn't have yet: a rate source (ECB feed? manual operator-entered rates?), a staleness policy for those rates, and a display convention that doesn't present converted sums as exact ("~$3,100 equivalent"). Stripe-side reporting solves this with Stripe's own FX data — a stripe provider surface might be the cheaper path than a core rate table. Single-currency deployments (the expected norm) are unaffected either way.

Filed 2026-07-27 while replacing the subscriptions count tile with monthly-normalized recurring money.

FedWiki integration

Member-console has no UI to manage sites it doesn't own (operator panel read-only; ownerless sites unmanageable)

Labels: enhancement, fedwiki, operator-ux, member-ux, affordance-gap

Noticed 2026-06-23, while resolving the orphaned-farm-sites issue (the "B1 holding workspace" fix below).

Every site-mutation surface today is member-side and ownership-scoped: archive / restore / keep-active / hard-DELETE (internal/server/fedwiki_partials.go) all require site.WorkspaceID == session.WorkspaceID. The operator FedWiki Sites page (/operator/fedwiki-sites, operator_pages.go:100) is read-only by M8c design — a table over ListAllSites with external links and no forms. Consequences:

• Operators cannot act on any site — not their own org's, not a member's, not an ownerless one. No archive, restore, purge, or reassign from the operator surface.
• Ownerless sites are unmanageable from the UI entirely. Sites parked in the System / "Orphan Reconcile" holding workspace (farm sites with no member owner — e.g. admin.localtest.me, the farm root, leftover test sites) have no logged-in member, so the member-side handlers' ownership check can never match, and the operator page can't mutate. Freeing such a name still requires a direct FarmManager hard-purge, out-of-band.
• No "claim" / "reassign owner" path to move an orphaned or ownerless site into a real member's workspace.

Fix direction: give the operator FedWiki surface (or a dedicated admin tool) write affordances — at minimum purge (?hard=true) and archive/restore — guarded by operator role, plus a "claim/reassign to workspace" action for ownerless sites. This is the operator-side counterpart to the member lifecycle controls shipped by fedwiki-lifecycle-states, and the residual half of the orphaned-farm-sites issue (whose config/visibility half is now resolved). Pairs with the read-only→writable operator-panel work and the per-item MPA pages already tracked.

Replace FedWiki sync polling with push-based (webhook) reconciliation

Labels: enhancement, fedwiki, integration, real-time

Noticed 2026-06-23 while testing the fedwiki-lifecycle-states downgrade flow.

The FedWiki state projection and the force_reduce quota reconcile both ride the periodic sync workflow (SyncFedWikiSitesWorkflow, default fedwiki-sync-interval). That makes enforcement eventually consistent — a downgrade's read-only parking, an out-of-band farm status change, and the retention purge all wait for the next tick. For testing we drop the interval to 1m, but the real fix is to stop polling and react to farm change events.

This is gated on the FarmManager change-webhooks capability (the 4th wishlist item in fedwiki-farmmanager-capability-wishlist.md, not yet shipped). When it lands: FarmManager POSTs site created/status-changed/deleted (and usage-threshold) events to integration.webhook_events (the inbound table already exists and is idempotent), a processor projects them immediately, and the periodic sync degrades to a slow safety-net reconcile rather than the primary path. Also revisit the related deferred refinement noted on the resolved force_reduce issue: an immediate per-trigger reconcile from the downgrade/upgrade paths, independent of the sync tick.

FedWiki HTTPS farm is a cross-stack singleton — needs a per-stack domain for true parallel isolation

Labels: test-infra, fedwiki, https, enhancement, low-urgency

Discovered 2026-06-22 while adding the Caddy TLS layer for the wiki-security-social migration.

Browser access to FedWiki farm sites now goes through a Caddy TLS proxy (wiki-security-social/better-auth sets Secure cookies, which browsers only store over HTTPS). The proxy binds host port 443, which is fixed rather than slot-allocated — so only one worktree stack can serve browser login at a time. A second stack's caddy container fails to bind 443 (the rest of that stack's services come up fine; only browser login is down).

Why a slot-allocated HTTPS port isn't enough: better-auth scopes its cookies to the shared *.localtest.me farm domain. Cookies are per-domain, not per-port (RFC 6265 — see the cookie note in test/bootstrap-stack.sh / .env), so two stacks on *.localtest.me clobber each other's session cookie jar regardless of port. The HTTP path is unaffected: member-console's farm API uses a bearer token over the slot-allocated FEDWIKI_PORT (no cookies), so provisioning stays isolated; only the browser/login surface is shared.

Fix direction: give each stack its own farm domain, e.g. *.<slug>.localtest.me (slug derived from COMPOSE_PROJECT_NAME/slot). Touches:

• test/bootstrap-stack.sh — derive + export the per-stack farm domain (and a slot-allocated FEDWIKI_HTTPS_PORT, which becomes safe once the domain isolates cookies).
• test/seed/caddy/Caddyfile — templated site address instead of the hardcoded *.localtest.me.
• test/seed/fedwiki/config.json.tpl — wikiDomains key + the rendered admin/owner entries.
• member-console — fedwiki-allowed-domains, fedwiki-site-scheme, and buildSiteURL (internal/server/fedwiki.go + fedwiki_partials.go), which currently emits no port.
• Keycloak fedwiki client — already redirectUris: ["*"], so likely no change.

Caddy tls internal can mint per-stack wildcard certs, so the cert side is free.

Severity: low, and lower since 2026-08-01. test-stack-integration-profiles put the fedwiki chain and Caddy behind a fedwiki compose profile that is off by default, so the collision surface shrank from "every stack" to "stacks that opt into the profile" — a default docker compose up -d now binds nothing on 443. The underlying singleton is unchanged: two stacks that both select fedwiki still contend, and the shared *.localtest.me cookie jar still defeats a slot-allocated port. Single-stack dev and CI are unaffected; this only bites when two worktrees need FedWiki browser login simultaneously. Documented as a known singleton in test/AGENTS.md and test/README.md.

Scope: test-infra only; no app-behaviour change beyond buildSiteURL learning an optional port. Natural home: whenever parallel-worktree FedWiki UI testing becomes a real need.

FedWiki Sites operator tab empty under full seed

Labels: bug, fedwiki, seed The compose seed provisions FedWiki fixtures at the FedWiki service but local fedwiki.sites rows are populated by integration workflows, not the seed. A "fully seeded" stack still shows an empty Sites tab. Related to "FedWiki sync does not populate DB from existing disk sites" (already filed) but distinct: that issue is about post-redeploy DB sync; this one is about first-run seed coverage. Candidate for M9 (Integration architecture) or earlier if the friction recurs.

FedWiki sync does not populate DB from existing disk sites

Labels: bug, fedwiki After a DB nuke and redeploy, the fedwiki.sites table is empty even though site directories exist on disk (e.g. test/data/fedwiki/). The sync workflow does not re-discover existing FedWiki sites from the filesystem to repopulate the database. This means both the operator panel (ListAllSites) and member views (ListSitesByWorkspace) show no sites.

Domains registry

A released hosted name is instantly re-claimable — no tombstone

Labels: enhancement, domains, security, design-gap

Noticed 2026-07-25, reviewing what the abandonment ledger (claim-lifecycle-hardening, c85ac6a) does not cover.

The ledger meters names that are abandoned before proving control. It says nothing about names released after being verified and used. Releasing a claim requires zero placements (ErrClaimHasPlacements), so by the time a name is free its site is genuinely gone and no content is exposed — but everything pointing at the name survives: inbound links, other wikis' federation neighborhoods and page references, bookmarks, search results. The next holder inherits all of it, and the console will mint a TLS certificate for them at exactly that name, by design. That is impersonation and traffic inheritance, not content disclosure.

Scope is narrower than it first looks: this is a member-claim problem only. For external claims, re-claiming requires proving zone control by TXT, so DNS itself is the tombstone — an attacker cannot take example.org from its owner by claiming it here. The exposure is carved names under an operator shared root (alice.<shared-domain>), where the registry is the only authority and the operator's DNS answers for every name uniformly.

Fix direction: a quarantine on release — a member claim that ever carried a servable placement stays unclaimable for N days after released, by anyone (including its previous holder, so it cannot be used to dodge the quarantine). Terminal claim rows are already retained with their status and timestamps, so the data exists; this is a predicate in evaluateWith's occupancy branch plus a policy knob (domains-release-quarantine, default off or short), not new schema. Decide deliberately whether the previous holder is exempt — re-claiming your own just-released name is a plausible mistake-recovery path, and exempting them costs nothing because they already held it.

Related, not the same: the pending-hold question (should an unverified claim reserve its whole subtree, or only its exact root?) is tracked separately — see the domains section of status/model-card-notes-domains.md and the non-goals of openspec/changes/archive/2026-07-25-claim-lifecycle-hardening/design.md.

Subtree exclusivity ignores DNS delegation for bring-your-own domains

Labels: enhancement, domains, design-gap

Noticed 2026-07-25, from a maintainer question: if I hold fruits.example.org and my friend holds the delegated subzone apricot.fruits.example.org, why can't we each claim ours?

A live claim owns its whole subtree exclusively, and the rule is applied uniformly to both claim kinds (domains-registry spec, "Claims are disjoint DNS subtrees with a single live owner"). For carved member claims under an operator shared root that is correct and load-bearing: members hold no DNS authority there — the operator answers for every name — so the registry is the only thing that can make "your subtree is yours" true.

For external (BYO) claims it is arguably over-restrictive, because DNS already arbitrates and does it better. Control of a name is proven by publishing TXT in its zone; a delegated subzone holder can prove control of apricot.fruits.example.org precisely because the parent delegated it, and the parent can revoke that at the nameserver whenever they like. The hierarchy is self-enforcing. Today the console refuses the child's claim purely because the parent claimed the parent first — with a generic "unavailable" that tells them nothing — even though both parties can independently prove exactly what they hold.

Fix direction: allow an external claim to nest inside another live external claim when the claimant proves control of the nested name, keeping exclusivity absolute for member claims under operator roots. Placement binding already resolves to the deepest live claim containing a name, so serving needs no change; what changes is the disjointness predicate (kind-aware) and the activation-time re-check when a parent verifies after a child already has. Weigh against the simplicity of one uniform rule — and note this is the same invariant the pending-hold narrowing question would disturb, so the two should be designed together if either is taken up.

Operator panel — UX, IA & accessibility

Residual SPA patterns: products and entitlement sets lack per-item pages

Labels: tech-debt, operator-ux, ia, mpa

Noticed 2026-06-23. Post-M7 the operator panel is meant to be MPA with addressable per-item pages (e.g. /operator/organizations/{orgID}). But /operator/products and /operator/entitlement-sets are list pages whose detail/management lives in partial-swap + modal flows (/partials/operator/products/{id}/edit, …/prices; /partials/operator/entitlement-sets/{id}/edit, …/rules) rather than dedicated pages. There is no /operator/products/{id} or /operator/entitlement-sets/{id} — so a product/set isn't linkable, the back button doesn't work, and the surfaces still behave like the old SPA.

Fix direction: give products and entitlement sets first-class per-item MPA pages (prices, edit, rules rendered inline on the item page), consistent with the per-org composite view. Candidate for an operator-IA follow-up. Related: the M7 IA work that moved enrollment/grants to per-org pages.

Operator URL/route/code naming drift

Labels: bug, frontend, dx The visible tab label, the ?tab= URL parameter, the route slug, and the partial filename disagree. Examples: tab label "People" → ?tab=people → route/partial users; tab label "Organizations" → ?tab=orgs (but ?tab=organizations does NOT switch tabs — operator-tabs.js only handles the short slug). Bookmarkability fails silently when a user infers the long name from the tab label. Discovered in Phase A v1 + reconfirmed in v2. Candidate for M7-7b/7d. IA decision (2026-05-12, OpenSpec change operator-ia): canonical route slugs are now declared in docs/operator-ia.md. The ?tab= short-slug shape disappears with M7-7d's MPA rewrite, which consumes the IA's route hierarchy as input — leave open until 7d closes it. Update 2026-07-22 (fresh-eyes IA audit remediation): the FedWiki instance of this drift is fixed — the operator surface moved to /operator/integrations/fedwiki (manifest, ia-position integration:integrations:fedwiki, legacy /operator/fedwiki-sites 301-redirects), so slug/URL/ia-position now agree; the capability/spec name fedwiki-sites and resource_key stay as-is.

Operator product edit: lifecycle_status not exposed

Labels: bug, frontend The schema added lifecycle_status (draft/published/retired) per M6a, and 7a.1 explicitly called out that retire-vs-delete is the right archive primitive. The product edit form (/partials/operator/products/{id}/edit) shows an Active checkbox but no lifecycle-state transitions. Operators cannot retire a product through the UI today. Discovered in Phase A v2. Candidate for M7-7b/7c (covered by existing "Product retirement and Stripe-mapping visibility in operator UI" issue — leave that as the umbrella).

Operator grant-issuance: two non-overlapping surfaces with no cross-link

Labels: bug, frontend, ia The global Grants tab and the per-org Enrollment "Issue Grant" form expose different products: global lets the operator pick any product (or an entitlement set); per-org Enrollment limits the Product dropdown to plan-typed products attached to the ladder. The two surfaces have no cross-link or "looking for X? try Y" guidance, and the operator must already know the distinction to choose correctly. Discovered in Phase A v2. Candidate for M7-7b IA. IA decision (2026-05-12, OpenSpec change operator-ia): both issuance forms move to the per-org composite view at /operator/organizations/{orgID}, labeled by intent ("Grant a plan" → IssueGrant; "Grant a non-plan product" → CreateGrant). The two code paths are kept (they align with the structural-vs-labeled product kind split per membcons-db Doc 35); only the surface is consolidated. Global Grants becomes read-only. 7d implements.

Two grant-revoke paths are non-equivalent and indistinguishable in UI

Labels: bug, frontend, correctness Global Grants tab "Revoke" → POST /grants/{id}/revoke (simple; body: "entitlements will be recalculated"). Per-org Enrollment "Revoke" → POST /grants/{id}/revoke-and-transition (composite; body: "pool returns to its org-type default and a downgrade or end transition is recorded"). The operator has no UI hint that these are non-equivalent — silent-correctness risk. Already flagged in docs/operator-ux-research.md as the "two revoke paths" 7a.1 finding; this entry is the issue-tracker pointer so 7b can scope consolidation work. Candidate for M7-7b. IA decision (2026-05-12, OpenSpec change operator-ia): the per-org composite view at /operator/organizations/{orgID} is the sole UI entry point for grant revocation, using the composite revoke-and-transition behavior; the global Grants Revoke affordance is removed. (The broader IA also moves all grant action affordances — issue/extend/revoke — to the per-org view; the global Grants surface becomes read-only browse.) Implementation lands with M7-7d's MPA rewrite — leave open until 7d closes it.

Operator plans surfaces — consolidate Plan Ladders + Plan Topology, reconcile grid orientation (very low priority, no milestone)

Labels: enhancement, frontend, ux, low-priority, deferred Three connected, deliberately-unscheduled refinements to the operator plans surfaces, noted 2026-05-30 after shipping operator-topology-legibility. Very low priority — intentionally NOT added to status/milestones.md; captured here only so the ideas survive.

1. Consolidate Plan Ladders + Plan Topology into one surface. They are two views of one concept — ladder/tier configuration (/operator/plan-ladders) vs. the cross-ladder read overview (/operator/plan-topology) — and may read better seen together than as two sibling Catalog nav entries, e.g. a single "Plans" / "Plans Management" page. Possibly nest the combined surface under Products as a child of that nav link rather than as top-level Catalog entries. Would touch the operator-panel-navigation IA contract.
2. Possibly transpose the topology grid axes. Today ladders are columns and ranks are rows; may prefer ladders as rows, ranks as columns — likely reads better at the realistic shape (many ladders, few ranks) and avoids the very-wide grid seen during verification.
3. Reconcile rank-order direction across the two surfaces. The operator "Manage Tiers" page (Plan Ladders → a ladder → Tiers) lists rank 0 at the top, increasing downward. The Plan Topology grid puts rank 0 at the bottom (highest rank on top — the member-catalog mirror chosen in the operator-topology-legibility design). These disagree; pick one convention and apply it consistently. (Rank-0-bottom was a resolved open question in the topology design; the inconsistency with Manage Tiers is the new observation.)

Operator SPA partial eager-fetch

Labels: tech-debt, frontend, perf On /operator initial page load, all 12 operator partials (users, organizations, org-types, grants, products, plan-ladders, entitlement-sets, billing accounts/subscriptions/invoices/payments, sites) are fetched eagerly via HTMX, then tabs are CSS show/hide on already-rendered DOM. Confirmed by network capture in docs/operator-ux-walkthrough-evidence/landing/network.json. The architectural cause is what M7-7d (SPA → MPA conversion) is here to retire. Tracked here so it survives the M7 phase scoping. Already noted in docs/operator-ux-research.md. IA decision (2026-05-12, OpenSpec change operator-ia): the IA in docs/operator-ia.md replaces the flat-tab SPA model with a three-layer route hierarchy and a curated landing surface — M7-7d's rewrite consumes that hierarchy as input. Leave open until 7d closes it.

Integration architecture

Per-stream migration ledgers: drop the ordered-source version namespace

Labels: architecture, integration, migrations, decided

Decision taken 2026-07-05, implemented via openspec/changes/per-stream-migration-ledgers: per-stream goose ledgers (goose_db_version_core / _fedwiki / _stripe), each stream keeping its native 00001… numbering; assembleMigrations()'s positional-namespace renumbering is deleted. Core still runs first (FKs are integration→core only); integration streams are mutually order-independent. Pre-production wipe-volumes rule applied — this reset local goose bookkeeping, same as the schema-consolidation baseline squash.

Surfaced 2026-07-05 (maintainer question at schema-consolidation close-out). The consolidation shrank migrate.Sources() from 10 ordered sources to 3, but kept the mechanism: one goose_db_version ledger, with each stream's versions derived from its position in the source slice ((index+1)*1000 + seq in internal/db/migrations.go). That means an integration's identity in the version ledger is a global list position — append-only by convention, and inserting/reordering a source renumbers every later stream and corrupts bookkeeping on any existing DB. A third-party integration author should not need to know (or be assigned) a slot number.

The actual ordering requirements are weaker than an ordered list: (1) core migrates before integrations (FKs point integration→core only — verified 2026-07-04, zero integration↔integration edges); (2) integration streams are mutually independent. That's "core first, then the set in any order," not a sequence.

Proposed fix: per-stream goose ledgers (goose.SetTableName per source, e.g. goose_db_version_core / _fedwiki / _stripe), each stream keeping its native 00001… numbering; run core's ledger first, then each integration's in any order; delete the assembleMigrations() renumbering machinery entirely. Adding an integration then requires no coordination with existing streams and never renumbers anything.

Related but separate: Sources() is compile-time (go:embed + a hand edited Go slice), so a true third-party integration currently requires a fork/recompile regardless of numbering — the registration story belongs to the provider-extension-contract discussion. Timing note: switching ledgers resets goose bookkeeping, so do this while pre-production (wipe-volumes rule still in effect) — cheap now, migration-project later.

Provider dispatch transport: Temporal vs integration.outbox — unify or coexist?

Labels: architecture, integration, providers, decided

Decision taken 2026-07-05, implemented via openspec/changes/integration-extraction (Decision 4): capability, not transport (option 3) — the contract describes the lifecycle capability; the provider picks its own dispatch. Decision rule for future providers: if dispatch must be atomic with a domain commit, use the outbox handoff via a shared enqueue helper (internal/integration; core code stops writing raw core.outbox SQL directly); if the workflow owns the domain writes, dispatch directly via Temporal. FedWiki keeps direct Temporal workflows/activities; Stripe keeps the transactional outbox, whose drainer (PollIntegrationOutbox) moves into the Stripe integration tree as an integration-owned workflow — it was already a Temporal workflow itself, so Temporal remains the universal execution substrate underneath both transports; the outbox is just the Postgres-transaction-to-substrate handoff for the atomic case. The Stripe action-type vocabulary baked into core moves out with the payments-provider-seam follow-up.

Surfaced 2026-06-22 during the read-only / lifecycle undeferral explore (the M9 follow-on that consumes wiki-plugin-farmmanager v0.4.1).

Two providers dispatch mutating actions two different ways:

• FedWiki runs its lifecycle (create / delete / and now set_status) as direct Temporal workflows + activities (internal/workflows/fedwiki/). No outbox involvement.
• Stripe runs through the transactional outbox (integration.outbox + the drainer in internal/workflows/stripe/outbox.go).

The provider-extension-contract doc asserts "mutating verbs are applied provider-side via integration.outbox," but that is only true for Stripe — so the contract's transport language is already inaccurate for the FedWiki provider.

Decision for the design team (do not delve now): pick a direction —

1. Temporal as the universal dispatch, retire the outbox; or
2. Outbox as the universal async dispatch, move FedWiki onto it; or
3. Per-provider by design — the contract describes the capability, not the transport, and both coexist legitimately.

Trade-offs to weigh: the outbox gives transactional enqueue + dead-letter + DB-visible retry state and pairs naturally with webhook-driven providers; Temporal gives durable execution, the workflow UI, signals/queries, and is already FedWiki's substrate. Not blocking the read-only/lifecycle change — that dispatches set_status via FedWiki's existing Temporal path (option 3's default). Flagged so the contract's transport wording is reconciled and a uniform direction is chosen deliberately rather than by accretion.

payments-provider-seam (follow-up to integration-extraction)

Labels: architecture, integration, needs-design-decision

Surfaced 2026-07-05 during openspec/changes/integration-extraction (Decision 6) — Stripe extracts only partially; the payments seam is carried forward as its own follow-up. internal/fulfillment is Stripe-coupled despite its core-sounding name (all non-test files import stripe-go), and internal/server/billing.go (checkout), operator_billing.go (catalog sync + the Stripe action-type outbox vocabulary), product_readiness.go, and member_products.go all call stripe-go directly from core code, alongside internal/stripetest. These files encode "core billing UX consumes a payments provider" without the provider abstraction existing yet. Extracting them requires designing a payments-provider port against the billing model first — bundling it into the mechanical integration-extraction move would have coupled that move to an open-ended design decision.

Integration architecture (and operator IA placement)

Labels: design-feedback, architecture, ux The operator panel today places FedWiki sites at the same IA level as Products, Plan Ladders, Org Types, and Billing. This entrenches the assumption that FedWiki is the only external service the member-console will ever integrate with — which is wrong. The intended trajectory has the member-console acting as a hub for multiple external services (FedWiki today; NextCloud, Discourse, and others to come). Each is structurally a different concern from the catalog and runtime layers — they own their own resources, admin surfaces, and provisioning patterns, and they plug into the entitlements/billing model rather than being part of it.

Two distinct pieces of work fall out of this:

1. M7 IA (immediate): the operator panel should not have a top-level "Sites" tab. Integrations live in their own section (e.g. /operator/integrations/...) so adding a second integration does not require re-thinking IA again. M7 only needs to not entrench the FedWiki-as-first-class assumption; it does not need to design the extension contract.
2. A dedicated milestone for the integration / extension model (next-or-later): a standardized contract for how external services plug into the member-console — extension manifest, resource-key namespacing, per-integration entitlement displays, admin-surface registration patterns, and the boundary between member-console-owned state and integration-owned state. Discourse and NextCloud are the concrete drivers that will exercise the contract. See proposed milestone in status/milestones.md.

Discovered during M7 phase 7a (2026-05-08); supersedes the immediate scope of "FedWiki-only integration assumption" above by carving out the IA work and the architecture work as separate pieces.

Out-of-tree integration distribution — explicit non-goal

Labels: architecture Integrations are first-party and in-tree: the contract surface lives under internal/, which the Go toolchain restricts to this module, and composition is compile-time via internal/integrations/registry.go — an external repository cannot import the interfaces today, and Go offers no viable dynamic-plugin path. Supporting out-of-tree integrations (separate modules compiled in by a builder tool, Caddy/xcaddy-style) would require publishing a semver-stable public contract API plus a conformance suite. Recorded 2026-07-06 as a deliberate non-goal, not an oversight — the in-tree model (branch/fork, add tree + registry line, PR) is documented in docs/building-an-integration.md § Distribution model. Revisit only if a concrete third party wants to build an integration that cannot live in-tree.

Core domain events have no fan-out to interested integrations (9e contract finding)

Labels: architecture, integration, contract-evolution

The 9d contract's outbox is caller-targeted (integration.Enqueue(providerSlug, ...)) and core handlers writing org_members/grants don't know which integrations care — so an integration whose delivery derives from core state (Discourse: group membership from entitlement × org-membership) has no transport for change-triggered nudges. FedWiki never hit this because provisioning flows through its own workflows. The Discourse integration ships correct without it (level-triggered sweep + provider webhooks bound staleness to one sweep interval), but entitlement-driven changes wait for the sweep when webhooks are quiet. Proposed evolution: manifest-declared core-event subscriptions (integration declares event types; core emits through a generic seam at its commit points). Recorded 2026-07-17 during discourse-integration (design.md D3, findings #3). Upstream 2026-08-21: ratified as a contract-cannot-express gap by the Doc-39 conformance check (doc39-conformance-2026-08-21.md); now tracked upstream as Issue 32 (design/companion.md), with candidate evolutions and advance triggers recorded in design/documents/doc-44-provider-contract-ratification.md.

Manifest cannot express set-shaped (converged) delivery (9e contract finding)

Labels: design-feedback, integration, contract-evolution

The provider manifest's verb set (create/set_status/delete + read class) models operator-driven per-instance lifecycles. Discourse's delivery is a converged set — membership reconciles automatically; there is no operator-invoked mutating verb. Declaring only list/describe validates and registers cleanly, so the contract permits the shape, but nothing in the registry can say "this provider reconciles" — the operator Integrations surface shows a provider with no mutating operations and no way to tell that's by design. Candidate: an operation class (or manifest flag) for converged delivery. Recorded 2026-07-17 (discourse-integration findings #2). Upstream 2026-08-21: ratified as a contract-cannot-express gap by the Doc-39 conformance check; now tracked upstream as Issue 33 (design/companion.md, co-traveler of Issue 32 per doc-44-provider-contract-ratification.md).

member-console lint never scans integration-registered routes

Labels: tooling, testing

The lint's route scanner covers internal/server registrations only ("66 routes" with or without the Discourse tree), so mutation routes registered through the contract's RegisterRoutes hook silently escape walkthrough-coverage and raw-error-render. FedWiki never exposed this (read-only operator page); Discourse's mapping surface declared its // covers: claims voluntarily. Teach the lint to walk internal/integrations/*/web (or collect routes via the registry). Found 2026-07-17 (discourse-integration findings #7).

Integration skeleton generator

Labels: tooling, dx Scaffold a new integration's mechanical surface from a slug: the internal/integrations/<slug>/ tree (front-door adapter implementing the mandatory interface, with capability hooks stubbed in comments), store/sqlc.yaml with the two-levels-up schema paths, a migrations/00001_init.sql template (schema, role triple, grants, core_reader grant, member_console membership, mirrored Down), workflows/ and web/ stubs, a registry-line reminder, and test/seed/<slug>/. Deliberately sequenced after 9e: the Discourse build is the first hand-build against docs/building-an-integration.md and should validate that the doc alone suffices — the generator then encodes what two conformant integrations agree on, rather than guesses. Recorded 2026-07-06.

Auth & security

Session/CSRF secret generation and rotation strategy

Labels: security

Scope narrowed 2026-07-31 by hardening-polish (10e), which deliberately trimmed this issue: docs/hosting.md now documents the hard-cutover rotation procedure and its blast radius — sessions are stored server-side in Valkey and are unaffected; in-flight forms invalidate (their CSRF tokens no longer verify). Remaining open work: zero-downtime dual-key rotation (accept old+new keys during a grace window; keyring-shaped config) plus generation guidance beyond the current one-liner. Candidate for M11.

Auth setup review

Labels: security, auth Remove Keycloak-specific code, backchannel logout, session timeout, rate limiting.

IdP-agnostic role-mapping design (follow-up to hardening-polish role merge)

Labels: auth, design

hardening-polish (10e) made extractRoles a deduplicated union over all four claim locations, which fixes client-scoped roles on Keycloak but is still convention-based: the role NAME is the contract, claim locations are hardcoded, and there is no per-deployment mapping (claim path selection, role renaming, operator-role aliasing) for IdPs like Authentik/Authelia/Zitadel that use different claim shapes. Full design deliberately deferred out of 10e (see the change's proposal "Deliberately trimmed" section): decide between merge-with-config-overrides vs a declarative claim-path mapping, and where operator-role naming is declared. Note the union semantics are a documented behavior change: a same-named role in any location now grants.

Infrastructure, operations & testing

TestPlanLaddersWalkthrough flakes at MustWaitLoad — RESOLVED 2026-08-23 (root-caused and fixed same day)

Labels: test-infra, flaky, e2e

Found during ux-honest-surfaces verification (reproduced identically at pristine HEAD, so not a regression), root-caused, fixed. Mechanism: MustNavigate returns at navigation commit; a bare page.MustWaitLoad() immediately after evaluates rod's JS helper through a cached execution-context object from the previous document; during the document swap Chrome rejects the stale reference with -32000 "Object reference chain is too long", which rod v0.116.2 does not classify as retryable (it retries only the exact string "Cannot find context with specified id" — rod/page_eval.go:130, lib/cdp/error.go:26) → panic. Other interleavings of the same race surface as context deadline exceeded. The race was always present (10j hit it once and blamed a dead dev server); a fast empty-DB dev stack made the window land reliably. Fix: removed the racy construct at both of the suite's only two call sites — plan_ladders_test.go drops the redundant MustWaitLoad (the following bounded MustElement is the stronger load signal and re-resolves contexts fresh per attempt), lookup_test.go wraps its recovery-path settle in a tolerated rod.Try with a timeout. Verified: 3 consecutive isolated greens + full walkthrough package green (62s, matching the 10j baseline). Latent residue for a future dep bump: rod's retry allowlist not recognizing modern Chrome's stale-reference message — worth rechecking on the next rod upgrade.

Temporal schedule management on redeploy

Labels: operations Old schedules not cleaned up when config changes.

Resolved (2026-07-11) for the FedWiki sync schedule's redeploy args-refresh half by the fedwiki-sync-schedule-resilience change: EnsureSyncSchedule now classifies Describe errors correctly (only Temporal NotFound routes to Create; any other error is surfaced, not masked as absence), so a transient describe failure no longer skips the Update that refreshes stale schedule args. See that change's proposal.md Impact list.

Billing sweep schedule shares the FedWiki describe-error misclassification

Labels: operations, tech-debt internal/workflows/billing/schedule.go's EnsureSweepSchedule was not audited or fixed by fedwiki-sync-schedule-resilience (explicitly out of that change's scope). Confirmed by inspection it shares the same pre-fix shape: its if _, err := handle.Describe(ctx); err == nil { ...update... } else unconditionally Creates, so any non-NotFound Describe error is misread as "schedule absent" and routed to Create — the exact bug fixed in EnsureSyncSchedule (task 2.4). Unlike the FedWiki case it carries no baked-in workspace UUID, so there is no FK-violation follow-on, but a transient describe failure would still fail the create-after-describe and skip the sweep schedule's args refresh. Follow-up debt: apply the same NotFound-only routing + create-race fallback.

Database backup before migrations

Labels: operations

Add middleware tests

Labels: testing CSRF, logging, compression, recovery, request ID, timeout, secure headers, CORS.

HTMX handler file structure cleanup

Labels: refactor

Temporal auth race on first boot

Labels: bug, operations After fresh docker compose up -d, first member-console start fails to reach Temporal. Second attempt works. Live cold-boot testing (2026-07-01) found the dominant cause is server-side, not the JWKS/JWT race hypothesized from code reading: the temporal auto-setup container races its own database — it runs schema setup before temporal-db accepts connections, fails (no usable database connection found), and exits, so nothing listens on the Temporal port and start gets connection refused. The temporal service used short-form depends_on: [temporal-db] (waits for container start, not readiness) and had no keycloak dependency. Two-part fix (in the temporal-first-boot-retry change, M12b): (1) compose ordering — gate temporal on temporal-db + keycloak service_healthy (+ a temporal-db healthcheck) so Temporal comes up; (2) a bounded client-side connect retry in member-console so it rides out Temporal's transient warm-up (observed: a connection reset by peer) and real-deployment Temporal/IdP restarts. Verified live: fresh boot → first start connects after one retry and fully boots.

Migration orchestration mechanics

Labels: design-feedback Per-module migrations need a boot sequence that collects from each module's embedded FS in dependency order.

Makefile sqlc-generate target is stale — RESOLVED 2026-08-22 (model-doc-rot, 10j)

Labels: tooling, resolved The target now iterates the nine directories that carry a sqlc.yaml, failing on first error, matching docs/database-management.md. Fixing it immediately paid off: the first run surfaced that internal/integration's generated code had never been regenerated after migration 00010 added suspended_at/retired_at to core.providers (the broken target had hidden the drift); the regeneration is folded into this change, and a second run is a clean no-op. (Found 2026-08-22 during purchase-path-blockers.)

Shared trigger function ownership

Labels: design-feedback update_updated_at_column() is used by all modules. Probably belongs in a shared migration or the db package.

Update 2026-08-01 (test-db-isolation): checked against the cluster-global question and cleared. Functions are database-scoped, not cluster-global like roles, so each database in a cluster gets its own copy and public.update_updated_at_column() never blocked a second database's migration. The same holds for every ALTER FUNCTION … OWNER TO and GRANT in the streams. This stays open purely as the code-organization question it started as.

Database vs app layer: where enforcement lives is ad hoc

Labels: architecture, conventions, design

Observed 2026-08-21 while writing the product-catalog model card (10i): some load-bearing rules are schema-enforced (CHECK constraints, partial unique indexes, conferral reading only its view), while equally load-bearing rules are app-layer-only (publication gating on catalog queries, display_category behavioral neutrality, the composite purchasability gate). Which layer a new rule lands in has been ad hoc — whatever the implementing session reached for that day. Wanted: a documented convention for when a rule belongs in the schema versus the app layer (candidate axes: cross-surface consistency, whether violation corrupts data or merely misleads the UI, migration cost, testability). The model cards' [db]/[app] invariant tags now surface the de-facto split per model; the convention would make the split deliberate. Candidate home: a developer doc under docs/, referenced from the model-catalog index.

Deferred to future milestones (metering, commitments, bundles)

Storage compliance check at downgrade presupposes storage metering (unbuilt) — deferred to M13

Labels: enhancement, entitlements, billing, metering, deferred, blocked

The M8c milestone named a storage compliance check as new downgrade work (Standard → Public storage reduction). The 8c scoping pass (2026-05-31) found it presupposes storage metering, which is entirely unbuilt: no storage_bytes numeric-entitlement is seeded, there is no usage tracking, and no enforcement consumer exists. The storage_bytes resource key is recognized in the data model / design/entitlements/, but design/entitlements/README.md calls storage metering "future metering infrastructure." The "16 MB" / "256 MB" tier figures are documented but never enforced in code.

A "compliance check" needs a measured usage value to compare against the new limit — there is nothing to measure today. This is a metering build, not a downgrade-UX build, so it belongs with network-egress metering in M13 (Network / Storage Metering & Flexible Service), which builds on the M9 integration contract's namespaced resource keys.

Scope when scheduled (M13): seed a storage_bytes resource limit per tier, meter per-site/per-pool storage usage (usage_events or a periodic measure), then a downgrade-time check that surfaces over-quota state. Until then, 8c's downgrade does not gate on storage. Split out 2026-05-31 during the 8c scoping pass. Related: the force_reduce/site-selection split-out above, and the integration-contract-before-metering swap (2026-05-31) that put M9 ahead of the metering milestone (now M13).

Pooled metered resources across arbitrary provider sets — scalar resource_keys.provider can't express subset scoping (model rework, deferred to M13)

Labels: design-feedback, architecture, entitlements, metering, deferred

The M9 contract gives entitlements.resource_keys a single nullable provider column encoding fact-source cardinality (provider='fedwiki' = usage from one provider; provider IS NULL = pooled across all providers, or platform-native — see the platform-owned-metered analysis, 2026-06-07). A scalar column expresses exactly two scopes: one provider, or all/none. It cannot express an arbitrary subset — e.g. a single storage quota pooled across {FedWiki, NextCloud} while Discourse meters separately, or a platform pool with a per-provider sub-cap nested inside it. Per-provider and pool-across-everything are just the endpoints (set size 1, set = all); the general case is "this resource is metered over this set of providers."

Why it needs model rework, not a column tweak: the scalar can't carry a set. Supporting arbitrary scopes needs a grouping construct — a junction (resource_key ↔ N providers), or a named "metering scope" / "resource group" entity that a key and its contributing providers attach to, with usage rolling up over the group's members. That also interacts with the limit side (a pooled limit on the group vs. per-provider sub-limits, meter enforcing the tighter — the "nested quotas" option already flagged as available-if-wanted).

Deferred — not designing now. Flagged so M13's metering model either accounts for arbitrary-set scoping or consciously punts to a flat scalar for v1. The pooled-vs-per-provider call already handed to M13/product generalizes to "which set of providers shares this quota." Noted 2026-06-07 during the M9 9a extension-model exploration. Related: the storage-compliance / storage-metering split-out above; "Integration architecture (and operator IA placement)" and "FedWiki-only integration assumption pervades UI and data patterns" below; the dotted-display-form retirement (bare key = machine id, provider column = grouping, display_name = UI label) settled in the same exploration.

Commitment early_termination_policy='fee' branch unimplemented (block/allow built; fee deferred)

Labels: enhancement, billing, deferred

Decision 126 (design/billing/model.md) models minimum-term commitments on billing.subscriptions (commitment_end, commitment_renewal, early_termination_policy ∈ {block, fee, allow}) and dispatches a mid-term downgrade/cancellation by policy: allow proceeds immediately, block defers the change to commitment_end via a subscription_scheduled_changes row (effective_trigger='term_boundary'), and fee proceeds immediately but emits an early_termination_fee invoice line item (invoice_line_items.line_type += 'early_termination_fee', carried so the patronage pipeline attributes it correctly).

plan-switch-mechanics (M8 workstream F) implements block and allow — they ride the scheduled-change firing path that change already builds, so they were nearly free. It does not implement fee: emitting the early_termination_fee line item and wiring its patronage/credit attribution is genuinely new economic machinery, out of scope there. Until it lands, a fee-policy committed downgrade/cancel is refused with a reason at the endpoint and rendered disabled-with-reason in the member catalog (never proceeds without emitting the fee it cannot yet emit).

Severity: none today — the live deployment is entirely evergreen (commitment_end IS NULL on every subscription), so no subscription carries a fee policy and nothing exercises this path. It becomes real only once an operator configures a fee-policy commitment.

Scope of change: a later billing change — emit the early_termination_fee line item on the next invoice when a fee-policy commitment is broken mid-term, attribute it through the patronage pipeline, then flip the endpoint/catalog from refuse/disabled to active. Depends on the patronage-attribution path for the new line_type. Split out 2026-05-30 during plan-switch-mechanics design (correcting an earlier mischaracterization that treated all committed moves as a flat refusal — real block defers, it does not refuse).

Member catalog does not pre-label committed moves (block/fee) — post-click enforcement only

Labels: enhancement, frontend, billing, deferred

The member catalog (internal/server/member_products.go buildPlansData → member_plans.html) renders paid switch/cancel controls generically enabled. It does not resolve each enrolled ladder's backing subscription to read commitment_end / early_termination_policy and reflect the policy on the control, as the member-product-discovery spec scenario "Committed move reflects the early-termination policy" describes: allow = active immediate, block = active labeled "takes effect at commitment end", fee = disabled-with-reason.

Policy is instead enforced by the endpoints after the click: a block downgrade/cancel defers to term_boundary (the member sees it scheduled for the boundary date), and a fee move is refused (ErrCommitmentFee → error banner). So enforcement is correct and tested (plan-switch-mechanics, 2026-05-30); only the pre-click labeling is missing.

Why deferred: the live deployment is entirely evergreen (no subscription carries a commitment), so the block/fee label branches would never render — the labeling is dead code today and would cost an extra per-enrolled-ladder subscription + commitment lookup in buildPlansData. Correctness holds regardless because the endpoints gate the action. The only gap: a committed member would see a normal-looking control and learn the policy only after clicking, rather than up front.

Scope: thread the backing subscription's commitment (commitment_end + early_termination_policy) into the per-(ladder, tier) view model, then branch the control's label/enabled state. Pairs naturally with the deferred fee branch and with operator-side commitment configuration — none of which exist yet. See the early_termination_policy='fee' issue above and the "Minimum-term commitments" backlog item in status/milestones.md.

Member plan bundles — cross-ladder SKUs & exclusivity messaging (deferred, blocked)

Labels: enhancement, frontend, billing, deferred, blocked A bundle is a single product that occupies rungs on multiple ladders at once (cross-axis) — e.g. a SKU covering hosting-Standard and support-Basic together — as opposed to a normal tier, which sits on one axis. Member-facing work (member-plan-bundles capability, named-but-deferred in the member-ladder-aware-catalog proposal) would present: what a bundle includes, cross-ladder exclusivity messaging ("subscribing replaces your standalone hosting / support"), and disabled-with-reason on the standalone tiers a held bundle blocks. Blocked: no bundle concept exists in code, and there is no operator-side bundle configuration — so there is nothing for the member UI to present yet. Phase 2 depends on operator bundle support landing first; expect member-plan-bundles to become its own change paired with an operator-side counterpart. Tracked here so it survives archival of the member-ladder-aware-catalog proposal. Split out 2026-05-24 during that change's design review. Update 2026-05-30: workstream D shipped as operator-topology-legibility, scoped to legibility only — it makes the existing M:N (a product as a tier in several ladders) legible but deliberately does not introduce the bundle domain. So both halves remain unbuilt: the operator bundle-configuration counterpart is still a separate future change, and this member half stays blocked on it.

Add-on multi-purchase semantics & checkout

Labels: enhancement, frontend, backend, billing Add-ons are off-ladder, stackable products a member may hold multiple times (unlike ladder-gated plans, which are mutually exclusive per axis). The member-ladder-aware-catalog change frames add-ons as a distinct stackable section but deliberately defers the mechanics: repeat purchase, quantity, and the checkout/provisioning path (one pool_provision per purchase, chk_pool_provisions_source = 'purchase'). Belongs to a later checkout-mechanics change alongside the paid plan-switch work (plan-switch-mechanics), not the catalog presentation change. Split out 2026-05-24 during member-ladder-aware-catalog design review.

Model documentation

Product-catalog card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, billing, bug

The model cards keep their bodies free of drift bookkeeping (calibration-gate decision in the model-cards change); traps observed while writing each card are ledgered here with full references. From the product-catalog card:

• The designed reference tells the pre-doc-41 story — RESOLVED 2026-08-21. Decisions 134–139 ratified (Issue 29 closed), the Data Model Reference bumped to v15 with the full doc-41 integration (60 tables — pool_provision_transitions enters the master reference for the first time), doc-35 carries a superseded-by banner, and the refreshed surfaces are synced into design/. The designed and as-built product models now agree.
• core.products.entitlement_set_id has no FK. The column is a bare nullable UUID (internal/db/migrations/00001_init.sql) while openspec/specs/product-catalog/spec.md describes it as an FK to entitlement_sets; enforcement is app-side only. Contrast core.pool_provisions.entitlement_set_id, which does carry the FK. Fix: add the FK or correct the spec prose.
• A draft product can be bought (BUG, launch-relevant) — RESOLVED 2026-08-22 (purchase-path-blockers, 10j). The catalog queries now filter lifecycle_status = 'published', checkout re-checks the shared member gate (evaluateMemberGate, internal/server/product_readiness.go) before any Stripe call, and an org enrolled on a now-unpublished tier keeps its current rung via a targeted fetch (buildPlansData). Verified by DB-backed tests plus a live browser walkthrough (draft hidden, direct checkout POST 400s, publish flip appears). Card updated: product-catalog invariant 11. Original entry: The member path never checked lifecycle_status: ListPublicProducts/ListPublicPlanProducts (internal/billing/queries/products.sql) filter is_active + is_public only, resolvePurchasable (internal/server/member_products.go) checks only price activity and the Stripe mapping, and HandleCheckout (internal/server/billing.go) validates only the price, the mapping, and a ladder guard. So a draft that is active + public + priced + mapped renders as purchasable and passes checkout, and only core.confer rejects it — after payment. The full composite verdict exists solely in buildProductReadinessVM (internal/server/product_readiness.go), which the member surface never calls. Confirmed 2026-08-21 by the model-card verification pass (adversarial fact-check with citations). Triaged 2026-08-21: scheduled for M10 (maintainer: "a fix for this milestone for sure") as its own small change; the fix should route member surfaces through the shared gate rather than adding a fourth partial re-derivation.
• core.prices.unit_amount is a bare INTEGER with no range CHECK (internal/db/migrations/00001_init.sql); overflow protection is handler-level (2026-07-02 audit finding, status/audit-2026-07-02-operator-ux.md).
• mixed billing shape has no consumer. core.product_shape reports mixed (recurring and one-time prices both active) but nothing blocks or blesses selling that way — tracked upstream, see the mixed-shape entry under Design feedback below.
• prices.trial_period_days stored but honored nowhere — already tracked under "Deferred-remediation debt" above; listed here only because the column sits in this model.

Payments-billing card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, billing, bug

From writing docs/models/payments-billing.md (code-verified evidence sheet + adversarial pass). Two entries are live bugs needing triage:

• BUG: core.webhook_events partitions run out — RESOLVED 2026-08-22 (purchase-path-blockers, 10j). The promised creator now exists: EnsureWebhookEventPartitions (internal/db/partitions.go, current + 3 months ahead, mirrors the migration's naming/bounds) runs logged-not-fatal at boot in cmd/start.go and on a 24h Temporal schedule (webhook-partition-ensure, internal/workflows/maintenance/, knob webhook-partition-ensure-interval); DB-backed idempotency test proves insert-fails-before/succeeds-after. Live-verified: boot created webhook_events_2026_11. Card updated: payments-billing map. Original entry: The baseline migration creates only the current + next two monthly partitions and its comment promises "application boot or a scheduler" creates future ones — but no such code exists anywhere (repo-wide grep). Roughly three months after a deployment's initial migration, inserts hit a missing partition and every webhook write fails. Fix candidates: partition creation at boot in the migration/boot path, or a Temporal maintenance schedule shared with the Discourse webhook path. Launch-relevant: a fresh OSS deployment hits this silently at month three.
• BUG: webhook receipt can silently lose events — RESOLVED 2026-08-22 (purchase-path-blockers, 10j). The receiver now answers 500 when the insert fails so Stripe redelivers, and 200 only once the event is recorded or deduplicated (TestServeHTTP_InsertFailureReturns500). Card updated: payments-billing invariant 14. Original entry: The receiver returned 200 to Stripe even when the core.webhook_events insert failed (internal/integrations/stripe/web/webhook.go logs and still answers 200), and Stripe only redelivers on non-2xx — so a transient DB failure at receipt drops the event permanently. Subscription events later self-heal via reconcile triggers; invoice/payment events do not.
• The no-Stripe-ids-on-core rule has an undocumented exception. core.subscription_changes.stripe_event_id is NOT NULL on a core table, and the reconciler writes attribution strings into it that are not always event ids ("eager:checkout-return", "fire:cancellation"). Either rename it to attribution/reason or move it provider-side.
• core.subscriptions.status is bare TEXT with no CHECK — RESOLVED 2026-08-22 (schema-hardening, 10j). Migration 00010 adds a CHECK over Stripe's full closed vocabulary (eight values, including incomplete_expired, which the reconciler really receives). The designed vocabulary omits incomplete_expired — see the Design feedback note filed 2026-08-22.
• Invoice/payment projection trusts the webhook payload. The "never trust the payload" cardinal rule is scoped to subscriptions; invoice and payment rows are built straight from scrubbed payload fields — a deliberate, carded posture (display facts). Update 2026-08-22 (schema-hardening, 10j): the unguarded int64→int32 casts within that projection are now checked — out-of-range amounts fail the activity with a non-retryable error naming the event instead of storing a wrapped negative value. En route the executor found and fixed a live bug: ProcessWebhookEvent wrapped dispatch errors with fmt.Errorf, and the Temporal SDK judges retryability by the top-level error type without unwrapping, so every non-retryable error in the package was silently retryable; now unwrapped via errors.As (regression-tested).
• The outbox customer path is dead code — RESOLVED 2026-08-22 (model-doc-rot, 10j). EnsureStripeCustomer deleted; EnsureStripeCustomerPayload kept (the outbox worker still unmarshals it, now commented with its consumer); the test that exercised only the deleted path removed, the live outbox-executor test kept.
• docs/stripe.md claims mapping sync_status can become dead_letter — RESOLVED 2026-08-22 (model-doc-rot, 10j). Doc corrected: mappings go pending → synced (or deleted); dead-letter is an outbox status; a terminally failed sync leaves the mapping pending until the operator retry.
• One-pending-scheduled-change has no index backing — subscription-scoped supersession in the writers only; the design's item-scoped partial unique index doesn't exist. Already tracked under "Subscription scheduled-change + commitment schema implemented from design-only model" (Design feedback); listed here for the card's sake.
• Commitments are read-complete, write-absent — gating honors the columns; no code, query, or UI sets them, so production is all-evergreen and the block/fee branches are dead paths. Already tracked (commitment fee entry, deferred section).
• prices.trial_period_days still stored-but-never-honored — checkout builds no trial parameters. Already tracked (Deferred-remediation #1).

Plan-ladders card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, plan-transitions, bug

From writing docs/models/plan-ladders-transitions.md (code-verified evidence sheet). The headline is developer-doc rot: three living docs/ pages describe machinery deleted by the doc-41 change — launch-facing, since these are the docs a new contributor reads:

• docs/plan-architecture.md, docs/grant-plan-safety.md, and docs/plan-management.md all describe the dead Go Transition primitive — RESOLVED 2026-08-22 (model-doc-rot, 10j). plan-architecture and grant-plan-safety retired (near-total redundancy with the plan-ladders card; the 2026-04 incident narrative preserved at status/archive/incident-2026-04-grant-provision-sync.md; docs/README.md index and the internal/entitlements/doc.go package comment updated); plan-management corrected in place with its model description delegated to the card. Original entry: plan-architecture says "Transition is defined in internal/entitlements/transitions.go" (file deleted); grant-plan-safety's reference list names transitions.go and RevokeGrantAndTransition (neither exists); plan-management says Extend "invokes Transition with Extend=true" recording transition_type='extend' ('extend' is CHECK-rejected for new writes; extend records 'transfer' via grant lineage). As-built: the five SECURITY DEFINER conferral functions (internal/db/migrations/00005_doc41_conferral_functions.sql) fronted by internal/entitlements/conferral.go. All three docs need a doc-41 rewrite pass — M10-relevant.
• docs/plan-management.md documents restore-as-downgrade; the code restores-as-initiate — RESOLVED 2026-08-22 (model-doc-rot, 10j). Corrected in the same plan-management pass: restoration is now documented as recording initiate via the floor-guarded reapply path.
• docs/grant-plan-safety.md's wrong-path heuristic is inverted post-doc-41 — RESOLVED 2026-08-22 (model-doc-rot, 10j). Resolved by the doc's retirement; the card carries the correct as-built shape story.
• The plan-transitions spec mandates a rank-shape CHECK that doesn't exist. openspec/specs/plan-transitions/spec.md requires a CHECK binding each transition type to its rank pattern; migrations carry only the type-list and occupancy CHECKs — rank shape holds db-code via core.confer's derivation. Either add the (small, NOT VALID) CHECK or amend the spec to accept db-code enforcement.
• Rank contiguity is detection-only. 0-based contiguous ranks are maintained by UI discipline and reported by the validation page (chosen 2026-07-23, commit 93bf698); out-of-UI writers can still create gaps. Candidate: deferrable constraint or trigger (nontrivial — reorder's park-then-assign fights a non-deferrable UNIQUE).

Entitlements card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, entitlements, bug

From writing docs/models/entitlements.md (code-verified evidence sheet). Two functional gaps lead:

• Rule changes never reach existing pools. Design promises rule add/modify/deactivate re-evaluate affected pools; as built, CreateEntitlementSetRule and DeleteEntitlementSetRule (internal/server/operator_entitlement_sets.go) call no materializer, so limits and boolean grants stay stale until an unrelated conferral event happens to touch each pool — and the operator has no way to push a rule change at all. Needs a fan-out decision (synchronous over N pools vs queued) plus the UX; filed as its own question below the ledger entries in this section's history — treat this bullet as the tracking item.
• Mixed stacking policies on one resource key are order-sensitive — RESOLVED 2026-08-22 (schema-hardening, 10j, maintainer decision). Resolved by removal rather than by either candidate guard: rule authoring now accepts only additive and the selector left the form, so new mixtures cannot be created (existing rows keep computing as before). The deeper questions — what stacking policies are for and how mixtures should combine — moved to "Stacking policies need a design exploration" below.
• Person- and billing-account-targeted grants are schema-legal but undeliverable. The recipient CHECK admits them; every conferral path is org-scoped (ConferGrantTx accepts only OrgID; the expiry activity skips pool settlement without one). Constrain the schema or build the delivery path.
• entitlement_sets.is_active is an authoring-time gate, not a delivery switch — inactive sets keep selling, conferring, and materializing; the toggle only trims the product-form picker. Already re-scoped by the 10h de-advertisement (#3, "Show in operator pickers"); listed here because the card states the honest meaning.
• Design tables that were never built: credit_grants, usage_events, pool_ondemand_config; quota and credit rule types are authorable per the CHECK but the materializer skips them. Build-or-prune is an upstream question (quota/credit belong with M13 metering).
• Stale code comment: RESOLVED 2026-08-22 (model-doc-rot, 10j). The operator_entitlement_sets.go comment now cites the 00001_init.sql baseline, keeping the finding #40 attribution.

Stacking policies need a design exploration

Labels: entitlements, design, product

Filed 2026-08-22 (maintainer decision during schema-hardening triage). Rule authoring is now restricted to additive; the stacking-policy selector left the rule form because it made operators wonder what "stacking policy" even means, and mixing policies on one resource key made an org's limit depend on purchase order. Before any non-additive policy returns, this exploration must answer: what the stacking policies were designed to do and what value each offers a deployment; a scenarios document explaining, with concrete examples, when an operator would want each policy (additive, maximum, the removed replace, and any future ones); whether per-rule authoring in the entitlement-set form is even the right UI home for this concept, or whether it belongs at a different level; and the combination semantics for mixtures on one resource key (a defined tie-breaker at materialization plus an authoring warning were sketched and deliberately not built). Related: the materializer still contributes 0 for any policy value outside additive/maximum on existing rows (legacy replace), which this exploration should also settle. Design-level parts likely go upstream once scoped.

Resource-pools card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, entitlements, bug

From writing docs/models/resource-pools.md (code-verified evidence sheet). Three unenforced-but-load-bearing rules lead; each is a small, schema-only or single-file fix:

• One default pool per org is unenforced and resolution is nondeterministic — RESOLVED 2026-08-22 (schema-hardening, 10j). Migration 00010 adds uq_resource_pools_one_default_per_org (partial unique on org_id WHERE pool_type='default') plus chk_resource_pools_pool_type_valid (default|shared|dedicated, per design/data-model.md; only default is written today). Verified by DB test and live psql rejection.
• Primary-assignment uniqueness per workspace is convention only — RESOLVED 2026-08-22 (schema-hardening, 10j). Migration 00010 adds uq_pool_assignments_one_primary_per_workspace (partial unique on workspace_id WHERE is_primary) with a deterministic dedup pre-flight (earliest assignment survives). The double-debit path is closed: the quota subquery can now match at most one pool.
• Workspace creation swallows a missing default pool — RESOLVED 2026-08-22 (schema-hardening, 10j). Workspace-plus-assignment creation moved into a shared transactional function (internal/provisioning/workspace.go, CreateWorkspaceWithPrimaryAssignment) used by both signup and the member handler; the handler now rolls back and renders an error instead of reporting success on a poolless workspace.
• Pool lifecycle is columns-only. status (suspended/archived) and timestamps have no writer. A manually suspended pool would sever delivery-side resolution (the default-pool resolvers filter pool status) while quota consumption kept working (those paths consult only assignment status) — an incoherent half-cascade; doc-22 §10.8 admits the cascade is undefined. Do not add writers before it is specified upstream.
• The grant-extend flow confers into a URL-named pool — RESOLVED 2026-08-22 (schema-hardening, 10j). ExtendGrant now refuses multi-pool orgs (same copy as issuance's finding-#32 guard) and verifies the URL pool belongs to the org and is its default before conferring; refusals write nothing.
• Design/code drift on pool parentage: design hangs the default pool off the billing account; code hangs it off the organization with no billing linkage (deliberate orthogonality as-built — upstream sync candidate). pool_type's designed shared/dedicated values are unreachable. On-demand/overage (pool_ondemand_config, usage_events, pending_charges) is design-only — nothing exists in code (M13 territory).

Cross-workspace quota sharing was decided by code, not by design (upstream)

Labels: design-feedback, entitlements, upstream-membcons-db

Usage counters are pool-grain — core.numeric_entitlement_usage keys on (pool, resource key) with no workspace column — so sibling workspaces of one org consume from a single shared bucket (e.g. fedwiki_sites). Doc-22 §10.2 leaves cross-workspace sharing undefined; the code has de facto decided "shared". Upstream should either bless pool-grain sharing as the model or specify sub-allocation. Surfaced 2026-08-21 while writing the resource-pools model card.

Provider-integration card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, integration

From writing docs/models/provider-integration.md. The Doc-39 conformance check ran alongside this card — full per-clause record in doc39-conformance-2026-08-21.md; its six new findings are upstream ratification input and are not repeated here. Member-console-side items:

• Integration.Slug() and the manifest's slug are documented as "must match" but nothing verifies it — RESOLVED 2026-08-22 (schema-hardening, 10j). Boot now asserts the match per integration (internal/integration/slug.go, called from cmd/start.go before provider registration) and fails startup naming the integration and both strings.
• Env-sourced enum config values are not enum-checked at startup — RESOLVED 2026-08-22 (schema-hardening, 10j). ValidateStart now validates every declared enum key's resolved value (unset passes), sharing one membership helper with the override path (CoerceOverride) so they cannot diverge; failures aggregate into the boot error report naming key, value, and allowed set.
• Registry tables' home drifted from design: doc-39 specified billing.providers; as-built they live in the core schema's squashed baseline. With v16 the designed model carries them as seam tables of the provider seam, so the conceptual-address convention (Decision 140) covers the homing. Substrate naming drift (integration.outbox → core.outbox) likewise stands as conceptual addressing.
• Convergence expected as-built (Doc 44 ruling, 2026-08-21): ratification deliberately kept the designed core.providers discipline — a CHECK on status and the suspended_at/retired_at timestamps — rather than absorbing the as-built free-text column. Update 2026-08-22 (schema-hardening, 10j): the member-console half is done — migration 00010 adds the status CHECK and both timestamps, closing the card-tracked drift. The §6.3 boot/lint declaration↔execution check and Enqueue validation against provider_operations likewise stay normative upstream — implementation debt deferred to the dispatch layer, not amended away.
• Webhook dedup reference corrected upstream: the designed global two-column UNIQUE was unimplementable on the partitioned table; the reference now documents handler-level WHERE NOT EXISTS dedup as the binding contract. Both as-built receivers (Stripe and Discourse) already conform — verified 2026-08-21 by grep; a conformance-report aside claiming Stripe retained the old shape was itself wrong and has been corrected with membcons-db.
• fedwiki_sites is the documented historical exception to own-your-keys (seeded by core's 00002 rather than FedWiki's stream); the authoring guide says to copy Discourse, not FedWiki. Fine as documented; listed so nobody "fixes" the guide against the exception.
• Already tracked, restated by the card: the payments-provider seam (Stripe's genus-only registration), the converged-set manifest gap, the free-form outbox action_type vocabulary, and the deferred declared-verb-to-activity binding check.

Domains-registry card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, domains

From writing docs/models/domains-registry.md. Two of the parked notes' traps are now CLOSED in code and recorded here so nobody re-fixes them: the own-root carve loophole (closed by claim-expiry-and-carve-guards D4's intent-based evaluation) and the caller-side entitlement gate (moved into Registry.ClaimExternal by centralize-external-claim-gate). Open items:

• The schema looks like it constrains what only Go constrains. reversed_labels is plain TEXT with no generated-column or trigger tie to root_fqdn (a row written outside the registry silently breaks every subtree scan), and nothing constrains placement-inside-claim containment. Candidate domains migration 00003 if accepted as a design decision.
• Zero means three different things across the config layers. Operator-set domains-abandon-budget=0 maps to PolicyDisabled(-1) → ledger off; but a raw Policy.AbandonBudget == 0 means "unconfigured" → default 3. A composition root passing a literal 0 straight through flips the ledger ON with the default budget. Also the hardening design's non-goal text ("approval-only falls out of budget 0") is backwards as shipped — 0 disables the ledger. Doc fix + consider a typed knob.
• /domains/ask 200 is ambiguous while the strangler fallback is configured — 200 means "servable placement OR the legacy answerer said yes". Migration-window caveat; retires with the fallback (10d Slice 3). Nothing dates that window.
• reconcileSite's doc comment lists six adoption outcomes; the code has seven arms plus an earlier exit — RESOLVED 2026-08-22 (model-doc-rot, 10j). The comment now enumerates the actual seven branches in code order (including the non-active-claim skip) and names GrandfatherCarvedClaim with its deliberate name-policy bypass.
• Cancel doesn't probe for evidence — RESOLVED 2026-08-22 (schema-hardening, 10j). MarkClaimCanceled gained expiry's @evidence parameter, and the member cancel path now runs a fresh TXT probe before the write (3 attempts, ~2s each, ~5s budget; probe runs before the registry lock so DNS latency never holds the allocation transaction). Strict on exhaustion per maintainer decision: all-attempts-failed counts as no evidence. Note: the workflow's probe couldn't be imported (cycle); the record format is reimplemented locally with a drift-pin cross-reference, following the ledger test precedent.
• Dead generated surface: SetPlacementServable and DeletePlacementByResource have no non-test callers. Cheap cleanup.
• Assumptions to keep visible: budgets key on workspace_id with no Sybil bound beyond the operator-granted boolean (an operator attaching external_domain_claims to a free tier changes the abuse model); the ledger's ScopeLabels is a label count, deliberately PSL-free — the co.uk-style false positive is accepted, not solved. Hosted-label carving is unmetered by design (only the FedWiki numeric quota bounds it), and name_rules has no UI — lift the recorded non-goal or declare it seed-only.
• Do-not-fix note: BudgetExceeded.RetryAt's doc comment is correct (the "oldest counted entry" is the budget-th newest overall); it reads wrong on a skim. The sibling Count doc pins the meaning.

Identity card: drift & trap ledger (2026-08-21)

Labels: documentation, debt, identity, bug

From writing docs/models/identity-organization-workspace.md. The operational risk leads:

• Rank-0 fragility can 500 every new-user login — RESOLVED 2026-08-22 (schema-hardening, 10j, both guards per maintainer decision). (a) Deleting a ladder's last tier is refused when the ladder is a live org-type default (narrower than the blanket guard the 2026-07-03 remediation rejected — emptying non-default ladders stays legal); (b) AutoProvision now completes a plan-less signup with an Error-level alarm naming the ladder when rank 0 is missing, instead of failing the login; the org is repairable via reapply-defaults once the ladder is fixed.
• docs/identity-provider-setup.md contradicts the code, stale-safe direction — RESOLVED 2026-08-22 (model-doc-rot, 10j). The role-extraction section now documents the union of all four claim locations (deduplicated, order-stable) and the stale resource_access limitation callout is gone.
• Database role permissions are dormant. Seeded roles carry rich permission arrays; signup writes memberships and assignments; no server code reads any of it for authorization. Decide (with upstream doc-03) whether to enforce or remove; until then reviewers must not assume they gate anything.
• Returning-login session binding is positional — first owned org, then its first workspace; multi-org membership has no session story, and org_members rows in non-owned orgs never surface. Contract or placeholder? Needs the org-switcher decision before multi-org ships.
• All lifecycle status columns on identity tables are unchecked free text (users, persons, organizations, workspaces, org_members) — the vocabulary lives only in Go string comparisons. Same class as the subscriptions.status gap in the payments ledger.
• Design far richer than schema (upstream divergence to sync): invitations, service accounts, PATs, retention holds, person merges, and soft-delete lifecycles are all design-only; even the seeded permission vocabulary names service accounts that cannot exist. Record for upstream; settle when member-facing sharing is scheduled.

Sub-models within the model cards (low priority)

Labels: documentation, enhancement, low-priority

Noted by the maintainer 2026-08-21 while reviewing the first card: the cards' invariants allude to smaller models with their own coherent rule-sets — purchasability and conferral shape are the product-catalog examples; more will surface as cards land. At some point, identify these sub-models explicitly (as named subsections or their own cards). Deliberately unscheduled.

Design feedback (upstream design repo)

Designed subscription-status vocabulary omits incomplete_expired

Labels: design-feedback, billing, upstream-membcons-db

Filed 2026-08-22 during schema-hardening. design/data-model.md's subscriptions section lists a seven-value status state machine (incomplete, trialing, active, past_due, unpaid, paused, canceled) but omits incomplete_expired, a real Stripe subscription status the reconciler receives and stores (a Checkout session abandoned past its expiry window). Member-console's new chk_subscriptions_status_valid CHECK (migration 00010) uses Stripe's full eight-value closed vocabulary, so as-built is now stricter and more complete than designed. Upstream fix is one line: add incomplete_expired to the designed list. Until synced, this is the one place the as-built CHECK deliberately exceeds the designed text.

Mixed billing shape semantics — RESOLVED upstream (Decision 138)

Labels: design-feedback, billing, upstream-membcons-db, resolved

Resolved 2026-08-21. Filed here as a doc-41 residual gap, but membcons-db corrected the reading: Doc 41 §6.4 adjudicates mixed co-occurrence as legal and explicitly classified — product_shape reports billing_shape = 'mixed' as a first-class answer, with a lifetime-license tier alongside a subscription as the canonical case — ratified under Decision 138 (design/companion.md, ratified 2026-08-21 with Decisions 134–139). No member-console work implied. Archive on next sweep.

Cross-source supersession vs. continued billing (upstream Issue 31)

Labels: design-feedback, billing, entitlements, upstream-membcons-db

The doc-41 §11.2 residue that did survive ratification, logged upstream as Stage-1 Issue 31 per Doc 41 §12's own instruction: when an operator grant supersedes a subscription-sourced position, the subscription vehicle keeps billing — the member pays for a position a grant now covers. Upstream owns the normative answer; member-console consumes it when decided.

Suspended-only pools have no baseline floor during dunning (design question)

Labels: design-feedback, entitlements, billing, upstream-membcons-db

A pool whose only plan position is suspended (past-due subscription) gets no default restoration: ReapplyDefaultsIfVacant counts suspended as occupied (correctly — the paid position must not be superseded by the free baseline), so the organization has no live plan delivery for the whole dunning window. Is that dark period intended, or should suspension trigger a temporary baseline? The guard's mechanics are documented in internal/entitlements/reapply_defaults.go; the dunning-period intent is not decided anywhere. Surfaced 2026-08-21 while writing the plan-ladders model card.

Provider schemas: provider_configs prescription is per-org and as-built config is app-level

Labels: design-feedback, integration, upstream-membcons-db

design/integration/architecture.md ("When a new provider integration is built…") prescribes three standard table types per provider schema, including "a provider_configs table for per-organization configuration". As built (9g, dynamic-provider-config, 2026-07-22), that prescription is wrong on both axes: integration config scope is app-level (single Stripe account, no Connect topology — the per-org model was never implemented by any integration), and per-provider config tables don't exist at all — the Stripe one was dropped after sitting unused for the project's entire history. The as-built model: non-secret runtime config lives in one core-owned core.integration_config_overrides table layered over the environment via ConfigSpec() declarations; secrets are env-only. The design doc's standard provider-schema table types should reduce to entity mappings + provider-specific object tables.

tier_reduction_policy (Decision 125) is design-only — clamp is de-facto/emergent, not configurable

Labels: design-feedback, entitlements, billing, upstream-membcons-db

Decision 125 (design/companion.md, design/data-model.md) models a tier_reduction_policy ∈ {block, defer, clamp, force_reduce} (default defer) on entitlements.entitlement_set_rules, enforced per-rule at the locus that knows allocation (block as a switch precondition, defer via a boundary scheduled change, clamp/force_reduce at materialization). The column does not exist in the code schema — entitlement_set_rules is (rule_id, set_id, rule_type, resource_key, resource_value, resource_per_unit, stacking_policy, reset_period, credit_amount, credit_currency, description, is_active, …), no policy column (confirmed 2026-05-31).

So downgrade reconciliation is not configurable today; the live behavior is clamp by emergence: the FedWiki site-create guard checks usage < limit (internal/workflows/fedwiki/activities.go), so on a tier reduction the ceiling drops, existing usage is preserved, and new creation is blocked until back under cap. Verified live 2026-05-31 (Standard→Public: sites limit 16→1, 3 sites retained, member Create Site disabled "Site limit reached"). No block / defer / force_reduce path exists.

For the 8c MVP, clamp is adopted as the documented de-facto policy and needs no schema change. Making reduction policy configurable (the Decision 125 column + enforcement: materialization-time for clamp/force_reduce, switch-precondition for block, boundary scheduled-change for defer) is a later schema-sync — same family as the design-only credit_disposition / invoice_line_items.line_type columns (see "Subscription scheduled-change + commitment schema implemented from design-only model"). Discovered during 8c live verification 2026-05-31.

Subscription scheduled-change + commitment schema implemented from design-only model (upstream sync)

Labels: design-feedback, billing, upstream-membcons-db

plan-switch-mechanics (2026-05-30) implemented, in member-console migration 00015_subscription_scheduled_changes.sql, the schema the design team had added to design/billing/model.md but which existed nowhere in code: billing.subscription_scheduled_changes (Decision 123) and the subscriptions commitment columns commitment_end / commitment_renewal / early_termination_policy + the commitment_fields_coherent CHECK (Decision 126). The block/allow dispatch composes onto the scheduled-change firing path exactly as the model describes (block → effective_trigger='term_boundary'). Confirmed sound.

Two parts of the canonical model were carried but left inert, because their supporting tables don't yet exist in code — flagging for upstream coherence:

• credit_disposition on subscription_scheduled_changes (Decision 124) is implemented as a nullable column but nothing reads it: there is no credit-ledger table and no billing_accounts.default_credit_disposition column in the code schema. Decision 124's ledger/cash routing has no landing zone yet.
• invoice_line_items.line_type does not exist as a column in the code schema at all (the table has amount/description/quantity but no line_type), so the design's += 'early_termination_fee' enum value (Decision 126 fee) can't be added until the column itself is introduced. This is the schema-side reason the fee branch is deferred (see the early_termination_policy='fee' issue above).

Upstream ask: when Decisions 124 and the fee branch are scheduled, land the credit-ledger table (+ default_credit_disposition) and the invoice_line_items.line_type column together, so the already-present credit_disposition/commitment columns become live rather than inert.

Boolean entitlement materialization is code-defined, not design-documented

Labels: design-feedback, entitlements, upstream-membcons-db

design/entitlements/model.md defines entitlement_set_rules.rule_type ∈ {boolean, limit, quota, credit} but only describes materialization for numeric rules. The boolean-entitlement-materialization change (2026-07-17) added core.boolean_entitlements — pool-scoped rows recomputed by the same materializer as numeric entitlements, granted = OR across active provisions carrying the rule, rows retained with granted = FALSE on lapse (absence = never conferred), no contributions/usage side tables (provenance answerable by joining active provisions). Consumers: Discourse forum access (9e discourse_posting), 10d custom domains. Upstream ask: document boolean materialization semantics in design/entitlements/model.md alongside the numeric materialization section — the OR-aggregation rule, the lapse-row-retention convention, and that quota/credit remain unmaterialized.

Cross-module queries are undocumented

Labels: design-feedback See 2026-03-26 entitlement sets log for discussion on raw SQL vs shared interfaces vs service-layer orchestration.

Use <meter> for quotas, not for limits

Labels: design-feedback, frontend <meter> is the right element for showing usage against a quota (e.g. 3 out of 17 sites used). It should not be used to display a limit value on its own — e.g. showing "17 sites included" as a bar makes less psychological sense than plain text. Use <meter> only where there is a current usage value to compare against a maximum.

Org type CRUD when non-personal types arrive

Labels: design-feedback, organization, ux The organization.org_types table supports more than the seeded 'personal' row — schema includes display_name, description, is_active, default_product_id, and default_plan_ladder_id — but the operator UI deliberately exposes no create/edit affordances. This is the right call today (operator misuse risk; only consumer is the personal-org auto-provisioning flow), but when non-personal org types arrive (a real "organization" type beyond the per-person workspace) the IA needs to grow:

• A create/edit surface for org types (with cascade visibility — changing default_product_id does not retroactively backfill; see "Auto-provisioning does not backfill existing orgs when default_product_id changes" above).
• A way for org-creation flows (whatever introduces a non-personal org) to pick the org type, instead of the implicit 'personal' default in current code.
• Disambiguation in URL/IA: /operator/organizations/... lists actual orgs; /operator/org-types/... lists the type schema.

Until that work is scheduled, M7 should leave the schema alone and not surface CRUD. Discovered during M7 phase 7a (2026-05-08).

Resource keys carry no shape discriminator — rule authoring cannot adapt to the key

Labels: design-feedback, entitlements, ux, upstream-membcons-db

design/entitlements/model.md §resource_keys defines the table as a pure shared-namespace registry (key, display_name, description, unit) — the entitlement taxonomy's types (boolean/limit/quota/credit, Decisions 98–105) live only on entitlement_set_rules.rule_type. But in practice every key has exactly one coherent shape: discourse_posting is only ever conferred by a boolean rule (its consumers read boolean_entitlements), fedwiki_sites only ever by a numeric rule (consumers read numeric_entitlements). Nothing machine-readable records that shape — unit is free text ('flag' vs 'site') that no code reads — so the rule-authoring form cannot adapt to the selected key, and the schema cannot reject a mismatched rule: authoring a limit rule on discourse_posting materializes a numeric entitlement nothing consumes while the boolean grant that actually gates forum access never happens. Silent misconfiguration, no error at any layer.

Downstream fix landed 2026-07-21 (OpenSpec change entitlement-rule-authoring): kind ∈ {boolean, numeric} on core.resource_keys (core migration 00008 + discourse stream 00002; populated where rows are created — same as display_name/unit; no manifest change), with a key-first adaptive rule form deriving rule_type from the selected key's kind. The upstream ask below remains open.

Upstream ask: consider adding a shape/kind column to design/entitlements/model.md §resource_keys so the shared-namespace table also anchors which rule types may target a key (boolean keys ↔ boolean rules; numeric keys ↔ limit/quota rules; credit rules reference no key and need no kind). With the column in the model, rule/key compatibility could be enforced in-schema (trigger or companion CHECK pattern) rather than by operator care — same fail-closed posture as the existing chk_entitlement_set_rules_type.