twin3-sdk 0.2.19-pre-alpha → 0.2.21-pre-alpha

package/README.md

@@ -116,7 +116,7 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-`v0.2.19-pre-alpha` is the current release candidate: `0.2.19-pre-alpha` for npm and `0.2.19a0` for PyPI. It is published from reviewed main through the existing Cloud Build tag trigger. 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`.
+`v0.2.21-pre-alpha` is the current release candidate: `0.2.21-pre-alpha` for npm and `0.2.21a0` for PyPI. Publication is pending approval and uses reviewed main through the existing Cloud Build tag trigger. 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`.
 
 The additive `twin3-sdk/runtime` subpath provides a single-action Agent runtime candidate. Products retain authenticated authority, context egress consent, durable storage and trusted tool brokers. Python `twin3.runtime` provides compatible contracts and digests only. OpenShell, ADK and Hermes adapters are not included. See [runtime scope and limits](docs/architecture/PERSONAL-AGENT-RUNTIME-V1.md).
 
@@ -125,15 +125,15 @@ The additive `twin3-sdk/runtime` subpath provides a single-action Agent runtime
 After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.19-pre-alpha
-pip install twin3-sdk==0.2.19a0
+npm install twin3-sdk@0.2.21-pre-alpha
+pip install twin3-sdk==0.2.21a0
 ```
 
 For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.19-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.21-pre-alpha.tgz
 ```
 
 ---
@@ -146,6 +146,9 @@ Agent ID consumes Twin3 SDK to execute the **5-Stage A2A Autonomous Commercial L
 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.
+
+Settlement integrations must follow the [x402 security boundaries](docs/x402-security-boundaries.md),
+including case-sensitive wallet binding, canonical network names and durable payment recovery.
 5. **Dispute**: Invokes `twin3.governance` to resolve contractual non-performance.
 
 ### 👤 Human ID (Personal Sovereignty Projection)

package/index.d.ts

@@ -224,6 +224,85 @@ export interface EngineObservationReading {
 export declare function normalizeEngineObservation(row: EngineObservationInput, options: { host: string }): EngineObservation;
 export declare function summarizeEngineObservations(observations: EngineObservation[], options: { host: string; sourceLevel?: boolean }): EngineObservationReading;
 export declare function summarizeCohortVisibility(readingsBySubject: Record<string, EngineObservationReading>, subjectId: string, options?: { minCohortSize?: number }): Record<string, any>;
+export declare class AiVisibilityError extends Error { code: string; }
+export declare const AI_REFERRAL_SCHEMA: "twin3-discovery-ai-referral-v1";
+export declare const AI_CRAWLER_SCHEMA: "twin3-discovery-ai-crawler-v1";
+export declare const AI_READINESS_SCHEMA: "twin3-discovery-ai-readiness-v1";
+export declare const AI_TRAJECTORY_SCHEMA: "twin3-discovery-ai-trajectory-v1";
+export type AiCrawlerPurpose = "training" | "search" | "user" | "agent" | "control";
+export type AiTrajectoryStage = "crawled" | "search_indexed" | "user_fetched" | "retrieved" | "mentioned" | "cited" | "clicked";
+export interface AiVisibilityCatalog {
+  version: number;
+  checked_on: string;
+  provenance: Array<{ name: string; url: string; license: string; used: string[] }>;
+  referral_sources: Array<{ key: string; operator: string; hosts: string[]; aliases: string[]; surfaces?: Array<{ key: string; medium: string }>; referrer_path?: string; utm?: boolean }>;
+  crawlers: Array<{ token: string; operator: string; purpose: AiCrawlerPurpose; robots: string; user_agent: boolean; claim?: string }>;
+  stages: Array<{ key: AiTrajectoryStage; en: string; "zh-TW": string }>;
+}
+export declare const AI_VISIBILITY_CATALOG: AiVisibilityCatalog;
+export interface AiReferral {
+  schema: "twin3-discovery-ai-referral-v1";
+  source: string;
+  operator: string;
+  origin: "referrer" | "utm";
+  surface: string | null;
+  catalog_version: number;
+}
+export interface AiCrawler {
+  schema: "twin3-discovery-ai-crawler-v1";
+  token: string;
+  operator: string;
+  purpose: AiCrawlerPurpose;
+  robots: string;
+  catalog_version: number;
+}
+export interface AiReadinessCheck {
+  id: string;
+  priority: "P0" | "P1" | "P2" | "P3";
+  status: "pass" | "warn" | "fail" | "info" | "na";
+  evidence: Record<string, unknown>;
+  action: string | null;
+}
+export interface AiReadinessReport {
+  schema: "twin3-discovery-ai-readiness-v1";
+  host: string;
+  path: string;
+  catalog_version: number;
+  checks: AiReadinessCheck[];
+  crawler_access: Record<string, { operator: string; purpose: AiCrawlerPurpose; allowed: boolean; matched: "named" | "star" | "none" }>;
+  gate: { passed: boolean; blocking: string[] };
+  actions: Array<{ check: string; priority: "P0" | "P1" | "P2" | "P3"; action: string }>;
+  non_claims: string[];
+  digest: string;
+}
+export interface AiTrajectorySignal { state: "measured" | "withheld" | "unknown"; rate_bp: number | null; }
+export interface AiTrajectoryOperator {
+  crawl: Record<"training" | "search" | "user" | "agent" | "other", number>;
+  refused: number;
+  engines: Record<string, Record<"retrieved" | "mentioned" | "cited", AiTrajectorySignal> & { answer_visibility_bp: number | null }>;
+  clicks: number;
+  click_sources: Record<string, number>;
+  click_surfaces: Record<string, number>;
+  stages: AiTrajectoryStage[];
+}
+export interface AiTrajectory {
+  schema: "twin3-discovery-ai-trajectory-v1";
+  host: string;
+  catalog_version: number;
+  operators: Record<string, AiTrajectoryOperator>;
+  totals: { fetched_requests: number; refused_requests: number; unclassified_requests: number; ai_sessions: number; non_ai_sessions: number };
+  reading_digest: string | null;
+  reading_valid: boolean | null;
+  unattributed_engines: string[];
+  score_weights: { mentioned: number; cited: number; divisor: number; source: string };
+  non_claims: string[];
+  digest: string;
+}
+export interface AiReferralRow { referrer?: string | null; landing_url?: string | null; utm_source?: string | null; sessions?: number; }
+export declare function classifyAiReferral(referrer?: string | null, options?: { landingUrl?: string | null; utmSource?: string | null }): AiReferral | null;
+export declare function classifyAiCrawler(userAgent: string): AiCrawler | null;
+export declare function auditAiReadiness(options: { host: string; path?: string; robotsTxt?: string | null; html?: string | null; llmsTxt?: string | null }): AiReadinessReport;
+export declare function summarizeAiTrajectory(options: { host: string; visits?: DiscoveryVisitEvidence[]; reading?: EngineObservationReading | null; referrals?: AiReferralRow[]; engineOperators?: Record<string, string> | null }): AiTrajectory;
 export declare function buildSignedReferral(options: Record<string, any>): Record<string, any>;
 export declare function verifySignedReferral(token: Record<string, any>, options: Record<string, any>): Record<string, any>;