@pikku/inspector 0.12.50 → 0.12.54

package/CHANGELOG.md

@@ -1,3 +1,746 @@
+## 0.12.54
+
+### Patch Changes
+
+- 62ea4cc: The audit trail is now readable — in the generated meta, through an RPC, and as
+  a page in the console.
+
+  `audit: true` reaches `FunctionRuntimeMeta.audit` as its resolved form
+  (`{ durability }`), so which functions record anything is answerable without
+  running them. It is informational: the runner still resolves audit from the live
+  function config, so meta and runtime cannot disagree.
+
+  `AuditService` grows an optional read side — `query(AuditQuery)` and `facets()`.
+  Optional because a sink can legitimately be write-only: a queue producer that
+  hands events to another system has nothing to read back, and a reader that finds
+  these absent should say the trail is not readable here rather than that it is
+  empty. The two are very different answers to give someone auditing a system.
+
+  `KyselyAuditService` implements both, newest first with offset paging, filtered
+  by user, action and time window. Two things it now gets right that are easy to
+  get wrong: an empty filter array means "match nothing" rather than "no filter",
+  and results are read by physical _and_ camelCase key, because `CamelCasePlugin`
+  is on most pikku Kysely instances and renames result keys on the way out — the
+  mismatch does not throw, it returns a page of `undefined`. `init()` creates the
+  `audit` table for projects that do not migrate it themselves, from a new
+  exported `auditSchema` that stays out of `pikkuSchemas` because the runtime does
+  not need it.
+
+  The console addon exposes `console:getAudits` and `console:getAuditFilters`
+  behind a new `pikku:audit:read` scope, and forwards the application's `audit`
+  service into the addon's own services — without that last part every install
+  reported the trail as unreadable, whatever sink it had configured.
+
+  The console gets an Audit trail page: an infinite list filtered server-side by
+  user and action, and a row that opens the whole event, metadata rendered as a
+  JSON tree. Refused, unreadable and empty are three different screens, because
+  "you may not read this", "nobody can read this" and "nothing happened" are three
+  different facts.
+
+  Events name the person who caused them. The trail records a user id — the only
+  thing stable enough to record, since a name can change after the event — so
+  `getAudits` resolves those ids against better-auth's user directory at read
+  time, and the page shows the name while keeping the recorded id on the event.
+  The filter follows: pick a colleague by name, filter by the id. A scenario
+  actor is labelled as one, so synthetic traffic is not mistaken for real, and a
+  caller who was signed out shows the wire identity pikku resolved for them
+  rather than being credited to the system.
+
+  **Breaking, for anyone already reading `AuditEvent`:** `actor` is now
+  `userIdentity`, and its type `AuditActor` is `AuditUserIdentity`; `AuditQuery`
+  takes `userIds`/`orgId` in place of `actorUserIds`/`actorOrgId`, and
+  `AuditFacets` returns `userIds`. In pikku an _actor_ is a synthetic person a
+  scenario drives, flagged on the user row — so naming the causer of an event
+  `actor` made the synthetic case unsayable (`actor.actor === true`) and implied
+  every recorded action was a test. The overwhelming majority are ordinary
+  customers. The `audit` table follows: `actor_user_id` / `actor_org_id`
+  are now `user_id` / `org_id`, and a `pikku_user_id` column joins them so the
+  wire identity of a caller who never signed in survives the round trip — the
+  sink was dropping it, which left the console's Session field permanently
+  blank. A project that already migrated the table needs to rename the two
+  columns and add the third; `KyselyAuditService.init()` creates the new shape
+  for anyone who did not.
+
+- 9dddff8: Split a column's at-rest form out of its classification.
+
+  `security: 'encrypted'` sat beside `'secret'` as though the two were
+  alternatives, which made the field unanswerable: a token hash and a live bearer
+  token are both secret, one must never be encrypted — the digest _is_ the lookup
+  key — and the other must always be. A column now carries a second, independent
+  `form: 'plain' | 'hashed' | 'wrapped' | 'sealed'` saying how the bytes are held.
+
+  Declaring a form other than `plain` makes the column's INSERT/UPDATE type
+  nominal — `WrappedValue`, `SealedValue`, `HashedValue` — so a plain string no
+  longer compiles there and the only way to write the column is with something an
+  encrypt, seal or hash call produced. `envelopeEncrypt`, `envelopeRewrap` and
+  `wrapDEK` now return the brand, and a new `hashToken` produces `HashedValue`, so
+  the round trip needs no casts; `column-form.ts` exports deliberately-named
+  `unsafeAs*` assertions for backfills, fixtures and values sealed elsewhere.
+  Reads are unaffected — the brands widen to `string` and compose with the
+  classification brand as `Secret<WrappedValue>`.
+
+  `wrapped` and `sealed` stay distinct because a sealed value is one the
+  application cannot read back; storing one where the other belongs is a row
+  nobody can open.
+
+  A `secret` column that has not declared a form now warns (PKU483), and a form on
+  a non-text column warns and is dropped (PKU484). Both are warnings, so existing
+  projects keep migrating — `pikku db --fail-on-warn` opts into the ratchet, and
+  an explicit `form: 'plain'` is the acknowledgement that silences it. The legacy
+  `security: 'encrypted'` keeps working and now expands to the pair it always
+  meant, `secret` + `wrapped`.
+
+- 9dddff8: Read schema-qualified annotations, and let a project name its default schema.
+
+  `DbClassificationMap` nests tables under their schema whenever a project sets
+  `db.schema`, but `loadAnnotations` read the sidecar as a flat table→column map.
+  It therefore took the schema for a table and each table for a column, found no
+  recognised fields, and dropped every annotation on the floor — so a project
+  could mark a column `secret` and watch it generate as `private`, with no error
+  anywhere. The parser now detects the extra level (a column entry's values are
+  primitives; a table's are objects) and flattens it, so both shapes load.
+
+  New `db.defaultSchema` drops one schema's qualifier from the generated types:
+  with `defaultSchema: 'app'`, `app.user` is queried as `selectFrom('user')` and
+  typed as `User` rather than `AppUser`, matching what a project whose
+  `search_path` already resolves the schema actually writes. Tables in other
+  schemas stay qualified. Where dropping the qualifier would make two tables
+  share a name, the table keeps its qualifier and the codegen warns (PKU485)
+  rather than letting one silently shadow the other — queries against the loser
+  would have typechecked against the wrong columns.
+
+  The generated key is what Kysely puts in the SQL, so this is opt-in and
+  separate from `db.schema`: setting it for a schema the connection does not
+  resolve gives you queries that compile and then fail to find their table.
+
+- 155528a: The PKU910 sessionless-output diagnostic advised marking a column `@public`, a
+  SQL-comment annotation syntax that no longer exists. Column classification is
+  sourced solely from the hand-authored `db/annotations.ts`, so the message now
+  points there.
+- 78b29f0: `SecretService` now returns a `SecretValue<T>` rather than the bare value, so a
+  vault secret cannot reach a sink by accident.
+
+  `SecretValue` is nominally typed, which means it is not assignable to `string`
+  (or to any other concretely-typed field). Every sink with a real type — a
+  database column, an email body, a session payload — rejects it with no lint
+  rule involved. The sinks typed `any`, `unknown`, or a free generic — the logger,
+  queue payloads, webhook and email inputs, and a function's own output — are
+  guarded with `Safe<T>`, which collapses a `SecretValue` found anywhere inside
+  `T`, however deeply nested, to `never`.
+
+  Unwrap deliberately at the point the secret reaches the wire:
+
+  ```ts
+  const secret = await secrets.getSecret('BETTER_AUTH_SECRET')
+  betterAuth({ secret: secret.reveal() })
+  ```
+
+  Two behaviours cover what types cannot see. Structured serialization redacts —
+  `JSON.stringify` and node's inspect both yield `[secret]`, so an audit or log
+  write stays honest without crashing the request. String coercion throws
+  `SecretCoercionError`, because a template literal is always a leak.
+
+  `AuditLog.write` is guarded the same way as the logger, since an audit event
+  carries `input` and `metadata` as `unknown` and nominality alone cannot stop a
+  secret landing in one.
+
+  `.reveal()` is the deliberate escape hatch, and what it hands back is an
+  ordinary string as far as every sink signature is concerned. **PKU953** closes
+  that gap: under `pikku all --security` the inspector reports a revealed secret
+  that flows into a logger, an audit, a queue, an email or a webhook — `console` included.
+
+  This also fixed a real one: `remote-addon-auth.ts` called `String(token)` on an
+  `unknown` and wrote the result straight into an `Authorization` header.
+
+- Updated dependencies [62ea4cc]
+- Updated dependencies [9dddff8]
+- Updated dependencies [78b29f0]
+  - @pikku/core@0.12.76
+
+## 0.12.53
+
+### Patch Changes
+
+- fd72e58: Drop `scenario.step` — a scenario step is now always a `given`, `when` or
+  `then`.
+
+  `step` rendered no keyword, which made it the phase to reach for whenever a
+  step did not obviously fit one of the three. That is exactly the step a reader
+  cannot check: a scenario is read by people deciding whether it describes the
+  behaviour they wanted, and a row that says what it does without saying whether
+  it is setup, action or claim tells them nothing to agree or disagree with. It
+  was also the escape hatch from the assertion lint — a scenario with no `then`
+  could be made to stop complaining by demoting its steps rather than by
+  asserting anything.
+
+  Replace `scenario.step(...)` with whichever of `given`, `when` or `then` the
+  step actually is. `then` is not a rename: it makes the step's bindings
+  witnesses rather than alternatives, so every declared surface runs and they
+  must agree.
+
+- d041d5b: Let a generated file declare scopes, roles and personas without taking the
+  single-declaration slot.
+
+  `defineScope`, `defineSystemRole` and `definePersonas` are one-per-codebase, and
+  the CLI generates declarations of its own — `user-admin.gen.ts` ships the whole
+  `admin` scope tree. Any project that scaffolded one therefore had two
+  declarations and failed codegen with PKU583, and the losing file's scopes were
+  dropped from the metadata rather than merged.
+
+  The rule exists to name the one place a person reads from and adds to, and
+  nobody adds to a file the next codegen run overwrites. A generated declaration
+  is still extracted; it just neither claims the slot nor collides with the app's
+  own.
+
+- fd72e58: Make personas a first-class surface rather than a detail of the test runner.
+
+  A persona is now read in three places — the knowledge base resolves `persona:`
+  URIs against it, scenarios cast it as an actor, and a virtual user runs as it —
+  so it gets its own page at `/personas` under a new **People** section in the
+  rail, alongside Users. The card is a profile: avatar, name, job title, computed
+  address, the system roles they hold, and how many scenarios cast them. Opening
+  one expands each role to the scopes it confers, which is the half of the picture
+  that explains a 403.
+
+  `definePersonas` takes an optional `avatarUrl` — any URL a browser can load.
+  Nothing is derived from the address: a persona's address is synthetic, so a
+  derived identicon would be the same shrug for everyone. Omitted, the console
+  keeps drawing the deterministic colour-and-icon avatar from the persona's id.
+
+- fd72e58: Read the actors that are not people on the personas page.
+
+  The platform — the app acting on itself, what `pikkuPlatformScenarioStep`
+  declares — now has a row of its own, alongside one per addon whose system a
+  step makes act. They sit behind a People / System / All filter that opens on
+  the people: a subject holds no roles and signs in as nobody, so leading with it
+  would put the rows nothing is authorized through above the ones that are.
+
+  The platform row is built in rather than derived. A project that has never
+  written a platform step still has a platform, and a card that appeared the
+  moment somebody declared their first step would read as a feature they had
+  switched on.
+
+  Also: PKU680 now counts `expectService`, `expectError` and `expectEventually`
+  as assertions. They are inline steps and carry no phase, so a scenario whose
+  only witness was a recorded service call was being told it never asserts.
+
+- 894b2f8: `defineScope` and `defineSystemRole` accumulate across call sites again. Only `definePersonas` is one-per-codebase.
+
+  The previous release made all three single-declaration constructs, which no project scaffolding user-admin could satisfy: the CLI generates a `defineScope` of its own in `user-admin.gen.ts` carrying the whole `admin` tree, and `@pikku/addon-console` spells the same tree out again, so a second hand-written declaration failed the build with PKU583 — and the losing file's scopes were dropped from the metadata rather than merged.
+
+  Exempting generated files would have reinstated exactly the ambiguity the rule removes, only for the files nobody can read the rule from. The real fix is for `admin` to be a default scope nobody declares, at which point the rule can come back for scopes and roles.
+
+  `definePersonas` is unaffected: nothing generates one, so its single call site stands.
+
+- dd19aa7: Drop `scopes` from sessionless functions, rename `selfAuthenticated`, and make both
+  escape hatches opt-in.
+
+  **`scopes` are gone from `pikkuSessionlessFunc`.** They are AND-ed and `verifyScopes`
+  fails closed on a session that does not exist, so every scope listed on a sessionless
+  function rejected the anonymous caller it exists to serve. `CorePikkuSessionlessFunctionConfig`
+  now states this once in core, and the generated `pikkuSessionlessFunc` / `pikkuVoidFunc`
+  configs derive from it — so the field is absent rather than subtracted.
+
+  `@pikku/addon-console`'s `installAddon` and `installOpenapiAddon` are now `pikkuFunc`.
+  Both set `auth: true` and `scopes: ['admin']`, and a test exercises that gate, so the
+  scopes were load-bearing — they only compiled as sessionless because the config accepted
+  a field it could not honour. No behaviour change: both already required a session.
+
+  **`selfAuthenticated` is now `permissionsInBody`.** It never described authentication:
+  what it records is that the permission check lives in the function body rather than in a
+  declared `permissions` entry.
+
+  **Both escape hatches must be opted into**, via a new `allow` block in
+  `pikku.config.json`:
+
+  ```json
+  "allow": { "permissionsInBody": true, "complexWorkflows": true }
+  ```
+
+  Unset means unavailable, and using the feature is a build error naming the flag that
+  would permit it — PKU576 for `permissionsInBody`, PKU643 for `pikkuWorkflowComplexFunc`.
+  Both trade something the tooling can inspect for something only a reader can verify: a
+  permission check buried in a body, or workflow steps that cannot be serialized into the
+  graph, replayed, or migrated. Both are occasionally right, and both are the path of least
+  resistance whenever the declarative form is merely inconvenient. Whoever owns the project
+  makes that call once, in writing, instead of every author making it silently at the call
+  site.
+
+  **PKU574's message no longer contradicts any of this.** Every function it reports is
+  sessionless — that is how the population is selected, not a finding — yet it opened by
+  reporting that they "require neither a session", then advised adding scopes. It now names
+  them as sessionless and recommends only gates an anonymous caller can meet:
+  `permissions`, `auth: true`, `wireAddon({ auth: true })`, or dropping `expose: true`.
+  `permissionsInBody` is deliberately absent from that list: a diagnostic should not
+  advertise its own escape hatch.
+
+- 50ec500: Make `defineScope`, `defineSystemRole` and `definePersonas` single-declaration constructs
+  — exactly one call site per codebase, the rule `pikkuBetterAuth` has always had.
+
+  Each of the three already takes a keyed object, so one call declares as many entries as
+  you like. Spreading the calls across files bought nothing and cost the thing that matters:
+  there was no answer to "where do I add a persona?", so downstream tooling and agents had
+  nowhere unambiguous to read from or append to. The only duplicate handling that existed
+  caught a narrow case — the same id declared twice with different content — and said
+  nothing about the same id declared twice in two files.
+
+  A second call now fails the build with `PKU583` (`defineScope`), `PKU584`
+  (`defineSystemRole`) or `PKU585` (`definePersonas`), naming both source files and saying
+  to declare them all in one call. A second call in the _same_ file is refused too: "the
+  file" is not an answer either when the file holds two calls.
+
+- Updated dependencies [32277d5]
+- Updated dependencies [ea8aabf]
+- Updated dependencies [33e96ab]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [894b2f8]
+- Updated dependencies [dd19aa7]
+- Updated dependencies [50ec500]
+  - @pikku/core@0.12.75
+
+## 0.12.52
+
+### Patch Changes
+
+- 8075f6a: Confine `SecretService` to the places an app is wired.
+
+  `secrets` is now omitted from the services every function, AI agent, workflow,
+  permission and wire receives, and the function runner replaces it with a
+  throwing accessor so a cast cannot reach past the type. It stays available in
+  `pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
+  read a secret there, give it to a service, and have the function ask that
+  service.
+
+  Alongside it:
+  - `wireSecret` gains `allowedHosts`, refusing a secret attached to a host it was
+    not declared for. Permissive by default; strict via
+    `config.secrets.requireAllowedHosts`.
+  - `pikku-graph`'s `httpRequest` resolves and attaches its credential inside a new
+    `httpRequester` service instead of holding the plaintext in the function.
+  - New inspector diagnostics: `PKU950` (a `SecretService` exposed under another
+    service name), `PKU951` (a secret read that no `wireSecret` declares) and
+    `PKU952` (a secret read with a non-literal key).
+
+- Updated dependencies [6a307f0]
+- Updated dependencies [afef587]
+- Updated dependencies [8075f6a]
+  - @pikku/core@0.12.74
+
+## 0.12.51
+
+### Patch Changes
+
+- c984df6: Give an agent's tools back the descriptions their authors wrote
+
+  A tool's description is what the model is told the tool does, and the main
+  thing it chooses between tools on. It was not reaching the model. `description`
+  is classed as a verbose field, so it is stripped from the metadata bundled into
+  the generated bootstrap — the copy `pikkuState('function', 'meta')` is built
+  from. `buildToolDefs` read the description from there, found it always
+  undefined, and fell through to the tool's own name. Every agent has been
+  choosing between bare identifiers. The same fallback was offering an addon's
+  MCP tools under their names, for the same reason.
+
+  Tool definitions now resolve descriptions through `metaService`, which reads
+  the verbose metadata and falls back to the minimal copy, so the authored text
+  is recovered wherever the generated `.pikku` directory is readable. Where it is
+  not — no `metaService`, or a deployment shipping only the stripped copy — a
+  tool falls back to its name, which is what it did before. Addon metadata is
+  likewise loaded verbose-first. `title` is no longer part of the chain: a title
+  labels a tool in a UI, it does not tell a model when to reach for it.
+
+  An addon has to ship the verbose file for any of this to reach it. `tsc` only
+  emits the JSON it sees imported and nothing imports the verbose meta, so the
+  bundled addons now copy it into `dist` explicitly.
+
+  `ref()` is resolved at build time. It used to be pushed through codegen as an
+  opaque string, so `ref('todos:doesNotExist')` generated cleanly and failed only
+  when the agent ran. The inspector now resolves each reference against the
+  project's functions, or — using the namespace-to-package mapping `wireAddon`
+  already provides — against the addon's own metadata, and reports an unwired
+  namespace (`PKU152`) or a missing function (`PKU153`) at codegen. An addon that
+  has not been built yet contributed no metadata and is skipped rather than
+  reported missing.
+
+  New `pikku --strict-meta` additionally fails the build on any agent tool with
+  no description (`PKU154`), including tools reached through an addon. It is off
+  by default, so nothing that builds today stops building; turn it on to hold a
+  project to the metadata its agents actually run on.
+
+- 63ff32b: Run a CLI's commands on the server, over the connection the client opened
+
+  A CLI that talks to a service has to ship the service's command tree, so the
+  two versions drift: the binary someone installed months ago still believes in
+  flags and commands the server has since changed. This makes the command tree
+  the server's, and leaves the client holding only a socket.
+
+  `wireCLI` gains `auth`, and a program wired with a channel entrypoint now
+  generates a `__raw` route: the client forwards argv untouched, the server
+  parses it, runs the command, and streams the output back as it happens. The
+  terminating frame carries the exit code, so a failed remote command still exits
+  non-zero locally. Renderers stay on the client and are matched by the command
+  id the server reports; an unrecognised command falls back to JSON rather than
+  failing.
+
+  Every channel gains `channel.remote(...)`: calling a function on the peer at
+  the other end of the connection and waiting for its answer. A channel is
+  otherwise fire-and-forget in both directions, so this is what reaches a peer
+  that has no address of its own — a CLI on a laptop, a browser tab, a sandbox
+  behind NAT. It is on `channel` rather than `rpc` because it is bound to one
+  connection: which peer answers is the socket the call goes out on, not
+  something the RPC map could resolve. Any `wireChannel` gets it — a client
+  registers what it is willing to answer to, and a name outside that list is
+  refused.
+
+  Requests are correlated by id, time out, and fail fast when the socket closes
+  rather than waiting out the timeout. Replies are taken off the socket ahead of
+  routing, so a channel needs no route for them and an answer can never be
+  mistaken for a new message; the transport is created on first use and released
+  when the channel closes, which is also what fails anything the departing peer
+  still owed an answer to. Channels that only flow one way — SSE, an agent's
+  output stream, a locally-run CLI — refuse the call outright instead of waiting
+  for an answer that was never going to come.
+
+  What a peer answers with is its word, so it is checked before a caller sees it
+  — against the schema codegen already generated from the function's declared
+  return type, the same one an agent tool or an HTTP response is checked against.
+  A capability is declared with `pikkuRemoteChannelFunc`, which takes the usual
+  `title` / `description` / `input` / `output` but no `func` — this side owns the
+  contract, the peer owns the body. It registers under its name like any other
+  function, so `channel.remote` is typed off the same generated map as
+  `rpc.remote` and no caller has to cast, and a local call throws rather than
+  missing: reaching it locally means a command asked the server for something
+  only a client knows. A client on an older build fails the call it answered
+  rather than the caller failing later somewhere with no reason to expect a bad
+  shape; a name with no declared contract is left alone. Both frame guards
+  validate the whole envelope rather than the action tag alone, and a failure
+  payload with a non-string name or message falls back rather than being attached
+  to an `Error`.
+
+  The arguments going the other way are checked too, against the schema for the
+  capability's declared input, before anything is registered or sent. That is not
+  a boundary — the peer runs the code and has to check what it was handed, and a
+  caller that meant harm would send arguments that pass. It catches drift, where a
+  server built against a newer capability signature calls a client that predates
+  it, and fails it here rather than inside someone else's process.
+
+  A channel-driven CLI command uses this to ask its caller for machine-local
+  facts mid-run — a git sha, a working tree, a local file. The CLI wire's own
+  channel is synthetic (it exists so a command can stream progress without
+  knowing where that goes), so it delegates `remote` to the connection the
+  command actually arrived on.
+
+  Because that runs code on someone's machine at a remote caller's request, the
+  capability map says what _can_ run and approval says whether a particular call
+  _should_. A capability may be declared `{ execute, needsApproval }`, sharing
+  `ApprovalPolicy` — `needsApproval` and `approvalDescriptionFn` — with
+  `AIAgentToolDef`, which has carried both since before channels could call back:
+  both are an allowlist of named callables invoked by something other than the
+  code that wrote them. The runtime around them is deliberately not shared, since
+  an agent suspends its run and resumes it later while a reverse call is a live
+  await with a person at the other end.
+
+  A capability written as a bare function is unclassified, and unclassified means
+  approval is required — the annotation nobody got round to writing is the one
+  most likely to matter, so it fails closed. Declare
+  `{ execute, needsApproval: false }` for a capability that may run unattended.
+  Nothing infers this: core cannot tell a read-only capability from a destructive
+  one, so `needsApproval: false` is the author asserting it, and the assertion is
+  the only thing standing between a remote caller and the machine.
+
+  The default is the opposite of `AIAgentToolDef`'s, where absence means "do not
+  ask" — a tool is written by the same people who run the server it executes on,
+  and a capability is not.
+
+  `executeRawCLIViaChannel` reads `--auto-approve` and
+  `--dangerously-auto-approve` out of argv (or `PIKKU_AUTO_APPROVE` /
+  `PIKKU_DANGEROUSLY_AUTO_APPROVE`) and strips them before argv reaches the
+  server — what may run on this machine is this machine's decision, and a flag
+  the server can see is one the server could act on. `--auto-approve` permits the
+  classified-safe set and refuses the rest; `--dangerously-auto-approve` permits
+  everything and says so once on stderr. Interactively the user is asked per
+  call, with `y` / `n` / `a`, where `a` is remembered for that one capability for
+  the rest of the run and never written to disk — widening it to the session
+  would quietly turn an interactive run into `--dangerously-auto-approve`. A run
+  with no terminal and no flag refuses rather than assuming yes, because CI is
+  exactly where an unattended `git push` would otherwise happen. The tiers are
+  meaningful here in a way they would not be for an agent: the caller is a
+  deterministic program whose source can be read, so "these calls are always
+  fine" is a claim someone can actually justify.
+
+  A peer that is asking a human sends a pending frame first, which stops the
+  caller's timeout. Without it any approval slower than the timeout would fail
+  the call and then discard the decision when it finally arrived. The call is
+  still failed the moment the socket drops — what actually happens when a peer
+  dies mid-prompt — and a peer that sends the frame dishonestly can do nothing
+  but keep its own call waiting. A refusal is sent as an answer, so a denied call
+  fails its command immediately rather than hanging.
+
+  Fixes found on the way, each of which broke this path:
+  - A websocket upgrade wrote middleware headers (CORS, on every request)
+    straight onto the socket, so the first bytes a client saw were headers rather
+    than `ws`'s `101` status line and the handshake failed to parse. Header
+    writes are now buffered and flushed behind a status line only when the
+    upgrade is actually being rejected.
+  - An upgrade socket had no error listener while the channel opened, so a client
+    that gave up mid-handshake took the whole server process down with an
+    unhandled `ECONNRESET`.
+  - `onConnect` and `onDisconnect` never saw the session established during the
+    upgrade, so a channel could not tell who had just connected.
+  - Setting the routing key on a channel result mutated the value in place, which
+    throws for a primitive under ESM strict mode.
+
+- a7b26c5: rename the inspected declarations to `define*`: `wireScope` → `defineScope`, `wireSecret` → `defineSecret`, `wireVariable` → `defineVariable`, `wireCredential` → `defineCredential`
+
+  `wire*` meant two unrelated things. A transport wiring attaches a function to
+  something that can invoke it — `wireHTTP`, `wireChannel`, `wireScheduler`,
+  `wireQueueWorker` and the rest — and the thing it wires runs. These four wire
+  nothing: they are no-ops that exist only so the call typechecks, they are
+  tree-shaken out of the build, and their whole job is to be found by the
+  inspector's AST pass and turned into a type union. One word for both left the
+  declaration reading like a registration with a runtime.
+
+  So the vocabulary splits: **`wire*` is a transport, `define*` is an inspected
+  declaration.**
+
+  ```ts
+  import { defineScope } from '@pikku/core/scope'
+  import { defineSecret } from '@pikku/core/secret'
+  import { defineVariable } from '@pikku/core/variable'
+  import { defineCredential } from '@pikku/core/credential'
+
+  defineScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+  ```
+
+  **Breaking:** no alias is kept. Rename the four call sites; the module subpaths
+  (`@pikku/core/scope`, `/secret`, `/variable`) are unchanged.
+
+  The inspector matches these by identifier text, so a stale `wire*` call is not a
+  type error — it is silently not extracted, and the generated union comes back
+  empty. That fails as "this scope isn't declared" on code that was fine a moment
+  ago, nowhere near the declaration. Grep for the old names rather than trusting a
+  clean build.
+
+  An addon published with `.pikku` output generated before this release re-exports
+  `wireSecret` from `@pikku/core/secret` and will not typecheck against this core
+  until it is rebuilt and republished.
+
+- 457cb25: Add `definePersonas()`: the people a project's scenarios and virtual users run
+  as, declared in code.
+
+  There used to be three names for two-and-a-bit things — an _actor_ in
+  `scenarios.actors`, a _persona_ in `scenarios.personas`, and a _virtual user_
+  declared separately against an actor. In practice almost every actor was its own
+  kind, so the second set carried no information and the third was a third place
+  for a name to drift. There is now one declaration:
+
+  ```ts
+  definePersonas({
+    shopper: {
+      name: 'Sam Shopper',
+      jobTitle: 'Shopper',
+      personality: 'Buys in a hurry and leaves tabs open',
+      roles: ['customer'],
+      disposition: 'careless',
+      goals: ['Buy something without reading anything'],
+      account: {},
+    },
+  })
+  ```
+
+  A persona is a person: what they are like, what they want, the roles they hold,
+  and **one** account they sign in with — `account: {}` plus `linkedAccounts` for
+  the rare case of more, modelled on how better-auth does linking. A persona with a
+  `disposition` is a virtual user; `runnable: false` marks someone who only ever
+  exists to be acted upon — banned, shared with, reset — and is never handed a
+  session.
+
+  **A persona names roles, never scopes.** Scopes come from `defineSystemRole()`
+  expansion, so the build fails if a persona names a role nobody declared, and
+  fails again if a role confers a scope no `defineScope` declares. Running one only
+  ever has to check that its roles are still valid.
+
+  **Addresses are computed, never declared.** `personaEmail(id, domain, runId)`
+  derives `<id>[+runId]@<domain>` from `scenarios.emailDomain`, so a seed, a
+  scenario run and a virtual-user run cannot disagree about who they are signing in
+  as. `scenarios.actors` and `scenarios.personas` are gone from
+  `pikku.config.json` — only `emailDomain` remains.
+
+  `actor` survives in exactly one place: the name of a **slot in a scenario step**,
+  which is the role a persona is cast in for that step. `pikkuVirtualUser()`,
+  `kind`, `grants` and the `actor` field are removed; the `actors` service is now
+  `personas`, and the CLI's `virtual-user` commands are now `pikku persona list` /
+  `pikku persona run`. `budget` and `allowApprovalRequired` moved to run flags —
+  how much you will spend today is not a fact about a person.
+
+  `@pikku/cucumber` drops its `Actor` class and `ActorDispatchContext`: a
+  hand-rolled cookie jar that a persona's own typed session replaces outright.
+
+- f7567ad: Add `defineSystemRole()`: roles that ship with the product, declared in code.
+
+  A system role is to a console-composed role what an AWS managed policy is to a
+  customer-managed one — the console may show and grant it, but not rename,
+  re-scope or delete it. The CLI extracts declarations by AST and generates a
+  `SystemRoleName` union, so naming a role that does not exist fails the build,
+  and a role granting a scope no `defineScope` declares fails it too.
+
+  Removal is additive on the same terms as `defineScope`: deleting a declaration
+  leaves an inert row rather than revoking everyone's grant mid-deploy.
+
+  `ScopeService` gains `syncSystemRoles`, `findStaleSystemRoles` and
+  `pruneSystemRoles`; `Role` gains `system` and `declared`. Implementations
+  enforce immutability through the shared `assertRoleIsMutable` /
+  `assertRoleNameAvailable` guards rather than each inventing the rule.
+
+- 457cb25: Let a persona do a real job in production, and say where it may act.
+
+  A persona was only ever a test subject: something you pointed at a stage to find
+  out what the product does wrong. But the same declaration — a name, a job, the
+  roles it holds and what it is trying to get done — describes a teammate doing
+  the work for real, and nothing about the engine cared which one it was.
+
+  Four changes make that difference explicit and enforced.
+
+  **`environments` moves to the top level of `pikku.config.json`**, out from under
+  `scenarios`. It was never a scenario's anything: `persona run` targets one, and
+  now so does `persona sync`. An environment may be flagged `production: true` —
+  a flag rather than a reserved name, because projects call it `prod`, `live` or
+  `eu-prod`, and more than one environment can be production.
+
+  **A persona may name its `environments`.** Omitting them means every configured
+  environment _except_ the production ones, so nothing reaches production by being
+  forgotten. Naming a production environment requires `disposition: 'accountable'`.
+  The rule is checked twice, on purpose: the inspector refuses to generate a
+  declaration that breaks it, and sign-in re-checks against the environment
+  actually resolved — the build check trusts the file, and the run check does not
+  trust which artifact got deployed. An unresolved environment fails closed.
+
+  **`disposition: 'accountable'`** is that production disposition. It sits opposite
+  `adversarial` on the intent axis rather than the care axis: what it changes stays
+  changed, every call is recorded against its name, and it stops to ask rather than
+  acting and reporting afterwards. Alongside it, **agents now appear in a persona's
+  computed catalogue**, gated by the same scopes as the RPCs — an agent is reached
+  rather than declared, so a persona finds the specialists its roles unlock and
+  chooses between calling the API itself and handing the work over. That also fixes
+  a latent gap: `talkTo` was wired at the target but never advertised in the
+  instructions, so it was never used.
+
+  **`pikku persona sync <environment>`** provisions them: it creates each account
+  and applies the roles it declares, additively, and never revokes. Seeding is test
+  data and `db seed` does not run in production; a teammate doing a real job still
+  needs an account and its grants. It needs both halves of an environment — its API
+  to sign the person in, its database to write the grants — and `--dry-run` reports
+  who would be provisioned, with what, and why anyone was skipped.
+
+  In the console, a virtual user now says where it may act — the environments it
+  named, or the rule when it named none — and its dossier carries the `sync`
+  command alongside the `run` one, because the account is not a by-product of a
+  run. `accountable` reads as a disposition like the rest.
+
+- 86a50b9: scenario: replace `browser: true` + `func` with per-surface bindings on `pikkuScenarioStep`
+
+  A step now declares one implementation per surface it can be driven through:
+
+  ```ts
+  export const buysTheItem = pikkuScenarioStep<{ sku: string }, { orderId: string }>({
+    name: 'buysTheItem',
+    description: 'buys the item',
+    browser: async (services, data, { browser }) => { ... },
+    default: async (services, data, { rpc }) => { ... },
+  })
+  ```
+
+  `pikku scenario run --run browser|cli|default` picks which surface the run drives,
+  and the two phases resolve bindings differently:
+  - **Actions** (`given` / `when` / `step`) run exactly one binding — the run
+    surface if it has one, otherwise `default`. A step with neither now fails with
+    `ScenarioNoSurfaceBinding` instead of silently running server-side.
+  - **Assertions** (`then`) are witnesses, not alternatives: every declared binding
+    runs and they must agree. Two surfaces reporting different things fails the run
+    with `ScenarioWitnessDisagreement` rather than reporting a pass. An assertion
+    with no witness the run can execute at all fails with `ScenarioNoWitness` —
+    without it the step returns `undefined` and renders as a tick, reporting a pass
+    for something nobody checked.
+
+  A scenario written as a step ladder that never calls `then` is now a **PKU680**
+  critical. It proves only that nothing threw, so an assertion-free ladder of
+  browser-bound actions would score perfect coverage while checking nothing.
+
+  The report gains a surface-coverage line — `n/m steps ran on browser`, counted
+  over every step, so an action that fell back to the server lowers the ratio
+  rather than needing a footnote. That also makes surfaces comparable over one
+  denominator: a scenario is `4/4` on a default run and `3/4` on a browser one.
+  Assertions that fell back are named separately and gate `--strict`, since a
+  sentence claiming the actor saw something nobody looked at is a different problem
+  from an action taking a shortcut.
+
+  **Breaking:** `browser: true` and the third `B extends boolean` type argument are
+  gone. Rename `func` to `default` (or to `browser` where the step drove a browser)
+  and drop the type argument.
+
+- 0e0f6eb: Add virtual users: LLM-driven synthetic users that work a real stage in
+  character.
+
+  A scenario proves a path somebody thought of. A virtual user works the same
+  ground without the script — it signs in as a declared persona over the app's own
+  auth, is handed the scenarios' BDD prose and the schema of every endpoint it may
+  reach, and decides for itself what to do. It asserts nothing; a run produces
+  findings, and their absence only ever means "not this time, not with this seed".
+
+  There is nothing extra to declare. A persona with a `disposition` is a virtual
+  user, and running it is what makes it one — see the `definePersonas` changeset
+  for the declaration itself. Listing, describing or running one never loads the
+  app: the inspector reads the literal declaration, the CLI writes
+  `scopes/pikku-personas-meta.gen.json`, and `MetaService.getPersonasMeta()`
+  serves it.
+
+  **Dispositions are engine dials, not prose.** Each carries its own intent weights
+  (continue / suspend / resume / abandon), temperature, re-read and repeat rates,
+  and switches: `careless` puts things down and picks them up in the wrong order,
+  `newcomer` starts with no memory, `auditor` is never offered a mutation,
+  `adversarial` is shown the catalogue its roles do not cover — being offered a
+  call it should not be able to make is the test — while those roles stay live as
+  the oracle, so a success outside them is authorization drift rather than a pass.
+
+  **Nothing is retrieved against.** The whole reachable catalogue goes into the
+  instructions (~8k tokens on a 430-RPC project, cached for the run), because a
+  ranking function would make the user only as adventurous as the ranking and lose
+  exactly the endpoints worth stumbling into. Schema first: an endpoint must be
+  described before it may be called.
+
+  **No money in core.** The engine counts steps, calls, mutations and tokens; what
+  they cost is the app's to decide through `stop(tally)`.
+
+  CLI: `pikku persona list` and `pikku persona run <environment> [name]`, with
+  flags overriding a declaration for reproduction (`--seed`, `--steps`,
+  `--disposition`). Spending is a run flag too — `--steps`, `--mutations` and
+  `--duration` bound a run, because how much you will spend today is not a fact
+  about a person. Console: a Virtual Users screen beside Scenarios, built out of
+  core's own derivation functions so it shows a run's actual inputs rather than a
+  second implementation of them.
+
+  `dev-ai-runner` now ships its own `@pikku/ai-vercel` and
+  `@ai-sdk/openai-compatible` instead of requiring them from the project. Behind a
+  proxy one openai-compatible provider answers for every prefix, so there was never
+  a per-vendor package worth making somebody install; the project's copies still
+  win when it has them, and both load from the same place or neither does.
+
+- Updated dependencies [c984df6]
+- Updated dependencies [63ff32b]
+- Updated dependencies [ba6cc08]
+- Updated dependencies [d007191]
+- Updated dependencies [a7b26c5]
+- Updated dependencies [457cb25]
+- Updated dependencies [f7567ad]
+- Updated dependencies [ba6cc08]
+- Updated dependencies [a2e21e5]
+- Updated dependencies [457cb25]
+- Updated dependencies [86a50b9]
+- Updated dependencies [0e0f6eb]
+  - @pikku/core@0.12.73
+
 ## 0.12.50
 
 ### Patch Changes