@runbound/config-browser 0.0.0-stage → 0.1.0-alpha.1

package/dist/config-experiment-web-durability.d.ts

@@ -0,0 +1,85 @@
+import type { BrowserExperimentDurableQueue, BrowserExperimentIdentityState, BrowserExperimentIdentityStore, BrowserExperimentQueueLimits, BrowserExperimentQueueRecord, BrowserExperimentQueueSnapshot } from "./config-experimentation.js";
+type StoredRecord = Readonly<{
+    outcome: "acknowledged" | "lost" | "pending";
+    record: BrowserExperimentQueueRecord;
+}>;
+export type BrowserExperimentDurabilityState = Readonly<{
+    formatVersion: "runbound.browser.experiment-durability-state.v1";
+    identity?: BrowserExperimentIdentityState;
+    lostByScope: Readonly<Record<string, number>>;
+    records: readonly StoredRecord[];
+    sequences: Readonly<Record<string, number>>;
+}>;
+export interface BrowserExperimentTransactionalDurability {
+    close?(): void;
+    transact<T>(mutate: (state: BrowserExperimentDurabilityState) => Readonly<{
+        result: T;
+        state: BrowserExperimentDurabilityState;
+    }>): Promise<T>;
+}
+export type BrowserExperimentDurabilityDiagnostics = Readonly<{
+    authorizationEligible: false;
+    causalEvidenceOnly: true;
+    lostRecords: number;
+    pendingRecords: number;
+    platform: "web-indexeddb";
+    rawIdentifiersIncluded: false;
+    supported: true;
+}>;
+export interface BrowserExperimentDurabilityAdapter {
+    readonly capability: Readonly<{
+        implementation: "indexeddb" | "mobile-host-provided";
+        nativeImplementationClaim: false;
+        platform: "mobile" | "web";
+        transactional: true;
+    }>;
+    readonly identityStore: BrowserExperimentIdentityStore;
+    readonly queue: BrowserExperimentDurableQueue;
+    close(): void;
+    diagnostics(sessionId: string, runId: string): Promise<BrowserExperimentDurabilityDiagnostics>;
+}
+/**
+ * Contract for a future mobile host. This package supplies no native storage
+ * implementation and makes no claim about a host until one injects both
+ * atomic stores and passes the shared conformance suite.
+ */
+export interface BrowserExperimentMobileDurabilityHost {
+    readonly capability: Readonly<{
+        implementation: "mobile-host-provided";
+        nativeImplementationClaim: false;
+        platform: "mobile";
+        transactional: true;
+    }>;
+    readonly identityStore: BrowserExperimentIdentityStore;
+    readonly queue: BrowserExperimentDurableQueue;
+}
+export type IndexedDbBrowserExperimentDurabilityOptions = Readonly<{
+    databaseName?: string;
+    indexedDB?: IDBFactory;
+}>;
+export declare function createIndexedDbBrowserExperimentDurabilityAdapter(options?: IndexedDbBrowserExperimentDurabilityOptions): BrowserExperimentDurabilityAdapter;
+export declare function createBrowserExperimentDurabilityAdapter(backend: BrowserExperimentTransactionalDurability): BrowserExperimentDurabilityAdapter;
+export declare class TransactionalBrowserExperimentIdentityStore implements BrowserExperimentIdentityStore {
+    #private;
+    constructor(backend: BrowserExperimentTransactionalDurability);
+    load(): Promise<BrowserExperimentIdentityState | undefined>;
+    save(state: BrowserExperimentIdentityState): Promise<void>;
+}
+export declare class TransactionalBrowserExperimentDurableQueue implements BrowserExperimentDurableQueue {
+    #private;
+    constructor(backend: BrowserExperimentTransactionalDurability);
+    acknowledge(idempotencyKeys: readonly string[]): Promise<void>;
+    append(record: BrowserExperimentQueueRecord, limits: BrowserExperimentQueueLimits): Promise<"duplicate" | "stored">;
+    failDelivery(idempotencyKeys: readonly string[], maximumAttempts: number): Promise<void>;
+    find(idempotencyKey: string): Promise<BrowserExperimentQueueRecord | undefined>;
+    pending(input: {
+        limit: number;
+        now: string;
+        runId: string;
+        sessionId: string;
+    }): Promise<readonly BrowserExperimentQueueRecord[]>;
+    purgeIdentity(pseudonymousUnitToken: string): Promise<number>;
+    reserveSequence(sessionId: string, runId: string): Promise<number>;
+    snapshot(sessionId: string, runId: string): Promise<BrowserExperimentQueueSnapshot>;
+}
+export {};

package/dist/config-experiment-web-durability.js

@@ -0,0 +1 @@
+import*as e from"./config-experimentation.js";var t={823(t){t.exports=e}},r={};function n(e){var o=r[e];if(void 0!==o)return o.exports;var i=r[e]={exports:{}};return t[e](i,i.exports,n),i.exports}n.d=(e,t,r)=>{var o=(t,r)=>{for(var o in t)n.o(t,o)&&!n.o(e,o)&&Object.defineProperty(e,o,{enumerable:!0,[r]:t[o]})};o(t,"get"),o(r,"value")},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t);var o={},i=n(823);function s(e={}){let t=e.indexedDB??globalThis.indexedDB;if(!t||"function"!=typeof t.open)throw x("CONFIG_EXPERIMENT_INDEXEDDB_UNAVAILABLE","Browser experiment durability requires IndexedDB and is unavailable in SSR or this host.");let r=e.databaseName??"runbound-config-experiment-evidence-v1";if(!/^[A-Za-z0-9._-]{1,128}$/u.test(r))throw x("CONFIG_EXPERIMENT_INDEXEDDB_NAME_INVALID","Browser experiment IndexedDB database name is invalid.");return a(new u(t,r))}function a(e){let t=new d(e),r=new c(e);return Object.freeze({capability:Object.freeze({implementation:"indexeddb",nativeImplementationClaim:!1,platform:"web",transactional:!0}),close:()=>e.close?.(),async diagnostics(e,t){w(e,"sessionId"),w(t,"runId");let n=await r.snapshot(e,t);return Object.freeze({authorizationEligible:!1,causalEvidenceOnly:!0,lostRecords:n.lostRecords,pendingRecords:n.pendingRecords,platform:"web-indexeddb",rawIdentifiersIncluded:!1,supported:!0})},identityStore:t,queue:r})}class d{#e;constructor(e){this.#e=e}async load(){return this.#e.transact(e=>({result:e.identity?h(e.identity):void 0,state:e}))}async save(e){p(e),await this.#e.transact(t=>({result:void 0,state:D({...t,identity:h(e)})}))}}class c{#e;constructor(e){this.#e=e}async acknowledge(e){let t=b(e);await this.#e.transact(e=>({result:void 0,state:E(e,e=>t.has(e.record.idempotencyKey)&&"pending"===e.outcome?{outcome:"acknowledged",record:e.record}:e)}))}async append(e,t){m(e),function(e){if(!Number.isSafeInteger(e.maximumPendingRecords)||e.maximumPendingRecords<1||!Number.isSafeInteger(e.maximumRecordBytes)||e.maximumRecordBytes<1)throw x("CONFIG_EXPERIMENT_QUEUE_LIMIT_INVALID","Browser experiment queue limits must be positive safe integers.")}(t);let r=await this.#e.transact(r=>{var n;let o=r.records.find(({record:t})=>t.idempotencyKey===e.idempotencyKey);if(o)return f(o.record)!==f(e)?{result:"conflict",state:r}:{result:"duplicate",state:r};if(n=e,new TextEncoder().encode(_(n)).byteLength>t.maximumRecordBytes)return{result:"oversize",state:I(r,e)};let i=r;for(;i.records.filter(({outcome:e})=>"pending"===e).length>=t.maximumPendingRecords;){let e=y(i.records)[0];if(!e)break;i=I(E(i,t=>t.record.idempotencyKey===e.record.idempotencyKey?{outcome:"lost",record:t.record}:t),e.record)}return{result:"stored",state:D({...i,records:[...i.records,{outcome:"pending",record:h(e)}]})}});if("conflict"===r)throw x("CONFIG_EXPERIMENT_IDEMPOTENCY_CONFLICT","An experiment idempotency key cannot bind different semantic content.");if("oversize"===r)throw x("CONFIG_EXPERIMENT_RECORD_BOUND_EXCEEDED","Browser experiment record exceeds its frozen byte bound.");return r}async failDelivery(e,t){if(!Number.isSafeInteger(t)||t<1)throw x("CONFIG_EXPERIMENT_DELIVERY_BOUND_INVALID","Maximum experiment delivery attempts must be a positive safe integer.");let r=b(e);await this.#e.transact(e=>{let n=e;for(let e of r){let r=n.records.find(({record:t})=>t.idempotencyKey===e);if(r?.outcome!=="pending")continue;let o=r.record.attempts+1;n=E(n,r=>r.record.idempotencyKey===e?{outcome:o>=t?"lost":"pending",record:h({...r.record,attempts:o})}:r),o>=t&&(n=I(n,r.record))}return{result:void 0,state:n}})}async find(e){return w(e,"idempotencyKey"),this.#e.transact(t=>({result:h(t.records.find(({record:t})=>t.idempotencyKey===e)?.record),state:t}))}async pending(e){if(w(e.runId,"runId"),w(e.sessionId,"sessionId"),!Number.isSafeInteger(e.limit)||e.limit<1)throw x("CONFIG_EXPERIMENT_PENDING_BOUND_INVALID","Pending experiment delivery limit must be a positive safe integer.");let t=Date.parse(e.now);if(!Number.isFinite(t))throw x("CONFIG_EXPERIMENT_PENDING_TIME_INVALID","Pending experiment query time must be ISO-8601.");return this.#e.transact(r=>{let n=r;for(let e of r.records)"pending"===e.outcome&&Date.parse(e.record.expiresAt)<=t&&(n=I(E(n,t=>t.record.idempotencyKey===e.record.idempotencyKey?{outcome:"lost",record:t.record}:t),e.record));return{result:Object.freeze(y((n=D({...n,records:n.records.filter(({outcome:e,record:r})=>"pending"===e||Date.parse(r.expiresAt)>t)})).records).filter(({record:t})=>t.sessionId===e.sessionId&&t.runId===e.runId).slice(0,e.limit).map(({record:e})=>h(e))),state:n}})}async purgeIdentity(e){return w(e,"pseudonymousUnitToken"),this.#e.transact(t=>({result:t.records.filter(({record:t})=>t.pseudonymousUnitToken===e).length,state:D({...t,records:t.records.filter(({record:t})=>t.pseudonymousUnitToken!==e)})}))}async reserveSequence(e,t){w(e,"sessionId"),w(t,"runId");let r=N(e,t);return this.#e.transact(e=>{let t=(e.sequences[r]??0)+1;if(!Number.isSafeInteger(t))throw x("CONFIG_EXPERIMENT_SEQUENCE_EXHAUSTED","Browser experiment sequence authority is exhausted.");return{result:t,state:D({...e,sequences:{...e.sequences,[r]:t}})}})}async snapshot(e,t){w(e,"sessionId"),w(t,"runId");let r=N(e,t);return this.#e.transact(n=>({result:Object.freeze({lostRecords:n.lostByScope[r]??0,pendingRecords:n.records.filter(({outcome:r,record:n})=>"pending"===r&&n.sessionId===e&&n.runId===t).length}),state:n}))}}class u{#t;#r;#n;#o;constructor(e,t){this.#r=e,this.#t=t}close(){this.#n?.close(),this.#n=void 0,this.#o=void 0}async transact(e){let t=await this.#i();return new Promise((r,n)=>{let o,i=!1,s=t.transaction("authority","readwrite"),a=s.objectStore("authority"),d=a.get("state");function c(e){i||(i=!0,n(e instanceof Error?e:x("CONFIG_EXPERIMENT_INDEXEDDB_TRANSACTION_FAILED","Browser experiment IndexedDB transaction failed closed.")))}d.onerror=()=>c(d.error),d.onsuccess=()=>{try{let t=function(e){if(void 0===e)return D({formatVersion:"runbound.browser.experiment-durability-state.v1",lostByScope:{},records:[],sequences:{}});if("object"!=typeof e||null===e||!("state"in e))throw x("CONFIG_EXPERIMENT_INDEXEDDB_STATE_INVALID","Browser experiment IndexedDB state is malformed.");let t=e.state;return l(t),D(h(t))}(d.result),r=e(t);l(r.state),o=r.result,a.put({key:"state",state:r.state}),s.commit?.()}catch(e){c(e),s.abort()}},s.onabort=()=>c(s.error??x("CONFIG_EXPERIMENT_INDEXEDDB_TRANSACTION_ABORTED","Browser experiment IndexedDB transaction aborted.")),s.onerror=()=>c(s.error),s.oncomplete=()=>{i||(i=!0,r(o))}})}async #i(){return this.#n?this.#n:(this.#o||(this.#o=new Promise((e,t)=>{let r=this.#r.open(this.#t,1);r.onupgradeneeded=()=>{let e=r.result;e.objectStoreNames.contains("authority")||e.createObjectStore("authority",{keyPath:"key"})},r.onerror=()=>t(r.error),r.onblocked=()=>t(x("CONFIG_EXPERIMENT_INDEXEDDB_UPGRADE_BLOCKED","Browser experiment IndexedDB upgrade is blocked by another context.")),r.onsuccess=()=>{let t=r.result;t.onversionchange=()=>{t.close(),this.#n=void 0,this.#o=void 0},this.#n=t,e(t)}}).catch(e=>{throw this.#o=void 0,e instanceof Error?e:x("CONFIG_EXPERIMENT_INDEXEDDB_OPEN_FAILED","Browser experiment IndexedDB authority failed to open.")})),this.#o)}}function l(e){if("runbound.browser.experiment-durability-state.v1"!==e.formatVersion||!Array.isArray(e.records)||"object"!=typeof e.lostByScope||null===e.lostByScope||"object"!=typeof e.sequences||null===e.sequences)throw x("CONFIG_EXPERIMENT_INDEXEDDB_STATE_INVALID","Browser experiment IndexedDB state does not match its durable contract.");e.identity&&p(e.identity);let t=new Set;for(let r of e.records){if(!["acknowledged","lost","pending"].includes(r.outcome)||t.has(r.record.idempotencyKey))throw x("CONFIG_EXPERIMENT_INDEXEDDB_STATE_INVALID","Browser experiment IndexedDB record authority is inconsistent.");t.add(r.record.idempotencyKey),m(r.record)}for(let t of[...Object.values(e.lostByScope),...Object.values(e.sequences)])if(!Number.isSafeInteger(t)||t<0)throw x("CONFIG_EXPERIMENT_INDEXEDDB_STATE_INVALID","Browser experiment IndexedDB counters are invalid.")}function p(e){if(!Number.isSafeInteger(e.generation)||e.generation<0||"active"!==e.state&&"deleted"!==e.state)throw x("CONFIG_EXPERIMENT_IDENTITY_STATE_INVALID","Browser experiment identity state is invalid.");if("active"===e.state){if("granted"!==e.consent||!0!==e.firstParty||!Array.isArray(e.priorPseudonymousUnitTokens))throw x("CONFIG_EXPERIMENT_IDENTITY_STATE_INVALID","Browser experiment identity must remain consented, first-party, and pseudonymous.");for(let t of(w(e.pseudonymousUnitToken,"pseudonymousUnitToken"),e.priorPseudonymousUnitTokens))w(t,"priorPseudonymousUnitToken")}}function m(e){for(let[t,r]of[["idempotencyKey",e.idempotencyKey],["pseudonymousUnitToken",e.pseudonymousUnitToken],["runId",e.runId],["sessionId",e.sessionId]])w(r,t);if(!Number.isSafeInteger(e.sequence)||e.sequence<1||!Number.isSafeInteger(e.attempts)||e.attempts<0||!Number.isSafeInteger(e.identityGeneration)||e.identityGeneration<1||!Number.isFinite(Date.parse(e.createdAt))||!Number.isFinite(Date.parse(e.expiresAt))||Date.parse(e.expiresAt)<=Date.parse(e.createdAt)||!1!==e.evidencePosture.authorizationEligible||"causalEvidenceOnly"!==e.evidencePosture.evidencePurpose||0!==e.evidencePosture.authorizationCapabilities.length)throw x("CONFIG_EXPERIMENT_QUEUE_RECORD_INVALID","Browser experiment queue record violates its causal-only durable contract.")}function I(e,t){let r=N(t.sessionId,t.runId);return D({...e,lostByScope:{...e.lostByScope,[r]:(e.lostByScope[r]??0)+1}})}function E(e,t){return D({...e,records:e.records.map(t)})}function y(e){return e.filter(({outcome:e})=>"pending"===e).sort((e,t)=>e.record.createdAt.localeCompare(t.record.createdAt)||e.record.sequence-t.record.sequence||e.record.idempotencyKey.localeCompare(t.record.idempotencyKey))}function f(e){return _({idempotencyKey:e.idempotencyKey,identityGeneration:e.identityGeneration,kind:e.kind,payload:e.payload,pseudonymousUnitToken:e.pseudonymousUnitToken,runId:e.runId,sessionId:e.sessionId})}function b(e){let t=new Set;for(let r of e)w(r,"idempotencyKey"),t.add(r);return t}function N(e,t){return`${e}\u0000${t}`}function _(e){return JSON.stringify(function e(t){if(null===t||"boolean"==typeof t||"string"==typeof t)return t;if("number"==typeof t){if(!Number.isFinite(t))throw x("CONFIG_EXPERIMENT_QUEUE_RECORD_INVALID","Browser experiment queue record contains a non-finite number.");return Object.is(t,-0)?0:t}if(Array.isArray(t))return t.map(e);if("object"!=typeof t||void 0===t)throw x("CONFIG_EXPERIMENT_QUEUE_RECORD_INVALID","Browser experiment queue record is not canonical JSON.");return Object.fromEntries(Object.entries(t).filter(([,e])=>void 0!==e).sort(([e],[t])=>e.localeCompare(t)).map(([t,r])=>[t,e(r)]))}(e))}function D(e){return function e(t){if(t&&"object"==typeof t&&!Object.isFrozen(t))for(let r of(Object.freeze(t),Object.values(t)))e(r);return t}(h(e))}function h(e){return void 0===e?e:structuredClone(e)}function w(e,t){if("string"!=typeof e||e.length<1||e.length>512||[...e].some(e=>{let t=e.codePointAt(0)??0;return t<32||127===t}))throw x("CONFIG_EXPERIMENT_DURABILITY_TOKEN_INVALID",`Browser experiment ${t} is invalid.`)}function x(e,t){return new i.BrowserExperimentRuntimeError(e,t)}n.d(o,{Ac:()=>a,JT:()=>s,XU:()=>c,kl:()=>d});var T=o.XU,B=o.kl,g=o.Ac,O=o.JT;export{T as TransactionalBrowserExperimentDurableQueue,B as TransactionalBrowserExperimentIdentityStore,g as createBrowserExperimentDurabilityAdapter,O as createIndexedDbBrowserExperimentDurabilityAdapter};

package/dist/config-experiment-web-proof.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserExperimentAssignmentProof, BrowserExperimentProofVerifier, BrowserExperimentSemanticIdentity } from "./config-experimentation.js";
+export type BrowserExperimentWebCryptoAlgorithm = "ECDSA_P256_SHA256" | "Ed25519";
+export type BrowserExperimentTrustedKey = Readonly<{
+    algorithm: BrowserExperimentWebCryptoAlgorithm;
+    key: CryptoKey;
+    keyId: string;
+    purpose: "ingestion" | "server-assignment";
+}>;
+export type BrowserExperimentWebCryptoVerifierOptions = Readonly<{
+    crypto?: Crypto;
+    localIngestionKeyId: string;
+    trustedKeys: readonly BrowserExperimentTrustedKey[];
+}>;
+export type BrowserExperimentProofMessagePurpose = "ingestion" | "server-assignment";
+export declare function createWebCryptoBrowserExperimentProofVerifier(options: BrowserExperimentWebCryptoVerifierOptions): BrowserExperimentProofVerifier;
+/** Canonical signing bytes shared by trusted receipt issuers and Web clients. */
+export declare function browserExperimentProofMessageBytes(input: Readonly<{
+    proof: BrowserExperimentAssignmentProof;
+    purpose: BrowserExperimentProofMessagePurpose;
+    semanticIdentity: BrowserExperimentSemanticIdentity;
+}>): Uint8Array<ArrayBuffer>;
+export declare function encodeBrowserExperimentCompactReceipt(keyId: string, signature: Uint8Array): string;

package/dist/config-experiment-web-proof.js

@@ -0,0 +1 @@
+import*as e from"./config-experimentation.js";var t={823(t){t.exports=e}},r={};function n(e){var i=r[e];if(void 0!==i)return i.exports;var o=r[e]={exports:{}};return t[e](o,o.exports,n),o.exports}n.d=(e,t,r)=>{var i=(t,r)=>{for(var i in t)n.o(t,i)&&!n.o(e,i)&&Object.defineProperty(e,i,{enumerable:!0,[r]:t[i]})};i(t,"get"),i(r,"value")},n.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t);var i={},o=n(823);function s(e){let t=e.crypto??globalThis.crypto;if(!t?.subtle||"function"!=typeof t.subtle.verify)throw f("CONFIG_EXPERIMENT_WEBCRYPTO_UNAVAILABLE","Trusted browser experiment proof verification requires WebCrypto and is unavailable in SSR or this host.");u(e.localIngestionKeyId,"localIngestionKeyId");let r=new Map;for(let t of e.trustedKeys){u(t.keyId,"keyId");let e=`${t.purpose}\u0000${t.keyId}`;if(r.has(e))throw f("CONFIG_EXPERIMENT_WEBCRYPTO_KEY_CONFLICT","Trusted browser experiment proof keys must be unique by purpose and key ID.");r.set(e,Object.freeze({...t}))}async function n(e,n,i,o,s){try{var c;let I=r.get(`${e}\u0000${n}`);if(!I||I.purpose!==e)return!1;let u=a({proof:o,purpose:e,semanticIdentity:s});return await t.subtle.verify((c=I.algorithm,"Ed25519"===c?{name:"Ed25519"}:{hash:"SHA-256",name:"ECDSA"}),I.key,p(i),u)}catch{return!1}}return Object.freeze({verifyLocalArtifact:async(t,r)=>n("ingestion",e.localIngestionKeyId,t.trustedIngestionSignature,t,r),verifyServerAssignment:async(e,t)=>n("server-assignment",e.keyId,e.signature,e,t),async verifyTrustedIngestionReceipt(t,r){if("localArtifact"===t.kind)return n("ingestion",e.localIngestionKeyId,t.trustedIngestionSignature,t,r);let i=function(e){let t=e.indexOf(".");if(t<1||t!==e.lastIndexOf("."))return;let r=e.slice(0,t),n=e.slice(t+1);try{return u(r,"receiptKeyId"),p(n),Object.freeze({keyId:r,signature:n})}catch{return}}(t.trustedIngestionReceipt);return!!i&&n("ingestion",i.keyId,i.signature,t,r)}})}function a(e){var t=e.semanticIdentity;if(!Number.isSafeInteger(t.assignmentEpoch)||t.assignmentEpoch<1)throw f("CONFIG_EXPERIMENT_PROOF_IDENTITY_INVALID","Browser experiment proof assignment epoch is invalid.");for(let[e,r]of[["assignmentUnitToken",t.assignmentUnitToken],["iterationId",t.iterationId],["runId",t.runId],["semanticBoundaryId",t.semanticBoundaryId],["switchbackPeriodId",t.switchbackPeriodId]])void 0!==r&&u(r,e);let r=function(e){if("serverSigned"===e.kind)return u(e.assignmentToken,"assignmentToken"),u(e.keyId,"keyId"),{assignmentToken:e.assignmentToken,keyId:e.keyId,kind:e.kind};if(u(e.activationSetId,"activationSetId"),u(e.trustedIngestionReceipt,"trustedIngestionReceipt"),!/^sha256:[0-9a-f]{64}$/u.test(e.artifactDigest)||!Number.isSafeInteger(e.bucket)||e.bucket<0)throw f("CONFIG_EXPERIMENT_LOCAL_ARTIFACT_PROOF_INVALID","Local browser experiment artifact proof is invalid.");return{activationSetId:e.activationSetId,artifactDigest:e.artifactDigest,bucket:e.bucket,kind:e.kind,trustedIngestionReceipt:e.trustedIngestionReceipt}}(e.proof);if("server-assignment"===e.purpose&&"serverSigned"!==e.proof.kind)throw f("CONFIG_EXPERIMENT_PROOF_PURPOSE_MISMATCH","Server-assignment proof bytes require a server-signed proof.");return new TextEncoder().encode(JSON.stringify(function e(t){if(null===t||"boolean"==typeof t||"string"==typeof t)return t;if("number"==typeof t){if(!Number.isFinite(t))throw f("CONFIG_EXPERIMENT_PROOF_MESSAGE_INVALID","Browser experiment proof message contains a non-finite number.");return Object.is(t,-0)?0:t}if(Array.isArray(t))return t.map(e);if("object"!=typeof t||void 0===t)throw f("CONFIG_EXPERIMENT_PROOF_MESSAGE_INVALID","Browser experiment proof message is not canonical JSON.");return Object.fromEntries(Object.entries(t).filter(([,e])=>void 0!==e).sort(([e],[t])=>e.localeCompare(t)).map(([t,r])=>[t,e(r)]))}({domain:"runbound.browser.config-experiment-proof.v1",proof:r,purpose:e.purpose,semanticIdentity:e.semanticIdentity,semanticIdempotencyKey:I(e.semanticIdentity),transportIdempotencyKey:I(e.semanticIdentity)})))}function c(e,t){if(u(e,"receiptKeyId"),t.byteLength<32||t.byteLength>512)throw f("CONFIG_EXPERIMENT_RECEIPT_SIGNATURE_INVALID","Trusted ingestion receipt signature length is invalid.");return`${e}.${function(e){let t="";for(let r of e)t+=String.fromCharCode(r);return globalThis.btoa(t).replaceAll("+","-").replaceAll("/","_").replace(/=+$/u,"")}(t)}`}function I(e){return["assignment",e.runId,e.iterationId,e.assignmentEpoch,e.assignmentUnitToken,e.semanticBoundaryId,e.switchbackPeriodId??""].join(":")}function p(e){if(!/^[A-Za-z0-9_-]+$/u.test(e))throw f("CONFIG_EXPERIMENT_SIGNATURE_ENCODING_INVALID","Browser experiment proof signature is not base64url.");let t=e.replaceAll("-","+").replaceAll("_","/"),r=globalThis.atob(t.padEnd(4*Math.ceil(t.length/4),"=")),n=new Uint8Array(r.length);for(let e=0;e<r.length;e+=1)n[e]=r.charCodeAt(e);if(n.byteLength<32||n.byteLength>512)throw f("CONFIG_EXPERIMENT_SIGNATURE_ENCODING_INVALID","Browser experiment proof signature length is invalid.");return n}function u(e,t){if("string"!=typeof e||e.length<1||e.length>512||[...e].some(e=>{let t=e.codePointAt(0)??0;return t<32||127===t}))throw f("CONFIG_EXPERIMENT_PROOF_TOKEN_INVALID",`Browser experiment proof ${t} is invalid.`)}function f(e,t){return new o.BrowserExperimentRuntimeError(e,t)}n.d(i,{Fi:()=>s,Zy:()=>c,cj:()=>a});var d=i.cj,l=i.Fi,g=i.Zy;export{d as browserExperimentProofMessageBytes,l as createWebCryptoBrowserExperimentProofVerifier,g as encodeBrowserExperimentCompactReceipt};

package/dist/config-experimentation.d.ts

@@ -0,0 +1,308 @@
+import type { ConfigExperimentObservationEvent } from "./internal/config-contract/experimentation.js";
+export type BrowserExperimentEvidenceStrength = "advisory" | "confirmatory" | "exploratory";
+export type BrowserExperimentJson = boolean | null | number | string | readonly BrowserExperimentJson[] | {
+    readonly [key: string]: BrowserExperimentJson;
+};
+export type BrowserExperimentQaOverride = Readonly<{
+    exclusionPolicy: "excludeFromConfirmatoryAndWinnerSelection";
+    overrideId: string;
+}>;
+export type BrowserExperimentSemanticIdentity = Readonly<{
+    assignmentEpoch: number;
+    assignmentUnitToken: string;
+    iterationId: string;
+    qaOverride?: BrowserExperimentQaOverride;
+    runId: string;
+    semanticBoundaryId: string;
+    switchbackPeriodId?: string;
+}>;
+export type BrowserExperimentAssignmentProof = Readonly<{
+    assignmentToken: string;
+    keyId: string;
+    kind: "serverSigned";
+    signature: string;
+    trustedIngestionReceipt: string;
+}> | Readonly<{
+    activationSetId: string;
+    artifactDigest: string;
+    bucket: number;
+    kind: "localArtifact";
+    trustedIngestionReceipt: string;
+    trustedIngestionSignature: string;
+}>;
+export type BrowserExperimentFrozenThresholds = Readonly<{
+    maximumClockSkewMilliseconds: number;
+    maximumIdentityTransitionsPerRun: number;
+    maximumLossRate: number;
+    maximumMissingnessRate: number;
+    requireHumanTraffic: true;
+    requireUnblockedTransport: true;
+    revision: string;
+}>;
+export type BrowserExperimentMeasurement = Readonly<{
+    adBlockerDetected: boolean;
+    automatedTraffic: "human" | "knownBot" | "unknown";
+    clockSkewMilliseconds: number;
+    missingRecords: number;
+    observedRecords: number;
+    transportBlocked: boolean;
+}>;
+export type BrowserExperimentEvidencePosture = Readonly<{
+    authorizationCapabilities: readonly never[];
+    authorizationEligible: false;
+    blockingReasons: readonly string[];
+    evidencePurpose: "causalEvidenceOnly";
+    evidenceStrength: BrowserExperimentEvidenceStrength;
+    frozenThresholdRevision: string;
+    humanExposureClaim: false;
+    renderExposureClaim: false;
+}>;
+export type BrowserExperimentActiveIdentity = Readonly<{
+    boundAt: string;
+    consent: "granted";
+    firstParty: true;
+    generation: number;
+    priorPseudonymousUnitTokens: readonly string[];
+    pseudonymousUnitToken: string;
+    state: "active";
+    transitionCount: number;
+}>;
+export type BrowserExperimentIdentityTombstone = Readonly<{
+    deletedAt: string;
+    deletionId: string;
+    generation: number;
+    state: "deleted";
+}>;
+export type BrowserExperimentIdentityState = BrowserExperimentActiveIdentity | BrowserExperimentIdentityTombstone;
+export interface BrowserExperimentIdentityStore {
+    load(): Promise<BrowserExperimentIdentityState | undefined>;
+    save(state: BrowserExperimentIdentityState): Promise<void>;
+}
+export type BrowserExperimentRecordKind = "assignment" | "exposure" | "observation";
+export type BrowserExperimentObservationValueProvenance = Readonly<{
+    metricRevisionId: string;
+    sourceRevision: string;
+    valueField: string;
+}>;
+export type BrowserExperimentQueueRecord = Readonly<{
+    attempts: number;
+    createdAt: string;
+    evidencePosture: BrowserExperimentEvidencePosture;
+    expiresAt: string;
+    idempotencyKey: string;
+    identityGeneration: number;
+    kind: BrowserExperimentRecordKind;
+    payload: BrowserExperimentJson;
+    pseudonymousUnitToken: string;
+    runId: string;
+    sequence: number;
+    sessionId: string;
+}>;
+export type BrowserExperimentQueueLimits = Readonly<{
+    maximumPendingRecords: number;
+    maximumRecordBytes: number;
+}>;
+export type BrowserExperimentQueueSnapshot = Readonly<{
+    lostRecords: number;
+    pendingRecords: number;
+}>;
+/**
+ * Production clients inject a persistent implementation whose append,
+ * sequence reservation, acknowledgement, attempt and loss updates are atomic.
+ * `find` covers pending and acknowledged idempotency tombstones so browser
+ * retries never manufacture a second transport identity.
+ */
+export interface BrowserExperimentDurableQueue {
+    acknowledge(idempotencyKeys: readonly string[]): Promise<void>;
+    append(record: BrowserExperimentQueueRecord, limits: BrowserExperimentQueueLimits): Promise<"duplicate" | "stored">;
+    failDelivery(idempotencyKeys: readonly string[], maximumAttempts: number): Promise<void>;
+    find(idempotencyKey: string): Promise<BrowserExperimentQueueRecord | undefined>;
+    pending(input: {
+        limit: number;
+        now: string;
+        runId: string;
+        sessionId: string;
+    }): Promise<readonly BrowserExperimentQueueRecord[]>;
+    purgeIdentity(pseudonymousUnitToken: string): Promise<number>;
+    reserveSequence(sessionId: string, runId: string): Promise<number>;
+    snapshot(sessionId: string, runId: string): Promise<BrowserExperimentQueueSnapshot>;
+}
+export interface BrowserExperimentProofVerifier {
+    verifyLocalArtifact(proof: Extract<BrowserExperimentAssignmentProof, {
+        kind: "localArtifact";
+    }>, semanticIdentity: BrowserExperimentSemanticIdentity): Promise<boolean>;
+    verifyServerAssignment(proof: Extract<BrowserExperimentAssignmentProof, {
+        kind: "serverSigned";
+    }>, semanticIdentity: BrowserExperimentSemanticIdentity): Promise<boolean>;
+    verifyTrustedIngestionReceipt(proof: BrowserExperimentAssignmentProof, semanticIdentity: BrowserExperimentSemanticIdentity): Promise<boolean>;
+}
+export type BrowserExperimentRuntimeBounds = Readonly<{
+    maximumBackgroundFlushEvents: number;
+    maximumBackgroundFlushMilliseconds: number;
+    maximumDeliveryAttempts: number;
+    maximumForegroundFlushEvents: number;
+    maximumPendingRecords: number;
+    maximumRecordBytes: number;
+    recordTtlMilliseconds: number;
+}>;
+export type BrowserExperimentAssignmentReceipt = Readonly<{
+    armId: string;
+    evidencePosture: BrowserExperimentEvidencePosture;
+    exposureToken: string;
+    identityGeneration: number;
+    record: BrowserExperimentQueueRecord;
+    semanticIdentity: BrowserExperimentSemanticIdentity;
+    status: "assigned";
+}>;
+export type BrowserExperimentExposureReceipt = Readonly<{
+    evidencePosture: BrowserExperimentEvidencePosture;
+    exposureRecorded: true;
+    humanExposureClaim: false;
+    record: BrowserExperimentQueueRecord;
+    renderExposureClaim: false;
+    status: "exposed";
+}>;
+export type BrowserExperimentObservationEventFactoryInput = Readonly<{
+    analysisUnitToken: string;
+    assignment: BrowserExperimentAssignmentReceipt;
+    dimensionValues: Readonly<Record<string, boolean | number | string>>;
+    metricRevisionId: string;
+    observationId: string;
+    occurredAt: string;
+    transport: Readonly<{
+        eventId: string;
+        producerEpoch: string;
+        producerId: string;
+        producerSequence: string;
+        producerSessionId: string;
+    }>;
+    value: boolean | number;
+    valueProvenance: BrowserExperimentObservationValueProvenance;
+}>;
+export type BrowserExperimentObservationReceipt = Readonly<{
+    authorizationCapabilities: readonly never[];
+    authorizationEligible: false;
+    evidencePosture: BrowserExperimentEvidencePosture;
+    event: ConfigExperimentObservationEvent;
+    record: BrowserExperimentQueueRecord;
+    status: "observed";
+    valueProvenance: BrowserExperimentObservationValueProvenance;
+}>;
+export type BrowserExperimentDeliveryBatch = Readonly<{
+    records: readonly BrowserExperimentQueueRecord[];
+    runId: string;
+    sessionId: string;
+}>;
+export type BrowserExperimentDeliveryResult = Readonly<{
+    acceptedIdempotencyKeys: readonly string[];
+}>;
+export type BrowserExperimentFlushResult = Readonly<{
+    acknowledged: number;
+    attempted: number;
+    background: boolean;
+    offline: boolean;
+    pending: number;
+    timedOut: boolean;
+}>;
+export declare class BrowserExperimentRuntimeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ConfigExperimentBrowserRuntime {
+    #private;
+    constructor(input: {
+        bounds: BrowserExperimentRuntimeBounds;
+        identityStore: BrowserExperimentIdentityStore;
+        proofVerifier: BrowserExperimentProofVerifier;
+        queue: BrowserExperimentDurableQueue;
+        thresholds: BrowserExperimentFrozenThresholds;
+    });
+    bindIdentity(input: {
+        consent: "denied" | "granted" | "unknown";
+        firstParty: boolean;
+        occurredAt: string;
+        pseudonymousUnitToken: string;
+    }): Promise<BrowserExperimentActiveIdentity>;
+    rotateIdentity(input: {
+        consent: "denied" | "granted" | "unknown";
+        firstParty: boolean;
+        nextPseudonymousUnitToken: string;
+        occurredAt: string;
+    }): Promise<BrowserExperimentActiveIdentity>;
+    deleteIdentity(input: {
+        deletedAt: string;
+        deletionId: string;
+    }): Promise<Readonly<{
+        purgedRecords: number;
+        tombstone: BrowserExperimentIdentityTombstone;
+    }>>;
+    recordAssignment(input: {
+        armId: string;
+        exposureToken: string;
+        measurement: BrowserExperimentMeasurement;
+        occurredAt: string;
+        proof: BrowserExperimentAssignmentProof;
+        semanticIdentity: BrowserExperimentSemanticIdentity;
+        sessionId: string;
+    }): Promise<BrowserExperimentAssignmentReceipt>;
+    expose(input: {
+        assignment: BrowserExperimentAssignmentReceipt;
+        measurement: BrowserExperimentMeasurement;
+        occurredAt: string;
+        semanticBoundaryId: string;
+        sessionId: string;
+    }): Promise<BrowserExperimentExposureReceipt>;
+    observe(input: {
+        allowedDimensionKeys: readonly string[];
+        assignment: BrowserExperimentAssignmentReceipt;
+        createObservationEvent: (input: BrowserExperimentObservationEventFactoryInput) => ConfigExperimentObservationEvent;
+        dimensionValues: Readonly<Record<string, boolean | number | string>>;
+        measurement: BrowserExperimentMeasurement;
+        metricRevisionId: string;
+        observationId: string;
+        occurredAt: string;
+        sessionId: string;
+        value: boolean | number;
+        valueProvenance: Omit<BrowserExperimentObservationValueProvenance, "metricRevisionId">;
+    }): Promise<BrowserExperimentObservationReceipt>;
+    flush(input: {
+        background: boolean;
+        deliver(batch: BrowserExperimentDeliveryBatch): Promise<BrowserExperimentDeliveryResult>;
+        now: string;
+        offline: boolean;
+        runId: string;
+        sessionId: string;
+    }): Promise<BrowserExperimentFlushResult>;
+}
+export declare function assessBrowserExperimentEvidence(input: {
+    identity: BrowserExperimentActiveIdentity;
+    identityTransitionAfterAssignment: boolean;
+    ingestionVerified: boolean;
+    measurement: BrowserExperimentMeasurement;
+    proofVerified: boolean;
+    queueSnapshot: BrowserExperimentQueueSnapshot;
+    thresholds: BrowserExperimentFrozenThresholds;
+}): BrowserExperimentEvidencePosture;
+/** Test/reference store only; production clients inject persistent storage. */
+export declare class MemoryBrowserExperimentIdentityStore implements BrowserExperimentIdentityStore {
+    #private;
+    load(): Promise<BrowserExperimentIdentityState | undefined>;
+    save(state: BrowserExperimentIdentityState): Promise<void>;
+}
+/** Test/reference queue only; production clients inject persistent storage. */
+export declare class MemoryBrowserExperimentDurableQueue implements BrowserExperimentDurableQueue {
+    #private;
+    acknowledge(idempotencyKeys: readonly string[]): Promise<void>;
+    append(record: BrowserExperimentQueueRecord, limits: BrowserExperimentQueueLimits): Promise<"duplicate" | "stored">;
+    failDelivery(idempotencyKeys: readonly string[], maximumAttempts: number): Promise<void>;
+    find(idempotencyKey: string): Promise<BrowserExperimentQueueRecord | undefined>;
+    pending(input: {
+        limit: number;
+        now: string;
+        runId: string;
+        sessionId: string;
+    }): Promise<readonly BrowserExperimentQueueRecord[]>;
+    purgeIdentity(pseudonymousUnitToken: string): Promise<number>;
+    reserveSequence(sessionId: string, runId: string): Promise<number>;
+    snapshot(sessionId: string, runId: string): Promise<BrowserExperimentQueueSnapshot>;
+}

package/dist/config-experimentation.js

@@ -0,0 +1 @@
+var e={};e.d=(t,n,i)=>{var s=(n,i)=>{for(var s in n)e.o(n,s)&&!e.o(t,s)&&Object.defineProperty(t,s,{enumerable:!0,[i]:n[s]})};s(n,"get"),s(i,"value")},e.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t);var t={};class n extends Error{code;constructor(e,t){super(t),this.name="BrowserExperimentRuntimeError",this.code=e}}class i{#e;#t;#n;#i;#s;constructor(e){(function(e){if([e.maximumBackgroundFlushEvents,e.maximumBackgroundFlushMilliseconds,e.maximumDeliveryAttempts,e.maximumForegroundFlushEvents,e.maximumPendingRecords,e.maximumRecordBytes,e.recordTtlMilliseconds].some(e=>!Number.isSafeInteger(e)||e<1))throw w("CONFIG_EXPERIMENT_BOUNDS_INVALID","Browser experiment queue and delivery bounds must be positive safe integers.");if(e.maximumBackgroundFlushEvents>e.maximumForegroundFlushEvents)throw w("CONFIG_EXPERIMENT_BACKGROUND_BOUND_INVALID","Background flushes cannot exceed the foreground event bound.")})(e.bounds),I(e.thresholds),this.#e=Object.freeze({...e.bounds}),this.#t=e.identityStore,this.#n=e.proofVerifier,this.#i=e.queue,this.#s=Object.freeze({...e.thresholds})}async bindIdentity(e){if(b(e.occurredAt,"occurredAt"),T(e.pseudonymousUnitToken,"pseudonymousUnitToken"),"granted"!==e.consent||!e.firstParty)throw w("CONFIG_EXPERIMENT_IDENTITY_CONSENT_REQUIRED","Browser experiment identity requires granted consent and a first-party binding.");let t=await this.#t.load();if(t?.state==="active"){if(t.pseudonymousUnitToken!==e.pseudonymousUnitToken)throw w("CONFIG_EXPERIMENT_IDENTITY_ROTATION_REQUIRED","A different pseudonymous identity must use the explicit rotation lifecycle.");return t}let n=Object.freeze({boundAt:e.occurredAt,consent:"granted",firstParty:!0,generation:(t?.generation??0)+1,priorPseudonymousUnitTokens:Object.freeze([]),pseudonymousUnitToken:e.pseudonymousUnitToken,state:"active",transitionCount:0});return await this.#t.save(n),n}async rotateIdentity(e){b(e.occurredAt,"occurredAt"),T(e.nextPseudonymousUnitToken,"nextPseudonymousUnitToken");let t=await this.#r();if("granted"!==e.consent||!e.firstParty)throw w("CONFIG_EXPERIMENT_IDENTITY_CONSENT_REQUIRED","Identity rotation requires current consent and a first-party binding.");if(t.pseudonymousUnitToken===e.nextPseudonymousUnitToken)return t;if(t.priorPseudonymousUnitTokens.length>=32)throw w("CONFIG_EXPERIMENT_IDENTITY_LINEAGE_BOUND_EXCEEDED","Browser experiment identity rotation exceeded its bounded deletion lineage.");let n=Object.freeze({boundAt:e.occurredAt,consent:"granted",firstParty:!0,generation:t.generation+1,priorPseudonymousUnitTokens:Object.freeze([...t.priorPseudonymousUnitTokens,t.pseudonymousUnitToken]),pseudonymousUnitToken:e.nextPseudonymousUnitToken,state:"active",transitionCount:t.transitionCount+1});return await this.#t.save(n),n}async deleteIdentity(e){b(e.deletedAt,"deletedAt"),T(e.deletionId,"deletionId");let t=await this.#t.load();if(t?.state==="deleted"){if(t.deletionId!==e.deletionId)throw w("CONFIG_EXPERIMENT_DELETION_CONFLICT","Identity deletion is idempotent only for the original deletion identifier.");return Object.freeze({purgedRecords:0,tombstone:t})}let n=0;if(t)for(let e of[...t.priorPseudonymousUnitTokens,t.pseudonymousUnitToken])n+=await this.#i.purgeIdentity(e);let i=Object.freeze({deletedAt:e.deletedAt,deletionId:e.deletionId,generation:t?.generation??0,state:"deleted"});return await this.#t.save(i),Object.freeze({purgedRecords:n,tombstone:i})}async recordAssignment(e){var t,n,i;T(e.armId,"armId"),T(e.exposureToken,"exposureToken"),T(e.sessionId,"sessionId"),b(e.occurredAt,"occurredAt"),function(e){if(!Number.isSafeInteger(e.assignmentEpoch)||e.assignmentEpoch<1)throw w("CONFIG_EXPERIMENT_ASSIGNMENT_EPOCH_INVALID","Assignment epoch must be a positive safe integer.");for(let[t,n]of Object.entries({assignmentUnitToken:e.assignmentUnitToken,iterationId:e.iterationId,runId:e.runId,semanticBoundaryId:e.semanticBoundaryId}))T(n,t);void 0!==e.switchbackPeriodId&&T(e.switchbackPeriodId,"switchbackPeriodId"),void 0!==e.qaOverride&&function(e){if(null===e||"object"!=typeof e||Array.isArray(e)||"exclusionPolicy,overrideId"!==Object.keys(e).sort().join(","))throw w("CONFIG_EXPERIMENT_QA_OVERRIDE_INVALID","QA overrides must be closed explicit evidence markers.");if(T(e.overrideId,"qaOverride.overrideId"),"excludeFromConfirmatoryAndWinnerSelection"!==e.exclusionPolicy)throw w("CONFIG_EXPERIMENT_QA_OVERRIDE_POLICY_INVALID","QA overrides must use the immutable confirmatory-analysis and winner-selection exclusion policy.")}(e.qaOverride)}(e.semanticIdentity),l(e.measurement);let r=await this.#r();if(r.pseudonymousUnitToken!==e.semanticIdentity.assignmentUnitToken)throw w("CONFIG_EXPERIMENT_ASSIGNMENT_IDENTITY_MISMATCH","Assignment evidence must bind the active first-party pseudonymous identity.");let o=(t=e.semanticIdentity,`assignment:${p(t)}`),a=await this.#i.find(o);if(a)return function(e,t){if(R(e.payload)!==R(t))throw w("CONFIG_EXPERIMENT_IDEMPOTENCY_CONFLICT","A semantic assignment retry changed its evidence content.")}(a,{armId:e.armId,exposureToken:e.exposureToken,proof:e.proof,semanticIdentity:e.semanticIdentity}),d(a,e);let u="serverSigned"===(n=e.proof).kind?[n.assignmentToken,n.keyId,n.signature,n.trustedIngestionReceipt].every(_):[n.activationSetId,n.artifactDigest,n.trustedIngestionReceipt,n.trustedIngestionSignature].every(_)&&Number.isSafeInteger(n.bucket)&&n.bucket>=0,c=!!u&&await m(this.#n,e.proof,e.semanticIdentity),I=!!u&&await this.#n.verifyTrustedIngestionReceipt(e.proof,e.semanticIdentity),y=await this.#i.snapshot(e.sessionId,e.semanticIdentity.runId),f=(i=s({identity:r,identityTransitionAfterAssignment:!1,ingestionVerified:I,measurement:e.measurement,proofVerified:c,queueSnapshot:y,thresholds:this.#s}),void 0===e.semanticIdentity.qaOverride?i:Object.freeze({...i,blockingReasons:Object.freeze([...new Set([...i.blockingReasons,"qa-override-excluded"])].sort()),evidenceStrength:"exploratory"})),v=await this.#i.reserveSequence(e.sessionId,e.semanticIdentity.runId),g=h({attempts:0,createdAt:e.occurredAt,evidencePosture:f,expiresAt:E(e.occurredAt,this.#e.recordTtlMilliseconds),idempotencyKey:o,identityGeneration:r.generation,kind:"assignment",payload:{armId:e.armId,exposureToken:e.exposureToken,proof:e.proof,semanticIdentity:e.semanticIdentity},pseudonymousUnitToken:r.pseudonymousUnitToken,runId:e.semanticIdentity.runId,sequence:v,sessionId:e.sessionId});return await this.#i.append(g,this.#o()),d(g,e)}async expose(e){var t,n;if(b(e.occurredAt,"occurredAt"),T(e.semanticBoundaryId,"semanticBoundaryId"),T(e.sessionId,"sessionId"),l(e.measurement),e.assignment.record.sessionId!==e.sessionId)throw w("CONFIG_EXPERIMENT_EXPOSURE_SESSION_MISMATCH","Explicit exposure must remain in the assignment session.");let i=await this.#r(),r=Object.freeze({...e.assignment.semanticIdentity,semanticBoundaryId:e.semanticBoundaryId}),o=(t=e.assignment.exposureToken,n=r,`exposure:${t}:${p(n)}`),d=await this.#i.find(o);if(d)return a(d);let u=await this.#i.snapshot(e.sessionId,r.runId),m="exploratory"===e.assignment.evidencePosture.evidenceStrength,I=s({identity:i,identityTransitionAfterAssignment:i.generation!==e.assignment.identityGeneration||i.pseudonymousUnitToken!==e.assignment.semanticIdentity.assignmentUnitToken,ingestionVerified:!m,measurement:e.measurement,proofVerified:!m,queueSnapshot:u,thresholds:this.#s}),y=c(e.assignment.evidencePosture,I),f=await this.#i.reserveSequence(e.sessionId,r.runId),v=h({attempts:0,createdAt:e.occurredAt,evidencePosture:y,expiresAt:E(e.occurredAt,this.#e.recordTtlMilliseconds),idempotencyKey:o,identityGeneration:i.generation,kind:"exposure",payload:{armId:e.assignment.armId,exposureBoundary:e.semanticBoundaryId,exposureClaim:"explicit-application-boundary",exposureToken:e.assignment.exposureToken,humanExposureClaim:!1,renderExposureClaim:!1,semanticIdentity:r},pseudonymousUnitToken:e.assignment.semanticIdentity.assignmentUnitToken,runId:r.runId,sequence:f,sessionId:e.sessionId});return await this.#i.append(v,this.#o()),a(v)}async observe(e){b(e.occurredAt,"occurredAt"),T(e.sessionId,"sessionId"),T(e.metricRevisionId,"metricRevisionId"),T(e.observationId,"observationId"),T(e.valueProvenance.sourceRevision,"sourceRevision"),T(e.valueProvenance.valueField,"valueField"),l(e.measurement),function(e){if("boolean"!=typeof e&&!Number.isFinite(e))throw w("CONFIG_EXPERIMENT_OBSERVATION_VALUE_INVALID","Metric observation values must be boolean or finite numbers.")}(e.value);let t=function(e,t){if(t.length>32||new Set(t).size!==t.length)throw w("CONFIG_EXPERIMENT_DIMENSION_ALLOWLIST_INVALID","Browser metric dimension allowlists must be unique and contain at most 32 keys.");for(let e of t)T(e,"allowedDimensionKey");let n=new Set(t);return Object.freeze(Object.fromEntries(Object.entries(e).filter(([e])=>n.has(e)).sort(([e],[t])=>e.localeCompare(t))))}(e.dimensionValues,e.allowedDimensionKeys);if(e.assignment.record.sessionId!==e.sessionId)throw w("CONFIG_EXPERIMENT_OBSERVATION_SESSION_MISMATCH","Metric observations must remain in the durable assignment session.");let n=await this.#i.find(e.assignment.record.idempotencyKey);if(n?.kind!=="assignment")throw w("CONFIG_EXPERIMENT_OBSERVATION_ASSIGNMENT_REQUIRED","Metric observations require a previously persisted assignment receipt.");var i,r=n,o=e.assignment;if(r.sessionId!==o.record.sessionId||r.runId!==o.semanticIdentity.runId||r.pseudonymousUnitToken!==o.semanticIdentity.assignmentUnitToken||R(r.payload)!==R(o.record.payload))throw w("CONFIG_EXPERIMENT_OBSERVATION_ASSIGNMENT_CONFLICT","Metric observation assignment receipts must match the persisted assignment identity and content.");let d=await this.#r(),a=Object.freeze({metricRevisionId:e.metricRevisionId,sourceRevision:e.valueProvenance.sourceRevision,valueField:e.valueProvenance.valueField}),m=["observation",(i={analysisUnitToken:e.assignment.semanticIdentity.assignmentUnitToken,metricRevisionId:e.metricRevisionId,observationId:e.observationId,runId:e.assignment.semanticIdentity.runId}).runId,i.metricRevisionId,i.analysisUnitToken,i.observationId].join(":"),I=await this.#i.find(m);if(I)return function(e,t){let n=e.payload;if("observation"!==e.kind||!n.event||n.event.metricRevisionId!==t.metricRevisionId||n.event.observationId!==t.observationId||!Object.is(n.event.value,t.value)||R(n.event.dimensionValues)!==R(t.dimensions)||R(n.valueProvenance)!==R(t.valueProvenance))throw w("CONFIG_EXPERIMENT_IDEMPOTENCY_CONFLICT","A semantic metric observation retry changed its evidence content.")}(I,{dimensions:t,metricRevisionId:e.metricRevisionId,observationId:e.observationId,value:e.value,valueProvenance:a}),u(I);let p=await this.#i.snapshot(e.sessionId,e.assignment.semanticIdentity.runId),y="exploratory"===e.assignment.evidencePosture.evidenceStrength,f=s({identity:d,identityTransitionAfterAssignment:d.generation!==e.assignment.identityGeneration||d.pseudonymousUnitToken!==e.assignment.semanticIdentity.assignmentUnitToken,ingestionVerified:!y,measurement:e.measurement,proofVerified:!y,queueSnapshot:p,thresholds:this.#s}),v=c(e.assignment.evidencePosture,f),g=await this.#i.reserveSequence(e.sessionId,e.assignment.semanticIdentity.runId),_=Object.freeze({eventId:`${e.sessionId}-${e.assignment.semanticIdentity.runId}-${g}`,producerEpoch:`identity-${d.generation}`,producerId:"browser-config-experiment",producerSequence:String(g),producerSessionId:e.sessionId}),N=e.createObservationEvent({analysisUnitToken:e.assignment.semanticIdentity.assignmentUnitToken,assignment:e.assignment,dimensionValues:t,metricRevisionId:e.metricRevisionId,observationId:e.observationId,occurredAt:e.occurredAt,transport:_,value:e.value,valueProvenance:a});var O=N,k={analysisUnitToken:e.assignment.semanticIdentity.assignmentUnitToken,dimensions:t,metricRevisionId:e.metricRevisionId,observationId:e.observationId,occurredAt:e.occurredAt,runId:e.assignment.semanticIdentity.runId,transport:_,value:e.value};if("runbound.config.experiment-observation.v1"!==O.formatVersion||O.analysisUnitToken!==k.analysisUnitToken||O.metricRevisionId!==k.metricRevisionId||O.observationId!==k.observationId||O.occurredAt!==k.occurredAt||O.runId!==k.runId||O.eventId!==k.transport.eventId||O.producerEpoch!==k.transport.producerEpoch||O.producerId!==k.transport.producerId||O.producerSequence!==k.transport.producerSequence||O.producerSessionId!==k.transport.producerSessionId||!Object.is(O.value,k.value)||R(O.dimensionValues)!==R(k.dimensions))throw w("CONFIG_EXPERIMENT_OBSERVATION_IDENTITY_MISMATCH","Browser observation factories cannot change reserved identity, redacted dimensions, value, or transport.");for(let[e,t]of Object.entries({appId:O.appId,configId:O.configId,projectId:O.projectId,tenantId:O.tenantId}))T(t,e);b(O.createdAt,"event.createdAt"),b(O.receivedAt,"event.receivedAt");let x=h({attempts:0,createdAt:e.occurredAt,evidencePosture:v,expiresAt:E(e.occurredAt,this.#e.recordTtlMilliseconds),idempotencyKey:m,identityGeneration:d.generation,kind:"observation",payload:{event:N,valueProvenance:a},pseudonymousUnitToken:e.assignment.semanticIdentity.assignmentUnitToken,runId:e.assignment.semanticIdentity.runId,sequence:g,sessionId:e.sessionId});return await this.#i.append(x,this.#o()),u(x)}async flush(e){let t;b(e.now,"now"),T(e.runId,"runId"),T(e.sessionId,"sessionId");let i=e.background?this.#e.maximumBackgroundFlushEvents:this.#e.maximumForegroundFlushEvents;if(e.offline){let t=await this.#i.snapshot(e.sessionId,e.runId);return g(0,0,e.background,!0,t.pendingRecords,!1)}let s=await this.#i.pending({limit:i,now:e.now,runId:e.runId,sessionId:e.sessionId});if(0===s.length)return g(0,0,e.background,!1,0,!1);let r=!1;try{var o,d;t=await (e.background?(o=e.deliver(Object.freeze({records:s,runId:e.runId,sessionId:e.sessionId})),d=this.#e.maximumBackgroundFlushMilliseconds,new Promise((e,t)=>{let n=globalThis.setTimeout(()=>{t(w("CONFIG_EXPERIMENT_BACKGROUND_FLUSH_TIMEOUT","Background experiment delivery exceeded its frozen time bound."))},d);o.then(t=>{globalThis.clearTimeout(n),e(t)},e=>{globalThis.clearTimeout(n),t(e)})})):e.deliver(Object.freeze({records:s,runId:e.runId,sessionId:e.sessionId})))}catch(i){r=i instanceof n&&"CONFIG_EXPERIMENT_BACKGROUND_FLUSH_TIMEOUT"===i.code,await this.#i.failDelivery(s.map(e=>e.idempotencyKey),this.#e.maximumDeliveryAttempts);let t=await this.#i.snapshot(e.sessionId,e.runId);return g(0,s.length,e.background,!1,t.pendingRecords,r)}let a=new Set(s.map(e=>e.idempotencyKey)),u=[...new Set(t.acceptedIdempotencyKeys)];if(u.some(e=>!a.has(e)))throw w("CONFIG_EXPERIMENT_DELIVERY_RECEIPT_INVALID","Delivery receipts may acknowledge only records in the submitted batch.");let c=new Set(u),m=s.map(e=>e.idempotencyKey).filter(e=>!c.has(e));await this.#i.acknowledge(u),await this.#i.failDelivery(m,this.#e.maximumDeliveryAttempts);let l=await this.#i.snapshot(e.sessionId,e.runId);return g(u.length,s.length,e.background,!1,l.pendingRecords,!1)}async #r(){let e=await this.#t.load();if(e?.state!=="active")throw w("CONFIG_EXPERIMENT_IDENTITY_UNAVAILABLE","An active consented first-party pseudonymous identity is required.");return e}#o(){return{maximumPendingRecords:this.#e.maximumPendingRecords,maximumRecordBytes:this.#e.maximumRecordBytes}}}function s(e){l(e.measurement),I(e.thresholds);let t=[],n=[];e.identity.firstParty&&"granted"===e.identity.consent||t.push("first-party-consent-unavailable"),e.proofVerified||t.push("assignment-proof-unverified"),e.ingestionVerified||t.push("trusted-ingestion-receipt-unverified"),(!Number.isFinite(e.measurement.clockSkewMilliseconds)||Math.abs(e.measurement.clockSkewMilliseconds)>e.thresholds.maximumClockSkewMilliseconds)&&n.push("clock-skew-threshold-failed"),e.thresholds.requireHumanTraffic&&"human"!==e.measurement.automatedTraffic&&n.push("automated-traffic-threshold-failed"),e.thresholds.requireUnblockedTransport&&(e.measurement.adBlockerDetected||e.measurement.transportBlocked)&&n.push("transport-blocking-threshold-failed"),(e.identity.transitionCount>e.thresholds.maximumIdentityTransitionsPerRun||e.identityTransitionAfterAssignment)&&n.push("identity-transition-threshold-failed");let i=e.measurement.observedRecords,s=e.measurement.missingRecords;s/Math.max(1,i+s)>e.thresholds.maximumMissingnessRate&&n.push("missingness-threshold-failed"),e.queueSnapshot.lostRecords/Math.max(1,e.queueSnapshot.lostRecords+e.queueSnapshot.pendingRecords+i)>e.thresholds.maximumLossRate&&n.push("queue-loss-threshold-failed");let r=Object.freeze([...t,...n].sort());return Object.freeze({authorizationCapabilities:Object.freeze([]),authorizationEligible:!1,blockingReasons:r,evidencePurpose:"causalEvidenceOnly",evidenceStrength:t.length>0?"exploratory":n.length>0?"advisory":"confirmatory",frozenThresholdRevision:e.thresholds.revision,humanExposureClaim:!1,renderExposureClaim:!1})}class r{#d;async load(){return this.#d?structuredClone(this.#d):void 0}async save(e){this.#d=structuredClone(e)}}class o{#a=new Map;#u=new Map;#c=new Map;#m=new Map;#l=new Map;async acknowledge(e){for(let t of e)this.#I(t)}async append(e,t){var n,i=t;if(!Number.isSafeInteger(i.maximumPendingRecords)||i.maximumPendingRecords<1||!Number.isSafeInteger(i.maximumRecordBytes)||i.maximumRecordBytes<1)throw w("CONFIG_EXPERIMENT_QUEUE_LIMIT_INVALID","Durable queue limits must be positive safe integers.");let s=this.#u.get(e.idempotencyKey);if(s){if(R(s.payload)!==R(e.payload))throw w("CONFIG_EXPERIMENT_IDEMPOTENCY_CONFLICT","An experiment idempotency key cannot bind different content.");return"duplicate"}if(n=e,new TextEncoder().encode(R(n)).byteLength>t.maximumRecordBytes)throw this.#p(e),w("CONFIG_EXPERIMENT_RECORD_BOUND_EXCEEDED","Browser experiment record exceeds its frozen byte bound.");for(;this.#l.size>=t.maximumPendingRecords;){let e=y(this.#l.values())[0];if(!e)break;this.#h(e.idempotencyKey),this.#p(e)}let r=h({...e,attempts:0});return this.#l.set(f(r),r),this.#u.set(r.idempotencyKey,r),this.#a.set(r.idempotencyKey,0),"stored"}async failDelivery(e,t){for(let n of e){if(!this.#u.has(n))continue;let e=(this.#a.get(n)??0)+1;if(this.#a.set(n,e),e>=t){let e=this.#u.get(n);this.#h(n),e&&this.#p(e)}else{let t=this.#u.get(n);if(t){let i=h({...t,attempts:e});this.#l.set(f(i),i),this.#u.set(n,i)}}}}async find(e){let t=this.#u.get(e);return t?structuredClone(t):void 0}async pending(e){let t=Date.parse(e.now);for(let e of this.#l.values())Date.parse(e.expiresAt)<=t&&(this.#h(e.idempotencyKey),this.#p(e));return y(this.#l.values()).filter(t=>t.sessionId===e.sessionId&&t.runId===e.runId).slice(0,e.limit).map(e=>structuredClone(e))}async purgeIdentity(e){let t=[...this.#u.values()].filter(t=>t.pseudonymousUnitToken===e);for(let e of t)this.#h(e.idempotencyKey);return t.length}async reserveSequence(e,t){let n=`${e}\u0000${t}`,i=(this.#m.get(n)??0)+1;return this.#m.set(n,i),i}async snapshot(e,t){let n=v(e,t),i=[...this.#l.values()].filter(n=>n.sessionId===e&&n.runId===t).length;return Object.freeze({lostRecords:this.#c.get(n)??0,pendingRecords:i})}#p(e){let t=v(e.sessionId,e.runId);this.#c.set(t,(this.#c.get(t)??0)+1)}#I(e){let t=this.#u.get(e);t&&(this.#l.delete(f(t)),this.#a.delete(e))}#h(e){let t=this.#u.get(e);t&&(this.#l.delete(f(t)),this.#u.delete(e),this.#a.delete(e))}}function d(e,t){return Object.freeze({armId:t.armId,evidencePosture:e.evidencePosture,exposureToken:t.exposureToken,identityGeneration:e.identityGeneration,record:e,semanticIdentity:t.semanticIdentity,status:"assigned"})}function a(e){return Object.freeze({evidencePosture:e.evidencePosture,exposureRecorded:!0,humanExposureClaim:!1,record:e,renderExposureClaim:!1,status:"exposed"})}function u(e){let t=e.payload;return Object.freeze({authorizationCapabilities:Object.freeze([]),authorizationEligible:!1,evidencePosture:e.evidencePosture,event:structuredClone(t.event),record:e,status:"observed",valueProvenance:structuredClone(t.valueProvenance)})}function c(e,t){let n={advisory:1,confirmatory:2,exploratory:0},i=n[e.evidenceStrength]<=n[t.evidenceStrength]?e.evidenceStrength:t.evidenceStrength;return Object.freeze({...t,blockingReasons:Object.freeze([...new Set([...e.blockingReasons,...t.blockingReasons])].sort()),evidenceStrength:i})}async function m(e,t,n){return"serverSigned"===t.kind?e.verifyServerAssignment(t,n):e.verifyLocalArtifact(t,n)}function l(e){if(!Number.isFinite(e.clockSkewMilliseconds)||!Number.isSafeInteger(e.missingRecords)||e.missingRecords<0||!Number.isSafeInteger(e.observedRecords)||e.observedRecords<0)throw w("CONFIG_EXPERIMENT_MEASUREMENT_INVALID","Experiment measurement counters and clock skew must be finite and non-negative where applicable.")}function I(e){if(T(e.revision,"threshold revision"),!Number.isFinite(e.maximumClockSkewMilliseconds)||e.maximumClockSkewMilliseconds<0||!Number.isSafeInteger(e.maximumIdentityTransitionsPerRun)||e.maximumIdentityTransitionsPerRun<0||!N(e.maximumLossRate)||!N(e.maximumMissingnessRate)||!0!==e.requireHumanTraffic||!0!==e.requireUnblockedTransport)throw w("CONFIG_EXPERIMENT_THRESHOLDS_INVALID","Confirmatory browser thresholds must be finite, bounded, and fail closed.")}function p(e){return[e.runId,e.iterationId,e.assignmentEpoch,e.assignmentUnitToken,e.semanticBoundaryId,e.switchbackPeriodId??""].join(":")}function h(e){return Object.freeze({...structuredClone(e),evidencePosture:Object.freeze({...e.evidencePosture,authorizationCapabilities:Object.freeze([]),blockingReasons:Object.freeze([...e.evidencePosture.blockingReasons])})})}function y(e){return[...e].sort((e,t)=>e.sessionId.localeCompare(t.sessionId)||e.runId.localeCompare(t.runId)||e.sequence-t.sequence||e.idempotencyKey.localeCompare(t.idempotencyKey))}function f(e){return`${e.sessionId}\u0000${e.runId}\u0000${e.sequence}`}function v(e,t){return`${e}\u0000${t}`}function g(e,t,n,i,s,r){return Object.freeze({acknowledged:e,attempted:t,background:n,offline:i,pending:s,timedOut:r})}function E(e,t){return new Date(Date.parse(e)+t).toISOString()}function b(e,t){if("string"!=typeof e||!Number.isFinite(Date.parse(e)))throw w("CONFIG_EXPERIMENT_TIMESTAMP_INVALID",`${t} must be an ISO-compatible timestamp.`)}function T(e,t){if(!_(e)||e.length>512)throw w("CONFIG_EXPERIMENT_IDENTIFIER_INVALID",`${t} must be a bounded non-empty identifier.`)}function _(e){return"string"==typeof e&&e.trim().length>0}function N(e){return Number.isFinite(e)&&e>=0&&e<=1}function R(e){return Array.isArray(e)?`[${e.map(R).join(",")}]`:e&&"object"==typeof e?`{${Object.entries(e).sort(([e],[t])=>e.localeCompare(t)).map(([e,t])=>`${JSON.stringify(e)}:${R(t)}`).join(",")}}`:JSON.stringify(e)}function w(e,t){return new n(e,t)}e.d(t,{KA:()=>i,SW:()=>r,eL:()=>n,nS:()=>o,nq:()=>s});var O=t.eL,k=t.KA,x=t.nS,A=t.SW,S=t.nq;export{O as BrowserExperimentRuntimeError,k as ConfigExperimentBrowserRuntime,x as MemoryBrowserExperimentDurableQueue,A as MemoryBrowserExperimentIdentityStore,S as assessBrowserExperimentEvidence};

package/dist/config-public-decision.d.ts

@@ -0,0 +1,67 @@
+import type { ConfigAudienceArtifact, ConfigContextContract, ConfigDecisioningActivationSet, ConfigDecisionResult, ConfigEvaluationContext } from "./internal/config-contract/decisioning.js";
+export type ConfigBrowserPublicDecisionManifest = Readonly<{
+    activationSequence: number;
+    activationSetId: string;
+    artifactDigest: string;
+    audience: "localPublic";
+    configId: string;
+    contextContractDigest: string;
+    currentUntil: string;
+    formatVersion: "runbound.config.browser-public-decision-manifest.v1";
+    keyId: string;
+    notBefore: string;
+    projectId: string;
+    schemaDigest: string;
+    signature: string;
+    signatureAlgorithm: "ECDSA_SHA_256" | "Ed25519";
+    softwareReleaseId: string;
+    tenantId: string;
+}>;
+export type ConfigBrowserPublicDecisionBundle = Readonly<{
+    activationSet: ConfigDecisioningActivationSet;
+    artifact: ConfigAudienceArtifact;
+    contextContract: ConfigContextContract;
+    formatVersion: "runbound.config.browser-public-decision-bundle.v1";
+    manifest: ConfigBrowserPublicDecisionManifest;
+}>;
+export type ConfigBrowserPublicDecisionScope = Readonly<{
+    activationSetId: string;
+    configId: string;
+    keyId: string;
+    minimumActivationSequenceExclusive?: number;
+    projectId: string;
+    schemaDigest: string;
+    softwareReleaseId: string;
+    tenantId: string;
+}>;
+export type ConfigBrowserPublicDecisionTrustedKey = Readonly<{
+    algorithm: "ECDSA_SHA_256" | "Ed25519";
+    key: CryptoKey;
+    keyId: string;
+}>;
+export type ConfigBrowserPublicDecisionClientOptions = Readonly<{
+    bundle: ConfigBrowserPublicDecisionBundle | Uint8Array | string;
+    crypto?: Crypto;
+    now?: Date;
+    scope: ConfigBrowserPublicDecisionScope;
+    trustedKeys: readonly ConfigBrowserPublicDecisionTrustedKey[];
+}>;
+export declare class ConfigBrowserPublicDecisionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ConfigBrowserPublicDecisionClient {
+    #private;
+    private constructor();
+    static create(options: ConfigBrowserPublicDecisionClientOptions): Promise<ConfigBrowserPublicDecisionClient>;
+    evaluate(decisionId: string, context: ConfigEvaluationContext, now?: Date): ConfigDecisionResult;
+    status(): Readonly<{
+        activationSequence: number;
+        activationSetId: string;
+        artifactDigest: string;
+        audience: "localPublic";
+        currentUntil: string;
+        schemaDigest: string;
+        softwareReleaseId: string;
+    }>;
+}