Plans

rebuildListFromPersistedOps replays the view from index 0 inside the 1-second join poll (up to ~120×). Add a materialized-view checkpoint to resume from; acceptance is bounded replay work during joins.

SYNC_LIST resends the whole list on poll ticks. Make per-item events the default and snapshots the exception; acceptance is no repeated full-list push during steady-state polling.

Shared _writableCheckTimer across two pollers and a module-global _writeChain never reset across base teardown can send in-flight writes to the wrong base. Add per-base write contexts, reset write queues on teardown, and use distinct timers.

lista.lock (wx, cleanup only on teardown) leaves a stale lock after a crash and cannot coordinate desktop + headless on one machine. Add a lease with owner pid/instance id, heartbeat, stale-lock recovery, and separate storage roots where appropriate.

Store-and-forward of others' messages has no quotas/rate limits. Defer third-party relay/storage past milestone 1, then add per-topic quotas, queue caps, TTLs, rate limits, and visible storage usage.

Zero tests exist and package-lock.json is gitignored. Stand up milestone-zero CI with a reproducible lockfile, test runner, lint, dependency hygiene, redaction scan, and backend reducer/join/security smoke tests.

Security hardening, test bootstrap, reproducible installs, and docs/wiki alignment should land before Redux/package extraction.

Stand up the separate app repositories (listam-mobile, listam-desktop, listam-headless) and the shared listam-shared package repo from milestone 1, and decouple @listam/backend from BareKit globals so the published backend package runs under mobile worklet, Pear Desktop, and headless Bare/Node.

The safe current tiers are trusted full participant and blind ciphertext helper. Richer read-only or sync-only roles require membership authority, key epochs, and a new credential model.

RPC numbers, protocol events, package exports, storage migrations, owner-control commands, and cross-app sync should all have boundary tests before desktop/headless are accepted.

Each instance starts with its own base dir (mobile = Expo document dir; desktop/headless take --storage <dir>). Never share lista-local between instances.

Run a local hyperdht bootstrap node and pass it via BOOTSTRAP / --bootstrap so test peers discover each other without the public DHT.

Headless exposes scriptable primitives: create-base, print-invite, join <invite>, status, dump-list, add-item, edit-item, mark-done, delete-item, export, import, shutdown.

Every shared harness run generates content, edits it, marks it done/undone, deletes it, and asserts the resulting snapshot syncs across peers. Assertions compare canonical item ids and deletion state, not display names, so duplicate-name content cannot collapse by text.

Every test closes stores, destroys swarms, releases the lock, and removes temp dirs; seeded keypairs make assertions reproducible.

Redux Toolkit is planned because Listam is expected to grow into multiple list types: to-dos, simple tasks, calendar-derived lists, kanban boards, configurable rules, and state transitions.

Normalized entities, predictable actions, selectors, and audit-friendly event trails give mobile and desktop one shared app-state model while Autobase/Corestore stays the durable replicated source of truth.

Redux should be the UI projection and command dispatcher, not the database. Backend snapshots and protocol events reconcile Redux after persistence and replication.

Shared packages should separate pure domain code from platform code. Domain reducers, selectors, protocol types, migrations, and grocery intelligence should stay usable in any JavaScript runtime. Bare, Pear, React Native, P2P owner-control, and setup/recovery transport details belong behind backend/client adapters so each app can swap transport without changing list logic.

Redux should not become the durable database. Replicated list data remains authoritative in Autobase/Corestore. Redux holds a local projection optimized for rendering, optimistic interaction, and debugging. Backend snapshots and operation events reconcile the Redux projection after persistence and peer replication.

Public command names, event names, operation versions, and RPC numeric values should be treated as shared contracts. New behavior should append new commands or versioned fields instead of changing old meanings, so mobile, desktop, and headless can update on different schedules.

Before implementing UI for any app or project, check for a project-local design-guide/ directory. When it exists, its design system docs, tokens, component rules, and example screens are the UI source of truth and must guide implementation and review before generic visual preferences.

Use trace for very detailed development-only command/event flow, debug for development diagnostics, info for normal lifecycle milestones, warn for recoverable problems, error for failed operations, fatal for startup or persistence failures, and audit for security-relevant owner actions.

Start with smaller mobile/desktop retention, such as 10 MB files with 10 rotations, and larger headless retention, such as 50 MB files with 20 rotations. Development can keep more debug or trace data; production should default to info and above.

Redact before writing and before export. Owner-control tokens, pairing codes, invite codes, base keys, writer keys, encryption keys, raw topic keys, auth headers, and local API tokens should become short fingerprints or omitted values. Full user content should also be omitted when a diagnostic event is useful without it.

Diagnostics views should filter by app or instance name, level, component, topic/list fingerprint, request or operation correlation id, time window, and warnings/errors only.

Log startup/shutdown, backend readiness, Redux commands, adapter requests, invite and pairing phases, peer count changes, replication progress, Autobase apply/snapshot, headless role changes, queue depth, storage usage, exports/imports, and unhandled errors.

Peer log requests should be disabled by default for normal production users. The user's own paired headless instance may expose logs through explicit diagnostics actions over owner-control, but logs should never be fetched from public endpoints.

Use iOS Keychain and Android Keystore-backed storage, such as Expo SecureStore or a lower-level native adapter if the Bare bridge needs tighter control.

Use the OS keychain where possible. If unavailable, use an encrypted key file unlocked by a device-local key or user passphrase, with strict file permissions.

Use the OS keyring, TPM-backed secret storage, systemd credentials, encrypted local key file, or user-provided passphrase depending on the device. Plain files should be explicit development mode only.

On startup, detect legacy plaintext key files, validate them, write sensitive values to the secure store, replace normal metadata with fingerprints, delete plaintext files after success, and log only migration status. Provide a recovery path if secure storage is unavailable or the user is moving to a new device.

Avoid storing raw application encryption keys on generic relay hardware unless the device is explicitly acting as trusted storage for the owner.

Mobile secret storage should align with Expo SecureStore, Apple Keychain Services, and Android Keystore-backed storage.

Owner-control tokens, pairing codes, invite codes, base keys, encryption keys, and writer keys must be redacted from production logs and should not remain in plaintext app files. Public internet exposure should require an explicit future decision, not a default headless behavior.

Adapters should report typed failures for backend unavailable, not writable, pairing timeout, invite expired, incompatible protocol version, storage locked, and auth rejected. Redux should surface these in sync or ownedDevices instead of hiding them in console logs.

Run milestone-zero hardening first, refactor mobile onto the shared Redux/protocol/client packages second, then extract the backend package, then build desktop and headless. That keeps the current app working while each shared boundary is proven by the existing product.

Use stable item ids when available, preserve compatibility with legacy text-only entries, normalize entities in Redux, keep operation contracts append-only and versioned, and avoid embedding UI-only concepts into replicated backend operations.

The first milestone should keep current simple Listam behavior, but the domain model should be ready for to-dos, simple tasks, calendar-ingested lists, kanban-style boards, configurable rules, and additional personal-life-management features.

Future USB dongles should work with every app using the Holepunch stack, not only Listam. Keep relay envelopes generic and encrypted so dongles can provide bootstrap, async messages, blind relay, reliable redundant storage, store-and-forward storage, push notification relay, reconnection help, media streaming/distribution improvements, and Bluetooth configuration for relay topics without understanding Listam payloads.

The dongle prototype path currently considers Seeed Studio XIAO ESP32S3, ESP32-S3 DevKitC-1 N16R8, SPI microSD card reader modules, and 32 GB microSDHC cards. The plan keeps those devices as relay/storage appliances around generic Holepunch topics rather than Listam-only hardware.

Prove current Listam parity across mobile, desktop, and headless first. Do not add new list domains in the first milestone; add the architecture that makes them possible. All three app surfaces should consume the shared package versions and existing simple list operations should remain compatible.