@atolljs/core 0.1.1 → 0.1.3

package/src/contract/listSchema.ts

@@ -1,4 +1,4 @@
-import { z } from './zod';
+import { z, fluent, type Fluent } from './zod';
 import type {
   ScalarKind,
   ListFieldSpec,
@@ -8,26 +8,30 @@ import type {
 
 const utf8 = new TextEncoder();
 
-/** Storage-bounded zod schemas per scalar kind — validation catches
+/** Storage-bounded schemas per scalar kind — validation catches
  *  out-of-range values at the contract boundary instead of silently
  *  truncating at write time. */
+const boundedInt = (min: number, max: number) =>
+  fluent(z.number().check(z.int(), z.gte(min), z.lte(max)));
+
 const SCALAR_SCHEMAS: Record<ScalarKind, z.ZodTypeAny> = {
-  i8: z.number().int().min(-128).max(127),
-  u8: z.number().int().min(0).max(255),
-  i16: z.number().int().min(-32768).max(32767),
-  u16: z.number().int().min(0).max(65535),
-  i32: z.number().int().min(-2147483648).max(2147483647),
-  u32: z.number().int().min(0).max(4294967295),
-  f32: z.number(),
-  f64: z.number(),
-  i64: z.bigint(),
-  u64: z.bigint().nonnegative(),
+  i8: boundedInt(-128, 127),
+  u8: boundedInt(0, 255),
+  i16: boundedInt(-32768, 32767),
+  u16: boundedInt(0, 65535),
+  i32: fluent(z.int32()),
+  u32: fluent(z.uint32()),
+  f32: fluent(z.number()),
+  f64: fluent(z.number()),
+  i64: fluent(z.bigint()),
+  u64: fluent(z.bigint().check(z.nonnegative())),
 };
 
 const byteBounded = (bytes: number) =>
-  z.string().refine(
-    (s) => utf8.encode(s).byteLength <= bytes,
-    `exceeds ${bytes} UTF-8 bytes`
+  fluent(
+    z.string().check(
+      z.refine((s: string) => utf8.encode(s).byteLength <= bytes, `exceeds ${bytes} UTF-8 bytes`)
+    )
   );
 
 /** Maps a list member to the zod shape whose inferred output type is
@@ -47,7 +51,7 @@ export type ListZodShape<F extends ListFields> = {
 
 /**
  * Builds a zod object schema from a member map — the shape you would pass
- * to `mz.object(...)` for `field.list({ schema, count })`. Members may be
+ * to `reef.object(...)` for `field.list({ schema, count })`. Members may be
  * spec tokens or zod schemas; the result's `z.infer` is the record type:
  *
  * ```ts
@@ -60,21 +64,35 @@ export type ListZodShape<F extends ListFields> = {
  * capacity the connector enforces; zod `z.string().meta({ bytes: n })`
  * members get the same bound attached to the declared schema.
  */
-export function listSchema<F extends ListFields>(fields: F): z.ZodObject<ListZodShape<F>> {
+export function listSchema<F extends ListFields>(fields: F): Fluent<z.ZodMiniObject<ListZodShape<F>>> {
   const shape: Record<string, z.ZodTypeAny> = {};
   for (const key of Object.keys(fields)) {
     shape[key] = memberToSchema(fields[key]);
   }
-  return z.object(shape) as unknown as z.ZodObject<ListZodShape<F>>;
+  return fluent(z.object(shape)) as unknown as Fluent<z.ZodMiniObject<ListZodShape<F>>>;
+}
+
+/** Duck-typed `$Zod*`-style detection — covers atoll-minted, classic zod,
+ *  and zod/mini schemas: they all carry `_zod.def`. */
+function isZodSchema(value: unknown): value is z.ZodTypeAny {
+  return (
+    typeof value === 'object' && value !== null &&
+    typeof (value as { _zod?: { def?: unknown } })._zod?.def === 'object'
+  );
 }
 
 function memberToSchema(member: ListMember): z.ZodTypeAny {
-  if (member instanceof z.ZodType) {
+  if (isZodSchema(member)) {
     const bytes =
       member._zod.def?.type === 'string' ? zodMetaBytes(member) : undefined;
-    return typeof bytes === 'number'
-      ? member.refine((s) => utf8.encode(s as string).byteLength <= bytes, `exceeds ${bytes} UTF-8 bytes`)
-      : member;
+    if (typeof bytes !== 'number') return member;
+    const fits = (s: unknown) => utf8.encode(s as string).byteLength <= bytes;
+    const message = `exceeds ${bytes} UTF-8 bytes`;
+    // classic + fluent-augmented members carry `.refine`; a raw mini schema
+    // takes the same check through `.check` — both keep def.type 'string'.
+    return typeof (member as { refine?: unknown }).refine === 'function'
+      ? (member as unknown as { refine: (fn: typeof fits, msg: string) => z.ZodTypeAny }).refine(fits, message)
+      : (member as unknown as { check: (c: unknown) => z.ZodTypeAny }).check(z.refine(fits, message));
   }
   return typeof member === 'string'
     ? SCALAR_SCHEMAS[member]
@@ -155,7 +173,7 @@ function numberMemberToSpec(def: ZodMemberDef): ListFieldSpec {
  */
 export function memberToSpec(member: ListMember, name: string): ListFieldSpec {
   if (typeof member === 'string') return member;
-  if (!(member instanceof z.ZodType)) {
+  if (!isZodSchema(member)) {
     if (typeof (member as { string?: unknown }).string === 'number') return member as { string: number };
     if ((member as { bool?: unknown }).bool === true) return member as { bool: true };
     throw new TypeError(`member "${name}": expected a scalar token, { string: n }, { bool: true }, or a zod schema`);
@@ -182,7 +200,7 @@ export function memberToSpec(member: ListMember, name: string): ListFieldSpec {
 
 /** The declared member map of a zod object, or null when `schema` isn't one. */
 export function zodObjectShape(schema: unknown): ListFields | null {
-  if (!(schema instanceof z.ZodObject)) return null;
+  if (!isZodSchema(schema) || schema._zod.def.type !== 'object') return null;
   return (schema._zod.def as unknown as { shape: ListFields }).shape;
 }
 
@@ -192,7 +210,7 @@ export function zodObjectShape(schema: unknown): ListFields | null {
  * schemas; `capacity` is null for unbounded arrays.
  */
 export function zodArrayInfo(schema: unknown): { element: z.ZodTypeAny; capacity: number | null } | null {
-  if (!(schema instanceof z.ZodArray)) return null;
+  if (!isZodSchema(schema) || schema._zod.def.type !== 'array') return null;
   const def = schema._zod.def as unknown as ZodMemberDef & { element: z.ZodTypeAny };
   let capacity: number | null = null;
   for (const c of def.checks ?? []) {
@@ -203,14 +221,18 @@ export function zodArrayInfo(schema: unknown): { element: z.ZodTypeAny; capacity
   return { element: def.element, capacity };
 }
 
-/** `.meta()?.bytes` — optional-call: mini schemas ($ZodString too) have no `.meta` method. */
+/** Byte budget carried in the schema's meta — atoll-minted schemas register
+ *  into the local `globalRegistry`; classic zod's `.meta()` reads its own
+ *  registry, so the `.meta?.()` call doubles as the consumer-zod channel. */
 function zodMetaBytes(schema: unknown): number | null {
-  const meta = (schema as { meta?: () => { bytes?: unknown } }).meta?.();
+  const meta =
+    (z.globalRegistry.get(schema as z.ZodTypeAny) as { bytes?: unknown } | undefined) ??
+    (schema as { meta?: () => { bytes?: unknown } }).meta?.();
   return typeof meta?.bytes === 'number' ? meta.bytes : null;
 }
 
-/** The byte budget carried by `mz.string(n)` / `z.string().meta({ bytes: n })` — null otherwise. */
+/** The byte budget carried by `reef.string(n)` / `z.string().meta({ bytes: n })` — null otherwise. */
 export function zodStringBytes(schema: unknown): number | null {
-  if (!(schema instanceof z.ZodString)) return null;
+  if (!isZodSchema(schema) || schema._zod.def.type !== 'string') return null;
   return zodMetaBytes(schema);
 }

package/src/contract/reef.ts

@@ -0,0 +1,62 @@
+import { z, fluent } from './zod';
+
+const utf8 = new TextEncoder();
+
+/**
+ * Reef — the atoll's structural barrier: the fixed-width schema
+ * vocabulary standing between your data and the raw buffer. Every helper
+ * mints a schema the layout compiler can read a byte width from: number
+ * formats (`reef.u32()`), int bounds (`reef.int(0, 3)` → u8), byte budgets
+ * (`reef.string(10)`), or flags (`reef.boolean()` → u8). There are no unfixed
+ * members — `reef.number()`/`z.date()`/`z.enum()` aren't exposed because they
+ * can't promise a width.
+ *
+ * Schemas are minted by the vendored engine in `./zod.ts` — a zod-shaped
+ * `_zod.def` surface (`type`/`format`/`checks`/`shape`/`element`), so no
+ * zod dependency ships. Width coverage: int32/uint32/float32/float64/
+ * int64/uint64 are format-tagged; reef fills the gaps (i8/u8/i16/u16 via
+ * bounded ints, which the compiler narrows identically) so all ten scalar
+ * kinds have one spelling.
+ *
+ * Composition derives byte width upward — `reef.object({...})` members lay out
+ * as a fixed record (field.object derives byteLength from it, no maxBytes),
+ * `reef.array(el).max(n)` bounds element capacity for field.array, and
+ * `reef.string(n)` carries the budget for field.string. Schemas keep the
+ * classic chain spellings — `.meta()`, `.refine()`, `.max()`/`.length()` —
+ * and consumer-supplied zod schemas introspect identically through their
+ * `_zod.def`, so `reef.object({ id: z.uint32() })` mixes freely.
+ */
+export const reef = {
+  i8: () => fluent(z.number().check(z.int(), z.gte(-128), z.lte(127))),
+  u8: () => fluent(z.number().check(z.int(), z.gte(0), z.lte(255))),
+  i16: () => fluent(z.number().check(z.int(), z.gte(-32768), z.lte(32767))),
+  u16: () => fluent(z.number().check(z.int(), z.gte(0), z.lte(65535))),
+  i32: () => fluent(z.int32()),
+  u32: () => fluent(z.uint32()),
+  f32: () => fluent(z.float32()),
+  f64: () => fluent(z.float64()),
+  i64: () => fluent(z.int64()),
+  u64: () => fluent(z.uint64()),
+  /** Bounded int — compiles to the narrowest covering kind (0..3 → u8). */
+  int: (min: number, max: number) => fluent(z.number().check(z.int(), z.gte(min), z.lte(max))),
+  /** A flag byte — reads and writes as boolean. */
+  boolean: () => fluent(z.boolean()),
+  /** Fixed-capacity inline UTF-8 string — `bytes` is the byte budget. The
+   *  schema itself refuses over-budget values, so `.parse` and connector
+   *  writes enforce the same limit. */
+  string: (bytes: number) =>
+    fluent(
+      z.string()
+        .check(
+          z.refine(
+            (s: string) => utf8.encode(s).byteLength <= bytes,
+            `exceeds ${bytes} UTF-8 bytes`
+          )
+        )
+        .register(z.globalRegistry, { bytes })
+    ),
+  /** A fixed-layout record shape — every member must be a fixed-width schema. */
+  object: <S extends z.ZodRawShape>(shape: S) => fluent(z.object(shape)),
+  /** A fixed-stride element — bound it with `.max(n)` or `.length(n)` before field.array. */
+  array: <E extends z.ZodTypeAny>(element: E) => fluent(z.array(element)),
+};

package/src/contract/sharedMemory.ts

@@ -2,7 +2,7 @@ import type { Prettify, Schema } from './types';
 import { msgpackrCodec } from './msgpackrCodec';
 import { memberToSpec, zodArrayInfo, zodObjectShape, zodStringBytes } from './listSchema';
 import { fmtBytes, scoped } from '../log';
-import { z } from './zod';
+import { z, fluent } from './zod';
 
 const memLog = scoped('memory');
 
@@ -156,7 +156,7 @@ export type ListSpec = Record<string, ListFieldSpec>;
 /**
  * A fixed-width member inside a record or element position — a binary spec
  * token (`'u32'`, `{ string: n }`, `{ bool: true }`) or a zod schema that
- * expresses the same thing (`mz.u32()`, `mz.int(0, 3)`, `mz.string(n)`).
+ * expresses the same thing (`reef.u32()`, `reef.int(0, 3)`, `reef.string(n)`).
  * Schemas are compiled to tokens for layout and kept as the field's
  * validation schema — one declaration.
  */
@@ -170,7 +170,7 @@ export interface ListDescriptor<S extends z.ZodObject<z.ZodRawShape> = z.ZodObje
   extends Omit<FieldDescriptor<ListRecord<S>[]>, 'schema'> {
   readonly kind: 'list';
   /**
-   * The declared record schema — an `mz.object` of fixed-width members. It
+   * The declared record schema — a `reef.object` of fixed-width members. It
    * IS the layout source AND the record validator (`schemas.lists.x` is this
    * same object). Note it parses one record, not the whole array.
    */
@@ -290,7 +290,7 @@ export interface FixedArrayDescriptor<T = unknown> extends FieldDescriptor<T[]>
 interface ObjectFieldFactory {
   /**
    * Inline fixed layout — the schema is a zod object of fixed-width members
-   * (`mz` helpers, `z.uint32()`, bounded ints, `mz.string(n)`, `z.boolean()`);
+   * (`reef` helpers, `z.uint32()`, bounded ints, `reef.string(n)`, `z.boolean()`);
    * `byteLength` derives from the member widths. Compile fails loudly for
    * members with no fixed width (unbounded strings, nested objects).
    */
@@ -322,9 +322,9 @@ const objectFieldImpl: ObjectFieldFactory = (options: { schema?: Schema<unknown>
 interface ArrayFieldFactory {
   /**
    * Inline fixed layout — the schema is a bounded zod array
-   * (`mz.array(mz.u32()).max(n)`, `.length(n)`); `byteLength` derives from
+   * (`reef.array(reef.u32()).max(n)`, `.length(n)`); `byteLength` derives from
    * the element width × the bound. Elements must be fixed-width members
-   * (scalars, `mz.string(n)`, booleans) — use `field.list` for record arrays.
+   * (scalars, `reef.string(n)`, booleans) — use `field.list` for record arrays.
    */
   <S extends z.ZodArray>(options: { schema: S }): FixedArrayDescriptor<S extends z.ZodArray<infer E> ? z.output<E> : unknown>;
   /** Codec-encoded blob — explicit byte budget for arbitrary payloads. */
@@ -363,7 +363,7 @@ const arrayFieldImpl: ArrayFieldFactory = (options: { schema?: Schema<unknown>;
 interface StringFieldFactory {
   /** Explicit byte budget — 4-byte length header + up to `maxBytes` of UTF-8. */
   (options: { maxBytes: number; schema?: Schema<string> }): FieldDescriptor<string>;
-  /** Budget derived from the schema — `mz.string(n)` / `z.string().meta({ bytes: n })`. */
+  /** Budget derived from the schema — `reef.string(n)` / `z.string().meta({ bytes: n })`. */
   (options: { schema: Schema<string> }): FieldDescriptor<string>;
 }
 
@@ -373,7 +373,7 @@ const stringFieldImpl: StringFieldFactory = (options: { schema?: Schema<string>;
   const bytes = schema ? zodStringBytes(schema) : null;
   if (bytes !== null) return { kind: 'string', byteLength: 4 + bytes, schema };
   throw new TypeError(
-    `field.string: pass { maxBytes } or a schema carrying a byte budget — mz.string(n) / z.string().meta({ bytes: n })`
+    `field.string: pass { maxBytes } or a schema carrying a byte budget — reef.string(n) / z.string().meta({ bytes: n })`
   );
 };
 
@@ -391,16 +391,16 @@ export const field = {
   bigInt64Array: ({ length }: { length: number }): FieldDescriptor<BigInt64Array> => ({ kind: 'BigInt64', byteLength: length * 8 }),
   uint8Array: ({ length }: { length: number }): FieldDescriptor<Uint8Array> => ({ kind: 'Uint8', byteLength: length }),
   /**
-   * A fixed-layout array of `count` records. `schema` is an `mz.object` of
-   * fixed-width members (`mz.u32()`, `mz.int(0, 3)`, `mz.string(n)`,
-   * `mz.boolean()`) — the same schema `field.object` takes, repeated `count`
+   * A fixed-layout array of `count` records. `schema` is a `reef.object` of
+   * fixed-width members (`reef.u32()`, `reef.int(0, 3)`, `reef.string(n)`,
+   * `reef.boolean()`) — the same schema `field.object` takes, repeated `count`
    * times. Every record occupies `recordSize` bytes at a computable offset:
    * reads and writes are direct memory access, no serialization.
    */
   list: <S extends z.ZodObject<z.ZodRawShape>>({ schema, count }: { schema: S; count: number }): ListDescriptor<S> => {
     const shape = zodObjectShape(schema);
     if (!shape) {
-      throw new TypeError(`field.list: schema must be an mz.object() of fixed-width members`);
+      throw new TypeError(`field.list: schema must be a reef.object() of fixed-width members`);
     }
     const { layout, offsets, recordSize } = compileListLayout(shape);
     return {
@@ -640,7 +640,7 @@ registerConnectorFactory('object', structuredFactory);
 registerConnectorFactory('array', structuredFactory);
 
 function listFactory(d: FieldDescriptor, ctx: ConnectorContext, byteOffset: number): ListConnector<any> {
-  const info = d as ListDescriptor;
+  const info = d as unknown as ListDescriptor;
   const { offsets, recordSize, count } = info;
   // `layout` is the compiled token map; `schema` stays the validation schema.
   const record = makeIO(ctx).compile(info.layout, offsets);
@@ -694,7 +694,7 @@ registerConnectorFactory('list', listFactory);
 const definedSharedMemories: SharedMemory<any>[] = [];
 
 /**
- * The zod schema for a field's logical unit: the declared `schema` for
+ * The schema for a field's logical unit: the declared `schema` for
  * object/array/list fields (for lists, the record schema), and a derived
  * scalar/typed-array schema for everything else.
  */
@@ -704,7 +704,7 @@ export type FieldSchema<D> =
     : z.ZodType<InferField<D>>;
 
 /**
- * A zod schema per field — `memory.schemas.<field>` re-exports what the spec
+ * A schema per field — `memory.schemas.<field>` re-exports what the spec
  * declared inline. Intent groups mirror their spec shape:
  * `memory.schemas.lists.incidents` is the record schema.
  */
@@ -733,14 +733,14 @@ function buildSchemas<S extends SharedSpec>(spec: S): SpecSchemas<S> {
 function fieldSchemaOf(descriptor: FieldDescriptor): Schema<unknown> {
   if (descriptor.schema) return descriptor.schema;
   switch (descriptor.kind) {
-    case 'number': return z.number();
-    case 'boolean': return z.boolean();
-    case 'string': return z.string();
-    case 'Int32': return z.instanceof(Int32Array);
-    case 'Float64': return z.instanceof(Float64Array);
-    case 'BigInt64': return z.instanceof(BigInt64Array);
-    case 'Uint8': return z.instanceof(Uint8Array);
-    default: return z.unknown();
+    case 'number': return fluent(z.number());
+    case 'boolean': return fluent(z.boolean());
+    case 'string': return fluent(z.string());
+    case 'Int32': return fluent(z.instanceof(Int32Array));
+    case 'Float64': return fluent(z.instanceof(Float64Array));
+    case 'BigInt64': return fluent(z.instanceof(BigInt64Array));
+    case 'Uint8': return fluent(z.instanceof(Uint8Array));
+    default: return fluent(z.unknown());
   }
 }
 
@@ -755,9 +755,9 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
   /** The field descriptors the contract was defined with — the inline spec. */
   public readonly spec: S;
   /**
-   * One zod schema per field, derived from the spec: declared schemas on
+   * One schema per field, derived from the spec: declared schemas on
    * object/array fields, the record schema on list fields, and derived
-   * scalar schemas (z.number(), z.string(), …) elsewhere.
+   * scalar schemas elsewhere.
    */
   public readonly schemas: SpecSchemas<S>;
   private readonly codec: Codec;