@signaltree/schema 9.3.0

package/README.md

@@ -0,0 +1,218 @@
+# @signaltree/schema
+
+Schema-driven validation for SignalTree. StandardSchema-compatible, async-first, observe-only.
+
+```ts
+import { signalTree } from '@signaltree/core';
+import { schemas } from '@signaltree/schema';
+import { z } from 'zod';
+
+const tree = signalTree({ user: { email: '', age: 0 } }).with(
+  schemas({
+    schemas: {
+      'user.email': z.string().email(),
+      'user.age': z.number().int().min(0),
+    },
+  }),
+);
+
+tree.$.user.email.set('not-an-email');
+tree.schemas.errorsAt('user.email')(); // 'Invalid email'
+tree.schemas.isValid(); // false
+```
+
+## Why this exists
+
+- **One registry.** Register your schemas in one place; read errors per path or in aggregate. No more drift between form validation, server-action checks, and ad-hoc Zod calls.
+- **StandardSchema interop.** Works with Zod, Valibot, ArkType, Effect Schema — anything that implements [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema).
+- **Async-first.** Schemas can return Promises. The write-sequence guard drops stale verdicts when a newer write supersedes an in-flight async run.
+- **Observe-only.** The enhancer never blocks writes. Verdicts populate signals; that's it. (See [Why no reject mode](#why-no-reject-mode) below.)
+
+## What it does NOT do
+
+- **Does not block writes.** This is intentional — see [§Why no reject mode](#why-no-reject-mode).
+- **Does not duplicate `@signaltree/guardrails`.** Guardrails is about performance and anti-patterns; schema is about data-shape conformance. Different jobs.
+- **Does not yet integrate with Angular Signal Forms.** Signal Forms hasn't shipped in stable Angular yet. See [spike result](../ng-forms/spike/signal-form-bridge-spike.md). Wire `errorsAt(path)` into your template manually for now.
+
+## Install
+
+```sh
+pnpm add @signaltree/schema @signaltree/core
+# plus your schema library:
+pnpm add zod    # or valibot, arktype, etc.
+```
+
+## API
+
+### `schemas(config)`
+
+Returns an enhancer. Apply via `.with(schemas({...}))`.
+
+```ts
+interface SchemaConfig {
+  schemas: Record<SchemaPath, StandardSchemaV1>;
+  mode?: 'accept' | 'warn'; // default 'accept'
+  validateOnAttach?: boolean; // default true
+  suppressIntents?: ReadonlyArray<NonNullable<UpdateMetadata['intent']>>;
+  suppressSources?: ReadonlyArray<NonNullable<UpdateMetadata['source']>>;
+  onError?: (path: string, message: string) => void;
+  formatIssue?: (issue: StandardSchemaV1.Issue, path: string) => string;
+}
+```
+
+### `tree.schemas.*` (after `.with(schemas({...}))`)
+
+| Member | Type | Purpose |
+|---|---|---|
+| `errors` | `Signal<Record<path, string \| null>>` | Path → last-settled error message (or null) |
+| `errorList` | `Signal<readonly string[]>` | Flat list of current error messages |
+| `isValid` | `Signal<boolean>` | True iff every path's last-settled verdict is valid. **O(1) per read.** |
+| `pending` | `Signal<boolean>` | True iff any path has an in-flight async run |
+| `pendingPaths` | `Signal<readonly string[]>` | Paths with in-flight async runs |
+| `errorsAt(path)` | `Signal<string \| null>` | Memoized per-path error signal |
+| `isValidAt(path)` | `Signal<boolean>` | Memoized per-path validity |
+| `isPendingAt(path)` | `Signal<boolean>` | Memoized per-path pending state |
+| `validate()` | `Promise<boolean>` | Re-run all schemas, resolve to current `isValid()` |
+| `validatePath(path)` | `Promise<boolean>` | Re-run schemas for one path |
+| `compact()` | `void` | Manual GC — evict bound paths that no longer resolve |
+| `boundPaths` | `Signal<readonly string[]>` | All currently-bound leaf paths (reactive) |
+
+## Entity collections — register at fields, not the collection root
+
+Use wildcard schemas (`users.*.email`) to validate **individual entity fields**. Do NOT register a schema at the collection root itself (`users`):
+
+```ts
+// ✅ CORRECT — wildcard schemas validate each entity's fields
+schemas({
+  schemas: {
+    'users.*.email': z.string().email(),
+    'users.*.age': z.number().int().min(0),
+  },
+});
+
+// ❌ AVOID — registering at the collection root receives the entityMap's
+// full marker value (an object with `all`/`ids`/`entities` internals),
+// not an array of users. Your Zod array schema will fail.
+schemas({
+  schemas: {
+    users: z.array(userSchema),  // gets the entityMap value, not the user array
+  },
+});
+```
+
+Entity collections (markers like `entityMap()`) are normalized state, not arrays. They're meant to be queried via `.all()`, `.byId(id)`, `.where(...)`. Individual fields within entities are the validation surface.
+
+## Wildcard paths
+
+Use `*` segments to match entity collections:
+
+```ts
+schemas({
+  schemas: {
+    'user.email': z.string().email(),         // specific leaf
+    'users.*.email': z.string().email(),      // wildcard — every users entity
+    'orders.*.items.*.qty': z.number().int(), // nested wildcards
+    'profile': profileSchema,                 // ancestor schema (whole subtree)
+  },
+});
+```
+
+**Precedence** (D4 in the architecture plan):
+- **Specific > wildcard > ancestor.** A schema at `users.42.email` always wins over `users.*.email`, which always wins over a `users` ancestor.
+- Each leaf has exactly one owner. The owner is chosen at first-match time and cached.
+
+## Ancestor schemas
+
+A schema registered at a non-leaf path (e.g., `user`) validates the whole subtree at that path. The schema runs against a fresh snapshot every time a covered leaf is written. Issues are distributed to the leaves they reference via `issue.path`.
+
+```ts
+schemas({
+  schemas: {
+    user: z.object({
+      email: z.string().email(),
+      age: z.number().int().min(0),
+    }),
+  },
+});
+
+tree.$.user.email.set('bad');
+tree.schemas.errorsAt('user.email')(); // 'Invalid email'
+tree.schemas.errorsAt('user.age')();   // depends on current age value
+```
+
+Issues from ancestor schemas use the leaf's nearest-match path via `issueToLeafPath`. The per-leaf staleness guard ensures slow ancestor runs can't clobber faster leaf writes that happened mid-flight.
+
+## Async semantics
+
+Async schemas (Valibot, custom uniqueness checks, etc.) return Promises. Behavior:
+
+- **Pending state:** while a schema is in flight, `pending()` is true, `pendingPaths()` includes the path, `isPendingAt(path)()` is true.
+- **Last-settled verdict:** `errorsAt`, `isValid`, etc. read the **last settled** verdict — they don't flicker to null during in-flight runs.
+- **Write-sequence guard:** if a newer write happens while an older schema run is in flight, the older verdict is dropped on settle (orphaned). The promise still resolves to completion (we can't abort it); only its verdict is discarded.
+
+### Debounce `validate()` for I/O-bound schemas
+
+`validate()` called repeatedly during typing piles up orphaned network requests that all run to completion before being discarded. If your schemas hit a server, debounce the caller:
+
+```ts
+const debouncedValidate = debounce(() => tree.schemas.validate(), 300);
+```
+
+## Suppression — skip validation for replays
+
+By default, validation runs on every write — including time-travel replays, hydration, and migrations. To suppress for specific intents/sources:
+
+```ts
+schemas({
+  schemas: { ... },
+  suppressIntents: ['hydrate', 'migration'],
+  suppressSources: ['time-travel'],
+});
+```
+
+The suppression reads the ambient write-context set via `withWriteContext()` from `@signaltree/core`. Devtools time-travel and the time-travel enhancer already wrap their replays in `withWriteContext({ source: 'time-travel' })`.
+
+**Do not suppress `source: 'serialization'`** — deserialize is the canonical ingest case validation exists for.
+
+## Compaction (`compact()`)
+
+The registry's `boundPathsSet` is bounded by **distinct leaf paths ever written that matched a schema**, not by current entity count. A long-lived `users.*.email` over a session that churns 10,000 user rows will retain 10,000 `PathState` entries.
+
+Call `tree.schemas.compact()` periodically (e.g., on tab visibility change, or after entity-bulk-removal) to evict bound paths that no longer resolve in the tree.
+
+```ts
+// After removing entities:
+tree.schemas.compact();
+```
+
+## Why no reject mode
+
+Some readers reach for `mode: 'reject'`. We don't offer it. Reasons:
+
+1. **Async schemas can't gate synchronously.** A Promise-returning schema means the write has already notified subscribers before the verdict arrives. "Reject" would mean silently rolling back state subscribers already saw.
+2. **Sync schemas don't save it either.** The enhancer observes writes via `interceptLeafSignals` — *after* the underlying signal has updated. There's no pre-write hook.
+3. **It's not a validation problem.** The right place to gate input is the form layer (Signal Forms' field validators, ReactiveForms' validators). The store edge is a reporter, not a gate.
+
+If you genuinely need to refuse a write: gate it in the form, in a guardrails rule, or in a wrapper around your write site.
+
+## Bundle size
+
+~4.3 KB gzipped. Tree-shakable. Angular is a peer dependency.
+
+## Migration: `UpdateMetadata` lifted to core
+
+In v9.3, `UpdateMetadata` was lifted from `@signaltree/guardrails` to `@signaltree/core`. If you imported it from guardrails, update the import:
+
+```ts
+// Before (still works as deprecated re-export)
+import type { UpdateMetadata } from '@signaltree/guardrails';
+
+// After
+import type { UpdateMetadata } from '@signaltree/core';
+```
+
+## See also
+
+- [Architecture plan](../../docs/architecture/validation-enhancer-plan.md) — design decisions and trade-offs
+- [`@signaltree/core`](../core) — base library
+- [`@signaltree/guardrails`](../guardrails) — performance and anti-pattern detection (different concern)

package/dist/index.js

@@ -0,0 +1 @@
+export { schemas } from './lib/schema.js';

package/dist/lib/internals/aggregates.js

@@ -0,0 +1,29 @@
+import { computed } from '@angular/core';
+
+function createAggregates(registry) {
+  const isValid = computed(() => registry.invalidCount() === 0);
+  const errors = computed(() => {
+    const out = {};
+    for (const [path, state] of registry.pathStates) {
+      out[path] = state.errorSignal();
+    }
+    return out;
+  });
+  const errorList = computed(() => {
+    const map = errors();
+    const list = [];
+    for (const v of Object.values(map)) {
+      if (v !== null) list.push(v);
+    }
+    return list;
+  });
+  const pending = computed(() => registry.pendingPathsSignal().length > 0);
+  return {
+    errors,
+    errorList,
+    isValid,
+    pending
+  };
+}
+
+export { createAggregates };

package/dist/lib/internals/ancestor-handler.js

@@ -0,0 +1,111 @@
+import { ensurePathState, addPendingPath, removePendingPath } from './state.js';
+import { readTreeAtPath, collectOwnedLeaves } from './matcher.js';
+import { defaultFormatIssue, issueToLeafPath } from './issue-mapper.js';
+import { applyLeafVerdict } from './leaf-handler.js';
+
+function dispatchAncestorRun(registry, treeRoot, entry, ancestorPath) {
+  const ancestorValue = readTreeAtPath(treeRoot, ancestorPath);
+  const ownedLeaves = new Set(collectOwnedLeaves(registry, entry, ancestorPath, ancestorValue));
+  const capturedVersions = new Map();
+  for (const leaf of ownedLeaves) {
+    capturedVersions.set(leaf, ensurePathState(registry, leaf).version);
+  }
+  const runId = ++registry.nextAncestorRunId;
+  const record = {
+    runId,
+    capturedVersions,
+    ownedLeaves
+  };
+  registry.activeAncestorRuns.set(ancestorPath, record);
+  let result;
+  try {
+    result = entry.schema['~standard'].validate(ancestorValue);
+  } catch (err) {
+    applyAncestorVerdict(registry, entry, ancestorPath, ownedLeaves, capturedVersions, {
+      issues: [{
+        message: runtimeErrorMessage(err)
+      }]
+    }, true);
+    registry.activeAncestorRuns.delete(ancestorPath);
+    return;
+  }
+  if (!(result instanceof Promise)) {
+    applyAncestorVerdict(registry, entry, ancestorPath, ownedLeaves, capturedVersions, result, false);
+    registry.activeAncestorRuns.delete(ancestorPath);
+    return;
+  }
+  for (const leaf of ownedLeaves) {
+    const state = ensurePathState(registry, leaf);
+    state.pendingSignal.set(true);
+    addPendingPath(registry, leaf);
+  }
+  return result.then(settled => {
+    applyAncestorVerdict(registry, entry, ancestorPath, ownedLeaves, capturedVersions, settled, false);
+    for (const leaf of ownedLeaves) {
+      const state = ensurePathState(registry, leaf);
+      if (state.inFlightVersion === null) {
+        state.pendingSignal.set(false);
+        removePendingPath(registry, leaf);
+      }
+    }
+    if (registry.activeAncestorRuns.get(ancestorPath)?.runId === runId) {
+      registry.activeAncestorRuns.delete(ancestorPath);
+    }
+  }, err => {
+    applyAncestorVerdict(registry, entry, ancestorPath, ownedLeaves, capturedVersions, {
+      issues: [{
+        message: runtimeErrorMessage(err)
+      }]
+    }, true);
+    for (const leaf of ownedLeaves) {
+      const state = ensurePathState(registry, leaf);
+      if (state.inFlightVersion === null) {
+        state.pendingSignal.set(false);
+        removePendingPath(registry, leaf);
+      }
+    }
+    if (registry.activeAncestorRuns.get(ancestorPath)?.runId === runId) {
+      registry.activeAncestorRuns.delete(ancestorPath);
+    }
+  });
+}
+function applyAncestorVerdict(registry, _entry, ancestorPath, ownedLeaves, capturedVersions, result, fromRuntimeError) {
+  const formatIssue = registry.config.formatIssue ?? defaultFormatIssue;
+  if ('issues' in result && result.issues && result.issues.length > 0) {
+    const reported = new Set();
+    for (const issue of result.issues) {
+      const leafPath = issueToLeafPath(ancestorPath, issue);
+      if (!ownedLeaves.has(leafPath)) {
+        if (fromRuntimeError) {
+          for (const leaf of ownedLeaves) {
+            staleSafeApply(registry, leaf, capturedVersions, formatIssue(issue, leaf));
+            reported.add(leaf);
+          }
+        }
+        continue;
+      }
+      staleSafeApply(registry, leafPath, capturedVersions, formatIssue(issue, leafPath));
+      reported.add(leafPath);
+    }
+    for (const leaf of ownedLeaves) {
+      if (reported.has(leaf)) continue;
+      staleSafeApply(registry, leaf, capturedVersions, null);
+    }
+    return;
+  }
+  for (const leaf of ownedLeaves) {
+    staleSafeApply(registry, leaf, capturedVersions, null);
+  }
+}
+function staleSafeApply(registry, leafPath, capturedVersions, msg) {
+  const state = ensurePathState(registry, leafPath);
+  const captured = capturedVersions.get(leafPath);
+  if (captured === undefined) return;
+  if (state.version !== captured) return;
+  applyLeafVerdict(registry, state, leafPath, msg);
+}
+function runtimeErrorMessage(err) {
+  return `validation runtime error: ${String(err instanceof Error ? err.message : err)}`;
+}
+
+export { dispatchAncestorRun };

package/dist/lib/internals/compact.js

@@ -0,0 +1,44 @@
+import { removeBoundPath, removePendingPath } from './state.js';
+
+function compact(registry, treeRoot) {
+  const toEvict = [];
+  for (const path of registry.boundPathsSet) {
+    if (!pathExists(treeRoot, path)) {
+      toEvict.push(path);
+    }
+  }
+  for (const path of toEvict) {
+    evictPath(registry, path);
+  }
+}
+function pathExists(treeRoot, path) {
+  if (path === '') return treeRoot !== undefined && treeRoot !== null;
+  const segs = path.split('.');
+  let cur = treeRoot;
+  for (const seg of segs) {
+    if (cur === null || cur === undefined) return false;
+    if (typeof cur !== 'object' && typeof cur !== 'function') return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  return true;
+}
+function evictPath(registry, path) {
+  const state = registry.pathStates.get(path);
+  if (state) {
+    if (state.lastSettledError !== null) {
+      registry.invalidCount.update(c => c - 1);
+    }
+    state.errorSignal.set(null);
+    state.pendingSignal.set(false);
+  }
+  registry.pathStates.delete(path);
+  registry.errorsAtCache.delete(path);
+  registry.isValidAtCache.delete(path);
+  registry.isPendingAtCache.delete(path);
+  registry.leafOwner.delete(path);
+  removeBoundPath(registry, path);
+  removePendingPath(registry, path);
+}
+
+export { compact };

package/dist/lib/internals/issue-mapper.js

@@ -0,0 +1,25 @@
+function issueToLeafPath(rootPath, issue) {
+  const path = issue.path;
+  if (!path || path.length === 0) return rootPath;
+  const segs = [];
+  for (const p of path) {
+    if (typeof p === 'object' && p !== null && 'key' in p) {
+      segs.push(String(p.key));
+    } else {
+      segs.push(String(p));
+    }
+  }
+  if (segs.length === 0) return rootPath;
+  return rootPath ? `${rootPath}.${segs.join('.')}` : segs.join('.');
+}
+function defaultFormatIssue(issue) {
+  return issue.message;
+}
+function resultToMessage(result, path, formatIssue) {
+  if (!('issues' in result) || !result.issues || result.issues.length === 0) {
+    return null;
+  }
+  return formatIssue(result.issues[0], path);
+}
+
+export { defaultFormatIssue, issueToLeafPath, resultToMessage };

package/dist/lib/internals/leaf-handler.js

@@ -0,0 +1,79 @@
+import { ensurePathState, addPendingPath, removePendingPath } from './state.js';
+import { matchLeaf, matchAncestors } from './matcher.js';
+import { resultToMessage, defaultFormatIssue } from './issue-mapper.js';
+import { dispatchAncestorRun } from './ancestor-handler.js';
+
+function routeWrite(registry, treeRoot, path, next, meta) {
+  if (meta?.intent && registry.config.suppressIntents?.includes(meta.intent)) {
+    return;
+  }
+  if (meta?.source && registry.config.suppressSources?.includes(meta.source)) {
+    return;
+  }
+  if (meta?.suppressGuardrails) return;
+  const leafEntry = matchLeaf(registry, path);
+  if (leafEntry && isLeafLengthMatch(leafEntry, path)) {
+    dispatchLeafRun(registry, leafEntry, path, next);
+  }
+  for (const {
+    entry,
+    ancestorPath
+  } of matchAncestors(registry, path)) {
+    void dispatchAncestorRun(registry, treeRoot, entry, ancestorPath);
+  }
+}
+function isLeafLengthMatch(entry, leafPath) {
+  const leafLen = leafPath === '' ? 0 : leafPath.split('.').length;
+  return entry.segments.length === leafLen;
+}
+function dispatchLeafRun(registry, entry, path, next) {
+  const state = ensurePathState(registry, path);
+  const myVersion = ++state.version;
+  let result;
+  try {
+    result = entry.schema['~standard'].validate(next);
+  } catch (err) {
+    applyLeafVerdict(registry, state, path, runtimeErrorMessage(err));
+    return;
+  }
+  if (!(result instanceof Promise)) {
+    applyLeafVerdict(registry, state, path, resultToMessage(result, path, registry.config.formatIssue ?? defaultFormatIssue));
+    return;
+  }
+  state.inFlightVersion = myVersion;
+  state.pendingSignal.set(true);
+  addPendingPath(registry, path);
+  result.then(settled => {
+    if (state.inFlightVersion !== myVersion) return;
+    state.inFlightVersion = null;
+    applyLeafVerdict(registry, state, path, resultToMessage(settled, path, registry.config.formatIssue ?? defaultFormatIssue));
+    state.pendingSignal.set(false);
+    removePendingPath(registry, path);
+  }, err => {
+    if (state.inFlightVersion !== myVersion) return;
+    state.inFlightVersion = null;
+    applyLeafVerdict(registry, state, path, runtimeErrorMessage(err));
+    state.pendingSignal.set(false);
+    removePendingPath(registry, path);
+  });
+}
+function applyLeafVerdict(registry, state, path, msg) {
+  const wasInvalid = state.lastSettledError !== null;
+  const nowInvalid = msg !== null;
+  if (wasInvalid !== nowInvalid) {
+    registry.invalidCount.update(c => c + (nowInvalid ? 1 : -1));
+  }
+  state.lastSettledError = msg;
+  state.errorSignal.set(msg);
+  if (msg && registry.config.mode === 'warn') {
+    (registry.config.onError ?? defaultWarn)(path, msg);
+  }
+}
+function runtimeErrorMessage(err) {
+  return `validation runtime error: ${String(err instanceof Error ? err.message : err)}`;
+}
+function defaultWarn(path, message) {
+  console.warn(`[validation] ${path}: ${message}`);
+}
+
+export { applyLeafVerdict, dispatchLeafRun, routeWrite };

package/dist/lib/internals/matcher.js

@@ -0,0 +1,141 @@
+import { isSignal } from '@angular/core';
+import { WILDCARD, addBoundPath } from './state.js';
+
+function compilePattern(pattern) {
+  return pattern.split('.').map(seg => seg === '*' ? WILDCARD : seg);
+}
+function matchSpecificity(pattern, segs) {
+  if (pattern.length > segs.length) return -1;
+  let literalCount = 0;
+  for (let i = 0; i < pattern.length; i++) {
+    const ps = pattern[i];
+    if (ps === WILDCARD) continue;
+    if (ps !== segs[i]) return -1;
+    literalCount++;
+  }
+  const exactLength = pattern.length === segs.length;
+  return literalCount * 2 + (exactLength ? 10_000 : 0);
+}
+function isStrictPrefixMatch(pattern, segs) {
+  if (pattern.length >= segs.length) return false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ps = pattern[i];
+    if (ps === WILDCARD) continue;
+    if (ps !== segs[i]) return false;
+  }
+  return true;
+}
+function matchLeaf(registry, leafPath) {
+  const cached = registry.leafOwner.get(leafPath);
+  if (cached) return cached;
+  const segs = leafPath.split('.');
+  let best;
+  let bestScore = -1;
+  for (const entry of registry.entries) {
+    const score = matchSpecificity(entry.segments, segs);
+    if (score > bestScore) {
+      best = entry;
+      bestScore = score;
+    }
+  }
+  if (best) {
+    registry.leafOwner.set(leafPath, best);
+    addBoundPath(registry, leafPath);
+  }
+  return best;
+}
+function matchAncestors(registry, leafPath) {
+  const segs = leafPath.split('.');
+  const matches = [];
+  for (const entry of registry.entries) {
+    if (!isStrictPrefixMatch(entry.segments, segs)) continue;
+    const ancestorPath = segs.slice(0, entry.segments.length).join('.');
+    matches.push({
+      entry,
+      ancestorPath
+    });
+  }
+  return matches;
+}
+function enumerateLeafPaths(value, rootPath) {
+  const out = [];
+  walk(value, rootPath, out);
+  return out;
+}
+function walk(value, prefix, out) {
+  if (value === null || value === undefined) {
+    out.push(prefix);
+    return;
+  }
+  if (typeof value !== 'object') {
+    out.push(prefix);
+    return;
+  }
+  if (Array.isArray(value) || value instanceof Date || value instanceof Map || value instanceof Set) {
+    out.push(prefix);
+    return;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) {
+    out.push(prefix);
+    return;
+  }
+  for (const k of keys) {
+    const child = value[k];
+    walk(child, prefix ? `${prefix}.${k}` : k, out);
+  }
+}
+function isLeafSignal(value) {
+  if (typeof value !== 'function') return false;
+  if (!isSignal(value)) return false;
+  const v = value;
+  return typeof v.set === 'function' && typeof v.update === 'function';
+}
+function snapshotTreeNode(node) {
+  if (node === null || node === undefined) return node;
+  if (isLeafSignal(node)) {
+    try {
+      return node();
+    } catch {
+      return undefined;
+    }
+  }
+  if (typeof node !== 'object' && typeof node !== 'function') return node;
+  if (Array.isArray(node) || node instanceof Date || node instanceof Map || node instanceof Set) {
+    return node;
+  }
+  const out = {};
+  let keys;
+  try {
+    keys = Object.keys(node);
+  } catch {
+    return node;
+  }
+  for (const key of keys) {
+    const child = node[key];
+    out[key] = snapshotTreeNode(child);
+  }
+  return out;
+}
+function readTreeAtPath(treeRoot, path) {
+  if (path === '') return snapshotTreeNode(treeRoot);
+  const segs = path.split('.');
+  let cur = treeRoot;
+  for (const seg of segs) {
+    if (cur === null || cur === undefined) return undefined;
+    if (typeof cur !== 'object' && typeof cur !== 'function') return undefined;
+    cur = cur[seg];
+  }
+  return snapshotTreeNode(cur);
+}
+function collectOwnedLeaves(registry, ancestorEntry, ancestorPath, ancestorValue) {
+  const allLeaves = enumerateLeafPaths(ancestorValue, ancestorPath);
+  const owned = [];
+  for (const leaf of allLeaves) {
+    const owner = matchLeaf(registry, leaf);
+    if (owner === ancestorEntry) owned.push(leaf);
+  }
+  return owned;
+}
+
+export { collectOwnedLeaves, compilePattern, enumerateLeafPaths, matchAncestors, matchLeaf, matchSpecificity, readTreeAtPath, snapshotTreeNode };

package/dist/lib/internals/signal-cache.js

@@ -0,0 +1,26 @@
+import { computed } from '@angular/core';
+import { ensurePathState } from './state.js';
+
+function errorsAt(registry, path) {
+  const cached = registry.errorsAtCache.get(path);
+  if (cached) return cached;
+  const sig = computed(() => ensurePathState(registry, path).errorSignal());
+  registry.errorsAtCache.set(path, sig);
+  return sig;
+}
+function isValidAt(registry, path) {
+  const cached = registry.isValidAtCache.get(path);
+  if (cached) return cached;
+  const sig = computed(() => ensurePathState(registry, path).errorSignal() === null);
+  registry.isValidAtCache.set(path, sig);
+  return sig;
+}
+function isPendingAt(registry, path) {
+  const cached = registry.isPendingAtCache.get(path);
+  if (cached) return cached;
+  const sig = computed(() => ensurePathState(registry, path).pendingSignal());
+  registry.isPendingAtCache.set(path, sig);
+  return sig;
+}
+
+export { errorsAt, isPendingAt, isValidAt };

package/dist/lib/internals/state.js

@@ -0,0 +1,42 @@
+import { signal } from '@angular/core';
+
+const WILDCARD = Symbol('validation/wildcard');
+function createPathState() {
+  return {
+    version: 0,
+    lastSettledError: null,
+    inFlightVersion: null,
+    errorSignal: signal(null),
+    pendingSignal: signal(false)
+  };
+}
+function ensurePathState(registry, path) {
+  let state = registry.pathStates.get(path);
+  if (!state) {
+    state = createPathState();
+    registry.pathStates.set(path, state);
+  }
+  return state;
+}
+function addBoundPath(registry, path) {
+  if (registry.boundPathsSet.has(path)) return;
+  registry.boundPathsSet.add(path);
+  registry.boundPathsSignal.set(Array.from(registry.boundPathsSet));
+}
+function removeBoundPath(registry, path) {
+  if (!registry.boundPathsSet.has(path)) return;
+  registry.boundPathsSet.delete(path);
+  registry.boundPathsSignal.set(Array.from(registry.boundPathsSet));
+}
+function addPendingPath(registry, path) {
+  if (registry.pendingPathsSet.has(path)) return;
+  registry.pendingPathsSet.add(path);
+  registry.pendingPathsSignal.set(Array.from(registry.pendingPathsSet));
+}
+function removePendingPath(registry, path) {
+  if (!registry.pendingPathsSet.has(path)) return;
+  registry.pendingPathsSet.delete(path);
+  registry.pendingPathsSignal.set(Array.from(registry.pendingPathsSet));
+}
+
+export { WILDCARD, addBoundPath, addPendingPath, createPathState, ensurePathState, removeBoundPath, removePendingPath };

package/dist/lib/schema.js

@@ -0,0 +1,199 @@
+import { signal } from '@angular/core';
+import { interceptLeafSignals } from '@signaltree/core';
+import { WILDCARD, ensurePathState, addPendingPath, removePendingPath } from './internals/state.js';
+import { compilePattern, readTreeAtPath, enumerateLeafPaths, matchLeaf, matchAncestors } from './internals/matcher.js';
+import { routeWrite, dispatchLeafRun, applyLeafVerdict } from './internals/leaf-handler.js';
+import { dispatchAncestorRun } from './internals/ancestor-handler.js';
+import { isPendingAt, isValidAt, errorsAt } from './internals/signal-cache.js';
+import { createAggregates } from './internals/aggregates.js';
+import { compact } from './internals/compact.js';
+import { defaultFormatIssue, resultToMessage } from './internals/issue-mapper.js';
+
+function schemas(config) {
+  return function (tree) {
+    const entries = compileEntries(config);
+    const registry = {
+      entries,
+      leafOwner: new Map(),
+      pathStates: new Map(),
+      errorsAtCache: new Map(),
+      isValidAtCache: new Map(),
+      isPendingAtCache: new Map(),
+      invalidCount: signal(0),
+      activeAncestorRuns: new Map(),
+      nextAncestorRunId: 0,
+      pendingPathsSignal: signal([]),
+      boundPathsSignal: signal([]),
+      boundPathsSet: new Set(),
+      pendingPathsSet: new Set(),
+      config
+    };
+    const aggregates = createAggregates(registry);
+    const treeRoot = tree.$;
+    const restoreInterceptor = interceptLeafSignals(treeRoot, (path, next, _prev, meta) => {
+      routeWrite(registry, treeRoot, path, next, meta);
+    });
+    if (config.validateOnAttach !== false) {
+      initialValidation(registry, treeRoot);
+    }
+    const originalDestroy = tree.destroy?.bind(tree);
+    tree.destroy = () => {
+      restoreInterceptor();
+      if (originalDestroy) originalDestroy();
+    };
+    const methods = {
+      errors: aggregates.errors,
+      errorList: aggregates.errorList,
+      isValid: aggregates.isValid,
+      pending: aggregates.pending,
+      pendingPaths: registry.pendingPathsSignal,
+      errorsAt: path => errorsAt(registry, path),
+      isValidAt: path => isValidAt(registry, path),
+      isPendingAt: path => isPendingAt(registry, path),
+      validate: () => validateAll(registry, treeRoot),
+      validatePath: path => validateOnePath(registry, treeRoot, path),
+      compact: () => compact(registry, treeRoot),
+      schemaFor: leafPath => {
+        const owner = matchLeaf(registry, leafPath);
+        return owner?.schema;
+      },
+      boundPaths: registry.boundPathsSignal
+    };
+    tree['schemas'] = methods;
+    return tree;
+  };
+}
+function compileEntries(config) {
+  const entries = [];
+  for (const [pattern, schema] of Object.entries(config.schemas)) {
+    const segments = compilePattern(pattern);
+    entries.push({
+      pattern,
+      schema,
+      isWildcard: segments.includes(WILDCARD),
+      isAncestor: false,
+      segments
+    });
+  }
+  return entries;
+}
+function initialValidation(registry, treeRoot) {
+  const rootValue = readTreeAtPath(treeRoot, '');
+  const allLeaves = enumerateLeafPaths(rootValue, '');
+  const ancestorPathsToRun = new Set();
+  for (const leafPath of allLeaves) {
+    const owner = matchLeaf(registry, leafPath);
+    if (!owner) continue;
+    const leafLen = leafPath === '' ? 0 : leafPath.split('.').length;
+    if (owner.segments.length === leafLen) {
+      const value = readTreeAtPath(treeRoot, leafPath);
+      dispatchLeafRun(registry, owner, leafPath, value);
+    }
+    for (const {
+      entry,
+      ancestorPath
+    } of matchAncestors(registry, leafPath)) {
+      ancestorPathsToRun.add(`${entry.pattern}::${ancestorPath}`);
+      _scheduleAncestorRun(registry, treeRoot, entry, ancestorPath);
+    }
+  }
+}
+const _ancestorScheduled = new WeakMap();
+function _scheduleAncestorRun(registry, treeRoot, entry, ancestorPath, _dedupHint) {
+  let scheduled = _ancestorScheduled.get(registry);
+  if (!scheduled) {
+    scheduled = new Set();
+    _ancestorScheduled.set(registry, scheduled);
+  }
+  const key = `${entry.pattern}::${ancestorPath}`;
+  if (scheduled.has(key)) return;
+  scheduled.add(key);
+  void dispatchAncestorRun(registry, treeRoot, entry, ancestorPath);
+}
+async function validateAll(registry, treeRoot) {
+  const promises = [];
+  for (const entry of registry.entries) {
+    if (entry.isWildcard) {
+      for (const path of registry.boundPathsSet) {
+        const owner = matchLeaf(registry, path);
+        if (owner === entry) {
+          promises.push(runOnePathForEntry(registry, treeRoot, entry, path));
+        }
+      }
+      continue;
+    }
+    entry.segments.length;
+    const literalPath = entry.segments.join('.');
+    promises.push(runOneLiteralEntry(registry, treeRoot, entry, literalPath));
+  }
+  await Promise.all(promises);
+  return registry.invalidCount() === 0;
+}
+async function runOnePathForEntry(registry, treeRoot, entry, leafPath) {
+  const leafLen = leafPath === '' ? 0 : leafPath.split('.').length;
+  if (entry.segments.length === leafLen) {
+    const value = readTreeAtPath(treeRoot, leafPath);
+    await runLeafAwait(registry, entry, leafPath, value);
+  } else {
+    const ancestorPath = leafPath.split('.').slice(0, entry.segments.length).join('.');
+    await Promise.resolve(dispatchAncestorRun(registry, treeRoot, entry, ancestorPath));
+  }
+}
+async function runOneLiteralEntry(registry, treeRoot, entry, literalPath, patternSegs) {
+  const value = readTreeAtPath(treeRoot, literalPath);
+  if (isAncestorTarget(value)) {
+    await Promise.resolve(dispatchAncestorRun(registry, treeRoot, entry, literalPath));
+    return;
+  }
+  await runLeafAwait(registry, entry, literalPath, value);
+}
+function isAncestorTarget(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  if (value instanceof Date || value instanceof Map || value instanceof Set) return false;
+  return true;
+}
+function runLeafAwait(registry, entry, path, next) {
+  const state = ensurePathState(registry, path);
+  const myVersion = ++state.version;
+  const formatIssue = registry.config.formatIssue ?? defaultFormatIssue;
+  let result;
+  try {
+    result = entry.schema['~standard'].validate(next);
+  } catch (err) {
+    applyLeafVerdict(registry, state, path, runtimeErrorMessage(err));
+    return Promise.resolve();
+  }
+  if (!(result instanceof Promise)) {
+    applyLeafVerdict(registry, state, path, resultToMessage(result, path, formatIssue));
+    return Promise.resolve();
+  }
+  state.inFlightVersion = myVersion;
+  state.pendingSignal.set(true);
+  addPendingPath(registry, path);
+  return result.then(settled => {
+    if (state.inFlightVersion !== myVersion) return;
+    state.inFlightVersion = null;
+    applyLeafVerdict(registry, state, path, resultToMessage(settled, path, formatIssue));
+    state.pendingSignal.set(false);
+    removePendingPath(registry, path);
+  }, err => {
+    if (state.inFlightVersion !== myVersion) return;
+    state.inFlightVersion = null;
+    applyLeafVerdict(registry, state, path, runtimeErrorMessage(err));
+    state.pendingSignal.set(false);
+    removePendingPath(registry, path);
+  });
+}
+async function validateOnePath(registry, treeRoot, path) {
+  const owner = matchLeaf(registry, path);
+  if (!owner) return registry.invalidCount() === 0;
+  await runOnePathForEntry(registry, treeRoot, owner, path);
+  return registry.invalidCount() === 0;
+}
+function runtimeErrorMessage(err) {
+  return `validation runtime error: ${String(err instanceof Error ? err.message : err)}`;
+}
+
+export { schemas };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@signaltree/schema",
+  "version": "9.3.0",
+  "description": "Schema-driven validation for SignalTree. StandardSchema-compatible, async-first, observe-only.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "src/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nx build schema",
+    "test": "nx test schema",
+    "lint": "nx lint schema",
+    "test:watch": "nx test schema --watch",
+    "test:coverage": "nx test schema --coverage",
+    "type-check": "tsc --project tsconfig.lib.json --noEmit"
+  },
+  "peerDependencies": {
+    "@angular/core": "^20.0.0 || ^21.0.0",
+    "@signaltree/core": "^9.0.1",
+    "@standard-schema/spec": "^1.0.0",
+    "tslib": "^2.0.0"
+  },
+  "peerDependenciesMeta": {},
+  "devDependencies": {
+    "@signaltree/core": "workspace:*",
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "keywords": [
+    "signaltree",
+    "state-management",
+    "schema",
+    "validation",
+    "standard-schema",
+    "zod",
+    "valibot",
+    "arktype",
+    "angular",
+    "signals"
+  ],
+  "author": "SignalTree Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signaltree/signaltree.git",
+    "directory": "packages/schema"
+  }
+}

package/src/__tests__/test-helpers.d.ts

@@ -0,0 +1,10 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export declare function syncSchema<T = unknown>(check: (v: unknown) => string | null): StandardSchemaV1<T, T>;
+export declare function asyncSchema<T = unknown>(check: (v: unknown) => Promise<string | null> | string | null, delayMs?: number): StandardSchemaV1<T, T>;
+export declare function controllableSchema<T = unknown>(): {
+    schema: StandardSchemaV1<T, T>;
+    resolveLatest(msg: string | null): void;
+    resolveAll(msg: string | null): void;
+    pendingCount(): number;
+};
+export declare function throwingSchema(message?: string): StandardSchemaV1<unknown, unknown>;

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export { schemas } from './lib/schema';
+export type { SchemaConfig, SchemaMethods, SchemaPath, } from './lib/types';

package/src/lib/internals/aggregates.d.ts

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

package/src/lib/internals/ancestor-handler.d.ts

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

package/src/lib/internals/compact.d.ts

@@ -0,0 +1 @@
+import { readTreeAtPath } from './matcher';

package/src/lib/internals/issue-mapper.d.ts

@@ -0,0 +1,3 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export declare function defaultFormatIssue(issue: StandardSchemaV1.Issue): string;
+export declare function resultToMessage(result: StandardSchemaV1.Result<unknown>, path: string, formatIssue: (issue: StandardSchemaV1.Issue, path: string) => string): string | null;

package/src/lib/internals/leaf-handler.d.ts

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

package/src/lib/internals/matcher.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaEntry, PatternSegment, Registry } from './state';
+export declare function compilePattern(pattern: string): PatternSegment[];
+export declare function matchLeaf(registry: Registry, leafPath: string): SchemaEntry | undefined;

package/src/lib/internals/signal-cache.d.ts

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

package/src/lib/internals/state.d.ts

@@ -0,0 +1,46 @@
+import { WritableSignal, Signal } from '@angular/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { SchemaConfig } from '../types';
+export declare const WILDCARD: unique symbol;
+export type PatternSegment = string | typeof WILDCARD;
+export interface PathState {
+    version: number;
+    lastSettledError: string | null;
+    inFlightVersion: number | null;
+    errorSignal: WritableSignal<string | null>;
+    pendingSignal: WritableSignal<boolean>;
+}
+export interface AncestorRunRecord {
+    runId: number;
+    capturedVersions: ReadonlyMap<string, number>;
+    ownedLeaves: ReadonlySet<string>;
+}
+export interface SchemaEntry {
+    pattern: string;
+    schema: StandardSchemaV1;
+    isWildcard: boolean;
+    isAncestor: boolean;
+    segments: ReadonlyArray<PatternSegment>;
+}
+export interface Registry {
+    entries: ReadonlyArray<SchemaEntry>;
+    leafOwner: Map<string, SchemaEntry>;
+    pathStates: Map<string, PathState>;
+    errorsAtCache: Map<string, Signal<string | null>>;
+    isValidAtCache: Map<string, Signal<boolean>>;
+    isPendingAtCache: Map<string, Signal<boolean>>;
+    invalidCount: WritableSignal<number>;
+    activeAncestorRuns: Map<string, AncestorRunRecord>;
+    nextAncestorRunId: number;
+    pendingPathsSignal: WritableSignal<readonly string[]>;
+    boundPathsSignal: WritableSignal<readonly string[]>;
+    boundPathsSet: Set<string>;
+    pendingPathsSet: Set<string>;
+    config: SchemaConfig;
+}
+export declare function createPathState(): PathState;
+export declare function ensurePathState(registry: Registry, path: string): PathState;
+export declare function addBoundPath(registry: Registry, path: string): void;
+export declare function removeBoundPath(registry: Registry, path: string): void;
+export declare function addPendingPath(registry: Registry, path: string): void;
+export declare function removePendingPath(registry: Registry, path: string): void;

package/src/lib/schema.d.ts

@@ -0,0 +1,3 @@
+import { type ISignalTree } from '@signaltree/core';
+import type { SchemaConfig, SchemaMethods } from './types';
+export declare function schemas(config: SchemaConfig): <T>(tree: ISignalTree<T>) => ISignalTree<T> & SchemaMethods;

package/src/lib/types.d.ts

@@ -0,0 +1,30 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Signal } from '@angular/core';
+import type { UpdateMetadata } from '@signaltree/core';
+export type SchemaPath = string;
+export interface SchemaConfig {
+    schemas: Readonly<Record<SchemaPath, StandardSchemaV1>>;
+    mode?: 'accept' | 'warn';
+    validateOnAttach?: boolean;
+    suppressIntents?: ReadonlyArray<NonNullable<UpdateMetadata['intent']>>;
+    suppressSources?: ReadonlyArray<NonNullable<UpdateMetadata['source']>>;
+    onError?: (path: string, message: string) => void;
+    formatIssue?: (issue: StandardSchemaV1.Issue, path: string) => string;
+}
+export interface SchemaMethods {
+    schemas: {
+        readonly errors: Signal<Readonly<Record<string, string | null>>>;
+        readonly errorList: Signal<readonly string[]>;
+        readonly isValid: Signal<boolean>;
+        readonly pending: Signal<boolean>;
+        readonly pendingPaths: Signal<readonly string[]>;
+        errorsAt(path: string): Signal<string | null>;
+        isValidAt(path: string): Signal<boolean>;
+        isPendingAt(path: string): Signal<boolean>;
+        validate(): Promise<boolean>;
+        validatePath(path: string): Promise<boolean>;
+        compact(): void;
+        schemaFor(leafPath: string): StandardSchemaV1 | undefined;
+        readonly boundPaths: Signal<readonly string[]>;
+    };
+}