twin3-sdk 0.2.15-pre-alpha → 0.2.17-pre-alpha

package/README.md

@@ -116,22 +116,22 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-`v0.2.15-pre-alpha` is the current release candidate: `0.2.15-pre-alpha` for npm and `0.2.15a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
+`v0.2.17-pre-alpha` is the current release candidate: `0.2.17-pre-alpha` for npm and `0.2.17a0` for PyPI. It is published from main through the Cloud Build tag trigger; the previous version number was never published. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
 
-`package.json` `engines` sets Node.js to `>=18` and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.
+`package.json` `engines` requires Node.js `>=22.23.4` and does not set an npm engine. CI covers patched Node 22, 24 and 26; Node 18 and 20 are outside the supported baseline. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.
 
 After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.15-pre-alpha
-pip install twin3-sdk==0.2.15a0
+npm install twin3-sdk@0.2.17-pre-alpha
+pip install twin3-sdk==0.2.17a0
 ```
 
 For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.15-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.17-pre-alpha.tgz
 ```
 
 ---

package/index.d.ts

@@ -158,6 +158,71 @@ export interface DiscoveryEvidenceView {
   digest: string;
 }
 export declare function buildDiscoveryEvidenceView(summary: DiscoveryEvidenceSummary, options: { visitSourceStatus: "connected" | "not_connected"; googleAiSearchSourceStatus: "connected" | "not_connected" }): DiscoveryEvidenceView;
+export declare const ENGINE_OBSERVATION_SCHEMA: "twin3-discovery-engine-observation-v1";
+export declare const ENGINE_READING_SCHEMA: "twin3-discovery-engine-reading-v1";
+export declare class EngineObservationError extends Error { code: string; }
+export type EngineObservationEvidenceLevel = "server_observed_engine_answer" | "replay_api" | "owner_supplied_platform_export";
+export interface EngineObservationInput {
+  engine: string;
+  prompt_id: string;
+  observed_at: number;
+  status: "answered" | "error";
+  model?: string | null;
+  need_id?: string | null;
+  paraphrase_of?: string | null;
+  run_id?: string | null;
+  host?: string | null;
+  retrieved?: boolean | null;
+  mentioned?: boolean | null;
+  cited?: boolean | null;
+  evidence_level?: EngineObservationEvidenceLevel;
+  evidence_strength?: EngineObservationEvidenceLevel;
+  answer?: string | null;
+  answer_digest?: string | null;
+  [extra: string]: unknown;
+}
+export interface EngineObservation {
+  schema: "twin3-discovery-engine-observation-v1";
+  host: string;
+  engine: string;
+  model: string | null;
+  prompt_id: string;
+  need_id: string | null;
+  run_id: string | null;
+  observed_at: number;
+  status: "answered" | "error";
+  retrieved: boolean | null;
+  mentioned: boolean | null;
+  cited: boolean | null;
+  evidence_level: EngineObservationEvidenceLevel;
+  answer_digest: string | null;
+  digest: string;
+}
+export interface EngineObservationSignalReading {
+  state: "measured" | "withheld" | "unknown";
+  observed: number;
+  positive: number;
+  rate_bp: number | null;
+  interval_bp: [number, number] | null;
+}
+export interface EngineObservationReading {
+  schema: "twin3-discovery-engine-reading-v1";
+  host: string;
+  valid: boolean;
+  source_level: boolean;
+  blockers: Array<"no_answered_observations" | "insufficient_repetitions" | "insufficient_paraphrases">;
+  caveats: Array<"window_shorter_than_21_days">;
+  window_utc: { first: string; last: string; span_days: number; observed_days: number } | null;
+  engines: string[];
+  by_engine: Record<string, { answered: number; errors: number; prompts: number; signals: Record<"retrieved" | "mentioned" | "cited", EngineObservationSignalReading> }>;
+  evidence_levels: EngineObservationEvidenceLevel[];
+  protocol: { min_runs_per_prompt: number; min_runs_for_source_coverage: number; min_paraphrases_per_need: number; window_days: number; interval: string; source: string };
+  non_claims: string[];
+  observation_digests: string[];
+  digest: string;
+}
+export declare function normalizeEngineObservation(row: EngineObservationInput, options: { host: string }): EngineObservation;
+export declare function summarizeEngineObservations(observations: EngineObservation[], options: { host: string; sourceLevel?: boolean }): EngineObservationReading;
 
 export declare const DESCRIPTOR_CANONICALIZATION: "rfc8785";
 export declare const DESCRIPTOR_SIGNATURE_FIELDS: readonly ["signatures", "signatureStatus"];
@@ -853,6 +918,15 @@ export declare function didWebForHost(host: string): string;
 export declare function didWebUrl(did: string): string;
 export declare function resolveDidWeb(did: string, fetch: (method: string, url: string, headers: Record<string, string>, body: null) => [number, string | Uint8Array | null], maxBytes?: number): { did: string; url: string; method_id: string; key_id: string; public_key: string; };
 export declare function multibaseEd25519(raw: Uint8Array, multicodec?: boolean): string;
+export type DidFetch = (method: string, url: string, headers: Record<string, string>, body: null) => [number, string | Uint8Array | null];
+export type DidKeyPurpose = "assertionMethod" | "authentication" | "keyAgreement" | "capabilityInvocation" | "capabilityDelegation";
+export interface DidDocumentKey { did: string; method_id: string; key_id: string; public_key: string; purpose: DidKeyPurpose | null; }
+/** Ed25519 verification methods of a did:web document, restricted to the requested verification relationship (default `assertionMethod`). */
+export declare function didWebDocumentKeys(doc: Record<string, unknown>, did: string, options?: { purpose?: DidKeyPurpose | null }): DidDocumentKey[];
+/** Resolve one did:web key through the injected fetch; `kid` must select exactly one method (`did_kid_not_found` / `did_kid_ambiguous`). */
+export declare function resolveDidWebKey(did: string, fetch: DidFetch, options?: { kid?: string | null; purpose?: DidKeyPurpose | null; maxBytes?: number }): DidDocumentKey & { url: string };
+/** Select one Ed25519 (`OKP`/`Ed25519`, `alg` EdDSA if present) key from a JWKS by `kid`. */
+export declare function jwksKey(jwks: Record<string, unknown>, kid: string): { kid: string; key_id: string; public_key: string };
 export declare const AuthorityAnchor: { readonly SUPPORTED_KINDS: readonly string[]; isValidKind(kind: string): boolean; };
 export declare function createKyaChallenge(params: {
   owner: string;
@@ -906,6 +980,9 @@ export interface TrustDelegation {
 export interface AuthorizationLease {
   bindings: KyaBinding[];
   delegations: TrustDelegation[];
+  /** Optional copy of the consumer registration the bindings were issued under; it is compared
+   *  against `LeaseAuthority.consumer_registration` and is never authority on its own. */
+  registration?: ConsumerRegistrationStatement | null;
 }
 export interface BindingWindow { not_before: number; not_after: number; epoch: number; }
 export interface LeaseAuthority {
@@ -916,6 +993,10 @@ export interface LeaseAuthority {
   policy_revision: string;
   binding_windows: Record<string, BindingWindow>;
   reanchored_at: number;
+  /** A `twin3-trust-consumer-registration-v1` statement signed by `owner_public_key` (the vertical's
+   *  root R). When present, a binding whose challenge was signed by the statement's `kya_owner` key
+   *  verifies; bindings signed by R itself verify unchanged. `null` means no registration. */
+  consumer_registration?: ConsumerRegistrationStatement | null;
 }
 export interface LeaseAuthorityPort {
   currentAuthority(tenant: string, owner: string): LeaseAuthority | Promise<LeaseAuthority>;
@@ -935,6 +1016,8 @@ export interface VerifiedLeaseRequest {
   policy_revision: string;
   binding_receipts: string[];
   delegation_receipts: string[];
+  /** Receipt of the verified consumer registration, or `null` when the authority carries none. */
+  registration_receipt: string | null;
 }
 export declare class AuthorizationLeaseError extends ProtocolError {
   constructor(code: string);
@@ -964,6 +1047,8 @@ export interface LeaseClearanceContext {
     actor_key_id: string; purpose: string; occurrence_index: number;
     binding_receipts: string[]; delegation_receipts: string[];
     binding_windows: Array<BindingWindow | null>; usage: Record<string, number>;
+    /** Present only when the authority carries a consumer registration. */
+    registration_receipt?: string;
   };
 }
 export type DetectorState = "allow" | "flag" | "block" | "unavailable" | "not_configured";
@@ -1790,3 +1875,78 @@ export declare function signDelegationWithSigner(delegation: Record<string, unkn
   options?: ExternalSignerOptions): Promise<Readonly<Record<string, unknown>>>;
 export declare function signEnvelopeWithSigner(envelope: Envelope, signer: ExternalEd25519Signer,
   options?: ExternalSignerOptions): Promise<Readonly<Envelope>>;
+
+export declare const CONSUMER_REGISTRATION_SCHEMA: "twin3-trust-consumer-registration-v1";
+export type ConsumerRegistrationEnvironment = "sandbox" | "staging" | "production";
+export type ConsumerRegistrationKeyRole = "kya_owner" | "evidence";
+export interface ConsumerRegistrationKey {
+  role: ConsumerRegistrationKeyRole;
+  key_id: string;
+  public_key: string;
+  label?: string;
+}
+export interface ConsumerRegistrationSubject {
+  consumer_id: string;
+  namespace: string;
+  environment: ConsumerRegistrationEnvironment;
+  identity_kinds: Array<"lei" | "duns" | "human_id">;
+  epoch: number;
+  policy_revision: string;
+  endpoints?: Record<string, string>;
+  sdk_contract_digest?: string;
+}
+/** `twin3-trust-consumer-registration-v1`: the vertical's root R signs which consumer keys it authorizes.
+ *  Exactly one `kya_owner` key; `issuer.key_id` and the JWS `kid` are descriptive and are compared against
+ *  the injected root, never fetched. */
+export interface ConsumerRegistrationStatement {
+  schema: "twin3-trust-consumer-registration-v1";
+  issuer: { key_id: string; did?: string };
+  subject: ConsumerRegistrationSubject;
+  authorized_keys: ConsumerRegistrationKey[];
+  not_before: number;
+  not_after: number;
+  signatures?: DescriptorSignature[];
+  signatureStatus?: string;
+}
+export interface ConsumerRegistrationExpectation {
+  consumer_id?: string;
+  namespace?: string;
+  environment?: ConsumerRegistrationEnvironment;
+  epoch?: number;
+  policy_revision?: string;
+  identity_kind?: "lei" | "duns" | "human_id";
+}
+export interface VerifiedConsumerRegistration {
+  receipt: string;
+  issuer_key_id: string;
+  subject: ConsumerRegistrationSubject;
+  kya_owner_key: ConsumerRegistrationKey;
+  evidence_keys: ConsumerRegistrationKey[];
+  not_before: number;
+  not_after: number;
+  kid: string;
+  jku: string | null;
+}
+export type ConsumerRegistrationErrorCode = "registration_schema_mismatch" | "registration_unknown_field"
+  | "registration_field_required" | "registration_signature_invalid" | "registration_root_required"
+  | "registration_root_mismatch" | "registration_kid_mismatch" | "registration_time_invalid"
+  | "registration_not_yet_valid" | "registration_expired" | "registration_subject_mismatch"
+  | "registration_key_unauthorized" | "registration_key_role_invalid" | "registration_required"
+  | "registration_mismatch";
+export declare class ConsumerRegistrationError extends ProtocolError {
+  readonly code: ConsumerRegistrationErrorCode;
+  constructor(code: ConsumerRegistrationErrorCode);
+}
+/** Shape rules only (no signature); returns the canonical body. With `now`, also checks the validity window. */
+export declare function validateConsumerRegistration(statement: ConsumerRegistrationStatement, options?: { now?: number | null }): Omit<ConsumerRegistrationStatement, "signatures" | "signatureStatus">;
+/** SHA-256 hex of the RFC 8785 body without signature fields; the revocation reference for the statement. */
+export declare function registrationReceipt(statement: ConsumerRegistrationStatement): string;
+export declare function signConsumerRegistration(statement: ConsumerRegistrationStatement, privateKey: string | Buffer | import("node:crypto").KeyObject,
+  options?: { kid?: string; jku?: string | null }): ConsumerRegistrationStatement & SignedDescriptor;
+export declare function signConsumerRegistrationWithSigner(statement: ConsumerRegistrationStatement, signer: ExternalEd25519Signer,
+  options?: { kid?: string; jku?: string | null; timeoutMs?: number; signal?: AbortSignal }): Promise<ConsumerRegistrationStatement & SignedDescriptor>;
+/** Verify shape, root signature (`rootPublicKey` is injected, never fetched), optional `kid`, window at `now` and the expected subject. No network. */
+export declare function verifyConsumerRegistration(statement: ConsumerRegistrationStatement, options: {
+  rootPublicKey: string | Buffer | import("node:crypto").KeyObject; expectedKid?: string | null; now: number;
+  expected?: ConsumerRegistrationExpectation | null;
+}): VerifiedConsumerRegistration;

package/js/comm/counterparty.js

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

package/js/discovery.d.ts

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

package/js/discovery.js

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

package/js/discovery.mjs

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

package/js/engine-observation.js

@@ -0,0 +1,261 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+const ENGINE_OBSERVATION_SCHEMA = "twin3-discovery-engine-observation-v1";
+const ENGINE_READING_SCHEMA = "twin3-discovery-engine-reading-v1";
+const MIN_RUNS_PER_PROMPT = 7;
+const MIN_RUNS_FOR_SOURCE_COVERAGE = 8;
+const MIN_PARAPHRASES_PER_NEED = 3;
+const PROTOCOL_WINDOW_DAYS = 21;
+const SIGNALS = ["retrieved", "mentioned", "cited"];
+const EVIDENCE_LEVELS = ["server_observed_engine_answer", "replay_api", "owner_supplied_platform_export"];
+const NON_CLAIMS = [
+  "observation_is_not_trust_or_authorization",
+  "rates_do_not_pool_across_engines",
+  "does_not_generalise_to_engines_that_were_not_queried",
+  "mention_rate_is_not_traffic_clicks_or_revenue",
+  "does_not_prove_a_buyer_saw_this_answer",
+];
+const PROTOCOL = {
+  min_runs_per_prompt: MIN_RUNS_PER_PROMPT,
+  min_runs_for_source_coverage: MIN_RUNS_FOR_SOURCE_COVERAGE,
+  min_paraphrases_per_need: MIN_PARAPHRASES_PER_NEED,
+  window_days: PROTOCOL_WINDOW_DAYS,
+  interval: "wilson_95_basis_points_floor_ceil",
+  source: "arXiv:2604.07585",
+};
+const IDENTIFIER = /^[A-Za-z0-9._:-]{1,160}$/;
+const ENGINE = /^[A-Za-z0-9._:/-](?:[A-Za-z0-9 ._:/-]{0,78}[A-Za-z0-9._:/-])?$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const OBSERVATION_FIELDS = [
+  "schema", "host", "engine", "model", "prompt_id", "need_id", "run_id", "observed_at", "status",
+  "retrieved", "mentioned", "cited", "evidence_level", "answer_digest", "digest",
+];
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+class EngineObservationError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "EngineObservationError";
+    this.code = code;
+  }
+}
+
+function requireValue(condition, code) {
+  if (!condition) throw new EngineObservationError(code);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+function field(row, key) {
+  return Object.hasOwn(row, key) && row[key] !== undefined ? row[key] : null;
+}
+
+function hostValue(value) {
+  requireValue(typeof value === "string" && !/[^\x00-\x7f]/.test(value), "observation_host_invalid");
+  const host = value.replace(/^[ \t\r\n\v\f]+|[ \t\r\n\v\f]+$/g, "").toLowerCase().replace(/\.$/, "");
+  requireValue(/^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/.test(host) && !host.includes(".."), "observation_host_invalid");
+  return host;
+}
+
+function identifier(value, pattern, code) {
+  requireValue(typeof value === "string" && pattern.test(value), code);
+  return value;
+}
+
+function optionalIdentifier(value, code) {
+  return value === null ? null : identifier(value, IDENTIFIER, code);
+}
+
+function modelValue(value) {
+  if (value === null) return null;
+  requireValue(typeof value === "string" && value.length > 0 && value.length <= 120 && !/[^\x20-\x7e]/.test(value), "observation_model_invalid");
+  return value;
+}
+
+function timestamp(value) {
+  requireValue(typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 253402300799, "observation_time_invalid");
+  return value;
+}
+
+function signal(value) {
+  requireValue(value === null || typeof value === "boolean", "observation_signal_invalid");
+  return value;
+}
+
+function aliased(row, primary, alias, code) {
+  const values = [primary, alias].map(key => field(row, key)).filter(value => value !== null);
+  requireValue(values.length < 2 || values[0] === values[1], code);
+  return values.length ? values[0] : null;
+}
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function observationFields(row, ownerHost) {
+  const status = field(row, "status");
+  requireValue(status === "answered" || status === "error", "observation_status_invalid");
+  const signals = Object.fromEntries(SIGNALS.map(name => [name, signal(field(row, name))]));
+  requireValue(status === "answered" || SIGNALS.every(name => signals[name] === null), "observation_error_has_signals");
+  const evidenceLevel = aliased(row, "evidence_level", "evidence_strength", "observation_evidence_level_invalid");
+  requireValue(EVIDENCE_LEVELS.includes(evidenceLevel), "observation_evidence_level_invalid");
+  if (field(row, "host") !== null) requireValue(hostValue(row.host) === ownerHost, "observation_host_mismatch");
+  return {
+    schema: ENGINE_OBSERVATION_SCHEMA,
+    host: ownerHost,
+    engine: identifier(field(row, "engine"), ENGINE, "observation_engine_invalid"),
+    model: modelValue(field(row, "model")),
+    prompt_id: identifier(field(row, "prompt_id"), IDENTIFIER, "observation_prompt_id_required"),
+    need_id: optionalIdentifier(aliased(row, "need_id", "paraphrase_of", "observation_need_id_invalid"), "observation_need_id_invalid"),
+    run_id: optionalIdentifier(field(row, "run_id"), "observation_run_id_invalid"),
+    observed_at: timestamp(field(row, "observed_at")),
+    status,
+    ...signals,
+    evidence_level: evidenceLevel,
+  };
+}
+
+function answerDigest(row) {
+  const supplied = field(row, "answer_digest");
+  requireValue(supplied === null || typeof supplied === "string" && SHA256.test(supplied), "observation_answer_digest_invalid");
+  const answer = field(row, "answer");
+  if (answer === null) return supplied;
+  requireValue(typeof answer === "string" && !/[\ud800-\udfff]/u.test(answer), "observation_answer_invalid");
+  const computed = sha256(answer);
+  requireValue(supplied === null || supplied === computed, "observation_answer_digest_invalid");
+  return computed;
+}
+
+function wilsonBasisPoints(positive, trials) {
+  const z = 1.96;
+  const phat = positive / trials;
+  const denominator = 1 + z * z / trials;
+  const centre = phat + z * z / (2 * trials);
+  const margin = z * Math.sqrt(phat * (1 - phat) / trials + z * z / (4 * trials * trials));
+  const low = Math.max(0, (centre - margin) / denominator);
+  const high = Math.min(1, (centre + margin) / denominator);
+  return [Math.max(0, Math.floor(low * 10000)), Math.min(10000, Math.ceil(high * 10000))];
+}
+
+function signalReading(rows, name, reportable) {
+  const known = rows.map(row => row[name]).filter(value => value !== null);
+  const positive = known.filter(Boolean).length;
+  if (!known.length) return { state: "unknown", observed: 0, positive: 0, rate_bp: null, interval_bp: null };
+  return {
+    state: reportable ? "measured" : "withheld",
+    observed: known.length,
+    positive,
+    rate_bp: reportable ? Math.floor(positive * 10000 / known.length) : null,
+    interval_bp: reportable ? wilsonBasisPoints(positive, known.length) : null,
+  };
+}
+
+function utcDay(seconds) {
+  return new Date(seconds * 1000).toISOString().slice(0, 10);
+}
+
+function createEngineObservationApi(canonicalJsonBuffer) {
+  const digest = value => crypto.createHash("sha256").update(canonicalJsonBuffer(value)).digest("hex");
+
+  function normalizeEngineObservation(row, { host } = {}) {
+    requireValue(isRecord(row), "observation_invalid");
+    const ownerHost = hostValue(host);
+    const body = { ...observationFields(row, ownerHost), answer_digest: answerDigest(row) };
+    return { ...body, digest: digest(body) };
+  }
+
+  function validateObservation(row, ownerHost) {
+    requireValue(isRecord(row) && row.schema === ENGINE_OBSERVATION_SCHEMA && row.host === ownerHost, "observation_invalid");
+    requireValue(Reflect.ownKeys(row).length === OBSERVATION_FIELDS.length && OBSERVATION_FIELDS.every(key => Object.hasOwn(row, key)), "observation_invalid");
+    const { digest: supplied, ...body } = row;
+    let expected;
+    try {
+      expected = digest(body);
+    } catch {
+      throw new EngineObservationError("observation_digest_mismatch");
+    }
+    requireValue(typeof supplied === "string" && !/[^\x00-\x7f]/.test(supplied) && supplied.length === expected.length
+      && crypto.timingSafeEqual(Buffer.from(supplied, "ascii"), Buffer.from(expected, "ascii")), "observation_digest_mismatch");
+    const fields = observationFields(row, ownerHost);
+    requireValue(Object.entries(fields).every(([key, value]) => row[key] === value), "observation_invalid");
+    requireValue(row.answer_digest === null || typeof row.answer_digest === "string" && SHA256.test(row.answer_digest), "observation_invalid");
+  }
+
+  function summarizeEngineObservations(observations = [], { host, sourceLevel = false } = {}) {
+    const ownerHost = hostValue(host);
+    requireValue(Array.isArray(observations), "observation_invalid");
+    requireValue(typeof sourceLevel === "boolean", "observation_source_level_invalid");
+    const seen = new Set();
+    for (const row of observations) {
+      validateObservation(row, ownerHost);
+      requireValue(!seen.has(row.digest), "observation_duplicate");
+      seen.add(row.digest);
+    }
+    const rows = [...observations].sort((a, b) =>
+      compare(a.engine, b.engine) || a.observed_at - b.observed_at || compare(a.prompt_id, b.prompt_id) || compare(a.digest, b.digest));
+    const minimum = sourceLevel ? MIN_RUNS_FOR_SOURCE_COVERAGE : MIN_RUNS_PER_PROMPT;
+    const answered = rows.filter(row => row.status === "answered");
+    const blockers = new Set();
+    if (!answered.length) blockers.add("no_answered_observations");
+    if (answered.some(row => !row.need_id)) blockers.add("insufficient_paraphrases");
+    const engines = [...new Set(rows.map(row => row.engine))].sort(compare);
+    for (const engine of engines) {
+      const engineAnswered = answered.filter(row => row.engine === engine);
+      const runsPerPrompt = new Map();
+      const promptsPerNeed = new Map();
+      for (const row of engineAnswered) {
+        runsPerPrompt.set(row.prompt_id, (runsPerPrompt.get(row.prompt_id) || 0) + 1);
+        if (row.need_id) {
+          if (!promptsPerNeed.has(row.need_id)) promptsPerNeed.set(row.need_id, new Set());
+          promptsPerNeed.get(row.need_id).add(row.prompt_id);
+        }
+      }
+      if (!engineAnswered.length || [...runsPerPrompt.values()].some(count => count < minimum)) blockers.add("insufficient_repetitions");
+      if ([...promptsPerNeed.values()].some(prompts => prompts.size < MIN_PARAPHRASES_PER_NEED)) blockers.add("insufficient_paraphrases");
+    }
+    const reportable = blockers.size === 0;
+    const byEngine = {};
+    for (const engine of engines) {
+      const engineRows = rows.filter(row => row.engine === engine);
+      const engineAnswered = engineRows.filter(row => row.status === "answered");
+      byEngine[engine] = {
+        answered: engineAnswered.length,
+        errors: engineRows.length - engineAnswered.length,
+        prompts: new Set(engineAnswered.map(row => row.prompt_id)).size,
+        signals: Object.fromEntries(SIGNALS.map(name => [name, signalReading(engineAnswered, name, reportable)])),
+      };
+    }
+    const days = [...new Set(answered.map(row => utcDay(row.observed_at)))].sort(compare);
+    const spanDays = days.length ? (Date.parse(days[days.length - 1]) - Date.parse(days[0])) / 86400000 + 1 : 0;
+    const body = {
+      schema: ENGINE_READING_SCHEMA,
+      host: ownerHost,
+      valid: reportable,
+      source_level: sourceLevel,
+      blockers: [...blockers].sort(compare),
+      caveats: answered.length && spanDays < PROTOCOL_WINDOW_DAYS ? ["window_shorter_than_21_days"] : [],
+      window_utc: days.length ? { first: days[0], last: days[days.length - 1], span_days: spanDays, observed_days: days.length } : null,
+      engines,
+      by_engine: byEngine,
+      evidence_levels: [...new Set(rows.map(row => row.evidence_level))].sort(compare),
+      protocol: { ...PROTOCOL },
+      non_claims: [...NON_CLAIMS],
+      observation_digests: rows.map(row => row.digest),
+    };
+    return { ...body, digest: digest(body) };
+  }
+
+  return { normalizeEngineObservation, summarizeEngineObservations };
+}
+
+module.exports = {
+  ENGINE_OBSERVATION_SCHEMA,
+  ENGINE_READING_SCHEMA,
+  EngineObservationError,
+  createEngineObservationApi,
+};

package/js/human-score.mjs

@@ -0,0 +1,13 @@
+import api from "./human-score.js";
+export const HumanScoreError = api.HumanScoreError;
+export const getHumanScorePolicy = api.getHumanScorePolicy;
+export const scoreUnits = api.scoreUnits;
+export const rawToHumanScore = api.rawToHumanScore;
+export const freshnessFactor = api.freshnessFactor;
+export const calculateTechnicalScore = api.calculateTechnicalScore;
+export const socialRaw = api.socialRaw;
+export const socialEdgeWeight = api.socialEdgeWeight;
+export const previewTechnicalDelta = api.previewTechnicalDelta;
+export const calculateHumanScoreEpoch = api.calculateHumanScoreEpoch;
+export const evaluateHumanScoreThresholds = api.evaluateHumanScoreThresholds;
+export default api;

package/js/index.js

@@ -15,6 +15,16 @@ module.exports = {
   createKyaChallengeWithSigner: trust.createKyaChallengeWithSigner,
   signDelegationWithSigner: trust.signDelegationWithSigner,
   signEnvelopeWithSigner: trust.signEnvelopeWithSigner,
+  CONSUMER_REGISTRATION_SCHEMA: trust.CONSUMER_REGISTRATION_SCHEMA,
+  ConsumerRegistrationError: trust.ConsumerRegistrationError,
+  validateConsumerRegistration: trust.validateConsumerRegistration,
+  registrationReceipt: trust.registrationReceipt,
+  signConsumerRegistration: trust.signConsumerRegistration,
+  signConsumerRegistrationWithSigner: trust.signConsumerRegistrationWithSigner,
+  verifyConsumerRegistration: trust.verifyConsumerRegistration,
+  didWebDocumentKeys: trust.didWebDocumentKeys,
+  resolveDidWebKey: trust.resolveDidWebKey,
+  jwksKey: trust.jwksKey,
   VISIT_EVIDENCE_SCHEMA: discovery.VISIT_EVIDENCE_SCHEMA,
   AI_EXPOSURE_SCHEMA: discovery.AI_EXPOSURE_SCHEMA,
   DISCOVERY_SUMMARY_SCHEMA: discovery.DISCOVERY_SUMMARY_SCHEMA,
@@ -24,6 +34,11 @@ module.exports = {
   normalizeAiExposure: discovery.normalizeAiExposure,
   summarizeDiscoveryEvidence: discovery.summarizeDiscoveryEvidence,
   buildDiscoveryEvidenceView: discovery.buildDiscoveryEvidenceView,
+  ENGINE_OBSERVATION_SCHEMA: discovery.ENGINE_OBSERVATION_SCHEMA,
+  ENGINE_READING_SCHEMA: discovery.ENGINE_READING_SCHEMA,
+  EngineObservationError: discovery.EngineObservationError,
+  normalizeEngineObservation: discovery.normalizeEngineObservation,
+  summarizeEngineObservations: discovery.summarizeEngineObservations,
   AuthorizationLeaseError: shield.AuthorizationLeaseError,
   verifyAuthorizationLease: shield.verifyAuthorizationLease,
   leaseClearanceContext: shield.leaseClearanceContext,