@pikku/inspector 0.12.106 → 0.12.108

package/OPTIMIZATION-PLAN.md

@@ -1,201 +0,0 @@
-# Inspector Package Optimization Plan
-
-## Context
-
-The inspector (`packages/inspector/src/`) is a static code analyzer built on TypeScript's compiler API. It extracts metadata from source files via a two-pass AST visitor pattern (setup + routes). Profiling reveals that for **every AST node**, all handlers are called sequentially (10 in setup, 16 in routes) even though only 1 ever matches. This creates millions of wasted function calls on large codebases.
-
-The inspector already has `performance.now()` instrumentation for 7 phases. We'll use this to measure each optimization independently.
-
----
-
-## Step 0: Create Benchmark Harness
-
-**Goal:** Establish reproducible baseline measurements.
-
-**File:** `src/benchmark.ts`
-
-**What it does:**
-
-- Collects `.ts` files from a target directory (e.g., the external repo's packages)
-- Runs `inspect()` N iterations (default 10) with a warmup run
-- Parses existing `logger.debug` messages to capture per-phase timings
-- Reports median, mean, min, max for each phase + total
-- Outputs JSON for before/after diffing
-- Also benchmarks `filterInspectorState()` separately using the test fixture (`src/utils/test-data/inspector-state.json`)
-- Adds counters for: total AST nodes visited, CallExpression nodes, dispatch hits
-
-**Run with:**
-
-```bash
-node --import tsx src/benchmark.ts <target-dir> <iterations>
-```
-
-**How to verify:** Run 3x, confirm <5% variance between runs for each phase.
-
----
-
-## Step 1: Identifier-Based Dispatch Map in `visit.ts`
-
-**File:** `src/visit.ts`
-
-**Problem:** Every AST node goes through ALL handlers. In `visitRoutes`, that's 16 function calls per node. Each handler independently checks `isCallExpression` -> `isIdentifier` -> `expression.text === 'xyz'`. For non-CallExpression nodes (the vast majority), all 16 calls are wasted.
-
-**Fix:** Check node kind once, extract identifier once, use `Map<string, handler>` for O(1) dispatch.
-
-**Dispatch map for `visitRoutes`** (all handlers expect CallExpression + Identifier):
-
-| Identifier          | Handler            |
-| ------------------- | ------------------ |
-| `wireHTTP`          | `addHTTPRoute`     |
-| `wireHTTPRoutes`    | `addHTTPRoutes`    |
-| `wireScheduler`     | `addSchedule`      |
-| `wireTrigger`       | `addTrigger`       |
-| `wireTriggerSource` | `addTrigger`       |
-| `wireQueueWorker`   | `addQueueWorker`   |
-| `wireChannel`       | `addChannel`       |
-| `wireCLI`           | `addCLI`           |
-| `pikkuCLIRender`    | `addCLIRenderers`  |
-| `wireMCPResource`   | `addMCPResource`   |
-| `wireMCPTool`       | `addMCPTool`       |
-| `wireMCPPrompt`     | `addMCPPrompt`     |
-| `wireWorkflowGraph` | `addWorkflowGraph` |
-| `defineSecret`      | `addSecret`        |
-| `defineCredential`  | `addCredential`    |
-| `defineScope`       | `addScope`         |
-| `defineVariable`    | `addVariable`      |
-
-`addAuth` stays outside the map: it matches several identifiers
-(`betterAuthStatelessSession`, `betterAuthSession`) and gates them on
-surrounding context rather than on the identifier alone, so it keeps running on
-every CallExpression.
-
-Fallback for unmatched identifiers: check `/pikku.*func/i` regex -> `addFunctions`.
-
-**Dispatch for `visitSetup`** (mixed node kinds):
-
-- `SyntaxKind.CallExpression` + Identifier -> map with: `external`, `workflow`, `workflowStart`, `workflowRun`, `workflowStatus`, `graphStart` -> `addRPCInvocations`; `pikkuMiddleware`, `pikkuMiddlewareFactory`, `addMiddleware`, `addHTTPMiddleware` -> `addMiddleware`; `pikkuPermission`, `pikkuPermissionFactory`, `addPermission`, `addHTTPPermission` -> `addPermission`; `pikkuWorkflowFunc`, `pikkuWorkflowComplexFunc` -> `addWorkflow`
-- `SyntaxKind.CallExpression` + PropertyAccessExpression (`rpc.invoke`) -> `addRPCInvocations`
-- `SyntaxKind.ClassDeclaration` / `InterfaceDeclaration` -> `addFileExtendsCoreType` (4 core type names)
-- `SyntaxKind.VariableDeclaration` -> `addFileWithFactory` (3 factory type names)
-- All other node kinds -> skip directly to recursion
-
-**Measure:** Compare "Visit setup phase" and "Visit routes phase" benchmark timings.
-
-**Expected improvement:** 30-60% reduction in visit phase times.
-
-**Verify:** `bash run-tests.sh` + compare serialized inspector state output before/after.
-
----
-
-## Step 2: Hoist Regex + Remove Redundant Checks in `add-functions.ts`
-
-**File:** `src/add/add-functions.ts`
-
-**Problem (lines 290-309):**
-
-```ts
-// Line 301: regex re-created EVERY call (every AST node)
-const pikkuFuncPattern = /pikku.*func/i
-// Line 307: redundant - isIdentifier already checked at line 296,
-// startsWith('pikku') is a subset of the regex
-if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku'))
-```
-
-**Fix:**
-
-1. Move `const pikkuFuncPattern = /pikku.*func/i` to module scope
-2. Remove the redundant check at line 307-309
-
-**Measure:** "Visit routes phase" timing.
-
-**Expected improvement:** 1-5% of visit routes phase.
-
-**Verify:** `bash run-tests.sh`
-
----
-
-## Step 3: Replace `getText()` with `.text` Property Access
-
-**Files:** 3-5 files, ~8 safe replacements
-
-`node.getText()` reconstructs text by slicing the source string. For `Identifier` nodes, `.text` is a direct property -- zero overhead.
-
-**Safe replacements:**
-
-- `src/add/add-file-extends-core-type.ts` line 13: `node.name?.getText()` -> `node.name?.text`
-- `src/add/add-file-with-factory.ts` line 24: `node.name.getText()` -> guard with `ts.isIdentifier(node.name) ? node.name.text : node.name.getText()`
-- `src/add/add-channel.ts` line 360: `shorthandDecl.name.getText()` -> `.text` (ImportSpecifier name is always Identifier)
-
-**Skip** (not safe or rarely hit): error messages, template literals, TypeNode, QualifiedName.
-
-**Measure:** "Visit setup phase" + "Visit routes phase" timings.
-
-**Expected improvement:** 1-3% of visit phases.
-
-**Verify:** `bash run-tests.sh`
-
----
-
-## Step 4: Replace `JSON.parse(JSON.stringify(...))` with `structuredClone()`
-
-**File:** `src/utils/filter-inspector-state.ts` (lines 198-233)
-
-**Problem:** 8 calls to `JSON.parse(JSON.stringify(...))` for deep cloning metadata objects. This serializes to string then parses back -- wasteful.
-
-**Fix:** Replace all 8 with `structuredClone()` (available Node 17+, package requires >=18).
-
-```ts
-// Before
-meta: JSON.parse(JSON.stringify(state.http.meta))
-// After
-meta: structuredClone(state.http.meta)
-```
-
-**Measure:** Separate `filterInspectorState` benchmark loop using the 45KB test fixture.
-
-**Expected improvement:** 10-30% of filter phase time (not the main inspect path, but important for CLI).
-
-**Verify:** `bash run-tests.sh` (filter-inspector-state.test.ts covers this extensively -- 1,440 lines of tests).
-
----
-
-## Step 5: Cache `node.getSourceFile().fileName` in Hot Handlers
-
-**Files:** Primarily `src/add/add-functions.ts`
-
-**Problem:** `add-functions.ts` calls `node.getSourceFile().fileName` 4+ times within a single handler invocation for the same node (lines 666, 700, 721, 735). `getSourceFile()` walks the parent chain each time.
-
-**Fix:** Extract once at handler entry:
-
-```ts
-const sourceFileName = node.getSourceFile().fileName
-```
-
-Then reuse `sourceFileName` throughout.
-
-**Measure:** "Visit routes phase" timing.
-
-**Expected improvement:** 1-2%.
-
-**Verify:** `bash run-tests.sh`
-
----
-
-## Summary
-
-| Step | Change            | File(s)                     | Expected Impact            | Metric               |
-| ---- | ----------------- | --------------------------- | -------------------------- | -------------------- |
-| 0    | Benchmark harness | New `benchmark.ts`          | Baseline                   | -                    |
-| 1    | Dispatch map      | `visit.ts`                  | **30-60%** of visit phases | Visit setup + routes |
-| 2    | Hoist regex       | `add-functions.ts`          | 1-5% of visit routes       | Visit routes         |
-| 3    | getText -> .text  | 3-5 files                   | 1-3% of visit phases       | Visit setup + routes |
-| 4    | structuredClone   | `filter-inspector-state.ts` | 10-30% of filter phase     | Filter benchmark     |
-| 5    | Cache sourceFile  | `add-functions.ts`          | 1-2% of visit routes       | Visit routes         |
-
-## Verification
-
-After each step:
-
-1. Run benchmark: `node --import tsx src/benchmark.ts <target> 10`
-2. Run tests: `cd packages/inspector && bash run-tests.sh`
-3. Compare serialized inspector state output (before vs after) to confirm identical results

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

@@ -1,22 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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

@@ -1,22 +0,0 @@
----
-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

@@ -1,29 +0,0 @@
----
-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

@@ -1,21 +0,0 @@
----
-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

@@ -1,21 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
----
-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

@@ -1,19 +0,0 @@
----
-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.

package/knowledge/decisions/an-inline-wiring-function-is-sessionless-unless-built-with-pikkufunc.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: An inline wiring function is sessionless unless its helper is pikkuFunc
-description: The inspector derives sessionless for a function inlined into a wiring from the name of the helper that built it
-tags: [inspector, functions, auth]
----
-
-# An inline wiring function is sessionless unless its helper is pikkuFunc
-
-`ensureInlineWiringFunction` in `packages/inspector/src/utils/ensure-function-metadata.ts`
-registers metadata for a function written inline in a wiring (lines 329-344). The comment at
-lines 324-327 says the stub would otherwise carry no session info, and the runtime would then
-require a session for every call.
-
-After that, if the metadata's `sessionless` is still `undefined` (line 349) and the initializer
-is a call whose callee is a plain identifier (lines 350-351), `sessionless` is set to
-`callee !== 'pikkuFunc'` (line 353). The comment at lines 324-327 gives the same rule as the
-one `addFunctions` applies to named functions.
-
-If the callee is not a plain identifier, `sessionless` is left `undefined`.
-
-**What this rules out:** treating an inline wiring function as session-required because it was
-built by a helper other than `pikkuFunc`.

package/knowledge/decisions/better-auth-admin-plugin-is-refused.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: better-auth's admin plugin is refused in favour of pikkuBan
-description: Wiring admin() in pikkuBetterAuth throws at build time, and the error names pikkuBan() as the replacement
-tags: [inspector, auth, better-auth]
----
-
-# better-auth's admin plugin is refused in favour of pikkuBan
-
-In `packages/inspector/src/add/add-auth.ts`, a plugin named `admin` inside
-`pikkuBetterAuth` throws rather than warning (lines 342-344). The error text is
-`UNSUPPORTED_ADMIN_PLUGIN` (lines 174-190). It tells the app to use `pikkuBan()`.
-
-The doc comment above the constant (lines 158-172) gives the reason. `admin()`
-authorizes against a `user.role` column, and pikku authorizes on scopes. Running
-both means projecting one onto the other, coarsely. The comment says user
-management now lives in `@pikku/addon-admin`, and the ban refusal lives in
-`pikkuBan()`.
-
-The comment at lines 170-172 says the throw is deliberate: "the failure it prevents
-is silent". An app that drops `admin()` without wiring `pikkuBan()` keeps its ban
-columns and stops enforcing bans.
-
-**What this rules out:** `admin()` as a second authorization model next to scopes.

package/knowledge/decisions/define-screens-scopes-must-be-string-literals.md

@@ -1,18 +0,0 @@
----
-type: decision
-title: A define-screens scopes list must be string literals, or the build reports a critical error
-description: add-define-screens reads each screen's scopes by AST and reports ADDON_SCREENS_NOT_STATIC when the value is not an array of string literals
-tags: [inspector, screens, scopes]
----
-
-# A define-screens scopes list must be string literals, or the build reports a critical error
-
-In `packages/inspector/src/add/add-define-screens.ts`, each screen's `scopes` value is read with
-`stringArray(value)` (line 110). If that returns nothing, `fail(...)` runs (lines 111-115), with the
-message "A screen's scopes must be an array of string literals".
-
-`fail` is defined at lines 60-61 as `logger.critical(ErrorCode.ADDON_SCREENS_NOT_STATIC, message)`.
-The same block requires `component` to be a literal lazy import (lines 116-120).
-
-**What this rules out:** a screen whose scopes come from a variable, a computed value or a call.
-The inspector reads scopes statically, so it cannot check a value it cannot see.