@prestack/thread 0.0.1 → 0.0.3

package/dist/operations/makers/capability.ts

@@ -0,0 +1,166 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { argv, exit, stdout } from 'node:process'
+
+import { RECEIPT, answer, asking, given, issue, only, refuse, spend, wordsIn } from '../../core/asking.ts'
+import { findTree } from '../../core/tree.ts'
+
+import { CAPABILITIES_AT, SURFACES, isSurface, type Capability, type Surface } from '../capabilities.ts'
+
+const TREE = findTree()
+
+const at = resolve(TREE.at, CAPABILITIES_AT)
+
+if (!existsSync(at)) {
+  refuse(
+    `${CAPABILITIES_AT} is not there, so this app has nothing reachable to switch. Declare an operation with ` +
+      '`thread create operation` — it writes this table on its way out — or run `thread capabilities`.',
+  )
+}
+
+let table: readonly Capability[]
+try {
+  table = JSON.parse(readFileSync(at, 'utf8')) as readonly Capability[]
+} catch (thrown) {
+  refuse(
+    `${CAPABILITIES_AT} could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}. ` +
+      'Run `thread capabilities` — it is derived, so it can always be written again.',
+  )
+}
+
+if (table.length === 0) {
+  refuse('this app declares no operation, so there is nothing to switch on or off yet.')
+}
+
+const mark = (one: Capability): readonly string[] => [
+  `  ${one.operation} — ${one.describes}`,
+  `      ${SURFACES.map((each) => `${one.live.includes(each) ? '[on] ' : '[off]'} ${each}`).join('   ')}`,
+  `      ${one.browsable ? 'may be called from a page' : 'server only — it reaches a target that needs a server secret'}`,
+]
+
+const listing = [`${String(table.length)} operation(s):`, ...table.flatMap(mark)].join('\n')
+
+const words = wordsIn(['edit'])
+
+const verb = words[0]
+
+stdout.write(`${listing}\n`)
+
+const ASKS: readonly { readonly key: string; readonly says: readonly string[] }[] = [
+  {
+    key: 'live',
+    says: [
+      'which surfaces are on, comma-separated. Answering nothing switches every',
+      'one of them off, which leaves the operation declared, compiled and proven',
+      'and reachable by nobody — a real thing to want, and said out loud rather',
+      'than refused.',
+    ],
+  },
+]
+
+const TAKES: readonly string[] = ASKS.map((one) => one.key)
+
+const ASKED: readonly string[] = ASKS.flatMap((one) =>
+  one.says.map((line, at) => `  ${at === 0 ? `${one.key}:`.padEnd(8) : ' '.repeat(8)}${line}`),
+)
+
+const method = (nonce: string): string =>
+  [
+    '',
+    'what this changes:',
+    '',
+    `  thread create capability edit <operation> ${RECEIPT} ${nonce}`,
+    '',
+    `  ${RECEIPT} is spent by one run and refused if the table moved after it was issued.`,
+    '',
+    `a surface is a way this app is CALLED, and there are ${String(SURFACES.length)}: ${SURFACES.join(', ')}.`,
+    '',
+    '  cli   a command a terminal runs',
+    '  api   a route a request arrives on, and the OpenAPI document written from it',
+    '  mcp   a tool an agent is offered. Switch this off and an AI actor cannot call the operation,',
+    '        while everything else about it goes on working',
+    '',
+    '`edit` asks, one answer per line:',
+    '',
+    ...ASKED,
+    '',
+    'It writes the flag and runs `thread capabilities`, which carries every flag across and rewrites',
+    'the tool list, the OpenAPI document and the client bundle from them.',
+  ].join('\n')
+
+const flagged = argv.indexOf(RECEIPT)
+
+if (verb === undefined && flagged === -1) {
+  const nonce = issue(TREE.at, listing)
+  stdout.write(`${method(nonce)}\n`)
+  stdout.write(`\ncapability: receipt ${nonce} — spent on use, and stale the moment ${CAPABILITIES_AT} changes.\n`)
+  exit(0)
+}
+
+spend(TREE.at, listing, argv[flagged + 1], CAPABILITIES_AT)
+
+if (verb !== 'edit') {
+  refuse(`there is nothing called "${verb ?? ''}" to do here — say edit. A capability is derived, so there is none to add`)
+}
+
+const which = words[1]
+if (which === undefined) {
+  refuse('`edit` takes the name of an operation this app declares')
+}
+
+const one = table.find((each) => each.operation === which)
+if (one === undefined) {
+  refuse(`\`${which}\` is not an operation this app declares. What is here is ${table.map((each) => each.operation).join(', ')}`)
+}
+
+const piped = given()
+only(piped, TAKES, 'editing a capability')
+const { ask, shut } = asking(piped)
+
+const said = (
+  piped.length > 0
+    ? (answer(piped, 'live') ?? '')
+    : await ask('live', `which surfaces are on — ${SURFACES.join(', ')} (now: ${one.live.join(', ') || 'none'}): `)
+).trim()
+shut()
+
+const wanted = said
+  .split(',')
+  .map((each) => each.trim().toLowerCase())
+  .filter((each) => each !== '')
+
+const wrong = wanted.filter((each) => !isSurface(each))
+if (wrong.length > 0) {
+  refuse(
+    `there is no surface called ${wrong.map((each) => `"${each}"`).join(', ')}. There are ${String(SURFACES.length)}: ` +
+      `${SURFACES.join(', ')}. Nothing was written.`,
+  )
+}
+
+const live = SURFACES.filter((each) => wanted.includes(each))
+
+writeFileSync(
+  at,
+  `${JSON.stringify(
+    table.map((each) => (each.operation === one.operation ? { ...each, live } : each)),
+    null,
+    2,
+  )}\n`,
+)
+
+const off = SURFACES.filter((each) => !live.includes(each))
+stdout.write(
+  `capability: ${one.operation} is live on ${live.join(', ') || 'nothing'}` +
+    `${off.length === 0 ? '' : `, and off for ${off.join(', ')}`}.\n`,
+)
+
+for (const what of [['capabilities'], ['docs']]) {
+  const made = spawnSync('npx', ['thread', ...what], { cwd: TREE.at, encoding: 'utf8' })
+  stdout.write(`${`${made.stdout ?? ''}${made.stderr ?? ''}`.trim()}\n`)
+  if (made.status !== 0) {
+    stdout.write(`capability: the flag is written and stands; \`thread ${what.join(' ')}\` refused above.\n`)
+    exit(1)
+  }
+}
+exit(0)

package/dist/operations/makers/trial.ts

@@ -0,0 +1,520 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import { argv, exit, stderr, stdout } from 'node:process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { answer, asking, given, only, refuse, slug, wordsIn } from '../../core/asking.ts'
+import { generators, settling } from '../../core/chain.ts'
+import { descend, shapeFields } from '../../core/descend.ts'
+import { listBounds, withRow } from '../../core/rows.ts'
+import { findTree, inTree } from '../../core/tree.ts'
+
+import type { Call, Target } from '../../integrations/target.ts'
+
+import { PUBLIC_ROLE } from '../../core/actor.ts'
+
+import { declaredWords, undeclared } from '../access.ts'
+import type { Operation } from '../operations.ts'
+import { operations, types } from '../generators/seed.ts'
+import type { Scenario } from '../generators/trial.ts'
+
+const TREE = findTree()
+
+const SCENARIOS = 'SCENARIOS'
+
+import { quoted } from '../../core/rows.ts'
+
+async function sheet<T>(file: string, list: string): Promise<readonly T[]> {
+  const at = inTree(TREE, file)
+  if (!existsSync(at)) return []
+  try {
+    const held = (await import(pathToFileURL(at).href)) as Record<string, readonly T[] | undefined>
+    return held[list] ?? []
+  } catch {
+    return []
+  }
+}
+
+const pass = descend()
+const known = types(pass)
+
+interface Held {
+  readonly id: string
+  readonly describes: string
+  readonly requires: readonly string[]
+  readonly takes: string
+  readonly body: string
+}
+
+const declared: readonly Held[] = [...operations(pass, known)]
+  .map(([id, one]): Held | undefined => {
+    const takes = one.takes[0]?.at
+    if (takes === undefined || one.body === undefined) return undefined
+    return {
+      id,
+      describes: pass.stated.get(id)?.describes ?? '',
+      requires: one.requires,
+      takes,
+      body: one.body,
+    }
+  })
+  .filter((one): one is Held => one !== undefined)
+  .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+
+if (declared.length === 0) {
+  refuse('this app declares no compiled operation, so there is nothing to run. Make one with `thread create operation`.')
+}
+
+async function scenarios(takes: string): Promise<readonly Scenario[]> {
+  const at = resolve(TREE.at, takes)
+  if (!existsSync(at)) return []
+  try {
+    const held = (await import(pathToFileURL(at).href)) as { readonly SCENARIOS?: readonly Scenario[] }
+    return held.SCENARIOS ?? []
+  } catch {
+    return []
+  }
+}
+
+const already = new Map<string, readonly Scenario[]>()
+for (const one of declared) already.set(one.id, await scenarios(one.takes))
+
+const listing = [
+  `${String(declared.length)} operation(s):`,
+  ...declared.flatMap((one) => {
+    const mine = already.get(one.id) ?? []
+    return [
+      `  ${one.id} — ${one.describes}`,
+      `      requires ${one.requires.join(', ') || 'nothing'}`,
+      `      ${mine.length === 0 ? 'no scenario yet — nothing has ever run it' : `tried with ${mine.map((each) => each.id).join(', ')}`}`,
+    ]
+  }),
+].join('\n')
+
+interface Declaring {
+  readonly id: string
+  readonly holds: readonly { readonly id: string; readonly options?: readonly string[] }[]
+  readonly rows?: readonly Record<string, unknown>[]
+  readonly must?: readonly { readonly unique?: readonly string[] }[]
+  readonly actor?: { readonly roles: string; readonly entitlements?: string }
+}
+
+const entities = await sheet<Declaring>('entities.ts', 'ENTITIES')
+
+const keyIn = (one: Declaring): string | undefined =>
+  (one.must ?? []).flatMap((each) => (each.unique?.length === 1 ? [each.unique[0] as string] : []))[0]
+
+const wordsFrom = (held: unknown): readonly string[] => {
+  if (typeof held === 'string') return [held]
+  if (Array.isArray(held)) return held.filter((each): each is string => typeof each === 'string')
+  return []
+}
+
+interface Caller {
+  readonly id: string
+  readonly entity: string
+  readonly roles: readonly string[]
+  readonly entitlements: readonly string[]
+}
+
+const casting: readonly Caller[] = entities.flatMap((one) => {
+  const said = one.actor
+  const key = keyIn(one)
+  if (said === undefined || key === undefined) return []
+  return (one.rows ?? []).flatMap((row): readonly Caller[] => {
+    const named = row[key]
+    if (typeof named !== 'string') return []
+    return [
+      {
+        id: named,
+        entity: one.id,
+        roles: wordsFrom(row[said.roles]),
+        entitlements: said.entitlements === undefined ? [] : wordsFrom(row[said.entitlements]),
+      },
+    ]
+  })
+})
+
+const callers: readonly string[] = casting.map(
+  (one) =>
+    `  ${one.id} — a ${one.entity}, ${one.roles.join(' and ') || 'holding no role'}` +
+    `${one.entitlements.length === 0 ? '' : `, entitled to ${one.entitlements.join(' and ')}`}`,
+)
+
+interface Seeded {
+  readonly id: string
+  readonly entity: string
+  readonly row: Record<string, unknown>
+}
+
+const seedable: readonly Seeded[] = entities.flatMap((one) => {
+  const key = keyIn(one)
+  if (key === undefined) return []
+  return (one.rows ?? []).flatMap((row): readonly Seeded[] => {
+    const named = row[key]
+    return typeof named === 'string' ? [{ id: named, entity: one.id, row }] : []
+  })
+})
+
+const words = wordsIn([])
+
+stdout.write(`${listing}\n`)
+
+const SAYS = new Map<string, string>([
+  ['id', 'what to call this scenario'],
+  ['describes', 'what this scenario is, in one sentence somebody who has not seen it could act on'],
+  ['input', 'the input to run the operation with, as JSON — blank for {}'],
+  ['actor', 'who is running it — name a declared row of an entity that says who its callers are'],
+  ['rows', 'rows this starts from — name declared rows, comma separated, blank for an empty store'],
+  ['answers', 'what each declared call answers with — a call nothing answers gets a 404'],
+])
+
+const SCENARIO = fileURLToPath(new URL('../generators/trial.ts', import.meta.url))
+
+const SHAPE = shapeFields('Scenario', relative(TREE.at, SCENARIO).split('\\').join('/'))
+
+if (SHAPE.length === 0) {
+  refuse(
+    'the shape of a scenario could not be read, so what this command may ask for is unknown. Asking anyway ' +
+      'would write a row against a shape nothing checked — which is how a scenario ends up stating fields no ' +
+      'trial reads, and fields the runner reads that nothing ever wrote.',
+  )
+}
+
+const ASKS: readonly { readonly key: string; readonly says: string }[] = SHAPE.filter((one) =>
+  SAYS.has(one.name),
+).map((one) => ({ key: one.name, says: SAYS.get(one.name) ?? '' }))
+
+const UNASKED: readonly string[] = SHAPE.filter((one) => !SAYS.has(one.name)).map((one) => one.name)
+
+const TAKES: readonly string[] = ASKS.map((one) => one.key)
+
+const ASKED: readonly string[] = ASKS.map((one) => `  ${`${one.key}:`.padEnd(16)}${one.says}`)
+
+const method = (): string =>
+  [
+    '',
+    'what this runs:',
+    '',
+    '  thread run trial <operation>',
+    '',
+    'it takes, as a flag on one command:',
+    '',
+    `  thread run trial <operation> --<answer> <value> ... `,
+    '',
+    'That form needs no terminal, which is what makes it the one that always works. One answer to a',
+    'line on stdin does the same, and so does a file of them named by `--answers <path>`.',
+    '',
+    'the answers:',
+    '',
+    ...ASKED,
+    '',
+    'It asks for the input to try the operation with, checks it against that operation\'s own schema',
+    'before writing anything, adds the scenario to the file the operation already takes, and then runs',
+    '`thread trials` — which hands the compiled function to this app\'s own dispatch and records',
+    'everything the run did.',
+    '',
+    'DO NOT INVENT A CALLER. `actor` names a row this app already declares, and the roles and',
+    'entitlements that row holds are read off it. There is no field here for typing a role, because a',
+    'role is one of the options on the column an entity names as saying what its callers may do — the',
+    'app declares the closed set and this command holds you to it. Naming somebody who is not declared',
+    'is refused, and the refusal lists who IS. Blank leaves the scenario with no actor at all, which is',
+    'the right answer for an operation anybody may run, and the wrong one for an operation with a grant.',
+    '',
+    'Same for `rows`. Name rows the entities already declare. A store put into a state nobody declared',
+    'is a trial proving something about data that does not exist anywhere else in this app.',
+    '',
+    ...(callers.length === 0
+      ? [
+          'This app declares no entity that says who its callers are, so there is nobody to name and every',
+          'scenario here runs anonymous. An entity says so by naming the column its roles come from.',
+          '',
+        ]
+      : ['who this app declares as callers:', '', ...callers, '']),
+    'An operation that reaches a declared target is asked one more thing: what each of its calls',
+    'answers with. That is the only part of an outward call nothing can derive — the verb, the path,',
+    'the address and the credential all come off rows. A call nothing answers gets a 404, which is a',
+    'real answer about an operation that did not handle one.',
+    '',
+    'Running it again with the same operation adds another scenario rather than replacing one. A',
+    'recording is evidence, and evidence is not overwritten because somebody ran the command twice.',
+    ...(UNASKED.length === 0
+      ? []
+      : [
+          '',
+          `A scenario also states ${UNASKED.join(', ')}, and this command cannot write ${UNASKED.length === 1 ? 'it' : 'them'}.`,
+          'The trial runner reads what is there. Nothing here can put it there, so no scenario this command',
+          'writes will ever carry one — said out loud because a field nobody can reach reads as a field',
+          'nobody needs, and that is how four of them sat unwritable without anyone noticing.',
+        ]),
+  ].join('\n')
+
+const which = words[0]
+
+if (which === undefined) {
+  stdout.write(`${method()}\n`)
+  exit(1)
+}
+
+const one = declared.find((each) => each.id === which)
+if (one === undefined) {
+  refuse(`\`${which}\` is not a compiled operation of this app. What is here is ${declared.map((each) => each.id).join(', ')}`)
+}
+
+const from = resolve(TREE.at, one.takes)
+if (!existsSync(from)) {
+  refuse(`\`${one.id}\` takes ${one.takes} and that file is not there. Run \`thread seed\`.`)
+}
+
+const taking = (await import(pathToFileURL(from).href)) as {
+  readonly input?: { readonly safeParse: (value: unknown) => { readonly success: boolean; readonly error?: unknown } }
+}
+const schema = taking.input
+if (schema === undefined) {
+  refuse(`${one.takes} exports no \`input\`, so nothing states what \`${one.id}\` takes. Run \`thread seed\`.`)
+}
+
+const targets = await sheet<Target>('targets.ts', 'TARGETS')
+const calls = await sheet<Call>('targets.ts', 'CALLS')
+const reachable = targets
+  .filter((each) => one.requires.includes(each.id))
+  .flatMap((each) => calls.filter((call) => call.of === each.id && each.takes.includes(call.id)))
+
+const piped = given()
+only(piped, TAKES, 'a trial')
+const { ask, shut } = asking(piped)
+
+const mine = already.get(one.id) ?? []
+const suggested = `s${String(mine.length + 1)}`
+const named = slug(piped.length > 0 ? (answer(piped, 'id') ?? suggested) : (await ask('id', `what to call this scenario (blank for "${suggested}"): `)) || suggested)
+if (mine.some((each) => each.id === named)) {
+  shut()
+  refuse(`\`${one.id}\` already has a scenario called \`${named}\`, and a trial is named after the one it ran`)
+}
+
+const meaning = (
+  piped.length > 0
+    ? (answer(piped, 'describes') ?? '')
+    : await ask('describes', 'what this scenario is, in one sentence: ')
+).trim()
+
+if (meaning === '') {
+  shut()
+  refuse(
+    `a scenario states what it is, and \`${named}\` is only a name. Every declared thing here carries a ` +
+      '`describes`, because the word on its own tells the next person nothing about which scenario they are ' +
+      'looking at or why it was worth recording. Say what world this run is given and what it is meant to show.',
+  )
+}
+
+const typed = (
+  piped.length > 0
+    ? (answer(piped, 'input') ?? '')
+    : await ask('input', `the input to run ${one.id} with, as JSON (blank for {}): `)
+).trim()
+
+let value: unknown
+try {
+  value = typed === '' ? {} : JSON.parse(typed)
+} catch (thrown) {
+  shut()
+  refuse(`that is not JSON: ${thrown instanceof Error ? thrown.message : String(thrown)}. Nothing was written.`)
+}
+
+const held = schema.safeParse(value)
+if (!held.success) {
+  shut()
+  refuse(
+    `\`${one.id}\` would refuse that input, so a trial of it would record a refusal and prove nothing: ` +
+      `${JSON.stringify(held.error)}. Nothing was written.`,
+  )
+}
+
+const listed = (said: string): readonly string[] =>
+  said
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '')
+
+const running = (
+  piped.length > 0
+    ? (answer(piped, 'actor') ?? '')
+    : await ask('actor', 'who is running it — name a declared row (blank for nobody, which is anonymous): ')
+).trim()
+
+if (running !== '' && casting.length === 0) {
+  shut()
+  refuse(
+    `this app declares nobody to run \`${one.id}\` as. An entity says who its callers are by naming the ` +
+      'column its roles come from, and then declaring rows on it. Until one does, every scenario here runs ' +
+      'anonymous, and naming somebody would be inventing them.',
+  )
+}
+
+const played = casting.find((each) => each.id === running)
+
+if (running !== '' && played === undefined) {
+  shut()
+  refuse(
+    `this app declares no caller called \`${running}\` — it declares ` +
+      `${casting.map((each) => `\`${each.id}\``).join(', ')}. A caller is a row an entity declares, not a name ` +
+      'to type here: the roles it holds are read off that row, so somebody invented at this prompt would carry ' +
+      'roles this app never granted and the trial would prove access that does not exist.',
+  )
+}
+
+if (played !== undefined) {
+  for (const which of ['roles', 'entitlements'] as const) {
+    const wrong = undeclared(played[which].join(','), declaredWords(entities, which, PUBLIC_ROLE), which)
+    if (wrong !== undefined) {
+      shut()
+      refuse(
+        `\`${played.id}\` is a declared row of \`${played.entity}\` and ${wrong}. The row holds a word its own ` +
+          'column does not offer, so running as it would prove access against a role this app never declared. ' +
+          'Fix the row, not the scenario. Nothing was written.',
+      )
+    }
+  }
+}
+
+const actor =
+  played === undefined
+    ? undefined
+    : { id: played.id, roles: [...played.roles], entitlements: [...played.entitlements] }
+
+const seeded = (
+  piped.length > 0
+    ? (answer(piped, 'rows') ?? '')
+    : await ask('rows', 'rows this starts from — declared rows, comma separated, blank for an empty store: ')
+).trim()
+
+const wanted = listed(seeded)
+
+const stray = wanted.filter((each) => !seedable.some((one) => one.id === each))
+if (stray.length > 0) {
+  shut()
+  refuse(
+    `this app declares no row called ${stray.map((each) => `\`${each}\``).join(', ')} — ` +
+      (seedable.length === 0
+        ? 'it declares none at all. A store starts from rows the entities themselves declare, so that what a ' +
+          'trial proves is about data this app really has. Declare them with `thread create entity edit`.'
+        : `it declares ${seedable.map((one) => `\`${one.id}\``).join(', ')}. Nothing was written.`),
+  )
+}
+
+const starting: readonly { readonly entity: string; readonly row: Record<string, unknown> }[] = wanted.flatMap(
+  (each) => {
+    const found = seedable.find((one) => one.id === each)
+    return found === undefined ? [] : [{ entity: found.entity, row: found.row }]
+  },
+)
+
+const answers: Record<string, { status: number; body?: string }> = {}
+if (piped.length > 0) {
+  const said = (answer(piped, 'answers') ?? '').trim()
+  if (said !== '') {
+    try {
+      Object.assign(answers, JSON.parse(said) as Record<string, { status: number; body?: string }>)
+    } catch (thrown) {
+      shut()
+      refuse(`\`answers\` is not JSON: ${thrown instanceof Error ? thrown.message : String(thrown)}. Nothing was written.`)
+    }
+  }
+} else if (reachable.length > 0) {
+  stdout.write(`\n${one.id} can make ${String(reachable.length)} declared call(s). What does each answer with?\n`)
+  for (const call of reachable) {
+    const key = `${call.method} ${call.path}`
+    const status = (await ask('status', `  ${key} — status (blank to leave it unanswered, which is a 404): `)).trim()
+    if (status === '') continue
+    const code = Number(status)
+    if (!Number.isInteger(code) || code < 100 || code > 599) {
+      shut()
+      refuse(`"${status}" is not an HTTP status. Nothing was written.`)
+    }
+    const body = (await ask('body', '  body, as JSON or blank: ')).trim()
+    answers[key] = body === '' ? { status: code } : { status: code, body }
+  }
+}
+shut()
+
+const row = [
+  '  {',
+  `    id: ${quoted(named)},`,
+  `    describes: ${quoted(meaning)},`,
+  `    input: ${JSON.stringify(value)},`,
+  ...(actor === undefined ? [] : [`    actor: ${JSON.stringify(actor)},`]),
+  ...(starting.length === 0 ? [] : [`    rows: ${JSON.stringify(starting)},`]),
+  ...(Object.keys(answers).length === 0 ? [] : [`    answers: ${JSON.stringify(answers)},`]),
+  '  },',
+].join('\n')
+
+const SEEDED = 'export const input = z.unknown()'
+
+const NAMEABLE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+function stated(value: unknown): string | undefined {
+  if (typeof value === 'string') return 'z.string()'
+  if (typeof value === 'number') return 'z.number()'
+  if (typeof value === 'boolean') return 'z.boolean()'
+  if (value === null) return 'z.null()'
+  if (Array.isArray(value)) {
+    const first: unknown = value[0]
+    const of = first === undefined ? undefined : stated(first)
+    return of === undefined ? undefined : `z.array(${of})`
+  }
+  if (typeof value !== 'object') return undefined
+  const parts: string[] = []
+  for (const [key, held] of Object.entries(value)) {
+    const one = stated(held)
+    if (one === undefined) return undefined
+    parts.push(`${NAMEABLE.test(key) ? key : quoted(key)}: ${one}`)
+  }
+  return `z.object({ ${parts.join(', ')} })`
+}
+
+function stating(text: string, value: unknown): string {
+  const schema = stated(value)
+  if (schema === undefined || !text.includes(SEEDED)) return text
+  return text.replace(SEEDED, `export const input = ${schema}`)
+}
+
+let text = readFileSync(from, 'utf8')
+const bounds = listBounds(text, SCENARIOS)
+if (bounds === undefined) {
+  text = `${text.trimEnd()}\n\nexport const ${SCENARIOS}: readonly Scenario[] = [\n${row}\n]\n`
+  text = text.replace(
+    "import { z } from 'zod'\n",
+    "import { z } from 'zod'\n\nimport type { Scenario } from '../generators/trial.ts'\n",
+  )
+  text = stating(text, value)
+} else {
+  text = withRow(text, bounds, row)
+}
+writeFileSync(from, text, 'utf8')
+
+stdout.write(`\ntrial: wrote scenario \`${named}\` into ${one.takes}.\n`)
+
+const ran = spawnSync('npx', ['thread', 'trials'], { cwd: TREE.at, encoding: 'utf8' })
+stdout.write(`${`${ran.stdout ?? ''}${ran.stderr ?? ''}`.trim()}\n`)
+if (ran.status !== 0) {
+  stdout.write('trial: the recording was refused above. The scenario is written and stands.\n')
+  exit(1)
+}
+
+const checked = spawnSync('npx', ['thread', 'trials', '--check'], { cwd: TREE.at, encoding: 'utf8' })
+stdout.write(`${`${checked.stdout ?? ''}${checked.stderr ?? ''}`.trim()}\n`)
+if (checked.status !== 0) exit(1)
+
+const settled = settling(TREE.at, await generators(TREE), ['thread trials', 'thread run trial'])
+for (const one of settled.ran) stdout.write(`${one}\n`)
+
+if (settled.unsettled.length > 0) {
+  stderr.write(
+    `trial: the scenario is written and the run is recorded, and ${settled.unsettled.join(', ')} would not settle ` +
+      `after ${String(settled.rounds)} round(s). Run it yourself and read what it says.\n`,
+  )
+  exit(1)
+}
+
+exit(0)