@atolljs/core 0.1.0 → 0.1.1

package/dist/worker/workerBootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@atolljs/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "description": "Typed shared-memory worker pools — defineWorker/connectWorker, SharedArrayBuffer contracts, cross-thread reactivity",
+  "homepage": "https://jwhenry3.github.io/atolljs/consumer/#/quickstart",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,8 +30,11 @@
     "serve:all": "node scripts/serve-all.mjs",
     "build": "tsc --noEmit && vite build",
     "test": "vitest run",
+    "stats": "node scripts/bundle-stats.mjs",
+    "stats:islands": "node scripts/island-perf.mjs",
     "build:pages": "node scripts/build-pages.mjs",
-    "assemble:pages": "node scripts/assemble-pages.mjs"
+    "assemble:pages": "node scripts/assemble-pages.mjs",
+    "serve:pages": "node scripts/serve-pages.mjs"
   },
   "devDependencies": {
     "@angular/core": "^22.2.0",
@@ -64,5 +69,12 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/jwhenry3/atolljs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bugs": {
+    "url": "https://github.com/jwhenry3/atolljs/issues"
   }
 }

package/src/contract/listSchema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from './zod';
 import type {
   ScalarKind,
   ListFieldSpec,
@@ -71,7 +71,7 @@ export function listSchema<F extends ListFields>(fields: F): z.ZodObject<ListZod
 function memberToSchema(member: ListMember): z.ZodTypeAny {
   if (member instanceof z.ZodType) {
     const bytes =
-      member.def?.type === 'string' ? (member as z.ZodString).meta()?.bytes : undefined;
+      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;
@@ -160,12 +160,12 @@ export function memberToSpec(member: ListMember, name: string): ListFieldSpec {
     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`);
   }
-  const def = member.def as ZodMemberDef;
+  const def = member._zod.def as unknown as ZodMemberDef;
   if (def.type === 'number') return numberMemberToSpec(def);
   if (def.type === 'bigint') return BIGINT_FORMATS[def.format ?? ''] ?? 'i64';
   if (def.type === 'boolean') return { bool: true };
   if (def.type === 'string') {
-    const bytes = (member as z.ZodString).meta()?.bytes;
+    const bytes = zodMetaBytes(member);
     if (typeof bytes === 'number') return { string: bytes };
     throw new TypeError(
       `member "${name}": z.string() needs .meta({ bytes: n }) — inline strings are fixed-width`
@@ -183,7 +183,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;
-  return (schema.def as { shape: ListFields }).shape;
+  return (schema._zod.def as unknown as { shape: ListFields }).shape;
 }
 
 /**
@@ -193,7 +193,7 @@ export function zodObjectShape(schema: unknown): ListFields | null {
  */
 export function zodArrayInfo(schema: unknown): { element: z.ZodTypeAny; capacity: number | null } | null {
   if (!(schema instanceof z.ZodArray)) return null;
-  const def = schema.def as ZodMemberDef & { element: z.ZodTypeAny };
+  const def = schema._zod.def as unknown as ZodMemberDef & { element: z.ZodTypeAny };
   let capacity: number | null = null;
   for (const c of def.checks ?? []) {
     const cd = checkDef(c);
@@ -203,9 +203,14 @@ 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. */
+function zodMetaBytes(schema: unknown): number | null {
+  const meta = (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. */
 export function zodStringBytes(schema: unknown): number | null {
   if (!(schema instanceof z.ZodString)) return null;
-  const bytes = schema.meta()?.bytes;
-  return typeof bytes === 'number' ? bytes : null;
+  return zodMetaBytes(schema);
 }

package/src/contract/mz.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from './zod';
 
 /**
  * Atoll zod — the fixed-width schema vocabulary. Every helper produces a

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 } from './zod';
 
 const memLog = scoped('memory');
 
@@ -768,6 +768,7 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
   private readonly connectors = new Map<string, Connector<any>>();
   private readonly boundListeners = new Set<() => void>();
   private isBound = false;
+  private boundBuffer?: SharedArrayBuffer;
 
   constructor(spec: S, options: SharedMemoryOptions = {}) {
     this.spec = spec;
@@ -818,6 +819,7 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
       });
     });
     this.isBound = true;
+    this.boundBuffer = buffer;
     for (const cb of [...this.boundListeners]) cb();
   }
 
@@ -826,6 +828,31 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
     return this.isBound;
   }
 
+  /**
+   * The buffer this contract is bound to on this thread — the raw backing
+   * store persistence adapters and snapshot tooling read/write through.
+   * Throws while unbound.
+   */
+  public get buffer(): SharedArrayBuffer {
+    if (!this.boundBuffer) {
+      throw new Error('Shared memory contract is not bound to a buffer on this thread.');
+    }
+    return this.boundBuffer;
+  }
+
+  /**
+   * Every field's address in the layout — `{ path, byteOffset, byteLength }`.
+   * Persistence adapters use this to read/write field regions directly and
+   * to pair each region with its `connector(path)._version` slot.
+   */
+  public fields(): { path: string; byteOffset: number; byteLength: number }[] {
+    return this.entries.map(({ path, descriptor }) => ({
+      path,
+      byteOffset: this.offsets.get(path)!,
+      byteLength: descriptor.byteLength,
+    }));
+  }
+
   /**
    * Fires when the contract is bound on this thread — immediately if already
    * bound. Returns an unsubscribe function.

package/src/contract/types.ts

@@ -26,6 +26,21 @@ export interface MemoryConfig {
   growthFactor?: number;
 }
 
+/**
+ * Runtime handle for a memory-persistence adapter — e.g. the Redis adapter
+ * in '@atolljs/node/redis'. The adapter mirrors the bound contract's field
+ * regions to external storage; the buffer stays the synchronous source of
+ * truth.
+ */
+export interface MemoryPersistence {
+  /** Resolves when initial state has been restored into the local buffer. */
+  readonly ready?: Promise<unknown>;
+  /** Push dirty fields now — most adapters also flush on an interval. */
+  flush?(): Promise<unknown>;
+  /** Final flush + release external resources. Invoked by pool.terminate(). */
+  stop(): void | Promise<void>;
+}
+
 export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> {
   /** Worker entry as a URL — e.g. `new URL('./worker.ts', import.meta.url)`. */
   workerUrl?: URL;
@@ -42,6 +57,12 @@ export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends T
    * skipped and workers receive a plain `{ type: 'INIT' }` handshake.
    */
   sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+  /**
+   * Persistence adapter for `sharedMemory` — invoked with the contract right
+   * after the pool binds it, and its `stop()` runs on `terminate()`.
+   * `redisMemoryAdapter(client)` from '@atolljs/node/redis' produces one.
+   */
+  persistence?: (memory: SharedMemory<S>) => MemoryPersistence | undefined;
   /** Worker count — a number, or 'auto' (the default) for navigator.hardwareConcurrency ?? 4. */
   poolSize?: number | 'auto';
   memory?: MemoryConfig;

package/src/contract/zod.ts

@@ -0,0 +1,44 @@
+/**
+ * The SDK's vendored zod surface — everything the contract layer needs,
+ * narrowed.
+ *
+ * `import { z } from 'zod'` bundles the ENTIRE classic namespace in consumer
+ * builds (~440KB minified): the `z` object can't be property-shaken, so it
+ * drags in every locale, the JSON-schema processors, and the compile
+ * pipeline. Named imports tree-shake (~93KB for the full set below).
+ *
+ * `instanceof` guards use the `$Zod*` base classes from `zod/v4/core` —
+ * classic AND mini schemas both extend them, so user-supplied schemas match
+ * either way. Constructors stay classic (`zod` named imports) because `mz`
+ * output and `memory.schemas` are documented as ordinary zod — `.meta()`,
+ * `.refine()`, `.parse()` must all work and compose with the consumer's own
+ * `z.object(...)`.
+ */
+import {
+  array, bigint, boolean, instanceof as instanceof_,
+  int32, int64, float32, float64, number, object, string, uint32, uint64,
+  unknown as unknown_,
+} from 'zod';
+import { $ZodArray, $ZodObject, $ZodString, $ZodType } from 'zod/v4/core';
+import type * as zod from 'zod';
+
+export const z = {
+  number, string, boolean, bigint, object, array,
+  instanceof: instanceof_, unknown: unknown_,
+  int32, uint32, float32, float64, int64, uint64,
+  /** Core classes — instanceof-matching for user schemas (classic or mini). */
+  ZodType: $ZodType, ZodObject: $ZodObject, ZodArray: $ZodArray, ZodString: $ZodString,
+};
+
+export namespace z {
+  /* Type surface — the classic zod types the contract layer annotates with.
+   * Value positions above are the runtime; these are the types the public
+   * signatures speak in (users pass real classic schemas). */
+  export type ZodTypeAny = zod.ZodTypeAny;
+  export type ZodType<Output = unknown, Input = unknown> = zod.ZodType<Output, Input>;
+  export type ZodString = zod.ZodString;
+  export type ZodArray<T extends zod.ZodTypeAny = zod.ZodTypeAny> = zod.ZodArray<T>;
+  export type ZodObject<S extends zod.ZodRawShape = zod.ZodRawShape> = zod.ZodObject<S>;
+  export type ZodRawShape = zod.ZodRawShape;
+  export type output<T extends zod.ZodTypeAny> = zod.output<T>;
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 /* ── Contract — shared memory declarations (both threads) ───────────────── */
 
-export { defineSharedMemory, field, getDefinedSharedMemoryCount, jsonCodec, registerConnectorFactory } from './contract/sharedMemory';
+export { bindSharedMemories, defineSharedMemory, field, getDefinedSharedMemoryCount, jsonCodec, registerConnectorFactory } from './contract/sharedMemory';
 export { mz } from './contract/mz';
 export type {
   Codec,
@@ -44,6 +44,7 @@ export type {
   TaskMap,
   TaskMessage,
   TaskResult,
+  MemoryPersistence,
   SharedWorkerConfig,
   ViewType,
   WorkerPoolConfig,

package/src/pool/workerPool.ts

@@ -1,7 +1,7 @@
 import { MemoryManager } from './memory';
 import { PoolQueueFullError, TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
 import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
-import { PoolTasks, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
 import { fmtBytes, scoped } from '../log';
 
 const poolLog = scoped('pool');
@@ -101,6 +101,8 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     runMs: agg(),
   };
   public readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+  /** The attached memory-persistence adapter, if the config supplied one. */
+  public readonly persistence: MemoryPersistence | undefined;
 
   constructor(config: WorkerPoolConfig<S, TaskMap>) {
     if (config.sharedMemory) {
@@ -125,6 +127,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       this.memoryManager = new MemoryManager(config.memory);
       this.memoryManager.ensureCapacity(this.sharedMemory.totalBytes);
       this.sharedMemory.bind(this.memoryManager.getBuffer());
+      this.persistence = config.persistence?.(config.sharedMemory);
     }
 
     const requestedSize = config.poolSize ?? 'auto';
@@ -367,6 +370,25 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     return this.dispatch(contract, args);
   }
 
+  /**
+   * The shared buffer handed to workers via INIT_MEMORY — undefined on
+   * message-only pools. Useful for passing the same buffer to auxiliaries
+   * (e.g. a second pool of HTTP workers via withSharedBuffer).
+   */
+  public get sharedBuffer(): SharedArrayBuffer | undefined {
+    return this.memoryManager?.getBuffer();
+  }
+
+  /**
+   * Live snapshot of the pool's worker slots — for auxiliary messaging that
+   * isn't task dispatch (e.g. routing accepted sockets into workers). The
+   * array is a copy; respawned workers appear on the next read. Do NOT use
+   * this to dispatch tasks — runTask/dispatch own the scheduling protocol.
+   */
+  public get workers(): readonly Worker[] {
+    return this.slots.map((s) => s.worker);
+  }
+
   /** Running aggregates — no histograms, just counts and means. */
   public stats(): PoolStats {
     return {
@@ -398,6 +420,10 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
 
   public terminate(): void {
     this.closed = true;
+    // Final flush + release — fire-and-forget; terminate() stays synchronous.
+    void this.persistence?.stop()?.catch?.((e: unknown) =>
+      poolLog.warn('memory persistence stop failed', e),
+    );
     poolLog.info(`terminating ${this.slots.length} worker(s)`);
     const crashed = new WorkerCrashedError('pool terminated');
     for (const [, entry] of this.pending) {