twin3-sdk 0.2.10a0__tar.gz

twin3_sdk-0.2.10a0/LICENSE

@@ -0,0 +1,67 @@
+Twin3 SDK Proprietary License
+
+Copyright (c) 2026 Twin3 AI Limited (the "Licensor"). All rights reserved.
+
+This software, together with its documentation, specifications, protocol
+designs, test vectors, and cryptographic constructions (the "Software"), is the
+proprietary property of the Licensor. It is not open-source software. Making a
+distribution artifact publicly downloadable from a package registry or source
+host does not place the Software in the public domain, does not grant any
+open-source licence, and does not waive any right reserved below.
+
+1. Limited licence
+   Subject to continuous compliance with these terms, the Licensor grants you a
+   personal, non-exclusive, non-transferable, non-sublicensable, revocable
+   licence to download, install, and execute unmodified official distribution
+   artifacts of the Software, solely to evaluate the Software and to build and
+   operate applications that interoperate with it.
+
+2. Restrictions
+   Except where applicable law expressly prohibits such a restriction, you may
+   not: copy the Software beyond what is required to exercise the licence in
+   section 1; modify, adapt, translate, or create derivative works of the
+   Software; redistribute, publish, sublicense, sell, rent, lease, or provide
+   the Software to any third party, whether standalone or embedded in another
+   product or service; remove, obscure, or alter any proprietary or attribution
+   notice; or reverse engineer, decompile, or disassemble the Software.
+
+3. Reservation of rights
+   All rights not expressly granted in section 1 are reserved by the Licensor,
+   including every copyright, patent, trade secret, trademark, database, and
+   other intellectual property right in the Software. No patent licence is
+   granted by implication, estoppel, or otherwise. No trademark licence is
+   granted.
+
+4. Contributions and derivative work
+   Nothing in this licence grants any right to fork the Software, publish a
+   derivative of it, or contribute to it. Any such activity requires prior
+   written permission from the Licensor.
+
+5. Termination
+   This licence terminates automatically and immediately upon any breach of
+   these terms. On termination you must stop using the Software and destroy all
+   copies in your possession or control. Sections 2, 3, 6, 7, and 8 survive
+   termination.
+
+6. No warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. THE SOFTWARE
+   IMPLEMENTS SECURITY AND SETTLEMENT PROTOCOLS; THE LICENSOR DOES NOT WARRANT
+   THAT IT IS FREE OF DEFECTS OR FIT FOR ANY PARTICULAR DEPLOYMENT.
+
+7. Limitation of liability
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSOR SHALL NOT BE
+   LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+   CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+   SOFTWARE OR ITS USE, INCLUDING ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS,
+   REVENUE, DATA, OR DIGITAL ASSETS.
+
+8. Entire terms
+   These terms are the entire licence for the Software and supersede any prior
+   or contemporaneous understanding. A separate written agreement signed by the
+   Licensor may grant broader rights; only that agreement can vary these terms.
+
+For commercial licensing, redistribution rights, or any permission not granted
+above, contact core@twin3.ai.

twin3_sdk-0.2.10a0/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include twin3 *.py
+prune .github
+prune docs
+prune release
+prune tests
+exclude API.md
+exclude API_ZH.md
+exclude CHANGELOG.md
+exclude CONTRIBUTING.md
+exclude README_ZH.md
+exclude index.d.ts
+exclude package.json
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude .DS_Store

twin3_sdk-0.2.10a0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: twin3-sdk
+Version: 0.2.10a0
+Summary: The Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans
+Author-email: Twin3 AI Limited <core@twin3.ai>
+License-Expression: LicenseRef-Twin3-Proprietary
+Project-URL: Homepage, https://github.com/twin3-team/twin3-sdk
+Project-URL: Repository, https://github.com/twin3-team/twin3-sdk.git
+Project-URL: Documentation, https://github.com/twin3-team/twin3-sdk/blob/main/README.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# Twin3 SDK (`twin3-sdk`)
+> **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**
+
+[English](README.md) | [繁體中文](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![Architecture: 7-Layer Symbiosis](https://img.shields.io/badge/Architecture-7--Layer%20Symbiosis-success.svg)](#the-seven-layer-symbiotic-architecture)
+[![Dual-Projection](https://img.shields.io/badge/Dual--Use-Agent%20ID%20%7C%20Human%20ID-orange.svg)](#dual-application-projections)
+[![Repo: twin3-team/twin3-sdk](https://img.shields.io/badge/GitHub-twin3--team%2Ftwin3--sdk-purple.svg)](https://github.com/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`](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`](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:
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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`](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.

twin3_sdk-0.2.10a0/README.md

@@ -0,0 +1,176 @@
+# Twin3 SDK (`twin3-sdk`)
+> **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**
+
+[English](README.md) | [繁體中文](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![Architecture: 7-Layer Symbiosis](https://img.shields.io/badge/Architecture-7--Layer%20Symbiosis-success.svg)](#the-seven-layer-symbiotic-architecture)
+[![Dual-Projection](https://img.shields.io/badge/Dual--Use-Agent%20ID%20%7C%20Human%20ID-orange.svg)](#dual-application-projections)
+[![Repo: twin3-team/twin3-sdk](https://img.shields.io/badge/GitHub-twin3--team%2Ftwin3--sdk-purple.svg)](https://github.com/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`](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`](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:
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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`](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.

twin3_sdk-0.2.10a0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools==80.9.0", "wheel==0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "twin3-sdk"
+version = "0.2.10a0"
+description = "The Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Twin3-Proprietary"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Twin3 AI Limited", email = "core@twin3.ai" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "cryptography>=42.0.0",
+]
+
+[project.scripts]
+twin3 = "twin3.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["twin3*"]
+exclude = ["tests*"]
+
+[tool.setuptools]
+include-package-data = false
+
+[project.urls]
+Homepage = "https://github.com/twin3-team/twin3-sdk"
+Repository = "https://github.com/twin3-team/twin3-sdk.git"
+Documentation = "https://github.com/twin3-team/twin3-sdk/blob/main/README.md"

twin3_sdk-0.2.10a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

twin3_sdk-0.2.10a0/twin3/__init__.py

@@ -0,0 +1,40 @@
+"""Twin3 SDK — The Universal Capability Motherboard for AI Agents & Sovereign Humans.
+
+Seven-Layer Symbiotic Architecture:
+- L1: twin3.discovery    (Twin3AgentCard, SovereignCard, declaration, signed descriptors, catalog, adapters)
+- L2: twin3.trust        (KYA Handshake, Passkey Binding, Ed25519)
+- L3: twin3.comm         (HMAC/ECDSA Envelope, Counterparty Table)
+- L4: twin3.shield       (T0-T5 Deterministic Defense, Plan Diff)
+- L5: twin3.matrix       (256-Byte Vector Topology, Cosine Distance)
+- L6: twin3.settlement   (HTTP 402 Micropayments, Clearing Protocol)
+- L7: twin3.governance   (Evidence Trail, Dispute Arbitration)
+"""
+
+__version__ = "0.2.10a0"
+__author__ = "Twin3 AI Limited"
+
+from . import jcs
+from . import discovery
+from . import trust
+from . import comm
+from . import shield
+from . import matrix
+from . import settlement
+from . import governance
+
+inbox = comm
+action = governance
+
+__all__ = [
+    "__version__",
+    "jcs",
+    "discovery",
+    "trust",
+    "comm",
+    "inbox",
+    "shield",
+    "matrix",
+    "action",
+    "settlement",
+    "governance",
+]

twin3_sdk-0.2.10a0/twin3/_compat.py

@@ -0,0 +1,25 @@
+"""twin3._compat: one import surface for the Inbox line, mirroring agent_id.inbox.
+
+Applications that were written against agent_id.inbox can switch with a
+single import change. New code should import from the layer modules."""
+from twin3.comm.counterparty import *  # noqa: F401,F403
+from twin3.comm.counterparty import CounterpartyTable, IdentityRequired, TierTransitionError, counterparty_key, decay_reputation, FREEZE_STRIKES, REPUTATION_HALF_LIFE_SECONDS  # noqa: F401
+from twin3.comm.envelope import *  # noqa: F401,F403
+from twin3.comm.envelope import build_envelope, envelope_digest, validate_envelope, EnvelopeLimits, EnvelopeRejected, ENVELOPE_SCHEMA  # noqa: F401
+from twin3.comm.inbox import *  # noqa: F401,F403
+from twin3.comm.inbox import TaskInbox, IntakeRejected, TransitionError, STATES, TRANSITIONS  # noqa: F401
+from twin3.comm.export import EXPORT_SCHEMA, export_task  # noqa: F401
+from twin3.trust.kya import *  # noqa: F401,F403
+from twin3.trust.kya import HandshakeError, create_challenge, complete_challenge, challenge_signature_payload, verify_owner_signature, sign_envelope, verify_envelope_signature, load_public_key, load_private_key, export_public_key, key_id, CHALLENGE_SCHEMA  # noqa: F401
+from twin3.trust.didweb import DidResolutionError, did_web_for_host, did_web_url, resolve_did_web  # noqa: F401
+from twin3.shield.defense import SHIELD_SCHEMA, ShieldVerdict, scan_text, scan_envelope  # noqa: F401
+from twin3.shield.plan_diff import AUTHORIZED_BY_KIND, PLANDIFF_SCHEMA, PlanDiffError, diff_plans, normalize_action, PlanDiffGuard, authorize_execution  # noqa: F401
+from twin3.shield.classifier import T4_SCHEMA, CallableClassifier, ClassifierUnavailable, Ensemble, HeuristicClassifier, HuggingFaceClassifier, ScamHeuristicClassifier, Score, default_ensemble  # noqa: F401
+from twin3.shield.intel import INTEL_SCHEMA, CallableFeed, FeedUnavailable, IntelEngine, LocalBlocklist, RdapDomainAge, URLhausFeed, YaraScanner, extract_domains, extract_urls, is_idn_homograph, registrable, typosquat_match  # noqa: F401
+from twin3.shield.corpus import CORPUS_SCHEMA, EVAL_SCHEMA, CorpusError, ShieldScorer, evaluate, gate, load_corpus, load_shard, validate_sample  # noqa: F401
+from twin3.shield.corpus_seed import SEED  # noqa: F401
+from twin3.shield.memory import MEMORY_SCHEMA, MemoryGuard, MemoryRejected  # noqa: F401
+from twin3.settlement.policy import DEFAULT_POLICY, POLICY_SCHEMA, QUOTE_SCHEMA, RECEIPT_SCHEMA, PaymentError, issue_receipt, normalize_policy, quote, verify_receipt  # noqa: F401
+from twin3.settlement.x402 import X402_DEMAND_SCHEMA, X402_RECEIPT_SCHEMA, REPLAY_RESERVATION_SECONDS, REPLAY_FINAL_EXPIRY, SettlementError, PaymentDemand, PaymentReceipt, ChainPaymentEvidence, ChainPaymentVerifier, X402SettlementEngine  # noqa: F401
+from twin3.governance.federation import APPEAL_SCHEMA, BUNDLE_SCHEMA, GovernanceError, export_reputation, import_reputation, list_appeals, open_appeal, resolve_appeal  # noqa: F401
+from twin3.discovery.declaration import DECLARATION_SCHEMA, build_declaration, can_stranger_decide  # noqa: F401