pipework 0.10.8 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.12.0
+
+- **Fix: a `PipeworkError` thrown by a shared library that resolved its own copy of pipework now maps to its real HTTP status (403/401/…) instead of a generic 500.** When a self-contained pipework workspace consumes a shared leaf library that also imports pipework at runtime, pnpm resolves two physical copies of pipework — so the library's `ForbiddenError` and the workspace's `ForbiddenError` are distinct class objects and `instanceof` between them is `false`. The HTTP error mapper keyed on `instanceof PipeworkError`, so a leaf-thrown error was unrecognized and fell through to 500 (and `.rejects.toThrow(ForbiddenError)` across the boundary failed even though the right error was thrown). Error identity is now carried on a global-`Symbol` brand (`Symbol.for('pipework.error')`) — the same cross-realm technique drizzle uses for table identity — and the mapper checks the brand, not the constructor. A new public predicate **`isPipeworkError(error)`** is exported for consumers whose own handlers have the same `instanceof` exposure. Issue #333.
+- **Fix: a shared leaf library and its consuming workspace now share one request context (AsyncLocalStorage), and two incompatible pipework versions in one process fail loudly instead of silently.** The request ALS was a plain module singleton, so the two physical copies above each had their own `AsyncLocalStorage` — a context entered by the workspace was invisible to `pipe()` called from the leaf ("No active context" on a live request). The ALS (and the version that owns it) is now pinned to a process-global slot keyed by `Symbol.for('pipework.runtime')`: same-version copies share one ALS (N copies behave as one), and a second copy of a *different* version throws an actionable error naming both versions rather than forking silently. The connection pool was never a separate singleton (it hangs off the context's instance), so it is fixed transitively.
+- **Fix: `pipe.insert` / `pipe.update` / `pipe.upsert` / `pipe.remove` now accept a concrete table.** Their generic was constrained to `DefinedTable<FieldRecord> & PgTable`, but a concrete `pipe.define(...)` result (`DefinedTable<{ specific fields }>`) is not assignable to `DefinedTable<FieldRecord>` (the projected columns are invariant under the field generics) — so `pipe.insert(myTable)` failed to type-check for callers. The constraint is relaxed to `DefinedTable<any> & PgTable`, matching the pattern already used elsewhere for the same reason. Row-type inference is unchanged (the concrete table type still flows through).
+- **Fix: manual-transaction jobs (`.transaction('manual')`) no longer expose the database handles at the top level of the handler deps, and handler deps no longer carry a `[string]: never` index signature.** The base builder deps type was `Record<string, never>`, an index signature that (a) made `Omit<TDeps, keyof TDb>` unable to remove the declared databases — so a manual-mode handler's deps type still appeared to carry `app` (a non-transactional handle that is a footgun, the exact thing the mode prevents) — and (b) made `deps.anyTypo` resolve to `never` instead of a compile error for every handler. The base is now `Record<never, never>`: manual mode correctly strips the db deps (they appear only inside `checkpoint`'s callback), and a typo'd dependency is now a type error.
+
+## 0.11.0
+
+- **Feature: jobs can own their transaction boundaries — `fitting.job(...).transaction('manual')` opts a job out of the single framework-owned outer transaction.** Every tenant job was wrapped, by the framework, in one outer transaction around its whole `.fit` run (`src/async/jobs/execute.ts`), making the job strictly all-or-nothing: a long sequence of independently-valid work either committed as one transaction or was lost entirely — a failure near the end rolled back the whole run, and the single long-open transaction pinned a snapshot (blocking vacuum) and held its connection for the job's full duration. A job that genuinely wants **one warm process** (to amortize in-memory state across a long run) but **many transactions** (to checkpoint progress durably) had no way to express it: an in-handler `pipe.transaction()` nests as a savepoint inside the outer tx, so it only commits when the whole job commits. `.transaction('manual')` separates the transaction axis from the process axis. In manual mode the framework builds the job context (tenant, trace, resolved databases) but opens **no** outer transaction; instead the handler receives a `checkpoint(fn)` primitive — each call opens a fresh top-level, tenant-scoped transaction (re-establishing the `SET LOCAL pipework.tenant_id` / custom session vars so database-side RLS sees the tenant on every checkpoint), runs `fn` with the declared databases bound as **raw** transactions, and commits it independently. The databases declared with `.use()` move out of the top-level deps (a non-transactional handle there would be a footgun) and into `checkpoint`'s callback; non-database deps (`auth`, `input`, …) stay at the top level. Multi-DB jobs get one independent transaction per database inside each checkpoint, and an outbox enqueue issued inside a checkpoint (`queue.enqueue(db, …)` with the checkpoint's handle) rides that checkpoint's commit. The contract shifts deliberately: a manual-mode job is **at-least-once / idempotent-on-resume**, not atomic — a crash after committing checkpoints 0..N leaves them committed, the job is re-claimed, and the handler must **resume** (it owns its idempotency key), not restart. Default jobs are unchanged (single outer transaction). Misuse fails at definition: `.transaction('manual')` without `.job(...)`, or without any `.use(...)`, throws an actionable error from `.fit()`. New `JobTransactionMode` and `Checkpoint<TDb>` exported types. Issue #332.
+
 ## 0.10.8
 
 - **Fix: a multi-database app could not make a bare `db()` / `pipe()` call — every no-name database resolution threw `ConfigError: Multiple databases configured` at runtime.** With >1 database declared, `defaultDatabaseName()` and `database(undefined)` had no way to know which database was primary, so they threw on *any* ambiguity. That throw is correct safety for a genuinely-ambiguous config, but there was no way to *resolve* the ambiguity short of naming the database at every call site — turning the addition of a second (e.g. read-only) database into a sweep across every bare `db()`/`pipe()` in the app. Configs now declare the default once: a top-level `defaultDatabase: '<name>'` (a key of `databases`). When set, both no-name resolvers return that database; the throw is preserved only for multi-DB configs with *no* default declared (still genuinely ambiguous) and single-DB configs are unchanged (the sole database is always the default, no declaration needed). `defaultDatabase` naming an undeclared database is a load-time `ConfigError` with a closest-match suggestion. Complements 0.10.6, which fixed the parallel throw on the *test-harness* template path; this fixes the runtime resolution path.

package/REFERENCE.md

@@ -1,7 +1,7 @@
 # Pipework API Reference
 
 > Auto-generated from source JSDoc. Do not edit manually.
-> Generated: 2026-05-13
+> Generated: 2026-06-29
 
 ## Contents
 
@@ -21,6 +21,7 @@
 - [jsonb — JSONB Column Helpers](#jsonb-jsonb-column-helpers)
 - [schema — Validation & Schema](#schema-validation-schema)
 - [temporal — Bitemporal Data](#temporal-bitemporal-data)
+- [valve](#valve)
 - [vector — Vector & Full-Text Search](#vector-vector-full-text-search)
 - [audit — Audit Logging](#audit-audit-logging)
 - [cache — Caching](#cache-caching)
@@ -31,6 +32,8 @@
 - [flow — Context (AsyncLocalStorage)](#flow-context-asynclocalstorage)
 - [http — Server](#http-server)
 - [openapi — API Documentation](#openapi-api-documentation)
+- [test](#test)
+- [trace](#trace)
 
 ## Core
 
@@ -41,7 +44,7 @@ Application instance and foundational types.
 Creates the Pipework application instance. This is the entry point for every Pipework app. Define in `pipework.config.ts` and export as default. /
 
 ```typescript
-function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<Blueprint, 'env'> &
+function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<BlueprintInput, 'env'> &
 ```
 
 ### Types
@@ -52,7 +55,7 @@ function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<Bluepri
 interface Manifold<TEnv extends EnvDefs = EnvDefs>
 ```
 
-**`SeedOptions`**
+**`SeedOptions`** — ALS context the {@link Manifold.seed} callback runs under — tenant scope, auth principal, and job type.
 
 ```typescript
 interface SeedOptions
@@ -330,7 +333,7 @@ Returns the SQL string for a tenant isolation RLS policy — use in migrations.
 
 ### `tenant.verify`
 
-Cross-checks ALS tenant against Postgres set_config('pipework.tenant_id') — defense-in-depth.
+Cross-checks the ALS principal (tenant, user, asOf) against the Postgres session GUCs — defense-in-depth.
 
 ### `tenant.propagate`
 
@@ -444,10 +447,47 @@ Creates a script surface — a one-shot process that runs and exits (migrations,
 
 Database accessor — returns a Drizzle DB instance scoped to the current request/job/test context. Requires active AsyncLocalStorage context.
 
+### `pipe.system`
+
+The system channel — deliberate cross-tenant access for pre-tenant surfaces (auth membership resolution, public webhook ingress, admin tooling). Never tenant-scoped or tenant-guarded; runs on the owner-role connection outside the request transaction.
+
 ### `pipe.filter`
 
 Query operators and aggregates — eq, gt, lt, and, or, count, sum, etc.
 
+### `pipe.aliasedRelation`
+
+
+### `pipe.aliasedTable`
+
+
+### `pipe.aliasedTableColumn`
+
+
+### `pipe.getTableColumns`
+
+
+### `pipe.getTableName`
+
+
+### `pipe.getViewName`
+
+
+### `pipe.getViewSelectedFields`
+
+
+### `pipe.isTable`
+
+
+### `pipe.createMany`
+
+
+### `pipe.createOne`
+
+
+### `pipe.relations`
+
+
 ### `pipe.migrate`
 
 Runs migrations for all configured databases.
@@ -488,21 +528,37 @@ Registers a domain definition with table, validators, and factory projections.
 
 Returns the global registry of all domain definitions.
 
+### `pipe.update`
+
+Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8).
+
+### `pipe.insert`
+
+Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8).
+
+### `pipe.delete`
+
+Pipework-owned DELETE builder — the only consumer-facing way to delete from pipework-managed tables (Q8).
+
+### `pipe.upsert`
+
+Pipework-owned UPSERT builder — insert with conflict resolution (Q8).
+
 ### Types
 
-**`WindowSpec`**
+**`WindowSpec`** — A window-frame specification — the `PARTITION BY` / `ORDER BY` clauses applied by {@link over}.
 
 ```typescript
 interface WindowSpec
 ```
 
-**`ValueColumnDef`**
+**`ValueColumnDef`** — One column of a typed `VALUES` clause: its name and the PostgreSQL type each value in that column is cast to. See {@link values}.
 
 ```typescript
 interface ValueColumnDef
 ```
 
-**`SerializableOptions`**
+**`SerializableOptions`** — Retry policy for {@link serializable}: how many attempts on a serialization failure / deadlock, and the base backoff between them.
 
 ```typescript
 interface SerializableOptions
@@ -626,6 +682,94 @@ Query all versions of temporal records (no date filter).
 
 Close the current version and create a new one with updated data.
 
+## valve
+
+Valve namespace — typed, directional, gated boundaries between code silos.
+
+### `valve.supply`
+
+Declare a handoff valve — the producer side of a payload crossing.
+
+### `valve.gate`
+
+Declare a transition-gate valve — the producer side of a gated state change.
+
+### `valve.faucet`
+
+Declare a faucet — the consumer side of a `supply -> faucet` edge.
+
+### `valve.cross`
+
+Decision outcome: cross the valve, delivering the payload.
+
+### `valve.held`
+
+Decision outcome: hold the crossing in a provisional, reviewable state.
+
+### `valve.failed`
+
+Decision outcome: evaluation failed — retryable, never a thrown exception.
+
+### `valve.crossSupply`
+
+Execute a handoff crossing in the caller's transaction (unrecorded mechanics).
+
+### `valve.crossGate`
+
+Execute a transition-gate crossing (unrecorded mechanics).
+
+### `valve.executeSupplyCrossing`
+
+Execute a handoff crossing with idempotency and provenance recording.
+
+### `valve.executeGateCrossing`
+
+Execute a transition-gate crossing with provenance recording.
+
+### `valve.enqueueCrossing`
+
+Enqueue a handoff crossing to run durably as a retried, dead-letterable job.
+
+### `valve.runCrossingJob`
+
+The durable-crossing job-handler body — wire into a worker.
+
+### `valve.VALVE_CROSSING_JOB_TYPE`
+
+Job type for a durable valve crossing.
+
+### `valve.graph`
+
+Assemble the directional valve graph from every registered valve and faucet.
+
+### `valve.downstreamFaucets`
+
+The faucet nodes a valve feeds.
+
+### `valve.contextDependents`
+
+The gates whose enrichment context depends on a valve.
+
+### `valve.diffContract`
+
+Diff a valve contract between two versions.
+
+### `valve.emitArtifact`
+
+Project a handoff supply to its lightweight contract artifact.
+
+### `valve.valves`
+
+All registered producer valves, keyed by name.
+
+### `valve.getValve`
+
+Look up a registered valve by name.
+
+### `valve.faucetsOf`
+
+The faucets consuming a named valve.
+
 ## vector — Vector & Full-Text Search
 
 Vector and full-text search namespace — pgvector column types, similarity queries, and FTS operators.
@@ -690,6 +834,10 @@ Audit logging namespace — structured audit trail for data changes.
 
 Creates an Audit instance that writes audit records to a Postgres table.
 
+### `audit.query`
+
+Queries the framework-managed `audit_record` table. Tenant-scoped via the active Flow.
+
 ## cache — Caching
 
 In-memory caching namespace — TTL-based with stats, preload, and tenant-aware variants.
@@ -871,3 +1019,15 @@ OpenAPI spec generation namespace.
 ### `openapi.generate`
 
 Generates an OpenAPI 3.1 document from route registrations — schemas derived from fitting() input/output.
+
+## test
+
+## trace
+
+### `__flowStep`
+
+Wraps `impl` so that, under an active traced Flow, each call records a `trace_step`.
+
+```typescript
+function __flowStep<F extends AnyFunction>(meta: FlowStepMeta, impl: F): F
+```