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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fireweave AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+> **This is the CommonJS build of [`@fireweaveai/server-sdk`](https://www.npmjs.com/package/@fireweaveai/server-sdk).**
+> Use it only when your project cannot load ES modules (see
+> [Module formats](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/module-formats.md)).
+> Same code, same version, same import paths. ES modules are the long-term format;
+> this package will be retired in a future major release.
+
+<a href="https://app.fireweave.ai">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FireWeave-HQ/fireweave-sdk/main/.github/assets/banner-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/FireWeave-HQ/fireweave-sdk/main/.github/assets/banner-light.png">
+    <img alt="Fireweave — agents write the code. We watch every rollout, under control." src="https://raw.githubusercontent.com/FireWeave-HQ/fireweave-sdk/main/.github/assets/banner-light.png" width="100%">
+  </picture>
+</a>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fireweaveai/server-sdk"><img alt="node" src="https://img.shields.io/npm/v/@fireweaveai/server-sdk?label=node&logo=nodedotjs&style=flat&labelColor=0E0E10&color=ED5502&logoColor=white"></a>
+</p>
+
+**Fireweave is the AI release engineer for teams shipping with coding agents.** Every change rolls out behind a control point, one step at a time, with guardrails watching real users — and if something breaks, Fireweave pauses or rolls it back before most users ever see it. It's the only way to ship as fast as your agents write code, without the fear of breaking production.
+
+## Quick start · Node.js · Bun · Deno
+
+```bash
+npm install @fireweaveai/server-sdk
+# bun add @fireweaveai/server-sdk  ·  deno add npm:@fireweaveai/server-sdk
+```
+
+```ts
+import { initFireweave } from '@fireweaveai/server-sdk';
+
+const fireweave = await initFireweave({
+  mode: 'remote',
+  apiUrl: process.env.FW_API_URL!,
+  apiKey: process.env.FW_PROJECT_API_KEY!,
+});
+
+// Once per user: the facts your targeting rules match on.
+await fireweave.registerTarget('user_42', { kind: 'user', properties: { plan: 'pro' } });
+
+// Per request: evaluate a control point.
+const enabled = await fireweave.controlPoints.getBooleanValue('new-checkout', false, {
+  targetingKey: 'user_42',
+});
+console.log('new-checkout:', enabled);
+
+await fireweave.shutdown();
+```
+
+## Learn more
+
+[Concepts](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/concepts.md) · [Identity](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/identity.md) · [Testing](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/testing.md) · [Troubleshooting](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/troubleshooting.md) · [Module formats (CommonJS)](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/docs/module-formats.md) · [All SDKs](https://github.com/FireWeave-HQ/fireweave-sdk#quick-start)
+
+## License
+
+[MIT](https://github.com/FireWeave-HQ/fireweave-sdk/blob/main/LICENSE)

package/dist/application/client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * FireweaveClient — control-point evaluation and target registration
+ * (spec/control-points.md): the only two v1 capabilities. Facade methods
+ * degrade instead of throwing.
+ */
+import { type FireweaveErrorKind } from '../domain/errors.js';
+import type { EvaluateOptions, ExpectedFlagType, FireweaveRuntime } from './runtime.js';
+import type { ContextInput } from '../domain/context.js';
+import type { RegisterTargetOptions, RegisterTargetResult } from './ports.js';
+import type { Decision, JsonValue } from '../domain/types.js';
+export interface ExtensionResult {
+    ok: boolean;
+    errorKind?: FireweaveErrorKind;
+    errorCode?: string;
+    errorMessage?: string;
+    degraded?: boolean;
+}
+/**
+ * Control-point evaluation on the public client surface (ruling 16):
+ * Decision-returning evaluation without reaching into the runtime. Never throws
+ * — errors surface as ERROR decisions, exactly like the OpenFeature path.
+ *
+ * "Control point" is the Fireweave product noun (ADR-0007), on the wire too
+ * (ADR-0013).
+ */
+export declare class ControlPointsApi {
+    private readonly runtime;
+    constructor(runtime: FireweaveRuntime);
+    /** Evaluate a flag to a canonical Decision (detailed evaluation). */
+    evaluate(controlPointKey: string, expectedType: ExpectedFlagType, defaultValue: JsonValue, context?: ContextInput, options?: EvaluateOptions): Promise<Decision>;
+    getBooleanValue(controlPointKey: string, defaultValue: boolean, context?: ContextInput): Promise<boolean>;
+    getStringValue(controlPointKey: string, defaultValue: string, context?: ContextInput): Promise<string>;
+    getNumberValue(controlPointKey: string, defaultValue: number, context?: ContextInput): Promise<number>;
+    getObjectValue(controlPointKey: string, defaultValue: JsonValue, context?: ContextInput): Promise<JsonValue>;
+    /**
+     * Detailed reads — the whole {@link Decision} rather than just its value.
+     *
+     * Same arguments as the `*Value` pair above, so a caller upgrades from one to
+     * the other without restructuring the call. Required by
+     * `spec/control-points.md`; before ADR-0010 the only route to `reason`,
+     * `variant` or `error` was the OpenFeature provider's `resolve*Evaluation`,
+     * so detailed evaluation was unreachable without installing OpenFeature.
+     */
+    getBooleanDetails(controlPointKey: string, defaultValue: boolean, context?: ContextInput): Promise<Decision>;
+    getStringDetails(controlPointKey: string, defaultValue: string, context?: ContextInput): Promise<Decision>;
+    getNumberDetails(controlPointKey: string, defaultValue: number, context?: ContextInput): Promise<Decision>;
+    getObjectDetails(controlPointKey: string, defaultValue: JsonValue, context?: ContextInput): Promise<Decision>;
+}
+export interface FireweaveClientOptions {
+}
+export declare class FireweaveClient {
+    readonly runtime: FireweaveRuntime;
+    readonly controlPoints: ControlPointsApi;
+    constructor(runtime: FireweaveRuntime, _options?: FireweaveClientOptions);
+    /**
+     * Register durable targeting facts for a target (spec/modes.md).
+     *
+     * Resolves `{ ok: false }` rather than throwing: this runs in sign-in paths,
+     * where a targeting concern must not break authentication. A careful caller
+     * logs a false — a silently unregistered target is how targeting rules end
+     * up matching nobody.
+     *
+     * In local mode this records in-process and traces the call; nothing reaches
+     * fw-server. See `FireweaveLocalAdapter.registerTarget`.
+     */
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    /**
+     * Dynamic capability dispatch. Unknown capabilities — currently all of
+     * them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
+     * UnsupportedCapability, never throw (fixture
+     * ext-unsupported-capability-degrade). Any future capability listed in
+     * SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
+     */
+    invokeCapability(capability: string, _args?: Record<string, JsonValue>): ExtensionResult;
+    initialize(signal?: AbortSignal): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/application/client.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveClient = exports.ControlPointsApi = void 0;
+/**
+ * FireweaveClient — control-point evaluation and target registration
+ * (spec/control-points.md): the only two v1 capabilities. Facade methods
+ * degrade instead of throwing.
+ */
+const errors_js_1 = require("../domain/errors.js");
+const failure = (err, degraded = false) => ({
+    ok: false,
+    errorKind: err.kind,
+    errorCode: err.openFeatureErrorCode,
+    errorMessage: err.message,
+    ...(degraded ? { degraded: true } : {}),
+});
+/**
+ * Lifecycle gate for extension calls (ruling 17, Go/Java model; fixture
+ * ext-lifecycle-gating): READY/STALE proceed; post-shutdown degrades
+ * AlreadyClosed; pre-ready degrades UnsupportedCapability. Gated methods never
+ * throw — failures come back as structured, degraded results.
+ */
+const lifecycleGate = (runtime) => {
+    switch (runtime.getState()) {
+        case 'READY':
+        case 'STALE':
+            return undefined;
+        case 'SHUTDOWN':
+            return new errors_js_1.FireweaveError('AlreadyClosed');
+        default:
+            return new errors_js_1.FireweaveError('UnsupportedCapability');
+    }
+};
+/**
+ * Control-point evaluation on the public client surface (ruling 16):
+ * Decision-returning evaluation without reaching into the runtime. Never throws
+ * — errors surface as ERROR decisions, exactly like the OpenFeature path.
+ *
+ * "Control point" is the Fireweave product noun (ADR-0007), on the wire too
+ * (ADR-0013).
+ */
+class ControlPointsApi {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    /** Evaluate a flag to a canonical Decision (detailed evaluation). */
+    evaluate(controlPointKey, expectedType, defaultValue, context, options) {
+        return this.runtime.evaluate(controlPointKey, expectedType, defaultValue, context, options ?? {});
+    }
+    async getBooleanValue(controlPointKey, defaultValue, context) {
+        const decision = await this.evaluate(controlPointKey, 'boolean', defaultValue, context);
+        return decision.value;
+    }
+    async getStringValue(controlPointKey, defaultValue, context) {
+        const decision = await this.evaluate(controlPointKey, 'string', defaultValue, context);
+        return decision.value;
+    }
+    async getNumberValue(controlPointKey, defaultValue, context) {
+        const decision = await this.evaluate(controlPointKey, 'number', defaultValue, context);
+        return decision.value;
+    }
+    async getObjectValue(controlPointKey, defaultValue, context) {
+        const decision = await this.evaluate(controlPointKey, 'object', defaultValue, context);
+        return decision.value;
+    }
+    /**
+     * Detailed reads — the whole {@link Decision} rather than just its value.
+     *
+     * Same arguments as the `*Value` pair above, so a caller upgrades from one to
+     * the other without restructuring the call. Required by
+     * `spec/control-points.md`; before ADR-0010 the only route to `reason`,
+     * `variant` or `error` was the OpenFeature provider's `resolve*Evaluation`,
+     * so detailed evaluation was unreachable without installing OpenFeature.
+     */
+    getBooleanDetails(controlPointKey, defaultValue, context) {
+        return this.evaluate(controlPointKey, 'boolean', defaultValue, context);
+    }
+    getStringDetails(controlPointKey, defaultValue, context) {
+        return this.evaluate(controlPointKey, 'string', defaultValue, context);
+    }
+    getNumberDetails(controlPointKey, defaultValue, context) {
+        return this.evaluate(controlPointKey, 'number', defaultValue, context);
+    }
+    getObjectDetails(controlPointKey, defaultValue, context) {
+        return this.evaluate(controlPointKey, 'object', defaultValue, context);
+    }
+}
+exports.ControlPointsApi = ControlPointsApi;
+/**
+ * Names invokeCapability will dispatch instead of degrading with
+ * UnsupportedCapability. Empty in v1: releases, exposures, signals,
+ * capabilities discovery, and guardrails are all out of scope
+ * (spec/control-points.md) and MUST NOT be exposed, so a cut namespace's
+ * capability string resolves exactly like any other unknown string.
+ */
+const SUPPORTED_CAPABILITIES = Object.freeze([]);
+class FireweaveClient {
+    runtime;
+    controlPoints;
+    constructor(runtime, _options = {}) {
+        this.runtime = runtime;
+        this.controlPoints = new ControlPointsApi(runtime);
+    }
+    /**
+     * Register durable targeting facts for a target (spec/modes.md).
+     *
+     * Resolves `{ ok: false }` rather than throwing: this runs in sign-in paths,
+     * where a targeting concern must not break authentication. A careful caller
+     * logs a false — a silently unregistered target is how targeting rules end
+     * up matching nobody.
+     *
+     * In local mode this records in-process and traces the call; nothing reaches
+     * fw-server. See `FireweaveLocalAdapter.registerTarget`.
+     */
+    registerTarget(targetingKey, options = {}) {
+        return this.runtime.registerTarget(targetingKey, options);
+    }
+    /**
+     * Dynamic capability dispatch. Unknown capabilities — currently all of
+     * them, v1's SUPPORTED_CAPABILITIES is empty — degrade with
+     * UnsupportedCapability, never throw (fixture
+     * ext-unsupported-capability-degrade). Any future capability listed in
+     * SUPPORTED_CAPABILITIES is lifecycle-gated the same way (ruling 17).
+     */
+    invokeCapability(capability, _args) {
+        if (!SUPPORTED_CAPABILITIES.includes(capability)) {
+            return failure(new errors_js_1.FireweaveError('UnsupportedCapability'), true);
+        }
+        if (capability !== 'capabilities.get') {
+            const gateError = lifecycleGate(this.runtime);
+            if (gateError !== undefined)
+                return failure(gateError, true);
+        }
+        return { ok: true };
+    }
+    async initialize(signal) {
+        await this.runtime.initialize(signal);
+    }
+    async shutdown() {
+        await this.runtime.shutdown();
+    }
+}
+exports.FireweaveClient = FireweaveClient;

package/dist/application/mode.d.ts

@@ -0,0 +1,70 @@
+/**
+ * initFireweave — the single SDK entry point (spec/modes.md).
+ *
+ * `mode` is required and never inferred: a missing or mistyped credential
+ * must fail loudly at boot, not silently fall back to local evaluation —
+ * that failure mode looks like a green boot and a feature that never ramps.
+ * This function's only job is to validate the initialisation-time contract
+ * and select the matching adapter; nothing downstream branches on mode again
+ * (spec/modes.md "Behaviour per mode" — both adapters implement the same
+ * BackendAdapter port, so FireweaveClient / FireweaveRuntime stay mode-blind).
+ *
+ * Initialisation fails loudly (throws); reads on the returned client never do
+ * (spec/control-points.md "initialise is the exception"). The validation
+ * itself lives in `validateInitOptions` (validation.ts), which returns
+ * `Validated<T>` like every other validator — this function is what converts
+ * a failed `Validated` into the throw spec/modes.md requires.
+ */
+import { FireweaveClient } from './client.js';
+import type { FireweaveRemoteAdapterOptions } from '../infrastructure/adapters/remote.js';
+export interface InitFireweaveRemoteOptions {
+    /** Evaluate against fw-server over the network (spec/remote-protocol.md). */
+    readonly mode: 'remote';
+    /** Fireweave project/runtime key (project-api-key_…). Required — never read from env. */
+    readonly apiKey: string;
+    /** fw-server base URL. Required — never read from env. */
+    readonly apiUrl: string;
+    /**
+     * SSRF allowlist override (spec/modes.md "apiUrl fails the host allowlist").
+     * Default: the canonical Fireweave hosts + loopback (`DEFAULT_ALLOWED_HOSTS`).
+     * A self-hosted fw-server must list its own host explicitly; `['*']` opts out.
+     */
+    readonly allowedHosts?: readonly string[];
+    /** Injected transport (tests). Production uses the runtime's global `fetch`. */
+    readonly fetch?: FireweaveRemoteAdapterOptions['fetch'];
+}
+export interface InitFireweaveLocalOptions {
+    /** Evaluate against an in-process seeded map; no network (spec/modes.md). */
+    readonly mode: 'local';
+    readonly local?: {
+        /**
+         * Per-key boolean overrides — the seeded local map. A present key
+         * resolves with reason `STATIC`; an absent key misses so the caller's own
+         * default is used. May be empty or omitted entirely.
+         */
+        readonly controlPoints?: Record<string, boolean>;
+        /**
+         * Sink for the `[fireweave:local]` registerTarget trace line
+         * (spec/modes.md "registerTarget in local mode"). Defaults to
+         * `console.info`.
+         */
+        readonly log?: (message: string) => void;
+    };
+}
+export type InitFireweaveOptions = InitFireweaveRemoteOptions | InitFireweaveLocalOptions;
+/**
+ * Build the adapter matching `options.mode` and bring a {@link FireweaveClient}
+ * to READY.
+ *
+ * Throws {@link FireweaveError} (kind `Configuration`) for every row of the
+ * initialisation-validation table (spec/modes.md):
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `apiUrl` fails the host allowlist
+ *  - `mode: 'local'` with credentials supplied
+ *
+ * The first, second and fourth rows are `validateInitOptions`'s job; the
+ * third is validated downstream, when `runtime.initialize()` brings the
+ * adapter up (`FireweaveRuntime`'s own config validation, `hosts.ts`).
+ */
+export declare function initFireweave(options: InitFireweaveOptions): Promise<FireweaveClient>;

package/dist/application/mode.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initFireweave = initFireweave;
+/**
+ * initFireweave — the single SDK entry point (spec/modes.md).
+ *
+ * `mode` is required and never inferred: a missing or mistyped credential
+ * must fail loudly at boot, not silently fall back to local evaluation —
+ * that failure mode looks like a green boot and a feature that never ramps.
+ * This function's only job is to validate the initialisation-time contract
+ * and select the matching adapter; nothing downstream branches on mode again
+ * (spec/modes.md "Behaviour per mode" — both adapters implement the same
+ * BackendAdapter port, so FireweaveClient / FireweaveRuntime stay mode-blind).
+ *
+ * Initialisation fails loudly (throws); reads on the returned client never do
+ * (spec/control-points.md "initialise is the exception"). The validation
+ * itself lives in `validateInitOptions` (validation.ts), which returns
+ * `Validated<T>` like every other validator — this function is what converts
+ * a failed `Validated` into the throw spec/modes.md requires.
+ */
+const client_js_1 = require("./client.js");
+const runtime_js_1 = require("./runtime.js");
+const local_js_1 = require("../infrastructure/adapters/local.js");
+const remote_js_1 = require("../infrastructure/adapters/remote.js");
+const validation_js_1 = require("../domain/validation.js");
+async function initLocal(options) {
+    const local = options.local ?? {};
+    const adapter = new local_js_1.FireweaveLocalAdapter({
+        devFlags: local.controlPoints ?? {},
+        ...(local.log !== undefined ? { log: local.log } : {}),
+    });
+    const runtime = new runtime_js_1.FireweaveRuntime(adapter);
+    await runtime.initialize();
+    return new client_js_1.FireweaveClient(runtime);
+}
+async function initRemote(options) {
+    const { apiKey, apiUrl, allowedHosts, fetch } = options;
+    const adapter = new remote_js_1.FireweaveRemoteAdapter({
+        apiKey,
+        apiUrl,
+        ...(allowedHosts !== undefined ? { allowedHosts } : {}),
+        ...(fetch !== undefined ? { fetch } : {}),
+    });
+    const runtime = new runtime_js_1.FireweaveRuntime(adapter, {
+        // The same host the adapter will actually call, gated through the
+        // canonical allowlist (hosts.ts) before any network I/O happens.
+        host: apiUrl,
+        ...(allowedHosts !== undefined ? { allowedHosts } : {}),
+    });
+    await runtime.initialize();
+    return new client_js_1.FireweaveClient(runtime);
+}
+/**
+ * Build the adapter matching `options.mode` and bring a {@link FireweaveClient}
+ * to READY.
+ *
+ * Throws {@link FireweaveError} (kind `Configuration`) for every row of the
+ * initialisation-validation table (spec/modes.md):
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `apiUrl` fails the host allowlist
+ *  - `mode: 'local'` with credentials supplied
+ *
+ * The first, second and fourth rows are `validateInitOptions`'s job; the
+ * third is validated downstream, when `runtime.initialize()` brings the
+ * adapter up (`FireweaveRuntime`'s own config validation, `hosts.ts`).
+ */
+async function initFireweave(options) {
+    const validated = (0, validation_js_1.validateInitOptions)(options);
+    if (!validated.ok)
+        throw validated.error;
+    const validOptions = validated.value;
+    return validOptions.mode === 'local' ? initLocal(validOptions) : initRemote(validOptions);
+}

package/dist/application/ports.d.ts

@@ -0,0 +1,94 @@
+import type { FireweaveError } from '../domain/errors.js';
+import type { CanonicalContext, DecisionReason, Exposure, FlagValueType, JsonValue, Signal } from '../domain/types.js';
+import type { TargetKind } from '../domain/target.js';
+export interface RegisterTargetOptions {
+    /** Defaults to 'user'. */
+    kind?: TargetKind;
+    /** Durable targeting facts: plan, beta membership, region, device model. */
+    properties?: Record<string, JsonValue>;
+    /** Client-declared environment (production, staging, …). */
+    environment?: string;
+    signal?: AbortSignal;
+}
+export interface RegisterTargetResult {
+    /**
+     * `false` means the target was NOT registered — rules that depend on its
+     * properties will not match until a later attempt succeeds. Callers in a
+     * login path normally ignore this; a careful caller logs it, because a
+     * silently unregistered target is exactly how targeting rules end up
+     * matching nobody.
+     */
+    readonly ok: boolean;
+    readonly error?: FireweaveError;
+}
+/** Result of a backend flag resolution (success path; faults throw FireweaveError). */
+export interface AdapterResolution {
+    found: boolean;
+    /** Flag enabled state; false ⇒ DISABLED reason with the flag's stored value. */
+    enabled?: boolean;
+    value?: JsonValue;
+    variant?: string;
+    /** Declared flag type when known (in-memory fixtures); adapters may omit. */
+    flagType?: FlagValueType | 'integer' | 'float';
+    /**
+     * Adapter-suggested reason override (e.g. SPLIT, STALE) on a `found: true`
+     * resolution. On a `found: false` miss, `reason: 'DEFAULT'` instead signals
+     * the runtime to return the caller's default with reason `DEFAULT` — not an
+     * error — per local mode's unknown-key row (spec/modes.md; see
+     * FireweaveLocalAdapter.resolve).
+     */
+    reason?: DecisionReason;
+    /** Vendor reason code (e.g. "condition_match"). */
+    reasonCode?: string;
+    /** Vendor condition index when the vendor reports one. */
+    conditionIndex?: number;
+    /** Flag definition version. */
+    version?: number;
+    /** Vendor-side numeric flag id. */
+    vendorControlPointId?: number;
+    /** Optional flag payload (object or pre-serialized JSON string). */
+    payload?: JsonValue;
+    /** True when the /flags response reported quota limiting. */
+    quotaLimited?: boolean;
+    /** True when served from a stale/last-good cache. */
+    fromCache?: boolean;
+}
+export interface ResolveOptions {
+    signal?: AbortSignal;
+}
+export interface AdapterRuntimeFeatures {
+    remoteEvaluation?: boolean;
+    localEvaluation?: boolean;
+    localOnly?: boolean;
+    exposureEmission?: boolean;
+    sideEffectFreeReads?: boolean;
+    groupAnalytics?: boolean;
+}
+/**
+ * Backend adapter boundary. Adapters translate
+ * canonical requests to vendor protocols; they never see OpenFeature types.
+ */
+export interface BackendAdapter {
+    /** Third-party adapters use 'other'; the vendor is fw-server's concern. */
+    readonly name: 'inmemory' | 'fireweave' | 'other';
+    /** Bring the backend to a usable state. Reject with FireweaveError on failure. */
+    initialize(signal?: AbortSignal): Promise<void>;
+    /** Resolve one flag. Throws FireweaveError for transport/auth/parse faults. */
+    resolve(controlPointKey: string, context: CanonicalContext, options?: ResolveOptions): Promise<AdapterResolution>;
+    /**
+     * Register a user or device so rules can target its durable properties
+     * (optional capability). Resolves with `ok: false` rather than throwing —
+     * registration sits in login paths and must not break sign-in.
+     */
+    registerTarget?(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    /** Record an exposure event (optional capability). */
+    recordExposure?(exposure: Exposure): void;
+    /** Deliver a telemetry signal to the backend sink (optional capability, ruling 17). */
+    recordSignal?(signal: Signal): void;
+    /** Flush buffered telemetry/exposures. */
+    flush?(): Promise<void>;
+    /** Release resources; must be idempotent. */
+    shutdown(): Promise<void>;
+    /** Runtime feature capabilities contributed by this adapter. */
+    features(): AdapterRuntimeFeatures;
+}

package/dist/application/ports.js

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

package/dist/application/runtime.d.ts

@@ -0,0 +1,101 @@
+import { type ContextInput, type ContextLimits } from '../domain/context.js';
+import { type ExpectedFlagType } from '../domain/validation.js';
+import type { BackendAdapter, RegisterTargetOptions, RegisterTargetResult } from './ports.js';
+import type { CanonicalContext, Decision, JsonValue, LifecycleState } from '../domain/types.js';
+export type { ExpectedFlagType } from '../domain/validation.js';
+export interface FireweaveRuntimeConfig {
+    /**
+     * Fireweave project/runtime key (`project-api-key_…`). Adapters may also read
+     * it from their own options.
+     */
+    projectApiKey?: string;
+    /** Backend host (must be http(s) and pass the allowlist). */
+    host?: string;
+    /**
+     * SSRF allowlist: hostnames the SDK may talk to. Empty/undefined ⇒ the
+     * canonical Fireweave default allowlist + loopback (DEFAULT_ALLOWED_HOSTS).
+     * Custom/self-hosted endpoints must be listed explicitly; ['*'] opts out.
+     */
+    allowedHosts?: readonly string[];
+    /** Require targetingKey on every evaluation. */
+    requireTargetingKey?: boolean;
+    /** Context bound overrides (defaults are the ratified spec bounds). */
+    limits?: Partial<ContextLimits>;
+    /** Additional reserved attribute keys. */
+    reservedAttributeKeys?: readonly string[];
+    /** Shutdown flush deadline (ms). Default DEFAULT_SHUTDOWN_TIMEOUT_MS. */
+    shutdownTimeoutMs?: number;
+}
+/** Default bound on shutdown/flush (matches capabilities.get()). */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10000;
+export interface EvaluateOptions {
+    /** Attach flag payload as fireweave.payload metadata (sorted-key JSON string). */
+    includePayload?: boolean;
+    /**
+     * When true, emit a Fireweave-owned exposure for a successful evaluation
+     * (H-4 / ADR-0001 §23 errata / ruling 20). Default `false` — phase-one
+     * evaluate is side-effect-free. Vendor `$feature_flag_called` stays
+     * suppressed on the local snapshot path (RB-2); Fireweave owns emission
+     * and dedup when opted in.
+     */
+    sendExposure?: boolean;
+    signal?: AbortSignal;
+}
+/** JSON stringify with deterministic (sorted) key order at every level. */
+export declare function stableStringify(value: JsonValue): string;
+export declare class FireweaveRuntime {
+    readonly adapter: BackendAdapter;
+    readonly config: FireweaveRuntimeConfig;
+    private readonly contextPolicy;
+    private state;
+    private globalContext;
+    private clientContext;
+    private initPromise;
+    private readonly stateListeners;
+    /** Dedup window for evaluate/OF-path exposures (cleared on flush / shutdown). */
+    private readonly evaluateExposureSeen;
+    constructor(adapter: BackendAdapter, config?: FireweaveRuntimeConfig);
+    /** Clear evaluate-path exposure dedup (M-2 / clear-on-flush lifecycle). */
+    clearEvaluateExposureDedup(): void;
+    getState(): LifecycleState;
+    onStateChange(listener: (state: LifecycleState) => void): void;
+    private setState;
+    /** Mark definitions/cache staleness (adapter-driven). */
+    markStale(): void;
+    setGlobalContext(context: ContextInput | undefined): void;
+    setClientContext(context: ContextInput | undefined): void;
+    /**
+     * Initialize the runtime: validate config, then bring the adapter up.
+     * Rejects with FireweaveError; Configuration errors put the runtime in FATAL.
+     */
+    initialize(signal?: AbortSignal): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Canonicalize + validate the merged context (throws FireweaveError). */
+    resolveContext(invocationContext: ContextInput | undefined): CanonicalContext;
+    /**
+     * 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).
+     */
+    evaluate(controlPointKey: string, expectedType: ExpectedFlagType, defaultValue: JsonValue, invocationContext?: ContextInput, options?: EvaluateOptions): Promise<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.
+     */
+    registerTarget(targetingKey: string, options?: RegisterTargetOptions): Promise<RegisterTargetResult>;
+    private emitEvaluateExposure;
+    private lifecycleError;
+    private errorDecision;
+}