@pikku/core 0.12.71 → 0.12.74

package/dist/crypto-utils.d.ts

@@ -1,12 +1,37 @@
 export declare const encryptJSON: (secret: string, value: unknown) => Promise<string>;
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
+/**
+ * Namespaces the remote-RPC session key so the same deployment secret used for
+ * another purpose derives a different key. See knowledge/crypto.md.
+ */
+export declare const REMOTE_SESSION_INFO = "pikku:remote-session";
+export declare const MIN_KEY_MATERIAL_LENGTH = 32;
+export declare const assertStrongKeyMaterial: (name: string, keyMaterial: string) => void;
+export declare const encryptWithKeyMaterial: (name: string, keyMaterial: string, info: string, value: unknown) => Promise<string>;
+export declare const decryptWithKeyMaterial: <T>(name: string, keyMaterial: string, info: string, token: string) => Promise<T>;
+export declare const encodeBase64UrlText: (value: string) => string;
+export declare const decodeBase64UrlText: (value: string) => string;
+/**
+ * HMAC-SHA256 over `payload` under a key expanded from high-entropy key
+ * material, base64url-encoded. The salt is empty by design so the verifier can
+ * re-derive the key from `keyMaterial` and `info` alone.
+ */
+export declare const signWithKeyMaterial: (name: string, keyMaterial: string, info: string, payload: string) => Promise<string>;
+/** False — never throws — for a malformed, truncated or mismatched signature. */
+export declare const verifyWithKeyMaterial: (name: string, keyMaterial: string, info: string, payload: string, signature: string) => Promise<boolean>;
 export declare const generateDEK: () => Promise<string>;
-export declare const wrapDEK: (kek: string, plaintextDEK: string) => Promise<string>;
-export declare const unwrapDEK: (kek: string, wrappedDEK: string) => Promise<string>;
+/**
+ * One salt per (deployment, key version), stored beside the wrapped DEKs.
+ * See knowledge/crypto.md.
+ */
+export declare const generateKEKSalt: () => string;
+export declare const deriveKEK: (passphrase: string, salt: string) => Promise<CryptoKey>;
+export declare const wrapDEK: (kek: CryptoKey, plaintextDEK: string) => Promise<string>;
+export declare const unwrapDEK: (kek: CryptoKey, wrappedDEK: string) => Promise<string>;
 export interface EnvelopeEncryptResult {
     ciphertext: string;
     wrappedDEK: string;
 }
-export declare const envelopeEncrypt: (kek: string, value: unknown) => Promise<EnvelopeEncryptResult>;
-export declare const envelopeDecrypt: <T>(kek: string, ciphertext: string, wrappedDEK: string) => Promise<T>;
-export declare const envelopeRewrap: (oldKEK: string, newKEK: string, wrappedDEK: string) => Promise<string>;
+export declare const envelopeEncrypt: (kek: CryptoKey, value: unknown) => Promise<EnvelopeEncryptResult>;
+export declare const envelopeDecrypt: <T>(kek: CryptoKey, ciphertext: string, wrappedDEK: string) => Promise<T>;
+export declare const envelopeRewrap: (oldKEK: CryptoKey, newKEK: CryptoKey, wrappedDEK: string) => Promise<string>;

package/dist/crypto-utils.js

@@ -1,3 +1,4 @@
+import { WeakKeyMaterialError } from './errors/errors.js';
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 const getSubtle = () => {
@@ -40,13 +41,19 @@ const fromBase64Url = (input) => {
         base64 += '=';
     return base64Decode(base64);
 };
-const deriveKey = async (secret) => {
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const PBKDF2_ITERATIONS = 600_000;
+const deriveKey = async (secret, salt) => {
     const subtle = getSubtle();
-    const hash = await subtle.digest('SHA-256', encoder.encode(secret));
-    return subtle.importKey('raw', hash, { name: 'AES-GCM' }, false, [
-        'encrypt',
-        'decrypt',
-    ]);
+    const material = await subtle.importKey('raw', encoder.encode(secret), { name: 'PBKDF2' }, false, ['deriveKey']);
+    return subtle.deriveKey({
+        name: 'PBKDF2',
+        salt: salt,
+        iterations: PBKDF2_ITERATIONS,
+        hash: 'SHA-256',
+    }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
 };
 export const encryptJSON = async (secret, value) => {
     const crypto = globalThis.crypto;
@@ -54,76 +61,174 @@ export const encryptJSON = async (secret, value) => {
         throw new Error('WebCrypto not available');
     }
     const subtle = getSubtle();
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const key = await deriveKey(secret);
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const key = await deriveKey(secret, salt);
     const plaintext = encoder.encode(JSON.stringify(value));
     const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext);
     const cipherBytes = new Uint8Array(encrypted);
-    const out = new Uint8Array(iv.length + cipherBytes.length);
-    out.set(iv, 0);
-    out.set(cipherBytes, iv.length);
+    const out = new Uint8Array(salt.length + iv.length + cipherBytes.length);
+    out.set(salt, 0);
+    out.set(iv, salt.length);
+    out.set(cipherBytes, salt.length + iv.length);
     return toBase64Url(out);
 };
 export const decryptJSON = async (secret, token) => {
     const subtle = getSubtle();
     const data = fromBase64Url(token);
-    if (data.length < 13) {
+    if (data.length <= SALT_BYTES + IV_BYTES + TAG_BYTES) {
         throw new Error('Invalid encrypted payload');
     }
-    const iv = data.slice(0, 12);
-    const ciphertext = data.slice(12);
-    const key = await deriveKey(secret);
+    const salt = data.slice(0, SALT_BYTES);
+    const iv = data.slice(SALT_BYTES, SALT_BYTES + IV_BYTES);
+    const ciphertext = data.slice(SALT_BYTES + IV_BYTES);
+    const key = await deriveKey(secret, salt);
     const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
 /**
- * Envelope encryption utilities.
- *
- * Each secret gets its own random DEK (data encryption key).
- * The DEK is wrapped (encrypted) by a KEK (key encryption key) — typically an env var.
- * The actual secret is encrypted with the DEK.
- *
- * KEK rotation only re-wraps the DEK, never touches the ciphertext.
+ * Namespaces the remote-RPC session key so the same deployment secret used for
+ * another purpose derives a different key. See knowledge/crypto.md.
  */
-const importRawKey = async (rawBytes) => {
+export const REMOTE_SESSION_INFO = 'pikku:remote-session';
+export const MIN_KEY_MATERIAL_LENGTH = 32;
+export const assertStrongKeyMaterial = (name, keyMaterial) => {
+    if (keyMaterial.length < MIN_KEY_MATERIAL_LENGTH) {
+        throw new WeakKeyMaterialError(name, MIN_KEY_MATERIAL_LENGTH, keyMaterial.length);
+    }
+};
+const expandKeyMaterial = async (keyMaterial, info, salt) => {
     const subtle = getSubtle();
-    return subtle.importKey('raw', rawBytes.buffer, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+    const material = await subtle.importKey('raw', encoder.encode(keyMaterial), 'HKDF', false, ['deriveKey']);
+    return subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: salt,
+        info: encoder.encode(info),
+    }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+};
+export const encryptWithKeyMaterial = async (name, keyMaterial, info, value) => {
+    assertStrongKeyMaterial(name, keyMaterial);
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('WebCrypto not available');
+    }
+    const subtle = getSubtle();
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const key = await expandKeyMaterial(keyMaterial, info, salt);
+    const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, encoder.encode(JSON.stringify(value)));
+    const cipherBytes = new Uint8Array(encrypted);
+    const out = new Uint8Array(salt.length + iv.length + cipherBytes.length);
+    out.set(salt, 0);
+    out.set(iv, salt.length);
+    out.set(cipherBytes, salt.length + iv.length);
+    return toBase64Url(out);
 };
-export const generateDEK = async () => {
-    const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
-    return toBase64Url(raw);
+export const decryptWithKeyMaterial = async (name, keyMaterial, info, token) => {
+    assertStrongKeyMaterial(name, keyMaterial);
+    const subtle = getSubtle();
+    const data = fromBase64Url(token);
+    if (data.length <= SALT_BYTES + IV_BYTES + TAG_BYTES) {
+        throw new Error('Invalid encrypted payload');
+    }
+    const salt = data.slice(0, SALT_BYTES);
+    const iv = data.slice(SALT_BYTES, SALT_BYTES + IV_BYTES);
+    const ciphertext = data.slice(SALT_BYTES + IV_BYTES);
+    const key = await expandKeyMaterial(keyMaterial, info, salt);
+    const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+    return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
-export const wrapDEK = async (kek, plaintextDEK) => {
-    return encryptJSON(kek, plaintextDEK);
+export const encodeBase64UrlText = (value) => toBase64Url(encoder.encode(value));
+export const decodeBase64UrlText = (value) => decoder.decode(fromBase64Url(value));
+const expandSigningKeyMaterial = async (keyMaterial, info) => {
+    const subtle = getSubtle();
+    const material = await subtle.importKey('raw', encoder.encode(keyMaterial), 'HKDF', false, ['deriveKey']);
+    return subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: new Uint8Array(0),
+        info: encoder.encode(info),
+    }, material, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
 };
-export const unwrapDEK = async (kek, wrappedDEK) => {
-    return decryptJSON(kek, wrappedDEK);
+/**
+ * HMAC-SHA256 over `payload` under a key expanded from high-entropy key
+ * material, base64url-encoded. The salt is empty by design so the verifier can
+ * re-derive the key from `keyMaterial` and `info` alone.
+ */
+export const signWithKeyMaterial = async (name, keyMaterial, info, payload) => {
+    assertStrongKeyMaterial(name, keyMaterial);
+    const key = await expandSigningKeyMaterial(keyMaterial, info);
+    const signature = await getSubtle().sign('HMAC', key, encoder.encode(payload));
+    return toBase64Url(new Uint8Array(signature));
+};
+/** False — never throws — for a malformed, truncated or mismatched signature. */
+export const verifyWithKeyMaterial = async (name, keyMaterial, info, payload, signature) => {
+    assertStrongKeyMaterial(name, keyMaterial);
+    const key = await expandSigningKeyMaterial(keyMaterial, info);
+    try {
+        return await getSubtle().verify('HMAC', key, fromBase64Url(signature), encoder.encode(payload));
+    }
+    catch {
+        return false;
+    }
 };
-const encryptWithDEK = async (dekBase64, value) => {
+const importRawKey = async (rawBytes) => {
+    const subtle = getSubtle();
+    return subtle.importKey('raw', rawBytes.buffer, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+};
+const encryptWithCryptoKey = async (key, value) => {
     const crypto = globalThis.crypto;
     const subtle = getSubtle();
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const key = await importRawKey(fromBase64Url(dekBase64));
-    const plaintext = encoder.encode(JSON.stringify(value));
-    const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext);
+    const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const encrypted = await subtle.encrypt({ name: 'AES-GCM', iv }, key, encoder.encode(JSON.stringify(value)));
     const cipherBytes = new Uint8Array(encrypted);
     const out = new Uint8Array(iv.length + cipherBytes.length);
     out.set(iv, 0);
     out.set(cipherBytes, iv.length);
     return toBase64Url(out);
 };
-const decryptWithDEK = async (dekBase64, token) => {
+const decryptWithCryptoKey = async (key, token) => {
     const subtle = getSubtle();
     const data = fromBase64Url(token);
-    if (data.length < 13) {
+    if (data.length < IV_BYTES + TAG_BYTES) {
         throw new Error('Invalid encrypted payload');
     }
-    const iv = data.slice(0, 12);
-    const ciphertext = data.slice(12);
-    const key = await importRawKey(fromBase64Url(dekBase64));
+    const iv = data.slice(0, IV_BYTES);
+    const ciphertext = data.slice(IV_BYTES);
     const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
+export const generateDEK = async () => {
+    const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
+    return toBase64Url(raw);
+};
+/**
+ * One salt per (deployment, key version), stored beside the wrapped DEKs.
+ * See knowledge/crypto.md.
+ */
+export const generateKEKSalt = () => {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('WebCrypto not available');
+    }
+    return toBase64Url(crypto.getRandomValues(new Uint8Array(SALT_BYTES)));
+};
+export const deriveKEK = async (passphrase, salt) => {
+    return deriveKey(passphrase, fromBase64Url(salt));
+};
+export const wrapDEK = async (kek, plaintextDEK) => {
+    return encryptWithCryptoKey(kek, plaintextDEK);
+};
+export const unwrapDEK = async (kek, wrappedDEK) => {
+    return decryptWithCryptoKey(kek, wrappedDEK);
+};
+const encryptWithDEK = async (dekBase64, value) => {
+    return encryptWithCryptoKey(await importRawKey(fromBase64Url(dekBase64)), value);
+};
+const decryptWithDEK = async (dekBase64, token) => {
+    return decryptWithCryptoKey(await importRawKey(fromBase64Url(dekBase64)), token);
+};
 export const envelopeEncrypt = async (kek, value) => {
     const dek = await generateDEK();
     const ciphertext = await encryptWithDEK(dek, value);

package/dist/dev/hot-reload.js

@@ -32,12 +32,6 @@ const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
     }
     return null;
 };
-// Changed user files are re-run through an evictable module runner keyed by a
-// stable path (createModuleRunner), NOT re-imported under a fresh URL. A
-// fresh-URL import (a `data:` URL on Node, a uniquely-named temp sibling on
-// Bun) permanently leaks a record in the native ESM loader map on every
-// reload, OOMing long editing sessions; the runner overwrites a single slot so
-// the previous module is collected. See ./module-runner.ts.
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
@@ -67,17 +61,12 @@ export async function pikkuDevReloader(options) {
             logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
         }
-        // Register every function-config export — replacing known functions AND
-        // adding new ones (a brand-new function becomes callable as soon as its
-        // meta lands via reloadGeneratedMeta after the next codegen pass).
-        // Write into the map captured at startup, NOT pikkuState's current one:
-        // a dev-server watcher may have temporarily swapped in a codegen-scoped
-        // map for the same file event (runAllWithCommandState), and a write to
-        // that map is silently discarded when it restores the original.
-        // Schemas are NOT touched here: `input`/`output` hold raw zod schemas,
-        // while the schema map carries codegen-generated JSON schemas — mixing the
-        // two crashed every reload. Fresh JSON schemas arrive via
-        // reloadGeneratedMeta once codegen has re-emitted them.
+        // Register every function-config export, replacing known functions and
+        // adding new ones. Write into the map captured at startup, NOT pikkuState's
+        // current one: a dev-server watcher may have temporarily swapped in a
+        // codegen-scoped map, whose writes are discarded when it restores.
+        // Schemas are NOT touched here: `input`/`output` hold raw zod schemas while
+        // the schema map carries codegen JSON schemas; mixing them crashed reloads.
         for (const [exportName, exportValue] of Object.entries(mod)) {
             if (!isFunctionConfig(exportValue))
                 continue;
@@ -88,10 +77,9 @@ export async function pikkuDevReloader(options) {
             else
                 reloadedNames.push(exportName);
         }
-        // Re-importing the module re-ran its wire* side effects (wireHTTP et al
-        // are keyed map-sets, so re-registration replaces/adds) — reset the
-        // router and caches even when no function export changed, so a
-        // wiring-only file edit rebuilds the route matchers too.
+        // Re-importing re-ran the module’s wire* side effects, so reset the router
+        // and caches even when no function export changed — a wiring-only edit has
+        // to rebuild the route matchers too.
         clearMiddlewareCache();
         clearPermissionsCache();
         clearChannelMiddlewareCache();
@@ -108,9 +96,8 @@ export async function pikkuDevReloader(options) {
     };
     let debounceTimer;
     const pendingChanges = new Set();
-    // Files re-imported since the last reimportPending() drain. A dev-server
-    // watcher drains this after its codegen pass so wire* registrations that
-    // were skipped for missing meta (a NEW route) run again with fresh meta.
+    // Files re-imported since the last reimportPending() drain, re-run after the
+    // dev server's codegen pass so registrations skipped for missing meta retry.
     const postCodegenQueue = new Set();
     const safeHandleFileChange = async (file) => {
         try {
@@ -156,12 +143,6 @@ export async function pikkuDevReloader(options) {
             }
             moduleRunner.clear();
         },
-        // Drain the queue of recently re-imported files and import them again.
-        // A dev-server watcher calls this AFTER its codegen pass has refreshed
-        // the generated meta (reloadGeneratedMeta): wire* registrations skip
-        // routes whose meta doesn't exist yet, so a wiring file changed
-        // alongside a NEW function only registers its new route when
-        // re-imported after the fresh meta has landed.
         reimportPending: async () => {
             const files = [...postCodegenQueue];
             postCodegenQueue.clear();

package/dist/dev/module-runner.d.ts

@@ -1,14 +1,10 @@
 export interface PikkuModuleRunner {
-    /** Run a user module by absolute path, returning its exports. Repeated runs
-     *  of the same path overwrite a single registry slot (the previous module is
-     *  collected). Returns `null` if transpile/compile/evaluation fails, so the
-     *  caller can keep the previously-loaded code. */
+    /** Run a user module by absolute path. Repeated runs of one path overwrite a
+     *  single registry slot. Returns `null` on failure so the caller can keep the
+     *  previously-loaded code. */
     run: (absPath: string) => Promise<Record<string, unknown> | null>;
-    /** Drop a single module from the registry. */
     evict: (absPath: string) => void;
-    /** Drop every module from the registry. */
     clear: () => void;
-    /** Number of modules currently held. */
     readonly size: number;
 }
 export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -7,9 +7,8 @@ let transformSync;
 const loadTransform = async () => {
     if (transformSync)
         return transformSync;
-    // esbuild is a dev-only dependency, hoisted from @pikku/cli at runtime — the
-    // same lazy pattern the reloader previously used for tsx. It is never loaded
-    // in production runtimes (the `./dev` export is dev-only).
+    // esbuild is a dev-only dependency hoisted from @pikku/cli at runtime; the
+    // `./dev` export is dev-only so it is never loaded in production runtimes.
     const esbuild = await import('esbuild');
     transformSync = esbuild.transformSync;
     return transformSync;
@@ -21,10 +20,6 @@ export const createModuleRunner = () => {
         try {
             const transform = await loadTransform();
             const source = await readFile(absPath, 'utf-8');
-            // No sourcemap: an inline sourcemap embeds a base64 copy of the source
-            // that the engine retains per compile, reintroducing linear growth on
-            // Node — the exact leak this runner exists to remove. `filename` still
-            // anchors stack traces to the user file.
             const { code } = transform(source, {
                 loader: absPath.endsWith('.ts') ? 'ts' : 'js',
                 format: 'cjs',
@@ -38,9 +33,8 @@ export const createModuleRunner = () => {
             return moduleObj.exports;
         }
         catch {
-            // Transpile/compile/evaluate failure (a bad edit, or the one known
-            // limitation — a file using top-level `await`, which can't be emitted in
-            // `cjs` form). Return null so the caller keeps the previously-loaded code.
+            // A bad edit, or the one known limitation: a file using top-level
+            // `await`, which cannot be emitted in `cjs` form.
             return null;
         }
     };

package/dist/dev/reload-meta.d.ts

@@ -9,29 +9,17 @@ export interface ReloadGeneratedMetaOptions {
     schemaService?: SchemaService;
 }
 /**
- * Re-reads the codegen output (wiring meta + JSON schemas) into the running
- * process so new and changed functions become callable without a server
- * restart. The generated `*-meta.gen.ts` files are plain
- * `pikkuState(area, key, <json>)` side effects, but they cannot be
- * re-imported after a dev-time codegen — the ESM cache pins both the wrapper
- * and its JSON import — so this reads the JSON sources directly and applies
- * the same state.
- *
- * Meant to be called by a dev-server watcher after each codegen pass. Routes
- * registered by NEW `wireHTTP` files are not picked up (their modules were
- * never imported); those still need a restart.
+ * Re-reads codegen output (wiring meta + JSON schemas) into the running
+ * process, so new and changed functions become callable without a restart.
+ * Called by a dev-server watcher after each codegen pass. Routes registered by
+ * NEW `wireHTTP` files are not picked up — their modules were never imported.
  */
 export declare function reloadGeneratedMeta(options: ReloadGeneratedMetaOptions): Promise<void>;
 /**
- * Prunes the live addon registry down to what the current source still declares.
- *
- * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
- * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
- * until a full restart — the reason `getInstalledAddons` reports removed addons.
- * The Map holds definitions (namespace → package config), not runtime state, so
- * dropping any namespace the fresh inspection no longer declares is safe.
+ * Prunes the live addon registry to the namespaces the current source still
+ * declares. Hot reload only re-imports files that exist, so a deleted
+ * `*.addon.ts` otherwise leaves its `wireAddon` entry stranded until a restart.
  *
- * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
- * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ * `declaredNamespaces` is `inspectorState.rpc.wireAddonDeclarations.keys()`.
  */
 export declare function reconcileAddonRegistry(declaredNamespaces: Iterable<string>, logger?: Logger): void;

package/dist/dev/reload-meta.js

@@ -24,27 +24,16 @@ const readJson = async (logger, file) => {
     }
 };
 /**
- * Re-reads the codegen output (wiring meta + JSON schemas) into the running
- * process so new and changed functions become callable without a server
- * restart. The generated `*-meta.gen.ts` files are plain
- * `pikkuState(area, key, <json>)` side effects, but they cannot be
- * re-imported after a dev-time codegen — the ESM cache pins both the wrapper
- * and its JSON import — so this reads the JSON sources directly and applies
- * the same state.
- *
- * Meant to be called by a dev-server watcher after each codegen pass. Routes
- * registered by NEW `wireHTTP` files are not picked up (their modules were
- * never imported); those still need a restart.
+ * Re-reads codegen output (wiring meta + JSON schemas) into the running
+ * process, so new and changed functions become callable without a restart.
+ * Called by a dev-server watcher after each codegen pass. Routes registered by
+ * NEW `wireHTTP` files are not picked up — their modules were never imported.
  */
 export async function reloadGeneratedMeta(options) {
     const { pikkuDir, logger, schemaService } = options;
     const dir = resolve(pikkuDir);
     const functionsMeta = await readJson(logger, join(dir, 'function/pikku-functions-meta.gen.json'));
-    // Merge over the existing map, don't replace it: framework internals like
-    // pikkuWorkflowOrchestrator / the per-workflow queue workers are registered
-    // at service-init (pikku-workflow-service.ts), never in the generated JSON —
-    // a wholesale replace drops them and workflow jobs then fail with
-    // "Function meta not found: pikkuWorkflowOrchestrator".
+    // knowledge: decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md
     if (functionsMeta) {
         const existing = pikkuState(null, 'function', 'meta') ?? {};
         pikkuState(null, 'function', 'meta', { ...existing, ...functionsMeta });
@@ -56,9 +45,6 @@ export async function reloadGeneratedMeta(options) {
     if (rpcMeta)
         pikkuState(null, 'rpc', 'meta', rpcMeta);
     const queueMeta = await readJson(logger, join(dir, 'queue/pikku-queue-workers-wirings-meta.gen.json'));
-    // Same reason as function meta: the workflow service adds its orchestrator /
-    // step queues (and wf-orchestrator-* / wf-step-* per-workflow queues) here at
-    // init, absent from the generated JSON — merge so they survive the reload.
     if (queueMeta) {
         const existing = pikkuState(null, 'queue', 'meta') ?? {};
         pikkuState(null, 'queue', 'meta', { ...existing, ...queueMeta });
@@ -67,7 +53,6 @@ export async function reloadGeneratedMeta(options) {
     if (agentMeta?.agentsMeta) {
         pikkuState(null, 'agent', 'agentsMeta', agentMeta.agentsMeta);
     }
-    // Generated JSON schemas: <outDir>/schemas/schemas/<Name>.schema.json.
     // Re-adding replaces the map entry; the schema service recompiles any
     // validator whose stored schema value no longer matches.
     const schemasDir = join(dir, 'schemas', 'schemas');
@@ -98,16 +83,11 @@ export async function reloadGeneratedMeta(options) {
     }
 }
 /**
- * Prunes the live addon registry down to what the current source still declares.
- *
- * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
- * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
- * until a full restart — the reason `getInstalledAddons` reports removed addons.
- * The Map holds definitions (namespace → package config), not runtime state, so
- * dropping any namespace the fresh inspection no longer declares is safe.
+ * Prunes the live addon registry to the namespaces the current source still
+ * declares. Hot reload only re-imports files that exist, so a deleted
+ * `*.addon.ts` otherwise leaves its `wireAddon` entry stranded until a restart.
  *
- * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
- * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ * `declaredNamespaces` is `inspectorState.rpc.wireAddonDeclarations.keys()`.
  */
 export function reconcileAddonRegistry(declaredNamespaces, logger) {
     const declared = new Set(declaredNamespaces);

package/dist/errors/error-handler.d.ts

@@ -1,46 +1,21 @@
-/**
- * Base class for custom errors.
- * @extends {Error}
- */
 export declare class PikkuError extends Error {
-    /**
-     * Creates an instance of PikkuError.
-     * @param message - The error message.
-     */
     constructor(message?: string);
 }
 /**
- * Whether an error is a deliberate, expected failure rather than an uncaught
- * bug. A `PikkuError` always counts; so does any error carrying `expected:
- * true` — used to keep the marker alive when an error is serialized across a
- * workflow step boundary and rehydrated as a plain `Error`. Callers log the
- * message alone for expected errors and the full stack for everything else.
+ * A `PikkuError`, or any error carrying `expected: true` — the marker that
+ * survives serialization across a workflow step boundary and rehydration as a
+ * plain `Error`. Callers log the message alone for these, the full stack for
+ * everything else.
  */
 export declare const isExpectedError: (error: unknown) => boolean;
-/**
- * Interface for error details.
- */
 export interface ErrorDetails {
     status: number;
     message: string;
     mcpCode?: number;
 }
-/**
- * Adds an error to the API errors map.
- * @param error - The error to add.
- * @param details - The details of the error.
- */
+export type PikkuErrorConstructor = new (...args: any[]) => Error;
 export declare const addError: (error: any, { status, message, mcpCode }: ErrorDetails) => void;
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
 export declare const addErrors: (errors: Array<[error: any, details: ErrorDetails]>) => void;
-/**
- * Retrieves the error response for a given error.
- * @param error - The error to get the response for.
- * @returns An object containing the status and message, or undefined if the error is not found.
- */
 export declare const getErrorResponse: (error: Error) => {
     status: number;
     message: string;