docs: Update DESIGN.md with latest architectural changes #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
## Summary Synchronizing DESIGN.md with the latest version from ans-registry-poc repository. ## Key Changes - Enhanced Dynamic Badge Lander description with dual-format deployment details - Added comprehensive 3-layer trust framework model documentation - Clarified DNS-01 challenge flow to prevent OAuth token delegation risks - Updated figure numbering for consistency - Improved DANE tier descriptions and trust model explanations - Added holistic trust framework diagram reference - Clarified agent lifecycle and event-driven identity model ## Technical Improvements - Better separation between Layer 1 (identity), Layer 2 (attestations), and Layer 3 (reputation) - Clearer explanation of PubSC vs PriCC certificate roles - Enhanced security posture by requiring AHP to execute DNS writes directly 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR synchronizes DESIGN.md with the latest architectural refinements from the ans-registry-poc repository, focusing on enhanced trust framework documentation, improved security clarifications, and better separation of concerns across system layers.
Key Changes:
- Introduced comprehensive 3-layer trust framework documentation distinguishing foundational identity (Layer 1/RA scope), operational maturity attestations (Layer 2), and real-time reputation scoring (Layer 3)
- Clarified DNS-01 challenge security model requiring AHP to execute DNS writes directly instead of OAuth token delegation
- Updated figure numbering and added references to holistic trust framework diagram
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The RA's internal AIM instance validates the attestation chain continuously. It verifies DNS records, Agent Card cryptographic integrity, and linked capability schemas against registration hashes. It triggers remediation when discrepancies occur. | ||
|
|
||
| **3.1.5 Interfaces Hosted by the RA System:** | ||
| * **Dynamic Badge Lander:** Shows real-time trust status for agents - green checkmark if valid, red X if compromised |
There was a problem hiding this comment.
The newly added Dynamic Badge Lander description duplicates the existing line 106. Line 107 should replace line 106 rather than being added as a separate bullet point.
Suggested change
| * **Dynamic Badge Lander:** Shows real-time trust status for agents - green checkmark if valid, red X if compromised |
Swaagie
requested changes
Nov 24, 2025
|
|
||
| Thus, the RA provides the immutable anchor of identity; the ecosystem (layers 2 and 3) builds the trust and reputation scores upon it. | ||
|
|
||
|  |
Member
There was a problem hiding this comment.
The image is missing from the PR
| The RA is the source of truth for registration, while independent external systems consume RA System public outputs for value-added services. | ||
| The ANS' RA architecture is scoped to be the first layer, the foundational identity, of a required 3-layer trust model. In this, the RA answers "who are you?" It is limited to verifying and sealing the agent's identity via the PriCC and public commitment via the Agent Card hash into the TL. | ||
|
|
||
| Having a layer 1 foundation enables a competitive ecosystem of external services to provide the higher-level trust guarantees necessary for high-stakes transactions: |
Member
There was a problem hiding this comment.
Suggested change
| Having a layer 1 foundation enables a competitive ecosystem of external services to provide the higher-level trust guarantees necessary for high-stakes transactions: | |
| Having a layer 1 foundation enables a competitive ecosystem of external services to provide the higher-level trust guarantees necessary for high-stakes transactions. |
| ### 3.4 The holistic trust framework: a 3-layer model | ||
|
|
||
| The RA is the source of truth for registration, while independent external systems consume RA System public outputs for value-added services. | ||
| The ANS' RA architecture is scoped to be the first layer, the foundational identity, of a required 3-layer trust model. In this, the RA answers "who are you?" It is limited to verifying and sealing the agent's identity via the PriCC and public commitment via the Agent Card hash into the TL. |
Member
There was a problem hiding this comment.
Nit
Suggested change
| The ANS' RA architecture is scoped to be the first layer, the foundational identity, of a required 3-layer trust model. In this, the RA answers "who are you?" It is limited to verifying and sealing the agent's identity via the PriCC and public commitment via the Agent Card hash into the TL. | |
| The ANS' RA architecture is scoped to be the first layer, the foundational identity, of a required 3-layer trust model. In this, the RA answers "who are you?" It is limited to verifying and sealing the agent's identity via the `PriCC` and public commitment via the Agent Card hash into the TL. |
For consistent formatting with other use of PriCC (had to look it up in the document 😄)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR synchronizes DESIGN.md with the latest version from the ans-registry-poc repository, incorporating recent architectural refinements and clarifications.
Key Changes
🏗️ Enhanced Architecture Documentation
🔒 Security Improvements
📝 Documentation Improvements
🔧 Technical Clarifications
Testing
Impact
This update ensures the public DESIGN.md accurately reflects the current architectural vision and implementation approach for the ANS Registry system.
🤖 Generated with Claude Code