@prestack/thread 0.1.3 → 0.1.5

package/dist/operations/generators/capability.ts

@@ -1,34 +1,44 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from '../../core/files.ts'
+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 { marked, wordsIn } from '../../core/answers.ts'
-import { ROOT, TREE, descend } from '../../core/descend.ts'
+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 type { Secret } from '../../integrations/secret.ts'
-import { servesBrowser, type Target } from '../../integrations/target.ts'
+import { secrecyOf, type Secret } from '../../integrations/secret.ts'
+import { reachOf, servesBrowser, standsHere, targetOf, type Call, type Target, type Webhook } from '../../integrations/target.ts'
 
 import {
   CAPABILITIES_AT,
   CLIENT_AT,
-  DECLARED_SEAMS_AT,
   MCP_AT,
   OPENAPI_AT,
+  REACHING_AT,
+  ACTOR_AT,
+  DEFAULTS_AT,
   DISPATCHING_AT,
-  SEAMS_AT,
+  inboundAt,
+  isSurface,
+  ROUTE,
   routeAt,
   SURFACES,
   switched,
+  UNSTATED,
   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 { DISPATCH_AT } from '../dispatch.ts'
+import { STREAMED, TOLD } from '../../integrations/https.ts'
+import { holdsRow, listBounds, marked, nestedBounds, rowsIn, 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 {
@@ -38,6 +48,13 @@ interface Written {
 
 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) {
@@ -97,17 +114,28 @@ function browsing(requires: readonly string[], targets: readonly Target[], secre
   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 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(): Promise<{
   readonly found: readonly Capability[]
   readonly refusals: readonly string[]
+  readonly live: readonly Surface[]
 }> {
   const pass = descend()
   const known = types(pass)
@@ -117,11 +145,35 @@ export async function derive(): Promise<{
   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 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`)
@@ -148,7 +200,17 @@ export async function derive(): Promise<{
       continue
     }
 
-    const live = already.get(id) ?? [...SURFACES]
+    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,
@@ -157,15 +219,66 @@ export async function derive(): Promise<{
       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),
-      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 }
+  for (const one of await 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 } {
@@ -250,11 +363,11 @@ function client(found: readonly Capability[]): string {
       ].join('\n'),
     )
 
-  const near = found.filter((one) => one.local && compiled(one.operation))
+  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, seams: Seams): Promise<Result<unknown>> {`,
-    `  const held = await dispatch(${one.operation}, input, actor, seams)`,
+    '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',
     '}',
     '',
@@ -266,9 +379,9 @@ function client(found: readonly Capability[]): string {
       : [
           `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'",
+          `import { counting, DECLARED, opening } from '${beside(CLIENT_AT, REACHING_AT)}'`,
           ...near.map((one) => `import { operation as ${one.operation} } from './${one.operation}.ts'`),
           '',
         ]),
@@ -292,12 +405,13 @@ function client(found: readonly Capability[]): string {
 function route(one: Capability): string {
   const at = routeAt(one.operation)
   return [
-    "import { existsSync } from 'node:fs'",
+    `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 { 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> = {',
@@ -320,15 +434,111 @@ function route(one: Capability): string {
     '  }',
     ...(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)',
+      : [
+          '  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')
 }
 
-const SEAM = /export\s+const\s+store\s*:/
+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'
 
@@ -339,7 +549,7 @@ function kept(): readonly string[] {
     .filter((one) => one.endsWith('.ts'))
     .filter((one) => {
       try {
-        return SEAM.test(readFileSync(resolve(at, one), 'utf8'))
+        return STORED.test(readFileSync(resolve(at, one), 'utf8'))
       } catch {
         return false
       }
@@ -354,169 +564,6 @@ 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 ? 'no store yet — no target keeps entities, so an operation that needs one is refused' : 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')
@@ -525,8 +572,6 @@ 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 {}']
@@ -569,26 +614,312 @@ function dispatching(found: readonly Capability[]): string {
   ].join('\n')
 }
 
-const installed = (): boolean => existsSync(resolve(ROOT, '_threads', 'ui.ts'))
+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 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) + ']')
+        return '  ' + one.id + ': { ' + each.join(', ') + ' },'
+      }
+      if (reach === 'disk') {
+        const through = one.requires.find((each) => reachOf(each) !== undefined)
+        return through === undefined ? '  ' + 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))
+        return '  ' + one.id + ': running(' + quoted(one.id.replace(/^cli_/, '')) + ', { ' + each.join(', ') + ' }, process.cwd()),'
+      }
+      if (reach === 'https') return '  ' + one.id + ': sendingHttp(),'
+      const held = named.find((each) => each.of === one.id)
+      return held === undefined ? '' : '  ' + one.id + ': ' + held.as + ','
+    })
+    .filter((each) => each !== '')
+
+  return [
+    'import { HERE } from ' + quoted(runtime(REACHING_AT, '../../integrations/disk.ts')),
+    'import { running } from ' + quoted(runtime(REACHING_AT, '../../integrations/cli.ts')),
+    '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.map((each) => 'import { store as ' + each.as + ' } from ' + quoted(each.from)),
+    ...adapted.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 installed = (): boolean => existsSync(resolve(ROOT, 'node_modules', packageOf('ui')))
 
-const files = (found: readonly Capability[]): readonly Written[] => [
+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) },
   ...(installed() ? [{ 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 { found, refusals } = await derive()
+  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(await 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 words = wordsIn(['read'])
   const verb = words[0]
 
   if (verb === 'read') {
@@ -609,7 +940,6 @@ if (invoked(import.meta.url)) {
     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`)
@@ -623,43 +953,22 @@ if (invoked(import.meta.url)) {
 
   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 {
-        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 {
-        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)
+  const all = await sheet<Target>('targets.ts', 'TARGETS')
+  const people = await 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,
+    await sheet<Call>('targets.ts', 'CALLS'),
+    where === undefined || typeof where === 'string' ? undefined : where.id,
+    await sheet<Webhook>('targets.ts', 'WEBHOOKS'),
+  )
 
   if (checking) {
     const drifted = written.filter((one) => {
@@ -671,7 +980,14 @@ if (invoked(import.meta.url)) {
         `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)
+    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).`,
@@ -686,6 +1002,19 @@ if (invoked(import.meta.url)) {
     exit(1)
   }
 
+  if (!installed()) {
+    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)