@pikku/core 0.12.72 → 0.12.77

package/dist/column-form.d.ts

@@ -0,0 +1,32 @@
+import type { HashedValue, SealedValue, WrappedValue } from './data-classification.js';
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export declare const hashToken: (raw: string) => Promise<HashedValue>;
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export declare const unsafeAsWrapped: (stored: string) => WrappedValue;
+/** See `unsafeAsWrapped`. */
+export declare const unsafeAsSealed: (stored: string) => SealedValue;
+/** See `unsafeAsWrapped`. */
+export declare const unsafeAsHashed: (stored: string) => HashedValue;

package/dist/column-form.js

@@ -0,0 +1,42 @@
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export const hashToken = async (raw) => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('WebCrypto not available');
+    }
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(raw));
+    let hex = '';
+    for (const byte of new Uint8Array(digest)) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return hex;
+};
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export const unsafeAsWrapped = (stored) => stored;
+/** See `unsafeAsWrapped`. */
+export const unsafeAsSealed = (stored) => stored;
+/** See `unsafeAsWrapped`. */
+export const unsafeAsHashed = (stored) => stored;

package/dist/crypto-utils.d.ts

@@ -1,12 +1,48 @@
+import type { WrappedValue } from './data-classification.js';
 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<WrappedValue>;
+export declare const unwrapDEK: (kek: CryptoKey, wrappedDEK: string) => Promise<string>;
 export interface EnvelopeEncryptResult {
-    ciphertext: string;
-    wrappedDEK: string;
+    ciphertext: WrappedValue;
+    wrappedDEK: WrappedValue;
 }
-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>;
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
+export declare const envelopeDecrypt: <T>(kek: CryptoKey, ciphertext: string, wrappedDEK: string) => Promise<T>;
+export declare const envelopeRewrap: (oldKEK: CryptoKey, newKEK: CryptoKey, wrappedDEK: string) => Promise<WrappedValue>;

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,82 +61,196 @@ 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 generateDEK = async () => {
-    const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
-    return toBase64Url(raw);
+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 wrapDEK = async (kek, plaintextDEK) => {
-    return encryptJSON(kek, plaintextDEK);
+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 unwrapDEK = async (kek, wrappedDEK) => {
-    return decryptJSON(kek, wrappedDEK);
+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']);
 };
-const encryptWithDEK = async (dekBase64, value) => {
+/**
+ * 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 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));
+};
+/**
+ * The one place a `WrappedValue` is minted. Every branded return below routes
+ * through here, so the assertion "these bytes really are ciphertext" is made
+ * once and audited once instead of at each call site.
+ */
+const asWrapped = (ciphertext) => ciphertext;
+export const wrapDEK = async (kek, plaintextDEK) => {
+    return asWrapped(await 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);
+    const ciphertext = asWrapped(await encryptWithDEK(dek, value));
     const wrappedDEK = await wrapDEK(kek, dek);
     return { ciphertext, wrappedDEK };
 };
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
 export const envelopeDecrypt = async (kek, ciphertext, wrappedDEK) => {
     const dek = await unwrapDEK(kek, wrappedDEK);
     return decryptWithDEK(dek, ciphertext);

package/dist/data-classification.d.ts

@@ -9,12 +9,56 @@ export type Secret<T> = T & {
 };
 export type Classification = 'public' | 'private' | 'pii' | 'secret';
 export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+/**
+ * How a column's bytes are represented at rest, as distinct from how sensitive
+ * the value is (`Classification`). The two are independent: a token hash is
+ * `secret` + `hashed` and must never be encrypted, because the hash *is* the
+ * lookup key; a live bearer token is `secret` + `plain` today and should not be.
+ *
+ * `wrapped` and `sealed` are siblings rather than one being "encrypted": both
+ * are ciphertext, and what separates them is who can read it back. Wrapped is
+ * symmetric and the application holds the key. Sealed is asymmetric and the
+ * application holds only the public half, so it can write the value and never
+ * read it. Storing one where the other is expected is silent, permanent data
+ * loss, which is why they are not collapsed into a single `encrypted`.
+ */
+export type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed';
+declare const wrappedBrand: unique symbol;
+declare const sealedBrand: unique symbol;
+declare const hashedBrand: unique symbol;
+/**
+ * Ciphertext under a symmetric key the application holds — the output of
+ * `envelopeEncrypt`, `wrapDEK` or `envelopeRewrap`.
+ *
+ * Unlike `Secret<T>` the brand is REQUIRED, so a plain `string` is not
+ * assignable and a column declared `form: 'wrapped'` cannot be written with
+ * anything but genuine ciphertext. It stays assignable *to* `string`, so it
+ * still works as a query operand and serializes normally — the constraint is on
+ * construction, not on use.
+ */
+export type WrappedValue = string & {
+    readonly [wrappedBrand]: true;
+};
+/** Ciphertext under a public key whose private half the application does not
+ *  hold. Deliberately not assignable to `WrappedValue`: writing one where the
+ *  other belongs produces a row nobody can ever open. */
+export type SealedValue = string & {
+    readonly [sealedBrand]: true;
+};
+/** A one-way digest of a secret input. The brand's job is narrow — stop a *raw*
+ *  credential being written into the column that should hold its hash. */
+export type HashedValue = string & {
+    readonly [hashedBrand]: true;
+};
 export interface ColumnClassification {
     classification: Classification;
     anonymize_strategy: AnonymizeStrategy;
+    /** At-rest representation. Absent means `plain`. */
+    form?: ColumnForm;
     description?: string;
 }
 export type ClassificationManifest = {
     version: 1;
     tables: Record<string, Record<string, ColumnClassification>>;
 };
+export {};

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;