@pikku/core 0.12.72 → 0.12.77

package/src/function/function-runner.ts

@@ -1,9 +1,11 @@
+import { beginChanges } from './abort-scope.js'
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
+import { withoutSecrets } from '../services/secretless.js'
 import { pikkuState } from '../pikku-state.js'
 import {
   applyDefaultsFromSchema,
@@ -39,6 +41,11 @@ import {
 } from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { getOrCreatePackageSingletonServices } from '../wirings/rpc/addon-runner.js'
+import {
+  resolveAddonAuth,
+  resolveAddonScopes,
+  resolveAddonTagMiddleware,
+} from '../wirings/rpc/wire-addon.js'
 import type { AddonInstance } from '../wirings/rpc/addon-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -170,7 +177,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
 
-  // For addon packages, get or create their singleton services
+  const keepsSecrets = funcMeta.secretBroker === true
+
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(
         packageName,
@@ -179,7 +187,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
       )
     : singletonServices
 
-  // Get the package's createWireServices if available
   let resolvedCreateWireServices = createWireServices
   if (packageName) {
     const factories = pikkuState(packageName, 'package', 'factories')
@@ -203,11 +210,9 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       : wire
 
-  // Set up credential wire service early so middleware can use setCredential.
-  // An addon instance with credentialOverrides always gets a fresh alias-aware
-  // service so its logical credential names resolve to instance-specific ones,
-  // even when a parent credential service is already present on the wire.
-  // Otherwise skip if already set up (e.g. addon functions reuse the parent wire).
+  // Set up early so middleware can use setCredential. An addon instance with
+  // credentialOverrides always gets a fresh alias-aware service, even when a
+  // parent credential service is already present on the wire.
   if (addonInstance?.credentialOverrides) {
     // Credentials belong to the consuming project, so resolve them via the
     // project's credentialService (the addon's own singletons may not carry it).
@@ -251,7 +256,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
     invocationWire.addonNamespace = addonInstance.namespace
   }
 
-  // Helper function to run permissions and execute the function
   const executeFunction = async () => {
     await resolveSession(
       invocationWire,
@@ -270,7 +274,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
     const session = invocationWire.session
 
     if (funcMeta.sessionless) {
-      if (wiringAuth === true || funcConfig.auth === true) {
+      if (
+        wiringAuth === true ||
+        funcConfig.auth === true ||
+        resolveAddonAuth(packageName, addonInstance?.namespace)
+      ) {
         if (!session) {
           throw new ForbiddenError('Authentication required')
         }
@@ -290,32 +298,38 @@ export const runPikkuFunc = async <In = any, Out = any>(
       throw new ReadonlySessionError()
     }
 
-    // Scopes gate before the data is evaluated: they depend only on the
-    // session, so a denied request never pays to parse or validate its body.
-    // Scopes are an AND gate and stay separate from runPermissions, which
-    // evaluates the function's own OR-groups against request data.
-    verifyScopes(funcConfig.scopes ?? funcMeta.scopes, session)
+    // Only mutating functions get a checkpoint. A read has nothing to declare,
+    // and offering it there would invite the contradiction of a `readonly`
+    // function announcing where its changes begin.
+    if (!funcMeta.readonly) {
+      invocationWire.beginChanges = beginChanges
+    }
+
+    // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+    const addonScopes = resolveAddonScopes(
+      packageName,
+      addonInstance?.namespace
+    )
+    const functionScopes = funcConfig.scopes ?? funcMeta.scopes
+    verifyScopes(
+      addonScopes.length > 0
+        ? [...addonScopes, ...(functionScopes ?? [])]
+        : functionScopes,
+      session
+    )
 
-    // Evaluate the data from the lazy function
     let actualData = await data()
 
-    // Validate and coerce data if schema is defined
     const inputSchemaName = funcMeta.inputSchemaName
     if (inputSchemaName) {
-      // Fill in schema defaults before anything reads the data. Unconditional:
-      // a default belongs to the schema, not to the transport the call arrived
-      // on. Runs before coercion so a defaulted value and a supplied one are
-      // treated identically from here on.
       actualData = applyDefaultsFromSchema(
         inputSchemaName,
         actualData,
         packageName
       )
-      // Coerce (top level) data types before validation (e.g. string→array, string→date)
       if (coerceDataFromSchema) {
         coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
       }
-      // Validate request data against the defined schema, if any
       await validateSchema(
         resolvedSingletonServices.logger,
         resolvedSingletonServices.schema,
@@ -327,7 +341,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
     await runPermissions({
       funcPermissions: funcConfig.permissions,
-      services: resolvedSingletonServices,
+      services: keepsSecrets
+        ? resolvedSingletonServices
+        : (withoutSecrets(
+            resolvedSingletonServices,
+            'a permission'
+          ) as CoreSingletonServices),
       wire: invocationWire as any,
       data: actualData,
       packageName,
@@ -344,13 +363,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
-      // The audit gate is per-function, but the auditLog wire service is
-      // created per-transport-invocation — a nested/exposed-RPC call would
-      // otherwise inherit an auditLog constructed while the OUTER wire's
-      // audit was unset (e.g. the generated rpcCaller has no audit config),
-      // silently dropping every write. Re-gate here: if this function
-      // declares audit and the inherited auditLog wasn't built for this
-      // invocation (config identity check), bind a fresh one to this wire.
+      // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
       if (
         resolvedAuditConfig &&
         resolvedSingletonServices.audit &&
@@ -383,7 +396,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
         configurable: true,
         enumerable: true,
       })
-      return await funcConfig.func(services, actualData, invocationWire)
+      return await funcConfig.func(
+        keepsSecrets ? services : withoutSecrets(services, 'a pikku function'),
+        actualData,
+        invocationWire
+      )
     } finally {
       // Flush the runner-installed audit buffer before wire services close.
       await invocationAuditLog?.close()
@@ -393,9 +410,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  const addonTagMiddleware = resolveAddonTagMiddleware(
+    packageName,
+    addonInstance?.namespace
+  )
+
   const allMiddleware = combineMiddleware(wireType, wireId, {
     wireInheritedMiddleware: inheritedMiddleware,
-    wireMiddleware,
+    wireMiddleware:
+      addonTagMiddleware.length > 0
+        ? [...addonTagMiddleware, ...(wireMiddleware ?? [])]
+        : wireMiddleware,
     funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
     packageName,
@@ -447,5 +472,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     } else {
       invocationWire.audit = previousAudit
     }
+    if (previousAddonNamespace === undefined) {
+      delete (invocationWire as any).addonNamespace
+    } else {
+      invocationWire.addonNamespace = previousAddonNamespace
+    }
   }
 }

package/src/function/functions.types.ts

@@ -1,15 +1,18 @@
 import type {
   CoreServices,
-  CoreSingletonServices,
+  CoreSecretlessSingletonServices,
   CoreUserSession,
   CorePikkuMiddleware,
   PikkuWire,
   PickRequired,
+  SecretlessServices,
 } from '../types/core.types.js'
 import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { PikkuError } from '../errors/error-handler.js'
 import type { CoreNodeConfig } from '../wirings/node/node.types.js'
+import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js'
+import type { Safe } from '../secret-value.js'
 
 /**
  * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
@@ -17,18 +20,11 @@ import type { CoreNodeConfig } from '../wirings/node/node.types.js'
  */
 export type ZodLike<T = any> = StandardSchemaV1<T, T>
 
-/**
- * Represents a core API function that performs an operation using core services and a user session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
 export type CorePikkuFunction<
   In,
   Out,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Session extends CoreUserSession = CoreUserSession,
   Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> =
     PikkuWire<In, Out, true, Session>,
@@ -36,20 +32,15 @@ export type CorePikkuFunction<
   services: Services,
   data: In,
   wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+) => Wire['channel'] extends null
+  ? Promise<Safe<Out>>
+  : Promise<Safe<Out>> | Promise<void>
 
-/**
- * Represents a core API function that can be used without a session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
 export type CorePikkuFunctionSessionless<
   In,
   Out,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Session extends CoreUserSession = CoreUserSession,
   Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> =
     PikkuWire<In, Out, false, Session>,
@@ -57,71 +48,34 @@ export type CorePikkuFunctionSessionless<
   services: Services,
   data: In,
   wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+) => Wire['channel'] extends null
+  ? Promise<Safe<Out>>
+  : Promise<Safe<Out>> | Promise<void>
 
-/**
- * Represents a function that checks permissions for a given operation.
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
 export type CorePikkuPermission<
   In = any,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
     PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = (services: Services, data: In, wire: Wire) => Promise<boolean>
 
-/**
- * Configuration object for creating a permission with metadata
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
 export type CorePikkuPermissionConfig<
   In = any,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
     PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = {
-  /** The permission function */
   func: CorePikkuPermission<In, Services, Wire>
-  /** Optional human-readable name for the permission */
   name?: string
-  /** Optional description of what the permission checks */
   description?: string
 }
 
-/**
- * Factory function for creating permissions with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
- *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * })
- * ```
- */
 export const pikkuPermission = <
   In = any,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Wire extends PickRequired<
     PikkuWire<In, never, false, any, PikkuRPC, never, never>,
     'session'
@@ -137,41 +91,14 @@ export const pikkuPermission = <
   return typeof permission === 'function' ? permission : permission.func
 }
 
-/**
- * A factory function that takes input and returns a permission
- * Used when permissions need configuration/input parameters
- *
- * @template In - The input type for the factory.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
 export type CorePikkuPermissionFactory<
   In = any,
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
     PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = (input: In) => CorePikkuPermission<any, Services, Wire>
 
-/**
- * Factory function for creating permission factories
- * Use this when your permission needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
- *   role
- * }) => {
- *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
- *      const currentSession = await getSession()
- *     if (!currentSession || currentSession.role !== role) {
- *       logger.warn(`Permission denied: required role '${role}'`)
- *       return false
- *     }
- *     return true
- *   })
- * })
- * ```
- */
 export const pikkuPermissionFactory = <In = any>(
   factory: CorePikkuPermissionFactory<In>
 ): CorePikkuPermissionFactory<In> => {
@@ -179,33 +106,19 @@ export const pikkuPermissionFactory = <In = any>(
 }
 
 /**
- * A function that generates a human-readable description of a pending approval action.
- * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
- *
- * @template In - The input type (same as the function it describes).
- * @template Services - The services type, defaults to `CoreSingletonServices`.
+ * Renders a human-readable approval prompt for an AI agent, in place of the
+ * raw tool arguments.
  */
 export type CorePikkuApprovalDescription<
   In = any,
-  Services extends CoreSingletonServices = CoreSingletonServices,
+  Services extends CoreSecretlessSingletonServices =
+    CoreSecretlessSingletonServices,
 > = (services: Services, data: In) => Promise<string>
 
-/**
- * Factory function for creating approval description functions with tree-shaking support.
- *
- * @example
- * ```typescript
- * export const deleteTodoApproval = pikkuApprovalDescription(
- *   async ({ todoStore }, { id }) => {
- *     const todo = await todoStore.get(id)
- *     return `Delete todo: "${todo.title}"`
- *   }
- * )
- * ```
- */
 export const pikkuApprovalDescription = <
   In = any,
-  Services extends CoreSingletonServices = CoreSingletonServices,
+  Services extends CoreSecretlessSingletonServices =
+    CoreSecretlessSingletonServices,
 >(
   fn: CorePikkuApprovalDescription<In, Services>
 ): CorePikkuApprovalDescription<In, Services> => {
@@ -213,12 +126,14 @@ export const pikkuApprovalDescription = <
 }
 
 export type CorePikkuAuth<
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, session: Session) => Promise<boolean> | boolean
 
 export type CorePikkuAuthConfig<
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Session extends CoreUserSession = CoreUserSession,
 > = {
   func: CorePikkuAuth<Services, Session>
@@ -227,7 +142,8 @@ export type CorePikkuAuthConfig<
 }
 
 export const pikkuAuth = <
-  Services extends CoreSingletonServices = CoreServices,
+  Services extends CoreSecretlessSingletonServices =
+    SecretlessServices<CoreServices>,
   Session extends CoreUserSession = CoreUserSession,
 >(
   auth:
@@ -249,9 +165,9 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | undefined
 
 /**
- * A lifecycle hook: the same call signature as the function it hangs off, but
- * its return value is discarded. A hook is setup/teardown, not a step — it has
- * no id, no meta and no schema, so it is never recorded and never replayed.
+ * A lifecycle hook: same call signature as the function it hangs off, return
+ * value discarded. Setup/teardown, not a step — no id, no meta, no schema, so
+ * it is never recorded and never replayed.
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (
   services: Services,
@@ -273,15 +189,26 @@ export type CorePikkuFunctionConfig<
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   Scope extends string = string,
 > = {
-  /** Short human-readable name (e.g. "Create Todo") */
   title?: string
-  /** Longer-form description of what the function does */
   description?: string
   /** Explicit logical name override; lets multiple exports share a versioned base */
   override?: string
   version?: number
   tags?: string[]
   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`.
+   */
+  permissionsInBody?: boolean
   remote?: boolean
   mcp?: boolean
   readonly?: boolean
@@ -293,8 +220,12 @@ export type CorePikkuFunctionConfig<
   workflowRetries?: number
   /** Timeout for this function when 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 before calling it. */
-  browser?: boolean
+  /**
+   * Scenario steps only: which surfaces this step declares a binding for. The
+   * runner uses it to pick a binding, decide whether to provision a browser,
+   * and report how much of the flow each surface actually covers.
+   */
+  surfaces?: ScenarioSurface[]
   audit?:
     | boolean
     | {
@@ -309,26 +240,23 @@ export type CorePikkuFunctionConfig<
    */
   before?: CorePikkuFunctionHook
   /**
-   * Scenarios only: always runs after the scenario body, in a `finally`.
-   * Throwing fails a run that would otherwise have passed; on an
-   * already-failed run it attaches as the `cause` and never replaces the
-   * original error.
+   * Scenarios only: always runs after the body, in a `finally`. Throwing fails
+   * an otherwise-passing run; on an already-failed run it attaches as `cause`
+   * and never replaces the original error.
    */
   after?: CorePikkuFunctionHook
   /**
-   * Scenarios only: why this scenario is held out of a default run. It is
-   * reported as skipped rather than quietly omitted, and naming it directly
-   * with `--flows` runs it anyway.
+   * Scenarios only: why this scenario is held out of a default run. Reported
+   * as skipped rather than quietly omitted; naming it in `--flows` runs it.
    */
   skip?: string
   auth?: boolean
   /**
-   * Scopes the session must hold to run this function. All of them are
-   * required (AND), and they are checked before `permissions` — unlike
-   * permissions, which OR together, a scope can only narrow access.
-   *
-   * Narrowed to the generated `ScopeId` union in a project's own
-   * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+   * 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?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>
@@ -338,3 +266,32 @@ export type CorePikkuFunctionConfig<
   node?: CoreNodeConfig
   errors?: Array<typeof PikkuError>
 }
+
+/**
+ * {@link CorePikkuFunctionConfig} for a function that runs without a session.
+ *
+ * Identical, minus `scopes`. Scopes are AND-ed and `verifyScopes` fails closed,
+ * so an anonymous caller holds none and satisfies none — a sessionless function
+ * with scopes rejects every caller it exists to serve. Gate it with
+ * `permissions`, which receive the optional session and may pass anonymous.
+ */
+export type CorePikkuSessionlessFunctionConfig<
+  PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<any, any, any> =
+    CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+> = Omit<
+  CorePikkuFunctionConfig<
+    PikkuFunction,
+    PikkuPermission,
+    PikkuMiddleware,
+    InputSchema,
+    OutputSchema
+  >,
+  'scopes'
+>

package/src/function/index.ts

@@ -9,6 +9,7 @@ export type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuFunctionConfig,
+  CorePikkuSessionlessFunctionConfig,
   CorePikkuAuth,
   CorePikkuAuthConfig,
   CorePikkuPermission,

package/src/function/list.types.test.ts

@@ -1,15 +1,11 @@
 /**
- * Type-level tests for list-function primitives.
- *
- * No runtime assertions — the point is that valid shapes compile and
- * invalid shapes fail with `@ts-expect-error`. The file is excluded
- * from `yarn build` via tsconfig's `**∕*.test.ts` pattern.
+ * Type-level tests: no runtime assertions — valid shapes must compile and
+ * invalid shapes must fail with `@ts-expect-error`. Excluded from `yarn build`
+ * via tsconfig's test-file pattern.
  */
 
 import type { ListInput, ListOutput, Filter } from './list.types.js'
 
-// -- ListInput ---------------------------------------------------------------
-
 type SessionFilter = {
   status?: string[]
   therapistId?: string
@@ -32,22 +28,18 @@ void _basic
 const _empty: ListInput = {}
 void _empty
 
-// sort.column must be from the declared union
 // @ts-expect-error — 'created_at' is not in SessionSort
 const _badSort: ListInput<SessionFilter, SessionSort> = {
   sort: [{ column: 'created_at', direction: 'asc' }],
 }
 void _badSort
 
-// sort.direction must be 'asc' or 'desc'
 // @ts-expect-error — 'descending' is not a valid direction
 const _badDirection: ListInput<SessionFilter, SessionSort> = {
   sort: [{ column: 'user', direction: 'descending' }],
 }
 void _badDirection
 
-// -- ListOutput --------------------------------------------------------------
-
 interface Session {
   id: string
   user: string
@@ -61,39 +53,29 @@ const _output: ListOutput<Session> = {
 }
 void _output
 
-// nextCursor is required (must be string or null, not undefined-only)
 // @ts-expect-error — missing nextCursor
 const _badOutput: ListOutput<Session> = {
   rows: [],
 }
 void _badOutput
 
-// -- Filter: leaves ----------------------------------------------------------
-
-// Simple equality
 const _leafEq: Filter<SessionFilter> = { therapistId: 'kim' }
 void _leafEq
 
-// Array = IN shorthand
 const _leafIn: Filter<SessionFilter> = { status: ['pending', 'processed'] }
 void _leafIn
 
-// Operator object
 const _leafOp: Filter<SessionFilter> = {
   uploadedAt: { gt: '2026-04-10', lte: '2026-04-17' },
 }
 void _leafOp
 
-// Null = IS NULL
 const _leafNull: Filter<SessionFilter> = { therapistId: null }
 void _leafNull
 
-// NOT on a value
 const _leafNot: Filter<SessionFilter> = { therapistId: { not: 'kim' } }
 void _leafNot
 
-// -- Filter: AND (array) -----------------------------------------------------
-
 const _and: Filter<SessionFilter> = [
   { status: ['pending'] },
   { therapistId: 'kim' },
@@ -101,16 +83,12 @@ const _and: Filter<SessionFilter> = [
 ]
 void _and
 
-// -- Filter: OR (object with arbitrary label keys) --------------------------
-
 const _or: Filter<SessionFilter> = {
   viaKim: { therapistId: 'kim' },
   viaPark: { therapistId: 'park' },
 }
 void _or
 
-// -- Filter: nested AND/OR ---------------------------------------------------
-
 const _nested: Filter<SessionFilter> = [
   { status: ['pending'] },
   {