Teams Todo architecture
ARCHIVED: xitdb/signed-entity architecture proposal, superseded by the SQLite event model in architecture.md. Statements below describe historical design, not active implementation requirements or completed features.
Status: the initial MVP code implements the baseline described in the historical evidence record. The target below was approved after first deployed review and is not implemented yet. See R0–R7 for execution order and gates.
Code map
| File | Responsibility |
|---|---|
init.ts |
Plugin lifecycle, protocol declaration, receive/connection callbacks |
model.ts |
Board/event schemas and deterministic task projection |
storage.ts |
Per-board/writer xitdb logs, local control SQLite, drafts and safe replica installation |
network.ts |
App subscriptions, change hints, bounded binary replication, durable acknowledgements and reconciliation |
app.ts |
Explicit owner commands, draft acceptance and board membership workflows |
definition.ts |
Command/form definitions |
view.ts |
Generic tree/treeItem, menus, checkboxes and grant-review actions |
Network boundary
Consumes peer-network:v1; provides all peer-channel:v1 operations. Protocol is
teams-todo.sync.v1; topic is the exact board UUID. describe registers this
protocol, receive validates signatures, membership and app frames, and
connection-changed hints restore subscriptions/reconcile published history.
Periodic reconciliation covers missed notifications without releasing working
changes. Capability calls use plugin-scoped clients and explicit FIPS keys.
FIPS grants permit communication but do not define board membership. The app owns subscriptions and publication fan-out. App callbacks acknowledge processing; binary sync has a separate durable commit acknowledgement. No subscriber or replica state is stored in the FIPS DB. Direct-origin replication remains the topology; signed events do not introduce third-party history forwarding in this revision.
Owner setup and invitation bootstrap
The normal flow is named paired-node selection → Create & share, then a direct invitation inbox → Accept & join on each recipient. These authenticated owner actions review and save the required exact local grants as part of setup. The app does not receive a normal capability operation that approves arbitrary grants. FIPS retains key/grant ownership; the app never reads FIPS SQL or private keys.
Invitations use a new bounded FIPS pre-grant carrier, since ordinary board messages cannot bootstrap a recipient grant. FIPS owns authenticated envelopes/limits; Teams Todo owns signed creator descriptors, intended recipient, membership revision, join/decline and accepted-member status. Receipt does not join/grant/install anything. Unknown members require explicit local pairing. Manual commands and signed descriptor export/import remain administrative fallbacks.
App/FIPS stores cannot commit together. Store setup stages and idempotent receipts, show partial failure and prevent replayed acceptance from restoring revoked grants. Membership expansion requires explicit new owner review. Invitation payloads and reassembly must be bounded; a signed multi-member descriptor exceeds one 512-byte app frame. Contract details are pinned in core/FIPS before consumer implementation.
Text controls include subscribe/result/unsubscribe, history-changed, sync-state, sync-start, sync-complete, sync-ack and sync-error. Binary chunks contain a 21-byte app header and source bytes. Transfer IDs, byte offsets, cursors and log generations are validated; source logs are read only up to a captured committed end position.
Persistence and convergence
Each board/writer has a separate immutable xitdb source or tracked replica. This prevents a grant to one board from copying the app's entire database. SQLite stores only local control state; no SQL file replication occurs. Remote data is validated before becoming visible; full replacement stages a separate file and checks known history rather than silently overwriting it. Source compaction/reset is unsupported.
Signed source records
Replace unsigned UUID mutation records with one immutable NIP-01 signed event per
mutation. Hash the UTF-8 JSON serialization of
[0, pubkey, created_at, kind, tags, content] using SHA-256; sign the ID with BIP-340.
Use public nostr-tools helpers rather than inventing a signature/hash format.
Teams Todo owns its payload schema and deterministic content encoding, covering
protocol/version, board/task identity, writer, operation/data, sequence and logical
clock inside signed content/tags. Extra top-level fields are not NIP-01-signed.
Preserve task identity independently from mutation hashes; parentId/hierarchy and
other relationship semantics remain deferred. Core does not define Todo entities.
FIPS signs only generic event templates with its existing key; no
bunker/human signing prompts, new private key or secret export. Sign board descriptors,
creator membership revisions and app invitations too. Verification checks app
authority as well as hash/signature before shared history becomes visible.
Title/completion retain deterministic logical-clock/author/event-hash field ordering; deletion remains a permanent tombstone. Signed timestamps support readable activity, not merge authority. Preserve signed creation/mutation records and derive the task projection, creator and editors; a multi-author projection has no single creator signature covering its current state. Human names are inferred from verified node-owner bindings, with node fallback; no human signature or assignment claim. Remote Git-style review remains deferred.
NIP-01's event pubkey is x-only 32-byte hex; FIPS peer identity remains 33-byte
compressed hex. The app checks the binding and validates signed authorship separately
from authenticated delivery. FIPS validates generic envelope shape/bounds, not entity
schema, signature-based app authorization or board policy. No relay publication is
implied by using Nostr's event format.
Working state and manual publication
Authenticated owner edits save immediately into durable nonreplicated working/outbox state, with no per-edit draft acceptance. Existing automation review remains separate. The local view combines published/received history and local signed working changes. Send updates captures a batch and releases it into the origin's published xitdb history before hint fan-out. Subsequent edits remain unsent. Pin clock/sequence and crash-safe outbox/log bookkeeping in R0; repeated/interrupted Send is idempotent.
All source reads, cursor responses, hints, retries, periodic/startup/reconnect sync and manual reconciliation use only released history. Disabling hints alone is insufficient. Published receive/retry/catch-up stays automatic. Local save, publication, transport send and remote durable acknowledgement are different states.
The creator controls signed membership revisions. Owner create/join approval may save the displayed exact local grants; incoming descriptors alone never widen them. Disabled/revoked networking leaves subscription intent explicitly blocked/retryable.
Presentation, diagnostics and reset
listis a boards-only tree with visible Open/New/Join and actionable status.show <board>has a title/header outside a task-only tree; compact checkbox/title rows, inline edits and contextual refresh follow personal Todo's public UI patterns.- Visible Share/Send/setup controls; names, relative/readable times, unsent changes and per-peer confirmation summaries. Readable Activity/Members panels; technical IDs, clocks and byte counts only in explicit diagnostics.
- Structured stage/peer/transfer/attempt/duration/error logs, bounded retention and Copy diagnostics. No task content or secrets in normal logs. Do not infer remote denial from silence or call a scheduled send synchronized.
- Clear tasks creates deletions to publish normally. Local board removal stops jobs and removes local state without remote deletion or silent reimport. Fresh board means a new ID/logs; app reset is explicit local cleanup, preserving FIPS identity, pairing and other apps. Relevant grant/request removal is separately explicit and scoped via owner FIPS management. Never rewrite known shared history in place.
Lifecycle and limits
onReady resolves local node/limits and starts bounded background reconciliation.
onStop stops timers, transfers and DB resources before host shared services close.
Local task data persists even if network access is unavailable. Local signing uses
the existing identity without requiring a remote connection; unavailable signing
identity is a distinct error, not an unsigned fallback.
Limits and measured local checks are in the README and implementation plan. Runtime operation, actual FIPS exchange and portability need deployed verification before stronger claims.