@pikku/core 0.12.143 → 0.12.145

package/dist/middleware-runner.js

@@ -14,6 +14,13 @@ const getMiddlewarePriority = (fn) => {
 const sortByPriority = (middlewares) => {
     return middlewares.sort((a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b));
 };
+/**
+ * Runs `middlewares` as an onion around `main`, ordered by priority (stable
+ * within a priority), and returns `main`'s result. A middleware that does not
+ * call `next` stops the chain: `main` is never run and the result is
+ * `undefined`.
+ * @internal
+ */
 export const runMiddleware = async (services, wire, middlewares, main) => {
     const sorted = isSortedByPriority(middlewares)
         ? middlewares
@@ -60,10 +67,16 @@ export const addGlobalMiddleware = (middleware, packageName = null) => {
     state.push(...middleware);
     return middleware;
 };
-const getMiddlewareByName = (name) => {
-    const middlewareStore = pikkuState(null, 'misc', 'middleware');
-    const middleware = middlewareStore[name];
-    return middleware?.[0];
+/**
+ * Wire-level middleware by name, from the namespace of the package whose
+ * metadata named it — the same namespace its tag and HTTP groups resolve from
+ * — and then from the application's, which is never narrower.
+ */
+const getMiddlewareByName = (name, packageName) => {
+    const own = pikkuState(packageName, 'misc', 'middleware')[name]?.[0];
+    if (own || packageName === null)
+        return own;
+    return pikkuState(null, 'misc', 'middleware')[name]?.[0];
 };
 /**
  * Per-wire-type cap on the memoized middleware chains. The cache key is the
@@ -120,7 +133,10 @@ export const MIDDLEWARE_CACHE_MAX_ENTRIES = MIDDLEWARE_CACHE_MAX;
 /** Current number of cached chains for a wire type. Test/observability only. */
 export const middlewareCacheSize = (wireType) => middlewareCache[wireType].size;
 export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wireMiddleware, funcInheritedMiddleware, funcMiddleware, packageName = null, } = {}) => {
-    const cached = cacheGet(wireType, uid);
+    // A wire id is only unique within its package: an addon's `getUser` and the
+    // application's are different functions with different gates.
+    const cacheKey = packageName === null ? uid : `${packageName}\0${uid}`;
+    const cached = cacheGet(wireType, cacheKey);
     if (cached) {
         return cached;
     }
@@ -150,7 +166,7 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
                 }
             }
             else if (meta.type === 'wire') {
-                const middleware = getMiddlewareByName(meta.name);
+                const middleware = getMiddlewareByName(meta.name, packageName);
                 if (middleware) {
                     resolved.push(middleware);
                 }
@@ -175,5 +191,5 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
         resolved.push(...funcMiddleware);
     }
     sortByPriority(resolved);
-    return cacheSet(wireType, uid, freezeDedupe(resolved));
+    return cacheSet(wireType, cacheKey, freezeDedupe(resolved));
 };

package/dist/permissions.d.ts

@@ -23,6 +23,19 @@ export declare const runPermissions: ({ funcPermissions, services, wire, data, p
     /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
     label?: string;
 }) => Promise<void>;
+/**
+ * Decides, from the session alone, whether a function is worth offering to
+ * that session: only the `pikkuAuth` checks among the global and the given
+ * permissions are run, since they need no input. Resolves `true` when there
+ * are none or any one of them passes. Used to filter an agent's tools before
+ * the model sees them; it is not the enforcement point, which remains the full
+ * permission check when the function is called.
+ *
+ * @param funcPermissions - The live permission group from the function or
+ * agent config, never the generated metadata, which carries no functions.
+ * @param packageName - The package whose global permissions apply; `null` for
+ * the app.
+ */
 export declare const checkAuthPermissions: (
 /** Must be the live permission group from the func/agent config, never metadata. */
 funcPermissions: CorePermissionGroup | undefined, session: CoreUserSession, services: CoreServices, packageName?: string | null) => Promise<boolean>;

package/dist/permissions.js

@@ -93,6 +93,19 @@ export const runPermissions = async ({ funcPermissions, services, wire, data, pa
         }
     }
 };
+/**
+ * Decides, from the session alone, whether a function is worth offering to
+ * that session: only the `pikkuAuth` checks among the global and the given
+ * permissions are run, since they need no input. Resolves `true` when there
+ * are none or any one of them passes. Used to filter an agent's tools before
+ * the model sees them; it is not the enforcement point, which remains the full
+ * permission check when the function is called.
+ *
+ * @param funcPermissions - The live permission group from the function or
+ * agent config, never the generated metadata, which carries no functions.
+ * @param packageName - The package whose global permissions apply; `null` for
+ * the app.
+ */
 export const checkAuthPermissions = async (
 /** Must be the live permission group from the func/agent config, never metadata. */
 funcPermissions, session, services, packageName = null) => {

package/dist/pikku-state.d.ts

@@ -1,11 +1,60 @@
 import type { PikkuPackageState } from './types/state.types.js';
 import type { CoreSingletonServices, CreateWireServices } from './types/core.types.js';
+/**
+ * Every package's registry, keyed by package name (`__main__` for the app).
+ * The map lives on `globalThis` under a registered symbol, so duplicate copies
+ * of `@pikku/core` in one process share it.
+ * @internal
+ */
 export declare const getAllPackageStates: () => Map<string, PikkuPackageState>;
+/**
+ * Reads, or with `value` replaces, one slot of a package's registry: the
+ * functions, wirings, metadata, middleware and services that generated code and
+ * the `wire*` helpers register at import time.
+ *
+ * This is framework plumbing, not app state. Generated bootstrap files and
+ * runtime adapters call it; application code should go through the `wire*`,
+ * `add*` and `define*` helpers instead, because writing a slot directly
+ * bypasses the validation they do.
+ *
+ * @param packageName - The package whose registry to use; `null` means the app.
+ * The registry is created on first use.
+ * @param type - The area, such as `'function'`, `'http'` or `'misc'`.
+ * @param content - The slot within that area.
+ * @param value - When given, replaces the slot. `undefined` cannot be stored;
+ * it always reads.
+ * @returns The slot's current value.
+ */
 export declare const pikkuState: <Type extends keyof PikkuPackageState, Content extends keyof PikkuPackageState[Type]>(packageName: string | null, type: Type, content: Content, value?: PikkuPackageState[Type][Content]) => PikkuPackageState[Type][Content];
+/**
+ * Creates an empty registry for `packageName` if it has none yet; an existing
+ * one is left untouched.
+ * @internal
+ */
 export declare const initializePikkuState: (packageName: string) => void;
+/**
+ * Discards every package's registry and starts the app's afresh. Registered
+ * error classes are carried over, because they come from module side effects
+ * that will not run again. Meant for tests.
+ */
 export declare const resetPikkuState: () => void;
+/**
+ * The app's singleton services, as registered by the generated bootstrap or a
+ * runtime adapter.
+ * @throws {Error} When none have been registered yet.
+ */
 export declare const getSingletonServices: () => CoreSingletonServices;
+/** Registers the app's singleton services, replacing any registered before. */
 export declare const setSingletonServices: (services: CoreSingletonServices) => void;
+/**
+ * The app's registered `createWireServices` factory, if it has one.
+ * @internal
+ */
 export declare const getCreateWireServices: () => CreateWireServices | undefined;
+/**
+ * Registers the service factories for a package (an addon), replacing any
+ * registered before.
+ * @internal
+ */
 export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState['package']['factories']>) => void;
 export type { PikkuPackageState } from './types/state.types.js';

package/dist/pikku-state.js

@@ -5,6 +5,12 @@ const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state');
  * access.
  */
 const stateHost = globalThis;
+/**
+ * Every package's registry, keyed by package name (`__main__` for the app).
+ * The map lives on `globalThis` under a registered symbol, so duplicate copies
+ * of `@pikku/core` in one process share it.
+ * @internal
+ */
 export const getAllPackageStates = () => {
     let states = stateHost[PIKKU_STATE_KEY];
     if (!states) {
@@ -13,6 +19,24 @@ export const getAllPackageStates = () => {
     }
     return states;
 };
+/**
+ * Reads, or with `value` replaces, one slot of a package's registry: the
+ * functions, wirings, metadata, middleware and services that generated code and
+ * the `wire*` helpers register at import time.
+ *
+ * This is framework plumbing, not app state. Generated bootstrap files and
+ * runtime adapters call it; application code should go through the `wire*`,
+ * `add*` and `define*` helpers instead, because writing a slot directly
+ * bypasses the validation they do.
+ *
+ * @param packageName - The package whose registry to use; `null` means the app.
+ * The registry is created on first use.
+ * @param type - The area, such as `'function'`, `'http'` or `'misc'`.
+ * @param content - The slot within that area.
+ * @param value - When given, replaces the slot. `undefined` cannot be stored;
+ * it always reads.
+ * @returns The slot's current value.
+ */
 export const pikkuState = (packageName, type, content, value) => {
     const resolvedPackageName = packageName ?? '__main__';
     if (!getAllPackageStates().has(resolvedPackageName)) {
@@ -125,11 +149,21 @@ const createEmptyPackageState = () => ({
         declaredSecrets: null,
     },
 });
+/**
+ * Creates an empty registry for `packageName` if it has none yet; an existing
+ * one is left untouched.
+ * @internal
+ */
 export const initializePikkuState = (packageName) => {
     if (!getAllPackageStates().has(packageName)) {
         getAllPackageStates().set(packageName, createEmptyPackageState());
     }
 };
+/**
+ * Discards every package's registry and starts the app's afresh. Registered
+ * error classes are carried over, because they come from module side effects
+ * that will not run again. Meant for tests.
+ */
 export const resetPikkuState = () => {
     // Error definitions come from module-import side effects that never re-run.
     const existingErrors = getAllPackageStates().get('__main__')?.misc.errors;
@@ -143,18 +177,33 @@ export const resetPikkuState = () => {
 if (!getAllPackageStates().has('__main__')) {
     resetPikkuState();
 }
+/**
+ * The app's singleton services, as registered by the generated bootstrap or a
+ * runtime adapter.
+ * @throws {Error} When none have been registered yet.
+ */
 export const getSingletonServices = () => {
     const services = pikkuState(null, 'package', 'singletonServices');
     if (!services)
         throw new Error('Singleton services not initialized');
     return services;
 };
+/** Registers the app's singleton services, replacing any registered before. */
 export const setSingletonServices = (services) => {
     pikkuState(null, 'package', 'singletonServices', services);
 };
+/**
+ * The app's registered `createWireServices` factory, if it has one.
+ * @internal
+ */
 export const getCreateWireServices = () => {
     return pikkuState(null, 'package', 'factories')?.createWireServices;
 };
+/**
+ * Registers the service factories for a package (an addon), replacing any
+ * registered before.
+ * @internal
+ */
 export const addPackageServiceFactories = (packageName, factories) => {
     pikkuState(packageName, 'package', 'factories', factories);
 };

package/dist/remote.js

@@ -1,4 +1,23 @@
 import { assertStrongKeyMaterial, encryptWithKeyMaterial, REMOTE_SESSION_INFO, } from './crypto-utils.js';
+/**
+ * An unset secret means remote auth is not configured, so the call goes out
+ * unauthenticated. A secrets backend that fails is a different thing: sending
+ * the call anyway would only earn a 401 from the peer with no hint why.
+ */
+const readRemoteSecret = async (secrets) => {
+    if (!secrets) {
+        return undefined;
+    }
+    try {
+        if (!(await secrets.hasSecret('PIKKU_REMOTE_SECRET'))) {
+            return undefined;
+        }
+        return (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
+    }
+    catch (cause) {
+        throw new Error('Could not read PIKKU_REMOTE_SECRET from the secrets service; refusing to send an unauthenticated remote call', { cause });
+    }
+};
 /**
  * Authorization headers carrying a JWT-signed session and traceId for
  * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
@@ -9,11 +28,7 @@ export async function buildRemoteHeaders(jwt, secrets, funcName, session, traceI
         'content-type': 'application/json',
         ...(traceId && { 'x-request-id': traceId }),
     };
-    let secret;
-    try {
-        secret = (await secrets?.getSecret('PIKKU_REMOTE_SECRET'))?.reveal();
-    }
-    catch { }
+    const secret = await readRemoteSecret(secrets);
     if (secret && jwt) {
         assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret);
         const sessionEnc = session

package/dist/schema.d.ts

@@ -1,7 +1,24 @@
 import type { Logger } from './services/logger.js';
 import type { SchemaService } from './services/schema-service.js';
+/**
+ * Registers a JSON Schema by name for a package. Generated schema files call
+ * this; a module's `default` export is unwrapped.
+ *
+ * @param name - The schema name functions' metadata refers to.
+ * @param value - The schema, or a module whose `default` is the schema.
+ * @param packageName - The addon package; `null` for the app.
+ */
 export declare const addSchema: (name: string, value: any, packageName?: string | null) => void;
+/** The JSON Schema registered under `name` for a package, if any. */
 export declare const getSchema: (name: string, packageName?: string | null) => Record<string, unknown> | undefined;
+/**
+ * Hands every registered schema, for the app and every addon, to the schema
+ * service to compile, then logs an error for each HTTP route whose input
+ * schema did not load. A schema that fails to compile is logged, not thrown.
+ *
+ * @param schemaService - Defaults to the registered singleton services' `schema`.
+ * @throws {Error} When no schema service is given or registered.
+ */
 export declare const compileAllSchemas: (logger: Logger, schemaService?: SchemaService) => void;
 /**
  * Fills in absent top-level properties from their schema `default`. Applied
@@ -11,5 +28,24 @@ export declare const compileAllSchemas: (logger: Logger, schemaService?: SchemaS
  * or array default is never shared as one mutable instance across requests.
  */
 export declare const applyDefaultsFromSchema: (schemaName: string, data: any, packageName?: string | null) => any;
+/**
+ * Converts top-level string values to the type their schema property declares,
+ * for transports that only carry text (query strings, argv): comma-separated
+ * strings to arrays, `date-time` strings to `Date`, and numeric strings to
+ * numbers only when the number prints back as the identical text. Mutates
+ * `data` in place; anything it cannot convert exactly is left for the
+ * validator to reject.
+ */
 export declare const coerceTopLevelDataFromSchema: (schemaName: string, data: any, packageName?: string | null) => void;
+/**
+ * Validates `data` against a registered schema, throwing on failure.
+ *
+ * Without a schema service this does nothing at all, so an app that wires no
+ * `schema` service runs functions on unvalidated input. With one, a function
+ * that declares no input schema refuses any non-empty data.
+ *
+ * @throws {UnprocessableContentError} Data was passed where no schema is declared.
+ * @throws {MissingSchemaError} The named schema was never registered.
+ * Validation failures are thrown by the schema service itself.
+ */
 export declare const validateSchema: (logger: Logger, schemaService: SchemaService | undefined, schemaName: string | undefined | null, data: any, packageName?: string | null) => Promise<void>;

package/dist/schema.js

@@ -1,13 +1,30 @@
 import { MissingSchemaError, UnprocessableContentError, } from './errors/errors.js';
 import { pikkuState, getAllPackageStates } from './pikku-state.js';
 const schemaKey = (name, packageName) => packageName ? `${packageName}:${name}` : name;
+/**
+ * Registers a JSON Schema by name for a package. Generated schema files call
+ * this; a module's `default` export is unwrapped.
+ *
+ * @param name - The schema name functions' metadata refers to.
+ * @param value - The schema, or a module whose `default` is the schema.
+ * @param packageName - The addon package; `null` for the app.
+ */
 export const addSchema = (name, value, packageName = null) => {
     const schema = value?.default ?? value;
     pikkuState(packageName, 'misc', 'schemas').set(name, schema);
 };
+/** The JSON Schema registered under `name` for a package, if any. */
 export const getSchema = (name, packageName = null) => {
     return pikkuState(packageName, 'misc', 'schemas').get(name);
 };
+/**
+ * Hands every registered schema, for the app and every addon, to the schema
+ * service to compile, then logs an error for each HTTP route whose input
+ * schema did not load. A schema that fails to compile is logged, not thrown.
+ *
+ * @param schemaService - Defaults to the registered singleton services' `schema`.
+ * @throws {Error} When no schema service is given or registered.
+ */
 export const compileAllSchemas = (logger, schemaService) => {
     if (!schemaService) {
         schemaService = pikkuState(null, 'package', 'singletonServices')?.schema;
@@ -114,6 +131,14 @@ const coerceNumeric = (value, integer) => {
         return value;
     return parsed;
 };
+/**
+ * Converts top-level string values to the type their schema property declares,
+ * for transports that only carry text (query strings, argv): comma-separated
+ * strings to arrays, `date-time` strings to `Date`, and numeric strings to
+ * numbers only when the number prints back as the identical text. Mutates
+ * `data` in place; anything it cannot convert exactly is left for the
+ * validator to reject.
+ */
 export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = null) => {
     const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);
     if (!schema?.properties)
@@ -173,6 +198,17 @@ const stripUndefinedValues = (value) => {
         .filter(([, entry]) => entry !== undefined)
         .map(([key, entry]) => [key, stripUndefinedValues(entry)]));
 };
+/**
+ * Validates `data` against a registered schema, throwing on failure.
+ *
+ * Without a schema service this does nothing at all, so an app that wires no
+ * `schema` service runs functions on unvalidated input. With one, a function
+ * that declares no input schema refuses any non-empty data.
+ *
+ * @throws {UnprocessableContentError} Data was passed where no schema is declared.
+ * @throws {MissingSchemaError} The named schema was never registered.
+ * Validation failures are thrown by the schema service itself.
+ */
 export const validateSchema = async (logger, schemaService, schemaName, data, packageName = null) => {
     if (schemaService) {
         if (!schemaName) {

package/dist/services/agent-run-state-service.d.ts

@@ -1,7 +1,15 @@
 import type { AgentRunState, PendingApproval } from '../wirings/agent/agent.types.js';
 import type { AgentRunScore } from '../wirings/agent-scorer/agent-scorer.types.js';
+/** A run as it is first recorded; the store assigns the `runId`. */
 export type CreateRunInput = Omit<AgentRunState, 'runId'>;
+/** A scorer's grade as it is saved; the store stamps `createdAt`. */
 export type SaveScoreInput = Omit<AgentRunScore, 'createdAt'>;
+/**
+ * Persists agent runs between steps, so a run that stops for a tool approval
+ * can be resumed later, possibly by another process. Implementations must make
+ * {@link AgentRunStateService.resolveApproval} atomic: it is what stops one
+ * approval from executing a tool twice.
+ */
 export interface AgentRunStateService {
     createRun(run: CreateRunInput): Promise<string>;
     updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>;

package/dist/services/agent-runner-service.d.ts

@@ -1,5 +1,10 @@
 import type { AgentMessage, AgentStep, AgentToolDef, AgentStreamChannel } from '../wirings/agent/agent.types.js';
 export type AIProviderOptions = Record<string, Record<string, unknown>>;
+/**
+ * One model call as `runAgent` and `streamAgent` hand it to an {@link
+ * AgentRunnerService}: the resolved model, instructions, conversation so far
+ * and the tools the agent may call.
+ */
 export type AgentRunnerParams = {
     model: string;
     temperature?: number;
@@ -33,6 +38,10 @@ export type AgentRunnerParams = {
      */
     providerOptions?: AIProviderOptions;
 };
+/**
+ * The outcome of a whole agent run: the final text (or structured `object` when
+ * an output schema was set), every step taken, and summed token usage.
+ */
 export type AgentRunnerResult = {
     text: string;
     object?: unknown;
@@ -42,6 +51,10 @@ export type AgentRunnerResult = {
         outputTokens: number;
     };
 };
+/**
+ * What one model step produced: text, the tool calls it made and their results,
+ * token usage, and why the model stopped.
+ */
 export type AgentStepResult = {
     text: string;
     object?: unknown;
@@ -205,6 +218,17 @@ export type AIRerankResult<VALUE extends string | Record<string, unknown>> = {
     providerMetadata?: Record<string, unknown>;
     response?: unknown;
 };
+/**
+ * The bridge from pikku agents to an LLM SDK (for example `@pikku/ai-vercel`).
+ * The agent runner calls `run` or `stream` once per step and executes the
+ * returned tool calls itself, so approval, permission and tool-scoping checks
+ * stay in pikku rather than in the SDK.
+ *
+ * `stream` must write deltas to the channel as they arrive and resolve with the
+ * same step result `run` would return. The media methods (`transcribe`,
+ * `generateSpeech`, `generateImage`, `embed`, `embedMany`, `rerank`) are
+ * optional; a runner without one makes the matching agent feature unavailable.
+ */
 export interface AgentRunnerService {
     stream(params: AgentRunnerParams, channel: AgentStreamChannel): Promise<AgentStepResult>;
     run(params: AgentRunnerParams): Promise<AgentStepResult>;

package/dist/services/agent-storage-service.d.ts

@@ -1,4 +1,12 @@
 import type { AgentThread, AgentMessage } from '../wirings/agent/agent.types.js';
+/**
+ * Agent memory: conversation threads, their messages, and working memory kept
+ * per thread or per resource (usually the user).
+ *
+ * The agent runner reads the last messages of a thread before each run and
+ * saves the new ones after it. This service does not check access; callers that
+ * expose threads to users should check ownership first (see `canAccessThread`).
+ */
 export interface AgentStorageService {
     createThread(resourceId: string, options?: {
         threadId?: string;

package/dist/services/ai-embedding-service.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Turns text into vectors for semantic search. One instance is tied to one
+ * model, so vectors indexed by it and queries embedded by it stay comparable.
+ */
 export interface AIEmbeddingService {
     readonly model: string;
     readonly dimensions?: number;

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

@@ -1,12 +1,22 @@
 import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core.types.js';
 import type { Logger } from './logger.js';
 import type { Safe } from '../classification/secret-value.js';
+/**
+ * `best-effort` buffers events and writes them when the invocation closes,
+ * logging (not throwing) on failure; `transactional` writes each event before
+ * `write` resolves, so a failed write fails the function.
+ */
 export type AuditDurability = 'best-effort' | 'transactional';
 export type AuditOutcome = 'success' | 'failed' | 'denied';
 export type AuditSource = 'auto' | 'explicit';
+/**
+ * A function's `audit` setting: `true` for best-effort auditing, or an object
+ * choosing the durability.
+ */
 export type AuditConfig = boolean | {
     durability?: AuditDurability;
 };
+/** An {@link AuditConfig} with its defaults filled in. */
 export type ResolvedAuditConfig = {
     durability: AuditDurability;
 };
@@ -27,6 +37,11 @@ export type AuditUserIdentity = {
     orgId?: string;
     pikkuUserId?: string;
 };
+/**
+ * One entry in the audit trail. The invocation fields (`functionId`,
+ * `wireType`, `traceId`, `userIdentity`) are filled in from the wire when an
+ * event is written through an {@link AuditLog}.
+ */
 export type AuditEvent = {
     eventId?: string;
     type: string;
@@ -43,6 +58,7 @@ export type AuditEvent = {
     input?: unknown;
     metadata?: Record<string, unknown>;
 };
+/** Events flushed together at the end of a best-effort invocation. */
 export type AuditEventBatch = AuditEvent[];
 /**
  * A page of the trail, newest first, narrowed by the filters a reader picked.
@@ -76,6 +92,7 @@ export type AuditFacets = {
     userIds: string[];
     types: string[];
 };
+/** One page of audit events returned by {@link AuditService.query}. */
 export type AuditQueryResult = {
     events: AuditEvent[];
     /** Offset of the next page, or `null` at the end. */
@@ -83,6 +100,15 @@ export type AuditQueryResult = {
     /** Present only when the caller asked for it — it costs two extra scans. */
     facets?: AuditFacets;
 };
+/**
+ * The durable sink for audit events, provided as the `audit` singleton service.
+ * Functions do not call it directly: they write through the per-invocation
+ * {@link AuditLog} from {@link createInvocationAudit}, which adds the caller's
+ * identity and applies the function's durability.
+ *
+ * `write` takes a whole batch when the sink supports it; otherwise events go
+ * through `audit` one at a time.
+ */
 export interface AuditService {
     audit(event: AuditEvent): Promise<void>;
     write?(batch: AuditEventBatch): Promise<void>;
@@ -96,6 +122,12 @@ export interface AuditService {
     /** Distinct users and types across the whole trail. Paired with {@link query}. */
     facets?(): Promise<AuditFacets>;
 }
+/**
+ * An audit sink that discards every event. Use it for local development and
+ * tests where no trail is kept; it has no read side.
+ *
+ * @example snippet: shopServices
+ */
 export declare class NoopAuditService implements AuditService {
     audit(_event: AuditEvent): Promise<void>;
     write(_batch: AuditEventBatch): Promise<void>;
@@ -117,5 +149,21 @@ export interface AuditLog {
     close(): Promise<void>;
 }
 export declare const resolveAuditConfig: (config?: AuditConfig) => ResolvedAuditConfig | undefined;
+/**
+ * Creates the {@link AuditLog} for one invocation, normally from your
+ * wire-services factory.
+ *
+ * When the function did not opt in with `audit`, the returned log drops every
+ * write and logs a warning once, so a missing opt-in is visible rather than
+ * silent.
+ *
+ * @param service - the singleton audit sink
+ * @param wire - the invocation's wire, which supplies the audit config and the
+ * caller's identity
+ * @param logger - used for the dropped-write warning when the wire has no
+ * logger
+ *
+ * @example snippet: shopWireServices
+ */
 export declare const createInvocationAudit: (service: AuditService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger) => AuditLog;
 export declare const resolveAuditUserIdentityFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditUserIdentity | undefined;

package/dist/services/audit-service.js

@@ -1,3 +1,9 @@
+/**
+ * An audit sink that discards every event. Use it for local development and
+ * tests where no trail is kept; it has no read side.
+ *
+ * @example snippet: shopServices
+ */
 export class NoopAuditService {
     async audit(_event) { }
     async write(_batch) { }
@@ -92,6 +98,22 @@ export const resolveAuditConfig = (config) => {
         durability: config.durability ?? 'best-effort',
     };
 };
+/**
+ * Creates the {@link AuditLog} for one invocation, normally from your
+ * wire-services factory.
+ *
+ * When the function did not opt in with `audit`, the returned log drops every
+ * write and logs a warning once, so a missing opt-in is visible rather than
+ * silent.
+ *
+ * @param service - the singleton audit sink
+ * @param wire - the invocation's wire, which supplies the audit config and the
+ * caller's identity
+ * @param logger - used for the dropped-write warning when the wire has no
+ * logger
+ *
+ * @example snippet: shopWireServices
+ */
 export const createInvocationAudit = (service, wire, logger) => {
     if (!wire.audit) {
         return new DisabledInvocationAudit(wire, logger);