@pikku/core 0.12.107 → 0.12.112

package/dist/wirings/channel/local/local-channel-runner.d.ts

@@ -1,7 +1,7 @@
 import type { CoreChannel, RunChannelOptions } from '../channel.types.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
 import type { PikkuHTTPRequest, PikkuHTTPResponse } from '../../http/http.types.js';
-export declare const runLocalChannel: ({ channelId, request, response, route, skipUserSession, respondWith404, coerceDataFromSchema, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreChannel<unknown, any>, "route">> & RunChannelOptions & {
+export declare const runLocalChannel: ({ channelId, request, response, route, skipUserSession, respondWith404, coerceDataFromSchema, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreChannel<unknown, any>, 'route'>> & RunChannelOptions & {
     channelId: string;
     request?: PikkuHTTPRequest;
     response?: PikkuHTTPResponse;

package/dist/wirings/channel/serverless/serverless-channel-runner.d.ts

@@ -5,6 +5,6 @@ export interface RunServerlessChannelParams<ChannelData> extends RunChannelParam
     channelHandlerFactory: PikkuChannelHandlerFactory;
     channelObject?: unknown;
 }
-export declare const runChannelConnect: ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreChannel<unknown, any>, "route"> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
+export declare const runChannelConnect: ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreChannel<unknown, any>, 'route'> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
 export declare const runChannelDisconnect: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>) => Promise<void>;
 export declare const runChannelMessage: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>, data: unknown) => Promise<unknown>;

package/dist/wirings/cli/channel/cli-approval.d.ts

@@ -6,8 +6,8 @@ import type { ApprovalRequester } from '../../channel/channel-rpc.js';
  */
 export type ApprovalMode = 'prompt' | 'auto' | 'dangerous';
 export declare const APPROVAL_FLAGS: {
-    readonly auto: "--auto-approve";
-    readonly dangerous: "--dangerously-auto-approve";
+    readonly auto: '--auto-approve';
+    readonly dangerous: '--dangerously-auto-approve';
 };
 /**
  * Stripped from argv, not just read: the server owns the command tree and has

package/dist/wirings/flag/assert-feature-available.d.ts

@@ -0,0 +1,15 @@
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { FeatureFlagSource } from '../../services/feature-flag-service.js';
+import type { FlagSubject } from './flag.types.js';
+/**
+ * The runner's half of a `featureFlag:` declaration.
+ *
+ * Availability only. Enforcing the capability half here would make a flag a
+ * second authorization path that ORs against `scopes:`, and the two would
+ * disagree the first time someone widened a flag's `anyOf` to preview it.
+ *
+ * No source registered is a no-op rather than a closed door: a project that has
+ * not wired one yet should not discover it by having every flagged function
+ * start throwing.
+ */
+export declare const assertFeatureAvailable: (key: string, featureFlags: FeatureFlagSource | undefined, session: CoreUserSession | undefined, subject?: FlagSubject) => Promise<void>;

package/dist/wirings/flag/assert-feature-available.js

@@ -0,0 +1,23 @@
+import { FeatureUnavailableError } from '../../errors/errors.js';
+import { resolveFlag } from './resolve-flag.js';
+/**
+ * The runner's half of a `featureFlag:` declaration.
+ *
+ * Availability only. Enforcing the capability half here would make a flag a
+ * second authorization path that ORs against `scopes:`, and the two would
+ * disagree the first time someone widened a flag's `anyOf` to preview it.
+ *
+ * No source registered is a no-op rather than a closed door: a project that has
+ * not wired one yet should not discover it by having every flagged function
+ * start throwing.
+ */
+export const assertFeatureAvailable = async (key, featureFlags, session, subject) => {
+    if (!featureFlags) {
+        return;
+    }
+    const config = await featureFlags.snapshot();
+    const { available } = resolveFlag(key, undefined, session, config, subject);
+    if (!available) {
+        throw new FeatureUnavailableError(key);
+    }
+};

package/dist/wirings/flag/cached-flag-source.d.ts

@@ -0,0 +1,73 @@
+import type { FeatureFlagSource } from '../../services/feature-flag-service.js';
+import type { DeclaredFlag, FlagConfigSnapshot } from './flag.types.js';
+export interface CachedFlagSourceOptions {
+    /**
+     * How long a snapshot is served before it is refreshed, in milliseconds.
+     *
+     * This is the latency of a kill switch, so it is short. It is not zero
+     * because the alternative is a round trip on every call to every flagged
+     * function, and a flag system that costs one is a flag system nobody puts on
+     * a hot path — which is exactly where a kill switch earns its keep.
+     */
+    ttlMs?: number;
+    /**
+     * The declared flags, used to build the cold-start fallback. Omitted leaves
+     * the fallback empty, which resolves every flag as available: a flag absent
+     * from a snapshot fails open.
+     */
+    declared?: readonly DeclaredFlag[];
+}
+/**
+ * The caching every flag source needs, so no adapter has to get it right twice.
+ *
+ * Three layers, in descending order of truth: a fresh read, the last good read,
+ * and the compiled declaration. The middle layer is the one that matters —
+ * dropping straight to the compiled fallback on a blip would switch on every
+ * flag an operator had deliberately left off, which is the opposite of what a
+ * dark launch is for. The compiled fallback is reached only on a cold start
+ * that has never managed a read, where there is nothing better to say.
+ *
+ * Refresh is pull-on-demand rather than a background poller on purpose. A
+ * poller assumes a long-lived process; an isolate on a serverless runtime is
+ * neither long-lived nor allowed to hold a timer between requests, so a vendor
+ * SDK built around one either never refreshes or leaks. Fetching inside the
+ * request that noticed the snapshot was stale works in both places.
+ */
+export declare abstract class CachedFlagSource implements FeatureFlagSource {
+    private cached;
+    private cachedAt;
+    private inflight;
+    /**
+     * Bumped by every `invalidate()`. A read that started before the signal
+     * arrived carries the generation it started in, and stores nothing if that
+     * generation is no longer current — otherwise a webhook that landed
+     * mid-fetch would be answered by the pre-webhook snapshot, stamped fresh,
+     * and the kill switch would sit stale for another whole TTL.
+     */
+    private generation;
+    private fallback;
+    private declared;
+    private readonly ttlMs;
+    constructor(options?: CachedFlagSourceOptions);
+    /** One read of the backing store. Never called concurrently with itself. */
+    protected abstract fetchSnapshot(): Promise<FlagConfigSnapshot>;
+    /** Replaces the cold-start fallback, once the declared set is known. */
+    protected setDeclared(declared: DeclaredFlag[]): void;
+    declaredFlags(): readonly DeclaredFlag[];
+    /**
+     * Drops the cache, so the next read goes to the store.
+     *
+     * Public because the signal usually arrives from outside: PostHog and Unleash
+     * both emit a webhook on a flag change, and an HTTP wiring that receives one
+     * calls this to cut the kill-switch latency from the TTL to delivery time. A
+     * LaunchDarkly stream is the same call from a held-open connection rather
+     * than a request.
+     *
+     * It does not fetch. An eager refetch makes a burst of webhooks N round
+     * trips, and on a serverless runtime the isolate that received the signal may
+     * be gone before anything reads the result. The request that next notices the
+     * cache is empty pays for the read, and it is the one that needs it.
+     */
+    invalidate(): void;
+    snapshot(): Promise<FlagConfigSnapshot>;
+}

package/dist/wirings/flag/cached-flag-source.js

@@ -0,0 +1,96 @@
+import { compiledFallbackSnapshot } from './validate-flag-definitions.js';
+const DEFAULT_TTL_MS = 30_000;
+/**
+ * The caching every flag source needs, so no adapter has to get it right twice.
+ *
+ * Three layers, in descending order of truth: a fresh read, the last good read,
+ * and the compiled declaration. The middle layer is the one that matters —
+ * dropping straight to the compiled fallback on a blip would switch on every
+ * flag an operator had deliberately left off, which is the opposite of what a
+ * dark launch is for. The compiled fallback is reached only on a cold start
+ * that has never managed a read, where there is nothing better to say.
+ *
+ * Refresh is pull-on-demand rather than a background poller on purpose. A
+ * poller assumes a long-lived process; an isolate on a serverless runtime is
+ * neither long-lived nor allowed to hold a timer between requests, so a vendor
+ * SDK built around one either never refreshes or leaks. Fetching inside the
+ * request that noticed the snapshot was stale works in both places.
+ */
+export class CachedFlagSource {
+    cached;
+    cachedAt = 0;
+    inflight;
+    /**
+     * Bumped by every `invalidate()`. A read that started before the signal
+     * arrived carries the generation it started in, and stores nothing if that
+     * generation is no longer current — otherwise a webhook that landed
+     * mid-fetch would be answered by the pre-webhook snapshot, stamped fresh,
+     * and the kill switch would sit stale for another whole TTL.
+     */
+    generation = 0;
+    fallback;
+    declared;
+    ttlMs;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.declared = options.declared ?? [];
+        this.fallback = compiledFallbackSnapshot(this.declared);
+    }
+    /** Replaces the cold-start fallback, once the declared set is known. */
+    setDeclared(declared) {
+        this.declared = declared;
+        this.fallback = compiledFallbackSnapshot(declared);
+    }
+    declaredFlags() {
+        return this.declared;
+    }
+    /**
+     * Drops the cache, so the next read goes to the store.
+     *
+     * Public because the signal usually arrives from outside: PostHog and Unleash
+     * both emit a webhook on a flag change, and an HTTP wiring that receives one
+     * calls this to cut the kill-switch latency from the TTL to delivery time. A
+     * LaunchDarkly stream is the same call from a held-open connection rather
+     * than a request.
+     *
+     * It does not fetch. An eager refetch makes a burst of webhooks N round
+     * trips, and on a serverless runtime the isolate that received the signal may
+     * be gone before anything reads the result. The request that next notices the
+     * cache is empty pays for the read, and it is the one that needs it.
+     */
+    invalidate() {
+        this.cachedAt = 0;
+        this.generation++;
+        this.inflight = undefined;
+    }
+    async snapshot() {
+        if (this.cached && Date.now() - this.cachedAt < this.ttlMs) {
+            return this.cached;
+        }
+        if (!this.inflight) {
+            const generation = this.generation;
+            const read = this.fetchSnapshot().then((snapshot) => {
+                if (generation === this.generation) {
+                    this.cached = snapshot;
+                    this.cachedAt = Date.now();
+                    if (this.inflight === read) {
+                        this.inflight = undefined;
+                    }
+                }
+                return snapshot;
+            });
+            read.catch(() => {
+                if (this.inflight === read) {
+                    this.inflight = undefined;
+                }
+            });
+            this.inflight = read;
+        }
+        try {
+            return await this.inflight;
+        }
+        catch {
+            return this.cached ?? this.fallback;
+        }
+    }
+}

package/dist/wirings/flag/define-feature-flags.d.ts

@@ -0,0 +1,33 @@
+import type { CoreFeatureFlags } from './flag.types.js';
+/**
+ * No-op function for declaring feature flags.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `FeatureFlagName`
+ * union, so `flags.calList` is a compile error rather than a silent `false`.
+ *
+ * That typing is load-bearing rather than a convenience: flags fail closed, so
+ * a typo'd flag reads `false`, hides its feature permanently, and leaves every
+ * test, screenshot and gate green. An untyped key makes a missing product
+ * indistinguishable from a working one.
+ *
+ * Removal is deliberately not destructive. Deleting a declaration leaves the
+ * row in the store, marked undeclared and inert, until `pikku flags prune` —
+ * the same additive contract `defineScope` and `defineSystemRole` have, and for
+ * the same reason: a mid-deploy revocation is not something a code edit should
+ * be able to cause.
+ *
+ * @example
+ * ```typescript
+ * defineFeatureFlags({
+ *   takeInBike: {
+ *     description: 'Book a bike in at the counter',
+ *     anyOf: ['bikes:intake'],
+ *   },
+ *   aiAssistant: {
+ *     description: 'The assistant panel',
+ *     // no anyOf — the switch is the whole answer
+ *   },
+ * })
+ * ```
+ */
+export declare const defineFeatureFlags: (_config: CoreFeatureFlags) => void;

package/dist/wirings/flag/define-feature-flags.js

@@ -0,0 +1,32 @@
+/**
+ * No-op function for declaring feature flags.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `FeatureFlagName`
+ * union, so `flags.calList` is a compile error rather than a silent `false`.
+ *
+ * That typing is load-bearing rather than a convenience: flags fail closed, so
+ * a typo'd flag reads `false`, hides its feature permanently, and leaves every
+ * test, screenshot and gate green. An untyped key makes a missing product
+ * indistinguishable from a working one.
+ *
+ * Removal is deliberately not destructive. Deleting a declaration leaves the
+ * row in the store, marked undeclared and inert, until `pikku flags prune` —
+ * the same additive contract `defineScope` and `defineSystemRole` have, and for
+ * the same reason: a mid-deploy revocation is not something a code edit should
+ * be able to cause.
+ *
+ * @example
+ * ```typescript
+ * defineFeatureFlags({
+ *   takeInBike: {
+ *     description: 'Book a bike in at the counter',
+ *     anyOf: ['bikes:intake'],
+ *   },
+ *   aiAssistant: {
+ *     description: 'The assistant panel',
+ *     // no anyOf — the switch is the whole answer
+ *   },
+ * })
+ * ```
+ */
+export const defineFeatureFlags = (_config) => { };

package/dist/wirings/flag/flag.types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A feature flag: a UI-facing name a client can ask about without knowing
+ * anything about the capability vocabulary.
+ *
+ * The flag is the indirection that keeps scopes a server concern. Returning
+ * `session.scopes` to the client would work and is wrong three times over: it
+ * publishes the vocabulary to every screen, it makes a scope rename a frontend
+ * refactor, and it forces each call site to reimplement parent-grant
+ * resolution — which some will get wrong in the permissive direction.
+ */
+export type CoreFeatureFlag = {
+    /** Surfaced in the console beside the switch. */
+    description?: string;
+    /**
+     * The session satisfies this flag by holding ANY of these — deliberately the
+     * opposite of `scopes:`, which is AND, because a flag usually reveals one
+     * entry point several roles can reach. Named `anyOf` and not `scopes` so the
+     * inverted semantics are visible at the call site.
+     *
+     * Every id must be declared with `defineScope`; the inspector fails the
+     * build otherwise, the same rule `defineSystemRole` already enforces.
+     *
+     * Omitted means no capability constraint — NOT "always on". The switch,
+     * the rollout bucket and any override still apply, which is what makes a
+     * flag usable as a pure kill switch. An explicit `anyOf: []` is a
+     * declaration error: write no key, or write scopes.
+     */
+    anyOf?: string[];
+};
+/**
+ * Feature flags to declare, keyed by name. A key must be non-empty and must
+ * not contain `:` — that separator belongs to scopes, and a flag that looks
+ * like a scope id invites exactly the confusion this exists to prevent.
+ */
+export type CoreFeatureFlags = Record<string, CoreFeatureFlag>;
+export type FeatureFlagDefinitionMeta = {
+    name: string;
+    description?: string;
+    anyOf?: string[];
+    sourceFile?: string;
+};
+export type FeatureFlagDefinitions = FeatureFlagDefinitionMeta[];
+export type FeatureFlagDefinitionsMeta = Record<string, FeatureFlagDefinitionMeta>;
+/** A declared flag, ready to sync into a flag store. */
+export type DeclaredFlag = {
+    name: string;
+    description?: string;
+    anyOf?: string[];
+};
+/**
+ * Who a rollout bucket and an override are keyed on.
+ *
+ * The organization is preferred over the user wherever both are known: two
+ * colleagues on a screen-share seeing different UIs is a support ticket.
+ */
+export type FlagSubject = {
+    organizationId?: string;
+    userId?: string;
+};
+/** The runtime half of one flag: what an operator set, not what code declared. */
+export type FlagConfig = {
+    enabled: boolean;
+    /** 0–100, or null for no rollout constraint. */
+    rolloutPercent: number | null;
+    /**
+     * Per-subject short-circuits, keyed by subject id. The one genuine OR in the
+     * model: "off for everyone, but these three orgs see it." An override wins
+     * over both the switch and the bucket, in either direction, so QA can enter a
+     * 5% rollout and a single tenant can be excluded from a bad one.
+     */
+    overrides: Record<string, boolean>;
+};
+/**
+ * The global config half, keyed by flag name. One small blob shared by every
+ * user, which is why it is not baked into the session: writing it per-session
+ * would make killing a feature an unbounded fan-out over every active session,
+ * with users on both sides of the flip for its duration.
+ */
+export type FlagConfigSnapshot = Record<string, FlagConfig>;
+/**
+ * A flag resolves to two booleans, not one. One bit cannot distinguish "you may
+ * not" (a 403, the caller's own situation) from "nobody may right now" (a 503,
+ * ours) — and collapsing them is what leaves a kill switch with nothing to
+ * enforce.
+ */
+export type FlagState = {
+    /** The feature is switched on at all. Global, caller-blind, and the only half
+     *  the runner enforces. */
+    available: boolean;
+    /** This session holds a satisfying scope. Advisory to the client; hides UI and
+     *  protects nothing, forever. */
+    capable: boolean;
+};
+/** What a client renders on. */
+export type ResolvedFlag = FlagState & {
+    show: boolean;
+};

package/dist/wirings/flag/flag.types.js

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

package/dist/wirings/flag/index.d.ts

@@ -0,0 +1,7 @@
+export { CachedFlagSource } from './cached-flag-source.js';
+export type { CachedFlagSourceOptions } from './cached-flag-source.js';
+export { assertFeatureAvailable } from './assert-feature-available.js';
+export { defineFeatureFlags } from './define-feature-flags.js';
+export { bucketOf, resolveFlag, resolveFlagForClient, resolveFlagsForClient, subjectIdOf, } from './resolve-flag.js';
+export { compiledFallbackSnapshot, flattenFeatureFlagDefinitions, validateAndBuildFeatureFlagDefinitionsMeta, } from './validate-flag-definitions.js';
+export type { CoreFeatureFlag, CoreFeatureFlags, DeclaredFlag, FeatureFlagDefinitionMeta, FeatureFlagDefinitions, FeatureFlagDefinitionsMeta, FlagConfig, FlagConfigSnapshot, FlagState, FlagSubject, ResolvedFlag, } from './flag.types.js';

package/dist/wirings/flag/index.js

@@ -0,0 +1,5 @@
+export { CachedFlagSource } from './cached-flag-source.js';
+export { assertFeatureAvailable } from './assert-feature-available.js';
+export { defineFeatureFlags } from './define-feature-flags.js';
+export { bucketOf, resolveFlag, resolveFlagForClient, resolveFlagsForClient, subjectIdOf, } from './resolve-flag.js';
+export { compiledFallbackSnapshot, flattenFeatureFlagDefinitions, validateAndBuildFeatureFlagDefinitionsMeta, } from './validate-flag-definitions.js';

package/dist/wirings/flag/resolve-flag.d.ts

@@ -0,0 +1,52 @@
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { DeclaredFlag, FlagConfigSnapshot, FlagState, FlagSubject, ResolvedFlag } from './flag.types.js';
+/**
+ * FNV-1a over `${flag}:${subject}`.
+ *
+ * Salted by flag key so two flags at 50% do not select the same half and
+ * concurrent rollouts stay independent. Sync and non-crypto on purpose:
+ * WebCrypto's digest is async and this runs inside resolution, which does no
+ * I/O and cannot await.
+ */
+export declare const bucketOf: (flag: string, subject: string) => number;
+/**
+ * The subject a bucket and an override are keyed on.
+ *
+ * Organization first: a percentage rollout that splits colleagues inside one
+ * account is a support ticket, not an experiment.
+ */
+export declare const subjectIdOf: (subject: FlagSubject | undefined) => string | undefined;
+/**
+ * Resolves one flag from the session and the config snapshot. Pure, sync, and
+ * the only thing on the request path — the I/O is the snapshot read, which the
+ * caller has already done and which implementations cache.
+ *
+ * `subject` is passed explicitly rather than read off the session because the
+ * subject is not always in one: a queue worker, a cron task or a workflow step
+ * knows its organization from its input, and resolving those against no subject
+ * would skip every per-org override and deny an org that was explicitly
+ * granted. Where it is omitted the session is used.
+ *
+ * A flag absent from the snapshot fails OPEN on availability, falling back to
+ * the declaration compiled into the bundle. Treating an unreadable config as
+ * everything-off turns a transient store blip into a total outage of your own
+ * product. It is safe only because `capable` comes from the session and
+ * `scopes:` is untouched, so failing open cannot expose anything the caller was
+ * not already authorized for.
+ */
+export declare const resolveFlag: (key: string, anyOf: readonly string[] | undefined, session: CoreUserSession | undefined, config: FlagConfigSnapshot, subject?: FlagSubject) => FlagState;
+/** {@link resolveFlag} plus the `show` a client renders on. */
+export declare const resolveFlagForClient: (key: string, anyOf: readonly string[] | undefined, session: CoreUserSession | undefined, config: FlagConfigSnapshot, subject?: FlagSubject) => ResolvedFlag;
+/**
+ * Every declared flag resolved for one caller, as a client consumes them.
+ *
+ * A client asks once per session and reads the map synchronously after, rather
+ * than asking per flag: a flag is checked wherever a component renders, and a
+ * request from each would put the network in front of a paint. The snapshot is
+ * already in isolate memory, so this is a map over a cached object.
+ *
+ * Bare booleans, not `FlagState`. `show` is the collapse of the two halves, and
+ * sending them apart would tell a client which features exist but are dark —
+ * a roadmap nobody meant to publish.
+ */
+export declare const resolveFlagsForClient: (declared: readonly DeclaredFlag[], session: CoreUserSession | undefined, config: FlagConfigSnapshot, subject?: FlagSubject) => Record<string, boolean>;

package/dist/wirings/flag/resolve-flag.js

@@ -0,0 +1,90 @@
+import { hasAnyScope } from '../../scopes.js';
+/**
+ * FNV-1a over `${flag}:${subject}`.
+ *
+ * Salted by flag key so two flags at 50% do not select the same half and
+ * concurrent rollouts stay independent. Sync and non-crypto on purpose:
+ * WebCrypto's digest is async and this runs inside resolution, which does no
+ * I/O and cannot await.
+ */
+export const bucketOf = (flag, subject) => {
+    let h = 0x811c9dc5;
+    const s = `${flag}:${subject}`;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h % 10_000;
+};
+/**
+ * The subject a bucket and an override are keyed on.
+ *
+ * Organization first: a percentage rollout that splits colleagues inside one
+ * account is a support ticket, not an experiment.
+ */
+export const subjectIdOf = (subject) => {
+    const usable = (id) => id === undefined || id === '' ? undefined : id;
+    return usable(subject?.organizationId) ?? usable(subject?.userId);
+};
+/**
+ * Resolves one flag from the session and the config snapshot. Pure, sync, and
+ * the only thing on the request path — the I/O is the snapshot read, which the
+ * caller has already done and which implementations cache.
+ *
+ * `subject` is passed explicitly rather than read off the session because the
+ * subject is not always in one: a queue worker, a cron task or a workflow step
+ * knows its organization from its input, and resolving those against no subject
+ * would skip every per-org override and deny an org that was explicitly
+ * granted. Where it is omitted the session is used.
+ *
+ * A flag absent from the snapshot fails OPEN on availability, falling back to
+ * the declaration compiled into the bundle. Treating an unreadable config as
+ * everything-off turns a transient store blip into a total outage of your own
+ * product. It is safe only because `capable` comes from the session and
+ * `scopes:` is untouched, so failing open cannot expose anything the caller was
+ * not already authorized for.
+ */
+export const resolveFlag = (key, anyOf, session, config, subject) => {
+    const capable = anyOf === undefined ? true : hasAnyScope(anyOf, session?.scopes);
+    const row = config[key];
+    if (!row) {
+        return { available: true, capable };
+    }
+    const id = subjectIdOf(subject) ??
+        subjectIdOf({ organizationId: session?.orgId, userId: session?.userId });
+    const override = id === undefined ? undefined : row.overrides[id];
+    if (override !== undefined) {
+        return { available: override, capable };
+    }
+    // No subject skips the bucket rather than failing it. A sessionless caller
+    // has nothing to hash, and hashing a constant would put every cron run in one
+    // bucket — making a 10% rollout either 0% or 100% of background work at
+    // random. A percentage is a statement about users; background work is either
+    // on or off.
+    const inBucket = row.rolloutPercent === null || id === undefined
+        ? true
+        : bucketOf(key, id) < Math.round(row.rolloutPercent * 100);
+    return { available: row.enabled && inBucket, capable };
+};
+/** {@link resolveFlag} plus the `show` a client renders on. */
+export const resolveFlagForClient = (key, anyOf, session, config, subject) => {
+    const state = resolveFlag(key, anyOf, session, config, subject);
+    return { ...state, show: state.available && state.capable };
+};
+/**
+ * Every declared flag resolved for one caller, as a client consumes them.
+ *
+ * A client asks once per session and reads the map synchronously after, rather
+ * than asking per flag: a flag is checked wherever a component renders, and a
+ * request from each would put the network in front of a paint. The snapshot is
+ * already in isolate memory, so this is a map over a cached object.
+ *
+ * Bare booleans, not `FlagState`. `show` is the collapse of the two halves, and
+ * sending them apart would tell a client which features exist but are dark —
+ * a roadmap nobody meant to publish.
+ */
+export const resolveFlagsForClient = (declared, session, config, subject) => Object.fromEntries(declared.map((flag) => [
+    flag.name,
+    resolveFlagForClient(flag.name, flag.anyOf, session, config, subject)
+        .show,
+]));

package/dist/wirings/flag/validate-flag-definitions.d.ts

@@ -0,0 +1,26 @@
+import type { DeclaredFlag, FeatureFlagDefinitions, FeatureFlagDefinitionsMeta, FlagConfigSnapshot } from './flag.types.js';
+/**
+ * The declared flags as a flat list, deduplicated by name.
+ *
+ * A flag may legitimately be declared more than once — an addon and its host
+ * app both contributing one — and
+ * {@link validateAndBuildFeatureFlagDefinitionsMeta} has already guaranteed
+ * those declarations are identical.
+ */
+export declare const flattenFeatureFlagDefinitions: (definitions: FeatureFlagDefinitions) => DeclaredFlag[];
+/**
+ * Validates declared flags and keys them by name.
+ *
+ * Definitions sharing a name must name the same scope set; a conflicting
+ * redeclaration is a hard error naming both source files. Order within `anyOf`
+ * is not significant.
+ */
+export declare function validateAndBuildFeatureFlagDefinitionsMeta(definitions: FeatureFlagDefinitions): FeatureFlagDefinitionsMeta;
+/**
+ * The snapshot a flag source falls back to when its store cannot be read: every
+ * declared flag on, no rollout, no overrides.
+ *
+ * This is the compiled declaration, not a database read — putting a fallback
+ * query on the request path is how a slow store becomes a slow product.
+ */
+export declare const compiledFallbackSnapshot: (flags: readonly DeclaredFlag[]) => FlagConfigSnapshot;