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

package/dist/start/env.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envFromBag = envFromBag;
+exports.processEnv = processEnv;
+exports.quiet = quiet;
+/**
+ * The ONLY place the SDK reads the process environment.
+ *
+ * The core SDK reads no environment variables (spec/modes.md). The start
+ * profile is the documented exception (docs/adr/0012-start-profile.md), and
+ * test/unit/runtime-portability.test.ts pins every env read to this file.
+ *
+ * Works on Node, Bun and Deno without importing a runtime module: Node and Bun
+ * expose `process.env`; Deno exposes `Deno.env.get`, which throws when the
+ * process lacks --allow-env. That refusal is reported, not swallowed, so a
+ * Deno app never boots with a key it was not allowed to read.
+ */
+const index_js_1 = require("../index.js");
+const clean = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+/** Reader over an explicit bag (start({ env }) and tests). Only string values count. */
+function envFromBag(bag) {
+    return (name) => clean(bag[name]);
+}
+/** Reader over the running process: Deno.env first, then process.env. */
+function processEnv() {
+    const deno = globalThis.Deno;
+    if (deno?.env !== undefined) {
+        return (name) => {
+            try {
+                return clean(deno.env?.get(name));
+            }
+            catch (cause) {
+                throw new index_js_1.FireweaveError('Configuration', {
+                    message: `[fireweave] Deno refused to read ${name}. Run with --allow-env=${name}, or pass the value to start() explicitly.`,
+                    cause,
+                });
+            }
+        };
+    }
+    const proc = globalThis.process;
+    const env = proc?.env;
+    if (env === undefined)
+        return () => undefined;
+    return (name) => clean(env[name]);
+}
+/**
+ * A reader that never throws, for values only needed to word a warning or an
+ * error (for example the key a local start ignores).
+ */
+function quiet(read) {
+    return (name) => {
+        try {
+            return read(name);
+        }
+        catch {
+            return undefined;
+        }
+    };
+}

package/dist/start/fw.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `fw`: the singleton accessor beside start(). Safe to import anywhere, in any
+ * order. Every read awaits start and never throws: if start failed, reads
+ * serve the caller's default (or an ERROR decision for the *Details forms).
+ */
+import { type ControlPointsApi, type FireweaveClient, type JsonValue, type RegisterTargetResult, type TargetKind } from '../index.js';
+import { type FireweaveStatus } from './state.js';
+/** The same nine read methods as the core client's controlPoints. */
+export type ControlPoints = Pick<ControlPointsApi, 'evaluate' | 'getBooleanValue' | 'getStringValue' | 'getNumberValue' | 'getObjectValue' | 'getBooleanDetails' | 'getStringDetails' | 'getNumberDetails' | 'getObjectDetails'>;
+export interface IdentifyOptions {
+    /** Defaults to 'user'. */
+    readonly kind?: TargetKind;
+    readonly signal?: AbortSignal;
+}
+export interface FireweaveStart {
+    /** Read control points: `await fw.controlPoints.getBooleanValue('key', false, { targetingKey })`. */
+    readonly controlPoints: ControlPoints;
+    /** Register durable targeting facts at sign-in. Resolves { ok }, never throws. */
+    identify(targetingKey: string, properties?: Record<string, JsonValue>, options?: IdentifyOptions): Promise<RegisterTargetResult>;
+    /** Stable key for reads where the server is the subject (cron, boot). No disk writes. */
+    instanceKey(): string;
+    /** What start() decided: mode, channel, host, key source. Never includes the key. */
+    status(): FireweaveStatus;
+    /** The core client, for anything the facade does not cover. Rejects if start failed. */
+    client(): Promise<FireweaveClient>;
+    /** Flush and close. A later start() begins fresh. */
+    shutdown(): Promise<void>;
+}
+export declare const fw: FireweaveStart;

package/dist/start/fw.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fw = void 0;
+/**
+ * `fw`: the singleton accessor beside start(). Safe to import anywhere, in any
+ * order. Every read awaits start and never throws: if start failed, reads
+ * serve the caller's default (or an ERROR decision for the *Details forms).
+ */
+const index_js_1 = require("../index.js");
+const state_js_1 = require("./state.js");
+const startFailure = () => (0, state_js_1.slot)().error ?? new index_js_1.FireweaveError('Configuration', { message: '[fireweave] FireWeave was not started.' });
+const errorDecision = (controlPointKey, defaultValue) => {
+    const err = startFailure();
+    return {
+        controlPointKey,
+        value: defaultValue,
+        reason: 'ERROR',
+        errorKind: err.kind,
+        errorCode: err.openFeatureErrorCode,
+        errorMessage: err.message,
+        metadata: {},
+    };
+};
+/** Local mode: a key missing from the control-points object gets its default, with one warning. */
+function noteLocalKey(controlPointKey) {
+    const s = (0, state_js_1.slot)();
+    const r = s.resolved;
+    if (r?.mode !== 'local' || Object.prototype.hasOwnProperty.call(r.controlPoints, controlPointKey))
+        return;
+    (0, state_js_1.warnOnce)(s, `[fireweave:local] '${controlPointKey}' is not in your control points (src/fireweave/control-points.ts), so it gets its default. Add it there to try it locally.`);
+}
+async function read(controlPointKey, fallback, run) {
+    const client = await (0, state_js_1.ensureClient)();
+    if (client === undefined)
+        return fallback();
+    noteLocalKey(controlPointKey);
+    return run(client);
+}
+const controlPoints = {
+    evaluate: (controlPointKey, expectedType, defaultValue, context, options) => read(controlPointKey, () => errorDecision(controlPointKey, defaultValue), (c) => c.controlPoints.evaluate(controlPointKey, expectedType, defaultValue, context, options)),
+    getBooleanValue: (controlPointKey, defaultValue, context) => read(controlPointKey, () => defaultValue, (c) => c.controlPoints.getBooleanValue(controlPointKey, defaultValue, context)),
+    getStringValue: (controlPointKey, defaultValue, context) => read(controlPointKey, () => defaultValue, (c) => c.controlPoints.getStringValue(controlPointKey, defaultValue, context)),
+    getNumberValue: (controlPointKey, defaultValue, context) => read(controlPointKey, () => defaultValue, (c) => c.controlPoints.getNumberValue(controlPointKey, defaultValue, context)),
+    getObjectValue: (controlPointKey, defaultValue, context) => read(controlPointKey, () => defaultValue, (c) => c.controlPoints.getObjectValue(controlPointKey, defaultValue, context)),
+    getBooleanDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, () => errorDecision(controlPointKey, defaultValue), (c) => c.controlPoints.getBooleanDetails(controlPointKey, defaultValue, context)),
+    getStringDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, () => errorDecision(controlPointKey, defaultValue), (c) => c.controlPoints.getStringDetails(controlPointKey, defaultValue, context)),
+    getNumberDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, () => errorDecision(controlPointKey, defaultValue), (c) => c.controlPoints.getNumberDetails(controlPointKey, defaultValue, context)),
+    getObjectDetails: (controlPointKey, defaultValue, context) => read(controlPointKey, () => errorDecision(controlPointKey, defaultValue), (c) => c.controlPoints.getObjectDetails(controlPointKey, defaultValue, context)),
+};
+exports.fw = Object.freeze({
+    controlPoints: Object.freeze(controlPoints),
+    async identify(targetingKey, properties, options = {}) {
+        const client = await (0, state_js_1.ensureClient)();
+        if (client === undefined)
+            return { ok: false };
+        try {
+            return await client.registerTarget(targetingKey, {
+                kind: options.kind ?? 'user',
+                ...(properties !== undefined ? { properties } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+        }
+        catch {
+            return { ok: false };
+        }
+    },
+    instanceKey: () => (0, state_js_1.instanceKeyFor)(),
+    status: () => (0, state_js_1.currentStatus)(),
+    async client() {
+        const client = await (0, state_js_1.ensureClient)();
+        if (client === undefined)
+            throw startFailure();
+        return client;
+    },
+    shutdown: () => (0, state_js_1.shutdownSlot)(),
+});

package/dist/start/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fireweaveai/server-sdk/start: FireWeave in one import (docs/adr/0012-start-profile.md).
+ *
+ *   // src/fireweave/start.ts  (imported first by your entrypoint)
+ *   import { start } from '@fireweaveai/server-sdk/start';
+ *   import { controlPoints } from './control-points';
+ *   start({ controlPoints });
+ *
+ *   // anywhere
+ *   import { fw } from '@fireweaveai/server-sdk/start';
+ *   if (await fw.controlPoints.getBooleanValue('new-checkout', false, { targetingKey: user.id })) { … }
+ *
+ * This layer is built only on the package's public exports; the core
+ * (initFireweave and everything in '.') is unchanged and still reads no env.
+ */
+export { start, resetForTests } from './state.js';
+export type { StartOptions, StartState, FireweaveStatus } from './state.js';
+export { fw } from './fw.js';
+export type { FireweaveStart, ControlPoints, IdentifyOptions } from './fw.js';
+export { defineControlPoints } from './control-points.js';
+export type { ControlPointDefinition, ControlPointMap } from './control-points.js';
+export type { StartMode, SdkChannel } from './resolve.js';
+export { SDK_VERSION, SDK_CHANNEL } from './build-info.js';

package/dist/start/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_CHANNEL = exports.SDK_VERSION = exports.defineControlPoints = exports.fw = exports.resetForTests = exports.start = void 0;
+/**
+ * @fireweaveai/server-sdk/start: FireWeave in one import (docs/adr/0012-start-profile.md).
+ *
+ *   // src/fireweave/start.ts  (imported first by your entrypoint)
+ *   import { start } from '@fireweaveai/server-sdk/start';
+ *   import { controlPoints } from './control-points';
+ *   start({ controlPoints });
+ *
+ *   // anywhere
+ *   import { fw } from '@fireweaveai/server-sdk/start';
+ *   if (await fw.controlPoints.getBooleanValue('new-checkout', false, { targetingKey: user.id })) { … }
+ *
+ * This layer is built only on the package's public exports; the core
+ * (initFireweave and everything in '.') is unchanged and still reads no env.
+ */
+var state_js_1 = require("./state.js");
+Object.defineProperty(exports, "start", { enumerable: true, get: function () { return state_js_1.start; } });
+Object.defineProperty(exports, "resetForTests", { enumerable: true, get: function () { return state_js_1.resetForTests; } });
+var fw_js_1 = require("./fw.js");
+Object.defineProperty(exports, "fw", { enumerable: true, get: function () { return fw_js_1.fw; } });
+var control_points_js_1 = require("./control-points.js");
+Object.defineProperty(exports, "defineControlPoints", { enumerable: true, get: function () { return control_points_js_1.defineControlPoints; } });
+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/instance.d.ts

@@ -0,0 +1,17 @@
+/**
+ * fw.instanceKey(): a stable targeting key for reads where the server itself is
+ * the subject (cron, migrations, boot-time decisions). Request reads still pass
+ * the user's id.
+ *
+ * Sources, in order: start({ instanceId }), FIREWEAVE_INSTANCE_ID, then a hash
+ * of the host name, then a random id for the life of the process. Nothing is
+ * written to disk: in a container the file would not outlive the process anyway.
+ */
+import type { EnvReader } from './env.js';
+export interface InstanceKey {
+    readonly value: string;
+    readonly source: 'option' | 'FIREWEAVE_INSTANCE_ID' | 'host' | 'random';
+}
+/** FNV-1a 64-bit, hex. Stable across runtimes; not a security hash. */
+export declare function fnv1a64(text: string): string;
+export declare function deriveInstanceKey(option: string | undefined, read: EnvReader): InstanceKey;

package/dist/start/instance.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fnv1a64 = fnv1a64;
+exports.deriveInstanceKey = deriveInstanceKey;
+const env_js_1 = require("./env.js");
+const names_js_1 = require("./names.js");
+/** FNV-1a 64-bit, hex. Stable across runtimes; not a security hash. */
+function fnv1a64(text) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash ^= BigInt(byte);
+        hash = (hash * prime) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/** Host name without importing a runtime module; undefined when the runtime will not say. */
+function hostName(read) {
+    const fromEnv = (0, env_js_1.quiet)(read)('HOSTNAME');
+    if (fromEnv !== undefined)
+        return fromEnv;
+    try {
+        const deno = globalThis.Deno;
+        if (typeof deno?.hostname === 'function')
+            return deno.hostname();
+    }
+    catch {
+        // Deno without --allow-sys=hostname: fall through.
+    }
+    try {
+        const proc = globalThis.process;
+        const os = proc?.getBuiltinModule?.('node:os');
+        const name = os?.hostname?.();
+        if (typeof name === 'string' && name !== '')
+            return name;
+    }
+    catch {
+        // Runtime without getBuiltinModule: fall through.
+    }
+    return undefined;
+}
+const randomId = () => {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+};
+function deriveInstanceKey(option, read) {
+    if (option !== undefined)
+        return { value: option, source: 'option' };
+    const fromEnv = (0, env_js_1.quiet)(read)(names_js_1.ENV.instanceId);
+    if (fromEnv !== undefined)
+        return { value: fromEnv, source: 'FIREWEAVE_INSTANCE_ID' };
+    const host = hostName(read);
+    if (host !== undefined)
+        return { value: `inst_${fnv1a64(host)}`, source: 'host' };
+    return { value: `inst_${randomId()}`, source: 'random' };
+}

package/dist/start/names.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every name the start profile reads, in one place, so the README, the
+ * initialise skill and the error messages cannot drift apart.
+ */
+/** Env vars the start profile reads. Explicit start() options always win. */
+export declare const ENV: Readonly<{
+    key: "FIREWEAVE_KEY";
+    url: "FIREWEAVE_URL";
+    environment: "FIREWEAVE_ENV";
+    instanceId: "FIREWEAVE_INSTANCE_ID";
+}>;
+/** Fallback env-name sources for mode inference, after the environment option and FIREWEAVE_ENV. */
+export declare const ENVIRONMENT_FALLBACKS: readonly ["APP_ENV", "NODE_ENV"];
+/** Environment names that mean "local development" when no key is set. Case-insensitive. */
+export declare const DEV_ENVIRONMENTS: ReadonlySet<string>;
+/** fw-server host for each release channel of this package. */
+export declare const CHANNEL_URLS: Readonly<{
+    production: "https://app-server.fireweave.ai";
+    staging: "https://staging-app-server.fireweave.ai";
+}>;
+/** Hosts always allowed beside a custom endpoint, so local stacks keep working. */
+export declare const LOOPBACK_HOSTS: readonly string[];

package/dist/start/names.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Every name the start profile reads, in one place, so the README, the
+ * initialise skill and the error messages cannot drift apart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOOPBACK_HOSTS = exports.CHANNEL_URLS = exports.DEV_ENVIRONMENTS = exports.ENVIRONMENT_FALLBACKS = exports.ENV = void 0;
+/** Env vars the start profile reads. Explicit start() options always win. */
+exports.ENV = Object.freeze({
+    key: 'FIREWEAVE_KEY',
+    url: 'FIREWEAVE_URL',
+    environment: 'FIREWEAVE_ENV',
+    instanceId: 'FIREWEAVE_INSTANCE_ID',
+});
+/** Fallback env-name sources for mode inference, after the environment option and FIREWEAVE_ENV. */
+exports.ENVIRONMENT_FALLBACKS = Object.freeze(['APP_ENV', 'NODE_ENV']);
+/** Environment names that mean "local development" when no key is set. Case-insensitive. */
+exports.DEV_ENVIRONMENTS = new Set(['development', 'dev', 'local', 'test']);
+/** fw-server host for each release channel of this package. */
+exports.CHANNEL_URLS = Object.freeze({
+    production: 'https://app-server.fireweave.ai',
+    staging: 'https://staging-app-server.fireweave.ai',
+});
+/** Hosts always allowed beside a custom endpoint, so local stacks keep working. */
+exports.LOOPBACK_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1']);

package/dist/start/resolve.d.ts

@@ -0,0 +1,40 @@
+import type { EnvReader } from './env.js';
+import { type ControlPointMap } from './control-points.js';
+export type StartMode = 'remote' | 'local';
+export type SdkChannel = 'staging' | 'production';
+export interface ResolveInput {
+    readonly mode?: unknown;
+    readonly environment?: unknown;
+    readonly url?: unknown;
+    readonly key?: unknown;
+    readonly controlPoints?: unknown;
+}
+export interface BuildInfo {
+    readonly version: string;
+    readonly channel: SdkChannel;
+}
+export interface ResolvedStart {
+    readonly mode: StartMode;
+    /** Why this mode: the mode option, a present key, or the environment name. */
+    readonly modeSource: 'option' | 'key' | 'environment';
+    /** Remote only. */
+    readonly url?: string;
+    readonly urlSource?: string;
+    readonly allowedHosts?: readonly string[];
+    /** Remote only. Never logged or printed. */
+    readonly key?: string;
+    readonly keySource: string;
+    /** Set when the environment name was consulted (no key, no mode option). */
+    readonly environment?: string;
+    readonly environmentSource?: string;
+    readonly controlPoints: ControlPointMap;
+    readonly channel: SdkChannel;
+    readonly sdkVersion: string;
+    /** Lines to log once each: ignored keys. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Resolve start() options against the environment.
+ * Throws FireweaveError('Configuration') naming the variable at fault.
+ */
+export declare function resolveStart(input: ResolveInput, read: EnvReader, build: BuildInfo): ResolvedStart;

package/dist/start/resolve.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStart = resolveStart;
+/**
+ * Pure start-profile resolver: options + env + build stamp in, one resolved
+ * config out. No I/O, no globals, no timers — every rule here is unit-tested
+ * through `resolveStart` alone.
+ *
+ * Precedence for every value: explicit start() option, then FIREWEAVE_* env,
+ * then the default. Reads are lazy:
+ * a source is read only if every earlier source was unset, so an explicit
+ * option never touches the environment (which matters on Deno).
+ */
+const index_js_1 = require("../index.js");
+const env_js_1 = require("./env.js");
+const control_points_js_1 = require("./control-points.js");
+const names_js_1 = require("./names.js");
+const configError = (message) => new index_js_1.FireweaveError('Configuration', { message });
+const optionString = (value, name) => {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw configError(`[fireweave] start({ ${name} }) must be a string.`);
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+/** First non-empty of: the option, then each env name in order. */
+function pick(option, optionName, names, read) {
+    if (option !== undefined)
+        return { value: option, source: `start({ ${optionName} })` };
+    for (const name of names) {
+        const value = read(name);
+        if (value !== undefined)
+            return { value, source: name };
+    }
+    return undefined;
+}
+/**
+ * Key family check, before any request. Messages name the source, never the
+ * value. The redactor masks analytics-vendor prefixes, so the message says
+ * "analytics vendor key" instead of quoting one.
+ */
+function checkKeyFamily(key, source) {
+    if (key.startsWith('fw_public_')) {
+        throw configError(`[fireweave] The key from ${source} is a browser key (fw_public_…). Server apps need a project key (project-api-key_…) from Project settings, API keys.`);
+    }
+    if (/^ph[a-z]_/.test(key)) {
+        throw configError(`[fireweave] The key from ${source} is an analytics vendor key, not a FireWeave project key. Use the project key (project-api-key_…).`);
+    }
+    if (key.startsWith('fw_org_') || key.startsWith('cli_at_')) {
+        throw configError(`[fireweave] The key from ${source} is an organisation or CLI token, not a project key. Use the project key (project-api-key_…).`);
+    }
+}
+function resolveUrl(input, read, build) {
+    const picked = pick(optionString(input.url, 'url'), 'url', [names_js_1.ENV.url], read);
+    if (picked === undefined) {
+        // The channel host is in DEFAULT_ALLOWED_HOSTS, so no custom allowlist.
+        return { url: names_js_1.CHANNEL_URLS[build.channel], urlSource: `SDK channel (${build.channel})` };
+    }
+    const url = picked.value.replace(/\/+$/, '');
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        throw configError(`[fireweave] The endpoint from ${picked.source} is not a valid URL.`);
+    }
+    const allowedHosts = [hostname.replace(/^\[|\]$/g, ''), ...names_js_1.LOOPBACK_HOSTS];
+    try {
+        (0, index_js_1.assertHostAllowed)(url, allowedHosts);
+    }
+    catch {
+        throw configError(`[fireweave] The endpoint from ${picked.source} must use https (http is allowed only for localhost).`);
+    }
+    return { url, urlSource: picked.source, allowedHosts };
+}
+function resolveKey(input, read) {
+    const picked = pick(optionString(input.key, 'key'), 'key', [names_js_1.ENV.key], read);
+    if (picked !== undefined)
+        checkKeyFamily(picked.value, picked.source);
+    return picked;
+}
+function resolveEnvironment(input, read) {
+    return pick(optionString(input.environment, 'environment'), 'environment', [names_js_1.ENV.environment, ...names_js_1.ENVIRONMENT_FALLBACKS], read);
+}
+function noKeyError(env) {
+    const where = env === undefined
+        ? 'no environment name is set (checked the environment option, FIREWEAVE_ENV, APP_ENV and NODE_ENV)'
+        : `the environment is '${env.value}' (from ${env.source}), which is not a development name`;
+    return configError(`[fireweave] ${names_js_1.ENV.key} is not set and ${where}. Set ${names_js_1.ENV.key} to the project's server key, or for local development set FIREWEAVE_ENV=development or call start({ mode: 'local' }).`);
+}
+/**
+ * Resolve start() options against the environment.
+ * Throws FireweaveError('Configuration') naming the variable at fault.
+ */
+function resolveStart(input, read, build) {
+    const warnings = [];
+    const controlPoints = (0, control_points_js_1.normalizeControlPoints)(input.controlPoints);
+    const base = { controlPoints, channel: build.channel, sdkVersion: build.version };
+    if (input.mode !== undefined && input.mode !== 'remote' && input.mode !== 'local') {
+        throw configError(`[fireweave] start({ mode }) must be 'remote' or 'local'.`);
+    }
+    if (input.mode === 'local') {
+        // The key is ignored. Look only to warn, and never fail on a refused read.
+        const ignored = resolveKeyQuietly(input, read);
+        if (ignored !== undefined) {
+            warnings.push(`[fireweave] start({ mode: 'local' }) ignores the key from ${ignored}; nothing is sent to fw-server.`);
+        }
+        return { ...base, mode: 'local', modeSource: 'option', keySource: 'none', warnings };
+    }
+    const key = resolveKey(input, read);
+    if (input.mode === 'remote') {
+        if (key === undefined) {
+            throw configError(`[fireweave] start({ mode: 'remote' }) needs a key. Set ${names_js_1.ENV.key} or pass start({ key }).`);
+        }
+        return { ...base, mode: 'remote', modeSource: 'option', ...resolveUrl(input, read, build), key: key.value, keySource: key.source, warnings };
+    }
+    if (key !== undefined) {
+        return { ...base, mode: 'remote', modeSource: 'key', ...resolveUrl(input, read, build), key: key.value, keySource: key.source, warnings };
+    }
+    const env = resolveEnvironment(input, read);
+    if (env !== undefined && names_js_1.DEV_ENVIRONMENTS.has(env.value.toLowerCase())) {
+        return {
+            ...base,
+            mode: 'local',
+            modeSource: 'environment',
+            keySource: 'none',
+            environment: env.value,
+            environmentSource: env.source,
+            warnings,
+        };
+    }
+    throw noKeyError(env);
+}
+function resolveKeyQuietly(input, read) {
+    if (typeof input.key === 'string' && input.key.trim() !== '')
+        return 'start({ key })';
+    return (0, env_js_1.quiet)(read)(names_js_1.ENV.key) !== undefined ? names_js_1.ENV.key : undefined;
+}

package/dist/start/state.d.ts

@@ -0,0 +1,96 @@
+/**
+ * start() and the process-wide singleton behind `fw`.
+ *
+ * One slot per process (or worker thread) at a Symbol.for key on globalThis,
+ * so two bundled copies of this package share one client. start() is
+ * synchronous: it resolves and validates everything up front, throws a
+ * Configuration error for bad config, then hands off to the unchanged core
+ * initFireweave(). Reads await readiness and never throw.
+ *
+ * A read that happens before any start() schedules an env-only start on the
+ * next macrotask. An ES module graph without top-level await evaluates in one
+ * job, so an entrypoint that imports ./fireweave/start first always wins.
+ */
+import { FireweaveError, type FireweaveClient, type FireweaveErrorKind, type FireweaveRemoteAdapterOptions } from '../index.js';
+import { type EnvReader } from './env.js';
+import { type ControlPointMap } from './control-points.js';
+import { type InstanceKey } from './instance.js';
+import { type ResolvedStart, type SdkChannel, type StartMode } from './resolve.js';
+export interface StartOptions {
+    /** Control points and their local values; import from src/fireweave/control-points.ts. */
+    readonly controlPoints?: ControlPointMap;
+    /** Force a mode. Without it: a key means remote; no key means local only in a dev environment. */
+    readonly mode?: StartMode;
+    /** Environment name used to infer the mode, instead of FIREWEAVE_ENV, APP_ENV or NODE_ENV. */
+    readonly environment?: string;
+    /** fw-server URL. Default: FIREWEAVE_URL, else this SDK build's channel host. */
+    readonly url?: string;
+    /** Project key (project-api-key_…). Default: FIREWEAVE_KEY. */
+    readonly key?: string;
+    /** Stable id for this process in server-subject reads. Default: FIREWEAVE_INSTANCE_ID, else the host. */
+    readonly instanceId?: string;
+    /** Read these values instead of the process environment (tests, Workers bindings). */
+    readonly env?: Readonly<Record<string, unknown>>;
+    /** Where [fireweave] lines go. Default: console. Not part of the idempotency check. */
+    readonly log?: (line: string) => void;
+    /** Transport override for tests. Not part of the idempotency check. */
+    readonly fetch?: FireweaveRemoteAdapterOptions['fetch'];
+}
+export type StartState = 'unstarted' | 'starting' | 'ready' | 'failed' | 'shutdown';
+export interface FireweaveStatus {
+    readonly state: StartState;
+    readonly mode?: StartMode;
+    readonly modeSource?: ResolvedStart['modeSource'];
+    readonly channel: SdkChannel;
+    readonly sdkVersion: string;
+    /** fw-server host name only: never a path or a credential. */
+    readonly host?: string;
+    readonly endpointSource?: string;
+    readonly keySource?: string;
+    readonly environment?: string;
+    readonly controlPointCount?: number;
+    /** Why start failed, when it did. Already redacted. */
+    readonly error?: string;
+    /**
+     * The kind of the latest failed fw-server request (Authentication,
+     * Authorization, RateLimited, Network, Timeout or BackendUnavailable).
+     * Sticky: a later success does not clear it; a fresh start() does.
+     */
+    readonly lastErrorKind?: FireweaveErrorKind;
+}
+interface Deferred<T> {
+    readonly promise: Promise<T>;
+    readonly resolve: (value: T | PromiseLike<T>) => void;
+}
+interface Slot {
+    readonly protocol: 1;
+    state: StartState;
+    signature?: string;
+    implicit: boolean;
+    resolved?: ResolvedStart;
+    ready: Deferred<FireweaveClient | undefined>;
+    client?: FireweaveClient | undefined;
+    error?: FireweaveError;
+    implicitScheduled: boolean;
+    read?: EnvReader;
+    instanceIdOption?: string;
+    instance?: InstanceKey;
+    log: (line: string) => void;
+    readonly warned: Set<string>;
+    lastErrorKind?: FireweaveErrorKind;
+    /** fw-server failure groups already logged; one line each for the life of the process. */
+    readonly diagnosed: Set<string>;
+}
+export declare function slot(): Slot;
+export declare function warnOnce(s: Slot, line: string): void;
+/** Start FireWeave for this process. Synchronous; call once, from src/fireweave/start.ts. */
+export declare function start(options?: StartOptions): void;
+export declare function startWith(options: StartOptions, implicit: boolean): void;
+/** The client once start() settles; undefined when start failed. Schedules an implicit start if none ran. */
+export declare function ensureClient(): Promise<FireweaveClient | undefined>;
+export declare function currentStatus(): FireweaveStatus;
+export declare function instanceKeyFor(): string;
+export declare function shutdownSlot(): Promise<void>;
+/** Test only: shut down and forget the singleton so the next start() begins fresh. */
+export declare function resetForTests(): Promise<void>;
+export {};