Files
member-console/docs
cgalo5758 0b34afa819 Let the retention purge delete only a site no request is changing
#245. The retention purge listed the archived sites past the 30-day
window once, then deleted each on the farm and its row without reading
the site again, so a restore accepted in between could finish and then
lose the site. The purge now takes each candidate in its own READ
COMMITTED transaction: it locks the site's lifecycle instance (the lock
every request's intake takes), then the site row by id while the row is
still archived and past the window, checks that no request on the site
is open, and holds both locks through the farm delete and the row
delete. A site that changed, went missing or has an open request is
left to a later tick; placements are released after the commit, and no
usage is written, since only archived sites without an open request
are deleted. A farm refusal keeps the row; a 404 from the farm counts
as deleted. docs/database-locks.md states the order.

Accepted: a farm delete under the locks can run 30 seconds against the
server's eight-second write timeout, so a member request on that site
waits and can lose its answer (#290). Not in this change: a request
made from a page loaded before the purge is accepted and then declined
when its workflow reads the site (recorded on #284).

Tests: TestRetentionPurgeRechecksCandidates_DB,
TestRetentionPurgeWaitsForLifecycleIntake_DB,
TestRetentionPurgeWaitsForSiteEligibility_DB,
TestRetentionPurgeHoldsLocksThroughFarmDelete_DB,
TestRetentionPurgeLeavesARestoreInFlight_DB and
TestRetentionPurgeFailures_DB. Checked by reading only: a failed
eligibility or open-request read inside the purge's transaction returns
before the farm call; nothing in the test kit fails that read, and no
production seam was added for it. Connection loss with an unknown
commit, a remote delete after cancellation and process death remain
analysis-only.

Full suite on reset databases: 5174 passed, 16 skipped, none failed.
No page changed.

Breaks, all CAUGHT (16):
- current status
- current archive time
- null archive time
- strict cutoff
- candidate identity
- open request skips
- lifecycle instance lock
- request snapshot after waiting
- row update is a successful skip
- site row lock
- locks last through HTTP
- local deletion
- placement release
- continue after candidate failure
- farm refusal keeps the row
- 404 is success
2026-10-30 02:09:31 -05:00
..
2026-09-07 21:32:14 -05:00

title, audience, summary
title audience summary
Documentation index
developer
admin
user
Index of member-console documentation, grouped by audience, plus the front-matter convention every doc follows.

Documentation

Every document in this directory carries YAML front matter declaring its audience, so readers can find what's for them and contributors know who they're writing for.

Front-matter convention

Start each doc with a front-matter block:

---
title: "Human-readable title"
audience: [admin, developer]   # one or more of: developer, admin, user (primary first)
summary: "One sentence describing what the doc covers."
---

The three audiences:

  • developer — contributing to or understanding the codebase: architecture, design decisions, dev setup, testing, UX research and conventions, the provider-extension contract.
  • admin — hosting and operating an instance: installing, configuring an identity provider, building the image, generating secrets, running the service.
  • user — the general public or a member using a running service. (None yet — the tag is reserved for member-facing docs.)

List the primary audience first; a doc may name more than one.

For administrators — hosting & operating

For developers — contributing & internals

  • Database Management — goose migrations and sqlc.
  • Database Locks — every advisory and serializing row lock, how each key is built, and the order each path takes them in.
  • Design System — UI conventions.
  • Domain Model Cards — the model catalog: one card per domain model with invariants, dimensions, and traps.
  • FedWiki Integration — provisioning via the FarmManager API.
  • Go Conventions — where a rule and an act live, transactions and locks, services that answer after the listener opens, output order, error handling, and dead code.
  • HTMX Setup — HTMX under a strict CSP.
  • Identifiers — IDs, names, and keys: which entities carry a key, its grammar and scope, and how seeds and lookups use it.
  • Operator Information Architecture — the operator panel's IA contract.
  • Operator UX Conventions — form and action conventions.
  • First-Contact UX Walk Process — the repeatable method for walking the console as a stranger.
  • First-Contact UX Rubric — the instrument that method scores with: the A–G question bank, the walker protocol, and the screen coverage checklist.
  • Agent Runner — how an agent from another model family reviews or ideates on the code inside a disposable copy: what contains it, how a task is shaped, and what a finding must carry before it counts.
  • Operator UI Accessibility Baseline — what operator-UI changes are diffed against.
  • Building an Integration — adding a new integration.
  • Testing — the test taxonomy and how to run each kind, plus the gates: make lint (page-anatomy rules and the Go static checks) and make screens (contact sheets at two widths).

For users

No member-facing documentation yet.

One page per rule

A rule is written on the one page that owns it. Another page that needs the rule links to that page instead of restating it, because two copies of a rule are edited separately and drift apart.

Where things are not

Research, drafts, audits, walkthrough evidence, and other records of how a decision was reached are not documentation; they stay in a local notebook that git ignores, so a clone never carries them. When a decision lands, whatever a reader still needs is written into this directory, which holds the result without the history. The rule for every kind of file is in status/MAINTAINING.md.