@pikku/core 0.12.106 → 0.12.111

package/dist/services/feature-flag-service.d.ts

@@ -0,0 +1,100 @@
+import type { DeclaredFlag, FlagConfigSnapshot, FlagSubject } from '../wirings/flag/flag.types.js';
+/**
+ * The read half of feature flags, and the only half on the request path.
+ *
+ * Split from {@link FeatureFlagStore} so a third-party provider — PostHog,
+ * Unleash, LaunchDarkly — can back flags without pretending to implement an
+ * administration surface it does not own. Their UI is the operator surface;
+ * writing flags back through their management API means two systems own the
+ * same rows, and an implementation that throws from six methods is a console
+ * full of buttons that 500.
+ */
+export interface FeatureFlagSource {
+    /**
+     * The global config half: one small blob shared by every user, never
+     * per-user data.
+     *
+     * Implementations MUST cache this in isolate memory and MUST fall back to the
+     * compiled declaration when the backing store cannot be read — never to a
+     * database query, which would put I/O on the request path this design exists
+     * to keep clear. See `compiledFallbackSnapshot`.
+     */
+    snapshot(): Promise<FlagConfigSnapshot>;
+    /**
+     * The flags the running app declares, where the implementation was told.
+     *
+     * Optional because it is not on the request path: resolution reads the
+     * snapshot, and a declaration absent from it already fails open. It exists so
+     * an administration surface can report the drift a provider cannot fix for
+     * itself — a flag declared in code that nobody created in PostHog resolves as
+     * on for everyone, and that is worth seeing before production finds it.
+     */
+    declaredFlags?(): readonly DeclaredFlag[];
+}
+/** One flag as an administration surface sees it. */
+export type FlagRow = DeclaredFlag & {
+    enabled: boolean;
+    rolloutPercent: number | null;
+    /**
+     * False when the flag's declaration has been removed from code but its row
+     * survives: still switchable, no longer offered, awaiting `pikku flags
+     * prune`. Never a silent revoke.
+     */
+    declared: boolean;
+};
+/**
+ * One override, as an administration surface sees it.
+ *
+ * Carries the subject's kind, which resolution does not: by the time a flag is
+ * resolved the organization and the user are one opaque string, and only a
+ * screen rendering the row needs to say which it was.
+ */
+export type FlagOverrideRow = {
+    /** The organization or user this override pins, as an opaque id. */
+    subjectId: string;
+    /** Which of the two `subjectId` is — `organization` or `user`. */
+    subjectKind: string;
+    /** Whether the subject is pinned on or pinned off, past the rollout either way. */
+    enabled: boolean;
+    /** The user who wrote the override, where the store recorded one. */
+    grantedBy?: string;
+    /** When it was written, as an ISO-8601 instant, where the store recorded one. */
+    grantedAt?: string;
+};
+/**
+ * The write half: the declaration lifecycle plus the operator controls.
+ *
+ * Implemented by a store pikku owns. Absent when flags come from a provider,
+ * which is what makes the console's Flags tab read-only rather than lying.
+ */
+export interface FeatureFlagStore extends FeatureFlagSource {
+    /**
+     * Registers the declared vocabulary. Additive on the same terms as
+     * `syncScopes`: a removed declaration leaves the row marked `declared: false`
+     * rather than deleting an operator's switch on deploy.
+     *
+     * A flag's description and `anyOf` *are* re-synced, because that is the
+     * declaration's whole content — editing it is how you change what the flag
+     * means, and the deploy is when it takes effect. `enabled`, the rollout and
+     * every override are the operator's, and are never touched.
+     */
+    syncFlags(flags: DeclaredFlag[]): Promise<void>;
+    listFlags(): Promise<FlagRow[]>;
+    /**
+     * One flag's overrides, in full.
+     *
+     * Not folded into {@link listFlags}: the overrides are unbounded per flag
+     * while the list is one row each, and a screen that reads every override of
+     * every flag to render a board would grow with the wrong number.
+     */
+    listOverrides(key: string): Promise<FlagOverrideRow[]>;
+    setEnabled(key: string, enabled: boolean, actor?: string, note?: string): Promise<void>;
+    /** `percent` is 0–100, or null to remove the rollout constraint. */
+    setRollout(key: string, percent: number | null, actor?: string): Promise<void>;
+    setOverride(key: string, subject: FlagSubject, enabled: boolean, actor?: string): Promise<void>;
+    clearOverride(key: string, subject: FlagSubject): Promise<void>;
+    /** Flags in the store with no declaration left in code; powers `pikku flags audit`. */
+    findStaleFlags(): Promise<string[]>;
+    /** Removes undeclared flags and their overrides. */
+    pruneFlags(): Promise<string[]>;
+}

package/dist/services/feature-flag-service.js

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

package/dist/services/index.d.ts

@@ -47,6 +47,7 @@ export type { VariableMeta } from './typed-variables-service.js';
 export type { MetaService } from './meta-service.js';
 export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.js';
+export type { FeatureFlagSource, FeatureFlagStore, FlagRow, FlagOverrideRow, } from './feature-flag-service.js';
 export type { IsSystemRole } from './system-role-guard.js';
 export { NoopAuditService, createInvocationAudit } from './audit-service.js';
 export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditService, AuditUserIdentity, ResolvedAuditConfig, } from './audit-service.js';

package/dist/services/meta-service.d.ts

@@ -9,6 +9,8 @@ import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
 import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
 import type { ResolvedPersona } from './personas-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
+import type { FeatureFlagDefinitionsMeta } from '../wirings/flag/flag.types.js';
+import type { AnalyticsEventsMeta } from '../analytics/analytics.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
 import type { CredentialDefinitionsMeta } from '../wirings/credential/credential.types.js';
@@ -152,6 +154,16 @@ export interface MetaService {
      * seed granted from rather than a second one.
      */
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    /**
+     * The flags declared with `defineFeatureFlags`, keyed by name.
+     *
+     * The declaration half only. What an operator set — the switch, the rollout,
+     * the overrides — lives in the flag store and is read through the admin
+     * surface, because it changes without a deploy and this does not.
+     */
+    getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;
+    /** The events declared with `defineAnalyticsEvents`, keyed by name. */
+    getAnalyticsMeta(): Promise<AnalyticsEventsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
@@ -182,6 +194,8 @@ export declare class LocalMetaService implements MetaService {
     private workflowMetaCache;
     private personasMetaCache;
     private systemRolesMetaCache;
+    private featureFlagsMetaCache;
+    private analyticsMetaCache;
     private featuresMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
@@ -216,6 +230,8 @@ export declare class LocalMetaService implements MetaService {
     getWorkflowMeta(): Promise<WorkflowsMeta>;
     getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
     getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
+    getFeatureFlagsMeta(): Promise<FeatureFlagDefinitionsMeta>;
+    getAnalyticsMeta(): Promise<AnalyticsEventsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;

package/dist/services/meta-service.js

@@ -15,6 +15,8 @@ export class LocalMetaService {
     workflowMetaCache = null;
     personasMetaCache = null;
     systemRolesMetaCache = null;
+    featureFlagsMetaCache = null;
+    analyticsMetaCache = null;
     featuresMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
@@ -111,6 +113,8 @@ export class LocalMetaService {
         this.workflowMetaCache = null;
         this.personasMetaCache = null;
         this.systemRolesMetaCache = null;
+        this.featureFlagsMetaCache = null;
+        this.analyticsMetaCache = null;
         this.featuresMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
@@ -270,6 +274,21 @@ export class LocalMetaService {
         this.systemRolesMetaCache = content ? JSON.parse(content) : {};
         return this.systemRolesMetaCache;
     }
+    async getFeatureFlagsMeta() {
+        if (this.featureFlagsMetaCache)
+            return this.featureFlagsMetaCache;
+        // Beside the scopes their `anyOf` names, which is where codegen writes it.
+        const content = await this.readFile('scopes/pikku-flags-meta.gen.json');
+        this.featureFlagsMetaCache = content ? JSON.parse(content) : {};
+        return this.featureFlagsMetaCache;
+    }
+    async getAnalyticsMeta() {
+        if (this.analyticsMetaCache)
+            return this.analyticsMetaCache;
+        const content = await this.readFile('analytics/pikku-analytics-meta.gen.json');
+        this.analyticsMetaCache = content ? JSON.parse(content) : {};
+        return this.analyticsMetaCache;
+    }
     async getFeaturesMeta() {
         if (this.featuresMetaCache)
             return this.featuresMetaCache;

package/dist/services/webhook-service.d.ts

@@ -92,8 +92,13 @@ export declare abstract class WebhookService {
     verify(secret: string, signature: string, body: string): boolean;
     /**
      * The three methods below are optional capability: the default queue-only
-     * service keeps no history and throws, and a store-backed implementation
-     * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
+     * service keeps no history, and a store-backed implementation (e.g.
+     * `KyselyWebhookService` in `@pikku/kysely`) overrides them.
+     *
+     * Only the write throws. A write that goes nowhere loses the caller's data,
+     * so it has to say so; a read of a history nobody keeps is honestly empty,
+     * and throwing there turns the console's webhooks page into an error on
+     * every app that has not opted into persistence.
      */
     recordAttempt(_deliveryId: string, _result: WebhookAttemptResult): Promise<void>;
     /** Most recent first. */

package/dist/services/webhook-service.js

@@ -14,17 +14,22 @@ export class WebhookService {
     }
     /**
      * The three methods below are optional capability: the default queue-only
-     * service keeps no history and throws, and a store-backed implementation
-     * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
+     * service keeps no history, and a store-backed implementation (e.g.
+     * `KyselyWebhookService` in `@pikku/kysely`) overrides them.
+     *
+     * Only the write throws. A write that goes nowhere loses the caller's data,
+     * so it has to say so; a read of a history nobody keeps is honestly empty,
+     * and throwing there turns the console's webhooks page into an error on
+     * every app that has not opted into persistence.
      */
     recordAttempt(_deliveryId, _result) {
         throw new NotImplementedError('webhook delivery persistence is not configured');
     }
     /** Most recent first. */
-    listDeliveries(_opts) {
-        throw new NotImplementedError('webhook delivery persistence is not configured');
+    async listDeliveries(_opts) {
+        return [];
     }
-    getDelivery(_deliveryId) {
-        throw new NotImplementedError('webhook delivery persistence is not configured');
+    async getDelivery(_deliveryId) {
+        return null;
     }
 }

package/dist/testing/service-tests/agent-run-service-tests.d.ts

@@ -1,10 +1,10 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
-export declare const defineAgentRunServiceTests: (name: string, agentRunService: NonNullable<ServiceTestConfig["services"]["agentRunService"]>, 
+export declare const defineAgentRunServiceTests: (name: string, agentRunService: NonNullable<ServiceTestConfig['services']['agentRunService']>, 
 /**
  * Thread-ownership is a property of the two services together — the run
  * service lists what the storage service owns — so that half of the suite
  * only runs when a backend supplies both. Passed explicitly rather than
  * closed over, so the dependency is visible in the signature.
  */
-agentStorageService?: ServiceTestConfig["services"]["agentStorageService"]) => void;
+agentStorageService?: ServiceTestConfig['services']['agentStorageService']) => void;

package/dist/testing/service-tests/agent-storage-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `agentStorageService`. Runs only when a backend supplies one. */
-export declare const defineAiStorageServiceTests: (name: string, agentStorageService: NonNullable<ServiceTestConfig["services"]["agentStorageService"]>) => void;
+export declare const defineAiStorageServiceTests: (name: string, agentStorageService: NonNullable<ServiceTestConfig['services']['agentStorageService']>) => void;

package/dist/testing/service-tests/channel-store-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `channelStore`. Runs only when a backend supplies one. */
-export declare const defineChannelStoreTests: (name: string, channelStore: NonNullable<ServiceTestConfig["services"]["channelStore"]>) => void;
+export declare const defineChannelStoreTests: (name: string, channelStore: NonNullable<ServiceTestConfig['services']['channelStore']>) => void;

package/dist/testing/service-tests/credential-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `credentialService`. Runs only when a backend supplies one. */
-export declare const defineCredentialServiceTests: (name: string, credentialService: NonNullable<ServiceTestConfig["services"]["credentialService"]>) => void;
+export declare const defineCredentialServiceTests: (name: string, credentialService: NonNullable<ServiceTestConfig['services']['credentialService']>) => void;

package/dist/testing/service-tests/deployment-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `deploymentService`. Runs only when a backend supplies one. */
-export declare const defineDeploymentServiceTests: (name: string, deploymentService: NonNullable<ServiceTestConfig["services"]["deploymentService"]>) => void;
+export declare const defineDeploymentServiceTests: (name: string, deploymentService: NonNullable<ServiceTestConfig['services']['deploymentService']>) => void;

package/dist/testing/service-tests/event-hub-store-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `eventHubStore`. Runs only when a backend supplies one. */
-export declare const defineEventHubStoreTests: (name: string, eventHubStore: NonNullable<ServiceTestConfig["services"]["eventHubStore"]>) => void;
+export declare const defineEventHubStoreTests: (name: string, eventHubStore: NonNullable<ServiceTestConfig['services']['eventHubStore']>) => void;

package/dist/testing/service-tests/secret-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `secretService`. Runs only when a backend supplies one. */
-export declare const defineSecretServiceTests: (name: string, secretService: NonNullable<ServiceTestConfig["services"]["secretService"]>) => void;
+export declare const defineSecretServiceTests: (name: string, secretService: NonNullable<ServiceTestConfig['services']['secretService']>) => void;

package/dist/testing/service-tests/session-store-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `sessionStore`. Runs only when a backend supplies one. */
-export declare const defineSessionStoreTests: (name: string, sessionStore: NonNullable<ServiceTestConfig["services"]["sessionStore"]>) => void;
+export declare const defineSessionStoreTests: (name: string, sessionStore: NonNullable<ServiceTestConfig['services']['sessionStore']>) => void;

package/dist/testing/service-tests/workflow-run-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `workflowRunService`. Runs only when a backend supplies one. */
-export declare const defineWorkflowRunServiceTests: (name: string, workflowRunService: NonNullable<ServiceTestConfig["services"]["workflowRunService"]>) => void;
+export declare const defineWorkflowRunServiceTests: (name: string, workflowRunService: NonNullable<ServiceTestConfig['services']['workflowRunService']>) => void;

package/dist/testing/service-tests/workflow-service-tests.d.ts

@@ -1,3 +1,3 @@
 import type { ServiceTestConfig } from '../service-tests.js';
 /** Conformance suite for `workflowService`. Runs only when a backend supplies one. */
-export declare const defineWorkflowServiceTests: (name: string, workflowService: NonNullable<ServiceTestConfig["services"]["workflowService"]>) => void;
+export declare const defineWorkflowServiceTests: (name: string, workflowService: NonNullable<ServiceTestConfig['services']['workflowService']>) => void;

package/dist/types/core.types.d.ts

@@ -38,7 +38,9 @@ import type { MetaService } from '../services/meta-service.js';
 import type { CoverageService } from '../services/v8-coverage-service.js';
 import type { SessionStore } from '../services/session-store.js';
 import type { ScopeService } from '../services/scope-service.js';
+import type { FeatureFlagSource } from '../services/feature-flag-service.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
+import type { AnalyticsLog, AnalyticsIdentityResolver, AnalyticsService } from '../analytics/analytics.types.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 /**
  * Runtime pool tuning for the Postgres adapter. The connection string stays
@@ -145,6 +147,20 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     /** V8 precise-coverage collector (`pikku dev --coverage` only) */
     coverageService?: CoverageService;
     audit?: AuditService;
+    /** Where product-analytics events go; unset means the logger. */
+    analyticsService?: AnalyticsService;
+    /**
+     * Resolves the browser-originated half of an event's identity — vendor ids
+     * and consent — from the wire. Unset means a sink sees only what the session
+     * carries, which is enough for a product-analytics tool and not enough for an
+     * ad platform.
+     */
+    analyticsIdentity?: AnalyticsIdentityResolver;
+    /**
+     * Request-scoped buffer writing into `analyticsService`. Narrow it to the
+     * app's own event union in `SingletonServices` to type `record()`.
+     */
+    analytics?: AnalyticsLog;
     /**
      * Request-scoped audit buffer that writes into `audit` (the durable sink).
      * Returned as a wire service so the runner flushes it via `close()` when the
@@ -158,6 +174,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      * never by the function runner.
      */
     scopeService?: ScopeService;
+    /**
+     * The global feature-flag config, read by the function runner to enforce a
+     * flag's availability. Inert when absent: a project that declares no flag
+     * carries nothing, and a `featureFlag:` with no source registered is a
+     * no-op rather than a closed door.
+     */
+    featureFlags?: FeatureFlagSource;
     /**
      * Built once by the factory an auth package registers and injected by the
      * generated `pikkuServices` wrapper — service factories must not return it

package/dist/wirings/agent/agent-rpc.d.ts

@@ -12,4 +12,4 @@ export type AgentRPCOptions = {
  * to the runner and stream code it delegates to, instead of a wing of the RPC
  * primitive.
  */
-export declare const createAgentRPC: (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC["agent"];
+export declare const createAgentRPC: (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC['agent'];

package/dist/wirings/agent/agent-turn.d.ts

@@ -30,10 +30,10 @@ export declare const toAccumulatedStep: (stepResult: StepResult) => {
         outputTokens: number;
     };
     toolCalls: {
-        error?: string | undefined;
         name: string;
         args: Record<string, unknown>;
         result: string;
+        error?: string | undefined;
     }[];
 };
 type PendingApproval = {

package/dist/wirings/agent-scorer/agent-scorer-live.d.ts

@@ -8,7 +8,7 @@ import { type ScorerInput } from './agent-scorer.types.js';
  * also strictly best-effort: the client already has its answer, so nothing here
  * may fail the run.
  */
-export declare const scoreFinishedRun: (run: ScorerInput, services: Pick<CoreSingletonServices, "logger"> & {
+export declare const scoreFinishedRun: (run: ScorerInput, services: Pick<CoreSingletonServices, 'logger'> & {
     queueService?: {
         add: (queueName: string, data: unknown) => Promise<any>;
     };

package/dist/wirings/channel/channel-common.d.ts

@@ -6,7 +6,7 @@ export declare const runChannelLifecycleWithMiddleware: ({ channelConfig, meta,
     channelConfig: CoreChannel<unknown, any>;
     meta: ChannelMessageMeta;
     lifecycleConfig: any;
-    lifecycleType: "connect" | "disconnect";
+    lifecycleType: 'connect' | 'disconnect';
     services: CoreSingletonServices;
     channel: any;
     data?: unknown;

package/dist/wirings/channel/channel-rpc-validators.d.ts

@@ -5,10 +5,10 @@ import type { ChannelRPCValidator } from './channel-rpc.types.js';
  * declared return type — the same one an agent tool or an HTTP response is
  * checked against.
  */
-export declare const createChannelRPCResultValidator: (singletonServices: Pick<CoreSingletonServices, "logger" | "schema">, packageName?: string | null) => ChannelRPCValidator;
+export declare const createChannelRPCResultValidator: (singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>, packageName?: string | null) => ChannelRPCValidator;
 /**
  * Checks outbound arguments against the declared input type. Unlike the result
  * check this is not a boundary — it catches version drift, where a server built
  * against a newer capability signature calls a client that predates it.
  */
-export declare const createChannelRPCInputValidator: (singletonServices: Pick<CoreSingletonServices, "logger" | "schema">, packageName?: string | null) => ChannelRPCValidator;
+export declare const createChannelRPCInputValidator: (singletonServices: Pick<CoreSingletonServices, 'logger' | 'schema'>, packageName?: string | null) => ChannelRPCValidator;

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

@@ -1,7 +1,7 @@
 import type { SessionService } from '../../services/user-session-service.js';
 import type { ChannelMeta, CoreChannel, RunChannelOptions, RunChannelParams } from './channel.types.js';
 export declare const wireChannel: <In, Channel extends string, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>(channel: CoreChannel<In, Channel, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>) => void;
-export declare const openChannel: ({ route, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, "route"> & RunChannelParams<unknown> & {
+export declare const openChannel: ({ route, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, 'route'> & RunChannelParams<unknown> & {
     userSession: SessionService<any>;
 } & RunChannelOptions) => Promise<{
     openingData: unknown;

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>;
+}