@pikku/core 0.12.72 → 0.12.77

package/dist/wirings/workflow/workflow-queue-workers.d.ts

@@ -1,17 +1,9 @@
-/**
- * Queue worker functions for workflow orchestration.
- *
- * These are registered as queue consumers by the codegen pipeline
- * (injected into queue meta when workflows exist). They provide
- * the runtime implementations that process queued workflow jobs.
- */
 import type { PikkuRPC } from '../rpc/rpc-types.js';
 export interface WorkflowStepInput {
     runId: string;
     stepName: string;
     rpcName: string;
     data: unknown;
-    /** Predecessor step name (the walked transition); undefined for entry steps. */
     fromStepName?: string;
 }
 export interface PikkuWorkflowOrchestratorInput {
@@ -21,22 +13,10 @@ export interface PikkuWorkflowSleeperInput {
     runId: string;
     stepId: string;
 }
-/**
- * Step worker — executes individual workflow steps dispatched via queue.
- * The orchestrator queues steps here when they're async (not inline).
- */
 export declare function pikkuWorkflowWorkerFunc(_services: Record<string, unknown>, { runId, stepName, rpcName, data }: WorkflowStepInput, { rpc }: {
     rpc: PikkuRPC;
 }): Promise<void>;
-/**
- * Orchestrator — resumes workflow execution after an async step completes.
- * Called when a step worker finishes and the workflow needs to continue.
- */
 export declare function pikkuWorkflowOrchestratorFunc(_services: Record<string, unknown>, { runId }: PikkuWorkflowOrchestratorInput, { rpc }: {
     rpc: PikkuRPC;
 }): Promise<void>;
-/**
- * Sleeper — wakes a workflow after a workflow.sleep() duration expires.
- * Triggered by a delayed queue message or scheduler callback.
- */
 export declare function pikkuWorkflowSleeperFunc(_services: Record<string, unknown>, { runId, stepId }: PikkuWorkflowSleeperInput): Promise<void>;

package/dist/wirings/workflow/workflow-queue-workers.js

@@ -1,15 +1,4 @@
-/**
- * Queue worker functions for workflow orchestration.
- *
- * These are registered as queue consumers by the codegen pipeline
- * (injected into queue meta when workflows exist). They provide
- * the runtime implementations that process queued workflow jobs.
- */
 import { getSingletonServices } from '../../pikku-state.js';
-/**
- * Step worker — executes individual workflow steps dispatched via queue.
- * The orchestrator queues steps here when they're async (not inline).
- */
 export async function pikkuWorkflowWorkerFunc(_services, { runId, stepName, rpcName, data }, { rpc }) {
     const services = getSingletonServices();
     if (!services?.workflowService) {
@@ -17,10 +6,6 @@ export async function pikkuWorkflowWorkerFunc(_services, { runId, stepName, rpcN
     }
     await services.workflowService.executeWorkflowStep(runId, stepName, rpcName, data, rpc);
 }
-/**
- * Orchestrator — resumes workflow execution after an async step completes.
- * Called when a step worker finishes and the workflow needs to continue.
- */
 export async function pikkuWorkflowOrchestratorFunc(_services, { runId }, { rpc }) {
     const services = getSingletonServices();
     if (!services?.workflowService) {
@@ -28,10 +13,6 @@ export async function pikkuWorkflowOrchestratorFunc(_services, { runId }, { rpc
     }
     await services.workflowService.orchestrateWorkflow(runId, rpc);
 }
-/**
- * Sleeper — wakes a workflow after a workflow.sleep() duration expires.
- * Triggered by a delayed queue message or scheduler callback.
- */
 export async function pikkuWorkflowSleeperFunc(_services, { runId, stepId }) {
     const services = getSingletonServices();
     if (!services?.workflowService) {

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

@@ -10,7 +10,6 @@ export interface WorkflowRunWire {
     id?: string;
     parentRunId?: string;
     parentStepId?: string;
-    /** Pikku user ID propagated from the originating request for credential resolution */
     pikkuUserId?: string;
 }
 export interface WorkflowServiceConfig {
@@ -20,126 +19,48 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     sleeperRPCName: string;
 }
-/**
- * How a workflow service spreads its jobs across queues.
- *
- * Passed to the service constructor rather than read from `config.workflow`:
- * the queues are wired during construction, before singleton services (and so
- * before `config`) exist.
- */
 export interface WorkflowQueueOptions {
-    /**
-     * - `'per-workflow'` (default) — each workflow gets its own
-     *   `wf-orchestrator-*` / `wf-step-*` queue. Complete isolation, and it's
-     *   what lets serverless providers deploy one unit per workflow. Costs one
-     *   set of pollers per queue, which adds up on pull-based backends.
-     * - `'shared-groups'` — every workflow shares the orchestrator/step-worker
-     *   queues and stays isolated via {@link queueGroupConcurrency}, so no
-     *   workflow can occupy more than its share. One set of pollers total.
-     *   Only for single-process (monolith) runtimes; a per-unit serverless
-     *   deploy needs the per-workflow queues to route to its units.
-     */
     queueStrategy?: 'per-workflow' | 'shared-groups';
-    /**
-     * Total concurrent workflow jobs per node under `'shared-groups'`.
-     * Defaults to 20.
-     */
     queueConcurrency?: number;
-    /**
-     * How many jobs of one workflow may run at once under `'shared-groups'`.
-     * Defaults to 2. Tiers are keyed by workflow name, so a specific workflow
-     * can be given its own limit without any extra wiring.
-     *
-     * Note tiers can only lower a workflow's limit, not raise it above
-     * `default`: the backend's pre-fetch exclusion is applied per group using
-     * `default` alone. To give one workflow more room, raise `default` and
-     * restrict the others by tier.
-     */
     queueGroupConcurrency?: number | GroupConcurrencyConfig;
 }
 export interface WorkflowPlannedStep {
-    /** Durable step key — matches the runtime step name stored in the DB */
     stepName: string;
-    /** Optional human-readable label for the UI timeline (falls back to stepName) */
     displayName?: string;
 }
-/**
- * Workflow run status
- */
 export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
-/**
- * Workflow version status (for AI-generated workflows)
- */
 export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
-/**
- * Workflow step status
- */
 export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended';
-/**
- * Workflow run representation
- */
 export interface WorkflowRun {
-    /** Unique run ID */
     id: string;
-    /** Workflow name */
     workflow: string;
-    /** Current status */
     status: WorkflowStatus;
-    /** Input data */
     input: any;
-    /** Output data (if completed) */
     output?: any;
-    /** Error (if failed) */
     error?: SerializedError;
-    /** If true, workflow executes inline without queues */
     inline?: boolean;
-    /** Graph hash of the workflow definition at run creation time */
     graphHash?: string;
-    /** True when the workflow has a static, pre-computable step timeline */
     deterministic?: boolean;
-    /** Static planned steps snapshot captured at run start */
     plannedSteps?: WorkflowPlannedStep[];
-    /** Wire origin info (how this run was started) */
     wire: WorkflowRunWire;
-    /** Creation timestamp */
     createdAt: Date;
-    /** Last update timestamp */
     updatedAt: Date;
 }
-/**
- * Step state representation
- */
 export interface StepState {
-    /** Unique step ID */
     stepId: string;
-    /** Step status */
     status: StepStatus;
-    /** Step result (if done) */
     result?: any;
-    /** Step error (if error) */
     error?: SerializedError;
-    /** Number of attempts made (starts at 1) */
     attemptCount: number;
-    /** Maximum retry attempts allowed */
     retries?: number;
-    /** Delay between retries */
     retryDelay?: string | number;
-    /** Step name of the predecessor that scheduled this step (the transition/edge
-     *  walked to reach it); undefined for entry steps. Reconstructs the path. */
     fromStepName?: string;
-    /** Creation timestamp */
     createdAt: Date;
-    /** Last update timestamp */
     updatedAt: Date;
-    /** Child workflow run ID (if this step spawned a sub-workflow) */
     childRunId?: string;
-    /** Timestamp when step started running */
     runningAt?: Date;
-    /** Timestamp when step was scheduled */
     scheduledAt?: Date;
-    /** Timestamp when step succeeded */
     succeededAt?: Date;
-    /** Timestamp when step failed */
     failedAt?: Date;
 }
 export interface WorkflowRunStatus {
@@ -153,7 +74,6 @@ export interface WorkflowRunStatus {
         name: string;
         status: StepStatus;
         duration?: number;
-        /** Number of attempts for this step (1 = first try; > 1 means it retried). */
         attempts?: number;
     }>;
     output?: unknown;
@@ -184,16 +104,6 @@ export interface WorkflowRunService {
     } | null>;
     deleteRun(id: string): Promise<boolean>;
 }
-/**
- * Write-only companion to `WorkflowRunService`. An executor (a
- * `PikkuWorkflowService` subclass) can be given a mirror; every write
- * the executor makes to its own canonical store is then forwarded here,
- * so an external read store (e.g. a DB queried by the console UI) stays
- * in sync with DO/Redis/etc-driven runs.
- *
- * Mirror failures are logged but never fail the workflow — the mirror is
- * an index, not the source of truth.
- */
 export interface WorkflowRunMirror {
     createRun(runId: string, workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
@@ -218,187 +128,87 @@ export interface WorkflowRunMirror {
     upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
 }
-/**
- * Core workflow definition
- */
 export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
-    /** Unique workflow name */
     name: string;
-    /** The workflow function */
     func: PikkuFunctionConfig;
-    /** Middleware chain for this workflow */
     middleware?: PikkuFunctionConfig['middleware'];
-    /** Tags for organization and filtering */
     tags?: string[];
 };
-/**
- * A scenario as a feature references it: either the scenario itself, or the
- * scenario paired with the input to run it with. The paired form is gherkin's
- * `Examples:` — the same scenario run once per row, written as an ordinary
- * loop rather than a table.
- */
 export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
     scenario: CorePikkuFunctionConfig<any, any, any>;
     data: unknown;
 };
-/**
- * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
- * Scenario structure. Scenarios are referenced by imported identifier, so a
- * renamed or deleted scenario is a compile error rather than a silent skip.
- *
- * Hooks run **once around the whole group** (`before → a → b → c → after`),
- * not per scenario — per-scenario setup is the scenario's own `before`. That
- * is the one thing a feature deliberately cannot express: gherkin's
- * `Background:` runs per scenario.
- */
 export type CoreFeature = {
-    /** Human-readable name. The export identifier is the id. */
     name: string;
     description?: string;
     tags?: string[];
-    /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
     scenarios: readonly CoreFeatureScenario[];
     before?: CorePikkuFunctionHook;
     after?: CorePikkuFunctionHook;
 };
-/** One entry of a feature's scenario list, as extracted from the source. */
 export type FeatureMetaEntry = {
-    /** The scenario's declared export name — its key in `WorkflowsMeta`. */
     scenario: string;
-    /** The input this entry runs the scenario with — gherkin's `Examples:`. */
     data?: unknown;
 };
-/**
- * A feature as the console reads it: the document structure around a group of
- * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
- * nothing app-facing has to import the scenario bootstrap to describe one.
- */
 export type FeatureMeta = {
-    /** The export identifier. */
     id: string;
     name: string;
     description?: string;
     tags: string[];
-    /** In declared order — a feature's reading order is its declaration order. */
     entries: FeatureMetaEntry[];
-    /**
-     * Entries that could not be read statically (a spread, a `.map()`). Their
-     * membership is only known once the scenario bootstrap has been evaluated,
-     * so a non-zero count means this listing is partial.
-     */
     unresolvedEntries: number;
-    /** Hooks are runtime-only; only their presence is knowable from meta. */
     hasBefore: boolean;
     hasAfter: boolean;
 };
 export type FeaturesMeta = Record<string, FeatureMeta>;
-/** One planned scenario run, resolved from a feature's scenario list. */
 export type FeaturePlanEntry = {
     featureId: string;
     featureName: string;
     scenarioName: string;
-    /** The input this entry runs the scenario with, if the feature supplied one. */
     data?: unknown;
-    /** The scenario's own tags unioned with the containing feature's. */
     tags: string[];
 };
-/**
- * Workflow client interface
- */
 export interface PikkuWorkflow {
-    /** Start a new workflow run */
     start: <I>(input: I) => Promise<{
         runId: string;
     }>;
-    /** Get a workflow run by ID */
     getRun: (runId: string) => Promise<WorkflowRun>;
-    /** Cancel a running workflow */
     cancelRun: (runId: string) => Promise<void>;
 }
-/**
- * Context variable definition (serialized from Zod schema or type inference)
- */
 export interface ContextVariable {
-    /** Variable type */
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-    /** Default value */
     default?: unknown;
-    /** Description for UI/docs */
     description?: string;
 }
-/**
- * Workflow context - state variables with defaults and types
- */
 export type WorkflowContext = Record<string, ContextVariable>;
-/**
- * Workflows metadata for inspector/CLI (DSL step-based format)
- */
 export type WorkflowsMeta = Record<string, CommonWireMeta & {
     name: string;
     steps: WorkflowStepMeta[];
     context?: WorkflowContext;
     dsl?: boolean;
     expose?: boolean;
-    /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean;
     /**
-     * Why a scenario is held out of a default run. Stating the reason in code
-     * keeps the quarantine next to the scenario it applies to, rather than in
-     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
-     * regardless.
+     * The flow asserts through an expectation helper — `expectService`,
+     * `expectError`, `expectEventually` — rather than a `then` step. Those are
+     * inline steps and carry no phase, so without this PKU680 reads a scenario
+     * whose only witness is a recorded service call as asserting nothing.
      */
+    asserts?: boolean;
     skip?: string;
-    /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
 }>;
-/**
- * Unified workflow runtime meta (used by runtime to execute workflows)
- * This is the format stored in pikkuState('workflows', 'meta')
- * Both DSL and graph-based workflows are converted to this format
- */
 export interface WorkflowRuntimeMeta {
-    /** Workflow name (used as key in registrations) */
     name: string;
-    /** Pikku function name (for execution) */
     pikkuFuncId: string;
-    /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'scenario' (complex + actor steps) */
     source: 'dsl' | 'complex' | 'graph' | 'scenario';
-    /** Optional description */
     description?: string;
-    /** Tags for organization */
     tags?: string[];
-    /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
-    /** Serialized nodes */
     nodes?: Record<string, any>;
-    /** Entry node IDs for graph workflows (computed at build time) */
     entryNodeIds?: string[];
-    /** Hash of graph topology (nodes, edges, input mappings) */
     graphHash?: string;
-    /** True when the workflow has a static, pre-computable step timeline */
     deterministic?: boolean;
-    /** Static planned steps metadata for deterministic workflows */
     plannedSteps?: WorkflowPlannedStep[];
 }
-/**
- * Unified workflow runtime metadata map
- */
 export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>;
-/**
- * Worker input types for generated queue workers
- */
-export type WorkflowStepInput = {
-    runId: string;
-    stepName: string;
-    rpcName: string;
-    data: any;
-    /** Predecessor step name (the walked transition); undefined for entry steps. */
-    fromStepName?: string;
-};
-export type WorkflowOrchestratorInput = {
-    runId: string;
-};
-export type WorkflowSleeperInput = {
-    runId: string;
-    stepId: string;
-};

package/knowledge/decisions/index.md

@@ -0,0 +1,19 @@
+---
+type: overview
+title: Decisions
+description: Rules chosen in @pikku/core, and what each one rules out
+---
+
+# Decisions
+
+A rule that was chosen, and what it rules out.
+
+Each note here replaces a comment that was carrying reasoning inside the source.
+If you are about to "clean up" something in core that looks pointless, search
+here first — several of these exist because the obvious simplification was tried
+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-secret-that-fails-to-decrypt-fails-the-whole-read.md

@@ -0,0 +1,49 @@
+---
+type: decision
+title: A secret that fails to decrypt fails the whole read
+description: getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
+tags: crypto, storage
+---
+
+# A secret that fails to decrypt fails the whole read
+
+Every store's bulk read — `getSecrets` in the kysely, mongodb and redis secret
+services — wraps the `getKEK` + `envelopeDecrypt` pair in a try/catch that
+rethrows:
+
+```
+Failed to decrypt secret "<key>" (key_version <n>): the configured KEK does not
+match the key it was wrapped under
+```
+
+with the original crypto error as `cause`. A key that has no row at all is still
+simply absent from the returned object; only a row that exists and will not
+decrypt is fatal.
+
+Those two cases look similar and are not. A missing key is an ordinary, callable
+state — the caller asked for something that was never stored, and the typed
+secret layer above already decides what to do about an absent value. A stored
+row that will not decrypt means the service is holding ciphertext it cannot
+read: a `PIKKU_SECRET_KEK` that does not match what the value was wrapped under,
+a `previousKey` missing for an older `keyVersion`, or a change to the derivation
+itself. Nothing the caller can do downstream makes that better.
+
+Dropping the row instead hands back a partial map, and the failure re-emerges
+somewhere with no connection to secrets — an auth middleware reading an
+undefined signing key and answering "server configuration error", a provider
+client constructed with `undefined` credentials and 401-ing. The name of the
+secret and the `key_version` it was wrapped under are precisely the two facts
+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
+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
+`undefined` for a row that exists; collecting failures and returning them
+alongside the successes, which just moves the ignoring one level up; and
+treating a missing key as an error, which would break callers that legitimately
+probe for optional secrets.
+
+See [[the-kek-salt-is-scoped-to-the-key-version]].

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

@@ -0,0 +1,48 @@
+---
+type: decision
+title: A virtual user run is not a workflow and not a queued job
+description: runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
+tags: virtual-user, storage
+---
+
+# A virtual user run is not a workflow and not a queued job
+
+`runVirtualUser` — the RPC `scaffold.virtualUser` generates — does three things
+in order: writes a `VirtualUserRunStore` record, dispatches
+`executeVirtualUserRun` **without awaiting it**, and returns the `runId`. There
+is no workflow, no queue, and no worker.
+
+Both of the alternatives are the obvious ones, and both are wrong for this.
+
+**A workflow** is a replayable step graph: its value is that a run can be
+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
+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
+explores the same way — which is a different property from resumable, and one
+the record already carries.
+
+**A queue** buys durability across a restart and a retry on failure. It costs a
+broker dependency in every application that turns the scaffold on, plus a worker
+whose progress cannot be read anyway: the run's state lives in the store, not in
+the queue entry. The queue would be holding a copy of what the record already
+has, on the way to the same place.
+
+So the record is the run's only trace, and that is what `VirtualUserRunStore`
+exists for. It is also why `fail()` is a method rather than an absence: a run
+that crashed and a run that found nothing are different answers, and a record
+left at `running` is neither.
+
+The cost is real and is stated on the type: **a restart mid-run strands a record
+at `running` with nothing left to finish it.** A run older than its budget
+window and still `running` is dead, not working — that is a read-side rule, and
+it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
+is started again, with its seed if the caller wants the same exploration.
+
+**What this rules out:** dispatching the run through `startWorkflow`; a
+scaffolded queue worker; awaiting the engine inside the request (a run takes
+minutes and survives neither a rollout nor a proxy timeout); and inferring
+`status` from `finishedAt` being unset, which cannot separate a crash from a run
+still going.

package/knowledge/decisions/internals/actor-flow-conversations-seed-a-hidden-kickoff-message.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An actor conversation starts from a seeded kickoff message
+description: The actor's first turn needs a non-empty message list because providers reject an empty prompt; the seed is an instruction and stays out of the transcript
+tags: actor-flow
+---
+
+# An actor conversation starts from a seeded kickoff message
+
+`runConversation` in
+`packages/core/src/wirings/actor-flow/run-conversation.ts` primes
+`actorMessages` with a single user message telling the persona to begin, before
+the first turn is generated.
+
+The actor speaks first, so at that point there is nothing for it to reply to —
+and LLM providers reject a completion request with no messages. The seed is
+addressed to the actor rather than to the target agent, which is why it is never
+pushed onto `transcript`: it is scaffolding, not something the simulated user
+said, and including it would corrupt the transcript the final evaluation reads.
+
+**What this rules out:** starting from an empty `actorMessages` array, folding
+the kickoff into the persona instructions where a provider may weight it
+differently, and pushing the seed into the transcript for symmetry.

package/knowledge/decisions/internals/actor-flow-drives-the-target-through-a-transport-seam.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: The actor-flow conversation engine only sees a transport-agnostic target driver
+description: The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
+tags: actor-flow
+---
+
+# The actor-flow conversation engine only sees a transport-agnostic target driver
+
+`runConversation` reaches the target agent exclusively through the injected
+`TargetAgentDriver` — `run(message)` and `approve(runId, decisions)` — declared
+in `packages/core/src/wirings/actor-flow/actor-flow.types.ts`. In production that
+driver is HTTP-backed, issuing the actor's `agentRun` and `agentApprove` calls as
+the signed-in actor.
+
+Keeping the seam transport-agnostic is what makes the conversation a real test:
+the agent is exercised through the same authenticated wire path a user takes,
+including middleware, permissions and session handling, rather than through an
+in-process call that skips all of it. It also lets the engine be unit-tested
+against scripted targets with no server at all.
+
+**What this rules out:** calling `runAIAgent` / `streamAIAgent` directly from the
+conversation engine, and widening `TargetAgentDriver` with transport details
+(headers, cookies, channels) that would tie the engine to HTTP.

package/knowledge/decisions/internals/actor-flow-verdicts-are-llm-self-evaluations.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: An actor-flow verdict is the persona's self-evaluation, not an assertion
+description: The engine returns what the actor judged plus the transcript; deterministic checks stay with the caller
+tags: actor-flow
+---
+
+# An actor-flow verdict is the persona's self-evaluation, not an assertion
+
+`runConversation` ends by asking the persona LLM whether the `evaluate`
+criterion was met and returns that as `ActorFlowVerdict` — `passed`, `reasoning`
+and the full `transcript`
+(`packages/core/src/wirings/actor-flow/`). Nothing in the engine inspects the
+system the agent acted on.
+
+The verdict is deliberately soft because the thing it judges is soft: whether a
+conversation accomplished a natural-language task. Deterministic checks — that a
+row was written, that an email went out — belong to the caller, which already
+holds the actor and can `actor.invoke(...)` after the conversation returns. The
+`reasoning` and `transcript` fields exist so a soft failure is debuggable rather
+than merely red.
+
+**What this rules out:** having `runConversation` assert or throw on a failed
+verdict, and adding deterministic post-conditions to `ConverseOptions` instead of
+running them at the call site.

package/knowledge/decisions/internals/addon-package-roots-resolve-by-walking-node-module-search-paths.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Addon package roots resolve by walking node module search paths
+description: LocalMetaService finds an addon's directory by scanning resolve.paths, not by require.resolve, because addon packages expose no main entry
+tags: services
+---
+
+# Addon package roots resolve by walking node module search paths
+
+`LocalMetaService.resolvePackageRoot` (`packages/core/src/services/meta-service.ts`)
+builds a `createRequire` anchored one level above `.pikku` — the app root — then
+walks `require.resolve.paths(packageName)` and takes the first candidate
+directory that contains a `package.json`. The result is memoised in
+`packageRootCache`.
+
+The obvious call, `require.resolve(packageName)`, throws for these packages:
+Pikku addon packages ship a `.pikku` directory and subpath exports but no main
+`exports` entry, so there is nothing for Node to resolve to. Walking the search
+paths asks the same question Node would ask — where would this package be
+found from the app root — without requiring the package to be importable.
+
+**What this rules out:** replacing the loop with `require.resolve(pkg)`,
+`import.meta.resolve`, or `createRequire(import.meta.url)`. The first two fail on
+every addon; the third anchors resolution at `@pikku/core`'s own location rather
+than the app's, so an addon installed only in the app's `node_modules` becomes
+invisible.