zodvex 0.7.2-beta.0 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zodvex",
-  "version": "0.7.2-beta.0",
+  "version": "0.7.2",
   "description": "Codec-first Zod v4 integration for Convex -- type-safe validation, encoding, DB wrapping, and codegen.",
   "keywords": ["zod", "convex", "validators", "codec", "mapping", "schema", "validation"],
   "homepage": "https://github.com/panzacoder/zodvex#readme",

package/src/internal/meta.ts

@@ -40,3 +40,29 @@ export function readMeta(target: unknown): ZodvexMeta | undefined {
   }
   return (target as Record<string, unknown>)[META_KEY] as ZodvexMeta | undefined
 }
+
+const CODEC_BRAND_KEY = '__zodvexCodecBrand'
+
+/**
+ * Attaches a provenance brand to a codec instance. Codegen reads this at
+ * discovery time to match a function-embedded codec to its importable twin
+ * by *declared* identity instead of inferring it from structure. Stored
+ * non-enumerably so it never leaks into user data, and survives
+ * `.optional()` / `.nullable()` wrapping (codegen unwraps to the codec).
+ * See `docs/decisions/2026-06-08-codec-provenance-brands.md`.
+ */
+export function attachCodecBrand(target: object, brand: string): void {
+  Object.defineProperty(target, CODEC_BRAND_KEY, {
+    value: brand,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  })
+}
+
+/** Reads a codec's provenance brand, or undefined if unbranded. */
+export function readCodecBrand(target: unknown): string | undefined {
+  if (target == null || typeof target !== 'object') return undefined
+  const value = (target as Record<string, unknown>)[CODEC_BRAND_KEY]
+  return typeof value === 'string' ? value : undefined
+}

package/src/internal/zx.ts

@@ -24,6 +24,7 @@ import type { GenericId } from 'convex/values'
 import { z } from 'zod'
 import { zodvexCodec } from './codec'
 import { registryHelpers } from './ids'
+import { attachCodecBrand } from './meta'
 import { createSchemaUpdateSchema } from './modelSchemaBundle'
 import { addSystemFields } from './schemaHelpers'
 import type { ZodvexCodec } from './types'
@@ -129,6 +130,13 @@ function id<TableName extends string>(tableName: TableName): ZxId<TableName> {
  * @param wire - Zod schema for the wire format (stored in Convex)
  * @param runtime - Zod schema for the runtime format (used in code)
  * @param transforms - Encode/decode functions
+ * @param opts.brand - Optional provenance brand. When set, codegen matches a
+ *   function-embedded instance of this codec to its importable twin (an
+ *   exported const or model field with the same brand) by *declared* identity
+ *   rather than inferring it from structure — collision-free and namespaced
+ *   across factories. Useful for codec factories like `tagged()` / `sensitive()`
+ *   whose every call returns a fresh instance. See
+ *   `docs/decisions/2026-06-08-codec-provenance-brands.md`.
  *
  * @example
  * ```typescript
@@ -141,6 +149,11 @@ function id<TableName extends string>(tableName: TableName): ZxId<TableName> {
  *     encode: (value) => ({ encrypted: encrypt(value) })
  *   }
  * )
+ *
+ * // Branded factory codec — codegen matches inline instances by brand
+ * function tagged(inner, name) {
+ *   return zx.codec(wire(inner), runtime(inner), transforms, { brand: `tagged:${name}` })
+ * }
  * ```
  */
 function codec<W extends $ZodType, R extends $ZodType, WO = zoutput<W>, RI = zoutput<R>>(
@@ -149,9 +162,12 @@ function codec<W extends $ZodType, R extends $ZodType, WO = zoutput<W>, RI = zou
   transforms: {
     decode: (wire: WO) => RI
     encode: (runtime: RI) => WO
-  }
+  },
+  opts?: { brand?: string }
 ): FullZodvexCodec<W, R> {
-  return zodvexCodec(wire, runtime, transforms) as unknown as FullZodvexCodec<W, R>
+  const built = zodvexCodec(wire, runtime, transforms) as unknown as FullZodvexCodec<W, R>
+  if (opts?.brand) attachCodecBrand(built as object, opts.brand)
+  return built
 }
 
 /**

package/src/public/cli/commands.ts

@@ -1,5 +1,7 @@
+import { spawn } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { discoverModules } from '../codegen/discover'
 import {
   generateApiFile,
@@ -11,10 +13,7 @@ import {
 /**
  * One-shot codegen. Discovers modules, generates files.
  */
-export async function generate(
-  convexDir?: string,
-  options?: { mini?: boolean; freshImports?: boolean }
-): Promise<void> {
+export async function generate(convexDir?: string, options?: { mini?: boolean }): Promise<void> {
   const resolved = resolveConvexDir(convexDir)
   const zodvexDir = path.join(resolved, '_zodvex')
 
@@ -23,7 +22,7 @@ export async function generate(
   // codegen can't discover those modules — a chicken-and-egg problem.
   writeStubApi(zodvexDir)
 
-  const result = await discoverModules(resolved, { freshImports: options?.freshImports })
+  const result = await discoverModules(resolved)
 
   const schemaContent = generateSchemaFile(result.models)
   const apiContent = generateApiFile(
@@ -77,17 +76,14 @@ export async function dev(convexDir?: string, options?: { mini?: boolean }): Pro
     }
 
     if (debounceTimer) clearTimeout(debounceTimer)
-    debounceTimer = setTimeout(async () => {
+    debounceTimer = setTimeout(() => {
       console.log('[zodvex] Regenerating...')
-      try {
-        // freshImports: bust the ESM module cache so the regen sees the edit
-        // that triggered this tick. Without it, Node/Bun returns the cached
-        // module record from the first generate() call and the output looks
-        // stale even though the watcher fired.
-        await generate(resolved, { ...options, freshImports: true })
-      } catch (err) {
-        console.error('[zodvex] Generation failed:', (err as Error).message)
-      }
+      // Spawn a fresh `generate` subprocess rather than regenerating in-process.
+      // A long-lived watcher can't reliably re-import edited modules: Bun's
+      // loader caches ESM by resolved path and ignores query-string busting, so
+      // an in-process regen emits stale output. A fresh process starts with an
+      // empty module cache and always sees the latest source.
+      void regenerate(resolved, options)
     }, 300)
   })
 
@@ -99,6 +95,32 @@ export async function dev(convexDir?: string, options?: { mini?: boolean }): Pro
   })
 }
 
+/**
+ * Regenerate in a fresh subprocess. The dev watcher cannot re-import edited
+ * modules in-process under Bun (it caches ESM by resolved path and ignores
+ * query-string cache-busting), so each change spawns a one-shot `zodvex
+ * generate`, which starts with an empty module cache and always sees the
+ * latest source. Runtime-agnostic by construction.
+ *
+ * @internal Exported for tests; not part of the public API.
+ */
+export function regenerate(resolved: string, options?: { mini?: boolean }): Promise<void> {
+  const cliEntry = fileURLToPath(new URL('./index.js', import.meta.url))
+  const args = [cliEntry, 'generate', resolved]
+  if (options?.mini) args.push('--mini')
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, args, { stdio: 'inherit' })
+    child.on('exit', code => {
+      if (code !== 0) console.error(`[zodvex] Regeneration exited with code ${code}`)
+      resolve()
+    })
+    child.on('error', err => {
+      console.error('[zodvex] Failed to spawn regeneration:', err.message)
+      resolve()
+    })
+  })
+}
+
 /** Writes minimal stub _zodvex/api.js + api.d.ts before discovery to break circular imports.
  *  Previous generations may contain stale imports that cause cycles during re-discovery. */
 function writeStubApi(zodvexDir: string): void {

package/src/public/codegen/discover.ts

@@ -1,5 +1,4 @@
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
 import { globSync } from 'tinyglobby'
 import { z } from 'zod'
 import { readMeta, type ZodvexFunctionMeta, type ZodvexModelMeta } from '../../internal/meta'
@@ -21,10 +20,6 @@ import { zx } from '../../internal/zx'
 import { registerDiscoveryHooks, writeGeneratedStubs } from './discovery-hooks'
 import { findCodec } from './extractCodec'
 
-// Per-process counter for cache-busting dynamic imports across successive
-// discoverModules() calls. See the comment at the import call site below.
-let discoveryRunCounter = 0
-
 export type DiscoveredModel = {
   exportName: string
   tableName: string
@@ -272,18 +267,15 @@ export function walkFunctionCodecs(functions: DiscoveredFunction[]): FunctionEmb
  * Imports each .ts/.js file, reads __zodvexMeta from exports,
  * and builds a registry of models and functions.
  *
+ * Each file is imported once per process. Watch mode (`zodvex dev`) does NOT
+ * re-import in-process between edits — query-string cache-busting is a
+ * Node-only trick that Bun's loader ignores (Bun caches ESM modules by
+ * resolved path), so the watcher spawns a fresh `generate` subprocess per
+ * change instead. See `regenerate()` in cli/commands.ts.
+ *
  * @param convexDir Absolute path to the convex directory to scan.
- * @param options.freshImports If true, append a per-run query string to each
- *   dynamic import so the ESM cache returns a fresh module record each call.
- *   Required for `zodvex dev` watch mode to pick up edits between regens.
- *   One-shot `generate` doesn't need it (each file is imported once per
- *   process). Default false — opt-in to avoid double-loading under test
- *   runners that intercept dynamic imports (Vitest/Vite SSR).
  */
-export async function discoverModules(
-  convexDir: string,
-  options?: { freshImports?: boolean }
-): Promise<DiscoveryResult> {
+export async function discoverModules(convexDir: string): Promise<DiscoveryResult> {
   const models: DiscoveredModel[] = []
   const functions: DiscoveredFunction[] = []
   const codecs: DiscoveredCodec[] = []
@@ -314,23 +306,13 @@ export async function discoverModules(
     ]
   }).sort()
 
-  // See the freshImports JSDoc. Watch mode opts in; one-shot generate skips
-  // the query string so test runners that intercept dynamic imports (Vitest
-  // / Vite SSR) don't double-load and create cross-instance Zod confusion.
-  let cacheKey: string | null = null
-  if (options?.freshImports) {
-    discoveryRunCounter += 1
-    cacheKey = `${process.pid}-${discoveryRunCounter}`
-  }
-
   try {
     for (const file of files) {
       const absPath = path.resolve(convexDir, file)
-      const importUrl = cacheKey ? `${pathToFileURL(absPath).href}?t=${cacheKey}` : absPath
 
       let moduleExports: Record<string, unknown>
       try {
-        moduleExports = await import(importUrl)
+        moduleExports = await import(absPath)
       } catch (err) {
         console.warn(`[zodvex] Warning: Failed to import ${file}:`, (err as Error).message)
         continue

package/src/public/codegen/generate.ts

@@ -1,3 +1,4 @@
+import { readCodecBrand } from '../../internal/meta'
 import {
   $ZodCodec,
   $ZodNullable,
@@ -32,10 +33,24 @@ export type GeneratedFile = { js: string; dts: string }
  * land on distinct fingerprints. Without this, codecs that differ only by
  * a constraint collide and the ambiguity-resolution path can't tell them
  * apart by structure alone.
+ *
+ * The transform bodies (decode/encode) are folded in too: two codecs with the
+ * same wire+runtime shape but different transform logic must NOT share a
+ * fingerprint, or the ambiguity path could reference a behaviorally-wrong
+ * codec. `.toString()` discriminates transform source (a residual gap remains
+ * for identical source with different captured closure config — documented).
  */
 function fingerprintCodec(schema: $ZodType): string {
   if (!(schema instanceof $ZodCodec)) return ''
-  return `${fingerprintLeaf(schema._zod.def.in)}|${fingerprintLeaf(schema._zod.def.out)}`
+  const def = schema._zod.def as {
+    in: $ZodType
+    out: $ZodType
+    transform?: unknown
+    reverseTransform?: unknown
+  }
+  const transform = typeof def.transform === 'function' ? def.transform.toString() : ''
+  const reverse = typeof def.reverseTransform === 'function' ? def.reverseTransform.toString() : ''
+  return `${fingerprintLeaf(def.in)}|${fingerprintLeaf(def.out)}|${transform}|${reverse}`
 }
 
 function fingerprintLeaf(schema: $ZodType): string {
@@ -386,19 +401,29 @@ export function generateApiFile(
 
   // Resolve function-embedded codecs against existing codecs by structural fingerprint.
   // Factory-created codecs (like tagged(), encrypted()) produce new instances each call,
-  // so identity matching fails. Fingerprinting matches by wire+runtime schema structure,
+  // so identity matching fails. Fingerprinting matches by wire+runtime+transform,
   // allowing us to reference the model/standalone codec instead of importing the function.
   // This avoids circular imports: functions.ts → _zodvex/api.ts → functionFile.ts → functions.ts
   //
-  // Ambiguity handling: when multiple codecs share a fingerprint, we cannot
-  // pick "the right one" by insertion order — that's how the same source file
-  // produced different output on macOS vs Linux (hotpot MR 206). Instead we
-  // track all candidates, then per function-codec lookup we prefer a
-  // same-source-file candidate when one exists, otherwise we skip the reuse
-  // (the codec falls through to inline serialization).
+  // Ambiguity handling: when multiple codecs share a fingerprint they are, by the
+  // fingerprint contract, behaviorally interchangeable — so any one is a correct
+  // reference. We prefer a same-source-file candidate, otherwise we pick the
+  // stable-sorted-first so output is byte-identical across discovery orders
+  // (hotpot MR 206). We MUST NOT fall through to inline serialization: a codec
+  // inlined via zodToSource loses its transform (emits the wire schema only),
+  // which silently breaks the client encode/decode path with no build signal.
+  //
+  // Zero candidates means the codec exists only inside the function (no model
+  // twin, not exported standalone) and has no importable reference. We collect
+  // every such case and hard-error after the loop — a loud build-time failure
+  // beats silent boundary corruption.
   if (functionCodecs) {
-    type FingerprintCandidate = { ref: CodecRef; sourceFile: string | undefined }
-    const fingerprintMap = new Map<string, FingerprintCandidate[]>()
+    type Candidate = { ref: CodecRef; sourceFile: string | undefined; brand: string | undefined }
+    const fingerprintMap = new Map<string, Candidate[]>()
+    // brand → importable candidates that declared it. Brand is the author's
+    // explicit identity (see docs/decisions/2026-06-08-codec-provenance-brands.md),
+    // matched ahead of the structural fingerprint and namespaced across factories.
+    const brandMap = new Map<string, Candidate[]>()
 
     // Build a lookup from codec schema → source file when we know it. Standalone
     // exported codecs carry a sourceFile in their CodecRef; model-embedded codecs
@@ -411,56 +436,88 @@ export function generateApiFile(
       codecSchemaToSourceFile.set(mc.codec, mc.modelSourceFile)
     }
 
-    // codecMap iteration: insertion order. With sorted input collections
-    // above, this is already deterministic — but we still need ambiguity
-    // tracking so we don't silently let "last wins" pick a random candidate.
     for (const [codecSchema, ref] of codecMap) {
-      const fp = fingerprintCodec(codecSchema)
-      if (!fp) continue
       const sourceFile = codecSchemaToSourceFile.get(codecSchema)
-      const existing = fingerprintMap.get(fp)
-      if (existing) {
-        existing.push({ ref, sourceFile })
-      } else {
-        fingerprintMap.set(fp, [{ ref, sourceFile }])
+      const brand = readCodecBrand(codecSchema)
+      const candidate: Candidate = { ref, sourceFile, brand }
+      const fp = fingerprintCodec(codecSchema)
+      if (fp) {
+        const existing = fingerprintMap.get(fp)
+        if (existing) existing.push(candidate)
+        else fingerprintMap.set(fp, [candidate])
+      }
+      if (brand) {
+        const existing = brandMap.get(brand)
+        if (existing) existing.push(candidate)
+        else brandMap.set(brand, [candidate])
       }
     }
 
+    const undiscoverable: { fn: string; path: string }[] = []
+
     for (const fc of functionCodecs) {
       if (codecMap.has(fc.codec)) continue
 
-      const fp = fingerprintCodec(fc.codec)
-      const candidates = fp ? fingerprintMap.get(fp) : undefined
+      // 1. Brand match — declared identity. Collision-free and namespaced: a
+      //    branded codec resolves only against codecs that declared the same brand.
+      const brand = readCodecBrand(fc.codec)
+      let candidates: Candidate[] | undefined = brand ? brandMap.get(brand) : undefined
+
+      // 2. Fingerprint fallback — structural identity. Exclude any candidate that
+      //    declared a *different* brand (a cross-factory match would violate the
+      //    brand's intent); unbranded candidates are always eligible.
       if (!candidates || candidates.length === 0) {
-        console.warn(
-          `[zodvex] Warning: Codec in ${fc.functionExportName}() (${fc.accessPath}) has no matching model or exported codec. ` +
-            `Export it standalone for full client-side codec support.`
+        const fp = fingerprintCodec(fc.codec)
+        candidates = (fp ? fingerprintMap.get(fp) : undefined)?.filter(
+          c => c.brand === undefined || c.brand === brand
         )
+      }
+
+      if (!candidates || candidates.length === 0) {
+        undiscoverable.push({ fn: fc.functionExportName, path: fc.accessPath })
         continue
       }
 
-      let chosen: CodecRef | undefined
+      let chosen: CodecRef
       if (candidates.length === 1) {
         chosen = candidates[0].ref
       } else {
-        // Multiple candidates — pick one only if exactly one has the same
-        // source file as the function. Otherwise leave it for inline
-        // serialization so we don't gamble on insertion order.
+        // Prefer a unique same-source-file candidate; otherwise pick the
+        // stable-sorted-first. Either way we reference a real codec — never
+        // inline a transform-less husk.
         const sameFile = candidates.filter(c => c.sourceFile === fc.functionSourceFile)
         if (sameFile.length === 1) {
           chosen = sameFile[0].ref
         } else {
-          console.warn(
-            `[zodvex] Warning: Codec in ${fc.functionExportName}() (${fc.accessPath}) matches ${candidates.length} candidates with the same fingerprint ` +
-              `(${candidates.map(c => c.ref.exportName).join(', ')}). Cannot pick a canonical reference — emitting inline. ` +
-              `Export the codec standalone to disambiguate.`
+          const sorted = [...candidates].sort((a, b) =>
+            `${a.sourceFile ?? ''}|${a.ref.exportName}`.localeCompare(
+              `${b.sourceFile ?? ''}|${b.ref.exportName}`
+            )
           )
+          chosen = sorted[0].ref
+          // Branded cohorts are interchangeable by the author's explicit
+          // declaration — only flag ambiguity for inferred (unbranded) matches.
+          if (!brand) {
+            console.warn(
+              `[zodvex] Note: Codec in ${fc.functionExportName}() (${fc.accessPath}) matches ${candidates.length} fingerprint-equivalent codecs ` +
+                `(${candidates.map(c => c.ref.exportName).join(', ')}). Referencing '${chosen.exportName}'. ` +
+                `Export the codec standalone or give it a brand if you want the reference to be explicit.`
+            )
+          }
         }
       }
 
-      if (chosen) {
-        codecMap.set(fc.codec, chosen)
-      }
+      codecMap.set(fc.codec, chosen)
+    }
+
+    if (undiscoverable.length > 0) {
+      const list = undiscoverable.map(u => `  - ${u.fn}() at ${u.path}`).join('\n')
+      throw new Error(
+        `[zodvex] ${undiscoverable.length} codec(s) in function args/returns have no importable reference ` +
+          `(not exported standalone, not embedded in a model). The generated client cannot encode or decode ` +
+          `them, which silently breaks the codec boundary. Export each codec standalone (or add it to a model) ` +
+          `so codegen can import it:\n${list}`
+      )
     }
   }
 

package/src/public/mini/zx.ts

@@ -27,9 +27,10 @@ function codec<W extends $ZodType, R extends $ZodType>(
   transforms: {
     decode: (wire: any) => any
     encode: (runtime: any) => any
-  }
+  },
+  opts?: { brand?: string }
 ): ZodvexCodec<W, R> {
-  return _zx.codec(wire, runtime, transforms) as unknown as ZodvexCodec<W, R>
+  return _zx.codec(wire, runtime, transforms, opts) as unknown as ZodvexCodec<W, R>
 }
 
 /** The zx namespace typed for zod-mini compatibility. */