@pikku/core 0.12.117 → 0.12.120

package/CHANGELOG.md

@@ -1,3 +1,98 @@
+## 0.12.120
+
+### Patch Changes
+
+- 4a9dcd2: `admin:listUsers` now pages, counts and can carry roles.
+
+  `ListUsersInput` gains `offset` and `includeRoles`; `ListUsersOutput` gains `total`, and each `User` gains `roles` and `fields`. `total` is how many users match `search`, which is what a pager counts against — `users.length` never was, because it is capped by `limit`.
+
+  ```typescript
+  const { users, total } = await rpc.invoke('admin:listUsers', {
+    search: 'example.com',
+    limit: 50,
+    offset: 50,
+    includeRoles: true,
+  })
+  ```
+
+  Paging only means something over a stable order, so the query now sorts newest first rather than however the database felt like returning rows.
+
+  Synthetic principals — the platform credential owner, Fabric service users, scenario actors — are excluded by the query instead of dropped from the page afterwards. Filtering after the fact broke both halves of paging: `limit` had already counted the rows it then discarded, so a page came back short, and `offset` skipped synthetic rows as though they were people, so the same person could appear on two pages or on none.
+
+  `includeRoles` is refused without `admin:scopes:read`. `admin:users:list` says who may see the directory; it does not say who may see what each of those users can do.
+
+  `ScopeService` gains `listRolesForUsers(userIds)`, implemented in `@pikku/kysely`. It answers for every id asked for — an empty array for a user holding no roles, so a caller cannot read a missing key as "holds nothing" — and chunks its `in` list to stay inside the bound-parameter cap. A page of users used to cost one query per row, which on a database reached over the network is a round trip per row.
+
+  ```typescript
+  listRolesForUsers(userIds: string[]): Promise<Record<string, string[]>>
+  ```
+
+  Anything implementing `ScopeService` outside this repository has to add it.
+
+- 5ab24ad: Scenario recordings can be followed by eye, at no cost to the run. The encode holds each browser step's starting screen, and the last frame, for two seconds (`E2E_VIDEO_STEP_HOLD_MS`, `0` to turn off). The step offsets in the run record account for the holds. Recordings are made at the viewport's own size instead of Playwright's 800px downscale, and they show a pointer that follows the mouse and jumps to each filled field. Drivers get an optional `ScenarioBrowserProvider.markVideoStep(actor)`, which returns a step's offset in the finished video. It is preferred over `videoStartedAt`.
+- 42b7ac3: The app decides which of an addon's functions `rpc.exposed` reaches
+
+  `wireAddon` takes `expose?: boolean | string[]`, mirroring `mcp`. Unset or
+  `true` keeps the functions the addon declared `expose: true`; `false` exposes
+  none of the instance's functions; a list names exactly the functions to expose,
+  whether or not the addon declared them, typed against the addon's function
+  names. A listed name the addon does not publish fails the build with PKU343, a value that is not written inline fails it with
+  PKU344,
+  and the deploy analyzer's per-addon unit carries only what the wiring exposes.
+
+## 0.12.119
+
+### Patch Changes
+
+- e85f07e: A route declaring a numeric parameter could not be called over a query string. `coerceTopLevelDataFromSchema` converted an `array` from a comma-separated string and a `date-time` from text, but left numbers alone — and because the JSON Schema check runs before zod, `?year=2027` was rejected as `Instance type "string" is invalid. Expected "integer"` before the function ever ran. `z.coerce.number()` does not help: it runs after the schema has already refused. The shipped validator is spec-compliant and has no `coerceTypes` of its own, and `minimum`/`maximum` cannot stand in for one, being value constraints that apply only to instances that are already numbers.
+
+  `integer` and `number` now coerce from a string, on the same path as the two existing cases — so query strings, path params and argv reach a numeric parameter.
+
+  A string converts only when the number it produces prints back as the identical text. That rules out the readings that quietly rewrite the input — `007`, `+5`, `1e3`, `2027.50`, a padded `12` — and the values `Number` invents from nothing, where `''` and `'  '` both become `0`. It also rules out `9007199254740993`, which does not survive a double: a caller who sends an id as a string is usually doing so precisely because it does not, and rounding it silently would be data corruption. `NaN` and `Infinity` are refused for the same reason, and a fraction is refused where `integer` was asked for. Everything refused is left exactly as it arrived, so the validator reports the value the caller actually sent.
+
+  Note that this applies wherever the existing coercions already applied, which includes a JSON body — a string `"2027"` for a numeric field is now accepted there too, consistently with how an array and a `date-time` have always been read. A union `type` such as `['integer', 'null']` is left alone, as the array and `date-time` cases already leave it.
+
+## 0.12.118
+
+### Patch Changes
+
+- b4a895e: A scenario step row now carries where it fell inside each actor's recording, and a scenario result now says which feature it came from by id as well as by title.
+
+  The video offset is recorded rather than estimated. Documentation built out of a run has to turn a step sentence into an exact moment — a chapter marker, or a still pulled with `ffmpeg -ss` — and the only number available until now was the scenario clock summed out of the ladder. That clock is not the video's: recording starts when the actor's browser context opens, which is somewhere after step one, and every RPC step before or between the browser ones burns scenario time while the file sits still. The two drift apart by however much of the scenario happened off camera, and a still forty seconds out is a picture of the wrong screen with nothing to say it is wrong.
+
+  So `ScenarioStepRow.video` is stamped at the moment the step runs, from the driver's own clock: `ScenarioBrowserProvider.videoStartedAt(actor)` reports when that actor's context was opened with `recordVideo`, and the runner subtracts. It is a list of `{ actor, offsetMs }` rather than one number, because a video belongs to an actor and not to the scenario — one step touching two windows falls at a different moment in each, and an offset that does not name its file cannot be seeked to. A run without video, a step with no actor, and a step that never ran all carry nothing, which is what keeps the console's existing estimate as the fallback for runs recorded before this.
+
+  `ScenarioResult.featureId` is the other half of the same problem. `feature` is a title written for people to read and rewritten whenever the wording improves, so nothing downstream could key off it; the id `addFeature` registered the feature under does not move. The runner threads it from the plan, which read it off the registry, instead of deriving it from the label. `scenarioName` already carried the registration id and keeps it.
+
+- b4a895e: `pikku scenario guide` writes the user guide a scenario suite already contains. A feature reads as a page and a scenario as a section, and a run leaves screenshots behind with the captions their author took them under — the command joins that to the editorial prose a project checks in under `docs/` and writes markdown. It renders no HTML, ships no components, resolves no asset URLs and calls no model: an image is an ordinary relative `![caption](path)`, and whoever consumes the markdown rewrites the paths.
+
+  A page cites a feature by leaving the marker pair where the block belongs:
+
+  ```markdown
+  ---
+  title: Deployments
+  ---
+
+  A deployment is one tracked shipment of your app.
+
+  <!-- pikku:guide feature=deploymentsFeature -->
+  <!-- /pikku:guide -->
+
+  ## Does my app go down during a deploy?
+  ```
+
+  That one line does both halves of the job. It says _where_ the block goes, which a frontmatter list cannot express, and it is what the coverage gate counts to decide _whether_ a feature is documented at all. The mapping stays many-to-many and falls out of the union of every marker in the tree. A rebuild rewrites exactly the regions between the markers, so every sentence a human wrote around them survives.
+
+  **The steps are evidence, not content.** A generated block is the scenario's title, the description its author wrote, and the shots it filed — never a numbered Given/When/Then ladder, which is a test report and not something anybody arrives at a documentation page wanting. The sentences are still what the guide is kept honest against: `docs/.guide.lock` records a hash of each feature's step sentences and artifact ids, deliberately not of the image bytes. Restyling a UI changes every screenshot and no sentence; inserting or renaming a step changes what the prose was describing, and the page is reported stale. The lock is generated and checked in, so no hash is ever typed or merged by hand — and a tree whose lock is untracked reports every page as current forever.
+
+  Every registered feature has to be cited by some page, and a feature that is pure plumbing says so rather than being written about — `pikkuFeature({ document: false })`, threaded through the inspector and `FeatureMeta`. An uncited feature fails the command by name; `--allow-undocumented` downgrades that one failure to a report. A page citing a feature id that is not registered stays an error either way.
+
+  A guide is only written out of a run that can stand behind it. A run that failed or was killed halfway is refused, because a page is a claim that the product does what it says. So is a narrowed one: `pikku scenario run --flows`/`--features`/`--tags` leaves out scenarios the suite has, and a guide built from it would describe those flows as though they do not exist. `ScenarioRunRecord.selection` records the filters a run was selected with, since nothing in the results afterwards can tell a suite of forty from forty that were asked for.
+
+  Results are joined to features by `featureId`, falling back to the display name only for records written before that field existed — a title is rewritten freely and two features may share one.
+
+  Emission is deterministic — identical inputs give byte-identical output, and no timestamp goes in that did not come from the run record. Frontmatter the compiler does not own (`slug`, `draft`, `sidebar_position`, anything else a docs site reads) passes through untouched, and a source written with CRLF line endings is read as having frontmatter.
+
 ## 0.12.117
 
 ### Patch Changes

package/dist/schema.js

@@ -77,6 +77,41 @@ export const applyDefaultsFromSchema = (schemaName, data, packageName = null) =>
     }
     return result;
 };
+/**
+ * A query string and an argv array carry numbers as text, and the JSON Schema
+ * check runs first — so without this a route declaring `year: number` can never
+ * be called at all: `?year=2027` is rejected as `Instance type "string" is
+ * invalid` long before zod or the function body get a look at it. The shipped
+ * validator is spec-compliant and has no `coerceTypes` of its own, so the
+ * conversion has to happen here.
+ *
+ * The rule is that a coerced value must be the *same* value, not merely a
+ * plausible reading of it. So a string converts only if the number it produces
+ * prints back as the identical text. That is a stronger test than it looks: it
+ * is what stops `9007199254740993` from silently becoming ...92, which is the
+ * one failure mode leniency cannot excuse, because a caller who sends an id as
+ * a string is usually doing it precisely because the number does not survive a
+ * double. It also rules out every reading that quietly rewrites the input —
+ * `007`, `+5`, `1e3`, `2027.50`, a padded ` 12 ` — along with the values
+ * `Number` invents out of nothing, where `''` and `'  '` both become 0.
+ *
+ * Anything it rejects is left exactly as it arrived, so the validator reports
+ * the value the caller actually sent rather than one this function made up.
+ * Erring that way costs a loud 422 on an odd-looking but legal input; erring
+ * the other way corrupts data in silence.
+ */
+const coerceNumeric = (value, integer) => {
+    const parsed = Number(value);
+    // Rejects NaN and Infinity, both of which would otherwise round-trip through
+    // String() unchanged, and neither of which JSON can carry anyway.
+    if (!Number.isFinite(parsed))
+        return value;
+    if (String(parsed) !== value)
+        return value;
+    if (integer && !Number.isInteger(parsed))
+        return value;
+    return parsed;
+};
 export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = null) => {
     const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);
     if (!schema?.properties)
@@ -96,6 +131,10 @@ export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = nul
         else if (type === 'string' && property.format === 'date-time') {
             data[key] = new Date(data[key]);
         }
+        else if ((type === 'integer' || type === 'number') &&
+            typeof data[key] === 'string') {
+            data[key] = coerceNumeric(data[key], type === 'integer');
+        }
     }
 };
 /**

package/dist/services/scope-service.d.ts

@@ -57,6 +57,19 @@ export interface ScopeService {
     addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
     removeUserFromRole(userId: string, role: string): Promise<void>;
     listUserRoles(userId: string): Promise<string[]>;
+    /**
+     * The roles held by each of `userIds`, keyed by user id.
+     *
+     * Every id asked for comes back as a key, holding an empty array when the
+     * user has no roles — so a caller can index the result directly and cannot
+     * mistake "this user was not in the answer" for "this user holds nothing".
+     *
+     * Exists because listing a page of the user directory otherwise costs one
+     * query per row. Against a database reached over the network — which is the
+     * normal case for a deployed unit — that is a round trip per user, so a page
+     * of fifty is fifty of them.
+     */
+    listRolesForUsers(userIds: string[]): Promise<Record<string, string[]>>;
     /** Grants outside of any role; additive with the user's role-derived scopes. */
     addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
     removeScopeFromUser(userId: string, scope: string): Promise<void>;

package/dist/types/state.types.d.ts

@@ -37,6 +37,8 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
+            /** Which functions `rpc.exposed` may call: unset/`true` keeps the addon's own `expose`, `false` none, a list exactly those */
+            expose?: boolean | string[];
             /** Required of every function in this package, on top of the function's own */
             scopes?: string[];
             /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */

package/dist/wirings/addon/wire-addon.d.ts

@@ -16,6 +16,16 @@ export type WireAddonConfig = {
      * and is typed against the addon's function names.
      */
     mcp?: boolean | string[];
+    /**
+     * Which of the addon's functions `rpc.exposed` may call, under
+     * `<name>:<function>`. Unset or `true` keeps the functions the addon itself
+     * declared `expose: true`; `false` exposes none of them; a list names exactly
+     * the functions to expose, whether or not the addon declared them, and is
+     * typed against the addon's function names.
+     *
+     * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+     */
+    expose?: boolean | string[];
     /**
      * Serves this addon's MCP tools on an endpoint of their own rather than
      * folding them into the project's single `/mcp`. `true` mounts them at
@@ -62,6 +72,14 @@ export type WireAddonConfig = {
  * @example snippet: addonWiring
  */
 export declare const wireAddon: (config: WireAddonConfig) => void;
+/**
+ * Whether `rpc.exposed` may reach an addon function through the instance that
+ * resolved it. The wiring's `expose` decides when it is `false` or a list;
+ * otherwise the addon's own `expose: true` does.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export declare const isAddonFunctionExposed: (expose: boolean | string[] | undefined, functionName: string, declaredExpose: boolean | undefined) => boolean;
 /**
  * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
  */

package/dist/wirings/addon/wire-addon.js

@@ -12,6 +12,7 @@ export const wireAddon = (config) => {
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,
         tags: config.tags,
+        ...(config.expose !== undefined ? { expose: config.expose } : {}),
         ...(config.scopes ? { scopes: config.scopes } : {}),
         ...(config.secretOverrides
             ? { secretOverrides: config.secretOverrides }
@@ -32,6 +33,22 @@ export const wireAddon = (config) => {
             : {}),
     });
 };
+/**
+ * Whether `rpc.exposed` may reach an addon function through the instance that
+ * resolved it. The wiring's `expose` decides when it is `false` or a list;
+ * otherwise the addon's own `expose: true` does.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export const isAddonFunctionExposed = (expose, functionName, declaredExpose) => {
+    if (Array.isArray(expose)) {
+        return expose.includes(functionName);
+    }
+    if (expose === false) {
+        return false;
+    }
+    return declaredExpose === true;
+};
 /**
  * The addon configs a running function is governed by: the named instance when
  * the caller resolved one, every instance of the package otherwise.

package/dist/wirings/rpc/rpc-runner.js

@@ -1,5 +1,6 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
+import { isAddonFunctionExposed } from '../addon/wire-addon.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
@@ -110,10 +111,11 @@ export class ContextAwareRPCService {
     }
     async rpcExposed(funcName, data) {
         let functionMeta;
+        let resolvedAddon = null;
         if (funcName.includes(':')) {
-            const resolved = resolveNamespace(funcName);
-            if (resolved) {
-                functionMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
+            resolvedAddon = resolveNamespace(funcName);
+            if (resolvedAddon) {
+                functionMeta = pikkuState(resolvedAddon.package, 'function', 'meta')[resolvedAddon.function];
             }
         }
         else {
@@ -121,12 +123,24 @@ export class ContextAwareRPCService {
             functionMeta = pikkuState(resolved.packageName, 'function', 'meta')[resolved.pikkuFuncId];
         }
         if (!functionMeta) {
-            if (funcName.includes(':') && this.services.deploymentService) {
+            // The addon runs in another deploy unit, which only carries the
+            // functions the analyzer found exposed. A wiring present here still
+            // gets to narrow what is forwarded.
+            const refusedHere = resolvedAddon &&
+                (resolvedAddon.addonConfig.expose === false ||
+                    (Array.isArray(resolvedAddon.addonConfig.expose) &&
+                        !resolvedAddon.addonConfig.expose.includes(resolvedAddon.function)));
+            if (funcName.includes(':') &&
+                this.services.deploymentService &&
+                !refusedHere) {
                 return await this.rpc(funcName, data);
             }
             throw new RPCNotFoundError(funcName);
         }
-        if (!functionMeta.expose || functionMeta.scenarioStep) {
+        const exposed = resolvedAddon
+            ? isAddonFunctionExposed(resolvedAddon.addonConfig.expose, resolvedAddon.function, functionMeta.expose)
+            : functionMeta.expose;
+        if (!exposed || functionMeta.scenarioStep) {
             throw new RPCNotFoundError(funcName);
         }
         return await this.rpc(funcName, data);

package/dist/wirings/rpc/rpc-types.d.ts

@@ -45,6 +45,8 @@ export interface ResolvedFunction {
         package: string;
         auth?: boolean;
         tags?: string[];
+        /** Set by the consuming app: which functions `rpc.exposed` may call */
+        expose?: boolean | string[];
         rpcEndpoint?: string;
         secretOverrides?: Record<string, string>;
         variableOverrides?: Record<string, string>;

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -3,11 +3,12 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioPersonas } from '../../services/personas-service.js';
+import type { ScenarioStepVideoOffset } from './scenario-run.types.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export type { CoreFeature, CoreFeatureScenario, FeatureMeta, FeaturesMeta, PikkuBrowserWire, PikkuScenarioWire, ScenarioBrowserFailure, ScenarioBrowserProvider, ScenarioEnvironment, ScenarioStepKind, ScenarioStepMeta, ScenarioStepOptions, ScenarioScreenshotOptions, ScenarioStepPhase, ScenarioSurface, TestIdSelector, } from './scenario.types.js';
-export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, } from './scenario-run.types.js';
+export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunSelection, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, ScenarioStepVideoOffset, } from './scenario-run.types.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil, type PollOptions } from './scenario-poll.js';
@@ -161,6 +162,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private readonly engine;
     private runActors;
     private runContexts;
+    private runVideoOffsets;
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
     private runSurface;
@@ -193,6 +195,25 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      */
     setScenarioEnvironment(env: ScenarioEnvironment | undefined): void;
     getScenarioEnvironment(): ScenarioEnvironment | undefined;
+    /**
+     * Where each of a run's browser steps fell in its actor's video, keyed by the
+     * durable step name, handed over and forgotten in one call.
+     *
+     * Taken rather than read because the runner joins these onto the step rows
+     * after the run has finished — which is past the point anything else would
+     * clear them, and the only moment they are still wanted.
+     */
+    takeStepVideoOffsets(runId: string): Map<string, ScenarioStepVideoOffset[]>;
+    /** Where a step starting now falls in this actor's recording, if anywhere. */
+    private videoOffsetFor;
+    /**
+     * Stamp where a step began inside one actor's recording.
+     *
+     * First write per actor wins: a `then` step runs once per witness, and the
+     * moment the reader wants is when the sentence started, not when its last
+     * witness got around to the browser.
+     */
+    private recordVideoOffset;
     attachRunContext(runId: string, workflowMeta: any, options?: {
         actors?: ScenarioPersonas;
     }): Promise<void>;

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -243,6 +243,10 @@ export class PikkuScenarioService {
     // so the body and its hooks share one object rather than reading it back off
     // the persisted wire.
     runContexts = new Map();
+    // Where each browser step landed in its actor's recording, per run. Held
+    // apart from the run context because the runner reads it once the run has
+    // ended, which is exactly when `detachRunContext` has cleared that.
+    runVideoOffsets = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
     runSurface = 'default';
@@ -292,6 +296,50 @@ export class PikkuScenarioService {
     getScenarioEnvironment() {
         return this.scenarioEnvironment;
     }
+    /**
+     * Where each of a run's browser steps fell in its actor's video, keyed by the
+     * durable step name, handed over and forgotten in one call.
+     *
+     * Taken rather than read because the runner joins these onto the step rows
+     * after the run has finished — which is past the point anything else would
+     * clear them, and the only moment they are still wanted.
+     */
+    takeStepVideoOffsets(runId) {
+        const offsets = this.runVideoOffsets.get(runId);
+        this.runVideoOffsets.delete(runId);
+        return offsets ?? new Map();
+    }
+    /** Where a step starting now falls in this actor's recording, if anywhere. */
+    videoOffsetFor(actor) {
+        const provider = this.scenarioBrowserProvider;
+        if (provider?.markVideoStep) {
+            return provider.markVideoStep(actor);
+        }
+        const startedAt = provider?.videoStartedAt?.(actor);
+        return startedAt === undefined
+            ? undefined
+            : Math.max(0, Date.now() - startedAt);
+    }
+    /**
+     * Stamp where a step began inside one actor's recording.
+     *
+     * First write per actor wins: a `then` step runs once per witness, and the
+     * moment the reader wants is when the sentence started, not when its last
+     * witness got around to the browser.
+     */
+    recordVideoOffset(runId, stepName, actor, offsetMs) {
+        let byStep = this.runVideoOffsets.get(runId);
+        if (!byStep) {
+            byStep = new Map();
+            this.runVideoOffsets.set(runId, byStep);
+        }
+        const offsets = byStep.get(stepName) ?? [];
+        if (offsets.some((offset) => offset.actor === actor)) {
+            return;
+        }
+        offsets.push({ actor, offsetMs });
+        byStep.set(stepName, offsets);
+    }
     async attachRunContext(runId, workflowMeta, options) {
         const actors = options?.actors ??
             (workflowMeta.source === 'scenario'
@@ -641,14 +689,19 @@ export class PikkuScenarioService {
                     // The dispatch guard above already refused an actor-less call, and a
                     // browser binding always requires one.
                     wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
+                    const offsetMs = this.videoOffsetFor(actor.name);
+                    if (offsetMs !== undefined) {
+                        this.recordVideoOffset(runId, stepName, actor.name, offsetMs);
+                    }
                 }
-                return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
+                const result = await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
                     singletonServices: getSingletonServices(),
                     createWireServices: getCreateWireServices(),
                     data: () => data,
                     wire,
                     packageName: packageName ?? undefined,
                 });
+                return result;
             };
             if (resolution.kind === 'action') {
                 if (resolution.fellBack &&

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -41,6 +41,21 @@ export interface ScenarioArtifact {
     /** Fit to show outside the run: a marketing card, a docs page, a gallery. */
     showcase?: boolean;
 }
+/**
+ * Where a step falls inside one actor's recording.
+ *
+ * Measured from the moment that actor's browser context opened — which is when
+ * Playwright starts the file — rather than from the start of the scenario, so
+ * it addresses the video's own clock. The two differ by however long the
+ * scenario spent before that window existed, plus every non-browser step since,
+ * which is why the offset is recorded at the moment the step runs instead of
+ * being summed back out of the ladder afterwards.
+ */
+export interface ScenarioStepVideoOffset {
+    /** Whose recording this offset is into: one actor, one video file. */
+    actor: string;
+    offsetMs: number;
+}
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
@@ -54,6 +69,16 @@ export interface ScenarioStepRow {
     status: string;
     durationMs?: number;
     error?: string;
+    /**
+     * Where this step lands in each actor's video, for the actors whose window
+     * was being recorded when it ran. Absent for a step with no actor, a run
+     * without video, and a step that never ran at all.
+     *
+     * A list rather than one number because a video belongs to an actor, not to
+     * the scenario: a step touching two windows falls at a different moment in
+     * each, and an offset that does not name its file cannot be seeked to.
+     */
+    video?: ScenarioStepVideoOffset[];
 }
 /** Everything known about why one scenario failed. */
 export interface ScenarioFailureDetail {
@@ -76,10 +101,22 @@ export interface ScenarioResult {
     error?: string;
     steps?: ScenarioStepRow[];
     failure?: ScenarioFailureDetail;
-    /** The scenario registration this ran, which the label alone does not give. */
+    /**
+     * The registered scenario this ran, by the id it is registered under — the
+     * same id `FeatureMetaEntry.scenario` references. The label alone does not
+     * give it, and unlike the label it is not rewritten when the prose is.
+     */
     scenarioName?: string;
-    /** The feature that grouped it, when one did. */
+    /** The feature that grouped it — its display name, which is freely renamed. */
     feature?: string;
+    /**
+     * The registered feature that grouped it, by id.
+     *
+     * `feature` is a title someone writes for people to read, so nothing that
+     * outlives a run can key off it. This is what `addFeature` registered the
+     * feature under, and it is what survives the title being rewritten.
+     */
+    featureId?: string;
     tags?: string[];
     /** Images and footage this scenario produced, filed under the run. */
     artifacts?: ScenarioArtifact[];
@@ -103,6 +140,21 @@ export interface ScenarioRunReport {
     hookFailures: string[];
 }
 export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
+/**
+ * The filters a run was selected with, recorded when it was narrowed at all.
+ *
+ * A narrowed run is a partial record of the suite: scenarios a feature owns can
+ * be missing from it, and whole features can be absent, with nothing in the
+ * results to say so. Anything that reads a run as evidence of what the suite
+ * does — rather than of what happened that afternoon — has to be able to tell
+ * the two apart, and it cannot be inferred from the results afterwards.
+ */
+export interface ScenarioRunSelection {
+    flows?: string[];
+    features?: string[];
+    tags?: string[];
+    excludeTags?: string[];
+}
 /**
  * A whole run, as it is stored and read back.
  *
@@ -116,6 +168,8 @@ export interface ScenarioRunRecord extends ScenarioRunReport {
     status: ScenarioRunStatus;
     /** The surface the run targeted: `default`, `browser`, … */
     surface: string;
+    /** Absent on a run of the whole suite; see {@link ScenarioRunSelection}. */
+    selection?: ScenarioRunSelection;
     startedAt: string;
     finishedAt?: string;
 }

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -177,6 +177,14 @@ export interface ScenarioScreenshotOptions {
     /** Photograph the whole scrollable page rather than the viewport. */
     fullPage?: boolean;
 }
+/**
+ * One actor's browser session, handed to a step as `wire.browser`.
+ *
+ * Only what every driver can honour is declared here. A driver package adds
+ * the rest by declaration-merging onto this interface — `@pikku/playwright`
+ * contributes `page`, `context` and `locate` — so a step written against the
+ * structural surface keeps working whichever driver runs it.
+ */
 export interface PikkuBrowserWire {
     /** The actor whose browser context this is */
     readonly actor: string;
@@ -235,6 +243,24 @@ export interface ScenarioBrowserProvider {
      * scenario's reset, long after the outcome that decides whether to keep them.
      */
     endScenario?(outcome: 'passed' | 'failed'): void;
+    /**
+     * When this actor's recording started, as epoch milliseconds.
+     *
+     * The seam that keeps the video clock out of `@pikku/core`: a driver knows
+     * when it opened the context it passed `recordVideo` to, and the runner turns
+     * that into a per-step offset. Absent for an actor with no window open, and
+     * for a run recording nothing — both of which leave the step's offset off.
+     */
+    videoStartedAt?(actorName: string): number | undefined;
+    /**
+     * Mark a browser step starting in this actor's recording, answering where it
+     * falls in the finished video (ms).
+     *
+     * Preferred over `videoStartedAt` when present: a driver that edits its
+     * footage afterwards — holding each step's screen still, say — is the only
+     * one that knows how far that moves the step. Undefined when nothing records.
+     */
+    markVideoStep?(actorName: string): number | undefined;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

package/dist/wirings/workflow/scenario.types.d.ts

@@ -9,6 +9,14 @@ export type CoreFeature = {
     name: string;
     description?: string;
     tags?: string[];
+    /**
+     * Whether this feature is guide material. Defaults to true: a feature is a
+     * page of the user guide unless it says otherwise, so a feature nobody has
+     * written about is a gap `pikku scenario guide` reports rather than a page
+     * silently missing. Pure plumbing — a wire, a validation layer, a bearer
+     * auth handshake — sets it false and stops being a coverage problem.
+     */
+    document?: boolean;
     scenarios: readonly CoreFeatureScenario[];
     before?: CorePikkuFunctionHook;
     after?: CorePikkuFunctionHook;
@@ -22,6 +30,8 @@ export type FeatureMeta = {
     name: string;
     description?: string;
     tags: string[];
+    /** Present only when the feature opted out; absent means documented. */
+    document?: boolean;
     entries: FeatureMetaEntry[];
     unresolvedEntries: number;
     hasBefore: boolean;

package/knowledge/decisions/security/index.md

@@ -24,6 +24,7 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [Addon auth and tags only tighten, and resolve where the function runs](addon-auth-and-tags-only-tighten.md) — wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
 - [Addon auth and tag gates apply wherever the function runs, including inside the addon](addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md) — wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
 - [Addon scopes are resolved where the function runs](addon-scopes-are-resolved-where-the-function-runs.md) — wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace
+- [wireAddon expose selects the RPC surface, and a list may widen it](wire-addon-expose-selects-the-rpc-surface.md) — The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
 - [Only a Symbol-branded framework result can request tool approval](ai-agent-approval-forwarding-requires-a-symbol-brand.md) — Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
 - [Credential requests are trusted only when Symbol-branded](ai-agent-credential-requests-are-symbol-branded.md) — The string key is a wire field; the Symbol is the capability, and only core can mint it
 - [An agent requires a session only when auth is true, but always enforces scopes and permissions](ai-agent-gate-requires-a-session-only-when-auth-is-true.md) — Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O

package/knowledge/decisions/security/wire-addon-expose-selects-the-rpc-surface.md

@@ -0,0 +1,51 @@
+---
+type: decision
+title: wireAddon expose selects the RPC surface, and a list may widen it
+description: The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
+tags: addon, rpc, expose, authorization
+---
+
+# wireAddon expose selects the RPC surface, and a list may widen it
+
+`rpc.exposed('<name>:<fn>')` — what the generated `POST /rpc/:rpcName` forwards
+to — used to consult only the addon's own `expose: true`. The app installing the
+addon had no say: it could not close an addon whose author marked functions
+exposed, and it could not open one the author had not. `mcp` already worked the
+other way (the wiring decides), and the two now match.
+
+`expose` on `wireAddon` is `boolean | string[]`, resolved per instance by
+`isAddonFunctionExposed`:
+
+- **unset or `true`** — the addon's declaration decides, as before. Keeping the
+  default unchanged means no existing app gains or loses a route on upgrade.
+- **`false`** — nothing in this instance is reachable through `rpc.exposed`.
+- **a list** — exactly those functions, whether or not the addon declared them.
+  The list can widen the addon's surface, the same power `mcp` has, because the
+  app is the one that knows what its deployment should offer. The generated
+  `#pikku/addon` types the list against the package's function names, and a name
+  that survives to the build unpublished fails it with PKU343.
+  The value has to be written inline (`true`, `false` or an array of string
+  literals): the build reads it statically, and a variable or spread fails it
+  with PKU344 rather than being read as unset, which would leave the deploy
+  units disagreeing with the runtime.
+
+The decision is per **instance**, not per package: two `wireAddon` calls for one
+package may expose different things, and the gate reads the config the
+namespace resolved to.
+
+The deploy analyzer's per-addon unit applies the same rule, since that unit is
+what the dispatcher can forward to. A function the wiring refuses gets no unit
+and no dispatch entry, so the `deploymentService` fallback in `rpc.exposed` —
+which forwards namespaced names with no local metadata — has nothing to reach.
+Where the dispatcher does hold the wiring, it also refuses locally before
+forwarding.
+
+`expose` is reachability, not authorization. A listed function still runs
+through `runPikkuFunc` with its own `auth`, permissions and the instance's
+`auth`/`scopes`/`tags` — see
+[addon auth and tags](./addon-auth-and-tags-only-tighten.md). Widening the list
+to a sessionless function makes it public unless one of those gates it.
+
+**What this rules out:** letting the addon's `expose: true` override a wiring's
+`false`; treating an unknown list entry as a silent no-op; and a deploy unit
+that carries functions the runtime gate would refuse.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.117",
+  "version": "0.12.120",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",