@pikku/core 0.12.95 → 0.12.97

package/CHANGELOG.md

@@ -1,3 +1,69 @@
+## 0.12.97
+
+### Patch Changes
+
+- 8154b1c: Restore the `SecretService.getSecret` JSDoc noting its failure mode, and state the `optional` carve-out `defineSecret` already documents: a key declared `optional` resolves `undefined` when absent rather than throwing. The line was on `main` and was removed by mistake in a comment cleanup on #1411 — the PR that changes what that throw says — leaving `getSecret` the only one of the interface's methods without its documented failure mode.
+- 6d9c09c: Resolve a variable's declared default instead of dropping it.
+
+  `defineVariable` takes a schema, and a schema can carry a default — `z.enum(['https://api.github.com']).default('https://api.github.com')` is the shape most addons declare their base URL with. Nothing read it. `variables.get('GITHUB_BASE_URL')` returned `undefined` on a host that had not set it, and the `as string` at the call site hid that until a request went to `undefined/repos/...`.
+
+  The default now resolves in `TypedVariablesService`, which is the layer that knows what was declared — `VariablesService` only knows what a host put in it. A stored value always wins; a schema with no default still resolves to `undefined`.
+
+  `VariableStatus` gains `hasDefault`, and `getMissing()` no longer lists a variable that defaults: it has a value, just not one anybody has to supply. `isConfigured` still means what it said — that a host set it.
+
+  For this to work the generated `TYPED_VARIABLES_META` now carries the schema as a value rather than only `z.infer`-ing its type, so the schema module is retained in the emit instead of being elided.
+
+- 239332b: Move first-party product analytics out of application code and into the framework.
+
+  `createAnalytics<Event>({ endpoint })` in `@pikku/react` is the buffered beacon client: it is typed against the app's own event union, flushes on an interval, on size and on `pagehide`/`visibilitychange` (via `sendBeacon`, so the abandon-point events survive unload), never surfaces a failure to the user and never retries. It also carries the delegated `data-analytics-click` listener, registered in the capture phase so a component calling `stopPropagation()` cannot silence instrumentation, and merging `data-analytics-meta` from ancestors with nearest-wins. Put the client on the Pikku instance and `usePikkuAnalytics<Event>()` reaches it from the provider, alongside `usePikkuFetch` and `usePikkuRPC`.
+
+  `requireOrigin()` in `@pikku/core/middleware` is a server-side origin lock for any unauthed route, and is re-exported from the generated `#pikku/middleware` leaf alongside `cors`. Unlike `cors()` — which only sets response headers a non-browser client ignores — it rejects with a 403 before the function body. Comparison is exact on the parsed origin, so `https://evil-myapp.com` cannot suffix-match `myapp.com`, and a missing `Origin` is rejected because a real browser always sets one on a cross-origin-capable POST. Allowed origins default to the request's own host and can be extended with a list or a resolver over services. `isAllowedOrigin` and `toOrigin` are exported for direct unit testing.
+
+  Together these let an app keep only its event registry and its wiring, instead of a few hundred lines of copied transport.
+
+## 0.12.96
+
+### Patch Changes
+
+- 88629af: Say why a hot-reload import failed instead of only that it did.
+
+  The dev module runner caught every failure bare and returned `null`, and the reloader turned that into a single line: `Failed to import: … (keeping old code)`. Keeping the old code is the right call, but it leaves the running process disagreeing with the file on disk, and the only symptom is a function returning stale output while the editor shows the new source — `tsc` passes, every import resolves, and there is nothing anywhere to explain it.
+
+  `run` now returns `{ ok: true, exports }` or `{ ok: false, error }`, so the failure case cannot be read past, and the reloader prints the error's message and stack under the existing line. A failure matching pikku's own documented limitation — a file using top-level `await`, which the `cjs` emit cannot express — says so outright, because in that case nothing is wrong with the file and re-reading it will never reveal that.
+
+- f1ccfe3: A step ladder reads as one paragraph, not a list of restatements
+
+  Every step prefixed its actor with `the `, named that actor again, and repeated
+  the phase keyword. A three-step run by one person said their name three times
+  and `Given` three times, only read as English when the persona key happened to
+  be a role noun, and never said who that person was — the fabric template's own
+  placeholder came out as `the nadia opens /app`.
+
+  ```
+  Given yasser (the founder) signs in
+  When  yasser opens the dashboard
+  And   sees the audit log
+  And   nadia reviews the invite
+  ```
+
+  The article is gone: the actor key is the subject verbatim, so a persona named
+  after a person reads as that person. A repeated phase reads as `And`, the way
+  Gherkin has always written it. A step that continues both the phase and the
+  actor drops the repeated subject, because English drops a repeated subject in a
+  compound predicate — it takes both, since eliding across a phase change gives
+  `When opens the dashboard`, and a pronoun rather than a name would give `they
+sees`, step templates being authored in the third person singular.
+
+  An actor is introduced once, by the persona's `jobTitle` — prose someone wrote
+  for a reader. `roles` is authorisation, so a persona whose only description is a
+  `reviewer` grant gets no introduction rather than one assembled out of grants.
+  A row carries `sentenceWithRole` alongside `sentence`, set only where an actor
+  is first named, so a renderer can offer the introduction as a toggle without
+  parsing a composed sentence back apart.
+
+  `{placeholder}` filling, the `#ordinal` lookup for repeated step names and an
+  actorless step reading as its description alone are all unchanged.
+
 ## 0.12.95
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -6,7 +6,7 @@ import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
-import { createModuleRunner } from './module-runner.js';
+import { createModuleRunner, isTopLevelAwaitLimitation, } from './module-runner.js';
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
@@ -40,6 +40,20 @@ const isWatchedTsFile = (filename) => {
         // Hidden files: editor/sed atomic-write temps must never trigger a reload.
         !basename(filename).startsWith('.'));
 };
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error) => {
+    if (isTopLevelAwaitLimitation(error)) {
+        return (`  ${error.message}\n` +
+            '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+            'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+            'dev server to pick the file up.');
+    }
+    return `  ${error.stack ?? error.message}`;
+};
 export async function pikkuDevReloader(options) {
     const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
@@ -56,11 +70,17 @@ export async function pikkuDevReloader(options) {
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
         const importPath = compiledFile ?? changedTsFile;
-        const mod = await moduleRunner.run(importPath);
-        if (!mod) {
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
+        const result = await moduleRunner.run(importPath);
+        if (!result.ok) {
+            // Keeping the old code leaves the process disagreeing with the file on
+            // disk, and the only symptom is stale output from a function that looks
+            // correct in the editor — so the reason has to be printed here, where it
+            // is still known, rather than left for the developer to reconstruct.
+            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+                reloadFailureReason(result.error));
             return;
         }
+        const mod = result.exports;
         // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
         for (const [exportName, exportValue] of Object.entries(mod)) {
             if (!isFunctionConfig(exportValue))

package/dist/dev/module-runner.d.ts

@@ -1,10 +1,27 @@
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult = {
+    ok: true;
+    exports: Record<string, unknown>;
+} | {
+    ok: false;
+    error: Error;
+};
 export interface PikkuModuleRunner {
     /** Run a user module by absolute path. Repeated runs of one path overwrite a
-     *  single registry slot. Returns `null` on failure so the caller can keep the
-     *  previously-loaded code. */
-    run: (absPath: string) => Promise<Record<string, unknown> | null>;
+     *  single registry slot. Failure is returned, not thrown, so the caller can
+     *  keep the previously-loaded code — and the discriminant makes that case
+     *  impossible to read past by accident. */
+    run: (absPath: string) => Promise<PikkuModuleRunResult>;
     evict: (absPath: string) => void;
     clear: () => void;
     readonly size: number;
 }
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export declare const isTopLevelAwaitLimitation: (error: Error) => boolean;
 export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -13,6 +13,11 @@ const loadTransform = async () => {
     transformSync = esbuild.transformSync;
     return transformSync;
 };
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
@@ -30,12 +35,20 @@ export const createModuleRunner = () => {
             const moduleObj = { exports: {} };
             fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
             registry.set(absPath, moduleObj.exports);
-            return moduleObj.exports;
+            return { ok: true, exports: moduleObj.exports };
         }
-        catch {
+        catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level
-            // `await`, which cannot be emitted in `cjs` form.
-            return null;
+            // `await`, which cannot be emitted in `cjs` form. Normalised to an
+            // `Error` so the caller always has a message and a stack to print
+            // without re-deriving them; a non-`Error` throw keeps its original value
+            // as the `cause`.
+            return {
+                ok: false,
+                error: thrown instanceof Error
+                    ? thrown
+                    : new Error(String(thrown), { cause: thrown }),
+            };
         }
     };
     return {

package/dist/middleware/index.d.ts

@@ -3,6 +3,7 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
+export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';

package/dist/middleware/index.js

@@ -3,6 +3,7 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
+export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';

package/dist/middleware/require-origin.d.ts

@@ -0,0 +1,23 @@
+import type { CoreSingletonServices } from '../types/core.types.js';
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export declare const toOrigin: (value: string | null | undefined) => string | null;
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export declare const isAllowedOrigin: (requestOrigin: string | null, hostOrigin: string | null, configuredOrigins: string[]) => boolean;
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export declare const requireOrigin: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** Extra allowed origins beyond the request's own host, or a resolver for them. */
+    origins?: string[] | ((services: CoreSingletonServices) => string[] | Promise<string[]>);
+}>;

package/dist/middleware/require-origin.js

@@ -0,0 +1,57 @@
+import { InvalidOriginError } from '../errors/errors.js';
+import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export const toOrigin = (value) => {
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol && url.host ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export const isAllowedOrigin = (requestOrigin, hostOrigin, configuredOrigins) => {
+    if (!requestOrigin)
+        return false;
+    if (hostOrigin && requestOrigin === hostOrigin)
+        return true;
+    return configuredOrigins.some((allowed) => toOrigin(allowed) === requestOrigin);
+};
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => pikkuMiddleware({
+    name: 'requireOrigin',
+    description: 'Rejects requests that did not come from this app.',
+    func: async (services, { http }, next) => {
+        const request = http?.request;
+        if (!request)
+            return next();
+        const requestOrigin = toOrigin(request.header('origin')) ??
+            toOrigin(request.header('referer'));
+        const host = request.header('host');
+        const proto = request.header('x-forwarded-proto') ?? 'https';
+        const hostOrigin = host ? toOrigin(`${proto}://${host}`) : null;
+        const configured = typeof origins === 'function'
+            ? await origins(services)
+            : origins;
+        if (!isAllowedOrigin(requestOrigin, hostOrigin, configured)) {
+            throw new InvalidOriginError(`Rejected origin ${requestOrigin ?? '(none)'}`);
+        }
+        return next();
+    },
+}));

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

@@ -4,6 +4,11 @@ export type SecretValues<T> = {
     [K in keyof T]: SecretValue<T[K]>;
 };
 export interface SecretService {
+    /**
+     * Throws if the secret is not found, unless `defineSecret` declared it
+     * `optional` — then absence resolves `undefined`. Unwrap the result with
+     * `.reveal()`.
+     */
     getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     /** Answers for any key, including a disallowed one — it must not throw. */
     hasSecret(key: string): Promise<boolean>;

package/dist/services/typed-variables-service.d.ts

@@ -1,14 +1,34 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { VariablesService } from './variables-service.js';
 export interface VariableStatus {
     variableId: string;
     name: string;
     displayName: string;
     isConfigured: boolean;
+    /** Whether the declaration answers for itself when the host sets nothing. */
+    hasDefault: boolean;
 }
 export type VariableMeta = {
     name: string;
     displayName: string;
+    /**
+     * The shape the variable was declared with. It is the schema itself rather
+     * than a description of it, because a default is only knowable by running it:
+     * `undefined` goes in and, if the declaration carries one, the default comes
+     * back out.
+     *
+     * A thunk is accepted, and is what code generation emits. The generated file
+     * and the file declaring the schema import each other, so reading the schema
+     * while the modules are still initializing throws — deferring the read until
+     * a variable is actually asked for is what keeps the cycle harmless.
+     */
+    schema?: StandardSchemaV1 | (() => StandardSchemaV1);
 };
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export declare class TypedVariablesService<TMap = Record<string, unknown>> implements VariablesService {
     private variables;
     private variablesMeta;
@@ -21,5 +41,19 @@ export declare class TypedVariablesService<TMap = Record<string, unknown>> imple
     has(name: string): Promise<boolean> | boolean;
     delete(name: string): Promise<void> | void;
     getAllStatus(): Promise<VariableStatus[]>;
+    /**
+     * What a deployment still has to be told. A variable that defaults is not on
+     * this list — it has a value, just not one anybody has to supply.
+     */
     getMissing(): Promise<VariableStatus[]>;
+    /**
+     * The value the declaration answers with when the host set nothing, or
+     * `undefined` when it does not answer for itself.
+     */
+    private resolveDefault;
+    /**
+     * Kept synchronous when the defaults resolve synchronously, so a caller that
+     * did not await `getVariables` before does not have to start.
+     */
+    private withDefaults;
 }

package/dist/services/typed-variables-service.js

@@ -1,3 +1,9 @@
+const isPromise = (value) => typeof value?.then === 'function';
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export class TypedVariablesService {
     variables;
     variablesMeta;
@@ -6,10 +12,18 @@ export class TypedVariablesService {
         this.variablesMeta = variablesMeta;
     }
     get(name) {
-        return this.variables.get(name);
+        const stored = this.variables.get(name);
+        if (isPromise(stored)) {
+            return stored.then((value) => value === undefined ? this.resolveDefault(name) : value);
+        }
+        return stored === undefined ? this.resolveDefault(name) : stored;
     }
     getVariables(names) {
-        return this.variables.getVariables(names);
+        const stored = this.variables.getVariables(names);
+        if (isPromise(stored)) {
+            return stored.then((values) => this.withDefaults(names, values));
+        }
+        return this.withDefaults(names, stored);
     }
     getAll() {
         return this.variables.getAll();
@@ -32,12 +46,64 @@ export class TypedVariablesService {
                 name: meta.name,
                 displayName: meta.displayName,
                 isConfigured: all[variableId] !== undefined,
+                hasDefault: (await this.resolveDefault(variableId)) !== undefined,
             });
         }
         return results;
     }
+    /**
+     * What a deployment still has to be told. A variable that defaults is not on
+     * this list — it has a value, just not one anybody has to supply.
+     */
     async getMissing() {
         const all = await this.getAllStatus();
-        return all.filter((v) => !v.isConfigured);
+        return all.filter((v) => !v.isConfigured && !v.hasDefault);
+    }
+    /**
+     * The value the declaration answers with when the host set nothing, or
+     * `undefined` when it does not answer for itself.
+     */
+    resolveDefault(name) {
+        const declared = this.variablesMeta[name]?.schema;
+        if (!declared) {
+            return undefined;
+        }
+        const schema = typeof declared === 'function' ? declared() : declared;
+        const result = schema['~standard'].validate(undefined);
+        if (isPromise(result)) {
+            return result.then(unwrapDefault);
+        }
+        return unwrapDefault(result);
+    }
+    /**
+     * Kept synchronous when the defaults resolve synchronously, so a caller that
+     * did not await `getVariables` before does not have to start.
+     */
+    withDefaults(names, values) {
+        const out = { ...values };
+        const pending = [];
+        for (const name of names) {
+            if (out[name] !== undefined)
+                continue;
+            const fallback = this.resolveDefault(name);
+            if (isPromise(fallback)) {
+                pending.push(fallback.then((value) => {
+                    if (value !== undefined)
+                        out[name] = value;
+                }));
+            }
+            else if (fallback !== undefined) {
+                out[name] = fallback;
+            }
+        }
+        if (pending.length > 0) {
+            return Promise.all(pending).then(() => out);
+        }
+        return out;
     }
 }
+/**
+ * A schema with no default rejects `undefined`, which is not a failure here —
+ * it is the answer that there is nothing to fall back to.
+ */
+const unwrapDefault = (result) => result.issues ? undefined : result.value;

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -1,10 +1,32 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
-export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+export declare const composeStepProse: ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;
     template?: string;
     input?: unknown;
     actor?: string;
+    /**
+     * What this actor is, rendered as an apposition after their key — "yasser
+     * (the founder)". Only pass it where the actor has not been named yet: an
+     * ordinary run repeats one actor for a dozen steps, and repeating the role
+     * with them turns the one piece of context into the noise around it.
+     */
+    actorRole?: string;
+    /**
+     * This step repeats the phase of the one before it, so it reads as `And`
+     * rather than saying `Given` three times — the same thing Gherkin does.
+     */
+    continuesPhase?: boolean;
+    /**
+     * The step before this one had the same actor. Combined with `continuesPhase`
+     * the subject is dropped, because English drops a repeated subject in a
+     * compound predicate: "yasser opens the dashboard / and sees the audit log".
+     *
+     * It takes both. Dropping the subject across a phase change gives "When opens
+     * the dashboard", and a pronoun instead of a name would give "they sees",
+     * since step templates are authored in the third person singular.
+     */
+    continuesActor?: boolean;
     keywordWidth?: number;
 }) => string;

package/dist/wirings/workflow/scenario-prose.js

@@ -14,9 +14,13 @@ const formatValue = (value) => {
     }
     return String(value);
 };
-export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = capitalise(phase);
-    const subject = actor ? `the ${actor}` : '';
+export const composeStepProse = ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }) => {
+    const keyword = capitalise(continuesPhase ? 'and' : phase);
+    // The actor key is the subject verbatim, with no article in front of it.
+    // "the ${actor}" only reads as English when the key happens to be a role
+    // noun — it turns a persona named after a person into "the nadia", which
+    // is the reporter quietly imposing a naming convention on the author.
+    const subject = continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole);
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');
     if (keywordWidth === undefined) {
@@ -24,4 +28,9 @@ export const composeStepProse = ({ phase, description, template, input, actor, k
     }
     return `${keyword.padEnd(keywordWidth)} ${sentence}`;
 };
+const composeSubject = (actor, actorRole) => {
+    if (!actor)
+        return '';
+    return actorRole ? `${actor} (the ${actorRole})` : actor;
+};
 const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

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

@@ -35,6 +35,13 @@ export interface ScenarioArtifact {
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
+    /**
+     * The same sentence with the actor's role in it — "yasser (the founder)
+     * signs in". Set only on the step that first names each actor, and only
+     * when a persona declares a job title or a role, so a reader who wants the
+     * context picks this and one who wants the bare run picks `sentence`.
+     */
+    sentenceWithRole?: string;
     status: string;
     durationMs?: number;
     error?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.95",
+  "version": "0.12.97",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/dev/hot-reload.test.ts

@@ -215,6 +215,48 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
     assert.deepEqual(await func.func({} as any, {}, {} as any), {
       working: true,
     })
+
+    // Serving the old code is only safe if the developer is told why; without
+    // the reason the sole symptom is a function that ignores the file on disk.
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    assert.ok(
+      failureLog!.message.includes('keeping old code'),
+      'Should say the old code is still being served'
+    )
+    assert.match(failureLog!.message, /badFunc\.js/)
+  })
+
+  test('should name the top-level await limitation when a reload hits it', async (t) => {
+    if (!(await ensureRecursiveWatchAvailable(t, tmpDir))) return
+
+    await writeFile(join(tmpDir, 'tlaFunc.ts'), '// initial')
+
+    reloader = await pikkuDevReloader({
+      srcDirectories: [tmpDir],
+      logger: mockLogger,
+      pikkuDir: tmpDir,
+    })
+
+    await writeFile(
+      join(tmpDir, 'tlaFunc.ts'),
+      `const config = await Promise.resolve({ ok: true })
+       export const tlaFunc = { func: async () => config }
+       // trigger ${Date.now()}`
+    )
+
+    await wait(300)
+
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    // The file is valid TypeScript; pointing at pikku's own `cjs` emit is the
+    // difference between a two-minute fix and an afternoon.
+    assert.match(failureLog!.message, /top-level `?await`?/i)
+    assert.match(failureLog!.message, /pikku limitation/i)
   })
 
   test('should ignore non-ts files, test files, and gen files', async (t) => {

package/src/dev/hot-reload.ts

@@ -9,7 +9,10 @@ import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middlewa
 import { httpRouter } from '../wirings/http/routers/http-router.js'
 import type { Logger } from '../services/logger.js'
 import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
-import { createModuleRunner } from './module-runner.js'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} from './module-runner.js'
 
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
@@ -63,6 +66,23 @@ const isWatchedTsFile = (filename: string): boolean => {
   )
 }
 
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error: Error): string => {
+  if (isTopLevelAwaitLimitation(error)) {
+    return (
+      `  ${error.message}\n` +
+      '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+      'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+      'dev server to pick the file up.'
+    )
+  }
+  return `  ${error.stack ?? error.message}`
+}
+
 export interface PikkuDevReloaderHandle {
   close: () => void
   /** Re-import every file changed since the last drain (post-codegen, once
@@ -96,13 +116,19 @@ export async function pikkuDevReloader(
     )
     const importPath = compiledFile ?? changedTsFile
 
-    const mod = await moduleRunner.run(importPath)
-    if (!mod) {
+    const result = await moduleRunner.run(importPath)
+    if (!result.ok) {
+      // Keeping the old code leaves the process disagreeing with the file on
+      // disk, and the only symptom is stale output from a function that looks
+      // correct in the editor — so the reason has to be printed here, where it
+      // is still known, rather than left for the developer to reconstruct.
       logger.error(
-        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`
+        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+          reloadFailureReason(result.error)
       )
       return
     }
+    const mod = result.exports
 
     // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
     for (const [exportName, exportValue] of Object.entries(mod)) {