twin3-sdk 0.2.17-pre-alpha → 0.2.19-pre-alpha

package/README.md

@@ -116,22 +116,24 @@ 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.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`.
+`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).
 
 `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.17-pre-alpha
-pip install twin3-sdk==0.2.17a0
+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.17-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"];
@@ -1708,6 +1711,16 @@ export declare class TransitionError extends Error {
 export declare function emptyTaskStore(): { schema: typeof TASK_STORE_SCHEMA; owners: Record<string, any> };
 export declare function normalizeTaskStore(value: unknown): Record<string, any>;
 export declare class TaskInbox {
+  readIssuerCompletions(envelope: Envelope, options?: { limit?: number; cursor?: [number, string] | null; now?: number | null }): {
+    tasks: TaskInboxTask[]; next_cursor: [number, string] | null;
+  };
+  applyCompletionPolicy(taskId: string, policy: CompletionPolicy, envelope: Envelope,
+    options?: { now?: number | null; acceptedAt?: number | null }): TaskInboxTask & { completion: CompletionJournal };
+  readCompletion(taskId: string, envelope: Envelope, options?: { now?: number | null }): TaskInboxTask;
+  applyCompletionReport(taskId: string, command: CompletionCommand, envelope: Envelope,
+    options?: { now?: number | null }): TaskInboxTask & { completion: CompletionJournal };
+  applyCompletion(taskId: string, command: CompletionCommand, actor: string,
+    options?: { verifier?: string | null; now?: number | null }): TaskInboxTask & { completion: CompletionJournal };
   constructor(taskStore: Record<string, any>, counterparties: CounterpartyTable, owner: string,
     options?: Omit<TaskInboxOptions, "store" | "taskStore" | "counterparties" | "owner">);
   constructor(options: TaskInboxOptions & {
@@ -1950,3 +1963,63 @@ export declare function verifyConsumerRegistration(statement: ConsumerRegistrati
   rootPublicKey: string | Buffer | import("node:crypto").KeyObject; expectedKid?: string | null; now: number;
   expected?: ConsumerRegistrationExpectation | null;
 }): VerifiedConsumerRegistration;
+export type CompletionMode = "manual" | "platform" | "api";
+export type CompletionFormat = "text" | "link" | "image" | "pdf";
+export type CompletionStatus = "awaiting_submission" | "pending_review" | "pending_check" | "awaiting_report" | "completed" | "rejected" | "unverified";
+export interface CompletionRules {
+  mode: CompletionMode;
+  conditions: Record<string, unknown>;
+  evidence_required: boolean;
+  evidence_formats: CompletionFormat[];
+  allow_resubmit: boolean;
+}
+export interface CompletionEvidence { kind: CompletionFormat; reference: string; }
+export type CompletionCommand = { operation_id: string; expected_revision: number } & (
+  { action: "configure"; rules: CompletionRules } |
+  { action: "submit"; evidence: CompletionEvidence[] } |
+  { action: "decide"; outcome: "passed" | "failed" | "unavailable"; reason: string }
+);
+export interface CompletionSubmission { evidence: CompletionEvidence[]; submitted_at: number; revision: number; }
+export interface CompletionEvent {
+  policy?: CompletionPolicyReference;
+  revision: number;
+  rules_version: number;
+  actor: string;
+  at: number;
+  command: CompletionCommand;
+  status: CompletionStatus;
+  submission: CompletionSubmission | null;
+}
+export interface CompletionJournal {
+  policy?: CompletionPolicyReference;
+  revision: number;
+  rules_version: number;
+  rules: CompletionRules | null;
+  status: CompletionStatus;
+  submission: CompletionSubmission | null;
+  history: CompletionEvent[];
+  operations: Record<string, { actor: string; verifier: string | null; command: CompletionCommand }>;
+}
+export declare class CompletionError extends Error {}
+export interface CompletionPolicy { version: number; operation_id: string; rules: CompletionRules; }
+export interface CompletionPolicyReference { version: number; operation_id: string; digest: string; }
+export interface CompletionOfferScope {
+  kind: Envelope["kind"];
+  signature_verified: boolean;
+  sender_key: string;
+  sender_key_id: string | null;
+  envelope_id: string;
+  envelope_digest: string;
+}
+export declare function completionPolicyPayload(task: CompletionOfferScope, policy: CompletionPolicy): {
+  scope: "task_offer_completion_all_recipients";
+  sender_key: string; sender_key_id: string; envelope_id: string; envelope_digest: string; policy_digest: string;
+};
+export declare function completionIssuerReadPayload(): { scope: "task_completion_issuer_read" };
+export declare function completionReportPayload(task: { task_id: string; owner: string }, command: CompletionCommand | { action: "read" }): {
+  task_id: string; owner: string; completion_digest: string;
+};
+export declare function applyTaskCompletion<T extends { task_id: string; owner: string; sender_key: string; completion?: CompletionJournal }>(
+  task: T, command: CompletionCommand, actor: string,
+  options?: { verifier?: string | null; now?: number }
+): T & { completion: CompletionJournal };

package/js/comm/completion.js

@@ -0,0 +1,157 @@
+"use strict";
+
+class CompletionError extends Error {}
+
+function fail(code) { throw new CompletionError(code); }
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function identifier(value) { return typeof value === "string" && [...value].length >= 1 && [...value].length <= 256 && value === value.trim(); }
+function keys(value, expected) { return object(value) && Object.keys(value).sort().join(",") === [...expected].sort().join(","); }
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+function equal(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => equal(v, b[i]));
+  if (!object(a) || !object(b) || !keys(a, Object.keys(b))) return false;
+  return Object.keys(a).every(k => equal(a[k], b[k]));
+}
+function jsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(jsonValue);
+  return object(value) && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every(jsonValue);
+}
+function rules(value) {
+  if (!keys(value, ["mode", "conditions", "evidence_required", "evidence_formats", "allow_resubmit"])) fail("invalid_completion_rules");
+  if (!["manual", "platform", "api"].includes(value.mode)
+      || typeof value.evidence_required !== "boolean" || typeof value.allow_resubmit !== "boolean") fail("invalid_completion_rules");
+  const formats = value.evidence_formats;
+  if (!Array.isArray(formats) || new Set(formats).size !== formats.length
+      || formats.some(kind => !["text", "link", "image", "pdf"].includes(kind))
+      || (value.evidence_required && !formats.length)
+      || !object(value.conditions) || !Object.keys(value.conditions).length) fail("invalid_completion_rules");
+  return clone(value);
+}
+function evidence(value, policy) {
+  if (!Array.isArray(value) || value.length > 20) fail("invalid_completion_evidence");
+  if (policy.evidence_required && !value.length) fail("completion_evidence_required");
+  for (const item of value) {
+    if (!keys(item, ["kind", "reference"]) || !policy.evidence_formats.includes(item.kind) || !identifier(item.reference)) fail("invalid_completion_evidence");
+  }
+  return clone(value);
+}
+function pending(policy) { return { manual: "pending_review", platform: "pending_check", api: "awaiting_report" }[policy.mode]; }
+
+function applyTaskCompletion(task, command, actor, { verifier = null, now = Date.now() / 1000 } = {}) {
+  if (!object(task) || !["task_id", "owner", "sender_key"].every(key => identifier(task[key]))) fail("invalid_completion_task");
+  if (!identifier(actor) || ![task.owner, task.sender_key, verifier].includes(actor)) fail("completion_actor_forbidden");
+  if (verifier !== null && (!identifier(verifier) || [task.owner, task.sender_key].includes(verifier))) fail("invalid_completion_verifier");
+  const fields = { configure: ["rules"], submit: ["evidence"], decide: ["outcome", "reason"] };
+  if (!object(command) || !Object.hasOwn(fields, command.action)
+      || !keys(command, ["action", "operation_id", "expected_revision", ...fields[command.action]])) fail("invalid_completion_command");
+  if (!identifier(command.operation_id)) fail("completion_operation_required");
+  const expected = command.expected_revision;
+  if (!Number.isSafeInteger(expected) || expected < 0) fail("invalid_completion_revision");
+  if (typeof now !== "number" || !Number.isFinite(now) || now < 0) fail("invalid_completion_time");
+  try {
+    if (!jsonValue(command)) fail("invalid_completion_command");
+    if (Buffer.byteLength(JSON.stringify(command)) > 65536) fail("completion_command_too_large");
+  } catch (error) {
+    if (error instanceof CompletionError) throw error;
+    fail("invalid_completion_command");
+  }
+  const result = clone(task);
+  const journal = result.completion ||= { revision: 0, rules_version: 0, rules: null,
+    status: "awaiting_submission", submission: null, history: [], operations: {} };
+  const operation = command.operation_id;
+  const payload = { actor, verifier, command };
+  if (Object.hasOwn(journal.operations, operation)) {
+    if (!equal(journal.operations[operation], payload)) fail("completion_idempotency_conflict");
+    return result;
+  }
+  if (expected !== journal.revision) fail("stale_completion_revision");
+  if (journal.history.length && now < journal.history.at(-1).at) fail("invalid_completion_time");
+  if (command.action === "configure") {
+    if (actor !== task.sender_key) fail("completion_issuer_required");
+    if (journal.policy) fail("completion_policy_required");
+    journal.rules = rules(command.rules);
+    journal.rules_version += 1;
+    journal.status = journal.submission !== null ? pending(journal.rules) : "awaiting_submission";
+  } else {
+    const policy = journal.rules;
+    if (policy === null) fail("completion_rules_required");
+    if (command.action === "submit") {
+      if (actor !== task.owner) fail("completion_participant_required");
+      if (journal.status === "completed") fail("completion_already_completed");
+      if (journal.status === "rejected" && !policy.allow_resubmit) fail("completion_resubmission_forbidden");
+      journal.submission = { evidence: evidence(command.evidence, policy), submitted_at: now, revision: expected + 1 };
+      journal.status = pending(policy);
+    } else {
+      const reviewer = policy.mode === "platform" ? verifier : task.sender_key;
+      if (reviewer === null || actor !== reviewer) fail("completion_reviewer_forbidden");
+      if (journal.submission === null) fail("completion_submission_required");
+      if (["completed", "rejected"].includes(journal.status)) fail("completion_decision_final");
+      if (!["passed", "failed", "unavailable"].includes(command.outcome) || !identifier(command.reason)) fail("invalid_completion_decision");
+      if (command.outcome === "passed") evidence(journal.submission.evidence, policy);
+      journal.status = { passed: "completed", failed: "rejected", unavailable: "unverified" }[command.outcome];
+    }
+  }
+  journal.revision += 1;
+  journal.history.push({ revision: journal.revision, rules_version: journal.rules_version, actor,
+    at: now, command: clone(command), status: journal.status, submission: clone(journal.submission) });
+  Object.defineProperty(journal.operations, operation, { value: clone(payload), enumerable: true, configurable: true, writable: true });
+  return result;
+}
+
+function completionIssuerReadPayload() {
+  return { scope: "task_completion_issuer_read" };
+}
+
+function completionReportPayload(task, command) {
+  if (!object(task) || !identifier(task.task_id) || !identifier(task.owner)) fail("invalid_completion_task");
+  if (!object(command) || !jsonValue(command)) fail("invalid_completion_command");
+  const core = require("../internal/core.js");
+  return { task_id: task.task_id, owner: task.owner,
+    completion_digest: core.crypto.createHash("sha256").update(core.canonicalJsonBuffer(command)).digest("hex") };
+}
+
+function completionPolicyPayload(task, policy) {
+  if (!object(task) || task.kind !== "task_offer" || task.signature_verified !== true
+      || !["sender_key", "sender_key_id", "envelope_id", "envelope_digest"].every(key => identifier(task[key]))) fail("invalid_completion_offer");
+  if (!keys(policy, ["version", "operation_id", "rules"]) || !Number.isSafeInteger(policy.version) || policy.version < 1
+      || !identifier(policy.operation_id) || [...policy.operation_id].length > 128) fail("invalid_completion_policy");
+  try { if (!jsonValue(policy)) fail("invalid_completion_policy"); }
+  catch { fail("invalid_completion_policy"); }
+  rules(policy.rules);
+  if (Buffer.byteLength(JSON.stringify(policy)) > 65536) fail("completion_command_too_large");
+  const core = require("../internal/core.js");
+  const payload = { scope: "task_offer_completion_all_recipients", sender_key: task.sender_key,
+    sender_key_id: task.sender_key_id, envelope_id: task.envelope_id, envelope_digest: task.envelope_digest,
+    policy_digest: core.crypto.createHash("sha256").update(core.canonicalJsonBuffer(policy)).digest("hex") };
+  return payload;
+}
+
+function applyCompletionPolicy(task, policy, actor, { now = Date.now() / 1000 } = {}) {
+  const payload = completionPolicyPayload(task, policy);
+  if (actor !== task.sender_key) fail("completion_issuer_required");
+  const core = require("../internal/core.js");
+  const digest = core.crypto.createHash("sha256").update(core.canonicalJsonBuffer(payload)).digest("hex");
+  const previous = task.completion?.policy;
+  const applied = (task.completion?.history || []).find(event => event.policy?.operation_id === policy.operation_id);
+  if (applied) {
+    if (!core.secureEquals(applied.policy.digest, digest)) fail("completion_policy_conflict");
+    return clone(task);
+  }
+  if (previous && policy.version < previous.version) fail("stale_completion_policy");
+  if (previous && policy.version === previous.version) {
+    if (!core.secureEquals(previous.digest, digest)) fail("completion_policy_conflict");
+    return clone(task);
+  }
+  const input = clone(task);
+  if (input.completion) delete input.completion.policy;
+  const result = applyTaskCompletion(input, { action: "configure", operation_id: `policy:${policy.version}:${policy.operation_id}`,
+    expected_revision: input.completion?.revision || 0, rules: policy.rules }, actor, { now });
+  result.completion.policy = { version: policy.version, operation_id: policy.operation_id, digest };
+  result.completion.history.at(-1).policy = clone(result.completion.policy);
+  return result;
+}
+
+module.exports = { CompletionError, applyTaskCompletion, completionReportPayload, completionPolicyPayload, completionIssuerReadPayload, applyCompletionPolicy };

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/comm.d.ts

@@ -1,3 +1,9 @@
+export {
+  CompletionMode, CompletionFormat, CompletionStatus, CompletionRules, CompletionEvidence,
+  CompletionCommand, CompletionSubmission, CompletionEvent, CompletionJournal,
+  CompletionError, completionReportPayload, applyTaskCompletion,
+  CompletionPolicy, CompletionPolicyReference, CompletionOfferScope, completionPolicyPayload, completionIssuerReadPayload
+} from "../index";
 export {
   ACCESS_GRANT_SCHEMA,
   COUNTERPARTY_RECORD_SCHEMA,

package/js/comm.js

@@ -1,7 +1,13 @@
 "use strict";
 const impl = require("./internal/comm.js");
+const completion = require("./comm/completion.js");
 
 module.exports = {
+  CompletionError: completion.CompletionError,
+  applyTaskCompletion: completion.applyTaskCompletion,
+  completionReportPayload: completion.completionReportPayload,
+  completionPolicyPayload: completion.completionPolicyPayload,
+  completionIssuerReadPayload: completion.completionIssuerReadPayload,
   TaskInbox: impl.TaskInbox,
   IntakeRejected: impl.IntakeRejected,
   TransitionError: impl.TransitionError,

package/js/comm.mjs

@@ -1,4 +1,9 @@
 import api from "./comm.js";
+export const CompletionError = api.CompletionError;
+export const applyTaskCompletion = api.applyTaskCompletion;
+export const completionReportPayload = api.completionReportPayload;
+export const completionPolicyPayload = api.completionPolicyPayload;
+export const completionIssuerReadPayload = api.completionIssuerReadPayload;
 export const TaskInbox = api.TaskInbox;
 export const IntakeRejected = api.IntakeRejected;
 export const TransitionError = api.TransitionError;

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;