twin3-sdk 0.2.18-pre-alpha → 0.2.19-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.18-pre-alpha` is the current release candidate: `0.2.18-pre-alpha` for npm and `0.2.18a0` 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.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`.
 
 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.18-pre-alpha
-pip install twin3-sdk==0.2.18a0
+npm install twin3-sdk@0.2.19-pre-alpha
+pip install twin3-sdk==0.2.19a0
 ```
 
 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.18-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.19-pre-alpha.tgz
 ```
 
 ---

package/index.d.ts

@@ -223,6 +223,9 @@ 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 function buildSignedReferral(options: Record<string, any>): Record<string, any>;
+export declare function verifySignedReferral(token: Record<string, any>, options: Record<string, any>): Record<string, any>;
 
 export declare const DESCRIPTOR_CANONICALIZATION: "rfc8785";
 export declare const DESCRIPTOR_SIGNATURE_FIELDS: readonly ["signatures", "signatureStatus"];

package/js/comm/counterparty.js

@@ -250,10 +250,20 @@ function envelopeDigest(envelope) {
   return crypto.createHash("sha256").update(canonicalJsonBuffer(body)).digest("hex");
 }
 
-function buildEnvelope(identity, kind, payload, { ttlSeconds = 900, now = Math.floor(Date.now() / 1000), legacySchemas = false } = {}) {
+function buildEnvelope(identity, kind, payload, { ttlSeconds = 900, now = Math.floor(Date.now() / 1000), legacySchemas = false, attribution = undefined } = {}) {
   const sender = identityOf(identity);
   if (!ENVELOPE_KINDS.has(kind)) throw sdkError("envelope_kind_unknown");
   if (!payload || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).length === 0) throw sdkError("envelope_payload_empty");
+  if (attribution !== undefined && attribution !== null) {
+    if (!attribution || typeof attribution !== "object" || Array.isArray(attribution)
+        || Object.keys(attribution).length !== 2
+        || !Object.prototype.hasOwnProperty.call(attribution, "attributed_card_digest")
+        || !Object.prototype.hasOwnProperty.call(attribution, "attribution_source")
+        || (attribution.attributed_card_digest !== null && (typeof attribution.attributed_card_digest !== "string" || !/^[0-9a-f]{64}$/.test(attribution.attributed_card_digest)))
+        || !["card_endpoint", "referral_token", "unknown"].includes(attribution.attribution_source)) {
+      throw sdkError("envelope_attribution_invalid");
+    }
+  }
   const at = Math.floor(now);
   const envelope = {
     schema: legacySchemas ? LEGACY.envelope : ENVELOPE_SCHEMA,
@@ -267,6 +277,9 @@ function buildEnvelope(identity, kind, payload, { ttlSeconds = 900, now = Math.f
     issued_at: at,
     deadline: at + Math.floor(ttlSeconds),
   };
+  if (attribution !== undefined && attribution !== null) {
+    envelope.attribution = JSON.parse(JSON.stringify(attribution));
+  }
   void sender;
   envelope.digest = envelopeDigest(envelope);
   return envelope;

package/js/discovery-evidence.js

@@ -2,12 +2,14 @@
 
 const crypto = require("node:crypto");
 const zhTw = require("../twin3/discovery/evidence-i18n.json")["zh-TW"];
+const { validId } = require("./id-format.js");
 
 const VISIT_EVIDENCE_SCHEMA = "twin3-discovery-visit-evidence-v1";
 const AI_EXPOSURE_SCHEMA = "twin3-discovery-ai-exposure-v1";
 const DISCOVERY_SUMMARY_SCHEMA = "twin3-discovery-evidence-summary-v1";
 const DISCOVERY_VIEW_SCHEMA = "twin3-discovery-evidence-view-v1";
 const VISIT_FIELDS = ["schema", "host", "path", "surface", "source", "record_id", "source_digest", "observed_at", "request_count", "method", "status", "provider", "bot", "evidence_level", "user_agent_digest", "digest"];
+const CARD_ATTRIBUTION_FIELDS = ["subject_namespace", "subject_id", "card_digest", "claim_axis", "network_axis", "identity_axis"];
 const EXPOSURE_FIELDS = ["schema", "host", "source", "report_digest", "date", "page", "page_digest", "impressions", "evidence_level", "digest"];
 const SHA256 = /^[0-9a-f]{64}$/;
 const URL_COMPONENT = /^(?:[A-Za-z0-9._~!$&'()*+,;=:@/?-]|%[0-9A-Fa-f]{2})*$/;
@@ -28,6 +30,14 @@ const BOTS = [
   ["Bingbot", "Microsoft"],
   ["Applebot", "Apple"],
 ];
+const PROTOCOL_BOTS = [
+  ["A2A-Client", "A2A"],
+  ["WebMCP-Client", "WebMCP"],
+];
+const ALL_BOTS = [...BOTS, ...PROTOCOL_BOTS];
+const CLAIM_AXES = ["unclassified", "ua_claim", "protocol_claim"];
+const NETWORK_AXES = ["unverified", "published_ip_range_matched", "rdns_verified"];
+const IDENTITY_AXES = ["unsigned", "request_signature_valid", "kya_delegation_bound"];
 
 class DiscoveryEvidenceError extends Error {
   constructor(code) {
@@ -97,7 +107,35 @@ function pathValue(value) {
   return path;
 }
 
-function visitFields(row, ownerHost) {
+function cardAttributionInput(row) {
+  const hasAttribution = CARD_ATTRIBUTION_FIELDS.some(key => Object.hasOwn(row, key)) || row.surface === "hosted_card";
+  if (!hasAttribution) return null;
+  const namespace = Object.hasOwn(row, "subject_namespace") ? row.subject_namespace : null;
+  const subjectId = Object.hasOwn(row, "subject_id") ? row.subject_id : null;
+  requireValue((namespace === null) === (subjectId === null), "visit_subject_invalid");
+  if (namespace !== null) {
+    requireValue(namespace === "agt" || namespace === "hum", "visit_subject_invalid");
+    requireValue(typeof subjectId === "string" && validId(subjectId) && subjectId.startsWith(namespace + "_") && subjectId.length > 4, "visit_subject_invalid");
+  }
+  const cardDigest = Object.hasOwn(row, "card_digest") ? row.card_digest : null;
+  requireValue(cardDigest === null || isSha256(cardDigest), "visit_card_digest_invalid");
+  const networkAxis = row.network_axis === undefined ? "unverified" : row.network_axis;
+  requireValue(NETWORK_AXES.includes(networkAxis), "visit_network_axis_invalid");
+  const identityAxis = row.identity_axis === undefined ? "unsigned" : row.identity_axis;
+  requireValue(IDENTITY_AXES.includes(identityAxis), "visit_identity_axis_invalid");
+  const claimAxis = Object.hasOwn(row, "claim_axis") ? row.claim_axis : null;
+  requireValue(claimAxis === null || CLAIM_AXES.includes(claimAxis), "visit_claim_axis_invalid");
+  return {
+    subject_namespace: namespace,
+    subject_id: subjectId,
+    card_digest: cardDigest,
+    claim_axis: claimAxis,
+    network_axis: networkAxis,
+    identity_axis: identityAxis,
+  };
+}
+
+function visitFields(row, ownerHost, { allowHostedCard = false } = {}) {
   requireValue(["cdn_log", "server_log"].includes(row.source), "visit_source_invalid");
   requireValue(typeof row.record_id === "string" && row.record_id.length > 0 && row.record_id.length <= 160 && !/[^A-Za-z0-9._:-]/.test(row.record_id), "visit_record_id_required");
   requireValue(isSha256(row.source_digest), "visit_source_digest_invalid");
@@ -109,8 +147,10 @@ function visitFields(row, ownerHost) {
   requireValue(method === "GET" || method === "HEAD", "visit_method_invalid");
   const path = pathValue(row.path);
   if (Object.hasOwn(row, "host")) requireValue(hostValue(row.host) === ownerHost, "visit_host_mismatch");
+  const defaultSurface = ["/.well-known/agent-card.json", "/.well-known/agent.json"].includes(path) ? "agent_card" : "website";
+  const surface = allowHostedCard && row.surface === "hosted_card" ? "hosted_card" : defaultSurface;
   return { schema: VISIT_EVIDENCE_SCHEMA, host: ownerHost, path,
-    surface: ["/.well-known/agent-card.json", "/.well-known/agent.json"].includes(path) ? "agent_card" : "website",
+    surface,
     source: row.source, record_id: row.record_id, source_digest: row.source_digest,
     observed_at: row.observed_at, request_count: requestCount, method, status };
 }
@@ -137,17 +177,35 @@ function createDiscoveryEvidenceApi(canonicalJsonBuffer) {
   function normalizeDiscoveryVisit(row, { host } = {}) {
     requireValue(isRecord(row), "visit_invalid");
     const ownerHost = hostValue(host);
-    const fields = visitFields(row, ownerHost);
+    const attribution = cardAttributionInput(row);
+    const fields = visitFields(row, ownerHost, { allowHostedCard: attribution !== null });
     const userAgent = row.user_agent === undefined ? "" : row.user_agent;
     requireValue(typeof userAgent === "string" && [...userAgent].length <= 512 && !/[\ud800-\udfff]/u.test(userAgent), "visit_user_agent_invalid");
-    const bot = BOTS.find(([name]) => new RegExp("(^|[^A-Za-z0-9_-])" + name + "($|[^A-Za-z0-9_-])", "i").test(userAgent));
+    const botCandidates = attribution !== null ? ALL_BOTS : BOTS;
+    const bot = botCandidates.find(([name]) => new RegExp("(^|[^A-Za-z0-9_-])" + name + "($|[^A-Za-z0-9_-])", "i").test(userAgent));
+    const isProtocol = Boolean(bot && PROTOCOL_BOTS.some(([name]) => name === bot[0]));
+    const evidenceLevel = bot ? (isProtocol ? "protocol_claim" : "ua_claim") : (
+      attribution && attribution.claim_axis === "protocol_claim" ? "protocol_claim" : "unclassified"
+    );
     const body = {
       ...fields,
       provider: bot ? bot[1] : null,
       bot: bot ? bot[0] : null,
-      evidence_level: bot ? "ua_claim" : "unclassified",
+      evidence_level: evidenceLevel,
       user_agent_digest: crypto.createHash("sha256").update(userAgent, "utf8").digest("hex"),
     };
+    if (attribution !== null) {
+      const claimAxis = attribution.claim_axis || evidenceLevel;
+      requireValue(claimAxis === evidenceLevel, "visit_claim_axis_invalid");
+      Object.assign(body, {
+        subject_namespace: attribution.subject_namespace,
+        subject_id: attribution.subject_id,
+        card_digest: attribution.card_digest,
+        claim_axis: claimAxis,
+        network_axis: attribution.network_axis,
+        identity_axis: attribution.identity_axis,
+      });
+    }
     return { ...body, digest: digest(body, canonicalJsonBuffer) };
   }
 
@@ -174,13 +232,25 @@ function createDiscoveryEvidenceApi(canonicalJsonBuffer) {
   function validateVisit(row, ownerHost) {
     requireValue(isRecord(row) && row.schema === VISIT_EVIDENCE_SCHEMA && row.host === ownerHost, "visit_invalid");
     verifyDigest(row, "visit_digest_mismatch");
-    requireValue(hasFields(row, VISIT_FIELDS), "visit_invalid");
-    const fields = visitFields(row, ownerHost);
+    const hasAttribution = CARD_ATTRIBUTION_FIELDS.some(key => Object.hasOwn(row, key));
+    requireValue(hasFields(row, hasAttribution ? [...VISIT_FIELDS, ...CARD_ATTRIBUTION_FIELDS] : VISIT_FIELDS), "visit_invalid");
+    const fields = visitFields(row, ownerHost, { allowHostedCard: hasAttribution });
     requireValue(row.path === fields.path && row.surface === fields.surface, "visit_invalid");
     requireValue(isSha256(row.user_agent_digest), "visit_invalid");
-    const bot = BOTS.find(([name]) => name === row.bot);
+    const botTable = hasAttribution ? ALL_BOTS : BOTS;
+    const bot = botTable.find(([name]) => name === row.bot);
     requireValue(row.bot === null || bot !== undefined, "visit_invalid");
-    requireValue(row.provider === (bot ? bot[1] : null) && row.evidence_level === (bot ? "ua_claim" : "unclassified"), "visit_invalid");
+    requireValue(row.provider === (bot ? bot[1] : null), "visit_invalid");
+    if (hasAttribution) {
+      const attribution = cardAttributionInput(row);
+      const isProtocol = Boolean(bot && PROTOCOL_BOTS.some(([name]) => name === bot[0]));
+      const expectedLevel = bot ? (isProtocol ? "protocol_claim" : "ua_claim") : (
+        attribution.claim_axis === "protocol_claim" ? "protocol_claim" : "unclassified"
+      );
+      requireValue(row.evidence_level === expectedLevel && row.claim_axis === expectedLevel, "visit_invalid");
+    } else {
+      requireValue(row.evidence_level === (bot ? "ua_claim" : "unclassified"), "visit_invalid");
+    }
   }
 
   function validateExposure(row, ownerHost) {
@@ -226,7 +296,7 @@ function createDiscoveryEvidenceApi(canonicalJsonBuffer) {
     for (const row of visitRows) {
       const count = row.request_count;
       const success = row.status >= 200 && row.status < 400;
-      const cardSuccess = row.status >= 200 && row.status < 300 && row.surface === "agent_card";
+      const cardSuccess = row.status >= 200 && row.status < 300 && (row.surface === "agent_card" || row.surface === "hosted_card");
       successful += success ? count : 0;
       failed += success ? 0 : count;
       cardReads += cardSuccess ? count : 0;
@@ -276,7 +346,7 @@ function createDiscoveryEvidenceApi(canonicalJsonBuffer) {
         summaryCount(count);
         requireValue(field === "by_date" || count > 0, "summary_invalid");
         if (field === "by_path") requireValue(pathValue(key) === key, "summary_invalid");
-        else if (field === "by_bot_claim") requireValue(BOTS.some(([name]) => name === key), "summary_invalid");
+        else if (field === "by_bot_claim") requireValue(ALL_BOTS.some(([name]) => name === key), "summary_invalid");
         else dateValue(key);
       }
       if (total !== null) requireValue(Object.values(values).reduce((sum, value) => sum + value, 0) === total, "summary_invalid");

package/js/discovery.d.ts

@@ -89,6 +89,7 @@ export {
   resolveDocumentPath,
   signA2AAgentCard,
   signDescriptor,
+  summarizeCohortVisibility,
   summarizeDiscoveryEvidence,
   summarizeEngineObservations,
   unsignedDescriptor,

package/js/discovery.js

@@ -16,6 +16,7 @@ module.exports = {
   EngineObservationError: impl.engineObservation.EngineObservationError,
   normalizeEngineObservation: impl.engineObservationApi.normalizeEngineObservation,
   summarizeEngineObservations: impl.engineObservationApi.summarizeEngineObservations,
+  summarizeCohortVisibility: impl.engineObservationApi.summarizeCohortVisibility,
   createSovereignCard: impl.createSovereignCard,
   createTwin3AgentCard: impl.createTwin3AgentCard,
   createAgentCard: impl.createAgentCard,

package/js/discovery.mjs

@@ -13,6 +13,7 @@ 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 summarizeCohortVisibility = api.summarizeCohortVisibility;
 export const createSovereignCard = api.createSovereignCard;
 export const createTwin3AgentCard = api.createTwin3AgentCard;
 export const createAgentCard = api.createAgentCard;

package/js/engine-observation.js

@@ -1,9 +1,11 @@
 "use strict";
 
 const crypto = require("node:crypto");
+const { validId } = require("./id-format.js");
 
 const ENGINE_OBSERVATION_SCHEMA = "twin3-discovery-engine-observation-v1";
 const ENGINE_READING_SCHEMA = "twin3-discovery-engine-reading-v1";
+const COHORT_VISIBILITY_SCHEMA = "twin3-discovery-cohort-visibility-v1";
 const MIN_RUNS_PER_PROMPT = 7;
 const MIN_RUNS_FOR_SOURCE_COVERAGE = 8;
 const MIN_PARAPHRASES_PER_NEED = 3;
@@ -250,12 +252,131 @@ function createEngineObservationApi(canonicalJsonBuffer) {
     return { ...body, digest: digest(body) };
   }
 
-  return { normalizeEngineObservation, summarizeEngineObservations };
+  function validateReadingForCohort(reading) {
+    requireValue(isRecord(reading) && reading.schema === ENGINE_READING_SCHEMA, "cohort_reading_invalid");
+    const { digest: supplied, ...body } = reading;
+    requireValue(typeof supplied === "string" && SHA256.test(supplied), "cohort_reading_digest_mismatch");
+    let expected;
+    try {
+      expected = digest(body);
+    } catch {
+      throw new EngineObservationError("cohort_reading_digest_mismatch");
+    }
+    requireValue(crypto.timingSafeEqual(Buffer.from(supplied, "ascii"), Buffer.from(expected, "ascii")), "cohort_reading_digest_mismatch");
+    requireValue(isRecord(reading.by_engine), "cohort_reading_invalid");
+    for (const [engine, engineEntry] of Object.entries(reading.by_engine)) {
+      requireValue(typeof engine === "string" && ENGINE.test(engine), "cohort_reading_invalid");
+      requireValue(isRecord(engineEntry), "cohort_reading_invalid");
+      const signals = engineEntry.signals;
+      requireValue(
+        isRecord(signals) && Object.keys(signals).length === SIGNALS.length && SIGNALS.every(name => Object.hasOwn(signals, name)),
+        "cohort_reading_invalid",
+      );
+      for (const signalName of SIGNALS) {
+        const sig = signals[signalName];
+        requireValue(isRecord(sig), "cohort_reading_invalid");
+        const state = sig.state;
+        const rate = sig.rate_bp;
+        if (state === "measured") {
+          requireValue(typeof rate === "number" && Number.isInteger(rate) && rate >= 0 && rate <= 10000, "cohort_reading_invalid");
+        } else if (state === "withheld" || state === "unknown") {
+          requireValue(rate === null || rate === undefined, "cohort_reading_invalid");
+        } else {
+          throw new EngineObservationError("cohort_reading_invalid");
+        }
+      }
+    }
+  }
+
+  function summarizeCohortVisibility(readingsBySubject, subjectId, { minCohortSize = 3 } = {}) {
+    requireValue(isRecord(readingsBySubject) && Object.keys(readingsBySubject).length > 0, "cohort_readings_invalid");
+    requireValue(typeof subjectId === "string" && validId(subjectId), "cohort_subject_id_invalid");
+    requireValue(typeof minCohortSize === "number" && Number.isInteger(minCohortSize) && minCohortSize >= 1 && minCohortSize <= 10000, "cohort_min_size_invalid");
+    requireValue(Object.hasOwn(readingsBySubject, subjectId), "cohort_subject_not_found");
+    const subjectIds = Object.keys(readingsBySubject).sort(compare);
+    const engineSet = new Set();
+    for (const sid of subjectIds) {
+      requireValue(typeof sid === "string" && validId(sid), "cohort_subject_id_invalid");
+      const reading = readingsBySubject[sid];
+      validateReadingForCohort(reading);
+      for (const engine of Object.keys(reading.by_engine)) engineSet.add(engine);
+    }
+    const sortedEngines = [...engineSet].sort(compare);
+    const byEngine = {};
+    for (const engine of sortedEngines) {
+      const engineSignals = {};
+      for (const signalName of SIGNALS) {
+        const subjectReading = readingsBySubject[subjectId].by_engine[engine]?.signals?.[signalName] ?? null;
+        const measuredRates = new Map();
+        let anyWithheld = false;
+        for (const sid of subjectIds) {
+          const sig = readingsBySubject[sid].by_engine[engine]?.signals?.[signalName];
+          if (!isRecord(sig)) continue;
+          const state = sig.state;
+          const rate = sig.rate_bp;
+          if (state === "measured" && typeof rate === "number" && Number.isInteger(rate) && rate >= 0 && rate <= 10000) {
+            measuredRates.set(sid, rate);
+          } else if (state === "withheld") {
+            anyWithheld = true;
+          }
+        }
+        const cohortSize = measuredRates.size;
+        if (subjectReading === null || subjectReading.state === "unknown") {
+          engineSignals[signalName] = {
+            state: "unknown",
+            cohort_size: cohortSize,
+            subject_rate_bp: null,
+            percentile_bp: null,
+            rank: null,
+          };
+        } else if (!measuredRates.has(subjectId) || cohortSize < minCohortSize) {
+          engineSignals[signalName] = {
+            state: (subjectReading.state === "withheld" || subjectReading.state === "measured" || anyWithheld) ? "withheld" : "unknown",
+            cohort_size: cohortSize,
+            subject_rate_bp: measuredRates.has(subjectId) ? measuredRates.get(subjectId) : null,
+            percentile_bp: null,
+            rank: null,
+          };
+        } else {
+          const subjRate = measuredRates.get(subjectId);
+          let better = 0;
+          let belowOrEqual = 0;
+          for (const r of measuredRates.values()) {
+            if (r > subjRate) better += 1;
+            if (r <= subjRate) belowOrEqual += 1;
+          }
+          engineSignals[signalName] = {
+            state: "measured",
+            cohort_size: cohortSize,
+            subject_rate_bp: subjRate,
+            percentile_bp: Math.floor(belowOrEqual * 10000 / cohortSize),
+            rank: 1 + better,
+          };
+        }
+      }
+      byEngine[engine] = { signals: engineSignals };
+    }
+    const readingDigests = Object.fromEntries(subjectIds.map(sid => [sid, readingsBySubject[sid].digest]));
+    const body = {
+      schema: COHORT_VISIBILITY_SCHEMA,
+      subject_id: subjectId,
+      min_cohort_size: minCohortSize,
+      subjects_total: subjectIds.length,
+      engines: sortedEngines,
+      by_engine: byEngine,
+      reading_digests: readingDigests,
+      non_claims: [...NON_CLAIMS],
+    };
+    return { ...body, digest: digest(body) };
+  }
+
+  return { normalizeEngineObservation, summarizeEngineObservations, summarizeCohortVisibility };
 }
 
 module.exports = {
   ENGINE_OBSERVATION_SCHEMA,
   ENGINE_READING_SCHEMA,
+  COHORT_VISIBILITY_SCHEMA,
   EngineObservationError,
   createEngineObservationApi,
 };

package/js/index.js

@@ -44,6 +44,7 @@ module.exports = {
   EngineObservationError: discovery.EngineObservationError,
   normalizeEngineObservation: discovery.normalizeEngineObservation,
   summarizeEngineObservations: discovery.summarizeEngineObservations,
+  summarizeCohortVisibility: discovery.summarizeCohortVisibility,
   AuthorizationLeaseError: shield.AuthorizationLeaseError,
   verifyAuthorizationLease: shield.verifyAuthorizationLease,
   leaseClearanceContext: shield.leaseClearanceContext,
@@ -57,6 +58,8 @@ module.exports = {
   claimExecution: shield.claimExecution,
   createInMemoryExecutionClaimStore: shield.createInMemoryExecutionClaimStore,
   recordExecutionOutcome: shield.recordExecutionOutcome,
+  buildSignedReferral: shield.buildSignedReferral,
+  verifySignedReferral: shield.verifySignedReferral,
   createSovereignCard: discovery.createSovereignCard,
   createTwin3AgentCard: discovery.createTwin3AgentCard,
   createAgentCard: discovery.createAgentCard,

package/js/index.mjs

@@ -132,6 +132,7 @@ export const authorizeExecution = api.authorizeExecution;
 export const buildDeclaration = api.buildDeclaration;
 export const buildDiscoveryEvidenceView = api.buildDiscoveryEvidenceView;
 export const buildEnvelope = api.buildEnvelope;
+export const buildSignedReferral = api.buildSignedReferral;
 export const buildWellKnownDocument = api.buildWellKnownDocument;
 export const canStrangerDecide = api.canStrangerDecide;
 export const canonicalJson = api.canonicalJson;
@@ -242,6 +243,7 @@ export const signDelegationWithSigner = api.signDelegationWithSigner;
 export const signDescriptor = api.signDescriptor;
 export const signEnvelope = api.signEnvelope;
 export const signEnvelopeWithSigner = api.signEnvelopeWithSigner;
+export const summarizeCohortVisibility = api.summarizeCohortVisibility;
 export const summarizeDiscoveryEvidence = api.summarizeDiscoveryEvidence;
 export const summarizeEngineObservations = api.summarizeEngineObservations;
 export const taskTrustLine = api.taskTrustLine;
@@ -275,6 +277,7 @@ export const verifyPasskeyAssertionWithStores = api.verifyPasskeyAssertionWithSt
 export const verifyPasskeyRegistration = api.verifyPasskeyRegistration;
 export const verifyReceipt = api.verifyReceipt;
 export const verifySignedPaymentReceipt = api.verifySignedPaymentReceipt;
+export const verifySignedReferral = api.verifySignedReferral;
 export const verifyX402Payment = api.verifyX402Payment;
 export const x402DnsTxtRecord = api.x402DnsTxtRecord;
 export default api;

package/js/internal/comm.js

@@ -10,11 +10,32 @@ function envelopeBuilderNumber(value, code) {
         core.fail(code);
     return Math.floor(value);
 }
-function buildEnvelope({ sender, kind = "message", payload = {}, ttlSeconds = 900, now: at }) {
+function validateEnvelopeAttribution(attr, failFn) {
+    if (attr === undefined || attr === null)
+        return;
+    if (!attr || typeof attr !== "object" || Array.isArray(attr))
+        failFn("envelope_attribution_invalid");
+    const keys = Object.keys(attr);
+    if (keys.length !== 2 || !Object.prototype.hasOwnProperty.call(attr, "attributed_card_digest")
+        || !Object.prototype.hasOwnProperty.call(attr, "attribution_source")) {
+        failFn("envelope_attribution_invalid");
+    }
+    const cardDigest = attr.attributed_card_digest;
+    if (cardDigest !== null && (typeof cardDigest !== "string" || !/^[0-9a-f]{64}$/.test(cardDigest))) {
+        failFn("envelope_attribution_invalid");
+    }
+    if (!["card_endpoint", "referral_token", "unknown"].includes(attr.attribution_source)) {
+        failFn("envelope_attribution_invalid");
+    }
+}
+function buildEnvelope({ sender, kind = "message", payload = {}, ttlSeconds = 900, now: at, attribution = undefined }) {
     const now = at === undefined
         ? Math.floor(Date.now() / 1000)
         : envelopeBuilderNumber(at, "envelope_timestamps_invalid");
     const ttl = envelopeBuilderNumber(ttlSeconds, "envelope_ttl_invalid");
+    if (attribution !== undefined && attribution !== null) {
+        validateEnvelopeAttribution(attribution, core.fail);
+    }
     const envelope = {
         schema: trust.ENVELOPE_SCHEMA,
         envelope_id: core.crypto.randomUUID(),
@@ -27,6 +48,9 @@ function buildEnvelope({ sender, kind = "message", payload = {}, ttlSeconds = 90
         issued_at: now,
         deadline: now + ttl,
     };
+    if (attribution !== undefined && attribution !== null) {
+        envelope.attribution = JSON.parse(JSON.stringify(attribution));
+    }
     const body = { ...envelope };
     delete body.digest;
     delete body.sender_signature;
@@ -154,6 +178,9 @@ const experimentalTaskInbox = (() => {
             if (tag.treat_as !== "data")
                 fail("envelope_field_not_marked_data");
         }
+        if (Object.prototype.hasOwnProperty.call(envelope, "attribution") && envelope.attribution !== null) {
+            validateEnvelopeAttribution(envelope.attribution, fail);
+        }
         if (![envelope.issued_at, envelope.deadline].every(Number.isFinite))
             fail("envelope_timestamps_invalid");
         if (envelope.deadline <= envelope.issued_at)
@@ -302,6 +329,8 @@ const experimentalTaskInbox = (() => {
                 const task = { schema: TASK_SCHEMA, task_id: taskId, tenant_id: this.#tenant, sender, kind: envelope.kind,
                     payload: envelope.payload, provenance: envelope.provenance, authority: "none", state: "submitted", version: 1,
                     review: { required: true }, created_at: at, updated_at: at, history: [], audit_head: "" };
+                if (envelope.attribution !== undefined && envelope.attribution !== null)
+                    task.attribution = clone(envelope.attribution);
                 audit(task, permission.principalId, "intake", at, digest([this.#tenant, operationKey]));
                 state.tasks[taskId] = task;
                 state.operations[operationKey] = { command_digest: commandDigest, result: clone(task) };
@@ -647,6 +676,9 @@ function taskEnvelopeInput(input, now) {
         if (tag.treat_as !== "data")
             throw new IntakeRejected("envelope_field_not_marked_data");
     }
+    if (Object.prototype.hasOwnProperty.call(envelope, "attribution") && envelope.attribution !== null) {
+        validateEnvelopeAttribution(envelope.attribution, (code) => { throw new IntakeRejected(code); });
+    }
     if (typeof envelope.issued_at !== "number" || !Number.isFinite(envelope.issued_at)
         || typeof envelope.deadline !== "number" || !Number.isFinite(envelope.deadline)) {
         throw new IntakeRejected("envelope_timestamps_invalid");
@@ -1352,6 +1384,8 @@ class TaskInbox {
             history: [],
             audit_head: "",
         };
+        if (validated.attribution !== undefined && validated.attribution !== null)
+            task.attribution = taskClone(validated.attribution);
         if (usesFreeAllowance)
             this._parties.noteFreeAllowanceUse(sender, { now: at });
         taskAudit(task, "submitted", senderKey, "intake", at);

package/js/internal/shield.js

@@ -924,9 +924,205 @@ function createLeaseApi({ ProtocolError, canonicalJsonBuffer, normalizeIdentity,
             return { ...denied("claim", ["occurrence_" + claim.state]), claim };
         return { allowed: true, stage: "allowed", reasons: [], claim, context, authorization: verified };
     }
+    const REFERRAL_SCHEMA = "twin3-shield-signed-referral-v1";
+    const REFERRAL_PURPOSE = "card_outbound_referral";
+    const MAX_REFERRAL_TTL_SECONDS = 300;
+    const REFERRAL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+    const REFERRAL_SHA256_RE = /^[0-9a-f]{64}$/;
+    const REFERRAL_URL_COMPONENT = /^(?:[A-Za-z0-9._~!$&'()*+,;=:@/?-]|%[0-9A-Fa-f]{2})*$/;
+    const REFERRAL_FIELDS = [
+        "schema", "issuer", "audience", "purpose", "subject_id", "card_digest",
+        "destination_id", "target_url", "epoch_id", "policy_revision", "issued_at",
+        "expires_at", "ttl_seconds", "nonce", "key_id", "signature", "digest",
+    ];
+    function referralRequire(condition, code) {
+        if (!condition)
+            fail(code);
+    }
+    function referralHost(value, code) {
+        referralRequire(typeof value === "string" && /^[\x00-\x7f]*$/.test(value), code);
+        const trimmed = value.replace(/^[ \t\r\n\v\f]+|[ \t\r\n\v\f]+$/g, "").toLowerCase();
+        const host = trimmed.endsWith(".") ? trimmed.slice(0, -1) : trimmed;
+        referralRequire(/^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/.test(host) && !host.includes(".."), code);
+        return host;
+    }
+    function referralTargetUrl(value) {
+        referralRequire(typeof value === "string" && value.length > 0 && value.length <= 2048, "referral_target_url_invalid");
+        for (let i = 0; i < value.length; i += 1) {
+            const code = value.charCodeAt(i);
+            referralRequire(code >= 33 && code <= 126, "referral_target_url_invalid");
+        }
+        const parsed = /^https:\/\/([^/?#]+)(\/[^?#]*)?(\?[^#]*)?(#[^#]*)?$/i.exec(value);
+        referralRequire(parsed !== null, "referral_target_url_invalid");
+        const [, authority, rawPath, query, fragment] = parsed;
+        referralRequire(!/[@[\]\\]/.test(authority), "referral_target_url_invalid");
+        const parts = authority.split(":");
+        referralRequire(parts.length <= 2 && (parts.length === 1 || /^0*443$/.test(parts[1])), "referral_target_url_invalid");
+        const host = referralHost(parts[0], "referral_target_url_invalid");
+        const path = rawPath || "/";
+        referralRequire(
+            REFERRAL_URL_COMPONENT.test(path)
+                && REFERRAL_URL_COMPONENT.test((query || "").slice(1))
+                && REFERRAL_URL_COMPONENT.test((fragment || "").slice(1)),
+            "referral_target_url_invalid",
+        );
+        return ["https://" + host + path + (query || "") + (fragment || ""), host];
+    }
+    function referralSubjectId(value) {
+        referralRequire(typeof value === "string" && REFERRAL_ID_RE.test(value), "referral_subject_id_invalid");
+        referralRequire((value.startsWith("agt_") || value.startsWith("hum_")) && value.length > 4, "referral_subject_id_invalid");
+        return value;
+    }
+    function referralIdentifier(value, code) {
+        referralRequire(typeof value === "string" && REFERRAL_ID_RE.test(value), code);
+        return value;
+    }
+    function referralTimestamp(value, code) {
+        referralRequire(typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 253402300799, code);
+        return value;
+    }
+    function referralTtl(value) {
+        referralRequire(typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= MAX_REFERRAL_TTL_SECONDS, "referral_ttl_invalid");
+        return value;
+    }
+    function buildSignedReferral(options = {}) {
+        referralRequire(object(options), "referral_invalid");
+        const issuerVal = referralIdentifier(options.issuer, "referral_issuer_invalid");
+        const audienceVal = referralIdentifier(options.audience, "referral_audience_invalid");
+        const subjectVal = referralSubjectId(options.subjectId !== undefined ? options.subjectId : options.subject_id);
+        const rawCardDigest = options.cardDigest !== undefined ? options.cardDigest : options.card_digest;
+        referralRequire(typeof rawCardDigest === "string" && REFERRAL_SHA256_RE.test(rawCardDigest), "referral_card_digest_invalid");
+        const destVal = referralIdentifier(options.destinationId !== undefined ? options.destinationId : options.destination_id, "referral_destination_invalid");
+        const [normalizedUrl] = referralTargetUrl(options.targetUrl !== undefined ? options.targetUrl : options.target_url);
+        const epochVal = referralIdentifier(options.epochId !== undefined ? options.epochId : options.epoch_id, "referral_epoch_invalid");
+        const policyVal = referralIdentifier(options.policyRevision !== undefined ? options.policyRevision : options.policy_revision, "referral_policy_revision_invalid");
+        const rawTtl = options.ttlSeconds !== undefined ? options.ttlSeconds : (options.ttl_seconds !== undefined ? options.ttl_seconds : MAX_REFERRAL_TTL_SECONDS);
+        const ttlVal = referralTtl(rawTtl);
+        const rawIssuedAt = options.issuedAt !== undefined ? options.issuedAt : options.issued_at;
+        const at = referralTimestamp(rawIssuedAt === undefined || rawIssuedAt === null ? Math.floor(Date.now() / 1000) : rawIssuedAt, "referral_time_invalid");
+        const nonceVal = options.nonce === undefined || options.nonce === null
+            ? core.crypto.randomBytes(16).toString("hex")
+            : referralIdentifier(options.nonce, "referral_nonce_invalid");
+        const rawPrivateKey = options.privateKey !== undefined ? options.privateKey : options.private_key;
+        let signingKey, signerKid;
+        try {
+            signingKey = core.loadEd25519PrivateKey(rawPrivateKey);
+            signerKid = keyId(core.crypto.createPublicKey(signingKey));
+        }
+        catch {
+            fail("referral_private_key_invalid");
+        }
+        const unsigned = {
+            schema: REFERRAL_SCHEMA,
+            issuer: issuerVal,
+            audience: audienceVal,
+            purpose: REFERRAL_PURPOSE,
+            subject_id: subjectVal,
+            card_digest: rawCardDigest,
+            destination_id: destVal,
+            target_url: normalizedUrl,
+            epoch_id: epochVal,
+            policy_revision: policyVal,
+            issued_at: at,
+            expires_at: at + ttlVal,
+            ttl_seconds: ttlVal,
+            nonce: nonceVal,
+            key_id: signerKid,
+        };
+        const signature = core.b64url(core.crypto.sign(null, canonicalJsonBuffer(unsigned), signingKey));
+        const signed = { ...unsigned, signature };
+        return { ...signed, digest: digest(signed) };
+    }
+    function verifySignedReferral(token, options = {}) {
+        referralRequire(object(token) && token.schema === REFERRAL_SCHEMA, "referral_invalid");
+        referralRequire(object(options), "referral_invalid");
+        const keys = Object.keys(token);
+        referralRequire(keys.length === REFERRAL_FIELDS.length && REFERRAL_FIELDS.every((k) => own(token, k)), "referral_invalid");
+        referralRequire(token.purpose === REFERRAL_PURPOSE, "referral_purpose_invalid");
+        const suppliedDigest = token.digest;
+        referralRequire(typeof suppliedDigest === "string" && REFERRAL_SHA256_RE.test(suppliedDigest), "referral_digest_mismatch");
+        const signedBody = without(token, ["digest"]);
+        let expectedDigest;
+        try {
+            expectedDigest = digest(signedBody);
+        }
+        catch {
+            fail("referral_digest_mismatch");
+        }
+        referralRequire(core.secureEquals(suppliedDigest, expectedDigest), "referral_digest_mismatch");
+        const issuerVal = referralIdentifier(token.issuer, "referral_issuer_invalid");
+        const audienceVal = referralIdentifier(token.audience, "referral_audience_invalid");
+        const subjectVal = referralSubjectId(token.subject_id);
+        referralRequire(typeof token.card_digest === "string" && REFERRAL_SHA256_RE.test(token.card_digest), "referral_card_digest_invalid");
+        const destVal = referralIdentifier(token.destination_id, "referral_destination_invalid");
+        const [normalizedUrl, targetHost] = referralTargetUrl(token.target_url);
+        referralRequire(normalizedUrl === token.target_url, "referral_target_url_invalid");
+        const epochVal = referralIdentifier(token.epoch_id, "referral_epoch_invalid");
+        const policyVal = referralIdentifier(token.policy_revision, "referral_policy_revision_invalid");
+        const issuedAt = referralTimestamp(token.issued_at, "referral_time_invalid");
+        const expiresAt = referralTimestamp(token.expires_at, "referral_time_invalid");
+        const ttlVal = referralTtl(token.ttl_seconds);
+        referralRequire(expiresAt === issuedAt + ttlVal, "referral_window_invalid");
+        referralIdentifier(token.nonce, "referral_nonce_invalid");
+        const at = referralTimestamp(options.now, "referral_time_invalid");
+        referralRequire(at >= issuedAt, "referral_not_yet_valid");
+        referralRequire(at <= expiresAt, "referral_expired");
+        const rawPublicKey = options.publicKey !== undefined ? options.publicKey : options.public_key;
+        let pub, expectedKid;
+        try {
+            pub = loadEd25519PublicKey(rawPublicKey);
+            expectedKid = keyId(pub);
+        }
+        catch {
+            fail("referral_public_key_invalid");
+        }
+        referralRequire(token.key_id === expectedKid, "referral_key_mismatch");
+        const sigBytes = core.strictB64urlDecode(token.signature, "referral_signature_invalid");
+        const unsignedBody = without(signedBody, ["signature"]);
+        referralRequire(core.crypto.verify(null, canonicalJsonBuffer(unsignedBody), pub, sigBytes), "referral_signature_invalid");
+        const expectedIssuer = options.expectedIssuer !== undefined ? options.expectedIssuer : options.expected_issuer;
+        if (expectedIssuer !== undefined && expectedIssuer !== null)
+            referralRequire(issuerVal === expectedIssuer, "referral_issuer_mismatch");
+        const expectedAudience = options.expectedAudience !== undefined ? options.expectedAudience : options.expected_audience;
+        if (expectedAudience !== undefined && expectedAudience !== null)
+            referralRequire(audienceVal === expectedAudience, "referral_audience_mismatch");
+        const expectedSubjectId = options.expectedSubjectId !== undefined ? options.expectedSubjectId : options.expected_subject_id;
+        if (expectedSubjectId !== undefined && expectedSubjectId !== null)
+            referralRequire(subjectVal === expectedSubjectId, "referral_subject_mismatch");
+        const expectedCardDigest = options.expectedCardDigest !== undefined ? options.expectedCardDigest : options.expected_card_digest;
+        if (expectedCardDigest !== undefined && expectedCardDigest !== null)
+            referralRequire(token.card_digest === expectedCardDigest, "referral_card_digest_mismatch");
+        const expectedDestinationId = options.expectedDestinationId !== undefined ? options.expectedDestinationId : options.expected_destination_id;
+        if (expectedDestinationId !== undefined && expectedDestinationId !== null)
+            referralRequire(destVal === expectedDestinationId, "referral_destination_mismatch");
+        const expectedEpochId = options.expectedEpochId !== undefined ? options.expectedEpochId : options.expected_epoch_id;
+        if (expectedEpochId !== undefined && expectedEpochId !== null)
+            referralRequire(epochVal === expectedEpochId, "referral_epoch_mismatch");
+        const expectedPolicyRevision = options.expectedPolicyRevision !== undefined ? options.expectedPolicyRevision : options.expected_policy_revision;
+        if (expectedPolicyRevision !== undefined && expectedPolicyRevision !== null)
+            referralRequire(policyVal === expectedPolicyRevision, "referral_policy_revision_mismatch");
+        const allowedDestinations = options.allowedDestinations !== undefined ? options.allowedDestinations : options.allowed_destinations;
+        if (allowedDestinations !== undefined && allowedDestinations !== null) {
+            referralRequire(object(allowedDestinations) && own(allowedDestinations, destVal), "referral_destination_unregistered");
+            const [registeredUrl] = referralTargetUrl(allowedDestinations[destVal]);
+            referralRequire(registeredUrl === normalizedUrl, "referral_target_url_mismatch");
+        }
+        return {
+            verified: true,
+            subject_id: subjectVal,
+            card_digest: token.card_digest,
+            destination_id: destVal,
+            target_url: normalizedUrl,
+            target_host: targetHost,
+            epoch_id: epochVal,
+            policy_revision: policyVal,
+            receipt_digest: suppliedDigest,
+        };
+    }
     return { AuthorizationLeaseError, verifyAuthorizationLease, leaseClearanceContext, guardLeasedAction,
         planDigest, occurrenceContext, occurrenceId, contextDigest, issueClearance, checkExecutionGate,
-        claimExecution, createInMemoryExecutionClaimStore, recordExecutionOutcome };
+        claimExecution, createInMemoryExecutionClaimStore, recordExecutionOutcome,
+        buildSignedReferral, verifySignedReferral };
 }
 // The consumer-registration verifier lives in the public trust layer, which itself loads
 // this module through internal/comm.js; resolving it lazily at call time avoids the cycle.

package/js/shield.d.ts

@@ -35,6 +35,7 @@ export {
   VerifiedLeaseRequest,
   actionKey,
   authorizeExecution,
+  buildSignedReferral,
   checkExecutionGate,
   claimExecution,
   contextDigest,
@@ -59,4 +60,5 @@ export {
   toolAuthorityMatches,
   validateToolCatalog,
   verifyAuthorizationLease,
+  verifySignedReferral,
 } from "../index";

package/js/shield.js

@@ -16,6 +16,8 @@ module.exports = {
   claimExecution: impl.authorizationLeaseApi.claimExecution,
   createInMemoryExecutionClaimStore: impl.authorizationLeaseApi.createInMemoryExecutionClaimStore,
   recordExecutionOutcome: impl.authorizationLeaseApi.recordExecutionOutcome,
+  buildSignedReferral: impl.authorizationLeaseApi.buildSignedReferral,
+  verifySignedReferral: impl.authorizationLeaseApi.verifySignedReferral,
   scanText: impl.scanText,
   MEMORY_SCHEMA: memory.MEMORY_SCHEMA,
   REVOCATION_SCHEMA: memory.REVOCATION_SCHEMA,

package/js/shield.mjs

@@ -12,6 +12,8 @@ export const checkExecutionGate = api.checkExecutionGate;
 export const claimExecution = api.claimExecution;
 export const createInMemoryExecutionClaimStore = api.createInMemoryExecutionClaimStore;
 export const recordExecutionOutcome = api.recordExecutionOutcome;
+export const buildSignedReferral = api.buildSignedReferral;
+export const verifySignedReferral = api.verifySignedReferral;
 export const scanText = api.scanText;
 export const MEMORY_SCHEMA = api.MEMORY_SCHEMA;
 export const REVOCATION_SCHEMA = api.REVOCATION_SCHEMA;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.18-pre-alpha",
+  "version": "0.2.19-pre-alpha",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",