Phase 4: Institutional Node Onboarding

2026-02-15

A P2P network of individuals is fragile. Hard drives die, phones get lost, -people lose interest. The long-term survival of humanity's memories depends on -institutions — libraries, archives, museums, universities — that measure their -lifetimes in centuries. Phase 4 continues with institutional node onboarding: -verified organizations can now pledge storage, run searchable indexes, and -participate in the network with a distinct identity.

The design follows a principle of trust but verify: institutions identify -themselves via DNS TXT records (the same mechanism used by SPF, DKIM, and DMARC -for email), pledge a storage budget, and receive reciprocity exemptions so they -can store fragments for others without expecting anything in return. In -exchange, the network treats their fragments as higher-quality replicas and -limits over-reliance on any single institution through diversity constraints.

What was built

Capability bits (tesseras-core/src/network.rs) — Two new flags added to -the Capabilities bitfield: INSTITUTIONAL (bit 7) and SEARCH_INDEX (bit 8). -A new institutional_default() constructor returns the full Phase 2 capability -set plus these two bits and RELAY. Normal nodes advertise phase2_default() -which lacks institutional flags. Serialization roundtrip tests verify the new -bits survive MessagePack encoding.

Search types (tesseras-core/src/search.rs) — Three new domain types for -the search subsystem:

SearchFilters — query parameters: memory_type, visibility, language, -date_range, geo (bounding box), page, page_size
SearchHit — a single result: content hash plus a MetadataExcerpt (title, -description, memory type, creation date, visibility, language, tags)
GeoFilter — bounding box with min_lat, max_lat, min_lon, max_lon for -spatial queries

All types derive Serialize/Deserialize for wire transport and -Clone/Debug for diagnostics.

Institutional daemon config (tesd/src/config.rs) — A new [institutional] -TOML section with domain (the DNS domain to verify), pledge_bytes (storage -commitment in bytes), and search_enabled (toggle for the FTS5 index). The -to_dht_config() method now sets Capabilities::institutional_default() when -institutional config is present, so institutional nodes advertise the right -capability bits in Pong responses.

DNS TXT verification (tesd/src/institutional.rs) — Async DNS resolution -using hickory-resolver to verify institutional identity. The daemon looks up -_tesseras.<domain> TXT records and parses key-value fields: v (version), -node (hex-encoded node ID), and pledge (storage pledge in bytes). -Verification checks:

A TXT record exists at _tesseras.<domain>
The node field matches the daemon's own node ID
The pledge field is present and valid

On startup, the daemon attempts DNS verification. If it succeeds, the node runs -with institutional capabilities. If it fails, the node logs a warning and -downgrades to a normal full node — no crash, no manual intervention.

CLI setup command (tesseras-cli/src/institutional.rs) — A new -institutional setup subcommand that guides operators through onboarding:

Reads the node's identity from the data directory
Prompts for domain name and pledge size
Generates the exact DNS TXT record to add: -v=tesseras1 node=<hex> pledge=<bytes>
Writes the institutional section to the daemon's config file
Prints next steps: add the TXT record, restart the daemon

SQLite search index (tesseras-storage) — A migration -(003_institutional.sql) that creates three structures:

search_content — an FTS5 virtual table for full-text search over tessera -metadata (title, description, creator, tags, language)
geo_index — an R-tree virtual table for spatial bounding-box queries over -latitude/longitude
geo_map — a mapping table linking R-tree row IDs to content hashes

The SqliteSearchIndex adapter implements the SearchIndex port trait with -index_tessera() (insert/update) and search() (query with filters). FTS5 -queries support natural language search; geo queries use R-tree INTERSECT for -bounding box lookups. Results are ranked by FTS5 relevance score.

The migration also adds an is_institutional column to the reciprocity table, -handled idempotently via pragma_table_info checks (SQLite's -ALTER TABLE ADD COLUMN lacks IF NOT EXISTS).

Reciprocity bypass (tesseras-replication/src/service.rs) — Institutional -nodes are exempt from reciprocity checks. When receive_fragment() is called, -if the sender's node ID is marked as institutional in the reciprocity ledger, -the balance check is skipped entirely. This means institutions can store -fragments for the entire network without needing to "earn" credits first — their -DNS-verified identity and storage pledge serve as their credential.

Node-type diversity constraint (tesseras-replication/src/distributor.rs) — -A new apply_institutional_diversity() function limits how many replicas of a -single tessera can land on institutional nodes. The cap is -ceil(replication_factor / 3.5) — with the default r=7, at most 2 of 7 -replicas go to institutions. This prevents the network from becoming dependent -on a small number of large institutions: if a university's servers go down, at -least 5 replicas remain on independent nodes.

DHT message extensions (tesseras-dht/src/message.rs) — Two new message -variants:

- - - -

Message	Purpose
`Search`	Client sends query string, filters, and page number
`SearchResult`	Institutional node responds with hits and total count

The encode() function was switched from positional to named MessagePack -serialization (rmp_serde::to_vec_named) to handle SearchFilters' optional -fields correctly — positional encoding breaks when skip_serializing_if omits -fields.

Prometheus metrics (tesd/src/metrics.rs) — Eight institutional-specific -metrics:

tesseras_institutional_pledge_bytes — configured storage pledge
tesseras_institutional_stored_bytes — actual bytes stored
tesseras_institutional_pledge_utilization_ratio — stored/pledged ratio
tesseras_institutional_peers_served — unique peers served fragments
tesseras_institutional_search_index_total — tesseras in the search index
tesseras_institutional_search_queries_total — search queries received
tesseras_institutional_dns_verification_status — 1 if DNS verified, 0 -otherwise
tesseras_institutional_dns_verification_last — Unix timestamp of last -verification

Integration tests — Two tests in -tesseras-replication/tests/integration.rs:

institutional_peer_bypasses_reciprocity — verifies that an institutional -peer with a massive deficit (-999,999 balance) is still allowed to store -fragments, while a non-institutional peer with the same deficit is rejected
institutional_node_accepts_fragment_despite_deficit — full async test using -ReplicationService with mocked DHT, fragment store, reciprocity ledger, and -blob store: sends a fragment from an institutional sender and verifies it's -accepted

322 tests pass across the workspace. Clippy clean with -D warnings.

Architecture decisions

DNS TXT over PKI or blockchain: DNS is universally deployed, universally -understood, and already used for domain verification (SPF, DKIM, Let's -Encrypt). Institutions already manage DNS. No certificate authority, no token, -no on-chain transaction — just a TXT record. If an institution loses control -of their domain, the verification naturally fails on the next check.
Graceful degradation on DNS failure: if DNS verification fails at startup, -the daemon downgrades to a normal full node instead of refusing to start. This -prevents operational incidents — a DNS misconfiguration shouldn't take a node -offline.
Diversity cap at ceil(r / 3.5): with r=7, at most 2 replicas go to -institutions. This is conservative — it ensures the network never depends on -institutions for majority quorum, while still benefiting from their storage -capacity and uptime.
Named MessagePack encoding: switching from positional to named encoding -adds ~15% overhead per message but eliminates a class of serialization bugs -when optional fields are present. The DHT is not bandwidth-constrained at the -message level, so the tradeoff is worth it.
Reciprocity exemption over credit grants: rather than giving institutions -a large initial credit balance (which is arbitrary and needs tuning), we -exempt them entirely. Their DNS-verified identity and public storage pledge -replace the bilateral reciprocity mechanism.
FTS5 + R-tree in SQLite: full-text search and spatial indexing are built -into SQLite as loadable extensions. No external search engine (Elasticsearch, -Meilisearch) needed. This keeps the deployment a single binary with a single -database file — critical for institutional operators who may not have a DevOps -team.

What comes next

Phase 4 continued — storage deduplication (content-addressable store with -BLAKE3 keying), security audits, OS packaging (Alpine, Arch, Debian, OpenBSD, -FreeBSD)
Phase 5: Exploration and Culture — public tessera browser by -era/location/theme/language, institutional curation, genealogy integration -(FamilySearch, Ancestry), physical media export (M-DISC, microfilm, acid-free -paper with QR), AI-assisted context

Institutional onboarding closes a critical gap in Tesseras' preservation model. -Individual nodes provide grassroots resilience — thousands of devices across the -globe, each storing a few fragments. Institutional nodes provide anchoring — -organizations with professional infrastructure, redundant storage, and -multi-decade operational horizons. Together, they form a network where memories -can outlast both individual devices and individual institutions.

- -