@prestack/thread 0.1.20 → 0.1.22

package/dist/operations/generators/trial.ts

@@ -1,666 +0,0 @@
-import { existsSync, readFileSync, writeFileSync, type Answering, type Listed } from '../../integrations/disk.ts'
-import { resolve } from 'node:path'
-import { argv, stdout } from 'node:process'
-import { pathToFileURL } from 'node:url'
-
-import { ANONYMOUS, type Actor } from '../../core/actor.ts'
-import { ROOT, descend } from '../../core/descend.ts'
-import { exit, invoked } from '../../core/invoked.ts'
-import { reachOf, standsHere, type Call, type Row, type Target } from '../../integrations/target.ts'
-
-import { recordingHttp, type RecordedCall, type Scripted, type ScriptedAnswer } from '../../integrations/https.ts'
-import { standing, type Kept, type Stood } from '../../integrations/pglite.ts'
-import { TRIALS_AT, type Operation } from '../operations.ts'
-import { PERMITS_AT } from '../access.ts'
-import type { Result } from '../result.ts'
-import type { Vault } from '../../integrations/secret.ts'
-import { operations, types } from './seed.ts'
-
-export { TRIALS_AT }
-
-const DISPATCH_AT = 'operations/_dispatch.ts'
-
-
-
-const ACCESS_AT = '_threads/access.ts'
-
-const WHEN = 1_767_225_600_000
-
-export interface Scenario {
-  readonly id: string
-
-  readonly describes: string
-
-  readonly input: unknown
-
-  readonly actor?: Actor
-
-  readonly rows?: readonly { readonly entity: string; readonly row: Row }[]
-
-  readonly answers?: Readonly<Record<string, Scripted>>
-
-  readonly views?: Readonly<Record<string, readonly unknown[]>>
-
-  readonly files?: Readonly<Record<string, string>>
-}
-
-export interface Trial {
-  readonly operation: string
-  readonly scenario: string
-
-  readonly refused: boolean
-
-  readonly measured: boolean
-
-  readonly result: unknown
-
-  readonly kept: unknown
-
-
-  readonly called: unknown
-}
-
-export interface Outcome {
-  readonly id: string
-  readonly operation: string
-  readonly passed: boolean
-  readonly refused: boolean
-  readonly measured: boolean
-  readonly failures: readonly string[]
-}
-
-export interface Run {
-  readonly outcomes: readonly Outcome[]
-  readonly passed: number
-  readonly failed: number
-  readonly measured: number
-}
-
-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 (value instanceof Map) return stable(Object.fromEntries(value))
-  if (value instanceof Set) 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
-  }
-  if (typeof value === 'bigint') return String(value)
-  if (typeof value === 'function') return '[function]'
-  if (value === undefined) return null
-  return value
-}
-
-const printed = (value: unknown): string => `${JSON.stringify(stable(value), null, 2)}\n`
-
-const asking = (scenario: Scenario): Actor => ({
-  ...(scenario.actor ?? ANONYMOUS),
-  run: 'trial',
-  replay: `trial_${scenario.id}`,
-  moment: new Date(WHEN).toISOString(),
-})
-
-function programmed(word: string, names: readonly string[]): Record<string, unknown> {
-  const made: Record<string, unknown> = {}
-  for (const order of names) {
-    made[order] = (): never => {
-      throw new Error(
-        word + ' was asked to run ' + order + ', and this scenario says nothing about what that did. A trial stands a ' +
-          'disk up out of the files its scenario states, and there is nowhere yet to state what a program or a package answered, so ' +
-          'a scenario cannot give either an order. This says that rather than inventing a result for one.',
-      )
-    }
-  }
-  return made
-}
-
-function packaged(
-  word: string,
-  names: readonly string[],
-  script: Readonly<Record<string, Scripted>>,
-  into: RecordedCall[],
-): Record<string, unknown> {
-  const spent = new Map<string, number>()
-  const made: Record<string, unknown> = {}
-  for (const name of names) {
-    made[name] = async (given?: unknown): Promise<unknown> => {
-      const key = word + ' ' + name
-      into.push({ target: word, method: 'CALL', path: name, headers: {}, body: JSON.stringify(stable(given ?? null)) })
-      const held = script[key]
-      if (held === undefined) {
-        throw new Error(
-          'this scenario scripts no answer for "' + key + '", so nothing here knows what ' + word + ' would hand back. Add ' +
-            'that key to the scenario\'s answers, with what the call returns written as JSON in its body.',
-        )
-      }
-      const each = Array.isArray(held) ? (held as readonly ScriptedAnswer[]) : undefined
-      const at = spent.get(key) ?? 0
-      spent.set(key, at + 1)
-      const answer = each === undefined ? (held as ScriptedAnswer) : each[at]
-      if (answer === undefined) {
-        throw new Error(
-          'this scenario scripts ' + String(each?.length ?? 0) + ' answer(s) for "' + key + '" and it has now been called ' +
-            String(at + 1) + ' time(s). A node that calls the same thing again needs one answer per call, in the order they come back.',
-        )
-      }
-      if (answer.status !== 200) throw new Error(answer.body ?? word + ' ' + name + ' failed with ' + String(answer.status))
-      return answer.body === undefined ? undefined : (JSON.parse(answer.body) as unknown)
-    }
-  }
-  return made
-}
-
-function disked(files: Readonly<Record<string, string>>): Answering {
-  const held = new Map<string, string>(Object.entries(files))
-  const under = (at: string): boolean => [...held.keys()].some((one) => one.startsWith(at + '/'))
-  const gone = (at: string): Error =>
-    new Error(at + ' is not in this scenario, and a trial answers a file order against the files its scenario states')
-  return {
-    kind: (at) => (held.has(at) ? 'file' : under(at) ? 'folder' : 'none'),
-    read: (at) => {
-      const said = held.get(at)
-      if (said === undefined) throw gone(at)
-      return said
-    },
-    write: (at, said) => {
-      held.set(at, said)
-    },
-    list: (at) => {
-      const inside = new Map<string, Listed>()
-      for (const one of held.keys()) {
-        if (!one.startsWith(at + '/')) continue
-        const rest = one.slice(at.length + 1)
-        const cut = rest.indexOf('/')
-        const name = cut === -1 ? rest : rest.slice(0, cut)
-        inside.set(name, { name, kind: cut === -1 ? 'file' : 'folder' })
-      }
-      return [...inside.values()]
-    },
-    stat: (at) => {
-      const said = held.get(at)
-      if (said === undefined) throw gone(at)
-      return { size: said.length, modified: 0 }
-    },
-    remove: (at) => {
-      held.delete(at)
-    },
-    real: (at) => at,
-  }
-}
-
-function vaulting(stood: Readonly<Record<string, string>>): Vault {
-  return {
-    async resolve(refs) {
-      const found: Record<string, string> = {}
-      for (const ref of refs) {
-        const value = stood[ref]
-        if (value === undefined) {
-          throw new Error(
-            ref + ' is not a secret this app declares, so a trial has nothing to stand in for it. Declare it with ' +
-              '`thread create secret`, or stop requiring the target that asks for it.',
-          )
-        }
-        found[ref] = value
-      }
-      return found
-    },
-  }
-}
-
-async function standingStore(row: Target): Promise<Stood | string> {
-  const said = row.derives?.find((each) => each.id === row.id + '_store')?.at
-  if (said === undefined) {
-    return row.id + ' keeps rows and its row derives no store, so a trial has nothing to stand up. Run `thread schema`'
-  }
-  const at = resolve(ROOT, said)
-  if (!existsSync(at)) return said + ' is not there, so ' + row.id + ' cannot be stood up. Run `thread schema`'
-  const made = (await import(pathToFileURL(at).href)) as { readonly kept?: Kept }
-  const held = made.kept
-  if (held === undefined) {
-    return said + ' says nothing about what ' + row.id + ' keeps or with what schema. Run `thread schema`'
-  }
-  return standing(held)
-}
-
-async function openedFor(
-  one: Operation<unknown>,
-  scenario: Scenario,
-  stood: Readonly<Record<string, string>>,
-  targets: readonly Target[] = [],
-  calls: readonly Call[] = [],
-): Promise<{
-  readonly opened: Readonly<Record<string, unknown>>
-  readonly opening: Vault
-  readonly stores: readonly Stood[]
-  readonly calls: () => unknown
-} | string> {
-  const recorder = recordingHttp(scenario.answers ?? {})
-  const packages: RecordedCall[] = []
-  const opening = vaulting(stood)
-  const opened: Record<string, unknown> = {}
-  const stores: Stood[] = []
-
-  const answering = (row: Target): readonly string[] =>
-    calls.filter((each) => each.of === row.id && row.takes.includes(each.id)).map((each) => each.id.replace(/^cl_/, ''))
-  for (const word of one.requires) {
-    const row = targets.find((each) => each.id === word)
-    if (row === undefined || !standsHere(row, targets)) continue
-    const reach = reachOf(row.id)
-    if (reach === 'disk') opened[word] = disked(scenario.files ?? {})
-    else if (reach === 'cli') opened[word] = programmed(word, answering(row))
-    else if (reach === 'https') opened[word] = recorder
-    else if (reach === 'sdk') opened[word] = packaged(word, answering(row), scenario.answers ?? {}, packages)
-    else {
-      const held = await standingStore(row)
-      if (typeof held === 'string') return held
-      opened[word] = held.store
-      stores.push(held)
-    }
-  }
-
-
-
-  return { opened, opening, stores, calls: () => [...recorder['calls'], ...packages] }
-}
-
-const BEFORE = new Set(['denied', 'invalid'])
-
-function entered(result: unknown): boolean {
-  if (typeof result !== 'object' || result === null) return false
-  const held = result as { readonly ok?: unknown; readonly code?: unknown }
-  if (held.ok === true) return true
-  return held.ok === false && !BEFORE.has(String(held.code))
-}
-
-function denied(result: unknown): boolean {
-  if (typeof result !== 'object' || result === null) return false
-  const held = result as { readonly ok?: unknown; readonly code?: unknown }
-  return held.ok === false && BEFORE.has(String(held.code))
-}
-
-export async function runScenario(
-  one: Operation<unknown>,
-  scenario: Scenario,
-  dispatch: (
-    operation: Operation<unknown>,
-    input: unknown,
-    actor: Actor,
-    opened: Readonly<Record<string, unknown>>,
-    opening: Vault,
-  ) => Promise<Result<unknown>>,
-  stood: Readonly<Record<string, string>> = {},
-  targets: readonly Target[] = [],
-  calls: readonly Call[] = [],
-): Promise<Trial | string> {
-
-  const made = await openedFor(one, scenario, stood, targets, calls)
-  if (typeof made === 'string') return made
-
-  const actor = asking(scenario)
-
-  for (const each of scenario.rows ?? []) {
-    const held = made.stores.find((store) => store.keeps.includes(each.entity))
-    if (held === undefined) {
-      return (
-        '`' + one.id + '` is tried with a row of "' + each.entity + '" and no target it requires keeps that entity, ' +
-        'so there is nowhere to put it. Require the target that keeps it, or take that row off the scenario'
-      )
-    }
-    await held.seed(actor, [each])
-  }
-
-  let result: unknown
-  try {
-    result = await dispatch(one, scenario['input'], actor, made.opened, made.opening)
-  } catch (thrown) {
-    result = { threw: thrown instanceof Error ? thrown.message : String(thrown) }
-  }
-
-  const kept: Record<string, unknown> = {}
-  for (const held of made.stores) Object.assign(kept, await held.taken(actor))
-
-  return {
-    operation: one.id,
-    scenario: scenario.id,
-    refused: denied(result),
-    measured: entered(result),
-    result,
-    kept,
-
-    called: made.calls(),
-  }
-}
-
-export async function scenariosFor(
-  one: Operation<unknown>,
-  takes: string,
-  granted: readonly string[] = [],
-): Promise<readonly Scenario[] | string> {
-  const from = resolve(ROOT, takes)
-  if (existsSync(from)) {
-    const made = (await import(pathToFileURL(from).href)) as { readonly SCENARIOS?: readonly Scenario[] }
-    const found = made.SCENARIOS
-    if (found !== undefined) {
-      if (found.length === 0) {
-        return `${takes} states an empty \`SCENARIOS\`, so nothing would be measured — remove it, or state one`
-      }
-      const named = new Set(found.map((each) => each.id))
-      if (named.size !== found.length) {
-        return `${takes} states two scenarios with the same id, and a trial is named after the one it ran`
-      }
-      return [...found].sort((a, b) => compare(a.id, b.id))
-    }
-  }
-
-  if (granted.length > 0) {
-    return (
-      `\`${one.id}\` is granted to ${granted.join(', ')}, and no scenario says who runs it. A caller is not ` +
-      `something to derive — a trial run as somebody the grant must allow proves nothing about access. State one ` +
-      `with \`thread run trial ${one.id}\`, which asks for the roles it arrives wearing, and export \`SCENARIOS\` ` +
-      `from ${takes}`
-    )
-  }
-
-  const empty = one.input.safeParse({})
-  if (empty.success) {
-    return [{ id: 'empty', describes: `runs ${one.id} with no input, as whoever arrives having said nothing`, input: {} }]
-  }
-
-  return (
-    `\`${one.id}\` takes an input that no empty object satisfies, and states no scenario to try it ` +
-    `with. Export \`SCENARIOS\` from ${takes} — until then this operation is not proven`
-  )
-}
-
-export function compared(was: readonly Trial[], now: readonly Trial[]): Run {
-  const before = new Map(was.map((one) => [`${one.operation}/${one.scenario}`, one]))
-  const outcomes: Outcome[] = []
-
-  for (const one of now) {
-    const id = `${one.operation}/${one.scenario}`
-    const failures: string[] = []
-    const older = before.get(id)
-
-    if (!one.refused && !one.measured) {
-      failures.push(
-        'the run never entered the operation and nothing denied it, so nothing about the operation was ' +
-          `measured and no refusal was proven either. What it answered was ${JSON.stringify(one.result)}`,
-      )
-    }
-
-    if (one.refused && one.measured) {
-      failures.push(
-        'this run was refused before the operation could start and REACHED THE OPERATION anyway — dispatch let a ' +
-          'refused request through to the compiled function, which is the gate not holding rather than a trial drifting',
-      )
-    }
-
-    if (older === undefined) {
-      failures.push('no trial holds this scenario. Run `thread trials` and commit the result')
-    } else {
-      for (const part of ['result', 'kept', 'called'] as const) {
-        const then = printed(older[part])
-        const said = printed(one[part])
-        if (then === said) continue
-        failures.push(
-          `${part} is not what was recorded — the operation's behaviour has changed.\n    was: ${then.trim().slice(0, 400)}\n    now: ${said.trim().slice(0, 400)}`,
-        )
-      }
-    }
-
-    outcomes.push({
-      id,
-      operation: one.operation,
-      passed: failures.length === 0,
-      refused: one.refused,
-      measured: one.measured,
-      failures,
-    })
-  }
-
-  for (const one of was) {
-    const id = `${one.operation}/${one.scenario}`
-    if (now.some((each) => `${each.operation}/${each.scenario}` === id)) continue
-    outcomes.push({
-      id,
-      operation: one.operation,
-      passed: false,
-      refused: one.refused,
-      measured: false,
-      failures: ['this scenario is recorded and no longer runs — an operation or a scenario was removed without the trials being regenerated'],
-    })
-  }
-
-  return {
-    outcomes,
-    passed: outcomes.filter((one) => one.passed).length,
-    failed: outcomes.filter((one) => !one.passed).length,
-    measured: outcomes.filter((one) => one.measured).length,
-  }
-}
-
-export function unproven(run: Run): readonly string[] {
-  const each = new Map<string, Outcome[]>()
-  for (const one of run.outcomes) {
-    const held = each.get(one.operation)
-    if (held === undefined) each.set(one.operation, [one])
-    else held.push(one)
-  }
-
-  const said: string[] = []
-  for (const [operation, outcomes] of [...each].sort((one, two) => compare(one[0], two[0]))) {
-    if (outcomes.some((one) => one.measured)) continue
-
-    const denied = outcomes.filter((one) => one.refused).length
-    const neither = outcomes.length - denied
-    const how = [
-      denied === 0
-        ? ''
-        : `${String(denied)} were refused before the operation could start — by the gate, or because what they were given is not what it takes — which proves the refusal and nothing whatever about the operation`,
-      neither === 0 ? '' : `${String(neither)} neither reached it nor were denied`,
-    ].filter((one) => one !== '')
-
-    said.push(
-      `\`${operation}\` is UNPROVEN — ${String(outcomes.length)} scenario(s) ran and not one of them reached it: ${how.join(', and ')}. ` +
-        'Grant a caller the trial can run as, or give it a scenario the gate admits',
-    )
-  }
-
-  return said
-}
-
-async function standIns(): Promise<Readonly<Record<string, string>> | string> {
-  const at = resolve(ROOT, '_threads/secrets.ts')
-  if (!existsSync(at)) return {}
-  let held: readonly { readonly id: string; readonly sends?: unknown; readonly signs?: unknown }[]
-  try {
-    const taken = (await import(pathToFileURL(at).href)) as {
-      readonly SECRETS?: readonly { readonly id: string; readonly sends?: unknown; readonly signs?: unknown }[]
-    }
-    held = taken.SECRETS ?? []
-  } catch (thrown) {
-    return (
-      `_threads/secrets.ts is there and could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}. ` +
-      'A secrets sheet that cannot be read reports exactly like an app that declares none, so every trial would run ' +
-      'as though nothing were sealed and pass having proved that'
-    )
-  }
-  const found: Record<string, string> = {}
-  for (const one of held) {
-    found[one.id] = one.sends === undefined && one.signs === undefined ? `https://${one.id.replace(/_/g, '-')}.invalid` : `${one.id}-stood-in-for`
-  }
-  return found
-}
-
-async function reaching(): Promise<{ readonly targets: readonly Target[]; readonly calls: readonly Call[] } | string> {
-  const at = resolve(ROOT, '_threads/targets.ts')
-  if (!existsSync(at)) return { targets: [], calls: [] }
-  try {
-    const taken = (await import(pathToFileURL(at).href)) as { readonly TARGETS?: readonly Target[]; readonly CALLS?: readonly Call[] }
-    return { targets: taken.TARGETS ?? [], calls: taken.CALLS ?? [] }
-  } catch (thrown) {
-    return (
-      `_threads/targets.ts is there and could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}. ` +
-      'Which disk a trial hands an operation is read from that sheet, so every trial would run with no disk at all and ' +
-      'the failures would name the operation instead of the sheet'
-    )
-  }
-}
-
-export async function record(): Promise<{ readonly trials: readonly Trial[]; readonly refusals: readonly string[] }> {
-  const pass = descend()
-  const known = types(pass)
-  const refusals: string[] = []
-  const trials: Trial[] = []
-
-  const declared = [...operations(pass, known)].filter(([, one]) => one.body !== undefined)
-  if (declared.length === 0) return { trials: [], refusals: [] }
-
-  const stood = await standIns()
-  if (typeof stood === 'string') return { trials: [], refusals: [stood] }
-
-  const reached = await reaching()
-  if (typeof reached === 'string') return { trials: [], refusals: [reached] }
-  const { targets, calls } = reached
-
-  const at = resolve(ROOT, DISPATCH_AT)
-  if (!existsSync(at)) {
-    return {
-      trials: [],
-      refusals: [
-        `this app has no ${DISPATCH_AT}. Run \`thread compile\` — an operation runs through dispatch and there is nothing here to run it with`,
-      ],
-    }
-  }
-  const made = (await import(pathToFileURL(at).href)) as {
-    readonly dispatch?: (
-      operation: Operation<unknown>,
-      input: unknown,
-      actor: Actor,
-      opened: Readonly<Record<string, unknown>>,
-      opening: Vault,
-    ) => Promise<Result<unknown>>
-  }
-  const dispatch = made.dispatch
-  if (dispatch === undefined) {
-    return { trials: [], refusals: [`${DISPATCH_AT} exports no \`dispatch\`, so nothing here can run an operation`] }
-  }
-
-  const permitted = resolve(ROOT, ACCESS_AT)
-  const may = new Map<string, string[]>()
-  if (existsSync(permitted)) {
-    const sheet = (await import(pathToFileURL(permitted).href)) as {
-      readonly GRANTS?: readonly {
-        readonly may?: readonly string[]
-        readonly to?: { readonly roles?: readonly string[] }
-      }[]
-    }
-    for (const one of sheet.GRANTS ?? []) {
-      for (const id of one.may ?? []) {
-        may.set(id, [...new Set([...(may.get(id) ?? []), ...(one.to?.roles ?? [])])])
-      }
-    }
-  }
-
-  const compiled = resolve(ROOT, PERMITS_AT)
-  const permits = existsSync(compiled)
-    ? ((await import(pathToFileURL(compiled).href)) as {
-        readonly permits?: (actor: Actor, action: string, resource: Row | null) => { allow: boolean; because?: string }
-      }).permits
-    : undefined
-  if (existsSync(compiled) && permits === undefined) {
-    return {
-      trials: [],
-      refusals: [`${PERMITS_AT} exports no \`permits\`, so a trial cannot be answered by the gate this app derives`],
-    }
-  }
-  for (const [id, one] of [...declared].sort((a, b) => compare(a[0], b[0]))) {
-    if (one.body === undefined) continue
-    const from = resolve(ROOT, one.body)
-    if (!existsSync(from)) {
-      refusals.push(`\`${id}\` derives ${one.body} and that file is not there. Run \`thread compile\``)
-      continue
-    }
-
-    const held = (await import(pathToFileURL(from).href)) as { readonly operation?: Operation<unknown> }
-    const operation = held.operation
-    if (operation === undefined) {
-      refusals.push(`${one.body} exports no \`operation\`, so \`${id}\` cannot be run`)
-      continue
-    }
-
-    const takes = one.takes[0]?.at
-    if (takes === undefined) {
-      refusals.push(`\`${id}\` names nothing it takes, so nothing states its input or what to try it with`)
-      continue
-    }
-
-    const scenarios = await scenariosFor(operation, takes, may.get(id) ?? [])
-    if (typeof scenarios === 'string') {
-      refusals.push(scenarios)
-      continue
-    }
-
-    for (const scenario of scenarios) {
-        const ran = await runScenario(operation, scenario, dispatch, stood, targets, calls)
-        if (typeof ran === 'string') refusals.push(ran)
-        else trials.push(ran)
-    }
-  }
-
-  return { trials, refusals }
-}
-
-function kept(): readonly Trial[] {
-  const at = resolve(ROOT, TRIALS_AT)
-  if (!existsSync(at)) return []
-  return JSON.parse(readFileSync(at, 'utf8')) as readonly Trial[]
-}
-
-if (invoked(import.meta.url)) {
-  const { trials, refusals } = await record()
-
-  for (const one of refusals) console.error(`trial: ${one}`)
-
-  if (argv.includes('--check')) {
-    const run = compared(kept(), trials)
-    for (const outcome of run.outcomes) {
-      if (outcome.passed) continue
-      for (const failure of outcome.failures) console.error(`trial: ${outcome.id} — ${failure}`)
-    }
-
-    if (run.outcomes.length === 0 && refusals.length === 0) {
-      console.log('trial: this app declares no operation, so there is nothing to prove.')
-      exit(0)
-    }
-
-    const short = unproven(run)
-    for (const one of short) console.error(`trial: ${one}`)
-
-    console.log(
-      `trial: ${String(run.passed)} of ${String(run.outcomes.length)} passed, ${String(run.measured)} measured, ` +
-        `${String(short.length)} operation(s) unproven.`,
-    )
-    exit(run.failed === 0 && refusals.length === 0 && short.length === 0 ? 0 : 1)
-  }
-
-  if (refusals.length > 0) {
-    console.error(
-      `trial: ${String(refusals.length)} refusal(s) above, so ${TRIALS_AT} is left as it was — ` +
-        'a run that was refused has nothing to record, and recording it would erase what does',
-    )
-    exit(1)
-  }
-
-  const at = resolve(ROOT, TRIALS_AT)
-  writeFileSync(at, printed(trials))
-  const measured = trials.filter((one) => one.measured).length
-  stdout.write(
-    `trial: wrote ${TRIALS_AT} — ${String(trials.length)} trial(s) from ${String(measured)} run(s) that reached an operation.\n`,
-  )
-  exit(0)
-}