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

package/dist/infrastructure/adapters/remote.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireweaveRemoteAdapter = void 0;
+/**
+ * Fireweave remote backend adapter (ADR-0005) — **default production path**.
+ *
+ * Speaks only the vendor-neutral Fireweave remote protocol to fw-server:
+ *   POST /v1/control-points/evaluate
+ *   POST /v1/capture
+ *   POST /v1/targets/register
+ *
+ * Auth: Authorization: Bearer <project key> (project-api-key_…).
+ * Which backend fw-server forwards to is fw-server's concern: no vendor SDK,
+ * key, or host ever enters the application process.
+ *
+ * See spec/remote-protocol.md.
+ */
+const errors_js_1 = require("../../domain/errors.js");
+const hosts_js_1 = require("../hosts.js");
+const validation_js_1 = require("../../domain/validation.js");
+const DEFAULT_ADAPTER_SHUTDOWN_TIMEOUT_MS = 10000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 3000;
+const EVALUATE_PATH = '/v1/control-points/evaluate';
+const CAPTURE_PATH = '/v1/capture';
+const REGISTER_TARGET_PATH = '/v1/targets/register';
+function mapHttpStatus(status) {
+    if (status === 401)
+        return new errors_js_1.FireweaveError('Authentication');
+    if (status === 403)
+        return new errors_js_1.FireweaveError('Authorization');
+    if (status === 429)
+        return new errors_js_1.FireweaveError('RateLimited');
+    if (status >= 500)
+        return new errors_js_1.FireweaveError('BackendUnavailable');
+    return new errors_js_1.FireweaveError('BackendUnavailable');
+}
+/**
+ * `apiUrl`/`apiKey` come from `options` only — never the environment
+ * (spec/modes.md "The SDK reads no environment variables. Credentials
+ * arrive as explicit options.", unscoped).
+ */
+function resolveCredentials(options) {
+    const apiUrl = (options.apiUrl ?? '').replace(/\/+$/, '');
+    const apiKey = options.apiKey ?? '';
+    return { apiUrl, apiKey };
+}
+function defaultAllowedHostsFor(apiUrl) {
+    try {
+        const hostname = new URL(apiUrl).hostname;
+        const hosts = [hostname, 'localhost', '127.0.0.1', '::1'];
+        if (hostname === '[::1]')
+            hosts.push('::1');
+        return hosts;
+    }
+    catch {
+        return ['localhost', '127.0.0.1', '::1'];
+    }
+}
+function reasonToAdapter(reason) {
+    const allowed = new Set([
+        'STATIC',
+        'DEFAULT',
+        'TARGETING_MATCH',
+        'SPLIT',
+        'CACHED',
+        'STALE',
+        'DISABLED',
+        'UNKNOWN',
+        'ERROR',
+    ]);
+    return allowed.has(reason) ? reason : undefined;
+}
+class FireweaveRemoteAdapter {
+    name = 'fireweave';
+    options;
+    apiUrl = '';
+    apiKey = '';
+    closed = false;
+    ready = false;
+    pending = [];
+    fetchImpl;
+    constructor(options = {}) {
+        this.options = { ...options };
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+    }
+    async initialize(_signal) {
+        if (this.closed)
+            throw new errors_js_1.FireweaveError('AlreadyClosed');
+        const { apiUrl, apiKey } = resolveCredentials(this.options);
+        if (!apiUrl || !apiKey) {
+            throw new errors_js_1.FireweaveError('Configuration');
+        }
+        let url;
+        try {
+            url = new URL(apiUrl);
+        }
+        catch {
+            throw new errors_js_1.FireweaveError('Configuration');
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new errors_js_1.FireweaveError('Configuration');
+        }
+        if (url.protocol === 'http:' && !(0, hosts_js_1.isLoopbackHostname)(url.hostname)) {
+            throw new errors_js_1.FireweaveError('Configuration');
+        }
+        const allow = this.options.allowedHosts !== undefined && this.options.allowedHosts.length > 0
+            ? this.options.allowedHosts
+            : defaultAllowedHostsFor(apiUrl);
+        (0, hosts_js_1.assertHostAllowed)(apiUrl, allow);
+        this.apiUrl = apiUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        this.ready = true;
+    }
+    async resolve(controlPointKey, context, options) {
+        if (this.closed)
+            throw new errors_js_1.FireweaveError('AlreadyClosed');
+        if (!this.ready)
+            throw new errors_js_1.FireweaveError('NotReady');
+        const targetingKeyResult = (0, validation_js_1.validateTargetingKey)(context.targetingKey, true);
+        if (!targetingKeyResult.ok)
+            throw targetingKeyResult.error;
+        const targetingKey = targetingKeyResult.value ?? '';
+        const attributes = {};
+        for (const [k, v] of Object.entries(context.attributes)) {
+            if (k === 'groups' || k === 'groupProperties' || k.startsWith('$') || k.startsWith('fireweave.')) {
+                continue;
+            }
+            attributes[k] = v;
+        }
+        const body = {
+            targetingKey,
+            controlPointKeys: [controlPointKey],
+        };
+        if (Object.keys(attributes).length > 0)
+            body['attributes'] = attributes;
+        if (context.groups !== undefined)
+            body['groups'] = context.groups;
+        if (context.groupProperties !== undefined)
+            body['groupProperties'] = context.groupProperties;
+        const response = await this.requestJson(EVALUATE_PATH, body, options?.signal);
+        const item = response.decisions?.find((d) => d.controlPointKey === controlPointKey);
+        if (item === undefined) {
+            const missing = { found: false };
+            if (response.quotaLimited === true)
+                missing.quotaLimited = true;
+            return missing;
+        }
+        return this.toResolution(item, response.quotaLimited === true);
+    }
+    /**
+     * Register a user or device so flag rules can target its DURABLE properties.
+     *
+     * Call once per login / device provisioning, then send the same
+     * `targetingKey` on evaluate. Per-request `attributes` still override the
+     * stored properties for a single evaluation — the two identity paths compose
+     * (see spec/remote-protocol.md § Two identity paths).
+     *
+     * Never throws for transport failures: registration sits in login paths, and
+     * an analytics call must not break sign-in. Retried ONCE when the error
+     * taxonomy marks the failure retryable (network / timeout / backend); a
+     * rejected payload or bad key is not retried, since it would be rejected
+     * identically. The result object reports what happened for callers that
+     * want to log it.
+     */
+    async registerTarget(targetingKey, options = {}) {
+        if (this.closed)
+            return { ok: false, error: new errors_js_1.FireweaveError('AlreadyClosed') };
+        if (!this.ready)
+            return { ok: false, error: new errors_js_1.FireweaveError('NotReady') };
+        const targetingKeyResult = (0, validation_js_1.validateTargetingKey)(targetingKey, true);
+        if (!targetingKeyResult.ok)
+            return { ok: false, error: targetingKeyResult.error };
+        const body = { targetingKey };
+        if (options.kind !== undefined)
+            body['kind'] = options.kind;
+        if (options.environment !== undefined)
+            body['environment'] = options.environment;
+        if (options.properties !== undefined && Object.keys(options.properties).length > 0) {
+            body['properties'] = options.properties;
+        }
+        let lastError;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                await this.requestJson(REGISTER_TARGET_PATH, body, options.signal);
+                return { ok: true };
+            }
+            catch (err) {
+                lastError =
+                    err instanceof errors_js_1.FireweaveError ? err : new errors_js_1.FireweaveError('BackendUnavailable');
+                if (!lastError.retryable)
+                    break;
+            }
+        }
+        return { ok: false, ...(lastError !== undefined ? { error: lastError } : {}) };
+    }
+    recordExposure(exposure) {
+        if (this.closed || !this.ready)
+            return;
+        const event = {
+            type: 'exposure',
+            targetingKey: exposure.targetingKey,
+            controlPointKey: exposure.controlPointKey,
+            value: exposure.value,
+        };
+        if (exposure.variant !== undefined)
+            event.variant = exposure.variant;
+        if (exposure.rolloutId !== undefined)
+            event.rolloutId = exposure.rolloutId;
+        if (exposure.changeId !== undefined)
+            event.changeId = exposure.changeId;
+        if (exposure.stampId !== undefined)
+            event.stampId = exposure.stampId;
+        this.pending.push(event);
+    }
+    recordSignal(signal) {
+        if (this.closed || !this.ready)
+            return;
+        const event = {
+            type: 'signal',
+            targetingKey: signal.targetingKey ?? signal.rolloutId ?? 'fireweave-sdk',
+            name: signal.name,
+            properties: {
+                kind: signal.kind,
+                ...(signal.status !== undefined ? { status: signal.status } : {}),
+                ...(signal.errorKind !== undefined ? { errorKind: signal.errorKind } : {}),
+                ...(signal.message !== undefined ? { message: signal.message } : {}),
+                ...(signal.value !== undefined ? { value: signal.value } : {}),
+            },
+        };
+        if (signal.controlPointKey !== undefined)
+            event.controlPointKey = signal.controlPointKey;
+        if (signal.variant !== undefined)
+            event.variant = signal.variant;
+        if (signal.rolloutId !== undefined)
+            event.rolloutId = signal.rolloutId;
+        if (signal.changeId !== undefined)
+            event.changeId = signal.changeId;
+        if (signal.stampId !== undefined)
+            event.stampId = signal.stampId;
+        if (signal.timestamp !== undefined)
+            event.timestamp = signal.timestamp;
+        this.pending.push(event);
+    }
+    async flush() {
+        if (this.closed || !this.ready || this.pending.length === 0)
+            return;
+        const batch = this.pending.splice(0, this.pending.length);
+        try {
+            await this.requestJson(CAPTURE_PATH, { events: batch });
+        }
+        catch {
+            // flush failures must not throw into shutdown paths; re-queue best-effort
+            this.pending.unshift(...batch);
+        }
+    }
+    async shutdown() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // The race timer is cleared once the flush wins; left armed, it held the
+        // process open for up to shutdownTimeoutMs after a clean shutdown.
+        let timer;
+        try {
+            const timeout = this.options.shutdownTimeoutMs ?? DEFAULT_ADAPTER_SHUTDOWN_TIMEOUT_MS;
+            await Promise.race([
+                this.flush(),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, timeout);
+                }),
+            ]);
+        }
+        catch {
+            // never throw from shutdown
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        this.ready = false;
+    }
+    features() {
+        return {
+            remoteEvaluation: true,
+            localEvaluation: false,
+            localOnly: false,
+            exposureEmission: true,
+            sideEffectFreeReads: true,
+            groupAnalytics: true,
+        };
+    }
+    toResolution(item, quotaLimited) {
+        if (item.found === false) {
+            const missing = { found: false };
+            if (quotaLimited)
+                missing.quotaLimited = true;
+            return missing;
+        }
+        const resolution = {
+            found: true,
+            value: item.value,
+            enabled: item.enabled ?? true,
+        };
+        if (item.variant != null)
+            resolution.variant = item.variant;
+        const reason = reasonToAdapter(item.reason);
+        if (reason !== undefined)
+            resolution.reason = reason;
+        if (item.payload !== undefined)
+            resolution.payload = item.payload;
+        const meta = item.controlPointMetadata ?? {};
+        if (typeof meta['fireweave.controlPointVersion'] === 'number') {
+            resolution.version = meta['fireweave.controlPointVersion'];
+        }
+        if (typeof meta['fireweave.vendorControlPointId'] === 'number') {
+            resolution.vendorControlPointId = meta['fireweave.vendorControlPointId'];
+        }
+        if (typeof meta['fireweave.reasonCode'] === 'string') {
+            resolution.reasonCode = meta['fireweave.reasonCode'];
+        }
+        if (quotaLimited || meta['fireweave.quotaLimited'] === true) {
+            resolution.quotaLimited = true;
+        }
+        return resolution;
+    }
+    async requestJson(path, body, outerSignal) {
+        const timeoutMs = this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const onOuterAbort = () => controller.abort();
+        if (outerSignal !== undefined) {
+            if (outerSignal.aborted)
+                controller.abort();
+            else
+                outerSignal.addEventListener('abort', onOuterAbort, { once: true });
+        }
+        try {
+            let response;
+            try {
+                response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                const aborted = err instanceof Error && err.name === 'AbortError';
+                throw aborted ? new errors_js_1.FireweaveError('Timeout') : new errors_js_1.FireweaveError('Network');
+            }
+            if (response.status >= 400) {
+                throw mapHttpStatus(response.status);
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new errors_js_1.FireweaveError('MalformedResponse');
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+            if (outerSignal !== undefined) {
+                outerSignal.removeEventListener('abort', onOuterAbort);
+            }
+        }
+    }
+}
+exports.FireweaveRemoteAdapter = FireweaveRemoteAdapter;

package/dist/infrastructure/hosts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical default host allowlist.
+ *
+ * v3 replaced the third-party analytics hostnames this list used to carry
+ * (ADR-0006) with Fireweave's own fw-server hostnames. The security property is
+ * unchanged — an unconfigured allowlist still denies everything it does not name
+ * — but the *contents* changed: code doing
+ * `allowedHosts: [...DEFAULT_ALLOWED_HOSTS, …]` no longer reaches the former
+ * vendor endpoints, which is the intent.
+ */
+export declare const DEFAULT_ALLOWED_HOSTS: readonly string[];
+/** True for loopback hostnames (http and test stubs are permitted here). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Validate a backend host URL against the allowlist.
+ * Throws FireweaveError('Configuration') — fixed message, no host echo.
+ */
+export declare function assertHostAllowed(host: string, allowedHosts?: readonly string[]): void;

package/dist/infrastructure/hosts.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALLOWED_HOSTS = void 0;
+exports.isLoopbackHostname = isLoopbackHostname;
+exports.assertHostAllowed = assertHostAllowed;
+/**
+ * Backend host allowlist (SSRF guard).
+ *
+ * The allowlist is ON by default: when no explicit `allowedHosts` is
+ * configured, only the canonical Fireweave hosts plus loopback are permitted,
+ * so a typo'd or tampered `host` cannot be aimed at cloud metadata endpoints.
+ * Custom / self-hosted deployments require an explicit `allowedHosts` entry;
+ * `['*']` opts out entirely.
+ *
+ * Scheme policy: https is required for non-loopback hosts; plain http is
+ * permitted on loopback only (the repo's test-server stub).
+ */
+const errors_js_1 = require("../domain/errors.js");
+/**
+ * Canonical default host allowlist.
+ *
+ * v3 replaced the third-party analytics hostnames this list used to carry
+ * (ADR-0006) with Fireweave's own fw-server hostnames. The security property is
+ * unchanged — an unconfigured allowlist still denies everything it does not name
+ * — but the *contents* changed: code doing
+ * `allowedHosts: [...DEFAULT_ALLOWED_HOSTS, …]` no longer reaches the former
+ * vendor endpoints, which is the intent.
+ */
+exports.DEFAULT_ALLOWED_HOSTS = Object.freeze([
+    'app-server.fireweave.ai',
+    'staging-app-server.fireweave.ai',
+    'localhost',
+    '127.0.0.1',
+    '::1',
+]);
+/** True for loopback hostnames (http and test stubs are permitted here). */
+function isLoopbackHostname(hostname) {
+    return (hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '[::1]');
+}
+/**
+ * Validate a backend host URL against the allowlist.
+ * Throws FireweaveError('Configuration') — fixed message, no host echo.
+ */
+function assertHostAllowed(host, allowedHosts) {
+    let url;
+    try {
+        url = new URL(host);
+    }
+    catch {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    const loopback = isLoopbackHostname(url.hostname);
+    if (url.protocol === 'http:' && !loopback) {
+        // https required for anything that leaves the machine.
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+    const list = allowedHosts !== undefined && allowedHosts.length > 0 ? allowedHosts : exports.DEFAULT_ALLOWED_HOSTS;
+    if (list.includes('*'))
+        return; // explicit opt-out
+    const allowed = list.some((h) => url.hostname === h ||
+        (h === 'localhost' && loopback) ||
+        (h === '::1' && url.hostname === '[::1]'));
+    if (!allowed) {
+        throw new errors_js_1.FireweaveError('Configuration');
+    }
+}

package/dist/register-browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register-browser.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Browser build of @fireweaveai/server-sdk/register: fails loudly, never starts. */
+const index_js_1 = require("./index.js");
+throw new index_js_1.FireweaveError('Configuration', {
+    message: '[fireweave] @fireweaveai/server-sdk/register is for server runtimes. Browser apps use @fireweaveai/web-sdk.',
+});

package/dist/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @fireweaveai/server-sdk/register: start FireWeave from the environment alone.
+ *
+ *   import '@fireweaveai/server-sdk/register';      // first import of the entrypoint
+ *   node --import @fireweaveai/server-sdk/register app.js
+ *   bun --preload @fireweaveai/server-sdk/register app.ts
+ *
+ * Use src/fireweave/start.ts instead when you pass control points or other options.
+ */
+const index_js_1 = require("./start/index.js");
+(0, index_js_1.start)();

package/dist/start/browser.d.ts

@@ -0,0 +1,12 @@
+export declare function start(): void;
+export declare function defineControlPoints<T>(controlPoints: T): T;
+export declare function resetForTests(): Promise<void>;
+export declare const fw: Readonly<{
+    controlPoints: {};
+    identify: () => never;
+    instanceKey: () => never;
+    status: () => never;
+    client: () => never;
+    shutdown: () => never;
+}>;
+export { SDK_VERSION, SDK_CHANNEL } from './build-info.js';

package/dist/start/browser.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_CHANNEL = exports.SDK_VERSION = exports.fw = void 0;
+exports.start = start;
+exports.defineControlPoints = defineControlPoints;
+exports.resetForTests = resetForTests;
+/**
+ * Browser build of @fireweaveai/server-sdk/start (the "browser" export
+ * condition). Server keys must never reach a bundle, so every entry point
+ * fails loudly and names the right package.
+ */
+const index_js_1 = require("../index.js");
+const serverOnly = () => new index_js_1.FireweaveError('Configuration', {
+    message: '[fireweave] @fireweaveai/server-sdk/start is for server runtimes. Browser apps use @fireweaveai/web-sdk.',
+});
+function start() {
+    throw serverOnly();
+}
+function defineControlPoints(controlPoints) {
+    return controlPoints;
+}
+async function resetForTests() { }
+const fail = () => {
+    throw serverOnly();
+};
+exports.fw = Object.freeze({
+    controlPoints: new Proxy({}, { get: () => fail }),
+    identify: fail,
+    instanceKey: fail,
+    status: fail,
+    client: fail,
+    shutdown: fail,
+});
+var build_info_js_1 = require("./build-info.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return build_info_js_1.SDK_VERSION; } });
+Object.defineProperty(exports, "SDK_CHANNEL", { enumerable: true, get: function () { return build_info_js_1.SDK_CHANNEL; } });

package/dist/start/build-info.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_VERSION = "3.0.0";
+export declare const SDK_CHANNEL: 'staging' | 'production';

package/dist/start/build-info.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_CHANNEL = exports.SDK_VERSION = void 0;
+// GENERATED by tools/release/version.sh apply server — do not edit by hand.
+// The start profile reads SDK_CHANNEL to choose its default fw-server host
+// (docs/adr/0012-start-profile.md). test/unit/start-build-info.test.ts pins
+// SDK_VERSION to package.json, so a release that forgets to stamp fails CI.
+exports.SDK_VERSION = '3.0.0';
+exports.SDK_CHANNEL = 'production';

package/dist/start/control-points.d.ts

@@ -0,0 +1,20 @@
+export interface ControlPointDefinition {
+    /** Value served in local mode. Ignored in remote mode. */
+    readonly local: boolean;
+    /** Optional note for humans and agents. Never sent anywhere. */
+    readonly description?: string;
+}
+export type ControlPointMap = Readonly<Record<string, ControlPointDefinition>>;
+/** Validate a control-points object and return a frozen copy. Throws Configuration on a bad entry. */
+export declare function normalizeControlPoints(controlPoints: unknown): ControlPointMap;
+/**
+ * Declare the app's control points. Returns its argument unchanged, typed, and
+ * checks it at import time so a typo fails where it was made.
+ *
+ *   export const controlPoints = defineControlPoints({
+ *     'new-checkout': { local: true },
+ *   });
+ */
+export declare function defineControlPoints<const T extends Record<string, ControlPointDefinition>>(controlPoints: T): T;
+/** The core local adapter's seed map. */
+export declare function toLocalControlPoints(controlPoints: ControlPointMap): Record<string, boolean>;

package/dist/start/control-points.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeControlPoints = normalizeControlPoints;
+exports.defineControlPoints = defineControlPoints;
+exports.toLocalControlPoints = toLocalControlPoints;
+/**
+ * The control-points object: every control point the app reads, with the value
+ * served in local mode. It lives in its own file
+ * (src/fireweave/control-points.ts by default) and is passed as
+ * start({ controlPoints }).
+ *
+ * It holds local values only. In remote mode fw-server and the rollout decide,
+ * and call sites keep `false` as their default (RAMP-1), so this file can
+ * never switch a feature on in production.
+ */
+const index_js_1 = require("../index.js");
+const configError = (message) => new index_js_1.FireweaveError('Configuration', { message });
+/** Validate a control-points object and return a frozen copy. Throws Configuration on a bad entry. */
+function normalizeControlPoints(controlPoints) {
+    if (controlPoints === undefined || controlPoints === null)
+        return Object.freeze({});
+    if (typeof controlPoints !== 'object' || Array.isArray(controlPoints)) {
+        throw configError('[fireweave] start({ controlPoints }) must be an object of { key: { local: boolean } }.');
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(controlPoints)) {
+        const keyResult = (0, index_js_1.validateControlPointKey)(key);
+        if (!keyResult.ok)
+            throw configError(`[fireweave] controlPoints: '${key}' is not a valid control point key.`);
+        if (typeof entry !== 'object' || entry === null || typeof entry.local !== 'boolean') {
+            throw configError(`[fireweave] controlPoints['${key}'] must be { local: true } or { local: false }.`);
+        }
+        const { local, description } = entry;
+        if (description !== undefined && typeof description !== 'string') {
+            throw configError(`[fireweave] controlPoints['${key}'].description must be a string.`);
+        }
+        out[key] = Object.freeze(description === undefined ? { local } : { local, description });
+    }
+    return Object.freeze(out);
+}
+/**
+ * Declare the app's control points. Returns its argument unchanged, typed, and
+ * checks it at import time so a typo fails where it was made.
+ *
+ *   export const controlPoints = defineControlPoints({
+ *     'new-checkout': { local: true },
+ *   });
+ */
+function defineControlPoints(controlPoints) {
+    normalizeControlPoints(controlPoints);
+    return controlPoints;
+}
+/** The core local adapter's seed map. */
+function toLocalControlPoints(controlPoints) {
+    const out = {};
+    for (const [key, entry] of Object.entries(controlPoints))
+        out[key] = entry.local;
+    return out;
+}

package/dist/start/env.d.ts

@@ -0,0 +1,11 @@
+/** Reads one variable. Returns undefined when unset, empty, or only whitespace. */
+export type EnvReader = (name: string) => string | undefined;
+/** Reader over an explicit bag (start({ env }) and tests). Only string values count. */
+export declare function envFromBag(bag: Readonly<Record<string, unknown>>): EnvReader;
+/** Reader over the running process: Deno.env first, then process.env. */
+export declare function processEnv(): EnvReader;
+/**
+ * A reader that never throws, for values only needed to word a warning or an
+ * error (for example the key a local start ignores).
+ */
+export declare function quiet(read: EnvReader): EnvReader;