@pikku/inspector 0.12.103 → 0.12.106

package/dist/utils/serialize-inspector-state.d.ts

@@ -269,8 +269,8 @@ export interface SerializableInspectorState {
         definitions: InspectorState['featureFlags']['definitions'];
         files: string[];
     };
-    personas: {
-        definitions: InspectorState['personas']['definitions'];
+    virtualUsers: {
+        definitions: InspectorState['virtualUsers']['definitions'];
         files: string[];
     };
     variables: {

package/dist/utils/serialize-inspector-state.js

@@ -140,9 +140,9 @@ export function serializeInspectorState(state) {
             definitions: state.featureFlags.definitions,
             files: Array.from(state.featureFlags.files),
         },
-        personas: {
-            definitions: state.personas.definitions,
-            files: Array.from(state.personas.files),
+        virtualUsers: {
+            definitions: state.virtualUsers.definitions,
+            files: Array.from(state.virtualUsers.files),
         },
         variables: {
             definitions: state.variables.definitions,
@@ -330,9 +330,9 @@ export function deserializeInspectorState(data) {
             definitions: data.featureFlags?.definitions || [],
             files: new Set(data.featureFlags?.files || []),
         },
-        personas: {
-            definitions: data.personas?.definitions || [],
-            files: new Set(data.personas?.files || []),
+        virtualUsers: {
+            definitions: data.virtualUsers?.definitions || [],
+            files: new Set(data.virtualUsers?.files || []),
         },
         variables: {
             definitions: data.variables?.definitions || [],

package/dist/utils/single-declaration.d.ts

@@ -3,18 +3,18 @@ import type { InspectorLogger } from '../types.js';
 /**
  * Claims the one call site a single-declaration construct is allowed.
  *
- * `definePersonas` takes a keyed object, so one call already declares as many
+ * `defineVirtualUsers` takes a keyed object, so one call already declares as many
  * entries as you like. Letting the call itself repeat buys nothing and costs
  * the thing that matters: a single place to read the declared set from, and a
  * single place to add to it. The same rule `pikkuBetterAuth` has had all along.
  *
  * A second call in the SAME file is refused too — "the file" is not an answer
- * to "where do I add a persona?" when the file holds two calls, so allowing it
+ * to "where do I add a virtual user?" when the file holds two calls, so allowing it
  * would keep the ambiguity the rule exists to remove.
  *
  * A generated file is exempt, and never claims the slot either. The rule exists
  * to name the one place a person adds to, and nobody adds to a file the CLI
- * rewrites on the next run — `pikku-personas.gen.ts` would otherwise make every
+ * rewrites on the next run — `pikku-virtual-users.gen.ts` would otherwise make every
  * project that scaffolds one unbuildable, and take the app's own declaration
  * down with it.
  *

package/dist/utils/single-declaration.js

@@ -1,18 +1,18 @@
 /**
  * Claims the one call site a single-declaration construct is allowed.
  *
- * `definePersonas` takes a keyed object, so one call already declares as many
+ * `defineVirtualUsers` takes a keyed object, so one call already declares as many
  * entries as you like. Letting the call itself repeat buys nothing and costs
  * the thing that matters: a single place to read the declared set from, and a
  * single place to add to it. The same rule `pikkuBetterAuth` has had all along.
  *
  * A second call in the SAME file is refused too — "the file" is not an answer
- * to "where do I add a persona?" when the file holds two calls, so allowing it
+ * to "where do I add a virtual user?" when the file holds two calls, so allowing it
  * would keep the ambiguity the rule exists to remove.
  *
  * A generated file is exempt, and never claims the slot either. The rule exists
  * to name the one place a person adds to, and nobody adds to a file the CLI
- * rewrites on the next run — `pikku-personas.gen.ts` would otherwise make every
+ * rewrites on the next run — `pikku-virtual-users.gen.ts` would otherwise make every
  * project that scaffolds one unbuildable, and take the app's own declaration
  * down with it.
  *

package/dist/utils/validate-single-step-workflows.d.ts

@@ -0,0 +1,3 @@
+import type { InspectorLogger, InspectorState } from '../types.js';
+/** Warns about a workflow with at most one RPC step and nothing to wait on or fan out: it is a function or a queue job wearing a workflow's cost. */
+export declare function validateSingleStepWorkflows(logger: InspectorLogger, state: InspectorState): void;

package/dist/utils/validate-single-step-workflows.js

@@ -0,0 +1,32 @@
+import { ErrorCode } from '../error-codes.js';
+const DURABLE_FLOWS = new Set([
+    'sleep',
+    'suspend',
+    'approval',
+    'parallel',
+    'fanout',
+]);
+/** Warns about a workflow with at most one RPC step and nothing to wait on or fan out: it is a function or a queue job wearing a workflow's cost. */
+export function validateSingleStepWorkflows(logger, state) {
+    for (const [name, graph] of Object.entries(state.workflows.graphMeta)) {
+        if (graph.source === 'scenario')
+            continue;
+        const file = state.workflows.files.get(graph.pikkuFuncId)?.path ??
+            state.workflows.graphFiles.get(name)?.path;
+        if (!file)
+            continue;
+        const nodes = Object.values(graph.nodes);
+        const rpcSteps = nodes.filter((n) => 'rpcName' in n && n.rpcName);
+        if (rpcSteps.length > 1)
+            continue;
+        if (nodes.some((n) => 'flow' in n && DURABLE_FLOWS.has(n.flow)))
+            continue;
+        logger.diagnostic({
+            severity: 'warn',
+            code: ErrorCode.SINGLE_STEP_WORKFLOW,
+            message: `Workflow '${name}' (${file}) runs ${rpcSteps.length === 0 ? 'no RPC step' : 'a single RPC step'} ` +
+                `and never sleeps, suspends or fans out, so it buys nothing a workflow is for. ` +
+                `Call the function directly, or enqueue it on a queue worker if it must survive a restart.`,
+        });
+    }
+}

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowMilestoneCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractVirtualUserFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowMilestoneCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -571,7 +571,7 @@ function extractRpcStep(call, context, outputVar) {
             outputVar,
             inputs,
             options,
-            actor: extractActorFromOptions(optionsArg),
+            virtualUser: extractVirtualUserFromOptions(optionsArg),
             expectEventually: expectEventually || undefined,
         };
     }
@@ -623,7 +623,7 @@ function extractScenarioStep(call, context, outputVar) {
             outputVar,
             inputs,
             options,
-            actor: extractActorFromOptions(optionsArg),
+            virtualUser: extractVirtualUserFromOptions(optionsArg),
         };
     }
     catch (error) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -44,11 +44,11 @@ export declare function isScenarioExpectationCall(node: ts.CallExpression): bool
  */
 export declare function isWorkflowExpectEventuallyCall(node: ts.CallExpression): boolean;
 /**
- * Extract the actor NAME from a step options object literal:
- * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * Extract the virtual user NAME from a step options object literal:
+ * `{ virtualUser: virtualUsers.x }` → 'x' (also `virtualUsers['x']`). Undefined when absent
  * or not statically resolvable.
  */
-export declare function extractActorFromOptions(optionsArg: ts.Expression | undefined): string | undefined;
+export declare function extractVirtualUserFromOptions(optionsArg: ts.Expression | undefined): string | undefined;
 /**
  * Check if a call expression is workflow.sleep()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -88,17 +88,17 @@ export function isWorkflowExpectEventuallyCall(node) {
         isWorkflowWireIdentifier(node.expression.expression));
 }
 /**
- * Extract the actor NAME from a step options object literal:
- * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * Extract the virtual user NAME from a step options object literal:
+ * `{ virtualUser: virtualUsers.x }` → 'x' (also `virtualUsers['x']`). Undefined when absent
  * or not statically resolvable.
  */
-export function extractActorFromOptions(optionsArg) {
+export function extractVirtualUserFromOptions(optionsArg) {
     if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg))
         return;
     for (const prop of optionsArg.properties) {
         if (ts.isPropertyAssignment(prop) &&
             ts.isIdentifier(prop.name) &&
-            prop.name.text === 'actor') {
+            prop.name.text === 'virtualUser') {
             const init = prop.initializer;
             if (ts.isPropertyAccessExpression(init)) {
                 return init.name.text;

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -59,8 +59,8 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 stepName: step.stepName,
                 next: nextNodeId,
             };
-            if (step.actor) {
-                node.actor = step.actor;
+            if (step.virtualUser) {
+                node.virtualUser = step.virtualUser;
             }
             if (step.expectEventually) {
                 node.expectEventually = true;
@@ -101,8 +101,8 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                 scenarioStepPhase: step.phase,
                 next: nextNodeId,
             };
-            if (step.actor) {
-                node.actor = step.actor;
+            if (step.virtualUser) {
+                node.virtualUser = step.virtualUser;
             }
             if (step.inputs) {
                 if (step.inputs === 'passthrough') {
@@ -401,7 +401,7 @@ export function convertDslToGraph(workflowName, meta) {
     }
     const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : [];
     // Determine source type:
-    // - scenario: complex workflow whose steps run as actors (scenario)
+    // - scenario: complex workflow whose steps run as virtual users (scenario)
     // - dsl === true: pure DSL workflow, can be serialized
     // - dsl === false: complex workflow with inline steps, not serializable
     const source = meta.scenario
@@ -417,7 +417,7 @@ export function convertDslToGraph(workflowName, meta) {
         description: meta.description,
         tags: meta.tags,
         skip: meta.skip,
-        actors: meta.actors,
+        virtualUsers: meta.virtualUsers,
         context: meta.context,
         nodes: nodesRecord,
         entryNodeIds,

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -110,8 +110,8 @@ export interface FunctionNode extends BaseNode {
     outputVar?: string;
     /** Hash of nodeId + RPC input/output schemas for version detection */
     stepHash?: string;
-    /** Scenario actor name this step runs as (workflow.do {actor: actors.x}) */
-    actor?: string;
+    /** Scenario virtual user name this step runs as (workflow.do {virtualUser: virtualUsers.x}) */
+    virtualUser?: string;
     /** True for workflow.expectEventually polling steps (scenarios) */
     expectEventually?: boolean;
     /** Gherkin-style phase for a declared scenario step (scenario.given/when/then) */
@@ -143,7 +143,7 @@ export declare const isFlowNode: (node: SerializedGraphNode) => node is FlowNode
  * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
  * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
  * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
- * - 'scenario': Scenario (pikkuScenario) - complex workflow whose steps run as actors
+ * - 'scenario': Scenario (pikkuScenario) - complex workflow whose steps run as virtual users
  */
 export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'scenario';
 /**
@@ -162,8 +162,8 @@ export interface SerializedWorkflowGraph {
     description?: string;
     /** Tags for organization */
     tags?: string[];
-    /** Actor names a scenario's steps run as */
-    actors?: string[];
+    /** Virtual user names a scenario's steps run as */
+    virtualUsers?: string[];
     /** Why a scenario is held out of a default run, stated where it is declared */
     skip?: string;
     /** If true, workflow always executes inline without queues */

package/dist/visit.js

@@ -26,7 +26,7 @@ import { addCredential } from './add/add-credential.js';
 import { addScope } from './add/add-scope.js';
 import { addSystemRole } from './add/add-system-role.js';
 import { addFeatureFlag } from './add/add-feature-flag.js';
-import { addPersonas } from './add/add-personas.js';
+import { addVirtualUsers } from './add/add-virtual-users.js';
 import { addVariable } from './add/add-variable.js';
 import { addWorkflowGraph } from './add/add-workflow-graph.js';
 import { addFeature } from './add/add-feature.js';
@@ -81,7 +81,7 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     addScope(logger, node, checker, state, nextOptions);
     addSystemRole(logger, node, checker, state, nextOptions);
     addFeatureFlag(logger, node, checker, state, nextOptions);
-    addPersonas(logger, node, checker, state, nextOptions);
+    addVirtualUsers(logger, node, checker, state, nextOptions);
     addVariable(logger, node, checker, state, nextOptions);
     addHTTPRoute(logger, node, checker, state, nextOptions);
     addHTTPRoutes(logger, node, checker, state, nextOptions);

package/knowledge/decisions/a-channel-with-auth-false-marks-its-connect-and-disconnect-sessionless.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A channel with auth false marks its connect and disconnect handlers sessionless
+description: The inspector synthesises metadata for a channel's connect and disconnect functions and sets sessionless from the channel's auth
+tags: [inspector, channels, auth]
+---
+
+# A channel with auth false marks its connect and disconnect handlers sessionless
+
+In `packages/inspector/src/add/add-channel.ts`, `channelAuth` is read from the channel's
+`auth` property (line 705). `sessionless` is `true` only when that value is `false`
+(line 708). Otherwise it is `undefined`.
+
+For each of the connect and disconnect function ids (line 709), the inspector creates a
+metadata entry with that `sessionless` value when none exists yet (lines 710-717). An entry
+that already exists is left alone (line 710).
+
+The comment at lines 701-704 says these handlers are defined with the channel-specific
+helpers and not `pikkuFunc` or `pikkuSessionlessFunc`, so the runtime needs the flag here.
+
+**What this rules out:** a channel with `auth: false` whose connect or disconnect handler is
+still treated as needing a session. The check covers only the channel's own `auth` value.

package/knowledge/decisions/a-declared-scope-id-never-shadows-a-definition.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A declared scope id never shadows a definition
+description: A bare declareScopes id is added only when no definition already holds it, so an addon's richer scope tree is kept
+tags: [inspector, scopes]
+---
+
+# A declared scope id never shadows a definition
+
+`addDeclareScopes` in `packages/inspector/src/add/add-scope.ts` records each valid id
+in `state.scopes.declared` and keeps the first source file for it (lines 164-167).
+
+`applyDeclaredScopes` folds those ids into `state.scopes.definitions` later (lines
+178-192). It reuses a root that already exists (lines 181-185). For each further
+segment it uses `??=`, so a node that is already there is kept (lines 188-189). The
+comments at lines 137-141 and 173-177 say an addon's richer declaration "is never
+shadowed by a bare id" and that an id already held "is left alone".
+
+**What this rules out:** a bare `declareScopes` entry overwriting the richer tree an
+addon or `defineScope` provided.

package/knowledge/decisions/a-dsl-step-virtual-user-is-the-literal-name-in-its-options.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A workflow DSL step's virtual user is the literal name written in its options object
+description: The DSL extractor reads a step's virtual user from a property access or string-keyed element access in the options literal, and leaves it undefined when the value is not static
+tags: inspector, workflow, dsl, virtual-users
+---
+
+# A workflow DSL step's virtual user is the literal name written in its options object
+
+`extractVirtualUserFromOptions` in `packages/inspector/src/utils/workflow/dsl/patterns.ts`
+returns the virtual user name for a step. Its doc comment says
+`{ virtualUser: virtualUsers.x }` gives `'x'`, also `virtualUsers['x']`, and is
+`undefined` when the virtual user is absent or "not statically resolvable"
+(`patterns.ts:122-126`).
+
+The function reads the `virtualUser` property of the options object literal
+(`patterns.ts:127-150`). A property access returns its name, and a string-keyed
+element access returns the string (`patterns.ts:138-146`). Any other form returns
+`undefined` (`patterns.ts:149`).
+
+The DSL extractor calls it for RPC steps (`packages/inspector/src/utils/workflow/dsl/extract-dsl-workflow.ts:790`)
+and for scenario steps (`extract-dsl-workflow.ts:853`). The step is still recorded
+with `virtualUser` set to `undefined` when the name is not literal.
+
+**What this rules out:** resolving a step's virtual user from a variable, a computed
+key or a runtime value at inspection time. A virtual user the inspector cannot read
+statically is left blank, not guessed.

package/knowledge/decisions/a-feature-flags-anyof-is-read-from-the-ast-and-an-empty-list-is-refused.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A feature flag's anyOf is read from the AST, and an empty anyOf is refused
+description: add-feature-flag reads the scope names in anyOf statically, refuses a non-array or empty anyOf, and refuses a flag name containing the scope separator
+tags: [inspector, feature-flags, scopes]
+---
+
+# A feature flag's anyOf is read from the AST, and an empty anyOf is refused
+
+`extractAnyOf` in `packages/inspector/src/add/add-feature-flag.ts` (lines 96-137) reads the
+`anyOf` property. If the property is absent it returns `undefined` (lines 108-110). If it is
+present but not an array literal, it reports a critical error (lines 112-121). Each element must be
+a string literal (lines 124-133). A non-literal element is reported and skipped.
+
+In `addFeatureFlag`, a flag name containing the scope separator is refused (lines 193-199). A body
+that is not an object literal, or a variable holding one, is refused (lines 204-211). An `anyOf` that
+is an empty array is refused (lines 215-221), and the message says to omit `anyOf` for a pure switch.
+
+**What this rules out:** a flag whose capability list cannot be read from the source, a flag named
+like a scope, and `anyOf: []`. An omitted `anyOf` is not refused; it is recorded as `undefined` (line 230).

package/knowledge/decisions/a-non-literal-string-array-reads-as-absent.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A string array with one computed entry reads as absent, not as its literal entries
+description: stringArrayProperty returns undefined unless every element of the array is a string literal
+tags: [inspector, literals, virtual-users]
+---
+
+# A string array with one computed entry reads as absent, not as its literal entries
+
+`stringArrayProperty` in `packages/inspector/src/utils/literal-properties.ts` returns
+`undefined` when the property is missing or is not an array literal (lines 84-86). It keeps
+the string-literal entries (lines 87-89) and returns them only when every element was kept
+(line 90). One computed entry therefore makes the whole result `undefined`.
+
+The comment at lines 74-77 says a half-read array "typechecks, runs, and grants less than
+the source says", which is why the helper is all-or-nothing.
+
+Callers in this package include `add-virtual-users.ts` for `roles`, `goals` and `tags`, which
+fall back to `[]` when the helper returns `undefined` (lines 248-250), and for `fixtures`
+and `environments` (lines 274 and 279). `add-feature.ts` keeps a local copy of the helper with the same all-or-nothing rule
+and reads `tags` through it (line 256).
+A search of the package found no caller that reads `scopes` through this helper.
+
+**What this rules out:** a virtual user or feature keeping the literal entries of a roles or tags
+array that also holds a computed value. Such a virtual user gets an empty list instead.

package/knowledge/decisions/a-permission-with-an-underscore-data-parameter-takes-no-data.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A permission whose data parameter starts with an underscore takes no data
+description: An underscore-prefixed data parameter marks a permission as auth-only, and pikkuAuth always has no data
+tags: [inspector, permissions]
+---
+
+# A permission whose data parameter starts with an underscore takes no data
+
+In `packages/inspector/src/add/add-permission.ts`, `requiresData` is false when the
+second parameter's name starts with `_` (lines 107-110). The permission entry then
+gets `requiresData: false` (line 120). The debug log labels such an entry
+"auth-only" (line 124).
+
+`pikkuAuth` always sets `requiresData: false` (line 204) and an empty, optimized wires
+list (line 171). Its handler's second parameter is the resolved session, not a wires
+bag (comment at lines 167-170).
+
+**What this rules out:** a permission whose data parameter is underscore-prefixed
+being treated as needing request data.

package/knowledge/decisions/a-provider-login-virtual-user-is-never-runnable.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A provider-login virtual user is never runnable, even when declared runnable
+description: Runnable is derived from the account, so a virtual user with a provider login cannot be driven, and an explicit runnable true does not change that
+tags: [inspector, virtual-users]
+---
+
+# A provider-login virtual user is never runnable, even when declared runnable
+
+`addVirtualUsers` in `packages/inspector/src/add/add-virtual-users.ts` sets `runnable`
+through `isRunnableVirtualUser`, passing the declared `runnable` value and the account
+(lines 242-256). It imports the function from `@pikku/core/virtual-user` (line 3).
+
+The function is in `packages/core/src/wirings/virtual-user/validate-virtual-users.ts`.
+An explicit `runnable: false` gives false (lines 23-25). Otherwise the result is
+`account?.provider === undefined` (line 26). A declared `runnable: true` does not
+override the provider check, so a provider account is never runnable.
+`packages/core/src/wirings/virtual-user/virtual-user-declaration.test.ts:89-90` covers
+the provider case.
+
+The doc comment gives the reason (`validate-virtual-users.ts:7-18`). Driving a
+provider's consent screen needs a human, so runnability is derived from the account
+rather than asked for: "a flag someone must remember to set is a flag that ships
+wrong". An explicit `false` marks a person who is only ever acted upon.
+
+**What this rules out:** a provider-login virtual user being driven by a run,
+whatever the declaration says.

package/knowledge/decisions/a-remote-addon-bound-credential-or-secret-must-be-wired.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A remote addon's bound credential or secret id must name a wired slot, or validation reports a critical error
+description: validateRemoteAddonAuth checks that a literal auth.credentialId or auth.secretId on a wireRemoteAddon names a declared credential or secret, and runs in every inspector pass
+tags: inspector, addon, auth, validation
+---
+
+# A remote addon's bound credential or secret id must name a wired slot, or validation reports a critical error
+
+`validateRemoteAddonAuth` in `packages/inspector/src/utils/post-process.ts:760` is one of the validators the
+inspector runs in every pass that is not setup-only (`packages/inspector/src/inspector.ts:523`). It is called
+at `packages/inspector/src/inspector.ts:578`, after the remote addon dependency check and before the scope checks.
+
+Its doc comment limits what it checks. A `credentialId` must name a wired credential and a `secretId` a
+wired secret. A custom `resolve()` and an omitted surface are not statically checkable, so they are left to
+runtime (`post-process.ts:754-759`).
+
+The function returns when no `wireAddon` declarations exist (`post-process.ts:764-765`). It then loops over
+the remote declarations (`post-process.ts:771`). A `credentialId` that matches no credential definition
+logs a critical `REMOTE_ADDON_AUTH_UNRESOLVED` error that lists the available credentials (`post-process.ts:773-776`).
+A `secretId` that matches no secret definition gets the same error with the available secrets (`post-process.ts:779-782`).
+
+Whether a non-literal `auth` value is checked at all is a separate gap, in
+[does a non-literal remote addon auth get checked](../questions/does-a-non-literal-remote-addon-auth-get-checked.md).
+
+**What this rules out:** a remote addon binding that names a credential or secret the consumer never wires,
+passing inspection silently and failing only at runtime.

package/knowledge/decisions/a-route-auth-overrides-its-groups-auth.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A route's own auth overrides its group's, and auth false on a route makes an inline function sessionless
+description: The route's auth is used when it is true or false, the group's inherited value otherwise; a resolved false sets sessionless on an inline function
+tags: [inspector, http, auth]
+---
+
+# A route's own auth overrides its group's, and auth false on a route makes an inline function sessionless
+
+In `packages/inspector/src/add/add-http-route.ts`, the route's own `auth` is read first
+(line 281). `resolvedAuth` takes that value when it is `true` or `false` (lines 282-284),
+and otherwise takes `inheritedAuth` (line 285), which the caller passes in from the group.
+
+The comment at lines 277-280 says the value is recorded on the meta so an audit can tell
+whether a route is open without re-reading the source.
+
+Lines 287-289 say that for inline functions, `sessionless` is set to `true` when auth is
+disabled at the route or group level. The code sets it only when the inline function's
+`sessionless` is still `undefined` and `resolvedAuth` is `false` (lines 290-298).
+
+**What this rules out:** a route with `auth: true` inheriting `false` from its group. It also
+rules out letting an inline function be marked sessionless while the route asks for auth.

package/knowledge/decisions/a-route-requires-a-session-when-any-auth-signal-says-so.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A route requires a session when any auth signal says so
+description: Four places can demand a session for an HTTP route and they combine with OR; a scope gate counts as a session demand
+tags: [inspector, auth, http]
+---
+
+# A route requires a session when any auth signal says so
+
+`annotateHttpRouteAuth` in `packages/inspector/src/utils/annotate-http-route-auth.ts`
+sets `route.requiresSession` to true when any one of these holds (lines 31-38):
+
+- the function's `sessionless` is `false`, which is a `pikkuFunc`;
+- the function's own `auth` is `true`;
+- the function declares one or more `scopes`;
+- the route's own `auth` is `true`;
+- the route's package is in the set of packages gated by their addon.
+
+The last signal comes from `packagesGatedByTheirAddon` (lines 44-53). It gates a
+package when one of its `wireAddon` declarations has `auth === true` or a
+non-empty `scopes` list.
+
+The scope rule is argued in the file's own doc comment. Scopes are checked
+against the session and fail closed, so an anonymous caller is rejected either
+way. Not counting them "would mark a route open that nobody can reach anonymously"
+(`annotateHttpRouteAuth`, lines 14-16).
+
+**What this rules out:** reading a scope-gated route as open. It also rules out
+letting one signal cancel another; the four places only add demands.

package/knowledge/decisions/a-webhook-source-with-verify-gets-a-singleton-secret-credential.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A webhook source with a verify step declares a singleton credential for its secret
+description: When a webhook source has a verify step, the inspector registers a string credential named by the source unless the author sets credential
+tags: [inspector, triggers, webhooks, credentials]
+---
+
+# A webhook source with a verify step declares a singleton credential for its secret
+
+In `packages/inspector/src/add/add-trigger.ts`, the code returns early unless the source has a
+`verify` initializer (line 283). When it has one, the credential name is the `credential`
+property if set, otherwise `webhookSecretCredentialName(name)` (lines 285-287). That helper is
+imported from `@pikku/core/trigger` (line 21).
+
+The inspector then records a credential definition with `type: 'singleton'` and a string schema,
+named by that value (lines 288-297). Its display name is `<name> webhook secret` (line 291), and
+its description is the `credentialDescription` property when set (lines 292-294).
+
+**What this rules out:** a verified webhook source whose secret is left out of the credential
+declarations. The author can choose a different credential name, but a verify step always
+registers one.

package/knowledge/decisions/a-wire-with-auth-disabled-cannot-point-at-a-pikkufunc.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A wire with auth disabled cannot point at a pikkuFunc
+description: A route or wiring with auth false that names a session-requiring pikkuFunc is reported as critical, and the function is not accepted
+tags: [inspector, auth, validation]
+---
+
+# A wire with auth disabled cannot point at a pikkuFunc
+
+`validateAuthSessionless` in `packages/inspector/src/utils/validate-auth-sessionless.ts`
+resolves the wire's auth. The wire's own `auth` wins when it is a boolean; otherwise
+the inherited value is used (lines 18-20).
+
+When that resolves to `false` and the function's meta has `sessionless === false`,
+the function logs `AUTH_DISABLED_REQUIRES_SESSIONLESS` as critical and returns
+`false` (lines 21-27). The message tells the author to use `pikkuSessionlessFunc`
+instead (line 24).
+
+**What this rules out:** a wire that declares no session needed while its function
+does need one. The check runs on the wire's auth, not on the function's own `auth`
+field.

package/knowledge/decisions/addon-contracts-cannot-wire-or-declare-handlers.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Addons may not call wiring helpers or declare middleware or permissions
+description: Addon packages are banned from transport wirings, and their define* contracts may not carry middleware or permissions
+tags: [inspector, addon]
+---
+
+# Addons may not call wiring helpers or declare middleware or permissions
+
+`checkAddonBans` in `packages/inspector/src/add/add-addon-bans.ts` runs only when the
+package is inspected as an addon (line 63). It enforces two rules.
+
+- A call to any name in `BANNED_WIRINGS` is critical `ADDON_WIRING_NOT_ALLOWED`
+  (lines 10-24, 68-74). The list includes `wireAddon`, `wireRemoteAddon`, `wireHTTP`
+  and `wireChannel`.
+- A `defineHTTPRoutes`, `defineChannelRoutes` or `defineCLICommands` call whose
+  first argument has a `middleware` or `permissions` property is critical
+  `ADDON_CONTRACT_HANDLERS_NOT_ALLOWED` (lines 26-30, 32-49, 76-83).
+
+The file comment (lines 6-8) says addons "declare contracts with the define*
+helpers and export functions", and the consuming app wires them. The comment at
+lines 52-54 says middleware and permissions "are the consuming app's concern".
+
+**What this rules out:** an addon fixing its own transports, or attaching its own
+access rules to the routes it contributes.

package/knowledge/decisions/addon-declarations-name-the-secrets-and-credentials-the-app-lends-it.md

@@ -0,0 +1,19 @@
+---
+type: decision
+title: An addon declaration names the secrets and credentials the app lends it
+description: secretGrants and credentialGrants are declared on the addon instance as lists of names the addon reads
+tags: [inspector, addons, grants]
+---
+
+# An addon declaration names the secrets and credentials the app lends it
+
+The addon declaration type in `packages/inspector/src/types.ts` has `secretGrants?: string[]` and
+`credentialGrants?: string[]`, each commented as the secrets or credentials "the app lends this
+instance, named as the addon reads them" (lines 757-760).
+
+In `packages/inspector/src/add/add-wire-addon.ts`, those two properties are read with
+`parseStringArray` (lines 212-215). The helper itself is not read here, so this note does not say how
+it treats a non-literal entry.
+
+**What this rules out:** an addon instance receiving secrets or credentials that the app did not name in
+its `wireAddon` call. The names are the grant.