From a2dfccdd9ceafba8d5970595172d2840ef02983a Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 14 Jun 2026 21:49:48 -0700 Subject: [PATCH 1/5] docs: add braids and strands roadmap --- docs/BEARING.md | 5 +- docs/design/braids-and-strands-roadmap.md | 316 ++++++++++++++++++++++ 2 files changed, 320 insertions(+), 1 deletion(-) create mode 100644 docs/design/braids-and-strands-roadmap.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 3d158efe..7a30d67d 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -3,7 +3,7 @@ # BEARING -Last updated: 2026-06-03. +Last updated: 2026-06-15. This signpost summarizes current direction. It does not create commitments or replace backlog items, design docs, retros, or CLI status. If it disagrees with @@ -12,6 +12,9 @@ code, the code wins and this file should be corrected. The WARP paper-to-Echo noun map is maintained in `docs/design/warp-optic-implementation-map.md`. +The post-PR #545 strands and braids hardening roadmap is maintained in +`docs/design/braids-and-strands-roadmap.md`. + The feature bar for the eventual `v0.1.0` release is maintained in `docs/design/v0.1.0-release-plan.md`. diff --git a/docs/design/braids-and-strands-roadmap.md b/docs/design/braids-and-strands-roadmap.md new file mode 100644 index 00000000..6f690a98 --- /dev/null +++ b/docs/design/braids-and-strands-roadmap.md @@ -0,0 +1,316 @@ + + + +# Braids And Strands Roadmap + +Status: active roadmap slice. + +Last updated: 2026-06-15. + +## Purpose + +PR #545 moved strands, braid shells, proof envelopes, blinded member references, +and evolving braid logs from concept-level scaffolding into checked +`warp-core` surfaces. The next phase is not a feature grab bag. It is a +hardening sequence that carries the new surfaces from public data shapes into +law-bearing admission APIs, witnessed transitions, stable identity vectors, +and replayable audit tools. + +The destination is: + +```text +Strands are not casually constructed. +Braid membership is historical, append-only, and queryable by coordinate. +Proof and witness claims are typed, bounded, and verifier-shaped. +Sealed membership is privacy-preserving by construction, not by convention. +Replay can show exactly what law admitted, retained, concealed, or rejected. +``` + +## Current Truth + +- `Strand

` carries causal posture as a sealed typestate parameter, while + live registry/runtime posture validation remains the final admission law. +- `Braid::apply` is checked: it rejects invalid lifecycle transitions, + duplicate members, mixed member-reference postures, sequence overflow, empty + settlement frontiers, and empty collapse witnesses. +- `ProofEnvelope::validate_shape` admits replay-trace envelope structure and + public-input binding only. Cryptographic proof kinds remain reserved until + verifier backends exist. +- `BraidShell::assemble_with_proof` binds proof-envelope identity into shell + identity, so proof-bearing and proofless shells do not collide. +- Sealed braid members require secure query material and no longer leak behind + generic member lookup APIs. +- Settlement member blinding has explicit salt input and deterministic default + derivation for reproducible local flows. + +## North Star + +Echo should feel less like a crate full of important structs and more like a +causal operating system with lawful doors: + +| Today | Target | +| ------------------------------- | ---------------------------------------------- | +| Constructing a `Strand` | admitted through posture-aware constructors | +| Creating a `Braid` | emitted as an authority-scoped event | +| Adding a member | witnessed as `MemberWoven` history | +| Settling | admitted as a shared settlement act | +| Attaching proof evidence | carried by verifier-shaped receipts | +| Reading a shell | replayed through an audit optic | +| Sealing a member | backed by authority/capability-local blinding | +| Interpreting retained plurality | governed by named settlement and collapse laws | + +## Execution Order + +### 1. Seal The Constructor Boundary + +Goal: callers should not be able to fabricate law-looking strand values with +public struct literals. + +Work: + +1. Make `Strand

` fields private where possible. +2. Add accessors for read-only public data. +3. Add named constructors or builders for `DynamicPosture`, `Scratch`, + `AuthorOnly`, and `Shared` paths. +4. Keep registry/runtime checks authoritative. +5. Move tests to fixture builders instead of public struct literals. + +Acceptance: + +- External callers cannot set `_marker` or `retention_posture` directly. +- Existing registry and settlement tests still prove stale or forged handles + cannot bypass runtime posture validation. +- Public API docs state that typestate narrows normal construction but does + not replace live admission checks. + +### 2. Type The Error And Transition Vocabulary + +Goal: validation and transition failures should be structured facts, not +stringly diagnostics. + +Work: + +1. Replace `ProofEnvelope::validate_shape(...) -> Result<(), String>` with a + structured `ProofError`. +2. Split malformed replay-trace envelope, public-input mismatch, unsupported + proof kind, and future backend rejection into distinct variants. +3. Replace braid transition action strings with a typed + `BraidTransitionKind`. +4. Preserve stable display text for humans while exposing typed variants to + callers and tests. + +Acceptance: + +- Tests assert exact `ProofError` variants. +- Tests assert exact invalid braid transition kinds. +- No caller depends on parsing error strings for behavior. + +### 3. Lock Digest And Proof Identity With Golden Vectors + +Goal: accidental identity drift should fail loudly and boringly. + +Work: + +1. Add golden vectors for `ProofEnvelope::digest`. +2. Add golden vectors for proofless and proof-bearing `BraidShell` identity. +3. Add vectors for revealed and sealed member references. +4. Keep vector fixtures small, hand-reviewable, and domain-separated. +5. Add a compatibility note for intentional vector changes. + +Acceptance: + +- A formatting-only or field-order refactor cannot silently change shell or + proof identity. +- CI catches digest drift in a targeted test. +- The vector file explains which identities are public compatibility promises + and which are internal E1 scaffolding. + +### 4. Clarify Privacy Posture Around Blinding Salt + +Goal: deterministic defaults must not be mistaken for unlinkability guarantees. + +Work: + +1. Document that the default member blinding salt is deterministic. +2. State that the default salt is not an unlinkability boundary across + independent settlements. +3. Require or strongly route privacy-preserving sealed-member flows through + authority-local, capability-local, or session-local blinding material. +4. Add tests showing caller-supplied salt changes sealed member commitments. + +Acceptance: + +- API docs say the quiet part clearly. +- Privacy-sensitive examples never use the deterministic default as their + privacy boundary. +- Tests distinguish reproducible local defaults from unlinkability-oriented + caller material. + +### 5. Make Braid Membership Historical + +Goal: braid membership changes should be append-only history, not current +state with a log nearby. + +Work: + +1. Promote the append-only braid membership backlog idea into an active design. +2. Treat `BraidEvent` as the source of truth for membership intervals. +3. Add historical membership views by braid coordinate or event sequence. +4. Preserve current membership as a projection. +5. Keep sealed member references lawful at historical coordinates. + +Acceptance: + +- A braid created with `s0` and `s1`, then woven with `s2`, reports `s2` only + at coordinates after the weave event. +- Current membership and historical membership are both deterministic + projections over the same event log. +- Settlement can admit a braid projection without pretending member strands + merged. + +### 6. Add Replay And Audit Optics + +Goal: the architecture should be able to show its work. + +Work: + +1. Add a braid replay surface that explains member verdicts, posture floors, + proof binding, retained support, settlement frontier, and witness posture. +2. Make replay output stable enough for tests and agent inspection. +3. Keep concealed member source chains concealed while reporting the lawful + reason they are concealed. +4. Add lower-mode output suitable for CLI, JSON, and docs examples. + +Acceptance: + +- Given a braid shell digest or event log, Echo can render an audit reading + without hand-inspecting internals. +- Replay distinguishes admitted, retained, concealed, conflicted, obstructed, + and unsupported claims. +- Tests can assert replay facts without depending on ornamental formatting. + +### 7. Name External Witness Receipts + +Goal: the current self-witness should remain honest E1 scaffolding, not become +the permanent witness model by accident. + +Work: + +1. Define `WitnessReceipt`, `WitnessKind`, and a verifier-shaped + `WitnessBackend` boundary. +2. Keep `SelfWitness` as deterministic local/test evidence. +3. Reserve shapes for signed witness, threshold witness, runtime attestation, + replay-trace receipt, ZK verifier receipt, and vector-opening receipt. +4. Bind witness receipt identity into braid shell or retained evidence identity + only through an explicit compatibility rule. + +Acceptance: + +- Docs and APIs distinguish self-witness integrity from independent + attestation. +- Adding a real witness backend does not require changing braid shell member + semantics. +- Unsupported witness kinds fail as typed unsupported-backend outcomes. + +### 8. Build Sealed Membership Capabilities + +Goal: a holder should be able to prove authorized membership for a purpose +without revealing global strand identity or the source chain. + +Work: + +1. Model a purpose-bound sealed membership presentation. +2. Bind presentations to authority domain, braid coordinate, purpose, and + blinding material. +3. Let reviewers or settlement authorities verify membership without learning + more than the aperture permits. +4. Keep revealed-member and sealed-member paths visibly different in API and + replay output. + +Acceptance: + +- A verifier can check "this actor is an authorized member of braid B for + purpose P" without requiring global strand-id revelation. +- Reusing material across independent settlements is either impossible by API + shape or explicitly visible as caller risk. +- Replay records what was proven and what remained sealed. + +### 9. Introduce Named Plurality Laws + +Goal: retained plural strand claims should be interpreted by named law, not +hidden caller policy. + +Work: + +1. Define a registry shape for settlement, collapse, conflict-preserving, + quorum, editorial, and authority laws. +2. Make the law name and version part of the witnessed reading. +3. Attach capability, support, budget, and evidence posture to law execution. +4. Keep application nouns out of Echo core; authored contracts may provide + domain-specific laws through generated adapters. + +Acceptance: + +- A retained braid reading states which law interpreted plurality. +- Two different laws over the same retained support produce distinct witnessed + readings. +- Unsupported or unauthorized law execution yields typed obstruction evidence. + +## Bad-Code Register + +These are not revert-class defects. They are hardening debt that should be +closed before more public APIs depend on the new shapes. + +| Priority | Area | Debt | Recommended next move | +| -------: | ---------------------- | ---------------------------------------- | ------------------------------------ | +| 1 | `Strand

` | public construction weakens typestate | private fields plus fixture builders | +| 2 | `ProofEnvelope` | validation returns strings | structured `ProofError` | +| 3 | digest identity | no golden vectors yet | proof and shell vector fixtures | +| 4 | `Braid::apply` | transition names are strings | typed `BraidTransitionKind` | +| 5 | settlement blinding | deterministic default may be overtrusted | sharper docs and salt-path tests | +| 6 | braid shell witnessing | self-witness is only E1 scaffolding | named witness receipt design | + +## Cool-Idea Queue + +Preserve these without letting them jump the hardening queue. + +| Rank | Idea | Why it matters | +| ---: | ---------------------------- | ----------------------------------------------- | +| 1 | braid replay explorer | forces the model to show its work | +| 2 | append-only membership views | makes braided history actually historical | +| 3 | external witness plugins | opens adversarial and institutional deployment | +| 4 | sealed membership capability | unlocks privacy-preserving authorization proofs | +| 5 | plurality law registry | turns interpretation policy into witnessed law | + +## Sequencing Guardrails + +- Do not implement real ZK or vector-opening verification until the verifier + boundary and golden vectors are in place. +- Do not make self-witness mean independent attestation. +- Do not treat typestate as the only authority; live runtime posture checks + remain final. +- Do not rewrite settlement as merge semantics. Settlement admits history; + it does not pretend braided strands became one published truth. +- Do not let application nouns enter Echo core while adding plurality laws or + replay tools. +- Do not make current braid membership the only queryable shape once event + history exists. + +## Issue Seeds + +Live backlog is GitHub Issues. These are ready to turn into issues when this +roadmap is pulled into execution: + +1. Private `Strand

` construction and fixture builders. +2. Structured `ProofError` and typed braid transition kinds. +3. Golden vectors for proof envelope and braid shell identity. +4. Blinding salt privacy docs and salt-path tests. +5. Append-only braid membership historical views. +6. Braid replay and audit optic. +7. External witness receipt boundary. +8. Purpose-bound sealed membership capability. +9. Named plurality law registry. + +Each issue should carry one executable witness. Design-only issues must state +which later runtime, API, golden-vector, replay, or DIND proof will close the +claim. From 2405e83d46a2fed11c08656928a4e35437173b2e Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 14 Jun 2026 22:31:07 -0700 Subject: [PATCH 2/5] docs: harden braids roadmap sequencing --- docs/design/braids-and-strands-roadmap.md | 468 +++++++++++++++++++--- 1 file changed, 405 insertions(+), 63 deletions(-) diff --git a/docs/design/braids-and-strands-roadmap.md b/docs/design/braids-and-strands-roadmap.md index 6f690a98..88c3467a 100644 --- a/docs/design/braids-and-strands-roadmap.md +++ b/docs/design/braids-and-strands-roadmap.md @@ -3,7 +3,7 @@ # Braids And Strands Roadmap -Status: active roadmap slice. +Status: active hardening roadmap slice. Last updated: 2026-06-15. @@ -16,6 +16,12 @@ hardening sequence that carries the new surfaces from public data shapes into law-bearing admission APIs, witnessed transitions, stable identity vectors, and replayable audit tools. +This roadmap is ordered. Items 1-4 are hardening prerequisites. Items 5-9 MUST +NOT bypass them except for design-only exploration that creates no public +runtime, API, digest, privacy, or witness dependency. + +No law-bearing object is born by accident. + The destination is: ```text @@ -45,7 +51,7 @@ Replay can show exactly what law admitted, retained, concealed, or rejected. ## North Star -Echo should feel less like a crate full of important structs and more like a +Echo must feel less like a crate full of important structs and more like a causal operating system with lawful doors: | Today | Target | @@ -59,12 +65,134 @@ causal operating system with lawful doors: | Sealing a member | backed by authority/capability-local blinding | | Interpreting retained plurality | governed by named settlement and collapse laws | +Every important causal claim must answer: + +1. Who admitted this? +2. Under what authority? +3. With what posture? +4. Bound to what identity? +5. Replayable by whom, revealing how much? + +The vocabulary stays sharp: + +| Term | Meaning | +| ------------------ | -------------------------------------------------------- | +| Struct | Represents a fact. | +| Constructor | Admits a fact through a named door. | +| Witness | Supports a fact with evidence. | +| Replay | Explains a fact from recorded causes. | +| Law | Interprets a fact under named authority and posture. | +| Digest | Preserves the identity of a fact. | +| Admission | Decides whether a claim enters Echo history. | +| Settlement | Admits history; it is not merge semantics. | +| Projection | Materializes one bounded reading from admitted history. | +| Sealed member | Hides member identity behind authorized proof material. | +| Revealed member | Exposes member identity directly. | +| Posture floor | Lowest causal posture the reading can honestly claim. | +| Retained plurality | Preserved multiple claims not collapsed to one fact. | +| Collapse law | Named law that interprets or reduces retained plurality. | + +## Dependency Graph + +This is a dependency chain, not a menu. + +| Item | Depends on | Why | +| -------------------------------- | --------------------------------------- | --------------------------------------------------- | +| Private `Strand

` construction | PR #545 final model | prevents typestate-looking forgery | +| Structured errors | current proof and braid APIs | stops tests and callers from parsing strings | +| Golden vectors | current digest and proof binding | freezes identity semantics | +| Blinding salt docs and tests | current sealed member API | prevents reproducibility from being sold as privacy | +| Historical braid membership | checked `BraidEvent` model | turns event log into source of truth | +| Replay optic | shell identity and historical views | shows lawful reading | +| External witness receipts | golden vectors and typed proof errors | prevents witness model drift | +| Sealed membership capability | blinding docs and historical membership | prevents privacy overclaim | +| Named plurality laws | replay optic and witness boundary | makes interpretation law visible | + +## Ownership Labels + +Each item owns a primary surface so issue triage stays narrow. + +| Item | Surface | +| ---: | ----------------------- | +| 1 | API/runtime | +| 2 | API/testability | +| 3 | digest compatibility | +| 4 | privacy/API | +| 5 | runtime/history | +| 6 | replay/agent inspection | +| 7 | witnessing/API | +| 8 | privacy/capability | +| 9 | law machinery/design | + +## Universal Definition Of Done + +Every issue created from this roadmap MUST include: + +1. One failing regression witness before the fix, unless the issue is + explicitly design-only. +2. One focused implementation change. +3. One stable test, vector, fixture, replay fact, or DIND proof. +4. Documentation when public semantics, privacy posture, digest identity, or + replay output changes. +5. No hidden reliance on parsing display strings. +6. No public constructor that bypasses law-bearing validation. +7. No weakening of live runtime posture or registry checks. +8. No application-domain nouns in Echo core. + +Design-only issues MUST name the later runtime, API, golden-vector, replay, or +DIND witness that closes the claim. + +## Non-Goals + +This roadmap slice does not include: + +- Real ZK backend implementation. +- Application-domain law nouns in Echo core. +- Settlement-as-merge semantics. +- Any promise that deterministic member blinding defaults provide + unlinkability. +- Replacement of runtime admission checks with typestate alone. +- Current-only braid history. +- Self-witness branding as independent attestation. + +## Threat Model Notes + +- Sealed member references hide global strand identity only when blinding + material remains non-public and is not reused across unlinkability domains. +- The deterministic default salt is for reproducibility, not unlinkability. + Privacy-preserving flows MUST provide authority-local, capability-local, or + session-local blinding material. +- Authority-local and capability-local salts are the preferred privacy + boundary. +- Replay MUST reveal what was lawfully proven without revealing concealed + source chains beyond the requested aperture. +- `SelfWitness` means integrity-only local witness unless an external receipt + says otherwise. +- Typestate is a guardrail. Runtime admission is the courthouse. + +## Compatibility Classes + +Golden vectors and replay fixtures MUST mark identity stability explicitly: + +| Class | Rule | +| -------------------------- | ------------------------------------------------------------- | +| Public stable identity | MUST NOT change without migration note and compatibility plan | +| E1 scaffolding identity | Changes require an explicit compatibility note | +| Test-only fixture identity | Carries no compatibility promise beyond the fixture | + +Intentional digest, proof, shell, witness, or replay identity changes MUST +state which compatibility class changed and how callers migrate. + ## Execution Order ### 1. Seal The Constructor Boundary -Goal: callers should not be able to fabricate law-looking strand values with -public struct literals. +Surfaces: API/runtime. + +Depends on: PR #545 final model. + +Goal: callers MUST NOT fabricate law-looking strand values with public struct +literals. Work: @@ -74,6 +202,8 @@ Work: `AuthorOnly`, and `Shared` paths. 4. Keep registry/runtime checks authoritative. 5. Move tests to fixture builders instead of public struct literals. +6. Ensure the public API cannot construct a value whose type-level posture and + runtime retention posture disagree. Acceptance: @@ -82,21 +212,46 @@ Acceptance: cannot bypass runtime posture validation. - Public API docs state that typestate narrows normal construction but does not replace live admission checks. +- Negative tests prove `Strand` cannot be publicly constructed with + `AuthorOnly` retention posture. ### 2. Type The Error And Transition Vocabulary -Goal: validation and transition failures should be structured facts, not +Surfaces: API/testability. + +Depends on: current proof and braid APIs. + +Goal: validation and transition failures MUST be structured facts, not stringly diagnostics. Work: 1. Replace `ProofEnvelope::validate_shape(...) -> Result<(), String>` with a structured `ProofError`. -2. Split malformed replay-trace envelope, public-input mismatch, unsupported - proof kind, and future backend rejection into distinct variants. -3. Replace braid transition action strings with a typed +2. Split malformed replay-trace envelope, empty payload, public-input + mismatch, unsupported proof kind, and future backend rejection into distinct + variants. +3. Reserve this shape: + + ```rust + pub enum ProofError { + UnsupportedKind { kind: ProofKind }, + EmptyPayload, + PublicInputsMismatch { + expected: Hash, + actual: Hash, + }, + MalformedEnvelope, + BackendRejected { + kind: ProofKind, + reason: VerificationFailureCode, + }, + } + ``` + +4. Replace braid transition action strings with a typed `BraidTransitionKind`. -4. Preserve stable display text for humans while exposing typed variants to +5. Preserve stable display text for humans while exposing typed variants to callers and tests. Acceptance: @@ -104,52 +259,80 @@ Acceptance: - Tests assert exact `ProofError` variants. - Tests assert exact invalid braid transition kinds. - No caller depends on parsing error strings for behavior. +- Negative tests prove display text is not the behavior contract. ### 3. Lock Digest And Proof Identity With Golden Vectors -Goal: accidental identity drift should fail loudly and boringly. +Surfaces: digest compatibility. + +Depends on: current digest and proof binding. + +Goal: accidental identity drift MUST fail loudly and boringly. Work: -1. Add golden vectors for `ProofEnvelope::digest`. -2. Add golden vectors for proofless and proof-bearing `BraidShell` identity. -3. Add vectors for revealed and sealed member references. -4. Keep vector fixtures small, hand-reviewable, and domain-separated. -5. Add a compatibility note for intentional vector changes. +1. Add golden vectors for `ProofEnvelope::digest` for replay traces. +2. Add vectors for rejected or unsupported proof-kind shape where applicable. +3. Add golden vectors for proofless and proof-bearing `BraidShell` identity. +4. Add vectors for revealed and sealed `BraidMemberRef` identity. +5. Add vectors proving member blinding salt effect. +6. Keep vector fixtures small, hand-reviewable, and domain-separated. +7. Add a compatibility note for intentional vector changes. Acceptance: - A formatting-only or field-order refactor cannot silently change shell or proof identity. - CI catches digest drift in a targeted test. -- The vector file explains which identities are public compatibility promises - and which are internal E1 scaffolding. +- The vector file marks each identity as public stable, E1 scaffolding, or + test-only fixture. +- Negative tests prove salt changes alter sealed member commitments where + required. ### 4. Clarify Privacy Posture Around Blinding Salt -Goal: deterministic defaults must not be mistaken for unlinkability guarantees. +Surfaces: privacy/API. + +Depends on: current sealed member API and golden vector plan. + +Goal: deterministic defaults MUST NOT be mistaken for unlinkability +guarantees. Work: -1. Document that the default member blinding salt is deterministic. -2. State that the default salt is not an unlinkability boundary across +1. Put this sentence in API docs, examples, and this roadmap: + + ```text + The deterministic default salt is for reproducibility, not unlinkability. + Privacy-preserving flows MUST provide authority-local, capability-local, or + session-local blinding material. + ``` + +2. Document that the default member blinding salt is deterministic. +3. State that the default salt is not an unlinkability boundary across independent settlements. -3. Require or strongly route privacy-preserving sealed-member flows through - authority-local, capability-local, or session-local blinding material. -4. Add tests showing caller-supplied salt changes sealed member commitments. +4. Route privacy-preserving sealed-member flows through authority-local, + capability-local, or session-local blinding material. +5. Add tests showing caller-supplied salt changes sealed member commitments. Acceptance: -- API docs say the quiet part clearly. +- API docs say the deterministic-default risk clearly. - Privacy-sensitive examples never use the deterministic default as their privacy boundary. - Tests distinguish reproducible local defaults from unlinkability-oriented caller material. +- Negative tests or docs examples prove deterministic salt reuse is surfaced as + caller risk. ### 5. Make Braid Membership Historical -Goal: braid membership changes should be append-only history, not current -state with a log nearby. +Surfaces: runtime/history. + +Depends on: checked `BraidEvent` model. + +Goal: braid membership changes MUST be append-only history, not current state +with a log nearby. Work: @@ -158,6 +341,8 @@ Work: 3. Add historical membership views by braid coordinate or event sequence. 4. Preserve current membership as a projection. 5. Keep sealed member references lawful at historical coordinates. +6. Add `braid.diff_membership(from_coordinate, to_coordinate)` as a design + target for replay, UI, and audit. Acceptance: @@ -167,10 +352,18 @@ Acceptance: projections over the same event log. - Settlement can admit a braid projection without pretending member strands merged. +- Negative tests prove a current-only membership projection cannot satisfy a + historical coordinate request. +- Historical membership diff can report added, removed, revealed, and + concealed member changes. ### 6. Add Replay And Audit Optics -Goal: the architecture should be able to show its work. +Surfaces: replay/agent inspection. + +Depends on: shell identity and historical views. + +Goal: the architecture MUST show its work. Work: @@ -180,6 +373,24 @@ Work: 3. Keep concealed member source chains concealed while reporting the lawful reason they are concealed. 4. Add lower-mode output suitable for CLI, JSON, and docs examples. +5. Define a Braid Flight Recorder artifact that records: + + ```text + event log + -> membership projection + -> shell assembly + -> proof binding + -> witness reading + -> replay verdict + ``` + +6. Define a Causal X-Ray CLI target: + + ```text + echo braid inspect + ``` + +7. Add generated audit examples in JSON form. Acceptance: @@ -188,11 +399,43 @@ Acceptance: - Replay distinguishes admitted, retained, concealed, conflicted, obstructed, and unsupported claims. - Tests can assert replay facts without depending on ornamental formatting. +- Replay cannot treat `SelfWitness` as independent attestation. +- Audit examples include warnings such as deterministic blinding salt usage. + +Example future audit output: + +```json +{ + "braid": "bsh1...", + "coordinate": "bc1...", + "members": [ + { + "reference": "sealed", + "verdict": "Plural", + "concealment": "AuthorityScoped" + } + ], + "posture_floor": "AuthorOnly", + "settlement_law": "AllowPluralOverFootprintOverlap", + "proof": { + "kind": "ReplayTrace", + "binding": "Matched" + }, + "witness": { + "kind": "SelfWitness", + "attestation": "IntegrityOnly" + } +} +``` ### 7. Name External Witness Receipts -Goal: the current self-witness should remain honest E1 scaffolding, not become -the permanent witness model by accident. +Surfaces: witnessing/API. + +Depends on: golden vectors and typed proof errors. + +Goal: the current self-witness MUST remain honest E1 scaffolding and MUST NOT +become the permanent witness model by accident. Work: @@ -203,6 +446,18 @@ Work: replay-trace receipt, ZK verifier receipt, and vector-opening receipt. 4. Bind witness receipt identity into braid shell or retained evidence identity only through an explicit compatibility rule. +5. Build a witness backend simulator before real witness backends: + `SelfWitness`, `SignedWitnessFixture`, `ThresholdWitnessFixture`, + `RejectedWitnessFixture`, and `UnsupportedWitnessFixture`. +6. Reserve a migration hook shape: + + ```rust + pub enum CompatibilityRule { + StableV1, + E1Scaffold, + RequiresMigration { from: u32, to: u32 }, + } + ``` Acceptance: @@ -211,10 +466,16 @@ Acceptance: - Adding a real witness backend does not require changing braid shell member semantics. - Unsupported witness kinds fail as typed unsupported-backend outcomes. +- Simulator fixtures harden the boundary before real cryptographic backends + arrive. ### 8. Build Sealed Membership Capabilities -Goal: a holder should be able to prove authorized membership for a purpose +Surfaces: privacy/capability. + +Depends on: blinding docs and historical membership. + +Goal: a holder MUST be able to prove authorized membership for a purpose without revealing global strand identity or the source chain. Work: @@ -226,6 +487,30 @@ Work: more than the aperture permits. 4. Keep revealed-member and sealed-member paths visibly different in API and replay output. +5. Add disclosure budget labels: + + ```rust + pub enum DisclosureBudget { + Public, + AuthorityScoped, + CapabilityScoped, + HolderOnly, + ZeroKnowledge, + } + ``` + +6. Preserve the target token shape: + + ```rust + pub struct SealedMembershipPresentation { + pub braid_coordinate: BraidCoordinate, + pub purpose: PresentationPurpose, + pub authority_domain: AuthorityDomainRef, + pub member_commitment: Hash, + pub proof_or_receipt: MembershipEvidence, + pub disclosure_budget: DisclosureBudget, + } + ``` Acceptance: @@ -234,10 +519,16 @@ Acceptance: - Reusing material across independent settlements is either impossible by API shape or explicitly visible as caller risk. - Replay records what was proven and what remained sealed. +- Replay says not just that a member is sealed, but why and under which + disclosure budget. ### 9. Introduce Named Plurality Laws -Goal: retained plural strand claims should be interpreted by named law, not +Surfaces: law machinery/design. + +Depends on: replay optic and witness boundary. + +Goal: retained plural strand claims MUST be interpreted by named law, not hidden caller policy. Work: @@ -246,8 +537,17 @@ Work: quorum, editorial, and authority laws. 2. Make the law name and version part of the witnessed reading. 3. Attach capability, support, budget, and evidence posture to law execution. -4. Keep application nouns out of Echo core; authored contracts may provide +4. Keep application nouns out of Echo core; authored contracts provide domain-specific laws through generated adapters. +5. Add Law Cards: + + ```text + name = "allow-plural-over-footprint-overlap" + version = 1 + requires = ["support-pins", "frontier-digest", "posture-floor"] + emits = ["PluralArtifact"] + conceals = ["sealed-member-source-chain"] + ``` Acceptance: @@ -255,32 +555,70 @@ Acceptance: - Two different laws over the same retained support produce distinct witnessed readings. - Unsupported or unauthorized law execution yields typed obstruction evidence. +- Law cards are machine-readable without baking application-domain nouns into + Echo core. + +## Required PR Sequence + +Follow-up implementation work MUST be split into small PRs: + +| PR | Scope | +| --- | ------------------------------------------------------ | +| A | Private `Strand

` construction plus fixture builders | +| B | `ProofError` plus `BraidTransitionKind` | +| C | Golden vectors | +| D | Blinding salt docs and tests | +| E | Historical braid membership views | +| F | Replay and audit optic | +| G | `WitnessReceipt` boundary plus simulator fixtures | +| H | Sealed membership capability design | +| I | Named plurality law registry design | + +PRs A-D are the hardening foundation. PRs E-I MUST NOT introduce runtime or +public API dependencies that bypass A-D. + +## Mandatory Negative Capability Tests + +The execution issues MUST include negative witnesses for these claims: + +- Cannot construct `Strand` with `AuthorOnly` retention posture through + public API. +- Cannot parse behavior from `ProofError` display text. +- Cannot silently reuse deterministic salt in a privacy-sensitive example. +- Cannot satisfy a historical membership coordinate with current-only + membership. +- Cannot treat `SelfWitness` as independent attestation. +- Cannot introduce a plurality law without a law name, version, and evidence + posture. ## Bad-Code Register -These are not revert-class defects. They are hardening debt that should be -closed before more public APIs depend on the new shapes. - -| Priority | Area | Debt | Recommended next move | -| -------: | ---------------------- | ---------------------------------------- | ------------------------------------ | -| 1 | `Strand

` | public construction weakens typestate | private fields plus fixture builders | -| 2 | `ProofEnvelope` | validation returns strings | structured `ProofError` | -| 3 | digest identity | no golden vectors yet | proof and shell vector fixtures | -| 4 | `Braid::apply` | transition names are strings | typed `BraidTransitionKind` | -| 5 | settlement blinding | deterministic default may be overtrusted | sharper docs and salt-path tests | -| 6 | braid shell witnessing | self-witness is only E1 scaffolding | named witness receipt design | - -## Cool-Idea Queue - -Preserve these without letting them jump the hardening queue. - -| Rank | Idea | Why it matters | -| ---: | ---------------------------- | ----------------------------------------------- | -| 1 | braid replay explorer | forces the model to show its work | -| 2 | append-only membership views | makes braided history actually historical | -| 3 | external witness plugins | opens adversarial and institutional deployment | -| 4 | sealed membership capability | unlocks privacy-preserving authorization proofs | -| 5 | plurality law registry | turns interpretation policy into witnessed law | +These are not revert-class defects. They are hardening debt that MUST be closed +before more public APIs depend on the new shapes. + +| Priority | Area | Debt | Required next move | +| -------: | ---------------------- | --------------------------------------- | ------------------------------------ | +| 1 | `Strand

` | public construction weakens typestate | private fields plus fixture builders | +| 2 | `ProofEnvelope` | validation returns strings | structured `ProofError` | +| 3 | digest identity | no golden vectors yet | proof and shell vector fixtures | +| 4 | `Braid::apply` | transition names are strings | typed `BraidTransitionKind` | +| 5 | settlement blinding | deterministic default invites overtrust | sharper docs and salt-path tests | +| 6 | braid shell witnessing | self-witness is only E1 scaffolding | named witness receipt design | + +## Cool-Idea Commitments + +These ideas are promoted into the roadmap as ordered extensions. They are +mandatory design targets, but they MUST respect the dependency graph. + +| Rank | Idea | Required placement | +| ---: | ------------------------------------ | ------------------ | +| 1 | Braid Flight Recorder | replay optic | +| 2 | Causal X-Ray CLI | replay optic | +| 3 | Privacy Budget Labels | sealed capability | +| 4 | Law Cards | plurality laws | +| 5 | Witness Backend Simulator | witness receipts | +| 6 | Historical Membership Diff | historical views | +| 7 | Sealed Membership Presentation Token | sealed capability | ## Sequencing Guardrails @@ -295,6 +633,10 @@ Preserve these without letting them jump the hardening queue. replay tools. - Do not make current braid membership the only queryable shape once event history exists. +- Do not implement witness backends before typed proof errors, witness receipt + identity, and simulator fixtures exist. +- Do not implement sealed membership capability before blinding docs, + salt-effect vectors, and historical membership are in place. ## Issue Seeds @@ -305,12 +647,12 @@ roadmap is pulled into execution: 2. Structured `ProofError` and typed braid transition kinds. 3. Golden vectors for proof envelope and braid shell identity. 4. Blinding salt privacy docs and salt-path tests. -5. Append-only braid membership historical views. -6. Braid replay and audit optic. -7. External witness receipt boundary. -8. Purpose-bound sealed membership capability. -9. Named plurality law registry. - -Each issue should carry one executable witness. Design-only issues must state -which later runtime, API, golden-vector, replay, or DIND proof will close the +5. Append-only braid membership historical views and membership diff. +6. Braid replay, Braid Flight Recorder, and Causal X-Ray optic. +7. External witness receipt boundary and witness backend simulator. +8. Purpose-bound sealed membership capability with disclosure budgets. +9. Named plurality law registry with Law Cards. + +Each issue MUST carry one executable witness. Design-only issues MUST state +which later runtime, API, golden-vector, replay, or DIND proof closes the claim. From 707b5d98bbe57ec7eea4bc942b8d6dc02ebaf315 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 14 Jun 2026 22:39:27 -0700 Subject: [PATCH 3/5] docs: finalize braids roadmap adoption edits --- docs/design/braids-and-strands-roadmap.md | 59 +++++++++++++++-------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/docs/design/braids-and-strands-roadmap.md b/docs/design/braids-and-strands-roadmap.md index 88c3467a..1236d711 100644 --- a/docs/design/braids-and-strands-roadmap.md +++ b/docs/design/braids-and-strands-roadmap.md @@ -92,6 +92,12 @@ The vocabulary stays sharp: | Retained plurality | Preserved multiple claims not collapsed to one fact. | | Collapse law | Named law that interprets or reduces retained plurality. | +Claim lifecycle: + +```text +created -> admitted -> projected -> witnessed -> replayed -> interpreted +``` + ## Dependency Graph This is a dependency chain, not a menu. @@ -131,7 +137,8 @@ Every issue created from this roadmap MUST include: 1. One failing regression witness before the fix, unless the issue is explicitly design-only. 2. One focused implementation change. -3. One stable test, vector, fixture, replay fact, or DIND proof. +3. One stable test, vector, fixture, replay fact, or deterministic integration + proof. 4. Documentation when public semantics, privacy posture, digest identity, or replay output changes. 5. No hidden reliance on parsing display strings. @@ -140,7 +147,18 @@ Every issue created from this roadmap MUST include: 8. No application-domain nouns in Echo core. Design-only issues MUST name the later runtime, API, golden-vector, replay, or -DIND witness that closes the claim. +deterministic integration witness that closes the claim. + +## Issue Output Format + +Every execution issue created from this roadmap MUST include: + +1. Invariant being protected. +2. Failing witness. +3. Implementation surface. +4. Compatibility class affected. +5. Acceptance test. +6. Documentation, vector, or replay impact. ## Non-Goals @@ -183,6 +201,9 @@ Golden vectors and replay fixtures MUST mark identity stability explicitly: Intentional digest, proof, shell, witness, or replay identity changes MUST state which compatibility class changed and how callers migrate. +Any public stable identity change MUST include a migration path, a version +bump, or an explicit declaration that no prior stable identity was published. + ## Execution Order ### 1. Seal The Constructor Boundary @@ -346,8 +367,8 @@ Work: Acceptance: -- A braid created with `s0` and `s1`, then woven with `s2`, reports `s2` only - at coordinates after the weave event. +- A braid whose initial interval includes `s0` and `s1`, then later weaves in + `s2`, reports `s2` only at coordinates after the weave event. - Current membership and historical membership are both deterministic projections over the same event log. - Settlement can admit a braid projection without pretending member strands @@ -534,7 +555,7 @@ hidden caller policy. Work: 1. Define a registry shape for settlement, collapse, conflict-preserving, - quorum, editorial, and authority laws. + quorum, authority, and adapter-provided law families. 2. Make the law name and version part of the witnessed reading. 3. Attach capability, support, budget, and evidence posture to law execution. 4. Keep application nouns out of Echo core; authored contracts provide @@ -562,17 +583,17 @@ Acceptance: Follow-up implementation work MUST be split into small PRs: -| PR | Scope | -| --- | ------------------------------------------------------ | -| A | Private `Strand

` construction plus fixture builders | -| B | `ProofError` plus `BraidTransitionKind` | -| C | Golden vectors | -| D | Blinding salt docs and tests | -| E | Historical braid membership views | -| F | Replay and audit optic | -| G | `WitnessReceipt` boundary plus simulator fixtures | -| H | Sealed membership capability design | -| I | Named plurality law registry design | +| PR | Scope | Risk if skipped | +| --- | ------------------------------------------------------ | ------------------------------------------------ | +| A | Private `Strand

` construction plus fixture builders | typestate-looking forgery remains API-shaped | +| B | `ProofError` plus `BraidTransitionKind` | callers parse strings | +| C | Golden vectors | digest drift goes undetected | +| D | Blinding salt docs and tests | reproducibility gets mistaken for privacy | +| E | Historical braid membership views | event history degrades into current-only state | +| F | Replay and audit optic | law-bearing readings remain hard to inspect | +| G | `WitnessReceipt` boundary plus simulator fixtures | self-witness scaffolding becomes permanent model | +| H | Sealed membership capability design | sealed membership turns into privacy theater | +| I | Named plurality law registry design | interpretation policy hides in callers | PRs A-D are the hardening foundation. PRs E-I MUST NOT introduce runtime or public API dependencies that bypass A-D. @@ -605,7 +626,7 @@ before more public APIs depend on the new shapes. | 5 | settlement blinding | deterministic default invites overtrust | sharper docs and salt-path tests | | 6 | braid shell witnessing | self-witness is only E1 scaffolding | named witness receipt design | -## Cool-Idea Commitments +## Promoted Design Targets These ideas are promoted into the roadmap as ordered extensions. They are mandatory design targets, but they MUST respect the dependency graph. @@ -654,5 +675,5 @@ roadmap is pulled into execution: 9. Named plurality law registry with Law Cards. Each issue MUST carry one executable witness. Design-only issues MUST state -which later runtime, API, golden-vector, replay, or DIND proof closes the -claim. +which later runtime, API, golden-vector, replay, or deterministic integration +proof closes the claim. From 1870ebe74f493f4f319055958300b1da7f6689d2 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 14 Jun 2026 22:45:45 -0700 Subject: [PATCH 4/5] docs: polish braid roadmap final wording --- docs/design/braids-and-strands-roadmap.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/design/braids-and-strands-roadmap.md b/docs/design/braids-and-strands-roadmap.md index 1236d711..725b7734 100644 --- a/docs/design/braids-and-strands-roadmap.md +++ b/docs/design/braids-and-strands-roadmap.md @@ -375,7 +375,7 @@ Acceptance: merged. - Negative tests prove a current-only membership projection cannot satisfy a historical coordinate request. -- Historical membership diff can report added, removed, revealed, and +- Historical membership diff can report added, ended, revealed, and concealed member changes. ### 6. Add Replay And Audit Optics @@ -520,7 +520,8 @@ Work: } ``` -6. Preserve the target token shape: +6. Preserve the target token shape. `PresentationPurpose` is a generic + capability purpose, not an application-domain purpose enum: ```rust pub struct SealedMembershipPresentation { From 6411abc8983bce3a5af3dec2787524c98cec0a22 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 14 Jun 2026 22:53:09 -0700 Subject: [PATCH 5/5] docs: add braid hardening goalposts --- docs/BEARING.md | 15 +++- ...-lawful-construction-and-typed-failures.md | 73 ++++++++++++++++++ ...-02-stable-identity-and-privacy-posture.md | 73 ++++++++++++++++++ ...ost-03-historical-membership-and-replay.md | 72 ++++++++++++++++++ ...itness-receipts-and-sealed-capabilities.md | 73 ++++++++++++++++++ .../goalpost-05-named-plurality-laws.md | 70 +++++++++++++++++ docs/design/braids-and-strands-roadmap.md | 75 +++++++++++++++++++ docs/index.md | 7 ++ 8 files changed, 457 insertions(+), 1 deletion(-) create mode 100644 docs/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures.md create mode 100644 docs/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture.md create mode 100644 docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md create mode 100644 docs/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities.md create mode 100644 docs/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws.md diff --git a/docs/BEARING.md b/docs/BEARING.md index 7a30d67d..bfbc5ffb 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -15,6 +15,9 @@ The WARP paper-to-Echo noun map is maintained in The post-PR #545 strands and braids hardening roadmap is maintained in `docs/design/braids-and-strands-roadmap.md`. +Its goalpost design packet is maintained under +`docs/design/braids-and-strands-hardening/`. + The feature bar for the eventual `v0.1.0` release is maintained in `docs/design/v0.1.0-release-plan.md`. @@ -50,12 +53,22 @@ but production Echo code must remain generic. ## Current Bearing +The active architecture hardening focus is the post-PR #545 braids and strands +campaign. Track progress through the goalpost and slice checklist in +`docs/design/braids-and-strands-roadmap.md`. Each goalpost has a focused design +document under `docs/design/braids-and-strands-hardening/`; implementation PRs +must check off slices in the roadmap only when the slice actually lands. + +This hardening campaign does not replace the `v0.1.0` external-app release +gate. It protects the newly landed strand, braid, proof, sealed-member, +identity, witness, and plurality surfaces before more callers depend on them. + Echo has a local witnessed intent pipeline into deterministic execution: application ingress can become witnessed submission history, lawful admission evidence, ticketed runtime ingress, scheduler-owned handler dispatch, receipt correlation, and observable intent outcome. -The current priority is to prove that pipeline with `jedit` as a real external +The release priority remains proving that pipeline with `jedit` as a real external consumer. The in-repo external fixture remains valuable, but it is no longer the `v0.1.0` release gate. Echo is not ready to release until jedit can submit an application-owned contract intent, let a trusted Echo host authorize diff --git a/docs/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures.md b/docs/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures.md new file mode 100644 index 00000000..2ada7622 --- /dev/null +++ b/docs/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures.md @@ -0,0 +1,73 @@ + + + +# Goalpost 1: Lawful Construction And Typed Failures + +Status: planned. + +Roadmap: +[`../braids-and-strands-roadmap.md`](../braids-and-strands-roadmap.md) + +## Decision Summary + +Echo will stop presenting law-bearing strand and braid/proof failures as casual +public data shapes. `Strand

` construction moves behind posture-aware doors, +proof validation reports structured `ProofError` variants, and braid transition +failures report typed transition kinds instead of string action names. + +## Invariant + +No law-looking strand value or transition failure is created by accident. +Typestate narrows ordinary construction, but live registry and runtime posture +checks remain the final admission law. + +## Sponsored Human + +A maintainer wants hard API boundaries around strand posture and braid/proof +failures so future refactors cannot create fake `Shared`-looking values or +parse behavior out of display text. + +## Sponsored Agent + +An agent needs typed constructors, fixture builders, and error variants so it +can write regression tests against behavior without inferring invariants from +public fields or error strings. + +## Scope + +This goalpost includes: + +- private or controlled `Strand

` construction; +- read-only accessors where public data remains needed; +- fixture builders for tests; +- structured `ProofError`; +- typed `BraidTransitionKind`; +- negative tests for forged construction and string parsing. + +## Non-Goals + +This goalpost does not include: + +- changing settlement semantics; +- replacing runtime posture checks with typestate; +- adding real cryptographic proof verification; +- adding historical braid membership views. + +## Slices + +| Slice | Work | Witness | +| ------ | -------------------------------------------------- | ------------------------------------------------ | +| GP1-S1 | Make `Strand

` construction posture-aware | compile-fail or API test for public forgery | +| GP1-S2 | Replace public test construction with fixtures | tests use builders instead of public literals | +| GP1-S3 | Replace proof validation strings with `ProofError` | tests assert exact error variants | +| GP1-S4 | Replace action strings with `BraidTransitionKind` | tests assert exact invalid transition kind | +| GP1-S5 | Add negative capability tests | tests reject forged strands and string contracts | + +## Acceptance + +- External callers cannot set `_marker` or `retention_posture` directly. +- `Strand` cannot be publicly constructed with `AuthorOnly` retention + posture. +- `ProofEnvelope` callers can branch on `ProofError` variants. +- Braid transition failures identify a typed transition kind. +- Display text remains human-facing only. diff --git a/docs/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture.md b/docs/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture.md new file mode 100644 index 00000000..b2787a91 --- /dev/null +++ b/docs/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture.md @@ -0,0 +1,73 @@ + + + +# Goalpost 2: Stable Identity And Privacy Posture + +Status: planned. + +Roadmap: +[`../braids-and-strands-roadmap.md`](../braids-and-strands-roadmap.md) + +## Decision Summary + +Echo will lock the young proof, braid shell, and member reference identity +surfaces with golden vectors before more callers depend on them. The same +goalpost makes deterministic blinding salt semantics explicit so reproducible +local behavior is never mistaken for unlinkability. + +## Invariant + +Digest identity drift is intentional, visible, and compatibility-classed. +Deterministic blinding defaults are reproducibility tools, not privacy +boundaries. + +## Sponsored Human + +A maintainer wants refactors to fail loudly when they change braid shell, +proof, or sealed member identity. + +## Sponsored Agent + +An agent needs hand-reviewable vector fixtures and explicit privacy wording so +it can distinguish stable identity promises from E1 scaffolding and test-only +fixtures. + +## Scope + +This goalpost includes: + +- replay-trace `ProofEnvelope` digest vectors; +- proofless and proof-bearing `BraidShell` vectors; +- revealed and sealed `BraidMemberRef` vectors; +- salt-effect vectors; +- compatibility class labels; +- privacy docs for deterministic and caller-supplied blinding material. + +## Non-Goals + +This goalpost does not include: + +- implementing verifier backends; +- changing shell semantics beyond identity hardening; +- claiming unlinkability from deterministic defaults; +- introducing sealed membership presentation tokens. + +## Slices + +| Slice | Work | Witness | +| ------ | -------------------------------------------- | --------------------------------------- | +| GP2-S1 | Add replay-trace `ProofEnvelope` vectors | vector fixture test | +| GP2-S2 | Add proofless/proof-bearing shell vectors | vector fixture test | +| GP2-S3 | Add revealed/sealed member reference vectors | vector and salt-effect tests | +| GP2-S4 | Mark compatibility classes | fixture metadata or docs assertion | +| GP2-S5 | Document deterministic blinding salt risk | docs/examples plus salt-path regression | + +## Acceptance + +- CI catches digest drift for proof envelopes and braid shells. +- Sealed member reference vectors prove caller-supplied salt changes the + commitment. +- Public stable identity changes require a migration path, version bump, or + declaration that no prior stable identity was published. +- Privacy-sensitive examples never use deterministic defaults as the privacy + boundary. diff --git a/docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md b/docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md new file mode 100644 index 00000000..9ae4c281 --- /dev/null +++ b/docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md @@ -0,0 +1,72 @@ + + + +# Goalpost 3: Historical Membership And Replay + +Status: planned. + +Roadmap: +[`../braids-and-strands-roadmap.md`](../braids-and-strands-roadmap.md) + +## Decision Summary + +Echo will make braid membership historical and replayable. Current membership +becomes one projection over append-only event history, while replay surfaces +explain member verdicts, posture floors, proof binding, retained support, +frontiers, and witness posture. + +## Invariant + +Braid membership changes are append-only history. Current-only views cannot +satisfy historical coordinate requests. + +## Sponsored Human + +A maintainer wants to answer who belonged to a braid at a coordinate without +pretending later members existed in earlier intervals. + +## Sponsored Agent + +An agent needs replay facts and lower-mode output so it can audit braid shell +readings without hand-inspecting internal state. + +## Scope + +This goalpost includes: + +- append-only membership design; +- historical membership views by coordinate or event sequence; +- membership diff facts for added, ended, revealed, and concealed changes; +- replay facts for member verdicts and proof/witness posture; +- Braid Flight Recorder artifact shape; +- Causal X-Ray lower-mode output target. + +## Non-Goals + +This goalpost does not include: + +- settlement-as-merge semantics; +- exposing sealed source chains beyond the requested aperture; +- external witness backend implementation; +- plurality law registry execution. + +## Slices + +| Slice | Work | Witness | +| ------ | --------------------------------------- | ----------------------------------------- | +| GP3-S1 | Promote append-only membership design | accepted design and invariant tests | +| GP3-S2 | Add historical membership views | coordinate-based membership tests | +| GP3-S3 | Add membership diff facts | added/ended/revealed/concealed diff tests | +| GP3-S4 | Add replay/audit facts | stable JSON or fact assertions | +| GP3-S5 | Define recorder and Causal X-Ray output | fixture output and docs example | + +## Acceptance + +- A braid whose initial interval includes `s0` and `s1`, then later weaves in + `s2`, reports `s2` only after the weave coordinate. +- Current membership remains a deterministic projection over the same event + log. +- Replay distinguishes admitted, retained, concealed, conflicted, obstructed, + and unsupported claims. +- `SelfWitness` is displayed as integrity-only unless an external receipt says + otherwise. diff --git a/docs/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities.md b/docs/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities.md new file mode 100644 index 00000000..9ac60011 --- /dev/null +++ b/docs/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities.md @@ -0,0 +1,73 @@ + + + +# Goalpost 4: Witness Receipts And Sealed Capabilities + +Status: planned. + +Roadmap: +[`../braids-and-strands-roadmap.md`](../braids-and-strands-roadmap.md) + +## Decision Summary + +Echo will name the witness receipt boundary before real witness backends +arrive, then design purpose-bound sealed membership presentations on top of +historical membership and explicit privacy posture. + +## Invariant + +Self-witness is local integrity scaffolding, not independent attestation. +Sealed membership proves only the aperture-authorized membership claim for a +purpose and disclosure budget. + +## Sponsored Human + +A maintainer wants witness and sealed membership surfaces that are ready for +real backends without giving current scaffolding stronger semantics than it +has earned. + +## Sponsored Agent + +An agent needs simulator fixtures and disclosure labels so it can test +supported, rejected, and unsupported witness outcomes before cryptographic or +institutional backends exist. + +## Scope + +This goalpost includes: + +- `WitnessReceipt`, `WitnessKind`, and `WitnessBackend`; +- deterministic witness backend simulator fixtures; +- explicit compatibility rules for witness identity; +- purpose-bound sealed membership presentation design; +- generic `PresentationPurpose` capability vocabulary; +- disclosure budget labels; +- replay wording for sealed membership. + +## Non-Goals + +This goalpost does not include: + +- real ZK, threshold, or signature backend implementation; +- domain-specific purpose enums in Echo core; +- sealed membership before historical membership and salt vectors exist; +- treating self-witness as independent attestation. + +## Slices + +| Slice | Work | Witness | +| ------ | --------------------------------------- | -------------------------------------------- | +| GP4-S1 | Define witness receipt boundary | typed unsupported-backend tests | +| GP4-S2 | Add witness simulator fixtures | supported/rejected/unsupported fixture tests | +| GP4-S3 | Bind witness identity by compatibility | compatibility class tests or docs assertions | +| GP4-S4 | Design sealed membership presentation | design doc and capability fixture | +| GP4-S5 | Add disclosure budget labels and replay | replay facts for sealed membership | + +## Acceptance + +- Unsupported witness kinds fail as typed unsupported-backend outcomes. +- Simulator fixtures harden witness behavior before real backends exist. +- `PresentationPurpose` remains a generic capability purpose, not an + application-domain enum. +- Replay records what was proven, what remained sealed, and which disclosure + budget applied. diff --git a/docs/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws.md b/docs/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws.md new file mode 100644 index 00000000..ecbf205d --- /dev/null +++ b/docs/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws.md @@ -0,0 +1,70 @@ + + + +# Goalpost 5: Named Plurality Laws + +Status: planned. + +Roadmap: +[`../braids-and-strands-roadmap.md`](../braids-and-strands-roadmap.md) + +## Decision Summary + +Echo will make retained plurality interpretation explicit through named, +versioned law machinery. Echo core provides the law registry shape and +obstruction posture; adapter-provided law families carry domain-specific +meaning outside core. + +## Invariant + +Retained plural claims are never interpreted by hidden caller policy. A +witnessed reading names the law, law version, evidence posture, and support +used to interpret plurality. + +## Sponsored Human + +A maintainer wants future plurality and collapse behavior to be reviewable as +law, not scattered caller logic. + +## Sponsored Agent + +An agent needs machine-readable Law Cards and typed obstruction evidence so it +can inspect whether a reading was authorized, supported, and produced under +the intended law. + +## Scope + +This goalpost includes: + +- plurality law registry shape; +- Law Cards; +- law name and version binding in witnessed readings; +- adapter-provided law family routing; +- unsupported or unauthorized law obstruction evidence. + +## Non-Goals + +This goalpost does not include: + +- application-domain law nouns in Echo core; +- hiding plurality interpretation inside callers; +- executing laws before replay and witness boundaries exist; +- collapsing braided strands into merge semantics. + +## Slices + +| Slice | Work | Witness | +| ------ | ----------------------------------- | --------------------------------------- | +| GP5-S1 | Define plurality law registry shape | compile/API tests for law registration | +| GP5-S2 | Add machine-readable Law Cards | schema or fixture validation | +| GP5-S3 | Bind law name/version into readings | witnessed reading identity tests | +| GP5-S4 | Route adapter-provided law families | no-app-nouns guard plus adapter fixture | +| GP5-S5 | Add law obstruction evidence | unsupported/unauthorized law tests | + +## Acceptance + +- A retained braid reading states which law interpreted plurality. +- Two laws over the same retained support produce distinct witnessed readings. +- Unsupported or unauthorized law execution yields typed obstruction evidence. +- Echo core keeps application nouns out while allowing adapters to provide + domain-specific law families. diff --git a/docs/design/braids-and-strands-roadmap.md b/docs/design/braids-and-strands-roadmap.md index 725b7734..b90ea6d8 100644 --- a/docs/design/braids-and-strands-roadmap.md +++ b/docs/design/braids-and-strands-roadmap.md @@ -49,6 +49,81 @@ Replay can show exactly what law admitted, retained, concealed, or rejected. - Settlement member blinding has explicit salt input and deterministic default derivation for reproducible local flows. +## Progress Tracker + +Check off a slice only in the PR that implements or lands that slice. Design +approval alone does not complete implementation slices unless the slice is +explicitly design-only. The roadmap stays as the live progress register for +this campaign. + +### Goalpost 1: Lawful Construction And Typed Failures + +Design: +[`goalpost-01-lawful-construction-and-typed-failures.md`](braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures.md) + +- [ ] GP1-S1: Make `Strand

` construction posture-aware and non-forgeable + through public API. +- [ ] GP1-S2: Replace public test construction with fixture builders. +- [ ] GP1-S3: Replace proof validation strings with structured `ProofError`. +- [ ] GP1-S4: Replace braid transition action strings with + `BraidTransitionKind`. +- [ ] GP1-S5: Add negative capability tests for forged strands and display + string parsing. + +### Goalpost 2: Stable Identity And Privacy Posture + +Design: +[`goalpost-02-stable-identity-and-privacy-posture.md`](braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture.md) + +- [ ] GP2-S1: Add golden vectors for replay-trace `ProofEnvelope` identity. +- [ ] GP2-S2: Add proofless and proof-bearing `BraidShell` identity vectors. +- [ ] GP2-S3: Add revealed and sealed `BraidMemberRef` vectors, including salt + effect. +- [ ] GP2-S4: Mark vector compatibility classes and migration/versioning rules. +- [ ] GP2-S5: Document deterministic blinding salt risk in API docs and + privacy-sensitive examples. + +### Goalpost 3: Historical Membership And Replay + +Design: +[`goalpost-03-historical-membership-and-replay.md`](braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md) + +- [ ] GP3-S1: Promote append-only braid membership into an implementation + design. +- [ ] GP3-S2: Add historical membership views by coordinate or event sequence. +- [ ] GP3-S3: Add membership diff facts for added, ended, revealed, and + concealed changes. +- [ ] GP3-S4: Add replay/audit facts for member verdicts, posture floors, + proof binding, retained support, frontier, and witness posture. +- [ ] GP3-S5: Define the Braid Flight Recorder and Causal X-Ray lower-mode + output. + +### Goalpost 4: Witness Receipts And Sealed Capabilities + +Design: +[`goalpost-04-witness-receipts-and-sealed-capabilities.md`](braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities.md) + +- [ ] GP4-S1: Define `WitnessReceipt`, `WitnessKind`, and `WitnessBackend`. +- [ ] GP4-S2: Add deterministic witness simulator fixtures for supported, + rejected, and unsupported outcomes. +- [ ] GP4-S3: Bind witness identity only through explicit compatibility rules. +- [ ] GP4-S4: Design purpose-bound sealed membership presentations. +- [ ] GP4-S5: Add disclosure budget labels and replay wording for sealed + membership. + +### Goalpost 5: Named Plurality Laws + +Design: +[`goalpost-05-named-plurality-laws.md`](braids-and-strands-hardening/goalpost-05-named-plurality-laws.md) + +- [ ] GP5-S1: Define the core plurality law registry shape. +- [ ] GP5-S2: Add machine-readable Law Cards. +- [ ] GP5-S3: Bind law name and version into witnessed readings. +- [ ] GP5-S4: Route adapter-provided law families without application nouns in + Echo core. +- [ ] GP5-S5: Add obstruction evidence for unsupported or unauthorized law + execution. + ## North Star Echo must feel less like a crate full of important structs and more like a diff --git a/docs/index.md b/docs/index.md index 94815f83..84821acf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,6 +12,7 @@ Echo's live documentation centers on the runtime carrier, the retained witnesses - Application contract hosting: [/architecture/application-contract-hosting](/architecture/application-contract-hosting) - Local contract host quickstart: [/quickstart-local-contract-host](/quickstart-local-contract-host) - WARP optic implementation map: [/design/warp-optic-implementation-map](/design/warp-optic-implementation-map) +- Braids and strands hardening roadmap: [/design/braids-and-strands-roadmap](/design/braids-and-strands-roadmap) - Echo v0.1.0 release plan: [/design/v0.1.0-release-plan](/design/v0.1.0-release-plan) - Echo v0.1.0 jedit release gate: [/design/v0.1.0-jedit-release-gate](/design/v0.1.0-jedit-release-gate) - Trusted runtime control history: [/design/trusted-runtime-control-history](/design/trusted-runtime-control-history) @@ -30,6 +31,12 @@ Echo's live documentation centers on the runtime carrier, the retained witnesses ## Settlement And Replay +- Braids and strands hardening roadmap: [/design/braids-and-strands-roadmap](/design/braids-and-strands-roadmap) +- Goalpost 1, lawful construction and typed failures: [/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures](/design/braids-and-strands-hardening/goalpost-01-lawful-construction-and-typed-failures) +- Goalpost 2, stable identity and privacy posture: [/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture](/design/braids-and-strands-hardening/goalpost-02-stable-identity-and-privacy-posture) +- Goalpost 3, historical membership and replay: [/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay](/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay) +- Goalpost 4, witness receipts and sealed capabilities: [/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities](/design/braids-and-strands-hardening/goalpost-04-witness-receipts-and-sealed-capabilities) +- Goalpost 5, named plurality laws: [/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws](/design/braids-and-strands-hardening/goalpost-05-named-plurality-laws) - DPO concurrency litmus: [/spec/SPEC-0003-dpo-concurrency-litmus-v0](/spec/SPEC-0003-dpo-concurrency-litmus-v0) - Rewrite scheduler: [/spec/scheduler-warp-core](/spec/scheduler-warp-core) - Canonical inbox sequencing: [/spec/canonical-inbox-sequencing](/spec/canonical-inbox-sequencing)