@prestack/thread 0.1.3 → 0.1.5

package/dist/integrations/target.ts

@@ -1,4 +1,8 @@
+import { join } from 'node:path'
+import { execPath } from 'node:process'
+
 import type { Member } from '../core/thread.ts'
+import type { Actor } from '../core/actor.ts'
 
 import { SECRECY, secrecyOf, type Secret } from './secret.ts'
 
@@ -7,21 +11,28 @@ export const REACH = {
   pglite: 'pl_',
   browser: 'zu_',
   https: 'ht_',
-  module: 'mod_',
   cli: 'cli_',
+  disk: 'dsk_',
+  sdk: 'sdk_',
 } as const satisfies Readonly<Record<string, string>>
 
 export type Reach = keyof typeof REACH
 
+export const ADDRESS = {
+  row: 'reached at the address written on its row, which anybody may read',
+  secret: 'reached at a secret, because its address is a connection string and a connection string carries a password',
+  nothing: 'addressed by nothing',
+} as const satisfies Readonly<Record<string, string>>
+
+export type Addressed = keyof typeof ADDRESS
+
 export interface Holds {
 
-  readonly takes: 'entities' | 'calls' | 'names'
+  readonly takes: 'entities' | 'calls' | null
 
   readonly from: 'server' | 'browser' | 'either'
 
-  readonly addressed: boolean
-
-  readonly arrives: 'npm' | 'machine' | null
+  readonly addressed: Addressed
 
   readonly migrations: boolean
 
@@ -33,46 +44,279 @@ export interface Holds {
 }
 
 export const HOLDS: Readonly<Record<Reach, Holds>> = {
-  postgres: { takes: 'entities', from: 'server', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: 'postgres' },
-  pglite: { takes: 'entities', from: 'either', addressed: true, arrives: null, migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
-  browser: { takes: 'entities', from: 'browser', addressed: false, arrives: null, migrations: false, references: false, sql: false, driver: 'zustand' },
-  https: { takes: 'calls', from: 'either', addressed: true, arrives: null, migrations: false, references: false, sql: false, driver: null },
-
-  module: { takes: 'names', from: 'either', addressed: false, arrives: 'npm', migrations: false, references: false, sql: false, driver: null },
-  cli: { takes: 'names', from: 'server', addressed: false, arrives: 'machine', migrations: false, references: false, sql: false, driver: null },
+  postgres: { takes: 'entities', from: 'server', addressed: 'secret', migrations: true, references: true, sql: true, driver: 'postgres' },
+  pglite: { takes: 'entities', from: 'either', addressed: 'nothing', migrations: true, references: true, sql: true, driver: '@electric-sql/pglite' },
+  browser: { takes: 'entities', from: 'browser', addressed: 'nothing', migrations: false, references: false, sql: false, driver: 'zustand' },
+  https: { takes: 'calls', from: 'either', addressed: 'row', migrations: false, references: false, sql: false, driver: null },
+  cli: { takes: 'calls', from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
+  disk: { takes: null, from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
+  sdk: { takes: 'calls', from: 'server', addressed: 'nothing', migrations: false, references: false, sql: false, driver: null },
 }
 
 export const SAID: Readonly<Record<Reach, string>> = {
   postgres:
     'A postgres this app connects to over the network. It keeps entities and holds everything a declaration can state about their shape — tables, references and invariants — so what is kept here is held to that shape by the database itself rather than by whatever remembered to check. Who may touch a row is not asked of it: that is answered by the app, against the caller who actually arrived. It is reached from a server only: a connection to it from a page is a database somebody else can open. This is where a thing goes when losing it would matter.',
   pglite:
-    'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
+    'A postgres running inside the process that opened it. It keeps entities and holds tables, references and invariants, exactly as the networked one does — what differs is who can reach it, not what it can be told to hold. It is addressed by nothing: its files sit under .thread beside the tree, in a folder named after the target, so nobody types a path and a fresh clone starts it empty. What belongs here is what the caller is already entitled to see: a local copy, a working set, an offline cache.',
   browser:
     'A store in the browser, held in memory the viewer owns. It keeps entities and it is addressed by nothing, because it is already where the code runs. It holds no migration, because a page load builds it from nothing every time. What belongs here is what the interface needs to be responsive and can afford to lose.',
   https:
-    'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Its address and its credential are both secrets, and whether it may be reached from a browser is decided by which kind of secret it needs rather than by the reach itself.',
-  module:
-    'Something this app brings in from outside the repository and calls — an npm package, an SDK, an installer. Declaring one installs it and reads the methods it publishes, then asks which of them this app may call. What is picked is written down, and a method that is not on that list is refused before the package is imported: what can ever run is fixed when the target is declared, not by whoever calls it. A credential is named only if it needs one, and it comes from the vault at the moment of the call and is never written anywhere. A package you only import is a dependency rather than one of these, and the manifest already declares it.',
+    'Something this app calls over https — a vendor, a service, another app. It accepts calls rather than entities: each is declared with the verb and the path it takes, so a node names the call and never writes a url. Where it is goes on its row as address, and a header every call carries goes on its row as headers, because both are facts anybody may read; a credential it sends is a secret, and requiring one is what keeps the target out of a browser.',
   cli:
-    'A program this app runs as a command — git is the one that made this necessary. It is not installed, because it is not a dependency: it is either on the machine or it is not, and declaring one checks that it is there and says what to do when it is not. What it accepts is its subcommands, read off the program itself at the moment it is declared and written down: the whole surface the tool really has, because it was asked rather than typed, and a subcommand that is not on that list never runs. Declaring one is what brings `thread run <name>` into being, so the CLI grows a command by the app stating an integration rather than by anybody writing a verb — and an app that has not declared it has no such command at all.',
+    'A program this app runs as a command. git is the one that made this necessary. It is not installed, because it is not a dependency: it is on the machine or it is not, and a run finds out. What it accepts is the words it is asked with, declared beside it as calls with thread create target call: a subcommand where the program has them, and the option that selects what it does where it has none, each spelled the way the program spells it. A word that is not declared never runs. The program is the one the target is named after, so declaring one runs nothing and reads nothing off the machine. An operation that requires it is handed one function per declared word, and that is the only way this app ever runs it.',
+  disk:
+    'The disk this app runs on. It answers a fixed set of orders — is this there, read it, write it, list what is beside it, how big it is, remove it, and what it really is — and those orders are the same for every disk, because they are what a filesystem does rather than what any one of them chose to offer. None of them runs anything: a disk holds files and a program that installs packages is not a file order, which is why installing what a tree depends on happens where somebody typed the command and is not something a disk can be asked for. It is reached from a server only: a page has no filesystem. A trial stands one of these up out of its own scenario, so a rule can be measured against files that exist for the length of that run and nothing is written where you work.',
+  sdk:
+    'A package this app calls inside its own process — a vendor\'s SDK, fetched from npm, a git link or a tarball. It accepts calls rather than entities: the file this target declares exports `calls`, each call names the function there it runs as its path, and that file is the only place the package is imported, so an operation names the call and never the package. The integration it is part of names what to fetch in needs, and declaring the integration fetches it. It runs where the app runs, so it is addressed by nothing and reached from a server only.',
+}
+
+const on = (host: string, names: readonly string[]): readonly string[] => names.map((one) => host + '.' + one)
+
+const driverOfReach = (one: Reach): readonly string[] => {
+  const driver = HOLDS[one].driver
+  return driver === null ? [] : ['import ' + driver]
+}
+
+export const OPENS: Readonly<Record<Reach, readonly string[]>> = {
+  postgres: driverOfReach('postgres'),
+  pglite: driverOfReach('pglite'),
+  browser: driverOfReach('browser'),
+  https: [
+    'fetch',
+    'XMLHttpRequest',
+    'WebSocket',
+    'EventSource',
+    ...on('window', ['fetch']),
+    ...on('navigator', ['sendBeacon']),
+    'import node:http',
+    'import node:https',
+    'import node:http2',
+    'import node:net',
+    'import node:tls',
+    'import node:dgram',
+    'import node:dns',
+  ],
+  cli: ['import node:child_process', 'import node:worker_threads', 'import node:cluster'],
+  disk: ['import node:fs', 'import node:fs/promises'],
+  sdk: [],
+}
+
+export type Kind = 'file' | 'folder' | 'other' | 'none'
+
+export interface Listed {
+  readonly name: string
+
+  readonly kind: Exclude<Kind, 'none'>
+}
+
+export interface Measured {
+  readonly size: number
+
+  readonly modified: number
+}
+
+export interface Answering {
+  readonly kind: (at: string) => Kind
+  readonly read: (at: string) => string
+  readonly write: (at: string, said: string, mode?: number) => void
+  readonly list: (at: string) => readonly Listed[]
+  readonly stat: (at: string) => Measured
+  readonly remove: (at: string) => void
+  readonly real: (at: string) => string
+}
+
+export interface Attached extends Answering {
+
+  readonly fetch: (at: string) => string
+
+  readonly run: (at: string, words: readonly string[]) => Ran
+}
+
+export const ORDERS = {
+  kind: 'kind',
+  read: 'read',
+  write: 'written',
+  list: 'list',
+  stat: 'stat',
+  remove: 'removed',
+  real: 'real',
+  fetch: 'fetched',
+  run: 'ran',
+} as const
+
+export interface Order {
+  readonly order: keyof typeof ORDERS
+  readonly at: string
+  readonly said?: string
+  readonly mode?: number
+  readonly words?: readonly string[]
+}
+
+export interface Answer {
+  readonly answered: string
+  readonly found?: unknown
+  readonly said?: string
+  readonly at?: string
+  readonly because?: string
+}
+
+export interface Recorded {
+  readonly order: Order
+  readonly answered: Answer
+}
+
+export interface How {
+  readonly at?: string
+  readonly hears?: string
+  readonly of?: string
+  readonly answered?: readonly Answer[]
+  readonly recording?: readonly Recorded[]
+  readonly answering?: number
+}
+
+export interface Ran {
+
+  readonly there: boolean
+
+  readonly ok: boolean
+
+  readonly code: number
+
+  readonly out: string
+
+  readonly err: string
+
+  readonly killed: string | null
+
+  readonly why: string
+
+  readonly of?: string
+
+  readonly asks?: readonly Order[]
+
+  readonly lost?: string
+}
+
+export type Running<C extends string = string> = Readonly<
+  Record<
+    C,
+    (
+      args: readonly string[],
+      shows?: boolean | 'errors' | 'tee',
+      within?: number,
+      how?: How,
+    ) => Promise<Ran>
+  >
+>
+
+export type Calling<C extends string = string> = { readonly [K in C]: (given?: unknown) => Promise<unknown> }
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+export interface HttpRequest {
+  readonly target: string
+
+  readonly address: string
+  readonly method: HttpMethod
+
+  readonly path: string
+
+  readonly headers?: Readonly<Record<string, string>>
+
+  readonly body?: Uint8Array
+  readonly contentType?: string
+
+  readonly idempotencyKey?: string
+
+  readonly told?: (said: unknown) => void
+}
+
+export interface HttpResponse {
+  readonly status: number
+  readonly headers: Readonly<Record<string, string>>
+  readonly body: Uint8Array
+}
+
+export interface Http {
+  call(request: HttpRequest, within?: number): Promise<HttpResponse>
+}
+
+export type Row = Record<string, unknown>
+
+export type PropertyValue = string | number | boolean | null | readonly (string | number | boolean)[]
+
+export function isRow(v: unknown): v is Row {
+  return typeof v === 'object' && v !== null && typeof (v as { id?: unknown }).id === 'string'
+}
+
+export type ReadField = `fld_${string}` | `rel_${string}` | (string & {})
+
+export type FieldList = readonly [ReadField, ...ReadField[]]
+
+export interface Store {
+  insert(actor: Actor, entity: string, row: Row): Promise<Row>
+
+  get(actor: Actor, entity: string, key: string | number, fields: FieldList): Promise<Row | null>
+
+  list(
+    actor: Actor,
+    entity: string,
+    opts?: { limit?: number; where?: Readonly<Record<string, string | number | boolean | null>> },
+  ): Promise<Row[]>
+
+  update(
+    actor: Actor,
+    entity: string,
+    key: string | number,
+    patch: Record<string, unknown>,
+    expectedVersion?: number,
+  ): Promise<Row>
+
+  remove(actor: Actor, entity: string, key: string | number): Promise<void>
+}
+
+export interface Transactional {
+  transaction<T>(actor: Actor, fn: () => Promise<T>): Promise<T>
+}
+
+export function isTransactional(store: Store): store is Store & Transactional {
+  return typeof (store as Partial<Transactional>).transaction === 'function'
+}
+
+export interface Integration extends Member {
+
+  readonly needs?: Readonly<Record<string, string>>
 }
 
 export interface Target extends Member {
 
+  readonly of: string
+
   readonly takes: readonly string[]
 
   readonly requires: readonly string[]
 
-  readonly uses?: string
+  readonly address?: string
 
-  readonly offers?: readonly string[]
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+export interface Webhook extends Member {
+
+  readonly of: string
+
+  readonly path: string
+
+  readonly arrives?: string
+
+  readonly invokes: string
 }
 
 export interface Call extends Member {
 
   readonly of: string
 
-  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
   readonly path: string
 }
@@ -87,27 +331,35 @@ export function reachOf(id: string): Reach | undefined {
   return (Object.keys(REACH) as Reach[]).find((one) => id.startsWith(REACH[one]))
 }
 
+export const standsHere = (one: Target, targets: readonly Target[]): boolean =>
+  !one.requires.some((each) => targets.some((two) => two.id === each))
+
 export function holdsOf(id: string): Holds | undefined {
   const what = reachOf(id)
   return what === undefined ? undefined : HOLDS[what]
 }
 
+export function requirable(targets: readonly Target[], calls: readonly Call[]): readonly Target[] {
+  const declared = new Set(calls.map((one) => one.id))
+  return targets.filter((one) => holdsOf(one.id)?.takes !== 'calls' || one.takes.some((each) => declared.has(each)))
+}
+
 export function driverOf(id: string): string | null {
   return holdsOf(id)?.driver ?? null
 }
 
 export function addressOf(one: Target, secrets: readonly Secret[]): Secret | undefined {
 
-  if (holdsOf(one.id)?.addressed !== true) return undefined
+  if (holdsOf(one.id)?.addressed !== 'secret') return undefined
   const held = new Map(secrets.map((each) => [each.id, each]))
-  return one.requires.map((each) => held.get(each)).find((each) => each !== undefined && each.sends === undefined)
+  return one.requires.map((each) => held.get(each)).find((each) => each !== undefined && each.sends === undefined && each.signs === undefined)
 }
 
 export function credentialsOf(one: Target, secrets: readonly Secret[]): readonly Secret[] {
   const held = new Map(secrets.map((each) => [each.id, each]))
   return one.requires
     .map((each) => held.get(each))
-    .filter((each): each is Secret => each !== undefined && each.sends !== undefined)
+    .filter((each): each is Secret => each !== undefined && (each.sends !== undefined || each.signs !== undefined))
 }
 
 export function servesBrowser(one: Target, secrets: readonly Secret[]): true | string {
@@ -144,28 +396,50 @@ export const unreachable = (targets: readonly Target[]): readonly string[] =>
         'nothing can tell how to reach it — and how a thing is reached decides what may be declared for it',
     )
 
-const SHAPED: Readonly<Record<'module' | 'cli', RegExp>> = {
+export const LOCKFILES: Readonly<Record<string, string>> = {
+  'pnpm-lock.yaml': 'pnpm',
+  'yarn.lock': 'yarn',
+  'bun.lockb': 'bun',
+  'package-lock.json': 'npm',
+}
+
+export const PACKAGER = 'packager'
+
+const NAMED: readonly string[] = ['git', 'thread']
+
+const RUNTIME = 'node'
 
-  module: /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/,
+export const managerOf = (at: string, there: (path: string) => boolean): string =>
+  Object.entries(LOCKFILES).find(([lock]) => there(join(at, lock)))?.[1] ?? 'npm'
 
-  cli: /^[a-z][a-z0-9-]*$/,
+export function programOf(name: string, at: string, there: (path: string) => boolean): string | undefined {
+  if (NAMED.includes(name)) return name
+  if (name === RUNTIME) return execPath
+  if (name === PACKAGER) return managerOf(at, there)
+  const installed = join(at, 'node_modules', '.bin', name)
+  return there(installed) ? installed : undefined
+}
+
+export const unlisted = (name: string): string =>
+  '`' + REACH.cli + name + '` names ' + name + ', and nothing lists a program by that name: it is not under node_modules/.bin, so this tree did not install it; it is not git, node or thread; and it is not `' + PACKAGER + '`, the word for whichever package manager the lockfile picks. A program the tree did not install is whatever the machine happens to have, and a target on that is a shell by another name. Add the package that provides it and declare the target again, or ask for it through a declared call on `' + REACH.cli + PACKAGER + '`'
+
+const SHAPED: Readonly<Record<'cli', RegExp>> = {
+  cli: /^-{0,2}[A-Za-z][A-Za-z0-9-]*$/,
 }
 
 const EVERY_VALUE = new Set(['constructor', '__proto__', 'prototype'])
 
 export function misnamed(target: string, name: string): string | undefined {
   const reach = reachOf(target)
-  if (reach !== 'module' && reach !== 'cli') return undefined
+  if (reach !== 'cli') return undefined
   if (EVERY_VALUE.has(name)) {
     return (
-      `\`${name}\` is a step every JavaScript value has rather than something \`${target}\` offers, and walking to ` +
+      `\`${name}\` is a step every JavaScript value has rather than something \`${target}\` answers to, and walking to ` +
       'it leaves what was declared'
     )
   }
   if (!SHAPED[reach].test(name)) {
-    return reach === 'module'
-      ? `\`${name}\` is not a method path — one name, or names joined by dots, e.g. \`customers.list\``
-      : `\`${name}\` is not a subcommand — one word as the program spells it, e.g. \`commit\` or \`rev-parse\``
+    return name + ' is not one word as the program spells it. Give a subcommand, e.g. commit or rev-parse, or, where the program has none, the option that selects what it does, e.g. -p'
   }
   return undefined
 }
@@ -185,12 +459,8 @@ export function misaccepted(
       if (holds.takes === 'entities' && isEntity.has(named)) continue
       if (holds.takes === 'calls' && isCall.has(named)) continue
 
-      if (holds.takes === 'names') {
-        found.push(
-          `\`${one.id}\` is reached as ${String(reachOf(one.id))} and its \`takes\` names "${named}" — what an ` +
-            'installed package or a program responds to goes in `offers`, not here. `takes` is a demand, and the ' +
-            'descent requires every word on one to be coined by a row in this tree; a method name never can be',
-        )
+      if (holds.takes === null) {
+        found.push(`\`${one.id}\` takes "${named}", and a ${String(reachOf(one.id))} takes nothing: it answers the orders every ${String(reachOf(one.id))} answers, stated once on the target itself`)
         continue
       }
       found.push(
@@ -202,21 +472,52 @@ export function misaccepted(
   return found
 }
 
+export const placedAt = (targets: readonly Target[], id: string): string => targets.find((one) => one.id === id)?.address ?? ''
+
+export function placed(one: Target): readonly string[] {
+  const said = one.address
+  if (said === undefined) {
+    return [one.id + ' is reached over https and its row says nothing about where. Give it an address: the absolute url every call on it is written from, scheme and host and nothing after the path']
+  }
+  let held: URL
+  try {
+    held = new URL(said)
+  } catch {
+    return [one.id + ' has the address ' + JSON.stringify(said) + ', and that is not an absolute url. Write the whole of it, scheme and host']
+  }
+  if ([held.search, held.hash].some((each) => each !== '')) {
+    return [one.id + ' has the address ' + said + ', which carries a query or a fragment. Those belong to a call, so an address ends at its path']
+  }
+  const wrong = Object.entries(one.headers ?? {}).filter(([, value]) => typeof value !== 'string')
+  if (wrong.length > 0) {
+    return [one.id + ' carries the header ' + String(wrong[0]?.[0] ?? '') + ' with a value that is not text. A header every call carries is written as text, exactly as it goes on the wire']
+  }
+  return []
+}
+
+const stated = (one: Target, holds: Holds): readonly string[] => {
+  if (holds.addressed === 'row') return placed(one)
+  const carried = [...(one.address === undefined ? [] : ['an address']), ...(one.headers === undefined ? [] : ['headers'])]
+  if (carried.length === 0) return []
+  return [one.id + ' carries ' + carried.join(' and ') + ', and a ' + String(reachOf(one.id)) + ' is ' + ADDRESS[holds.addressed] + '. Take it off the row']
+}
+
 export function unaddressed(targets: readonly Target[], secrets: readonly Secret[]): readonly string[] {
   const held = new Map(secrets.map((one) => [one.id, one]))
   const found: string[] = []
   for (const one of targets) {
     const holds = holdsOf(one.id)
     if (holds === undefined) continue
+    found.push(...stated(one, holds))
     const addresses = one.requires
       .map((each) => held.get(each))
-      .filter((each): each is Secret => each !== undefined && each.sends === undefined)
-    if (!holds.addressed) {
+    .filter((each): each is Secret => each !== undefined && each.sends === undefined && each.signs === undefined)
+    if (holds.addressed !== 'secret') {
 
-      if (holds.arrives === null && addresses.length > 0) {
+      if (addresses.length > 0) {
         found.push(
-          `\`${one.id}\` is reached over ${String(reachOf(one.id))}, which is addressed by nothing and needs nothing to ` +
-            `reach it, and it requires \`${addresses[0]?.id ?? ''}\` — there is nowhere for that value to go`,
+          one.id + ' is reached over ' + String(reachOf(one.id)) + ', which is ' + ADDRESS[holds.addressed] + ', and it requires ' +
+            (addresses[0]?.id ?? '') + ', a secret with nowhere to be sent. A secret is a credential: give it the header it goes on with sends, or take it off this row',
         )
       }
       continue
@@ -239,14 +540,15 @@ export function unaddressed(targets: readonly Target[], secrets: readonly Secret
 }
 
 export function unheld(targets: readonly Target[], secrets: readonly Secret[]): readonly string[] {
-  const known = new Set(secrets.map((one) => one.id))
+  const known = new Set([...secrets.map((one) => one.id), ...targets.map((one) => one.id)])
   const found: string[] = []
   for (const one of targets) {
     for (const named of one.requires) {
       if (known.has(named)) continue
       found.push(
-        `\`${one.id}\` requires "${named}", and this app declares no secret by that name. A secret is declared before it ` +
-          'is required, so the one place saying who may hold a value is never whichever place happened to need it',
+        `\`${one.id}\` requires "${named}", and this app declares no secret and no target by that name. A secret is declared before it ` +
+          'is required, and a target before it is reached through, so the one place saying who holds a value, or ' +
+          'answers for a reach, is never whichever place happened to need it',
       )
     }
   }
@@ -265,11 +567,25 @@ export function unanswered(calls: readonly Call[], targets: readonly Target[]):
     const holds = holdsOf(of.id)
     if (holds !== undefined && holds.takes !== 'calls') {
       found.push(
-        `\`${one.id}\` is a call on \`${of.id}\`, which is reached over ${String(reachOf(of.id))} and keeps entities. ` +
-          'A place you keep rows in is not a place you issue verbs at',
+        holds.takes === 'entities'
+          ? `\`${one.id}\` is a call on \`${of.id}\`, which is reached over ${String(reachOf(of.id))} and keeps entities. A place you keep rows in is not a place you issue verbs at`
+          : `\`${one.id}\` is a call on \`${of.id}\`, which is a ${String(reachOf(of.id))} and answers the orders every ${String(reachOf(of.id))} answers, so nothing is declared on it. A node is handed those orders by requiring it`,
       )
       continue
     }
+    if (reachOf(of.id) === 'https' && one.method === undefined) {
+      found.push(`\`${one.id}\` is a call over https and states no method. A call over https says its verb: GET, POST, PUT, PATCH or DELETE`)
+      continue
+    }
+    if (reachOf(of.id) !== 'https' && one.method !== undefined) {
+      found.push(`\`${one.id}\` states the method ${one.method}, and \`${of.id}\` is a ${String(reachOf(of.id))}. A subcommand or a method has no http verb, so take \`method\` off that row`)
+      continue
+    }
+    const shaped = misnamed(of.id, one.path)
+    if (shaped !== undefined) {
+      found.push(`\`${one.id}\` is a call on \`${of.id}\`, and its path ${shaped}`)
+      continue
+    }
     if (!of.takes.includes(one.id)) {
       found.push(
         `\`${one.id}\` is a call on \`${of.id}\` and \`${of.id}\` does not accept it. Add it to that target's \`takes\` — ` +
@@ -280,25 +596,24 @@ export function unanswered(calls: readonly Call[], targets: readonly Target[]):
   return found
 }
 
-export function misused(targets: readonly Target[]): readonly string[] {
+export function unplaced(targets: readonly Target[], integrations: readonly Integration[]): readonly string[] {
+  const known = new Set(integrations.map((one) => one.id))
   const found: string[] = []
   for (const one of targets) {
-    const holds = holdsOf(one.id)
-    if (holds === undefined) continue
-    if (holds.arrives !== null && (one.uses ?? '') === '') {
+    const named = one.of ?? ''
+    if (named === '') {
       found.push(
-        `\`${one.id}\` is reached as ${String(reachOf(one.id))} and does not say what it uses — ` +
-          `${holds.arrives === 'npm' ? 'the npm package to install' : 'the program to run'} goes in \`uses\`, because the ` +
-          'id is what this app calls it and not what it is',
+        `\`${one.id}\` names no integration, and every target is one way into something outside this app — a vendor, ` +
+          'a service, a program on the machine. Say which one it reaches into: `thread create integration` lists ' +
+          'the ones already declared and declares another',
       )
       continue
     }
-    if (holds.arrives === null && one.uses !== undefined) {
-      found.push(
-        `\`${one.id}\` is reached over ${String(reachOf(one.id))}, where nothing is installed and nothing is spawned, ` +
-          `and it states \`uses: '${one.uses}'\` — there is nothing for that name to be`,
-      )
-    }
+    if (known.has(named)) continue
+    found.push(
+      `\`${one.id}\` is part of "${named}", and this app declares no integration by that name. Declare it with ` +
+        '`thread create integration`, or point this row at one already declared',
+    )
   }
   return found
 }
@@ -308,14 +623,15 @@ export function refusals(
   secrets: readonly Secret[],
   calls: readonly Call[],
   entities: readonly string[],
+  integrations: readonly Integration[],
 ): readonly string[] {
   return [
     ...unreachable(targets),
+    ...unplaced(targets, integrations),
     ...unheld(targets, secrets),
     ...unaddressed(targets, secrets),
     ...unanswered(calls, targets),
     ...misaccepted(targets, entities, calls),
-    ...misused(targets),
   ]
 }
 

package/dist/integrations/vault.d.ts

@@ -11,4 +11,5 @@ export declare function keyed(root: string): Buffer;
 export declare function seal(root: string, named: string, env: Env, value: string): void;
 export declare const sealedIn: (root: string, env: Env) => readonly string[];
 export declare function opened(root: string, declared: readonly string[], env: Env): (refs: readonly string[]) => Promise<Readonly<Record<string, string>>>;
+export declare function unseal(root: string, named: string, envs: readonly Env[]): readonly Env[];
 export declare const IGNORES: readonly string[];