@empire-builder-kit/runtime 1.0.0-beta.8 → 1.0.0-rc.1

package/src/configuration/provider.d.ts

@@ -0,0 +1,59 @@
+import { type ConfigurationDeclaration, type ConfigurationValue } from './contract.js';
+export declare const CONFIGURATION_EVALUATION_REASONS: readonly ["STATIC", "CACHED", "STALE", "DEFAULT", "ERROR"];
+export declare const CONFIGURATION_ERROR_CATEGORIES: readonly ["FLAG_NOT_FOUND", "TYPE_MISMATCH", "PROVIDER_UNAVAILABLE", "TIMEOUT", "CANCELLED", "INVALID_CONTEXT"];
+export type ConfigurationEvaluationReason = (typeof CONFIGURATION_EVALUATION_REASONS)[number];
+export type ConfigurationErrorCategory = (typeof CONFIGURATION_ERROR_CATEGORIES)[number];
+export type ConfigurationContextValue = boolean | number | string;
+export type ConfigurationEvaluationContext = Readonly<Record<string, ConfigurationContextValue>>;
+export interface ConfigurationEvaluationDetails<Value extends ConfigurationValue> {
+    errorCategory?: ConfigurationErrorCategory;
+    flagKey: string;
+    providerName: string;
+    providerVersion?: string;
+    reason: ConfigurationEvaluationReason;
+    value: Value;
+    variant?: string;
+}
+export interface ConfigurationEvaluationTelemetry {
+    cacheState: 'fresh' | 'stale' | 'miss';
+    errorCategory?: ConfigurationErrorCategory;
+    key: string;
+    provider: string;
+    reason: ConfigurationEvaluationReason;
+}
+export interface ConfigurationSnapshot {
+    loadedAt: number;
+    values: Readonly<Record<string, ConfigurationValue>>;
+    variants?: Readonly<Record<string, string>>;
+    version: string;
+}
+export interface ConfigurationSnapshotLoader {
+    load(signal: AbortSignal): Promise<ConfigurationSnapshot>;
+}
+export interface LocalConfigurationProviderOptions {
+    initialSnapshot?: ConfigurationSnapshot;
+    loader?: ConfigurationSnapshotLoader;
+    now?: () => number;
+    onEvaluation?: (event: ConfigurationEvaluationTelemetry) => void;
+    providerName?: string;
+}
+export declare class LocalConfigurationProvider {
+    readonly metadata: Readonly<{
+        name: string;
+    }>;
+    private readonly declarations;
+    private readonly loader?;
+    private readonly now;
+    private readonly onEvaluation?;
+    private readonly providerName;
+    private snapshot?;
+    constructor(declarationsInput: readonly ConfigurationDeclaration[], options: LocalConfigurationProviderOptions);
+    private emit;
+    private fallback;
+    private refresh;
+    resolveEvaluation<Value extends ConfigurationValue>(flagKey: string, defaultValue: Value, context?: ConfigurationEvaluationContext, callerSignal?: AbortSignal): Promise<ConfigurationEvaluationDetails<Value>>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context?: ConfigurationEvaluationContext, signal?: AbortSignal): Promise<ConfigurationEvaluationDetails<boolean>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, context?: ConfigurationEvaluationContext, signal?: AbortSignal): Promise<ConfigurationEvaluationDetails<number>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, context?: ConfigurationEvaluationContext, signal?: AbortSignal): Promise<ConfigurationEvaluationDetails<string>>;
+    resolveObjectEvaluation<Value extends ConfigurationValue>(flagKey: string, defaultValue: Value, context?: ConfigurationEvaluationContext, signal?: AbortSignal): Promise<ConfigurationEvaluationDetails<Value>>;
+}

package/src/configuration/provider.js

@@ -0,0 +1,198 @@
+import { __awaiter } from "tslib";
+import { configurationValueMatchesDeclaration, defineConfiguration, } from './contract.js';
+export const CONFIGURATION_EVALUATION_REASONS = [
+    'STATIC',
+    'CACHED',
+    'STALE',
+    'DEFAULT',
+    'ERROR',
+];
+export const CONFIGURATION_ERROR_CATEGORIES = [
+    'FLAG_NOT_FOUND',
+    'TYPE_MISMATCH',
+    'PROVIDER_UNAVAILABLE',
+    'TIMEOUT',
+    'CANCELLED',
+    'INVALID_CONTEXT',
+];
+const SAFE_CONTEXT_KEY = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+const MAX_CONTEXT_ENTRIES = 16;
+const MAX_CONTEXT_STRING_LENGTH = 256;
+const DEFAULT_PROVIDER_NAME = 'ebk-local';
+const SAFE_PROVIDER_NAME = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+function contextIsValid(context) {
+    const entries = Object.entries(context);
+    return (entries.length <= MAX_CONTEXT_ENTRIES &&
+        entries.every(([key, value]) => SAFE_CONTEXT_KEY.test(key) &&
+            (typeof value !== 'string' ||
+                value.length <= MAX_CONTEXT_STRING_LENGTH) &&
+            (typeof value !== 'number' || Number.isFinite(value))));
+}
+function timeoutSignal(timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    let didTimeOut = false;
+    const timer = setTimeout(() => {
+        didTimeOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const cancel = () => controller.abort();
+    callerSignal === null || callerSignal === void 0 ? void 0 : callerSignal.addEventListener('abort', cancel, { once: true });
+    return {
+        dispose() {
+            clearTimeout(timer);
+            callerSignal === null || callerSignal === void 0 ? void 0 : callerSignal.removeEventListener('abort', cancel);
+        },
+        signal: controller.signal,
+        timedOut: () => didTimeOut,
+    };
+}
+export class LocalConfigurationProvider {
+    constructor(declarationsInput, options) {
+        var _a, _b;
+        const declarations = defineConfiguration(declarationsInput);
+        if (declarations.some((declaration) => !['local', 'appconfig'].includes(declaration.provider) ||
+            declaration.class === 'secret')) {
+            throw new Error('LocalConfigurationProvider accepts only local or AppConfig non-secret declarations.');
+        }
+        if (!options.loader && !options.initialSnapshot) {
+            throw new Error('LocalConfigurationProvider requires an initial snapshot or loader.');
+        }
+        const providerName = (_a = options.providerName) !== null && _a !== void 0 ? _a : DEFAULT_PROVIDER_NAME;
+        if (!SAFE_PROVIDER_NAME.test(providerName)) {
+            throw new Error('LocalConfigurationProvider providerName must be a bounded machine-safe identifier.');
+        }
+        this.declarations = new Map(declarations.map((declaration) => [declaration.key, declaration]));
+        this.loader = options.loader;
+        this.now = (_b = options.now) !== null && _b !== void 0 ? _b : Date.now;
+        this.onEvaluation = options.onEvaluation;
+        this.providerName = providerName;
+        this.metadata = { name: providerName };
+        this.snapshot = options.initialSnapshot;
+    }
+    emit(details, cacheState) {
+        var _a;
+        (_a = this.onEvaluation) === null || _a === void 0 ? void 0 : _a.call(this, Object.assign(Object.assign({ cacheState }, (details.errorCategory
+            ? { errorCategory: details.errorCategory }
+            : {})), { key: details.flagKey, provider: this.providerName, reason: details.reason }));
+    }
+    fallback(declaration, flagKey, defaultValue, errorCategory, cacheState) {
+        const fallback = (declaration === null || declaration === void 0 ? void 0 : declaration.safeFallback) !== undefined
+            ? declaration.safeFallback
+            : defaultValue;
+        const details = {
+            errorCategory,
+            flagKey,
+            providerName: this.providerName,
+            reason: errorCategory === 'FLAG_NOT_FOUND' ? 'DEFAULT' : 'ERROR',
+            value: fallback,
+        };
+        this.emit(details, cacheState);
+        return details;
+    }
+    refresh(declaration, callerSignal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.loader) {
+                return this.snapshot
+                    ? { cancelled: false, snapshot: this.snapshot, timedOut: false }
+                    : { cancelled: false, timedOut: false };
+            }
+            const boundedSignal = timeoutSignal(declaration.cache.timeoutMs, callerSignal);
+            try {
+                const snapshot = yield this.loader.load(boundedSignal.signal);
+                if (snapshot.version.trim().length === 0 ||
+                    !Number.isFinite(snapshot.loadedAt) ||
+                    snapshot.loadedAt > this.now()) {
+                    return { cancelled: false, timedOut: false };
+                }
+                this.snapshot = snapshot;
+                return { cancelled: false, snapshot, timedOut: false };
+            }
+            catch (_a) {
+                return {
+                    cancelled: (callerSignal === null || callerSignal === void 0 ? void 0 : callerSignal.aborted) === true,
+                    timedOut: boundedSignal.timedOut(),
+                };
+            }
+            finally {
+                boundedSignal.dispose();
+            }
+        });
+    }
+    resolveEvaluation(flagKey_1, defaultValue_1) {
+        return __awaiter(this, arguments, void 0, function* (flagKey, defaultValue, context = {}, callerSignal) {
+            var _a;
+            const declaration = this.declarations.get(flagKey);
+            if (!declaration) {
+                return this.fallback(undefined, flagKey, defaultValue, 'FLAG_NOT_FOUND', 'miss');
+            }
+            if (!contextIsValid(context) ||
+                (callerSignal === null || callerSignal === void 0 ? void 0 : callerSignal.aborted) ||
+                !configurationValueMatchesDeclaration(defaultValue, declaration)) {
+                return this.fallback(declaration, flagKey, defaultValue, (callerSignal === null || callerSignal === void 0 ? void 0 : callerSignal.aborted)
+                    ? 'CANCELLED'
+                    : !contextIsValid(context)
+                        ? 'INVALID_CONTEXT'
+                        : 'TYPE_MISMATCH', this.snapshot ? 'stale' : 'miss');
+            }
+            const age = this.snapshot
+                ? Math.max(0, this.now() - this.snapshot.loadedAt)
+                : Number.POSITIVE_INFINITY;
+            let snapshot = this.snapshot;
+            let refreshFailed = false;
+            let refreshCancelled = false;
+            let refreshTimedOut = false;
+            if (!snapshot || age >= declaration.cache.refreshAfterMs) {
+                const refreshed = yield this.refresh(declaration, callerSignal);
+                if (refreshed.snapshot) {
+                    snapshot = refreshed.snapshot;
+                }
+                else {
+                    refreshFailed = true;
+                    refreshCancelled = refreshed.cancelled;
+                    refreshTimedOut = refreshed.timedOut;
+                }
+            }
+            if (!snapshot) {
+                return this.fallback(declaration, flagKey, defaultValue, refreshCancelled
+                    ? 'CANCELLED'
+                    : refreshTimedOut
+                        ? 'TIMEOUT'
+                        : 'PROVIDER_UNAVAILABLE', 'miss');
+            }
+            const snapshotAge = Math.max(0, this.now() - snapshot.loadedAt);
+            if (snapshotAge > declaration.cache.maxStaleMs) {
+                return this.fallback(declaration, flagKey, defaultValue, refreshCancelled
+                    ? 'CANCELLED'
+                    : refreshTimedOut
+                        ? 'TIMEOUT'
+                        : 'PROVIDER_UNAVAILABLE', 'stale');
+            }
+            const value = snapshot.values[flagKey];
+            if (value === undefined ||
+                !configurationValueMatchesDeclaration(value, declaration)) {
+                return this.fallback(declaration, flagKey, defaultValue, value === undefined ? 'FLAG_NOT_FOUND' : 'TYPE_MISMATCH', snapshotAge >= declaration.cache.refreshAfterMs ? 'stale' : 'fresh');
+            }
+            const cacheState = snapshotAge >= declaration.cache.refreshAfterMs ? 'stale' : 'fresh';
+            const details = Object.assign(Object.assign(Object.assign({}, (refreshFailed
+                ? { errorCategory: 'PROVIDER_UNAVAILABLE' }
+                : {})), { flagKey, providerName: this.providerName, providerVersion: snapshot.version, reason: refreshFailed ? 'STALE' : this.loader ? 'CACHED' : 'STATIC', value: value }), (((_a = snapshot.variants) === null || _a === void 0 ? void 0 : _a[flagKey])
+                ? { variant: snapshot.variants[flagKey] }
+                : {}));
+            this.emit(details, cacheState);
+            return details;
+        });
+    }
+    resolveBooleanEvaluation(flagKey, defaultValue, context, signal) {
+        return this.resolveEvaluation(flagKey, defaultValue, context, signal);
+    }
+    resolveNumberEvaluation(flagKey, defaultValue, context, signal) {
+        return this.resolveEvaluation(flagKey, defaultValue, context, signal);
+    }
+    resolveStringEvaluation(flagKey, defaultValue, context, signal) {
+        return this.resolveEvaluation(flagKey, defaultValue, context, signal);
+    }
+    resolveObjectEvaluation(flagKey, defaultValue, context, signal) {
+        return this.resolveEvaluation(flagKey, defaultValue, context, signal);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/src/configuration/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/configuration/provider.ts"],"names":[],"mappings":"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"}

package/src/configuration/rollout-evaluator.cjs

@@ -0,0 +1,54 @@
+// @generated from packages/runtime/src/configuration/rollout-evaluator.ts by tools/runtime/generate-shared-authorities.mjs
+// Do not edit this artifact directly.
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.evaluatePercentageRolloutValue = evaluatePercentageRolloutValue;
+exports.evaluatePseudonymousPercentageRolloutValue =
+  evaluatePseudonymousPercentageRolloutValue;
+const node_crypto_1 = require('node:crypto');
+const safe_reference_js_1 = require('../safe-reference.cjs');
+const PSEUDONYMOUS_STABLE_KEY = /^psk_v1_[a-f0-9]{64}$/;
+const OPERATIONAL_STABLE_KEY = /^opk_v1_[a-f0-9]{64}$/;
+/**
+ * Sole authored implementation of deterministic percentage assignment.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+function evaluatePercentageRolloutValue(input, keyContract) {
+  const acceptsStableKey =
+    keyContract === 'pseudonymous'
+      ? PSEUDONYMOUS_STABLE_KEY.test(input?.stableKey)
+      : keyContract === 'pseudonymous-or-operational' &&
+        (PSEUDONYMOUS_STABLE_KEY.test(input?.stableKey) ||
+          OPERATIONAL_STABLE_KEY.test(input?.stableKey));
+  if (
+    (keyContract !== 'pseudonymous' &&
+      keyContract !== 'pseudonymous-or-operational') ||
+    typeof input?.enabled !== 'boolean' ||
+    !Number.isInteger(input?.percentage) ||
+    input.percentage < 0 ||
+    input.percentage > 100 ||
+    !(0, safe_reference_js_1.isBoundedSafeReference)(input?.rolloutId) ||
+    !(0, safe_reference_js_1.isBoundedSafeReference)(input?.version) ||
+    !acceptsStableKey
+  ) {
+    throw new Error(
+      'Percentage rollout requires bounded configuration identity and a derived stable key.',
+    );
+  }
+  const hash = (0, node_crypto_1.createHash)('sha256')
+    .update(
+      `${input.rolloutId}\u0000${input.version}\u0000${input.stableKey}`,
+      'utf8',
+    )
+    .digest();
+  const bucket = hash.readUInt32BE(0) % 10_000;
+  return {
+    assigned: input.enabled && bucket < input.percentage * 100,
+    bucket,
+  };
+}
+function evaluatePseudonymousPercentageRolloutValue(input) {
+  return evaluatePercentageRolloutValue(input, 'pseudonymous');
+}
+
+Object.freeze(module.exports);

package/src/configuration/rollout-evaluator.d.cts

@@ -0,0 +1,26 @@
+// @generated from packages/runtime/src/configuration/rollout-evaluator.ts by tools/runtime/generate-shared-authorities.mjs
+// Do not edit this artifact directly.
+export interface PercentageRolloutValueInput {
+  enabled: boolean;
+  percentage: number;
+  rolloutId: string;
+  stableKey: string;
+  version: string;
+}
+export interface PercentageRolloutValueEvaluation {
+  assigned: boolean;
+  bucket: number;
+}
+export type PercentageRolloutKeyContract =
+  'pseudonymous' | 'pseudonymous-or-operational';
+/**
+ * Sole authored implementation of deterministic percentage assignment.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export declare function evaluatePercentageRolloutValue(
+  input: PercentageRolloutValueInput,
+  keyContract: PercentageRolloutKeyContract,
+): PercentageRolloutValueEvaluation;
+export declare function evaluatePseudonymousPercentageRolloutValue(
+  input: PercentageRolloutValueInput,
+): PercentageRolloutValueEvaluation;

package/src/configuration/rollout-evaluator.d.ts

@@ -0,0 +1,18 @@
+export interface PercentageRolloutValueInput {
+    enabled: boolean;
+    percentage: number;
+    rolloutId: string;
+    stableKey: string;
+    version: string;
+}
+export interface PercentageRolloutValueEvaluation {
+    assigned: boolean;
+    bucket: number;
+}
+export type PercentageRolloutKeyContract = 'pseudonymous' | 'pseudonymous-or-operational';
+/**
+ * Sole authored implementation of deterministic percentage assignment.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export declare function evaluatePercentageRolloutValue(input: PercentageRolloutValueInput, keyContract: PercentageRolloutKeyContract): PercentageRolloutValueEvaluation;
+export declare function evaluatePseudonymousPercentageRolloutValue(input: PercentageRolloutValueInput): PercentageRolloutValueEvaluation;

package/src/configuration/rollout-evaluator.js

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+import { isBoundedSafeReference } from '../safe-reference.js';
+const PSEUDONYMOUS_STABLE_KEY = /^psk_v1_[a-f0-9]{64}$/;
+const OPERATIONAL_STABLE_KEY = /^opk_v1_[a-f0-9]{64}$/;
+/**
+ * Sole authored implementation of deterministic percentage assignment.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export function evaluatePercentageRolloutValue(input, keyContract) {
+    const acceptsStableKey = keyContract === 'pseudonymous'
+        ? PSEUDONYMOUS_STABLE_KEY.test(input === null || input === void 0 ? void 0 : input.stableKey)
+        : keyContract === 'pseudonymous-or-operational' &&
+            (PSEUDONYMOUS_STABLE_KEY.test(input === null || input === void 0 ? void 0 : input.stableKey) ||
+                OPERATIONAL_STABLE_KEY.test(input === null || input === void 0 ? void 0 : input.stableKey));
+    if ((keyContract !== 'pseudonymous' &&
+        keyContract !== 'pseudonymous-or-operational') ||
+        typeof (input === null || input === void 0 ? void 0 : input.enabled) !== 'boolean' ||
+        !Number.isInteger(input === null || input === void 0 ? void 0 : input.percentage) ||
+        input.percentage < 0 ||
+        input.percentage > 100 ||
+        !isBoundedSafeReference(input === null || input === void 0 ? void 0 : input.rolloutId) ||
+        !isBoundedSafeReference(input === null || input === void 0 ? void 0 : input.version) ||
+        !acceptsStableKey) {
+        throw new Error('Percentage rollout requires bounded configuration identity and a derived stable key.');
+    }
+    const hash = createHash('sha256')
+        .update(`${input.rolloutId}\u0000${input.version}\u0000${input.stableKey}`, 'utf8')
+        .digest();
+    const bucket = hash.readUInt32BE(0) % 10000;
+    return {
+        assigned: input.enabled && bucket < input.percentage * 100,
+        bucket,
+    };
+}
+export function evaluatePseudonymousPercentageRolloutValue(input) {
+    return evaluatePercentageRolloutValue(input, 'pseudonymous');
+}
+//# sourceMappingURL=rollout-evaluator.js.map

package/src/configuration/rollout-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout-evaluator.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/configuration/rollout-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAkB9D,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AACxD,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAEvD;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAAkC,EAClC,WAAyC;IAEzC,MAAM,gBAAgB,GACpB,WAAW,KAAK,cAAc;QAC5B,CAAC,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAC;QAChD,CAAC,CAAC,WAAW,KAAK,6BAA6B;YAC7C,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAC;gBAC7C,sBAAsB,CAAC,IAAI,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAC,CAAC,CAAC;IACvD,IACE,CAAC,WAAW,KAAK,cAAc;QAC7B,WAAW,KAAK,6BAA6B,CAAC;QAChD,OAAO,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,OAAO,CAAA,KAAK,SAAS;QACnC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,UAAU,CAAC;QACpC,KAAK,CAAC,UAAU,GAAG,CAAC;QACpB,KAAK,CAAC,UAAU,GAAG,GAAG;QACtB,CAAC,sBAAsB,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAC;QACzC,CAAC,sBAAsB,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,OAAO,CAAC;QACvC,CAAC,gBAAgB,EACjB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,sFAAsF,CACvF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC9B,MAAM,CACL,GAAG,KAAK,CAAC,SAAS,SAAS,KAAK,CAAC,OAAO,SAAS,KAAK,CAAC,SAAS,EAAE,EAClE,MAAM,CACP;SACA,MAAM,EAAE,CAAC;IACZ,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,KAAM,CAAC;IAC7C,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,OAAO,IAAI,MAAM,GAAG,KAAK,CAAC,UAAU,GAAG,GAAG;QAC1D,MAAM;KACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0CAA0C,CACxD,KAAkC;IAElC,OAAO,8BAA8B,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AAC/D,CAAC"}

package/src/configuration/rollout-key.cjs

@@ -0,0 +1,38 @@
+// @generated from packages/runtime/src/configuration/rollout-key.ts by tools/runtime/generate-shared-authorities.mjs
+// Do not edit this artifact directly.
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.derivePseudonymousStableKeyValue = derivePseudonymousStableKeyValue;
+const node_crypto_1 = require('node:crypto');
+const safe_reference_js_1 = require('../safe-reference.cjs');
+/**
+ * Sole authored implementation of pseudonymous rollout-key derivation.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+function derivePseudonymousStableKeyValue(input) {
+  const supportedSecret =
+    typeof input?.secret === 'string' || input?.secret instanceof Uint8Array;
+  const secret =
+    typeof input?.secret === 'string'
+      ? Buffer.from(input.secret, 'utf8')
+      : supportedSecret
+        ? Buffer.from(input.secret)
+        : Buffer.alloc(0);
+  if (
+    !(0, safe_reference_js_1.isBoundedSafeReference)(input?.namespace) ||
+    typeof input?.subjectId !== 'string' ||
+    input.subjectId.length === 0 ||
+    input.subjectId.length > 512 ||
+    !supportedSecret ||
+    secret.byteLength < 32
+  ) {
+    throw new Error(
+      'Pseudonymous stable-key derivation requires a bounded namespace and subject plus a deployment-held secret of at least 32 bytes.',
+    );
+  }
+  return `psk_v1_${(0, node_crypto_1.createHmac)('sha256', secret)
+    .update(`${input.namespace}\u0000${input.subjectId}`, 'utf8')
+    .digest('hex')}`;
+}
+
+Object.freeze(module.exports);

package/src/configuration/rollout-key.d.cts

@@ -0,0 +1,14 @@
+// @generated from packages/runtime/src/configuration/rollout-key.ts by tools/runtime/generate-shared-authorities.mjs
+// Do not edit this artifact directly.
+export interface PseudonymousStableKeyValueInput {
+  namespace: string;
+  secret: string | Uint8Array;
+  subjectId: string;
+}
+/**
+ * Sole authored implementation of pseudonymous rollout-key derivation.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export declare function derivePseudonymousStableKeyValue(
+  input: PseudonymousStableKeyValueInput,
+): string;

package/src/configuration/rollout-key.d.ts

@@ -0,0 +1,10 @@
+export interface PseudonymousStableKeyValueInput {
+    namespace: string;
+    secret: string | Uint8Array;
+    subjectId: string;
+}
+/**
+ * Sole authored implementation of pseudonymous rollout-key derivation.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export declare function derivePseudonymousStableKeyValue(input: PseudonymousStableKeyValueInput): string;

package/src/configuration/rollout-key.js

@@ -0,0 +1,26 @@
+import { createHmac } from 'node:crypto';
+import { isBoundedSafeReference } from '../safe-reference.js';
+/**
+ * Sole authored implementation of pseudonymous rollout-key derivation.
+ * Runtime ESM consumes this source; the CommonJS peer is generated from it.
+ */
+export function derivePseudonymousStableKeyValue(input) {
+    const supportedSecret = typeof (input === null || input === void 0 ? void 0 : input.secret) === 'string' || (input === null || input === void 0 ? void 0 : input.secret) instanceof Uint8Array;
+    const secret = typeof (input === null || input === void 0 ? void 0 : input.secret) === 'string'
+        ? Buffer.from(input.secret, 'utf8')
+        : supportedSecret
+            ? Buffer.from(input.secret)
+            : Buffer.alloc(0);
+    if (!isBoundedSafeReference(input === null || input === void 0 ? void 0 : input.namespace) ||
+        typeof (input === null || input === void 0 ? void 0 : input.subjectId) !== 'string' ||
+        input.subjectId.length === 0 ||
+        input.subjectId.length > 512 ||
+        !supportedSecret ||
+        secret.byteLength < 32) {
+        throw new Error('Pseudonymous stable-key derivation requires a bounded namespace and subject plus a deployment-held secret of at least 32 bytes.');
+    }
+    return `psk_v1_${createHmac('sha256', secret)
+        .update(`${input.namespace}\u0000${input.subjectId}`, 'utf8')
+        .digest('hex')}`;
+}
+//# sourceMappingURL=rollout-key.js.map

package/src/configuration/rollout-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout-key.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/configuration/rollout-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAQ9D;;;GAGG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAAsC;IAEtC,MAAM,eAAe,GACnB,OAAO,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA,KAAK,QAAQ,IAAI,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,aAAY,UAAU,CAAC;IAC3E,MAAM,MAAM,GACV,OAAO,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA,KAAK,QAAQ;QAC/B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC;QACnC,CAAC,CAAC,eAAe;YACf,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAC3B,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,IACE,CAAC,sBAAsB,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAC;QACzC,OAAO,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,SAAS,CAAA,KAAK,QAAQ;QACpC,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAC5B,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,GAAG;QAC5B,CAAC,eAAe;QAChB,MAAM,CAAC,UAAU,GAAG,EAAE,EACtB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,iIAAiI,CAClI,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC1C,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,SAAS,KAAK,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC;SAC5D,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACrB,CAAC"}

package/src/configuration/rollout.d.ts

@@ -0,0 +1,60 @@
+declare const pseudonymousStableKeyBrand: unique symbol;
+declare const operationalRolloutStableKeyBrand: unique symbol;
+export type PseudonymousStableKey = string & {
+    readonly [pseudonymousStableKeyBrand]: true;
+};
+export type OperationalRolloutStableKey = string & {
+    readonly [operationalRolloutStableKeyBrand]: true;
+};
+export type RolloutStableKey = OperationalRolloutStableKey | PseudonymousStableKey;
+export interface PseudonymousStableKeyDerivationInput {
+    namespace: string;
+    secret: string | Uint8Array;
+    subjectId: string;
+}
+export interface OperationalRolloutStableKeyDerivationInput {
+    kind: 'job' | 'lambda' | 'next-server' | 'service';
+    slice: string;
+    workload: string;
+}
+export interface PercentageRolloutInput {
+    enabled: boolean;
+    percentage: number;
+    rolloutId: string;
+    stableKey: RolloutStableKey;
+    version: string;
+}
+export interface PercentageRolloutEvaluation {
+    assigned: boolean;
+    bucket: number;
+}
+/**
+ * Establishes the only supported raw-subject boundary for rollout targeting.
+ * The namespace separates products/uses, while the deployment-held secret
+ * prevents the resulting stable key from revealing or enumerating subjects.
+ */
+export declare const derivePseudonymousStableKey: (input: PseudonymousStableKeyDerivationInput) => PseudonymousStableKey;
+/**
+ * Derives a stable key only for a declared operational workload identity.
+ * This explicit boundary is intentionally separate from authenticated-subject
+ * HMAC derivation. Generator-compatible names describe deployment topology;
+ * their vocabulary is not used to infer whether they identify a person.
+ */
+export declare function deriveOperationalRolloutStableKey(input: OperationalRolloutStableKeyDerivationInput): OperationalRolloutStableKey;
+/**
+ * Evaluates one derived subject or operational identity against a stable
+ * 10,000-bucket rollout.
+ *
+ * The assignment is independent of process, host type, and evaluation order.
+ * The branded stableKey can only be produced at an explicit subject or
+ * non-personal workload derivation boundary.
+ */
+export declare function evaluatePercentageRollout(input: PercentageRolloutInput): PercentageRolloutEvaluation;
+/**
+ * Uses the shared bucket evaluator while retaining the stricter
+ * authenticated-subject key boundary required by release controllers.
+ */
+export declare const evaluatePseudonymousPercentageRollout: (input: Omit<PercentageRolloutInput, "stableKey"> & {
+    stableKey: PseudonymousStableKey;
+}) => PercentageRolloutEvaluation;
+export {};

package/src/configuration/rollout.js

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+import { evaluatePercentageRolloutValue, evaluatePseudonymousPercentageRolloutValue, } from './rollout-evaluator.js';
+import { derivePseudonymousStableKeyValue } from './rollout-key.js';
+const OPERATIONAL_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+ * Establishes the only supported raw-subject boundary for rollout targeting.
+ * The namespace separates products/uses, while the deployment-held secret
+ * prevents the resulting stable key from revealing or enumerating subjects.
+ */
+export const derivePseudonymousStableKey = derivePseudonymousStableKeyValue;
+/**
+ * Derives a stable key only for a declared operational workload identity.
+ * This explicit boundary is intentionally separate from authenticated-subject
+ * HMAC derivation. Generator-compatible names describe deployment topology;
+ * their vocabulary is not used to infer whether they identify a person.
+ */
+export function deriveOperationalRolloutStableKey(input) {
+    if (!OPERATIONAL_NAME.test(input.slice) ||
+        !OPERATIONAL_NAME.test(input.workload)) {
+        throw new Error('Operational rollout identity requires declared generator-compatible Slice, host-kind, and workload names.');
+    }
+    return `opk_v1_${createHash('sha256')
+        .update(`ebk-operational-rollout-v1\u0000${input.slice}\u0000${input.kind}\u0000${input.workload}`, 'utf8')
+        .digest('hex')}`;
+}
+/**
+ * Evaluates one derived subject or operational identity against a stable
+ * 10,000-bucket rollout.
+ *
+ * The assignment is independent of process, host type, and evaluation order.
+ * The branded stableKey can only be produced at an explicit subject or
+ * non-personal workload derivation boundary.
+ */
+export function evaluatePercentageRollout(input) {
+    return evaluatePercentageRolloutValue(input, 'pseudonymous-or-operational');
+}
+/**
+ * Uses the shared bucket evaluator while retaining the stricter
+ * authenticated-subject key boundary required by release controllers.
+ */
+export const evaluatePseudonymousPercentageRollout = evaluatePseudonymousPercentageRolloutValue;
+//# sourceMappingURL=rollout.js.map

package/src/configuration/rollout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout.js","sourceRoot":"","sources":["../../../../../packages/runtime/src/configuration/rollout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,8BAA8B,EAC9B,0CAA0C,GAC3C,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC;AAyCpE,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAEjB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAC/C,KAAiD;IAEjD,IACE,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnC,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EACtC,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2GAA2G,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC;SAClC,MAAM,CACL,mCAAmC,KAAK,CAAC,KAAK,SAAS,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,QAAQ,EAAE,EAC1F,MAAM,CACP;SACA,MAAM,CAAC,KAAK,CAAC,EAAiC,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAA6B;IAE7B,OAAO,8BAA8B,CAAC,KAAK,EAAE,6BAA6B,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAChD,0CAIgC,CAAC"}