twin3-sdk 0.2.20-pre-alpha → 0.3.0

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.20-pre-alpha` is the current release candidate: `0.2.20-pre-alpha` for npm and `0.2.20a0` 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.3.0` is the current production release: `0.3.0` for npm and `0.3.0` for PyPI, published on the npm dist-tag `latest` as an immutable GitHub release for Google Cloud Marketplace GM-13. It is the first production, non-prerelease release and has no API changes from 0.2.21-pre-alpha. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency.
 
 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.20-pre-alpha
-pip install twin3-sdk==0.2.20a0
+npm install twin3-sdk@0.3.0
+pip install twin3-sdk==0.3.0
 ```
 
 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.20-pre-alpha.tgz
+npm install ./twin3-sdk-0.3.0.tgz
 ```
 
 ---

package/index.d.ts

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

package/js/ai-visibility.js

@@ -0,0 +1,616 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const CATALOG = require("../twin3/discovery/ai-visibility-catalog.json");
+
+const CATALOG_VERSION = CATALOG.version;
+const VISIT_EVIDENCE_SCHEMA = "twin3-discovery-visit-evidence-v1";
+const ENGINE_READING_SCHEMA = "twin3-discovery-engine-reading-v1";
+const AI_REFERRAL_SCHEMA = "twin3-discovery-ai-referral-v1";
+const AI_CRAWLER_SCHEMA = "twin3-discovery-ai-crawler-v1";
+const AI_READINESS_SCHEMA = "twin3-discovery-ai-readiness-v1";
+const AI_TRAJECTORY_SCHEMA = "twin3-discovery-ai-trajectory-v1";
+
+const PURPOSES = ["training", "search", "user", "agent", "other"];
+const SIGNALS = ["retrieved", "mentioned", "cited"];
+const STAGES = CATALOG.stages.map(stage => stage.key);
+const MIN_VISIBLE_CHARS = 200;
+const SCORE_WEIGHTS = {
+  mentioned: 12,
+  cited: 5,
+  divisor: 17,
+  source: "ansvisor visibility-score 0.60 mention / 0.25 citation, position term dropped",
+};
+const READINESS_NON_CLAIMS = [
+  "robots_allow_is_not_proof_of_indexing",
+  "readiness_is_not_visibility",
+  "unverified_user_agent_responses_not_tested",
+  "llms_txt_has_no_documented_ranking_effect",
+];
+const TRAJECTORY_NON_CLAIMS = [
+  "user_agent_claims_are_not_verified_operator_identity",
+  "referrer_counts_undercount_apps_that_strip_referrers",
+  "rates_do_not_pool_across_engines",
+  "stages_are_not_a_causal_funnel",
+];
+const ENTITY_TYPES = new Set([
+  "Organization", "Corporation", "LocalBusiness", "NGO", "Person", "ProfilePage", "Brand",
+  "SoftwareApplication", "WebApplication", "WebAPI", "Product", "Service",
+]);
+
+const WS = " \t\n\r\f";
+const HOST = /^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/;
+const OPERATOR = /^[A-Za-z0-9](?:[A-Za-z0-9 ._-]{0,78}[A-Za-z0-9.])?$/;
+const ENGINE = /^[A-Za-z0-9._:/-](?:[A-Za-z0-9 ._:/-]{0,78}[A-Za-z0-9._:/-])?$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const DIRECTIVE = /^[a-z0-9_:-]{1,40}$/;
+const TYPE_NAME = /^[A-Za-z0-9:/._#-]{1,100}$/;
+const RAW_TEXT = /<(script|style|template)(?=[\t\n\f\r />])([^>]*)>([\s\S]*?)<\/\1[\t\n\f\r ]*>/gi;
+const ATTR = /([A-Za-z_:][-A-Za-z0-9_:.]*)(?:[\t\n\f\r ]*=[\t\n\f\r ]*(?:"([^"]*)"|'([^']*)'|([^\t\n\f\r "'>`=<]+)))?/g;
+const escapeRegex = value => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const CRAWLER_PATTERNS = CATALOG.crawlers.filter(crawler => crawler.user_agent).map(crawler =>
+  [crawler, new RegExp("(?:^|[^A-Za-z0-9_-])" + escapeRegex(crawler.token) + "(?:$|[^A-Za-z0-9_@.-])", "i")]);
+const CRAWLERS_BY_TOKEN = new Map(CATALOG.crawlers.map(crawler => [crawler.token, crawler]));
+const PRIORITY = { P0: 0, P1: 1, P2: 2, P3: 3 };
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+class AiVisibilityError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "AiVisibilityError";
+    this.code = code;
+  }
+}
+
+function requireValue(condition, code) {
+  if (!condition) throw new AiVisibilityError(code);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+function get(record, key) {
+  return Object.hasOwn(record, key) && record[key] !== undefined ? record[key] : null;
+}
+
+function asciiLower(value) {
+  return value.replace(/[A-Z]/g, char => String.fromCharCode(char.charCodeAt(0) + 32));
+}
+
+function strip(value, chars = WS) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && chars.includes(value[start])) start += 1;
+  while (end > start && chars.includes(value[end - 1])) end -= 1;
+  return value.slice(start, end);
+}
+
+function codePoints(value) {
+  let count = 0;
+  for (const _ of value) count += 1;
+  return count;
+}
+
+function text(value, limit, code) {
+  requireValue(typeof value === "string" && value.length <= limit * 2 && !/[\ud800-\udfff]/u.test(value) && codePoints(value) <= limit, code);
+  return value;
+}
+
+function optionalText(value, limit, code) {
+  return value === null || value === undefined ? null : text(value, limit, code);
+}
+
+function hostValue(value, code = "host_invalid") {
+  requireValue(typeof value === "string" && !/[^\x00-\x7f]/.test(value), code);
+  const host = asciiLower(strip(value, WS + "\v")).replace(/\.$/, "");
+  requireValue(HOST.test(host) && !host.includes(".."), code);
+  return host;
+}
+
+function count(value, code, minimum = 0) {
+  requireValue(Number.isSafeInteger(value) && minimum <= value && value <= 1_000_000_000, code);
+  return value;
+}
+
+function stripWww(host) {
+  return host.startsWith("www.") ? host.slice(4) : host;
+}
+
+function under(value, host) {
+  return value === host || value.endsWith("." + host);
+}
+
+function urlParts(value) {
+  const match = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?(#[\s\S]*)?$/.exec(value);
+  if (match === null || !["http", "https"].includes(asciiLower(match[1]))) return null;
+  const authority = match[2];
+  if (authority.includes("@") || authority.includes("[")) return null;
+  let host;
+  try {
+    host = hostValue(authority.split(":")[0]);
+  } catch {
+    return null;
+  }
+  return [host, match[3] || "/", (match[4] || "").slice(1)];
+}
+
+function landingMedium(landingUrl) {
+  const parts = landingUrl === null ? null : urlParts(landingUrl);
+  if (parts === null) return "";
+  for (const pair of parts[2].split("&")) {
+    const index = pair.indexOf("=");
+    const name = index < 0 ? pair : pair.slice(0, index);
+    if (asciiLower(name) === "utm_medium") return asciiLower(index < 0 ? "" : pair.slice(index + 1));
+  }
+  return "";
+}
+
+function surfaceOf(source, landingUrl) {
+  const medium = landingMedium(landingUrl);
+  if (!medium) return null;
+  const surface = (source.surfaces || []).find(item => item.medium === medium);
+  return surface ? surface.key : null;
+}
+
+function classifyAiReferral(referrer = null, { landingUrl = null, utmSource = null } = {}) {
+  referrer = optionalText(referrer, 2048, "referral_invalid");
+  landingUrl = optionalText(landingUrl, 4096, "referral_invalid");
+  utmSource = optionalText(utmSource, 256, "referral_invalid");
+  let match = null;
+  if (referrer) {
+    let parts = referrer.includes("://") ? urlParts(referrer) : null;
+    if (parts === null && !referrer.includes("://")) {
+      try {
+        parts = [hostValue(referrer), null, ""];
+      } catch {
+        parts = null;
+      }
+    }
+    if (parts !== null) {
+      const host = stripWww(parts[0]);
+      const path = parts[1];
+      for (const source of CATALOG.referral_sources) {
+        if (!source.hosts.some(candidate => under(host, candidate))) continue;
+        const required = source.referrer_path;
+        if (required !== undefined && (path === null || !path.startsWith(required))) continue;
+        match = [source, "referrer"];
+        break;
+      }
+    }
+  }
+  if (match === null && utmSource) {
+    const value = stripWww(asciiLower(strip(utmSource)));
+    for (const source of CATALOG.referral_sources) {
+      if (source.utm === false) continue;
+      if (source.aliases.includes(value) || source.hosts.some(candidate => under(value, candidate))) {
+        match = [source, "utm"];
+        break;
+      }
+    }
+  }
+  if (match === null) return null;
+  const [source, origin] = match;
+  return {
+    schema: AI_REFERRAL_SCHEMA,
+    source: source.key,
+    operator: source.operator,
+    origin,
+    surface: surfaceOf(source, landingUrl),
+    catalog_version: CATALOG_VERSION,
+  };
+}
+
+function classifyAiCrawler(userAgent) {
+  userAgent = text(userAgent, 2048, "crawler_user_agent_invalid");
+  for (const [crawler, pattern] of CRAWLER_PATTERNS) {
+    if (pattern.test(userAgent)) {
+      return {
+        schema: AI_CRAWLER_SCHEMA,
+        token: crawler.token,
+        operator: crawler.operator,
+        purpose: crawler.purpose,
+        robots: crawler.robots,
+        catalog_version: CATALOG_VERSION,
+      };
+    }
+  }
+  return null;
+}
+
+function parseRobots(source) {
+  const groups = [];
+  let current = null;
+  let lastWasAgent = false;
+  for (const raw of source.replace(/^/, "").split(/\r\n|\n|\r/)) {
+    const line = strip(raw.split("#")[0], WS + "\v");
+    if (!line || !line.includes(":")) continue;
+    const index = line.indexOf(":");
+    const name = asciiLower(strip(line.slice(0, index), WS + "\v"));
+    const value = strip(line.slice(index + 1), WS + "\v");
+    if (name === "user-agent") {
+      if (current === null || !lastWasAgent) {
+        current = { agents: [], rules: [] };
+        groups.push(current);
+      }
+      current.agents.push(asciiLower(value));
+      lastWasAgent = true;
+      continue;
+    }
+    lastWasAgent = false;
+    if (current !== null && (name === "allow" || name === "disallow")) current.rules.push([name, value]);
+  }
+  return groups;
+}
+
+function selectGroup(groups, token) {
+  const lowered = asciiLower(token);
+  const named = groups.filter(group => group.agents.includes(lowered));
+  const chosen = named.length ? named : groups.filter(group => group.agents.includes("*"));
+  const matched = named.length ? "named" : chosen.length ? "star" : "none";
+  return [matched, chosen.flatMap(group => group.rules)];
+}
+
+function patternMatches(pattern, path) {
+  const anchored = pattern.endsWith("$");
+  const parts = (anchored ? pattern.slice(0, -1) : pattern).split("*");
+  if (!path.startsWith(parts[0])) return false;
+  let position = parts[0].length;
+  if (parts.length === 1) return anchored ? position === path.length : true;
+  for (const part of parts.slice(1, -1)) {
+    const index = path.indexOf(part, position);
+    if (index < 0) return false;
+    position = index + part.length;
+  }
+  const last = parts[parts.length - 1];
+  if (anchored) return path.length - last.length >= position && path.endsWith(last);
+  return path.indexOf(last, position) >= 0;
+}
+
+function allowedBy(rules, path) {
+  let best = -1;
+  let allowed = true;
+  for (const [name, value] of rules) {
+    if (name === "disallow" && value === "") continue;
+    if (patternMatches(value, path) && (value.length > best || (value.length === best && name === "allow"))) {
+      best = value.length;
+      allowed = name === "allow";
+    }
+  }
+  return allowed;
+}
+
+function attributes(tag) {
+  const inner = tag.replace(/^<[A-Za-z0-9]+/, "").replace(/[>/]+$/, "");
+  const found = {};
+  for (const match of inner.matchAll(ATTR)) {
+    const name = asciiLower(match[1]);
+    if (!Object.hasOwn(found, name)) {
+      const value = [match[2], match[3], match[4]].find(group => group !== undefined);
+      found[name] = value === undefined ? "" : value;
+    }
+  }
+  return found;
+}
+
+function tags(html, name) {
+  return [...html.matchAll(new RegExp("<" + name + "(?=[\\t\\n\\f\\r />])[^>]*>", "gi"))].map(match => attributes(match[0]));
+}
+
+function attr(record, key) {
+  return Object.hasOwn(record, key) ? record[key] : "";
+}
+
+function jsonLd(blocks) {
+  const types = new Set();
+  let dated = false;
+  let invalid = 0;
+  for (const block of blocks.slice(0, 32)) {
+    let value;
+    try {
+      value = JSON.parse(block);
+    } catch {
+      invalid += 1;
+      continue;
+    }
+    const stack = [[value, 0]];
+    while (stack.length) {
+      const [node, depth] = stack.pop();
+      if (depth > 64) continue;
+      if (node !== null && typeof node === "object" && !Array.isArray(node)) {
+        const kind = Object.hasOwn(node, "@type") ? node["@type"] : null;
+        for (const name of Array.isArray(kind) ? kind : [kind]) {
+          if (typeof name === "string" && TYPE_NAME.test(name)) types.add(name);
+        }
+        for (const key of ["dateModified", "datePublished"]) {
+          if (Object.hasOwn(node, key) && typeof node[key] === "string" && strip(node[key])) dated = true;
+        }
+        for (const child of Object.values(node)) stack.push([child, depth + 1]);
+      } else if (Array.isArray(node)) {
+        for (const child of node) stack.push([child, depth + 1]);
+      }
+    }
+  }
+  return [[...types].sort(compare), dated, invalid];
+}
+
+function shortType(name) {
+  const parts = name.split(/[/:#]/);
+  return parts[parts.length - 1];
+}
+
+function check(id, priority, status, evidence, action = null) {
+  return { id, priority, status, evidence, action };
+}
+
+function crawlerChecks(robotsTxt, path) {
+  const groups = robotsTxt !== null ? parseRobots(robotsTxt) : [];
+  const present = robotsTxt !== null;
+  const checks = [check("robots_txt", "P2", present ? "pass" : "warn", { present }, present ? null : "publish_robots_txt")];
+  const access = {};
+  for (const crawler of CATALOG.crawlers) {
+    if (crawler.robots === "not_applicable") continue;
+    const [matched, rules] = selectGroup(groups, crawler.token);
+    const allowed = allowedBy(rules, path);
+    access[crawler.token] = { operator: crawler.operator, purpose: crawler.purpose, allowed, matched };
+    const evidence = { allowed, matched, purpose: crawler.purpose, claim: crawler.claim === undefined ? null : crawler.claim };
+    let result;
+    if (crawler.purpose === "search") result = allowed ? ["pass", "P0", null] : ["fail", "P0", "allow_ai_search_crawler"];
+    else if (crawler.purpose === "user") result = allowed ? ["pass", "P1", null] : ["warn", "P1", "allow_user_triggered_fetcher"];
+    else result = ["info", "P3", null];
+    checks.push(check("crawler:" + crawler.token, result[1], result[0], evidence, result[2]));
+  }
+  return [checks, access];
+}
+
+function htmlChecks(source, host) {
+  if (source === null) return [check("html", "P0", "na", { present: false }, "supply_server_rendered_html")];
+  const html = source.replace(/<!--[\s\S]*?-->/g, " ");
+  const ldBlocks = [];
+  for (const match of html.matchAll(RAW_TEXT)) {
+    if (asciiLower(match[1]) !== "script") continue;
+    const kind = asciiLower(strip(attr(attributes("<script" + match[2] + ">"), "type")));
+    if (kind === "application/ld+json") ldBlocks.push(match[3]);
+  }
+  const body = html.replace(RAW_TEXT, " ");
+  let visible = 0;
+  for (const char of body.replace(/<[^>]*>/g, " ")) if (!(WS + "\v ").includes(char)) visible += 1;
+  const enough = visible >= MIN_VISIBLE_CHARS;
+  const checks = [check("ssr_text", "P0", enough ? "pass" : "fail", { visible_chars: visible, minimum: MIN_VISIBLE_CHARS },
+    enough ? null : "server_render_card_content")];
+  const title = /<title(?=[\t\n\f\r />])[^>]*>([\s\S]*?)<\/title[\t\n\f\r ]*>/i.exec(body);
+  const hasTitle = title !== null && Boolean(strip(title[1].replace(/<[^>]*>/g, "")));
+  checks.push(check("title", "P1", hasTitle ? "pass" : "fail", { present: hasTitle }, hasTitle ? null : "add_title"));
+  const metas = tags(body, "meta");
+  const content = (key, value) => metas.some(meta => asciiLower(attr(meta, key)) === value && Boolean(strip(attr(meta, "content"))));
+  const hasDescription = content("name", "description");
+  checks.push(check("meta_description", "P2", hasDescription ? "pass" : "warn", { present: hasDescription },
+    hasDescription ? null : "add_meta_description"));
+  const canonicalLink = tags(body, "link").find(link => asciiLower(attr(link, "rel")).split(/[ \t\n\r\f\v]+/).includes("canonical"));
+  const canonical = canonicalLink === undefined ? null : strip(attr(canonicalLink, "href"));
+  if (!canonical) {
+    checks.push(check("canonical", "P2", "warn", { present: false, same_host: null }, "add_canonical"));
+  } else {
+    const parts = canonical.includes("://") ? urlParts(canonical) : null;
+    const same = (canonical.startsWith("/") && !canonical.startsWith("//")) || (parts !== null && parts[0] === host);
+    checks.push(check("canonical", same ? "P2" : "P1", same ? "pass" : "warn", { present: true, same_host: same },
+      same ? null : "point_canonical_to_card_host"));
+  }
+  const directives = new Set();
+  for (const meta of metas) {
+    if (["robots", "googlebot"].includes(asciiLower(attr(meta, "name")))) {
+      for (const piece of asciiLower(attr(meta, "content")).split(",")) {
+        const part = strip(piece);
+        if (DIRECTIVE.test(part)) directives.add(part);
+      }
+    }
+  }
+  const sortedDirectives = [...directives].sort(compare);
+  if (directives.has("noindex") || directives.has("none")) {
+    checks.push(check("meta_robots", "P0", "fail", { directives: sortedDirectives }, "remove_noindex"));
+  } else if (directives.has("nosnippet")) {
+    checks.push(check("meta_robots", "P1", "warn", { directives: sortedDirectives }, "remove_nosnippet"));
+  } else {
+    checks.push(check("meta_robots", "P0", "pass", { directives: sortedDirectives }));
+  }
+  const [types, ldDated, invalid] = jsonLd(ldBlocks);
+  const entity = types.some(name => ENTITY_TYPES.has(shortType(name)));
+  const evidence = { blocks: ldBlocks.length, invalid, types, entity };
+  if (invalid) checks.push(check("json_ld", "P1", "fail", evidence, "fix_json_ld_syntax"));
+  else if (!ldBlocks.length) checks.push(check("json_ld", "P1", "warn", evidence, "add_entity_json_ld"));
+  else if (!entity) checks.push(check("json_ld", "P2", "warn", evidence, "add_entity_json_ld"));
+  else checks.push(check("json_ld", "P1", "pass", evidence));
+  const dated = ldDated || content("property", "article:modified_time") || content("property", "article:published_time")
+    || tags(body, "time").some(time => Boolean(strip(attr(time, "datetime"))));
+  checks.push(check("freshness", "P2", dated ? "pass" : "warn", { dated }, dated ? null : "publish_dates"));
+  const headings = [...body.matchAll(/<h1(?=[\t\n\f\r />])/gi)].length;
+  checks.push(check("h1", headings === 0 ? "P2" : "P3", headings === 1 ? "pass" : "warn", { count: headings },
+    headings === 1 ? null : "use_one_h1"));
+  return checks;
+}
+
+function operatorEntry() {
+  return {
+    crawl: Object.fromEntries(PURPOSES.map(purpose => [purpose, 0])),
+    refused: 0,
+    engines: {},
+    clicks: 0,
+    click_sources: {},
+    click_surfaces: {},
+    stages: [],
+  };
+}
+
+function signalOf(readingSignal) {
+  requireValue(isRecord(readingSignal), "trajectory_reading_invalid");
+  const state = get(readingSignal, "state");
+  const rate = get(readingSignal, "rate_bp");
+  requireValue(["measured", "withheld", "unknown"].includes(state), "trajectory_reading_invalid");
+  if (state === "measured") requireValue(Number.isInteger(rate) && rate >= 0 && rate <= 10000, "trajectory_reading_invalid");
+  else requireValue(rate === null, "trajectory_reading_invalid");
+  return { state, rate_bp: rate };
+}
+
+function createAiVisibilityApi(canonicalJsonBuffer) {
+  const digest = value => crypto.createHash("sha256").update(canonicalJsonBuffer(value)).digest("hex");
+
+  function verified(row, schema, host, code) {
+    requireValue(isRecord(row) && row.schema === schema && row.host === host, code);
+    const supplied = row.digest;
+    requireValue(typeof supplied === "string" && SHA256.test(supplied), code);
+    const { digest: _, ...body } = row;
+    let expected;
+    try {
+      expected = digest(body);
+    } catch {
+      throw new AiVisibilityError(code);
+    }
+    requireValue(crypto.timingSafeEqual(Buffer.from(supplied, "ascii"), Buffer.from(expected, "ascii")), code);
+  }
+
+  function auditAiReadiness({ host, path = "/", robotsTxt = null, html = null, llmsTxt = null } = {}) {
+    const owner = hostValue(host, "readiness_host_invalid");
+    requireValue(typeof path === "string" && path.startsWith("/") && path.length <= 2048
+      && !/[^\x00-\x7f]/.test(path) && !/[\x00-\x20\x7f?#]/.test(path), "readiness_path_invalid");
+    robotsTxt = optionalText(robotsTxt, 512_000, "readiness_robots_invalid");
+    html = optionalText(html, 2_000_000, "readiness_html_invalid");
+    llmsTxt = optionalText(llmsTxt, 512_000, "readiness_llms_invalid");
+    const [checks, access] = crawlerChecks(robotsTxt, path);
+    checks.push(...htmlChecks(html, owner));
+    checks.push(check("llms_txt", "P3", "info", { present: Boolean(llmsTxt && strip(llmsTxt)) }));
+    const blocking = checks.filter(item => ["fail", "na"].includes(item.status) && item.priority === "P0").map(item => item.id).sort(compare);
+    const actions = checks
+      .filter(item => item.action && ["fail", "warn", "na"].includes(item.status))
+      .map(item => ({ check: item.id, priority: item.priority, action: item.action }))
+      .sort((a, b) => PRIORITY[a.priority] - PRIORITY[b.priority] || compare(a.check, b.check));
+    const body = {
+      schema: AI_READINESS_SCHEMA,
+      host: owner,
+      path,
+      catalog_version: CATALOG_VERSION,
+      checks,
+      crawler_access: access,
+      gate: { passed: !blocking.length, blocking },
+      actions,
+      non_claims: [...READINESS_NON_CLAIMS],
+    };
+    return { ...body, digest: digest(body) };
+  }
+
+  function summarizeAiTrajectory({ host, visits = [], reading = null, referrals = [], engineOperators = null } = {}) {
+    const owner = hostValue(host, "trajectory_host_invalid");
+    requireValue(Array.isArray(visits) && visits.length <= 100_000, "trajectory_visits_invalid");
+    requireValue(Array.isArray(referrals) && referrals.length <= 100_000, "trajectory_referrals_invalid");
+    const mapping = engineOperators === null ? {} : engineOperators;
+    requireValue(isRecord(mapping) && Object.entries(mapping).every(([engine, operator]) =>
+      ENGINE.test(engine) && typeof operator === "string" && OPERATOR.test(operator)), "trajectory_engine_operators_invalid");
+    const operators = {};
+    const ensure = name => (operators[name] = Object.hasOwn(operators, name) ? operators[name] : operatorEntry());
+    const totals = { fetched_requests: 0, refused_requests: 0, unclassified_requests: 0, ai_sessions: 0, non_ai_sessions: 0 };
+    for (const visit of visits) {
+      verified(visit, VISIT_EVIDENCE_SCHEMA, owner, "trajectory_visit_invalid");
+      const requests = count(get(visit, "request_count"), "trajectory_visit_invalid", 1);
+      const status = count(get(visit, "status"), "trajectory_visit_invalid");
+      const bot = get(visit, "bot");
+      if (bot === null) {
+        totals.unclassified_requests += requests;
+        continue;
+      }
+      requireValue(typeof bot === "string" && typeof get(visit, "provider") === "string", "trajectory_visit_invalid");
+      const crawler = CRAWLERS_BY_TOKEN.get(bot);
+      const entry = ensure(crawler ? crawler.operator : visit.provider);
+      const purpose = crawler && PURPOSES.includes(crawler.purpose) ? crawler.purpose : "other";
+      if (status >= 400) {
+        entry.refused += requests;
+        totals.refused_requests += requests;
+      } else {
+        entry.crawl[purpose] += requests;
+        totals.fetched_requests += requests;
+      }
+    }
+    const unattributed = [];
+    let readingDigest = null;
+    let readingValid = null;
+    if (reading !== null) {
+      verified(reading, ENGINE_READING_SCHEMA, owner, "trajectory_reading_invalid");
+      requireValue(isRecord(get(reading, "by_engine")) && typeof get(reading, "valid") === "boolean", "trajectory_reading_invalid");
+      readingDigest = reading.digest;
+      readingValid = reading.valid;
+      for (const engine of Object.keys(reading.by_engine).sort(compare)) {
+        const entryIn = reading.by_engine[engine];
+        requireValue(ENGINE.test(engine), "trajectory_reading_invalid");
+        requireValue(isRecord(entryIn) && isRecord(get(entryIn, "signals")), "trajectory_reading_invalid");
+        const signals = Object.fromEntries(SIGNALS.map(name => [name, signalOf(get(entryIn.signals, name))]));
+        const { mentioned, cited } = signals;
+        const score = mentioned.state === "measured" && cited.state === "measured"
+          ? Math.floor((SCORE_WEIGHTS.mentioned * mentioned.rate_bp + SCORE_WEIGHTS.cited * cited.rate_bp) / SCORE_WEIGHTS.divisor)
+          : null;
+        if (!Object.hasOwn(mapping, engine)) {
+          unattributed.push(engine);
+          continue;
+        }
+        ensure(mapping[engine]).engines[engine] = { ...signals, answer_visibility_bp: score };
+      }
+    }
+    const referralKeys = ["referrer", "landing_url", "utm_source", "sessions"];
+    for (const row of referrals) {
+      requireValue(isRecord(row) && Object.keys(row).every(key => referralKeys.includes(key)), "trajectory_referral_invalid");
+      const sessions = count(Object.hasOwn(row, "sessions") ? row.sessions : 1, "trajectory_referral_invalid", 1);
+      let referral;
+      try {
+        referral = classifyAiReferral(get(row, "referrer"), { landingUrl: get(row, "landing_url"), utmSource: get(row, "utm_source") });
+      } catch {
+        throw new AiVisibilityError("trajectory_referral_invalid");
+      }
+      if (referral === null) {
+        totals.non_ai_sessions += sessions;
+        continue;
+      }
+      const entry = ensure(referral.operator);
+      entry.clicks += sessions;
+      entry.click_sources[referral.source] = (entry.click_sources[referral.source] || 0) + sessions;
+      if (referral.surface !== null) entry.click_surfaces[referral.surface] = (entry.click_surfaces[referral.surface] || 0) + sessions;
+      totals.ai_sessions += sessions;
+    }
+    for (const entry of Object.values(operators)) {
+      const reached = {
+        crawled: Object.values(entry.crawl).some(value => value > 0),
+        search_indexed: entry.crawl.search > 0,
+        user_fetched: entry.crawl.user > 0,
+        clicked: entry.clicks > 0,
+      };
+      for (const name of SIGNALS) {
+        reached[name] = Object.values(entry.engines).some(engine => engine[name].state === "measured" && engine[name].rate_bp > 0);
+      }
+      entry.stages = STAGES.filter(stage => reached[stage]);
+    }
+    const body = {
+      schema: AI_TRAJECTORY_SCHEMA,
+      host: owner,
+      catalog_version: CATALOG_VERSION,
+      operators,
+      totals,
+      reading_digest: readingDigest,
+      reading_valid: readingValid,
+      unattributed_engines: unattributed,
+      score_weights: { ...SCORE_WEIGHTS },
+      non_claims: [...TRAJECTORY_NON_CLAIMS],
+    };
+    return { ...body, digest: digest(body) };
+  }
+
+  return { auditAiReadiness, summarizeAiTrajectory };
+}
+
+module.exports = {
+  AI_VISIBILITY_CATALOG: CATALOG,
+  AI_REFERRAL_SCHEMA,
+  AI_CRAWLER_SCHEMA,
+  AI_READINESS_SCHEMA,
+  AI_TRAJECTORY_SCHEMA,
+  AiVisibilityError,
+  classifyAiReferral,
+  classifyAiCrawler,
+  createAiVisibilityApi,
+};

package/js/discovery-evidence.js

@@ -20,8 +20,9 @@ const BOTS = [
   ["GPTBot", "OpenAI"],
   ["OAI-SearchBot", "OpenAI"],
   ["ChatGPT-User", "OpenAI"],
-  ["ClaudeBot", "Anthropic"],
+  ["Claude-SearchBot", "Anthropic"],
   ["Claude-User", "Anthropic"],
+  ["ClaudeBot", "Anthropic"],
   ["PerplexityBot", "Perplexity"],
   ["Perplexity-User", "Perplexity"],
   ["Googlebot", "Google"],

package/js/discovery.d.ts

@@ -1,4 +1,25 @@
 export {
+  AI_CRAWLER_SCHEMA,
+  AI_READINESS_SCHEMA,
+  AI_REFERRAL_SCHEMA,
+  AI_TRAJECTORY_SCHEMA,
+  AI_VISIBILITY_CATALOG,
+  AiCrawler,
+  AiCrawlerPurpose,
+  AiReadinessCheck,
+  AiReadinessReport,
+  AiReferral,
+  AiReferralRow,
+  AiTrajectory,
+  AiTrajectoryOperator,
+  AiTrajectorySignal,
+  AiTrajectoryStage,
+  AiVisibilityCatalog,
+  AiVisibilityError,
+  auditAiReadiness,
+  classifyAiCrawler,
+  classifyAiReferral,
+  summarizeAiTrajectory,
   A2AAgentCardSignature,
   A2AInterface,
   A2AJwks,

package/js/discovery.js

@@ -17,6 +17,16 @@ module.exports = {
   normalizeEngineObservation: impl.engineObservationApi.normalizeEngineObservation,
   summarizeEngineObservations: impl.engineObservationApi.summarizeEngineObservations,
   summarizeCohortVisibility: impl.engineObservationApi.summarizeCohortVisibility,
+  AI_VISIBILITY_CATALOG: impl.aiVisibility.AI_VISIBILITY_CATALOG,
+  AI_REFERRAL_SCHEMA: impl.aiVisibility.AI_REFERRAL_SCHEMA,
+  AI_CRAWLER_SCHEMA: impl.aiVisibility.AI_CRAWLER_SCHEMA,
+  AI_READINESS_SCHEMA: impl.aiVisibility.AI_READINESS_SCHEMA,
+  AI_TRAJECTORY_SCHEMA: impl.aiVisibility.AI_TRAJECTORY_SCHEMA,
+  AiVisibilityError: impl.aiVisibility.AiVisibilityError,
+  classifyAiReferral: impl.aiVisibility.classifyAiReferral,
+  classifyAiCrawler: impl.aiVisibility.classifyAiCrawler,
+  auditAiReadiness: impl.aiVisibilityApi.auditAiReadiness,
+  summarizeAiTrajectory: impl.aiVisibilityApi.summarizeAiTrajectory,
   createSovereignCard: impl.createSovereignCard,
   createTwin3AgentCard: impl.createTwin3AgentCard,
   createAgentCard: impl.createAgentCard,

package/js/discovery.mjs

@@ -14,6 +14,16 @@ export const EngineObservationError = api.EngineObservationError;
 export const normalizeEngineObservation = api.normalizeEngineObservation;
 export const summarizeEngineObservations = api.summarizeEngineObservations;
 export const summarizeCohortVisibility = api.summarizeCohortVisibility;
+export const AI_VISIBILITY_CATALOG = api.AI_VISIBILITY_CATALOG;
+export const AI_REFERRAL_SCHEMA = api.AI_REFERRAL_SCHEMA;
+export const AI_CRAWLER_SCHEMA = api.AI_CRAWLER_SCHEMA;
+export const AI_READINESS_SCHEMA = api.AI_READINESS_SCHEMA;
+export const AI_TRAJECTORY_SCHEMA = api.AI_TRAJECTORY_SCHEMA;
+export const AiVisibilityError = api.AiVisibilityError;
+export const classifyAiReferral = api.classifyAiReferral;
+export const classifyAiCrawler = api.classifyAiCrawler;
+export const auditAiReadiness = api.auditAiReadiness;
+export const summarizeAiTrajectory = api.summarizeAiTrajectory;
 export const createSovereignCard = api.createSovereignCard;
 export const createTwin3AgentCard = api.createTwin3AgentCard;
 export const createAgentCard = api.createAgentCard;

package/js/index.js

@@ -45,6 +45,9 @@ module.exports = {
   normalizeEngineObservation: discovery.normalizeEngineObservation,
   summarizeEngineObservations: discovery.summarizeEngineObservations,
   summarizeCohortVisibility: discovery.summarizeCohortVisibility,
+  AI_VISIBILITY_CATALOG: discovery.AI_VISIBILITY_CATALOG, AiVisibilityError: discovery.AiVisibilityError,
+  AI_REFERRAL_SCHEMA: discovery.AI_REFERRAL_SCHEMA, AI_CRAWLER_SCHEMA: discovery.AI_CRAWLER_SCHEMA, AI_READINESS_SCHEMA: discovery.AI_READINESS_SCHEMA, AI_TRAJECTORY_SCHEMA: discovery.AI_TRAJECTORY_SCHEMA,
+  classifyAiReferral: discovery.classifyAiReferral, classifyAiCrawler: discovery.classifyAiCrawler, auditAiReadiness: discovery.auditAiReadiness, summarizeAiTrajectory: discovery.summarizeAiTrajectory,
   AuthorizationLeaseError: shield.AuthorizationLeaseError,
   verifyAuthorizationLease: shield.verifyAuthorizationLease,
   leaseClearanceContext: shield.leaseClearanceContext,

package/js/index.mjs

@@ -246,6 +246,16 @@ export const signEnvelopeWithSigner = api.signEnvelopeWithSigner;
 export const summarizeCohortVisibility = api.summarizeCohortVisibility;
 export const summarizeDiscoveryEvidence = api.summarizeDiscoveryEvidence;
 export const summarizeEngineObservations = api.summarizeEngineObservations;
+export const AI_VISIBILITY_CATALOG = api.AI_VISIBILITY_CATALOG;
+export const AI_REFERRAL_SCHEMA = api.AI_REFERRAL_SCHEMA;
+export const AI_CRAWLER_SCHEMA = api.AI_CRAWLER_SCHEMA;
+export const AI_READINESS_SCHEMA = api.AI_READINESS_SCHEMA;
+export const AI_TRAJECTORY_SCHEMA = api.AI_TRAJECTORY_SCHEMA;
+export const AiVisibilityError = api.AiVisibilityError;
+export const classifyAiReferral = api.classifyAiReferral;
+export const classifyAiCrawler = api.classifyAiCrawler;
+export const auditAiReadiness = api.auditAiReadiness;
+export const summarizeAiTrajectory = api.summarizeAiTrajectory;
 export const taskTrustLine = api.taskTrustLine;
 export const toolAuthorityMatches = api.toolAuthorityMatches;
 export const unresolvedPropositions = api.unresolvedPropositions;

package/js/internal/discovery.js

@@ -5,6 +5,7 @@ const trust = require("./trust.js");
 
 const discoveryEvidence = require("../discovery-evidence.js");
 const engineObservation = require("../engine-observation.js");
+const aiVisibility = require("../ai-visibility.js");
 const { validId } = require("../id-format.js");
 const SOVEREIGN_CARD_SCHEMA = "twin3-discovery-sovereign-card-v1";
 const CARD_CANONICALIZATION = "rfc8785";
@@ -1039,28 +1040,60 @@ function parseX402DnsTxt(records, host) {
         scheme: (tags.scheme || "").split(",").filter(Boolean),
     };
 }
-function x402AddressIsUnsafe(address) {
-    const text = String(address).trim();
-    if (require("node:net").isIP(text) === 0 || text.includes("%"))
-        core.fail("x402_fetch_address_invalid");
+function x402V4IsUnsafe(a, b, c) {
+    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 0 && c === 0) || (a === 192 && b === 0 && c === 2) || (a === 192 && b === 168)
+        || (a === 198 && (b === 18 || b === 19)) || (a === 198 && b === 51 && c === 100) || (a === 203 && b === 0 && c === 113)
+        || a >= 224;
+}
+function x402ParseV4(text) {
     const v4 = text.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
-    if (v4) {
-        const [a, b] = [Number(v4[1]), Number(v4[2])];
-        if ([a, b, Number(v4[3]), Number(v4[4])].some((n) => n > 255))
+    if (!v4)
+        return null;
+    const octets = v4.slice(1).map(Number);
+    if (octets.some((n) => n > 255))
+        core.fail("x402_fetch_address_invalid");
+    return octets;
+}
+function x402ParseV6(text) {
+    if (!/^[0-9a-f:.]+$/.test(text) || (text.match(/::/g) || []).length > 1)
+        core.fail("x402_fetch_address_invalid");
+    let groups = text.split(":");
+    const tail = groups[groups.length - 1];
+    if (tail.includes(".")) {
+        const octets = x402ParseV4(tail);
+        if (!octets)
             core.fail("x402_fetch_address_invalid");
-        return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31)
-            || (a === 192 && b === 0 && Number(v4[3]) === 0) || (a === 192 && b === 0 && Number(v4[3]) === 2) || (a === 192 && b === 168)
-            || (a === 198 && (b === 18 || b === 19)) || (a === 198 && b === 51 && Number(v4[3]) === 100) || (a === 203 && b === 0 && Number(v4[3]) === 113)
-            || a >= 224;
+        groups = [...groups.slice(0, -1), ((octets[0] << 8) | octets[1]).toString(16), ((octets[2] << 8) | octets[3]).toString(16)];
     }
-    if (text.includes(":")) {
-        const lower = new URL(`https://[${text}]/`).hostname.slice(1, -1);
-        const [first, second] = lower.split(":").map((part) => parseInt(part || "0", 16));
-        return first < 0x2000 || first > 0x3fff || first === 0x2002
-            || (first === 0x2001 && (second < 0x200 || second === 0xdb8))
-            || (first === 0x3fff && second < 0x1000);
+    const gap = groups.indexOf("");
+    if (text.includes("::")) {
+        const head = text.startsWith("::") ? [] : groups.slice(0, gap);
+        const rest = groups.slice(groups.lastIndexOf("") + 1);
+        if (head.length + rest.length > 7)
+            core.fail("x402_fetch_address_invalid");
+        groups = [...head, ...Array(8 - head.length - rest.length).fill("0"), ...rest];
     }
-    core.fail("x402_fetch_address_invalid");
+    if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group)))
+        core.fail("x402_fetch_address_invalid");
+    return groups.map((group) => parseInt(group, 16));
+}
+function x402AddressIsUnsafe(address) {
+    const text = String(address).trim().toLowerCase();
+    const v4 = x402ParseV4(text);
+    if (v4)
+        return x402V4IsUnsafe(v4[0], v4[1], v4[2]);
+    if (!text.includes(":"))
+        core.fail("x402_fetch_address_invalid");
+    const h = x402ParseV6(text);
+    if (h.slice(0, 6).every((n) => n === 0))
+        return true;
+    if (h.slice(0, 5).every((n) => n === 0) && h[5] === 0xffff)
+        return true;
+    if ((h[0] === 0x64 && h[1] === 0xff9b) || h[0] === 0x2002)
+        return true;
+    return h[0] < 0x2000 || h[0] > 0x3fff || (h[0] === 0x2001 && (h[1] < 0x0200 || h[1] === 0x0db8))
+        || (h[0] === 0x3fff && h[1] < 0x1000);
 }
 function checkX402FetchTarget(url, host, { resolvedAddresses = [], hop = 0, maxRedirects = X402_FETCH_BOUNDS.max_redirects } = {}) {
     const safeHost = x402Host(host);
@@ -1244,10 +1277,12 @@ function canStrangerDecide(declaration) {
 }
 const discoveryEvidenceApi = discoveryEvidence.createDiscoveryEvidenceApi(core.canonicalJsonBuffer);
 const engineObservationApi = engineObservation.createEngineObservationApi(core.canonicalJsonBuffer);
+const aiVisibilityApi = aiVisibility.createAiVisibilityApi(core.canonicalJsonBuffer);
 
 module.exports = {
   discoveryEvidence,
   engineObservation,
+  aiVisibility,
   validId,
   SOVEREIGN_CARD_SCHEMA,
   CARD_CANONICALIZATION,
@@ -1367,4 +1402,5 @@ module.exports = {
   canStrangerDecide,
   discoveryEvidenceApi,
   engineObservationApi,
+  aiVisibilityApi,
 };

package/js/runtime-session.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const contracts = require("./runtime.js");
+const { occurrenceContext, occurrenceId } = require("./shield.js");
 
 const copy = value => JSON.parse(JSON.stringify(value));
 const fail = code => { throw new contracts.RuntimeContractError(code); };
@@ -23,15 +24,17 @@ function taskSnapshot(state, replayed = false) {
   return copy({ task_id: state.task_id, run_id: state.run_id, request_id: state.request_id, revision: state.revision,
     execution_status: state.execution_status, approval_status: state.approval_status, effect_outcome: state.effect_outcome,
     reply: state.reply, error: state.error, operation_id: state.operation_id, result: state.result,
-    preview: state.preview, available_actions: availableActions, events: state.events, cursor: state.revision, replayed });
+    preview: state.preview, available_actions: availableActions, events: state.events, cursor: state.revision, replayed,
+    ...(state.reconciliation ? { reconciliation: state.reconciliation } : {}) });
 }
 
 class AgentRuntime {
-  constructor({ store, resolvePrincipal, resolveContext, engine, resolveSkill, resolveExecution, evaluateAction = async () => "ask", clock = () => Math.floor(Date.now() / 1000), timeoutMs = 30000 }) {
+  constructor({ store, resolvePrincipal, resolveContext, engine, resolveSkill, resolveExecution, resolveOutcome = null, evaluateAction = async () => "ask", clock = () => Math.floor(Date.now() / 1000), timeoutMs = 30000 }) {
     if (!store || typeof store.get !== "function" || typeof store.transact !== "function"
         || ![resolvePrincipal, resolveContext, engine, resolveSkill, resolveExecution, evaluateAction, clock].every(value => typeof value === "function")) fail("runtime_ports_required");
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300000) fail("runtime_timeout_invalid");
-    Object.assign(this, { store, resolvePrincipal, resolveContext, engine, resolveSkill, resolveExecution, evaluateAction, clock, timeoutMs });
+    if (resolveOutcome !== null && typeof resolveOutcome !== "function") fail("runtime_ports_required");
+    Object.assign(this, { store, resolvePrincipal, resolveContext, engine, resolveSkill, resolveExecution, resolveOutcome, evaluateAction, clock, timeoutMs });
     this.controllers = new Map();
   }
 
@@ -253,6 +256,75 @@ class AgentRuntime {
     });
   }
 
+  async reconcile(caller, { task_id: taskId, expected_revision: expectedRevision, request_id: requestId }) {
+    boundedText(requestId, 128);
+    if (!Number.isSafeInteger(expectedRevision)) fail("runtime_request_invalid");
+    if (!this.resolveOutcome) fail("runtime_reconciliation_unavailable");
+    const principal = await this.principal(caller), key = this.key(principal, taskId);
+    const command = contracts.runtimeDigest({ operation: "reconcile", task_id: taskId, expected_revision: expectedRevision, request_id: requestId });
+    const state = await this.store.get(key);
+    if (!state) fail("runtime_task_not_found");
+    if (Object.hasOwn(state.commands, requestId)) {
+      if (state.commands[requestId] !== command) fail("runtime_request_conflict");
+      if (contracts.runtimeDigest(await this.principal(caller)) !== contracts.runtimeDigest(principal)) fail("runtime_authority_changed");
+      return taskSnapshot(state, true);
+    }
+    if (state.revision !== expectedRevision) fail("runtime_revision_conflict");
+    if (state.execution_status !== "outcome_unknown" || state.effect_outcome !== "unknown" || !state.preview || !state.context) fail("runtime_reconciliation_not_available");
+    const preview = contracts.createExecutionPreview({ principal: state.principal, context: state.context, actions: state.preview.actions,
+      task_id: taskId, request_id: state.preview.request_id, revision: state.preview.revision, expires_at: state.preview.expires_at });
+    if (contracts.runtimeDigest(preview) !== contracts.runtimeDigest(state.preview) || preview.actions.length !== 1) fail("runtime_preview_changed");
+    const original = state.principal;
+    if (["kind", "tenant", "subject", "owner", "claim_generation"].some(field => original[field] !== principal[field])) fail("runtime_authority_changed");
+    const operationId = occurrenceId(occurrenceContext({ tenant: original.tenant, taskId, plan: preview.actions, index: 0, epoch: original.epoch }));
+    if (state.operation_id && state.operation_id !== operationId) fail("runtime_operation_changed");
+    const identity = { operation_id: operationId, action_digest: contracts.runtimeDigest(preview.actions[0]),
+      context_digest: contracts.runtimeDigest(state.context), principal_digest: contracts.runtimeDigest(original) };
+    const controller = new AbortController();
+    let timer;
+    const returned = await Promise.race([
+      Promise.resolve().then(() => this.resolveOutcome(caller, copy(identity), controller.signal)),
+      new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new contracts.RuntimeContractError("runtime_reconciliation_timeout")); }, this.timeoutMs); })
+    ]).finally(() => clearTimeout(timer));
+    contracts.runtimeDigest(returned);
+    const outcome = copy(returned);
+    if (!outcome || !["confirmed", "not_submitted", "unknown"].includes(outcome.effect_outcome)
+        || Object.keys(outcome).some(field => ![...Object.keys(identity), "effect_outcome", "evidence_ref", "result"].includes(field))
+        || Object.entries(identity).some(([field, value]) => outcome[field] !== value)) fail("runtime_reconciliation_invalid");
+    if (contracts.runtimeDigest(await this.principal(caller)) !== contracts.runtimeDigest(principal)) fail("runtime_authority_changed");
+    if (outcome.effect_outcome === "unknown") {
+      const latest = await this.store.get(key);
+      if (contracts.runtimeDigest(await this.principal(caller)) !== contracts.runtimeDigest(principal)) fail("runtime_authority_changed");
+      return taskSnapshot(latest);
+    }
+    const evidence = boundedText(outcome.evidence_ref, 512);
+    if (/[\u0000-\u001f\u007f]/u.test(evidence) || outcome.effect_outcome === "confirmed" && !Object.hasOwn(outcome, "result")) fail("runtime_reconciliation_invalid");
+    const result = outcome.effect_outcome === "confirmed" ? outcome.result : null;
+    contracts.runtimeDigest(result);
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") > 65536) fail("runtime_payload_too_large");
+    return this.store.transact(key, async current => {
+      if (!current) fail("runtime_task_not_found");
+      if (Object.hasOwn(current.commands, requestId)) {
+        if (current.commands[requestId] !== command) fail("runtime_request_conflict");
+        return { state: current, value: taskSnapshot(current, true) };
+      }
+      if (current.revision !== expectedRevision || current.execution_status !== "outcome_unknown"
+          || contracts.runtimeDigest(current.preview) !== contracts.runtimeDigest(preview)
+          || contracts.runtimeDigest(current.context) !== identity.context_digest
+          || contracts.runtimeDigest(current.principal) !== identity.principal_digest) fail("runtime_revision_conflict");
+      if (contracts.runtimeDigest(await this.principal(caller)) !== contracts.runtimeDigest(principal)) fail("runtime_authority_changed");
+      current.commands = { ...current.commands, [requestId]: command };
+      current.operation_id = operationId;
+      current.effect_outcome = outcome.effect_outcome;
+      current.execution_status = outcome.effect_outcome === "confirmed" ? "completed" : "blocked";
+      current.result = result;
+      current.error = outcome.effect_outcome === "confirmed" ? null : "runtime_action_not_submitted";
+      current.reconciliation = { evidence_ref: evidence, ...identity };
+      appendEvent(current, "reconciled", this.clock());
+      return { state: current, value: taskSnapshot(current) };
+    });
+  }
+
   async cancel(caller, { task_id: taskId, expected_revision: expectedRevision, request_id: requestId }) {
     boundedText(requestId, 128);
     const principal = await this.principal(caller);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.20-pre-alpha",
+  "version": "0.3.0",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",
@@ -83,9 +83,11 @@
     "js/index.js",
     "js/discovery-evidence.js",
     "js/engine-observation.js",
+    "js/ai-visibility.js",
     "js/id-format.js",
     "twin3/discovery/id-format.v1.json",
     "twin3/discovery/evidence-i18n.json",
+    "twin3/discovery/ai-visibility-catalog.json",
     "js/comm/counterparty.js",
     "js/comm/completion.js",
     "twin3/comm/task-completion-command.schema.json",
@@ -138,7 +140,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "next"
+    "tag": "latest"
   },
   "scripts": {
     "test": "node --test tests/*.test.js"

package/runtime.d.ts

@@ -115,7 +115,19 @@ export interface RuntimeTaskSnapshot {
   events: { event_id: string; task_id: string; run_id: string; cursor: number; type: string; at: number }[];
   cursor: number;
   replayed: boolean;
+  reconciliation?: RuntimeReconciliationIdentity & { evidence_ref: string };
 }
+export interface RuntimeReconciliationIdentity {
+  operation_id: string;
+  action_digest: string;
+  context_digest: string;
+  principal_digest: string;
+}
+export type RuntimeReconciliationOutcome = RuntimeReconciliationIdentity & (
+  | { effect_outcome: "unknown" }
+  | { effect_outcome: "not_submitted"; evidence_ref: string }
+  | { effect_outcome: "confirmed"; evidence_ref: string; result: JsonValue }
+);
 export interface RuntimeTaskStore {
   get(key: string): Promise<unknown>;
   transact<T>(key: string, update: (state: unknown) => Promise<{ state: unknown; value: T }> | { state: unknown; value: T }): Promise<T>;
@@ -129,6 +141,7 @@ export declare class AgentRuntime<Caller = unknown> {
     engine(input: { intent: string; context: ContextEnvelope; principal: PrincipalContext; request_id: string; signal: AbortSignal }): Promise<{ reply: string; actions: unknown[] }>;
     resolveSkill(caller: Caller, skillId: string): Promise<{ ready: boolean; manifest: SkillManifest } | null>;
     resolveExecution(caller: Caller, state: unknown): Promise<{ gate: RuntimeGate; broker: RuntimeBroker } | null>;
+    resolveOutcome?(caller: Caller, identity: RuntimeReconciliationIdentity, signal: AbortSignal): Promise<RuntimeReconciliationOutcome>;
     evaluateAction?(caller: Caller, action: SkillAction, context: ContextEnvelope): Promise<"allow" | "ask" | "deny">;
     clock?: () => number;
     timeoutMs?: number;
@@ -137,5 +150,6 @@ export declare class AgentRuntime<Caller = unknown> {
   get(caller: Caller, taskId: string): Promise<RuntimeTaskSnapshot>;
   decide(caller: Caller, input: { task_id: string; preview_id: string; expected_revision: number; decision: "approve" | "deny"; request_id: string }): Promise<RuntimeTaskSnapshot>;
   execute(caller: Caller, input: { task_id: string; expected_revision: number; request_id: string }): Promise<RuntimeTaskSnapshot>;
+  reconcile(caller: Caller, input: { task_id: string; expected_revision: number; request_id: string }): Promise<RuntimeTaskSnapshot>;
   cancel(caller: Caller, input: { task_id: string; expected_revision: number; request_id: string }): Promise<RuntimeTaskSnapshot>;
 }

package/twin3/discovery/ai-visibility-catalog.json

@@ -0,0 +1,68 @@
+{
+  "version": 1,
+  "checked_on": "2026-10-27",
+  "provenance": [
+    {
+      "name": "ansvisor",
+      "url": "https://github.com/ansvisor/ansvisor",
+      "license": "MIT",
+      "used": ["server/src/lib/ai-sources.json v3", "server/src/lib/ai-bots.json v1", "server/src/config/visibility-score.js weights"]
+    },
+    {
+      "name": "claude-seo",
+      "url": "https://github.com/AgriciDaniel/claude-seo/tree/6be93f45064ffbadced572b5d5c95f55fd263af0",
+      "license": "MIT",
+      "used": ["scripts/agentic_check.py AI_AGENTS and RFC 9309 group selection", "skills/seo-geo crawler claim table"]
+    },
+    {
+      "name": "GEOFlow",
+      "url": "https://github.com/yaojingang/GEOFlow",
+      "license": "AGPL-3.0",
+      "used": ["publish quality-gate concept only; no code or data copied"]
+    }
+  ],
+  "referral_sources": [
+    { "key": "chatgpt.com", "operator": "OpenAI", "hosts": ["chatgpt.com", "chat.openai.com"], "aliases": ["chatgpt", "openai", "openai.com"], "surfaces": [{ "key": "shopping", "medium": "feed" }] },
+    { "key": "perplexity.ai", "operator": "Perplexity", "hosts": ["perplexity.ai"], "aliases": ["perplexity"] },
+    { "key": "claude.ai", "operator": "Anthropic", "hosts": ["claude.ai"], "aliases": ["claude"] },
+    { "key": "gemini.google.com", "operator": "Google", "hosts": ["gemini.google.com", "bard.google.com"], "aliases": ["gemini", "bard"] },
+    { "key": "copilot.microsoft.com", "operator": "Microsoft", "hosts": ["copilot.microsoft.com", "copilot.com"], "aliases": ["copilot"] },
+    { "key": "grok.com", "operator": "xAI", "hosts": ["grok.com"], "aliases": ["grok"] },
+    { "key": "deepseek.com", "operator": "DeepSeek", "hosts": ["deepseek.com"], "aliases": ["deepseek"] },
+    { "key": "meta.ai", "operator": "Meta", "hosts": ["meta.ai"], "aliases": [] },
+    { "key": "you.com", "operator": "You.com", "hosts": ["you.com"], "aliases": [] },
+    { "key": "phind.com", "operator": "Phind", "hosts": ["phind.com"], "aliases": [] },
+    { "key": "poe.com", "operator": "Quora", "hosts": ["poe.com"], "aliases": [] },
+    { "key": "labs.google", "operator": "Google", "hosts": ["labs.google"], "aliases": [] },
+    { "key": "bing.com", "operator": "Microsoft", "hosts": ["bing.com"], "aliases": [], "referrer_path": "/ck/a", "utm": false }
+  ],
+  "crawlers": [
+    { "token": "GPTBot", "operator": "OpenAI", "purpose": "training", "robots": "honours", "user_agent": true },
+    { "token": "OAI-SearchBot", "operator": "OpenAI", "purpose": "search", "robots": "honours", "user_agent": true, "claim": "citable_in_chatgpt_search" },
+    { "token": "ChatGPT-User", "operator": "OpenAI", "purpose": "user", "robots": "may_not_apply", "user_agent": true },
+    { "token": "ClaudeBot", "operator": "Anthropic", "purpose": "training", "robots": "honours", "user_agent": true },
+    { "token": "Claude-SearchBot", "operator": "Anthropic", "purpose": "search", "robots": "honours", "user_agent": true, "claim": "citable_in_claude_search" },
+    { "token": "Claude-User", "operator": "Anthropic", "purpose": "user", "robots": "honours", "user_agent": true },
+    { "token": "PerplexityBot", "operator": "Perplexity", "purpose": "search", "robots": "honours", "user_agent": true, "claim": "citable_in_perplexity" },
+    { "token": "Perplexity-User", "operator": "Perplexity", "purpose": "user", "robots": "generally_ignores", "user_agent": true },
+    { "token": "Googlebot", "operator": "Google", "purpose": "search", "robots": "honours", "user_agent": true, "claim": "eligible_for_google_ai_overviews" },
+    { "token": "Google-Extended", "operator": "Google", "purpose": "control", "robots": "honours", "user_agent": false },
+    { "token": "Google-Agent", "operator": "Google", "purpose": "user", "robots": "generally_ignores", "user_agent": true },
+    { "token": "Google-CloudVertexBot", "operator": "Google", "purpose": "user", "robots": "honours", "user_agent": true },
+    { "token": "Bingbot", "operator": "Microsoft", "purpose": "search", "robots": "honours", "user_agent": true, "claim": "eligible_for_copilot_and_bing" },
+    { "token": "Applebot", "operator": "Apple", "purpose": "search", "robots": "honours", "user_agent": true },
+    { "token": "Applebot-Extended", "operator": "Apple", "purpose": "control", "robots": "honours", "user_agent": false },
+    { "token": "CCBot", "operator": "Common Crawl", "purpose": "training", "robots": "honours", "user_agent": true },
+    { "token": "A2A-Client", "operator": "A2A", "purpose": "agent", "robots": "not_applicable", "user_agent": true },
+    { "token": "WebMCP-Client", "operator": "WebMCP", "purpose": "agent", "robots": "not_applicable", "user_agent": true }
+  ],
+  "stages": [
+    { "key": "crawled", "en": "Fetched by an AI crawler", "zh-TW": "被 AI 爬蟲抓取" },
+    { "key": "search_indexed", "en": "Fetched by an AI search crawler", "zh-TW": "被 AI 搜尋爬蟲收錄" },
+    { "key": "user_fetched", "en": "Fetched for a person's question", "zh-TW": "因使用者提問被即時讀取" },
+    { "key": "retrieved", "en": "Retrieved in an AI answer run", "zh-TW": "在 AI 回答中被檢索" },
+    { "key": "mentioned", "en": "Mentioned in an AI answer", "zh-TW": "在 AI 回答中被提及" },
+    { "key": "cited", "en": "Cited as a source", "zh-TW": "被列為引用來源" },
+    { "key": "clicked", "en": "Visited from an AI answer", "zh-TW": "從 AI 回答點擊進站" }
+  ]
+}