@pmelab/gtd 59.0.1 → 60.1.0

package/src/workflow/load.ts

@@ -1,18 +1,24 @@
-import { existsSync, readFileSync } from "node:fs"
-import { createRequire } from "node:module"
-import { dirname, join } from "node:path"
+import { existsSync, readFileSync, realpathSync } from "node:fs"
+import { createRequire, isBuiltin } from "node:module"
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
+import { stripVTControlCharacters } from "node:util"
+import { runInThisContext } from "node:vm"
+import type { Plugin as RolldownPlugin } from "rolldown"
 import { Context, Effect, Layer } from "effect"
 import { GtdError, Narrator } from "../platform/index.js"
-import { replay, type TreeView } from "../replay/index.js"
+import { accessShapeFault, replay, type TreeView } from "../replay/index.js"
+// The published facade: what a config's `@pmelab/gtd/flows` import is served.
 import * as flows from "../flows/index.js"
+import { configure, isFactoryWorkflow, markedOptions, type OptionIssue } from "../flows/internal.js"
 import type { StateMode, WorkflowDefinition } from "./Workflow.js"
-import type { Door, Flow } from "../flows/index.js"
+import type { Door, Flow, ScopeAccess } from "../flows/index.js"
 import { Host, Workspace, type WorkspaceOps } from "../platform/index.js"
 import { compileConfig, type CompiledConfig } from "./compile.js"
 import { SETTING_NAME_RULE, isSettingName } from "./vars.js"
 import { ConfigDiscovery, WORKFLOW_MODULE, type WorkflowModule } from "./discovery.js"
 import { configFingerprint, type ConfigFingerprint } from "./fingerprint.js"
+import { PIN_KEY } from "../install/index.js"
 import {
   dedupeDiagnostics,
   formatDiagnostic,
@@ -33,10 +39,10 @@ export interface ConfigOperations {
   readonly workflow: WorkflowDefinition
   /** The default, resolved like a named one; its name is what status shows: the named export it also is, else `"default"`. */
   readonly defaultWorkflow: ResolvedWorkflow
-  /** Every name `gtd --workflow` accepts, sorted — never `"default"`. */
+  /** Every workflow name `gtd start` accepts, sorted — never `"default"`. */
   readonly workflowNames: readonly string[]
   readonly workflowNamed: (name: string) => ResolvedWorkflow | undefined
-  /** Every door `gtd door` accepts. A door's `workflow` resolves through `workflowNamed`. */
+  /** Every door `gtd start` accepts. A door's `workflow` resolves through `workflowNamed`. */
   readonly doors: ReadonlyMap<string, Door>
   /** `config.ui` (absent when unconfigured) — `gtd ui` and its CLI flags read it. */
   readonly ui?: flows.UiSettings
@@ -87,8 +93,8 @@ export const refuseLegacyRc: Effect.Effect<void, GtdError, Host | ConfigDiscover
           "gtd: config:",
           ...found.map((file) => `  - ${file}: no longer read — delete it`),
           "  gtd 23 removed the .gtdrc files; move each key they set:",
-          "    vars    → an option of the workflow factory in gtd.config.ts, or its `defaults` export",
-          "    env     → an option of the workflow factory in gtd.config.ts, or its `envDefaults` export",
+          "    vars    → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { defaults })`",
+          "    env     → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { envDefaults })`",
           "    judge   → ~/.config/gtd/judge.json, or GTD_JUDGE_PROVIDER / GTD_JUDGE_MODEL",
           "    modes, ui, skills, access → the `config` export of gtd.config.ts (`defineConfig`)",
           "    $schema → nothing; drop it",
@@ -98,9 +104,25 @@ export const refuseLegacyRc: Effect.Effect<void, GtdError, Host | ConfigDiscover
     )
   })
 
+const configModule: Effect.Effect<WorkflowModule, Error, Host | ConfigDiscovery> = Effect.gen(
+  function* () {
+    const host = yield* Host
+    const module = yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)
+    if (module !== undefined) return module
+    const missing: Diagnostic = {
+      severity: "error",
+      path: [],
+      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd guide\` says where to get one`,
+      origin: host.root,
+    }
+    return yield* Effect.fail(configError([missing]))
+  },
+)
+
 /**
- * Find and evaluate `gtd.config.ts`, then check what it exports. Every finding
- * is collected into ONE sorted report rather than failing on the first.
+ * Find and evaluate `gtd.config.ts` — or, inside a pin, the workflow bundled
+ * into it — then check what it exports. Every finding is collected into ONE
+ * sorted report rather than failing on the first.
  */
 export const load: Effect.Effect<
   ConfigOperations,
@@ -108,25 +130,30 @@ export const load: Effect.Effect<
   Narrator | Workspace | Host | ConfigDiscovery
 > = Effect.gen(function* () {
   const host = yield* Host
-  const discovery = yield* ConfigDiscovery
   yield* refuseLegacyRc
-  const module = yield* discovery.workflowModule(host.root, host.home)
-  if (module === undefined) {
-    const missing: Diagnostic = {
-      severity: "error",
-      path: [],
-      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd install\` says where to get one`,
-      origin: host.root,
-    }
-    return yield* Effect.fail(configError([missing]))
-  }
-  yield* (yield* Narrator).narrate(`config: module ${module.filepath}`)
-  const shipped = yield* Effect.tryPromise({
-    try: shippedModules,
-    catch: (e) => new GtdError(`gtd: ${e instanceof Error ? e.message : String(e)}`),
-  })
-  const loaded = yield* Effect.try({
-    try: () => loadWorkflows(module, shipped),
+  const pinned = pinnedWorkflow()
+  const module: WorkflowModule =
+    pinned === undefined
+      ? yield* configModule
+      : { filepath: resolvePath(host.root, pinned.origin), source: "" }
+  yield* (yield* Narrator).narrate(
+    `config: ${pinned === undefined ? "module" : "pinned module"} ${module.filepath}`,
+  )
+  const shipped =
+    pinned === undefined
+      ? yield* Effect.tryPromise({
+          try: shippedModules,
+          catch: (e) => new GtdError(`gtd: ${e instanceof Error ? e.message : String(e)}`),
+        })
+      : undefined
+  const loaded = yield* Effect.tryPromise({
+    try: async () =>
+      loadWorkflows(
+        module.filepath,
+        shipped === undefined
+          ? runPinned(pinned!, module.filepath, host.root)
+          : await evaluate(module, shipped),
+      ),
     catch: (e) =>
       new GtdError(
         `gtd: config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
@@ -142,17 +169,15 @@ export const load: Effect.Effect<
   }
 
   const initial = yield* firstStep(loaded.default, headTree(yield* Workspace))
-  const steering = loaded.file.steering as Record<string, StateMode>
   const define = (entry: LoadedWorkflow): WorkflowDefinition => ({
     flow: entry.flow,
-    summary: entry.file.summary,
-    // A config's own `base` export wins when it answers; else the factory's.
-    base: (w, v) => entry.file.base?.(w, v) ?? entry.base?.(w, v),
-    steering,
+    summary: entry.summary,
+    base: (w, v) => entry.base?.(w, v),
+    steering: entry.steering as Record<string, StateMode>,
     modes: compiled.modes,
-    skills: entry.file.skills,
+    skills: entry.skills,
     configuredSkills: compiled.skills,
-    access: entry.file.access,
+    access: entry.access,
     configuredAccess: compiled.access,
     skillsOrigin: entry.file.origin,
     initial,
@@ -176,11 +201,9 @@ export const load: Effect.Effect<
     },
     ...(compiled.ui !== undefined ? { ui: compiled.ui } : {}),
     warnings: diagnostics.filter((d) => d.severity === "warning"),
-    fingerprint: configFingerprint(
-      loaded.file.dependencyFiles,
-      host.root,
-      module.read ?? readFromDisk,
-    ),
+    fingerprint:
+      pinned?.fingerprint ??
+      configFingerprint(loaded.file.dependencyFiles, host.root, module.read ?? readFromDisk),
   }
 })
 
@@ -197,25 +220,21 @@ interface Settings {
   readonly envDefaults: Readonly<Record<string, string>>
 }
 
-interface LoadedFile
-  extends
-    Pick<WorkflowDefinition, "summary" | "base" | "steering" | "skills" | "access">,
-    Settings {
+interface LoadedFile {
   readonly origin: string
   /**
-   * Every real file this module's evaluation touched — `origin` itself plus
-   * any relative import it (transitively) resolved on disk, in NO particular
-   * order. A caller that
-   * needs to know when a workflow's DEFINITION might have changed (the LSP's
-   * steering-map memo) must watch this whole set, not just `origin`: a
-   * `gtd.config.ts` re-exporting a sibling module is a documented pattern,
-   * and jiti resolves that import off disk same as any other require.
+   * Every file bundled evaluating this module — `origin` itself plus every
+   * local module it (transitively) imports, in NO particular order. A caller
+   * that needs to know when a workflow's DEFINITION might have changed (the
+   * LSP's steering-map memo) must watch this whole set, not just `origin`: a
+   * `gtd.config.ts` re-exporting a sibling module is a documented pattern.
    */
   readonly dependencyFiles: readonly string[]
 }
 
-/** A startable workflow; its settings are its file's, under whatever its factory declared. */
-interface LoadedWorkflow extends Settings {
+/** A startable workflow, built from a factory or a `workflow()` call's options. */
+interface LoadedWorkflow
+  extends Settings, Pick<WorkflowDefinition, "summary" | "steering" | "skills" | "access"> {
   readonly flow: Flow
   readonly file: LoadedFile
   readonly doors?: flows.WorkflowDoors | undefined
@@ -233,76 +252,8 @@ interface Loaded {
   readonly diagnostics: readonly Diagnostic[]
 }
 
-type JitiInstance = {
-  evalModule: (
-    source: string,
-    options: { filename: string; async?: false; cache?: Record<string, unknown> },
-  ) => unknown
-}
-type JitiModule = {
-  createJiti: (id: string, options: Record<string, unknown>) => JitiInstance
-}
-
-type Transform = (options: { readonly source: string }) => { code: string; error?: unknown }
-
-// Transpiling is most of a load's cost, and a load re-transpiles
-// gtd.config.ts and every shipped module it imports. The same options (the
-// source included) always transpile to the same code, so an in-process memo
-// is safe; evaluation stays fresh on every load.
-const TRANSFORM_MEMO_SIZE = 512
-const memoized = (transform: Transform): Transform => {
-  const memo = new Map<string, ReturnType<Transform>>()
-  return (options) => {
-    const key = JSON.stringify(options)
-    const hit = memo.get(key)
-    if (hit !== undefined) return hit
-    const result = transform(options)
-    if (result.error !== undefined) return result
-    if (memo.size >= TRANSFORM_MEMO_SIZE) memo.delete(memo.keys().next().value!)
-    memo.set(key, result)
-    return result
-  }
-}
-
-let jitiModule: JitiModule | undefined
-let transform: Transform | undefined
-/** Relative specifiers a module imports, served from somewhere other than the disk. */
-interface LocalModules {
-  /** The path a specifier names, or nothing when it names no module. */
-  readonly resolve: (specifier: string) => string | undefined
-  readonly load: (path: string) => unknown
-}
-
-const jiti = (shipped: ShippedModules, local?: LocalModules): JitiInstance => {
-  const require = createRequire(import.meta.url)
-  jitiModule ??= require("jiti") as JitiModule
-  // jiti's own Babel transform, which its package exports don't name.
-  transform ??= memoized(
-    require(join(dirname(require.resolve("jiti/package.json")), "dist", "babel.cjs")) as Transform,
-  )
-  return jitiModule.createJiti(import.meta.url, {
-    // Consulted when a module is required, so a local module is evaluated
-    // only once an import actually runs.
-    virtualModules: new Proxy(shipped.modules, {
-      has: (modules, id) =>
-        id in modules || (typeof id === "string" && local?.resolve(id) !== undefined),
-      get: (modules, id) => {
-        const path = typeof id === "string" ? local?.resolve(id) : undefined
-        return path === undefined ? modules[id as string] : local!.load(path)
-      },
-    }),
-    alias: shipped.missing,
-    // No transpile cache on disk, and a fresh module every load — nothing a
-    // later command could read back instead of the source.
-    fsCache: false,
-    moduleCache: false,
-    transform,
-    // The whole module, not just its default: the named exports are read too.
-    interopDefault: false,
-  })
-}
-
 const PACKAGE = "@pmelab/gtd"
+const FLOWS = `${PACKAGE}/flows`
 
 interface PackageJson {
   readonly name?: string
@@ -311,7 +262,7 @@ interface PackageJson {
 
 // Only gtd's own package.json: whatever other one sits nearest (a vendored
 // bundle inside a project) must never get its exports executed.
-const ownPackage = (): { readonly root: string; readonly pkg: PackageJson } => {
+export const ownPackage = (): { readonly root: string; readonly pkg: PackageJson } => {
   const start = dirname(fileURLToPath(import.meta.url))
   for (let dir = start; ; dir = dirname(dir)) {
     const file = join(dir, "package.json")
@@ -342,7 +293,7 @@ const shippedModules = (): Promise<ShippedModules> =>
   (shippedMemo ??= (async () => {
     const fromSource = import.meta.url.endsWith(".ts")
     const files = subpathFiles(fromSource ? "source" : "default")
-    const modules: Record<string, unknown> = { [`${PACKAGE}/flows`]: flows }
+    const modules: Record<string, unknown> = { [FLOWS]: flows }
     const missing: Record<string, string> = {}
     if (process.features.require_module && !fromSource) {
       return { modules: requiredOnUse(modules, files), missing }
@@ -384,75 +335,105 @@ const requiredOnUse = (
   })
 }
 
-const stringRecord = (
-  exports: Record<string, unknown>,
-  name: string,
-): Readonly<Record<string, string>> => {
-  const value = exports[name] ?? {}
+/** `what` names the value in an error: `workflow "x"'s "steering"`. */
+const stringRecord = (value: unknown, what: string): Readonly<Record<string, string>> => {
+  const record = value ?? {}
   if (
-    typeof value !== "object" ||
-    value === null ||
-    Object.values(value).some((entry) => typeof entry !== "string")
+    typeof record !== "object" ||
+    record === null ||
+    Object.values(record).some((entry) => typeof entry !== "string")
   ) {
-    throw new Error(`the "${name}" export is not a record of strings`)
+    throw new Error(`${what} is not a record of strings`)
   }
-  return value as Readonly<Record<string, string>>
+  return record as Readonly<Record<string, string>>
 }
 
 const isStringArray = (v: unknown): v is readonly string[] =>
   Array.isArray(v) && v.every((entry) => typeof entry === "string")
 
-const checkSkillsRecord = (value: unknown): Readonly<Record<string, readonly string[]>> => {
+const checkSkillsRecord = (
+  value: unknown,
+  what: string,
+): Readonly<Record<string, readonly string[]>> => {
   if (
     typeof value !== "object" ||
     value === null ||
     Object.values(value).some((entry) => !isStringArray(entry))
   ) {
-    throw new Error(`the "skills" export is not a record of skill-name arrays`)
+    throw new Error(`${what} is not a record of skill-name arrays`)
   }
   return value as Readonly<Record<string, readonly string[]>>
 }
 
-/** Read a module's optional `skills` export — a scope full name -> skill list record, or a function of the vars returning one. */
-const skillsExport = (exports: Record<string, unknown>): WorkflowDefinition["skills"] => {
-  const value = exports["skills"] ?? {}
+/** A workflow's `skills` option — a scope full name -> skill list record, or a function of the vars returning one. */
+const skillsFrom = (value: unknown, what: string): WorkflowDefinition["skills"] => {
   if (typeof value === "function") {
-    return (vars) => checkSkillsRecord((value as (v: typeof vars) => unknown)(vars))
+    return (vars) => checkSkillsRecord((value as (v: typeof vars) => unknown)(vars), what)
   }
-  const record = checkSkillsRecord(value)
+  const record = checkSkillsRecord(value ?? {}, what)
   return () => record
 }
 
-/** Read a module's optional `access` export — a scope full name -> `{ read?, write? }` record, or a function of the vars returning one. */
-const accessExport = (exports: Record<string, unknown>): WorkflowDefinition["access"] => {
-  const value = exports["access"] ?? {}
+const checkAccessRecord = (value: unknown, what: string): Readonly<Record<string, ScopeAccess>> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${what} is not a record of scope access (scope -> { read?, write? }) or a function returning one`,
+    )
+  }
+  for (const [scope, access] of Object.entries(value)) {
+    const fault = accessShapeFault(access)
+    if (fault !== undefined) throw new Error(`${what}: scope "${scope}": ${fault}`)
+  }
+  return value as Readonly<Record<string, ScopeAccess>>
+}
+
+/**
+ * A workflow's `access` option — a scope full name -> `{ read?, write? }`
+ * record, checked now, or a function of the vars returning one, checked when
+ * the process's settings are known.
+ */
+const accessFrom = (value: unknown, what: string): WorkflowDefinition["access"] => {
   if (typeof value === "function") {
     return (vars) => (value as (v: typeof vars) => never)(vars)
   }
-  return () => value as never
+  const record = checkAccessRecord(value ?? {}, what)
+  return () => record
 }
 
-const optionalFunction = <T>(exports: Record<string, unknown>, name: string): T | undefined => {
-  const value = exports[name]
+const optionalFunction = <T>(value: unknown, what: string): T | undefined => {
   if (value === undefined) return undefined
-  if (typeof value !== "function") throw new Error(`the "${name}" export is not a function`)
+  if (typeof value !== "function") throw new Error(`${what} is not a function`)
   return value as T
 }
 
-const RESERVED_EXPORTS: ReadonlySet<string> = new Set([
-  "default",
-  "summary",
-  "base",
+// What each file-level export of earlier versions became: an option of the
+// workflow it configured. Exporting one is a load error, never silently ignored.
+const RETIRED_EXPORTS: ReadonlySet<string> = new Set([
   "defaults",
   "envDefaults",
   "steering",
   "skills",
   "access",
   "doors",
-  "config",
+  "summary",
+  "base",
 ])
 
-/** The rules every declared setting meets, whether a file's export or a factory's build. */
+/** Names that are never a workflow. */
+const RESERVED_EXPORTS: ReadonlySet<string> = new Set(["default", "config", ...RETIRED_EXPORTS])
+
+const retiredExports = (exports: Record<string, unknown>, origin: string): Diagnostic[] =>
+  Object.keys(exports)
+    .filter((name) => RETIRED_EXPORTS.has(name))
+    .sort()
+    .map((name) => ({
+      severity: "error",
+      path: [name],
+      origin,
+      message: `the "${name}" export is no longer read — pass it to the workflow it configures: \`workflow(flow, { ${name} })\`, or the build a workflow factory returns`,
+    }))
+
+/** The rules every declared setting meets. */
 const checkSettings = (
   defaults: Readonly<Record<string, unknown>>,
   envDefaults: Readonly<Record<string, unknown>>,
@@ -481,28 +462,6 @@ const checkSettings = (
   }
 }
 
-/** A module's per-file exports: `defaults`, `envDefaults`, `steering`, `skills`, `access`, `summary`, `base`. */
-const fileFrom = (
-  exports: Record<string, unknown>,
-  origin: string,
-  dependencyFiles: readonly string[],
-): LoadedFile => {
-  const defaults = stringRecord(exports, "defaults")
-  const envDefaults = stringRecord(exports, "envDefaults")
-  checkSettings(defaults, envDefaults, (kind) => `the "${kind}" export declares`)
-  return {
-    defaults,
-    envDefaults,
-    steering: stringRecord(exports, "steering"),
-    skills: skillsExport(exports),
-    access: accessExport(exports),
-    summary: optionalFunction(exports, "summary"),
-    base: optionalFunction(exports, "base"),
-    origin,
-    dependencyFiles,
-  }
-}
-
 const DOOR_NAME_RULE = /^[a-z][a-z0-9-]*$/
 
 /** Why one door's `args` are malformed, or `undefined` when they are well-formed. */
@@ -532,27 +491,12 @@ const doorProblem = (name: string, door: unknown): string | undefined => {
   return argsProblem(args) ?? (varsOk ? undefined : `has "vars" that is not a function`)
 }
 
-/** A module's `doors` export, shape-checked; the workflow names are checked later, against the catalogue. */
-const doorsFrom = (exports: Record<string, unknown>): ReadonlyMap<string, Door> => {
-  const value = exports["doors"]
-  if (value === undefined) return new Map()
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error(`the "doors" export is not a record of doors`)
-  }
-  for (const [name, door] of Object.entries(value)) {
-    const problem = doorProblem(name, door)
-    if (problem !== undefined) throw new Error(`door "${name}" ${problem}`)
-  }
-  return new Map(Object.entries(value) as [string, Door][])
-}
-
 /**
- * Each exported workflow's own doors, onto the name it is exported under. The
- * `doors` export adds to them and declares a name several workflows clash on.
+ * Each exported workflow's own doors, onto the name it is exported under. A
+ * door several workflows build and none is exported under is a clash: no door.
  */
 const derivedDoors = (
   catalogue: ReadonlyMap<string, LoadedWorkflow>,
-  declared: ReadonlyMap<string, Door>,
 ): {
   readonly doors: ReadonlyMap<string, Door>
   readonly clashes: ReadonlyMap<string, readonly string[]>
@@ -572,53 +516,30 @@ const derivedDoors = (
   for (const [name, built] of builders) {
     const owner = ownerOf(name, built)
     if (owner !== undefined) doors.set(name, owner)
-    else if (!declared.has(name))
+    else
       clashes.set(
         name,
         built.map((door) => door.workflow),
       )
   }
-  return { doors: new Map([...doors, ...declared]), clashes }
+  return { doors, clashes }
 }
 
 /** The export named after the door owns it, else the sole builder; a clash of several builds no door. */
 const ownerOf = (name: string, built: readonly Door[]): Door | undefined =>
   built.find((door) => door.workflow === name) ?? (built.length === 1 ? built[0] : undefined)
 
-/** Sort the doors and check each names a startable workflow. */
-const checkDoors = (
-  declared: ReadonlyMap<string, Door>,
-  catalogue: ReadonlyMap<string, LoadedWorkflow>,
-): ReadonlyMap<string, Door> => {
-  const doors = new Map([...declared].sort(([a], [b]) => a.localeCompare(b)))
-  for (const [name, door] of doors) {
-    if (!catalogue.has(door.workflow)) {
-      throw new Error(
-        `door "${name}" names workflow "${door.workflow}", which is not startable — known: ${[...catalogue.keys()].sort().join(", ")}`,
-      )
-    }
-  }
-  return doors
-}
-
 const namespaceOf = (exported: unknown): Record<string, unknown> =>
   (typeof exported === "object" && exported !== null ? exported : {}) as Record<string, unknown>
 
 /**
- * Evaluate `gtd.config.ts`. Every exported function or factory workflow but
- * the reserved names is a workflow named by its export. `cache` is jiti's OWN
- * per-call module cache (unrelated to the instance's `moduleCache: false`) —
- * passing an empty object in has the side effect of collecting every real file
- * jiti resolved evaluating this module, module AND every relative import it
- * pulled in, transitively.
+ * Evaluate `gtd.config.ts`. Every export but the reserved names that went
+ * through `workflow()` or is a factory workflow is a workflow named by its
+ * export.
  */
-const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded => {
-  const { exports: evaluated, files } =
-    module.read === undefined
-      ? evaluateFromDisk(module, shipped)
-      : evaluateRead(module, module.read, shipped)
-  const exports = namespaceOf(evaluated)
-  const file = fileFrom(exports, module.filepath, files)
+const loadWorkflows = (origin: string, evaluated: Evaluated): Loaded => {
+  const exports = namespaceOf(evaluated.exports)
+  const file: LoadedFile = { origin, dependencyFiles: evaluated.files }
   const exported = Object.entries(exports).filter(
     ([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value),
   )
@@ -643,20 +564,23 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   const derived =
     rejections.length > 0
       ? { doors: new Map<string, Door>(), clashes: new Map<string, readonly string[]>() }
-      : derivedDoors(catalogue, doorsFrom(exports))
+      : derivedDoors(catalogue)
+  const doors = new Map([...derived.doors].sort(([a], [b]) => a.localeCompare(b)))
   return {
     file,
     catalogue,
-    doors: checkDoors(derived.doors, catalogue),
+    doors,
     default: defaultWorkflow && { ...defaultWorkflow, name: defaultName },
-    config: compileConfig(exports["config"], module.filepath),
+    config: compileConfig(exports["config"], origin),
     diagnostics: [
+      ...retiredExports(exports, file.origin),
       ...nameRejections(rejections),
+      ...shadowingDoors(doors, catalogue, file.origin),
       ...[...derived.clashes].map(([name, builders]): Diagnostic => {
         const names = [...builders].sort().map((b) => JSON.stringify(b))
         return {
           severity: "warning",
-          message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — declare it in the "doors" export`,
+          message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — rename the export that should own it to "${name}"`,
           path: ["doors", name],
           origin: file.origin,
         }
@@ -665,17 +589,23 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   }
 }
 
-const evaluateFromDisk = (
-  module: WorkflowModule,
-  shipped: ShippedModules,
-): { readonly exports: unknown; readonly files: readonly string[] } => {
-  const cache: Record<string, unknown> = {}
-  const exports = jiti(shipped).evalModule(module.source, { filename: module.filepath, cache })
-  return { exports, files: Object.keys(cache) }
-}
+/** `gtd start <name>` takes the door, so a door named like a workflow it does not start hides that workflow. */
+const shadowingDoors = (
+  doors: ReadonlyMap<string, Door>,
+  catalogue: ReadonlyMap<string, unknown>,
+  origin: string,
+): Diagnostic[] =>
+  [...doors]
+    .filter(([name, door]) => catalogue.has(name) && door.workflow !== name)
+    .map(([name, door]) => ({
+      severity: "warning",
+      message: `door "${name}" starts workflow ${JSON.stringify(door.workflow)} and hides the workflow of the same name from \`gtd start ${name}\` — rename one of them`,
+      path: ["doors", name],
+      origin,
+    }))
 
-// How jiti finds a TypeScript module behind a specifier: as written, its
-// `.js` spelling as `.ts`, with `.ts` appended, or as a directory index.
+// How a TypeScript module is found behind a relative specifier: as written,
+// its `.js` spelling as `.ts`, with `.ts` appended, or as a directory index.
 const moduleCandidates = (path: string): readonly string[] => [
   path,
   path.replace(/\.js$/, ".ts"),
@@ -684,97 +614,341 @@ const moduleCandidates = (path: string): readonly string[] => [
   join(path, "index.ts"),
 ]
 
+interface Evaluated {
+  readonly exports: unknown
+  readonly files: readonly string[]
+}
+
+/** A bundle's one chunk: CommonJS, so it runs as a plain function. */
+type Chunk = (
+  exports: unknown,
+  require: (id: string) => unknown,
+  module: { exports: unknown },
+  __filename: string,
+  __dirname: string,
+) => void
+
+const execute = (chunk: Chunk, filepath: string, require: (id: string) => unknown): unknown => {
+  const cjs = { exports: {} as unknown }
+  chunk(cjs.exports, require, cjs, filepath, dirname(filepath))
+  return cjs.exports
+}
+
 /**
- * Evaluates the config with every local module it imports taken from `read`
- * instead of the disk. jiti matches a virtual module on the specifier as
- * written, so each module gets its own instance resolving against its own
- * directory. A specifier `read` cannot serve falls through to the disk, and
- * fails the way a missing file does.
+ * Bundles the config and every local module it imports in memory, then
+ * evaluates the bundle. With `read`, a relative import `read` can serve is
+ * taken from it instead of the disk; one it cannot falls through to the disk,
+ * and fails the way a missing file does. An ES module or TypeScript package is
+ * bundled too; a CommonJS one is required from where its importer resolved
+ * it, as Node would. `@pmelab/gtd/*` is the running gtd's own copy, and
+ * `files` leaves out every package file.
  */
-const evaluateRead = (
+const evaluate = async (module: WorkflowModule, shipped: ShippedModules): Promise<Evaluated> => {
+  const { code, files } = await bundleConfig(module, { kind: "evaluate", shipped })
+  const fromConfig = createRequire(module.filepath)
+  const require = Object.assign(
+    (id: string): unknown =>
+      id in shipped.modules
+        ? shipped.modules[id]
+        : fromConfig(id in shipped.missing ? shipped.missing[id]! : id),
+    { resolve: fromConfig.resolve },
+  )
+  const chunk = runInThisContext(
+    `(function (exports, require, module, __filename, __dirname) {${code}\n})`,
+    { filename: module.filepath },
+  ) as Chunk
+  return { exports: execute(chunk, module.filepath, require), files }
+}
+
+/**
+ * What a pin registers: its workflow bundled, its origin relative to the
+ * repository root, and the fingerprint of the files it was bundled from — the
+ * content it runs, whatever the disk holds now.
+ */
+interface PinnedWorkflow {
+  readonly version: string
+  readonly origin: string
+  readonly fingerprint: ConfigFingerprint
+  readonly run: Chunk
+}
+
+const pinnedWorkflow = (): PinnedWorkflow | undefined =>
+  (globalThis as { [PIN_KEY]?: PinnedWorkflow })[PIN_KEY]
+
+const runPinned = (pinned: PinnedWorkflow, filepath: string, root: string): Evaluated => ({
+  // Everything but the engine's own flows and Node's builtins is in the bundle.
+  exports: execute(pinned.run, filepath, (id) =>
+    id === FLOWS ? flows : createRequire(import.meta.url)(id),
+  ),
+  files: Object.keys(pinned.fingerprint).map((file) => resolvePath(root, file)),
+})
+
+/**
+ * The statement that registers `module`'s workflow for a pin: the config and
+ * everything it imports — npm packages and gtd's own subpaths included — in
+ * one function, so the engine runs it without a config, a package or rolldown.
+ */
+export const pinnedWorkflowSource = async (
   module: WorkflowModule,
-  read: (path: string) => string | undefined,
-  shipped: ShippedModules,
-): { readonly exports: unknown; readonly files: readonly string[] } => {
-  const files = [module.filepath]
-  const evaluated = new Map<string, unknown>()
-  const evaluate = (filepath: string, source: string): unknown =>
-    jiti(shipped, {
-      resolve: (specifier) =>
-        /^\.\.?\//.test(specifier)
-          ? moduleCandidates(join(dirname(filepath), specifier)).find(
-              (candidate) => read(candidate) !== undefined,
-            )
-          : undefined,
-      load: (path) => {
-        if (!evaluated.has(path)) {
-          // A placeholder first, so an import cycle ends here.
-          evaluated.set(path, {})
-          files.push(path)
-          evaluated.set(path, evaluate(path, read(path)!))
-        }
-        return evaluated.get(path)
-      },
-    }).evalModule(source, { filename: filepath })
-  return { exports: evaluate(module.filepath, module.source), files }
+  root: string,
+  version: string,
+): Promise<string> => {
+  const gtd = realpathSync(ownPackage().root) + sep
+  const { code, files } = await bundleConfig(module, {
+    kind: "pin",
+    shipped: subpathFiles(import.meta.url.endsWith(".ts") ? "source" : "default"),
+  })
+  // gtd's own subpaths are bundled from its package, which only a config
+  // living in gtd's own repository may count among its files.
+  const own = (file: string) => file.startsWith(gtd) && !module.filepath.startsWith(gtd)
+  const registered = {
+    version,
+    origin: relative(root, module.filepath),
+    fingerprint: configFingerprint(
+      files.filter((file) => !own(file)),
+      root,
+      module.read ?? readFromDisk,
+    ),
+  }
+  return `globalThis[Symbol.for(${JSON.stringify(PIN_KEY.description)})] = { ...${JSON.stringify(registered)}, run: function (exports, require, module, __filename, __dirname) {\n${code}\n} };\n`
+}
+
+type BundleMode =
+  | { readonly kind: "evaluate"; readonly shipped: ShippedModules }
+  // Every import goes into the bundle but flows, the engine's own.
+  | { readonly kind: "pin"; readonly shipped: ReadonlyMap<string, string> }
+
+const shippedImport = (
+  source: string,
+  mode: BundleMode,
+): string | { readonly id: string; readonly external: true } | undefined => {
+  if (mode.kind === "pin")
+    return source === FLOWS ? { id: source, external: true } : mode.shipped.get(source)
+  return source in mode.shipped.modules || source in mode.shipped.missing
+    ? { id: source, external: true }
+    : undefined
+}
+
+const bundleConfig = async (
+  module: WorkflowModule,
+  mode: BundleMode,
+): Promise<{ readonly code: string; readonly files: readonly string[] }> => {
+  const { read } = module
+  const served = new Set<string>()
+  const fromRead = (path: string): string | null => {
+    const hit = moduleCandidates(path).find((candidate) => read?.(candidate) !== undefined)
+    if (hit === undefined) return null
+    served.add(hit)
+    return hit
+  }
+  const plugin: RolldownPlugin = {
+    name: "gtd-config",
+    async resolveId(source, importer) {
+      if (importer === undefined) return source === module.filepath ? source : null
+      const shipped = shippedImport(source, mode)
+      if (shipped !== undefined) return shipped
+      if (/^\.\.?(\/|$)/.test(source)) return fromRead(join(dirname(importer), source))
+      if (!isPackage(source)) return null
+      const resolved = await this.resolve(source, importer, { skipSelf: true })
+      return mode.kind === "pin" ? resolved : packageImport(source, resolved)
+    },
+    load(id) {
+      if (mode.kind === "pin" && isNativeAddon(id)) throw new Error(nativeAddon(id))
+      if (id === module.filepath) return module.source
+      return served.has(id) ? read!(id) : null
+    },
+    // One bundle has one file; each module keeps its own location.
+    transform(code, id) {
+      return code.replace(/\bimport\.meta\.(url|filename|dirname)\b/g, (_, key: string) =>
+        JSON.stringify(
+          key === "url" ? pathToFileURL(id).href : key === "filename" ? id : dirname(id),
+        ),
+      )
+    },
+  }
+  const bundle = await (rolldownModule ??= requireRolldown()).rolldown({
+    input: module.filepath,
+    platform: "node",
+    plugins: [plugin],
+    external: (id) => isBuiltin(id),
+    resolve: { extensionAlias: { ".js": [".js", ".ts"], ".mjs": [".mjs", ".mts"] } },
+    // Every statement runs, as it would unbundled.
+    treeshake: false,
+    tsconfig: false,
+    logLevel: "silent",
+  })
+  try {
+    const { output } = await bundle
+      // One chunk, and no `import()` left: the bundle runs as a plain function.
+      .generate({
+        format: "cjs",
+        exports: "named",
+        codeSplitting: false,
+        dynamicImportInCjs: false,
+      })
+      .catch((e) => {
+        throw bundleError(e)
+      })
+    const chunk = output[0]
+    return {
+      code: chunk.code,
+      files: chunk.moduleIds.filter((id) => !id.startsWith("\0") && !inPackage(id)),
+    }
+  } finally {
+    await bundle.close()
+  }
+}
+
+// A pin is plain JavaScript: a compiled addon stays a file on one machine.
+// A package node-gyp builds loads its addon by a path no bundler sees.
+const isNativeAddon = (id: string): boolean => {
+  if (id.endsWith(".node")) return true
+  const at = id.lastIndexOf(`node_modules${sep}`)
+  if (at < 0) return false
+  const rest = id.slice(at + `node_modules${sep}`.length).split(sep)
+  const root =
+    id.slice(0, at) + ["node_modules", ...rest.slice(0, rest[0]!.startsWith("@") ? 2 : 1)].join(sep)
+  return existsSync(join(root, "binding.gyp"))
+}
+
+const nativeAddon = (path: string): string => {
+  const at = path.lastIndexOf(`node_modules${sep}`)
+  const rest = at < 0 ? [] : path.slice(at + `node_modules${sep}`.length).split(sep)
+  const name = rest[0]?.startsWith("@") ? rest.slice(0, 2).join("/") : rest[0]
+  return `${name === undefined ? path : `package "${name}"`} loads a native addon (${path}), which a pin cannot carry`
 }
 
+// Bundled, an ES module gets the shipped `@pmelab/gtd/*` like the config
+// does. CommonJS stays Node's: it may read `__dirname`, which a bundle loses.
+const packageImport = (
+  source: string,
+  resolved: { readonly id: string } | null,
+): string | { readonly id: string; readonly external: true } =>
+  resolved !== null && isEsModule(resolved.id)
+    ? resolved.id
+    : { id: resolved?.id ?? source, external: true }
+
+const isEsModule = (path: string): boolean => {
+  if (/\.(mjs|[cm]?tsx?)$/.test(path)) return true
+  if (!/\.jsx?$/.test(path)) return false
+  for (let dir = dirname(path); dirname(dir) !== dir; dir = dirname(dir)) {
+    const file = join(dir, "package.json")
+    if (existsSync(file)) {
+      return (JSON.parse(readFileSync(file, "utf8")) as { type?: string }).type === "module"
+    }
+  }
+  return false
+}
+
+const inPackage = (path: string): boolean => /[\\/]node_modules[\\/]/.test(path)
+
+const isPackage = (specifier: string): boolean => !isAbsolute(specifier) && !isBuiltin(specifier)
+
+// rolldown reports each error with a colored code frame; a diagnostic takes
+// its headline and location.
+const bundleError = (e: unknown): unknown => {
+  const errors = (e as { errors?: readonly { message: string }[] } | null)?.errors
+  if (errors === undefined) return e
+  const lines = errors.map(({ message }) => {
+    const plain = stripVTControlCharacters(message)
+    const at = /\[ (.+:\d+:\d+) \]/.exec(plain)?.[1]
+    const headline = plain.split("\n")[0]!
+    return at === undefined ? headline : `${headline} (${at})`
+  })
+  return new Error(lines.join("\n"))
+}
+
+type Rolldown = typeof import("rolldown")
+let rolldownModule: Rolldown | undefined
+// Required at run time, never bundled: rolldown ships a native binding.
+const requireRolldown = (): Rolldown => createRequire(import.meta.url)("rolldown") as Rolldown
+
 const isWorkflow = (value: unknown): boolean =>
-  typeof value === "function" || flows.isFactoryWorkflow(value)
+  markedOptions(value) !== undefined || isFactoryWorkflow(value)
 
 const defaultExport = (exports: Record<string, unknown>): unknown => {
   const value = exports.default
   if (value === undefined) {
     throw new Error(
-      "no default export — export the workflow an ordinary start runs (`gtd install` scaffolds one)",
+      "no default export — export the workflow an ordinary start runs; `gtd guide` says where to get one, or write your own",
     )
   }
-  if (!isWorkflow(value)) throw new Error("the default export is not a function")
+  if (typeof value !== "function" && !isFactoryWorkflow(value)) {
+    throw new Error("the default export is not a function")
+  }
   return value
 }
 
-/** One exported workflow: a plain flow as-is, a factory validated and built. */
+/** One exported workflow: a factory validated and built, a `workflow()` call's options checked alike. */
 const buildWorkflow = (
   name: string,
   value: unknown,
   file: LoadedFile,
   rejections: Rejection[],
 ): LoadedWorkflow | undefined => {
-  const result = flows.configure(value)
-  if (result === undefined)
-    return { flow: value as Flow, file, defaults: file.defaults, envDefaults: file.envDefaults }
+  const result = configure(value)
+  if (result === undefined) {
+    // A plain function only gets here as the default export: a flow without options.
+    return checkedBuild(name, file, { ...markedOptions(value), flow: value as Flow })
+  }
   if (!result.ok) {
     for (const issue of result.issues) rejections.push(optionDiagnostic(name, issue, file))
     return undefined
   }
+  return checkedBuild(name, file, result.build)
+}
+
+const BUILD_KEYS: ReadonlySet<string> = new Set([
+  "flow",
+  "defaults",
+  "envDefaults",
+  "doors",
+  "base",
+  "skills",
+  "access",
+  "steering",
+  "summary",
+])
+
+/** A build — a factory's, or a `workflow()` call's options with its flow — held to one set of rules. */
+const checkedBuild = (
+  name: string,
+  file: LoadedFile,
+  build: flows.WorkflowBuild,
+): LoadedWorkflow => {
+  const what = (key: string): string => `workflow "${name}"'s "${key}"`
+  const unknown = Object.keys(build).filter((key) => !BUILD_KEYS.has(key))
+  if (unknown.length > 0) {
+    throw new Error(
+      `workflow "${name}" has unknown option(s) ${unknown.map((key) => JSON.stringify(key)).join(", ")} — known: ${[...BUILD_KEYS].filter((key) => key !== "flow").join(", ")}`,
+    )
+  }
+  if (typeof build.flow !== "function") throw new Error(`${what("flow")} is not a function`)
+  const defaults = stringRecord(build.defaults, what("defaults"))
+  const envDefaults = stringRecord(build.envDefaults, what("envDefaults"))
+  checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" declares ${kind}`)
+  if (
+    build.doors !== undefined &&
+    (typeof build.doors !== "object" || build.doors === null || Array.isArray(build.doors))
+  ) {
+    throw new Error(`${what("doors")} is not a record of doors`)
+  }
   return {
-    flow: result.build.flow,
+    flow: build.flow,
     file,
-    ...builtSettings(name, file, result.build),
-    doors: result.build.doors,
-    base: result.build.base,
+    defaults,
+    envDefaults,
+    summary: optionalFunction<flows.Summary>(build.summary, what("summary")),
+    steering: stringRecord(build.steering, what("steering")),
+    skills: skillsFrom(build.skills, what("skills")),
+    access: accessFrom(build.access, what("access")),
+    doors: build.doors,
+    base: optionalFunction<flows.WorkflowBase>(build.base, what("base")),
   }
 }
 
-/** A factory's settings over its file's, held to the rules a file's own exports are. */
-const builtSettings = (name: string, file: LoadedFile, build: flows.WorkflowBuild): Settings => {
-  checkSettings(
-    build.defaults ?? {},
-    build.envDefaults ?? {},
-    (kind) => `workflow "${name}" builds ${kind}`,
-  )
-  const defaults = { ...file.defaults, ...build.defaults }
-  const envDefaults = { ...file.envDefaults, ...build.envDefaults }
-  checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" builds ${kind}`)
-  return { defaults, envDefaults }
-}
-
 /** A rejected factory option, reported at `gtd.config.ts`. */
-const optionDiagnostic = (
-  workflow: string,
-  issue: flows.OptionIssue,
-  file: LoadedFile,
-): Rejection => ({
+const optionDiagnostic = (workflow: string, issue: OptionIssue, file: LoadedFile): Rejection => ({
   workflow,
   severity: "error",
   path: issue.path,
@@ -905,7 +1079,7 @@ const firstStep = (
     const empty = watchedEmptyTree()
     const vars = watchedEmptySettings()
     const env = watchedEmptySettings()
-    const outcome = yield* Effect.either(
+    const outcome = yield* Effect.result(
       replayToFirstStep(loaded, vars.settings, env.settings, empty.tree),
     )
     const reads = [...settingReads("process", vars), ...settingReads("environment", env)]
@@ -916,8 +1090,8 @@ const firstStep = (
         ),
       )
     }
-    if (outcome._tag === "Left") return yield* Effect.fail(outcome.left)
-    const name = outcome.right
+    if (outcome._tag === "Failure") return yield* Effect.fail(outcome.failure)
+    const name = outcome.success
     if (!empty.read()) return name
     const atHead = yield* replayToFirstStep(loaded, vars.settings, env.settings, head)
     if (atHead === name) return name
@@ -936,9 +1110,8 @@ interface ConfigServiceOperations {
   >
 }
 
-export class ConfigService extends Context.Tag("ConfigService")<
-  ConfigService,
-  ConfigServiceOperations
->() {
+export class ConfigService extends Context.Service<ConfigService, ConfigServiceOperations>()(
+  "ConfigService",
+) {
   static Live = Layer.succeed(ConfigService, { load })
 }