@pikku/core 0.12.92 → 0.12.94

package/dist/wirings/persona/index.js

@@ -2,6 +2,7 @@ export { definePersonas } from './define-personas.js';
 export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
 export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
 export { personaEmail, personaEmails } from './persona-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-app-scopes.js';
 /**
  * Signing in as a persona and talking to a stage over HTTP.
  *

package/dist/wirings/persona/persona-app-scopes.d.ts

@@ -0,0 +1,41 @@
+import type { ScopeDefinitionMeta } from '../scope/scope.types.js';
+import type { PersonaMeta } from './persona.types.js';
+/**
+ * The root every app grant hangs off. One segment, so a grant of `app` alone
+ * means "may use all of them" under the same parent-grant rule the admin tree
+ * relies on — which is what a support operator or an internal tool wants, and
+ * what a per-app boolean column could never express.
+ */
+export declare const APP_SCOPE_ROOT = "app";
+/** `app:staff` for `staff`. */
+export declare const appScopeId: (app: string) => string;
+/**
+ * The apps named across the declared personas, sorted and deduplicated.
+ *
+ * The personas *are* the registry. There is no separate list of apps to keep in
+ * step, because a frontend nobody signs into is not a thing the auth layer has
+ * an opinion about — and the moment somebody does sign into it, they are a
+ * persona and they name it.
+ */
+export declare const declaredApps: (personas: PersonaMeta[]) => string[];
+/**
+ * The `app` scope tree, synthesised from the personas that name an app.
+ *
+ * Which frontend a person may sign into is a different question from what they
+ * may do once inside it, but it is the same *kind* of question — a grant that
+ * an admin can make and revoke at runtime, that resolves at the session
+ * boundary, and that a restricted API key can decline to inherit. So it is
+ * carried as a scope rather than a `can_access_<app>` column: no migration per
+ * app, one query for "which apps may this user reach", and no second
+ * authorization mechanism to keep honest.
+ *
+ * Synthesised rather than written by hand because the declaration already
+ * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
+ * beside its personas invites the two to drift, and the failure that produces —
+ * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * `pikku scopes prune` away from silently revoking sign-in.
+ *
+ * Null when no persona names an app, which is the single-frontend case: nothing
+ * to declare, and no empty root cluttering the console's grant list.
+ */
+export declare const buildAppScopeDefinition: (personas: PersonaMeta[]) => ScopeDefinitionMeta | null;

package/dist/wirings/persona/persona-app-scopes.js

@@ -0,0 +1,61 @@
+/**
+ * The root every app grant hangs off. One segment, so a grant of `app` alone
+ * means "may use all of them" under the same parent-grant rule the admin tree
+ * relies on — which is what a support operator or an internal tool wants, and
+ * what a per-app boolean column could never express.
+ */
+export const APP_SCOPE_ROOT = 'app';
+/** `app:staff` for `staff`. */
+export const appScopeId = (app) => `${APP_SCOPE_ROOT}:${app}`;
+/**
+ * The apps named across the declared personas, sorted and deduplicated.
+ *
+ * The personas *are* the registry. There is no separate list of apps to keep in
+ * step, because a frontend nobody signs into is not a thing the auth layer has
+ * an opinion about — and the moment somebody does sign into it, they are a
+ * persona and they name it.
+ */
+export const declaredApps = (personas) => [
+    ...new Set(personas
+        .map((persona) => persona.app)
+        .filter((app) => typeof app === 'string' && app !== '')),
+].sort();
+/**
+ * The `app` scope tree, synthesised from the personas that name an app.
+ *
+ * Which frontend a person may sign into is a different question from what they
+ * may do once inside it, but it is the same *kind* of question — a grant that
+ * an admin can make and revoke at runtime, that resolves at the session
+ * boundary, and that a restricted API key can decline to inherit. So it is
+ * carried as a scope rather than a `can_access_<app>` column: no migration per
+ * app, one query for "which apps may this user reach", and no second
+ * authorization mechanism to keep honest.
+ *
+ * Synthesised rather than written by hand because the declaration already
+ * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
+ * beside its personas invites the two to drift, and the failure that produces —
+ * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * `pikku scopes prune` away from silently revoking sign-in.
+ *
+ * Null when no persona names an app, which is the single-frontend case: nothing
+ * to declare, and no empty root cluttering the console's grant list.
+ */
+export const buildAppScopeDefinition = (personas) => {
+    const apps = declaredApps(personas);
+    if (apps.length === 0) {
+        return null;
+    }
+    const scopes = {};
+    for (const app of apps) {
+        scopes[app] = {
+            displayName: app,
+            description: `May sign in to the ${app} app`,
+        };
+    }
+    return {
+        name: APP_SCOPE_ROOT,
+        displayName: 'Apps',
+        description: 'Which frontend a person may sign in to',
+        scopes,
+    };
+};

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

@@ -110,11 +110,17 @@ export type QueueWorkersMeta = Record<string, CommonWireMeta & {
     config?: PikkuWorkerConfig;
 }>;
 export type CoreQueueWorker<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
+    /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
     name: string;
+    /** The function to run per job. Its `input` schema is the job payload's schema — a job that does not match is rejected before the body runs. */
     func: PikkuFunctionConfig;
+    /** Concurrency, retry and backoff, passed through to the queue service backing this worker. Defaults come from the service, not from here. */
     config?: PikkuWorkerConfig;
+    /** Names of error classes that mean the job is bad rather than the run — thrown, they fail the job permanently instead of being retried. */
     errors?: string[];
+    /** Filters this worker in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuFunctionConfig['middleware'];
 };
 export interface PikkuQueue {

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

@@ -7,10 +7,15 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Reco
     session?: UserSession;
 }>;
 export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
     name: string;
+    /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
     schedule: string;
+    /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
     func: PikkuFunctionConfig;
+    /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuMiddleware[];
 };
 export interface PikkuScheduledTask {

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

@@ -4,21 +4,9 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
-    /**
-     * A secret is REQUIRED by default because `getSecret` throws when the value is
-     * missing — a deploy without it is a runtime failure waiting to happen, so the
-     * deploy gate refuses it. Mark a secret `optional` when absence is a supported
-     * state the app handles (a feature that simply stays off): the generated map
-     * emits it as an optional property and `getSecret` resolves `undefined`
-     * instead of throwing.
-     */
+    /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
     optional?: boolean;
-    /**
-     * Where a user goes to obtain this value — a provider's API-key page, a setup
-     * guide, an internal runbook. Consoles and deploy UIs surface it beside a
-     * missing value. The same field on every credential/variable definition means
-     * the same thing.
-     */
+    /** Where a user goes to obtain this value, surfaced beside a missing one. */
     docsUrl?: string;
     /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
     rotationPeriod?: string;
@@ -59,4 +47,11 @@ export type SecretDefinitionMeta = {
 };
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;
 export type SecretDefinitions = SecretDefinitionMeta[];
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export declare const defineSecret: <T>(_config: CoreSecret<T>) => void;

package/dist/wirings/secret/secret.types.js

@@ -1 +1,8 @@
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export const defineSecret = (_config) => { };

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

@@ -28,11 +28,14 @@ export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown,
 };
 export declare const pikkuTriggerFunc: <TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(triggerOrConfig: CorePikkuTriggerFunction<TInput, TOutput, Services> | CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>) => CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>;
 export interface CoreTrigger<PikkuFunctionConfig = any> {
+    /** What a `wireTriggerSource` points at to fire this trigger. It is the contract between the two, so both must spell it the same. */
     name: string;
+    /** The function to run each time the trigger fires. */
     func: PikkuFunctionConfig;
+    /** What firing this trigger means, for whoever is reading the wiring rather than writing it. */
     description?: string;
+    /** Filters this trigger in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
-    graph?: true;
 }
 export interface TriggerInstance {
     name: string;

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

@@ -1,23 +1,17 @@
 export type CoreVariable<T = unknown> = {
+    /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
     name: string;
+    /** The name shown to whoever configures the deployment. */
     displayName: string;
+    /** What the value does, for the person setting it rather than the one reading it. */
     description?: string;
+    /** The environment variable this reads, which is the name that has to exist on the host. */
     variableId: string;
+    /** The shape of the value. It arrives as a string, so this is also what parses it. */
     schema: T;
-    /**
-     * A variable is REQUIRED by default, and marking it `optional` is how a
-     * declaration says its absence is a supported state. Same flag, same
-     * polarity and same meaning as `CoreSecret.optional` — one word to learn
-     * rather than two with opposite senses.
-     *
-     * Defaulting to required rather than following `variables.get`'s
-     * `T | undefined` return is deliberate. That signature describes what a
-     * caller must HANDLE, not whether a deployment is correct without the value:
-     * an undefined feature flag is fine, an undefined API base URL is an outage
-     * that the type system cannot tell apart. Declaring the difference is the
-     * point of the flag, and the safe default for an undeclared one is to ask.
-     */
+    /** Required by default: this says the deployment is still correct without it. */
     optional?: boolean;
+    /** Where to go to work out what to set this to. */
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -32,4 +26,11 @@ export type VariableDefinitionMeta = {
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
 export type VariableDefinitions = VariableDefinitionMeta[];
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export declare const defineVariable: <T>(_config: CoreVariable<T>) => void;

package/dist/wirings/variable/variable.types.js

@@ -1 +1,8 @@
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export const defineVariable = (_config) => { };

package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts

@@ -1,10 +1,17 @@
 export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>, T> {
+    /** Keeps the graph in the codebase but out of the build. */
     disabled?: true;
+    /** Unique across the project. It is how the graph is started and how its runs are grouped. */
     name?: string;
+    /** What the graph does, for whoever is reading it rather than editing it. */
     description?: string;
+    /** Filters this graph in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here. */
     nodes: FuncMap;
+    /** Per-node settings — retries, timeouts, the edges between them. */
     config?: T;
+    /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
     notes?: string[];
 }
 export interface PikkuWorkflowGraphResult {

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -3,4 +3,10 @@ export interface ScenarioCookieJar {
     clear(): void;
     readonly empty: boolean;
 }
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -1,3 +1,9 @@
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export const createCookieJar = (apiUrl) => {
     const jar = new Map();
     const origin = new URL(apiUrl).origin;

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -2,4 +2,10 @@ export interface PollOptions {
     timeoutMs?: number;
     intervalMs?: number;
 }
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -1,3 +1,9 @@
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
     const deadline = Date.now() + timeoutMs;
     for (;;) {

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -1,2 +1,8 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,3 +1,9 @@
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

package/dist/wirings/workflow/workflow-errors.d.ts

@@ -9,6 +9,10 @@ export declare class WorkflowAsyncException extends Error {
     readonly stepName: string;
     constructor(runId: string, stepName: string);
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export declare class WorkflowCancelledException extends Error {
     readonly runId: string;
     readonly reason?: string | undefined;

package/dist/wirings/workflow/workflow-errors.js

@@ -13,6 +13,10 @@ export class WorkflowAsyncException extends Error {
         this.name = 'WorkflowAsyncException';
     }
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export class WorkflowCancelledException extends Error {
     runId;
     reason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.92",
+  "version": "0.12.94",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -124,12 +124,12 @@ const barrelSpecifiers = (file: string) => {
  * it otherwise never imports.
  */
 const namesOwnedByALeaf = new Map<string, string>([
-  ['defineCredential', '#pikku/credentials'],
+  ['defineCredential', '#pikku/auth'],
   ['defineSecret', '#pikku/secrets'],
   ['defineVariable', '#pikku/variables'],
   ['defineScope', '#pikku/scopes'],
   ['defineSystemRole', '#pikku/scopes'],
-  ['cors', '#pikku/http'],
+  ['cors', '#pikku/middleware'],
   ['InvalidOriginError', '#pikku/error'],
 ])
 

package/src/errors/error-handler.ts

@@ -13,19 +13,30 @@ export class PikkuError extends Error {
  * survives serialization across a workflow step boundary and rehydration as a
  * plain `Error`. Callers log the message alone for these, the full stack for
  * everything else.
+ *
+ * @example snippet: isExpectedError
  */
 export const isExpectedError = (error: unknown): boolean =>
   error instanceof PikkuError ||
   (error as { expected?: unknown } | null)?.expected === true
 
 export interface ErrorDetails {
+  /** The HTTP status this error answers with, instead of a 500. */
   status: number
+  /** What the caller is told. It leaves the process, so it must not name anything internal. */
   message: string
+  /** The JSON-RPC code an MCP client is given, where the HTTP status has no equivalent. */
   mcpCode?: number
 }
 
 export type PikkuErrorConstructor = new (...args: any[]) => Error
 
+/**
+ * Registers one of your own error classes with the HTTP status and message it
+ * should produce, so throwing it maps to a real response instead of a 500.
+ *
+ * @example snippet: addError
+ */
 export const addError = (
   error: any,
   { status, message, mcpCode }: ErrorDetails

package/src/errors/serialized-error.ts

@@ -1,6 +1,9 @@
 export interface SerializedError {
+  /** What went wrong, carried across a boundary that cannot carry an Error. */
   message: string
+  /** Present only where the failure was unexpected; a deliberate error is logged by its message alone. */
   stack?: string
+  /** The error class's registered name, which is what a caller matches on rather than the message. */
   code?: string
   // Set for a deliberate PikkuError; survives step-boundary rehydration so
   // the workflow runner logs the message alone rather than a stack trace.

package/src/function/function-runner.ts

@@ -29,7 +29,7 @@ import type { CorePikkuFunctionConfig } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
-import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js'
 import { verifyScopes } from '../scopes.js'
 import {
   PikkuCredentialWireService,
@@ -83,7 +83,7 @@ async function resolveSession(
 
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>,
+  funcConfig: CorePikkuFunctionConfig<any, any, any, any, any>,
   packageName: string | null = null
 ) => {
   pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
@@ -329,7 +329,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         resolveAddonAuth(packageName, addonInstance?.namespace)
       ) {
         if (!session) {
-          throw new ForbiddenError('Authentication required')
+          throw new MissingSessionError('Authentication required')
         }
       }
     } else {
@@ -339,7 +339,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       }
       if (!session) {
-        throw new ForbiddenError('Authentication required')
+        throw new MissingSessionError('Authentication required')
       }
     }
 

package/src/function/functions.types.ts

@@ -193,30 +193,38 @@ export type CorePikkuFunctionConfig<
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   Scope 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. */
   description?: string
   /** Explicit logical name override; lets multiple exports share a versioned base */
   override?: string
+  /** Which version of this contract this export is. Two exports sharing an `override` and differing here are the same function at two versions. */
   version?: number
+  /** Filters this function in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone. */
   expose?: boolean
   /**
-   * The permission check for this function lives in its body — verifying a
-   * signed token, checking a webhook signature, matching an invite code — so
-   * it is not open despite declaring no session, scope or permission.
-   *
-   * A last resort. Prefer `permissions`, which are declared, inspectable, and
-   * reusable; reach for this only when the check cannot be expressed as one.
-   *
-   * Purely declarative — it grants nothing, and asserting it falsely disables
-   * the audit that would have caught the mistake. Requires
-   * `allow.permissionsInBody` in `pikku.config.json`.
+   * Declares that the body does its own permission check, so the function is
+   * not open despite naming no session, scope or permission. It grants
+   * nothing — asserting it falsely just disables the audit that would have
+   * caught the mistake. Requires `allow.permissionsInBody` in the config.
    */
   permissionsInBody?: boolean
+  /** Publishes the function in this package's remote surface, which is what a `wireRemoteAddon` consumer gets a typed client for. */
   remote?: boolean
+  /** Offers the function to MCP clients as a tool, without a separate `wireMCPTool`. */
   mcp?: boolean
+  /**
+   * Declares that the function only reads. It is enforced rather than
+   * decorative: a read-only session is refused any function without it, and an
+   * agent may call one without asking permission first.
+   */
   readonly?: boolean
+  /** Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches. */
   deploy?: 'serverless' | 'server' | 'auto'
+  /** Under an agent's `explicit` approval policy, calling this pauses for a human to approve it. */
   approvalRequired?: boolean
   /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
   workflowQueued?: boolean
@@ -230,18 +238,21 @@ export type CorePikkuFunctionConfig<
    * and report how much of the flow each surface actually covers.
    */
   surfaces?: ScenarioSurface[]
+  /** Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`. */
+  requiresActor?: boolean
   /**
-   * Scenario steps only: this step is driven by a persona, so the runner injects
-   * `wire.actor` and refuses to dispatch it without one. Set by the definer from
-   * a `browser` binding or an explicit `actor: true`, never written by hand.
+   * Records every call in the audit log. `transactional` durability writes the
+   * entry in the same transaction as the work, so the two cannot disagree;
+   * `best-effort` does not hold the request up for it.
    */
-  requiresActor?: boolean
   audit?:
     | boolean
     | {
         durability?: 'best-effort' | 'transactional'
       }
+  /** Builds the sentence a human is shown when asked to approve a call, from that call's own input. */
   approvalDescription?: any
+  /** The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away. */
   func: PikkuFunction
   /**
    * Scenarios only: runs before the scenario body, with the scenario's own
@@ -260,20 +271,21 @@ export type CorePikkuFunctionConfig<
    * as skipped rather than quietly omitted; naming it in `--flows` runs it.
    */
   skip?: string
+  /** Whether calling this requires a session, wherever it is wired. A wiring can be more permissive than the function, never less. */
   auth?: boolean
-  /**
-   * Scopes the session must hold; all are required (AND) and checked before
-   * `permissions`, which OR together — a scope can only narrow access.
-   * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
-   * compile error. Requires a session — see
-   * {@link CorePikkuSessionlessFunctionConfig}.
-   */
+  /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
   scopes?: Scope[]
+  /** 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. */
   middleware?: PikkuMiddleware[]
+  /** The input schema, which is also the input type — there is no separate generic to keep in step with it. */
   input?: InputSchema
+  /** The output schema, which is also the return type. Naming a type here instead is what produces PKU463. */
   output?: OutputSchema
+  /** Presentation for this function as a node in a workflow graph. */
   node?: CoreNodeConfig
+  /** Error classes this may throw, so each one's registered HTTP status is used instead of a 500. */
   errors?: Array<typeof PikkuError>
 }
 

package/src/middleware/auth-apikey.ts

@@ -2,7 +2,14 @@ import {
   pikkuMiddleware,
   pikkuMiddlewareFactory,
 } from './middleware-factories.js'
+/**
+ * Reads an API key from the request and JWT-decodes it into a session. Leaves
+ * an existing session alone, so it composes with other auth middleware.
+ *
+ * @example snippet: machineAuth
+ */
 export const authAPIKey = pikkuMiddlewareFactory<{
+  /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>
   pikkuMiddleware(

package/src/middleware/auth-bearer.ts

@@ -17,8 +17,11 @@ const constantTimeEqual = (a: string, b: string): boolean => {
  * Validates a bearer token: JWT-decoded by default, or compared in constant
  * time against a static `value` or a `secretId` resolved through the secrets
  * service per request.
+ *
+ * @example snippet: machineAuth
  */
 export const authBearer = pikkuMiddlewareFactory<{
+  /** Omit to JWT-decode the token. Set it to accept one fixed token instead, matched in constant time. */
   token?:
     | {
         value: string

package/src/middleware/auth-cookie.ts

@@ -6,10 +6,6 @@ import {
 import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 
-/**
- * Reads a JWT session from a cookie, and re-issues the cookie after the
- * request whenever the session changed (e.g. after login).
- */
 /** Standard JWT registered claims — present on a token even with no session. */
 const JWT_REGISTERED_CLAIMS = new Set([
   'iat',
@@ -31,9 +27,18 @@ const hasSessionIdentity = (session: unknown): boolean => {
   return Object.keys(session).some((key) => !JWT_REGISTERED_CLAIMS.has(key))
 }
 
+/**
+ * Reads a JWT session from a cookie, and re-issues the cookie after the
+ * request whenever the session changed (e.g. after login).
+ *
+ * @example snippet: machineAuth
+ */
 export const authCookie = pikkuMiddlewareFactory<{
+  /** Cookie name to read and write. */
   name: string
+  /** Serialize options merged over the defaults, which are httpOnly and sameSite lax. */
   options: SerializeOptions
+  /** How long the re-issued cookie lives, as a relative time such as `'7d'`. */
   expiresIn: RelativeTimeInput
 }>(({ name, options, expiresIn }) => {
   const mergedOptions: SerializeOptions = {