From 78a218d62fb2c113d830732a45280eeb4bb3fa02 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:12:34 -0700 Subject: [PATCH 01/11] Add public ENTITY developer portal gateway --- DEVELOPERS.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 DEVELOPERS.md diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 0000000..b10932a --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,148 @@ +# ENTITY Developer Portal + +This page is the public engineering gateway for ENTITY, an open-source project stewarded by **Blackmore Technology Group Limited (BTG)**. + +ENTITY is designed so that protocol conformance, verification and interoperability can be reproduced outside BTG-controlled infrastructure. BTG stewardship of the public project does not convert BTG hosting, storage, routing or software distribution into sovereign authority over conforming Entity identities or data. + +## Start by objective + +| Goal | Start here | +| --- | --- | +| Understand ENTITY in 10 minutes | [START_HERE.md](START_HERE.md) | +| Run the reference implementation | [README.md](README.md#quick-start) | +| Inspect public engineering evidence | [docs/ENGINEERING_EVIDENCE.md](docs/ENGINEERING_EVIDENCE.md) | +| Understand architecture decisions | [docs/architecture/README.md](docs/architecture/README.md) | +| Review project governance | [GOVERNANCE.md](GOVERNANCE.md) | +| Understand release discipline | [docs/governance/RELEASE_POLICY.md](docs/governance/RELEASE_POLICY.md) | +| Contribute code or documentation | [CONTRIBUTING.md](CONTRIBUTING.md) | +| Find bounded starter work | [Open contributor tasks](https://github.com/blackmore-technology-group/ENTITY/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) | +| Attempt independent interoperability | [docs/INTEROPERABILITY_CHALLENGE.md](docs/INTEROPERABILITY_CHALLENGE.md) | +| Check interoperability status | [docs/interoperability/STATUS.md](docs/interoperability/STATUS.md) | +| Report a vulnerability | [SECURITY.md](SECURITY.md) | +| Review the external security-review program | [docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md](docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md) | +| Read technical notes | [docs/papers/README.md](docs/papers/README.md) | +| See how contributors are recognized | [docs/community/CONTRIBUTOR_RECOGNITION.md](docs/community/CONTRIBUTOR_RECOGNITION.md) | +| Discuss engineering questions | [GitHub Discussions](https://github.com/blackmore-technology-group/ENTITY/discussions) | + +## Current protected release + +**ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality** + +Protected release commit: + +`9c79f987207592cb6791e1a8956f23351cdfb2d3` + +Public qualification evidence includes: + +- complete regression: **144/144 PASS**; +- targeted v3.3 suite: **16/16 PASS**; +- sealed v3.3 reality vectors: **20/20 PASS** — 10 valid / 10 invalid; +- canonical sealed kit SHA-256: `f8b39ee01fb7346f33a57530e925b545d2bf9a770c7ec60724e28a4971d55a46`; +- deterministic result SHA-256: `82bd1f1fb328edd37a26d8ea60ede5a599c7d9af5027bffd73b9e52843b5a51d`. + +These results are BTG-controlled engineering evidence. They are **not** described as unrelated third-party validation. + +## Engineering tracks + +### 1. Reproduction and portability + +Best for engineers who want to evaluate the project without implementing the protocol. + +Typical work: + +- reproduce the release on Linux or macOS; +- validate sealed vectors; +- identify machine-specific assumptions; +- benchmark verification; +- improve onboarding and diagnostics. + +### 2. Specification and architecture review + +Best for protocol, security, identity, distributed-systems and data-rights engineers. + +Typical work: + +- identify ambiguous semantics; +- challenge authority transitions; +- review canonicalization and signature boundaries; +- produce counterexamples; +- review evidence, attestation, recovery and portability semantics. + +### 3. Independent implementation + +Best for unrelated developers or organizations who want to test whether ENTITY semantics are reproducible from public material alone. + +Independent implementations own their own: + +- architecture; +- libraries; +- code structure; +- testing strategy; +- repository; +- qualification evidence. + +BTG-controlled Rust, TypeScript, C#, Go, Swift and Java implementations are reproducibility baselines, **not independent implementations**. + +### 4. Live interoperability + +This track begins after an independently authored implementation can classify the public vectors correctly. + +The target progression is: + +`sealed material → independent implementation → vector conformance → reproducible CI → bidirectional live interoperability → sovereign export/recovery survival → independently authored evidence` + +Partial results are published as partial results. A failed vector, ambiguity or non-interoperable result is useful evidence and must not be upgraded into a success claim. + +### 5. Security research + +Security research should focus on concrete boundaries such as: + +- cryptographic misuse; +- signature/canonicalization ambiguity; +- authority escalation; +- provider capture; +- recovery or portability failure; +- evidence/attestation confusion; +- external-anchor substitution; +- rights/usage/settlement authorization flaws. + +Use private vulnerability reporting for exploitable findings. Public architectural criticism and non-sensitive counterexamples are welcome in issues or Discussions. + +## Public engineering principles + +ENTITY development follows several rules that contributors should be able to audit: + +1. **Evidence before claims.** Qualification artifacts and exact hashes are published separately from marketing language. +2. **No silent authority transfer.** Hosting, storage, routing, discovery and custody do not become sovereign authority merely because an infrastructure provider performs them. +3. **No silent semantic rewrite.** Historical signed state is superseded or migrated explicitly rather than reinterpreted under new rules. +4. **Independent evidence stays independent.** BTG-controlled testing is never relabeled as third-party validation. +5. **Protocol versions are reviewable public targets.** Conformance should be possible from public specifications, schemas, vectors and reproducible tooling. +6. **External-world claims remain contestable.** Cryptographic validity, protocol validity and evidence supporting a claim are separate questions. +7. **Useful failures are publishable results.** Reproducible failures, counterexamples and ambiguities improve the protocol. + +## Contribution lifecycle + +A typical contribution moves through: + +`issue/discussion → bounded proposal → implementation or evidence → pull request → automated checks → review → merge → release qualification where applicable` + +Changes that affect identity, authority, signature meaning, provider independence, recovery, portability, evidence semantics or wire compatibility receive architecture/governance review in addition to ordinary code review. + +See [GOVERNANCE.md](GOVERNANCE.md) and [docs/governance/RELEASE_POLICY.md](docs/governance/RELEASE_POLICY.md). + +## Corporate stewardship and project independence + +Blackmore Technology Group Limited currently stewards ENTITY's specifications, reference implementation, release process and official public repositories. + +That stewardship is intentionally separated from protocol sovereignty. A conforming published ENTITY version is not intended to require BTG hosting, BTG DNS, a BTG resolver, a mandatory BTG cloud service or paid permission to use the protocol. + +The strongest long-term evidence for that boundary is external reproduction and interoperability by parties BTG does not control. + +## Where to participate + +- [Issues](https://github.com/blackmore-technology-group/ENTITY/issues) — bounded engineering work, defects, portability findings and specification questions. +- [Discussions](https://github.com/blackmore-technology-group/ENTITY/discussions) — architecture, design review, implementation questions and broader engineering discussion. +- [Pull requests](https://github.com/blackmore-technology-group/ENTITY/pulls) — code, documentation and reproducible evidence. +- [Releases](https://github.com/blackmore-technology-group/ENTITY/releases) — protected public release artifacts and release notes. + +If you are evaluating ENTITY for the first time, start with [START_HERE.md](START_HERE.md), then choose one bounded task before attempting a complete implementation. From 37839798d03bbd5eaaf652e683643b49c07e2bb0 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:13:01 -0700 Subject: [PATCH 02/11] Document evidence-gated ENTITY release policy --- docs/governance/RELEASE_POLICY.md | 112 ++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/governance/RELEASE_POLICY.md diff --git a/docs/governance/RELEASE_POLICY.md b/docs/governance/RELEASE_POLICY.md new file mode 100644 index 0000000..809db57 --- /dev/null +++ b/docs/governance/RELEASE_POLICY.md @@ -0,0 +1,112 @@ +# ENTITY Release Policy + +This document defines the public release discipline for ENTITY. + +ENTITY does not use a calendar promise as evidence of readiness. Releases are **evidence-gated**: a version is published when its scoped engineering, compatibility review and qualification evidence are complete enough to support the claims made for that version. + +## Release classes + +ENTITY uses semantic versioning as a public coordination convention: + +- **PATCH** — implementation fixes, documentation corrections, tooling improvements or other changes intended to preserve published semantics and compatibility. +- **MINOR** — additive protocol/reference capabilities that preserve the stated compatibility boundary of the release line. +- **MAJOR** — changes that intentionally alter compatibility, controlling semantics or public protocol assumptions in a way that cannot be treated as an additive extension. + +A version number does not override the actual protocol documents, manifests, release notes or qualification evidence. Where a frozen protocol target exists, its freeze/governance material controls that target. + +## Evidence gate + +A release candidate is not promoted solely because code compiles or unit tests pass. The release owner should establish, as applicable: + +1. scoped requirements are identified; +2. regression tests pass; +3. targeted tests for the release feature set pass; +4. schemas/vectors/manifests are internally consistent; +5. reproducibility or sealed-kit hashes are recorded where applicable; +6. security-sensitive changes receive explicit review; +7. provider-independence and sovereignty invariants remain intact; +8. release notes describe both added capability and claim boundaries; +9. protected-branch checks pass; +10. the final release commit/tag is identified and preserved. + +Some releases may require additional gates, including interoperability, migration, recovery, compatibility or performance qualification. + +## Release evidence record + +Each protected release should publish enough information for an external engineer to identify what was actually qualified. Depending on release scope, this may include: + +- protected release commit; +- release manifest; +- exact test counts; +- vector counts; +- deterministic result hashes; +- sealed-kit hashes; +- schema hashes; +- overlay/snapshot hashes; +- CI status; +- known limitations; +- explicit external milestones that remain pending. + +The public release note must distinguish BTG-controlled engineering evidence from independent third-party evidence. + +## Claim discipline + +The release process must not silently convert any of the following into stronger claims: + +- a passing BTG-controlled test into independent validation; +- cryptographic validity into proof that an external-world claim is true; +- protocol validity into legal recognition; +- implemented market machinery into demonstrated market liquidity; +- a controlled clean-room exercise into unrelated external interoperability; +- an internal red-team result into an independent security review. + +When an external milestone is pending, the release record should say so. + +## Security-sensitive release changes + +Changes affecting any of the following require explicit security/governance consideration before release: + +- signing or canonicalization; +- root identity or authority; +- delegation/revocation; +- recovery or migration; +- provider independence; +- evidence/attestation semantics; +- external anchors; +- rights, entitlement, usage or settlement authorization; +- backward interpretation of signed historical state. + +A security fix that changes published semantics may require a new protocol/version boundary rather than an implementation-only patch. + +## Historical integrity + +Released evidence is not rewritten merely to make later presentation cleaner. + +If a signed/sealed historical kit contains a document that later appears dated or cosmetically imperfect, the preferred options are: + +- publish an external clarification; +- publish an erratum where governance permits; +- issue a new release/version when semantics or target material genuinely change. + +Do not weaken a verifier, rewrite a signed manifest or silently reseal historical evidence solely for presentation. + +## Release cadence + +ENTITY has **no fixed public release calendar**. The practical cadence is: + +- development may proceed continuously on protected branches and reviewed pull requests; +- patch releases may occur when a bounded fix is qualified; +- minor/major releases occur after scoped engineering and qualification evidence are complete; +- security releases may be accelerated while still preserving evidence and governance requirements. + +This policy is intended to keep public version numbers tied to engineering evidence rather than marketing deadlines. + +## Current release + +As of 2026-09-24, the current protected release is **ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality**. + +Protected release commit: + +`9c79f987207592cb6791e1a8956f23351cdfb2d3` + +See [ROADMAP.md](../../ROADMAP.md), [docs/ENGINEERING_EVIDENCE.md](../ENGINEERING_EVIDENCE.md) and the [GitHub Releases](https://github.com/blackmore-technology-group/ENTITY/releases) page for current evidence and open external milestones. From 26267b7437861c89da10d501c7980425f9a6a33d Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:13:23 -0700 Subject: [PATCH 03/11] Add contributor recognition policy --- docs/community/CONTRIBUTOR_RECOGNITION.md | 83 +++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/community/CONTRIBUTOR_RECOGNITION.md diff --git a/docs/community/CONTRIBUTOR_RECOGNITION.md b/docs/community/CONTRIBUTOR_RECOGNITION.md new file mode 100644 index 0000000..eda16aa --- /dev/null +++ b/docs/community/CONTRIBUTOR_RECOGNITION.md @@ -0,0 +1,83 @@ +# ENTITY Contributor Recognition + +ENTITY is an open-source engineering project stewarded by Blackmore Technology Group Limited. Contributions should be recognized according to the work actually performed, without converting participation into claims of endorsement, employment, independent validation or authorship beyond the contribution itself. + +## What counts as a contribution + +Useful contributions include more than merged production code. ENTITY recognizes, where attributable and appropriate: + +- code and tests; +- documentation; +- reproducible bug reports; +- portability findings; +- specification ambiguities; +- counterexamples; +- security findings handled through the appropriate disclosure path; +- benchmark evidence; +- clean-room implementations; +- interoperability evidence; +- issue triage and review; +- architecture/design analysis; +- examples and onboarding improvements. + +A reproducible failure can be as valuable as a passing result. + +## Recognition surfaces + +Depending on the contribution, recognition may appear in one or more of: + +- Git commit and pull-request history; +- issue/discussion history; +- release notes; +- a release evidence record; +- interoperability status records; +- repository acknowledgements; +- a future contributors/maintainers roster if sustained project participation develops. + +Recognition should link to public evidence when possible rather than relying on an unsupported attribution statement. + +## Independent contributors and organizations + +When an unrelated engineer or organization produces independent implementation or interoperability evidence, ENTITY will distinguish that work from BTG-controlled engineering. + +BTG will not describe an external party's work as independent unless the relationship and implementation conditions actually support that description. + +Likewise, participation in an issue, discussion, pull request or test does not imply that the contributor: + +- endorses ENTITY generally; +- endorses Blackmore Technology Group Limited; +- accepts every project claim; +- provides a legal, regulatory, audit or certification opinion; +- has independently validated areas they did not test. + +## Controlled implementation credit + +BTG-controlled clean-room or cross-language implementations are credited as BTG-controlled reproducibility work. They are not presented as unrelated third-party validation even if different languages, repositories, teams or implementation techniques are used. + +## Security researcher recognition + +Security researchers may choose public attribution after coordinated disclosure when publication is safe. Anonymous or private credit requests should be respected when operationally possible. + +Security reports should use the process in [SECURITY.md](../../SECURITY.md). Do not place exploitable details, private keys, credentials or affected private data into public recognition records. + +## Release acknowledgement criteria + +A contributor may be acknowledged in release notes when their work materially affects that release, for example by: + +- authoring a merged change; +- identifying a defect fixed in the release; +- producing a reproducible conformance or portability result referenced by the release; +- contributing a security finding that was remediated; +- producing an external implementation/interoperability result relevant to the release evidence. + +Acknowledgement should be factual and scoped. It should not overstate the person's role. + +## Maintainer status + +Contributor recognition is not the same as maintainer authority. + +If the project later assigns formal maintainer roles, those roles should be documented separately with explicit scopes, review powers, security responsibilities and governance boundaries. + +## Corrections + +If contributor attribution is inaccurate, incomplete or unwanted, open a documentation issue or contact BTG through an appropriate private channel when privacy or security is involved. Public records such as Git commit authorship remain governed by the underlying Git/GitHub history, but project-authored recognition material can be corrected in a later commit. From c297e755ebae1d2ba04d539e994c856187df0e5f Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:13:44 -0700 Subject: [PATCH 04/11] Add public interoperability status scoreboard --- docs/interoperability/STATUS.md | 92 +++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/interoperability/STATUS.md diff --git a/docs/interoperability/STATUS.md b/docs/interoperability/STATUS.md new file mode 100644 index 0000000..030b944 --- /dev/null +++ b/docs/interoperability/STATUS.md @@ -0,0 +1,92 @@ +# ENTITY Interoperability Status + +This page is the public status board for reproducibility, conformance and interoperability evidence. + +It is intentionally conservative: a repository, implementation or test is listed only for the evidence it actually demonstrates. Controlled implementations are not promoted into independent validation merely because they are written in different languages. + +## Status vocabulary + +- **PASS** — the stated test/evidence requirement was completed successfully. +- **PARTIAL** — useful evidence exists, but the stated end-to-end milestone is incomplete. +- **PENDING** — no qualifying public result has yet been recorded. +- **FAILED / COUNTEREXAMPLE** — a reproducible result demonstrates non-conformance, ambiguity or failure. This is useful evidence and should remain visible until resolved or superseded. + +## Current release evidence + +Release: **ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality** + +Protected release commit: + +`9c79f987207592cb6791e1a8956f23351cdfb2d3` + +Canonical v3.3 sealed kit SHA-256: + +`f8b39ee01fb7346f33a57530e925b545d2bf9a770c7ec60724e28a4971d55a46` + +Deterministic v3.3 result SHA-256: + +`82bd1f1fb328edd37a26d8ea60ede5a599c7d9af5027bffd73b9e52843b5a51d` + +## BTG-controlled cross-language reproducibility baselines + +These implementations are controlled by Blackmore Technology Group Limited. They demonstrate cross-language reproducibility against the stated public vector target, but **do not constitute unrelated external validation**. + +| Implementation | Control | v3.3 vector target | Native CI | Evidence class | +| --- | --- | --- | --- | --- | +| Rust | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | +| TypeScript | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | +| C# | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | +| Go | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | +| Swift | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | +| Java | BTG-controlled | 20/20 | **PASS** | Controlled cross-language reproducibility | + +Repositories: + +- [ENTITY-RUST-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-RUST-CLEANROOM) +- [ENTITY-TYPESCRIPT-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-TYPESCRIPT-CLEANROOM) +- [ENTITY-CSHARP-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-CSHARP-CLEANROOM) +- [ENTITY-GO-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-GO-CLEANROOM) +- [ENTITY-SWIFT-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-SWIFT-CLEANROOM) +- [ENTITY-JAVA-CLEANROOM](https://github.com/blackmore-technology-group/ENTITY-JAVA-CLEANROOM) + +## External milestone scoreboard + +| Milestone | Current status | Evidence required to change status | +| --- | --- | --- | +| Unrelated developer reproduces the v3.3 public vector result | **PENDING** | Public independently authored implementation/evidence from a party outside BTG control | +| Unrelated implementation accepts all valid v3.3 vectors | **PENDING** | Reproducible public candidate result | +| Unrelated implementation rejects all invalid/tampered v3.3 vectors | **PENDING** | Reproducible public candidate result | +| Reproducible CI in unrelated repository | **PENDING** | Public CI tied to independently authored implementation | +| Bidirectional live interoperability with BTG reference implementation | **PENDING** | Public test evidence covering both directions | +| Sovereign export/recovery survival across independent implementation boundary | **PENDING** | Recovery evidence showing preservation of the same authoritative result/root | +| Independently authored qualification report | **PENDING** | External party's own evidence package | +| Independent external security review | **PENDING** | Public or privately verifiable independent review with defined scope | + +## Protocol 1.0 historical conformance target + +The separately published [ENTITY Protocol 1.0 Conformance Kit](https://github.com/blackmore-technology-group/ENTITY-Protocol-1.0-Conformance-Kit) remains the authoritative sealed target for Protocol 1.0 external conformance campaigns. + +That historical target must not be silently rewritten to match later ENTITY versions. Protocol 1.0 and v3.3 evidence should be reported separately. + +## How a new external result is added + +An external result should identify at least: + +1. implementation repository and commit; +2. authoring organization/developer relationship to BTG; +3. language/runtime; +4. exact target kit/version and hashes; +5. test command; +6. valid/invalid vector outcome; +7. CI evidence where available; +8. known failures, skipped cases or deviations; +9. whether live interoperability was attempted; +10. whether sovereign export/recovery was attempted. + +A result may be recorded as **PARTIAL**. Partial evidence must not be upgraded to full interoperability merely because the completed portion passed. + +## Challenge + +For the public path from a small vector classifier through full interoperability, see [ENTITY Interoperability Challenge](../INTEROPERABILITY_CHALLENGE.md). + +A reproducible failure, ambiguity or counterexample is an acceptable and useful outcome. From f67e71361b449bd8f05cd2081915ee6d4f8804d9 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:14:12 -0700 Subject: [PATCH 05/11] Add independent security review program --- .../INDEPENDENT_SECURITY_REVIEW_PROGRAM.md | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md diff --git a/docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md b/docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md new file mode 100644 index 0000000..bbb56da --- /dev/null +++ b/docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md @@ -0,0 +1,153 @@ +# ENTITY Independent Security Review Program + +Blackmore Technology Group Limited maintains this public program to make independent security review of ENTITY easier to scope, reproduce and evaluate. + +The program does **not** claim that ENTITY has already completed an independent external security audit. Unless a specific external review is published and listed here, that milestone remains **PENDING**. + +## Objectives + +An independent review should test whether ENTITY's implementation and protocol boundaries preserve the project's stated security and sovereignty invariants under hostile conditions. + +Priority review areas include: + +1. cryptographic primitive use and key handling; +2. signature canonicalization and replay boundaries; +3. identity-root continuity; +4. delegation, attenuation and revocation; +5. authority escalation paths; +6. recovery, migration and provider replacement; +7. external evidence and attestation semantics; +8. external reality anchors and substitution attacks; +9. rights, entitlement, usage and settlement authorization; +10. portable-state integrity and rollback resistance; +11. parser/schema ambiguity and differential interpretation; +12. historical-state reinterpretation risks; +13. denial-of-service and resource exhaustion where security-relevant; +14. dependency and supply-chain exposure. + +## Review levels + +### Level A — focused review + +A bounded review of one subsystem, invariant or attack surface. + +Examples: + +- signature/canonicalization review; +- recovery boundary review; +- evidence-state transition review; +- external-anchor threat model. + +### Level B — release security review + +A structured review of the current protected release and its release-specific security surfaces. + +Expected outputs include: + +- exact release commit; +- scope; +- methodology; +- findings by severity; +- reproducibility notes; +- exclusions; +- remediation status. + +### Level C — protocol and implementation assessment + +A broader independent assessment covering both protocol semantics and reference implementation behaviour, including cross-component attack paths and provider-independence guarantees. + +This is the strongest review class described by this program, but it is still distinct from legal certification, regulatory approval or proof that every deployment is secure. + +## Current review target + +Current protected release: + +**ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality** + +Protected release commit: + +`9c79f987207592cb6791e1a8956f23351cdfb2d3` + +Reviewers should pin findings to an exact commit, tag or release artifact rather than reviewing an unspecified moving branch. + +## Evidence expected from reviewers + +A useful independent review should publish or privately provide, as appropriate: + +- reviewer identity/organization or explicit anonymous status; +- relationship to BTG and any conflicts of interest; +- exact target version/commit; +- scope and exclusions; +- methodology and tooling; +- reproducible proof-of-concept material when safe; +- severity rationale; +- affected invariants/components; +- remediation verification where performed; +- residual risk and unresolved questions. + +If exploitation details would create unnecessary risk, public reports may summarize the issue while technical reproduction remains under coordinated disclosure until remediation is available. + +## Security invariants reviewers should challenge + +At minimum, reviewers should attempt to falsify these boundaries: + +- registration does not prove ownership; +- provenance does not prove rights or external truth; +- a valid signature does not make an external-world assertion objectively true; +- provider possession does not become sovereign authority; +- applications/agents require explicit scoped revocable authorization; +- historical signed semantics are not silently rewritten; +- recovery preserves the same authoritative Entity root rather than manufacturing a replacement identity; +- external evidence sources do not silently acquire general ENTITY authority; +- rights/usage/economic consequences require the authorization/evidence the protocol says they require. + +## Reporting process + +Potentially exploitable vulnerabilities should be reported through the private vulnerability process described in [SECURITY.md](../../SECURITY.md). + +Public issues and Discussions are appropriate for: + +- non-sensitive threat models; +- specification ambiguities; +- architectural critiques; +- counterexamples that do not expose active users or secrets; +- hardening proposals after responsible disclosure requirements are satisfied. + +## Remediation workflow + +A security finding should move through: + +`report → reproduce → classify → contain where necessary → remediate → regress-test → review semantic impact → release/errata decision → verify remediation → disclose at appropriate level` + +Security fixes must not silently weaken sovereignty, portability or historical-integrity invariants merely to close an implementation defect. + +If remediation changes published protocol semantics, the project should use an explicit governance/version mechanism rather than silently reinterpret existing signed state. + +## Independent review status + +| Review class | Status | Public evidence | +| --- | --- | --- | +| BTG-controlled CI/static analysis | **ACTIVE** | GitHub Actions / CodeQL in repository | +| BTG-controlled qualification/red-team work | **AVAILABLE AS PROJECT EVIDENCE** | See engineering evidence and qualification materials | +| Independent external focused review | **PENDING** | None claimed as complete | +| Independent external release review | **PENDING** | None claimed as complete | +| Independent external protocol + implementation assessment | **PENDING** | None claimed as complete | + +BTG-controlled testing is not a substitute for an unrelated security review. + +## Recognition and publication + +Independent reviewers may be credited according to [Contributor Recognition](../community/CONTRIBUTOR_RECOGNITION.md), subject to security/privacy constraints. + +A future completed review should be added to this document with: + +- reviewer/organization; +- review date; +- target commit; +- scope; +- report link or disclosure reference; +- remediation status. + +## No automatic bounty or certification claim + +This document defines a review pathway. It does not itself promise a monetary bounty, procurement engagement, certification, safe-harbour contract or regulatory recognition. Any such arrangement must be separately stated by Blackmore Technology Group Limited. From a52090c334c85c6f905cfbb610247b58b7142e48 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:14:21 -0700 Subject: [PATCH 06/11] Add technical papers index --- docs/papers/README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/papers/README.md diff --git a/docs/papers/README.md b/docs/papers/README.md new file mode 100644 index 0000000..7bc0c8e --- /dev/null +++ b/docs/papers/README.md @@ -0,0 +1,29 @@ +# ENTITY Technical Papers and Engineering Notes + +This directory collects public technical writing that explains ENTITY's architecture, threat boundaries and engineering decisions in a form that can be reviewed independently of marketing material. + +These papers are informative unless a document explicitly states that it is normative. Normative requirements remain controlled by the applicable protocol, schema, manifest, governance and requirements documents. + +## Current papers + +1. [Technical Note 001 — Three Verification Boundaries](TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md) + +## Publication rules + +A technical paper should: + +- identify whether it is normative or informative; +- identify the release/version it describes; +- distinguish implemented behavior from proposed behavior; +- distinguish BTG-controlled evidence from independent external evidence; +- state important limitations and unresolved questions; +- link to reproducible public material where possible; +- avoid silently redefining frozen protocol semantics. + +## Architecture Decision Records + +Architecture decisions are maintained separately under [docs/architecture](../architecture/README.md). ADRs record decisions and their rationale; technical papers explain broader concepts, boundaries or analysis. + +## Corrections and supersession + +If a paper becomes outdated, the preferred approach is to mark it superseded or publish a revision rather than silently changing historical claims in a way that makes the original evidence impossible to reconstruct. From 89f2144c6bc03f1270c9c37e73c87a89f136602b Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:14:54 -0700 Subject: [PATCH 07/11] Publish technical note on three verification boundaries --- ..._NOTE_001_THREE_VERIFICATION_BOUNDARIES.md | 232 ++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 docs/papers/TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md diff --git a/docs/papers/TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md b/docs/papers/TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md new file mode 100644 index 0000000..d9ca631 --- /dev/null +++ b/docs/papers/TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md @@ -0,0 +1,232 @@ +# Technical Note 001 — Three Verification Boundaries + +**Status:** Informative +**Applies to:** ENTITY v3.3.0 +**Steward:** Blackmore Technology Group Limited +**Normative effect:** None. This note explains existing public design boundaries; it does not replace protocol or requirements documents. + +## Abstract + +ENTITY v3.3 separates three questions that are often collapsed in identity, provenance and evidence systems: + +1. **Cryptographic verification** — was a specific record signed by the expected key over the expected bytes? +2. **Protocol verification** — is the signed record structurally and semantically valid under the applicable ENTITY rules? +3. **Reality/evidence verification** — what evidence supports an assertion about the external world, who supplied that evidence, under what authority, and what is the current contestable state of the claim? + +The separation is intentional. A successful answer at one layer must not silently imply success at another. + +## 1. Why the distinction matters + +A signature can prove attribution to a key without proving that the signed statement is factually correct. + +A protocol verifier can prove that a state transition obeys ENTITY rules without proving that a legal, physical, scientific, financial or other external-world assertion embedded in that state is true. + +An external institution can provide evidence or an attestation without thereby becoming sovereign authority over an Entity's complete identity, rights or state. + +ENTITY v3.3 therefore treats these as separate verification domains. + +## 2. Cryptographic verification + +Cryptographic verification asks questions such as: + +- does the signature validate against the referenced public key? +- were the exact canonical bytes signed? +- is the expected signature algorithm/profile in use? +- is the key valid for the relevant signing operation under the protocol's key/authority state? + +A positive cryptographic result means that the signature relationship has been verified within the stated cryptographic/profile assumptions. + +It does **not** by itself establish: + +- ownership; +- legal title; +- truth of a factual claim; +- authorization outside the key's granted scope; +- regulatory recognition; +- current validity if the signing authority has been revoked or otherwise constrained by applicable protocol rules. + +## 3. Protocol verification + +Protocol verification asks whether the record or transition obeys ENTITY semantics. + +Typical questions include: + +- is the record/schema valid? +- is the signer authorized for this transition? +- does delegation stay within its permitted scope? +- are revocation and historical-state rules respected? +- does a transition preserve identity continuity? +- are provider-independence and portability invariants maintained? +- are rights, usage or economic consequence transitions supported by the required protocol evidence? + +Protocol validity therefore sits above raw signature validity. + +A correctly signed transition can still be invalid if the signer lacks authority, the transition violates state-machine rules, or required prerequisites are absent. + +## 4. Reality and evidence verification + +ENTITY v3.3 introduces explicit structures for claims about the external world. + +The relevant model can be summarized as: + +```text +REALITY + ↓ +OBSERVATION + ↓ +CLAIM + ↓ +EVIDENCE + ↓ +ATTESTATION + ↓ +VERIFICATION + ↓ +AUTHORITATIVE ENTITY STATE +``` + +The purpose is not to make an external-world claim indisputable. The purpose is to make the basis of the claim attributable, typed, contestable and machine-verifiable. + +Relevant questions include: + +- who observed or asserted the fact? +- what evidence object supports it? +- what kind of claim is it? +- what authority did the attester have for this class of fact? +- is that authority still valid? +- does the evidence depend on an external registry, sensor, laboratory, receipt, document or API? +- has the claim been disputed, superseded, revoked or adjudicated? +- which downstream rights or economic consequences depend on it? + +## 5. Typed claim states + +ENTITY v3.3 defines typed states including: + +- `OBSERVED` +- `ASSERTED` +- `INFERRED` +- `ATTESTED` +- `EXTERNALLY_VERIFIED` +- `ADJUDICATED` +- `DISPUTED` +- `REVOKED` +- `UNKNOWN` + +These states are deliberately not interchangeable. + +For example, `ATTESTED` indicates that an authorized attester has made or supported the claim within a stated authority scope. It does not mean the protocol has transformed the claim into universal truth. + +`EXTERNALLY_VERIFIED` indicates that an external verification process or source supports the claim under the recorded evidence conditions. It does not make the external source sovereign authority over unrelated ENTITY state. + +## 6. External anchors are evidence, not sovereignty + +ENTITY may reference registries, APIs, sensors, institutions or other external systems as reality anchors. + +That relationship must remain bounded. + +An external source can provide: + +- a value; +- a timestamped observation; +- a registry record; +- a certification result; +- a receipt; +- a laboratory result; +- an institutional attestation. + +It does not automatically acquire the right to: + +- control the Entity root; +- delegate arbitrary authority; +- redefine unrelated rights; +- replace the Entity's sovereign authorization chain; +- silently rewrite historical signed records. + +## 7. Contestability and supersession + +External-world claims can change, be challenged or be shown to be wrong. + +ENTITY therefore preserves challenge and supersession instead of assuming that the latest accepted record erases the previous one. + +A later claim can supersede an earlier claim while maintaining evidence of: + +- what the earlier state was; +- who asserted it; +- what evidence supported it; +- who challenged it; +- what decision or new evidence caused the state to change. + +This supports auditability without pretending that an earlier accepted claim was necessarily true merely because it was validly recorded. + +## 8. Economic causality + +ENTITY's data-rights and market model extends beyond provenance into usage and economic consequence. + +The lifecycle remains: + +```text +DCO + ↓ +Instrument + ↓ +Listing + ↓ +Disclosure + ↓ +Order / RFQ / Auction + ↓ +Price Discovery + ↓ +Trade + ↓ +Clearing + ↓ +Settlement + ↓ +Entitlement + ↓ +Usage + ↓ +Derived Output + ↓ +Economic Consequence +``` + +The v3.3 evidence layer allows downstream economic records to retain links to the evidence and claims that materially supported the authorized result. + +This still does not mean every correlated event is causally attributable. Causal attribution must follow the rules and evidence represented by the protocol rather than being inferred from temporal proximity alone. + +## 9. Security implications + +Collapsing the three verification boundaries creates several dangerous failure modes: + +- **signature-to-truth escalation:** treating a valid signature as proof a factual assertion is true; +- **protocol-to-law escalation:** treating protocol conformance as proof of legal title or regulatory recognition; +- **anchor-to-sovereignty escalation:** allowing an external data source to acquire control beyond its attestation scope; +- **provenance-to-rights escalation:** treating evidence of origin as proof of current rights; +- **usage-to-value escalation:** claiming realized economic value without the evidence required to support the consequence. + +Security review should attempt to find implementation paths where these boundaries can be bypassed. + +## 10. Public evidence and current limits + +ENTITY v3.3 publishes a sealed 20-vector reality/evidence campaign and BTG-controlled cross-language reproducibility baselines. + +Those results demonstrate controlled engineering reproducibility against the stated target. They do not constitute unrelated external implementation, independent security review, legal recognition or proof of market adoption. + +The project therefore keeps the following external milestones separate: + +- unrelated implementation/conformance; +- bidirectional interoperability; +- sovereign export/recovery across an independent implementation boundary; +- independent security review; +- deployment-specific legal/regulatory determinations; +- demonstrated external market participation/liquidity. + +## Conclusion + +ENTITY's v3.3 verification model is designed around a simple rule: + +> A cryptographically valid statement is not automatically a protocol-valid statement, and a protocol-valid statement is not automatically a true statement about the external world. + +Keeping those questions separate makes authority, evidence, contestability and downstream economic consequences easier to audit without turning infrastructure or signatures into authority they were never granted. From efbb27e3f4ca71528b46109db523a94fcbc2007c Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:15:09 -0700 Subject: [PATCH 08/11] Document ADR governance process --- docs/architecture/ADR_PROCESS.md | 73 ++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/architecture/ADR_PROCESS.md diff --git a/docs/architecture/ADR_PROCESS.md b/docs/architecture/ADR_PROCESS.md new file mode 100644 index 0000000..19e3925 --- /dev/null +++ b/docs/architecture/ADR_PROCESS.md @@ -0,0 +1,73 @@ +# ENTITY Architecture Decision Record Process + +Architecture Decision Records (ADRs) document decisions that affect ENTITY's durable architecture, protocol boundaries or security/governance invariants. + +## When an ADR is required + +An ADR should be considered when a change affects one or more of: + +- root identity semantics; +- authority, delegation or revocation; +- signature/canonicalization meaning; +- provider independence; +- custody versus sovereignty boundaries; +- recovery, migration or portability; +- evidence and attestation semantics; +- external reality anchors; +- historical signed-state interpretation; +- rights, entitlement, usage or economic consequence semantics; +- compatibility or public protocol behavior. + +Routine implementation detail that preserves existing architecture does not require an ADR. + +## ADR states + +Use one of these states: + +- **PROPOSED** — under discussion; not yet authoritative. +- **ACCEPTED** — approved architecture decision. +- **SUPERSEDED** — replaced by a later ADR; retained for historical traceability. +- **REJECTED** — considered but not adopted. +- **DEPRECATED** — retained for historical reference but no longer recommended for new implementation. + +## Required sections + +A new ADR should include: + +1. **Title and identifier** +2. **Status** +3. **Date** +4. **Context** +5. **Decision** +6. **Security/sovereignty implications** +7. **Compatibility implications** +8. **Alternatives considered** +9. **Consequences** +10. **Evidence / references** +11. **Supersedes / superseded by**, if applicable + +## Review expectations + +ADRs touching security- or sovereignty-critical boundaries should be reviewed against: + +- [GOVERNANCE.md](../../GOVERNANCE.md) +- [SECURITY.md](../../SECURITY.md) +- [Release Policy](../governance/RELEASE_POLICY.md) +- applicable protocol governance/freeze documents +- the project's public engineering evidence and current claim boundaries. + +An ADR cannot silently rewrite a frozen protocol target or historical signed semantics. If a decision changes published protocol meaning, the change must use an explicit version/governance mechanism. + +## Numbering + +ADRs use a stable numeric identifier, for example: + +`ADR-0004-SOVEREIGN-AUTHORITY-DOCTRINE.md` + +Numbers are never reused, even if an ADR is rejected or superseded. + +## Relationship to technical papers + +ADRs record a decision. Technical papers explain concepts, threat boundaries or analysis. A paper may motivate an ADR, but it does not become normative merely because it exists in the public repository. + +See [docs/papers/README.md](../papers/README.md). From 892358a92ddf84bd4ead9b62641430b4a134b38b Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:15:30 -0700 Subject: [PATCH 09/11] Update security policy for v3.3 and external review program --- SECURITY.md | 160 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 104 insertions(+), 56 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 38f258c..81e37c2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,56 +1,104 @@ -# Security Policy - -ENTITY handles identity, authority, provenance, rights, cryptographic verification, and portable state. Security reports should be treated as potentially high impact. - -## Supported public release - -The current public source/reference release is **ENTITY v3.0.1**. The separately published Windows x64 binary remains **1.0.0-rc2**. ENTITY Protocol 1.0 remains **FROZEN_FOR_EXTERNAL_CONFORMANCE** as historical conformance scope. - - -## v3.0.1 key-lifecycle hardening - -ENTITY v3.0.1 enforces operational signing-key creation and retirement/revocation cutoffs for v2 signature records and removes obsolete local operational key material after successful rotation/recovery. Valid historical signatures remain verifiable when their signed time precedes the relevant cutoff. A signer-controlled `signed_at_ms` is evidence from the signer, not an objective trusted timestamp; authoritative temporal claims require independently anchored time/event evidence. - -## Reporting a vulnerability - -Do not publish exploit details, private keys, operational bindings, or affected user data in a public issue. - -**Private vulnerability reporting is enabled for this repository.** Use GitHub's private security reporting feature for ENTITY. If that feature is temporarily unavailable, contact Blackmore Technology Group through an official private company channel and reference the `blackmore-technology-group/ENTITY` repository. - -A useful report includes: - -- affected file/module and commit; -- attack preconditions; -- expected vs observed authorization behavior; -- reproducible steps or a minimal proof of concept; -- whether identity, signing, recovery, rights, portability, or provider-independence semantics are affected. - -## Never include in reports or commits - -- real private signing/recovery keys; -- live principal bindings; -- live authentication tokens or credentials; -- production SQLite/state databases; -- encrypted backups together with their decryption keys; -- personal/business source data not required to demonstrate the issue. - -## Release-signing key lifecycle - -ENTITY's public signing-key rotation, revocation, recovery and release-tag procedure is documented in: - -[`docs/security/RELEASE_SIGNING_KEY_LIFECYCLE.md`](docs/security/RELEASE_SIGNING_KEY_LIFECYCLE.md) - -The document publishes fingerprints/process only. Private keys and recovery codes must never be committed. - -## Security invariants - -A security fix must not silently weaken these protocol invariants: - -- registration does not prove ownership; -- provenance does not prove rights or truth; -- provider possession does not become sovereign authority; -- applications require explicit revocable authorization; -- historical signed semantics are not silently rewritten; -- state migration/recovery preserves the same Entity root rather than manufacturing a replacement identity. - -Security-critical semantic changes require an auditable protocol/governance change and, where applicable, a new protocol version. +# Security Policy + +ENTITY handles identity, authority, provenance, evidence, rights, cryptographic verification and portable state. Security reports should be treated as potentially high impact. + +## Supported public release + +The current protected public source/reference release is **ENTITY v3.3.0 — Verifiable Reality, Evidence and Economic Causality**. + +Protected release commit: + +`9c79f987207592cb6791e1a8956f23351cdfb2d3` + +The separately published Windows x64 `1.0.0-rc2` binary remains a historical product build and should not be confused with the current v3 protocol/reference-source release line. + +ENTITY Protocol 1.0 remains **FROZEN_FOR_EXTERNAL_CONFORMANCE** as its separately sealed historical conformance scope. + +Current v3.3 qualification and claim boundaries are published in [Engineering Evidence](docs/ENGINEERING_EVIDENCE.md). Independent external security review remains a separate **PENDING** milestone. + +## Security model additions through v3.3 + +ENTITY v3.0.1 hardened operational signing-key creation, retirement/revocation cutoffs and recovery/rotation behavior while preserving valid historical signatures under the applicable signed-time semantics. + +Later releases add further security-sensitive protocol surfaces, including: + +- provider-neutral adoption and Rights Passport machinery; +- evidence objects and typed claim states; +- scoped and revocable attestation authority; +- external reality anchors that remain evidence rather than automatic sovereign authority; +- contestability and supersession; +- evidence-linked economic causality. + +A signer-controlled timestamp is evidence from the signer, not an objective trusted timestamp. Authoritative temporal claims require the applicable independent anchoring/evidence semantics. + +## Reporting a vulnerability + +Do not publish exploit details, private keys, operational bindings or affected user data in a public issue. + +**Private vulnerability reporting is enabled for this repository.** Use GitHub's private security reporting feature for ENTITY. If that feature is temporarily unavailable, contact Blackmore Technology Group through an official private company channel and reference the `blackmore-technology-group/ENTITY` repository. + +A useful report includes: + +- affected file/module and exact commit; +- attack preconditions; +- expected vs observed authorization behavior; +- reproducible steps or a minimal proof of concept; +- whether identity, signing, evidence, attestation, recovery, rights, settlement, portability or provider-independence semantics are affected; +- known impact and constraints; +- whether public disclosure before remediation would create additional risk. + +## Never include in reports or commits + +- real private signing/recovery keys; +- live principal bindings; +- live authentication tokens or credentials; +- production SQLite/state databases; +- encrypted backups together with their decryption keys; +- personal/business source data not required to demonstrate the issue; +- unrelated third-party secrets or data. + +## Independent security review + +The public pathway for external focused reviews, release reviews and broader protocol/implementation assessments is documented in: + +[`docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md`](docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md) + +That program defines review scope and evidence expectations. It does not claim that an independent external audit has already been completed. + +## Release-signing key lifecycle + +ENTITY's public signing-key rotation, revocation, recovery and release-tag procedure is documented in: + +[`docs/security/RELEASE_SIGNING_KEY_LIFECYCLE.md`](docs/security/RELEASE_SIGNING_KEY_LIFECYCLE.md) + +The document publishes fingerprints/process only. Private keys and recovery codes must never be committed. + +## Security invariants + +A security fix must not silently weaken these protocol invariants: + +- registration does not prove ownership; +- provenance does not prove rights or external truth; +- a valid signature does not make an external-world assertion objectively true; +- provider possession does not become sovereign authority; +- applications and agents require explicit scoped revocable authorization; +- external evidence sources do not silently acquire general ENTITY authority; +- historical signed semantics are not silently rewritten; +- state migration/recovery preserves the same Entity root rather than manufacturing a replacement identity; +- rights, usage and economic consequence transitions require the authorization/evidence the applicable protocol rules specify. + +Security-critical semantic changes require an auditable protocol/governance change and, where applicable, a new protocol version. + +## Disclosure and remediation + +A security finding should normally progress through: + +`report → reproduce → classify → contain where necessary → remediate → regression test → semantic/governance review → release or errata decision → remediation verification → disclosure` + +The project may delay publication of exploit details when immediate disclosure would materially increase risk before a fix or mitigation is available. + +## Security evidence boundaries + +Repository CI, CodeQL, dependency review, BTG-controlled qualification, clean-room baselines and internal red-team work are valuable engineering evidence. They are **not** described as an independent external security audit. + +A completed external review should identify its reviewer, scope, target commit, methodology, exclusions and remediation status so that the resulting claim remains bounded to the work actually performed. From 66d2415458f023346c5539b76e39af125f11e782 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:16:01 -0700 Subject: [PATCH 10/11] Expand ENTITY project and protocol governance model --- GOVERNANCE.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 187 insertions(+), 13 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 9f7cc64..f589a31 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,41 +1,215 @@ # ENTITY Open-Source Governance +## Purpose + +This document defines how the public ENTITY project is stewarded, how protocol-impacting decisions are handled, and how Blackmore Technology Group Limited's project stewardship is separated from protocol sovereignty. + ## Stewardship -Blackmore Technology Group Limited stewards the ENTITY specifications, reference implementation, and public release process. +Blackmore Technology Group Limited (BTG) currently stewards the official ENTITY specifications, reference implementation, release process, project repositories and public engineering evidence. + +Stewardship does **not** make BTG the sovereign authority over conforming Entity identities, rights or data merely because BTG publishes software, specifications, resolvers, repositories or infrastructure. + +A conforming published protocol version is intended to remain usable without mandatory dependence on BTG-controlled hosting or services. -Stewardship does not make BTG the sovereign authority over conforming Entity identities or data merely because BTG publishes software, specifications, resolvers, or infrastructure. +## Governance principles + +ENTITY governance follows these principles: + +1. **Published meaning is stable.** A published protocol version is not silently reinterpreted after release. +2. **Evidence is separated from claims.** BTG-controlled testing is not relabeled as unrelated external validation. +3. **Infrastructure is not sovereignty.** Hosting, routing, custody, storage, discovery and software distribution do not automatically create authority. +4. **Historical signed state is preserved.** New rules supersede or migrate old state explicitly rather than rewriting history. +5. **Security-critical semantics require explicit review.** Identity, authority, signatures, recovery, portability, evidence, rights and compatibility changes cannot be treated as ordinary refactors when their meaning changes. +6. **External criticism is useful evidence.** Reproducible failures, ambiguities and counterexamples are valid engineering outcomes. +7. **Protocol conformance should be publicly reproducible.** Public specifications, schemas, vectors and verification material should be sufficient for an unrelated implementer to test the stated target. ## Published protocol versions -A published protocol version is immutable in meaning. Corrections are handled through documented errata or a new version. +A published protocol version is immutable in meaning. Corrections are handled through one or more of: -A conforming implementation of a published version must not require: +- implementation fixes that preserve semantics; +- documented errata; +- clarifying non-normative guidance; +- an explicitly versioned protocol change. + +A conforming implementation of a published version must not require, as a hidden condition of core conformance: - BTG hosting; - BTG DNS; - a BTG resolver; - a mandatory BTG cloud service; -- a paid BTG subscription +- a paid BTG subscription or licence to use the published protocol. + +Optional BTG-operated services may exist, but service use must remain distinguishable from core protocol authority and conformance. -unless that dependency is explicitly outside core conformance and chosen by the Entity. +## Protocol 1.0 freeze -## Conformance +ENTITY Protocol 1.0 remains **FROZEN_FOR_EXTERNAL_CONFORMANCE** under its separately published freeze and conformance materials. -Conformance is determined by public specifications, schemas, test vectors, and reproducible verification—not by access to private BTG infrastructure. +That historical target is not rewritten to match later ENTITY releases. Later versions may extend the system while preserving Protocol 1.0 evidence as a distinct historical conformance target. -ENTITY Protocol 1.0 is currently **FROZEN_FOR_EXTERNAL_CONFORMANCE**. Independent external interoperability qualification is still pending. +Independent external interoperability qualification for that target remains separate from BTG-controlled testing. ## Decision classes -Implementation-only fixes may be accepted without a protocol revision when they preserve published semantics. +### Class A — implementation-preserving + +Examples: + +- bug fixes that preserve published semantics; +- performance improvements; +- diagnostics; +- developer tooling; +- documentation corrections that do not change normative meaning. + +These changes can normally proceed through standard pull-request review and release qualification. + +### Class B — architecture-sensitive + +Examples: + +- changes to internal boundaries that affect security or portability assumptions; +- new provider/custody integration surfaces; +- new evidence or rights-processing components; +- changes that introduce a new durable architectural dependency. + +These changes should receive explicit architecture review and may require an ADR. + +### Class C — protocol/security semantic + +Changes affecting any of the following require explicit governance review and may require a new protocol/version boundary: + +- identity-root semantics; +- authority, delegation or revocation; +- signature or canonicalization meaning; +- provider independence; +- recovery, migration or portability; +- evidence/attestation state semantics; +- external reality anchors; +- historical signed-state interpretation; +- rights, entitlement, usage or settlement authorization; +- wire compatibility or conformance behavior. + +See [ADR Process](docs/architecture/ADR_PROCESS.md). + +## Architecture Decision Records + +Durable architecture decisions are recorded under `docs/architecture/`. + +ADRs should be used when the project needs a stable public record of: + +- context; +- decision; +- alternatives; +- security/sovereignty implications; +- compatibility effects; +- consequences; +- supersession history. + +An ADR cannot silently override a frozen protocol target. Protocol semantics must change through the applicable version/governance mechanism. + +## Release governance + +ENTITY releases are **evidence-gated**, not calendar-promised. + +Release readiness should be supported by the qualification appropriate to that release, including regression, targeted tests, manifests/hashes, compatibility review, security-sensitive review and protected-branch checks. + +The project maintains a separate [Release Policy](docs/governance/RELEASE_POLICY.md) describing patch/minor/major expectations, evidence gates, historical-integrity rules and claim discipline. + +## Conformance governance + +Conformance is determined by public specifications, schemas, test vectors and reproducible verification—not by privileged access to private BTG infrastructure. + +BTG-controlled cross-language implementations are controlled reproducibility evidence. They are not described as unrelated independent implementations. -Changes affecting identity, authority, signature meaning, portability, recovery, provider independence, evidence semantics, or wire compatibility require documented architecture/governance review. +External conformance evidence should identify: + +- implementation repository/commit; +- authoring party and relationship to BTG; +- exact target/version; +- test command; +- public result/evidence; +- known failures or exclusions; +- whether live interoperability/recovery was attempted. + +Current status is published in [Interoperability Status](docs/interoperability/STATUS.md). + +## Security governance + +Potentially exploitable vulnerabilities use the private reporting process in [SECURITY.md](SECURITY.md). + +Security-critical changes must preserve or explicitly version changes to the project's core invariants. A security fix is not permitted to silently trade away provider independence, portability, historical integrity or scoped authority merely to close a defect. + +The public external-review pathway is described in [Independent Security Review Program](docs/security/INDEPENDENT_SECURITY_REVIEW_PROGRAM.md). + +## Contributor governance + +Contributors retain credit for their actual work through Git/GitHub history and project recognition surfaces where appropriate. + +Contribution does not automatically imply: + +- employment; +- maintainer authority; +- endorsement of ENTITY or BTG; +- independent validation of areas not tested; +- legal, regulatory or certification opinion. + +See [Contributor Recognition](docs/community/CONTRIBUTOR_RECOGNITION.md). + +## Maintainers + +BTG currently retains stewardship/merge/release authority for the official ENTITY repositories. + +If formal external maintainer roles are established later, the project should document each role's: + +- scope; +- review authority; +- merge authority; +- release authority; +- security responsibilities; +- conflict-of-interest expectations; +- removal/succession process. + +Contributor activity alone does not silently create maintainer authority. ## Extensions -Vendor- or application-specific extensions must be namespaced and must not silently redefine core ENTITY records. +Vendor-, deployment- or application-specific extensions must be namespaced and must not silently redefine core ENTITY records or claim conformance by changing the meaning of a published core field. + +An extension may add optional behavior without converting its vendor-specific dependency into a core protocol requirement. ## Historical integrity -Signed historical records are never silently reinterpreted under newer policy or protocol semantics. +Signed historical records, sealed conformance targets and published release evidence are not silently reinterpreted under newer policy or protocol semantics. + +When presentation or documentation later improves, the project prefers: + +- new explanatory material; +- explicit errata where permitted; +- a new release/version where the target genuinely changes; + +rather than weakening verification or rewriting signed historical evidence for cosmetic reasons. + +## Technical publications + +Informative technical papers are published under [docs/papers](docs/papers/README.md). They explain architecture and threat boundaries but are not automatically normative. + +Normative authority remains with the applicable protocol, schemas, freeze/governance documents, release manifests and controlling requirements. + +## Public participation + +Engineering participation occurs through: + +- GitHub Issues for bounded work, defects and specification questions; +- GitHub Discussions for design/architecture discussion; +- Pull Requests for reviewable code/documentation/evidence; +- private security reporting for exploitable vulnerabilities. + +The public developer gateway is [DEVELOPERS.md](DEVELOPERS.md). + +## Governance changes + +Changes to this governance document should themselves be reviewable through the protected pull-request process. + +A governance edit cannot retroactively transform BTG-controlled evidence into independent validation or silently change the meaning of a previously frozen/released protocol target. From 351a4841cfaaa99cd7f742de7eda56e2dbaa95d9 Mon Sep 17 00:00:00 2001 From: Shawn Blackmore Date: Thu, 24 Sep 2026 10:16:18 -0700 Subject: [PATCH 11/11] Turn architecture directory into a public ADR and architecture index --- docs/architecture/README.md | 82 +++++++++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 6ccc2d9..4121cd9 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,6 +1,6 @@ -# Architecture Overview +# ENTITY Architecture -ENTITY separates sovereign authority from infrastructure custody. +ENTITY separates sovereign authority from infrastructure custody and keeps identity, authorization, evidence, rights, usage and economic consequence as auditable but distinct concerns. At a high level: @@ -20,12 +20,80 @@ Licensing / usage / settlement evidence Portable state + recovery ``` -The reference implementation is divided into: +The v3.3 evidence path extends that model with: -- `01_Core_Runtime` — identity, policy, permissions, contracts, usage, canonical APIs. -- `04_Entity_Registry` — assets, event ledger, provenance, relationships, rights claims, credentials. -- `15_Operations` — portable state, recovery/migration, runtime state machinery. +```text +REALITY + ↓ +OBSERVATION + ↓ +CLAIM + ↓ +EVIDENCE + ↓ +ATTESTATION + ↓ +VERIFICATION + ↓ +AUTHORITATIVE ENTITY STATE +``` + +The project deliberately separates **cryptographic verification**, **protocol verification** and **reality/evidence verification**. See [Technical Note 001 — Three Verification Boundaries](../papers/TECHNICAL_NOTE_001_THREE_VERIFICATION_BOUNDARIES.md). + +## Major implementation surfaces + +- `01_Core_Runtime` — identity, policy, permissions, contracts, usage and canonical APIs. +- `04_Entity_Registry` — assets, event ledger, provenance, relationships, rights claims and credentials. +- `15_Operations` — portable state, recovery/migration and runtime state machinery. - `22_Sovereign_Domain` — Entity-native domains, nodes, presence, resolution, portability and verification. +- `31_Profiles` — profile machinery. +- `33_Economic_Participation` — economic participation and consequence surfaces. +- `36_Adoption_Layer` — Rights Passports and adoption-layer interfaces. +- `37_Verifiable_Reality` — evidence objects, attestation, external anchors, contestability and causal attribution. - `sdk/` — provider-neutral application integration and principal/device/application binding. -The controlling authority doctrine is recorded in `ADR-0004-SOVEREIGN-AUTHORITY-DOCTRINE.md`. +## Architecture Decision Records + +Durable architecture decisions are recorded as ADRs. The process is defined in [ADR_PROCESS.md](ADR_PROCESS.md). + +Current public ADRs: + +| ADR | Status | Subject | +| --- | --- | --- | +| [ADR-0004](ADR-0004-SOVEREIGN-AUTHORITY-DOCTRINE.md) | Accepted | Sovereign Authority Doctrine — platform non-authority, provider replaceability and digital-existence continuity | + +ADR numbers are stable and never reused. A superseded/rejected ADR remains part of the historical architecture record. + +## Other architecture documents + +- [ENTITY Domain Protocols v1](ENTITY_DOMAIN_PROTOCOLS_v1.md) +- [ENTITY 2 — Causal NIKI Integration](ENTITY_2_CAUSAL_NIKI_INTEGRATION.md) +- [ENTITY 2 — Full ADAM Integration](ENTITY_2_FULL_ADAM_INTEGRATION.md) + +These documents should be read with their stated version/status. Their presence in the architecture directory does not automatically make every statement normative for the current protected release. + +## Architecture invariants + +The current architecture is intended to preserve these boundaries: + +- identity is not an account; +- registration is not ownership; +- provenance is not truth; +- a valid signature is not proof that an external-world assertion is correct; +- possession, hosting, routing, custody and storage do not create sovereign authority; +- external registries and anchors can provide evidence without becoming general authority; +- applications and agents act only through explicit, scoped, revocable authority; +- recovery preserves authoritative identity continuity rather than manufacturing a new root; +- historical signed semantics are superseded explicitly, not silently rewritten; +- data bytes do not require artificial scarcity for rights, entitlements, licensing and usage to be economically governed. + +## Change control + +Changes affecting identity, authority, signature meaning, provider independence, recovery, portability, evidence semantics, historical interpretation, rights/settlement authorization or wire compatibility require explicit architecture/governance consideration. + +See: + +- [GOVERNANCE.md](../../GOVERNANCE.md) +- [Release Policy](../governance/RELEASE_POLICY.md) +- [SECURITY.md](../../SECURITY.md) +- [Engineering Evidence](../ENGINEERING_EVIDENCE.md)