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

package/dist/domain/types.d.ts

@@ -0,0 +1,107 @@
+import type { FireweaveErrorKind, OpenFeatureErrorCode } from './errors.js';
+/** JSON-compatible value (spec/decision.schema.json `value`). */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
+export type DecisionReason = 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'SPLIT' | 'CACHED' | 'STALE' | 'DISABLED' | 'UNKNOWN' | 'ERROR';
+/** Canonical decision (spec/decision.schema.json). */
+export interface Decision {
+    controlPointKey: string;
+    value: JsonValue;
+    reason: DecisionReason;
+    variant?: string;
+    errorCode?: OpenFeatureErrorCode;
+    errorKind?: FireweaveErrorKind;
+    errorMessage?: string;
+    /** fireweave.* flag metadata surfaced to OpenFeature controlPointMetadata. */
+    metadata: Record<string, string | number | boolean>;
+}
+/** Canonical evaluation context after validation/canonicalization. */
+export interface CanonicalContext {
+    targetingKey?: string;
+    /** All non-reserved attributes (targetingKey excluded). */
+    attributes: Record<string, JsonValue>;
+    /**
+     * Group memberships extracted from `fireweave.groups` (canonical, ruling 13)
+     * or the plain `groups` alias, when shaped as Record<string,string>.
+     */
+    groups?: Record<string, string>;
+    /**
+     * Group properties extracted from `fireweave.groupProperties` (canonical)
+     * or the plain `groupProperties` alias.
+     */
+    groupProperties?: Record<string, JsonValue>;
+}
+export type LifecycleState = 'UNINITIALIZED' | 'INITIALIZING' | 'READY' | 'STALE' | 'ERROR' | 'FATAL' | 'SHUTDOWN';
+export type SignalKind = 'health' | 'error' | 'metric' | 'outcome';
+/** Canonical signal envelope (spec/signal.schema.json). */
+export interface Signal {
+    kind: SignalKind;
+    name: string;
+    status?: string;
+    errorKind?: FireweaveErrorKind;
+    message?: string;
+    value?: number | boolean | string;
+    timestamp?: string;
+    targetingKey?: string;
+    rolloutId?: string;
+    changeId?: string;
+    stampId?: string;
+    controlPointKey?: string;
+    variant?: string;
+    traceId?: string;
+    role?: 'adoption' | 'guard' | 'quality' | 'custom';
+    direction?: 'up-good' | 'up-bad' | 'neutral';
+    attributes?: Record<string, string | number | boolean | null>;
+}
+/** Release / rollout context (spec/release-context.schema.json; ruling 15: rolloutId + stampIds required). */
+export interface ReleaseContext {
+    stampIds: string[];
+    rolloutId: string;
+    changeId?: string;
+    surfaces?: Array<{
+        surfaceId: string;
+        kind?: 'ts-server' | 'node-server' | 'python' | 'go' | 'java' | 'web' | 'other';
+    }>;
+    metadata?: Record<string, string | number | boolean>;
+}
+export type ReleaseStatus = 'set' | 'in_progress' | 'completed' | 'failed';
+export interface ReleaseState {
+    context: ReleaseContext;
+    status: ReleaseStatus;
+    reason?: string;
+}
+/** Exposure event (extensions fixtures shape). */
+export interface Exposure {
+    targetingKey: string;
+    controlPointKey: string;
+    value: JsonValue;
+    variant?: string;
+    rolloutId?: string;
+    changeId?: string;
+    stampId?: string;
+}
+/** Capability matrix (spec/capabilities.schema.json). */
+export interface Capabilities {
+    static: {
+        language: 'node';
+        sdkVersion?: string;
+        specVersion?: '0.1.0';
+        openFeature: {
+            specFloor: '0.8.0';
+            providerName: 'fireweave';
+            serverOnly?: boolean;
+        };
+        features: Record<string, boolean>;
+    };
+    runtime: {
+        backend: 'fireweave' | 'inmemory' | 'none' | 'other';
+        lifecycle: LifecycleState;
+        features?: Record<string, boolean>;
+        limits?: {
+            intSafeMaxAbs?: number;
+            shutdownTimeoutMsDefault?: number;
+        };
+    };
+}

package/dist/domain/types.js

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

package/dist/domain/validation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Fireweave SDK validation — pure, total functions per spec/control-points.md
+ * "Validation, before any I/O" and spec/modes.md "Initialisation validation".
+ *
+ * Every read-path validator here (`validateControlPointKey`,
+ * `validateDefaultValue`, `validateContext`, `validateTargetingKey`) returns
+ * `Validated<T>` instead of throwing. `FireweaveRuntime.evaluate` runs them,
+ * in the fixed order the spec names — key, default-vs-type, context,
+ * lifecycle — and degrades to the caller's default on the first failure; it
+ * NEVER throws (spec/control-points.md "Return discipline — never throw into
+ * a read path").
+ *
+ * `validateInitOptions` is the one named exception (spec/modes.md
+ * "Initialisation validation"): its failures are converted to a THROW by
+ * `initFireweave` (src/init.ts). The validator itself still returns
+ * `Validated<T>` — the entry point does the throwing, not this module.
+ *
+ * Collected into one module so it can move wholesale into `domain/` (plan
+ * Phase 1.4) without touching its exports or call sites again. Everything
+ * below is pure (no I/O, no ambient state) and total (every branch returns a
+ * `Validated<T>`) — `conformance/` can exercise all four read-path rules
+ * offline, with no backend.
+ *
+ * `validateInitOptions` is deliberately generic rather than importing
+ * `InitFireweaveOptions` from `init.ts`: init.ts is the "mode" entry point
+ * (Phase 1.4 assigns it to `application/`), and this module is destined for
+ * `domain/`, which must not depend on outer layers. It also does not
+ * validate "apiUrl fails the host allowlist" (spec/modes.md row 3) — that
+ * check (`assertHostAllowed`) lives in `hosts.ts`, which Phase 1.4 assigns to
+ * `infrastructure/`; it stays reachable today via `FireweaveRuntime.initialize`
+ * (runtime.ts) / `FireweaveRemoteAdapter.initialize` (adapters/remote.ts),
+ * unchanged by this module.
+ */
+import { FireweaveError } from './errors.js';
+import { type ContextPolicy } from './context.js';
+import type { CanonicalContext, JsonValue } from './types.js';
+/** Result of a pure validator: success carries the validated value, failure the canonical error. */
+export type Validated<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: FireweaveError;
+};
+/**
+ * key — non-empty, ≤256 characters, no control characters
+ * (spec/control-points.md rule 1, the first check in the fixed order).
+ *
+ * No taxonomy kind names "malformed key" explicitly (the return-discipline
+ * table's closest row is "key unknown to the backend" → ControlPointNotFound): a key
+ * that can never identify a flag is treated the same as one the backend
+ * doesn't recognise, so this maps to ControlPointNotFound too.
+ *
+ * Controller-ruled interim mapping (Task 3 review): the 15-kind taxonomy in
+ * errors.schema.json is frozen at exactly 15 entries, `InvalidContext` is
+ * textually scoped to the evaluation *context* (not the key), and the
+ * schema already maps another non-literal case — quota-limited responses —
+ * onto `ControlPointNotFound` rather than adding a kind for it. `ControlPointNotFound` is
+ * therefore the least-wrong existing kind, not a literal fit. Other-language
+ * implementations copying node as the reference SHOULD use the same mapping
+ * rather than each independently guessing a different one.
+ */
+export declare function validateControlPointKey(key: string): Validated<string>;
+export type ExpectedFlagType = 'boolean' | 'string' | 'number' | 'object';
+/**
+ * Whether `value` matches the shape `expected` names. Shared by
+ * {@link validateDefaultValue} (the caller's default, before any I/O) and
+ * `FireweaveRuntime.evaluate`'s post-resolve check (the backend's resolved
+ * value, after I/O) — same predicate, two different inputs.
+ */
+export declare function matchesExpectedType(value: JsonValue, expected: ExpectedFlagType): boolean;
+/**
+ * default vs type — e.g. `getBooleanValue` with a non-boolean default is
+ * TypeMismatch (spec/control-points.md rule 2, checked before any I/O).
+ */
+export declare function validateDefaultValue(expectedType: ExpectedFlagType, defaultValue: JsonValue): Validated<JsonValue>;
+/**
+ * targetingKey: "An SDK MUST NOT invent one: a missing targeting key is
+ * InvalidContext where the evaluation needs it, never a generated anonymous
+ * id" (spec/control-points.md "Context"). `required` is call-site policy —
+ * the remote adapter always requires one for `resolve`/`registerTarget`
+ * (spec/remote-protocol.md "Two identity paths"); the generic context
+ * pipeline ({@link validateContext}) only does when
+ * `ContextPolicy.requireTargetingKey` opts in.
+ */
+export declare function validateTargetingKey(targetingKey: string | undefined, required: boolean): Validated<string | undefined>;
+/**
+ * context — depth, key count, value size, reserved keys
+ * (evaluation-context.schema.json) (spec/control-points.md rule 3). Also
+ * enforces `policy.requireTargetingKey` via {@link validateTargetingKey}, and
+ * — on success — extracts `groups`/`groupProperties` the same way the former
+ * `canonicalizeContext` did.
+ *
+ * `merged` is the already-merged (global → client → invocation) raw input;
+ * merging itself (`mergeContexts`) lives in context.ts and carries no
+ * validation concerns of its own.
+ */
+export declare function validateContext(merged: {
+    targetingKey?: string;
+    attributes: Record<string, unknown>;
+}, policy: ContextPolicy): Validated<CanonicalContext>;
+/**
+ * Throwing wrapper around {@link validateContext} kept for the pre-existing
+ * public surface (`FireweaveRuntime.resolveContext`, direct callers of the
+ * package export). Read paths do not use this — they call
+ * {@link validateContext} directly so a failure degrades instead of throwing.
+ */
+export declare function canonicalizeContext(merged: {
+    targetingKey?: string;
+    attributes: Record<string, unknown>;
+}, policy: ContextPolicy): CanonicalContext;
+/**
+ * Initialisation-validation table (spec/modes.md), rows 1, 2 and 4:
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `mode: 'local'` with credentials supplied (a config half-migrated from
+ *    remote to local reads as neither, silently — reject it instead)
+ *
+ * Row 3 ("apiUrl fails the host allowlist") is intentionally NOT checked
+ * here — see the module doc comment.
+ */
+export declare function validateInitOptions<T extends {
+    readonly mode?: unknown;
+}>(options: T): Validated<T>;

package/dist/domain/validation.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateControlPointKey = validateControlPointKey;
+exports.matchesExpectedType = matchesExpectedType;
+exports.validateDefaultValue = validateDefaultValue;
+exports.validateTargetingKey = validateTargetingKey;
+exports.validateContext = validateContext;
+exports.canonicalizeContext = canonicalizeContext;
+exports.validateInitOptions = validateInitOptions;
+/**
+ * Fireweave SDK validation — pure, total functions per spec/control-points.md
+ * "Validation, before any I/O" and spec/modes.md "Initialisation validation".
+ *
+ * Every read-path validator here (`validateControlPointKey`,
+ * `validateDefaultValue`, `validateContext`, `validateTargetingKey`) returns
+ * `Validated<T>` instead of throwing. `FireweaveRuntime.evaluate` runs them,
+ * in the fixed order the spec names — key, default-vs-type, context,
+ * lifecycle — and degrades to the caller's default on the first failure; it
+ * NEVER throws (spec/control-points.md "Return discipline — never throw into
+ * a read path").
+ *
+ * `validateInitOptions` is the one named exception (spec/modes.md
+ * "Initialisation validation"): its failures are converted to a THROW by
+ * `initFireweave` (src/init.ts). The validator itself still returns
+ * `Validated<T>` — the entry point does the throwing, not this module.
+ *
+ * Collected into one module so it can move wholesale into `domain/` (plan
+ * Phase 1.4) without touching its exports or call sites again. Everything
+ * below is pure (no I/O, no ambient state) and total (every branch returns a
+ * `Validated<T>`) — `conformance/` can exercise all four read-path rules
+ * offline, with no backend.
+ *
+ * `validateInitOptions` is deliberately generic rather than importing
+ * `InitFireweaveOptions` from `init.ts`: init.ts is the "mode" entry point
+ * (Phase 1.4 assigns it to `application/`), and this module is destined for
+ * `domain/`, which must not depend on outer layers. It also does not
+ * validate "apiUrl fails the host allowlist" (spec/modes.md row 3) — that
+ * check (`assertHostAllowed`) lives in `hosts.ts`, which Phase 1.4 assigns to
+ * `infrastructure/`; it stays reachable today via `FireweaveRuntime.initialize`
+ * (runtime.ts) / `FireweaveRemoteAdapter.initialize` (adapters/remote.ts),
+ * unchanged by this module.
+ */
+const errors_js_1 = require("./errors.js");
+const context_js_1 = require("./context.js");
+const ok = (value) => ({ ok: true, value });
+const fail = (error) => ({ ok: false, error });
+// ---------------------------------------------------------------------------
+// Rule 1 — validateControlPointKey (spec/control-points.md "Validation,
+// before any I/O": "key — non-empty, ≤256 characters, no control characters")
+// ---------------------------------------------------------------------------
+/** C0 + C1 control characters (U+0000-U+001F, U+007F-U+009F). */
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+const MAX_CONTROL_POINT_KEY_LENGTH = 256;
+/**
+ * key — non-empty, ≤256 characters, no control characters
+ * (spec/control-points.md rule 1, the first check in the fixed order).
+ *
+ * No taxonomy kind names "malformed key" explicitly (the return-discipline
+ * table's closest row is "key unknown to the backend" → ControlPointNotFound): a key
+ * that can never identify a flag is treated the same as one the backend
+ * doesn't recognise, so this maps to ControlPointNotFound too.
+ *
+ * Controller-ruled interim mapping (Task 3 review): the 15-kind taxonomy in
+ * errors.schema.json is frozen at exactly 15 entries, `InvalidContext` is
+ * textually scoped to the evaluation *context* (not the key), and the
+ * schema already maps another non-literal case — quota-limited responses —
+ * onto `ControlPointNotFound` rather than adding a kind for it. `ControlPointNotFound` is
+ * therefore the least-wrong existing kind, not a literal fit. Other-language
+ * implementations copying node as the reference SHOULD use the same mapping
+ * rather than each independently guessing a different one.
+ */
+function validateControlPointKey(key) {
+    if (typeof key !== 'string' || key.length === 0) {
+        return fail(new errors_js_1.FireweaveError('ControlPointNotFound', { message: 'control point key must be a non-empty string' }));
+    }
+    if (key.length > MAX_CONTROL_POINT_KEY_LENGTH) {
+        return fail(new errors_js_1.FireweaveError('ControlPointNotFound', { message: 'control point key exceeds maximum length' }));
+    }
+    if (CONTROL_CHARACTERS.test(key)) {
+        return fail(new errors_js_1.FireweaveError('ControlPointNotFound', { message: 'control point key contains control characters' }));
+    }
+    return ok(key);
+}
+/**
+ * Whether `value` matches the shape `expected` names. Shared by
+ * {@link validateDefaultValue} (the caller's default, before any I/O) and
+ * `FireweaveRuntime.evaluate`'s post-resolve check (the backend's resolved
+ * value, after I/O) — same predicate, two different inputs.
+ */
+function matchesExpectedType(value, expected) {
+    switch (expected) {
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number';
+        case 'object':
+            return value !== null && typeof value === 'object';
+    }
+}
+/**
+ * default vs type — e.g. `getBooleanValue` with a non-boolean default is
+ * TypeMismatch (spec/control-points.md rule 2, checked before any I/O).
+ */
+function validateDefaultValue(expectedType, defaultValue) {
+    if (!matchesExpectedType(defaultValue, expectedType)) {
+        return fail(new errors_js_1.FireweaveError('TypeMismatch'));
+    }
+    return ok(defaultValue);
+}
+// ---------------------------------------------------------------------------
+// validateTargetingKey (spec/control-points.md "Context": targetingKey)
+// ---------------------------------------------------------------------------
+/**
+ * targetingKey: "An SDK MUST NOT invent one: a missing targeting key is
+ * InvalidContext where the evaluation needs it, never a generated anonymous
+ * id" (spec/control-points.md "Context"). `required` is call-site policy —
+ * the remote adapter always requires one for `resolve`/`registerTarget`
+ * (spec/remote-protocol.md "Two identity paths"); the generic context
+ * pipeline ({@link validateContext}) only does when
+ * `ContextPolicy.requireTargetingKey` opts in.
+ */
+function validateTargetingKey(targetingKey, required) {
+    if (required && (targetingKey === undefined || targetingKey === '')) {
+        return fail(new errors_js_1.FireweaveError('InvalidContext', {
+            message: 'targeting key missing',
+            openFeatureErrorCode: 'TARGETING_KEY_MISSING',
+        }));
+    }
+    return ok(targetingKey);
+}
+// ---------------------------------------------------------------------------
+// Rule 3 — validateContext (spec/control-points.md rule 3: "context — depth,
+// key count, value size, reserved keys (evaluation-context.schema.json)")
+// ---------------------------------------------------------------------------
+/**
+ * UTF-8 byte length. `TextEncoder` rather than `Buffer.byteLength`: `Buffer`
+ * is a Node global that Deno only exposes under npm compatibility, and this
+ * bound is enforced on every evaluation (ADR-0008 runtime portability).
+ */
+const utf8Encoder = new TextEncoder();
+const byteLength = (s) => utf8Encoder.encode(s).length;
+/**
+ * Sentinel returned (never thrown) when `deepCopyJson` walks back into an
+ * object already on the current recursion path — an actual reference cycle,
+ * not merely the same object shared by two sibling branches (which is legal
+ * and handled by backtracking `seen.delete(...)` below). Untyped caller
+ * input is `unknown`, so a circular attribute value is reachable from a
+ * caller today; without this, recursion never terminates and crashes the
+ * whole process with `RangeError: Maximum call stack size exceeded` —
+ * exactly the kind of throw a "before any I/O" validator must not allow
+ * (spec/control-points.md "Return discipline — never throw into a read
+ * path"). Module-local: never returned across this file's public surface,
+ * only used to fail `validateContext` closed as `InvalidContext`.
+ */
+const CYCLIC = Symbol('fireweave.cyclicJson');
+function deepCopyJson(value, seen = new WeakSet()) {
+    // Structured clone of JSON-compatible data; drops functions/undefined like JSON round-trip.
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return CYCLIC;
+        seen.add(value);
+        const out = [];
+        for (const v of value) {
+            const copied = deepCopyJson(v, seen);
+            if (copied === CYCLIC)
+                return CYCLIC;
+            out.push(copied);
+        }
+        seen.delete(value);
+        return out;
+    }
+    if (typeof value === 'object') {
+        if (seen.has(value))
+            return CYCLIC;
+        seen.add(value);
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v !== undefined) {
+                const copied = deepCopyJson(v, seen);
+                if (copied === CYCLIC)
+                    return CYCLIC;
+                out[k] = copied;
+            }
+        }
+        seen.delete(value);
+        return out;
+    }
+    return null;
+}
+/**
+ * Cycle-safe defensively: `nestingDepth` only ever runs on `deepCopyJson`'s
+ * own output today, which is guaranteed acyclic by construction (it builds
+ * fresh containers, never back-references). Guarded anyway per the same
+ * "must be genuinely total" reasoning as `deepCopyJson`, so a future caller
+ * (e.g. a Task 4 reuse) can't reintroduce the same crash by feeding this
+ * function un-copied input. A detected cycle returns `Infinity`, which
+ * always exceeds `limits.maxNestingDepth` and fails closed through the
+ * existing bound check in {@link validateContext} — no new failure path.
+ */
+function nestingDepth(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return 0;
+    if (seen.has(value))
+        return Infinity;
+    seen.add(value);
+    let max = 0;
+    const children = Array.isArray(value) ? value : Object.values(value);
+    for (const child of children) {
+        const d = nestingDepth(child, seen);
+        if (d > max)
+            max = d;
+    }
+    seen.delete(value);
+    return max + 1;
+}
+const invalidContext = (message) => new errors_js_1.FireweaveError('InvalidContext', { message });
+/**
+ * context — depth, key count, value size, reserved keys
+ * (evaluation-context.schema.json) (spec/control-points.md rule 3). Also
+ * enforces `policy.requireTargetingKey` via {@link validateTargetingKey}, and
+ * — on success — extracts `groups`/`groupProperties` the same way the former
+ * `canonicalizeContext` did.
+ *
+ * `merged` is the already-merged (global → client → invocation) raw input;
+ * merging itself (`mergeContexts`) lives in context.ts and carries no
+ * validation concerns of its own.
+ */
+function validateContext(merged, policy) {
+    const { limits } = policy;
+    const copied = deepCopyJson(merged.attributes);
+    if (copied === CYCLIC) {
+        return fail(invalidContext('context contains a circular reference'));
+    }
+    const attributes = copied;
+    const keys = Object.keys(attributes);
+    if (keys.length > limits.maxAttributeCount) {
+        return fail(invalidContext('context exceeds maximum attribute count'));
+    }
+    for (const key of keys) {
+        if (byteLength(key) > limits.maxKeyBytes) {
+            return fail(invalidContext('context key exceeds maximum size'));
+        }
+    }
+    for (const key of keys) {
+        const value = attributes[key];
+        if (byteLength(JSON.stringify(value ?? null)) > limits.maxValueBytes) {
+            return fail(invalidContext('context value exceeds maximum size'));
+        }
+    }
+    for (const key of keys) {
+        const value = attributes[key];
+        if (value !== undefined && nestingDepth(value) > limits.maxNestingDepth) {
+            return fail(invalidContext('context exceeds maximum nesting depth'));
+        }
+    }
+    const serialized = JSON.stringify({ targetingKey: merged.targetingKey, attributes });
+    if (byteLength(serialized) > limits.maxSerializedContextBytes) {
+        return fail(invalidContext('serialized context exceeds maximum size'));
+    }
+    for (const key of keys) {
+        if (policy.reservedAttributeKeys.includes(key)) {
+            return fail(invalidContext('invalid evaluation context'));
+        }
+        // Ruling 13: exactly fireweave.groups + fireweave.groupProperties are
+        // permitted in the reserved namespace; every other fireweave.* key is rejected.
+        if (key.startsWith('fireweave.') && !context_js_1.ALLOWED_FIREWEAVE_CONTEXT_KEYS.includes(key)) {
+            return fail(invalidContext('invalid evaluation context'));
+        }
+    }
+    const targetingKeyResult = validateTargetingKey(merged.targetingKey, policy.requireTargetingKey);
+    if (!targetingKeyResult.ok)
+        return targetingKeyResult;
+    const canonical = { attributes };
+    if (merged.targetingKey !== undefined)
+        canonical.targetingKey = merged.targetingKey;
+    // Group memberships: canonical carrier `fireweave.groups` (rulings 13–14),
+    // with plain `groups` retained as a documented alias.
+    const groups = attributes['fireweave.groups'] ?? attributes['groups'];
+    if (groups !== null && groups !== undefined && typeof groups === 'object' && !Array.isArray(groups)) {
+        const g = {};
+        let allStrings = true;
+        for (const [k, v] of Object.entries(groups)) {
+            if (typeof v === 'string')
+                g[k] = v;
+            else
+                allStrings = false;
+        }
+        if (allStrings)
+            canonical.groups = g;
+    }
+    // Group properties: canonical carrier `fireweave.groupProperties`,
+    // plain `groupProperties` retained as alias.
+    const groupProps = attributes['fireweave.groupProperties'] ?? attributes['groupProperties'];
+    if (groupProps !== null &&
+        groupProps !== undefined &&
+        typeof groupProps === 'object' &&
+        !Array.isArray(groupProps)) {
+        canonical.groupProperties = groupProps;
+    }
+    return ok(canonical);
+}
+/**
+ * Throwing wrapper around {@link validateContext} kept for the pre-existing
+ * public surface (`FireweaveRuntime.resolveContext`, direct callers of the
+ * package export). Read paths do not use this — they call
+ * {@link validateContext} directly so a failure degrades instead of throwing.
+ */
+function canonicalizeContext(merged, policy) {
+    const result = validateContext(merged, policy);
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+// ---------------------------------------------------------------------------
+// validateInitOptions (spec/modes.md "Initialisation validation")
+// ---------------------------------------------------------------------------
+/** "missing" and "blank" collapse to one check: not a non-empty string. */
+const isBlank = (value) => typeof value !== 'string' || value.trim().length === 0;
+const configError = (message) => new errors_js_1.FireweaveError('Configuration', { message });
+/**
+ * Initialisation-validation table (spec/modes.md), rows 1, 2 and 4:
+ *  - `mode` absent or unrecognised
+ *  - `mode: 'remote'` with `apiKey` or `apiUrl` missing/blank
+ *  - `mode: 'local'` with credentials supplied (a config half-migrated from
+ *    remote to local reads as neither, silently — reject it instead)
+ *
+ * Row 3 ("apiUrl fails the host allowlist") is intentionally NOT checked
+ * here — see the module doc comment.
+ */
+function validateInitOptions(options) {
+    const mode = options?.mode;
+    if (mode !== 'local' && mode !== 'remote') {
+        return fail(configError('mode is required and must be "local" or "remote"'));
+    }
+    // Runtime-only guard: a config object half-migrated from remote to local
+    // can carry apiKey/apiUrl even though the local-mode type declares
+    // neither — TypeScript's excess-property check only fires on a fresh
+    // object literal, not on a variable assembled elsewhere and passed in.
+    const credentials = options;
+    if (mode === 'remote') {
+        if (isBlank(credentials.apiKey) || isBlank(credentials.apiUrl)) {
+            return fail(configError('mode "remote" requires apiKey and apiUrl'));
+        }
+        return ok(options);
+    }
+    if (!isBlank(credentials.apiKey) || !isBlank(credentials.apiUrl)) {
+        return fail(configError('mode "local" must not be combined with apiKey/apiUrl — the caller means one or the other'));
+    }
+    return ok(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fireweaveai/server-sdk — Fireweave release-engineering SDK for server runtimes
+ * (Node, Bun, Deno).
+ *
+ * Exactly two v1 capabilities (spec/control-points.md): control points and
+ * target registration.
+ *
+ * Production default: {@link FireweaveRemoteAdapter} (Fireweave project key →
+ * fw-server). {@link InMemoryAdapter} for offline work and tests. The backend
+ * fw-server forwards to is fw-server's concern — no vendor SDK, key, or host
+ * appears in the application process (ADR-0005, ADR-0006).
+ */
+export { FireweaveError, ERROR_TAXONOMY, redactSecrets, isFireweaveError } from './domain/errors.js';
+export type { FireweaveErrorKind, OpenFeatureErrorCode, ErrorKindSpec } from './domain/errors.js';
+export type { JsonValue, Decision, DecisionReason, CanonicalContext, LifecycleState, Signal, SignalKind, ReleaseContext, ReleaseState, ReleaseStatus, Exposure, Capabilities, FlagValueType, } from './domain/types.js';
+export { DEFAULT_CONTEXT_LIMITS, DEFAULT_RESERVED_ATTRIBUTE_KEYS, ALLOWED_FIREWEAVE_CONTEXT_KEYS, mergeContexts, normalizeContextInput, resolvedContextView, } from './domain/context.js';
+export type { ContextInput, ContextLimits, ContextPolicy } from './domain/context.js';
+export { canonicalizeContext, validateControlPointKey, validateDefaultValue, validateContext, validateTargetingKey, validateInitOptions, } from './domain/validation.js';
+export type { Validated } from './domain/validation.js';
+export type { BackendAdapter, AdapterResolution, AdapterRuntimeFeatures, RegisterTargetOptions, RegisterTargetResult, ResolveOptions, } from './application/ports.js';
+export type { TargetKind } from './domain/target.js';
+export { InMemoryAdapter } from './infrastructure/adapters/inmemory.js';
+export type { InMemoryAdapterOptions, InMemoryFlagDefinition, InMemoryFault } from './infrastructure/adapters/inmemory.js';
+export { FireweaveRemoteAdapter } from './infrastructure/adapters/remote.js';
+export type { FireweaveRemoteAdapterOptions } from './infrastructure/adapters/remote.js';
+export { FireweaveLocalAdapter } from './infrastructure/adapters/local.js';
+export type { FireweaveLocalAdapterOptions } from './infrastructure/adapters/local.js';
+export { DEFAULT_ALLOWED_HOSTS, assertHostAllowed, isLoopbackHostname } from './infrastructure/hosts.js';
+export { FireweaveRuntime, stableStringify, DEFAULT_SHUTDOWN_TIMEOUT_MS } from './application/runtime.js';
+export type { FireweaveRuntimeConfig, EvaluateOptions, ExpectedFlagType } from './application/runtime.js';
+export { FireweaveClient } from './application/client.js';
+export type { ControlPointsApi, FireweaveClientOptions } from './application/client.js';
+export { initFireweave } from './application/mode.js';
+export type { InitFireweaveOptions, InitFireweaveLocalOptions, InitFireweaveRemoteOptions, } from './application/mode.js';