# TESTING.md — per-area manual test checklists Run the checklist for every area a PR touches, in a live browser against the local dev stack (`npm run web-pms`, worktree stacks get their own port trio — see `AI_ALL.md`). Each list is the distilled regression history of that area: every line exists because it broke once. Add a line whenever a new bug class is fixed, and cite the checklist you ran in the PR description. ## Canonical AI instruction links (`AI_ALL.md`) - [ ] Root `AGENTS.md` and `CLAUDE.md` are relative symlinks whose target is exactly `AI_ALL.md`. - [ ] `cmp -s AI_ALL.md AGENTS.md` and `cmp -s AI_ALL.md CLAUDE.md` both pass, and root `CODEX.md` is absent. - [ ] In a fresh Git checkout, `git ls-files -s AGENTS.md CLAUDE.md` reports mode `120000` for both links and both still resolve to `AI_ALL.md`. ## Worktree dependency bootstrap (`remix/scripts/ensure-dependencies.js`) - [ ] In a fresh linked worktree with no copied `node_modules`, run `npm run worktree-setup`: every direct Remix dependency is linked and `npm --prefix remix run ensure-deps -- --check` passes. - [ ] With the pnpm virtual store present but top-level `eslint` and `vite` links removed, run `npm run worktree-setup`: both links are restored without copying dependency files from another checkout. - [ ] Run `npm run worktree-setup` again: it exits successfully without reinstalling, then `corepack pnpm --dir remix run lint:files -- scripts/ensure-dependencies.js scripts/dev.mjs` starts ESLint normally. ## Composer — Thingtime tab (`remix/app/components/Feed/PostComposer.tsx`) - [ ] Open the feed composer → Thingtime tab: the editor shows exactly ONE root property, `New Thing`, with no default children (no `name`). - [ ] The draft path is session-scoped (`tmp..New Thing`): add a field, reload the page, reopen the tab → the draft is EMPTY again and the store's `tmp` branch holds only the new session. - [ ] Post button stays disabled until the thing has real content (empty strings don't count; numbers/booleans/nulls do). - [ ] Photos toggle ON requires ≥1 valid image URL before Post enables; Marketplace toggle ON requires valid listing fields. Toggling either off re-enables Post on thing content alone. - [ ] Posting a thing + photo + listing renders the card as thing → photo grid → listing, with the first photo appearing exactly once. - [ ] Change type on the `New Thing` root (context menu → change type): string shows a text editor that accepts input; boolean shows a boolean editor; the seed effect must NOT clobber the converted value back to {}. - [ ] Rename the `New Thing` root TWICE in a row (click the key, type, Enter; repeat) on a FRESH page load: both renames must land in the store, not just the visible text. Regression class: memoized JSX pinning a mount-time `updatePath` whose `parent` was undefined pre-seed, and string path bindings (editor leaf, composer draftPath) not following the first rename (`path-renamed` bus event). - [ ] The in-post editor height-drags via the bottom handle (mouse and touch) with no upper limit, and never below the small floor. ## Editor windows & layer system (`remix/app/components/Thingtime/EditorSplit.tsx`) - [ ] Every toolbar control on a FLOATING frame (splits, edit toggle, reader/ code toggle, pop-out, dock-in, ▲▼ layer arrows, …) fires its action on click — none of them start a frame drag. Dragging empty toolbar space still moves the frame. - [ ] The composer's pop-out button duplicates the window into a native floating frame (traffic lights + toolbar); the in-post editor stays and both live-sync through the store. - [ ] New frames layer ABOVE the drawer; hovering the drawer brings it to front, mouse-leave hands it back. - [ ] ▼ on the top below-drawer frame / ▲ on the bottom above-drawer frame crosses the drawer WITHOUT changing relative window order; ⇧-click is bring-to-front / send-to-back. - [ ] Close or dock a below-drawer frame: the frames stacked above it must STAY above the drawer (layer divider accounting). - [ ] Open a dropdown (feed Filters, Algorithm menu) and a drawer modal with a frame floating: menus (10220) and modals (10240/10250) render ABOVE the frame; the chrome z ladder is documented in `remix/app/components/Nav/Drawer/useDrawer.tsx`. - [ ] Dragging a window from one editor instance over ANOTHER instance's window must not dock (and must never lose the window) — drop targets are instance-scoped. - [ ] `/editor` still opens with its two-window default and the drawer's Editor section still lists/saves/restores layouts (embedded composer editors must never appear there). ## Multi-editor focus (`remix/app/components/Editor/LongTextEditor.tsx`) - [ ] With the popout open (same path in two editors), click into an editor.js field, type, wait ~1s (autosave echo remounts the OTHER instance), keep typing WITHOUT re-clicking: the caret must stay exactly where it was — no jump to block start, no focus loss. Test typing in the popout and in the in-post editor. - [ ] Single-editor echo: typing continuously through several autosaves in one editor never remounts or resets it (signature echo acknowledgment). ## Feed thing rendering (`remix/app/components/Thingtime/ThingView.tsx`) - [ ] A thingtime post renders its thing as the NATIVE Thingtime tree in view mode — right-click opens the thing context menu, Toggle Edit Mode makes values editable (numbers get steppers, booleans a switch, Editor.js docs the block editor), and edits stay LOCAL: reloading the feed restores the server value, and neither the viewer's persisted thingtime blob nor the composer's tmp draft branch is touched. - [ ] A thing that resolves a kind renderer (a `render:` prop naming a kind, an explicit kind, or a structural match — in that priority order) shows the RENDERED form by default, with a small corner 🌀 icon back to the Thingtime view and ✨ back again; things resolving no renderer show the tree with no corner icon. - [ ] Editor.js docs render as rich text by default everywhere: a rich-text post body (feed + profile), a nested rich-text value inside a tree, and /search crystal chips (plain-text preview, never raw block JSON). - [ ] Untrusted (other users') things are only auto-rendered for the vetted-safe kinds (rich-text, image, audio, playlist, podcast, article, quote, book, movie, link, file, code, repository); every other kind — including the arbitrary-markup `chakra`/`element` kinds — falls back to the sanitising native tree with no rendered toggle. - [ ] SECURITY (feed + search): a thing shaped as `kind:'link'` with `url:'javascript:…'` renders a card that is NOT a clickable link (no anchor, no "Open link"); a `chakra`/`element` thing with `props:{position:'fixed',inset:0,zIndex:99999,…}` renders as a data tree, NOT a viewport overlay; image/audio/cover URLs with unsafe schemes fall back to the emoji placeholder. Verify via DOM: no `a[href^= "javascript:"]`, no fixed/absolute high-z overlay from post content. - [ ] Editing a feed thing (context menu → Toggle Edit Mode) and pressing Cmd/Ctrl+Z does NOT undo the viewer's own persisted tree — the keydown is contained to the sandbox (native field undo still works). - [ ] A very large thing (deeply nested, hundreds of nodes) mounts COLLAPSED and scrolls within a bounded box — it never mass-mounts nodes or wall-of-texts the feed. ## Post interactions & inherit chains (`remix/app/api/utils/things/things.ts`) - [ ] Reacting, commenting, saving, sharing, and opening the `/post/:id` permalink all work on a comment nested DEEP in a reply chain (build a 6+-deep comment-on-comment chain via the UI or API and interact with the deepest one) — visibility resolves through the whole `tt:inherit` chain, never "Post not found" for a legitimately deep reply. Chain resolution is bounded by cycle detection (`aclChainCore.ts`, `npm run test:acl`), NOT by a small depth cap: a depth cap silently orphaned deep replies while the feed still rendered them. - [ ] A comment whose parent chain is broken (target deleted) fails closed: not viewable, not reactable, permalink 404s. ## Thing context menu (`remix/app/components/Thingtime/ContextMenu/`) - [ ] Open the hover (popover) menu from a row inside a SMALL editor box: the menu must overflow the box freely (portal) and stay anchored to its trigger through page scroll, window resize, and layout shifts (e.g. height-dragging the composer editor while open). - [ ] The menu renders above floating frames and drawer modals (z 10260). - [ ] Drag-move and corner-resize the menu; near the right viewport edge it clamps inside the viewport without jitter. - [ ] The design-system anatomy stories (/docs/design-system → thing-context-menu) still lay out statically inside their canvases (`inline` mode). ## Post engagement row & comment threads (`remix/app/components/Feed/PostCard.tsx`) - [ ] The action row is icon + count ONLY (no text labels): 💬 comments with the merged react button DIRECTLY beside it, then 🔁 repost and ↗ share. Comment rows mirror the pattern — reply icon then react control inline under the bubble (no right-edge column) — and the react popup + full picker open without clipping from the left-side positions. - [ ] The merged react button shows ALL the viewer's own reaction tokens FIRST, then the crowd's top remaining tokens by count (+ total; heart outline at zero), and tints accent when the viewer holds a reaction. Click, hover, and touch-and-hold all open the quick-react popup on the POST button; picking an emoji applies optimistically (no wait), and ＋ opens the full custom picker. - [ ] Threads that mount OPEN (the two-level ship, drill-panel roots) revalidate in the background even when the cache already covers their reply count — reactions/edits made elsewhere reconcile in within a beat. Regression: cache-complete threads skipped the mount refetch and froze reply reactions at the cached snapshot forever. - [ ] RACE (devtools: delay `/api/v1/things?id=` responses ~3s): tap a reaction while a thread/feed/permalink fetch is in flight — the tap must survive the stale response landing (no disappear/reappear, no wrong counts), and a fresh reload must converge on the server truth. All server-copy ingestion merges through `reactionOverlay` stamped with the fetch START time; every local mutation notes itself there. Regression class: background refetches snapshotted pre-tap clobbered optimistic (even acked) reactions wholesale on ingest. - [ ] Comment rows: reply is an icon-only toggle under the bubble with the merged react control right beside it — a SINGLE tap hearts the comment (❤️, optimistic, tap again to unheart) while hover / touch-and-hold opens the quick-react popup (the POST button's click still opens the popup). The thread reveal is a "View N replies / Hide replies" text link BELOW the comment; "Show previous replies/comments" reveals from BELOW the lists. Reply avatars (20px) are smaller than parent comment avatars (28px). - [ ] The "Write a comment… / Reply to…" pills are subdued: house grey border + muted placeholder (never Chakra's default near-black outline). - [ ] Threads never flatten and have NO max depth: opening replies (or the reply input) at visual depth 4 slides that comment in as the panel's new top-level row (slide-right animation; the back arrow slides left to return one level), with its replies restarting at depth 1 — repeatable indefinitely. Closing comments exits the drill-down back to the root. - [ ] The server never caps thread depth either: replying at depth 65+ still creates, and a deep comment's permalink resolves its parent AND walks all the way back to the root post. Cycle safety in the visibility and parent-chain walks is a visited set, never a depth rail (regression class: 4-hop, then 64-hop caps 404ing deep replies as "Post not found"). - [ ] Repost is a menu: instant "Repost" posts immediately (toast + count bump); "Quote post" opens the caption + circle popover. Share is OUTWARD only: native share sheet where available, otherwise copy-link with the Lopu toast — logged-out users can still share, while react / repost nudge them to log in. ## Drawer navigation & settings (`remix/app/components/Nav/Drawer/`) - [ ] Clicking a NAVIGATING drawer item (top-level or sub-item) closes the drawer after navigating on BOTH desktop and mobile; items without a destination only select their submenu and keep it open. Search keeps its own "Search closes drawer" setting on desktop. - [ ] Settings → Drawer → "Close after click" lists every menu item (auth filtered, children nested under their top item) with per-item switches defaulting ON; turning one off keeps the drawer open for that item's clicks and persists across reloads. - [ ] The drawer footer avatar, composer avatars, and account switcher rows show the user's avatar IMAGE when one is set — the rainbow initial circle is only the no-avatar fallback (regression: UserAvatarCircle ignored avatarUrl entirely). ## PR conflict resolver model waterfall (`remix/app/components/Admin/`) - [ ] Logged out, `GET /api/v1/settings/pr-conflict-auto-resolver-model-waterfall` returns the public key, ordered waterfall, and curated model catalog; `POST` returns 401. A signed-in non-admin `POST` returns 403, while an admin can save a valid reordered waterfall. - [ ] Settings → Admin paints the last-known waterfall immediately, then reconciles in the background. Add Fable 5 and Opus 5, drag a row by its dedicated handle, use the Up/Down controls, remove a non-default row, save, reload, and confirm the exact order persists. `default` stays present and cannot be removed. - [ ] Exercise the editor at desktop and mobile widths from the top to the bottom of `/settings`: model names, Max-effort badges, handles, fallback copy, and save/add/remove controls never clip, overlap, or create horizontal scrolling. - [ ] Resolver workflow config parsing accepts only `default`, `claude-fable-5`, and `claude-opus-5`, preserves their public order, and appends `default` defensively. An unavailable endpoint, malformed JSON, duplicate/unknown model, wrong key, or empty array emits a warning and selects only `--model default`; no stored value can inject another CLI flag. - [ ] With an availability failure on the first configured model, Claude Code tries the ordered native fallback chain. A completed run that still leaves conflict markers stops for manual review; it does not silently spend another model attempt. ## Data crystals & nesting depth (`remix/app/schemas/registry.ts`) - [ ] Post a thingtime post whose thing contains an Editor.js document (or any structure) nested well past 6 levels: it must save. There is NO validator depth rail (the walk is iterative, so nesting never touches the JS call stack); the only depth bound is MongoDB's physical BSON limit (MAX_STORABLE_NESTING, probed at 179 crystal levels on mongod 8.0; crystal.thing payloads get one less), reported as a precise 400 naming MongoDB — never a raw driver 500. Circular or repeated object references also 400 loudly (identity WeakSet). - [ ] Oversized payloads still fail loudly: >10000 nodes, >1000 array items, or a key with `$`/dots must 400 with a precise message, never silently drop data. - [ ] `["post","data"]` combinations still 400 (data crystals stand alone); a thingtime post's free-form payload lives ONLY under `crystal.thing`. ## Feed & profile advanced filters (`remix/app/components/Feed/AdvancedFilters.tsx`) - [ ] Filters ▸ Advanced opens the panel between the controls row and the composer; applying keeps the last-known posts rendered while loading (no skeleton flash); a FAILED search clears to the honest empty state. - [ ] A sort-only search (e.g. oldest, nothing else) applies; relevance with no text does NOT activate advanced mode. - [ ] Shortcuts round-trip: tags, by-user (unknown user = empty result, not an error), min reactions/comments (bounded-window mode), text length. - [ ] Profile panels are locked to the profile's user (no By-user field) and the header post count stays the profile total, not the filtered count. ## Search page (`remix/app/components/Search/SearchPage.tsx`) - [ ] Visiting plain `/search` fires NO search request (check the network tab): last-cached results still paint instantly, and with no cache the empty state invites a search ("then hit Search"), never claims "Nothing matched". - [ ] Deep links still auto-run their search: `/search?q=…` (Commander's "Search things for…") and `/search?schema=…` (from /schemas). - [ ] Submit a search and navigate to another page BEFORE it resolves: you stay on that page — the resolving search must never replace-navigate back to `/search` (or eat the destination's history entry). This includes loader-bearing destinations (`/login`, `/welcome`, `/status`) where /search stays mounted while the departure is pending, and Back from `/search?q=…` to plain `/search` (must not be undone). - [ ] With a cache-restored query (input pre-filled from a previous session, no search run yet), Commander's "Search things for…" with that same text still fires a fresh search — the ?q= echo guard compares against the last q the page itself synced, never live input state. - [ ] A submit rejected by number-validation, or a failed request, keeps the invite empty state ("then hit Search") — only a RESOLVED search may claim "Nothing matched". A failed first page also must not poison Load more: it continues the previous result set's query, not the failed one's params. - [ ] A dead `?schema=` deep link (unknown/invisible shareId) toasts, strips the param from the URL, and fires NO fallback search; while a live `?schema=` resolves, no empty-state copy shows at all. ## Admin migrations & collection generations (`remix/app/components/Schemas/MigrationsPanel.tsx`) - [ ] As an admin (register a throwaway user, restart dev with `ADMIN_USERNAMES=`), the census table shows every registry collection with its logical name AND physical `_v` name. - [ ] The Storage generations table lists every physical collection with a current / stale / ahead badge, and doc counts. - [ ] After first boot against a pre-versioning db, adoption has renamed unversioned collections in place (`things` → `things_v2`) — data (users, sessions, posts) is still all there, no re-login required. - [ ] `merge-legacy-collections` dry-run reports per-collection copy counts and writes nothing; the real run copies only docs missing at the destination (re-run reports 0) and never deletes a legacy collection. - [ ] `drop-stale-collection-generations` shows the red destructive badge; dry-run lists exactly what would drop with doc counts; a non-dry run without `confirm: true` is rejected by the API (the panel sends it after the inline Really run? confirmation); the run refuses to drop a legacy collection that still has unmerged docs and says so in the notes. - [ ] Raw admin Mongo queries (`/api/v1/mongodb/raw-results`) still take LOGICAL collection names ('things'), including `$lookup`/`$unionWith` pipeline targets and collectionStats, and hit the versioned physical collections. ## Docs code windows & embed SDK preview (`remix/app/routes/docs/docsCode.tsx`, `remix/app/routes/docs/embed.tsx`) - [ ] Shell samples with bare URLs (`curl -X POST https://…`) highlight the URL as plain text — never as a `//` comment from the protocol slashes onward; real `//` and `#` comment lines still render muted. - [ ] JSON samples color negative numbers as numbers (yellow), not as CLI flags (blue); shell flags (`-H`, `--data`) stay flag-blue. - [ ] On /docs/embed, blocking `/sdk/thingtime-login.js` (devtools request blocking) swaps "Loading the SDK…" for the failure notice with the standalone-demo link within ~10s — the preview must never show a permanent loading state. ## MongoDB data endpoint (`/mongodb-status`, `remix/app/components/MongoDB/MongoEndpointConfig.tsx`) - [ ] Logged OUT: paste a reachable `mongodb://` URL → "Use for this session" flips the page to the Custom endpoint badge, the footer indicator reads "MongoDB (custom)", and the feed/search read from that DB. "Use" on the Thingtime row returns everything to default. - [ ] An unreachable URL is rejected at activation (422 toast, e.g. `MongoServerSelectionError (ECONNREFUSED)`) and the previous endpoint stays active — a bad URL must never brick the session's data calls. - [ ] A non-mongodb scheme (`http://…`), whitespace, or a >2048-char URL is rejected with a clear validation message. - [ ] Logged IN: "Save to my endpoints" persists the endpoint (survives logout/login and other browsers); the raw URL/credentials NEVER appear in any API response, page, or error — only host + db name. - [ ] While a custom endpoint is active: login/logout, profile, themes, account switcher and saved-endpoint management still work (identity is home-pinned); posts created land in the CUSTOM db; admin routes (migrations especially) still operate on the home DB. - [ ] Removing the saved endpoint the session currently uses also clears the override (page falls back to Thingtime default without a reload). - [ ] The `tt_mongo` cookie is httpOnly + session-scoped: closing the browser drops the override; document.cookie can't read it. - [ ] LOCAL DEV footer parity: with an override active, the footer indicator reads "MongoDB (custom)" on the local stack too. Regression class: the vite /api proxy's changeOrigin hid the web origin from nitro, so resolveStatusTarget classified "Current Tab" as REMOTE and health routes re-fetched themselves WITHOUT cookies (session state invisible). The proxy must forward x-forwarded-host/-proto (vite.config.ts) — verify /api/v1/health/mongodb?targetOrigin= returns custom:true with the cookie, while a real remote target (e.g. thingtime.com) still server-side fetches. ## Docs search (`remix/app/routes/docs/DocsSearch.tsx`, `docsSearchIndex.ts`) - [ ] Searching "acl" in the /docs drawer ranks the Thing schema (its `acl` field section) first; results highlight the matched terms and show an area badge + mono meta path; the nav list hides while a query is active and returns on clear (× button or Escape). - [ ] Anchored results deep-link AND scroll on client-side navigation: "scopes" → Enter lands on /docs/embed#permissions-scopes with the heading at the sticky-header offset, not the page top (DocsLayout's scroll-to-top must skip hash navigations); schema results scroll to their /docs/schemas#schema- card. - [ ] ArrowUp/Down move the active row, Enter opens it (query-param entries like design mockups/components select the exact entry), and on mobile tapping a result closes the drawer. - [ ] The query lives in the URL (?q=) with replace-style updates: typing never stacks history entries, refresh restores the search, /docs?q=acl deep-links it, result clicks carry ?q= along (so the landed URL is shareable with its search context), and × strips it. - [ ] Typing is instant and never drops keys: the input is locally controlled and the URL syncs on a ~200ms debounce — fast typing on /docs/api (the heaviest page) must not lag, and the ?q= write lands once after the pause (the static drawer lists are memoized so keystrokes don't re-render the 78-endpoint menu). - [ ] The desktop drawer never shows an internal scrollbar: content renders full height, sticks under the top nav only while it fits the viewport, and taller content (search results, expanded endpoint lists) flows with the page scroll — the bottom of the menu stays reachable. ## Shared app-data (`/api/v1/app-data/shared`, `api/utils/apps/appData.ts`) - [ ] POST /api/v1/app-data with `visibility: 'app'` on a token WITHOUT the `app-data.shared` scope returns 403 and writes nothing; with the scope the entry's acl becomes `["tt:user", "tt:app/"]`. - [ ] A plain `{ key, value }` rewrite of an existing shared entry keeps it shared (audience only changes when the write names one); `visibility: 'private'` flips the acl back to `["tt:user"]`. - [ ] GET /api/v1/app-data/shared returns other users' `visibility: 'app'` entries for the SAME app only — never private entries, never another app's entries — newest first, and `key=post:*` prefix-filters. - [ ] Author objects honour each AUTHOR's own grant: displayName/avatarUrl appear only when that author granted the profile field. - [ ] Revoking a user's grant (disconnect in settings) removes their entries from the shared feed on the next read while `GET /api/v1/app-data` still shows the entries to the owner. - [ ] The consent screen lists "Shared app storage" as its own line, and a grant of plain `app-data` does NOT cover `app-data.shared` (exact consent — no ancestor coverage). - [ ] GET /api/docs returns the whole API reference as text/markdown, and /api/docs-docs + every `-docs` route (including /api/v1/app-data/shared-docs) return their JSON doc payloads. - [ ] App-token things CRUD stays inside the namespace: POST/PUT/PATCH/DELETE /api/v1/things (and /things/search, /things/update, /things/delete) with an app token only ever touch docs carrying the app's root `appId` stamp; reads, updates, and deletes aimed at a first-party thing's id (or another app's doc) all 404. - [ ] App writes are acl-clamped: an acl beyond `tt:user` / `tt:app/` (tt:all, other apps, other users, exclusions) 400s; an insert that omits visibility/acl lands PRIVATE (never the generic route's public default); `save`/`share` thingtimes 403 as first-party surfaces; protected kinds stay refused. - [ ] Byte allowances replace key counts: keys keep writing past 200 until either the effective (user, app) allowance (50 MiB app default, or its custom sub-tier) or the app's aggregate plan (5 GiB Free by default) is spent. The corresponding over-limit write 507s and writes nothing; concurrent users never overshoot either guarded counter. GET /api/v1/app-data/usage returns userStorage and appStorage with exact used/allowance/remaining arithmetic while keeping usedBytes/budgetBytes as user-ledger aliases. A write raises both by its serialized size, an update charges only the delta, and a delete refunds both. - [ ] App allowance ownership + migration: POST /api/v1/apps stores the Free tier, storageAllowanceBytes=5 GiB, storageUsedBytes=0, and the 50 MiB default user cap; /apps/update cannot change them. Tier + runtime aggregate allowance live on that same app Thing. A legacy app fails writes closed until backfill-app-storage-allowances reconciles per-user sums and initializes aggregate last; two migration runners cannot overwrite a now-live aggregate. - [ ] Canonical account storage: create, grow, shrink, and delete first-party Things, comments/reactions, themes, algorithms, and registered app data. Each mutation changes the protected subscription ledger by exactly the UTF-8 byte delta of `JSON.stringify({ crystal, extended, tags })` in the same transaction. App data changes the account, whole-app, and app-user counters by the same delta while appearing only once in the account total. Stale/malformed stamps and ledgers fail growth closed; deletes fence for repair instead of guessing. Settings/admin/app surfaces show the same canonical value and exact bytes, with `reconciling` or `unavailable` never rendered as zero. Rerun the interrupted global migration and confirm it converges without double charging. - [ ] Registered app lifecycle stays on its dedicated surface: generic /api/v1/things POST/PUT/PATCH/DELETE cannot create, replace, edit, or remove an `app` control Thing. /api/v1/apps/delete atomically removes exactly that control row and revokes all live app sessions; retrying an already-completed delete succeeds, while users' namespace data and protected app-storage counters remain browseable/reconcilable. - [ ] Run `node scripts/verify-app-storage.mjs ` against a disposable local database: all 30 app-manager + registered-ledger checks pass for two users, including owner plan/default/single/bulk/reset flows, authorization, same-key CAS races, and first-party owner updates/deletes. The script refuses non-local URLs so it cannot seed verification accounts into production by accident. - [ ] KV listing grammar: GET /api/v1/app-data with key=post:\* or prefix= filters, limit=/cursor= page, and nextCursor walks the whole set; KV entries also appear via GET /api/v1/things?thingtime=app-data with the same token (one namespace). - [ ] Cross-user comment/reaction via the inherit chain: with app-data.shared, user B's app token can comment/react on user A's app-audience doc; the child is auto-stamped into the namespace and its visibility resolves through tt:inherit to the shared ancestor; without the scope (or after A revokes) the target 404s. - [ ] Revoking the author's grant removes their shared entries from EVERY app read on the next request — the KV shared feed and the app-token things reads alike — while the docs stay owned and browsable first-party. - [ ] Session browse: GET /api/v1/apps/data-summary lists the namespace (appName null after the app is deleted, data still counted); GET /api/v1/things?appId= narrows the own-things list to one namespace; POST /api/v1/apps/data/delete-all wipes the namespace + cascaded children and zeroes usage (works with no live grant); GET /api/v1/apps/data/shared?appId= mirrors the app's own view (sharedRead reflects the grant) and 403s with the plain no-live-grant explanation after disconnect. ## Sandbox tokens (`/api/v1/oauth/sandbox`, `api/utils/apps/sandbox.ts`) - [ ] POST /api/v1/oauth/sandbox (no auth, any clientId) returns a Bearer token that works against /app-data set/get/list/delete, the shared pool, and /oauth/userinfo — resolving to the synthetic `sandbox-you` user, never a real account. - [ ] Sandbox app-data docs carry `sandboxExpiresAt` (TTL-reaped) and are namespaced per token: a second sandbox token sees NONE of the first's entries (private or shared). - [ ] A sandbox token can never act as an account credential: /api/v1/auth/me (and any cookie/session path) rejects it. - [ ] GET /api/v1/apps/public?sandbox=1 returns a mock app (flagged `sandbox: true`) for an unregistered clientId instead of 404; without sandbox=1 the 404/403 behaviour is unchanged. - [ ] The consent popup's sandbox approve hands back a REAL minted token (falls back to the inert `tt-sandbox-token` only if the mint call fails), and scope gating on the handoff user object still matches the selection. - [ ] Feed-pollution fence: a sandbox token minted with a REAL app's clientId can write shared entries, but that real app's /app-data/shared feed never scans them (`sandboxExpiresAt` excluded) — real pages stay full-size even with fresh sandbox junk on top. - [ ] Sandbox storage budget: writes 507 once the sandbox namespace's 5 MiB byte budget is spent (no key-count cap remains); deleting entries refunds bytes and unblocks; real grants get the 50 MiB budget. - [ ] Explicit sandbox KV/things deletes refund only the ephemeral sandbox ledger. Even when a sandbox uses a real clientId, its delete never decrements that registered app's standing aggregate or a real user's ledger. - [ ] Global sandbox byte brake: the `sandbox.storage.global` rule (limit is MEGABYTES per window, default 512MB/hour, fail-closed) burns on every sandbox write app-wide and 507s all sandbox writes once spent; a write refused by the per-namespace budget refunds its global charge; an unavailable ledger 503s instead of waving writes through. - [ ] Sandbox tokens exercise the full things surface identically (CRUD, search, react, comment); every doc written through one carries `sandboxExpiresAt` (+ `sandboxSpace` in a space) whatever its kind, real app-token reads never see sandbox docs, and the TTL reap removes them with the token. - [ ] Sandbox spaces: tokens minted with the same `space` see each other's visibility-'app' entries in /app-data/shared, each authored by its own `sandbox-` pretend user; PRIVATE entries stay per-token even in a shared space; a different space (or no space) sees nothing; real feeds still exclude all sandbox docs. - [ ] Space validation: space shorter than 8 chars 400s; usernames are always 'sandbox-' prefixed so pooled feeds can't impersonate real accounts. ## Token minter — personal access tokens (`remix/app/components/Settings/TokenMinter.tsx`, `api/utils/auth/patTokens.ts`) - [ ] Settings → Token minter (auth only): mint with default "Full things access" — the returned token appears ONCE in the reveal card (token + curl example + copy buttons); after reload the reveal is gone and the token is unrecoverable, but the row lists in "Your tokens" (painted instantly from the `tt-pat-tokens-` local cache, server reconciles behind). - [ ] Permissions selector: with Full things access on, unticking one leaf (e.g. Delete) converts the selection to "every leaf except that one" and the hint lists exactly the granted scopes; minting with zero scopes is blocked with a toast. - [ ] Expiry dials stay in sync: preset chips (1h…1y, Never ∞), the log-scale slider (1ms → 10y, far right = never), and the value+unit inputs all drive the same expiresInMs; the human date preview updates. - [ ] Uses dials: Unlimited / 1 / 10 / 1000 / custom; a use-limited token consumes exactly one use per authenticated call — the (maxUses+1)-th call 401s "no uses remaining", and a 403 (missing scope) consumes NOTHING. Two racing final calls can never both spend the last use (atomic usesRemaining > 0 decrement). - [ ] A PAT works ONLY where wired: things CRUD/search/feed/user/save/ comment/react/share by scope (PUT upsert needs create+update), plus free introspection at /api/v1/tokens/self. It must 401 on /api/v1/tokens (list/mint), /tokens/revoke, /auth/me, themes, algorithms, oauth — and be rejected when smuggled via the auth COOKIE (Bearer-only). - [ ] Sub-second expiry is real: a 1500ms token works immediately and 401s after 2s (session expiresAt is the authoritative ms check; the JWT exp is ceiled to seconds). - [ ] Revoke (session-only) kills the token immediately, is idempotent, flips the row optimistically (reverts on failure), and gives a never-expiring token a reap date so the TTL index eventually clears it. Expired tokens vanish from the list once Mongo's TTL sweep runs. - [ ] Permissions selector "Select all ✅ / Unselect all 🧹" buttons: all → the single Full-access chip state; none → zero chips + mint blocked. - [ ] Sandbox ("Only its own things 🧸", onlyCreatedThings) — the tt:token grant system: every PAT-created thing carries the creator's tt:token/ entry in tokenAcl; a sandboxed token CAN patch/PUT- replace/delete/comment/react/save/share things carrying its entry and gets 403 "sandboxed … tt:token grant" on everything else (the 403 is a post-auth target check, so it DOES consume a use — only missing-scope 403s are free) — including reaction/save REMOVAL on ungranted things and re-sharing a token-created share of a foreign root. Delete stays one atomic filter op on success (tokenAcl OR legacy createdByTokenId) and returns the sandbox 403, not a phantom 404, when the thing exists but carries no grant. - [ ] Grant layering: owner PATCHes a thing's tokenAcl to [A, B] → BOTH sandboxed tokens mutate it; removing A's entry cuts A off immediately while B keeps working; owner can CREATE a thing pre-granted to a token that never touched it; a sandboxed token can re-grant (add peers to) things it holds a grant on, and can lock itself out by dropping its own entry (session always recovers it). tokenAcl replaces WHOLE (null clears), max 32 entries, entries must match tt:token/ (400 otherwise), and a tokenAcl replacement also clears the legacy createdByTokenId stamp so removed grants can't resurrect through the back-compat read. - [ ] tokenAcl is owner-only in projections: the owner (and their tokens) see it on GET /things?id=; anonymous viewers and other users never receive the field. Legacy round-2 docs (createdByTokenId, no tokenAcl) still honor their creator via the read shim. - [ ] Non-sandboxed tokens and full sessions ignore tokenAcl entirely; the settings list row shows "🧸 its own things only" + a "Grant 🆔" copy button (copies tt:token/). - [ ] PAT × app-token coexistence on the shared things routes (one resolver, three credential kinds): a PAT ignores Origin (no app binding), the OPTIONS preflight for app SDKs still serves with Authorization allowed, a PAT with things.read can browse `GET /things?appId=` (first-party read), a PAT 401s on the app-token-only app-data surface, an app token 401s on /api/v1/tokens, and the oversized-payload 413 fires BEFORE actor resolution so it never consumes a PAT use. One command re-checks all of this: `node scripts/verify-pat-tokens.mjs ` (companion to `scripts/verify-app-namespaces.mjs`). ## Admin dashboard, subscription tiers & ownership links (`/admin`, `api/utils/subscriptions/`, `api/utils/accounts/accountLinks.ts`) Dev bootstrap: register a throwaway user via `POST /api/v1/auth/register`, then restart the dev stack with `ADMIN_USERNAMES=` (registering a name already on the allowlist is refused, so register FIRST). One command re-checks the whole management plane end-to-end: `TT_VERIFY_ADMIN_USER= TT_VERIFY_ADMIN_PASS= node scripts/verify-admin-subscriptions.mjs `. - [ ] `/admin` renders the 🔐 gate card for anonymous/non-admin visitors and the dashboard (Users / Apps / Tiers / System tabs) for admins; the drawer's Account section shows the 🛠️ Admin item only for admins. - [ ] Users tab: free-text query searches every safe projected field; typed filters cover created-day ranges, tier id/name/version, booleans, quotas, storage, and every count; multiple filters combine with AND and sorting is deterministic. Each row shows created time, tier badge (+ `custom` badge when overrides exist), storage used/allowance, app-namespace bytes, and app/PAT/connected counts. With more than 400 mixed Things/legacy users, confirm the UI drains every 200-row cursor page without gaps or duplicates and a field/tier match found only on page 3 is still returned. Confirm numeric `is any of` / `is none of` filters accept comma-separated values. Exact-email matches and all backing stores stay globally newest first across page boundaries. If a continuation request fails, the last complete snapshot stays visible; a cold failure shows an error with an in-place Retry action instead of an authoritative empty table. - [ ] Apps tab query covers identity, origins, created/suspended time, status, owners/managers, users, storage, and every subscription field. A no-match query keeps the controls visible; Clear filters restores the rows; tier or link changes refresh rows without clearing the active query. Seed more than 200 apps and confirm a manager/tier match beyond page 1 is queryable. - [ ] Tiers tab query covers every descriptor field: lifecycle/version, identity text, display price amounts, computed/custom discounts, Editor.js inclusion text, quotas, and all timestamps. Filtered cards stay in Live / Draft / Archived groups with correct per-group empty states. - [ ] System has independent queries for rate-limit rules and current admins. Filtering rate limits never discards hidden unsaved edits, and the separate Promote a user lookup keeps its existing username/email flow. - [ ] Subscription editor: assigning a live tier's exact `tierVersionId` + per-field override (number in MB for byte fields, or Unlimited) persists and the row updates on save; Reset to default pins the current live default revision. If the current revision was archived, its card remains visible as current/non-selectable and note/override-only edits preserve that exact historical revision. - [ ] Tiers tab lifecycle: create a new draft, edit its name/tagline/banner, currency, all four renewal prices, quota defaults, and Editor.js inclusions; reload and confirm every field persists. The draft appears only in Draft / not live and never in public `GET /api/v1/tiers`. - [ ] Pricing discounts: each daily→weekly/monthly/yearly, weekly→monthly/yearly, and monthly→yearly percentage is computed from annualized prices. Enter a custom saved percentage, confirm it overrides just that comparison, then clear it and confirm the computed value returns. Check a zero-decimal currency (JPY) and a three-decimal currency (KWD) render their minor-unit prices correctly. - [ ] Publish requires confirmation, makes the immutable revision live/public, and hides the mutable editor. Create a new draft version, publish it, and confirm the former live revision moves to Archived while an existing user's pinned `tierVersionId`, title, and quota snapshot stay unchanged. - [ ] Archive requires confirmation and never deletes history. The default Free revision cannot be archived without publishing its replacement; draft and archived revisions are rejected for new assignments. A tier already holding a draft disables duplicate draft creation. - [ ] Tier cards render the optional banner (with graceful broken-image fallback), tagline, four prices, savings, quotas, and rich inclusions. Desktop and 375px layouts have no clipping/overlap; open each lifecycle confirmation and the Editor.js content editor while testing. - [ ] Tier quotas actually enforce: with `maxApps: 1` override the second `POST /api/v1/apps` is refused 400; a `null` override (or payg) lifts the cap. App subjects accept only `appStorageBytes`; tier/override and the runtime aggregate move atomically on the app Thing, `null` meters without blocking, and administrator-custom app plans lock owner tier changes. - [ ] `subscription-tier`, `subscription`, and `account-link` kinds are PROTECTED: generic `POST /api/v1/things` refuses them, and generic creation also rejects the deterministic `subscription-*` shareId namespace (published tiers, self-assigned plans, or links would be privilege escalation). - [ ] Apps tab: every app across all users with owner, co-managers, live-grant user count, storage rollup, and status. Suspend uses an inline Confirm/Cancel, flips the row to SUSPENDED + Restore, and: existing app tokens die immediately (401), the consent screen and /oauth/authorize refuse 403, restore allows re-authorization but does NOT resurrect swept sessions. - [ ] Ownership links (many-to-many both ways): admin assigns an account link → target appears under the owner's "Owned accounts" in the switcher (`GET /api/v1/auth/accounts/owned`), "Sign in →" assumes it without credentials (fresh per-browser session folded into the roster; other browsers/owners are never signed out), non-linked users get 403. App links put the app in the co-manager's `/apps` list and update/delete accept them; removing the link removes access (404). - [ ] Mobile (375px): the admin tables scroll inside their own container — the page body itself never scrolls horizontally; modals fit with no clipped controls. ## App-owner storage manager (`/apps/manage`, `api/utils/apps/appStorageManagement.ts`) - [ ] Logged-out visitors get the sign-in card. An owner sees every registered app; an administrator-linked co-manager sees the linked app; ordinary app users and removed co-managers get the same 404-shaped denial as an unknown app and cannot inspect aggregate usage or the user roster. - [ ] Selecting any current live card sends its stable tier id plus exact `tierVersionId`, updates the whole-app allowance while preserving exact usage, and rejects a downgrade below current usage atomically. The bootstrapped Free → Plus → Pro → PAYG path yields 5/25/100 GiB/null. An administrator-custom plan shows `custom` and disables self-service tier buttons until the admin resets it; an archived current revision remains visible but cannot be newly selected. - [ ] Default cap starts at 50 MiB, accepts 0 and finite MiB values no larger than the current aggregate, and is re-checked atomically against a racing plan change. Existing users without overrides immediately inherit it. - [ ] Select one user or many (up to all 200 shown) and apply a custom cap; each protected `app-storage` ledger records its own override, `Use app default` unsets it, and runtime usage reports the effective cap. A custom value above the aggregate is refused; a later aggregate downgrade clamps enforcement even if a historical override was larger. - [ ] The roster includes users with current or past grants/ledgers, but a username appears only while a live unexpired grant covers `profile.username`. App-user IDs/usernames are never written to the browser localStorage cache, and a failed manager re-authorization clears the cached storage view. - [ ] Desktop and 375px mobile: switch apps; inspect banner/price/savings/rich inclusions on tier cards; choose a plan; edit the default; search, select-all, single-select, bulk apply/reset; horizontally scroll the user table; and scroll the full page top-to-bottom. No page-level horizontal overflow, clipping, sticky overlap, or console errors. ## Rate limiting & index-ensure reliability (`api/utils/rateLimit/enforce.ts`, `api/utils/mongodb/collections.ts`) - [ ] Healthy path: burst a rate-limited endpoint past its limit (e.g. `things.search`, 120/min → 121 requests) → 429 with `Retry-After`, and NO `[rate-limit]`/`[mongodb]` error lines in the logs. - [ ] Index-ensure failure is AUDIBLE, never silent: break the index battery (drop `things_v2`'s `ownerId_1_crystal.appId_1_crystal.key_1` unique index, insert two docs sharing `(ownerId, crystal.appId, crystal.key)`), start a FRESH API process → the boot-time warmup run logs one line beginning `[mongodb] ensureIndexes failed building things.` and saying the next bootstrap call will retry. The cold-start PR moved the battery off the request path, so ordinary API traffic neither retries it nor logs; only the awaited bootstrap callers (`registerUser`, admin migrations) can trigger another attempt. - [ ] In-flight work is shared, but failures are retryable immediately: while one ensureIndexes battery is running, concurrent bootstrap callers await that same promise; after it fails, the next explicit bootstrap caller starts one fresh attempt instead of inheriting a rejected promise for a fixed cooldown. - [ ] Self-heals after cleanup: delete the duplicate docs, then hit an awaited ensureIndexes caller (register a user / run an admin migration) or restart the process → the unique index is rebuilt immediately (`getIndexes()` shows it) and no stale cooldown blocks the recovered database. - [ ] Limiter outage is AUDIBLE, never silent: with the limiter's own DB ops failing (e.g. Mongo down/unreachable), a limited endpoint logs `[rate-limit] enforcement unavailable for — failing open` per request; ordinary actions fail open (the route then surfaces its own DB error), `failClosed` routes return the 429 unavailable shape. Regression class: a bare `catch {}` fail-open invisibly disabled ALL rate limiting (2026-07 perf audit). ## Password hasher (`/crypto` Password Hasher panel, `api/utils/crypto/passwordHasher.server.ts`) - [ ] `/crypto` → Password Hasher: enter a username + password → the panel shows a VERIFIED badge, `bcrypt cost 10`, the `$2b$10$…` hash, and a mongosh snippet templated with that username. A supplied password is NEVER echoed back in the response; only a generated one is. - [ ] "Generate a strong one" + a length (12–64) returns a password shown exactly once ("save it now") whose hash verifies against it — check independently with `bcrypt.compare` if in doubt. - [ ] The hash is self-verified server-side before return (`verified: true`); a password under 6 chars still hashes but is flagged (register's minimum), because an existing account may predate any policy. - [ ] END-TO-END (the point of the tool): register a throwaway user via the real API, hash a NEW password, run the returned snippet VERBATIM in mongosh, then log in — the new password works and the old one is rejected. The snippet must report `things: matched 1, modified 1`. - [ ] Blob integrity: after the snippet runs, the user's `secure` BinData blob still holds email / accountKind / emailVerified / meta, and `secureVersion` incremented by 1 (matching the app's CAS write). A plain `$set: { passwordHash }` on a things-era user writes a field NOTHING reads — the snippet must unpack → edit → repack instead. - [ ] Snippet handles both stores and a miss: an unknown username reports "No user named …" AND lists the usernames that do exist, instead of silently modifying 0 docs. - [ ] Collection names in the snippet come from `physicalCollectionName()` (currently `things_v2` / `users_v2`) — never hardcoded, so a version bump can't hand out a snippet that edits a frozen generation. - [ ] Rate limited per IP (`crypto.hashPassword`, 20/min): bcrypt is the CPU cost, so a burst past the limit 429s with the hashing message. The intent stays ANONYMOUS on purpose — being locked out is the reason to reach for it — and never reads or writes the database.