rip-lang 3.16.0 → 3.16.2

package/src/schema/runtime-validate.js

@@ -30,11 +30,20 @@ function __schemaFormatIssues(issues, name) {
 }
 
 const __SCHEMA_RESERVED_STATIC = new Set([
-  'parse','safe','ok','find','findMany','where','all','first','count','create','toSQL',
+  'parse','array','safe','ok','parseAsync','safeAsync','okAsync','toJSONSchema',
+  'find','findMany','where','all','first','count','create','toSQL',
+  'includes','upsert','insertMany','updateAll','deleteAll','withDeleted','onlyDeleted',
+  'unscoped',
+]);
+// Names a @scope may not take: the model statics above plus the
+// builder-only chain methods — scopes install on both surfaces.
+const __SCHEMA_SCOPE_RESERVED = new Set([
+  ...__SCHEMA_RESERVED_STATIC,
+  'limit','offset','order','orderBy',
 ]);
 const __SCHEMA_RESERVED_INSTANCE = new Set([
-  'save','destroy','reload','ok','errors','toJSON','savedChanges','markDirty',
-  '_saving',
+  'save','destroy','restore','reload','ok','errors','toJSON','savedChanges','markDirty',
+  '_saving','_relMemo',
 ]);
 // Implicit columns owned by directive-driven runtime behavior. Declaring
 // them as user fields would either shadow the runtime API (savedChanges /
@@ -71,6 +80,64 @@ function __schemaCheckValue(v, typeName) {
   return check ? check(v) : true;
 }
 
+// Strict coercion tables for the `~type` marker — "coerce, then
+// validate". Deliberately narrow: `~integer` rejects "12.5" and NaN,
+// `~boolean` accepts exactly six tokens, `~date` accepts ISO-8601
+// strings and finite epoch numbers. A failed coercion is
+// {error: 'coerce'}, distinct from {error: 'type'} — the value LOOKED
+// like wire data but didn't convert, which is a different user mistake
+// than sending the wrong shape entirely.
+const __SCHEMA_COERCERS = {
+  integer(v) {
+    if (typeof v === 'number') return Number.isInteger(v) ? { ok: true, value: v } : { ok: false };
+    if (typeof v === 'string' && /^[+-]?\d+$/.test(v.trim())) return { ok: true, value: parseInt(v.trim(), 10) };
+    return { ok: false };
+  },
+  number(v) {
+    if (typeof v === 'number') return Number.isNaN(v) ? { ok: false } : { ok: true, value: v };
+    if (typeof v === 'string' && /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(v.trim())) {
+      return { ok: true, value: Number(v.trim()) };
+    }
+    return { ok: false };
+  },
+  boolean(v) {
+    if (typeof v === 'boolean') return { ok: true, value: v };
+    if (v === 'true' || v === '1' || v === 1) return { ok: true, value: true };
+    if (v === 'false' || v === '0' || v === 0) return { ok: true, value: false };
+    return { ok: false };
+  },
+  date(v) {
+    if (v instanceof Date) return Number.isNaN(v.getTime()) ? { ok: false } : { ok: true, value: v };
+    if (typeof v === 'number' && Number.isFinite(v)) return { ok: true, value: new Date(v) };
+    if (typeof v === 'string' && /^\d{4}-\d{2}-\d{2}/.test(v)) {
+      const d = new Date(v);
+      if (!Number.isNaN(d.getTime())) return { ok: true, value: d };
+    }
+    return { ok: false };
+  },
+};
+__SCHEMA_COERCERS.datetime = __SCHEMA_COERCERS.date;
+
+// Named-coercer registry for the `~:name` field syntax. A coercer is a
+// function (wireValue) → coercedValue, where null/undefined/false means
+// "didn't convert" → {error: 'coerce'}. @rip-lang/server registers its
+// entire read() validator vocabulary (id, money, ssn, phone, name,
+// date, …) here at module load, so every wire normalizer that works in
+// `read 'x', 'ssn'` also works as `x? ~:ssn` in a schema. Apps register
+// their own via schema.registerCoercer.
+//
+//   opts.raw — pass the value through un-stringified (validators that
+//   operate on arrays/objects, e.g. the server's array/hash/json).
+const __schemaNamedCoercers = new Map();
+
+function __schemaRegisterCoercer(name, fn, opts) {
+  if (typeof name !== 'string' || typeof fn !== 'function') {
+    throw new Error('schema.registerCoercer(name, fn, opts?): name string and fn required');
+  }
+  __schemaNamedCoercers.set(name, { fn, raw: opts?.raw === true });
+  return fn;
+}
+
 function __schemaValidateValue(v, typeName) {
   const prim = __schemaTypes[typeName];
   if (prim) {
@@ -85,6 +152,12 @@ function __schemaValidateValue(v, typeName) {
   if (subDef.kind === 'mixin') {
     return [{field: '', error: 'type', message: ':mixin ' + typeName + ' is not usable as a field type'}];
   }
+  if (subDef.kind === 'union') {
+    const r = subDef._unionResolve(v);
+    if (r.issue) return [r.issue];
+    const memberErrs = r.def._validateFields(v, true);
+    return memberErrs.length ? memberErrs : null;
+  }
   if (v === null || typeof v !== 'object' || Array.isArray(v)) {
     return [{field: '', error: 'type', message: 'must be a ' + typeName + ' object'}];
   }
@@ -158,6 +231,21 @@ function __schemaSnapshot(norm, inst) {
   return snap;
 }
 
+// Relation memo — caches resolved relation values per instance under
+// the accessor name. Lazily created and non-enumerable so it never
+// shows up in Object.keys / JSON.stringify. Written by the relation
+// accessors (on first resolve) and by the eager-loading preloader
+// (.includes), read by the accessors.
+function __schemaRelMemoSet(inst, acc, v) {
+  if (!inst._relMemo) {
+    Object.defineProperty(inst, '_relMemo', {
+      value: new Map(), enumerable: false, writable: false, configurable: true,
+    });
+  }
+  inst._relMemo.set(acc, v);
+  return v;
+}
+
 // SameValue-Zero: like ===, except NaN equals NaN. Used by the dirty
 // check so a persisted NaN doesn't trigger a wasted UPDATE on every
 // save. Distinguishes from Object.is by treating +0/-0 as equal, which
@@ -166,17 +254,74 @@ function __schemaSameValue(a, b) {
   return a === b || (a !== a && b !== b);
 }
 
+// Structural signature of a declaration — name-shape only, function
+// bodies excluded. Two registrations with the same signature are the
+// same declaration arriving twice (double import via symlinked paths,
+// re-eval of an unchanged module) and rebind silently. Different
+// signatures under the same name are a real collision and throw,
+// unless `__SchemaRegistry.replace` is set (dev/HMR semantics).
+function __schemaSignature(def) {
+  // Constraints may hold RegExp values; JSON.stringify would erase them
+  // to {} and miss a real difference, so stringify them explicitly.
+  const safe = (v) => JSON.stringify(v ?? null, (k, x) =>
+    x instanceof RegExp ? String(x) : (typeof x === 'function' ? '<fn>' : x));
+  const parts = [def.kind];
+  for (const e of def._desc.entries || []) {
+    switch (e.tag) {
+      case 'field':
+        parts.push('f:' + e.name + ':' + (e.typeName || '') +
+          (e.array ? '[]' : '') + ':' + (e.modifiers || []).join('') +
+          (e.literals ? ':' + e.literals.join(',') : '') +
+          ':' + safe(e.constraints) + ':' + safe(e.attrs) + (e.coerce ? ':~' + (e.coercer || '') : '') +
+          (e.transform ? ':t' : ''));
+        break;
+      case 'enum-member':
+        parts.push('e:' + e.name + '=' + String(e.value));
+        break;
+      case 'directive':
+        parts.push('d:' + e.name + ':' + safe(e.args));
+        break;
+      case 'ensure':
+        parts.push('n:' + (e.message || ''));
+        break;
+      default:
+        // method / computed / derived / hook — name identity only.
+        parts.push(e.tag + ':' + (e.name || ''));
+    }
+  }
+  return parts.join('|');
+}
+
 const __SchemaRegistry = {
   _entries: new Map(),
+  // Dev/HMR escape hatch: when true, re-registering a name rebinds
+  // unconditionally (pre-hardening "last loaded wins" semantics). Dev
+  // servers and test harnesses set it; production code should not.
+  replace: false,
   register(def) {
     // Named schemas of any kind land here. Relations look up :model,
     // @mixin Name looks up :mixin. Algebra (.extend etc.) accepts :shape
     // and derived shapes. Kind is checked at lookup time.
     if (!def.name) return;
-    // Most recent registration wins. Recompilation produces a fresh
-    // __SchemaDef with the same name; the registry rebinds. Cross-
-    // module name collisions should be avoided — schema names are
-    // app-global identifiers for relation resolution.
+    const existing = this._entries.get(def.name);
+    if (existing && existing.def !== def && !this.replace) {
+      // Identical declarations (same structural signature) rebind
+      // silently — the same module arriving twice is not a conflict.
+      // Anything else is the "two different models, one name" footgun:
+      // relation / @mixin resolution is name-keyed and app-global, so
+      // silently letting the last one win corrupts resolution. Throw.
+      if (__schemaSignature(existing.def) !== __schemaSignature(def)) {
+        throw new SchemaError(
+          [{
+            field: def.name, error: 'collision',
+            message: "schema name '" + def.name + "' is already registered with a different definition. " +
+              "Schema names are app-global (they resolve relations and @mixin references), so two different " +
+              "schemas cannot share one name. Rename one of them — or, for dev/HMR reload semantics, set " +
+              "__SchemaRegistry.replace = true before re-evaluating modules.",
+          }],
+          def.name, def.kind);
+      }
+    }
     this._entries.set(def.name, { def, kind: def.kind });
   },
   get(name) {
@@ -189,6 +334,24 @@ const __SchemaRegistry = {
   },
   has(name) { return this._entries.has(name); },
   reset() { this._entries.clear(); },
+  // Run `fn` against a fresh, empty registry; restore the parent
+  // registry afterward (success, throw, or async rejection). Replaces
+  // ad-hoc reset() in tests and makes schema-declaring test blocks
+  // safe to run without leaking registrations into each other.
+  scope(fn) {
+    const saved = this._entries;
+    this._entries = new Map();
+    const restore = () => { this._entries = saved; };
+    try {
+      const r = fn();
+      if (r && typeof r.then === 'function') return r.finally(restore);
+      restore();
+      return r;
+    } catch (e) {
+      restore();
+      throw e;
+    }
+  },
 };
 
 class __SchemaDef {
@@ -199,6 +362,25 @@ class __SchemaDef {
     this._norm = null;
     this._klass = null;
     this._sourceModel = null;
+    this._unionPlanCache = null;
+    // Per-schema adapter (`schema :model, on: analytics`). null → the
+    // process-global adapter. Resolved per ORM call by the orm fragment.
+    this._adapter = desc.adapter || null;
+    // Install @scope statics eagerly so `User.active()` works as the
+    // very first call on the model (normalization hasn't run yet at
+    // that point; the scope invocation itself triggers it, which also
+    // fires the duplicate / reserved-name collision checks). Prototype
+    // methods win on name conflicts (`in` sees the prototype chain),
+    // and normalize rejects those names anyway.
+    for (const e of desc.entries || []) {
+      if (e.tag !== 'scope' || (e.name in this)) continue;
+      const self = this;
+      const sfn = e.fn;
+      Object.defineProperty(this, e.name, {
+        enumerable: false, configurable: true,
+        value: function(...args) { return __schemaInvokeScope(self, null, sfn, args); },
+      });
+    }
   }
 
   _normalize() {
@@ -213,6 +395,8 @@ class __SchemaDef {
     const enumMembers = new Map();
     const relations = new Map();
     const ensures = [];
+    const scopes = new Map();
+    let defaultScope = null;
     let timestamps = false;
     let softDelete = false;
 
@@ -252,12 +436,15 @@ class __SchemaDef {
           fields.set(e.name, {
             name: e.name,
             required: e.modifiers.includes('!'),
-            unique: e.modifiers.includes('#'),
+            unique: e.unique === true,
             optional: e.modifiers.includes('?'),
             typeName: e.typeName,
             literals: e.literals || null,
             array: e.array === true,
+            coerce: e.coerce === true,
+            coercer: e.coercer || null,
             constraints: e.constraints || null,
+            attrs: e.attrs || null,
             transform: e.transform || null,
           });
           break;
@@ -299,8 +486,32 @@ class __SchemaDef {
         case 'ensure':
           // @ensure entries are schema-level invariants (cross-field
           // predicates). Declaration order is preserved so diagnostics
-          // come out in the order authored.
-          ensures.push({ message: e.message, fn: e.fn });
+          // come out in the order authored. `field` attributes the
+          // failure to a specific input; `async` marks an @ensure!
+          // refinement (the schema becomes async-validating).
+          ensures.push({
+            message: e.message,
+            field: e.field || '',
+            async: e.async === true,
+            fn: e.fn,
+          });
+          break;
+        case 'scope':
+          // Scopes live in the STATIC namespace (model + builder), not
+          // the instance namespace — a field `active` and a scope
+          // `:active` coexist by design. Collisions are checked against
+          // other scopes and the reserved static/builder names.
+          if (scopes.has(e.name)) collision(e.name, 'scope');
+          if (__SCHEMA_SCOPE_RESERVED.has(e.name)) collision(e.name, 'reserved query API name');
+          scopes.set(e.name, e.fn);
+          break;
+        case 'defaultScope':
+          if (defaultScope) {
+            throw new SchemaError(
+              [{field: '', error: 'collision', message: 'only one @defaultScope per model'}],
+              this.name, this.kind);
+          }
+          defaultScope = e.fn;
           break;
       }
     }
@@ -320,14 +531,98 @@ class __SchemaDef {
     const primaryKey = 'id';
     const tableName = this.kind === 'model' ? __schemaTableName(this.name) : null;
 
+    // `@tableWas old_name` — table-rename annotation for the differ.
+    let tableWas = null;
+    for (const d of directives) {
+      if (d.name === 'tableWas' && d.args?.[0]?.name) tableWas = d.args[0].name;
+    }
+
+    // :union metadata — discriminator field + constituent names.
+    let unionOn = null;
+    const unionMembers = [];
+    if (this.kind === 'union') {
+      for (const d of directives) {
+        if (d.name === 'on' && d.args?.[0]?.field) unionOn = d.args[0].field;
+      }
+      for (const e of this._desc.entries) {
+        if (e.tag === 'union-member') unionMembers.push(e.name);
+      }
+    }
+
     this._norm = {
       fields, methods, computed, derived, hooks, directives, enumMembers, relations,
-      ensures,
-      timestamps, softDelete, primaryKey, tableName,
+      ensures, scopes, defaultScope,
+      hasAsyncEnsures: ensures.some(r => r.async),
+      timestamps, softDelete, primaryKey, tableName, tableWas,
+      unionOn, unionMembers,
     };
     return this._norm;
   }
 
+  // ---- :union dispatch -------------------------------------------------------
+  //
+  // Built lazily on first parse (consistent with registry resolution):
+  // resolves every constituent from the registry, reads its declared
+  // discriminator literals, and compiles a value → constituent map for
+  // O(1) dispatch. Collisions and shapeless discriminators fail here
+  // with the constituent names in the message.
+
+  _unionPlan() {
+    if (this._unionPlanCache) return this._unionPlanCache;
+    const norm = this._normalize();
+    const disc = norm.unionOn;
+    if (this.kind !== 'union' || !disc) {
+      throw new Error("schema: '" + (this.name || 'anon') + "' is not a :union");
+    }
+    const map = new Map();
+    const members = [];
+    for (const name of norm.unionMembers) {
+      const def = __SchemaRegistry.get(name);
+      if (!def) {
+        throw new SchemaError(
+          [{field: '', error: 'union', message: 'unknown union constituent: ' + name + ' (import the file that declares it)'}],
+          this.name, this.kind);
+      }
+      members.push(def);
+      const f = def._normalize().fields.get(disc);
+      if (!f || f.typeName !== 'literal-union' || !f.literals?.length) {
+        throw new SchemaError(
+          [{field: disc, error: 'union', message: name + " must declare '" + disc +
+            "' as a string-literal type (e.g. " + disc + '! "click") to join union ' + (this.name || '')}],
+          this.name, this.kind);
+      }
+      for (const lit of f.literals) {
+        if (map.has(lit)) {
+          throw new SchemaError(
+            [{field: disc, error: 'union', message: 'duplicate discriminator value ' + JSON.stringify(lit) +
+              ' in ' + (map.get(lit).name || 'anon') + ' and ' + name}],
+            this.name, this.kind);
+        }
+        map.set(lit, def);
+      }
+    }
+    const plan = {
+      disc, map,
+      expected: [...map.keys()].join(' | '),
+      hasAsyncEnsures: members.some(d => d._normalize().hasAsyncEnsures),
+    };
+    this._unionPlanCache = plan;
+    return plan;
+  }
+
+  // Resolve a raw value to its constituent def, or produce the issue.
+  _unionResolve(data) {
+    const plan = this._unionPlan();
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+      return { issue: {field: plan.disc, error: 'union', message: 'expected an object with ' + plan.disc} };
+    }
+    const def = plan.map.get(data[plan.disc]);
+    if (!def) {
+      return { issue: {field: plan.disc, error: 'union', message: 'expected one of ' + plan.expected} };
+    }
+    return { def };
+  }
+
   // Run eager-derived entries (!>) — one pass, in declaration order.
   //
   // Invariants worth keeping in mind here:
@@ -385,14 +680,14 @@ class __SchemaDef {
         ok = !!r.fn(data);
       } catch (e) {
         errs.push({
-          field: '', error: 'ensure',
+          field: r.field || '', error: 'ensure',
           message: r.message || e?.message || 'ensure failed',
         });
         continue;
       }
       if (!ok) {
         errs.push({
-          field: '', error: 'ensure',
+          field: r.field || '', error: 'ensure',
           message: r.message || 'ensure failed',
         });
       }
@@ -400,6 +695,53 @@ class __SchemaDef {
     return errs;
   }
 
+  // Async-aware refinement pass for parseAsync/safeAsync/okAsync. Sync
+  // refinements run first (cheap before expensive); async refinements
+  // then run CONCURRENTLY (Promise.all) — preserving the no-short-
+  // circuit rule. Issues come out in declaration order regardless of
+  // completion order. A rejected async predicate counts as failure
+  // with the declared message, same as a thrown sync one.
+  async _applyEnsuresAsync(data) {
+    const norm = this._normalize();
+    if (!norm.ensures.length) return [];
+    const results = [];
+    const pending = [];
+    norm.ensures.forEach((r, idx) => {
+      const issue = () => ({
+        field: r.field || '', error: 'ensure',
+        message: r.message || 'ensure failed',
+      });
+      if (r.async) {
+        pending.push((async () => {
+          let ok = false;
+          try { ok = !!(await r.fn(data)); } catch { ok = false; }
+          if (!ok) results.push({ idx, issue: issue() });
+        })());
+      } else {
+        let ok = false;
+        try { ok = !!r.fn(data); } catch { ok = false; }
+        if (!ok) results.push({ idx, issue: issue() });
+      }
+    });
+    await Promise.all(pending);
+    results.sort((a, b) => a.idx - b.idx);
+    return results.map(r => r.issue);
+  }
+
+  // A schema with ≥1 @ensure! is async-validating: the sync entry
+  // points refuse loudly rather than sometimes-returning a promise.
+  _assertSyncValidatable(api) {
+    const async = this.kind === 'union'
+      ? this._unionPlan().hasAsyncEnsures
+      : this._normalize().hasAsyncEnsures;
+    if (async) {
+      throw new Error(
+        "schema '" + (this.name || 'anon') + "' has async refinements (@ensure!" +
+        (this.kind === 'union' ? ' in a constituent' : '') + "); " +
+        '.' + api + '() is sync. Use parseAsync!/safeAsync!/okAsync! instead.');
+    }
+  }
+
   _getClass() {
     if (this._klass) return this._klass;
     const norm = this._normalize();
@@ -447,12 +789,23 @@ class __SchemaDef {
       });
     }
 
-    // Relation methods: user.organization(). Accepts no args; returns
-    // a promise to a target-model instance (or array for has_many).
+    // Relation methods: user.organization(). Accepts an optional opts
+    // object; returns a promise to a target-model instance (or array
+    // for has_many). Results memoize per instance — the second call
+    // resolves from cache with no query, and eager loading (.includes)
+    // fills the same memo so preloaded relations are free. Pass
+    // {reload: true} to bust the memo and re-query.
     for (const [acc, rel] of norm.relations) {
       Object.defineProperty(klass.prototype, acc, {
         enumerable: false, configurable: true,
-        value: async function() { return __schemaResolveRelation(def, this, rel); },
+        value: async function(opts) {
+          if (!(opts && opts.reload === true) && this._relMemo && this._relMemo.has(acc)) {
+            return this._relMemo.get(acc);
+          }
+          const v = await __schemaResolveRelation(def, this, rel);
+          __schemaRelMemoSet(this, acc, v);
+          return v;
+        },
       });
     }
 
@@ -462,9 +815,17 @@ class __SchemaDef {
         enumerable: false, configurable: true, writable: true,
         value: async function() { return __schemaSave(def, this); },
       });
+      // destroy() honors @softDelete (UPDATE deleted_at) by default;
+      // destroy(hard: true) forces a real DELETE. Hooks fire either way.
       Object.defineProperty(klass.prototype, 'destroy', {
         enumerable: false, configurable: true, writable: true,
-        value: async function() { return __schemaDestroy(def, this); },
+        value: async function(opts) { return __schemaDestroy(def, this, opts); },
+      });
+      // restore() un-deletes a soft-deleted row (deleted_at = NULL).
+      // Throws on models without @softDelete.
+      Object.defineProperty(klass.prototype, 'restore', {
+        enumerable: false, configurable: true, writable: true,
+        value: async function() { return __schemaRestore(def, this); },
       });
       Object.defineProperty(klass.prototype, 'ok', {
         enumerable: false, configurable: true, writable: true,
@@ -582,10 +943,37 @@ class __SchemaDef {
     return inst;
   }
 
-  _validateFields(data, collect) {
+  // Coerce ISO date strings to Date for date/datetime fields. Over JSON a
+  // date is a string, so a value crossing the wire (or any `.parse` of
+  // external input) arrives as a string; this lets it validate and be stored
+  // as a Date. Runs on parse/safe only — hydrate gets canonical DB values.
+  _coerceDates(working) {
+    const norm = this._normalize();
+    // Only ISO-shaped strings (`YYYY-MM-DD` optionally followed by a time) are
+    // coerced. `new Date(v)` is otherwise lax — `new Date("5")` is a valid
+    // Date — which would let clearly-bad input slip past a date field as a
+    // bogus Date instead of failing validation. Array-of-date fields coerce
+    // element-wise.
+    const isoShaped = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(s);
+    const toDate = (s) => { const d = new Date(s); return Number.isNaN(d.getTime()) ? s : d; };
+    for (const [n, f] of norm.fields) {
+      if (f.typeName !== 'date' && f.typeName !== 'datetime') continue;
+      const v = working[n];
+      if (f.array && Array.isArray(v)) {
+        working[n] = v.map(el => isoShaped(el) ? toDate(el) : el);
+      } else if (isoShaped(v)) {
+        working[n] = toDate(v);
+      }
+    }
+  }
+
+  _validateFields(data, collect, skip) {
     const norm = this._normalize();
     const errors = collect ? [] : null;
     for (const [n, f] of norm.fields) {
+      // Fields whose coercion already failed carry a {error: 'coerce'}
+      // issue; re-checking the uncoerced value would double-report.
+      if (skip && skip.has(n)) continue;
       const v = data == null ? undefined : data[n];
       if (v === undefined || v === null) {
         if (f.required) {
@@ -687,6 +1075,54 @@ class __SchemaDef {
     return errors;
   }
 
+  // `~type` coercions — part of pipeline step 1 (obtain raw candidate):
+  // the wire value converts through the strict coercion table before
+  // defaults and validation, so range checks see the coerced value.
+  // Failed coercions collect {error: 'coerce'} issues and the field
+  // lands in `failed` so per-field validation doesn't double-report
+  // the same problem as a type error. Skipped on hydrate (rows arrive
+  // canonical), like transforms. Mutually exclusive with transforms at
+  // compile time.
+  _applyCoercions(working, failed) {
+    const norm = this._normalize();
+    const errors = [];
+    for (const [n, f] of norm.fields) {
+      if (!f.coerce) continue;
+      const v = working[n];
+      if (v === undefined || v === null) continue;
+      if (f.coercer) {
+        // `~:name` — registry lookup. A missing coercer is a CONFIG
+        // error (the package that provides it wasn't loaded), not a
+        // validation failure — fail loud.
+        const entry = __schemaNamedCoercers.get(f.coercer);
+        if (!entry) {
+          throw new Error(
+            "schema: no coercer registered for '~:" + f.coercer + "' (field '" + n + "' on " +
+            (this.name || 'anon') + "). Import '@rip-lang/validate' (browser-safe; registers the " +
+            "whole vocabulary) or register it with schema.registerCoercer('" + f.coercer + "', fn).");
+        }
+        const input = entry.raw ? v : String(v).trim();
+        let out;
+        try { out = entry.fn(input); } catch { out = null; }
+        if (out === null || out === undefined || out === false) {
+          errors.push({field: n, error: 'coerce', message: n + ' is not a valid ' + f.coercer});
+          failed.add(n);
+        } else {
+          working[n] = out;
+        }
+        continue;
+      }
+      const r = __SCHEMA_COERCERS[f.typeName] ? __SCHEMA_COERCERS[f.typeName](v) : { ok: false };
+      if (r.ok) {
+        working[n] = r.value;
+      } else {
+        errors.push({field: n, error: 'coerce', message: n + ' cannot be coerced to ' + f.typeName});
+        failed.add(n);
+      }
+    }
+    return errors;
+  }
+
   _validateEnum(data, collect) {
     const norm = this._normalize();
     for (const [n, v] of norm.enumMembers) {
@@ -727,16 +1163,27 @@ class __SchemaDef {
     if (this.kind === 'mixin') {
       throw new Error(":mixin schema '" + (this.name || 'anon') + "' is not instantiable");
     }
+    if (this.kind === 'union') {
+      const plan = this._unionPlan();
+      if (plan.hasAsyncEnsures) this._assertSyncValidatable('parse');
+      const r = this._unionResolve(data);
+      if (r.issue) throw new SchemaError([r.issue], this.name, this.kind);
+      return r.def.parse(data);
+    }
     if (this.kind === 'enum') {
       const errs = this._validateEnum(data, true);
       if (errs.length) throw new SchemaError(errs, this.name, this.kind);
       return this._materializeEnum(data);
     }
+    this._assertSyncValidatable('parse');
     const raw = data || {};
     const working = { ...raw };
+    const failed = new Set();
     const transformErrors = this._applyTransforms(raw, working);
+    const coerceErrors = this._applyCoercions(working, failed);
     this._applyDefaults(working);
-    const errs = transformErrors.concat(this._validateFields(working, true));
+    this._coerceDates(working);
+    const errs = transformErrors.concat(coerceErrors, this._validateFields(working, true, failed));
     if (errs.length) throw new SchemaError(errs, this.name, this.kind);
     // @ensure runs AFTER per-field validation so predicates can
     // assume declared fields are typed and defaulted. A field-level
@@ -749,20 +1196,93 @@ class __SchemaDef {
     return inst;
   }
 
+  // Array combinator: `Schema.array` is a list-of-this schema exposing the
+  // same validation family (parse/safe/ok + async). The common list-endpoint
+  // case is `Schema.array.parse(api.get!('x').json!())` → Out[]. A non-array
+  // input fails fast with a descriptive error naming what it got — so passing
+  // an enveloped `{ items: [...] }` whole, a typo'd key, or a changed server
+  // contract surfaces clearly at the boundary. Item failures aggregate, each
+  // issue tagged with its `[index]` so a bad element is locatable.
+  get array() {
+    const elem = this;
+    const notArray = (data) => {
+      const got = data === null ? 'null'
+        : data === undefined ? 'undefined'
+        : typeof data === 'object' ? ('an object with keys [' + Object.keys(data).join(', ') + ']')
+        : typeof data;
+      return { field: '', error: 'not_array', message: 'expected an array, received ' + got };
+    };
+    const collect = (results) => {
+      const value = [];
+      const errors = [];
+      results.forEach((r, i) => {
+        if (r.ok) value.push(r.value);
+        else for (const e of r.errors) {
+          errors.push({ ...e, field: '[' + i + ']' + (e.field ? '.' + e.field : '') });
+        }
+      });
+      return { value, errors };
+    };
+    return {
+      parse(data) {
+        if (!Array.isArray(data)) throw new SchemaError([notArray(data)], elem.name, elem.kind);
+        const { value, errors } = collect(data.map((x) => elem.safe(x)));
+        if (errors.length) throw new SchemaError(errors, elem.name, elem.kind);
+        return value;
+      },
+      safe(data) {
+        if (!Array.isArray(data)) return { ok: false, value: null, errors: [notArray(data)] };
+        const { value, errors } = collect(data.map((x) => elem.safe(x)));
+        return errors.length ? { ok: false, value: null, errors } : { ok: true, value, errors: null };
+      },
+      ok(data) {
+        return Array.isArray(data) && data.every((x) => elem.ok(x));
+      },
+      async parseAsync(data) {
+        if (!Array.isArray(data)) throw new SchemaError([notArray(data)], elem.name, elem.kind);
+        const { value, errors } = collect(await Promise.all(data.map((x) => elem.safeAsync(x))));
+        if (errors.length) throw new SchemaError(errors, elem.name, elem.kind);
+        return value;
+      },
+      async safeAsync(data) {
+        if (!Array.isArray(data)) return { ok: false, value: null, errors: [notArray(data)] };
+        const { value, errors } = collect(await Promise.all(data.map((x) => elem.safeAsync(x))));
+        return errors.length ? { ok: false, value: null, errors } : { ok: true, value, errors: null };
+      },
+      async okAsync(data) {
+        return Array.isArray(data) && (await Promise.all(data.map((x) => elem.okAsync(x)))).every(Boolean);
+      },
+      toJSONSchema() {
+        return { type: 'array', items: elem.toJSONSchema() };
+      },
+    };
+  }
+
   safe(data) {
     if (this.kind === 'mixin') {
       return {ok: false, value: null, errors: [{field: '', error: 'mixin', message: 'not instantiable'}]};
     }
+    if (this.kind === 'union') {
+      const plan = this._unionPlan();
+      if (plan.hasAsyncEnsures) this._assertSyncValidatable('safe');
+      const r = this._unionResolve(data);
+      if (r.issue) return {ok: false, value: null, errors: [r.issue]};
+      return r.def.safe(data);
+    }
     if (this.kind === 'enum') {
       const errs = this._validateEnum(data, true);
       if (errs.length) return {ok: false, value: null, errors: errs};
       return {ok: true, value: this._materializeEnum(data), errors: null};
     }
+    this._assertSyncValidatable('safe');
     const raw = data || {};
     const working = { ...raw };
+    const failed = new Set();
     const transformErrors = this._applyTransforms(raw, working);
+    const coerceErrors = this._applyCoercions(working, failed);
     this._applyDefaults(working);
-    const errs = transformErrors.concat(this._validateFields(working, true));
+    this._coerceDates(working);
+    const errs = transformErrors.concat(coerceErrors, this._validateFields(working, true, failed));
     if (errs.length) return {ok: false, value: null, errors: errs};
     const ensureErrs = this._applyEnsures(working);
     if (ensureErrs.length) return {ok: false, value: null, errors: ensureErrs};
@@ -777,17 +1297,89 @@ class __SchemaDef {
 
   ok(data) {
     if (this.kind === 'mixin') return false;
+    if (this.kind === 'union') {
+      const plan = this._unionPlan();
+      if (plan.hasAsyncEnsures) this._assertSyncValidatable('ok');
+      const r = this._unionResolve(data);
+      return r.issue ? false : r.def.ok(data);
+    }
     if (this.kind === 'enum') return this._validateEnum(data, false);
+    this._assertSyncValidatable('ok');
     const raw = data || {};
     const working = { ...raw };
+    const failed = new Set();
     const transformErrors = this._applyTransforms(raw, working);
     if (transformErrors.length) return false;
+    if (this._applyCoercions(working, failed).length) return false;
     this._applyDefaults(working);
+    this._coerceDates(working);
     if (!this._validateFields(working, false)) return false;
     // Per-field validation passed — @ensure predicates are the final gate.
     return this._applyEnsures(working).length === 0;
   }
 
+  // Async validation entry points. Work on EVERY schema (sync-only
+  // schemas just resolve immediately); REQUIRED when the schema has
+  // @ensure! refinements. The dammit operator gives the idiomatic
+  // form: `SignupInput.parseAsync! raw`.
+  async _runPipelineAsync(data) {
+    const raw = data || {};
+    const working = { ...raw };
+    const failed = new Set();
+    const transformErrors = this._applyTransforms(raw, working);
+    const coerceErrors = this._applyCoercions(working, failed);
+    this._applyDefaults(working);
+    this._coerceDates(working);
+    const errs = transformErrors.concat(coerceErrors, this._validateFields(working, true, failed));
+    if (errs.length) return { errors: errs };
+    const ensureErrs = await this._applyEnsuresAsync(working);
+    if (ensureErrs.length) return { errors: ensureErrs };
+    return { working };
+  }
+
+  async parseAsync(data) {
+    if (this.kind === 'mixin') {
+      throw new Error(":mixin schema '" + (this.name || 'anon') + "' is not instantiable");
+    }
+    if (this.kind === 'union') {
+      const r = this._unionResolve(data);
+      if (r.issue) throw new SchemaError([r.issue], this.name, this.kind);
+      return r.def.parseAsync(data);
+    }
+    if (this.kind === 'enum') return this.parse(data);
+    const r = await this._runPipelineAsync(data);
+    if (r.errors) throw new SchemaError(r.errors, this.name, this.kind);
+    const klass = this._getClass();
+    const inst = new klass(r.working, false);
+    this._applyEagerDerived(inst);
+    return inst;
+  }
+
+  async safeAsync(data) {
+    if (this.kind === 'mixin') {
+      return {ok: false, value: null, errors: [{field: '', error: 'mixin', message: 'not instantiable'}]};
+    }
+    if (this.kind === 'union') {
+      const r = this._unionResolve(data);
+      if (r.issue) return {ok: false, value: null, errors: [r.issue]};
+      return r.def.safeAsync(data);
+    }
+    if (this.kind === 'enum') return this.safe(data);
+    const r = await this._runPipelineAsync(data);
+    if (r.errors) return {ok: false, value: null, errors: r.errors};
+    const klass = this._getClass();
+    const inst = new klass(r.working, false);
+    try { this._applyEagerDerived(inst); }
+    catch (e) {
+      return {ok: false, value: null, errors: [{field: '', error: 'derived', message: e?.message || String(e)}]};
+    }
+    return {ok: true, value: inst, errors: null};
+  }
+
+  async okAsync(data) {
+    return (await this.safeAsync(data)).ok;
+  }
+
   // ---- :model static ORM methods --------------------------------------------
 
   pick(...keys) {
@@ -832,6 +1424,9 @@ class __SchemaDef {
     if (!(other instanceof __SchemaDef)) {
       throw new Error('extend(): argument must be a schema value');
     }
+    if (other.kind === 'union') {
+      throw new Error('extend(): :union schemas have no fields to merge');
+    }
     return __schemaDerive(this, (src) => {
       const merged = new Map(src);
       const otherFields = other._normalize().fields;
@@ -846,6 +1441,159 @@ class __SchemaDef {
   }
 }
 
+// ---- JSON Schema export (draft 2020-12) -------------------------------------
+//
+// One declaration → wire contract. Field types map per the table in the
+// language reference; nested registry schemas become `$ref`s collected
+// under `$defs` (cycle-safe); enums map to `enum`, unions to `oneOf` +
+// an OpenAPI-style `discriminator`. Transforms and refinements have no
+// executable JSON Schema equivalent — they export as `description`
+// annotations rather than being silently dropped or approximated.
+
+const __SCHEMA_JSON_TYPES = {
+  string:   () => ({ type: 'string' }),
+  text:     () => ({ type: 'string' }),
+  email:    () => ({ type: 'string', format: 'email' }),
+  url:      () => ({ type: 'string', format: 'uri' }),
+  uuid:     () => ({ type: 'string', format: 'uuid' }),
+  phone:    () => ({ type: 'string', pattern: '^[\\d\\s\\-+()]+$' }),
+  zip:      () => ({ type: 'string', pattern: '^\\d{5}(-\\d{4})?$' }),
+  number:   () => ({ type: 'number' }),
+  integer:  () => ({ type: 'integer' }),
+  boolean:  () => ({ type: 'boolean' }),
+  date:     () => ({ type: 'string', format: 'date' }),
+  datetime: () => ({ type: 'string', format: 'date-time' }),
+  json:     () => ({}),
+  any:      () => ({}),
+};
+
+function __schemaFieldJSONSchema(f, ctx) {
+  let s;
+  if (f.typeName === 'literal-union' && f.literals?.length) {
+    s = f.literals.length === 1 ? { const: f.literals[0] } : { enum: [...f.literals] };
+  } else if (__SCHEMA_JSON_TYPES[f.typeName]) {
+    s = __SCHEMA_JSON_TYPES[f.typeName]();
+  } else {
+    const sub = __SchemaRegistry.get(f.typeName);
+    if (sub) {
+      s = __schemaJSONSchemaRef(sub, ctx);
+    } else {
+      s = {}; // unknown identifier — permissive, matching the validator
+    }
+  }
+  const c = f.constraints;
+  if (c && !f.array) {
+    const stringish = s.type === 'string';
+    const numeric = s.type === 'number' || s.type === 'integer';
+    if (stringish) {
+      if (c.min != null) s.minLength = c.min;
+      if (c.max != null) s.maxLength = c.max;
+      if (c.regex) s.pattern = c.regex.source;
+    } else if (numeric) {
+      if (c.min != null) s.minimum = c.min;
+      if (c.max != null) s.maximum = c.max;
+    }
+  }
+  if (f.array) {
+    const items = s;
+    s = { type: 'array', items };
+    if (c) {
+      if (c.min != null) s.minItems = c.min;
+      if (c.max != null) s.maxItems = c.max;
+    }
+  }
+  if (c && c.default !== undefined) s.default = c.default;
+  if (f.coerce) {
+    s.description = ((s.description ? s.description + ' ' : '') +
+      'Coerced from wire data (' + (f.coercer ? '~:' + f.coercer : '~' + f.typeName) + ').').trim();
+  }
+  if (f.transform) {
+    s.description = ((s.description ? s.description + ' ' : '') +
+      'Derived via transform; the raw input may use different keys.').trim();
+  }
+  return s;
+}
+
+// A registry schema used as a field type / union constituent becomes a
+// `$ref` into `$defs`, expanding each named schema exactly once.
+function __schemaJSONSchemaRef(def, ctx) {
+  const name = def.name || 'Anon';
+  if (!ctx.defs.has(name) && !ctx.expanding.has(name)) {
+    ctx.expanding.add(name);
+    ctx.defs.set(name, null); // reserve slot to keep insertion order
+    ctx.defs.set(name, __schemaJSONSchemaBody(def, ctx));
+    ctx.expanding.delete(name);
+  }
+  return { $ref: '#/$defs/' + name };
+}
+
+function __schemaJSONSchemaBody(def, ctx) {
+  const norm = def._normalize();
+
+  if (def.kind === 'enum') {
+    return { enum: [...new Set(norm.enumMembers.values())] };
+  }
+
+  if (def.kind === 'union') {
+    const plan = def._unionPlan();
+    const oneOf = norm.unionMembers.map(name => {
+      const member = __SchemaRegistry.get(name);
+      return member ? __schemaJSONSchemaRef(member, ctx) : {};
+    });
+    return {
+      oneOf,
+      discriminator: { propertyName: plan.disc },
+    };
+  }
+
+  // Fielded kinds: object schema. A field is required on the wire only
+  // when it's `!`-marked AND has no default (defaults apply before the
+  // required check, so a defaulted field can never fail required).
+  const properties = {};
+  const required = [];
+  for (const [n, f] of norm.fields) {
+    properties[n] = __schemaFieldJSONSchema(f, ctx);
+    if (f.required && f.constraints?.default === undefined) required.push(n);
+  }
+  // :model wire shapes include the DB-managed columns toJSON() carries.
+  if (def.kind === 'model') {
+    properties[norm.primaryKey] = { type: 'integer' };
+    for (const [, rel] of norm.relations) {
+      if (rel.kind !== 'belongsTo') continue;
+      properties[__schemaCamel(rel.foreignKey)] = rel.optional
+        ? { type: ['integer', 'null'] }
+        : { type: 'integer' };
+    }
+    if (norm.timestamps) {
+      properties.createdAt = { type: 'string', format: 'date-time' };
+      properties.updatedAt = { type: 'string', format: 'date-time' };
+    }
+    if (norm.softDelete) {
+      properties.deletedAt = { type: ['string', 'null'], format: 'date-time' };
+    }
+  }
+  const out = { type: 'object', properties };
+  if (required.length) out.required = required;
+  if (norm.ensures.length) {
+    out.description = 'Refinements (not expressible in JSON Schema): ' +
+      norm.ensures.map(r => r.message).join('; ') + '.';
+  }
+  return out;
+}
+
+__SchemaDef.prototype.toJSONSchema = function () {
+  const ctx = { defs: new Map(), expanding: new Set() };
+  // The root schema expands inline; only REFERENCED schemas go to $defs.
+  const root = __schemaJSONSchemaBody(this, ctx);
+  root.$schema = 'https://json-schema.org/draft/2020-12/schema';
+  if (this.name) root.title = this.name;
+  if (ctx.defs.size) {
+    root.$defs = {};
+    for (const [k, v] of ctx.defs) root.$defs[k] = v;
+  }
+  return root;
+};
+
 function __schemaFlatten(keys) {
   const out = [];
   for (const k of keys) {
@@ -856,20 +1604,53 @@ function __schemaFlatten(keys) {
   return out;
 }
 
+// The full projectable column set of a schema: declared fields plus the
+// columns a :model manages implicitly — the `id` primary key, `@timestamps`
+// (createdAt/updatedAt), `@softDelete` (deletedAt), and `@belongs_to` FK
+// columns. Algebra (.pick/.omit/.partial/.required) operates over THIS set so
+// a client projection can include `id`/`createdAt` even though they aren't
+// declared fields. Non-model kinds have no implicit columns — declared only.
+function __schemaProjectableFields(def) {
+  const norm = def._normalize();
+  const out = new Map(norm.fields);
+  if (def.kind !== 'model') return out;
+  const col = (name, typeName, required) => {
+    if (!out.has(name)) out.set(name, {
+      name, required: !!required, unique: false, optional: !required,
+      typeName, literals: null, array: false, constraints: null, transform: null,
+    });
+  };
+  col(norm.primaryKey, 'integer', true);
+  if (norm.timestamps) { col('createdAt', 'datetime', true); col('updatedAt', 'datetime', true); }
+  if (norm.softDelete) col('deletedAt', 'datetime', false);
+  for (const [, rel] of norm.relations) {
+    if (rel.kind === 'belongsTo') col(__schemaCamel(rel.foreignKey), 'integer', !rel.optional);
+  }
+  return out;
+}
+
 function __schemaDerive(source, transform) {
-  const src = source._normalize().fields;
+  // Algebra on a union has no obviously-right semantics (distribute?
+  // intersect?) — deferring is honest. Derive from a constituent.
+  if (source.kind === 'union') {
+    throw new Error('schema algebra (.pick/.omit/.partial/.required/.extend) is not supported on :union — derive from a constituent schema instead');
+  }
+  const src = __schemaProjectableFields(source);
   const derivedFields = transform(src);
   const entries = [];
   for (const [, f] of derivedFields) {
     const mods = [];
     if (f.required) mods.push('!');
-    if (f.unique) mods.push('#');
     if (f.optional && !f.required) mods.push('?');
     entries.push({
       tag: 'field', name: f.name, modifiers: mods,
+      unique: f.unique === true,
       typeName: f.typeName, array: f.array,
       literals: f.literals || null,
+      coerce: f.coerce === true,
+      coercer: f.coercer || null,
       constraints: f.constraints,
+      attrs: f.attrs || null,
       transform: f.transform || null,
     });
   }
@@ -935,12 +1716,15 @@ function __schemaExpandMixins(host, fields, directives, ctx) {
       fields.set(e.name, {
         name: e.name,
         required: e.modifiers.includes('!'),
-        unique: e.modifiers.includes('#'),
+        unique: e.unique === true,
         optional: e.modifiers.includes('?'),
         typeName: e.typeName,
         literals: e.literals || null,
         array: e.array === true,
+        coerce: e.coerce === true,
+        coercer: e.coercer || null,
         constraints: e.constraints || null,
+        attrs: e.attrs || null,
         transform: e.transform || null,
       });
     }