Twin3 SDK (twin3-sdk)

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

English | Traditional Chinese | 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 (experimental), open_appeal / resolve_appeal, export_reputation / import_reputation, ArbitrationEngine (experimental), DisputeCase (experimental)

L1 also exposes a candidate discovery evidence API for xAgent ID and xHuman ID. It normalizes owner-supplied CDN/server visits and Google Search Console generative AI search exports, then returns separate visit and impression summaries and a display-ready view model. See the L1 evidence contract and interface presentation guidance. These APIs do not collect private logs or establish visitor identity on their own.

Python and Node support explicit Matrix comparison profiles, including weighted/masked cosine and structured coverage results. Node constructor coercions still differ. Node TaskInbox admits owner-policy receipts with applyPayment and injected-verifier receipts with applyX402Payment. Evidence trail is experimental until an actual consumer supplies durable integration evidence.

(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:

The paths below describe historical source in the Agent ID repository, not the current SDK directory layout. See the generated Node API reference for the installed package's public declarations.

• 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: 256-dimensional single-pair vector arithmetic and tolerance comparison. The SDK does not supply population clustering, a similarity index or a batch ranking engine.

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

v0.2.17-pre-alpha is the current release candidate: 0.2.17-pre-alpha for npm and 0.2.17a0 for PyPI. It is published from main through the Cloud Build tag trigger; the previous version number was never published. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release 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 requires Node.js >=22.23.4 and does not set an npm engine. CI covers patched Node 22, 24 and 26; Node 18 and 20 are outside the supported baseline. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.

After publication, install the exact released version from the registry:

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

For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:

npm pack --ignore-scripts
npm install ./twin3-sdk-0.2.17-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. Personality Assets: Uses twin3.matrix for single-pair vector comparisons. Population indexing, ranking throughput and storage remain product responsibilities.
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.