@fireweaveai/server-sdk-cjs 0.0.0-reserve.0

package/dist/application/runtime.js

@@ -0,0 +1,346 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveRuntime = exports.DEFAULT_SHUTDOWN_TIMEOUT_MS = void 0;
+exports.stableStringify = stableStringify;
+/**
+ * FireweaveRuntime: shared engine behind the OpenFeature provider and the
+ * FireweaveClient extensions. Owns lifecycle state machine, config validation,
+ * context policy, and decision construction. Defaults never throw: evaluation
+ * always returns a Decision.
+ */
+const errors_js_1 = require("../domain/errors.js");
+const hosts_js_1 = require("../infrastructure/hosts.js");
+const context_js_1 = require("../domain/context.js");
+const validation_js_1 = require("../domain/validation.js");
+/** Default bound on shutdown/flush (matches capabilities.get()). */
+exports.DEFAULT_SHUTDOWN_TIMEOUT_MS = 10000;
+function validateConfig(config) {
+    if (config.host !== undefined) {
+        // Allowlist is ON by default: undefined/empty
+        // allowedHosts falls back to the canonical Fireweave + loopback list.
+        (0, hosts_js_1.assertHostAllowed)(config.host, config.allowedHosts);
+    }
+    if (config.limits !== undefined) {
+        for (const value of Object.values(config.limits)) {
+            if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+                throw new errors_js_1.FireweaveError('Configuration');
+            }
+        }
+    }
+}
+/** JSON stringify with deterministic (sorted) key order at every level. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+class FireweaveRuntime {
+    adapter;
+    config;
+    contextPolicy;
+    state = 'UNINITIALIZED';
+    globalContext;
+    clientContext;
+    initPromise;
+    stateListeners = new Set();
+    /** Dedup window for evaluate/OF-path exposures (cleared on flush / shutdown). */
+    evaluateExposureSeen = new Set();
+    constructor(adapter, config = {}) {
+        this.adapter = adapter;
+        this.config = { ...config };
+        const limits = { ...context_js_1.DEFAULT_CONTEXT_LIMITS, ...(config.limits ?? {}) };
+        this.contextPolicy = {
+            limits,
+            reservedAttributeKeys: [
+                ...context_js_1.DEFAULT_RESERVED_ATTRIBUTE_KEYS,
+                ...(config.reservedAttributeKeys ?? []),
+            ],
+            requireTargetingKey: config.requireTargetingKey ?? false,
+        };
+    }
+    /** Clear evaluate-path exposure dedup (M-2 / clear-on-flush lifecycle). */
+    clearEvaluateExposureDedup() {
+        this.evaluateExposureSeen.clear();
+    }
+    getState() {
+        return this.state;
+    }
+    onStateChange(listener) {
+        this.stateListeners.add(listener);
+    }
+    setState(next) {
+        this.state = next;
+        for (const listener of this.stateListeners)
+            listener(next);
+    }
+    /** Mark definitions/cache staleness (adapter-driven). */
+    markStale() {
+        if (this.state === 'READY')
+            this.setState('STALE');
+    }
+    setGlobalContext(context) {
+        this.globalContext = context;
+    }
+    setClientContext(context) {
+        this.clientContext = context;
+    }
+    /**
+     * Initialize the runtime: validate config, then bring the adapter up.
+     * Rejects with FireweaveError; Configuration errors put the runtime in FATAL.
+     */
+    async initialize(signal) {
+        if (this.state === 'SHUTDOWN') {
+            throw new errors_js_1.FireweaveError('AlreadyClosed');
+        }
+        if (this.state === 'READY')
+            return;
+        if (this.initPromise !== undefined)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            this.setState('INITIALIZING');
+            try {
+                validateConfig(this.config);
+            }
+            catch (err) {
+                this.setState('FATAL');
+                throw err;
+            }
+            try {
+                await this.adapter.initialize(signal);
+                this.setState('READY');
+            }
+            catch (err) {
+                if ((0, errors_js_1.isFireweaveError)(err) && err.kind === 'Configuration') {
+                    this.setState('FATAL');
+                }
+                else {
+                    this.setState('ERROR');
+                }
+                throw (0, errors_js_1.isFireweaveError)(err) ? err : new errors_js_1.FireweaveError('Internal', { cause: err });
+            }
+            finally {
+                this.initPromise = undefined;
+            }
+        })();
+        return this.initPromise;
+    }
+    async shutdown() {
+        if (this.state === 'SHUTDOWN')
+            return; // idempotent
+        // The configured deadline bounds the whole flush+close sequence (M-1/L-4):
+        // a wedged vendor client must not hang process exit.
+        const timeoutMs = this.config.shutdownTimeoutMs ?? exports.DEFAULT_SHUTDOWN_TIMEOUT_MS;
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        const close = (async () => {
+            try {
+                await this.adapter.flush?.();
+            }
+            catch {
+                // best-effort flush; never throw from shutdown
+            }
+            try {
+                await this.adapter.shutdown();
+            }
+            catch {
+                // swallow: shutdown must not throw
+            }
+        })();
+        try {
+            await Promise.race([close, deadline]);
+        }
+        finally {
+            this.evaluateExposureSeen.clear();
+            if (timer !== undefined)
+                clearTimeout(timer);
+            this.setState('SHUTDOWN');
+        }
+    }
+    /** Canonicalize + validate the merged context (throws FireweaveError). */
+    resolveContext(invocationContext) {
+        const merged = (0, context_js_1.mergeContexts)(this.globalContext, this.clientContext, invocationContext);
+        const result = (0, validation_js_1.validateContext)(merged, this.contextPolicy);
+        if (!result.ok)
+            throw result.error;
+        return result.value;
+    }
+    /**
+     * Evaluate a flag to a canonical Decision. Never throws.
+     *
+     * Validates in the fixed order spec/control-points.md "Validation, before
+     * any I/O" names, stopping at the first failure: (1) key, (2) default vs
+     * type, (3) context, (4) lifecycle. Only once all four pass does this
+     * reach the adapter (the one I/O call in this method).
+     */
+    async evaluate(controlPointKey, expectedType, defaultValue, invocationContext, options = {}) {
+        const keyResult = (0, validation_js_1.validateControlPointKey)(controlPointKey);
+        if (!keyResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, keyResult.error);
+        }
+        const defaultResult = (0, validation_js_1.validateDefaultValue)(expectedType, defaultValue);
+        if (!defaultResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, defaultResult.error);
+        }
+        const merged = (0, context_js_1.mergeContexts)(this.globalContext, this.clientContext, invocationContext);
+        const contextResult = (0, validation_js_1.validateContext)(merged, this.contextPolicy);
+        if (!contextResult.ok) {
+            return this.errorDecision(controlPointKey, defaultValue, contextResult.error);
+        }
+        const context = contextResult.value;
+        const lifecycleError = this.lifecycleError();
+        if (lifecycleError !== undefined) {
+            return this.errorDecision(controlPointKey, defaultValue, lifecycleError);
+        }
+        let resolution;
+        try {
+            const resolveOpts = options.signal !== undefined ? { signal: options.signal } : {};
+            resolution = await this.adapter.resolve(controlPointKey, context, resolveOpts);
+        }
+        catch (err) {
+            // H-2: non-Fireweave (vendor/internal) exception text never reaches the
+            // outward errorMessage — the fixed taxonomy message is used and the
+            // original error is preserved on `cause` only.
+            const fw = (0, errors_js_1.isFireweaveError)(err) ? err : new errors_js_1.FireweaveError('Internal', { cause: err });
+            return this.errorDecision(controlPointKey, defaultValue, fw);
+        }
+        if (!resolution.found) {
+            // spec/modes.md "Behaviour per mode": local's unknown-key row is
+            // `default` / `reason: DEFAULT` — deliberately not an error, unlike
+            // remote's `default` / `ERROR` / `ControlPointNotFound`. An adapter signals the
+            // former by carrying `reason: 'DEFAULT'` on its miss (FireweaveLocalAdapter);
+            // any adapter that leaves `reason` unset (InMemoryAdapter,
+            // FireweaveRemoteAdapter) keeps the ControlPointNotFound/ERROR path below.
+            if (resolution.reason === 'DEFAULT') {
+                return { controlPointKey, value: defaultValue, reason: 'DEFAULT', metadata: {} };
+            }
+            const meta = {};
+            if (resolution.quotaLimited === true)
+                meta['fireweave.quotaLimited'] = true;
+            return this.errorDecision(controlPointKey, defaultValue, new errors_js_1.FireweaveError('ControlPointNotFound', { metadata: meta }));
+        }
+        const value = resolution.value ?? null;
+        if (!(0, validation_js_1.matchesExpectedType)(value, expectedType)) {
+            return this.errorDecision(controlPointKey, defaultValue, new errors_js_1.FireweaveError('TypeMismatch'));
+        }
+        const metadata = {};
+        if (resolution.version !== undefined)
+            metadata['fireweave.controlPointVersion'] = resolution.version;
+        // Detailed vendor fields travel together: they surface only when the
+        // backend reported BOTH a vendor flag id and a matched condition index
+        // (fixtures: eval-detailed-fields exposes them; eval-multivariate-string
+        // [index, no id] and eval-payload-attached [id, no index] do not).
+        if (resolution.vendorControlPointId !== undefined && resolution.conditionIndex !== undefined) {
+            metadata['fireweave.vendorControlPointId'] = resolution.vendorControlPointId;
+            if (resolution.reasonCode !== undefined)
+                metadata['fireweave.reasonCode'] = resolution.reasonCode;
+        }
+        if (options.includePayload === true && resolution.payload !== undefined) {
+            metadata['fireweave.payload'] =
+                typeof resolution.payload === 'string' ? resolution.payload : stableStringify(resolution.payload);
+        }
+        if (resolution.quotaLimited === true)
+            metadata['fireweave.quotaLimited'] = true;
+        if (resolution.fromCache === true)
+            metadata['fireweave.fromCache'] = true;
+        let reason;
+        if (resolution.enabled === false) {
+            reason = 'DISABLED';
+        }
+        else if (resolution.reason !== undefined) {
+            reason = resolution.reason;
+        }
+        else if (resolution.fromCache === true || this.state === 'STALE') {
+            reason = 'STALE';
+        }
+        else {
+            reason = 'TARGETING_MATCH';
+        }
+        const decision = { controlPointKey, value, reason, metadata };
+        if (resolution.variant !== undefined)
+            decision.variant = resolution.variant;
+        // H-4 / ruling 20: evaluate is side-effect-free by default; opt in via sendExposure: true.
+        if (options.sendExposure === true) {
+            this.emitEvaluateExposure({
+                targetingKey: context.targetingKey ?? '',
+                controlPointKey,
+                value,
+                ...(resolution.variant !== undefined ? { variant: resolution.variant } : {}),
+            });
+        }
+        return decision;
+    }
+    /**
+     * Register a user or device so flag rules can target its DURABLE properties.
+     *
+     * Call once per login / device provisioning with the facts that outlive a
+     * request (plan, beta membership, region, device model), then send the same
+     * `targetingKey` on evaluation. Per-request context attributes still override
+     * the registered properties for a single evaluation — the two identity paths
+     * compose (spec/remote-protocol.md § Two identity paths).
+     *
+     * Resolves with `ok: false` instead of throwing: this runs in sign-in paths.
+     * Adapters without the capability (in-memory, local dev) report
+     * `Unsupported` so a dev harness does not silently look registered.
+     */
+    async registerTarget(targetingKey, options = {}) {
+        const lifecycle = this.lifecycleError();
+        if (lifecycle !== undefined)
+            return { ok: false, error: lifecycle };
+        if (this.adapter.registerTarget === undefined) {
+            return { ok: false, error: new errors_js_1.FireweaveError('UnsupportedCapability') };
+        }
+        return this.adapter.registerTarget(targetingKey, options);
+    }
+    emitEvaluateExposure(exposure) {
+        if (exposure.targetingKey.length === 0)
+            return;
+        if (this.adapter.recordExposure === undefined)
+            return;
+        const key = `${exposure.targetingKey}\u0000${exposure.controlPointKey}\u0000${exposure.variant ?? ''}\u0000${stableStringify(exposure.value ?? null)}`;
+        if (this.evaluateExposureSeen.has(key))
+            return;
+        this.evaluateExposureSeen.add(key);
+        this.adapter.recordExposure({
+            targetingKey: exposure.targetingKey,
+            controlPointKey: exposure.controlPointKey,
+            value: exposure.value,
+            ...(exposure.variant !== undefined ? { variant: exposure.variant } : {}),
+        });
+    }
+    lifecycleError() {
+        switch (this.state) {
+            case 'UNINITIALIZED':
+            case 'INITIALIZING':
+                return new errors_js_1.FireweaveError('NotReady');
+            case 'ERROR':
+                return new errors_js_1.FireweaveError('NotReady');
+            case 'FATAL':
+                return new errors_js_1.FireweaveError('Configuration');
+            case 'SHUTDOWN':
+                return new errors_js_1.FireweaveError('AlreadyClosed');
+            default:
+                return undefined;
+        }
+    }
+    errorDecision(controlPointKey, defaultValue, err) {
+        const metadata = {
+            'fireweave.errorKind': err.kind,
+            ...err.metadata,
+        };
+        return {
+            controlPointKey,
+            value: defaultValue,
+            reason: 'ERROR',
+            errorCode: err.openFeatureErrorCode,
+            errorKind: err.kind,
+            errorMessage: err.message,
+            metadata,
+        };
+    }
+}
+exports.FireweaveRuntime = FireweaveRuntime;

package/dist/domain/context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Evaluation-context handling: merge order (global → client → invocation)
+ * and normalization of raw caller input into the shape validation.ts checks,
+ * plus the post-canonicalization reporting view.
+ * Bounds per spec/evaluation-context.schema.json (ratified 2026-07-27):
+ * 128 attrs / 256 B keys / 4 KiB values / depth 6 / 64 KiB serialized.
+ *
+ * Bound/reserved-key ENFORCEMENT (the pure, Validated<T>-returning checks)
+ * lives in validation.ts (`validateContext`) — spec/control-points.md
+ * "Validation, before any I/O" rule 3. This module has no throwing/failing
+ * surface of its own.
+ */
+import type { CanonicalContext, JsonValue } from './types.js';
+export interface ContextLimits {
+    maxAttributeCount: number;
+    maxKeyBytes: number;
+    maxValueBytes: number;
+    maxNestingDepth: number;
+    maxSerializedContextBytes: number;
+}
+export declare const DEFAULT_CONTEXT_LIMITS: Readonly<ContextLimits>;
+/** Attribute keys callers may never set (in addition to the fireweave.* namespace). */
+export declare const DEFAULT_RESERVED_ATTRIBUTE_KEYS: readonly string[];
+/**
+ * Sanctioned fireweave.* carriers (orchestrator rulings 12–14): the ONLY
+ * `fireweave.*` context keys callers may set. They are the canonical spelling
+ * for group memberships / group properties; plain `groups`/`groupProperties`
+ * remain accepted as a documented alias.
+ */
+export declare const ALLOWED_FIREWEAVE_CONTEXT_KEYS: readonly string[];
+export interface ContextPolicy {
+    limits: ContextLimits;
+    reservedAttributeKeys: readonly string[];
+    requireTargetingKey: boolean;
+}
+/** Loose input shape accepted from callers (OpenFeature EvaluationContext-compatible). */
+export interface ContextInput {
+    targetingKey?: string;
+    attributes?: Record<string, unknown>;
+    /** OpenFeature flat contexts: extra top-level keys are treated as attributes. */
+    [key: string]: unknown;
+}
+/**
+ * Extract {targetingKey, attributes} from a caller context. Supports both the
+ * canonical shape ({targetingKey, attributes:{...}}) and OpenFeature flat shape
+ * ({targetingKey, plan:"pro", ...}).
+ */
+export declare function normalizeContextInput(input: ContextInput | undefined): {
+    targetingKey?: string;
+    attributes: Record<string, unknown>;
+};
+/**
+ * Merge context layers with later layers winning at the attribute-key level.
+ * Layers are raw inputs; output is a deep copy (caller objects never retained).
+ */
+export declare function mergeContexts(...layers: Array<ContextInput | undefined>): {
+    targetingKey?: string;
+    attributes: Record<string, unknown>;
+};
+/**
+ * Resolved context for reporting/telemetry: `$`-prefixed system directives are
+ * filtered out; empty attributes omitted.
+ */
+export declare function resolvedContextView(ctx: CanonicalContext): {
+    targetingKey?: string;
+    attributes?: Record<string, JsonValue>;
+};

package/dist/domain/context.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_FIREWEAVE_CONTEXT_KEYS = exports.DEFAULT_RESERVED_ATTRIBUTE_KEYS = exports.DEFAULT_CONTEXT_LIMITS = void 0;
+exports.normalizeContextInput = normalizeContextInput;
+exports.mergeContexts = mergeContexts;
+exports.resolvedContextView = resolvedContextView;
+exports.DEFAULT_CONTEXT_LIMITS = Object.freeze({
+    maxAttributeCount: 128,
+    maxKeyBytes: 256,
+    maxValueBytes: 4096,
+    maxNestingDepth: 6,
+    maxSerializedContextBytes: 65536,
+});
+/** Attribute keys callers may never set (in addition to the fireweave.* namespace). */
+exports.DEFAULT_RESERVED_ATTRIBUTE_KEYS = Object.freeze([
+    'targetingKey',
+    'kind',
+]);
+/**
+ * Sanctioned fireweave.* carriers (orchestrator rulings 12–14): the ONLY
+ * `fireweave.*` context keys callers may set. They are the canonical spelling
+ * for group memberships / group properties; plain `groups`/`groupProperties`
+ * remain accepted as a documented alias.
+ */
+exports.ALLOWED_FIREWEAVE_CONTEXT_KEYS = Object.freeze([
+    'fireweave.groups',
+    'fireweave.groupProperties',
+]);
+/**
+ * Extract {targetingKey, attributes} from a caller context. Supports both the
+ * canonical shape ({targetingKey, attributes:{...}}) and OpenFeature flat shape
+ * ({targetingKey, plan:"pro", ...}).
+ */
+function normalizeContextInput(input) {
+    if (input === undefined || input === null)
+        return { attributes: {} };
+    const attributes = {};
+    let targetingKey;
+    if (typeof input.targetingKey === 'string' && input.targetingKey.length > 0) {
+        targetingKey = input.targetingKey;
+    }
+    if (input.attributes !== undefined && typeof input.attributes === 'object' && input.attributes !== null && !Array.isArray(input.attributes)) {
+        for (const [k, v] of Object.entries(input.attributes)) {
+            if (v !== undefined)
+                attributes[k] = v;
+        }
+    }
+    for (const [k, v] of Object.entries(input)) {
+        if (k === 'targetingKey' || k === 'attributes')
+            continue;
+        if (v !== undefined)
+            attributes[k] = v;
+    }
+    return targetingKey !== undefined ? { targetingKey, attributes } : { attributes };
+}
+/**
+ * Merge context layers with later layers winning at the attribute-key level.
+ * Layers are raw inputs; output is a deep copy (caller objects never retained).
+ */
+function mergeContexts(...layers) {
+    let targetingKey;
+    const attributes = {};
+    for (const layer of layers) {
+        const { targetingKey: tk, attributes: attrs } = normalizeContextInput(layer);
+        if (tk !== undefined)
+            targetingKey = tk;
+        for (const [k, v] of Object.entries(attrs)) {
+            attributes[k] = v;
+        }
+    }
+    return targetingKey !== undefined ? { targetingKey, attributes } : { attributes };
+}
+/**
+ * Resolved context for reporting/telemetry: `$`-prefixed system directives are
+ * filtered out; empty attributes omitted.
+ */
+function resolvedContextView(ctx) {
+    const attributes = {};
+    for (const [k, v] of Object.entries(ctx.attributes)) {
+        if (k.startsWith('$'))
+            continue;
+        attributes[k] = v;
+    }
+    const out = {};
+    if (ctx.targetingKey !== undefined)
+        out.targetingKey = ctx.targetingKey;
+    if (Object.keys(attributes).length > 0)
+        out.attributes = attributes;
+    return out;
+}

package/dist/domain/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Fireweave canonical error taxonomy (spec/errors.schema.json, contracts/errors.json).
+ *
+ * 15 PascalCase kinds mapped to OpenFeature error codes. Rules:
+ *  - defaults never throw: evaluation paths surface errors via Decision, not exceptions;
+ *  - no secrets in messages: all outward-facing messages are redacted;
+ *  - cause preserved internally (`FireweaveError.cause`), never serialized outward.
+ */
+export type FireweaveErrorKind = 'NotReady' | 'ControlPointNotFound' | 'TypeMismatch' | 'InvalidContext' | 'Authentication' | 'Authorization' | 'RateLimited' | 'Timeout' | 'Network' | 'BackendUnavailable' | 'MalformedResponse' | 'UnsupportedCapability' | 'Configuration' | 'AlreadyClosed' | 'Internal';
+/** OpenFeature error code strings (mirrors @openfeature/core ErrorCode values). */
+export type OpenFeatureErrorCode = 'PROVIDER_NOT_READY' | 'PROVIDER_FATAL' | 'FLAG_NOT_FOUND' | 'PARSE_ERROR' | 'TYPE_MISMATCH' | 'TARGETING_KEY_MISSING' | 'INVALID_CONTEXT' | 'GENERAL';
+export interface ErrorKindSpec {
+    readonly kind: FireweaveErrorKind;
+    readonly openFeatureErrorCode: OpenFeatureErrorCode;
+    readonly retryable: boolean;
+    readonly errorClass: 'transient' | 'permanent';
+    readonly defaultMessage: string;
+}
+export declare const ERROR_TAXONOMY: Readonly<Record<FireweaveErrorKind, ErrorKindSpec>>;
+/**
+ * Scrub secrets per the redaction contract, then collapse whitespace runs and
+ * trim (so a message stays on one log line).
+ */
+export declare function redactSecrets(text: string): string;
+export interface FireweaveErrorOptions {
+    /** Custom message; will be redacted. Defaults to the taxonomy default message. */
+    message?: string;
+    /** Underlying cause, preserved internally only. */
+    cause?: unknown;
+    /** Override the OF code (e.g. TARGETING_KEY_MISSING for InvalidContext). */
+    openFeatureErrorCode?: OpenFeatureErrorCode;
+    /** Extra fireweave.* flag metadata to surface with error decisions. */
+    metadata?: Record<string, string | number | boolean>;
+}
+export declare class FireweaveError extends Error {
+    readonly kind: FireweaveErrorKind;
+    readonly openFeatureErrorCode: OpenFeatureErrorCode;
+    readonly retryable: boolean;
+    readonly errorClass: 'transient' | 'permanent';
+    /** Deterministic outward-facing message from the taxonomy. */
+    readonly safeMessage: string;
+    readonly metadata: Readonly<Record<string, string | number | boolean>>;
+    constructor(kind: FireweaveErrorKind, options?: FireweaveErrorOptions);
+}
+export declare function isFireweaveError(err: unknown): err is FireweaveError;

package/dist/domain/errors.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Fireweave canonical error taxonomy (spec/errors.schema.json, contracts/errors.json).
+ *
+ * 15 PascalCase kinds mapped to OpenFeature error codes. Rules:
+ *  - defaults never throw: evaluation paths surface errors via Decision, not exceptions;
+ *  - no secrets in messages: all outward-facing messages are redacted;
+ *  - cause preserved internally (`FireweaveError.cause`), never serialized outward.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveError = exports.ERROR_TAXONOMY = void 0;
+exports.redactSecrets = redactSecrets;
+exports.isFireweaveError = isFireweaveError;
+const spec = (kind, openFeatureErrorCode, retryable, errorClass, defaultMessage) => ({ kind, openFeatureErrorCode, retryable, errorClass, defaultMessage });
+exports.ERROR_TAXONOMY = Object.freeze({
+    NotReady: spec('NotReady', 'PROVIDER_NOT_READY', true, 'transient', 'provider not ready'),
+    ControlPointNotFound: spec('ControlPointNotFound', 'FLAG_NOT_FOUND', false, 'permanent', 'flag not found'),
+    TypeMismatch: spec('TypeMismatch', 'TYPE_MISMATCH', false, 'permanent', 'flag type mismatch'),
+    InvalidContext: spec('InvalidContext', 'INVALID_CONTEXT', false, 'permanent', 'invalid evaluation context'),
+    Authentication: spec('Authentication', 'GENERAL', false, 'permanent', 'authentication failed'),
+    Authorization: spec('Authorization', 'GENERAL', false, 'permanent', 'authorization failed'),
+    RateLimited: spec('RateLimited', 'GENERAL', true, 'transient', 'rate limited'),
+    Timeout: spec('Timeout', 'GENERAL', true, 'transient', 'request timed out'),
+    Network: spec('Network', 'GENERAL', true, 'transient', 'network error'),
+    BackendUnavailable: spec('BackendUnavailable', 'GENERAL', true, 'transient', 'backend unavailable'),
+    MalformedResponse: spec('MalformedResponse', 'PARSE_ERROR', false, 'permanent', 'malformed backend response'),
+    UnsupportedCapability: spec('UnsupportedCapability', 'GENERAL', false, 'permanent', 'unsupported capability'),
+    Configuration: spec('Configuration', 'PROVIDER_FATAL', false, 'permanent', 'invalid configuration'),
+    AlreadyClosed: spec('AlreadyClosed', 'PROVIDER_NOT_READY', false, 'permanent', 'provider already closed'),
+    Internal: spec('Internal', 'GENERAL', false, 'permanent', 'internal error'),
+});
+/**
+ * The redaction contract (contracts/errors.json `rules.redaction`, start-profile
+ * SP-26). Applied in this order: bearer tokens, URL userinfo, named
+ * assignments, then key-shaped values. A variable NAME is never redacted on its
+ * own; only its value is. `test/unit/redaction-contract.test.ts` runs every
+ * contract vector through `redactSecrets`.
+ */
+const REDACTION_PLACEHOLDER = '[REDACTED]';
+/** Variables whose assigned value is scrubbed: `NAME=value`, `NAME: value`, `NAME = "value"`. */
+const ASSIGNMENT_NAMES = ['FIREWEAVE_KEY', 'FIREWEAVE_BROWSER_KEY', 'FW_PROJECT_API_KEY'];
+/** Key families; a prefix only counts when one or more of [A-Za-z0-9_-] follows it. */
+const VALUE_PREFIXES = [
+    'project-api-key_',
+    'fw_public_',
+    'fw_ingest_pub_',
+    'fw_org_',
+    'cli_at_',
+    'phc_',
+    'phx_',
+    'phs_',
+];
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const BEARER = /\bBearer(\s+)[A-Za-z0-9._~+/=-]+/g;
+// scheme://userinfo@host: userinfo cannot hold whitespace, '/', '?', '#' or '@'.
+const URL_USERINFO = /\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s/?#@]+@/g;
+// The name stays, as do the separator and any opening quote; the value runs to
+// whitespace, a quote, a comma or a semicolon. The lookbehind keeps a longer
+// name that merely ends in one of these (MY_FIREWEAVE_KEY) out of scope.
+const ASSIGNMENT = new RegExp(`(?<![A-Za-z0-9_])(${ASSIGNMENT_NAMES.map(escapeRegExp).join('|')})(\\s*[=:]\\s*)(["']?)[^\\s"',;]+`, 'g');
+// No leading boundary: a key glued to other text is still a key.
+const KEY_VALUE = new RegExp(`(?:${VALUE_PREFIXES.map(escapeRegExp).join('|')})[A-Za-z0-9_-]+`, 'g');
+/**
+ * Scrub secrets per the redaction contract, then collapse whitespace runs and
+ * trim (so a message stays on one log line).
+ */
+function redactSecrets(text) {
+    const out = text
+        .replace(BEARER, `Bearer$1${REDACTION_PLACEHOLDER}`)
+        .replace(URL_USERINFO, `$1${REDACTION_PLACEHOLDER}@`)
+        .replace(ASSIGNMENT, `$1$2$3${REDACTION_PLACEHOLDER}`)
+        .replace(KEY_VALUE, REDACTION_PLACEHOLDER);
+    return out.replace(/\s+/g, ' ').trim();
+}
+class FireweaveError extends Error {
+    kind;
+    openFeatureErrorCode;
+    retryable;
+    errorClass;
+    /** Deterministic outward-facing message from the taxonomy. */
+    safeMessage;
+    metadata;
+    constructor(kind, options = {}) {
+        const taxonomy = exports.ERROR_TAXONOMY[kind];
+        const message = options.message !== undefined ? redactSecrets(options.message) : taxonomy.defaultMessage;
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'FireweaveError';
+        this.kind = kind;
+        this.openFeatureErrorCode = options.openFeatureErrorCode ?? taxonomy.openFeatureErrorCode;
+        this.retryable = taxonomy.retryable;
+        this.errorClass = taxonomy.errorClass;
+        this.safeMessage = taxonomy.defaultMessage;
+        this.metadata = Object.freeze({ ...(options.metadata ?? {}) });
+    }
+}
+exports.FireweaveError = FireweaveError;
+function isFireweaveError(err) {
+    return err instanceof FireweaveError;
+}

package/dist/domain/target.d.ts

@@ -0,0 +1,2 @@
+/** What is being registered — see spec/remote-register-target.schema.json. */
+export type TargetKind = 'user' | 'device';

package/dist/domain/target.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });