@prestack/thread 0.0.1 → 0.0.2

package/dist/operations/generators/capability.ts

@@ -0,0 +1,704 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { argv, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { marked, wordsIn } from '../../core/asking.ts'
+import { ROOT, TREE, descend } 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 type { Secret } from '../../integrations/secret.ts'
+import { servesBrowser, type Target } from '../../integrations/target.ts'
+
+import {
+  CAPABILITIES_AT,
+  CLIENT_AT,
+  DECLARED_SEAMS_AT,
+  MCP_AT,
+  OPENAPI_AT,
+  DISPATCHING_AT,
+  SEAMS_AT,
+  routeAt,
+  SURFACES,
+  switched,
+  type Capability,
+  type Surface,
+} from '../capabilities.ts'
+import { ANONYMOUS, ENVIRONMENT } from '../../core/actor.ts'
+import { PERMITS_AT } from '../access.ts'
+import { SAID as HANDED, supplies } from '../seams.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)
+
+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)}`
+  }
+}
+
+async function sheet<T>(file: string, list: string): Promise<readonly T[]> {
+  const at = resolve(ROOT, `_threads/${file}`)
+  if (!existsSync(at)) return []
+  try {
+    const held = (await import(pathToFileURL(at).href)) as Record<string, readonly T[] | undefined>
+    return held[list] ?? []
+  } catch {
+    return []
+  }
+}
+
+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
+}
+
+function locally(requires: readonly string[]): boolean {
+  for (const word of requires) {
+    if (!supplies(word)) return false
+    if (word === 'sm_vault') return false
+  }
+  return true
+}
+
+export async function derive(): Promise<{
+  readonly found: readonly Capability[]
+  readonly refusals: readonly string[]
+}> {
+  const pass = descend()
+  const known = types(pass)
+  const refusals: string[] = []
+  const found: Capability[] = []
+
+  const targets = await sheet<Target>('targets.ts', 'TARGETS')
+  const secrets = await sheet<Secret>('secrets.ts', 'SECRETS')
+
+  const at = resolve(ROOT, CAPABILITIES_AT)
+  const already = switched(existsSync(at) ? readFileSync(at, 'utf8') : undefined)
+
+  for (const [id, one] of [...operations(pass, known)].sort((a, b) => compare(a[0], b[0]))) {
+    const stated = pass.stated.get(id)
+    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 = await schemaOf(takes)
+    if (typeof schema === 'string') {
+      refusals.push(`\`${id}\`: ${schema}`)
+      continue
+    }
+
+    const live = already.get(id) ?? [...SURFACES]
+
+    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[],
+      browsable: browsing(one.requires, targets, secrets),
+      local: browsing(one.requires, targets, secrets) && locally(one.requires),
+      mcp: { name: id, description: describes, inputSchema: schema },
+      cli: { invocation: `${id} --input '<json>'`, describes },
+      api: { method, path: `/operations/${id}` },
+    })
+  }
+
+  return { found, refusals }
+}
+
+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.local && compiled(one.operation))
+
+  const bound = near.flatMap((one) => [
+    `export async function ${one.operation}Locally(input: unknown, actor: Actor, seams: Seams): Promise<Result<unknown>> {`,
+    `  const held = await dispatch(${one.operation}, input, actor, seams)`,
+    '  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 type { Seams } from '${runtime(CLIENT_AT, '../seams.ts')}'`,
+          '',
+          "import { dispatch } from './_dispatch.ts'",
+          ...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 'node:fs'",
+    "import { join } from 'node:path'",
+    '',
+    "import { dispatch } from '../../../operations/_dispatch.ts'",
+    `import { actor } from '${beside(at, DECLARED_SEAMS_AT)}'`,
+    `import { SEAMS } from '${beside(at, SEAMS_AT)}'`,
+    `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)']),
+    '  const held = await dispatch(operation, input, await actor(request), SEAMS)',
+    '  return Response.json(held, { status: held.ok ? 200 : (STATUS[held.code] ?? 500) })',
+    '}',
+    '',
+  ].join('\n')
+}
+
+const SEAM = /export\s+const\s+store\s*:/
+
+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 SEAM.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'}`
+
+function settled(keeping: boolean, stores: readonly string[], ruled: boolean, vaulted: boolean): string {
+  const named = stores.map((one, at) => ({ from: beside(DECLARED_SEAMS_AT, one), as: `s${String(at)}` }))
+  const only = named[0]
+  return [
+    `import type { Actor, Environment } from '${runtime(DECLARED_SEAMS_AT, '../../core/actor.ts')}'`,
+    `import type { Seams } from '${runtime(DECLARED_SEAMS_AT, '../seams.ts')}'`,
+    ...(keeping ? [`import { ENTITIES } from '${beside(DECLARED_SEAMS_AT, ENTITIES_AT)}'`] : []),
+    ...(ruled ? [`import { permits } from '${beside(DECLARED_SEAMS_AT, PERMITS_AT)}'`] : []),
+    ...(vaulted ? [`import { vault as opening } from '${beside(DECLARED_SEAMS_AT, VAULT_AT)}'`] : []),
+    ...(stores.length === 1 && only !== undefined ? [`import { store as kept } from '${only.from}'`] : []),
+    ...(stores.length > 1 ? named.map((one) => `import { keeps as ${one.as}Keeps, store as ${one.as} } from '${one.from}'`) : []),
+    '',
+    ...(keeping
+      ? [
+          'const made = {', "  log: { write(level: string, action: string, who: Actor, data: Record<string, unknown>) { console.log(JSON.stringify({ level, action, who, data })) } },", "  audit: { async append(who: Actor, record: unknown) { console.log(JSON.stringify({ audit: record, who })) } },", "  errors: { async record(who: Actor, failure: unknown) { console.error(JSON.stringify({ failure, who })) } },", '}',
+        ]
+      : ['const made = {', "  log: { write(level: string, action: string, who: Actor, data: Record<string, unknown>) { console.log(JSON.stringify({ level, action, who, data })) } },", "  audit: { async append(who: Actor, record: unknown) { console.log(JSON.stringify({ audit: record, who })) } },", "  errors: { async record(who: Actor, failure: unknown) { console.error(JSON.stringify({ failure, who })) } },", '}']),
+    '',
+    ...(stores.length > 1
+      ? [
+          "const WHERE = new Map<string, Seams['store']>([",
+          ...named.map((one) => `  ...${one.as}Keeps.map((entity) => [entity, ${one.as}] as const),`),
+          '])',
+          '',
+          'function at(entity: string) {',
+          '  const found = WHERE.get(entity)',
+          "  if (found === undefined) throw new Error(entity + ' is not kept in any target this app declares')",
+          '  return found',
+          '}',
+          '',
+          "const store: Seams['store'] = {",
+          '  insert: (actor, entity, row) => at(entity).insert(actor, entity, row),',
+          '  get: (actor, entity, key, fields) => at(entity).get(actor, entity, key, fields),',
+          '  list: (actor, entity, opts) => at(entity).list(actor, entity, opts),',
+          '  update: (actor, entity, key, patch, expectedVersion) => at(entity).update(actor, entity, key, patch, expectedVersion),',
+          '  remove: (actor, entity, key) => at(entity).remove(actor, entity, key),',
+          '}',
+          '',
+        ]
+      : []),
+    `const ANONYMOUS: Actor = ${JSON.stringify(ANONYMOUS)}`,
+      '',
+      "const http: NonNullable<Seams['http']> = {",
+      '  async call(request) {',
+      '    const base = new URL(request.address)',
+      "    if (base.protocol !== 'https:') throw new Error(request.target + ' is reached over ' + base.protocol + ' and an outward call goes over https only')",
+      '    const stem = base.pathname.length === 1 ? String() : base.pathname',
+      '    const url = new URL(base.origin + stem + request.path)',
+      "    if (url.origin !== base.origin) throw new Error(request.path + ' resolves to ' + url.origin + ', which is not where ' + request.target + ' is')",
+      '    const headers: Record<string, string> = { ...request.headers }',
+      "    if (request.contentType !== undefined) headers['content-type'] = request.contentType",
+      '    const carried = new Uint8Array(request.body === undefined ? 0 : request.body.byteLength)',
+      '    if (request.body !== undefined) carried.set(request.body)',
+      '    const began = Date.now()',
+      '    const sent = JSON.stringify(headers).length + (request.body === undefined ? 0 : request.body.byteLength)',
+      '    const answered = await fetch(url.toString(), { method: request.method, headers, ...(request.body === undefined ? {} : { body: carried }), signal: AbortSignal.timeout(10000) })',
+      '    const body = new Uint8Array(await answered.arrayBuffer())',
+      '    return { status: answered.status, headers: Object.fromEntries(answered.headers.entries()), body, bytesSent: sent, bytesReceived: body.byteLength, durationMs: Date.now() - began }',
+      '  },',
+      '}',
+      '',
+      'const shared = globalThis as { __threadSeams?: Seams }',
+    '',
+    'export const DECLARED: Seams = (shared.__threadSeams ??= {',
+    '  ...made,',
+    ...(stores.length === 1 ? ['  store: kept,'] : []),
+    ...(stores.length > 1 ? ['  store,'] : []),
+    '  clock: { now: () => Date.now() },',
+    '  random: { next: Math.random, uuid: () => crypto.randomUUID() },',
+    '  http,',
+    ...(ruled ? ['  permits: { check: (actor, action, resource) => Promise.resolve(permits(actor, action, resource)) },'] : []),
+    ...(vaulted ? ['  vault: { resolve: opening },'] : []),
+    '})',
+    '',
+    'function environment(request: Request): Environment {',
+    ...ENVIRONMENT.map(([fact, header]) => `  const ${fact} = request.headers.get(${quoted(header)})`),
+    '  return {',
+    ...ENVIRONMENT.map(([fact]) => `    ...(${fact} === null ? {} : { ${fact} }),`),
+    '  }',
+    '}',
+    '',
+    ...(keeping
+      ? [
+          'const worn = (held: unknown): readonly string[] =>',
+          "  Array.isArray(held) ? held.filter((one) => typeof one === 'string') : typeof held === 'string' ? [held] : []",
+          '',
+          'function addressed(request: Request, from: string): string | null {',
+          "  if (from.startsWith('cookie:')) {",
+          "    const jar = request.headers.get('cookie') ?? ''",
+          "    const want = `${from.slice('cookie:'.length).trim()}=`",
+          "    const found = jar.split(';').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('Bearer ') ? held.slice('Bearer '.length) : held",
+          "  return bare.trim() === '' ? null : bare.trim()",
+          '}',
+          '',
+          'export async function actor(request: Request): Promise<Actor> {',
+          '  const anyone: Actor = { ...ANONYMOUS, ...environment(request) }',
+          '  const who = ENTITIES.find((one) => one.actor !== undefined)',
+          '  if (who?.actor === undefined) return anyone',
+          '',
+          "  const address = (who.must ?? []).flatMap((one) => ('unique' in one ? one.unique : []))[0]",
+          '  if (address === undefined) return anyone',
+          '',
+          '  const held = addressed(request, who.actor.from)',
+          '  if (held === null) return anyone',
+          '',
+          '  const token = who.actor.verifies',
+          '',
+          '  const row =',
+          '    token === undefined',
+          '      ? await DECLARED.store.get(anyone, who.id, held, [',
+          '          address,',
+          '          who.actor.roles,',
+          '          ...(who.actor.entitlements === undefined ? [] : [who.actor.entitlements]),',
+          '        ])',
+          '      : ((await DECLARED.store.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]),',
+          '  }',
+          '}',
+          '',
+        ]
+      : [
+          'export const actor = (request: Request): Promise<Actor> => Promise.resolve({ ...ANONYMOUS, ...environment(request) })',
+          '',
+        ]),
+  ].join('\n')
+}
+
+const seeded = (): string =>
+  [
+    `import { DECLARED } from '${beside(SEAMS_AT, DECLARED_SEAMS_AT)}'`,
+    `import type { Seams } from '${runtime(SEAMS_AT, '../seams.ts')}'`,
+    '',
+    'export const SEAMS: Seams = {',
+    '  ...DECLARED,',
+    '}',
+    '',
+  ].join('\n')
+
+const width = Math.max(...Object.keys(HANDED).map((one) => one.length))
+
+const handing = (stores: readonly string[], keeping: boolean, vaulted: boolean): string =>
+  [
+    `capabilities: seeded ${SEAMS_AT} — what this app hands its operations, and yours from here.`,
+    `  It hands on everything ${DECLARED_SEAMS_AT} settles from your declarations: rows go to ` +
+      (stores.length === 0 ? 'memory until a target keeps entities' : stores.join(', ')) +
+      `, who is asking is ${keeping ? 'read off the entity that names the caller' : 'nobody until an entity names the caller'}, ` +
+      `calls leave through http${vaulted ? ' with credentials opened by the vault' : ''}.`,
+    '  Replace a seam, or add one, by naming it in SEAMS. Every seam an operation can be handed:',
+    ...Object.entries(HANDED).map(([one, says]) => `    ${one.padEnd(width)}  ${says}`),
+    '',
+  ].join('\n')
+
+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)
+  return [
+    '/* GENERATED by thread — do not edit. It is derived from what this app declares. */',
+    '',
+    `declare module '${packageOf('ui')}/ui/checked' {`,
+    ...(reachable.length === 0
+      ? ['  interface Dispatching {}']
+      : ['  interface Dispatching {', ...reachable.map((one) => `    readonly ${one.operation}: true`), '  }']),
+    '}',
+    '',
+    'interface Reaches {',
+    '  readonly operation: string',
+    "  readonly method: 'GET' | 'POST'",
+    '  readonly path: string',
+    '}',
+    '',
+    `const REACHES: readonly Reaches[] = [${
+      reachable.length === 0
+        ? ''
+        : `\n${reachable
+            .map(
+              (one) =>
+                `  { operation: ${JSON.stringify(one.operation)}, method: ${JSON.stringify(one.api?.method)}, path: ${JSON.stringify(one.api?.path)} },`,
+            )
+            .join('\n')}\n`
+    }]`,
+    '',
+    'export async function dispatchTo(operation: string, input?: Readonly<Record<string, unknown>>): Promise<unknown> {',
+    '  const one = REACHES.find((each) => each.operation === operation)',
+    '  if (one === undefined) {',
+    '    throw new Error(',
+    "      `thread: nothing declares an operation called ${operation}, so there is nowhere to send this. ` +",
+    "        `This app reaches: ${REACHES.map((each) => each.operation).join(', ') || '(nothing)'}`,",
+    '    )',
+    '  }',
+    '  const sent = await fetch(one.path, {',
+    '    method: one.method,',
+    "    headers: { 'content-type': 'application/json' },",
+    "    ...(one.method === 'GET' ? {} : { body: JSON.stringify(input ?? {}) }),",
+    '  })',
+    '  return await sent.json()',
+    '}',
+    '',
+  ].join('\n')
+}
+
+const installed = (): boolean => existsSync(resolve(ROOT, '_threads', 'ui.ts'))
+
+const files = (found: readonly Capability[]): 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) },
+
+  ...(installed() ? [{ at: DISPATCHING_AT, text: dispatching(found) }] : []),
+  ...found.filter(served).map((one) => ({ at: routeAt(one.operation), text: route(one) })),
+]
+
+if (invoked(import.meta.url)) {
+  const { found, refusals } = 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 words = wordsIn(['read'])
+  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(`${one.local ? 'runs where it is called, with nothing sent' : 'reaches a target over the network'}\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
+
+  const keeping = existsSync(resolve(ROOT, ENTITIES_AT))
+
+  if (existsSync(resolve(ROOT, OPERATIONS_AT))) {
+    const stores = kept()
+    const vaulted = existsSync(resolve(ROOT, VAULT_AT))
+    const text = settled(keeping, stores, existsSync(resolve(ROOT, PERMITS_AT)), vaulted)
+    const at = resolve(ROOT, DECLARED_SEAMS_AT)
+    if ((existsSync(at) ? readFileSync(at, 'utf8') : '') !== text) {
+      if (checking) {
+        adrift += 1
+        console.error(
+          `capabilities: ${DECLARED_SEAMS_AT} is not what the declarations settle. Run \`thread capabilities\` and commit the result.`,
+        )
+      } else {
+        mkdirSync(dirname(at), { recursive: true })
+        writeFileSync(at, text, 'utf8')
+        console.log(`capabilities: wrote ${DECLARED_SEAMS_AT} — the seams your targets, entities, grants and secrets settle.`)
+      }
+    }
+
+    const seed = resolve(ROOT, SEAMS_AT)
+    if (!existsSync(seed)) {
+      if (checking) {
+        adrift += 1
+        console.error(
+          `capabilities: ${SEAMS_AT} is not there, and it is what hands every operation its seams. Run \`thread capabilities\` — it seeds the file once, and from then on it is yours.`,
+        )
+      } else {
+        mkdirSync(dirname(seed), { recursive: true })
+        writeFileSync(seed, seeded(), 'utf8')
+        stdout.write(handing(stores, keeping, vaulted))
+      }
+    }
+  }
+
+  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 written = files(found)
+
+  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 off = found.filter((one) => one.live.length < SURFACES.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)
+  }
+
+  for (const one of written) {
+    const path = resolve(ROOT, one.at)
+    mkdirSync(dirname(path), { recursive: true })
+    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)
+}
+