Twin3 SDK (twin3-sdk)

The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans

English | 繁體中文 | GitHub: twin3-team/twin3-sdk

---

1. Overview & Vision

Twin3 SDK is a domain-agnostic, cryptographically secure foundational runtime designed to bridge autonomous AI agents and self-sovereign human individuals into a single symbiotic economic network.

As AI models evolve toward fully autonomous trading actors, the primary barrier to adoption is not intelligence, but counterparty trust, deterministic authorization, cryptographic non-repudiation, and autonomous financial settlement.

Twin3 SDK solves this by establishing a Seven-Layer Symbiotic Architecture (L1 to L7). It serves as the universal hardware-like motherboard, while domain-specific applications plug into it as specialized software projections:

1. Agent ID (Enterprise Projection): Powers B2B autonomous commerce, procurement negotiation, and Dun & Bradstreet (D-U-N-S) enterprise identity verification across 20 commercial capabilities.
2. Human ID (Sovereign Projection): Protects 140,000+ real-world human identity assets, providing Passkey (WebAuthn) biometrics, personal sovereign cards, and paid anti-spam inboxes.

---

2. The Seven-Layer Symbiotic Architecture

Twin3 SDK organizes all distributed primitives into seven clean, composable layers:

                  ┌─────────────────────────────────────────────────────────┐
                  │                 Twin3 SDK Core Engine                   │
                  ├────┬───────────────────────┬────────────────────────────┤
                  │ L1 │ Discovery Layer       │ twin3.discovery            │
                  │ L2 │ Trust & Identity      │ twin3.trust                │
                  │ L3 │ Communication Layer   │ twin3.comm                 │
                  │ L4 │ Shield & Guardrails   │ twin3.shield               │
                  │ L5 │ Matrix Understanding  │ twin3.matrix               │
                  │ L6 │ Clearing & Settlement │ twin3.settlement           │
                  │ L7 │ Governance & Audit    │ twin3.governance           │
                  └────┴───────────────────────┴────────────────────────────┘
                               ▲                             ▲
                               │                             │
          ┌────────────────────┴───────────┐    ┌────────────┴─────────────────┐
          │     Agent ID (Enterprise)      │    │      Human ID (Sovereign)    │
          ├────────────────────────────────┤    ├──────────────────────────────┤
          │ • A2A 5-Stage Commercial Loop  │    │ • Sovereign Identity Card    │
          │ • D-U-N-S Entity Verification  │    │ • 140,000 Personality Vectors│
          │ • Manufacturing Tolerance Match│    │ • Passkey WebAuthn Login     │
          │ • Corporate Multi-Sig Escrow   │    │ • Paid Threshold Inbox       │
          └────────────────────────────────┘    └──────────────────────────────┘

Layer Breakdown

Layer	Module Path	Purpose	Key Primitives & Protocols
L1 Discovery	twin3.discovery	Agent Card & Sovereign Card specifications, public inbox declaration, in-memory registry.	AgentCard, SovereignCard, build_declaration, DiscoveryRegistry
L2 Trust	twin3.trust	Cryptographic identity handshake, public/private key verification, authority anchoring.	create_challenge / complete_challenge / verify_binding, PasskeyAdapter, AuthorityAnchor, resolve_did_web, nonce and sign-count stores
L3 Communication	twin3.comm	Non-repudiable message packaging, counterparty attention ladder, task inbox.	build_envelope / validate_envelope (Ed25519), CounterpartyTable, TaskInbox, owner access grants
L4 Shield	twin3.shield	Differential tampering defense, prompt injection filtering, and authorization guardrails.	scan_text / scan_envelope (T0–T3), IntelEngine (T1), Ensemble (T4), diff_plans / authorize_execution (T5), MemoryGuard
L5 Matrix	twin3.matrix	High-density vector space topological mapping and semantic cosine matching.	DenseVector256, feature_distance, HumanMatrixSchema, EnterpriseMatrixSchema
L6 Settlement	twin3.settlement	Signed-receipt verification for HTTP 402 gates, with externally supplied chain-finality and replay controls.	PaymentDemand, PaymentReceipt, X402SettlementEngine
L7 Governance	twin3.governance	Immutable evidence trail, appeals, advisory reputation federation, provisional arbitration helper.	EvidenceTrail, open_appeal / resolve_appeal, export_reputation / import_reputation, ArbitrationEngine (experimental), DisputeCase (experimental)

(experimental) marks a capability whose row in tests/capability-inventory.json is not yet available: it is importable today and its surface may still change. Everything unmarked is available. A name written Class.method is a method, not a module export. Every name in this table is checked against a real public export by tests/test_readme_capability_claims.py.

---

3. Pull Request Lineage & Provenance

The primitives in twin3-sdk are extracted from the twin3-team/agent-id Inbox line (PRs #615–#642, merged 2026-09-03 → 2026-09-05; spec: docs/architecture/inbox-module-spec.md in that repo). What each layer inherited:

• Envelope, KYA handshake, counterparty ladder — agent_id/inbox/{envelope,kya,counterparty}.py: canonical-JSON signed envelopes with authority:"none", the mutual Ed25519 challenge that binds a declared identity to a key, and the G0→G3 attention ladder keyed on the counterparty rather than the request.
• Task inbox and state machine — agent_id/inbox/state.py: intake gate, review gate, rate limits, stale expiry, hash-chained audit.
• Shield T0–T5 — agent_id/inbox/{shield,intel,classifier,plandiff,corpus}.py: deterministic layers, URL/domain/hash intelligence, the T4 ensemble, plan diffing, and the corpus that publishes error rates.
• Settlement policy — agent_id/inbox/payments.py: owner policy, signed quotes and receipts behind HTTP 402.
• Governance — agent_id/inbox/governance.py: appeals, pardons, advisory reputation federation.
• Canonical Matrix Core: High-density 256-Byte vector topological clustering powering 140k natural human personality profiles and industrial tolerance matching.

The 2026-09-05 sync also adds the AI-era hardening (mandatory T5, identity-cost tier caps, provenance-gated memory, rotation demotes, paid ≠ authorized). See CHANGELOG.md.

---

4. Package Distribution & Integration Model

Why Not File Copying?

Copying code (vendoring) causes protocol drift where Agent ID and Human ID implementations diverge within weeks, breaking cross-network signature validation.

Why Not Pure HTTP Microservices?

Cryptographic signatures (ECDSA/Ed25519) and 256-bit vector operations execute in under 0.2 milliseconds locally. Routing them through remote HTTP hops adds unnecessary latency and exposes private signing keys to network attack vectors.

The Standard Solution: Semantic Package Dependencies

Twin3 SDK follows standard modern packaging conventions (pyproject.toml / npm). Production consumers must use immutable registry artifacts and exact version pins; local links are development-only.

1. Development Mode (Local Symlink / Editable Install)

During local development, both agent-id and XHuman_ID link directly to the local SDK workspace:

# In agent-id or XHuman_ID virtual environment:
pip install -e /path/to/twin3-sdk

Benefits:

• Zero code duplication.
• Any protocol or algorithm improvement in twin3-sdk is reflected in both applications in 0 milliseconds.

2. Production Distribution

The next release candidate is 0.2.10-pre-alpha for npm and 0.2.10a0 for Python. It is not a production dependency until the GitHub release workflows have built, attested, rehearsed, and published the exact tagged artifacts. Consumers must then pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This candidate stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is next, not latest.

package.json engines sets Node.js to >=18 and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.

After the release workflow has published that exact version, install the pin. These commands are not evidence that the registry already serves the package:

npm install twin3-sdk@0.2.10-pre-alpha
pip install twin3-sdk==0.2.10a0

Until publication, evaluate the packed npm tarball only. Do not install from a git URL or a version range:

npm pack --ignore-scripts
npm install ./twin3-sdk-0.2.10-pre-alpha.tgz

---

5. Dual-Application Projections

🏢 Agent ID (Enterprise Commerce Projection)

Agent ID consumes Twin3 SDK to execute the 5-Stage A2A Autonomous Commercial Loop:

1. Discovery: Queries twin3.discovery for available suppliers and verified agent cards.
2. Understand: Uses twin3.matrix to compute tolerance matching against industrial RFQs.
3. Negotiate: Uses twin3.comm and twin3.shield to exchange signed quotes without prompt-tampering risks.
4. Settle: Uses the Twin3 signed-receipt adapter at an HTTP 402 gate. Acceptance additionally requires a trusted signer key, a chain-specific finality verifier, and a shared replay store.
5. Dispute: Invokes twin3.governance to resolve contractual non-performance.

👤 Human ID (Personal Sovereignty Projection)

Human ID consumes Twin3 SDK to empower natural individuals:

1. 140,000 Real Personality Assets: Computes high-density personality matching via twin3.matrix without risking underlying database schemas.
2. Passkey WebAuthn Login: Binds biometric secure enclaves to decentralized keys via twin3.trust.
3. Paid Inbox: Protects individual inboxes against spam using twin3.comm and the signed-receipt adapter ($5 paywall threshold); the application supplies chain verification and shared replay state.
4. Sovereign Card: Renders non-custodial credentials using twin3.discovery.

---

6. Directory Structure

twin3-sdk/
├── pyproject.toml               # Standard packaging definition (PEP 621)
├── README.md                    # Canonical English manual
├── LICENSE                      # Proprietary licence, all rights reserved
├── js/index.js                  # Node runtime; js/comm/counterparty.js = Inbox line, counterparty side
├── twin3/                       # Core SDK namespace
│   ├── __init__.py
│   ├── _compat.py               # One import surface mirroring agent_id.inbox
│   ├── discovery/               # L1: Cards, Endpoints, agents.json, public inbox declaration
│   ├── trust/                   # L2: KYA Handshake, did:web, Passkey Adapter
│   ├── comm/                    # L3: Envelope, Counterparty Table, TaskInbox, export, client (counterparty side)
│   ├── shield/                  # L4: T0–T3 defense, T1 intel, T4 classifier, T5 plan diff, corpus, memory gate
│   ├── matrix/                  # L5: 256-Byte Vector Topology Engine
│   ├── settlement/              # L6: HTTP 402 Micropayments, owner policy, quotes, receipts
│   └── governance/              # L7: Evidence Trail, Arbitration, appeals, federation
└── tests/                       # Hermetic standalone Python and Node test suites
    ├── test_{discovery,trust,comm,shield,matrix,settlement,governance}.py
    ├── test_{envelope,counterparty,kya_gate,inbox_gate,plan_diff_gate}.py   # ported contracts
    ├── test_{classifier,intel,corpus_eval,settlement_policy,governance_gate,declaration,export}.py
    └── test_ai_era_hardening.py                                              # the five hardening rules

---

7. License

Proprietary. All rights reserved. Twin3 SDK is not open-source software. See LICENSE for the exact terms.

Distribution artifacts are published to public package registries so that anyone can install and evaluate the SDK and build against it — open access is not open source. Public availability grants no right to copy, modify, redistribute, fork, or create derivative works, and no patent or trademark licence. For commercial licensing or redistribution rights, contact core@twin3.ai.