@pikku/core 0.12.107 → 0.12.112

package/dist/function/function-runner.js

@@ -9,9 +9,12 @@ import { parseVersionedId } from '../version.js';
 import { PikkuSessionService } from '../services/user-session-service.js';
 import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js';
 import { verifyScopes } from '../scopes.js';
+import { assertFeatureAvailable } from '../wirings/flag/assert-feature-available.js';
 import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
 import { createInvocationAudit, resolveAuditConfig, } from '../services/audit-service.js';
+import { createInvocationAnalytics } from '../analytics/analytics.js';
+import { LoggerAnalyticsService } from '../analytics/logger-analytics-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { getOrCreatePackageSingletonServices } from '../wirings/addon/addon-runner.js';
 import { resolveAddonAuth, resolveAddonFunctionTarget, resolveAddonScopes, resolveAddonTagMiddleware, } from '../wirings/addon/wire-addon.js';
@@ -209,6 +212,16 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         verifyScopes(addonScopes.length > 0
             ? [...addonScopes, ...(functionScopes ?? [])]
             : functionScopes, session);
+        const featureFlag = funcConfig.featureFlag ?? funcMeta.featureFlag;
+        if (featureFlag) {
+            // The host's source, not the package's: a `featureFlag:` on an addon
+            // function names a flag the consuming application declared and its
+            // operators switch. A package factory builds its own services and has no
+            // reason to carry one, and reading that would leave every addon gate
+            // open.
+            await assertFeatureAvailable(featureFlag, singletonServices.featureFlags ??
+                resolvedSingletonServices.featureFlags, session);
+        }
         let actualData = await data();
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
@@ -228,6 +241,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         });
         let wireServices;
         let invocationAuditLog;
+        let invocationAnalytics;
         try {
             wireServices = (await resolvedCreateWireServices?.(resolvedSingletonServices, invocationWire));
             let services = wireServices && Object.keys(wireServices).length > 0
@@ -240,6 +254,20 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 invocationAuditLog = createInvocationAudit(resolvedSingletonServices.audit, invocationWire, resolvedSingletonServices.logger);
                 services = { ...services, auditLog: invocationAuditLog };
             }
+            // Unconditional, unlike the audit — every function can record. Built on
+            // first access, since most invocations record nothing.
+            if (!services.analytics) {
+                services = { ...services };
+                Object.defineProperty(services, 'analytics', {
+                    get() {
+                        invocationAnalytics ??= createInvocationAnalytics(resolvedSingletonServices.analyticsService ??
+                            new LoggerAnalyticsService(resolvedSingletonServices.logger), invocationWire, resolvedSingletonServices.logger, resolvedSingletonServices.analyticsIdentity);
+                        return invocationAnalytics;
+                    },
+                    configurable: true,
+                    enumerable: true,
+                });
+            }
             const callerPackageName = funcPackageName;
             Object.defineProperty(invocationWire, 'rpc', {
                 get() {
@@ -259,6 +287,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         finally {
             // Flush the runner-installed audit buffer before wire services close.
             await invocationAuditLog?.close();
+            await invocationAnalytics?.close();
             if (wireServices && Object.keys(wireServices).length > 0) {
                 await closeWireServices(resolvedSingletonServices.logger, wireServices);
             }

package/dist/function/functions.types.d.ts

@@ -15,7 +15,7 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessS
     name?: string;
     description?: string;
 };
-export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session"> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
+export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'>>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
@@ -47,7 +47,7 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Re
  * it is never recorded and never replayed.
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (services: Services, data: Data, wire: Wire) => Promise<void> | void;
-export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string> = {
+export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string, FeatureFlagName extends string = string> = {
     /** A human name for this function, shown wherever it is listed rather than called. */
     title?: string;
     /** What the function does. An agent choosing between tools reads this, so it is worth more care than a comment would be. */
@@ -128,6 +128,20 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     auth?: boolean;
     /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
     scopes?: Scope[];
+    /**
+     * The feature this function belongs to. Singular: a function implements part
+     * of one feature, and needing two is a sign it does two things.
+     *
+     * Resolved at runtime on every call, unlike `tags:` — a flag is
+     * meant to be flipped in a running system, so nothing here filters a build.
+     *
+     * Checked for AVAILABILITY only, never capability — if the runner enforced
+     * the capability half a flag would become a second authorization path with
+     * OR-ish semantics against `scopes:`. Authorization is always `scopes:`.
+     * Runs after `scopes:` so an unauthorized caller gets a 403 whether or not
+     * the feature is up, rather than learning that it exists and is off.
+     */
+    featureFlag?: FeatureFlagName;
     /** Checks that run before the body. Grouped names OR together, so any one passing admits the caller; use `scopes` to require rather than offer. */
     permissions?: CorePermissionGroup<PikkuPermission>;
     /** Wraps this function wherever it is called from, unlike wiring middleware which only wraps one route into it. */
@@ -148,5 +162,10 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
  * so an anonymous caller holds none and satisfies none — a sessionless function
  * with scopes rejects every caller it exists to serve. Gate it with
  * `permissions`, which receive the optional session and may pass anonymous.
+ *
+ * `featureFlag` is deliberately NOT omitted. It reads the config snapshot
+ * rather than the session, so it applies identically to a cron task, a queue
+ * worker and a webhook — which is where a kill switch matters most, since
+ * nobody is watching a UI to notice the feature is off.
  */
-export type CorePikkuSessionlessFunctionConfig<PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware, InputSchema, OutputSchema>, 'scopes'>;
+export type CorePikkuSessionlessFunctionConfig<PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, FeatureFlagName extends string = string> = Omit<CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware, InputSchema, OutputSchema, string, FeatureFlagName>, 'scopes'>;

package/dist/middleware/auth-apikey.d.ts

@@ -6,5 +6,5 @@
  */
 export declare const authAPIKey: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
     /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
-    source: "header" | "query" | "all";
+    source: 'header' | 'query' | 'all';
 }>;

package/dist/pikku-state.d.ts

@@ -7,5 +7,5 @@ export declare const resetPikkuState: () => void;
 export declare const getSingletonServices: () => CoreSingletonServices;
 export declare const setSingletonServices: (services: CoreSingletonServices) => void;
 export declare const getCreateWireServices: () => CreateWireServices | undefined;
-export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState["package"]["factories"]>) => void;
+export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState['package']['factories']>) => void;
 export type { PikkuPackageState } from './types/state.types.js';

package/dist/scopes.d.ts

@@ -4,6 +4,17 @@ import type { CoreUserSession } from './types/core.types.js';
  * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
+/**
+ * True when `held` satisfies AT LEAST ONE of `candidates`, with the same
+ * parent/wildcard rules as {@link hasScopes}.
+ *
+ * The OR counterpart to {@link hasScopes}, for a feature flag's `anyOf`: a flag
+ * usually reveals one entry point several roles can reach, so requiring all of
+ * them would hide it from everyone who can actually use it. Fails closed — an
+ * empty or absent `candidates` is satisfied by nothing, because "any of
+ * nothing" has no member that could hold.
+ */
+export declare const hasAnyScope: (candidates: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
  * Throws {@link MissingScopeError} naming the first scope the session does not
  * hold. Fails closed: no session, or a session without `scopes`, satisfies

package/dist/scopes.js

@@ -36,6 +36,23 @@ const firstUnsatisfied = (required, held) => {
  * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export const hasScopes = (required, held) => firstUnsatisfied(required, held) === null;
+/**
+ * True when `held` satisfies AT LEAST ONE of `candidates`, with the same
+ * parent/wildcard rules as {@link hasScopes}.
+ *
+ * The OR counterpart to {@link hasScopes}, for a feature flag's `anyOf`: a flag
+ * usually reveals one entry point several roles can reach, so requiring all of
+ * them would hide it from everyone who can actually use it. Fails closed — an
+ * empty or absent `candidates` is satisfied by nothing, because "any of
+ * nothing" has no member that could hold.
+ */
+export const hasAnyScope = (candidates, held) => {
+    if (!candidates || candidates.length === 0) {
+        return false;
+    }
+    const grants = new Set(held ?? []);
+    return candidates.some((scope) => holds(grants, scope));
+};
 /**
  * Throws {@link MissingScopeError} naming the first scope the session does not
  * hold. Fails closed: no session, or a session without `scopes`, satisfies

package/dist/services/credential-wire-service.d.ts

@@ -42,5 +42,5 @@ export declare function createMiddlewareCredentialWireProps(credentialWire: Pikk
 export declare function createWireServicesCredentialWireProps(credentialWire: PikkuCredentialWireService, allowedNames?: string[]): {
     setCredential: (name: string, value: unknown) => void;
     getCredential: <T = unknown>(name: string) => T | Promise<T | null> | null;
-    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+    getCredentials: () => Promise<Record<string, unknown>> | Record<string, unknown>;
 };

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;