pipework 0.251.0 → 0.252.1

package/src/data/temporal/types.ts

@@ -0,0 +1,22 @@
+import type { DB, SQL, Table } from '../db/types.js'
+
+export interface TemporalOptions {
+  readonly tx: DB
+  readonly table: string | Table
+  readonly where: SQL
+}
+
+export interface ReviseOptions extends TemporalOptions {
+  readonly data: Record<string, unknown>
+  readonly userId?: string
+}
+
+export interface ReviseResult {
+  readonly id: string
+  readonly version: number
+}
+
+export interface GetCurrentResult {
+  readonly id: string
+  readonly version: number
+}

package/src/data/valve/artifact.ts

@@ -0,0 +1,33 @@
+import { schema } from '../schema/namespace.js'
+import type { JsonSchema } from '../schema/namespace.js'
+import type { SupplyDefinition, ValveKind, ValveTopology } from './types.js'
+
+/**
+ * The lightweight artifact a supply declaration emits — JSON Schema plus valve
+ * metadata, zero logic and zero transitive producer dependencies. A consumer's
+ * faucet imports only this, never the producer silo.
+ */
+export interface ContractArtifact {
+  readonly valve: string
+  readonly kind: ValveKind
+  readonly topology: ValveTopology
+  readonly version: number
+  readonly schema: JsonSchema
+  readonly invariants: readonly string[]
+}
+
+/** Project a handoff supply to its contract artifact. */
+export function emitArtifact<TSource, TPayload>(
+  definition: SupplyDefinition<TSource, TPayload>,
+): ContractArtifact {
+  return {
+    valve: definition.name,
+    kind: definition.kind,
+    topology: definition.topology,
+    // Explicit contract versioning (a `.version()` builder step) is a later
+    // refinement; the field exists so the artifact is diffable from day one.
+    version: 1,
+    schema: schema.check.toJsonSchema(schema.check.object(definition.contract)),
+    invariants: [...definition.invariants],
+  }
+}

package/src/data/valve/contract-diff.ts

@@ -0,0 +1,21 @@
+import type { ContractShape } from './types.js'
+
+export interface ContractDiff {
+  readonly added: readonly string[]
+  readonly removed: readonly string[]
+  readonly retained: readonly string[]
+  /** True when the diff removes a field — consumers reading it break. */
+  readonly breaking: boolean
+}
+
+/**
+ * Diff a valve contract between two versions. Removing a field breaks any
+ * consumer that reads it; adding a field is additive. Field-level — deep
+ * schema-change detection within a retained field is a later refinement.
+ */
+export function diffContract(before: ContractShape, after: ContractShape): ContractDiff {
+  const added = Object.keys(after).filter((key) => !(key in before))
+  const removed = Object.keys(before).filter((key) => !(key in after))
+  const retained = Object.keys(before).filter((key) => key in after)
+  return { added, removed, retained, breaking: removed.length > 0 }
+}

package/src/data/valve/cross.ts

@@ -0,0 +1,57 @@
+import { faucetsOf } from './registry.js'
+import { schema } from '../schema/namespace.js'
+import type { DB } from '../db/namespace.js'
+import type { GateCrossingResult, GateDefinition, SupplyCrossingResult, SupplyDefinition } from './types.js'
+
+/**
+ * Execute a handoff crossing in the caller's transaction: run the guard, project
+ * the payload, validate it against the contract, and deliver it to every faucet
+ * — each faucet re-validating, because it does not trust the supply.
+ */
+export async function crossSupply<TSource, TPayload>(
+  definition: SupplyDefinition<TSource, TPayload>,
+  source: TSource,
+  tx: DB,
+): Promise<SupplyCrossingResult> {
+  if (definition.guard !== undefined && !definition.guard(source)) {
+    return { kind: 'blocked' }
+  }
+  const payload = definition.project(source)
+  const contractSchema = schema.check.object(definition.contract)
+  schema.check.parse(contractSchema, payload)
+  for (const consumer of faucetsOf(definition.name)) {
+    const revalidated = schema.check.parse(contractSchema, payload)
+    await consumer.handler(revalidated, tx)
+  }
+  return { kind: 'crossed', payload }
+}
+
+/**
+ * Execute a transition-gate crossing: fan the event out to N items, run the
+ * async decision per item, and partition each outcome — cross / held / failed —
+ * into a crossing result.
+ */
+export async function crossGate<TEvent>(
+  definition: GateDefinition<TEvent>,
+  event: TEvent,
+  context: Readonly<Record<string, unknown>>,
+): Promise<readonly GateCrossingResult[]> {
+  const items: readonly unknown[] = definition.fanOut !== undefined
+    ? definition.fanOut(event)
+    : [event]
+  const results: GateCrossingResult[] = []
+  for (const item of items) {
+    // Fan-out re-scopes the trigger into per-item decision events; #307 leaves
+    // the item/event type relation open, so the executor treats each item as
+    // the decision's event.
+    const outcome = await definition.decision(item as TEvent, context)
+    if (outcome.kind === 'cross') {
+      results.push({ kind: 'crossed', payload: outcome.payload })
+    } else if (outcome.kind === 'held') {
+      results.push({ kind: 'held', reason: outcome.reason })
+    } else {
+      results.push({ kind: 'failed', error: outcome.error })
+    }
+  }
+  return results
+}

package/src/data/valve/crossing-ledger.ts

@@ -0,0 +1,50 @@
+import { sql } from '../db/sql.js'
+import type { DB } from '../db/namespace.js'
+
+/** A provenance row to append to the `valve_crossing` ledger. */
+export interface CrossingRecord {
+  readonly valve: string
+  readonly idempotencyKey: string | null
+  readonly outcome: 'crossed' | 'blocked' | 'held' | 'failed'
+  readonly payload: unknown
+  readonly detail: unknown
+  readonly lineageId: string | null
+}
+
+/**
+ * Append a crossing's provenance row to the ledger. `valve_crossing` is
+ * framework substrate, so — like trace and audit — it is written with raw SQL
+ * rather than the audited write surface. Runs on the caller's transaction, so
+ * the row commits atomically with the crossing it records.
+ */
+export async function recordCrossing(db: DB, record: CrossingRecord): Promise<void> {
+  const payload = record.payload === undefined || record.payload === null
+    ? null
+    : JSON.stringify(record.payload)
+  const detail = record.detail === undefined || record.detail === null
+    ? null
+    : JSON.stringify(record.detail)
+  await db.execute(sql`
+    INSERT INTO valve_crossing (valve, idempotency_key, outcome, payload, detail, lineage_id, crossed_at)
+    VALUES (
+      ${record.valve}, ${record.idempotencyKey}, ${record.outcome},
+      ${payload === null ? sql`NULL` : sql`${payload}::jsonb`},
+      ${detail === null ? sql`NULL` : sql`${detail}::jsonb`},
+      ${record.lineageId}, now()
+    )
+  `)
+}
+
+/**
+ * Whether a keyed crossing has already crossed — the idempotency check. A
+ * `crossed` ledger row for `(valve, idempotencyKey)` means the crossing's
+ * effect already landed and must not be replayed.
+ */
+export async function findCrossing(db: DB, valve: string, idempotencyKey: string): Promise<boolean> {
+  const rows = await db.execute(sql`
+    SELECT 1 FROM valve_crossing
+    WHERE valve = ${valve} AND idempotency_key = ${idempotencyKey} AND outcome = 'crossed'
+    LIMIT 1
+  `)
+  return rows.length > 0
+}

package/src/data/valve/decision.ts

@@ -0,0 +1,44 @@
+/**
+ * The decision outcome — the load-bearing seam of the transition-gate form
+ * (#307 field 13). A gate's `.decision()` hook returns one of three branches.
+ * The three-way partition is fixed here by the primitive; the business verdict
+ * that *picks* a branch is consumer-silo application code.
+ */
+
+/** The crossing proceeds — `payload` is delivered to the consumer. */
+export interface Crossed<TPayload> {
+  readonly kind: 'cross'
+  readonly payload: TPayload
+}
+
+/** The crossing is blocked into a provisional, reviewable state carrying `reason`. */
+export interface Held<TReason> {
+  readonly kind: 'held'
+  readonly reason: TReason
+}
+
+/** Evaluation itself failed — a durable, retryable outcome, not a thrown exception. */
+export interface Failed {
+  readonly kind: 'failed'
+  readonly error: Error
+}
+
+export type DecisionOutcome<TPayload, TReason> =
+  | Crossed<TPayload>
+  | Held<TReason>
+  | Failed
+
+/** Cross the valve: deliver `payload` to the consumer. */
+export function cross<TPayload>(payload: TPayload): Crossed<TPayload> {
+  return { kind: 'cross', payload }
+}
+
+/** Hold the crossing: it enters a provisional, reviewable state carrying `reason`. */
+export function held<TReason>(reason: TReason): Held<TReason> {
+  return { kind: 'held', reason }
+}
+
+/** Evaluation failed: a retryable, dead-letterable outcome — never a thrown exception. */
+export function failed(error: Error): Failed {
+  return { kind: 'failed', error }
+}

package/src/data/valve/durable-crossing.ts

@@ -0,0 +1,52 @@
+import { getValve } from './registry.js'
+import { executeSupplyCrossing } from './execute-crossing.js'
+import type { DB } from '../db/namespace.js'
+import type { Queue } from '../../async/jobs/queue.js'
+import type { CrossingResult, SupplyDefinition } from './types.js'
+
+/** Job type for a durable valve crossing. */
+export const VALVE_CROSSING_JOB_TYPE = 'pipework:valve-crossing'
+
+/** The payload of a durable-crossing job. */
+export interface CrossingJobPayload {
+  readonly valve: string
+  readonly source: unknown
+}
+
+/**
+ * Enqueue a handoff crossing to run durably. The job queue retries it with
+ * backoff and dead-letters it on retry exhaustion — failure-to-cross becomes a
+ * terminal job outcome, not an exception that vanishes.
+ */
+export async function enqueueCrossing(
+  queue: Queue,
+  db: DB,
+  valve: string,
+  source: unknown,
+): Promise<string> {
+  const payload: CrossingJobPayload = { valve, source }
+  return queue.enqueue(db, { type: VALVE_CROSSING_JOB_TYPE, payload })
+}
+
+/**
+ * The job-handler body for a durable crossing. Wire it into a worker — e.g.
+ * `fitting().job(VALVE_CROSSING_JOB_TYPE).fit(({ input, db }) => runCrossingJob(input, db))`.
+ * The valve must be registered in the worker process; the crossing runs
+ * recorded and idempotent on the job's transaction. A throw fails the job,
+ * which the queue retries and finally dead-letters.
+ */
+export async function runCrossingJob(payload: CrossingJobPayload, tx: DB): Promise<CrossingResult> {
+  const definition = getValve(payload.valve)
+  if (definition === undefined) {
+    throw new Error(
+      `[pipework] Durable crossing names an unregistered valve: "${payload.valve}".\n\n` +
+      '  The valve declaration must be imported in the worker process so it registers.\n',
+    )
+  }
+  if (definition.kind !== 'handoff') {
+    throw new Error(
+      `[pipework] Durable crossing supports handoff valves; "${payload.valve}" is a ${definition.kind}.\n`,
+    )
+  }
+  return executeSupplyCrossing(definition as SupplyDefinition<unknown, unknown>, payload.source, tx)
+}

package/src/data/valve/execute-crossing.ts

@@ -0,0 +1,77 @@
+import { crossSupply, crossGate } from './cross.js'
+import { recordCrossing, findCrossing } from './crossing-ledger.js'
+import type { DB } from '../db/namespace.js'
+import type {
+  CrossingResult,
+  GateCrossingResult,
+  GateDefinition,
+  SupplyDefinition,
+} from './types.js'
+
+function lineageOf<TSource, TPayload>(
+  definition: SupplyDefinition<TSource, TPayload>,
+  source: TSource,
+): string | null {
+  if (definition.lineageField === undefined) return null
+  const value = (source as Record<string, unknown>)[definition.lineageField]
+  return typeof value === 'string' ? value : null
+}
+
+function detailOf(result: GateCrossingResult): unknown {
+  if (result.kind === 'held') return { reason: result.reason }
+  if (result.kind === 'failed') return { error: result.error.message }
+  return null
+}
+
+/**
+ * Execute a handoff crossing with idempotency and provenance, on the caller's
+ * transaction. If the supply declares an idempotency key and a `crossed` row
+ * already exists for it, the crossing is skipped — its effect already landed.
+ * Otherwise the crossing runs and its outcome is appended to the ledger
+ * atomically with it.
+ */
+export async function executeSupplyCrossing<TSource, TPayload>(
+  definition: SupplyDefinition<TSource, TPayload>,
+  source: TSource,
+  tx: DB,
+): Promise<CrossingResult> {
+  const key = definition.idempotentBy !== undefined ? definition.idempotentBy(source) : null
+  if (key !== null && await findCrossing(tx, definition.name, key)) {
+    return { kind: 'skipped' }
+  }
+  const result = await crossSupply(definition, source, tx)
+  await recordCrossing(tx, {
+    valve: definition.name,
+    idempotencyKey: key,
+    outcome: result.kind,
+    payload: result.kind === 'crossed' ? result.payload : null,
+    detail: null,
+    lineageId: lineageOf(definition, source),
+  })
+  return result
+}
+
+/**
+ * Execute a transition-gate crossing with provenance. Each fanned-out crossing
+ * — crossed, held, or failed — is appended to the ledger as its own row, on the
+ * caller's transaction.
+ */
+export async function executeGateCrossing<TEvent>(
+  definition: GateDefinition<TEvent>,
+  event: TEvent,
+  context: Readonly<Record<string, unknown>>,
+  tx: DB,
+): Promise<readonly GateCrossingResult[]> {
+  const results = await crossGate(definition, event, context)
+  for (const result of results) {
+    await recordCrossing(tx, {
+      valve: definition.name,
+      idempotencyKey: null,
+      outcome: result.kind,
+      payload: result.kind === 'crossed' ? result.payload : null,
+      detail: detailOf(result),
+      lineageId: null,
+    })
+  }
+  return results
+}

package/src/data/valve/faucet.ts

@@ -0,0 +1,56 @@
+import { registerFaucet } from './registry.js'
+import type { FaucetDefinition, FaucetHandler } from './types.js'
+
+/**
+ * The consumer-side builder. A faucet binds to a valve by name — never to the
+ * producer silo — and lands every (re-validated) payload in a consumer entity.
+ * `.on()` is terminal: supplying the intake handler registers the faucet.
+ */
+export interface FaucetBuilder<TPayload> {
+  /** The consumer entity the payload lands in. */
+  into(target: string): FaucetBuilder<TPayload>
+  /** The intake handler. Terminal — registers the faucet and returns its definition. */
+  on(handler: FaucetHandler<TPayload>): FaucetDefinition<TPayload>
+}
+
+interface FaucetState {
+  readonly valve: string
+  target: string | undefined
+}
+
+function finalizeFaucet(state: FaucetState, handler: FaucetHandler<unknown>): FaucetDefinition<unknown> {
+  if (state.target === undefined) {
+    throw new Error(
+      `[pipework] Faucet for valve "${state.valve}" is missing .into(...).\n\n` +
+      '  A faucet must declare the consumer entity its payload lands in before .on(...).\n' +
+      '  Example: faucet("frozen-outcome").into("ledger-entries").on(handler)\n',
+    )
+  }
+  const definition: FaucetDefinition<unknown> = {
+    valve: state.valve,
+    target: state.target,
+    handler,
+  }
+  registerFaucet(definition)
+  return definition
+}
+
+/**
+ * Declare a faucet — the consumer side of a `supply -> faucet` edge. `valve` is
+ * the name of the producer valve this faucet consumes.
+ */
+export function faucet<TPayload = unknown>(valve: string): FaucetBuilder<TPayload> {
+  const state: FaucetState = { valve, target: undefined }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the builder erases the payload generic; FaucetBuilder is the precise public surface
+  const builder: any = {
+    into(target: string) {
+      state.target = target
+      return builder
+    },
+    on(handler: FaucetHandler<unknown>) {
+      return finalizeFaucet(state, handler)
+    },
+  }
+  return builder as FaucetBuilder<TPayload>
+}

package/src/data/valve/gate.ts

@@ -0,0 +1,114 @@
+import { registerValve } from './registry.js'
+import type { GateDecision, GateDefinition, GateRetraction, GateTrigger } from './types.js'
+
+/**
+ * The producer-side builder for a transition-gate valve. `.on()` fixes the
+ * source event type; `.fanOut()` and `.decision()` are checked against it.
+ * `.decision()` is terminal — the async hook is the load-bearing seam, and
+ * supplying it registers the gate.
+ */
+export interface GateBuilder<TEvent> {
+  /** The source entity and the set of triggers that fire the gate. */
+  on<TOnEvent = TEvent>(source: string, triggers: readonly GateTrigger[]): GateBuilder<TOnEvent>
+  /** Enrichment context — context key -> inbound valve name. Fed by inbound faucets. */
+  context(inbound: Record<string, string>): GateBuilder<TEvent>
+  /** Names the computed signals the decision may read. */
+  signals(names: readonly string[]): GateBuilder<TEvent>
+  /** Fans one trigger out to N independently-keyed crossings. */
+  fanOut(items: (event: TEvent) => readonly unknown[]): GateBuilder<TEvent>
+  /** Declares that a trigger supersedes and retracts the prior crossing. */
+  retracts(config: GateRetraction): GateBuilder<TEvent>
+  /** The async decision hook. Terminal — registers the gate and returns its definition. */
+  decision(hook: GateDecision<TEvent>): GateDefinition<TEvent>
+}
+
+interface GateState {
+  readonly name: string
+  readonly silo: string
+  source: string | undefined
+  triggers: readonly GateTrigger[] | undefined
+  context: Record<string, string>
+  signals: readonly string[]
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the builder erases the per-stage event generic; GateBuilder is the precise public surface
+  fanOut: ((event: any) => readonly unknown[]) | undefined
+  retraction: GateRetraction | undefined
+}
+
+function finalizeGate(state: GateState, hook: GateDecision<unknown>): GateDefinition<unknown> {
+  if (state.source === undefined || state.triggers === undefined) {
+    throw new Error(
+      `[pipework] Valve "${state.name}" is missing .on(...).\n\n` +
+      '  A gate must declare its source entity and trigger set before .decision(...).\n' +
+      '  Example: gate("event-verification", "events")\n' +
+      '             .on("event-versions", [{ trigger: "admission" }])\n',
+    )
+  }
+  if (state.triggers.length === 0) {
+    throw new Error(
+      `[pipework] Valve "${state.name}" has an empty trigger set.\n\n` +
+      '  .on(...) must declare at least one trigger — a gate that never fires is dead.\n',
+    )
+  }
+  const definition: GateDefinition<unknown> = {
+    name: state.name,
+    kind: 'transition-gate',
+    topology: { producer: state.silo, consumer: state.silo },
+    source: state.source,
+    triggers: state.triggers,
+    context: { ...state.context },
+    signals: [...state.signals],
+    fanOut: state.fanOut,
+    decision: hook,
+    retraction: state.retraction,
+  }
+  registerValve(definition)
+  return definition
+}
+
+/**
+ * Declare a transition-gate valve. A gate modulates a state change within one
+ * silo, so `silo` is both producer and consumer. Chain the anatomy and finish
+ * with `.decision(hook)`.
+ */
+export function gate(name: string, silo: string): GateBuilder<unknown> {
+  const state: GateState = {
+    name,
+    silo,
+    source: undefined,
+    triggers: undefined,
+    context: {},
+    signals: [],
+    fanOut: undefined,
+    retraction: undefined,
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- builder type param narrows per stage; the public GateBuilder type is precise
+  const builder: any = {
+    on(source: string, triggers: readonly GateTrigger[]) {
+      state.source = source
+      state.triggers = triggers
+      return builder
+    },
+    context(inbound: Record<string, string>) {
+      state.context = inbound
+      return builder
+    },
+    signals(names: readonly string[]) {
+      state.signals = names
+      return builder
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- fan-out event generic erased into state; see GateState
+    fanOut(items: (event: any) => readonly unknown[]) {
+      state.fanOut = items
+      return builder
+    },
+    retracts(config: GateRetraction) {
+      state.retraction = config
+      return builder
+    },
+    decision(hook: GateDecision<unknown>) {
+      return finalizeGate(state, hook)
+    },
+  }
+  return builder as GateBuilder<unknown>
+}

package/src/data/valve/graph.ts

@@ -0,0 +1,77 @@
+import { valves, faucetsOf } from './registry.js'
+import type { GateDefinition } from './types.js'
+
+export type ValveNodeKind = 'supply' | 'gate' | 'faucet'
+
+export interface ValveGraphNode {
+  readonly id: string
+  readonly kind: ValveNodeKind
+}
+
+/**
+ * `crossing` — a producer delivers to a faucet. `context` — a gate's enrichment
+ * depends on an inbound valve. `retraction` — a superseded crossing invalidates
+ * the downstream it fed.
+ */
+export type ValveEdgeKind = 'crossing' | 'context' | 'retraction'
+
+export interface ValveGraphEdge {
+  readonly kind: ValveEdgeKind
+  readonly from: string
+  readonly to: string
+}
+
+/** The directional data-dependency graph, distinct from the package graph. */
+export interface ValveGraph {
+  readonly nodes: readonly ValveGraphNode[]
+  readonly edges: readonly ValveGraphEdge[]
+}
+
+function faucetNodeId(valve: string, target: string): string {
+  return `${valve}::${target}`
+}
+
+/** Assemble the valve graph from every registered valve and faucet. */
+export function buildValveGraph(): ValveGraph {
+  const nodes = new Map<string, ValveGraphNode>()
+  const edges: ValveGraphEdge[] = []
+
+  for (const [name, definition] of valves()) {
+    nodes.set(name, { id: name, kind: definition.kind === 'transition-gate' ? 'gate' : 'supply' })
+
+    const consumers = faucetsOf(name)
+    for (const consumer of consumers) {
+      const faucetId = faucetNodeId(name, consumer.target)
+      nodes.set(faucetId, { id: faucetId, kind: 'faucet' })
+      edges.push({ kind: 'crossing', from: name, to: faucetId })
+    }
+
+    if (definition.kind === 'transition-gate') {
+      const gateDef = definition as GateDefinition<unknown>
+      for (const inbound of Object.values(gateDef.context)) {
+        edges.push({ kind: 'context', from: name, to: inbound })
+      }
+      if (gateDef.retraction !== undefined) {
+        for (const consumer of consumers) {
+          edges.push({ kind: 'retraction', from: name, to: faucetNodeId(name, consumer.target) })
+        }
+      }
+    }
+  }
+
+  return { nodes: [...nodes.values()], edges }
+}
+
+/** Faucet node ids fed by the named valve — the direct downstream of a crossing. */
+export function downstreamFaucets(graph: ValveGraph, valveName: string): readonly string[] {
+  return graph.edges
+    .filter((edge) => edge.kind === 'crossing' && edge.from === valveName)
+    .map((edge) => edge.to)
+}
+
+/** Gate valve names whose enrichment context depends on the named valve. */
+export function contextDependents(graph: ValveGraph, valveName: string): readonly string[] {
+  return graph.edges
+    .filter((edge) => edge.kind === 'context' && edge.to === valveName)
+    .map((edge) => edge.from)
+}

package/src/data/valve/index.ts

@@ -0,0 +1,53 @@
+export { cross, held, failed } from './decision.js'
+export type { Crossed, Held, Failed, DecisionOutcome } from './decision.js'
+export {
+  registerValve,
+  valves,
+  getValve,
+  registerFaucet,
+  faucetsOf,
+  clearValveRegistry,
+} from './registry.js'
+export { supply } from './supply.js'
+export type { SupplyBuilder } from './supply.js'
+export { gate } from './gate.js'
+export type { GateBuilder } from './gate.js'
+export { faucet } from './faucet.js'
+export type { FaucetBuilder } from './faucet.js'
+export { crossSupply, crossGate } from './cross.js'
+export { executeSupplyCrossing, executeGateCrossing } from './execute-crossing.js'
+export { enqueueCrossing, runCrossingJob, VALVE_CROSSING_JOB_TYPE } from './durable-crossing.js'
+export type { CrossingJobPayload } from './durable-crossing.js'
+export { recordCrossing, findCrossing } from './crossing-ledger.js'
+export type { CrossingRecord } from './crossing-ledger.js'
+export { valveCrossing } from './schema/valve-crossing.js'
+export { buildValveGraph, downstreamFaucets, contextDependents } from './graph.js'
+export type { ValveGraph, ValveGraphNode, ValveGraphEdge, ValveNodeKind, ValveEdgeKind } from './graph.js'
+export { diffContract } from './contract-diff.js'
+export type { ContractDiff } from './contract-diff.js'
+export { emitArtifact } from './artifact.js'
+export type { ContractArtifact } from './artifact.js'
+export type {
+  ValveKind,
+  ValveTopology,
+  ValveDefinition,
+  HandoffTrigger,
+  CrossingMode,
+  ContractShape,
+  ContractPayload,
+  SupplyDefinition,
+  GateTrigger,
+  GateRetraction,
+  GateDecision,
+  GateDefinition,
+  FaucetHandler,
+  FaucetDefinition,
+  CrossedResult,
+  BlockedResult,
+  HeldResult,
+  FailedResult,
+  SkippedResult,
+  SupplyCrossingResult,
+  GateCrossingResult,
+  CrossingResult,
+} from './types.js'