hyl.st / reams
Automerge backed Markdown editor for the Atmosphere
Star
Fork 0
Watch
reams problems.md
14 kB
Markdown
at main

Problems #

Short, actionable notes about friction encountered while changing Reams. Before each model-created commit, consider whether the task exposed a problem that would make the next change harder. Update an existing entry or add one only when there is concrete unresolved friction. No entry is required for a smooth task.

Use: affected path — problem; smallest useful improvement. Keep entries to a few lines. Remove resolved entries in the fixing commit; Git retains the history. When work needs scheduling, link a Chainlink issue rather than duplicating its status or implementation plan here.

Open #

  • Provider registration / automerge-atproto OAuth diagnostics — the SDK drops the /oauth/sessions rejection body, leaving only HTTP 400 and repeated retries. Preserve safe structured provider failure details upstream; retain previously issued grant capabilities when upstream permission-set definitions change.

  • Icon authoring / logo.svg and public/icon-* — the source SVG, regular and maskable variants, and PNG sizes were synchronized manually. Add one checked generator for the complete icon family so later logo tweaks cannot leave platform-specific artwork behind.

  • src/editions/__tests__/folder-delete-concurrency.test.ts — seven review rounds exposed missing ingress/order/failure combinations, and reproductions repeat durability-gate setup. Extract small always-released gate fixtures and keep a table of creation, attachment, move and cleanup interleavings so future lifecycle changes cover competing writers before review.

  • Browser smoke / fresh agent-browser sessions — initial navigation reported the production URL, but the next readiness wait timed out on about:blank; navigating again worked. Assert the actual active URL/tab before waiting for editor readiness so harness startup races are not mistaken for app failures.

  • src/services/refresh-welcome.ts / welcome upgrade lifecycle — a disposable content refresh acquired traversal, placement-repair and leaf-handoff machinery. Retire the release-specific runner and its exclusive helpers after the small legacy cohort has updated, rather than growing a permanent updater; #665.

  • tests/invariants/support/playwright.ts — the browser lane only runs Chromium, so iOS standalone viewport/touch bugs require manual device roundtrips. Add opt-in WebKit execution and retain a small installed-iOS PWA smoke checklist.

  • src/atproto/account-sync-worker.ts / automerge-atproto OAuth — the SDK requires synchronous Web Storage and stable resolver/transport object identity, forcing a credential snapshot/CAS bridge and cross-tab serialization. Add an injectable worker-compatible auth store and a reusable configured session factory upstream so Reams can remove this adapter rather than expand it.

  • Automerge-atproto publication API / automerge-repo-compat.ts — local durability, acknowledgement of a captured publication frontier, and an empty outbox are different barriers but share ambiguous flush/status surfaces. Expose an explicit publication result/frontier in the SDK; keep destructive retirement's empty-outbox check separate from ordinary publication success.

  • Async task lifecycle / workspace-lifecycle.ts — long-running work needs accepted-work ownership, safe stopping/retry and completion signals independent of interactive drain deadlines or a particular view. The personal importer is intentionally temporary; design the reusable local-first boundary in Chainlink #664, using the Ink & Switch task framework as a reference. The profile-to-import teardown failed in the user's live account; reproduce that close failure before restoring an editor-to-maintenance handoff.

  • SDK space-runtime / indexeddb-storage capacity — account runtimes eagerly materialize the partition, and storage notifications reload/merge it; unload does not evict native state. The worker importer avoids page CPU but still retains SDK residency. Add selective inventory/body loading and targeted invalidation before claiming concurrent large jobs remain cheap on memory-constrained devices. The real mobile archive has a 2.3 MB encoded document with 7.2 million operations and about 1.5 GB native residency; removing copy/replay overhead does not remove that underlying cost. See docs/verification/2026-10-08-mobile-archive-import.md. Incremental remote discovery now avoids lifetime network scans, but the derived inventory still loads/checksums its whole bounded journal. Use indexed metadata reads and measure local cost separately from native residency before widening the 100,000-record / 64 MiB staged-history envelope; remote compaction is deferred.

  • Browser dependency provenance / vite.config.ts — the shared ATProto optimizer cache retained an older SDK after local tarball updates, invalidating SDK-specific browser performance comparisons. Import campaigns now use per-run caches; make general dev cache identity follow the consumed lock/artifact and assert SDK provenance in browser campaigns before attributing results to a pin.

  • Image publication / scripts/publish-container.sh — registry authentication succeeded before the build, but pushing returned UNAUTHORIZED. Re-authenticating and retrying the exact loaded image succeeded without rebuilding. Refresh auth at the push boundary and retain the immutable tag in failure output for retries.

  • scripts/spikes/confidential-reams-browser.test.mjs / scripts/test-plugin-catalog.browser.mjs — the full lifecycle campaign takes about 185 seconds, so a late selector/fixture failure repeats service setup and earlier consent journeys. Split independently selectable journeys with resettable fixtures; keep the complete campaign at release checkpoints and use the fast production-worker IPC lane during iteration. An in-flight pre-expiry poll and boot's initial idle display also raced session assertions; wait for causal worker results/durable credentials, not status copy. The catalog campaign similarly couples install/lifecycle, styling and corpus navigation; make those checkpoints independently selectable for iteration. The background/fresh-reader journey also repeats about 155 seconds after a late fixture failure; keep popup preparation and ordinary-policy overrides explicit.

  • Cross-repository adversary reviews — the review agent could read Reams but was denied the companion SDK checkout, requiring pasted implementation handoffs. Give the reviewer explicit read-only access to the named SDK checkout, or run its review from that repository, so source and tests can be inspected directly.

  • src/server/oauth-broker.mjs refresh recovery — an unanswered refresh can rotate tokens without a durable browser acknowledgement, leaving its grant reserved and requiring reauthorization. Investigate a recoverable refresh-result contract with the provider while preserving DPoP replay and account fencing.

  • src/auth/integration-oauth-scopes.mjs / live permission-set fixtures — an obsolete, unused Lichen member-request capability caused invalid_token_scope before sync. The capability list is corrected, but fixtures resolve live upstream lexicons. Pin resolved definitions/CIDs for deterministic campaigns and add an upstream capability-contract check so drift is identified independently of login.

  • Namespace migration / installed Reams clients — the isolated exact deployed frontend now passes small-note offline restart/in-place PWA upgrade and fresh native recovery. The complete 113-document backup and private production database clone rehearsals remain release gates; do not substitute the small-note result. Retain native outboxes and distinguish update-required refusal from auth failure. See docs/plans/2026-10-11-happyview-client-cutover.md.

  • HappyView local service/operator builds — sharing a Cargo target between stock provider and operator checkouts previously reused a stale library artifact; separate targets are now documented. Add a launcher provenance check for selected source revision/binary and distinguish the finite operator from the served provider.

  • Legacy signed-out archive browser lane — the local HappyView fixture stages an archive but stalls at the prepared-login Sign in button, including before cleanup. Update the fixture for the current login flow and document the library Nix shell prerequisites so retained archive publication has runnable E2E evidence. Signed-in maintenance import now has separate passing local/real-service evidence in docs/verification/2026-10-08-worker-import-ingester.md.

  • Architecture checks — npm run depcruise reports 14 cycles, while ratchet:document-boundary rejects 76 raw-access sites in the audited checkout. Triage intended low-level seams separately from accidental dependencies; start with sync's import of the React editor and core imports of the Obsidian barrel. Audit findings 2–3. npm run build:editions also stops on the committed ATProto import in src/services/__tests__/refresh-welcome.test.ts, despite passing bundles and built edition checks. Move that cross-edition test into the permitted src/editions/__tests__/ directory rather than weakening the source boundary.

  • src/test-setup.ts — the global Worker fake reimplements three worker protocols and differs from production's sparse Record derivation and responses. Extract production request processing behind a thin Worker transport and use it in a controllable test transport. Finding 4.

  • Quality-tool discovery — knip.json starts at deleted src/main.tsx, so real edition entrypoints are reported unused; Node script tests have no common package-level lane. Correct the entry inventory before acting on dead-code reports, and document/run the server test lane. Findings 3 and 10.

  • docs/ — undated historical records can still look current in search results. Date remaining historical plans/decisions as encountered and remove contradictory prescriptive advice when a contract is replaced. Retain dated evidence; keep current contracts in docs/architecture.md and historical records outside startup reading. Finding 1.

  • Coverage workflow (updated 2026-10-08) — the worktree's full run took 829s: 11,025 tests passed, but the per-file 100% thresholds failed in 14 files. The user clarified that prek/100% coverage is aspirational, not a commit gate. Earlier full runs also timed out. Report assertions and coverage separately, compare against an unmodified base before repairing gaps, and use targeted checks for routine commits with full campaigns at meaningful checkpoints. Cleanup completed 11,090 passing tests with 95.37% scoped line coverage; retained checkpoint.

  • Worktree handoffs (2026-10-05) — the harness defaults to main; an omitted absolute path let three cleanup workers edit there despite the intended scope. Their exact edits were relocated and removed from main. Require each worker to verify its worktree/branch before writing, with explicit workdir and absolute file paths on every call, including follow-up handoffs. Before integration, inspect main's merge/rebase state and serialize merges between sessions.

  • package.json targeted tests (2026-10-05) — appended npm arguments reach the last command in the chained test script, unexpectedly starting the full suite; several cleanup workers repeated this and timed out. Put the exact npx vitest run <files> command in handoffs rather than npm test -- <files>, then run required lint/ratchet/type checks separately.

  • Regression fixtures (2026-10-05) — first-pass tests selected already-stored values or unmounted rows while claiming scoped writes and mounted schema changes. Require a changed canonical result and rerender a stable cell for contract-change tests; distinguish helper assertions from the real caller's behavior.

  • scripts/spikes/progressive-app-benchmark.mjs (2026-10-05) — sequential builds share mutable remote history, so later totals can resemble a regression. Retain the opt-in per-record/per-case trace and baseline-repeat check; restore equivalent service history for exact comparisons rather than rely on totals.

  • Typed-catalog test fixtures (2026-10-08) — ready catalogs were assembled separately in six suites, sometimes without beginning a rebuild, hiding lifecycle assumptions. Use explicit begin/index/finish setup; a small shared ready-catalog fixture would keep new tests consistent without replacing the real catalog.

  • tests/format-preservation/core-graph.test.ts (2026-10-08) — the exact dependency manifest had drifted from committed imports before this refactor. A read-only graph-delta command with import reasons would make deliberate manifest review easier; retain explicit approval of dependencies rather than auto-accept them.