@czap/core 0.1.0

package/src/fnv.ts

@@ -0,0 +1,31 @@
+/**
+ * FNV-1a hash utility for content addressing.
+ *
+ * Shared implementation used by Boundary, Token, Style, Theme, Component,
+ * and GenFrame modules. Produces `fnv1a:XXXXXXXX` ContentAddress values.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from './brands.js';
+import { ContentAddress as mkContentAddress } from './brands.js';
+
+/** FNV-1a hash of a string, returned as a ContentAddress. */
+export function fnv1a(str: string): ContentAddress {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return mkContentAddress(`fnv1a:${(h >>> 0).toString(16).padStart(8, '0')}`);
+}
+
+/** FNV-1a hash of raw bytes, returned as a ContentAddress. */
+export function fnv1aBytes(bytes: Uint8Array): ContentAddress {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= bytes[i]!;
+    h = Math.imul(h, 0x01000193);
+  }
+  return mkContentAddress(`fnv1a:${(h >>> 0).toString(16).padStart(8, '0')}`);
+}

package/src/frame-budget.ts

@@ -0,0 +1,149 @@
+/**
+ * FrameBudget -- rAF priority lanes for frame budget management.
+ *
+ * Tracks remaining frame budget per animation frame and
+ * schedules work by priority: `critical > high > low > idle`.
+ *
+ * Hot path methods (remaining, canRun, scheduleSync) are plain JS.
+ * Effect is used only for resource lifecycle (rAF cleanup) and
+ * backwards-compatible schedule() wrapper.
+ *
+ * @module
+ */
+
+import type { Scope } from 'effect';
+import { Effect } from 'effect';
+import { DEFAULT_TARGET_FPS, MS_PER_SEC } from './defaults.js';
+
+/**
+ * Frame-budget priority lane in descending urgency. `critical` always runs;
+ * `high` / `low` / `idle` gate based on the milliseconds remaining in the
+ * current frame.
+ */
+export type Priority = 'critical' | 'high' | 'low' | 'idle';
+
+// ms budget per priority lane within a 16ms frame (critical=0 runs first, high=2ms, low=6ms, idle=12ms)
+const PRIORITY_THRESHOLDS: Record<Priority, number> = {
+  critical: 0,
+  high: 2,
+  low: 6,
+  idle: 12,
+};
+
+interface FrameBudgetShape {
+  remaining(): number;
+  canRun(priority: Priority): boolean;
+  /** Synchronous scheduler for hot paths — no Effect overhead. */
+  scheduleSync<A>(priority: Priority, task: () => A): A | null;
+  schedule<A>(priority: Priority, task: Effect.Effect<A>): Effect.Effect<A | null>;
+  readonly fps: Effect.Effect<number>;
+  /** Synchronous FPS accessor for hot paths. */
+  readonly fpsSync: number;
+}
+
+/**
+ * Creates a FrameBudget tracker tied to rAF, with priority-based scheduling.
+ * Critical tasks always run; lower priorities are deferred if budget is exhausted.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   const remaining = budget.remaining(); // ms left in this frame
+ *   const canAnimate = budget.canRun('high'); // true if enough budget
+ *   const result = yield* budget.schedule('low', Effect.succeed('done'));
+ *   // result is 'done' if budget permits, null otherwise
+ * }));
+ * ```
+ */
+function _make(config?: { targetFps?: number }): Effect.Effect<FrameBudgetShape, never, Scope.Scope> {
+  const targetFps = config?.targetFps ?? DEFAULT_TARGET_FPS;
+  if (targetFps <= 0 || !Number.isFinite(targetFps)) {
+    throw new RangeError(`FrameBudget.make: targetFps must be a positive finite number, got ${targetFps}`);
+  }
+  const frameBudgetMs = MS_PER_SEC / targetFps;
+
+  return Effect.gen(function* () {
+    let frameStart = typeof performance !== 'undefined' ? performance.now() : 0;
+    let currentFps = targetFps;
+    let lastFrameTime = typeof performance !== 'undefined' ? performance.now() : 0;
+    let frameCount = 0;
+    let fpsAccum = 0;
+
+    if (typeof requestAnimationFrame !== 'undefined') {
+      const tick = (now: number) => {
+        frameStart = now;
+        frameCount++;
+        fpsAccum += now - lastFrameTime;
+        lastFrameTime = now;
+        if (fpsAccum >= MS_PER_SEC) {
+          currentFps = Math.round((frameCount * MS_PER_SEC) / fpsAccum);
+          frameCount = 0;
+          fpsAccum %= MS_PER_SEC;
+        }
+        rafId = requestAnimationFrame(tick);
+      };
+      let rafId = requestAnimationFrame(tick);
+      yield* Effect.addFinalizer(() => Effect.sync(() => cancelAnimationFrame(rafId)));
+    }
+
+    const budget: FrameBudgetShape = {
+      remaining(): number {
+        if (typeof performance === 'undefined') return frameBudgetMs;
+        return Math.max(0, frameBudgetMs - (performance.now() - frameStart));
+      },
+
+      canRun(priority: Priority): boolean {
+        const rem = budget.remaining();
+        return rem >= PRIORITY_THRESHOLDS[priority]!;
+      },
+
+      scheduleSync<A>(priority: Priority, task: () => A): A | null {
+        if (budget.canRun(priority) || priority === 'critical') {
+          return task();
+        }
+        return null;
+      },
+
+      schedule<A>(priority: Priority, task: Effect.Effect<A>): Effect.Effect<A | null> {
+        return Effect.gen(function* () {
+          if (priority === 'critical' || budget.canRun(priority)) {
+            return yield* task;
+          }
+          return null;
+        });
+      },
+
+      fps: Effect.sync(() => currentFps),
+
+      get fpsSync(): number {
+        return currentFps;
+      },
+    };
+
+    return budget;
+  });
+}
+
+/**
+ * FrameBudget -- rAF-based frame budget manager with priority lanes.
+ * Tracks remaining time per animation frame and gates work by priority:
+ * `critical` (always runs) `> high > low > idle`.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   if (budget.canRun('high')) {
+ *     yield* budget.schedule('high', Effect.succeed('rendered'));
+ *   }
+ *   const fps = yield* budget.fps; // current measured FPS
+ * }));
+ * ```
+ */
+export const FrameBudget = { make: _make };
+
+export declare namespace FrameBudget {
+  /** Structural shape of a {@link FrameBudget} instance — `canRun`, `schedule`, `remaining`, `fps`. */
+  export type Shape = FrameBudgetShape;
+}

package/src/gen-frame.ts

@@ -0,0 +1,229 @@
+/**
+ * GenFrame -- generative UI frame scheduler.
+ *
+ * Fixed-step scheduler producing "UI frames" at configurable fps
+ * from token buffer. Each frame classified as keyframe (I-frame),
+ * delta (P-frame), or interpolated (B-frame).
+ *
+ * Integrates with FrameBudget for priority scheduling and receipt
+ * chain for disconnect-resilient generative UI state.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from './brands.js';
+import type { TokenBuffer } from './token-buffer.js';
+import { fnv1a } from './fnv.js';
+import type { UIQualityTier } from './ui-quality.js';
+
+// ---------------------------------------------------------------------------
+// UIFrame
+// ---------------------------------------------------------------------------
+
+/**
+ * Classification of a {@link UIFrame} in the generative-UI pipeline, analogous to
+ * I/P/B frames in video: `keyframe` replaces, `delta` patches, `interpolated`
+ * keeps the DOM still and animates via CSS only.
+ */
+export type FrameType = 'keyframe' | 'delta' | 'interpolated';
+
+/** How a {@link UIFrame} is applied to the DOM: full replace, patch, or CSS-only motion. */
+export type MorphStrategy = 'replace' | 'patch' | 'css-only';
+
+/**
+ * A single frame emitted by the {@link GenFrame} scheduler — the unit of work
+ * the DOM runtime consumes. Carries the drained tokens, its classification,
+ * the quality tier that produced it, and a content-addressed receipt for
+ * disconnect-resilient replay.
+ */
+export interface UIFrame {
+  readonly type: FrameType;
+  readonly tokens: readonly string[];
+  readonly qualityTier: UIQualityTier;
+  readonly morphStrategy: MorphStrategy;
+  readonly timestamp: number;
+  readonly receiptId: ContentAddress;
+  readonly bufferPosition: number;
+}
+
+// ---------------------------------------------------------------------------
+// Gap resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Recovery plan returned by {@link GenFrame.resolveGap} when a stream disconnects:
+ * resume from a buffer position, replay cached frames, request a full restart,
+ * or do nothing.
+ */
+export type GapStrategy =
+  | { readonly type: 'resume'; readonly bufferPosition: number }
+  | { readonly type: 'replay'; readonly frames: readonly UIFrame[] }
+  | { readonly type: 're-request'; readonly fromScratch: true }
+  | { readonly type: 'noop' };
+
+/** Transport-layer snapshot indicating whether the stream can resume from its last event. */
+export interface ResumptionInfo {
+  readonly canResume: boolean;
+  readonly lastEventId?: string;
+}
+
+/** Accessor bundle that exposes the receipt chain to {@link GenFrame.resolveGap}. */
+export interface ReceiptChainInfo {
+  readonly hasFramesAfter: (receiptId: ContentAddress | null) => boolean;
+  readonly getFramesAfter: (receiptId: ContentAddress | null) => readonly UIFrame[];
+}
+
+function resolveGap(
+  lastAckReceiptId: ContentAddress | null,
+  currentStreamPosition: number,
+  receiptChain: ReceiptChainInfo,
+  resumptionState: ResumptionInfo,
+): GapStrategy {
+  // 1. Can the stream resume?
+  if (resumptionState.canResume) {
+    return { type: 'resume', bufferPosition: currentStreamPosition };
+  }
+
+  // 2. Do we have cached frames in the receipt chain?
+  if (receiptChain.hasFramesAfter(lastAckReceiptId)) {
+    const frames = receiptChain.getFramesAfter(lastAckReceiptId);
+    if (frames.length > 0) {
+      return { type: 'replay', frames };
+    }
+  }
+
+  // 3. Neither available — full re-request
+  return { type: 're-request', fromScratch: true };
+}
+
+// ---------------------------------------------------------------------------
+// Frame scheduler
+// ---------------------------------------------------------------------------
+
+interface GenFrameConfig {
+  readonly fps?: number;
+  readonly tokenBuffer: TokenBuffer.Shape<string>;
+  readonly getQualityTier: () => UIQualityTier;
+}
+
+interface GenFrameSchedulerShape {
+  tick(): UIFrame | null;
+  readonly frameCount: number;
+  readonly lastFrame: UIFrame | null;
+  markKeyframe(): void;
+  reset(): void;
+}
+
+// FNV-1a for receipt IDs — delegated to shared fnv.ts (see fnv.ts)
+
+function _make(config: GenFrameConfig): GenFrameSchedulerShape {
+  const { tokenBuffer, getQualityTier } = config;
+
+  let frameCount = 0;
+  let lastFrame: UIFrame | null = null;
+  let lastQualityTier: UIQualityTier | null = null;
+  let forceKeyframe = true; // First frame is always a keyframe
+  let totalTokensDrained = 0;
+
+  return {
+    tick(): UIFrame | null {
+      const tier = getQualityTier();
+      const tokens = tokenBuffer.drain(32); // Drain up to 32 tokens per frame
+
+      // Determine frame type
+      let type: FrameType;
+      if (forceKeyframe || lastQualityTier !== tier) {
+        type = 'keyframe';
+        forceKeyframe = false;
+      } else if (tokens.length === 0) {
+        // Stall — produce interpolated frame (CSS-only, no DOM mutation)
+        if (tokenBuffer.isStalled) {
+          type = 'interpolated';
+        } else {
+          // No tokens but not stalled — skip frame
+          return null;
+        }
+      } else {
+        type = 'delta';
+      }
+
+      // Determine morph strategy
+      let morphStrategy: MorphStrategy;
+      switch (type) {
+        case 'keyframe':
+          morphStrategy = 'replace';
+          break;
+        case 'interpolated':
+          morphStrategy = 'css-only';
+          break;
+        default:
+          morphStrategy = 'patch';
+      }
+
+      totalTokensDrained += tokens.length;
+      const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+
+      // Generate receipt ID from frame content
+      const receiptId = fnv1a(`${frameCount}:${now}:${tokens.join('')}`);
+
+      const frame: UIFrame = {
+        type,
+        tokens,
+        qualityTier: tier,
+        morphStrategy,
+        timestamp: now,
+        receiptId,
+        bufferPosition: totalTokensDrained,
+      };
+
+      lastFrame = frame;
+      lastQualityTier = tier;
+      frameCount++;
+
+      return frame;
+    },
+
+    get frameCount(): number {
+      return frameCount;
+    },
+
+    get lastFrame(): UIFrame | null {
+      return lastFrame;
+    },
+
+    markKeyframe(): void {
+      forceKeyframe = true;
+    },
+
+    reset(): void {
+      frameCount = 0;
+      lastFrame = null;
+      lastQualityTier = null;
+      forceKeyframe = true;
+      totalTokensDrained = 0;
+    },
+  };
+}
+
+/**
+ * Generative-UI frame scheduler namespace.
+ *
+ * Turns a bursty LLM token stream into evenly-paced frames the DOM runtime
+ * can apply without stalling, and resolves disconnect gaps using the receipt
+ * chain or transport resumption.
+ */
+export const GenFrame = {
+  /** Create a new fixed-step scheduler bound to a {@link TokenBuffer} and quality-tier probe. */
+  make: _make,
+  /** Pick a recovery {@link GapStrategy} after a stream disconnect. */
+  resolveGap,
+};
+
+export declare namespace GenFrame {
+  /** Structural shape of a scheduler instance returned by {@link GenFrame.make}. */
+  export type Shape = GenFrameSchedulerShape;
+  /** Configuration accepted by {@link GenFrame.make}. */
+  export type Config = GenFrameConfig;
+  /** Alias for {@link UIFrame}. */
+  export type Frame = UIFrame;
+}

package/src/harness/arbitrary-from-schema.ts

@@ -0,0 +1,270 @@
+/**
+ * arbitrary-from-schema — derive a `fast-check` arbitrary from an Effect
+ * `Schema.Codec<T>`. Used by the harness templates so generated property
+ * tests feed real, schema-conformant inputs into capsule run handlers.
+ *
+ * Coverage: scalars (String, Number, Boolean, BigInt), Literal,
+ * Null/Undefined/Void, Unknown/Any, ObjectKeyword, Enum, Union, Array
+ * (Schema.Array + fixed Tuple + NonEmptyArray-style elements+rest),
+ * TypeLiteral (Struct with optional property signatures), Suspend,
+ * Declaration (Date specifically; throws for other declarations), and
+ * AST-level `checks` (Filter / FilterGroup) which model refinements
+ * such as `Schema.NonEmptyString` and `Schema.minLength(n)` — these
+ * post-filter the underlying arbitrary by running each Filter's
+ * predicate.
+ *
+ * KNOWN GAPS — these AST nodes throw `UnsupportedSchemaError` and the
+ * harness falls back to `it.skip` rather than a vacuous test:
+ *   - Transformation (Schema.transform, Schema.compose chains)
+ *   - TemplateLiteral (Schema.TemplateLiteral)
+ *   - Declaration for non-Date opaque types (e.g. Uint8Array)
+ *
+ * @module
+ */
+import { Effect } from 'effect';
+import type { Schema, SchemaAST } from 'effect';
+import * as fc from 'fast-check';
+
+/** Error thrown when an AST node has no supported arbitrary mapping. */
+export class UnsupportedSchemaError extends Error {
+  readonly _tag = 'UnsupportedSchemaError';
+  readonly nodeTag: string;
+  constructor(nodeTag: string, hint?: string) {
+    super(`arbitrary-from-schema: AST node "${nodeTag}" is not supported${hint ? ` (${hint})` : ''}`);
+    this.nodeTag = nodeTag;
+  }
+}
+
+/**
+ * Apply post-type-match `checks` (Filter / FilterGroup) declared on the
+ * AST node to the produced arbitrary. Each Filter's `run` returns
+ * `Issue | undefined`; `undefined` means the input passed. We compose all
+ * checks and `.filter` the arbitrary so only conforming samples survive.
+ *
+ * fast-check throws if the filter rejection rate exceeds ~10%. For
+ * common refinements (NonEmptyString, minLength) the underlying
+ * arbitrary already biases toward populated values so rejection stays
+ * well below the threshold.
+ */
+function _applyChecks(ast: SchemaAST.AST, arb: fc.Arbitrary<unknown>): fc.Arbitrary<unknown> {
+  const checks = ast.checks;
+  if (checks === undefined || checks.length === 0) return arb;
+  return arb.filter((sample) => {
+    for (const check of checks) {
+      if (check._tag === 'Filter') {
+        // ParseOptions is opaque — pass an empty object; the runtime
+        // tolerates missing fields for filter execution.
+        const issue = (check as SchemaAST.Filter<unknown>).run(sample, ast, {} as SchemaAST.ParseOptions);
+        if (issue !== undefined) return false;
+      } else if (check._tag === 'FilterGroup') {
+        const group = check as SchemaAST.FilterGroup<unknown>;
+        for (const inner of group.checks) {
+          if (inner._tag === 'Filter') {
+            const issue = (inner as SchemaAST.Filter<unknown>).run(sample, ast, {} as SchemaAST.ParseOptions);
+            if (issue !== undefined) return false;
+          }
+          // Nested FilterGroup is theoretically possible but rare;
+          // ignore for now and let the outer test catch failures.
+        }
+      }
+    }
+    return true;
+  });
+}
+
+/**
+ * Probe a `Declaration` node to determine the JavaScript class it accepts.
+ * We attempt to construct a sentinel value and see whether the node's
+ * `run` parser accepts it. If yes, return a fast-check arbitrary that
+ * produces values of that shape. Otherwise throw.
+ *
+ * Currently supports `Date`. Add new probes here when production
+ * capsules require them.
+ */
+function _arbitraryForDeclaration(ast: SchemaAST.Declaration): fc.Arbitrary<unknown> {
+  const parser = ast.run(ast.typeParameters);
+  // Probe with `new Date()` — the most common Declaration in production.
+  const probeDate = new Date();
+  // The parser returns an Effect; we synchronously inspect via the
+  // runtime sync path. If it succeeds, the Declaration accepts Date.
+  // We avoid pulling in the full Effect runtime here — a try/catch
+  // around the parser's first sync step is enough for the probe.
+  let acceptsDate = false;
+  try {
+    const out = parser(probeDate, ast, {} as SchemaAST.ParseOptions);
+    // The Effect returned by `out` succeeds synchronously when the
+    // input matches; failure surfaces as an Issue. We use Effect's
+    // `runSyncExit` to inspect the success/failure tag without
+    // throwing on parse failures.
+    const exit = Effect.runSyncExit(out as never);
+    acceptsDate = exit._tag === 'Success';
+  } catch {
+    acceptsDate = false;
+  }
+  if (acceptsDate) return fc.date();
+  throw new UnsupportedSchemaError('Declaration', 'opaque user-defined type — only Date is currently probed');
+}
+
+function walk(ast: SchemaAST.AST): fc.Arbitrary<unknown> {
+  let arb: fc.Arbitrary<unknown>;
+  switch (ast._tag) {
+    case 'String':
+      arb = fc.string();
+      break;
+    case 'Number':
+      // Integer is safer than float — avoids NaN/Infinity which trip
+      // most user-defined invariants. Capsules that need floats can
+      // refine via filter checks (not yet handled here).
+      arb = fc.integer();
+      break;
+    case 'Boolean':
+      arb = fc.boolean();
+      break;
+    case 'BigInt':
+      arb = fc.bigInt();
+      break;
+    case 'Literal':
+      arb = fc.constant((ast as SchemaAST.Literal).literal);
+      break;
+    case 'Null':
+      arb = fc.constant(null);
+      break;
+    case 'Undefined':
+    case 'Void':
+      arb = fc.constant(undefined);
+      break;
+    case 'Unknown':
+    case 'Any':
+      arb = fc.anything();
+      break;
+    case 'ObjectKeyword':
+      arb = fc.object();
+      break;
+    case 'Enum': {
+      const enums = (ast as SchemaAST.Enum).enums;
+      if (enums.length === 0) {
+        throw new UnsupportedSchemaError('Enum', 'empty enum');
+      }
+      arb = fc.constantFrom(...enums.map(([, v]) => v));
+      break;
+    }
+    case 'Union': {
+      const u = ast as SchemaAST.Union;
+      if (u.types.length === 0) {
+        throw new UnsupportedSchemaError('Union', 'empty union');
+      }
+      const arbs = u.types.map(walk);
+      // fc.oneof accepts an arbitraries-array as variadic args
+      arb = fc.oneof(...arbs);
+      break;
+    }
+    case 'Arrays': {
+      const a = ast as SchemaAST.Arrays;
+      // Common case: Schema.Array(T) yields elements=[], rest=[T]
+      if (a.elements.length === 0 && a.rest.length === 1) {
+        const elem = a.rest[0];
+        if (elem === undefined) {
+          throw new UnsupportedSchemaError('Arrays', 'rest[0] missing');
+        }
+        arb = fc.array(walk(elem), { maxLength: 8 });
+        break;
+      }
+      // Fixed tuple
+      if (a.rest.length === 0 && a.elements.length > 0) {
+        const elemArbs = a.elements.map(walk);
+        arb = fc.tuple(...elemArbs);
+        break;
+      }
+      // Mixed: required leading element(s) + rest tail. NonEmptyArray
+      // surfaces here as elements=[T], rest=[T] — generate the leading
+      // tuple and append a variable-length tail of the same elem type.
+      if (a.elements.length > 0 && a.rest.length === 1) {
+        const headArbs = a.elements.map(walk);
+        const tailElem = a.rest[0];
+        if (tailElem === undefined) {
+          throw new UnsupportedSchemaError('Arrays', 'rest[0] missing');
+        }
+        const tailArb = fc.array(walk(tailElem), { maxLength: 7 });
+        arb = fc.tuple(fc.tuple(...headArbs), tailArb).map(([head, tail]) => [...head, ...tail]);
+        break;
+      }
+      throw new UnsupportedSchemaError(
+        'Arrays',
+        `unsupported tuple+rest shape (elements=${a.elements.length}, rest=${a.rest.length})`,
+      );
+    }
+    case 'Objects': {
+      const o = ast as SchemaAST.Objects;
+      if (o.indexSignatures.length > 0) {
+        throw new UnsupportedSchemaError('Objects', 'index signatures');
+      }
+      const required: Record<string, fc.Arbitrary<unknown>> = {};
+      const optional: Record<string, fc.Arbitrary<unknown>> = {};
+      for (const ps of o.propertySignatures) {
+        const key = String(ps.name);
+        const fieldArb = walk(ps.type);
+        const isOptional = ps.type.context?.isOptional === true;
+        if (isOptional) optional[key] = fieldArb;
+        else required[key] = fieldArb;
+      }
+      if (Object.keys(optional).length === 0) {
+        arb = fc.record(required);
+        break;
+      }
+      // fast-check supports `requiredKeys` to mark a subset as required —
+      // but the simpler, version-stable approach is to merge all keys and
+      // post-process: for each optional key, randomly drop it.
+      const allKeys = { ...required, ...optional };
+      arb = fc.record(allKeys).chain((rec) =>
+        fc.tuple(...Object.keys(optional).map(() => fc.boolean())).map((dropFlags) => {
+          const out: Record<string, unknown> = { ...rec };
+          const optKeys = Object.keys(optional);
+          for (let i = 0; i < optKeys.length; i++) {
+            if (dropFlags[i] === true) {
+              const k = optKeys[i];
+              if (k !== undefined) delete out[k];
+            }
+          }
+          return out;
+        }),
+      );
+      break;
+    }
+    case 'Suspend': {
+      const s = ast as SchemaAST.Suspend;
+      // Resolve once; arbitrary depth control is left to fast-check defaults.
+      arb = walk(s.thunk());
+      break;
+    }
+    case 'Declaration':
+      arb = _arbitraryForDeclaration(ast as SchemaAST.Declaration);
+      break;
+    default:
+      throw new UnsupportedSchemaError(ast._tag);
+  }
+  return _applyChecks(ast, arb);
+}
+
+/**
+ * Walk a `Schema` AST and return a `fc.Arbitrary` that produces values
+ * structurally conforming to the schema. Throws
+ * {@link UnsupportedSchemaError} on AST nodes with no supported mapping.
+ *
+ * Accepts any `Schema.Schema<T>` (or `Codec`) — only `.ast` is read.
+ */
+function _schemaToArbitrary<T>(schema: Schema.Schema<T>): fc.Arbitrary<T> {
+  return walk(schema.ast) as fc.Arbitrary<T>;
+}
+
+/** Public namespace for the arbitrary-from-schema walker. */
+export const ArbitraryFromSchema = {
+  fromSchema: _schemaToArbitrary,
+} as const;
+
+/** Convenience top-level export — most call sites use this directly. */
+export const schemaToArbitrary = _schemaToArbitrary;
+
+export declare namespace ArbitraryFromSchema {
+  /** The result type returned by {@link ArbitraryFromSchema.fromSchema}. */
+  export type Result<T> = fc.Arbitrary<T>;
+}