diff --git a/.filenesting.json b/.filenesting.json
new file mode 100644
index 0000000..0b71966
--- /dev/null
+++ b/.filenesting.json
@@ -0,0 +1,3 @@
+{
+ "help":"https://go.microsoft.com/fwlink/?linkid=866610"
+}
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
deleted file mode 100644
index 4128026..0000000
--- a/.github/workflows/ci.yml
+++ /dev/null
@@ -1,45 +0,0 @@
-name: CI
-
-on:
- push:
- branches: [ "main", "develop" ]
- pull_request:
- branches: [ "main" ]
-
-jobs:
- build-and-test:
- name: Build and Test (.NET 8)
- runs-on: ubuntu-latest
-
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup .NET 8
- uses: actions/setup-dotnet@v4
- with:
- dotnet-version: '8.0.x'
-
- - name: Restore dependencies
- run: dotnet restore Svrn7.sln
-
- - name: Build
- run: dotnet build Svrn7.sln --no-restore --configuration Release
-
- - name: Run tests — Svrn7.Tests (Federation)
- run: >
- dotnet test tests/Svrn7.Tests/Svrn7.Tests.csproj
- --no-build --configuration Release
- --logger "console;verbosity=normal"
-
- - name: Run tests — Svrn7.Society.Tests
- run: >
- dotnet test tests/Svrn7.Society.Tests/Svrn7.Society.Tests.csproj
- --no-build --configuration Release
- --logger "console;verbosity=normal"
-
- - name: Run tests — Svrn7.TDA.Tests
- run: >
- dotnet test tests/Svrn7.TDA.Tests/Svrn7.TDA.Tests.csproj
- --no-build --configuration Release
- --logger "console;verbosity=normal"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4830c68..99a8847 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,7 +35,7 @@ Open a GitHub Issue with:
### Pull Requests
- Target the `main` branch.
-- All tests must pass: `dotnet test Svrn7.sln`
+- All tests must pass locally: `dotnet test Web7-DSA.sln`
- New behaviour requires new tests.
- C# code must target .NET 8 (`net8.0`), use nullable reference types, and follow the
existing naming conventions (see `README.md` Section 19).
diff --git a/README.md b/README.md
index 1a54be8..81d7218 100644
--- a/README.md
+++ b/README.md
@@ -1,495 +1,463 @@
-# SOVRONA (SVRN7) — Web 7.0 Shared Reserve Currency (SRC) Library
+# Web 7.0 Decentralized System Architecture (DSA)
+## Citizen/Society Trusted Digital Assistant (TDA) — v0.8.0
-> **Version 0.8.0** | .NET 8 | LiteDB | DIDComm v2 | W3C DID + VC | RFC 6962 Merkle Log | CC BY-SA 4.0 (docs) / MIT (code)
+> **Epoch 0 — Endowment Phase** | .NET 8 | DIDComm V2 | PowerShell LOBEs | W3C DID + VC | LiteDB | PPML
-[](https://github.com/web7foundation/svrn7/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT) [](https://creativecommons.org/licenses/by-sa/4.0/)
-SVRN7 (SOVRONA) is the proposed Shared Reserve Currency (SRC) for the Web 7.0 digital ecosystem,
-implemented as an embeddable .NET 8 library that manages citizen and society wallets,
-enforces a governance-controlled three-epoch monetary lifecycle, and maintains a
-cryptographically tamper-evident audit log of all transactions. Unlike traditional
-cryptocurrencies, SVRN7 is built on a foundation of self-sovereign identity — every
-participant is a DID holder, every entitlement is a Verifiable Credential, and trust
-between parties is established through standards-based cryptographic proofs rather than
-a shared blockchain or central authority.
+The Web 7.0 Decentralized System Architecture (DSA) is a sovereign, DID-native, DIDComm-native
+runtime for digital participation. Every participant in the Web 7.0 ecosystem operates a
+**Trusted Digital Assistant (TDA)** — a personal or institutional software agent that holds
+identity, manages value, communicates exclusively over end-to-end encrypted DIDComm channels,
+and participates in **Verifiable Trust Circles (VTC7)** — federated peer meshes in which
+identity and trust are cryptographic properties, not institutional ones.
+
+This repository is the Epoch 0 (Endowment Phase) reference implementation of the Web 7.0 DSA,
+specified by the DSA 0.24 diagram using the Parchment Programming Modeling Language (PPML).
+It includes the TDA Host runtime, all eleven standard LOBE modules, the SOVRONA (SVRN7)
+Shared Reserve Currency (SRC) library, and fifteen IETF Internet-Drafts.
---
## Table of Contents
-1. [Architecture Overview](#1-architecture-overview)
-2. [Solution Structure](#2-solution-structure)
-3. [Key Design Decisions](#3-key-design-decisions)
-4. [Monetary Model](#4-monetary-model)
-5. [Identity Model](#5-identity-model)
-6. [DID Method Names](#6-did-method-names)
-7. [Transfer Protocol](#7-transfer-protocol)
-8. [Overdraft Facility](#8-overdraft-facility)
-9. [DIDComm v2 Integration](#9-didcomm-v2-integration)
+1. [What is the Web 7.0 DSA?](#1-what-is-the-web-70-dsa)
+2. [The Trusted Digital Assistant (TDA)](#2-the-trusted-digital-assistant-tda)
+3. [Parchment Programming and Consistent Code Generation](#3-parchment-programming-and-consistent-code-generation)
+4. [Architecture — DSA 0.24 Epoch 0](#4-architecture--dsa-024-epoch-0)
+5. [TDA Host Runtime](#5-tda-host-runtime)
+6. [LOBE Registry](#6-lobe-registry)
+7. [DIDComm V2 Integration](#7-didcomm-v2-integration)
+8. [SOVRONA (SVRN7) Shared Reserve Currency](#8-sovrona-svrn7-shared-reserve-currency)
+9. [Identity Model](#9-identity-model)
10. [Verifiable Credentials](#10-verifiable-credentials)
11. [Merkle Audit Log](#11-merkle-audit-log)
12. [GDPR Compliance](#12-gdpr-compliance)
-13. [Getting Started — Federation](#13-getting-started--federation)
-14. [Getting Started — Society](#14-getting-started--society)
-15. [Configuration Reference](#15-configuration-reference)
-16. [DIDComm Protocol URIs](#16-didcomm-protocol-uris)
-17. [Exception Reference](#17-exception-reference)
-18. [Testing](#18-testing)
-19. [Naming Conventions](#19-naming-conventions)
-20. [NuGet Dependencies](#20-nuget-dependencies)
-21. [Roadmap](#21-roadmap)
+13. [Getting Started — TDA Host](#13-getting-started--tda-host)
+14. [Getting Started — Federation Library](#14-getting-started--federation-library)
+15. [Getting Started — Society Library](#15-getting-started--society-library)
+16. [Configuration Reference](#16-configuration-reference)
+17. [DIDComm Protocol URIs](#17-didcomm-protocol-uris)
+18. [Exception Reference](#18-exception-reference)
+19. [Solution Structure](#19-solution-structure)
+20. [Testing](#20-testing)
+21. [Naming Conventions](#21-naming-conventions)
+22. [NuGet Dependencies](#22-nuget-dependencies)
+23. [Roadmap](#23-roadmap)
---
-## 1. Architecture Overview
+## 1. What is the Web 7.0 DSA?
+
+The Web 7.0 Decentralized System Architecture is a design framework and reference
+implementation for sovereign digital participation. Its governing premise is that **identity
+precedes participation** — every action in the system is taken by a DID holder, every
+entitlement is a Verifiable Credential, and trust between parties is established by
+cryptographic proof, not by institutional authority.
-Two NuGet packages in a strict dependency hierarchy:
+The DSA has five structural layers:
```
-Svrn7.Society ← Society-level driver, DIDComm transfers, Federation resolvers
- └─ Svrn7.Federation ← Federation-level driver, ISvrn7Driver, options
- ├─ Svrn7.DIDComm ← Full DIDComm v2 — five pack modes
- ├─ Svrn7.Identity ← VC issuance / verification (W3C VC v2 JWT)
- ├─ Svrn7.Ledger ← RFC 6962 Merkle log, 8-step transfer validator
- ├─ Svrn7.Store ← LiteDB persistence — three independent databases
- ├─ Svrn7.Crypto ← secp256k1, Ed25519, AES-256-GCM, Blake3, Base58btc
- └─ Svrn7.Core ← Models, interfaces, exceptions, constants (zero deps)
++--------------------------------------------------------------+
+| VTC7 Mesh — Verifiable Trust Circles |
+| Federated peer TDAs; DIDComm-native; no central broker |
++--------------------------------------------------------------+
+| TDA — Trusted Digital Assistant |
+| Sovereign agent runtime; LOBEs; Switchboard; Runspace Pool |
++--------------------------------------------------------------+
+| DIDComm V2 — Transport |
+| SignThenEncrypt; HTTP/2 + mTLS; did:drn Locator DID URLs |
++--------------------------------------------------------------+
+| W3C DID + VC — Identity and Trust |
+| did:drn method; VTC7 proof sets; IETF-specified |
++--------------------------------------------------------------+
+| SVRN7 SRC — Value Layer |
+| Shared Reserve Currency; UTXO; RFC 6962 Merkle log |
++--------------------------------------------------------------+
```
-### Three-Database Architecture
+The DSA is not a blockchain. There is no shared ledger, no consensus protocol, no mining.
+Trust is a property of cryptographic identity and standards-based credential exchange
+between sovereign agents.
-| Database | Default file | Contents |
-|---|---|---|
-| `svrn7.db` | `data/svrn7.db` | Wallets, UTXOs, citizens, societies, memberships, overdraft records, Merkle log, tree heads |
-| `svrn7-dids.db` | `data/svrn7-dids.db` | DID Documents, version history, verification method index |
-| `svrn7-vcs.db` | `data/svrn7-vcs.db` | Verifiable Credentials, revocation events |
+---
-All three paths can be set to `:memory:` for zero-disk testing.
+## 2. The Trusted Digital Assistant (TDA)
-### Deployment Topology
+A TDA is a sovereign runtime — a .NET 8 console application (Generic Host + Kestrel HTTP/2
++ mTLS) that acts on behalf of a citizen or a Society. It has exactly one inbound surface:
```
-┌──────────────────────────────────────────────────────────┐
-│ Web 7.0 Federation (ISvrn7Driver) │
-│ • Federation wallet — sole source of all SVRN7 │
-│ • Global DID method name registry │
-│ • Supply governance (monotonically increasing) │
-└──────────┬───────────────────┬───────────────┬───────────┘
- │ DIDComm │ │
- ┌──────┴──────┐ ┌───────┴──────┐ ┌────┴──────────┐
- │ Society A │ │ Society B │ │ Society N │
- │ did:soc-a │ │ did:soc-b │ │ did:soc-n │
- │ citizens │ │ citizens │ │ citizens │
- └─────────────┘ └──────────────┘ └───────────────┘
+POST /didcomm (HTTP/2 + mTLS, DIDComm V2 SignThenEncrypt)
```
----
+All TDA-to-TDA communication is DIDComm. No SMTP, no CalDAV, no gRPC, no public REST API.
+The TDA is the boundary of trust: only packed, authenticated DIDComm messages enter or leave.
-## 2. Solution Structure
-
-```
-Svrn7.sln
-├── src/
-│ ├── Svrn7.Core/
-│ │ ├── Svrn7Constants.cs Protocol constants, DIDComm URIs, epoch values
-│ │ ├── Models.cs All record types (Wallet, Utxo, CitizenRecord, ...)
-│ │ ├── Exceptions.cs 19 typed domain exceptions
-│ │ └── Interfaces.cs All interfaces (IDidDocumentResolver, IVcDocumentResolver, ...)
-│ ├── Svrn7.Crypto/
-│ │ └── CryptoService.cs secp256k1, Ed25519, AES-256-GCM, Blake3, Base58btc
-│ ├── Svrn7.Store/
-│ │ ├── Svrn7LiteContext.cs svrn7.db LiteDB context
-│ │ ├── LiteStores.cs LiteWalletStore, LiteIdentityRegistry
-│ │ ├── LiteRegistries.cs LiteDidDocumentRegistry, LiteVcRegistry
-│ │ └── LiteFederationAndResolvers.cs
-│ │ LiteFederationStore, LocalDidDocumentResolver,
-│ │ LiteVcDocumentResolver
-│ ├── Svrn7.Ledger/
-│ │ ├── MerkleLog.cs RFC 6962 SHA-256 Merkle log
-│ │ └── TransferValidator.cs 8-step federation transfer validator
-│ ├── Svrn7.Identity/
-│ │ └── VcService.cs W3C VC v2 JWT issue, verify, revoke
-│ ├── Svrn7.DIDComm/
-│ │ ├── DIDCommPacker.cs 5 pack modes + RFC 3394 key wrap + RFC 7748 key conversion
-│ │ └── DIDCommService.cs DIDCommPackingService (high-level facade)
-│ ├── Svrn7.Federation/
-│ │ ├── ISvrn7Driver.cs ISvrn7Driver (41+ members) + Svrn7Options
-│ │ ├── Svrn7Driver.cs Concrete Federation driver
-│ │ └── ServiceCollectionExtensions.cs AddSvrn7Federation() DI registration
-│ └── Svrn7.Society/
-│ ├── ISvrn7SocietyDriver.cs ISvrn7SocietyDriver : ISvrn7Driver
-│ ├── Svrn7SocietyDriver.cs Concrete Society driver
-│ ├── SocietyTransferValidator.cs 8-step Society validator (Step 0: NormaliseDids)
-│ ├── FederationResolvers.cs FederationDidDocumentResolver, FederationVcDocumentResolver
-│ ├── DIDCommServices.cs DIDCommTransferHandler, DIDCommMessageProcessorService
-│ └── SocietyExtensions.cs AddSvrn7Society() DI registration
-└── tests/
- ├── Svrn7.Tests/ 207 federation-level facts, :memory: databases
- └── Svrn7.Society.Tests/ Society citizen registration, DID methods, overdraft
-```
+Internally, the TDA is structured around the PPML Legend 0.25 element types:
----
+| PPML Element | TDA Component | Artefact |
+|-------------------|-----------------------------------------|-------------------------------------|
+| Host | TDA process (Program.cs) | .NET 8 Generic Host + DI |
+| Runspace Pool | RunspacePoolManager | PS RunspacePool + InitialSessionState |
+| PowerShell Runspace | Agent scripts (Agent1, Agent2, AgentN) | .ps1 + Switchboard routing |
+| Switchboard | DIDCommMessageSwitchboard | ConcurrentDictionary protocol registry |
+| LOBE | PowerShell modules (.psm1) | .psm1 + .psd1 + .lobe.json |
+| Data Storage | LiteDB databases | LiteDB context class + IXxxStore |
+| Data Access | Resolvers / caches | IXxxResolver + IMemoryCache |
+| Protocol | Kestrel listener + HttpClient | KestrelListenerService.cs |
+| Network | Internet/LAN/P2P | Transport configuration |
-## 3. Key Design Decisions
+Every component is traceable to a diagram element in DSA 0.24 via a derivation trace comment.
-### Supply Conservation
+---
-Total SVRN7 in circulation at any moment equals exactly `FederationRecord.TotalSupplyGrana`
-minus the Federation wallet balance. No synthetic grana are ever created. The Federation
-wallet is the sole source of all SVRN7.
+## 3. Parchment Programming and Consistent Code Generation
-### Endowment Chain
+This repository is specified and built using **Parchment Programming** (PPML — Parchment
+Programming Modeling Language), a diagram-first methodology in which the DSA 0.24 Epoch 0
+architecture diagram is the primary specification and all code is derived from it. PPML has
+nine core principles (PP-1 through PP-9).
-```
-Federation wallet
- → Society wallet (at Society registration, EndowmentPerSocietyGrana)
- → Citizen wallet (at citizen registration, CitizenEndowmentGrana = 1,000 SVRN7)
+Every source file carries a derivation trace:
+```csharp
+// Derived from: "DIDComm Message Switchboard" — element type Switchboard — DSA 0.24 Epoch 0 (PPML)
```
-All transfers are real UTXO transfers. Supply conservation holds at all times.
+**PP-9 Consistent Code Generation** — the most relevant principle for AI-assisted
+development — states that two independent AI generators given the same conformant diagram
+MUST produce functionally equivalent artefacts. This enables **session independence**: the
+diagram alone, without chat history, is sufficient to regenerate any artefact correctly.
-### UTXO Model
+For the full treatment of PPML implications for software development — including the
+specification artefact inversion, deterministic AI code generation, explicit architectural
+change governance, testability traceability, documentation staleness detection, and
+scalability with AI capability — see:
-All balances are composed of UTXOs. A spent UTXO is immutable — never deleted —
-giving a complete spend graph for independent audit.
+- **`draft-herman-parchment-programming-00`** Section 8.6 — *Implications for Software Development* (normative)
+- **`SVRN7_Architecture_Whitepaper.docx`** Section 2a — *Parchment Programming and Consistent Code Generation*
+- **`Web7_TDA_Design_v024_Consolidated.docx`** Section 11b — *PPML Implications for this Codebase*
+- **`draft-herman-svrn7-ai-legibility-00`** Section 13a — *PPML and AI Legibility* (AI-specific implications)
-### Idempotency
+---
-Cross-Society transfers use `TransferId = Blake3(canonical transfer JSON)` as a nonce.
-A receiving Society that processes the same `TransferId` twice returns the cached receipt
-without double-crediting.
+## 4. Architecture — DSA 0.24 Epoch 0
-### DIDComm-First
+### Deployment Topology
-All transfers flow through DIDComm Authcrypt. Citizens send transfer requests as
-encrypted DIDComm messages. Societies exchange `TransferOrderCredential` and
-`TransferReceiptCredential` VCs via DIDComm. Overdraft draws use the
-`endowment/1.0/overdraft-draw-request` protocol.
+```
++-------------------------------------------------------------+
+| Web 7.0 Federation (ISvrn7Driver) |
+| . Federation wallet — sole source of all SVRN7 SRC |
+| . Global DID method name registry |
+| . Supply governance (monotonically increasing) |
++------------+--------------------+-------------+------------+
+ | DIDComm V2 | |
+ +-------+------+ +-------+------+ +---+----------+
+ | Society A | | Society B | | Society N |
+ | Citizen TDAs| | Citizen TDAs| | Citizen TDAs|
+ +--------------+ +--------------+ +--------------+
+```
+
+Each participant — Federation, Society, and Citizen — operates a TDA. A Society TDA manages
+the monetary layer and registry services. A Citizen TDA manages personal identity,
+communications, and value exchange.
+
+### Solution Structure
+
+```
+Web7-DSA.sln
++-- src/
+| +-- Svrn7.Core/ Models, interfaces, exceptions, TdaResourceId
+| +-- Svrn7.Crypto/ secp256k1, Ed25519, AES-256-GCM, Blake3
+| +-- Svrn7.Store/ LiteDB: 4 database contexts + store implementations
+| +-- Svrn7.Ledger/ RFC 6962 Merkle log, 8-step transfer validator
+| +-- Svrn7.Identity/ W3C VC v2 JWT issuance, verification, revocation
+| +-- Svrn7.DIDComm/ DIDComm V2: 5 pack modes, RFC 3394, X25519
+| +-- Svrn7.Federation/ ISvrn7Driver (44+ members), DI extensions
+| +-- Svrn7.Society/ ISvrn7SocietyDriver, InboxStore, SchemaRegistry
+| +-- Svrn7.TDA/ TDA Host: Kestrel, Switchboard, LobeManager, RunspacePool
++-- lobes/ 11 LOBE modules (.psm1 + .psd1 + .lobe.json) + 3 agent scripts
++-- specs/ 15 IETF Internet-Drafts
++-- docs/ Design documents, whitepaper, principles of operations
++-- tests/
+ +-- Svrn7.Tests/ 94 federation tests
+ +-- Svrn7.Society.Tests/ 11 society tests
+ +-- Svrn7.TDA.Tests/ 62 TDA + LOBE registry tests
+```
+
+### NuGet Package Hierarchy
+
+```
+Svrn7.TDA (deployable runtime — not a NuGet package)
+Svrn7.Society
+ +-- Svrn7.Federation
+ +-- Svrn7.DIDComm
+ +-- Svrn7.Identity
+ +-- Svrn7.Ledger
+ +-- Svrn7.Store
+ +-- Svrn7.Crypto
+ +-- Svrn7.Core (zero dependencies)
+```
---
-## 4. Monetary Model
+## 5. TDA Host Runtime
-### Units
+Derived from: "Citizen/Society TDA (Host)" — element type Host — DSA 0.24 Epoch 0 (PPML).
+
+**Inbound**: `POST /didcomm` (Kestrel HTTP/2 + mTLS)
+→ `KestrelListenerService.UnpackAsync()`
+→ `LiteInboxStore.EnqueueAsync()` — persists to `svrn7-inbox.db`
+→ `DIDCommMessageSwitchboard` — routes by `@type` Locator DID URL
+→ LOBE cmdlet pipeline (PowerShell Runspace)
-| Unit | Value | Note |
-|---|---|---|
-| `grana` | 1 | Smallest unit. All arithmetic uses `long`. |
-| `SVRN7` | 1,000,000 grana | Display denomination only |
+**Outbound**: LOBE returns `OutboundMessage { PeerEndpoint, PackedMessage, MessageType }`
+→ `DIDCommMessageSwitchboard.EnqueueOutbound()`
+→ `HttpClient` HTTP/2 POST to peer TDA endpoint
-### Epochs
+### Message Identity — Pass-by-Reference
-| Epoch | Name | Permitted Transfers |
-|---|---|---|
-| 0 | Endowment | Citizen → own Society wallet or Federation wallet only |
-| 1 | Ecosystem Utility | Any citizen → any citizen in any Society or the Federation |
-| 2 | Market Issuance | Reserved |
+Every inbound message is assigned a TDA resource DID URL at ingestion:
-Epoch advancement requires a Foundation-signed governance operation.
+```
+did:drn:{networkId}/inbox/msg/{objectId}
+```
-### Initial Supply
+Example: `did:drn:alpha.svrn7.net/inbox/msg/5f43a2b1c8e9d7f012345678`
-1,000,000,000 SVRN7 = 10¹⁵ grana. Configured at genesis.
-Additional supply via `UpdateFederationSupplyAsync()` with Foundation signature.
-Supply is monotonically increasing — reduction is architecturally impossible.
+The Switchboard passes this DID URL — not the payload — to the LOBE cmdlet pipeline.
+LOBEs call `$SVRN7.GetMessageAsync($MessageDid)` to resolve the payload on demand.
+This is the pass-by-reference constraint derived from the Data Access arrow in DSA 0.24.
+
+### Dead-Letter Outbox
+
+Failed outbound messages (after Polly retry exhaustion) are persisted to `IOutboxStore`
+(`LiteOutboxStore` in `svrn7-inbox.db`) for operator inspection and replay.
---
-## 5. Identity Model
+## 6. LOBE Registry
-### Hierarchy
+LOBEs (Loadable Object Brain Extensions) are PowerShell modules — the cognitive capability
+layer of the TDA. Every LOBE ships three files:
```
-Federation (1)
- └─ Societies (N) — each with 1..N DID method names
- └─ Citizens (M per Society) — each with 1..N DIDs
+{Name}.psm1 PowerShell module
+{Name}.psd1 PowerShell manifest
+{Name}.lobe.json LOBE descriptor
```
-### Primary DID
+### Standard LOBE Inventory (v0.8.0)
-Every participant has exactly one primary DID. It is the wallet key and cannot be
-deregistered or changed.
+| # | Module | Loading | Protocol families | Role |
+|----|---------------------------|---------|--------------------------|-----------------------------|
+| 1 | `Svrn7.Common` | Eager | — | Shared helpers |
+| 2 | `Svrn7.Federation` | Eager | transfer/1.0/*, did/1.0/*| DID management, key pairs |
+| 3 | `Svrn7.Society` | Eager | transfer/1.0/*, onboard/*| Monetary + identity ops |
+| 4 | `Svrn7.UX` | Eager | ux/1.0/* | UX adapter, balance updates |
+| 5 | `Svrn7.Email` | JIT | email/1.0/* | RFC 5322 over DIDComm |
+| 6 | `Svrn7.Calendar` | JIT | calendar/1.0/* | iCalendar over DIDComm |
+| 7 | `Svrn7.Presence` | JIT | presence/1.0/* | TDA availability status |
+| 8 | `Svrn7.Notifications` | JIT | notification/1.0/* | Typed alert dispatch |
+| 9 | `Svrn7.Onboarding` | JIT | onboard/1.0/* | Citizen registration |
+| 10 | `Svrn7.Invoicing` | JIT | invoice/1.0/* | Invoice-to-payment |
+| 11 | `Svrn7.Identity` | JIT | did/1.0/*, vc/1.0/* | DID Document + VC resolution|
-### Multi-DID Citizens
+**Eager**: pre-loaded into `InitialSessionState` at TDA startup.
+**JIT**: imported on first inbound message of a matching `@type` via `LobeManager.EnsureLoadedAsync()`.
-A citizen can hold additional DIDs under any method name that is currently **Active**
-for their Society. Example — Society Alpha owns `socalpha` and `socalphahealth`:
+### LOBE Descriptor Format
-- `did:socalpha:citizen123` — primary
-- `did:socalphahealth:citizen123` — additional (health context)
+Each `.lobe.json` declares:
+- Protocol URI registrations (`match: "exact"` or `"prefix"`) for Switchboard routing
+- MCP-aligned cmdlet definitions with `inputSchema`/`outputSchema` (JSON Schema 2020-12)
+- Behavioural `annotations` (`idempotent`, `modifiesState`, `destructive`, `pipelinePosition`)
+- `dependencies.lobes` for dependency graph resolution
+- `ai` block (`summary`, `useCases`, `compositionHints`, `limitations`)
-`IIdentityRegistry.ResolveCitizenPrimaryDidAsync(anyDid)` resolves any DID back to
-the citizen's primary DID. The transfer validator calls this in Step 0 (`NormaliseDids`)
-before all other validation steps.
+In a future epoch, the TDA will expose LOBEs as MCP tools via `tools/list` — the descriptor
+becomes the MCP tool definition with no translation needed.
----
+### Dynamic Registration
-## 6. DID Method Names
+`LobeManager` scans all `*.lobe.json` files at startup and watches for new files via
+`FileSystemWatcher`. Third-party LOBEs can be hot-loaded without TDA restart.
-### Lifecycle
+### Pipeline Semantics
+```powershell
+# Example: citizen onboarding pipeline
+Get-TdaMessage -Did $MessageDid |
+ ConvertFrom-TdaOnboardRequest |
+ Register-Svrn7CitizenInSociety |
+ New-TdaOnboardReceipt |
+ Send-TdaMessage
```
-Never existed
- │ RegisterAdditionalDidMethodAsync() [self-service, uniqueness check only]
- ▼
- Active ──────────────── ← any Society re-registers after dormancy expires
- │ DeregisterDidMethodAsync()
- ▼
- Dormant (DormantUntil = DeregisteredAt + DormancyPeriod)
- │ DormantUntil < UtcNow
- ▼
- Available [time-based — no record cleanup required]
- │ RegisterMethodAsync() by any Society
- ▼
- Active (new record; old record retained permanently for audit)
-```
-
-### Rules
-
-- Must match `[a-z0-9]+` per W3C DID spec.
-- Unique across the Federation while Active.
-- Dormancy records are retained permanently — availability evaluated by time comparison.
-- The primary method name (set at Society creation) **cannot** be deregistered.
-- Issued DIDs under a deregistered method name remain fully resolvable — deregistration
- only prevents **new** DID issuance under that name.
-
-### DID Method Exceptions
-
-| Exception | Thrown When |
-|---|---|
-| `DuplicateDidMethodException` | Name currently Active under another Society |
-| `DormantDidMethodException` | Name within its dormancy period |
-| `DeregisteredDidMethodException` | Issuing new DID under deregistered method |
-| `PrimaryDidMethodException` | Attempting to deregister primary method name |
---
-## 7. Transfer Protocol
+## 7. DIDComm V2 Integration
-### 8-Step Validator
+All TDA-to-TDA communication is DIDComm V2, **SignThenEncrypt** default:
-Both `TransferValidator` (Federation) and `SocietyTransferValidator` (Society) run
-these steps in strict order. Failure at any step throws a typed exception.
+| Mode | Algorithm | Use |
+|------------------|------------------------------------|------------------|
+| `Plaintext` | None | Testing only |
+| `Anoncrypt` | ECDH-ES+A256KW / AES-256-GCM | Sender anonymous |
+| `Authcrypt` | ECDH-1PU+A256KW / AES-256-GCM | Authenticated |
+| `SignOnly` | EdDSA (Ed25519) JWS | Attestation |
+| `SignThenEncrypt`| JWS inside Anoncrypt JWE | **Default** |
-| Step | Name | Description |
-|---|---|---|
-| 0 | NormaliseDids | Resolve any DID to canonical primary DID *(Society only)* |
-| 1 | ValidateFields | Non-null, amount > 0, memo ≤ 256 chars |
-| 2 | ValidateEpochRules | Epoch matrix enforcement |
-| 3 | ValidateNonce | 24-hour replay window |
-| 4 | ValidateFreshness | ±10 minute timestamp window |
-| 5 | ValidateSanctions | ISanctionsChecker |
-| 6 | ValidateSignature | secp256k1 CESR over canonical JSON |
-| 7 | ValidateBalance | Dry-run UTXO sum (no spend yet) |
-| 8 | ValidateSocietyMembership | Cross-Society Epoch 1 only: payee must be known citizen |
+### Protocol URI Scheme
-### Cross-Society Transfer Flow (Epoch 1)
+All `@type` URIs are **Locator DID URLs** — not `https://` URIs:
```
-Society A (payer's home) Society B (payee's home)
- │ │
- │ 1. Validate payer (8 steps) │
- │ 2. Debit payer UTXO │
- │ 3. Issue TransferOrderCredential VC │
- │ 4. DIDComm Authcrypt ──────────────────────► │
- │ 5. Unpack │
- │ 6. Validate VC
- │ 7. Credit payee UTXO
- │ 8. Issue TransferReceiptCredential VC
- │ ◄──────────────────────────────── 9. DIDComm receipt
- │ 10. Append settlement to Merkle log │
+did:drn:svrn7.net / protocols / transfer / 1.0 / request
++-----------------+ +----------------------------------+
+Identity DID DID URL path (Locator)
+(protocol namespace)(specific protocol definition)
```
-Atomicity: fire-and-forget + nonce idempotency.
-`TransferId = Blake3(canonical transfer JSON)`.
+The SVRN7 ecosystem is intentionally self-contained. Cross-ecosystem interoperability with
+non-SVRN7 DIDComm agents is not a goal.
---
-## 8. Overdraft Facility
+## 8. SOVRONA (SVRN7) Shared Reserve Currency
-When a Society wallet falls below `CitizenEndowmentGrana` during registration,
-the library automatically requests an overdraft draw from the Federation.
+SVRN7 is the value layer of the Web 7.0 DSA — a Shared Reserve Currency (SRC) embedded
+within the TDA and governed by a three-epoch monetary lifecycle.
-### Draw Flow
+### Units
-```
-RegisterCitizenInSocietyAsync()
- │
- ├─ Balance < CitizenEndowmentGrana?
- │ YES → check: TotalOverdrawnGrana + DrawAmountGrana > OverdraftCeilingGrana?
- │ YES → throw SocietyEndowmentDepletedException
- │ DIDComm OverdraftDrawRequest → Federation
- │ (synchronous, timeout = OverdraftDrawTimeout)
- │ Federation transfers DrawAmountGrana → Society wallet
- │ Federation returns OverdraftDrawReceipt VC
- │ TotalOverdrawnGrana += DrawAmountGrana
- │ LifetimeDrawsGrana += DrawAmountGrana ← never resets
- │
- └─ Continue citizen registration
-```
+| Unit | Value | Note |
+|---------|----------------|--------------------------------|
+| `grana` | 1 | Smallest unit. All math: long. |
+| `SVRN7` | 1,000,000 grana| Display denomination |
-### Overdraft Status
+### Epoch Matrix
-| Status | Condition |
-|---|---|
-| `Clean` | `TotalOverdrawnGrana == 0` |
-| `Overdrawn` | `0 < TotalOverdrawnGrana < OverdraftCeilingGrana` |
-| `Ceiling` | `TotalOverdrawnGrana >= OverdraftCeilingGrana` — registration **blocked** |
+| Epoch | Name | Permitted Transfers |
+|-------|-------------------|--------------------------------------------------|
+| 0 | Endowment | Citizen to own Society or Federation only |
+| 1 | Ecosystem Utility | Any citizen to any citizen across any Society |
+| 2 | Market Issuance | Open-market rules (future) |
-### Federation Top-Up
+### Supply and Endowment Chain
```
-TotalOverdrawnGrana = Max(0, TotalOverdrawnGrana - topUpAmount)
+Federation wallet (1,000,000,000 SVRN7 at genesis)
+ |
+ +-- RegisterSocietyAsync() --> Society wallet (EndowmentPerSocietyGrana)
+ |
+ +-- RegisterCitizenAsync() --> Citizen wallet (1,000 SVRN7)
```
-Overshoot goes to Society operating balance. `TotalOverdrawnGrana` floors at zero.
+Supply conservation is an invariant: total circulating supply always equals
+`FederationRecord.TotalSupplyGrana` minus the Federation wallet balance. No synthetic grana
+are ever created.
----
+### 8-Step Transfer Validator
-## 9. DIDComm v2 Integration
+| Step | Name | Description |
+|------|-------------------------|----------------------------------------------|
+| 0 | NormaliseDids | Resolve any DID to primary DID (Society only)|
+| 1 | ValidateFields | Non-null, amount > 0, memo <= 256 chars |
+| 2 | ValidateEpochRules | Epoch matrix enforcement |
+| 3 | ValidateNonce | 24-hour replay window |
+| 4 | ValidateFreshness | +/-10 minute timestamp window |
+| 5 | ValidateSanctions | ISanctionsChecker |
+| 6 | ValidateSignature | secp256k1 CESR over canonical JSON |
+| 7 | ValidateBalance | Dry-run UTXO sum |
+| 8 | ValidateSocietyMembership | Cross-Society Epoch 1: payee citizenship |
-### Five Pack Modes
+### Four-Database Design
-| Mode | Algorithm | Default Use |
-|---|---|---|
-| `Plaintext` | None | Testing |
-| `Anoncrypt` | ECDH-ES+A256KW / AES-256-GCM | Sender anonymous |
-| `Authcrypt` | ECDH-1PU+A256KW / AES-256-GCM | **All transfers** |
-| `SignOnly` | EdDSA (Ed25519) JWS | Attestation without encryption |
-| `SignThenEncrypt` | JWS inside Anoncrypt JWE | Maximum assurance |
+| Database | Default file | Contents |
+|-----------------|-----------------------|----------------------------------------|
+| `svrn7.db` | `data/svrn7.db` | Wallets, UTXOs, citizens, Merkle log |
+| `svrn7-dids.db` | `data/svrn7-dids.db` | DID Documents, version history |
+| `svrn7-vcs.db` | `data/svrn7-vcs.db` | Verifiable Credentials, revocations |
+| `svrn7-inbox.db`| `data/svrn7-inbox.db` | Inbox queue, Schema Registry, outbox |
-### Cryptographic Details
+All paths accept `:memory:` for zero-disk testing.
-- Ed25519 → X25519: birational map per RFC 7748 §4.1 with scalar clamping.
-- Key wrap: RFC 3394 AES-256.
-- Shared secret expansion: HKDF-SHA-256.
-- Content encryption: AES-256-GCM with 12-byte random nonce, 16-byte tag.
-- CEKs and ephemeral keys zeroed with `Array.Clear()` after use.
-
-### Background Message Processor
-
-`DIDCommMessageProcessorService` runs three loops on `BackgroundSweepInterval`:
+---
-1. VC expiry sweep (`ExpireStaleVcsAsync`)
-2. Merkle tree head auto-sign (`SignMerkleTreeHeadAsync`)
-3. DIDComm inbox dispatch (`IDIDCommTransferHandler`)
+## 9. Identity Model
----
+### Hierarchy
+```
+Federation (1)
+ +-- Societies (N) -- each with 1..N DID method names
+ +-- Citizens (M per Society) -- each with 1..N DIDs
+```
-## 9a. TDA Host and LOBE Registry
+Every participant has exactly one primary DID — the wallet key, immutable.
-The TDA (Trusted Digital Assistant) is a .NET 8 console application (Generic Host + Kestrel HTTP/2 + mTLS) that hosts the PowerShell Runspace Pool, DIDComm Message Switchboard, and all LOBE modules.
+### Identity DID vs Locator DID URL
-### Standard LOBE Inventory (v0.8.0)
+Formalised in `draft-herman-did-w3c-drn-00` Section 5a (W3C DID Core Section 3.2):
-| # | Module | Type | Protocol families | Description |
-|---|---|---|---|---|
-| 1 | `Svrn7.Common.psm1` | Eager | — | Shared helpers, DID URL parsing, logging |
-| 2 | `Svrn7.Federation.psm1` | Eager | transfer/1.0/*, did/1.0/* | DID management, key pairs, base registry |
-| 3 | `Svrn7.Society.psm1` | Eager | transfer/1.0/*, onboard/1.0/* | Monetary + identity operations |
-| 4 | `Svrn7.UX.psm1` | Eager | ux/1.0/* | UX adapter — balance updates, notifications |
-| 5 | `Svrn7.Email.psm1` | JIT | email/1.0/* | RFC 5322 email tunneled over DIDComm |
-| 6 | `Svrn7.Calendar.psm1` | JIT | calendar/1.0/* | iCalendar events and meeting invites |
-| 7 | `Svrn7.Presence.psm1` | JIT | presence/1.0/* | TDA availability status |
-| 8 | `Svrn7.Notifications.psm1` | JIT | notification/1.0/* | Typed alert dispatch |
-| 9 | `Svrn7.Onboarding.psm1` | JIT | onboard/1.0/* | Citizen registration pipeline |
-|10 | `Svrn7.Invoicing.psm1` | JIT | invoice/1.0/* | Invoice-to-payment pipeline |
-|11 | `Svrn7.Identity.psm1` | JIT | did/1.0/*, vc/1.0/* | DID Document + VC resolution |
+| Form | Delimiter | Example | DID Document? |
+|--------------------|-----------|----------------------------------------------|---------------|
+| Identity DID | `:` | `did:drn:alice.alpha.svrn7.net` | Yes |
+| Locator DID URL | `/` | `did:drn:alpha.svrn7.net/inbox/msg/5f43a2...`| No |
-Each LOBE ships a `.lobe.json` descriptor declaring its protocol URI registrations, MCP-aligned `inputSchema`/`outputSchema` on every cmdlet, and AI legibility metadata. The Switchboard uses these descriptors for dynamic routing — no hardcoded routing table.
+Identity DIDs identify subjects. Locator DID URLs address resources. The `:` vs `/` choice
+reflects W3C DID Core structural semantics, made explicit as a design principle.
-### LOBE Loading
+### DID Method Name Lifecycle
-- **Eager**: imported into `InitialSessionState` at TDA startup. Available in every runspace with zero import cost.
-- **JIT**: imported on first inbound message of a matching `@type` via `LobeManager.EnsureLoadedAsync()`. Subsequent calls are no-ops.
+```
+Never existed --> Active --> Dormant (deregistered) --> Available --> Active (re-registered)
+```
-### Dynamic LOBE Registration
+Primary method name cannot be deregistered. Existing DIDs under a deregistered method
+remain resolvable — deregistration only prevents new issuance.
-Third-party LOBEs can be hot-loaded without TDA restart: drop `{Name}.psm1`, `{Name}.psd1`, and `{Name}.lobe.json` into the TDA's LOBE directory. `FileSystemWatcher` detects the descriptor within milliseconds and registers the protocol URIs into the Switchboard.
+---
## 10. Verifiable Credentials
-### Credential Types Issued
+### Credential Types
-| Type | Issuer | Subject | Validity |
-|---|---|---|---|
-| `Svrn7EndowmentCredential` | Society | Citizen | 5 years |
-| `Svrn7SocietyRegistrationCredential` | Federation | Society | Indefinite |
-| `Svrn7EpochCredential` | Federation | Federation | Per epoch |
-| `TransferOrderCredential` | Originating Society | Payee | 24 hours |
-| `TransferReceiptCredential` | Receiving Society | Payer | 24 hours |
+| Type | Issuer | Subject | Validity |
+|-------------------------------------|------------|----------|------------|
+| `Svrn7EndowmentCredential` | Society | Citizen | 5 years |
+| `Svrn7SocietyRegistrationCredential`| Federation | Society | Indefinite |
+| `Svrn7EpochCredential` | Federation | Federation| Per epoch |
+| `TransferOrderCredential` | Orig. Society | Payee | 24 hours |
+| `TransferReceiptCredential` | Recv. Society | Payer | 24 hours |
### Lifecycle
```
-Active
- │ SuspendVcAsync() │ RevokeVcAsync()
- ▼ ▼
-Suspended Revoked (permanent)
- │ ReinstateVcAsync()
- ▼
-Active
-
-Active → Expired (auto-detected on read — no background sweep required)
+Active --> Suspended --> Active (ReinstateVcAsync)
+Active --> Revoked (permanent)
+Active --> Expired (auto-detected on read)
```
-### IVcDocumentResolver — Federation-Level Search
-
-| Method | Description |
-|---|---|
-| `ResolveAsync(vcId)` | Core resolution with status metadata |
-| `FindBySubjectAsync(did, status?)` | All VCs for a subject |
-| `FindByIssuerAsync(did, status?)` | All VCs issued by a DID |
-| `FindByTypeAsync(type, status?)` | All VCs of a given credential type |
-| `FindBySocietyAsync(did, status?)` | All VCs associated with a Society |
-| `FindBySubjectAcrossSocietiesAsync(did, timeout?)` | Cross-Society fan-out with partial-result manifest |
-| `IsValidAsync(vcId)` | Lightweight single-call validity check |
-| `GetStatusBatchAsync(vcIds)` | Batch status check |
-| `FindExpiringAsync(window)` | VCs expiring within given window |
-| `GetRevocationHistoryAsync(subject?, issuer?, since?)` | Filtered revocation history |
-| `GetCountsByTypeAsync()` | Type distribution (for dashboards) |
-| `GetCountsByStatusAsync()` | Status distribution (for dashboards) |
-
-The cross-Society fan-out returns a `CrossSocietyVcQueryResult` containing
-`RespondedSocieties` and `TimedOutSocieties` — partial results are always returned
-rather than blocking on an unresponsive Society.
+Cross-Society VC resolution (`FindBySubjectAcrossSocietiesAsync`) performs a DIDComm
+fan-out to all known Societies, returning partial results when some time out.
---
## 11. Merkle Audit Log
-### Algorithm — RFC 6962
+All significant state changes are appended to an RFC 6962 SHA-256 Merkle log:
```
Leaf: SHA-256(0x00 || data)
Internal: SHA-256(0x01 || left || right)
-Odd node: propagates upward without duplication
```
-### Entry Types
-
-| EntryType | Trigger |
-|---|---|
-| `CitizenRegistration` | RegisterCitizenInSocietyAsync |
-| `SocietyRegistration` | RegisterSocietyAsync |
-| `FederationSupplyUpdate` | UpdateFederationSupplyAsync |
-| `EpochTransition` | AdvanceEpochAuthorisedAsync |
-| `TransferCompleted` | TransferAsync |
-| `CrossSocietyTransferDebit` | TransferToExternalCitizenAsync (originating) |
-| `CrossSocietyTransferCredit` | HandleTransferOrderAsync (receiving) |
-| `CrossSocietyTransferSettled` | HandleTransferReceiptAsync |
-| `DidMethodRegistration` | RegisterAdditionalDidMethodAsync |
-| `DidMethodDeregistration` | DeregisterOwnDidMethodAsync |
-| `VcRevocation` | RevokeVcAsync |
-| `GdprErasure` | ErasePersonAsync |
-
-### Tree Heads
-
-`DIDCommMessageProcessorService` signs a `TreeHead` on every sweep. Tree heads
-contain root hash, tree size, and secp256k1 CESR signature. Accessible via
-`GetLatestTreeHeadAsync()`.
+Entry types include: citizen/society registration, supply updates, epoch transitions,
+transfers (debit/credit/settlement), DID method registration/deregistration, VC revocation,
+GDPR erasure. UTXO records and tree heads are retained permanently — deletion is impossible.
---
@@ -497,28 +465,51 @@ contain root hash, tree size, and secp256k1 CESR signature. Accessible via
`ErasePersonAsync(did, controllerSignature, requestTimestamp)`:
-1. Validates controller signature.
-2. Burns `EncryptedPrivateKeyBase64` to CSPRNG bytes — private key permanently lost.
-3. Nullifies all PII fields on `CitizenRecord`.
-4. Deactivates all DID Documents for the citizen.
-5. Revokes all VCs where citizen is subject.
-6. Appends `GdprErasure` to Merkle log (non-repudiable proof).
-7. UTXO records retained — required for supply conservation audit.
+1. Validates controller signature
+2. Burns `EncryptedPrivateKeyBase64` to CSPRNG bytes — private key permanently lost
+3. Nullifies all PII fields on `CitizenRecord`
+4. Deactivates all DID Documents for the citizen
+5. Revokes all VCs where citizen is subject
+6. Appends `GdprErasure` to Merkle log (non-repudiable proof of erasure)
+7. UTXO records retained — required for supply conservation audit
---
-## 13. Getting Started — Federation
+## 13. Getting Started — TDA Host
+
+The TDA Host (`Svrn7.TDA`) is a deployable .NET 8 console app, not a NuGet package.
-### Install
+```bash
+cd src/Svrn7.TDA
+dotnet run
+```
+
+`appsettings.json`:
+
+```json
+{
+ "Tda": {
+ "SocietyDid": "did:drn:alpha.svrn7.net",
+ "NetworkId": "alpha.svrn7.net",
+ "LobesConfigPath": "lobes/lobes.config.json",
+ "LobeDirectory": "lobes/",
+ "InboxDbPath": "data/svrn7-inbox.db",
+ "HttpPort": 8080,
+ "CertificatePath": "certs/tda.pfx"
+ }
+}
+```
+
+---
+
+## 14. Getting Started — Federation Library
```xml
```
-### Register Services
-
```csharp
-builder.Services.AddSvrn7(opts =>
+builder.Services.AddSvrn7Federation(opts =>
{
opts.FoundationPublicKeyHex = Environment.GetEnvironmentVariable("SVRN7_FOUNDATION_KEY")!;
opts.Svrn7DbPath = "data/svrn7.db";
@@ -527,18 +518,15 @@ builder.Services.AddSvrn7(opts =>
opts.DidMethodName = "web7";
opts.DidMethodDormancyPeriod = TimeSpan.FromDays(30);
});
-```
-
-### Initialise Federation (once at genesis)
-```csharp
+// Genesis (run once)
var driver = app.Services.GetRequiredService();
var keyPair = driver.GenerateSecp256k1KeyPair();
-// Store keyPair.PrivateKeyBytes in HSM — never in config
+// Store keyPair.PrivateKeyBytes in HSM -- never in config
await driver.InitialiseFederationAsync(new InitialiseFederationRequest
{
- Did = "did:web7:federation",
+ Did = "did:web7:foundation",
PublicKeyHex = keyPair.PublicKeyHex,
FederationName = "Web 7.0 Foundation",
PrimaryDidMethodName = "web7",
@@ -547,53 +535,28 @@ await driver.InitialiseFederationAsync(new InitialiseFederationRequest
});
```
-### Register a Society
-
-```csharp
-var societyKey = driver.GenerateSecp256k1KeyPair();
-await driver.RegisterSocietyAsync(new RegisterSocietyRequest
-{
- Did = "did:socalpha:my-society",
- PublicKeyHex = societyKey.PublicKeyHex,
- PrivateKeyBytes = societyKey.PrivateKeyBytes,
- SocietyName = "Alpha Society",
- PrimaryDidMethodName = "socalpha",
- DrawAmountGrana = 100_000 * Svrn7Constants.GranaPerSvrn7,
- OverdraftCeilingGrana = 1_000_000 * Svrn7Constants.GranaPerSvrn7,
-});
-```
-
---
-## 14. Getting Started — Society
-
-### Install
+## 15. Getting Started — Society Library
```xml
```
-### Register Services
-
```csharp
builder.Services.AddSvrn7Society(opts =>
{
opts.SocietyDid = "did:socalpha:my-society";
- opts.FederationDid = "did:web7:federation";
- opts.DidMethodNames = new List { "socalpha" };
+ opts.FederationDid = "did:web7:foundation";
opts.DrawAmountGrana = 100_000 * Svrn7Constants.GranaPerSvrn7;
opts.OverdraftCeilingGrana = 1_000_000 * Svrn7Constants.GranaPerSvrn7;
- opts.OverdraftDrawTimeout = TimeSpan.FromSeconds(30);
opts.SocietyMessagingPrivateKeyEd25519 = societyEd25519PrivKey;
opts.FederationMessagingPublicKeyEd25519 = federationEd25519PubKey;
opts.FederationEndpoint = "https://federation.svrn7.net/didcomm";
});
-```
-
-### Register a Citizen
-```csharp
-var driver = app.Services.GetRequiredService();
+// Register a citizen
+var driver = app.Services.GetRequiredService();
var citizenKey = driver.GenerateSecp256k1KeyPair();
await driver.RegisterCitizenInSocietyAsync(new RegisterCitizenInSocietyRequest
@@ -602,224 +565,185 @@ await driver.RegisterCitizenInSocietyAsync(new RegisterCitizenInSocietyRequest
PublicKeyHex = citizenKey.PublicKeyHex,
PrivateKeyBytes = citizenKey.PrivateKeyBytes,
SocietyDid = "did:socalpha:my-society",
- // PreferredMethodName = null → uses Society's primary method name
});
-// Alice's wallet now contains CitizenEndowmentGrana = 1,000 SVRN7
+// Alice's wallet now contains 1,000 SVRN7 (CitizenEndowmentGrana)
```
-### Register an Additional DID Method Name
-
-```csharp
-// Self-service — uniqueness is the only constraint
-await driver.RegisterOwnAdditionalDidMethodAsync("socalphahealth");
+---
-// Issue Alice an additional DID under the new method
-await driver.AddCitizenDidAsync(
- citizenPrimaryDid: "did:socalpha:citizen-alice",
- additionalDid: "did:socalphahealth:citizen-alice",
- methodName: "socalphahealth");
-```
+## 16. Configuration Reference
-### Cross-Society Transfer (Epoch 1)
+### TdaOptions
-```csharp
-await driver.TransferToExternalCitizenAsync(
- request: transferRequest, // payer is Alice in socalpha
- targetSocietyDid: "did:socbeta:their-society");
-// Debit is immediate; credit async via DIDComm TransferOrderCredential
-```
+| Property | Default | Description |
+|-------------------|-----------------------------|------------------------------------|
+| `SocietyDid` | *(required)* | This TDA's Society DID |
+| `NetworkId` | *(required)* | Network identifier |
+| `LobesConfigPath` | `lobes/lobes.config.json` | LOBE loading manifest path |
+| `LobeDirectory` | `lobes/` | Watched for new .lobe.json files |
+| `InboxDbPath` | `data/svrn7-inbox.db` | LiteDB inbox + schema + outbox |
+| `HttpPort` | `8080` | Kestrel listen port |
-### Deregister a DID Method Name
+### Svrn7Options (Federation / Society)
-```csharp
-// Primary method cannot be deregistered — throws PrimaryDidMethodException
-await driver.DeregisterOwnDidMethodAsync("socalphahealth");
-// Method enters dormancy for DidMethodDormancyPeriod (default 30 days)
-// Existing DIDs under "socalphahealth" remain valid and resolvable
-// New DIDs under "socalphahealth" are blocked (DeregisteredDidMethodException)
-```
+| Property | Default | Description |
+|----------------------------------|----------------|---------------------------------------|
+| `FoundationPublicKeyHex` | *(required)* | Foundation governance secp256k1 key |
+| `Svrn7DbPath` | `data/svrn7.db`| Main LiteDB |
+| `DidsDbPath` | `data/svrn7-dids.db` | DID Document LiteDB |
+| `VcsDbPath` | `data/svrn7-vcs.db` | VC LiteDB |
+| `DidMethodName` | `drn` | Primary DID method name |
+| `DidMethodDormancyPeriod` | `30 days` | Dormancy after deregistration |
+| `BackgroundSweepInterval` | `1 hour` | VC expiry + Merkle sign interval |
---
-## 15. Configuration Reference
-
-### Svrn7Options
-
-| Property | Default | Description |
-|---|---|---|
-| `FoundationPublicKeyHex` | *(required)* | Foundation governance secp256k1 public key |
-| `Svrn7DbPath` | `data/svrn7.db` | Main LiteDB path |
-| `DidsDbPath` | `data/svrn7-dids.db` | DID Document LiteDB path |
-| `VcsDbPath` | `data/svrn7-vcs.db` | VC LiteDB path |
-| `DidMethodName` | `drn` | Primary DID method name for this Federation |
-| `DidMethodDormancyPeriod` | `30 days` | Duration deregistered names are dormant |
-| `BackgroundSweepInterval` | `1 hour` | VC expiry + Merkle sign sweep interval |
-
-### Svrn7SocietyOptions *(extends Svrn7Options)*
-
-| Property | Default | Description |
-|---|---|---|
-| `SocietyDid` | *(required)* | This Society's own DID |
-| `FederationDid` | *(required)* | Federation DID |
-| `DidMethodNames` | *(required, ≥ 1)* | DID method names owned by this Society |
-| `DrawAmountGrana` | 100,000 SVRN7 | Fixed overdraft draw amount per event |
-| `OverdraftCeilingGrana` | 1,000,000 SVRN7 | Maximum accumulated overdraft |
-| `OverdraftDrawTimeout` | `30 seconds` | Federation DIDComm round-trip timeout |
-| `SocietyMessagingPrivateKeyEd25519` | *(required)* | Ed25519 private key for DIDComm |
-| `FederationMessagingPublicKeyEd25519` | *(required)* | Federation Ed25519 public key |
-| `FederationEndpoint` | *(required)* | Federation DIDComm service endpoint URL |
+## 17. DIDComm Protocol URIs
----
-
-## 16. DIDComm Protocol URIs
-
-All SVRN7 DIDComm `@type` URIs are **Locator DID URLs** — `did:drn:svrn7.net/protocols/...` — not `https://` URIs. This is architecturally coherent with the `did:drn` identity model. The SVRN7 ecosystem is intentionally self-contained; cross-ecosystem interoperability with non-SVRN7 DIDComm agents is not a goal.
+All SVRN7 `@type` URIs follow: `did:drn:svrn7.net/protocols/{family}/{version}/{type}`
**Core constants** (`Svrn7Constants.Protocols.*`):
-| Constant | URI |
-|---|---|
-| `TransferRequest` | `did:drn:svrn7.net/protocols/transfer/1.0/request` |
-| `TransferReceipt` | `did:drn:svrn7.net/protocols/transfer/1.0/receipt` |
-| `TransferOrder` | `did:drn:svrn7.net/protocols/transfer/1.0/order` |
-| `TransferOrderReceipt` | `did:drn:svrn7.net/protocols/transfer/1.0/order-receipt` |
-| `OverdraftDrawRequest` | `did:drn:svrn7.net/protocols/endowment/1.0/overdraft-draw-request` |
-| `OverdraftDrawReceipt` | `did:drn:svrn7.net/protocols/endowment/1.0/overdraft-draw-receipt` |
-| `EndowmentTopUp` | `did:drn:svrn7.net/protocols/endowment/1.0/top-up` |
-| `SupplyUpdate` | `did:drn:svrn7.net/protocols/supply/1.0/update` |
-| `DidResolveRequest` | `did:drn:svrn7.net/protocols/did/1.0/resolve-request` |
-| `DidResolveResponse` | `did:drn:svrn7.net/protocols/did/1.0/resolve-response` |
-| `OnboardRequest` | `did:drn:svrn7.net/protocols/onboard/1.0/request` |
-| `OnboardReceipt` | `did:drn:svrn7.net/protocols/onboard/1.0/receipt` |
-| `InvoiceRequest` | `did:drn:svrn7.net/protocols/invoice/1.0/request` |
-| `InvoiceReceipt` | `did:drn:svrn7.net/protocols/invoice/1.0/receipt` |
+| Constant | URI |
+|----------------------|------------------------------------------------------------------------|
+| `TransferRequest` | `did:drn:svrn7.net/protocols/transfer/1.0/request` |
+| `TransferReceipt` | `did:drn:svrn7.net/protocols/transfer/1.0/receipt` |
+| `TransferOrder` | `did:drn:svrn7.net/protocols/transfer/1.0/order` |
+| `TransferOrderReceipt`| `did:drn:svrn7.net/protocols/transfer/1.0/order-receipt` |
+| `OverdraftDrawRequest`| `did:drn:svrn7.net/protocols/endowment/1.0/overdraft-draw-request` |
+| `OverdraftDrawReceipt`| `did:drn:svrn7.net/protocols/endowment/1.0/overdraft-draw-receipt` |
+| `EndowmentTopUp` | `did:drn:svrn7.net/protocols/endowment/1.0/top-up` |
+| `SupplyUpdate` | `did:drn:svrn7.net/protocols/supply/1.0/update` |
+| `DidResolveRequest` | `did:drn:svrn7.net/protocols/did/1.0/resolve-request` |
+| `DidResolveResponse` | `did:drn:svrn7.net/protocols/did/1.0/resolve-response` |
+| `OnboardRequest` | `did:drn:svrn7.net/protocols/onboard/1.0/request` |
+| `OnboardReceipt` | `did:drn:svrn7.net/protocols/onboard/1.0/receipt` |
+| `InvoiceRequest` | `did:drn:svrn7.net/protocols/invoice/1.0/request` |
+| `InvoiceReceipt` | `did:drn:svrn7.net/protocols/invoice/1.0/receipt` |
**LOBE protocol families** (declared in `.lobe.json` descriptors):
-| Family | URI prefix | LOBE |
-|---|---|---|
-| Email | `did:drn:svrn7.net/protocols/email/1.0/` | `Svrn7.Email` |
-| Calendar | `did:drn:svrn7.net/protocols/calendar/1.0/` | `Svrn7.Calendar` |
-| Presence | `did:drn:svrn7.net/protocols/presence/1.0/` | `Svrn7.Presence` |
-| Notification | `did:drn:svrn7.net/protocols/notification/1.0/` | `Svrn7.Notifications` |
-| UX | `did:drn:svrn7.net/protocols/ux/1.0/` | `Svrn7.UX` |
-| DID resolution | `did:drn:svrn7.net/protocols/did/1.0/` | `Svrn7.Identity` |
-| VC resolution | `did:drn:svrn7.net/protocols/vc/1.0/` | `Svrn7.Identity` |
+| Family | URI prefix | LOBE |
+|-----------------|-------------------------------------------------|------------------------|
+| Email | `did:drn:svrn7.net/protocols/email/1.0/` | `Svrn7.Email` |
+| Calendar | `did:drn:svrn7.net/protocols/calendar/1.0/` | `Svrn7.Calendar` |
+| Presence | `did:drn:svrn7.net/protocols/presence/1.0/` | `Svrn7.Presence` |
+| Notification | `did:drn:svrn7.net/protocols/notification/1.0/` | `Svrn7.Notifications` |
+| UX | `did:drn:svrn7.net/protocols/ux/1.0/` | `Svrn7.UX` |
+| DID resolution | `did:drn:svrn7.net/protocols/did/1.0/` | `Svrn7.Identity` |
+| VC resolution | `did:drn:svrn7.net/protocols/vc/1.0/` | `Svrn7.Identity` |
+
+---
+
+## 18. Exception Reference
+
+| Exception | Thrown When |
+|------------------------------------|-------------------------------------------------------|
+| `InsufficientBalanceException` | UTXO sum insufficient for transfer |
+| `EpochViolationException` | Transfer violates current epoch rules |
+| `InvalidDidException` | DID malformed, unresolvable, or deactivated |
+| `NonceReplayException` | Nonce reused within 24-hour window |
+| `StaleTransferException` | Timestamp outside +/-10 minute window |
+| `SanctionedPartyException` | Payer or payee on sanctions list |
+| `SignatureVerificationException` | secp256k1 or Ed25519 signature invalid |
+| `NotFoundException` | Entity not found |
+| `DoubleSpendException` | UTXO already spent |
+| `InvalidCredentialException` | VC invalid, expired, or revoked |
+| `ConfigurationException` | Options missing or invalid |
+| `MerkleIntegrityException` | Merkle log integrity failure |
+| `SocietyEndowmentDepletedException`| Overdraft ceiling reached |
+| `FederationUnavailableException` | DIDComm round-trip to Federation timed out |
+| `DuplicateDidMethodException` | Method name already Active under another Society |
+| `DormantDidMethodException` | Method name within dormancy period |
+| `DeregisteredDidMethodException` | Issuing DID under deregistered method |
+| `PrimaryDidMethodException` | Attempting to deregister primary method |
+| `UnresolvableDidException` | DID method has no registered resolver |
---
-## 17. Exception Reference
-
-| Exception | Thrown When |
-|---|---|
-| `InsufficientBalanceException` | UTXO sum insufficient for transfer |
-| `EpochViolationException` | Transfer violates current epoch rules |
-| `InvalidDidException` | DID malformed, unresolvable, or deactivated |
-| `NonceReplayException` | Nonce reused within 24-hour window |
-| `StaleTransferException` | Timestamp outside ±10 minute window |
-| `SanctionedPartyException` | Payer or payee on sanctions list |
-| `SignatureVerificationException` | secp256k1 or Ed25519 signature invalid |
-| `NotFoundException` | Entity not found |
-| `DoubleSpendException` | UTXO already spent |
-| `InvalidCredentialException` | VC invalid, expired, or revoked |
-| `ConfigurationException` | Options missing or invalid |
-| `MerkleIntegrityException` | Merkle log integrity failure |
-| `SocietyEndowmentDepletedException` | Overdraft ceiling reached — registration blocked |
-| `FederationUnavailableException` | DIDComm round-trip to Federation timed out |
-| `DuplicateDidMethodException` | Method name already Active under another Society |
-| `DormantDidMethodException` | Method name within dormancy period |
-| `DeregisteredDidMethodException` | Issuing DID under deregistered method |
-| `PrimaryDidMethodException` | Attempting to deregister primary method |
-| `UnresolvableDidException` | DID method has no registered resolver |
+## 19. Solution Structure (Detailed)
+
+```
+src/Svrn7.Core/
+ Svrn7Constants.cs Protocol constants, TdaResourceId DID URL builder, epoch values
+ Models.cs All record types: Wallet, Utxo, CitizenRecord, InboxMessage, ...
+ Exceptions.cs 19 typed domain exceptions
+ Interfaces.cs All C# interfaces
+
+src/Svrn7.TDA/
+ Program.cs Entry point -- Generic Host startup
+ TdaHost.cs DI container configuration
+ KestrelListenerService.cs POST /didcomm -- unpack -> persist -> enqueue
+ DIDCommMessageSwitchboard.cs Descriptor-driven routing + Option A transfer idempotency
+ LobeManager.cs RegisterFromDescriptor, EnsureLoadedAsync, FileSystemWatcher
+ LobeRegistration.cs C# model for .lobe.json (MCP-aligned)
+ RunspacePoolManager.cs PS RunspacePool + InitialSessionState
+ Svrn7RunspaceContext.cs $SVRN7 session variable
+ TdaResourceAddress.cs DID URL parser for TDA resource addresses
+```
---
-## 18. Testing
+## 20. Testing
All tests use LiteDB `:memory:` — no disk I/O, no test isolation issues.
```bash
-dotnet test # all tests
-dotnet test tests/Svrn7.Tests/ # federation only
-dotnet test tests/Svrn7.Society.Tests/ # society only
+dotnet test # all 3 projects (167 tests total)
+dotnet test tests/Svrn7.Tests/ # federation (94 tests)
+dotnet test tests/Svrn7.Society.Tests/ # society (11 tests)
+dotnet test tests/Svrn7.TDA.Tests/ # TDA + LOBE registry (62 tests)
dotnet test --collect:"XPlat Code Coverage"
```
-### Test Fixture Pattern
-
-```csharp
-public class MyTests : IAsyncLifetime
-{
- private TestFixture _fx = null!;
- public Task InitializeAsync() { _fx = new TestFixture(); return Task.CompletedTask; }
- public async Task DisposeAsync() => await _fx.DisposeAsync();
-
- [Fact]
- public async Task ShouldRegisterCitizen()
- {
- var key = _fx.Crypto.GenerateSecp256k1KeyPair();
- var result = await _fx.Driver.RegisterCitizenAsync(new RegisterCitizenRequest
- {
- Did = "did:drn:citizen-test",
- PublicKeyHex = key.PublicKeyHex,
- PrivateKeyBytes = key.PrivateKeyBytes,
- });
- result.Success.Should().BeTrue();
- }
-}
-```
+`LobeManagerRegistryTests` covers: `RegisterFromDescriptor` (exact and prefix protocols),
+`TryResolveProtocol` (exact beats prefix, longest-prefix wins), epoch gating, idempotency,
+`FileSystemWatcher` hot-reload, and `IsRegistered`.
---
-## 19. Naming Conventions
+## 21. Naming Conventions
-| Term | Correct | Incorrect |
-|---|---|---|
-| Protocol domain | `svrn7.net` | `svrn7.io` |
-| Resolution process | DID Document Resolution | DID Resolution |
-| Resolver interface | `IDidDocumentResolver` | `IDidResolver` |
-| Local resolver | `LocalDidDocumentResolver` | `LocalDidResolver` |
-| Federation resolver | `FederationDidDocumentResolver` | `FederationDidResolver` |
-| VC resolver | `IVcDocumentResolver` | `IVcResolver` |
-| Smallest monetary unit | `grana` | `micro`, `satoshi` |
-| Primary token | `SVRN7` | `SOVRONA` *(informal only)* |
+| Term | Correct | Incorrect |
+|-----------------------|-------------------------------|-----------------------------|
+| Protocol domain | `svrn7.net` | `svrn7.io` |
+| Resolution process | DID Document Resolution | DID Resolution |
+| Resolver interface | `IDidDocumentResolver` | `IDidResolver` |
+| VC resolver | `IVcDocumentResolver` | `IVcResolver` |
+| Smallest monetary unit| `grana` | `micro`, `satoshi` |
+| Primary token | `SVRN7` | `SOVRONA` (informal only) |
+| DID method | `did:drn` | `did:svrn7` |
+| LOBE loading | Eager / JIT | Always-on / Lazy |
+| PPML element 4 | `Device` | `DEVICE` |
---
-## 20. NuGet Dependencies
-
-| Package | Version | Used In |
-|---|---|---|
-| `LiteDB` | 5.0.21 | Svrn7.Store |
-| `NBitcoin` | 7.0.37 | Svrn7.Crypto, Svrn7.DIDComm |
-| `NSec.Cryptography` | 23.9.0 | Svrn7.Crypto, Svrn7.DIDComm |
-| `Blake3` | 1.3.0 | Svrn7.Crypto |
-| `Konscious.Security.Cryptography.Argon2` | 1.3.1 | Svrn7.Crypto |
-| `Microsoft.Extensions.*` | 8.0.x | Svrn7.Federation, Svrn7.Society |
-| `xunit` | 2.7.0 | Tests |
-| `FluentAssertions` | 6.12.0 | Tests |
+## 22. NuGet Dependencies
+
+| Package | Version | Used In |
+|--------------------------------------------|---------|------------------------------|
+| `LiteDB` | 5.0.21 | Svrn7.Store |
+| `NBitcoin` | 7.0.37 | Svrn7.Crypto, Svrn7.DIDComm |
+| `NSec.Cryptography` | 23.9.0 | Svrn7.Crypto, Svrn7.DIDComm |
+| `Blake3` | 1.3.0 | Svrn7.Crypto |
+| `Konscious.Security.Cryptography.Argon2` | 1.3.1 | Svrn7.Crypto |
+| `Microsoft.Extensions.*` | 8.0.x | Svrn7.Federation, Society, TDA|
+| `Microsoft.AspNetCore.Server.Kestrel` | 2.2.0 | Svrn7.TDA |
+| `System.Management.Automation` | 7.4.6 | Svrn7.TDA |
+| `xunit` | 2.7.0 | Tests |
+| `FluentAssertions` | 6.12.0 | Tests |
---
-## 21. Roadmap
-
-### v0.7.0 — DIDComm Production Hardening
-- Persistent DIDComm inbox (LiteDB queue replaces in-process ConcurrentQueue)
-- Live `FederationDidDocumentResolver` — real DIDComm round-trip to owning Society
-- Live `FederationVcDocumentResolver` — real cross-Society fan-out
-- OTel meters: `svrn7.federation.*` gauges
-- Health checks: `ISvrn7HealthCheck`
-
-### v0.8.0 — LOBE Registry + Architectural Coherence (April 2026)
-- Dynamic LOBE loading via `.lobe.json` descriptors + `FileSystemWatcher` hot-reload
-- Switchboard: hardcoded routing replaced with descriptor-driven dynamic dispatch
-- DIDComm protocol URIs: `https://` → `did:drn:svrn7.net/protocols/...` (Locator DID URLs)
-- PPML Legend 0.25 formally specified in parchment draft; "DEVICE" → "Device"
-- `TdaResourceId` zero-dependency DID URL builder in `Svrn7.Core`
-- `InboxMessage.Id` is now a TDA resource DID URL (not UUID)
-- Schema Registry, dead-letter outbox, nine `.lobe.json` descriptors with MCP-aligned schemas
-- New IETF draft: `draft-herman-drn-resource-addressing-00`
-- Identity DID vs Locator DID URL formalised in `draft-herman-did-w3c-drn-00` Section 5a
+## 23. Roadmap
+
+### v0.8.0 — TDA + LOBE Registry + Architectural Coherence (April 2026) <- *current*
+- TDA Host: Kestrel, Switchboard, LobeManager, RunspacePool fully implemented
+- Dynamic LOBE registry: `.lobe.json` descriptors + `FileSystemWatcher` hot-reload
+- DIDComm protocol URIs: `did:drn:svrn7.net/protocols/...` (Locator DID URLs)
+- PPML Legend 0.25 + PP-9 Consistent Code Generation formalised
+- 11 standard LOBEs with MCP-aligned descriptors
+- 15 IETF Internet-Drafts
### v0.9.0 — Epoch 2 Market Issuance
- Open-market transfer rules
@@ -833,10 +757,30 @@ public class MyTests : IAsyncLifetime
### v1.1.0 — Production Release
- Full cross-Society DIDComm routing table
-- Nonce replay window in LiteDB TTL collection
-- IETF Internet-Draft alignment: `draft-herman-did-drn`, `draft-herman-vtc-proof-sets`
- NuGet publication on nuget.org
---
+## IETF Internet-Drafts
+
+| Draft | Subject |
+|---------------------------------------------|------------------------------------------------|
+| `draft-herman-did-w3c-drn-00` | `did:drn` DID method + Web 7.0 profile |
+| `draft-herman-drn-resource-addressing-00` | TDA Data Storage record addressing |
+| `draft-herman-vtc-proof-sets-01` | Verifiable Trust Circle VC Proof Sets |
+| `draft-herman-didcomm-svrn7-transfer-00` | SVRN7 DIDComm transfer protocol |
+| `draft-herman-svrn7-monetary-protocol-00` | Monetary model and epoch governance |
+| `draft-herman-svrn7-overdraft-protocol-00` | Society overdraft facility |
+| `draft-herman-web7-society-architecture-00` | Society architecture |
+| `draft-herman-web7-merkle-audit-log-00` | RFC 6962 Merkle audit log |
+| `draft-herman-web7-epoch-governance-00` | Epoch transition governance |
+| `draft-herman-did-method-governance-00` | DID method name lifecycle |
+| `draft-herman-svrn7-gdpr-erasure-00` | GDPR erasure in a UTXO system |
+| `draft-herman-svrn7-ai-legibility-00` | AI legibility engineering |
+| `draft-herman-tda-lobe-registry-00` | TDA LOBE descriptor format and registry |
+| `draft-herman-cesr-svrn7-profile-00` | CESR signature profile |
+| `draft-herman-parchment-programming-00` | PPML — Parchment Programming Modeling Language |
+
+---
+
*Web 7.0 Foundation — Bindloss, Alberta, Canada — https://svrn7.net*
diff --git a/Svrn7.sln b/Web7-DSA.sln
similarity index 100%
rename from Svrn7.sln
rename to Web7-DSA.sln
diff --git a/docs/SVRN7_Comprehensive_Prompt.md b/docs/SVRN7_Comprehensive_Prompt.md
index e064ad6..cf71275 100644
--- a/docs/SVRN7_Comprehensive_Prompt.md
+++ b/docs/SVRN7_Comprehensive_Prompt.md
@@ -100,7 +100,7 @@ teams, poker parties, tribes, clans, political parties, and any other form of di
**10 projects (8 src, 2 test). 25 C# files. ~7,427 lines. Zero stubs. Zero TODOs.**
```
-Svrn7.sln
+Web7-DSA.sln
├── src/
│ ├── Svrn7.Core/ — Models, interfaces, exceptions, constants. Zero deps.
│ ├── Svrn7.Crypto/ — secp256k1, Ed25519, AES-256-GCM, Blake3, Base58btc
@@ -693,3 +693,18 @@ Formally defined in draft-herman-parchment-programming-00 Section 5.2.1.
### Conditional Components Criteria examples:
- "Society TDA Only" → Schema Registry, DID Doc Registry, VC Doc Registry (and their resolvers)
- "Epoch 1+" → components activated at epoch transition
+
+## PPML Core Principles (PP-1 through PP-9)
+
+PP-1: Diagram Primacy — diagram is the source of truth; code conforms to diagram.
+PP-2: Legend Formalism — every element type formally defined in the Legend.
+PP-3: Element Instance Unambiguity — every element belongs to exactly one type.
+PP-4: Tractability — every element has an artefact or Gap Register entry.
+PP-5: Change Record — diagram changes precede code changes.
+PP-6: Epoch Stability — Legend frozen within an epoch.
+PP-7: AI Legibility — diagram sufficient for correct AI code generation.
+PP-8: Living Specification — diagram evolves with the system across its lifetime.
+PP-9: Consistent Code Generation — two independent generators given the same conformant
+ diagram MUST produce functionally equivalent artefacts (same interfaces, ownership,
+ dependencies, protocol registrations). Enables session independence: the diagram
+ alone is sufficient to regenerate any artefact without chat history or prior context.
diff --git a/docs/llms.txt b/docs/llms.txt
index f94473c..08bbaeb 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -397,3 +397,18 @@ Elements 7, 8, 10 are Web 7.0 / SVRN7 specific (substitute equivalents for other
Each LOBE ships .psm1 + .psd1 + .lobe.json (MCP-aligned descriptor).
lobes.config.json: eager = [Common, Federation, Society, UX]; jit = [Email, Calendar, Presence, Notifications, Onboarding, Invoicing, Identity]
+
+## PPML Core Principles (PP-1 through PP-9)
+
+PP-1: Diagram Primacy — diagram is the source of truth; code conforms to diagram.
+PP-2: Legend Formalism — every element type formally defined in the Legend.
+PP-3: Element Instance Unambiguity — every element belongs to exactly one type.
+PP-4: Tractability — every element has an artefact or Gap Register entry.
+PP-5: Change Record — diagram changes precede code changes.
+PP-6: Epoch Stability — Legend frozen within an epoch.
+PP-7: AI Legibility — diagram sufficient for correct AI code generation.
+PP-8: Living Specification — diagram evolves with the system across its lifetime.
+PP-9: Consistent Code Generation — two independent generators given the same conformant
+ diagram MUST produce functionally equivalent artefacts (same interfaces, ownership,
+ dependencies, protocol registrations). Enables session independence: the diagram
+ alone is sufficient to regenerate any artefact without chat history or prior context.