@pikku/core 0.12.74 → 0.12.77

package/src/wirings/rpc/remote-addon-auth.ts

@@ -1,5 +1,6 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
 import { PikkuError, addError } from '../../errors/error-handler.js'
+import { isSecretValue, type SecretValue } from '../../secret-value.js'
 
 export type RemoteAddonAuthBinding =
   | { credentialId: string }
@@ -8,7 +9,7 @@ export type RemoteAddonAuthBinding =
       resolve: (
         services: CoreServices,
         wire: PikkuRawWire
-      ) => string | Promise<string>
+      ) => string | SecretValue<string> | Promise<string | SecretValue<string>>
     }
 
 export class RemoteAddonAuthError extends PikkuError {
@@ -49,9 +50,13 @@ export async function resolveRemoteAddonToken(
     token = await auth.resolve(services, wire)
   }
 
-  if (token === null || token === undefined || token === '') {
+  // The wire is where a secret is meant to end up, so unwrap it here rather
+  // than at each branch — `resolve` and `getCredential` may hand one back too.
+  const resolved = isSecretValue(token) ? token.reveal() : token
+
+  if (resolved === null || resolved === undefined || resolved === '') {
     throw new RemoteAddonAuthError(namespace, 'resolved token was empty')
   }
 
-  return String(token)
+  return String(resolved)
 }

package/src/wirings/rpc/rpc-runner.test.ts

@@ -13,6 +13,7 @@ import {
 import { RemoteAddonAuthError } from './remote-addon-auth.js'
 import { wireAddon } from './wire-addon.js'
 import { wireRemoteAddon } from './wire-remote-addon.js'
+import { createSecretValue } from '../../secret-value.js'
 
 const createLogger = () => ({
   debug: () => {},
@@ -690,7 +691,7 @@ describe('ContextAwareRPCService.remote', () => {
 
 describe('multi-instance addons', () => {
   const createSecretService = () => ({
-    getSecret: async (key: string) => `secret:${key}`,
+    getSecret: async (key: string) => createSecretValue(`secret:${key}`),
     hasSecret: async () => true,
     setSecret: async () => {},
     deleteSecret: async () => {},
@@ -701,7 +702,7 @@ describe('multi-instance addons', () => {
     const createdServices: any[] = []
     pikkuState('@addon/slack', 'package', 'factories', {
       createSingletonServices: async (_config: any, parent: any) => {
-        const token = await parent.secrets.getSecret('slackToken')
+        const token = (await parent.secrets.getSecret('slackToken')).reveal()
         const svc = { logger: createLogger(), token }
         createdServices.push(svc)
         return svc
@@ -748,7 +749,7 @@ describe('multi-instance addons', () => {
         factoryCalls++
         return {
           logger: createLogger(),
-          token: await parent.secrets.getSecret('slackToken'),
+          token: (await parent.secrets.getSecret('slackToken')).reveal(),
         }
       },
     } as never)
@@ -854,7 +855,8 @@ describe('wireRemoteAddon dispatch', () => {
 
   const secretService = () =>
     ({
-      getSecret: async (key: string) => `secret-value-for-${key}`,
+      getSecret: async (key: string) =>
+        createSecretValue(`secret-value-for-${key}`),
       getSecrets: async () => ({}),
       hasSecret: async () => true,
       setSecret: async () => {},

package/src/wirings/virtual-user/index.ts

@@ -31,12 +31,24 @@ export type {
   VirtualUserTally,
   VirtualUserTarget,
 } from './virtual-user.types.js'
+export { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
 export {
   runVirtualUser,
   rememberIds,
   type RunVirtualUserParams,
   type VirtualUserCallContext,
 } from './run-virtual-user.js'
+export {
+  personaScopes,
+  prepareVirtualUserRun,
+  type VirtualUserPreparation,
+} from './prepare-virtual-user-run.js'
+export type {
+  VirtualUserRunOutcome,
+  VirtualUserRunRecord,
+  VirtualUserRunStart,
+  VirtualUserRunStore,
+} from './virtual-user-run-store.js'
 export {
   DISPOSITIONS,
   dispositionProfile,

package/src/wirings/virtual-user/prepare-virtual-user-run.test.ts

@@ -0,0 +1,115 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  personaScopes,
+  prepareVirtualUserRun,
+} from './prepare-virtual-user-run.js'
+
+const ROLE_DEFINITIONS = [
+  { name: 'editor', scopes: ['docs:write', 'docs:read'] },
+  { name: 'viewer', scopes: ['docs:read'] },
+]
+
+const FUNCTIONS_META = {
+  listDocs: { pikkuFuncName: 'listDocs', services: [], expose: true },
+  deleteDoc: { pikkuFuncName: 'deleteDoc', services: [], expose: true },
+} as any
+
+describe('personaScopes', () => {
+  test('expands the roles a persona declares into the scopes functions check', () => {
+    const scopes = personaScopes(
+      { roles: ['editor'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('a persona with no roles holds no scopes', () => {
+    assert.deepEqual(personaScopes({}, { editor: ['docs:write'] }), [])
+  })
+
+  // Two roles granting the same scope is ordinary, and the catalogue narrowing
+  // downstream compares scopes as a set.
+  test('de-duplicates overlapping roles', () => {
+    const scopes = personaScopes(
+      { roles: ['editor', 'viewer'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+        viewer: ['docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  // An undeclared role granting everything would be the worst possible default.
+  test('an unknown role grants nothing', () => {
+    assert.deepEqual(personaScopes({ roles: ['ghost'] }, {}), [])
+  })
+})
+
+describe('prepareVirtualUserRun', () => {
+  // The CLI reads the inspector state, which holds an array; the scaffolded RPC
+  // reads metaService, which hands the same definitions back keyed by name. Both
+  // callers must land on the same scopes or the same persona and seed explore a
+  // different API depending on how the run was started.
+  test('accepts role definitions as an array or keyed by name, identically', () => {
+    const asArray = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+    })
+    const asRecord = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: {
+        editor: ROLE_DEFINITIONS[0],
+        viewer: ROLE_DEFINITIONS[1],
+      } as any,
+    })
+    assert.deepEqual(asArray.scopes, asRecord.scopes)
+    assert.deepEqual(asArray.scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('derives the catalogue from the function meta', () => {
+    const { catalogue } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(catalogue.map((entry) => entry.name).sort(), [
+      'deleteDoc',
+      'listDocs',
+    ])
+  })
+
+  // An agent is reached rather than declared: its scopes are checked against the
+  // session, so a persona must find the specialists its roles unlock and no
+  // others.
+  test('narrows agents to the ones the persona s scopes reach', () => {
+    const agentsMeta = {
+      helper: { scopes: [] },
+      auditor: { scopes: ['docs:audit'] },
+    } as any
+
+    const { agents } = prepareVirtualUserRun({
+      persona: { roles: ['viewer'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+      agentsMeta,
+    })
+
+    assert.deepEqual(
+      agents.map((agent) => agent.name),
+      ['helper']
+    )
+  })
+
+  test('a project with no scenarios simply has no intents', () => {
+    const { intents } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(intents, [])
+  })
+})

package/src/wirings/virtual-user/prepare-virtual-user-run.ts

@@ -0,0 +1,95 @@
+import type { FunctionsMeta } from '../../types/core.types.js'
+import type { WorkflowsMeta } from '../workflow/workflow.types.js'
+import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.js'
+import type {
+  SystemRoleDefinitions,
+  SystemRoleDefinitionsMeta,
+} from '../role/role.types.js'
+import {
+  deriveCatalogue,
+  deriveIntents,
+  type SchemaMap,
+} from './virtual-user-derive.js'
+import {
+  reachableAgents,
+  type AgentReachability,
+  type ReachableAgent,
+} from './virtual-user-agents.js'
+import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js'
+
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export const personaScopes = (
+  persona: { roles?: readonly string[] },
+  roleScopes: Record<string, readonly string[]>
+): string[] => {
+  const scopes = new Set<string>()
+  for (const role of persona.roles ?? []) {
+    for (const scope of roleScopes[role] ?? []) {
+      scopes.add(scope)
+    }
+  }
+  return [...scopes].sort()
+}
+
+/** Everything a run needs that is derived rather than decided. */
+export interface VirtualUserPreparation {
+  /** Every RPC the app exposes, narrowed to what this persona can reach. */
+  catalogue: ApiCatalogueEntry[]
+  intents: IntentSource[]
+  scopes: string[]
+  agents: ReachableAgent[]
+}
+
+/**
+ * Derive what a virtual user needs from what the project already generates.
+ *
+ * Shared because there are two callers with the same problem and different
+ * sources for it: `pikku persona run` reads the inspector state at build time,
+ * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
+ * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * finds different things from the same seed, which is exactly the property a
+ * seed exists to give.
+ *
+ * Nothing here is authored for the virtual user's benefit: the function meta is
+ * the catalogue, the scenario meta is the intents, and the role definitions are
+ * what turn a persona's declared roles into the scopes a function checks.
+ */
+export const prepareVirtualUserRun = (input: {
+  persona: { roles?: readonly string[] }
+  functionsMeta: FunctionsMeta
+  schemas?: SchemaMap
+  workflowsMeta?: WorkflowsMeta
+  /**
+   * Either shape: the inspector holds an array, `metaService` hands back the
+   * same definitions keyed by name. Accepting both is what lets the CLI and the
+   * scaffolded RPC share this.
+   */
+  systemRoles?: SystemRoleDefinitions | SystemRoleDefinitionsMeta
+  agentsMeta?: Readonly<Record<string, AgentReachability>>
+}): VirtualUserPreparation => {
+  const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {})
+  const intents = deriveIntents(input.workflowsMeta ?? {}, input.functionsMeta)
+
+  const declared = input.systemRoles ?? []
+  const roleScopes: Record<string, string[]> = {}
+  for (const role of flattenSystemRoleDefinitions(
+    Array.isArray(declared) ? declared : Object.values(declared)
+  )) {
+    roleScopes[role.name] = role.scopes
+  }
+  const scopes = personaScopes(input.persona, roleScopes)
+
+  // Gated by the same scopes as the RPCs, because an agent is reached rather
+  // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+  // persona finds the specialists its roles unlock and no others.
+  const agents = reachableAgents(input.agentsMeta ?? {}, scopes)
+
+  return { catalogue, intents, scopes, agents }
+}

package/src/wirings/virtual-user/virtual-user-run-store.ts

@@ -0,0 +1,98 @@
+import type {
+  VirtualUserDisposition,
+  VirtualUserFinding,
+  VirtualUserTally,
+} from './virtual-user.types.js'
+
+/**
+ * One recorded run: who ran, what they were told, and what came back.
+ *
+ * A run is dispatched and answered for later, so the record is created before
+ * the work starts and is the thing the returned `runId` addresses.
+ *
+ * This record is a run's ONLY trace. A virtual user is not a workflow — it
+ * explores, so no two attempts take the same steps and there is nothing to
+ * replay — and it is not queued either, because the record already carries the
+ * progress a queue would only be holding on the way here.
+ *
+ * The cost of that is the one thing to know when reading `status`: a restart
+ * mid-run leaves a record at `running` with nothing left to finish it. A run
+ * older than its budget window and still `running` is dead, not working.
+ */
+export interface VirtualUserRunRecord {
+  runId: string
+  persona: string
+  disposition: VirtualUserDisposition
+  /** What makes a run replayable at all — a finding without it is an anecdote. */
+  seed: number
+  /**
+   * `running` until the engine returns. Not derived from `finishedAt` being
+   * unset: a crashed run has no finish time either, and the two are not the
+   * same result.
+   */
+  status: 'running' | 'completed' | 'failed'
+  /** The caller's situational goals, run alongside the derived intents. */
+  goals: string[]
+  /**
+   * Ids and slugs the user carried in, and whatever it learned on the way out.
+   * Kept because a finding only reproduces alongside the notes that produced it.
+   */
+  memory: Record<string, string>
+  findings: VirtualUserFinding[]
+  tally: VirtualUserTally | null
+  /** Which budget or stopping rule ended the run. */
+  stoppedBy: string | null
+  /**
+   * Why the run itself failed, as opposed to what it found. A run that could
+   * not start has no findings and is not a clean empty result.
+   */
+  error: string | null
+  /** The session that started it, where the host tracks one. */
+  startedBy: string | null
+  createdAt: Date
+  finishedAt: Date | null
+}
+
+/** What a run is created with — everything else is filled in by the outcome. */
+export interface VirtualUserRunStart {
+  persona: string
+  disposition: VirtualUserDisposition
+  seed: number
+  goals?: readonly string[]
+  memory?: Record<string, string>
+  startedBy?: string | null
+}
+
+/** The outcome of a run that reached the end of its budget without throwing. */
+export interface VirtualUserRunOutcome {
+  findings: readonly VirtualUserFinding[]
+  tally: VirtualUserTally
+  memory: Record<string, string>
+  stoppedBy: string | null
+}
+
+/**
+ * Where runs are kept. Declared here rather than in a database package so the
+ * scaffolded RPCs depend on the shape and not on kysely — `@pikku/kysely` ships
+ * one implementation, and an app with its own store satisfies this instead.
+ *
+ * SECURITY: findings from an `adversarial` run are working exploits carrying
+ * live ids. An implementation is a privileged store; the scaffold gates every
+ * read behind a scope for that reason, and a host exposing these records more
+ * widely is publishing its own exploits.
+ */
+export interface VirtualUserRunStore {
+  /** Records a run as `running` and returns its id. */
+  start(run: VirtualUserRunStart): Promise<string>
+  /** Marks a run `completed` and stores what it found. */
+  complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>
+  /** Marks a run `failed`. The run itself broke; it has no findings. */
+  fail(runId: string, error: string): Promise<void>
+  get(runId: string): Promise<VirtualUserRunRecord | null>
+  /** Newest first. `persona` narrows to one persona's history. */
+  list(options?: {
+    persona?: string
+    limit?: number
+    offset?: number
+  }): Promise<VirtualUserRunRecord[]>
+}

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -85,7 +85,7 @@ export type WorkflowWireDoInline = <T>(
 ) => Promise<T>
 
 /**
- * Type signature for scenario.step/given/when/then - used by inspector.
+ * Type signature for scenario.given/when/then - used by inspector.
  *
  * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
  * an imported symbol, so the extractor reads it as a literal.
@@ -199,7 +199,7 @@ export interface RpcStepMeta {
 }
 
 /**
- * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ * Scenario step metadata — a call to `scenario.given/when/then`.
  *
  * Distinct from RpcStepMeta on purpose: a step runs locally through
  * runPikkuFunc and must never be treated as dispatchable on the queue/replay
@@ -212,7 +212,7 @@ export interface ScenarioStepMeta {
   stepName: string
   /** Registered name of the step function being run */
   stepFunc: string
-  /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+  /** Which keyword the reporter prefixes — Given, When or Then */
   phase: ScenarioStepPhase
   /** Output variable name (if assigned) */
   outputVar?: string
@@ -557,20 +557,14 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
   ) => Promise<void>
 
   /**
-   * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
-   * `(stepName, target, data, options)` — so the inspector reads the target as
-   * a string literal rather than resolving an imported symbol.
+   * Run a registered scenario step, as the setup the scenario starts from.
+   *
+   * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
+   * so the inspector reads the target as a string literal rather than resolving
+   * an imported symbol.
    *
    * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
    */
-  step(
-    stepName: string,
-    stepFunc: string,
-    data?: any,
-    options?: ScenarioStepOptions
-  ): Promise<any>
-
-  /** `step` with a "Given" prefix in the rendered prose */
   given(
     stepName: string,
     stepFunc: string,
@@ -578,7 +572,7 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: ScenarioStepOptions
   ): Promise<any>
 
-  /** `step` with a "When" prefix in the rendered prose */
+  /** `when`: the same call as `given`, rendered as the action under test */
   when(
     stepName: string,
     stepFunc: string,
@@ -586,7 +580,11 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     options?: ScenarioStepOptions
   ): Promise<any>
 
-  /** `step` with a "Then" prefix in the rendered prose */
+  /**
+   * `then`: a claim about what the action left behind. Unlike `given`/`when`
+   * this is not prose alone — the step's bindings become witnesses, so every
+   * declared surface is observed and the observations must agree.
+   */
   then(
     stepName: string,
     stepFunc: string,

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -649,20 +649,11 @@ export class PikkuScenarioService implements WorkflowRunExtension {
       },
 
       // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-      // `given`/`when`/`step` are sugar for each other, differing only in the
+      // `given`/`when` are sugar for each other, differing only in the
       // prose a reporter renders. `then` is not: the phase is what decides
       // whether the step's bindings are alternatives or witnesses, so the same
       // step function called two ways runs differently. See
       // {@link resolveScenarioSurfaces}.
-      step: (stepName, stepFunc, data, options) =>
-        this.scenarioStep(
-          'step',
-          scenarioStepContext(),
-          stepName,
-          stepFunc,
-          data,
-          options
-        ),
       given: (stepName, stepFunc, data, options) =>
         this.scenarioStep(
           'given',

package/src/wirings/workflow/scenario-prose.test.ts

@@ -110,14 +110,14 @@ describe('composeStepProse basics', () => {
     )
   })
 
-  test('the neutral `step` phase adds no keyword', () => {
+  test('every phase renders its keyword', () => {
     assert.equal(
       composeStepProse({
-        phase: 'step',
+        phase: 'when',
         description: 'refreshes the dashboard',
         actor: 'admin',
       }),
-      'the admin refreshes the dashboard'
+      'When the admin refreshes the dashboard'
     )
   })
 
@@ -127,7 +127,6 @@ describe('composeStepProse basics', () => {
         { phase: 'given', description: 'buys an apple' },
         { phase: 'when', description: 'checks out' },
         { phase: 'then', description: 'sees a receipt' },
-        { phase: 'step', description: 'waits' },
       ] as const
     ).map((step) =>
       composeStepProse({ ...step, actor: 'shopper', keywordWidth: 5 })
@@ -137,7 +136,6 @@ describe('composeStepProse basics', () => {
       'Given the shopper buys an apple',
       'When  the shopper checks out',
       'Then  the shopper sees a receipt',
-      '      the shopper waits',
     ])
     const columns = new Set(rendered.map((line) => line.indexOf('the shopper')))
     assert.equal(columns.size, 1, 'every sentence starts in the same column')
@@ -145,8 +143,8 @@ describe('composeStepProse basics', () => {
 
   test('prose degrades to just the description when nothing else is known', () => {
     assert.equal(
-      composeStepProse({ phase: 'step', description: 'does the thing' }),
-      'does the thing'
+      composeStepProse({ phase: 'when', description: 'does the thing' }),
+      'When does the thing'
     )
   })
 })

package/src/wirings/workflow/scenario-prose.ts

@@ -37,7 +37,7 @@ export const composeStepProse = ({
   actor?: string
   keywordWidth?: number
 }): string => {
-  const keyword = phase === 'step' ? '' : capitalise(phase)
+  const keyword = capitalise(phase)
   const subject = actor ? `the ${actor}` : ''
   const rendered = template ? renderStepTemplate(template, input) : description
   const sentence = [subject, rendered].filter(Boolean).join(' ')

package/src/wirings/workflow/scenario-service.test.ts

@@ -21,7 +21,6 @@ const SCENARIO_MEMBERS = [
 ]
 
 const SCENARIO_WIRE_MEMBERS = [
-  'step',
   'given',
   'when',
   'then',

package/src/wirings/workflow/scenario-step.test.ts

@@ -155,7 +155,7 @@ const registerStep = (
   } as any
 }
 
-describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
+describe('pikkuScenarioStep (scenario.given/when/then)', () => {
   beforeEach(() => resetPikkuState())
 
   test('the step func is called with the phase, step identity and data on the wire', async () => {
@@ -202,12 +202,11 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    await wire.step('a', 'noop')
     await wire.given('b', 'noop')
     await wire.when('c', 'noop')
     await wire.then('d', 'noop')
 
-    assert.deepEqual(phases, ['step', 'given', 'when', 'then'])
+    assert.deepEqual(phases, ['given', 'when', 'then'])
   })
 
   test('the actor is handed to the step rather than used to dispatch it', async () => {
@@ -291,7 +290,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    const result = await wire.step('waits for the page', 'flaky', undefined, {
+    const result = await wire.when('waits for the page', 'flaky', undefined, {
       retries: 3,
       retryDelay: 1,
     })
@@ -509,7 +508,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     await assert.rejects(
-      (wire.step as any)('a name', async () => 'inline'),
+      (wire.when as any)('a name', async () => 'inline'),
       /string/i
     )
   })

package/src/wirings/workflow/scenario-step.types.ts

@@ -4,15 +4,21 @@ import type { ScenarioPersona } from '../../services/personas-service.js'
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then'
+export type ScenarioStepPhase = 'given' | 'when' | 'then'
 
 /**
  * Who acts in a step.
@@ -51,7 +57,7 @@ export const SCENARIO_SURFACES: readonly ScenarioSurface[] = [
 /**
  * How a step's declared surfaces resolve for one run.
  *
- * `given`/`when`/`step` bindings are **alternatives** — clicking Buy and calling
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
  * `createOrder` are two ways to cause one effect, so exactly one runs.
  *
  * `then` bindings are **witnesses** — "the order row says paid" and "the
@@ -86,7 +92,7 @@ export type ScenarioSurfaceResolution =
     }
 
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps