@pikku/core 0.12.84 → 0.12.86

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

@@ -1,4 +1,5 @@
-import type { CoreUserSession, SerializedError } from '../../types/core.types.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';

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

@@ -1,7 +1,7 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
+import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, stripInstanceOrdinal, } from './graph/graph-runner.js';
 import { isExpectedError } from '../../errors/error-handler.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -735,9 +735,8 @@ export class PikkuWorkflowService {
                     graphNodeId = stepName;
                 }
                 else {
-                    const hash = stepName.lastIndexOf('#');
-                    const base = hash > 0 ? stepName.slice(0, hash) : undefined;
-                    if (base && base in workflowMeta.nodes)
+                    const base = stripInstanceOrdinal(stepName);
+                    if (base !== stepName && base in workflowMeta.nodes)
                         graphNodeId = base;
                 }
             }

package/dist/wirings/workflow/run-timeline.d.ts

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { StepState, StepStatus } from './workflow.types.js';
 export interface RunTimelineEvent {
     seq: number;

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

@@ -0,0 +1,171 @@
+/**
+ * What one `pikku scenario run` leaves behind.
+ *
+ * A run is history: the scenarios it selected, the sentences they were made of,
+ * and the images and footage they produced. The sentences are snapshotted into
+ * the record rather than looked up later, because a scenario is code and the
+ * code moves — a run from last week describes a suite that no longer exists,
+ * and re-deriving its ladder from today's source would quietly rewrite it.
+ *
+ * Everything here is plain serialisable data. That is what lets one record be
+ * a JSON file on disk in OSS and a row in Postgres on a hosted project, read
+ * back by the same console screen either way.
+ */
+import type { ScenarioBrowserFailure } from './scenario-step.types.js';
+/** What a run filed, in the order it filed it. */
+export type ScenarioArtifactKind = 'screenshot' | 'failure' | 'video';
+/**
+ * One image or recording a scenario produced.
+ *
+ * `path` is relative to the run's artifact root and always uses forward
+ * slashes: it is a content key, not a filesystem path. Locally it resolves
+ * under the run's directory; on a hosted project it is the object key in a
+ * bucket, and the same record works unchanged.
+ */
+export interface ScenarioArtifact {
+    /** The scenario label this belongs to, as the report names it. */
+    scenario: string;
+    kind: ScenarioArtifactKind;
+    path: string;
+    /** Whose window it was — a two-actor scenario produces two of everything. */
+    actor?: string;
+    /** The caption the scenario author took a screenshot under. */
+    name?: string;
+}
+/** One step of a run, already joined to the prose that declared it. */
+export interface ScenarioStepRow {
+    sentence: string;
+    status: string;
+    durationMs?: number;
+    error?: string;
+}
+/** Everything known about why one scenario failed. */
+export interface ScenarioFailureDetail {
+    /** The rendered sentence of the failing step; absent if no step failed. */
+    sentence?: string;
+    message: string;
+    stack?: string;
+    /**
+     * True when the failure was a deliberate one (a PikkuError). Its message is
+     * the whole story, so the stack is noise.
+     */
+    expected?: boolean;
+    browser?: ScenarioBrowserFailure[];
+}
+export interface ScenarioResult {
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    output?: unknown;
+    error?: string;
+    steps?: ScenarioStepRow[];
+    failure?: ScenarioFailureDetail;
+    /** The scenario registration this ran, which the label alone does not give. */
+    scenarioName?: string;
+    /** The feature that grouped it, when one did. */
+    feature?: string;
+    tags?: string[];
+    /** Images and footage this scenario produced, filed under the run. */
+    artifacts?: ScenarioArtifact[];
+}
+/** One scenario that was not run, and why. */
+export interface ScenarioSkip {
+    name: string;
+    reason: string;
+}
+export interface ScenarioRunReport {
+    environment: string;
+    results: ScenarioResult[];
+    /**
+     * Scenarios not run at all, each carrying why. A skip is only useful if the
+     * reader can tell a browser scenario held back by `--no-browser` from one the
+     * project itself quarantined, so the reason travels with the name rather than
+     * being assumed by the formatter.
+     */
+    skipped: ScenarioSkip[];
+    /** Feature-level hook failures, which belong to no single scenario. */
+    hookFailures: string[];
+}
+export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
+/**
+ * A whole run, as it is stored and read back.
+ *
+ * `status` is `running` from the moment the run is created until it finishes,
+ * so a console watching a run in progress can tell "still going" from "nothing
+ * came back" — and a run killed halfway stays `running` forever, which is the
+ * honest record of what happened to it.
+ */
+export interface ScenarioRunRecord extends ScenarioRunReport {
+    runId: string;
+    status: ScenarioRunStatus;
+    /** The surface the run targeted: `default`, `browser`, … */
+    surface: string;
+    startedAt: string;
+    finishedAt?: string;
+}
+/** Enough of a run to list it without loading its steps and stacks. */
+export interface ScenarioRunSummary {
+    runId: string;
+    environment: string;
+    surface: string;
+    status: ScenarioRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Whether anything is there to watch, so a list can say so without a second read. */
+    artifacts: number;
+}
+/**
+ * Where runs are kept.
+ *
+ * Deliberately not the workflow service: a scenario run is a workflow run under
+ * the hood, but its history has a different lifetime, a different audience, and
+ * a different home — a JSON file beside the project locally, a project-scoped
+ * table and an object store when hosted.
+ *
+ * Written progressively rather than at the end, so a suite that dies on its
+ * fortieth scenario still leaves the thirty-nine behind.
+ */
+export interface ScenarioRunStore {
+    /** Open a run. Called before the first scenario, with `status: 'running'`. */
+    start(record: ScenarioRunRecord): Promise<void>;
+    /** Append one finished scenario to an open run. */
+    recordScenario(runId: string, result: ScenarioResult): Promise<void>;
+    /**
+     * File the run's artifacts against the scenarios that produced them.
+     *
+     * Separate from `recordScenario` because a scenario's video does not exist
+     * when the scenario ends — it is finalised by the next scenario's reset, and
+     * renamed again when the run closes. Artifacts are matched to a result by the
+     * label the report knows it under.
+     */
+    attachArtifacts(runId: string, artifacts: ScenarioArtifact[]): Promise<void>;
+    /** Close a run, settling everything only known once every scenario has run. */
+    finish(runId: string, outcome: Pick<ScenarioRunRecord, 'status' | 'finishedAt' | 'skipped' | 'hookFailures'>): Promise<void>;
+    /**
+     * The bytes of one artifact, by the `path` its record carries.
+     *
+     * Reading goes through the store because only the store knows where a run's
+     * files actually are — a directory beside the project, or an object store
+     * behind a bucket. Absent when the run or the path is unknown, which is also
+     * the answer for a path that tries to leave the run.
+     *
+     * The bytes are backed by their own `ArrayBuffer` so they can be handed
+     * straight to a `Response` — a view onto a pooled or shared buffer is not a
+     * valid body.
+     */
+    readArtifact(runId: string, path: string): Promise<{
+        body: Uint8Array<ArrayBuffer>;
+        contentType: string;
+    } | undefined>;
+    /** Most recent first. */
+    list(options?: {
+        limit?: number;
+    }): Promise<ScenarioRunSummary[]>;
+    get(runId: string): Promise<ScenarioRunRecord | undefined>;
+    /** Forget a run and everything it filed. */
+    remove(runId: string): Promise<void>;
+}

package/dist/wirings/workflow/scenario-run.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,3 +1,2 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
-export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
-export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,11 +1,3 @@
-export const requireActor = (scenarioStep) => {
-    const actor = scenarioStep?.actor;
-    if (!actor) {
-        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
-            `Pass { actor: actors.<name> } so it runs as that persona.`);
-    }
-    return actor;
-};
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

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

@@ -1,4 +1,4 @@
-import type { ScenarioPersona } from '../../services/personas-service.js';
+import type { ScenarioArtifact } from './scenario-run.types.js';
 /**
  * Scenario steps: named, typed units of scenario behaviour.
  *
@@ -86,7 +86,10 @@ export type ScenarioSurfaceResolution = {
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-    /** The actor this step runs as. Required for steps declaring a `browser` binding. */
+    /**
+     * The actor this step runs as. Required for a step that declares `actor: true`
+     * or a `browser` binding; the runner refuses to dispatch one without it.
+     */
     actor?: unknown;
     /** Overrides the step's own `description` for this call site only. */
     description?: string;
@@ -107,11 +110,12 @@ export interface ScenarioEnvironment {
 /**
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
- * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioPersona` for a
- * project that declares no registry.
+ * The persona a step runs as is not here: it arrives as `wire.actor`, injected
+ * by the runner and typed as present exactly on the bindings that declared they
+ * need one. Keeping it off this interface is what makes that possible — a wire
+ * member can be required per binding, a property of one cannot.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
+export interface PikkuScenarioStepWire {
     /** Registered step name (also its pikkuFuncId) */
     name: string;
     /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
@@ -123,12 +127,6 @@ export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
      * per witness, so its body sees this change between invocations.
      */
     surface: ScenarioSurface;
-    /**
-     * The actor this step runs as, when one was given. Call RPCs through it
-     * (`actor.invoke(...)`) so they run against the target environment as that
-     * persona.
-     */
-    actor?: TActor;
     /**
      * The environment this run targets. A step runs in the CLI process, where
      * there is no `variables` service — this is how a raw-HTTP step learns the
@@ -218,11 +216,28 @@ export interface ScenarioBrowserProvider {
      * folder — findable only by timestamp.
      */
     beginScenario?(scenario: string): void;
+    /**
+     * Report how the scenario that just ran finished.
+     *
+     * Called after each scenario, and separate from `reset()` because artifacts
+     * that only exist once a window closes — a video — are produced by the NEXT
+     * scenario's reset, long after the outcome that decides whether to keep them.
+     */
+    endScenario?(outcome: 'passed' | 'failed'): void;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must
      * not replace the failure being captured.
      */
     captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    /**
+     * Everything the run filed, each entry naming the scenario it belongs to.
+     *
+     * Reported by the driver rather than discovered by scanning the directory:
+     * only the driver knows which window produced a file and under what caption,
+     * and a video's final name is not settled until the run closes. Read after
+     * `close()`, which is the first moment the answer is complete.
+     */
+    artifacts?(): ScenarioArtifact[];
     close(): Promise<void>;
 }

package/dist/wirings/workflow/workflow-approval.js

@@ -103,7 +103,8 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
         return stepState.result;
     }
     const stateKey = approvalStateKey(approvalStepName);
-    let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    let record = ((await store.getRunState(runId))[stateKey] ??
+        {});
     const policy = {
         approvers: options.approvers,
         approverScope: options.approverScope,

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

@@ -1,4 +1,5 @@
-import type { PikkuRawWire, SerializedError } from '../../types/core.types.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { CoreWorkflow, PikkuWorkflowWire, StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
 export interface RunLifecycleContext {
     runId: string;

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

@@ -1,4 +1,5 @@
-import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
+import type { CommonWireMeta } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';

package/knowledge/decisions/index.md

@@ -14,6 +14,8 @@ here first — several of these exist because the obvious simplification was tri
 and broke something.
 
 <!-- pikku:knowledge-index -->
+
 - [internals](internals/index.md) — a rule about how it works under the hood, and why
 - [security](security/index.md) — a rule about who may do what
+
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/a-scenario-step-template-is-offered-unfilled.md

@@ -14,7 +14,7 @@ A reporter fills those placeholders from a run that already happened. There is
 no run yet at derivation time, so there is nothing to fill them from. More
 importantly, filling them would answer the wrong question: "invites {email}"
 tells the user to choose someone, where "invites ada@example.com" tells it whom
-— and *whom* is the scenario author's answer, not something the virtual user
+— and _whom_ is the scenario author's answer, not something the virtual user
 worked out.
 
 **What this rules out:** substituting example or fixture values to make the

package/knowledge/decisions/internals/a-secret-that-fails-to-decrypt-fails-the-whole-read.md

@@ -37,7 +37,7 @@ that turn that into a one-line fix, and they are known at the catch site and
 nowhere after it.
 
 This matters most at exactly the moment it is least convenient: a change to
-`deriveKEK` makes *every* previously stored secret undecryptable at once. Loud
+`deriveKEK` makes _every_ previously stored secret undecryptable at once. Loud
 failure names the first one; silence produces an empty map and a support ticket.
 
 **What this rules out:** a `getSecrets` that skips unreadable rows; returning

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -18,9 +18,9 @@ Both of the alternatives are the obvious ones, and both are wrong for this.
 resumed at the step it died on, and that the same input reaches the same step.
 A virtual user is the opposite by construction — it is an LLM deciding what to
 try next, so no two attempts take the same steps, and there is no step to resume
-*to*. Recording a run as a workflow puts entries in the workflow store that can
+_to_. Recording a run as a workflow puts entries in the workflow store that can
 never be replayed, and gives every operator reading that store a row that lies
-about what it is. The seed makes a run *reproducible* — run it again and it
+about what it is. The seed makes a run _reproducible_ — run it again and it
 explores the same way — which is a different property from resumable, and one
 the record already carries.
 

package/knowledge/decisions/internals/a-wall-clock-threshold-is-a-load-test-in-disguise.md

@@ -13,11 +13,11 @@ per secret turns a 10ms operation into a 4-second one.
 
 It guarded it with `assert.ok(elapsed < 50)`. Measured on this machine:
 
-| | |
-| --- | --- |
-| one `deriveKEK` | ~86ms |
-| 50 `envelopeDecrypt` | 10.8ms |
-| the old 50ms threshold | 4.6x headroom |
+|                               |                                 |
+| ----------------------------- | ------------------------------- |
+| one `deriveKEK`               | ~86ms                           |
+| 50 `envelopeDecrypt`          | 10.8ms                          |
+| the old 50ms threshold        | 4.6x headroom                   |
 | the failure it guards against | ~4281ms — a **396x** separation |
 
 So the assertion had 4.6x of margin to detect a 396x regression. Everything
@@ -37,7 +37,7 @@ suite grows or CI moves to a noisier runner. Any assertion of the form
 ratio against something measured alongside it.
 
 Worth knowing: `envelopeDecrypt(kek: CryptoKey, …)` takes the derived key as a
-parameter, so it *cannot* derive one — the property is already enforced by the
+parameter, so it _cannot_ derive one — the property is already enforced by the
 signature, and [[the-api-report-pins-members-not-just-names]] would catch a
 change to it. The test is defence in depth, which is a reason to make it cheap
 and quiet rather than to delete it.

package/knowledge/decisions/internals/a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md

@@ -18,7 +18,7 @@ pikkuUserId: rpcService.wire?.pikkuUserId,
 ```
 
 `PikkuRPC` has no `wire`. Neither does the object `getContextRPCService`
-actually returns — `ContextAwareRPCService` holds its wire *privately* and
+actually returns — `ContextAwareRPCService` holds its wire _privately_ and
 exposes `invoke`, `remote`, `exposed`, `startWorkflow`, `agent` and
 `rpcWithWire`, and nothing else. Every one of those reads was `undefined`, and
 the `rpcService: any` parameter type is what kept the compiler quiet about it.

package/knowledge/decisions/internals/addon-singleton-services-are-cached-per-namespace-not-per-package.md

@@ -17,7 +17,7 @@ One package may be wired twice — the same payments addon against a live and a
 sandbox account, say — with different secret and variable names. Caching by
 package name would build the service graph once, from whichever instance called
 first, and silently hand the other instance the wrong credentials. Because the
-overrides have to be visible to the addon's *own* `createSingletonServices`, they
+overrides have to be visible to the addon's _own_ `createSingletonServices`, they
 are applied by wrapping the parent `secrets` and `variables` services
 (`aliasSecretService`, `aliasVariablesService`) so that every logical name the
 addon reads is remapped to the real project name before resolution. A call with

package/knowledge/decisions/internals/addon-workflow-names-are-prefixed-with-the-consumer-namespace.md

@@ -15,7 +15,7 @@ instance namespace when known and otherwise the package's sole namespace via
 `findAddonNamespaceForPackage`.
 
 Workflows declared by an addon are registered under the addon's package scope,
-but the namespace they answer to is chosen by the *consumer* in `wireAddon`.
+but the namespace they answer to is chosen by the _consumer_ in `wireAddon`.
 Without the proxy, `runToCompletion('myWorkflow')` written inside the addon
 resolves against root meta, misses, and throws `WorkflowNotFoundError` — leaving
 the addon author no option but to hardcode the consumer-defined namespace, which

package/knowledge/decisions/internals/an-addon-scope-root-loses-to-a-root-the-host-already-declares.md

@@ -24,7 +24,7 @@ permissions bug rather than a merge that dropped.
 This is a different rule from
 [scope roots may be co-declared by an addon and its host
 app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md): that one
-is about `flattenScopeDefinitions` deduping ids *within* a build where both
+is about `flattenScopeDefinitions` deduping ids _within_ a build where both
 declarations are present and identical. This one is about the addon's copy never
 arriving. The consequence for addon authors is the same either way — own a root
 outright, named for the package or vendor, and nest everything under it. It is

package/knowledge/decisions/internals/channel-message-handlers-accept-three-config-shapes.md

@@ -14,7 +14,7 @@ things a caller may put on `onMessage` or inside `onMessageWiring`:
 - a direct function config, where `onMessage.func` is a plain `Function`;
 - a wrapper, where `onMessage.func` is itself a `CorePikkuFunctionConfig` and so
   has its own nested `.func`;
-- a simple wrapper, which carries a plain `Function` under `func` *and* a
+- a simple wrapper, which carries a plain `Function` under `func` _and_ a
   sibling `middleware` array.
 
 The `isWrapper` check tests exactly that: an object with `func`, where either

package/knowledge/decisions/internals/channel-middleware-caches-only-statically-resolved-middleware.md

@@ -19,7 +19,7 @@ user's stream and growing memory run over run. It is therefore appended fresh on
 every call, after the cached inherited slice.
 
 The `uid` matters as much as the cache split. `processMessageHandlers` in
-`channel-handler.ts` builds it from the channel name *plus* the routing property
+`channel-handler.ts` builds it from the channel name _plus_ the routing property
 and router value (`${name}:${routingProperty}:${routerValue}`, or
 `${name}:default`), because several message routes on one channel may point at
 the same function — a key based on the function alone would serve one route's

package/knowledge/decisions/internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md

@@ -10,7 +10,7 @@ tags: channel
 `runChannelConnect` in
 `packages/core/src/wirings/channel/serverless/serverless-channel-runner.ts`
 reads `userSession.getPikkuUserId()` and calls `channelStore.setPikkuUserId`
-*after* `runChannelLifecycleWithMiddleware` has executed the `onConnect`
+_after_ `runChannelLifecycleWithMiddleware` has executed the `onConnect`
 lifecycle, not before.
 
 Auth middleware runs as part of that lifecycle — it is what inspects the upgrade

package/knowledge/decisions/internals/cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md

@@ -19,7 +19,7 @@ the conversion happens. The parser normalises every incoming `--from-plan` to
 `fromPlan` on the way in, and both `formatOptions` (help text) and the
 "Missing required option" / "Invalid value for" errors render back to kebab on
 the way out. `suggestOption` deliberately compares the typed string against
-*both* forms, so `--autoApply` and `--auto-apply` both find `autoApply`.
+_both_ forms, so `--autoApply` and `--auto-apply` both find `autoApply`.
 
 **What this rules out:** storing option keys kebab-cased anywhere in CLI state or
 metadata — the schema pluck would then match nothing and every option would be

package/knowledge/decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md

@@ -18,7 +18,7 @@ mistake (show the help text) or a value mistake (print the errors) by
 This is why the parser pushes `Missing subcommand: <path>` for a group command
 that has subcommands but no `pikkuFuncId` of its own, rather than simply
 returning the command meta and letting the runner discover it is unrunnable. The
-message *is* the routing signal. Rewording any of those three strings, or
+message _is_ the routing signal. Rewording any of those three strings, or
 localising them, silently turns "show me the subcommands" into a raw error dump.
 
 **What this rules out:** editing those error message prefixes without updating

package/knowledge/decisions/internals/cli-unknown-long-options-warn-instead-of-failing.md

@@ -18,7 +18,7 @@ The reason is forward compatibility: a script or wrapper written against a newer
 command version may pass options an older installed binary does not know, and
 failing hard there turns a harmless extra flag into a broken pipeline.
 `RESERVED_OPTIONS` exempts flags the runner handles itself (`help`) from the
-warning. Unknown *short* flags are treated differently — they go to
+warning. Unknown _short_ flags are treated differently — they go to
 `result.errors` and do fail — because a bundled short-flag cluster like `-abc`
 cannot be reliably attributed, and a typo'd short flag is far more likely than a
 version skew.

package/knowledge/decisions/internals/core-column-form-is-an-axis-of-its-own.md

@@ -15,13 +15,13 @@ value leave the process?".
 The two axes were one field before this, with `security: 'encrypted'` sitting
 alongside `secret` as though they were alternatives. They are not, and the
 conflation 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 —
+both `secret`, one must never be encrypted — the digest _is_ the lookup key —
 and the other must always be. Nothing in a single enum could tell them apart, so
 nothing could check either.
 
 ## Why `wrapped` and `sealed` rather than `encrypted`
 
-Sealed values *are* encrypted, so an `encrypted` member sitting beside `sealed`
+Sealed values _are_ encrypted, so an `encrypted` member sitting beside `sealed`
 would be a supertype posing as a sibling, and every new column would be an
 even-odds guess. What actually separates them is who can read the value back:
 `wrapped` is symmetric and the application holds the key; `sealed` is asymmetric
@@ -64,7 +64,7 @@ it would buy nothing — feeding in the wrong string already fails at the AEAD t
 — while forcing a cast into every path that reads ciphertext out of a row or off
 the wire, which is where casts are least reviewable.
 
-The brand proves *provenance*, not correctness. It cannot know a value was
+The brand proves _provenance_, not correctness. It cannot know a value was
 wrapped under the right key, and making it know would mean phantom-typing key
 ids per scope, which the multi-recipient path would fight constantly.
 
@@ -75,7 +75,7 @@ error. Every project predating the axis has such columns, and failing their next
 `db migrate` would be a breaking change for a diagnosis they have not had a
 chance to act on. `pikku db --fail-on-warn` is how a project opts into the
 ratchet. An explicit `form: 'plain'` silences it — that is the acknowledgement
-that reading the row is *meant* to yield a usable credential.
+that reading the row is _meant_ to yield a usable credential.
 
 **What this rules out:** collapsing `wrapped` and `sealed` back into one
 `encrypted`; making the form brands optional (they would enforce nothing);

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -16,7 +16,7 @@ A required property would make a plain value unassignable to a branded column: a
 `string` could no longer be passed where `Private<string>` is expected, which
 breaks every ordinary Kysely query operand — `where('email', '=', someString)`,
 inserts, and `.set(...)`. Making it optional keeps the brand structurally present
-so static analysis still sees it, while letting plain values flow *in*. The
+so static analysis still sees it, while letting plain values flow _in_. The
 asymmetry is the point: the brand constrains what comes out of a query, not what
 goes into one.
 

package/knowledge/decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md

@@ -9,7 +9,7 @@ tags: core
 
 `runPikkuFunc` in `packages/core/src/function/function-runner.ts` does not build a
 fresh wire per call. Nested invocations — an RPC from inside a function, an addon
-sibling call, a workflow step — reuse the *same* wire object the outer transport
+sibling call, a workflow step — reuse the _same_ wire object the outer transport
 created. So before it runs, the runner captures `functionId`, `audit`,
 `addonNamespace` and the property descriptor for `rpc`, overwrites them for the
 duration of this function, and restores or `delete`s them in a `finally`. Both
@@ -18,7 +18,7 @@ inner call would leave its identity on the wire and every subsequent outer step
 would be attributed to the wrong function.
 
 The same reuse is why the audit binding is re-gated inside `executeFunction`
-rather than trusted from `createWireServices`. The audit *gate* is per-function
+rather than trusted from `createWireServices`. The audit _gate_ is per-function
 but the `auditLog` wire service is created per-transport-invocation. A nested or
 exposed-RPC call would otherwise inherit an `auditLog` built while the outer
 wire's audit config was unset (the generated `rpcCaller` declares none), and
@@ -32,7 +32,7 @@ then the auth/readonly checks, then `verifyScopes` — all of which depend only
 the session — and only then `await data()`, schema defaults, coercion, validation
 and `runPermissions`. A request denied by scope never pays to parse or validate
 its body. `rpc` is installed as a lazily-evaluating accessor that replaces itself
-with the resolved value on first read, capturing the *caller's* package name in
+with the resolved value on first read, capturing the _caller's_ package name in
 the closure so an addon's RPCs resolve in its own namespace.
 
 **What this rules out:** dropping the save/restore blocks as duplicated

package/knowledge/decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md

@@ -22,7 +22,7 @@ workflow job fails with `Function meta not found: pikkuWorkflowOrchestrator`.
 `dev/reload-meta.test.ts` pins this. Meta maps that only codegen ever writes
 (`http`, `rpc`, `agent`) are assigned outright.
 
-Two limits are inherent rather than incidental. Routes registered by a *new*
+Two limits are inherent rather than incidental. Routes registered by a _new_
 `wireHTTP` file are not picked up here — those modules were never imported — which
 is why `hot-reload.ts` keeps a `postCodegenQueue` and exposes `reimportPending()`
 for the dev server to drain after codegen, so registrations that were skipped for
@@ -35,5 +35,5 @@ entry stranded until a restart.
 `pikkuState(null, 'function', 'meta', functionsMeta)` assignments on the grounds
 that codegen output is authoritative — it is authoritative only for what codegen
 emits. It also rules out folding `reimportPending()` back into the debounced
-reload (the whole point is that it runs *after* codegen), and dropping
+reload (the whole point is that it runs _after_ codegen), and dropping
 `reconcileAddonRegistry` as dead code.

package/knowledge/decisions/internals/core-hot-reload-owns-its-module-registry.md

@@ -23,7 +23,7 @@ edits, and eventually OOMs a long editing session. `dev/module-runner.test.ts`
 asserts both the single-slot guarantee and bounded heap growth.
 
 Two details keep the mechanism honest. `import`s inside the user file are
-delegated to `createRequire`, whose resolution matches the native loader *and*
+delegated to `createRequire`, whose resolution matches the native loader _and_
 returns the same live singletons (Node and Bun share the require/import cache) —
 that is what lets a reloaded file's top-level `wireHTTP` side effects mutate the
 services the running server is already using. And esbuild is invoked with no
@@ -37,6 +37,6 @@ code.
 import(url + '?t=' + Date.now())` or any fresh-URL variant, and turning
 sourcemaps back on for nicer stack traces (`filename` already anchors traces to
 the user file). It also rules out swapping `createRequire` for a fresh `import()`
-inside the compiled module — resolution would produce a *distinct* copy of every
+inside the compiled module — resolution would produce a _distinct_ copy of every
 dependency, and the reloaded file would then wire itself into services nobody is
 serving from.

package/knowledge/decisions/internals/core-middleware-order-is-scope-then-priority.md

@@ -19,7 +19,7 @@ finally passed through `freezeDedupe` and cached in `middlewareCache` keyed by
 wire type and wire id.
 
 Two properties fall out of that and both are load-bearing. Because the sort is
-stable, priority is a coarse band and registration order breaks ties *within* a
+stable, priority is a coarse band and registration order breaks ties _within_ a
 band, so declaration order still means something. And because the result is
 deduped by function identity, a middleware reachable through both a tag group and
 a direct wire registration runs exactly once — a fact several tests assert