@michaelthielemann/kestrel 3.0.0 → 4.0.0

package/scripts/coverage-all.mjs

@@ -0,0 +1,163 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const VITEST_BIN = path.join(ROOT, 'node_modules/.bin/vitest')
+const PARTS_DIR = path.join(ROOT, 'reports/coverage/.parts')
+const OUT_DIR = path.join(ROOT, 'reports/coverage')
+
+function sameKeys(a, b) {
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  const setB = new Set(kb)
+  return ka.every((k) => setB.has(k))
+}
+
+function mapsAgree(a, b) {
+  return sameKeys(a.statementMap, b.statementMap) && sameKeys(a.fnMap, b.fnMap) && sameKeys(a.branchMap, b.branchMap)
+}
+
+function countExecutedFunctions(entry) {
+  return Object.values(entry.f).filter((n) => n > 0).length
+}
+
+function cloneEntry(entry) {
+  return structuredClone(entry)
+}
+
+function sumCounters(a, b) {
+  const out = {}
+  for (const k of Object.keys(a)) out[k] = a[k] + (b[k] ?? 0)
+  return out
+}
+
+function sumBranches(a, b) {
+  const out = {}
+  for (const k of Object.keys(a)) {
+    const branchA = a[k]
+    const branchB = b[k] ?? []
+    out[k] = branchA.map((count, i) => count + (branchB[i] ?? 0))
+  }
+  return out
+}
+
+// Istanbul JSON is keyed by absolute file path; the same path can show up in several parts
+// (a package run and the root run both touching a shared file). When their instrumentation
+// maps agree, counters are additive. When they disagree, the maps describe different
+// transforms of the file — summing them would misattribute counts to the wrong statements/
+// functions, so the richer entry wins outright and the conflict is reported instead of hidden.
+export function mergeCoverage(parts, conflicts = []) {
+  const merged = {}
+  for (const part of parts) {
+    for (const [filePath, entry] of Object.entries(part)) {
+      const existing = merged[filePath]
+      if (!existing) {
+        merged[filePath] = cloneEntry(entry)
+        continue
+      }
+      if (mapsAgree(existing, entry)) {
+        merged[filePath] = {
+          ...existing,
+          s: sumCounters(existing.s, entry.s),
+          f: sumCounters(existing.f, entry.f),
+          b: sumBranches(existing.b, entry.b),
+        }
+      } else {
+        if (countExecutedFunctions(entry) > countExecutedFunctions(existing)) {
+          merged[filePath] = cloneEntry(entry)
+        }
+        conflicts.push(filePath)
+      }
+    }
+  }
+  return merged
+}
+
+function readCoverage(dir) {
+  const file = path.join(dir, 'coverage-final.json')
+  if (!fs.existsSync(file)) return null
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+function countFiles(coverage) {
+  return coverage ? Object.keys(coverage).length : 0
+}
+
+function countFunctionsTotal(coverage) {
+  if (!coverage) return 0
+  let total = 0
+  for (const entry of Object.values(coverage)) total += countExecutedFunctions(entry)
+  return total
+}
+
+function discoverPackageSuites() {
+  const packagesDir = path.join(ROOT, 'packages')
+  if (!fs.existsSync(packagesDir)) return []
+  return fs
+    .readdirSync(packagesDir)
+    .filter((name) => fs.existsSync(path.join(packagesDir, name, 'vitest.config.ts')))
+    .sort()
+    .map((name) => ({ name, cwd: path.join(packagesDir, name) }))
+}
+
+function runSuite(name, cwd) {
+  const reportsDirectory = path.join(PARTS_DIR, name)
+  fs.mkdirSync(reportsDirectory, { recursive: true })
+  const args = [
+    'run',
+    '--coverage.enabled',
+    '--coverage.provider=v8',
+    '--coverage.reporter=json',
+    `--coverage.reportsDirectory=${reportsDirectory}`,
+    '--coverage.reportOnFailure=true',
+  ]
+  console.log(`\n=== ${name} (${path.relative(ROOT, cwd) || '.'}) ===`)
+  const result = spawnSync(VITEST_BIN, args, { cwd, stdio: 'inherit' })
+  const passed = result.status === 0
+  const coverage = readCoverage(reportsDirectory)
+  return { name, passed, coverage }
+}
+
+export function main() {
+  fs.rmSync(PARTS_DIR, { recursive: true, force: true })
+  fs.mkdirSync(PARTS_DIR, { recursive: true })
+
+  const suites = [{ name: 'root', cwd: ROOT }, ...discoverPackageSuites()]
+  const results = suites.map(({ name, cwd }) => runSuite(name, cwd))
+
+  const conflicts = []
+  const merged = mergeCoverage(
+    results.map((r) => r.coverage).filter(Boolean),
+    conflicts,
+  )
+
+  fs.mkdirSync(OUT_DIR, { recursive: true })
+  fs.writeFileSync(path.join(OUT_DIR, 'coverage-final.json'), JSON.stringify(merged))
+
+  console.log('\n=== coverage-all summary ===')
+  for (const r of results) {
+    const status = r.passed ? 'PASS' : 'FAIL'
+    console.log(
+      `${r.name.padEnd(24)} ${status}  files=${countFiles(r.coverage)}  functionsExecuted=${countFunctionsTotal(r.coverage)}`,
+    )
+  }
+
+  if (conflicts.length > 0) {
+    console.log(`\n${conflicts.length} merge conflict(s) (kept the entry with more executed functions):`)
+    for (const filePath of conflicts) console.log(`  ${filePath}`)
+  } else {
+    console.log('\nno merge conflicts')
+  }
+
+  console.log(
+    `\nmerged: files=${Object.keys(merged).length} functionsExecuted=${countFunctionsTotal(merged)} -> ${path.join(OUT_DIR, 'coverage-final.json')}`,
+  )
+
+  const anyFailed = results.some((r) => !r.passed)
+  process.exitCode = anyFailed ? 1 : 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main()

package/scripts/dashboard.mjs

@@ -0,0 +1,89 @@
+// Deterministic static dashboard generator — no network. Boots the pipeline/collection registries
+// the same way test/architecture/pipeline-invariants.test.ts does (no Nuxt boot needed for that), then
+// renders through the SAME renderDashboard() the dev route uses, so the two surfaces never drift.
+//
+// Run with: npx tsx scripts/dashboard.mjs   (or `pnpm dashboard`)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { fieldTypes } from '@michaelthielemann/kestrel-fields'
+import {
+  buildIntrospectionPipelines, buildPipelineIndex, clearPipelines, clearRegistry,
+  registerCollection, registerPipeline, renderDashboard, setResolvedKestrelConfig, allCollections,
+} from '@michaelthielemann/kestrel-core'
+import { buildAuthPipelines } from '@michaelthielemann/kestrel-auth'
+import { pagesCollection } from '@michaelthielemann/kestrel-collections'
+import { mediaCollection, mediaSettingsCollection } from '@michaelthielemann/kestrel-media'
+import { redirectsCollection, siteCollection } from '@michaelthielemann/kestrel-publishing'
+import { resolveServerKestrelConfig } from '../layers/core/server/utils/server-config.ts'
+import { PLUGIN_ORDER } from '../layers/core/modules/plugin-order/plugin-order.ts'
+import posts from '../server/collections/posts.ts'
+import settings from '../server/collections/settings.ts'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+void fieldTypes
+setResolvedKestrelConfig(resolveServerKestrelConfig())
+Object.assign(globalThis, {
+  useRuntimeConfig: () => ({
+    kestrel: { output: { driver: 'local', dir: '', publicDir: '/kestrel-no-such-public-dir', auto: true, publishOnSave: false, reconcileMinutes: 0, verbose: false, s3: {} } },
+  }),
+  useDb: () => drizzle(new Database(':memory:')),
+  primaryLocale: () => 'en',
+  prefixPrimaryLocale: () => false,
+})
+
+clearRegistry()
+for (const c of [pagesCollection, posts, settings, mediaCollection, mediaSettingsCollection, redirectsCollection, siteCollection]) registerCollection(c)
+
+clearPipelines()
+for (const def of buildAuthPipelines()) registerPipeline(def)
+for (const def of buildIntrospectionPipelines()) registerPipeline(def)
+
+const collections = allCollections().map((c) => ({
+  name: c.name,
+  mode: c.def.mode,
+  translatable: Boolean(c.def.translatable),
+  fieldCount: Object.keys(c.def.fields).length,
+}))
+
+/** Reads a repo-only enrichment file, or returns undefined — a consumer project (or a fresh checkout
+ *  before `graphify update`/`pnpm api:check` have run) ships none of these, so every read is optional. */
+function readJsonIfExists(relPath) {
+  const abs = join(repoRoot, relPath)
+  if (!existsSync(abs)) return undefined
+  return JSON.parse(readFileSync(abs, 'utf8'))
+}
+
+function apiSurfaceSection() {
+  const ceilings = readJsonIfExists('test/architecture/public-api-ceilings.json')
+  if (!ceilings) return undefined
+  const out = []
+  for (const [report, ceiling] of Object.entries(ceilings)) {
+    const abs = join(repoRoot, report)
+    if (!existsSync(abs)) continue
+    const count = readFileSync(abs, 'utf8').split('\n').filter((l) => /^\/\/ @(public|alpha|beta|internal)\b/.test(l)).length
+    out.push({ report, count, ceiling })
+  }
+  return out
+}
+
+const edgeAllowlist = readJsonIfExists('test/architecture/edge-allowlist.json')
+const apiSurface = apiSurfaceSection()
+
+const html = renderDashboard({
+  pipelines: buildPipelineIndex(),
+  pluginOrder: PLUGIN_ORDER.map((p) => ({ layer: p.layer, file: p.file, after: p.after })),
+  collections,
+  graph: (edgeAllowlist || apiSurface) ? { packageEdges: edgeAllowlist?.edges, apiSurface } : undefined,
+  generatedAt: new Date().toISOString(),
+})
+
+const outDir = join(repoRoot, 'docs')
+mkdirSync(outDir, { recursive: true })
+const outFile = join(outDir, 'dashboard.html')
+writeFileSync(outFile, html)
+console.log(`[dashboard] wrote ${outFile} (${buildPipelineIndex().length} pipelines, ${collections.length} collections)`)

package/scripts/hash-password.mjs

@@ -3,7 +3,7 @@ import { hashPassword } from './lib/password.mjs'
 import { Cancelled, promptPassword } from './lib/cli.mjs'
 
 // Not used at runtime: this prints a value an operator pastes into KESTREL_ADMIN_PASSWORD_HASH. Kept as a
-// standalone entry point because docs/consuming-kestrel.md tells consumers to run it straight out of
+// standalone entry point because docs/guide/getting-started.md tells consumers to run it straight out of
 // node_modules, which must keep working whether or not the `kestrel` bin is on PATH.
 const arg = process.argv[2]
 if (arg) {

package/scripts/lib/coverage-model.mjs

@@ -0,0 +1,51 @@
+// Indexed view over an Istanbul-shaped coverage report, for the audit detectors.
+//
+// Two questions only: which branch arms were never taken, and which functions never ran. Both are
+// keyed by line so they can be joined to the graph, whose nodes carry a start line and no span.
+import { readFileSync, statSync } from 'node:fs'
+import { join, relative, isAbsolute } from 'node:path'
+
+export function loadCoverage(root, file = 'reports/coverage/coverage-final.json') {
+  const path = isAbsolute(file) ? file : join(root, file)
+  let raw
+  let generatedAt
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))
+    generatedAt = statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+
+  const byFile = new Map()
+  for (const entry of Object.values(raw)) {
+    const rel = relative(root, entry.path)
+    const missedBranchLines = new Set()
+    let branchMissCount = 0
+    for (const [key, arm] of Object.entries(entry.branchMap ?? {})) {
+      const counts = entry.b?.[key] ?? []
+      arm.locations?.forEach((location, index) => {
+        if (counts[index] !== 0) return
+        branchMissCount += 1
+        const line = location.start?.line ?? arm.line
+        if (line) missedBranchLines.add(line)
+      })
+    }
+    const ranFunctionLines = new Set()
+    for (const [key, fn] of Object.entries(entry.fnMap ?? {})) {
+      if (!entry.f?.[key]) continue
+      const line = fn.decl?.start?.line ?? fn.loc?.start?.line
+      if (line) ranFunctionLines.add(line)
+    }
+    byFile.set(rel, { missedBranchLines, branchMissCount, ranFunctionLines })
+  }
+
+  const empty = { missedBranchLines: new Set(), branchMissCount: 0, ranFunctionLines: new Set() }
+  return {
+    generatedAt,
+    files: [...byFile.keys()],
+    has: (file) => byFile.has(file),
+    missedBranchLines: (file) => (byFile.get(file) ?? empty).missedBranchLines,
+    branchMissCount: (file) => (byFile.get(file) ?? empty).branchMissCount,
+    ranFunctionLines: (file) => (byFile.get(file) ?? empty).ranFunctionLines,
+  }
+}

package/scripts/port-graph.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// Port-graph extraction (experiment): for every exported function in packages/kestrel-core/src whose
+// return type resolves to `Effect.Effect<A, E, R>`, the R (requirements) channel becomes that function's
+// port list. Every `Layer.succeed`/`Layer.effect`/`Layer.scoped` call becomes an adapter binding from the
+// layer's containing function to the port it provides. Nodes reuse graphify-out/graph.json's id scheme so
+// the two graphs join; a node not already present there is synthesized with the same scheme and flagged.
+//
+// The R channel alone cannot answer "does persist always follow validate" — this codebase passes the
+// database as a plain function parameter, not a Context.Tag requirement, so R is `never` on every step.
+// To make that invariant askable as a graph query at all, this script also extracts each `definePipeline`
+// call's literal `steps: [...]` array (resolving each step-factory call to the runtime step name registered
+// via `syncStep(name, ...)`) into an ordered step chain, and exposes `stepOrderRespectsInvariant` for
+// querying it.
+import ts from 'typescript'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const corePkg = join(root, 'packages/kestrel-core')
+const graphOutDir = join(root, 'graphify-out')
+
+// --- graph id scheme (mirrors graphify's own slugging, see graphify-out/graph.json) ---
+
+function slugFile(relFile) {
+  return relFile.replace(/\.[^/.]+$/, '').replace(/[^A-Za-z0-9]+/g, '_').toLowerCase()
+}
+
+function slugSymbol(name) {
+  return name.replace(/\(\)$/, '').toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+function loadExistingGraph() {
+  const graphPath = join(graphOutDir, 'graph.json')
+  if (!existsSync(graphPath)) return { nodes: [], byFileAndLabel: new Map() }
+  const graph = JSON.parse(readFileSync(graphPath, 'utf8'))
+  const byFileAndLabel = new Map()
+  for (const n of graph.nodes) byFileAndLabel.set(`${n.source_file}::${n.label}`, n)
+  return { nodes: graph.nodes, byFileAndLabel }
+}
+
+/** Reuses the existing graph's node id for (relFile, name) when present; otherwise synthesizes one with
+ *  the same scheme and marks it so a future graphify run can be checked against it. */
+function nodeIdFor(existing, relFile, name) {
+  const found = existing.byFileAndLabel.get(`${relFile}::${name}()`)
+  if (found) return { id: found.id, synthesized: false }
+  return { id: `${slugFile(relFile)}_${slugSymbol(name)}`, synthesized: true }
+}
+
+function loadProgram() {
+  const tsconfigPath = join(corePkg, 'tsconfig.json')
+  const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile)
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, corePkg)
+  const fileNames = parsed.fileNames.filter((f) => !/\.test\.ts$/.test(f) && !f.includes(`${corePkg}/test/`))
+  const program = ts.createProgram(fileNames, { ...parsed.options, noEmit: true })
+  return { program, fileNames }
+}
+
+function hasExportModifier(node) {
+  return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0
+}
+
+function isEffectReturnType(type) {
+  const target = type.aliasSymbol ?? type.target?.symbol ?? type.symbol
+  return target?.name === 'Effect' && !!(type).typeArguments
+}
+
+/** Flattens a union of `Context.Tag`-shaped types (or a bare one) into distinct display names, dropping
+ *  `never` (the honest "no requirements" answer, not an omission). */
+function portNamesFromRType(checker, rType) {
+  if (!rType) return []
+  const parts = rType.isUnion?.() ? rType.types : [rType]
+  const names = new Set()
+  for (const t of parts) {
+    const text = checker.typeToString(t)
+    if (text === 'never' || text === 'unknown') continue
+    names.add(text)
+  }
+  return [...names]
+}
+
+/** Visits every exported function-like declaration (function declarations and `export const f = (...) =>`)
+ *  in a source file, at the top level and one level of nesting (namespaces are not used in this codebase). */
+function* exportedFunctions(sf) {
+  for (const stmt of sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && hasExportModifier(stmt) && stmt.name) {
+      yield { name: stmt.name.text, decl: stmt }
+    } else if (ts.isVariableStatement(stmt) && hasExportModifier(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+          yield { name: d.name.text, decl: d.initializer }
+        }
+      }
+    }
+  }
+}
+
+function extractFunctionPorts(program, existing) {
+  const checker = program.getTypeChecker()
+  const functions = []
+  let scanned = 0
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    for (const { name, decl } of exportedFunctions(sf)) {
+      scanned++
+      const sig = checker.getSignatureFromDeclaration(decl)
+      if (!sig) continue
+      const returnType = checker.getReturnTypeOfSignature(sig)
+      if (!isEffectReturnType(returnType)) continue
+      const typeArgs = checker.getTypeArguments(returnType)
+      const rType = typeArgs[2]
+      const ports = portNamesFromRType(checker, rType)
+      const { id, synthesized } = nodeIdFor(existing, relFile, name)
+      functions.push({ id, name, file: relFile, ports, synthesized })
+    }
+  }
+  return { functions, scanned }
+}
+
+function containingFunctionName(node) {
+  let cur = node.parent
+  while (cur) {
+    if ((ts.isFunctionDeclaration(cur) || ts.isFunctionExpression(cur) || ts.isArrowFunction(cur)) ) {
+      if (ts.isFunctionDeclaration(cur) && cur.name) return cur.name.text
+      if (ts.isVariableDeclaration(cur.parent) && ts.isIdentifier(cur.parent.name)) return cur.parent.name.text
+    }
+    cur = cur.parent
+  }
+  return null
+}
+
+/** Resolves a `Context.GenericTag<X>(...)` (or `Context.Tag<X, ...>`) expression, following one level of
+ *  identifier indirection, to the service type name `X`. */
+function resolveTagTypeName(checker, expr) {
+  let target = expr
+  if (ts.isIdentifier(expr)) {
+    const sym = checker.getSymbolAtLocation(expr)
+    const decl = sym?.valueDeclaration
+    if (decl && ts.isVariableDeclaration(decl) && decl.initializer) target = decl.initializer
+  }
+  if (ts.isCallExpression(target) && target.typeArguments?.length) {
+    return target.typeArguments[0].getText()
+  }
+  return null
+}
+
+const LAYER_CONSTRUCTORS = new Set(['succeed', 'effect', 'scoped', 'sync'])
+
+function extractLayerBindings(program, existing) {
+  const checker = program.getTypeChecker()
+  const bindings = []
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    const visit = (node) => {
+      if (
+        ts.isCallExpression(node)
+        && ts.isPropertyAccessExpression(node.expression)
+        && ts.isIdentifier(node.expression.expression)
+        && node.expression.expression.text === 'Layer'
+        && LAYER_CONSTRUCTORS.has(node.expression.name.text)
+        && node.arguments.length > 0
+      ) {
+        const tagName = resolveTagTypeName(checker, node.arguments[0])
+        if (tagName) {
+          const fnName = containingFunctionName(node) ?? '<module scope>'
+          const { id, synthesized } = nodeIdFor(existing, relFile, fnName)
+          bindings.push({
+            layerFnId: id,
+            layerFnName: fnName,
+            file: relFile,
+            line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+            constructor: node.expression.name.text,
+            port: tagName,
+            synthesized,
+          })
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return bindings
+}
+
+// --- Pipeline step-order extraction (makes the validate-before-persist invariant askable as a graph query) ---
+
+/** Maps every step-factory function name (e.g. `validateCreateStep`) to the runtime step name it registers
+ *  via `syncStep('<name>', ...)` / `asyncStep('<name>', ...)`. A factory with more than one such call inside
+ *  keeps only the first — every factory in this codebase registers exactly one step. */
+function buildStepNameMap(program) {
+  const map = new Map()
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.includes('/pipeline/steps/') || sf.fileName.includes('/node_modules/')) continue
+    for (const { name, decl } of exportedFunctions(sf)) {
+      let stepName = null
+      const visit = (node) => {
+        if (stepName) return
+        if (
+          ts.isCallExpression(node)
+          && ts.isIdentifier(node.expression)
+          && (node.expression.text === 'syncStep' || node.expression.text === 'asyncStep')
+          && node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+        ) {
+          stepName = node.arguments[0].text
+          return
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(decl)
+      if (stepName) map.set(name, stepName)
+    }
+  }
+  return map
+}
+
+function extractPipelineStepChains(program) {
+  const stepNameMap = buildStepNameMap(program)
+  const pipelines = []
+  for (const sf of program.getSourceFiles()) {
+    if (!sf.fileName.startsWith(corePkg) || sf.fileName.includes('/node_modules/')) continue
+    const relFile = relative(root, sf.fileName)
+    const visit = (node) => {
+      if (
+        ts.isCallExpression(node)
+        && ts.isIdentifier(node.expression)
+        && node.expression.text === 'definePipeline'
+        && node.arguments[0] && ts.isObjectLiteralExpression(node.arguments[0])
+      ) {
+        const obj = node.arguments[0]
+        const nameProp = obj.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'name')
+        const stepsProp = obj.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'steps')
+        if (nameProp && ts.isStringLiteral(nameProp.initializer) && stepsProp && ts.isArrayLiteralExpression(stepsProp.initializer)) {
+          const steps = []
+          for (const el of stepsProp.initializer.elements) {
+            // `steps: deleteSteps` (an identifier referring to a separately declared array) is skipped —
+            // rollback/duplicate/delete are not in VALIDATING_WRITE_OPS, so the invariant query never needs it.
+            if (ts.isCallExpression(el) && ts.isIdentifier(el.expression)) {
+              const factoryName = el.expression.text
+              steps.push(stepNameMap.get(factoryName) ?? factoryName)
+            } else if (ts.isCallExpression(el) && ts.isPropertyAccessExpression(el.expression)) {
+              steps.push(el.expression.name.text)
+            }
+          }
+          pipelines.push({ name: nameProp.initializer.text, file: relFile, line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1, steps })
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return pipelines
+}
+
+/** The validate-before-persist invariant, as a pure query over an ordered step-name chain: `validate` must occur, `persist`
+ *  must occur, and `validate` must precede `persist`. Mirrors test/architecture/pipeline-invariants.test.ts'
+ *  registry-based check, but over the statically extracted `definePipeline` step array instead of a
+ *  runtime-composed `PipelineDescriptor`. */
+export function stepOrderRespectsInvariant(stepNames) {
+  const validateAt = stepNames.indexOf('validate')
+  const persistAt = stepNames.indexOf('persist')
+  if (validateAt < 0 || persistAt < 0) return false
+  return validateAt < persistAt
+}
+
+export const VALIDATING_WRITE_OPS = new Set(['createOne', 'createMany', 'updateOne', 'updateMany'])
+
+export function extractPortGraph() {
+  const { program } = loadProgram()
+  const existing = loadExistingGraph()
+  const { functions, scanned } = extractFunctionPorts(program, existing)
+  const bindings = extractLayerBindings(program, existing)
+  const pipelines = extractPipelineStepChains(program)
+  return { functions, scanned, bindings, pipelines }
+}
+
+function buildEmittedGraph({ functions, bindings, pipelines }) {
+  const nodes = []
+  const links = []
+  const seenNodes = new Set()
+  const addNode = (node) => {
+    if (seenNodes.has(node.id)) return
+    seenNodes.add(node.id)
+    nodes.push(node)
+  }
+
+  for (const fn of functions) {
+    addNode({ id: fn.id, label: `${fn.name}()`, kind: 'function', source_file: fn.file, synthesized: fn.synthesized })
+    for (const port of fn.ports) {
+      const portId = `port_${slugSymbol(port)}`
+      addNode({ id: portId, label: port, kind: 'port' })
+      links.push({ relation: 'requires', source: fn.id, target: portId, source_file: fn.file })
+    }
+  }
+
+  for (const b of bindings) {
+    addNode({ id: b.layerFnId, label: `${b.layerFnName}()`, kind: 'function', source_file: b.file, synthesized: b.synthesized })
+    const portId = `port_${slugSymbol(b.port)}`
+    addNode({ id: portId, label: b.port, kind: 'port' })
+    links.push({ relation: 'provides', source: b.layerFnId, target: portId, source_file: b.file, source_location: `L${b.line}`, layer_constructor: b.constructor })
+  }
+
+  for (const [i, p] of pipelines.entries()) {
+    const pipelineId = `pipeline_${slugFile(p.file)}_${slugSymbol(p.name)}_${i}`
+    addNode({ id: pipelineId, label: `${p.name} (pipeline)`, kind: 'pipeline', source_file: p.file, source_location: `L${p.line}` })
+    p.steps.forEach((stepName, order) => {
+      const stepId = `pipeline_step_${slugSymbol(stepName)}`
+      addNode({ id: stepId, label: stepName, kind: 'pipeline_step' })
+      links.push({ relation: 'pipeline_step', source: pipelineId, target: stepId, order, source_file: p.file })
+    })
+  }
+
+  return { nodes, links }
+}
+
+function main() {
+  const { functions, scanned, bindings, pipelines } = extractPortGraph()
+  const nonEmpty = functions.filter((f) => f.ports.length > 0)
+  const totalPorts = new Set(functions.flatMap((f) => f.ports)).size
+
+  const emitted = buildEmittedGraph({ functions, bindings, pipelines })
+  const reportDir = join(root, 'reports/graph')
+  mkdirSync(reportDir, { recursive: true })
+  const outPath = join(reportDir, 'port-graph.json')
+  writeFileSync(outPath, JSON.stringify({ generated_at: new Date().toISOString(), nodes: emitted.nodes, links: emitted.links }, null, 2))
+
+  console.log(`port-graph: scanned ${scanned} exported functions in packages/kestrel-core/src`)
+  console.log(`port-graph: ${functions.length} have an Effect.Effect<A, E, R> return type`)
+  console.log(`port-graph: ${nonEmpty.length} have a non-empty (non-never) R channel; ${totalPorts} distinct ports found`)
+  console.log(`port-graph: ${bindings.length} Layer composition(s) -> adapter binding(s) found`)
+  console.log(`port-graph: ${pipelines.length} definePipeline() call(s) with a literal steps array extracted`)
+  console.log(`port-graph: wrote ${emitted.nodes.length} nodes, ${emitted.links.length} links to ${relative(root, outPath)}`)
+
+  if (nonEmpty.length === 0) {
+    console.log('port-graph: honest finding — every scanned function has R = never (DB/services are plain')
+    console.log('port-graph: parameters here, not Context.Tag requirements), so the R-channel port list is')
+    console.log('port-graph: empty by construction. The pipeline_step chains above make the validate-before-persist')
+    console.log('port-graph: invariant askable as a graph query at all; see test/architecture/port-graph-cross-check.test.ts.')
+  }
+
+  for (const p of pipelines) {
+    if (!VALIDATING_WRITE_OPS.has(p.name)) continue
+    const ok = stepOrderRespectsInvariant(p.steps)
+    console.log(`port-graph: pipeline "${p.name}" (${p.file}:L${p.line}) validate-before-persist = ${ok}`)
+  }
+}
+
+const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url
+if (isMain) main()

package/scripts/typecheck.mjs

@@ -44,6 +44,17 @@ pass('server (Nitro) project', 'tsc', ['--noEmit', '-p', gateConfig])
 // 3. App / `.vue` / modules / config — vue-tsc via `nuxt typecheck` (needs the committed root tsconfig.json).
 pass('app + .vue (vue-tsc)', 'nuxt', ['typecheck'])
 
+// 4. Standalone workspace packages have their own tsconfig, outside the playground project. Globbed by
+// pnpm's own filter (topological order, every current and future `@michaelthielemann/kestrel-*` package, `create-kestrel`
+// excluded by name) rather than a hand-written list per package — the class of drift a hand list invites
+// (a package silently missing from this one script) is the exact failure mode this rail exists to avoid.
+console.log('› typechecking packages (@michaelthielemann/kestrel-*)…')
+try {
+  execFileSync('pnpm', ['--filter', '@michaelthielemann/kestrel-*', '-r', 'typecheck'], { cwd: root, stdio: 'inherit', env })
+} catch {
+  failed.push('packages (@michaelthielemann/kestrel-*)')
+}
+
 if (failed.length) {
   console.error(`\n✗ typecheck failed: ${failed.join(', ')}`)
   process.exit(1)