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

package/dist/internal/config-contract/decisioning.d.ts

@@ -0,0 +1,430 @@
+import { type JsonValue } from "./base.js";
+export declare const configDecisioningContractVersion = "runbound.config.decisioning.v1";
+/**
+ * Hard protocol bounds. These are compatibility-bearing rejection thresholds,
+ * not deployment defaults, and therefore cannot be raised without a new
+ * decisioning contract version and cross-runtime fixtures.
+ */
+export declare const configDecisioningLimits: Readonly<{
+    maximumActivationSetBytes: number;
+    maximumAllocationFieldBytes: 4096;
+    maximumAllocationRangesPerRule: 64;
+    maximumAttributePathBytes: 256;
+    maximumAttributesPerKind: 64;
+    maximumAttributesTotal: 256;
+    maximumBoundedSetBytes: number;
+    maximumBoundedSetItems: 64;
+    maximumContextBytes: number;
+    maximumContextContractBytes: number;
+    maximumContextKinds: 16;
+    maximumContextStringBytes: 4096;
+    maximumDecisionsPerProgram: 1024;
+    maximumEvaluationDetailsBytes: number;
+    maximumDependencyNodesPerEvaluation: 128;
+    maximumDirectPrerequisites: 16;
+    maximumDirectTargetsPerDecision: 128;
+    maximumEvaluationSteps: 10000;
+    maximumExplicitSegmentMembers: 10000;
+    maximumInlineSimulationCases: 1024;
+    maximumReferencedCohortUnits: 100000;
+    maximumPrerequisiteDepth: 32;
+    maximumPrivateArtifactBytes: number;
+    maximumProgramClauses: 65536;
+    maximumProgramIrBytes: number;
+    maximumProgramRules: 16384;
+    maximumPublicArtifactBytes: number;
+    maximumRemoteRequestBytes: number;
+    maximumRemoteResponseBytes: number;
+    maximumRuleBooleanDepth: 8;
+    maximumRuleClauses: 32;
+    maximumRuleClausesPerDecision: 2048;
+    maximumRulesPerDecision: 128;
+    maximumSegmentSnapshotBytes: number;
+    maximumSegmentsPerProgram: 1024;
+    maximumTraceBytes: number;
+    maximumTraceSteps: 512;
+    maximumUnitKeyBytes: 512;
+    maximumVariationsPerDecision: 32;
+    slotCount: 1000000;
+}>;
+export declare const configDecisioningAdmissionLimits: Readonly<{
+    artifactDelivery: Readonly<{
+        bindingBurst: 20;
+        bindingPerMinute: 120;
+        tenantBurst: 200;
+        tenantPerMinute: 1200;
+    }>;
+    remoteEvaluation: Readonly<{
+        credentialBurst: 200;
+        credentialInFlight: 64;
+        credentialPerMinute: 6000;
+        tenantBurst: 2000;
+        tenantInFlight: 512;
+        tenantPerMinute: 60000;
+    }>;
+    simulation: Readonly<{
+        principalInFlight: 2;
+        principalPerMinute: 30;
+        tenantInFlight: 8;
+        tenantPerMinute: 300;
+    }>;
+}>;
+/**
+ * Inactive/unpriced Phase 3 usage dimensions. Keeping these calculations in
+ * the contract prevents admission counters from being mistaken for billable
+ * units when later gates activate pricing.
+ */
+export declare const configDecisioningCostUnits: Readonly<{
+    artifactDelivery(bodyBytes: number, responseHasBody?: boolean): number;
+    remoteEvaluation(acceptedDecisions: number): number;
+    simulation(decisionContextPairs: number): number;
+}>;
+export declare const configDecisioningPerformanceBudgets: Readonly<{
+    artifactLoad: Readonly<{
+        p95Ms: 500;
+        peakRssGrowthBytes: number;
+    }>;
+    localBudgetEdge: Readonly<{
+        p95Ms: 10;
+        p99Ms: 20;
+    }>;
+    localCommon: Readonly<{
+        minimumEvaluationsPerSecond: 25000;
+        p95Ms: 0.5;
+        p99Ms: 1;
+    }>;
+    localSoak: Readonly<{
+        durationSeconds: 300;
+        maximumP95DriftRatio: 0.1;
+        postWarmRssGrowthBytes: number;
+        minimumEvaluations: 7500000;
+    }>;
+    remoteBudgetEdge: Readonly<{
+        p95Ms: 500;
+        p99Ms: 1000;
+    }>;
+    remoteCold: Readonly<{
+        p99Ms: 2000;
+    }>;
+    remoteWarm: Readonly<{
+        p95Ms: 150;
+        p99Ms: 500;
+    }>;
+    retainedBaseline: Readonly<{
+        maximumP95Ratio: 1.25;
+        minimumThroughputRatio: 0.9;
+    }>;
+}>;
+export type ConfigContextSourceClass = "advisoryClientAsserted" | "applicationAsserted" | "authenticatedWorkload" | "runboundRegistered" | "serverEnriched";
+export type ConfigContextSensitivity = "confidential" | "internal" | "public" | "restricted";
+export type ConfigContextRetention = "assignment" | "exposure" | "metric" | "none" | "request";
+export type ConfigContextAttributeType = "boolean" | "finiteNumber" | "ipAddress" | "semanticVersion" | "string" | "stringSet" | "timestamp";
+export type ConfigTargetingOperator = "equals" | "exists" | "greaterThan" | "greaterThanOrEqual" | "inSet" | "ipInCidr" | "intersects" | "lessThan" | "lessThanOrEqual" | "notEquals" | "prefix" | "substring" | "suffix";
+export type ConfigContextAttributeContract = Readonly<{
+    allowedOperators: readonly ConfigTargetingOperator[];
+    description: string;
+    lifecycle: "active" | "deprecated";
+    nullable: boolean;
+    owner: string;
+    path: string;
+    publicRuleEligible: boolean;
+    required: boolean;
+    retention: ConfigContextRetention;
+    sensitivity: ConfigContextSensitivity;
+    source: ConfigContextSourceClass;
+    type: ConfigContextAttributeType;
+}>;
+export type ConfigContextKindContract = Readonly<{
+    attributes: readonly ConfigContextAttributeContract[];
+    description: string;
+    kind: string;
+    owner: string;
+    required: boolean;
+    unitKey: string;
+}>;
+export type ConfigContextContract = Readonly<{
+    configId: string;
+    contextContractId: string;
+    formatVersion: typeof configDecisioningContractVersion;
+    kinds: readonly ConfigContextKindContract[];
+    projectId: string;
+    revision: number;
+    tenantId: string;
+}>;
+export type ConfigContextScalar = boolean | number | string;
+export type ConfigContextValue = ConfigContextScalar | null | readonly string[];
+export type ConfigEvaluationEntity = Readonly<{
+    attributes: Readonly<Record<string, ConfigContextValue>>;
+    key: string;
+    kind: string;
+}>;
+export type ConfigEvaluationContext = Readonly<{
+    formatVersion: "runbound.config.evaluation-context.v1";
+    kinds: readonly ConfigEvaluationEntity[];
+}>;
+export type ConfigAllocationV1Input = Readonly<{
+    allocationNamespace: string;
+    projectId: string;
+    randomizationContextKind: string;
+    reassignmentEpoch: number;
+    salt: string;
+    tenantId: string;
+    unitKey: string;
+}>;
+export type ConfigAllocationV1Result = Readonly<{
+    bucket: number;
+    digest: `sha256:${string}`;
+    protocolVersion: 1;
+}>;
+export type ConfigDecisionValueSchema = Readonly<{
+    type: "boolean";
+}> | Readonly<{
+    type: "number";
+}> | Readonly<{
+    type: "string";
+}> | Readonly<{
+    type: "enum";
+    values: readonly string[];
+}> | Readonly<{
+    schemaDigest: string;
+    type: "object";
+}>;
+export type ConfigVariation = Readonly<{
+    description: string;
+    variationId: string;
+    value: JsonValue;
+}>;
+export type ConfigPrerequisite = Readonly<{
+    decisionId: string;
+    variationIds: readonly string[];
+}>;
+export type ConfigDecisionReason = "CACHED" | "DEFAULT" | "DISABLED" | "ERROR" | "SPLIT" | "STATIC" | "STALE" | "TARGETING_MATCH";
+export type ConfigDecisionErrorCode = "FLAG_NOT_FOUND" | "GENERAL" | "INVALID_CONTEXT" | "PARSE_ERROR" | "PROVIDER_FATAL" | "PROVIDER_NOT_READY" | "TARGETING_KEY_MISSING" | "TYPE_MISMATCH";
+export type ConfigDecisionFallback = Readonly<{
+    mode: "current";
+}> | Readonly<{
+    mode: "failClosed";
+    variationId: string;
+}> | Readonly<{
+    mode: "lastKnownGood";
+}> | Readonly<{
+    mode: "literal";
+    variationId: string;
+}>;
+export type ConfigDecisionDefinition = Readonly<{
+    decisionId: string;
+    delivery: Readonly<{
+        allowedAudiences: readonly ConfigAudience[];
+        publicRuleApproved: boolean;
+    }>;
+    description: string;
+    disabledVariationId?: string;
+    fallthroughVariationId: string;
+    fallback: ConfigDecisionFallback;
+    openFeaturePrimaryContextKind: string;
+    prerequisites: readonly ConfigPrerequisite[];
+    targets?: readonly ConfigDecisionTarget[];
+    valueSchema: ConfigDecisionValueSchema;
+    variations: readonly ConfigVariation[];
+}>;
+export type ConfigDecisionClause = Readonly<{
+    contextKind: string;
+    expected: ConfigContextValue;
+    operator: ConfigTargetingOperator;
+    path: string;
+}>;
+export type ConfigDecisionTarget = Readonly<{
+    contextKind: string;
+    targetId: string;
+    unitKey: string;
+    variationId: string;
+}>;
+export type ConfigSegmentMembershipExpression = Readonly<{
+    segment: Readonly<{
+        segmentId: string;
+        sourceRevision: string;
+    }>;
+}>;
+export type ConfigDecisionExpression = ConfigDecisionClause | ConfigSegmentMembershipExpression | Readonly<{
+    all: readonly ConfigDecisionExpression[];
+}> | Readonly<{
+    any: readonly ConfigDecisionExpression[];
+}> | Readonly<{
+    not: ConfigDecisionExpression;
+}>;
+export type ConfigAllocationRange = Readonly<{
+    end: number;
+    start: number;
+    variationId?: string;
+}>;
+export type ConfigAllocationReservationClass = "experiment" | "holdout" | "rollout";
+export type ConfigRuleAllocation = Readonly<{
+    allocationNamespace: string;
+    missingRandomizationUnitPolicy: "error" | "fallthrough";
+    ranges: readonly ConfigAllocationRange[];
+    randomizationContextKind: string;
+    reassignmentEpoch: number;
+    reassignmentPolicy: "explicitLedger" | "rebucket" | "stickyExpansion";
+    reservationClass: ConfigAllocationReservationClass;
+    revision: number;
+    salt: string;
+}>;
+export type ConfigDecisionRule = Readonly<{
+    allocation?: ConfigRuleAllocation;
+    condition: ConfigDecisionExpression;
+    ruleId: string;
+    schedule?: Readonly<{
+        endsAt?: string;
+        startsAt?: string;
+    }>;
+    variationId?: string;
+}>;
+export type ConfigDecisionProgram = Readonly<{
+    configId: string;
+    contextContractDigest: string;
+    decisions: readonly ConfigDecisionDefinition[];
+    formatVersion: "runbound.config.decision-program.v1";
+    programRevisionId: string;
+    projectId: string;
+    rules: Readonly<Record<string, readonly ConfigDecisionRule[]>>;
+    segmentRevisionIds: readonly string[];
+    tenantId: string;
+}>;
+export type ConfigDecisionIr = Readonly<{
+    canonicalProgramDigest: string;
+    configId: string;
+    contextContractDigest: string;
+    decisions: readonly ConfigDecisionDefinition[];
+    formatVersion: "runbound.config.decision-ir.v1";
+    projectId: string;
+    rules: Readonly<Record<string, readonly ConfigDecisionRule[]>>;
+    segmentRevisionDigests: readonly string[];
+}>;
+export type ConfigSegment = Readonly<{
+    configId: string;
+    description: string;
+    environmentId: string;
+    projectId: string;
+    segmentId: string;
+    tenantId: string;
+}>;
+export type ConfigSegmentRevision = Readonly<{
+    configId: string;
+    exclude: readonly string[];
+    expiresAt?: string;
+    externalSnapshotDigest?: string;
+    include: readonly string[];
+    projectId: string;
+    revision: number;
+    segmentId: string;
+    sourceRevision: string;
+}>;
+export type ConfigEvaluationDetails = Readonly<{
+    activationSetId: string;
+    allocationNamespace?: string;
+    artifactFreshness?: "current" | "lastKnownGood";
+    artifactDigest: string;
+    bucket?: number;
+    configReleaseId?: string;
+    decisionId: string;
+    errorCode?: ConfigDecisionErrorCode;
+    evaluationMode?: ConfigAudience;
+    exposureToken?: string;
+    fallbackSource?: "current" | "default" | "failClosed" | "lastKnownGood";
+    matchedId?: string;
+    overrideSource?: "assignmentLedger" | "localTest";
+    reason: ConfigDecisionReason;
+    reassignmentEpoch?: number;
+    reservationClass?: ConfigAllocationReservationClass;
+    reservationId?: string;
+    softwareReleaseId?: string;
+    traceDigest: string;
+    variationId?: string;
+}>;
+export type ConfigDecisionResult = Readonly<{
+    details: ConfigEvaluationDetails;
+    value?: JsonValue;
+}>;
+export type ConfigDecisionTraceStep = Readonly<{
+    decisionId: string;
+    outcome: string;
+    step: "allocation" | "context" | "fallthrough" | "override" | "prerequisite" | "reservation" | "rule" | "segment" | "target";
+    subjectId?: string;
+    /**
+     * Which revision of the subject decided. Populated by the `segment` step,
+     * where naming the segment alone is not an explanation: the same segment id
+     * decides differently across revisions, and a reader reconciling a decision
+     * with an audience needs to know which membership answered.
+     */
+    subjectRevision?: number;
+    subjectSourceRevision?: string;
+}>;
+export type ConfigDecisionTrace = Readonly<{
+    formatVersion: "runbound.config.decision-trace.v1";
+    steps: readonly ConfigDecisionTraceStep[];
+    traceDigest: string;
+}>;
+export type ConfigAudience = "edge" | "localPrivate" | "localPublic" | "remote";
+export type ConfigAudienceArtifact = Readonly<{
+    audience: ConfigAudience;
+    canonicalProgramDigest: string;
+    configId: string;
+    contextContractDigest: string;
+    formatVersion: "runbound.config.audience-artifact.v1";
+    ir: ConfigDecisionIr;
+    projectId: string;
+    projectionDigest: string;
+    segmentRevisionDigests: readonly string[];
+}>;
+export type ConfigDecisionArtifactEnvelope = Readonly<{
+    artifactDigest: string;
+    audience: ConfigAudience;
+    envelopeId: string;
+    formatVersion: "runbound.config.decision-artifact-envelope.v1";
+    keyId: string;
+    signature: string;
+    signatureAlgorithm: "ECDSA_SHA_256" | "Ed25519";
+    tenantId: string;
+}>;
+export type ConfigDecisioningActivationSet = Readonly<{
+    activationSetId: string;
+    allocationManifestDigest: string;
+    appId: string;
+    assignmentId: string;
+    audience: ConfigAudience;
+    audienceArtifactDigest: string;
+    baseActivationIds: readonly string[];
+    channel: string;
+    configId: string;
+    consumerRegistrationId: string;
+    contextContractDigest: string;
+    environmentId: string;
+    formatVersion: "runbound.config.targeted-activation-set.v1";
+    keyId: string;
+    projectId: string;
+    sequence: number;
+    signature: string;
+    signatureAlgorithm: "ECDSA_SHA_256" | "Ed25519";
+    softwareReleaseIds: readonly string[];
+    tenantId: string;
+}>;
+export declare function isConfigDecisioningSemanticVersion(value: unknown): value is string;
+export declare function isConfigDecisioningTimestamp(value: unknown): value is string;
+export declare function validateConfigContextContract(value: unknown): asserts value is ConfigContextContract;
+export declare function validateConfigEvaluationContext(contract: ConfigContextContract, value: unknown): asserts value is ConfigEvaluationContext;
+/** Owns one immutable contract and validates each independently owned context. */
+export declare function createConfigEvaluationContextPreparer(contract: ConfigContextContract): Readonly<{
+    contract: ConfigContextContract;
+    prepare: (value: unknown) => Readonly<{
+        context: ConfigEvaluationContext;
+        canonicalBytes: Uint8Array;
+    }>;
+    prepareFromEntities: (kinds: ConfigEvaluationContext["kinds"]) => Readonly<{
+        context: ConfigEvaluationContext;
+        canonicalBytes: Uint8Array;
+    }>;
+}>;
+export declare function validateConfigDecisionClauseAgainstContextContract(contract: ConfigContextContract, clause: ConfigDecisionClause): void;
+export declare function configIpAddressMatchesCidr(addressValue: string, cidrValue: string): boolean;
+/** Implements the sole epoch-bound million-slot allocation protocol. */
+export declare function allocateConfigBucketV1(input: ConfigAllocationV1Input): ConfigAllocationV1Result;