pipework 0.251.0 → 0.252.1

package/src/data/write/update.ts

@@ -0,0 +1,54 @@
+// `pipe.update(table)` — the pipework-owned update builder. Mirrors drizzle's
+// `db.update(table).set(...).where(...).returning(...)` API, but the chain
+// returns a builder that holds the intent as `WriteState` (see state.ts)
+// rather than a drizzle handle. That separation is what lets the CTE generator
+// (#45) intercept at execute time: it reads the same intent and compiles to a
+// single statement with `before` / `updated` / `diffs` / `audit_inserts` CTEs
+// when the active flow_step carries `@touches`. Without `@touches`, the
+// executor takes the vanilla-DML branch and the call behaves exactly like
+// drizzle's update would.
+//
+// The builder is `PromiseLike`: awaiting it runs the execute step. Before /
+// after capture is a side channel onto trace_step / audit_record (Q8) — it
+// never appears in the awaited shape.
+
+import type { PgTable } from '../query/pg-core/index.js'
+import type { UpdateSetValues } from './values.js'
+import type { SQL } from '../db/types.js'
+import { assertNotExternal } from '../domain/external-registry.js'
+import type { DefinedTable } from '../domain/types.js'
+import type { WriteState } from './state.js'
+import { executeWrite } from './execute.js'
+
+export class UpdateBuilder<T extends PgTable, TResult = unknown> implements PromiseLike<TResult> {
+  constructor(private readonly state: WriteState) {}
+
+  set(values: UpdateSetValues<T>): UpdateBuilder<T, TResult> {
+    return new UpdateBuilder<T, TResult>({ ...this.state, set: values as Record<string, unknown> })
+  }
+
+  where(condition: SQL): UpdateBuilder<T, TResult> {
+    return new UpdateBuilder<T, TResult>({ ...this.state, where: condition })
+  }
+
+  returning(): UpdateBuilder<T, Record<string, unknown>[]>
+  returning<TShape extends Record<string, unknown>>(shape: TShape): UpdateBuilder<T, Record<string, unknown>[]>
+  returning(shape?: Record<string, unknown>): UpdateBuilder<T, Record<string, unknown>[]> {
+    const returning = shape === undefined ? 'all' as const : shape
+    return new UpdateBuilder<T, Record<string, unknown>[]>({ ...this.state, returning })
+  }
+
+  then<TFulfilled = TResult, TRejected = never>(
+    onfulfilled?: ((value: TResult) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): PromiseLike<TFulfilled | TRejected> {
+    return executeWrite(this.state).then(onfulfilled as (value: unknown) => TFulfilled, onrejected) as PromiseLike<TFulfilled | TRejected>
+  }
+}
+
+/** Starts a pipework-owned update against `table`. Chain with `.set(...).where(...).returning(...)`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- DefinedTable's field generics are unused by the builder; PgTable is the surface drizzle's set/returning need
+export function update<T extends DefinedTable<any> & PgTable>(table: T): UpdateBuilder<T, any> {
+  assertNotExternal(table, 'update')
+  return new UpdateBuilder<T, unknown>({ verb: 'update', table })
+}

package/src/data/write/upsert.ts

@@ -0,0 +1,58 @@
+// `pipe.upsert(table)` — the pipework-owned upsert builder. Insert with a
+// conflict target; if `.set(...)` is provided, conflict rows are updated to
+// those values, otherwise the conflict is silently ignored (DO NOTHING).
+//
+// Same intent-based design as the other write builders — see update.ts for
+// the CTE-vs-vanilla rationale.
+
+import type { PgTable } from '../query/pg-core/index.js'
+import type { UpdateSetValues } from './values.js'
+import { assertNotExternal } from '../domain/external-registry.js'
+import type { DefinedTable } from '../domain/types.js'
+import type { WriteState } from './state.js'
+import type { InsertValues } from './values.js'
+import { executeWrite } from './execute.js'
+
+export class UpsertBuilder<T extends PgTable, TResult = unknown> implements PromiseLike<TResult> {
+  constructor(private readonly state: WriteState) {}
+
+  values(rows: InsertValues<T> | ReadonlyArray<InsertValues<T>>): UpsertBuilder<T, TResult> {
+    const normalized = Array.isArray(rows) ? rows : [rows]
+    return new UpsertBuilder<T, TResult>({
+      ...this.state,
+      values: normalized as ReadonlyArray<Record<string, unknown>>,
+    })
+  }
+
+  onConflict(columns: readonly (keyof T['$inferSelect'] & string)[]): UpsertBuilder<T, TResult> {
+    return new UpsertBuilder<T, TResult>({
+      ...this.state,
+      onConflictColumns: columns as readonly string[],
+    })
+  }
+
+  set(values: UpdateSetValues<T>): UpsertBuilder<T, TResult> {
+    return new UpsertBuilder<T, TResult>({ ...this.state, set: values as Record<string, unknown> })
+  }
+
+  returning(): UpsertBuilder<T, Record<string, unknown>[]>
+  returning<TShape extends Record<string, unknown>>(shape: TShape): UpsertBuilder<T, Record<string, unknown>[]>
+  returning(shape?: Record<string, unknown>): UpsertBuilder<T, Record<string, unknown>[]> {
+    const returning = shape === undefined ? 'all' as const : shape
+    return new UpsertBuilder<T, Record<string, unknown>[]>({ ...this.state, returning })
+  }
+
+  then<TFulfilled = TResult, TRejected = never>(
+    onfulfilled?: ((value: TResult) => TFulfilled | PromiseLike<TFulfilled>) | null,
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): PromiseLike<TFulfilled | TRejected> {
+    return executeWrite(this.state).then(onfulfilled as (value: unknown) => TFulfilled, onrejected) as PromiseLike<TFulfilled | TRejected>
+  }
+}
+
+/** Starts a pipework-owned upsert against `table`. Chain with `.values(...).onConflict([...]).set(...).returning(...)`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function upsert<T extends DefinedTable<any> & PgTable>(table: T): UpsertBuilder<T, any> {
+  assertNotExternal(table, 'upsert')
+  return new UpsertBuilder<T, unknown>({ verb: 'upsert', table })
+}

package/src/data/write/values.ts

@@ -0,0 +1,19 @@
+import type { InferInsertModel } from '../query/index.js'
+import type { PgTable } from '../query/pg-core/index.js'
+import type { PgUpdateSetSource } from '../query/pg-core/query-builders/update.js'
+
+export type { AcceptReadonly } from '../db/readonly.js'
+import type { AcceptReadonly } from '../db/readonly.js'
+
+/**
+ * The table's column-level insert shape: NOT NULL columns without a default are
+ * required, nullable or defaulted ones optional, no other keys. Auto-managed
+ * columns stay insertable. Tuple and array values may be readonly. Falls back to
+ * an open record for a table whose columns are not statically known (generic
+ * framework code).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- the open arm is the deliberate untyped fallback for DefinedTable<any>
+export type InsertValues<T extends PgTable> = string extends keyof InferInsertModel<T> ? Record<string, any> : T['$inferInsert'] | InferInsertModel<T> | { [K in keyof InferInsertModel<T>]: AcceptReadonly<InferInsertModel<T>[K]> }
+
+/** The `set(...)` shape of update and upsert, with tuple and array values allowed readonly. */
+export type UpdateSetValues<T extends PgTable> = PgUpdateSetSource<T> | { [K in keyof PgUpdateSetSource<T>]: AcceptReadonly<PgUpdateSetSource<T>[K]> }

package/src/index.ts

@@ -0,0 +1,230 @@
+export { StartupValidationError, type ValidationIssue, type ValidationPhase } from './core/validation/index.js'
+export { createManifold } from './core/pipework.js'
+export { discoverInstance, findConfig } from './core/config/discover.js'
+export type { ConnectionBudget } from './data/db/reservation.js'
+export type { Manifold, PoolState, IsolationState, ConnectionTracker, SeedOptions, ScriptOptions, StopResult } from './core/pipework.js'
+
+export { pipe, filter, excluded } from './data/db/namespace.js'
+export type { DB, SQL, Table, Column, TransactionConfig } from './data/db/namespace.js'
+export type { WindowSpec, WindowFrame, FrameBound } from './data/db/expressions.js'
+export type { Aggregate, EmptyableAggregate, AggregateOptions, JsonOf } from './data/db/aggregates.js'
+export type { ValueColumnDef } from './data/db/values.js'
+export type { ArraySource, ElementOf, JsonbElements } from './data/db/array-elements.js'
+export type { FunctionSpec, FunctionSource, FunctionSourceFields } from './data/db/function-source.js'
+export type { SerializableOptions } from './data/db/serializable.js'
+export { StatementTimeoutError, LockTimeoutError } from './data/db/timeouts.js'
+export type { TimeoutOptions } from './data/db/timeouts.js'
+
+// Standalone managed connection for contexts outside the manifold's AsyncLocalStorage —
+// worker_threads, detached monitors — where pipe()/pipeSystem() cannot resolve. The one
+// sanctioned door to a raw connection; keeps the WRAPPED_PACKAGES postgres ban airtight.
+export { tap } from './data/db/pool.js'
+export type { ManagedConnection, ConnectOptions } from './data/db/pool.js'
+export type { StatementObserver, StatementEvent } from './core/config/statement-observer.js'
+
+export type { DefinedTable, ExternalTable, DomainDefinition, DefinitionMethods, FieldDescriptor, FieldModifiers, FieldMeta, DefineOptions,
+  FactoryBuilder, FactoryOptions, TraitDefinition, FieldColumn, ProjectedColumns,
+  EffectiveDatedFields, AppendOnlyVersionsFields, AuditedFields, SoftDeletedFields,
+  FieldKind, FieldFlags, FieldRecord, ForeignKeyAction, CompositeForeignKey, PartitionSpec,
+  InsertProjection, SelectProjection, UpdateProjection,
+  Branded, Brand, InferSelect, InferFieldOutput } from './data/domain/index.js'
+
+export { schema } from './data/schema/namespace.js'
+export type { JsonSchema } from './data/schema/namespace.js'
+export type { Schema, Infer, StringSchema, NumberSchema, BooleanSchema, EnumSchema, LiteralSchema, ArraySchema, OptionalSchema, NullableSchema, ObjectSchema, ObjectOps } from './data/schema/types.js'
+// zod classes the validator types are made of, exported so an app without zod can name them in declaration emit
+export type { ZodString, ZodNumber, ZodBoolean, ZodEnum, ZodLiteral, ZodArray, ZodOptional, ZodNullable, ZodObject, ZodType, $strip, $ZodTypeInternals } from './data/schema/types.js'
+
+export { fitting } from './request/fitting/namespace.js'
+export type { Handler, HandlerMeta, RouteMeta, HttpMethod, InferDeps, InferReturn, DatabaseDeps, UploadConfig, BinaryUploadConfig, MultipartUploadConfig, BinaryUpload, MultipartUpload, UploadRefusal, UploadRefuseHook, RouteRefusal, RouteRefusedHook, FileConfig } from './request/di/types.js'
+export type { PermissionMeta, JobRetryConfig, JobTransactionMode, Checkpoint } from './request/di/types.js'
+export type { RouteScreen, ScreenedRequest, ScreenRefusal } from './request/di/types.js'
+
+export { http } from './request/http/namespace.js'
+export { createServer } from './request/http/server.js'
+export { detectMediaType, resolveMediaType, SNIFF_BYTES } from './request/http/sniff.js'
+export type { ServerConfig, CorsConfig, SecurityConfig, RateLimitConfig,
+  RateLimitClassesConfig, RateLimitClass, RateLimitWindow, RateLimitRefusal, InternalErrorFault,
+  ErrorResponse, HandlerResponse, InjectOptions, InjectResponse } from './request/http/types.js'
+export type { PipeworkServer } from './request/http/server.js'
+export type { FileResponse, FileResponseInit } from './request/http/file.js'
+
+export type { HttpRequest, HttpResponse } from './request/http/types.js'
+
+export { auth } from './auth/auth/namespace.js'
+export type { AuthStrategy, AuthRequest, AuthContext, BaseAuth } from './auth/auth/types.js'
+export type { AuthEnricher, TenantResolver, AuthChainConfig } from './auth/auth/chain.js'
+export type { SessionAuth, SessionStrategyOptions } from './auth/auth/sessions.js'
+export type { Sessions, SessionConfig, TokenPair, TokenPayload, HttpTokenResult } from './auth/auth/sessions.js'
+export type { CookieConfig } from './auth/auth/cookie.js'
+export type { Passwords, PasswordsConfig, ScryptParams, VerifyResult } from './auth/auth/passwords.js'
+export type { SignIn, SignInConfig, SignInAttempt, SignInResult } from './auth/auth/sign-in.js'
+export type { MultiOrgConfig, MultiOrgSessions, ResolveLoginResult,
+  AuthenticatedResult, OrgSelectResult, OrgMembership, OrgInfo, OrgMembershipDetail } from './auth/auth/multi-org.js'
+
+export { flow } from './request/flow/namespace.js'
+export type { Flow, RequestMetadata, BoundTransaction } from './request/context/index.js'
+
+export { tenant } from './auth/tenant/namespace.js'
+export type { TenantConfig, TenantContext, TenantExtractionResult } from './auth/tenant/index.js'
+
+export { rbac } from './auth/rbac/namespace.js'
+export type { RbacConfig, Rbac, PermissionSet, ResolvedPermission, Scope,
+  SeedData, SeedPermission, SeedRole, SeedRolePermission, SeedUserRole } from './auth/rbac/index.js'
+
+export { audit } from './infra/audit/namespace.js'
+export type { AuditConfig, AuditEmitOptions, Audit } from './infra/audit/index.js'
+export type { AuditQueryFilters, AuditQueryOptions, AuditQueryResult, AuditRecordRow,
+  AuditCursor } from './audit/query/index.js'
+export type { AuditChainHead, AuditChainBreak, AuditChainBreakReason, AuditVerifyOptions,
+  AuditVerifyResult } from './audit/chain/index.js'
+
+export { jobs } from './async/jobs/namespace.js'
+export { JobAbortedError, JobLaterError, JobPermanentError } from './async/jobs/index.js'
+export { serializeError } from './async/jobs/serialize-error.js'
+export type { ExecuteJobOptions, Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobClaim, JobClaimReason, ReapedJob, FailedAttempt, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig,
+  WaitOptions, WaitResult, ListenClient, ListenHandle, CronSchedule, ScheduleSpec,
+  ScheduleInfo, SchedulerOptions } from './async/jobs/index.js'
+
+export { steps } from './async/steps/namespace.js'
+export type { GraphConfig, GraphStepDefinition, GraphStepContext, GraphForEachContext, GraphRunInfo, GraphFailure,
+  GraphRunStatus, RequestOptions as StepRequestOptions, RequestResult as StepRequestResult, PlanOptions as StepPlanOptions,
+  PlanResult as StepPlanResult, StepPlan, StepCounts, TaskState as StepTaskState, RunTask as StepRunTask, RunStatus as StepRunStatus, EndedRun as StepEndedRun, EndedRunsOptions as StepEndedRunsOptions, DecideOptions as StepDecideOptions,
+  StepResultRecord, RemoveItemOptions as StepRemoveItemOptions, RemoveItemResult as StepRemoveItemResult,
+  StepGraph, GraphSelection } from './async/steps/index.js'
+export { StepItemRunningError } from './async/steps/index.js'
+
+export { cache } from './infra/cache/namespace.js'
+export type { CacheConfig, CacheStats, Cache, TenantCacheConfig, TenantCacheStats,
+  TenantCache } from './infra/cache/index.js'
+
+export { fixture } from './request/fixture/namespace.js'
+export type { Resource, ResourceOperations, ResourceMeta, ResourceId, PaginationConfig,
+  PaginationParams, PaginatedResponse, PageResult, CursorPaginationParams,
+  BatchAction, BatchTargets, BatchRequest } from './request/fixture/index.js'
+
+export { temporal } from './data/temporal/namespace.js'
+export type { TemporalOptions, ReviseOptions, ReviseResult, GetCurrentResult, DefinitionReviseOptions } from './data/temporal/index.js'
+
+export { vector } from './data/vector/namespace.js'
+export type { HeadlineOptions } from './data/vector/index.js'
+
+export { jsonb } from './data/jsonb/namespace.js'
+
+export { valve } from './data/valve/namespace.js'
+export type { ValveKind, ValveTopology, ValveDefinition, HandoffTrigger, CrossingMode,
+  ContractShape, ContractPayload, SupplyDefinition, SupplyBuilder,
+  GateTrigger, GateRetraction, GateDecision, GateDefinition, GateBuilder,
+  FaucetHandler, FaucetDefinition, FaucetBuilder,
+  CrossedResult, BlockedResult, HeldResult, FailedResult, SkippedResult,
+  SupplyCrossingResult, GateCrossingResult, CrossingResult, CrossingRecord, CrossingJobPayload,
+  DecisionOutcome, Crossed, Held, Failed, ContractArtifact, ContractDiff,
+  ValveGraph, ValveGraphNode, ValveGraphEdge, ValveNodeKind, ValveEdgeKind } from './data/valve/index.js'
+
+export { pipeline } from './async/pipeline/namespace.js'
+export type { PipelineConfig, Pipeline, PipelineRun, PipelineExecuteContext,
+  StepDefinition, StepContext, StepRunResult } from './async/pipeline/index.js'
+
+export { state } from './async/state-machine/namespace.js'
+export type { StateMachineConfig, TransitionDef, TransitionContext, TransitionResult,
+  StateMachine } from './async/state-machine/index.js'
+
+export { behavior } from './request/behavior/namespace.js'
+export type { BehaviorConfig, VersionedBehaviorConfig, AuditedBehaviorConfig,
+  InvalidationBehaviorConfig } from './request/behavior/index.js'
+
+export { openapi } from './request/openapi/namespace.js'
+export type { OpenAPIDocument, OpenAPIInfo } from './request/openapi/index.js'
+
+export { lifecycle } from './core/lifecycle/namespace.js'
+export type { LifecycleConfig, StartupHook, ShutdownHook, HealthCheck,
+  HealthCheckResult, HealthStatus, StartupOptions } from './core/lifecycle/index.js'
+
+export { createIdempotency } from './infra/idempotency/index.js'
+export type { IdempotencyConfig, IdempotencyMiddleware, IdempotencyRecord, IdempotencyStore } from './infra/idempotency/index.js'
+
+export { webhook } from './infra/webhook/namespace.js'
+export { defineInboundWebhook, createOutboundWebhook } from './infra/webhook/index.js'
+export type { InboundWebhookConfig, InboundWebhookContext, SignatureVerifier,
+  OutboundWebhookConfig, OutboundWebhook, WebhookEndpoint, DeliveryAttempt,
+  SignedPayload, WebhookSignatureOptions } from './infra/webhook/index.js'
+
+export { mail } from './infra/email/namespace.js'
+export { awsCredentials, SEND_JOB, RECEIVE_JOB } from './infra/email/index.js'
+export type { Mail, MailConfig, SendInput, SendResult, RenderedEmail, EmailTemplates, EmailRenderMeta,
+  MailProvider, OutgoingMessage, SesConfig, SnsWebhookConfig, AwsCredentials,
+  Inbound, InboundConfig, InboundSource, InboundRecord, InboundScanResult, InboundSweepResult, ReceivedEmail, ReceivedAttachment,
+  EmailAddress, EmailVerdicts, FromProblem, UnthreadedEmail, SesReceiptConfig } from './infra/email/index.js'
+
+export { credits } from './infra/credits/namespace.js'
+export type { Credits, CreditsConfig, CreditGrant, GrantOptions, GrantResult, CreditReservation, ReserveResult,
+  CreditBalance, CreditLedgerEntry, HistoryOptions, HistoryPage, LowBalanceState, LowBalanceCrossing } from './infra/credits/index.js'
+export { creditLine } from './infra/credit-line/namespace.js'
+export type { CreditLine, CreditLineConfig, CreditLineCap, CapWindow, LineCrossing, LimitRef, LineReserveResult,
+  LineReservation, LineState, LineCapState, LineEntry, Payment, PaymentApplication, PaymentWithEntries,
+  Authorization, AuthorizationStatus, Statement, OpenLineOptions, AuthorizeOptions } from './infra/credit-line/index.js'
+export { quota } from './infra/quota/namespace.js'
+export { QuotaExhaustedError } from './infra/quota/index.js'
+export type { Quota, QuotaConfig, QuotaHeaders, QuotaHeaderInput, QuotaBudget, QuotaState, QuotaCallOptions } from './infra/quota/index.js'
+export { alerts } from './infra/alerts/namespace.js'
+export type { Alerts, AlertsConfig, Alert, AlertSeverity, AlertSubject, RaiseOptions as AlertRaiseOptions, DeliveryRow as AlertDeliveryRow,
+  TickResult as AlertsTickResult, AlertSink, AlertDelivery, AlertPayload, AlertEventPayload, AlertDigestPayload, AlertWebhookConfig, MemoryAlertSink, AlertSource,
+  AlertCondition, AlertStatus, JsonValue as AlertJsonValue, AlertOccurrence, Page as AlertPage, AlertTotals, DeliveryHealth as AlertDeliveryHealth,
+  ResolveOptions as AlertResolveOptions, AlertsHttpOptions, ClientFaultsOptions,
+  OwnerChange as AlertOwnerChange, ClientFaultReport, RequestFaultsOptions as AlertRequestFaultsOptions } from './infra/alerts/index.js'
+export { support } from './infra/support/namespace.js'
+export { DraftStateError } from './infra/support/index.js'
+export type { SupportHttpOptions } from './infra/support/index.js'
+export type { Support, SupportConfig, TicketApi as SupportTicketApi, Ticket as SupportTicket, TicketMessage as SupportMessage,
+  TicketLink as SupportLink, TicketDetail as SupportTicketDetail, TicketState as SupportTicketState, ListOptions as SupportListOptions,
+  ListPage as SupportListPage, DraftInput as SupportDraftInput, ReceiveResult as SupportReceiveResult, ReceiveInput as SupportReceiveInput,
+  SupportEventKind, SupportEventPayload, SupportSink, SupportDelivery, ScreenVerdict as SupportScreenVerdict } from './infra/support/index.js'
+export type { Sink, SinkDelivery } from './infra/outbox/core.js'
+export { storage } from './infra/storage/namespace.js'
+export type { Storage, StorageConfig, StoredFile, PutOptions as StoragePutOptions, FindOptions as StorageFindOptions, SignedUrlOptions as StorageSignedUrlOptions,
+  SweepOptions as StorageSweepOptions, SweepResult as StorageSweepResult, StorageBackend, S3Config, S3Encryption,
+  LocalConfig as StorageLocalConfig } from './infra/storage/index.js'
+export { untrustedFetch, connectRetry } from './infra/fetch/namespace.js'
+export type {
+  ConnectRetryOptions, UntrustedFetchOptions, UntrustedPostOptions, UntrustedFetchResult, FetchHead, FetchTarget, FetchRefusal } from './infra/fetch/index.js'
+export { crawl } from './infra/crawl/namespace.js'
+export type {
+  CrawlConfig, CrawlSite, CrawlStartOptions, CrawlLimits, CrawlScope, CrawlState, CrawlStoppedBy, CrawlStatus, CrawlCounts,
+  CrawlResource, CrawlRefusal, CrawlPage } from './infra/crawl/index.js'
+export { CrawlNotEnabledError, CrawlSeedError } from './infra/crawl/index.js'
+export { accessLinks } from './infra/access-links/namespace.js'
+export type { AccessLinks, AccessLinksConfig, AccessLink, PublicLink, AccessLinkUse, AccessLinkTarget, AccessLinkListed, AccessLinkPage,
+  AccessLinkCheck, AccessLinkCheckArgs, LinkOptions, ResolveResult, BeginUseResult,
+  CompleteUseResult, AbandonUseResult, PersonCheck, PersonCheckConfig, PersonChallenge, PersonPass,
+  CodeConfig as AccessLinkCodeConfig } from './infra/access-links/index.js'
+
+export { joinRequests } from './infra/join-requests/namespace.js'
+export type { JoinRequests, JoinRequestsConfig, JoinRequest, JoinRequestStatus, SettleResult as JoinRequestSettleResult } from './infra/join-requests/index.js'
+
+export { surface } from './core/surface/namespace.js'
+export type { Surface, SurfaceKind, SurfaceHandle, SurfaceManifest, SurfaceContext, SurfaceMap,
+  HttpSurfaceConfig, HttpSurfaceBuilder, TestClient,
+  WorkerSurfaceConfig, JobEvent, JobEventJob, ScriptSurfaceConfig, ScriptContext,
+  RetryConfig } from './core/surface/index.js'
+
+export { errors } from './core/errors/namespace.js'
+export { PipeworkError, isPipeworkError, NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError,
+  ValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './core/errors/index.js'
+
+export { config } from './core/config/namespace.js'
+export type { ResolvedConfig, ResolvedDatabase, ResolvedObservability, Blueprint, DatabaseConfig,
+  TestConfig, Environment, IsolationStrategy, ObservabilityConfig, ModuleConfig,
+  EnvVarDef, EnvDefs, ResolveEnvDefs } from './core/config/index.js'
+export { ConfigError } from './core/config/index.js'
+
+export { log } from './core/logging/namespace.js'
+export { describeError } from './core/logging/error-chain.js'
+export type { ErrorLink, ErrorDescription } from './core/logging/error-chain.js'
+export type { LoggerConfig, LogLevel, PipeworkLogger, LoggingConfig, ContextField } from './core/logging/index.js'
+
+export { __flowStep } from './trace/runtime/flow-step.js'
+export type { FlowStepMeta } from './trace/runtime/step-meta.js'
+
+export { trace } from './trace/namespace.js'
+export type { ExternalStepReport, ExternalRecordResult } from './trace/external/report.js'
+export type { TraceTree, TraceNode, TraceStepNode } from './trace/read/tree.js'

package/src/infra/access-links/code.ts

@@ -0,0 +1,70 @@
+// Random short codes. Every character is drawn by rejection sampling over
+// crypto bytes, so no character is more likely than another (a plain modulo
+// would favour the first `256 % alphabetSize` characters).
+
+import { randomBytes } from 'node:crypto'
+
+export const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+export const LOOKALIKES = '0Oo1lI'
+export const DEFAULT_CODE_LENGTH = 6
+export const MIN_CODE_LENGTH = 4
+export const MAX_CODE_LENGTH = 32
+
+export interface CodeConfig {
+  /** Characters per code. Default 6, min 4, max 32. */
+  readonly length?: number
+  /** The characters a code is drawn from. Default base62 (`0-9A-Za-z`), case-sensitive. */
+  readonly alphabet?: string
+  /** Drop `0 O o 1 l I` from the alphabet. Default false. */
+  readonly excludeLookalikes?: boolean
+}
+
+export interface CodeGenerator {
+  readonly length: number
+  readonly alphabet: string
+  next(): string
+}
+
+export function createCodeGenerator(config: CodeConfig = {}): CodeGenerator {
+  const length = config.length ?? DEFAULT_CODE_LENGTH
+  if (!Number.isInteger(length) || length < MIN_CODE_LENGTH || length > MAX_CODE_LENGTH) {
+    throw new Error(
+      `[pipework] accessLinks code length must be an integer from ${MIN_CODE_LENGTH} to ${MAX_CODE_LENGTH}, got ${String(length)}.\n`,
+    )
+  }
+
+  let chars = [...new Set(config.alphabet ?? BASE62)]
+  if (config.excludeLookalikes === true) chars = chars.filter(c => !LOOKALIKES.includes(c))
+  if (chars.length < 2 || chars.length > 256) {
+    throw new Error(
+      `[pipework] accessLinks code alphabet must have 2 to 256 distinct characters after exclusions, got ${chars.length}.\n`,
+    )
+  }
+  if (chars.some(c => c.length !== 1 || c === '.' || /\s/.test(c))) {
+    throw new Error(
+      '[pipework] accessLinks code alphabet must be single characters without "." or whitespace — a code appears in URLs and in use tokens.\n',
+    )
+  }
+
+  const alphabet = chars.join('')
+  const size = chars.length
+  // Bytes at or above `limit` are rejected: the rest map onto the alphabet evenly.
+  const limit = Math.floor(256 / size) * size
+
+  return {
+    length,
+    alphabet,
+    next(): string {
+      let out = ''
+      while (out.length < length) {
+        const bytes = randomBytes((length - out.length) * 2)
+        for (const byte of bytes) {
+          if (byte >= limit) continue
+          out += chars[byte % size]
+          if (out.length === length) break
+        }
+      }
+      return out
+    },
+  }
+}