@pikku/inspector 0.12.48 → 0.12.50

package/CHANGELOG.md

@@ -1,3 +1,96 @@
+## 0.12.50
+
+### Patch Changes
+
+- b89d3b3: Bring the knowledge base into OSS: a package, a CLI gate, a console browser and a skill
+
+  `knowledge/` is where a project records the things `pikku meta` cannot tell you —
+  what a slice is for, which rule was chosen and what it rules out, what is still an
+  open question. Tables, routes, schemas and permissions are generated, so a note
+  that repeats them is a copy that will drift, and the profile refuses the sections
+  where that happens.
+  - **`@pikku/knowledge`** (new) reads the notes, builds the link graph in both
+    directions, and validates the app-project profile: every note typed, every
+    section indexed, every slice carrying a third-person gherkin scenario and at
+    most three entities, and every `resource:` URI resolving against the generated
+    meta. The resource check fails closed on drift and open on ignorance — a prefix
+    whose meta is absent is skipped rather than called dangling.
+  - **`pikku knowledge validate`** and **`pikku knowledge index`** replace the dead
+    three-flat-files check. Both exit non-zero on an inconsistent base, so a
+    pipeline can stop on one; `index` refreshes each `index.md` listing while
+    leaving the prose around it alone, and now gives a section that holds only
+    sub-sections an index of its own instead of leaving it unreachable.
+  - **The console** gains a read-only Knowledge page: notes grouped by section,
+    a rendered document with its tags, resources, links in both directions and the
+    findings against it, and intra-bundle markdown links that open the linked note
+    instead of leaving the page. Read-only by design — a note is edited in the repo,
+    in the same commit as the code it describes.
+  - **The `pikku-knowledge` skill** documents the format for agents, and Fabric
+    builds on it rather than restating it.
+  - **`@pikku/inspector`**: a zod schema imported from a built workspace package
+    resolved to that package's `.d.ts`, which has no runtime exports at all, so
+    every schema in it was reported missing. The emitted JS beside it is imported
+    instead.
+
+- b89d3b3: Invalidate the TS-schema cache when a type it was built from changes
+
+  The on-disk schema cache was keyed on the synthesized custom-types source, the
+  generator options and the inspector version — but not on the types it actually
+  resolves. A named type (anything a function declares as its input or output)
+  appears in that source only as a name; its definition is read out of a project
+  file or a dependency's `.d.ts`. Change the shape without changing the name and
+  the key is identical, so pikku serves a schema for a type that no longer looks
+  like that, and requests are validated against it.
+
+  The stale schema also outlives `rm -rf .pikku`, because the cache lives in
+  `node_modules/.cache/pikku/ts-schemas.json`.
+
+  Codegen now records the files each schema set was derived from, storing their
+  mtime and size beside it, and regenerates when any of them moves or disappears.
+  The schema program is rooted at the virtual types file, so its source files are
+  exactly the transitive closure the schemas depend on. A cache written by an
+  earlier version carries no dep list and is treated as stale. The check costs
+  about 3ms per cache hit, and also guards the in-process cache, so `pikku dev`
+  picks up a type edit without a restart.
+
+- Updated dependencies [384e484]
+- Updated dependencies [b5a73fb]
+- Updated dependencies [6be5ab0]
+  - @pikku/core@0.12.72
+
+## 0.12.49
+
+### Patch Changes
+
+- 426610a: Scenario instrumentation is no longer scaffolded into projects, and no longer deploys.
+
+  `scaffold.scenarios` generated four functions — `pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls` — into the project's own source. As project source they were indistinguishable from application code: registered in the app bootstrap, listed in the app's function and RPC meta, and shipped `expose: true` inside every deployed bundle. Coverage and stub inspection are things you do to a development server; production carried two endpoints that fingerprint the build and one that resets a global tracker, gated only by whether a metadata file happened to sit beside the bundle.
+
+  `pikku dev` now registers the implementations itself, after the app bootstrap. Nothing is generated, nothing is written to the project, and a bundle cannot carry what was never in its bootstrap — `pikku serve` and every deployed unit have no trace of them. The scenario runner reaches them over `/rpc/<name>` exactly as before.
+
+  Also:
+  - The inspector ignores these four names wherever it finds them, so a project that has not regenerated — and still has the scaffolded file checked in — stops deploying it immediately. Codegen deletes the retired scaffold on its next run.
+  - They no longer count towards a project's function total, so `pikku scenario --coverage` stops reporting four permanently-uncovered functions that were never the project's to cover.
+  - The instrumentation no longer carries schemas (there was nothing to validate but one optional string), which drops the `zod` dependency the scaffold silently required of every project that enabled it.
+  - They are registered sessionless, so `scaffold.scenarios: true` — as opposed to `'auth'` — now genuinely means "no session required". As a sessioned `pikkuFunc` with `auth: false`, it demanded a session anyway and logged a warning saying so.
+
+- 09973b9: Scenarios, features and steps no longer reach a deployment.
+
+  Steps were already held back from the app bootstrap, so a deployed server never imported a step body. Everything _about_ a scenario still travelled with the application: a `pikkuScenario(...)` is a function, so its name, schemas and hashes sat in the app function meta; the schemas it and its steps validate against sat in the app's `register.gen.ts` — on one project 458 of the 582 registered schemas belonged to tests; its name sat in the internal RPC meta; and because a scenario is _also_ a workflow, the inspector synthesised a `wf-orchestrator-<scenario>` queue worker for each one. The deploy analyzer, which reads inspector state rather than the partitioned codegen output, then read all of it back as application code: a unit per scenario, a `WorkflowDefinition` per scenario, and a real queue per scenario. A 13-scenario suite turned into 13 production queues named after tests, waiting for a provider to create them.
+
+  The existing scenario/app partition is now applied everywhere it was missing. `FunctionRuntimeMeta` gains a `scenario` marker (the counterpart of `scenarioStep`) so a scenario body is recognisable without walking the workflow graph; scenario bodies join their steps on the scenario side of the function-meta and registration split; schemas only a scenario or step needs are written and registered under `.pikku/scenarios/schemas/` and imported by the scenario bootstrap alone; scenario names are dropped from the internal RPC meta; no orchestrator queue worker is synthesised for a scenario; and the deploy analyzer drops both scenario functions and scenario workflows before it decides what a deployment contains.
+
+  The MCP metas are keyed by wiring rather than by function, so a scenario wired as an MCP tool, resource or prompt was the one id that still reached the manifest after the function and workflow filters — as an endpoint on the gateway plus a gateway dependency on a unit that was never emitted. Those ids are now filtered too.
+
+  `scenarioSchemaDirectory` is rejected when it resolves to the same directory as `schemaDirectory`. A schema write owns its directory — it emits `register.gen.ts` and prunes every schema file its own required-set does not name — so sharing one would replace the application register with the scenario-only one and delete the app's schema files, which nothing downstream can detect.
+
+  Nothing changes for `pikku scenario run` — the scenario bootstrap still registers every scenario, feature, step, meta and schema. What changes is that a bundle stops carrying them.
+
+- Updated dependencies [8a2c993]
+- Updated dependencies [a261006]
+- Updated dependencies [09973b9]
+  - @pikku/core@0.12.71
+
 ## 0.12.48
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,106 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Yasser Fadl and Pikku contributors
+Licensed Work:        TypeScript inspector for Pikku — discovers functions and wirings to drive code generation (@pikku/inspector)
+                      Pikku Console (@pikku/console)
+                      The Licensed Work is (c) 2021 - present Yasser Fadl and Pikku contributors
+Additional Use Grant: You may make production use of the Licensed Work for any purpose,
+                      including creating free or open source software. However, you may
+                      not offer as a commercial product or service any software featuring
+                      a visual or graphical interface for authoring, editing, building,
+                      or managing Pikku code, Pikku functions, Pikku handlers, or Pikku
+                      workflows.
+Change Date:          Four years from the date the Licensed Work was first made available
+Change License:       MIT License
+
+For information about alternative licensing arrangements, contact yasser.fadl@gmail.com
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open Source
+license. However, the Licensed Work will eventually be made available under an Open
+Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works,
+redistribute, and make non-production use of the Licensed Work. The Licensor may make
+an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this License,
+whichever comes first, the Licensor hereby grants you rights under the terms of the
+Change License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in
+effect as described in this License, you must purchase a commercial license from the
+Licensor, its affiliated entities, or authorized resellers, or you must refrain from
+using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the
+Licensed Work, are subject to this License. This License applies separately for each
+version of the Licensed Work and the Change Date may vary for each version of the
+Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of the
+Licensed Work. If you receive the Licensed Work in original or modified form from a
+third party, the terms and conditions set forth in this License apply to your use of
+that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate
+your rights under this License for the current and all other versions of the Licensed
+Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or its
+affiliates (provided that you may use a trademark or logo of Licensor as expressly
+required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS"
+BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED,
+INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your works,
+and to refer to it using the trademark "Business Source License", as long as you
+comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or a
+   license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be included
+   in a program with software provided under GPL Version 2.0 or a later version.
+   Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not impose
+   any additional restriction on the right granted in this License, as the Additional
+   Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Note: Every other Pikku package — @pikku/core, the runtimes, the services, the clients,
+and @pikku/skills — is licensed under the MIT License. Each package ships its own LICENSE
+file stating its terms; that file governs, and this one covers only the Licensed Work
+named above.
+
+In particular, the Pikku agent skills (@pikku/skills) are MIT. They are the instruction
+set coding agents read to build, wire and deploy Pikku projects, and they are meant to be
+adopted, forked and extended by any harness — so their terms do not depend on the CLI
+that happens to install them.

package/dist/add/add-functions.js

@@ -11,6 +11,7 @@ import { resolvePermissions } from '../utils/permissions.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { ErrorCode } from '../error-codes.js';
 import { findPiiPaths } from '../utils/check-pii-output.js';
+import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     return regex.test(name);
@@ -285,6 +286,10 @@ export const addFunctions = (logger, node, checker, state, options) => {
     // never RPC-registered: a step may drive a browser, so exposing it over the
     // network would put a test harness on the public API surface.
     const isScenarioStep = expression.text === 'pikkuScenarioStep';
+    // A scenario's own body. Marked so the codegen partitions and the deploy
+    // analyzer can tell it apart from an application workflow without having to
+    // reach into the workflow graph.
+    const isScenario = expression.text === 'pikkuScenario';
     // only handle calls like pikkuFunc(...)
     if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
         return;
@@ -295,6 +300,14 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (!pikkuFuncId || pikkuFuncId.startsWith('__temp_')) {
         return;
     }
+    // pikku's own scenario instrumentation, which older projects still carry as a
+    // scaffolded file in their source. It is not application code and must not be
+    // registered, metadata'd or deployed as if it were — `pikku dev` registers the
+    // implementations itself, and that is the only server that should have them.
+    if (isScenarioInstrumentationFunction(pikkuFuncId) ||
+        isScenarioInstrumentationFunction(name)) {
+        return;
+    }
     let title;
     let tags;
     let summary;
@@ -784,6 +797,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
         expose: expose || undefined,
         remote: remote || undefined,
         scenarioStep: isScenarioStep || undefined,
+        scenario: isScenario || undefined,
         mcp: mcpEnabled || undefined,
         readonly: readonly_ || undefined,
         deploy: deploy || undefined,

package/dist/add/scenario-instrumentation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The instrumentation RPCs `pikku scenario run` calls on the server it is
+ * testing: snapshot/reset live coverage, and reset/read recorded stub calls.
+ *
+ * They are pikku's own, not the application's. They used to be scaffolded into
+ * the project as ordinary `pikkuFunc`s, which made them indistinguishable from
+ * application code — so they were registered in the app bootstrap, listed in the
+ * app's function and RPC meta, and shipped, `expose: true`, in every deployed
+ * bundle. A deployment has no use for them: coverage and stub inspection are
+ * things you do to a development server.
+ *
+ * The inspector therefore ignores these names wherever it finds them, and
+ * `pikku dev` registers the implementations itself. Ignoring by name (rather
+ * than deleting the scaffold and requiring every project to regenerate) is what
+ * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ */
+export declare const SCENARIO_INSTRUMENTATION_FUNCTIONS: readonly ["pikkuScenarioTakeLiveCoverage", "pikkuScenarioResetLiveCoverage", "pikkuScenarioResetStubs", "pikkuScenarioGetStubCalls"];
+export type ScenarioInstrumentationFunction = (typeof SCENARIO_INSTRUMENTATION_FUNCTIONS)[number];
+/**
+ * True for a scenario instrumentation function, by name. Versioned ids
+ * (`name@v2`) are matched on their base so a project that bumps one is still
+ * covered.
+ */
+export declare const isScenarioInstrumentationFunction: (name: string | undefined) => boolean;

package/dist/add/scenario-instrumentation.js

@@ -0,0 +1,29 @@
+/**
+ * The instrumentation RPCs `pikku scenario run` calls on the server it is
+ * testing: snapshot/reset live coverage, and reset/read recorded stub calls.
+ *
+ * They are pikku's own, not the application's. They used to be scaffolded into
+ * the project as ordinary `pikkuFunc`s, which made them indistinguishable from
+ * application code — so they were registered in the app bootstrap, listed in the
+ * app's function and RPC meta, and shipped, `expose: true`, in every deployed
+ * bundle. A deployment has no use for them: coverage and stub inspection are
+ * things you do to a development server.
+ *
+ * The inspector therefore ignores these names wherever it finds them, and
+ * `pikku dev` registers the implementations itself. Ignoring by name (rather
+ * than deleting the scaffold and requiring every project to regenerate) is what
+ * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ */
+export const SCENARIO_INSTRUMENTATION_FUNCTIONS = [
+    'pikkuScenarioTakeLiveCoverage',
+    'pikkuScenarioResetLiveCoverage',
+    'pikkuScenarioResetStubs',
+    'pikkuScenarioGetStubCalls',
+];
+const names = new Set(SCENARIO_INSTRUMENTATION_FUNCTIONS);
+/**
+ * True for a scenario instrumentation function, by name. Versioned ids
+ * (`name@v2`) are matched on their base so a project that bumps one is still
+ * covered.
+ */
+export const isScenarioInstrumentationFunction = (name) => (name ? names.has(name.split('@')[0]) : false);

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
+export type { ScenarioInstrumentationFunction } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export { ErrorCode } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';

package/dist/utils/post-process.js

@@ -212,6 +212,13 @@ export function aggregateRequiredServices(state) {
     for (const [, graph] of Object.entries(state.workflows.graphMeta)) {
         if (!graph.nodes || !graph.name)
             continue;
+        // A scenario is a workflow, but it only ever runs in-process under
+        // `pikku scenario run` — no step of one is dispatched through a queue. The
+        // synthetic entries were pure leakage: they put a
+        // `wf-orchestrator-<scenario>` worker into the app's queue meta, which every
+        // bundle imports and a provider then creates as a real production queue.
+        if (graph.source === 'scenario')
+            continue;
         const toKebab = (s) => s
             .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
             .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')

package/dist/utils/schema-generator.d.ts

@@ -1,5 +1,29 @@
 import type { JSONValue } from '@pikku/core';
 import type { InspectorLogger, InspectorState } from '../types.js';
+/** One file the generated schemas were derived from, as of when they were generated. */
+export type SchemaDep = {
+    path: string;
+    mtimeMs: number;
+    size: number;
+};
+export declare function readDiskTSSchemas(logger: InspectorLogger, cacheDir: string, key: string): {
+    schemas: Record<string, JSONValue>;
+    deps: SchemaDep[];
+} | null;
+export declare function writeDiskTSSchemas(logger: InspectorLogger, cacheDir: string, key: string, schemas: Record<string, JSONValue>, deps: SchemaDep[]): void;
+/**
+ * Where the RUNTIME value of a schema lives, given where TypeScript resolved it.
+ *
+ * A schema imported from a built workspace package resolves to that package's
+ * declaration file, and importing a `.d.ts` yields a module with no exports at
+ * all — every one of them is a type. The value is in the emitted JS beside it, so
+ * that is what gets imported.
+ *
+ * Falls back to the original path when no sibling JS exists, which keeps the
+ * "could not find exported schema" error pointing at the file the developer
+ * actually wrote.
+ */
+export declare const schemaRuntimeFile: (sourceFile: string) => string;
 export declare function generateAllSchemas(logger: InspectorLogger, config: {
     tsconfig: string;
     schemasFromTypes?: string[];

package/dist/utils/schema-generator.js

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { createGenerator, RootlessError } from 'ts-json-schema-generator';
 import { register } from 'tsx/esm/api';
@@ -57,6 +57,7 @@ let cachedParsedConfig;
 let cachedTsconfigPath;
 let cachedCustomTypesContent;
 let cachedTSSchemas;
+let cachedTSSchemaDeps;
 const SCHEMA_CACHE_VERSION = 1;
 // This package's own version — folded into the cache key so that upgrading
 // @pikku/inspector (the channel through which a schema-format change ships)
@@ -90,25 +91,93 @@ function tsSchemaCacheKey(customTypesContent, config) {
 function schemaCacheFile(cacheDir) {
     return join(cacheDir, 'ts-schemas.json');
 }
-function readDiskTSSchemas(logger, cacheDir, key) {
+/**
+ * The files a set of generated schemas was actually derived from.
+ *
+ * The cache key alone cannot answer whether the schemas are stale. It hashes the
+ * *synthesized* custom-types source, but a named type — `KnowledgeBundle`,
+ * `DbSchema`, anything a function declares as its input or output — appears
+ * there only as a name; its definition is resolved out of a project file or a
+ * dependency's `.d.ts`. Edit one of those and the key is unchanged, so a stale
+ * schema is served for a type that no longer looks like that. The failure is
+ * silent and outlives `rm -rf .pikku`, because this cache lives in
+ * `node_modules/.cache`.
+ *
+ * The program is rooted at the virtual file, so its source files are exactly the
+ * transitive closure the schemas depend on — nothing wider, nothing missed.
+ * Default-lib files are skipped: they change only when TypeScript itself does,
+ * which the inspector version in the key already covers.
+ */
+function fingerprintSchemaDeps(program) {
+    const deps = [];
+    for (const sourceFile of program.getSourceFiles()) {
+        if (program.isSourceFileDefaultLibrary(sourceFile))
+            continue;
+        try {
+            const stat = statSync(sourceFile.fileName);
+            deps.push({
+                path: sourceFile.fileName,
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+            });
+        }
+        catch {
+            // The virtual root has no file on disk. Its content is the custom-types
+            // source, which the cache key already hashes.
+        }
+    }
+    return deps;
+}
+/**
+ * Whether every file the schemas were derived from is still exactly as it was.
+ *
+ * mtime-and-size rather than a content hash: this runs on the cache-hit path,
+ * where the whole point is to answer in milliseconds without building a TS
+ * program. Anything that rewrites a file — a dependency rebuild, a checkout, an
+ * edit — moves its mtime, and a missing file reads as changed, so the answer errs
+ * toward regenerating.
+ */
+function schemaDepsUnchanged(deps) {
+    if (!Array.isArray(deps))
+        return false;
+    for (const dep of deps) {
+        if (!dep || typeof dep.path !== 'string')
+            return false;
+        try {
+            const stat = statSync(dep.path);
+            if (stat.mtimeMs !== dep.mtimeMs || stat.size !== dep.size)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+export function readDiskTSSchemas(logger, cacheDir, key) {
     const file = schemaCacheFile(cacheDir);
     if (!existsSync(file))
         return null;
     try {
         const parsed = JSON.parse(readFileSync(file, 'utf-8'));
-        if (parsed?.key === key && parsed.schemas)
-            return parsed.schemas;
+        if (parsed?.key !== key || !parsed.schemas)
+            return null;
+        if (!schemaDepsUnchanged(parsed.deps)) {
+            logger.debug('Discarding TS-schema cache: a type it was built from changed');
+            return null;
+        }
+        return { schemas: parsed.schemas, deps: parsed.deps };
     }
     catch (e) {
         logger.debug(`Ignoring unreadable TS-schema cache: ${e.message}`);
     }
     return null;
 }
-function writeDiskTSSchemas(logger, cacheDir, key, schemas) {
+export function writeDiskTSSchemas(logger, cacheDir, key, schemas, deps) {
     const file = schemaCacheFile(cacheDir);
     try {
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, JSON.stringify({ key, schemas }));
+        writeFileSync(file, JSON.stringify({ key, schemas, deps }));
     }
     catch (e) {
         logger.debug(`Failed to persist TS-schema cache: ${e.message}`);
@@ -196,7 +265,7 @@ function generateTSSchemas(logger, tsconfig, customTypesContent, typesMap, funct
     // so that failed Zod conversions fall through to TS schema generation.
     const uncoveredSchemas = [...schemasSet].filter((s) => !PRIMITIVE_TYPES.has(s) && !generatedZodSchemas?.[s]);
     if (uncoveredSchemas.length === 0) {
-        return {};
+        return { schemas: {}, deps: [] };
     }
     logger.debug(`generateTSSchemas needed for ${uncoveredSchemas.length} types: ${uncoveredSchemas.slice(0, 3).join(', ')}${uncoveredSchemas.length > 3 ? '...' : ''}`);
     const virtualFilePath = join(dirname(resolve(tsconfig)), '__pikku_virtual_types__.ts');
@@ -239,8 +308,29 @@ function generateTSSchemas(logger, tsconfig, customTypesContent, typesMap, funct
             logger.error(`[${ErrorCode.SCHEMA_GENERATION_ERROR}] Error generating schema: ${schema}. Message: ${e.message}. Type info: ${customType ? `type=${customType.type}` : 'not in typesMap'}`);
         }
     });
-    return schemas;
+    // Fingerprinted here, while the program is still alive — it is released as soon
+    // as the schemas are out of it.
+    return { schemas, deps: fingerprintSchemaDeps(program) };
 }
+/**
+ * Where the RUNTIME value of a schema lives, given where TypeScript resolved it.
+ *
+ * A schema imported from a built workspace package resolves to that package's
+ * declaration file, and importing a `.d.ts` yields a module with no exports at
+ * all — every one of them is a type. The value is in the emitted JS beside it, so
+ * that is what gets imported.
+ *
+ * Falls back to the original path when no sibling JS exists, which keeps the
+ * "could not find exported schema" error pointing at the file the developer
+ * actually wrote.
+ */
+export const schemaRuntimeFile = (sourceFile) => {
+    const match = /\.d\.([cm]?)ts$/.exec(sourceFile);
+    if (!match)
+        return sourceFile;
+    const emitted = sourceFile.replace(/\.d\.([cm]?)ts$/, '.$1js');
+    return existsSync(emitted) ? emitted : sourceFile;
+};
 /**
  * Import all source files in parallel using tsx's register() API.
  *
@@ -333,7 +423,7 @@ async function generateZodSchemas(logger, schemaLookup, typesMap) {
     }
     // Collect unique source files and batch-import them in parallel
     const uniqueSourceFiles = [
-        ...new Set([...schemaLookup.values()].map((ref) => ref.sourceFile)),
+        ...new Set([...schemaLookup.values()].map((ref) => schemaRuntimeFile(ref.sourceFile))),
     ];
     logger.debug(`[TIMING] Zod schemas: ${schemaLookup.size} schemas from ${uniqueSourceFiles.length} files`);
     const importStart = performance.now();
@@ -343,11 +433,12 @@ async function generateZodSchemas(logger, schemaLookup, typesMap) {
     // Track schemas that need per-file tsImport fallback
     const fallbackSchemas = [];
     for (const [schemaName, ref] of schemaLookup.entries()) {
-        const mod = importedModules?.get(ref.sourceFile);
+        const runtimeFile = schemaRuntimeFile(ref.sourceFile);
+        const mod = importedModules?.get(runtimeFile);
         if (mod) {
             const zodSchema = mod[ref.variableName];
             if (!zodSchema) {
-                errors.push(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`);
+                errors.push(`Could not find exported schema '${ref.variableName}' in ${runtimeFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`);
                 continue;
             }
             try {
@@ -368,11 +459,12 @@ async function generateZodSchemas(logger, schemaLookup, typesMap) {
     if (fallbackSchemas.length > 0) {
         logger.debug(`Falling back to register() import for ${fallbackSchemas.length} schema(s)`);
         for (const [schemaName, ref] of fallbackSchemas) {
+            const runtimeFile = schemaRuntimeFile(ref.sourceFile);
             try {
-                const module = await importWithRegister(ref.sourceFile);
+                const module = await importWithRegister(runtimeFile);
                 const zodSchema = module[ref.variableName];
                 if (!zodSchema) {
-                    errors.push(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`);
+                    errors.push(`Could not find exported schema '${ref.variableName}' in ${runtimeFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`);
                     continue;
                 }
                 processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger);
@@ -395,8 +487,13 @@ export async function generateAllSchemas(logger, config, state) {
     const zodSchemas = await generateZodSchemas(logger, state.schemaLookup, state.functions.typesMap);
     const requiredTypes = new Set();
     const customTypesContent = generateCustomTypes(state.functions.typesMap, requiredTypes);
-    // Fast path: same process, types unchanged — reuse the in-memory result.
-    if (cachedTSSchemas && cachedCustomTypesContent === customTypesContent) {
+    // Fast path: same process, types unchanged — reuse the in-memory result. The
+    // dep check is what makes this correct under `pikku dev`, where the process
+    // outlives the edits: the custom-types source is identical whenever a named
+    // type changes shape without changing its name.
+    if (cachedTSSchemas &&
+        cachedCustomTypesContent === customTypesContent &&
+        schemaDepsUnchanged(cachedTSSchemaDeps)) {
         logger.debug('Reusing cached TS schemas (types unchanged)');
         return { ...cachedTSSchemas, ...zodSchemas };
     }
@@ -411,11 +508,12 @@ export async function generateAllSchemas(logger, config, state) {
         if (disk) {
             logger.debug('Reusing on-disk TS schemas (types unchanged across runs)');
             cachedCustomTypesContent = customTypesContent;
-            cachedTSSchemas = disk;
-            return { ...disk, ...zodSchemas };
+            cachedTSSchemas = disk.schemas;
+            cachedTSSchemaDeps = disk.deps;
+            return { ...disk.schemas, ...zodSchemas };
         }
     }
-    const tsSchemas = generateTSSchemas(logger, config.tsconfig, customTypesContent, state.functions.typesMap, state.functions.meta, state.http.meta, config.schemasFromTypes, config.schema?.additionalProperties, zodSchemas);
+    const { schemas: tsSchemas, deps: tsSchemaDeps } = generateTSSchemas(logger, config.tsconfig, customTypesContent, state.functions.typesMap, state.functions.meta, state.http.meta, config.schemasFromTypes, config.schema?.additionalProperties, zodSchemas);
     // Release the program once the schemas are out of it. It spans the whole
     // tsconfig (~2.5k files, ~600MB on a large tree) and was previously pinned at
     // module scope for the life of the process, so it stacked on top of the main
@@ -425,8 +523,9 @@ export async function generateAllSchemas(logger, config, state) {
     cachedSchemaProgram = undefined;
     cachedCustomTypesContent = customTypesContent;
     cachedTSSchemas = tsSchemas;
+    cachedTSSchemaDeps = tsSchemaDeps;
     if (config.cacheDir && cacheKey) {
-        writeDiskTSSchemas(logger, config.cacheDir, cacheKey, tsSchemas);
+        writeDiskTSSchemas(logger, config.cacheDir, cacheKey, tsSchemas, tsSchemaDeps);
     }
     return { ...tsSchemas, ...zodSchemas };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.48",
+  "version": "0.12.50",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.70"
+    "@pikku/core": "^0.12.72"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.70",
+    "@pikku/core": "^0.12.72",
     "@types/node": "^24.11.0"
   },
   "engines": {