@pikku/addon-twist 0.0.2

package/dist/.pikku/function/pikku-function-types.gen.ts

@@ -0,0 +1,754 @@
+/**
+ * This file was generated by @pikku/cli@0.12.54
+ */
+/**
+ * Core function, middleware, and permission types for all wirings
+ */
+
+import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired } from '@pikku/core'
+import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
+import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
+import {
+  addTagMiddleware as addTagMiddlewareCore,
+  addGlobalMiddleware as addGlobalMiddlewareCore,
+  addTagPermission as addTagPermissionCore,
+  addGlobalPermission as addGlobalPermissionCore,
+} from '@pikku/core/middleware'
+import { pikkuState as __pikkuState, CreateWireServices } from '@pikku/core/internal'
+import type { NodeType } from '@pikku/core/node'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
+
+import type { UserSession } from '../../types/application-types.d.js'
+import type { SingletonServices } from '../../types/application-types.d.js'
+import type { Services } from '../../types/application-types.d.js'
+import type { Config } from '../../types/application-types.d.js'
+import type { TypedPikkuRPC, FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js'
+import type { RequiredSingletonServices, RequiredWireServices } from '../pikku-services.gen.js'
+import type { TypedWorkflow } from '../workflow/pikku-workflow-types.gen.js'
+
+export type { SingletonServices as SingletonServices }
+export type { Services as Services }
+export type Session = UserSession
+
+
+/**
+ * Inline node configuration for function definitions.
+ */
+export type NodeConfig = {
+  displayName: string
+  category: string
+  type: NodeType
+  errorOutput?: boolean
+}
+
+/**
+ * Type-safe API permission definition that integrates with your application's session type.
+ * Use this to define authorization logic for your API endpoints.
+ *
+ * @template In - The input type that the permission check will receive
+ * @template RequiredServices - The services required for this permission check
+ */
+export type PikkuPermission<In = unknown, RequiredServices extends Services = Services> = CorePikkuPermission<In, RequiredServices, PikkuWire<In, never, false, Session>>
+
+/**
+ * Type-safe middleware definition that can access your application's services and session.
+ * Use this to define reusable middleware that can be applied to multiple wirings.
+ *
+ * @template RequiredServices - The services required for this middleware
+ */
+export type PikkuMiddleware<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuMiddleware<RequiredServices>
+
+/**
+ * Configuration object for creating a permission with metadata
+ */
+export type PikkuPermissionConfig<In = unknown, RequiredServices extends Services = Services> = {
+  /** The permission function */
+  func: PikkuPermission<In, RequiredServices>
+  /** 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
+ * const permission = pikkuPermission(async ({ logger }, data, { session }) => {
+ *   const session = await session?.get()
+ *   return session?.role === 'admin'
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * const adminPermission = pikkuPermission({
+ *   name: 'Admin Permission',
+ *   description: 'Checks if user has admin role',
+ *   func: async ({ logger }, data, { session }) => {
+ *     const session = await session?.get()
+ *     return session?.role === 'admin'
+ *   }
+ * })
+ * ```
+ */
+export const pikkuPermission = <In>(
+  permission: PikkuPermission<In> | PikkuPermissionConfig<In>
+): PikkuPermission<In> => {
+  return typeof permission === 'function' ? permission : permission.func
+}
+
+/**
+ * Type-safe auth-only permission that only needs services and session.
+ * Use this for upfront authorization gates (MCP tools, AI agents, workflows)
+ * where request data isn't available yet.
+ *
+ * @template RequiredServices - The services required for this auth check
+ */
+export type PikkuAuth<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuAuth<RequiredServices, Session>
+
+/**
+ * Configuration object for creating an auth permission with metadata
+ */
+export type PikkuAuthConfig<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuAuthConfig<RequiredServices, Session>
+
+/**
+ * Factory function for creating auth-only permissions with tree-shaking support.
+ * Auth permissions only receive services and session (no request data),
+ * making them evaluable before request data is available.
+ *
+ * @example
+ * \`\`\`typescript
+ * const isAuthenticated = pikkuAuth(async ({ logger }, session) => {
+ *   return !!session
+ * })
+ *
+ * const isAdmin = pikkuAuth({
+ *   name: 'Admin Auth',
+ *   description: 'Checks if user is an admin',
+ *   func: async ({ logger }, session) => {
+ *     return session?.role === 'admin'
+ *   }
+ * })
+ * \`\`\`
+ */
+export const pikkuAuth = <RequiredServices extends SingletonServices = SingletonServices>(
+  auth: PikkuAuth<RequiredServices> | PikkuAuthConfig<RequiredServices>
+): PikkuPermission<any, any> => {
+  return pikkuAuthCore(auth as any) as any
+}
+
+/**
+ * Configuration object for creating middleware with metadata
+ */
+export type PikkuMiddlewareConfig<RequiredServices extends SingletonServices = SingletonServices> = {
+  /** The middleware function */
+  func: PikkuMiddleware<RequiredServices>
+  /** Optional human-readable name for the middleware */
+  name?: string
+  /** Optional description of what the middleware does */
+  description?: string
+}
+
+/**
+ * Factory function for creating middleware with tree-shaking support.
+ * Supports both direct function and configuration object syntax.
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * const middleware = pikkuMiddleware(({ logger }, wires, next) => {
+ *   logger.info('Middleware executed')
+ *   await next()
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs all incoming requests',
+ *   func: async ({ logger }, wires, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
+ */
+export const pikkuMiddleware = <RequiredServices extends SingletonServices = SingletonServices>(
+  middleware: PikkuMiddleware<RequiredServices> | PikkuMiddlewareConfig<RequiredServices>
+): PikkuMiddleware<RequiredServices> => {
+  return typeof middleware === 'function' ? middleware : middleware.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 = <In = any>(
+  factory: (input: In) => PikkuMiddleware
+): ((input: In) => PikkuMiddleware) => {
+  return factory
+}
+
+/**
+ * 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, { session }) => {
+ *     if (!session || session.role !== role) {
+ *       logger.warn(`Permission denied: required role '${role}'`)
+ *       return false
+ *     }
+ *     return true
+ *   })
+ * })
+ * ```
+ */
+export const pikkuPermissionFactory = <In = any>(
+  factory: (input: In) => PikkuPermission<any>
+): ((input: In) => PikkuPermission<any>) => {
+  return factory
+}
+
+/**
+ * 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 RequiredServices - The services required for this description function
+ */
+export type PikkuApprovalDescription<In = unknown, RequiredServices extends Services = Services> = (
+  services: RequiredServices,
+  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 = unknown, RequiredServices extends Services = Services>(
+  fn: PikkuApprovalDescription<In, RequiredServices>
+): PikkuApprovalDescription<In, RequiredServices> => {
+  return fn
+}
+
+/**
+ * A sessionless API function that doesn't require user authentication.
+ * Use this for public endpoints, health checks, or operations that don't need user context.
+ *
+ * @template In - The input type
+ * @template Out - The output type that the function returns
+ * @template RequiredServices - Services required by this function
+ */
+export type PikkuFunctionSessionless<
+  In = unknown,
+  Out = never,
+  RequiredWires extends keyof PikkuWire = never,
+  RequiredServices extends Services = Services
+> = CorePikkuFunctionSessionless<
+    In,
+    Out,
+    RequiredServices,
+    Session,
+    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow>, RequiredWires>
+  >
+
+/**
+ * A session-aware API function that requires user authentication.
+ * Use this for protected endpoints that need access to user session data.
+ *
+ * @template In - The input type
+ * @template Out - The output type that the function returns
+ * @template RequiredServices - Services required by this function
+ */
+export type PikkuFunction<
+  In = unknown,
+  Out = never,
+  RequiredWires extends keyof PikkuWire = 'session',
+  RequiredServices extends Services = Services
+> = CorePikkuFunction<
+    In,
+    Out,
+    RequiredServices,
+    Session,
+    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow>, RequiredWires>
+  >
+
+/**
+ * Helper type to infer the output type from a Standard Schema
+ */
+export type InferSchemaOutput<T> = T extends StandardSchemaV1<any, infer Output> ? Output : never
+
+/**
+ * Configuration object for Pikku functions with optional middleware, permissions, tags, and documentation.
+ * This type wraps CorePikkuFunctionConfig with the user's custom types.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @template PikkuFunc - The function type (can be narrowed to PikkuFunction or PikkuFunctionSessionless)
+ */
+export type PikkuFunctionConfig<
+  In = unknown,
+  Out = unknown,
+  RequiredWires extends keyof PikkuWire = never,
+  PikkuFunc extends PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema>
+
+/**
+ * Configuration object for Pikku functions with Zod schema validation.
+ * Use this when you want to define input/output schemas using Zod.
+ * Types are automatically inferred from the schemas.
+ */
+type SchemaInferred<S, Fallback = unknown> = S extends StandardSchemaV1
+  ? InferSchemaOutput<S>
+  : Fallback
+
+/**
+ * Schema-overload variant for pikkuFunc. Derived from CorePikkuFunctionConfig
+ * so adding a field on the core type automatically propagates here.
+ */
+export type PikkuFunctionConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  RequiredWires extends keyof PikkuWire = never
+> = Omit<
+  CorePikkuFunctionConfig<
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
+  func:
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  input?: InputSchema
+  output?: OutputSchema
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
+}
+
+/**
+ * Creates a Pikku function that can be either session-aware or sessionless.
+ * This is the main function wrapper for creating API endpoints.
+ *
+ * Supports two patterns:
+ * 1. Generic types: `pikkuFunc<Input, Output>({ func: ... })`
+ * 2. Zod schemas: `pikkuFunc({ input: z.object(...), output: z.object(...), func: ... })`
+ *
+ * @template In - Input type for the function (inferred from schema if provided)
+ * @template Out - Output type for the function (inferred from schema if provided)
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * ```typescript
+ * // Pattern 1: Using generic types
+ * const createUser = pikkuFunc<{name: string, email: string}, {id: number}>({
+ *   func: async ({db}, input) => {
+ *     const user = await db.users.create(input)
+ *     return { id: user.id }
+ *   }
+ * })
+ *
+ * // Pattern 2: Using Zod schemas (types inferred automatically)
+ * const createUserInput = z.object({ name: z.string(), email: z.string() })
+ * const createUserOutput = z.object({ id: z.number() })
+ *
+ * const createUser = pikkuFunc({
+ *   input: createUserInput,
+ *   output: createUserOutput,
+ *   func: async ({db}, input) => {
+ *     // input is typed as { name: string, email: string }
+ *     const user = await db.users.create(input)
+ *     return { id: user.id } // must match output schema
+ *   }
+ * })
+ * ```
+ */
+export function pikkuFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuFunctionConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
+export function pikkuFunc<In, Out = unknown>(
+  func:
+    | PikkuFunction<In, Out, 'session' | 'rpc'>
+    | PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+): PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+export function pikkuFunc(func: any) {
+  return typeof func === 'function' ? { func } : func
+}
+
+export type PikkuListFunction<
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+> =
+  | PikkuFunction<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'>
+  | PikkuFunctionSessionless<
+      ListInput<F, S>,
+      ListOutput<Row>,
+      'session' | 'rpc'
+    >
+
+export const pikkuListFunc = <
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+>(
+  config: PikkuFunctionConfig<
+    ListInput<F, S>,
+    ListOutput<Row>,
+    'session' | 'rpc'
+  >
+): PikkuFunctionConfig<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'> => {
+  return pikkuFunc(config)
+}
+
+/**
+ * Configuration object for sessionless Pikku functions with Zod schema validation.
+ */
+/**
+ * Schema-overload variant for pikkuSessionlessFunc. Derived from
+ * CorePikkuFunctionConfig to stay in sync with the generic-typed config.
+ */
+export type PikkuFunctionSessionlessConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  RequiredWires extends keyof PikkuWire = never
+> = Omit<
+  CorePikkuFunctionConfig<
+    PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
+  func: PikkuFunctionSessionless<
+    SchemaInferred<InputSchema>,
+    SchemaInferred<OutputSchema>,
+    RequiredWires
+  >
+  input?: InputSchema
+  output?: OutputSchema
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
+}
+
+/**
+ * Creates a sessionless Pikku function that doesn't require user authentication.
+ * Use this for public endpoints, webhooks, or background tasks.
+ *
+ * Supports two patterns:
+ * 1. Generic types: `pikkuSessionlessFunc<Input, Output>({ func: ... })`
+ * 2. Zod schemas: `pikkuSessionlessFunc({ input: z.object(...), func: ... })`
+ *
+ * @template In - Input type for the function (inferred from schema if provided)
+ * @template Out - Output type for the function (inferred from schema if provided)
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * ```typescript
+ * // Pattern 1: Using generic types
+ * const healthCheck = pikkuSessionlessFunc<void, {status: string}>({
+ *   func: async ({logger}) => {
+ *     return { status: 'healthy' }
+ *   }
+ * })
+ *
+ * // Pattern 2: Using Zod schemas
+ * const greetInput = z.object({ name: z.string() })
+ * const greetOutput = z.object({ message: z.string() })
+ *
+ * const greet = pikkuSessionlessFunc({
+ *   input: greetInput,
+ *   output: greetOutput,
+ *   func: async (_services, { name }) => {
+ *     return { message: `Hello, ${name}!` }
+ *   }
+ * })
+ * ```
+ */
+export function pikkuSessionlessFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
+export function pikkuSessionlessFunc<In, Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<In, Out, 'session' | 'rpc'>
+    | PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+): PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+export function pikkuSessionlessFunc(func: any) {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Creates a function that takes no input and returns no output.
+ * Useful for health checks, triggers, or cleanup operations.
+ *
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * ```typescript
+ * const cleanupTempFiles = pikkuVoidFunc(async ({fileSystem, logger}) => {
+ *     logger.info('Starting cleanup of temporary files')
+ *     await fileSystem.deleteDirectory('/tmp/uploads')
+ *     logger.info('Cleanup completed')
+ * })
+ * ```
+ */
+export const pikkuVoidFunc = (
+  func:
+    | PikkuFunctionSessionless<void, void, 'session' | 'rpc'>
+    | PikkuFunctionConfig<void, void, 'session' | 'rpc'>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * References a registered function by name for use in any wiring.
+ * Works for both local and addon functions — resolves via RPC at runtime.
+ *
+ * @template Name - The function name (must be a key in FlattenedRPCMap)
+ * @param rpcName - The name of the function to reference
+ * @returns A Pikku function config that proxies calls via RPC
+ *
+ * @example
+ * ```typescript
+ * // Use in agent tools
+ * tools: [ref('todos:listTodos'), ref('myLocalFunc')]
+ *
+ * // Use in HTTP wiring
+ * wireHTTP({ route: '/greet', method: 'post', func: ref('greet') })
+ * ```
+ */
+export const ref = <Name extends keyof FlattenedRPCMap>(
+  rpcName: Name
+): PikkuFunctionConfig<
+  FlattenedRPCMap[Name]['input'],
+  FlattenedRPCMap[Name]['output'],
+  'session' | 'rpc'
+> => {
+  return {
+    func: async (_services: any, data: FlattenedRPCMap[Name]['input'], { rpc }: any) => {
+      return rpc.invoke(rpcName, data)
+    }
+  } as PikkuFunctionConfig<
+    FlattenedRPCMap[Name]['input'],
+    FlattenedRPCMap[Name]['output'],
+    'session' | 'rpc'
+  >
+}
+
+/**
+ * Creates a Pikku config factory.
+ * Use this to define your application's configuration factory.
+ *
+ * @param func - Config factory function that returns your application's config
+ * @returns The config factory function
+ *
+ * @example
+ * ```typescript
+ * export const createConfig = pikkuConfig(async () => {
+ *   return {
+ *     apiUrl: process.env.API_URL || 'http://localhost:3000',
+ *     dbUrl: process.env.DATABASE_URL
+ *   }
+ * })
+ * ```
+ */
+export const pikkuConfig = (
+  func: (variables?: any, ...args: any[]) => Promise<Config>
+) => func
+
+
+/**
+ * Creates a Pikku singleton services factory.
+ * Use this to define services that are created once and shared across all requests.
+ *
+ * @param func - Singleton services factory function
+ * @returns The singleton services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createSingletonServices = pikkuServices(async (config, existingServices) => {
+ *   return {
+ *     config,
+ *     logger: new CustomLogger(),
+ *     db: await createDatabaseConnection(config.dbUrl)
+ *   }
+ * })
+ * ```
+ */
+export const pikkuServices = (
+  func: (config: Config, existingServices: Partial<SingletonServices>) => Promise<Partial<Omit<RequiredSingletonServices, 'auth'>>>
+) => {
+  return async (config: Config, existingServices: Partial<SingletonServices> = {}) => {
+    const createdServices = await func(config, existingServices)
+    const services = { ...existingServices, ...createdServices }
+    const authFactory = __pikkuState(null, 'package', 'authFactory')
+    if (authFactory) {
+      let authInstance: Promise<unknown> | undefined
+      ;(services as any).auth = () => {
+        authInstance ??= Promise.resolve()
+          .then(() => authFactory(services as any))
+          .catch((error) => {
+            authInstance = undefined
+            throw error
+          })
+        return authInstance
+      }
+    }
+    const resolved = services as RequiredSingletonServices
+    __pikkuState(null, 'package', 'singletonServices', resolved as any)
+    return resolved
+  }
+}
+
+/**
+ * Creates a Pikku wire services factory.
+ * Use this to define services that are created per-request/session.
+ *
+ * @param func - Wire services factory function
+ * @returns The wire services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createWireServices = pikkuWireServices(async (services, wire) => {
+ *   const session = await wire.session?.get()
+ *   return {
+ *     userCache: new UserCache(session?.userId)
+ *   }
+ * })
+ * ```
+ */
+export const pikkuWireServices = (
+  func: (
+    services: SingletonServices,
+    wire: any
+  ) => Promise<RequiredWireServices>
+): CreateWireServices => {
+  const factories = __pikkuState(null, 'package', 'factories')
+  __pikkuState(null, 'package', 'factories', { ...factories, createWireServices: func as any })
+  return func as unknown as CreateWireServices
+}
+
+/**
+ * Tag-scoped middleware. Applies to any wiring that carries the matching tag.
+ *
+ * @example
+ * addTagMiddleware('admin', [adminMiddleware])
+ */
+export const addTagMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
+  addTagMiddlewareCore(tag, middleware as any, '@pikku/addon-twist')
+}
+
+/**
+ * Wire-agnostic global middleware. Runs at the top of every wiring's
+ * middleware chain — before wire-, tag-, and function-level entries.
+ *
+ * Resolution order: global -> wire -> tag -> function.
+ *
+ * @example
+ * addGlobalMiddleware([telemetryMiddleware])
+ */
+export const addGlobalMiddleware = (middleware: PikkuMiddleware[]) => {
+  addGlobalMiddlewareCore(middleware as any, '@pikku/addon-twist')
+}
+
+/**
+ * Tag-scoped permissions. Applies to any wiring that carries the matching tag.
+ *
+ * @example
+ * addTagPermission('admin', [adminPermission])
+ */
+export const addTagPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
+  addTagPermissionCore(tag, permissions as any, '@pikku/addon-twist')
+}
+
+/**
+ * Wire-agnostic global permissions. Runs at the top of every wiring's
+ * permission resolution — before wire-, tag-, and function-level entries.
+ *
+ * Resolution order: global -> wire -> tag -> function.
+ *
+ * @example
+ * addGlobalPermission([signedInUser])
+ */
+export const addGlobalPermission = <In = unknown>(permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
+  addGlobalPermissionCore(permissions as any, '@pikku/addon-twist')
+}
+
+export { wireAddon } from '@pikku/core/rpc'
+export type { WireAddonConfig } from '@pikku/core/rpc'
+
+
+/**
+ * Addon contract references. Generated from each wired addon's published
+ * contract metadata — no addon source is imported. Functions are proxied via
+ * ref() (RPC) exactly like ref('namespace:fn').
+ */
+const __addonHttp = {} as const
+const __addonChannel = {} as const
+const __addonCli = {} as const
+
+export const refHTTP = <Name extends keyof typeof __addonHttp>(
+  name: Name,
+  options?: { basePath?: string }
+): (typeof __addonHttp)[Name] => {
+  const contract = __addonHttp[name] as any
+  return (
+    options?.basePath !== undefined
+      ? { ...contract, basePath: options.basePath }
+      : contract
+  ) as (typeof __addonHttp)[Name]
+}
+
+export const refChannel = <Name extends keyof typeof __addonChannel>(
+  name: Name
+): (typeof __addonChannel)[Name] => __addonChannel[name]
+
+export const refCLI = <Name extends keyof typeof __addonCli>(
+  name: Name
+): (typeof __addonCli)[Name] => __addonCli[name]