@prestack/thread 0.1.21 → 0.1.22

package/dist/operations/generators/capability.ts

@@ -1,1054 +0,0 @@
-import ts from 'typescript'
-
-import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from '../../integrations/disk.ts'
-import { dirname, resolve } from 'node:path'
-import { argv, stdout } from 'node:process'
-import { pathToFileURL } from 'node:url'
-
-import { ROOT, TREE, descend, forget } from '../../core/descend.ts'
-import { exit, invoked } from '../../core/invoked.ts'
-import { named as packageOf } from '../../core/scope.ts'
-import { PREFIXES } from '../../core/thread.ts'
-
-import { secrecyOf, type Secret } from '../../integrations/secret.ts'
-import { reachOf, servesBrowser, targetOf, type Call, type Target, type Webhook } from '../../integrations/target.ts'
-
-import {
-  CAPABILITIES_AT,
-  CLIENT_AT,
-  MCP_AT,
-  OPENAPI_AT,
-  REACHING_AT,
-  ACTOR_AT,
-  DEFAULTS_AT,
-  DISPATCHING_AT,
-  CHECKED_AT,
-  inboundAt,
-  isSurface,
-  ROUTE,
-  routeAt,
-  SURFACES,
-  switched,
-  UNSTATED,
-  type Capability,
-  type Surface,
-} from '../capabilities.ts'
-import { ANONYMOUS, ENVIRONMENT } from '../../core/actor.ts'
-import { DISPATCH_AT } from '../dispatch.ts'
-import { STREAMED, TOLD } from '../../integrations/https.ts'
-import { holdsRow, listBounds, marked, nestedBounds, rowsIn, unread, valuesIn, withField, withRow, withTopField, withoutRow } from '../../core/rows.ts'
-import { said } from '../attach.ts'
-import { MEMBERS_LIST } from '../operations.ts'
-import { beside, operations, quoted, runtime, types } from './seed.ts'
-
-interface Written {
-  readonly at: string
-  readonly text: string
-}
-
-const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
-
-const listedIn = (held: ts.Expression | undefined): readonly string[] =>
-  held !== undefined && ts.isArrayLiteralExpression(held)
-    ? held.elements.filter((one) => ts.isStringLiteral(one)).map((one) => (one as ts.StringLiteral).text)
-    : []
-
-const trueIn = (held: ts.Expression | undefined): boolean => held !== undefined && held.kind === ts.SyntaxKind.TrueKeyword
-
-function stable(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(stable)
-  if (typeof value === 'object' && value !== null) {
-    const found: Record<string, unknown> = {}
-    for (const key of Object.keys(value as Record<string, unknown>).sort(compare)) {
-      found[key] = stable((value as Record<string, unknown>)[key])
-    }
-    return found
-  }
-  return value === undefined ? null : value
-}
-
-const printed = (value: unknown): string => `${JSON.stringify(stable(value), null, 2)}\n`
-
-function verbOf(id: string): 'GET' | 'POST' | undefined {
-  if (id.startsWith(PREFIXES.view)) return 'GET'
-  if (id.startsWith(PREFIXES.workflow) || id.startsWith(PREFIXES.agent)) return 'POST'
-  return undefined
-}
-
-async function schemaOf(at: string): Promise<unknown | string> {
-  const from = resolve(ROOT, at)
-  if (!existsSync(from)) return `${at} is not there, so nothing states what this operation takes`
-
-  const held = (await import(pathToFileURL(from).href)) as { readonly input?: unknown }
-  const input = held.input
-  if (input === undefined) return `${at} exports no \`input\`, so nothing states what this operation takes`
-
-  const zod = (await import('zod')) as { readonly toJSONSchema?: (one: unknown) => unknown }
-  if (zod.toJSONSchema === undefined) {
-    return 'this app\'s zod states no `toJSONSchema`, so an input schema cannot be written from it'
-  }
-  try {
-    return zod.toJSONSchema(input)
-  } catch (thrown) {
-    return `${at} states an input that cannot be written as a schema: ${thrown instanceof Error ? thrown.message : String(thrown)}`
-  }
-}
-
-function sheet<T>(file: string, list: string): readonly T[] {
-  const at = resolve(ROOT, `_threads/${file}`)
-  if (!existsSync(at)) return []
-  const text = readFileSync(at, 'utf8')
-  if (unread(text).includes(list)) {
-    throw new Error(
-      `_threads/${file} works out \`${list}\` when the file runs instead of writing it down, and this command reads sheets ` +
-        'without running them. Write each row of it out in full',
-    )
-  }
-  return (valuesIn(text) as Record<string, readonly T[] | undefined>)[list] ?? []
-}
-
-function browsing(requires: readonly string[], targets: readonly Target[], secrets: readonly Secret[]): boolean {
-  for (const word of requires) {
-    const target = targets.find((one) => one.id === word)
-    if (target === undefined) continue
-    if (servesBrowser(target, secrets) !== true) return false
-  }
-  return true
-}
-
-export interface Surfaced {
-  readonly live: readonly Surface[]
-  readonly stated: boolean
-  readonly wrong: readonly string[]
-}
-
-export function defaulted(): Surfaced | undefined {
-  const at = resolve(ROOT, DEFAULTS_AT)
-  if (!existsSync(at)) return undefined
-  const row = Object.values(valuesIn(readFileSync(at, 'utf8'))).find(
-    (one): one is { readonly live?: unknown } =>
-      typeof one === 'object' && one !== null && (one as { readonly at?: unknown }).at === DEFAULTS_AT,
-  )
-  if (row === undefined || !Array.isArray(row.live)) return { live: UNSTATED, stated: false, wrong: [] }
-  const given = row.live.map(String)
-  return { live: SURFACES.filter((each) => given.includes(each)), stated: true, wrong: given.filter((each) => !isSurface(each)) }
-}
-
-export async function derive({ schemas = true }: { readonly schemas?: boolean } = {}): Promise<{
-  readonly found: readonly Capability[]
-  readonly refusals: readonly string[]
-  readonly live: readonly Surface[]
-}> {
-  const pass = descend()
-  const known = types(pass)
-  const refusals: string[] = []
-  const found: Capability[] = []
-
-  const targets = sheet<Target>('targets.ts', 'TARGETS')
-  const secrets = sheet<Secret>('secrets.ts', 'SECRETS')
-
-  for (const one of targets) {
-    if (reachOf(one.id) !== 'sdk' || (one.declares ?? []).length > 0) continue
-    refusals.push(
-      `\`${one.id}\` calls a package inside this app, and its row declares no file that does the calling. That file is the one ` +
-        'place the package is imported, and it exports `calls`, holding the function each call names as its path. Give the row ' +
-        `one, and the file with it, with \`thread edit ${one.id} --declares <id> --at <path> --describes <sentence> --body <text>\``,
-    )
-  }
-
-  const tree = defaulted()
-  if (tree === undefined) {
-    refusals.push(
-      `${DEFAULTS_AT} is not here, so nothing says which surfaces an operation answers on, and working it out anyway would ` +
-        `take away every route this app has. \`thread attach ${packageOf('operations')}\` writes it`,
-    )
-  }
-  for (const one of tree?.wrong ?? []) {
-    refusals.push(
-      `${DEFAULTS_AT} says \`${one}\` is live, and there is no such surface. There are ${String(SURFACES.length)}: ` +
-        `${SURFACES.join(', ')}. \`thread create capability edit defaults\` rewrites it`,
-    )
-  }
-
-  for (const [id, one] of [...operations(pass, known)].sort((a, b) => compare(a[0], b[0]))) {
-    const stated = pass.stated.get(id)
-    const declared = {
-      webhooks: listedIn(stated?.fields.get('webhooks')),
-      signed: trueIn(stated?.fields.get('signed')),
-    }
-    const describes = stated?.describes
-    if (describes === undefined) {
-      refusals.push(`\`${id}\` states no \`describes\`, and a caller told nothing about an operation cannot choose it`)
-      continue
-    }
-
-    const method = verbOf(id)
-    if (method === undefined) {
-      refusals.push(
-        `\`${id}\` wears none of the prefixes an operation may wear (${Object.values(PREFIXES).join(', ')}), so there is no verb to give it`,
-      )
-      continue
-    }
-
-    const takes = one.takes[0]?.at
-    if (takes === undefined) {
-      refusals.push(`\`${id}\` names nothing it takes, so nothing states its input`)
-      continue
-    }
-
-    const schema = schemas ? await schemaOf(takes) : undefined
-    if (typeof schema === 'string') {
-      refusals.push(`\`${id}\`: ${schema}`)
-      continue
-    }
-
-    const off = listedIn(stated?.fields.get('off'))
-    const stray = off.filter((each) => !isSurface(each))
-    if (stray.length > 0) {
-      refusals.push(
-        `\`${id}\` turns off ${stray.map((each) => `\`${each}\``).join(', ')}, and there is no such surface. There are ` +
-          `${String(SURFACES.length)}: ${SURFACES.join(', ')}. \`thread create capability edit ${id}\` rewrites it`,
-      )
-      continue
-    }
-
-    const live = (tree?.live ?? UNSTATED).filter((each) => !off.includes(each))
-
-    found.push({
-      operation: id,
-      describes,
-      requires: [...one.requires].sort(compare),
-      nodes: one.nodes.map((each) => each.id ?? '').filter((each) => each !== ''),
-      input: schema,
-      live: [...live].sort(compare) as readonly Surface[],
-      webhooks: [...declared.webhooks].sort(compare),
-      signed: declared.signed,
-      browsable: browsing(one.requires, targets, secrets),
-      mcp: { name: id, description: describes, inputSchema: schema },
-      cli: { invocation: `${id} --input '<json>'`, describes },
-      api: { method, path: `/operations/${id}` },
-    })
-  }
-
-  for (const one of sheet<Webhook>('targets.ts', 'WEBHOOKS')) {
-    const runs = found.find((each) => each.operation === one.invokes)
-    if (runs === undefined) {
-      refusals.push(
-        `\`${one.id}\` invokes \`${one.invokes}\`, and this app declares no operation by that name. A webhook is a way in ` +
-          `to something already declared, so declare that operation or point this webhook at one that exists`,
-      )
-      continue
-    }
-    const route = (one.derives ?? []).some((each) => each.at === inboundAt(one.id) && each.by !== undefined && each.runs !== undefined)
-    if (!route) {
-      refusals.push(
-        `\`${one.id}\` derives no route. A webhook is an address anybody may post to, so the file that answers it has to be a row ` +
-          `this tree declares: state a \`derives\` on this webhook naming ${inboundAt(one.id)}, with \`by\` and \`runs\` set to ` +
-          '`thread capabilities` and `thread capabilities --check`, so what is written there is checked against what writes it',
-      )
-    }
-    if (!runs.webhooks.includes(one.id)) {
-      refusals.push(
-        `\`${one.id}\` invokes \`${one.invokes}\`, and that operation does not name it back. An operation is run from outside ` +
-          `only by a webhook it named, so add ${one.id} to \`webhooks\` on that operation's row in ${TREE}operations.ts, or point this webhook elsewhere`,
-      )
-    }
-    if (runs.signed && (one.arrives === undefined || (one.requires ?? []).length === 0)) {
-      refusals.push(
-        `\`${one.invokes}\` says it will only be run by a signed webhook, and \`${one.id}\` carries no signature to check. ` +
-          `Give this webhook the header its signature arrives on and the secret it is signed with`,
-      )
-    }
-    if (!runs.live.includes('webhook')) {
-      refusals.push(
-        `\`${one.id}\` invokes \`${one.invokes}\`, and that operation does not answer on the webhook surface. Both halves have to ` +
-          `agree before anything outside can run it: webhook has to be live in ${DEFAULTS_AT}, which \`thread create capability edit defaults\` changes, and not in the \`off\` on its row, which \`thread create capability edit ${one.invokes}\` changes`,
-      )
-    }
-    const holds = (one.requires ?? []).filter((each) => secrecyOf(each) !== undefined)
-    if (one.arrives !== undefined && holds.length === 0) {
-      refusals.push(
-        `\`${one.id}\` says a signature arrives on \`${one.arrives}\` and requires no secret to check it against, so every ` +
-          `request would be taken on trust. Name the secret it is signed with, or take \`arrives\` off the row`,
-      )
-    }
-    if (one.arrives === undefined && holds.length > 0) {
-      refusals.push(
-        `\`${one.id}\` requires ${holds.join(', ')} and says no header a signature arrives on, so nothing would ever be checked ` +
-          `against it. Say which header carries the signature, or take the secret off the row`,
-      )
-    }
-  }
-
-  return { found, refusals, live: tree?.live ?? UNSTATED }
-}
-
-function named(): { readonly title: string; readonly version: string } {
-  try {
-    const held = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8')) as {
-      readonly name?: unknown
-      readonly version?: unknown
-    }
-    return {
-      title: typeof held.name === 'string' ? held.name : 'this app',
-      version: typeof held.version === 'string' ? held.version : '0.0.0',
-    }
-  } catch {
-    return { title: 'this app', version: '0.0.0' }
-  }
-}
-
-function openapi(found: readonly Capability[]): unknown {
-  const paths: Record<string, unknown> = {}
-  for (const one of found) {
-    if (!one.live.includes('api')) continue
-    const method = one.api.method.toLowerCase()
-    const responses = {
-      '200': {
-        description: 'the operation ran',
-        content: { 'application/json': { schema: { type: 'object', properties: { ok: { const: true }, value: {} }, required: ['ok'] } } },
-      },
-      '400': {
-        description: 'dispatch refused it — the code says which gate',
-        content: {
-          'application/json': {
-            schema: {
-              type: 'object',
-              properties: {
-                ok: { const: false },
-                code: { enum: ['denied', 'invalid', 'rate_limited', 'feature_denied', 'quota_exceeded', 'error'] },
-                error: { type: 'string' },
-                because: { type: 'string' },
-              },
-              required: ['ok', 'code', 'error'],
-            },
-          },
-        },
-      },
-    }
-    paths[one.api.path] = {
-      [method]: {
-        operationId: one.operation,
-        summary: one.describes,
-        ...(one.api.method === 'GET'
-          ? { parameters: [{ name: 'input', in: 'query', required: true, content: { 'application/json': { schema: one.input } } }] }
-          : { requestBody: { required: true, content: { 'application/json': { schema: one.input } } } }),
-        responses,
-      },
-    }
-  }
-  const who = named()
-  return {
-    openapi: '3.1.0',
-    info: { title: who.title, version: who.version, description: 'Every operation this app declares that is live on its API surface.' },
-    paths,
-  }
-}
-
-const mcp = (found: readonly Capability[]): unknown => ({
-  tools: found.filter((one) => one.live.includes('mcp')).map((one) => one.mcp),
-})
-
-const compiled = (operation: string): boolean => existsSync(resolve(ROOT, `operations/${operation}.ts`))
-
-function client(found: readonly Capability[]): string {
-  const rows = found
-    .filter(held)
-    .map((one) =>
-      [
-        '  {',
-        `    operation: ${JSON.stringify(one.operation)},`,
-        `    describes: ${JSON.stringify(one.describes)},`,
-        `    method: ${JSON.stringify(one.api.method)},`,
-        `    path: ${JSON.stringify(one.api.path)},`,
-        '  },',
-      ].join('\n'),
-    )
-
-  const near = found.filter((one) => one.browsable && compiled(one.operation))
-
-  const bound = near.flatMap((one) => [
-    'export async function ' + one.operation + 'Locally(input: unknown, actor: Actor): Promise<Result<unknown>> {',
-    `  const held = await dispatch(${one.operation}, input, actor, DECLARED, opening, counting)`,
-    '  return held',
-    '}',
-    '',
-  ])
-
-  return [
-    ...(near.length === 0
-      ? []
-      : [
-          `import type { Actor } from '${runtime(CLIENT_AT, '../../core/actor.ts')}'`,
-          `import type { Result } from '${runtime(CLIENT_AT, '../result.ts')}'`,
-          '',
-          "import { dispatch } from './_dispatch.ts'",
-          `import { counting, DECLARED, opening } from '${beside(CLIENT_AT, REACHING_AT)}'`,
-          ...near.map((one) => `import { operation as ${one.operation} } from './${one.operation}.ts'`),
-          '',
-        ]),
-    'export interface Reachable {',
-    '  readonly operation: string',
-    '  readonly describes: string',
-    "  readonly method: 'GET' | 'POST'",
-    '  readonly path: string',
-    '}',
-    '',
-    `export const CLIENT: readonly Reachable[] = [${rows.length === 0 ? '' : `\n${rows.join('\n')}\n`}]`,
-    '',
-    'export const reachable = (operation: string): Reachable | undefined =>',
-    '  CLIENT.find((one) => one.operation === operation)',
-    '',
-    ...bound,
-    '',
-  ].join('\n')
-}
-
-function route(one: Capability): string {
-  const at = routeAt(one.operation)
-  return [
-    `import { existsSync } from ${quoted(runtime(at, '../../integrations/disk.ts'))}`,
-    "import { join } from 'node:path'",
-    '',
-    'import { counting, DECLARED, opening } from ' + quoted(beside(at, REACHING_AT)),
-    'import { actor } from ' + quoted(beside(at, ACTOR_AT)),
-    '',
-    "import { dispatch } from '../../../operations/_dispatch.ts'",
-    `import { operation } from '../../../operations/${one.operation}.ts'`,
-    '',
-    'const STATUS: Record<string, number> = {',
-    '  denied: 403,',
-    '  invalid: 400,',
-    '  rate_limited: 429,',
-    '  feature_denied: 403,',
-    '  quota_exceeded: 429,',
-    '  error: 500,',
-    '}',
-    '',
-    "const PASSED = existsSync(join(process.cwd(), '.thread', 'gate.json'))",
-    '',
-    `export async function ${one.api.method}(request: Request): Promise<Response> {`,
-    '  if (!PASSED) {',
-    '    return Response.json(',
-    "      { ok: false, code: 'error', error: 'failed', because: 'this tree has no passing gate, so nothing in it may answer a request. Run `thread gate` — a gate that has never run is not a gate that passed' },",
-    '      { status: 500 },',
-    '    )',
-    '  }',
-    ...(one.api.method === 'GET'
-      ? ['  const input = Object.fromEntries(new URL(request.url).searchParams)']
-      : [
-          '  const input = await request.json().catch(() => undefined)',
-          "  if ((request.headers.get('accept') ?? '').includes(" + quoted(STREAMED) + ')) {',
-          '    const lines = new TransformStream<string, string>()',
-          '    const writing = lines.writable.getWriter()',
-          "    const sent = (said: unknown): void => { writing.write(JSON.stringify(said) + '\\n').catch(() => undefined) }",
-          '    void dispatch(operation, input, await actor(request), DECLARED, opening, counting, (said) => sent({ ' + TOLD + ': said })).then((held) => {',
-          '      sent(held)',
-          '      return writing.close()',
-          '    }).catch(() => undefined)',
-          '    return new Response(lines.readable.pipeThrough(new TextEncoderStream()), { headers: { ' + quoted('content-type') + ': ' + quoted(STREAMED) + ' } })',
-          '  }',
-        ]),
-    '  const held = await dispatch(operation, input, await actor(request), DECLARED, opening, counting)',
-    '  return Response.json(held, { status: held.ok ? 200 : (STATUS[held.code] ?? 500) })',
-    '}',
-    '',
-  ].join('\n')
-}
-
-function inbound(one: Webhook): string {
-  const at = inboundAt(one.id)
-  const secret = (one.requires ?? [])[0]
-  const signed = one.arrives !== undefined && secret !== undefined
-  const refuse = (why: string): string =>
-    "    return Response.json({ ok: false, code: " + quoted("denied") + ", error: " + quoted("not allowed") +
-    ", because: " + quoted(why) + " }, { status: 403 })"
-  return [
-    ...(signed ? ["import { createHmac, timingSafeEqual } from " + quoted("node:crypto")] : []),
-    "import { existsSync } from " + quoted(runtime(at, "../../integrations/disk.ts")),
-    "import { join } from " + quoted("node:path"),
-    "",
-    "import { counting, DECLARED, opening } from " + quoted(beside(at, REACHING_AT)),
-    "",
-    "import { dispatch } from " + quoted(beside(at, DISPATCH_AT)),
-    "import { operation } from " + quoted(beside(at, "operations/" + one.invokes + ".ts")),
-    "",
-    "const ARRIVING = " + JSON.stringify(ANONYMOUS),
-    "",
-    "const PASSED = existsSync(join(process.cwd(), " + quoted(".thread") + ", " + quoted("gate.json") + "))",
-    "",
-    "export async function POST(request: Request): Promise<Response> {",
-    "  if (!PASSED) {",
-    refuse("this tree has no passing gate, so nothing in it may answer a request. Run thread gate"),
-    "  }",
-    "  const raw = await request.text()",
-    ...(signed
-      ? [
-          "  const carried = request.headers.get(" + quoted(one.arrives as string) + ")",
-          "  if (carried === null) {",
-          refuse("this webhook is signed and the request carried nothing on " + String(one.arrives)),
-          "  }",
-          "  const held = await opening.resolve([" + quoted(secret as string) + "])",
-          "  const mine = Buffer.from(createHmac(" + quoted("sha256") + ", held[" + quoted(secret as string) +
-            "] ?? " + quoted("") + ").update(raw).digest(" + quoted("hex") + "))",
-          "  const said = Buffer.from(carried)",
-          "  if (said.length !== mine.length || !timingSafeEqual(said, mine)) {",
-          refuse("the signature on this request is not what " + String(secret) + " signs a body with"),
-          "  }",
-        ]
-      : []),
-    "  const input: unknown = JSON.parse(raw)",
-    "  const answer = await dispatch(operation, input, ARRIVING, DECLARED, opening, counting)",
-    "  return Response.json(answer, { status: answer.ok ? 200 : 500 })",
-    "}",
-    "",
-  ].join("\n")
-}
-
-function declaring(webhooks: readonly Webhook[]): readonly string[] {
-  const sheet = resolve(ROOT, TREE + 'targets.ts')
-  if (!existsSync(sheet)) return []
-  let text = readFileSync(sheet, 'utf8')
-  const wrote: string[] = []
-  for (const one of webhooks) {
-    const id = one.id + '_route'
-    const where = listBounds(text, 'WEBHOOKS')
-    if (where === undefined) break
-    const inside = nestedBounds(text, where, one.id, 'derives')
-    if (inside !== undefined && holdsRow(text, inside, id)) continue
-    const row = [
-      '        {',
-      "          id: " + quoted(id) + ",",
-      "          at: " + quoted(inboundAt(one.id)) + ",",
-      "          describes: " + quoted(
-        'The file that answers what ' + one.id + ' posts. It checks the signature before anything runs and then hands the body ' +
-          'to the same dispatch every other caller reaches, so an inbound event is refused or dispatched and never anything else.',
-      ) + ",",
-      '          version: 1,',
-      "          by: 'thread capabilities',",
-      "          runs: 'thread capabilities --check',",
-      '        },',
-    ].join('\n')
-    const next = inside === undefined
-      ? withField(text, where, one.id, 'derives', '[\n' + row + '\n      ]')
-      : withRow(text, inside, row)
-    if (next === undefined || next === text) continue
-    text = next
-    wrote.push(id)
-  }
-  if (wrote.length > 0) writeFileSync(sheet, text, 'utf8')
-  return wrote
-}
-
-const STORED = /export\s+const\s+store\b/
-
-const STORES_AT = 'src/stores'
-
-function kept(): readonly string[] {
-  const at = resolve(ROOT, STORES_AT)
-  if (!existsSync(at)) return []
-  return readdirSync(at)
-    .filter((one) => one.endsWith('.ts'))
-    .filter((one) => {
-      try {
-        return STORED.test(readFileSync(resolve(at, one), 'utf8'))
-      } catch {
-        return false
-      }
-    })
-    .sort()
-    .map((one) => `${STORES_AT}/${one}`)
-}
-
-const ENTITIES_AT = `${TREE}entities.ts`
-
-const OPERATIONS_AT = `${TREE}operations.ts`
-
-const VAULT_AT = `src/vault.${'ts'}`
-
-const served = (one: Capability): boolean => one.live.includes('api') && compiled(one.operation)
-
-const held = (one: Capability): boolean => one.browsable && one.live.includes('api')
-
-function dispatching(found: readonly Capability[]): string {
-
-  const reachable = found.filter(served)
-  const checked = quoted(beside(DISPATCHING_AT, CHECKED_AT))
-  return [
-    'import type {} from ' + checked,
-    'import type { Calling } from ' + quoted(runtime(DISPATCHING_AT, '../../integrations/target.ts')),
-    '',
-    'declare module ' + checked + ' {',
-    ...(reachable.length === 0
-      ? ['  interface Dispatching {}']
-      : ['  interface Dispatching {', ...reachable.map((one) => `    readonly ${one.operation}: true`), '  }']),
-    '}',
-    '',
-    ...(reachable.length === 0
-      ? []
-      : [
-          'interface Reaches {',
-          '  readonly operation: string',
-          "  readonly method: 'GET' | 'POST'",
-          '  readonly path: string',
-          '}',
-          '',
-          'async function sent(one: Reaches, input?: unknown): Promise<unknown> {',
-          '  const answered = await fetch(one.path, {',
-          '    method: one.method,',
-          "    headers: { 'content-type': 'application/json' },",
-          "    ...(one.method === 'GET' ? {} : { body: JSON.stringify(input ?? {}) }),",
-          '  })',
-          '  return await answered.json()',
-          '}',
-          '',
-        ]),
-    `export const calls: Calling<${reachable.length === 0 ? 'never' : reachable.map((one) => quoted(one.operation)).join(' | ')}> = {${
-      reachable.length === 0
-        ? ''
-        : `\n${reachable
-            .map(
-              (one) =>
-                `  ${one.operation}: (given) => sent({ operation: ${JSON.stringify(one.operation)}, method: ${JSON.stringify(one.api?.method)}, path: ${JSON.stringify(one.api?.path)} }, given),`,
-            )
-            .join('\n')}\n`
-    }}`,
-    '',
-    'const CALLS: Readonly<Record<string, ((given?: unknown) => Promise<unknown>) | undefined>> = calls',
-    '',
-    'export async function dispatchTo(operation: string, input?: Readonly<Record<string, unknown>>): Promise<unknown> {',
-    '  const one = CALLS[operation]',
-    '  if (one === undefined) {',
-    '    throw new Error(',
-    "      `thread: nothing declares an operation called ${operation}, so there is nowhere to send this. ` +",
-    "        `This app reaches: ${Object.keys(CALLS).join(', ') || '(nothing)'}`,",
-    '    )',
-    '  }',
-    '  return await one(input)',
-    '}',
-    '',
-  ].join('\n')
-}
-
-export function reaching(
-  targets: readonly Target[],
-  calls: readonly Call[],
-  stores: readonly string[],
-  vaulted: boolean,
-  carried: boolean,
-): string {
-  const taken = (one: Target): readonly string[] =>
-    calls.filter((each) => each.of === one.id && one.takes.includes(each.id)).map((each) => each.id.replace(/^cl_/, ''))
-
-  const rows = targets.map((one) => {
-    const mine = taken(one).map((each) => quoted(each))
-    return '    readonly ' + one.id + ': ' + (mine.length === 0 ? 'never' : mine.join(' | '))
-  })
-
-  const named = stores.map((one, at) => ({
-    from: beside(REACHING_AT, one),
-    as: 's' + String(at),
-    of: (one.split('/').pop() ?? '').replace(/\.ts$/, ''),
-  }))
-
-  const adapted = targets
-    .filter((one) => reachOf(one.id) === 'sdk')
-    .flatMap((one, at) => {
-      const file = (one.declares ?? [])[0]?.at
-      return file === undefined ? [] : [{ from: beside(REACHING_AT, file), as: 'c' + String(at), of: one.id }]
-    })
-
-  const used = new Set<string>()
-  const opened = targets
-    .map((one) => {
-      const reach = reachOf(one.id)
-      if (reach === 'sdk') {
-        const held = adapted.find((each) => each.of === one.id)
-        if (held === undefined) return ''
-        const each = calls
-          .filter((call) => call.of === one.id && one.takes.includes(call.id))
-          .map((call) => quoted(call.id.replace(/^cl_/, '')) + ': ' + held.as + '[' + quoted(call.path) + ']')
-        if (each.length > 0) used.add(held.as)
-        return '  ' + one.id + ': { ' + each.join(', ') + ' },'
-      }
-      if (reach === 'disk') {
-        const through = one.requires.find((each) => reachOf(each) !== undefined)
-        if (through !== undefined) return ''
-        used.add('HERE')
-        return '  ' + one.id + ': HERE,'
-      }
-      if (reach === 'cli') {
-        const each = calls
-          .filter((call) => call.of === one.id && one.takes.includes(call.id))
-          .map((call) => quoted(call.id.replace(/^cl_/, '')) + ': ' + quoted(call.path))
-        used.add('running')
-        return '  ' + one.id + ': running(' + quoted(one.id.replace(/^cli_/, '')) + ', { ' + each.join(', ') + ' }, process.cwd()),'
-      }
-      if (reach === 'https') {
-        used.add('sendingHttp')
-        return '  ' + one.id + ': sendingHttp(),'
-      }
-      const held = named.find((each) => each.of === one.id)
-      if (held === undefined) return ''
-      used.add(held.as)
-      return '  ' + one.id + ': ' + held.as + ','
-    })
-    .filter((each) => each !== '')
-
-  return [
-    ...(used.has('HERE') ? ['import { HERE } from ' + quoted(runtime(REACHING_AT, '../../integrations/disk.ts'))] : []),
-    ...(used.has('running') ? ['import { running } from ' + quoted(runtime(REACHING_AT, '../../integrations/cli.ts'))] : []),
-    ...(used.has('sendingHttp') ? ['import { sendingHttp } from ' + quoted(runtime(REACHING_AT, '../../integrations/https.ts'))] : []),
-    'import type { Counting } from ' +
-      quoted(carried ? packageOf('operations') + '/operations/operations' : runtime(REACHING_AT, '../operations.ts')),
-    ...named.filter((each) => used.has(each.as)).map((each) => 'import { store as ' + each.as + ' } from ' + quoted(each.from)),
-    ...adapted.filter((each) => used.has(each.as)).map((each) => 'import { calls as ' + each.as + ' } from ' + quoted(each.from)),
-    ...(vaulted ? ['import { vault } from ' + quoted(beside(REACHING_AT, VAULT_AT))] : []),
-    '',
-    'declare module ' +
-      quoted(carried ? packageOf('operations') + '/operations/operations' : runtime(REACHING_AT, '../operations.ts')) +
-      ' {',
-    ...(rows.length === 0 ? ['  interface Reaching {}'] : ['  interface Reaching {', ...rows, '  }']),
-    '}',
-    '',
-    'export const DECLARED: Readonly<Record<string, unknown>> = {',
-    ...opened,
-    '}',
-    '',
-    vaulted ? 'export const opening = { resolve: vault }' : 'export const opening = undefined',
-    '',
-    'export const counting: Counting | undefined = undefined',
-    '',
-  ].join('\n')
-}
-
-const reading = (header: string): string => 'request.headers.get(' + quoted(header) + ')'
-
-const CARRIED = ENVIRONMENT.flatMap(([fact, header, fills]) => {
-  const taken = header === null ? fills : fills === null ? reading(header) : reading(header) + ' ?? ' + fills
-  return taken === null ? [] : [{ fact, taken, always: fills !== null }]
-})
-
-function caller(keeping: boolean, kept: string | undefined): string {
-  const looking = keeping && kept !== undefined
-  return [
-    'import type { Actor, Environment } from ' + quoted(runtime(ACTOR_AT, '../../core/actor.ts')),
-    ...(looking ? ['import { ENTITIES } from ' + quoted(beside(ACTOR_AT, ENTITIES_AT))] : []),
-    ...(looking ? ['import { DECLARED } from ' + quoted(beside(ACTOR_AT, REACHING_AT))] : []),
-    ...(looking ? ['import type { Store } from ' + quoted(runtime(ACTOR_AT, '../../integrations/target.ts'))] : []),
-    '',
-    'const ANONYMOUS: Actor = ' + JSON.stringify(ANONYMOUS),
-    '',
-    'function environment(request: Request): Environment {',
-    ...CARRIED.map((one) => '  const ' + one.fact + ' = ' + one.taken),
-    '  return {',
-    ...CARRIED.map((one) =>
-      one.always ? '    ' + one.fact + ',' : '    ...(' + one.fact + ' === null ? {} : { ' + one.fact + ' }),',
-    ),
-    '  }',
-    '}',
-    '',
-    ...(looking
-      ? [
-          'const worn = (held: unknown): readonly string[] =>',
-          '  Array.isArray(held) ? held.filter((one) => typeof one === ' + quoted('string') + ') : typeof held === ' + quoted('string') + ' ? [held] : []',
-          '',
-          'function addressed(request: Request, from: string): string | null {',
-          '  if (from.startsWith(' + quoted('cookie:') + ')) {',
-          '    const jar = request.headers.get(' + quoted('cookie') + ') ?? ' + quoted(''),
-          '    const want = from.slice(' + quoted('cookie:') + '.length).trim() + ' + quoted('='),
-          '    const found = jar.split(' + quoted(';') + ').map((one) => one.trim()).find((one) => one.startsWith(want))',
-          '    return found === undefined ? null : decodeURIComponent(found.slice(want.length))',
-          '  }',
-          '  const held = request.headers.get(from)',
-          '  if (held === null) return null',
-          '  const bare = held.startsWith(' + quoted('Bearer ') + ') ? held.slice(' + quoted('Bearer ') + '.length) : held',
-          '  return bare.trim() === ' + quoted('') + ' ? null : bare.trim()',
-          '}',
-          '',
-        ]
-      : []),
-    'export async function actor(request: Request): Promise<Actor> {',
-    '  const anyone: Actor = { ...ANONYMOUS, ...environment(request) }',
-    ...(looking
-      ? [
-          '  const who = ENTITIES.find((one) => one.actor !== undefined)',
-          '  if (who?.actor === undefined) return anyone',
-          '  const address = (who.must ?? []).flatMap((one) => (' + quoted('unique') + ' in one ? one.unique : []))[0]',
-          '  if (address === undefined) return anyone',
-          '  const held = addressed(request, who.actor.from)',
-          '  if (held === null) return anyone',
-          '  const keeper = DECLARED[' + quoted(kept ?? '') + '] as Store | undefined',
-          '  if (keeper === undefined) return anyone',
-          '  const token = who.actor.verifies',
-          '  const row =',
-          '    token === undefined',
-          '      ? await keeper.get(anyone, who.id, held, [',
-          '          address,',
-          '          who.actor.roles,',
-          '          ...(who.actor.entitlements === undefined ? [] : [who.actor.entitlements]),',
-          '        ])',
-          '      : ((await keeper.list(anyone, who.id, { where: { [token]: held }, limit: 1 }))[0] ?? null)',
-          '  if (row === null) return anyone',
-          '  return {',
-          '    ...anyone,',
-          '    id: String(row[address] ?? held),',
-          '    roles: worn(row[who.actor.roles]),',
-          '    entitlements: who.actor.entitlements === undefined ? [] : worn(row[who.actor.entitlements]),',
-          '  }',
-        ]
-      : ['  return anyone']),
-    '}',
-    '',
-  ].join('\n')
-}
-
-const carries = (): boolean => existsSync(resolve(ROOT, 'node_modules', packageOf('operations')))
-
-const emitted = (): boolean => existsSync(resolve(ROOT, CHECKED_AT))
-
-const files = (
-  found: readonly Capability[],
-  targets: readonly Target[],
-  calls: readonly Call[],
-  keeps: string | undefined,
-  webhooks: readonly Webhook[] = [],
-): readonly Written[] => [
-  { at: CAPABILITIES_AT, text: printed(found) },
-  { at: OPENAPI_AT, text: printed(openapi(found)) },
-  { at: MCP_AT, text: printed(mcp(found)) },
-  { at: CLIENT_AT, text: client(found) },
-
-  { at: REACHING_AT, text: reaching(targets, calls, kept(), existsSync(resolve(ROOT, VAULT_AT)), carries()) },
-  { at: ACTOR_AT, text: caller(existsSync(resolve(ROOT, ENTITIES_AT)), keeps) },
-  ...(emitted() ? [{ at: DISPATCHING_AT, text: dispatching(found) }] : []),
-  ...found.filter(served).map((one) => ({ at: routeAt(one.operation), text: route(one) })),
-  ...webhooks
-    .filter((one) => found.some((each) => each.operation === one.invokes && each.live.includes('webhook') && each.webhooks.includes(one.id) && compiled(one.invokes)))
-    .flatMap((one) => {
-      const at = (one.derives ?? []).map((each) => each.at).find((each) => each === inboundAt(one.id))
-      return at === undefined ? [] : [{ at, text: inbound(one) }]
-    }),
-]
-
-interface Carried {
-  readonly live: readonly Surface[]
-  readonly off: ReadonlyMap<string, readonly Surface[]>
-}
-
-function unmoved(): Carried | undefined {
-  const tree = defaulted()
-  if (tree === undefined || tree.stated) return undefined
-  const at = resolve(ROOT, CAPABILITIES_AT)
-  const switches = switched(existsSync(at) ? readFileSync(at, 'utf8') : undefined)
-  if (switches.size === 0) return undefined
-  const live = SURFACES.filter((each) => [...switches.values()].some((one) => one.includes(each)))
-  const off = new Map(
-    [...switches]
-      .map(([id, one]) => [id, live.filter((each) => !one.includes(each))] as const)
-      .filter(([, one]) => one.length > 0),
-  )
-  const same = off.size === 0 && live.length === UNSTATED.length && live.every((each) => UNSTATED.includes(each))
-  return same ? undefined : { live, off }
-}
-
-export const asArray = (surfaces: readonly Surface[]): string => `[${surfaces.map((one) => quoted(one)).join(', ')}]`
-
-function carry(plan: Carried): readonly string[] {
-  const at = resolve(ROOT, DEFAULTS_AT)
-  const put = withTopField(readFileSync(at, 'utf8'), 'live', asArray(plan.live))
-  if (put === undefined) return []
-  writeFileSync(at, put, 'utf8')
-  const sheet = resolve(ROOT, OPERATIONS_AT)
-  let text = readFileSync(sheet, 'utf8')
-  const told = [`${DEFAULTS_AT} is live on ${plan.live.join(', ') || 'nothing'}`]
-  for (const [id, off] of plan.off) {
-    const where = listBounds(text, MEMBERS_LIST)
-    const next = where === undefined ? undefined : withField(text, where, id, 'off', asArray(off))
-    if (next === undefined) continue
-    text = next
-    told.push(`${id} turns off ${off.join(', ')}`)
-  }
-  writeFileSync(sheet, text, 'utf8')
-  return told
-}
-
-function routed(found: readonly Capability[], writing: boolean): readonly string[] {
-  const sheet = resolve(ROOT, OPERATIONS_AT)
-  if (!existsSync(sheet)) return []
-  let text = readFileSync(sheet, 'utf8')
-  const wrong: string[] = []
-  for (const one of found) {
-    const id = `${one.operation}_route`
-    const row = said(
-      { id, at: routeAt(one.operation), describes: ROUTE, by: 'thread capabilities', runs: 'thread capabilities --check' },
-      '      ',
-    )
-    const members = listBounds(text, MEMBERS_LIST)
-    const inside = members === undefined ? undefined : nestedBounds(text, members, one.operation, 'derives')
-    const standing = inside === undefined ? undefined : rowsIn(text, inside).find((each) => each.id === id)
-    const wants = one.live.includes('api')
-    if (wants ? standing?.source.trim() === row.trim() : standing === undefined) continue
-    wrong.push(
-      wants
-        ? `${one.operation} answers on api and its row ${standing === undefined ? 'declares no route' : 'says something else about its route'}`
-        : `${one.operation} does not answer on api and its row still declares ${routeAt(one.operation)}`,
-    )
-    if (!writing) continue
-    let next = inside !== undefined && standing !== undefined ? withoutRow(text, inside, id) : text
-    if (wants) {
-      const list = listBounds(next, MEMBERS_LIST)
-      const within = list === undefined ? undefined : nestedBounds(next, list, one.operation, 'derives')
-      const put =
-        within !== undefined
-          ? withRow(next, within, row)
-          : list === undefined
-            ? undefined
-            : withField(next, list, one.operation, 'derives', `[\n${row}\n    ]`)
-      if (put !== undefined) next = put
-    }
-    text = next
-  }
-  if (writing && wrong.length > 0) writeFileSync(sheet, text, 'utf8')
-  return wrong
-}
-
-const unserved = (found: readonly Capability[]): readonly string[] =>
-  found
-    .filter((one) => !one.live.includes('api') && existsSync(resolve(ROOT, routeAt(one.operation))))
-    .map((one) => routeAt(one.operation))
-
-if (invoked(import.meta.url)) {
-  const words = argv.slice(2).filter((one) => !one.startsWith('-'))
-  if (words[0] !== undefined && words[0] !== 'read') {
-    console.error(
-      'capabilities: `' + words[0] + '` is not something this command does. `thread capabilities` writes what can be reached, and ' +
-        '`thread capabilities read <mark>` prints one. Nothing was written.',
-    )
-    exit(1)
-  }
-  if (!argv.includes('--check')) {
-    const declared = declaring(sheet<Webhook>('targets.ts', 'WEBHOOKS'))
-    for (const one of declared) console.log(`capabilities: declared ${one} in ${TREE}targets.ts, so the route it writes has a row that says the address was agreed to`)
-    if (declared.length > 0) forget()
-    const pending = unmoved()
-    if (pending !== undefined) {
-      console.log(
-        `capabilities: carried what ${CAPABILITIES_AT} had switched onto the rows it is worked out from now — ` +
-          `${carry(pending).join('; ')}. Nothing in it is set by hand any more.`,
-      )
-      forget()
-    }
-  }
-  const { found, refusals, live } = await derive()
-  for (const one of refusals) console.error(`capabilities: ${one}`)
-
-  const mark = (one: Capability): string =>
-    marked([one.operation, one.describes, one.requires.join(','), one.nodes.join(','), one.live.join(',')])
-
-  const verb = words[0]
-
-  if (verb === 'read') {
-    const which = words[1]
-    const one = found.find((each) => mark(each) === which)
-    if (one === undefined) {
-      console.error(
-        `capabilities: \`${which ?? '(nothing)'}\` is not a mark this tree issued. Run \`thread capabilities\` to see them — each is printed in brackets beside the capability it belongs to.`,
-      )
-      exit(1)
-    }
-    stdout.write(`${one.operation} — ${one.describes}\n`)
-    stdout.write(`requires ${one.requires.length === 0 ? 'nothing' : one.requires.join(', ')}\n`)
-    stdout.write(`nodes: ${one.nodes.length === 0 ? '(none)' : one.nodes.join(', ')}\n`)
-    stdout.write(
-      `live: ${SURFACES.map((each) => `${one.live.includes(each) ? '[on] ' : '[off]'} ${each}`).join('   ')}\n`,
-    )
-    stdout.write(
-      `${one.browsable ? 'may be called from a page' : 'server only — it reaches a target that needs a server secret'}\n`,
-    )
-    stdout.write(`api: ${one.api.method} ${one.api.path}\n`)
-    stdout.write(`cli: ${one.cli.invocation}\n`)
-    stdout.write(`mcp: ${one.mcp.name} — ${one.mcp.description}\n`)
-    stdout.write('input:\n')
-    for (const line of printed(one.input).trimEnd().split('\n')) stdout.write(`  ${line}\n`)
-    exit(0)
-  }
-
-  const checking = argv.includes('--check')
-  let adrift = 0
-
-  if (found.length === 0 && refusals.length === 0) {
-    console.log('capabilities: this app declares no operation, so nothing is reachable through one yet.')
-    exit(adrift > 0 ? 1 : 0)
-  }
-
-  const all = sheet<Target>('targets.ts', 'TARGETS')
-  const people = sheet<{ readonly id: string; readonly actor?: unknown }>('entities.ts', 'ENTITIES')
-  const one = people.find((each) => each.actor !== undefined)
-  const where = one === undefined ? undefined : targetOf(one.id, all)
-  const written = files(
-    found,
-    all,
-    sheet<Call>('targets.ts', 'CALLS'),
-    where === undefined || typeof where === 'string' ? undefined : where.id,
-    sheet<Webhook>('targets.ts', 'WEBHOOKS'),
-  )
-
-  if (checking) {
-    const drifted = written.filter((one) => {
-      const path = resolve(ROOT, one.at)
-      return (existsSync(path) ? readFileSync(path, 'utf8') : '') !== one.text
-    })
-    for (const one of drifted) {
-      console.error(
-        `capabilities: ${one.at} is not what the operations derive. Run \`thread capabilities\` and commit the result.`,
-      )
-    }
-    const unsettled = [
-      ...(unmoved() === undefined ? [] : [`${CAPABILITIES_AT} switches surfaces that no row states yet`]),
-      ...routed(found, false),
-      ...unserved(found).map((at) => `${at} is still on disk to be served, and its operation does not answer on api`),
-    ]
-    for (const one of unsettled) console.error(`capabilities: ${one}. Run \`thread capabilities\` and commit the result.`)
-    adrift += unsettled.length
-    const off = found.filter((one) => one.live.length < live.length)
-    console.log(
-      `capabilities: ${String(found.length)} operation(s) reachable, ${String(off.length)} with a surface switched off, ` +
-        `${String(drifted.length + adrift)} finding(s).`,
-    )
-    exit(drifted.length + adrift > 0 || refusals.length > 0 ? 1 : 0)
-  }
-
-  if (refusals.length > 0) {
-    console.error(
-      `capabilities: ${String(refusals.length)} refusal(s) above, so nothing was written`,
-    )
-    exit(1)
-  }
-
-  if (!emitted()) {
-    const gone = resolve(ROOT, DISPATCHING_AT)
-    if (existsSync(gone)) rmSync(gone)
-  }
-
-  for (const one of routed(found, true)) console.log(`capabilities: ${one}, so ${OPERATIONS_AT} was changed to match`)
-  for (const at of unserved(found)) {
-    rmSync(resolve(ROOT, at))
-    const folder = dirname(resolve(ROOT, at))
-    if (readdirSync(folder).length === 0) rmSync(folder, { recursive: true, force: true })
-    console.log(`capabilities: deleted ${at}, because its operation does not answer on api and nothing may serve it`)
-  }
-
-  for (const one of written) {
-    const path = resolve(ROOT, one.at)
-    writeFileSync(path, one.text)
-  }
-
-  const shipped = found.filter(held).length
-  stdout.write(
-    `capabilities: wrote ${written.map((one) => one.at).join(', ')} — ${String(found.length)} operation(s), ` +
-      `${String(shipped)} of them in the client bundle.\n`,
-  )
-  exit(0)
-}
-