twin3-sdk 0.0.0-stage → 0.2.10-pre-alpha

package/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.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# Twin3 SDK (`twin3-sdk`)
+> **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[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.

package/human-score.d.ts

@@ -0,0 +1,70 @@
+export type PolicyId = 'HV-LADDER-BETA-1';
+export type MethodId = 'google'|'passkey'|'telegram'|'line'|'discord'|'totp'|'recaptcha';
+export class HumanScoreError extends Error { readonly code:string; constructor(code:string); }
+export interface HumanScorePolicy {
+  readonly policy_id:PolicyId; readonly policy_hash:string; readonly release_state:'candidate';
+  readonly algorithm_version:'human-score-ladder-v1'; readonly schema_version:'human-score-ladder-v1';
+  readonly scale:Readonly<{min:0;max:255;decimals:0}>; readonly raw_scale:Readonly<{min:0;max:255}>;
+  readonly methods:readonly MethodId[];
+  readonly anchor:Readonly<{methods:readonly ['google','passkey'];raw_points:60;aggregation:'max'}>;
+  readonly additive_methods:Readonly<{telegram:45;line:30;discord:30;totp:20;recaptcha:5}>;
+  readonly requires_anchor:true; readonly technical_raw_cap:190; readonly social_raw_cap:65; readonly total_raw_cap:255;
+  readonly technical_validity:string;
+  readonly social:Readonly<{exponent:2;direct_floor:0.75;previous_mix:0.25;budget:5;max_targets:20;saturation_mass:10;full_days:90;end_days:180}>;
+  readonly epoch:Readonly<{interval_ms:number;freshness_ms:number}>;
+  readonly mint:Readonly<{enabled:false;reason:'ladder_mint_policy_not_approved'}>;
+}
+export type MethodEvidence = {status:'passed';verified_at:string;expires_at:string} |
+  {status:'not_completed'|'failed'|'revoked'|'unknown'} | null;
+export type EvidenceMap = Readonly<Record<MethodId,MethodEvidence>>;
+export interface TechnicalResult {
+  readonly anchor_present:boolean; readonly anchor_raw:number; readonly technical_raw:number;
+  readonly additive_raw:Readonly<Record<'telegram'|'line'|'discord'|'totp'|'recaptcha',number>>;
+  readonly pending_anchor_methods:readonly MethodId[];
+}
+export interface ScoreSubject {subject_id:string;created_at:string;method_evidence:EvidenceMap;}
+export interface WitnessEdge {
+  id:string;source_subject_id:string;target_subject_id:string;statement_version:'human_witness_v1'|'support_v1';
+  status:'accepted'|'pending'|'revoked'|'blocked';accepted_at?:string;confirmed_at?:string;
+}
+interface SnapshotBase {
+  readonly schema_version:'human-score-ladder-v1';readonly subject_id:string;
+  readonly policy_id:PolicyId;readonly policy_hash:string;readonly epoch_id:string;
+  readonly as_of:string;readonly computed_at:string;readonly next_scheduled_at:string;readonly fresh_until:string;
+  readonly scale:Readonly<{min:0;max:255;decimals:0}>;readonly received_count:number;readonly outgoing_count:number;
+  readonly seed_reason:'policy_activation'|'new_subject'|null;readonly reasons:readonly string[];
+}
+export interface ReadyScoreSnapshot extends SnapshotBase {
+  readonly status:'ready';readonly score:number;readonly score_units:number;readonly social_reputation_units:number;
+  readonly technical_raw:number;readonly social_raw:number;readonly total_raw:number;readonly anchor_present:boolean;
+  readonly breakdown:TechnicalResult;readonly effective_mass:number;readonly counted_source_count:number;
+}
+export interface UnavailableScoreSnapshot extends SnapshotBase {
+  readonly status:'unavailable';readonly score:null;readonly score_units:null;readonly social_reputation_units:null;
+}
+export type ScoreSnapshot = ReadyScoreSnapshot|UnavailableScoreSnapshot;
+export interface PreviousEpoch {
+  schema_version:'human-score-ladder-epoch-v1';policy_id:PolicyId;policy_hash:string;epoch_id:string;as_of:string;status:'complete';
+  snapshots:readonly ({subject_id:string}&(
+    {status:'ready';score_units:number;social_reputation_units:number}|
+    {status:'unavailable'|'invalidated';score_units:null;social_reputation_units:null}))[];
+}
+export type EpochInput = {
+  policy_id:PolicyId;policy_hash:string;as_of:string;computed_at:string;
+  coverage:{subjects:true;evidence:true;witnesses:true};subjects:readonly ScoreSubject[];edges:readonly WitnessEdge[];
+}&({mode:'policy_activation';activation_as_of:string;previous:null}|{mode:'daily';previous:PreviousEpoch});
+export interface HumanScoreEpoch extends PreviousEpoch {readonly snapshots:readonly ScoreSnapshot[];}
+export function getHumanScorePolicy(id:PolicyId):HumanScorePolicy;
+export function scoreUnits(value:number):number;
+export function rawToHumanScore(raw:number):number;
+export function freshnessFactor(ageDays:number,fullDays?:number,endDays?:number):number;
+export function calculateTechnicalScore(evidence:EvidenceMap,asOf:string):Readonly<TechnicalResult>|null;
+export function socialRaw(mass:number):number;
+export function socialEdgeWeight(input:{technical_raw:number;previous_score_units:number;outgoing_count:number;age_days:number}):number;
+export function previewTechnicalDelta(input:{evidence:EvidenceMap;as_of:string;method_id:MethodId;social_raw?:number}):Readonly<
+  {status:'unavailable';delta_units:null;authorization_required:true}|
+  {status:'conditional';technical_raw_before:number;technical_raw_after:number;delta_units:number;same_epoch_only:true;authorization_required:true}>;
+export function calculateHumanScoreEpoch(input:EpochInput):HumanScoreEpoch;
+export function evaluateHumanScoreThresholds(snapshot:ScoreSnapshot):Readonly<{
+  meets_thresholds:false;mint_authorized:false;authorization_required:true;reasons:readonly string[];
+}>;