@pikku/core 0.12.71 → 0.12.74

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

@@ -12,7 +12,7 @@ import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js
 import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js';
 import type { PikkuCLI } from '../wirings/cli/cli.types.js';
 import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowService, WorkflowServiceConfig, WorkflowStepWire } from '../wirings/workflow/workflow.types.js';
-import type { PikkuBrowserWire, PikkuScenarioStepWire } from '../wirings/workflow/scenario-step.types.js';
+import type { PikkuBrowserWire, PikkuScenarioStepWire, ScenarioStepKind, ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js';
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js';
 import type { PikkuGateway } from '../wirings/gateway/gateway.types.js';
@@ -20,7 +20,7 @@ import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
-import type { ScenarioActorOf, ScenarioActors } from '../services/scenario-actors-service.js';
+import type { ScenarioPersonaOf, ScenarioPersonas } from '../services/personas-service.js';
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
@@ -44,12 +44,6 @@ export interface FunctionWiresMeta {
     optimized: boolean;
     wires: string[];
 }
-/**
- * Metadata for middleware at any level
- * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
- * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
- * - type: 'wire' = Wire-level individual middleware
- */
 export type MiddlewareMetadata = {
     type: 'http';
     route: string;
@@ -62,16 +56,8 @@ export type MiddlewareMetadata = {
     inline?: boolean;
 };
 /**
- * Metadata for permissions at any level
- * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
- * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
- * - type: 'wire' = Wire-level individual permission
- */
-/**
- * A reference to a permission function a function declares, resolved by name.
- * Used at filter time (e.g. listing agent tools) to run the session-only
- * (pikkuAuth) predicates without request data. Permissions are function-scoped
- * only — there are no wire- or tag-level permission references.
+ * A reference to a permission function, resolved by name. Function-scoped
+ * only: there are no wire- or tag-level permission references.
  */
 export type PermissionMetadata = {
     type: 'wire';
@@ -85,21 +71,28 @@ export type FunctionRuntimeMeta = {
     /** Scopes the session must hold to run this function. All are required (AND). */
     scopes?: string[];
     expose?: boolean;
+    /**
+     * A sessionless function's own `auth: true`. `sessionless` carries the
+     * baseline — a `pikkuFunc` always requires a session — and this carries the
+     * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
+     * know whether a function is gated without running it.
+     */
+    auth?: boolean;
+    /**
+     * The author's declaration that this function authorizes callers in its own
+     * body. Carries no runtime effect — it records a gate codegen cannot see, so
+     * an audit is not left to guess whether a sessionless function is open.
+     */
+    selfAuthenticated?: boolean;
     remote?: boolean;
     /**
-     * A step RPC: a name dispatched by a scenario run and refused everywhere
-     * else. It sits alongside `expose` (public) and `remote` as a kind of RPC
-     * rather than a separate concept — a step is invoked by name exactly as an
-     * RPC is, which is why a run records the step function in its `rpcName`.
-     * What makes it its own kind is that it is never network-callable: a step
-     * may drive a browser or assert against fixtures.
+     * A step RPC: invoked by name only from a scenario run and refused
+     * everywhere else, so it is never network-callable.
      */
     scenarioStep?: boolean;
     /**
-     * The function behind a `pikkuScenario(...)` — a scenario's own body, as
-     * opposed to the steps it calls. Marked for the same reason as
-     * `scenarioStep`: a scenario is only ever run by `pikku scenario run`, so it
-     * has to be held back from the app bootstrap and from every deployed unit.
+     * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
+     * so it is held back from the app bootstrap and from every deployed unit.
      */
     scenario?: boolean;
     mcp?: boolean;
@@ -112,10 +105,30 @@ export type FunctionRuntimeMeta = {
     workflowRetries?: number;
     /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
     workflowTimeout?: string;
-    /** Scenario steps only: this step drives a browser, so the runner must provision one and an actor is mandatory. */
-    scenarioStepBrowser?: boolean;
+    /**
+     * Scenario steps only: which surfaces this step declares a binding for.
+     *
+     * The reporter derives coverage from this — a `then` with no binding for the
+     * surface the run targeted was never actually witnessed there, which is a gap
+     * worth counting rather than excusing.
+     */
+    scenarioStepSurfaces?: ScenarioSurface[];
+    /**
+     * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
+     * and the only kind that existed before the other two.
+     *
+     * A `platform` or `addon` step is the app or a third-party system acting, and
+     * it must never reach a virtual user's catalogue. That is not tidiness: a
+     * virtual user that can invoke "Stripe's webhook arrives" can forge its own
+     * payment success, and every finding downstream of that is worthless.
+     */
+    scenarioStepKind?: ScenarioStepKind;
+    /** Addon steps only: the addon whose system acts — `wireAddon`'s `name`. */
+    scenarioStepAddon?: string;
     /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
     scenarioStepTemplate?: string;
+    /** Keeps the full `SecretService`. Set by the inspector, read by the runner. */
+    secretBroker?: boolean;
     version?: number;
     approvalRequired?: boolean;
     approvalDescription?: string;
@@ -126,7 +139,8 @@ export type FunctionRuntimeMeta = {
 };
 export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     name: string;
-    functionType: 'user' | 'inline' | 'helper';
+    /** `remote`: a contract with no local body, answered by a connected client. */
+    functionType: 'user' | 'inline' | 'helper' | 'remote';
     funcWrapper: string;
     services: FunctionServicesMeta;
     wires: FunctionWiresMeta;
@@ -147,35 +161,18 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
 export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-/**
- * Represents a JSON primitive type which can be a string, number, boolean, null, or undefined.
- */
 export type JSONPrimitive = string | number | boolean | null | undefined;
-/**
- * Represents a JSON value which can be a primitive, an array, or an object.
- */
 export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
 };
-/**
- * Utility type for making certain keys required and leaving the rest as optional.
- */
 export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
-/**
- * Utility type for making certain keys optional while keeping the rest required.
- */
 export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
-/**
- * Utility type that ensures at least one key in the given type `T` is required.
- */
 export type RequireAtLeastOne<T> = {
     [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
 }[keyof T];
 /**
- * Runtime options for the Postgres adapter (@pikku/kysely-postgres).
- * The connection string itself stays the flat `postgresUrl` config field (the
- * contract the CLI's db commands read); this block is purely runtime pool
- * tuning that the CLI never touches.
+ * Runtime pool tuning for the Postgres adapter. The connection string stays
+ * the flat `postgresUrl` config field — the contract the CLI's db commands read.
  */
 export interface PostgresConfig {
     /** Max connections in the postgres.js pool. Defaults to postgres.js's 10. */
@@ -201,23 +198,16 @@ export interface PostgresConfig {
      */
     prepare?: boolean;
 }
-/**
- * Interface for the core configuration settings of Pikku.
- */
 export type CoreConfig<Config extends Record<string, unknown> = {}> = {
-    /** The log level for the application. */
     logLevel?: LogLevel;
-    /** Secrets used by the application (optional). */
-    secrets?: {};
+    secrets?: {
+        /** Refuse a secret that declares no `allowedHosts` rather than treating it as unrestricted. */
+        requireAllowedHosts?: boolean;
+    };
     workflow?: WorkflowServiceConfig;
-    /** Default retry and signing settings for outgoing webhooks. */
     webhook?: WebhookServiceConfig;
-    /** Runtime Postgres adapter options (pool sizing). */
     postgres?: PostgresConfig;
 } & Config;
-/**
- * Represents a core user session, which can be extended for more specific session information.
- */
 export interface CoreUserSession {
     userId?: string;
     orgId?: string;
@@ -225,109 +215,70 @@ export interface CoreUserSession {
     actor?: boolean;
     /**
      * Scopes granted to this session, checked against a function's `scopes`.
-     * Populated by whoever builds the session (e.g. better-auth's `mapSession`
-     * resolving them via a ScopeService) — core reads them and never fetches.
+     * Populated by whoever builds the session — core reads them, never fetches.
      */
     scopes?: string[];
 }
 /**
- * The shape pikku needs from whatever auth library a project wires: something
- * that can answer an HTTP request and expose its own endpoints as callable
- * methods. Kept structural so core stays independent of any one auth package —
- * `@pikku/better-auth`'s `BetterAuthInstance` is this type.
+ * Kept structural so core stays independent of any one auth package —
+ * `@pikku/better-auth`'s `BetterAuthInstance` satisfies it.
  */
 export interface AuthInstance {
     handler: (request: Request) => Promise<Response>;
     api: Record<string, any>;
-    /**
-     * The auth library's resolved context. Optional because a hand-built instance
-     * may omit it.
-     */
     $context?: Promise<any>;
 }
-/**
- * Interface for core singleton services provided by Pikku.
- */
 export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
-    /** The schema library used to validate data */
     schema?: SchemaService;
-    /** The JWT service used to encode and decode tokens */
     jwt?: JWTService;
-    /** The core configuration for the application. */
     config: Config;
-    /** The logger used by the application. */
     logger: Logger;
-    /** The variable service to be used */
     variables: VariablesService;
-    /** The secrets service to retrieve secrets */
     secrets: SecretService;
-    /** The workflow orchestrator service */
     workflowService?: WorkflowService;
-    /** The queue service */
     queueService?: QueueService;
-    /** Event hub for realtime pub/sub across channels */
     eventHub?: EventHubService<Record<string, any>>;
-    /** The scheduler service */
     schedulerService?: SchedulerService;
-    /** The deployment service for service discovery */
     deploymentService?: DeploymentService;
-    /** AI agent storage service (threads, messages, working memory) */
     aiStorage?: AIStorageService;
-    /** Content service for file storage and retrieval */
     content?: ContentService;
-    /** AI agent runner service (model calls + tool loop) */
     aiAgentRunner?: AIAgentRunnerService;
-    /** Dedicated embedding service (vector stores use it at index & query time) */
     aiEmbedding?: AIEmbeddingService;
-    /** AI run state service (run lifecycle + approval persistence) */
     aiRunState?: AIRunStateService;
-    /** Agent run service (listing threads, runs, steps) */
     agentRunService?: AgentRunService;
-    /** Workflow run service (listing workflow runs) */
     workflowRunService?: WorkflowRunService;
-    /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
     credentialService?: CredentialService;
-    /** Email service for outbound messages and template-backed delivery */
     emailService?: EmailService;
     /**
-     * Webhook service for outgoing webhook delivery via a queue. A store-backed
-     * implementation (e.g. `KyselyWebhookService`) additionally records delivery
-     * history; the queue-only default throws on the delivery-read methods.
+     * Queue-backed outgoing webhook delivery. The queue-only default throws on
+     * the delivery-read methods; a store-backed implementation records history.
      */
     webhookService?: WebhookService;
-    /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
     metaService?: MetaService;
     /** V8 precise-coverage collector (`pikku dev --coverage` only) */
     coverageService?: CoverageService;
-    /** Audit service for durable or staged audit event capture */
     audit?: AuditService;
     /**
-     * Per-invocation audit log. Typically created in `createWireServices` via
-     * `createInvocationAudit(audit, wire)` and returned as a wire service so the
-     * runner flushes its buffer (via `close()`) when the invocation ends. Distinct
-     * from `audit` (the durable sink): this is the request-scoped buffer that
-     * writes into it.
+     * 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
+     * invocation ends.
      */
     auditLog?: AuditLog;
     /** Session store for persisting user sessions keyed by pikkuUserId */
     sessionStore?: SessionStore;
     /**
-     * Resolves and administers user scopes. Called when building a session (e.g.
-     * better-auth's `mapSession`), never by the function runner.
+     * Resolves and administers user scopes. Called when building a session,
+     * never by the function runner.
      */
     scopeService?: ScopeService;
     /**
-     * The project's resolved auth instance, built once by the factory an auth
-     * package registers (e.g. `pikkuBetterAuth`) and injected by the generated
-     * `pikkuServices` wrapper — which is why service factories are forbidden from
-     * returning it themselves. Absent when the project wires no auth.
+     * Built once by the factory an auth package registers and injected by the
+     * generated `pikkuServices` wrapper — service factories must not return it
+     * themselves. Absent when the project wires no auth.
      */
     auth?: () => Promise<AuthInstance>;
 }
-/**
- * Represents different forms of wire within Pikku and the outside world.
- */
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire, TypedActors extends ScenarioActors = ScenarioActors> = {
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
@@ -335,21 +286,19 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     wireId: string;
     /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
     traceId: string;
-    /** Function id for the current invocation */
     functionId: string;
-    /** The addon instance namespace (wireAddon name) currently executing, if any */
     addonNamespace: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
-    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out> : PikkuChannel<unknown, Out> | undefined;
+    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out, TypedRPC['remote']> : PikkuChannel<unknown, Out, TypedRPC['remote']> | undefined;
     scheduledTask: PikkuScheduledTask;
     queue: PikkuQueue;
-    cli: PikkuCLI;
+    cli: PikkuCLI<TypedRPC['remote']>;
     workflow: TypedWorkflow;
     scenario: TypedScenario;
     actors: TypedActors;
     /** Present on every scenario step invocation */
-    scenarioStep: PikkuScenarioStepWire<ScenarioActorOf<TypedActors>>;
+    scenarioStep: PikkuScenarioStepWire<ScenarioPersonaOf<TypedActors>>;
     /** Present only when the runner provisioned a browser for this step */
     browser: PikkuBrowserWire;
     workflowStep: WorkflowStepWire;
@@ -357,15 +306,11 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     trigger: PikkuTrigger<TriggerOutput>;
     gateway: PikkuGateway;
     session: HasInitialSession extends true ? UserSession : UserSession | undefined;
-    /** Update and persist the current session */
     setSession: (session: UserSession) => Promise<void> | void;
-    /** Clear and persist the current session */
     clearSession: () => Promise<void> | void;
     /** Fetch the latest session (may read from backing store) */
     getSession: () => Promise<UserSession> | UserSession | undefined;
-    /** Whether the session was modified during this run */
     hasSessionChanged: () => boolean;
-    /** The resolved user identity for credential lookups */
     pikkuUserId: string;
     /** Set a credential value (available in middleware) */
     setCredential: (name: string, value: unknown) => void;
@@ -373,131 +318,62 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     getCredential: <T = unknown>(name: string) => T | null | Promise<T | null>;
     /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
     getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
-    /** Resolved function audit metadata for this invocation, if enabled */
     audit: {
         durability: AuditDurability;
     };
+    /**
+     * Declare that everything after this line changes something.
+     *
+     * Present only on functions that are not `readonly` — a read has nothing to
+     * declare. Throws `AbandonedError` if whatever asked for this work has
+     * already gone away (an interrupted agent run, a disconnected client), so the
+     * mutation never runs and the abort is clean. Otherwise it marks the call as
+     * mutating, so an interrupt landing after this point is reported rather than
+     * silently discarded.
+     *
+     * Cooperative: a function that never calls it is assumed to have changed
+     * something, which is the safe default.
+     */
+    beginChanges: () => Promise<void>;
 }>;
-/**
- * Wire object as constructed by runners, before rpc is lazily added by the function runner.
- */
+/** Wire as constructed by runners, before the function runner lazily adds `rpc`. */
 export type PikkuRawWire = Omit<PikkuWire, 'rpc'>;
-/**
- * A function that can wrap an wire and be called before or after
- */
 export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire, next: () => Promise<void>) => Promise<void>;
 /**
- * Priority levels for middleware execution order.
- * Lower priority runs first (outermost in the onion model).
- *
- * - `highest` — Runs first (outermost). Use for telemetry, request tracing.
- * - `high` — Runs early. Use for CORS, rate limiting.
- * - `medium` — Default. Use for auth, most user middleware.
- * - `low` — Runs late. Use for post-auth processing.
- * - `lowest` — Runs last (innermost, closest to function). Use for inner telemetry.
+ * Execution order: `highest` runs first (outermost in the onion), `lowest`
+ * runs last, closest to the function.
  */
 export type MiddlewarePriority = 'highest' | 'high' | 'medium' | 'low' | 'lowest';
-/**
- * Configuration object for creating middleware with metadata
- *
- * @template SingletonServices - The singleton services type
- * @template UserSession - The user session type
- */
 export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = {
-    /** The middleware function */
     func: CorePikkuMiddleware<SingletonServices, UserSession>;
-    /** Optional human-readable name for the middleware */
     name?: string;
-    /** Optional description of what the middleware does */
     description?: string;
     /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
     priority?: MiddlewarePriority;
 };
-/**
- * A factory function that takes input and returns middleware
- * Used when middleware needs configuration/input parameters
- */
 export type CorePikkuMiddlewareFactory<In = any, SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>;
-/**
- * A group of middleware (combination of regular middleware and factories)
- * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
- */
 export type CorePikkuMiddlewareGroup<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = Array<CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>>;
-/**
- * Factory function for creating middleware with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const logMiddleware = pikkuMiddleware(
- *   async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const logMiddleware = pikkuMiddleware({
- *   name: 'Request Logger',
- *   description: 'Logs request information',
- *   func: async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * })
- * ```
- */
 export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareConfig<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
-/**
- * Factory function for creating middleware factories
- * Use this when your middleware needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
- *   message,
- *   level = 'info'
- * }) => {
- *   return pikkuMiddleware(async ({ logger }, next) => {
- *     logger[level](message)
- *     await next()
- *   })
- * })
- * ```
- */
 export declare const pikkuMiddlewareFactory: <In = any>(factory: CorePikkuMiddlewareFactory<In>) => CorePikkuMiddlewareFactory<In>;
 export declare const pikkuChannelMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, Event = unknown>(middleware: CorePikkuChannelMiddleware<SingletonServices, Event>) => CorePikkuChannelMiddleware<SingletonServices, Event>;
 export declare const pikkuChannelMiddlewareFactory: <In = any>(factory: CorePikkuChannelMiddlewareFactory<In>) => CorePikkuChannelMiddlewareFactory<In>;
 export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 export declare const pikkuAIMiddleware: <State extends Record<string, unknown> = Record<string, unknown>, SingletonServices extends CoreSingletonServices = CoreSingletonServices>(hooks: PikkuAIMiddlewareHooks<State, SingletonServices>) => PikkuAIMiddlewareHooks<State, SingletonServices>;
-/**
- * Represents the core services used by Pikku, including singleton services.
- */
 export type CoreServices<SingletonServices = CoreSingletonServices> = SingletonServices;
+/** Strips `secrets` from a services type. */
+export type SecretlessServices<Services> = Omit<Services, 'secrets'>;
+/** The constraint every function-, permission- and auth-facing type is bounded by. */
+export type CoreSecretlessSingletonServices<Config extends CoreConfig = CoreConfig> = SecretlessServices<CoreSingletonServices<Config>>;
 export type WireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services = CoreServices<SingletonServices>> = Omit<Services, keyof SingletonServices | 'session'>;
-/**
- * Defines a function type for creating singleton services from the given configuration.
- */
 export type CreateSingletonServices<Config extends CoreConfig, SingletonServices extends CoreSingletonServices> = (config: Config, existingServices?: Partial<SingletonServices>) => Promise<SingletonServices>;
-/**
- * Defines a function type for creating session-specific services.
- */
 export type CreateWireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wire: PikkuRawWire) => Promise<WireServices<Services, SingletonServices>>;
-/**
- * Defines a function type for creating config.
- */
 export type CreateConfig<Config extends CoreConfig, RemainingArgs extends any[] = unknown[]> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>;
-/** Server lifecycle hooks for startup and shutdown phases. */
 export type ServerLifecycle<SingletonServices extends CoreSingletonServices = CoreSingletonServices> = {
     beforeStart?: (services: SingletonServices) => void | Promise<void>;
     afterStart?: (services: SingletonServices) => void | Promise<void>;
     beforeStop?: (services: SingletonServices) => void | Promise<void>;
     afterStop?: (services: SingletonServices) => void | Promise<void>;
 };
-/**
- * Represents the documentation for a route, including summary, description, tags, and errors.
- */
 export type CommonWireMeta = {
     pikkuFuncId: string;
     packageName?: string;
@@ -510,9 +386,8 @@ export type CommonWireMeta = {
     permissions?: PermissionMetadata[];
 };
 /**
- * Dependency security audit artifact — the shape of `.pikku/audit.json` written
- * by `pikku audit`. Canonical home for the type shared by the CLI (writer), the
- * console addon (reader), and the console UI (renderer).
+ * The shape of `.pikku/audit.json`. Shared by the CLI (writer), the console
+ * addon (reader) and the console UI (renderer).
  */
 export type SecuritySeverity = 'critical' | 'high' | 'moderate' | 'low' | 'info';
 export type SecurityUpdateLevel = 'major' | 'minor' | 'patch' | 'unknown';
@@ -553,9 +428,6 @@ export interface SecurityAuditReport {
     updates: SecurityAuditUpdate[];
     summary: SecurityAuditSummary;
 }
-/**
- * Serialized error for storage
- */
 export interface SerializedError {
     message: string;
     stack?: string;
@@ -563,3 +435,11 @@ export interface SerializedError {
     expected?: boolean;
     [key: string]: any;
 }
+/**
+ * A generated schema's declaration site, used by the credential/secret/variable
+ * definition validators to point conflicting definitions at their source.
+ */
+export interface SchemaRefLike {
+    variableName: string;
+    sourceFile: string;
+}

package/dist/types/core.types.js

@@ -1,28 +1,3 @@
-/**
- * Factory function for creating middleware with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const logMiddleware = pikkuMiddleware(
- *   async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const logMiddleware = pikkuMiddleware({
- *   name: 'Request Logger',
- *   description: 'Logs request information',
- *   func: async ({ logger }, next) => {
- *     logger.info('Request started')
- *     await next()
- *   }
- * })
- * ```
- */
 export const pikkuMiddleware = (middleware) => {
     if (typeof middleware === 'function')
         return middleware;
@@ -32,23 +7,6 @@ export const pikkuMiddleware = (middleware) => {
     }
     return func;
 };
-/**
- * Factory function for creating middleware factories
- * Use this when your middleware needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
- *   message,
- *   level = 'info'
- * }) => {
- *   return pikkuMiddleware(async ({ logger }, next) => {
- *     logger[level](message)
- *     await next()
- *   })
- * })
- * ```
- */
 export const pikkuMiddlewareFactory = (factory) => {
     return factory;
 };

package/dist/types/state.types.d.ts

@@ -1,4 +1,4 @@
-import type { PikkuError, ErrorDetails } from '../errors/error-handler.js';
+import type { PikkuErrorConstructor, ErrorDetails } from '../errors/error-handler.js';
 import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
 import type { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
 import type { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types.js';
@@ -13,9 +13,6 @@ import type { CoreWorkflow, CoreFeature, WorkflowsRuntimeMeta } from '../wirings
 import type { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
-/**
- * State structure for an individual package
- */
 export interface PikkuPackageState {
     function: {
         meta: FunctionsMeta;
@@ -35,6 +32,8 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
+            /** Required of every function in this package, on top of the function's own */
+            scopes?: string[];
             /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */
             secretOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
@@ -119,32 +118,28 @@ export interface PikkuPackageState {
         global: (CorePermissionGroup | CorePikkuPermission)[];
     };
     misc: {
-        errors: Map<PikkuError, ErrorDetails>;
+        errors: Map<PikkuErrorConstructor, ErrorDetails>;
         schemas: Map<string, any>;
         middleware: Record<string, CorePikkuMiddleware[]>;
         channelMiddleware: Record<string, CorePikkuChannelMiddleware[]>;
         permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
     };
     package: {
-        /** Service factory functions for addon packages */
         factories: {
             createConfig?: CreateConfig<CoreConfig>;
             createSingletonServices?: CreateSingletonServices<CoreConfig, CoreSingletonServices>;
             createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>;
         } | null;
-        /** Cached singleton services for this package */
         singletonServices: CoreSingletonServices | null;
         /** The pikkuBetterAuth factory, self-registered when auth.ts is evaluated.
          *  pikkuServices reads it to build and inject the `auth` singleton. */
         authFactory: ((services: CoreSingletonServices) => unknown | Promise<unknown>) | null;
-        /** Credential metadata for this addon package */
         credentialsMeta: Record<string, {
             name: string;
             displayName: string;
             type: string;
             oauth2?: boolean;
         }> | null;
-        /** Services this addon needs from the parent project */
         requiredParentServices: string[] | null;
     };
 }