twin3-sdk 0.2.14-pre-alpha → 0.2.17-pre-alpha

package/README.md

@@ -66,7 +66,8 @@ L1 also exposes a candidate discovery evidence API for xAgent ID and xHuman ID.
 
 Python and Node support [explicit Matrix comparison profiles](docs/matrix-runtime-profiles.md),
 including weighted/masked cosine and structured coverage results. Node constructor
-coercions still differ; Node Inbox payment admission remains Python-only. Evidence
+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`](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).
@@ -115,22 +116,22 @@ 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.14-pre-alpha` is the current release candidate: `0.2.14-pre-alpha` for npm and `0.2.14a0` for PyPI. Publication is pending. 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.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` 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.
+`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:
 
 ```bash
-npm install twin3-sdk@0.2.14-pre-alpha
-pip install twin3-sdk==0.2.14a0
+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:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.14-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.17-pre-alpha.tgz
 ```
 
 ---

package/index.d.ts

@@ -158,6 +158,71 @@ export interface DiscoveryEvidenceView {
   digest: string;
 }
 export declare function buildDiscoveryEvidenceView(summary: DiscoveryEvidenceSummary, options: { visitSourceStatus: "connected" | "not_connected"; googleAiSearchSourceStatus: "connected" | "not_connected" }): DiscoveryEvidenceView;
+export declare const ENGINE_OBSERVATION_SCHEMA: "twin3-discovery-engine-observation-v1";
+export declare const ENGINE_READING_SCHEMA: "twin3-discovery-engine-reading-v1";
+export declare class EngineObservationError extends Error { code: string; }
+export type EngineObservationEvidenceLevel = "server_observed_engine_answer" | "replay_api" | "owner_supplied_platform_export";
+export interface EngineObservationInput {
+  engine: string;
+  prompt_id: string;
+  observed_at: number;
+  status: "answered" | "error";
+  model?: string | null;
+  need_id?: string | null;
+  paraphrase_of?: string | null;
+  run_id?: string | null;
+  host?: string | null;
+  retrieved?: boolean | null;
+  mentioned?: boolean | null;
+  cited?: boolean | null;
+  evidence_level?: EngineObservationEvidenceLevel;
+  evidence_strength?: EngineObservationEvidenceLevel;
+  answer?: string | null;
+  answer_digest?: string | null;
+  [extra: string]: unknown;
+}
+export interface EngineObservation {
+  schema: "twin3-discovery-engine-observation-v1";
+  host: string;
+  engine: string;
+  model: string | null;
+  prompt_id: string;
+  need_id: string | null;
+  run_id: string | null;
+  observed_at: number;
+  status: "answered" | "error";
+  retrieved: boolean | null;
+  mentioned: boolean | null;
+  cited: boolean | null;
+  evidence_level: EngineObservationEvidenceLevel;
+  answer_digest: string | null;
+  digest: string;
+}
+export interface EngineObservationSignalReading {
+  state: "measured" | "withheld" | "unknown";
+  observed: number;
+  positive: number;
+  rate_bp: number | null;
+  interval_bp: [number, number] | null;
+}
+export interface EngineObservationReading {
+  schema: "twin3-discovery-engine-reading-v1";
+  host: string;
+  valid: boolean;
+  source_level: boolean;
+  blockers: Array<"no_answered_observations" | "insufficient_repetitions" | "insufficient_paraphrases">;
+  caveats: Array<"window_shorter_than_21_days">;
+  window_utc: { first: string; last: string; span_days: number; observed_days: number } | null;
+  engines: string[];
+  by_engine: Record<string, { answered: number; errors: number; prompts: number; signals: Record<"retrieved" | "mentioned" | "cited", EngineObservationSignalReading> }>;
+  evidence_levels: EngineObservationEvidenceLevel[];
+  protocol: { min_runs_per_prompt: number; min_runs_for_source_coverage: number; min_paraphrases_per_need: number; window_days: number; interval: string; source: string };
+  non_claims: string[];
+  observation_digests: string[];
+  digest: string;
+}
+export declare function normalizeEngineObservation(row: EngineObservationInput, options: { host: string }): EngineObservation;
+export declare function summarizeEngineObservations(observations: EngineObservation[], options: { host: string; sourceLevel?: boolean }): EngineObservationReading;
 
 export declare const DESCRIPTOR_CANONICALIZATION: "rfc8785";
 export declare const DESCRIPTOR_SIGNATURE_FIELDS: readonly ["signatures", "signatureStatus"];
@@ -848,6 +913,21 @@ export interface KyaBinding {
   receipt: string;
 }
 
+export declare class DidResolutionError extends Error { readonly code: string; }
+export declare function didWebForHost(host: string): string;
+export declare function didWebUrl(did: string): string;
+export declare function resolveDidWeb(did: string, fetch: (method: string, url: string, headers: Record<string, string>, body: null) => [number, string | Uint8Array | null], maxBytes?: number): { did: string; url: string; method_id: string; key_id: string; public_key: string; };
+export declare function multibaseEd25519(raw: Uint8Array, multicodec?: boolean): string;
+export type DidFetch = (method: string, url: string, headers: Record<string, string>, body: null) => [number, string | Uint8Array | null];
+export type DidKeyPurpose = "assertionMethod" | "authentication" | "keyAgreement" | "capabilityInvocation" | "capabilityDelegation";
+export interface DidDocumentKey { did: string; method_id: string; key_id: string; public_key: string; purpose: DidKeyPurpose | null; }
+/** Ed25519 verification methods of a did:web document, restricted to the requested verification relationship (default `assertionMethod`). */
+export declare function didWebDocumentKeys(doc: Record<string, unknown>, did: string, options?: { purpose?: DidKeyPurpose | null }): DidDocumentKey[];
+/** Resolve one did:web key through the injected fetch; `kid` must select exactly one method (`did_kid_not_found` / `did_kid_ambiguous`). */
+export declare function resolveDidWebKey(did: string, fetch: DidFetch, options?: { kid?: string | null; purpose?: DidKeyPurpose | null; maxBytes?: number }): DidDocumentKey & { url: string };
+/** Select one Ed25519 (`OKP`/`Ed25519`, `alg` EdDSA if present) key from a JWKS by `kid`. */
+export declare function jwksKey(jwks: Record<string, unknown>, kid: string): { kid: string; key_id: string; public_key: string };
+export declare const AuthorityAnchor: { readonly SUPPORTED_KINDS: readonly string[]; isValidKind(kind: string): boolean; };
 export declare function createKyaChallenge(params: {
   owner: string;
   identity: KyaIdentity;
@@ -900,6 +980,9 @@ export interface TrustDelegation {
 export interface AuthorizationLease {
   bindings: KyaBinding[];
   delegations: TrustDelegation[];
+  /** Optional copy of the consumer registration the bindings were issued under; it is compared
+   *  against `LeaseAuthority.consumer_registration` and is never authority on its own. */
+  registration?: ConsumerRegistrationStatement | null;
 }
 export interface BindingWindow { not_before: number; not_after: number; epoch: number; }
 export interface LeaseAuthority {
@@ -910,6 +993,10 @@ export interface LeaseAuthority {
   policy_revision: string;
   binding_windows: Record<string, BindingWindow>;
   reanchored_at: number;
+  /** A `twin3-trust-consumer-registration-v1` statement signed by `owner_public_key` (the vertical's
+   *  root R). When present, a binding whose challenge was signed by the statement's `kya_owner` key
+   *  verifies; bindings signed by R itself verify unchanged. `null` means no registration. */
+  consumer_registration?: ConsumerRegistrationStatement | null;
 }
 export interface LeaseAuthorityPort {
   currentAuthority(tenant: string, owner: string): LeaseAuthority | Promise<LeaseAuthority>;
@@ -929,6 +1016,8 @@ export interface VerifiedLeaseRequest {
   policy_revision: string;
   binding_receipts: string[];
   delegation_receipts: string[];
+  /** Receipt of the verified consumer registration, or `null` when the authority carries none. */
+  registration_receipt: string | null;
 }
 export declare class AuthorizationLeaseError extends ProtocolError {
   constructor(code: string);
@@ -958,6 +1047,8 @@ export interface LeaseClearanceContext {
     actor_key_id: string; purpose: string; occurrence_index: number;
     binding_receipts: string[]; delegation_receipts: string[];
     binding_windows: Array<BindingWindow | null>; usage: Record<string, number>;
+    /** Present only when the authority carries a consumer registration. */
+    registration_receipt?: string;
   };
 }
 export type DetectorState = "allow" | "flag" | "block" | "unavailable" | "not_configured";
@@ -1032,6 +1123,54 @@ export declare function verifyEnvelopeSignature(envelope: Envelope, publicKey: C
 
 export declare function scanText(text: string, options?: { source?: string; now?: number }): ShieldVerdict;
 
+export declare const MEMORY_SCHEMA: string;
+export declare const REVOCATION_SCHEMA: string;
+
+export declare class MemoryRejected extends Error {
+  readonly code: string;
+}
+
+export interface MemoryShieldStamp {
+  verdict: string;
+  reason_codes: string[];
+  receipt: unknown;
+}
+
+export interface MemoryEntry {
+  schema: string;
+  id: string;
+  text: string;
+  origin: string;
+  kind: "data" | "instruction";
+  treat_as: "data" | "instruction";
+  actor: string;
+  source: string;
+  source_epoch: number;
+  at: number;
+  shield: MemoryShieldStamp | null;
+  flagged: boolean;
+}
+
+export interface MemoryRevocation {
+  schema: string;
+  source: string;
+  epoch: number;
+  actor: string;
+  reason: string;
+  at: number;
+  removed: number;
+}
+
+export declare class MemoryGuard {
+  constructor(store: { entries?: MemoryEntry[]; revocations?: Record<string, MemoryRevocation>; purges?: unknown[] }, ensemble?: unknown, intel?: unknown);
+  revokedEpoch(source: string): number | null;
+  purgeSource(source: string, actor: string, reason: string, now?: number, epoch?: number): MemoryRevocation;
+  write(text: string, origin: string, actor: string, kind?: "data" | "instruction", source?: string, sourceEpoch?: number, now?: number): MemoryEntry;
+  recall(kinds?: Array<"data" | "instruction">, origins?: string[] | null, includeFlagged?: boolean): MemoryEntry[];
+  instructions(): MemoryEntry[];
+  purgeOrigin(origin: string, actor: string, reason: string): number;
+}
+
 export declare const TASK_EXPORT_SCHEMA: string;
 
 export declare function taskTrustLine(task: Record<string, unknown>, row: Record<string, unknown> | null): string;
@@ -1552,8 +1691,8 @@ export interface TaskInboxOptions {
   ensemble?: null | undefined;
   intel?: null | undefined;
   requirePlanDiff?: true;
-  replayStore?: null | undefined;
-  replay_store?: null | undefined;
+  replayStore?: { consume(key: string, expiresAt: number, now?: number): boolean | Promise<boolean> } | null;
+  replay_store?: { consume(key: string, expiresAt: number, now?: number): boolean | Promise<boolean> } | null;
 }
 
 export declare class IntakeRejected extends Error {
@@ -1614,6 +1753,10 @@ export declare class TaskInbox {
   }): TaskInboxTask;
   clearReview(taskId: string, actor: string, reason: string, now?: number): TaskInboxTask;
   clearReview(input: { taskId: string; actor: string; reason: string; now?: number }): TaskInboxTask;
+  getPolicy(): Record<string, any> | null;
+  setPolicy(policy: Record<string, any>): Record<string, any>;
+  quoteFor(identity: { kind: string; value: string }, now?: number): Record<string, any> | null;
+  applyPayment(identity: { kind: string; value: string }, receipt: Record<string, any>, ownerPublicKey: CryptoKeyInput, quoteBody?: Record<string, any> | null, actor?: string, now?: number): Promise<Record<string, any>>;
   recordPlanDiff(taskId: string, before: any[], after: any[], actor: string,
     authorized?: string[], now?: number): Record<string, any>;
   recordPlanDiff(input: {
@@ -1624,6 +1767,19 @@ export declare class TaskInbox {
     authorized?: string[];
     now?: number;
   }): Record<string, any>;
+  getPolicy(): Record<string, any> | null;
+  setPolicy(policy: Record<string, any>): Record<string, any>;
+  applyX402Payment(
+    identity: { kind: string; value: string },
+    demand: Record<string, any>,
+    receipt: Record<string, any>,
+    publicKey: CryptoKeyInput,
+    chainVerifier: { verifyPayment?: (demand: Record<string, any>, receipt: Record<string, any>) => Promise<Record<string, any>> | Record<string, any>; verify_payment?: (demand: Record<string, any>, receipt: Record<string, any>) => Promise<Record<string, any>> | Record<string, any> } | ((demand: Record<string, any>, receipt: Record<string, any>) => Promise<Record<string, any>> | Record<string, any>),
+    replayStore?: { reserve: Function; commit: Function; release: Function } | null,
+    minimumConfirmations?: number,
+    actor?: string,
+    now?: number,
+  ): Promise<Record<string, any>>;
   expireStale(now?: number): string[];
   verifyAuditChain(taskId: string): boolean;
 }
@@ -1719,3 +1875,78 @@ export declare function signDelegationWithSigner(delegation: Record<string, unkn
   options?: ExternalSignerOptions): Promise<Readonly<Record<string, unknown>>>;
 export declare function signEnvelopeWithSigner(envelope: Envelope, signer: ExternalEd25519Signer,
   options?: ExternalSignerOptions): Promise<Readonly<Envelope>>;
+
+export declare const CONSUMER_REGISTRATION_SCHEMA: "twin3-trust-consumer-registration-v1";
+export type ConsumerRegistrationEnvironment = "sandbox" | "staging" | "production";
+export type ConsumerRegistrationKeyRole = "kya_owner" | "evidence";
+export interface ConsumerRegistrationKey {
+  role: ConsumerRegistrationKeyRole;
+  key_id: string;
+  public_key: string;
+  label?: string;
+}
+export interface ConsumerRegistrationSubject {
+  consumer_id: string;
+  namespace: string;
+  environment: ConsumerRegistrationEnvironment;
+  identity_kinds: Array<"lei" | "duns" | "human_id">;
+  epoch: number;
+  policy_revision: string;
+  endpoints?: Record<string, string>;
+  sdk_contract_digest?: string;
+}
+/** `twin3-trust-consumer-registration-v1`: the vertical's root R signs which consumer keys it authorizes.
+ *  Exactly one `kya_owner` key; `issuer.key_id` and the JWS `kid` are descriptive and are compared against
+ *  the injected root, never fetched. */
+export interface ConsumerRegistrationStatement {
+  schema: "twin3-trust-consumer-registration-v1";
+  issuer: { key_id: string; did?: string };
+  subject: ConsumerRegistrationSubject;
+  authorized_keys: ConsumerRegistrationKey[];
+  not_before: number;
+  not_after: number;
+  signatures?: DescriptorSignature[];
+  signatureStatus?: string;
+}
+export interface ConsumerRegistrationExpectation {
+  consumer_id?: string;
+  namespace?: string;
+  environment?: ConsumerRegistrationEnvironment;
+  epoch?: number;
+  policy_revision?: string;
+  identity_kind?: "lei" | "duns" | "human_id";
+}
+export interface VerifiedConsumerRegistration {
+  receipt: string;
+  issuer_key_id: string;
+  subject: ConsumerRegistrationSubject;
+  kya_owner_key: ConsumerRegistrationKey;
+  evidence_keys: ConsumerRegistrationKey[];
+  not_before: number;
+  not_after: number;
+  kid: string;
+  jku: string | null;
+}
+export type ConsumerRegistrationErrorCode = "registration_schema_mismatch" | "registration_unknown_field"
+  | "registration_field_required" | "registration_signature_invalid" | "registration_root_required"
+  | "registration_root_mismatch" | "registration_kid_mismatch" | "registration_time_invalid"
+  | "registration_not_yet_valid" | "registration_expired" | "registration_subject_mismatch"
+  | "registration_key_unauthorized" | "registration_key_role_invalid" | "registration_required"
+  | "registration_mismatch";
+export declare class ConsumerRegistrationError extends ProtocolError {
+  readonly code: ConsumerRegistrationErrorCode;
+  constructor(code: ConsumerRegistrationErrorCode);
+}
+/** Shape rules only (no signature); returns the canonical body. With `now`, also checks the validity window. */
+export declare function validateConsumerRegistration(statement: ConsumerRegistrationStatement, options?: { now?: number | null }): Omit<ConsumerRegistrationStatement, "signatures" | "signatureStatus">;
+/** SHA-256 hex of the RFC 8785 body without signature fields; the revocation reference for the statement. */
+export declare function registrationReceipt(statement: ConsumerRegistrationStatement): string;
+export declare function signConsumerRegistration(statement: ConsumerRegistrationStatement, privateKey: string | Buffer | import("node:crypto").KeyObject,
+  options?: { kid?: string; jku?: string | null }): ConsumerRegistrationStatement & SignedDescriptor;
+export declare function signConsumerRegistrationWithSigner(statement: ConsumerRegistrationStatement, signer: ExternalEd25519Signer,
+  options?: { kid?: string; jku?: string | null; timeoutMs?: number; signal?: AbortSignal }): Promise<ConsumerRegistrationStatement & SignedDescriptor>;
+/** Verify shape, root signature (`rootPublicKey` is injected, never fetched), optional `kid`, window at `now` and the expected subject. No network. */
+export declare function verifyConsumerRegistration(statement: ConsumerRegistrationStatement, options: {
+  rootPublicKey: string | Buffer | import("node:crypto").KeyObject; expectedKid?: string | null; now: number;
+  expected?: ConsumerRegistrationExpectation | null;
+}): VerifiedConsumerRegistration;

package/js/comm/counterparty.js

@@ -316,7 +316,8 @@ function createCounterpartyAgent({ identity, keyPath, privateKeyPem, privateKey,
     if (id.kind !== self.identity.kind || id.value !== self.identity.value) throw sdkError("challenge_identity_mismatch");
     if (!(now() <= Number(challenge.expires_at))) throw sdkError("challenge_expired");
     verifyOwnerSignature(challenge, ownerPublicKey || challenge.owner_public_key);
-    const payload = signPayload ? b64urlDecode(signPayload) : challengeSignaturePayload(challenge);
+    const payload = challengeSignaturePayload(challenge);
+    if (signPayload && !b64urlDecode(signPayload).equals(payload)) throw sdkError("challenge_payload_mismatch");
     return { handshake_id: challenge.handshake_id, signature: b64url(crypto.sign(null, payload, key)) };
   };
 

package/js/discovery.d.ts

@@ -24,6 +24,8 @@ export {
   DESCRIPTOR_CANONICALIZATION,
   DESCRIPTOR_SIGNATURE_FIELDS,
   DISCOVERY_SUMMARY_SCHEMA,
+  ENGINE_OBSERVATION_SCHEMA,
+  ENGINE_READING_SCHEMA,
   DISCOVERY_VIEW_SCHEMA,
   DeclarationEndpoints,
   DescriptorSignature,
@@ -31,6 +33,11 @@ export {
   DiscoveryEvidenceError,
   DiscoveryEvidenceSummary,
   DiscoveryEvidenceView,
+  EngineObservation,
+  EngineObservationError,
+  EngineObservationInput,
+  EngineObservationReading,
+  EngineObservationSignalReading,
   DiscoveryVisitEvidence,
   DiscoveryVisitInput,
   InboxDeclaration,
@@ -73,6 +80,7 @@ export {
   inspectCardWire,
   migrateCardToEmit,
   normalizeAiExposure,
+  normalizeEngineObservation,
   normalizeDiscoveryVisit,
   parseSovereignCard,
   parseTwin3AgentCard,
@@ -82,6 +90,7 @@ export {
   signA2AAgentCard,
   signDescriptor,
   summarizeDiscoveryEvidence,
+  summarizeEngineObservations,
   unsignedDescriptor,
   validateAgentCardV1,
   validateWellKnownDocument,

package/js/discovery.js

@@ -11,6 +11,11 @@ module.exports = {
   normalizeAiExposure: impl.discoveryEvidenceApi.normalizeAiExposure,
   summarizeDiscoveryEvidence: impl.discoveryEvidenceApi.summarizeDiscoveryEvidence,
   buildDiscoveryEvidenceView: impl.discoveryEvidenceApi.buildDiscoveryEvidenceView,
+  ENGINE_OBSERVATION_SCHEMA: impl.engineObservation.ENGINE_OBSERVATION_SCHEMA,
+  ENGINE_READING_SCHEMA: impl.engineObservation.ENGINE_READING_SCHEMA,
+  EngineObservationError: impl.engineObservation.EngineObservationError,
+  normalizeEngineObservation: impl.engineObservationApi.normalizeEngineObservation,
+  summarizeEngineObservations: impl.engineObservationApi.summarizeEngineObservations,
   createSovereignCard: impl.createSovereignCard,
   createTwin3AgentCard: impl.createTwin3AgentCard,
   createAgentCard: impl.createAgentCard,

package/js/discovery.mjs

@@ -8,6 +8,11 @@ export const normalizeDiscoveryVisit = api.normalizeDiscoveryVisit;
 export const normalizeAiExposure = api.normalizeAiExposure;
 export const summarizeDiscoveryEvidence = api.summarizeDiscoveryEvidence;
 export const buildDiscoveryEvidenceView = api.buildDiscoveryEvidenceView;
+export const ENGINE_OBSERVATION_SCHEMA = api.ENGINE_OBSERVATION_SCHEMA;
+export const ENGINE_READING_SCHEMA = api.ENGINE_READING_SCHEMA;
+export const EngineObservationError = api.EngineObservationError;
+export const normalizeEngineObservation = api.normalizeEngineObservation;
+export const summarizeEngineObservations = api.summarizeEngineObservations;
 export const createSovereignCard = api.createSovereignCard;
 export const createTwin3AgentCard = api.createTwin3AgentCard;
 export const createAgentCard = api.createAgentCard;