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

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.