@jarenjs/linq 0.49.2 → 0.66.1

package/src/model/entity.js

@@ -0,0 +1,307 @@
+//@ts-check
+/**
+ * @file The `x-entity` vocabulary as builder methods: one mixin,
+ * `withEntity(Base)`, applied to every schema-pen class at module
+ * scope, so `./model` is a set of NEW classes (never a patched
+ * prototype) whose every builder can be a key, an index, a column
+ * override, a store-written default or a version token. The methods
+ * write into the one `x-entity` annotation; what the store does with
+ * it is MODEL-FORMAT §9's business, and the pen refuses only what the
+ * store's own model walk would refuse and the builder can already see
+ * — `identity('auto')` off an integer, `identity('uuid')` off a string,
+ * `column('integer')` off a date, `key()`/`unique()`/`index()` off a
+ * kind that can never hold a column, `version()` off an integer, and a
+ * member outside the closed vocabulary — with `JL0102` naming the rule.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { requireJson, requireName } from '../schema/builders.js';
+import { captureQuery } from '../schema/check.js';
+
+/** What a captured model default or member path evaluates over, for the
+ * `JL0104` a second callback argument raises: the document being
+ * written, which the callback's own first argument already is. The
+ * shared capture cannot say this — it holds for this pen and not for the
+ * others (`capture-root.js`). */
+export const DOCUMENT_SCOPE = ' — it evaluates over the document being written, '
+  + 'which its argument IS; there is nothing else to read';
+
+/** The keyword every entity method writes. */
+const KEYWORD = 'x-entity';
+
+/** The two storage overrides MODEL-FORMAT §9.2 names. */
+const COLUMNS = new Set(['integer', 'json']);
+
+/** The closed set MODEL-FORMAT §9.2 defines. An unknown member is the
+ * store's `JD0030` — a silently ignored mapping directive loses data —
+ * so `entity()` refuses it here rather than emitting it. */
+const BLOCK = ['key', 'unique', 'index', 'default', 'column', 'relation', 'version'];
+
+/**
+ * Kinds that can NEVER be a column of their own: the store maps a
+ * top-level scalar to a typed column and keeps everything else in the
+ * JSONB document (MODEL-FORMAT §9.3), so `key`/`unique`/`index` on one
+ * of these is `JD0005` at `openStore`. `raw`, `named`, `ref`, `lazy` and
+ * `intersection` are NOT here: the store resolves `$ref` and merges
+ * `allOf` before it reads the type, so any of them may still be a
+ * scalar and the pen cannot tell.
+ */
+const NEVER_COLUMN = new Set([
+  'object', 'record', 'array', 'tuple', 'enum', 'literal',
+  'any', 'never', 'union', 'discriminated', 'when',
+]);
+
+/** Whether a builder is a string with a date or date-time format. */
+function isDateString(builder) {
+  const st = builder.state;
+  return st.kind === 'string'
+    && (st.keywords.format === 'date-time' || st.keywords.format === 'date');
+}
+
+/**
+ * The mapping directives that need a column: refused on a kind the
+ * store could never give one. The position is still the store's
+ * question — a scalar nested inside an object takes no column either,
+ * and the builder cannot see where it is placed.
+ * @param {any} builder
+ * @param {string} what - the method's name
+ */
+function requireColumnable(builder, what) {
+  const kind = builder.state.kind;
+  if (NEVER_COLUMN.has(kind)) {
+    throw new LinqBuildError('JL0102',
+      `${what}() applies to a member with a column of its own — this one's kind is `
+      + `'${kind}', and only a top-level scalar (string, number, integer, boolean, null) `
+      + 'is column-mapped; everything else lives in the JSON document');
+  }
+  return builder;
+}
+
+/**
+ * The mixin: a subclass of `Base` carrying the entity methods.
+ * @template {new (state: any) => any} B
+ * @param {B} Base - a schema-pen builder class
+ * @returns {B} a new class, `Base` plus the vocabulary
+ */
+export function withEntity(Base) {
+  return class extends Base {
+    /**
+     * Merge into the `x-entity` block, keeping the order members were
+     * first set in. The primitive every method below writes through, and
+     * the one door to a member of the vocabulary that has no method of
+     * its own — held to the same closed set the store reads.
+     * @param {Record<string, any>} patch
+     * @returns {this}
+     */
+    entity(patch) {
+      if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new LinqBuildError('JL0101',
+          'entity() takes a plain object of x-entity members');
+      }
+      for (const member of Object.keys(patch)) {
+        if (!BLOCK.includes(member)) {
+          throw new LinqBuildError('JL0102',
+            `entity() writes the closed x-entity vocabulary (${BLOCK.join(', ')}); `
+            + `'${member}' is not a member of it, and the store refuses one it cannot read `
+            + 'rather than ignoring it (a mapping directive that is silently dropped loses data)');
+        }
+      }
+      const current = this.annotation(KEYWORD) ?? {};
+      return this.annotate(KEYWORD, Object.freeze({ ...current, ...patch }));
+    }
+
+    /** `key: true` — (part of) the primary key. */
+    key() { return requireColumnable(this, 'key').entity({ key: true }); }
+
+    /**
+     * `unique: true` — a unique index over the column. The ARRAY builder
+     * already owns this name (`uniqueItems`, a validation keyword), and a
+     * mixin must not change what a document asserts: where the base
+     * defines it, the base wins, and an array member takes no column of
+     * its own anyway.
+     */
+    unique() {
+      return typeof super.unique === 'function'
+        ? super.unique()
+        : requireColumnable(this, 'unique').entity({ unique: true });
+    }
+
+    /** `index: true` — a non-unique index over the column. */
+    index() { return requireColumnable(this, 'index').entity({ index: true }); }
+
+    /**
+     * `version: true` — the optimistic-concurrency token (§11.5): one
+     * plain integer column per entity, engine-owned. Whether it is also
+     * a key, a relation or column-mapped is a COMBINATION the store
+     * judges (`JD0005`); its kind is visible here.
+     */
+    version() {
+      if (this.state.kind !== 'integer') {
+        throw new LinqBuildError('JL0102',
+          'version() is the optimistic-concurrency token and lives in a plain integer '
+          + `column — this member's kind is '${this.state.kind}'; spell it integer()`);
+      }
+      return this.entity({ version: true });
+    }
+
+    /**
+     * `column`: `'integer'` stores a date-formatted string as epoch
+     * milliseconds; `'json'` keeps a scalar in the document.
+     * @param {'integer' | 'json'} storage
+     */
+    column(storage) {
+      if (!COLUMNS.has(storage)) {
+        throw new LinqBuildError('JL0101',
+          `column() takes 'integer' (an epoch column for a date) or 'json' (stay in the `
+          + `document), got ${JSON.stringify(storage)}`);
+      }
+      if (storage === 'integer' && !isDateString(this)) {
+        throw new LinqBuildError('JL0102',
+          "column('integer') applies to a date-time or date formatted string — the epoch "
+          + 'column is derived from the RFC 3339 text; spell the member datetime() or date()');
+      }
+      return this.entity({ column: storage });
+    }
+
+    /**
+     * A store-allocated key (MODEL-FORMAT §9.5): `key: true` with
+     * `default: 'uuid'` (`crypto.randomUUID()` on a single string key)
+     * or `default: 'auto'` (the database allocates a single integer key).
+     * @param {'uuid' | 'auto'} kind
+     */
+    identity(kind) {
+      if (kind === 'uuid') {
+        if (this.state.kind !== 'string') {
+          throw new LinqBuildError('JL0102',
+            `identity('uuid') allocates a single string key — the member is a ${this.state.kind}`);
+        }
+      }
+      else if (kind === 'auto') {
+        if (this.state.kind !== 'integer') {
+          throw new LinqBuildError('JL0102',
+            "identity('auto') is allocated by the database for a single integer key only — the "
+            + `member is ${this.state.kind === 'number' ? 'a number; spell it integer()' : `a ${this.state.kind}`}`);
+        }
+      }
+      else {
+        throw new LinqBuildError('JL0101',
+          `identity() takes 'uuid' or 'auto', got ${JSON.stringify(kind)}`);
+      }
+      return this.entity({ key: true, default: kind });
+    }
+
+    /** `default: 'now'` — an RFC 3339 stamp on insert, when absent. */
+    now() { return this.entity({ default: 'now' }); }
+    /** `default: 'updated'` — a stamp on insert and on every update. */
+    updated() { return this.entity({ default: 'updated' }); }
+
+    /** `default: { value }` — a literal, filled when absent. @param {any} value */
+    fill(value) { return this.entity({ default: { value: requireJson(value, 'fill()') } }); }
+
+    /**
+     * `default: { query }` — evaluated over the document being written
+     * (`$` is that document; no externals): a captured callback, or a
+     * query document verbatim.
+     * @param {((doc: any, externals: any) => any) | object} rule
+     */
+    compute(rule) {
+      const query = typeof rule === 'function'
+        ? captureQuery('compute()', [], rule, { advice: () => DOCUMENT_SCOPE })
+        : requireJson(rule, 'compute()');
+      return this.entity({ default: { query } });
+    }
+
+    /**
+     * `x-rename`: this entity was previously named `name` (a migration
+     * hint the planner reads; lifted onto the entity declaration by
+     * `defineModel`). @param {string} name
+     */
+    renamedFrom(name) { return this.with({ renamedFrom: requireName(name, 'renamedFrom()') }); }
+
+    /** As in the schema pen, but `x-entity` is owned here. @param {Record<string, any>} annotations */
+    meta(annotations) {
+      if (annotations !== null && typeof annotations === 'object' && KEYWORD in annotations) {
+        throw new LinqBuildError('JL0104',
+          `meta() cannot write '${KEYWORD}' — the model pen owns that keyword; spell it `
+          + 'through key(), identity(), unique(), index(), column(), now(), updated(), '
+          + 'fill(), compute() or rel.*');
+      }
+      return super.meta(annotations);
+    }
+  };
+}
+
+/**
+ * The builders one builder holds, as `[segment, child]` pairs. A
+ * `lazy()` thunk is NOT invoked: it exists to break a cycle, and calling
+ * it here would rebuild the recursion this walk is trying to finish.
+ * @param {any} state
+ * @returns {[string, any][]}
+ */
+function childrenOf(state) {
+  switch (state.kind) {
+    case 'object': return [
+      ...state.props.map(([name, child]) => [name, child]),
+      ...state.patterns.map(([pattern, child]) => [`[${pattern}]`, child]),
+      ...(state.names === null ? [] : [['propertyNames', state.names]]),
+    ];
+    case 'array': return [
+      ['items', state.items],
+      ...(state.contains === null ? [] : [['contains', state.contains]]),
+    ];
+    case 'tuple': return [
+      ...state.items.map((child, i) => [`[${i}]`, child]),
+      ...(state.rest === null ? [] : [['rest', state.rest]]),
+    ];
+    case 'record': return [['values', state.values]];
+    case 'union': case 'discriminated': case 'intersection':
+      return state.options.map((child, i) => [`[${i}]`, child]);
+    case 'when': return [
+      ['if', state.cond],
+      ...(state.then === null ? [] : [['then', state.then]]),
+      ...(state.else === null ? [] : [['else', state.else]]),
+    ];
+    case 'named': return [[state.name, state.target]];
+    default: return [];
+  }
+}
+
+/**
+ * The path of the first DESCENDANT carrying a `renamedFrom` hint, or
+ * `null`. `$model` 0.1 puts `x-rename` on an entity or a collection
+ * declaration and nowhere else (MIGRATION-FORMAT §3), so a hint anywhere
+ * but the declaration's own builder is written by nobody — and a rename
+ * the planner never sees is a drop plus a create.
+ * @param {any} root - the declaration's builder; its OWN hint is lifted
+ * @returns {string | null}
+ */
+export function strandedRename(root) {
+  const seen = new Set();
+  /** @type {[string, any][]} */
+  const queue = childrenOf(root.state).map(([segment, child]) => [segment, child]);
+  while (queue.length > 0) {
+    const [path, builder] = /** @type {any} */ (queue.shift());
+    if (builder === null || typeof builder !== 'object' || seen.has(builder)) continue;
+    seen.add(builder);
+    if (builder.state?.renamedFrom !== undefined) return path;
+    for (const [segment, child] of childrenOf(builder.state)) {
+      queue.push([segment.startsWith('[') ? `${path}${segment}` : `${path}.${segment}`, child]);
+    }
+  }
+  return null;
+}
+
+/**
+ * The refusal `defineModel()` and `collection()` share for a stranded
+ * hint (see `strandedRename`).
+ * @param {any} builder @param {string} what @param {string} [docPath]
+ */
+export function refuseStrandedRename(builder, what, docPath = undefined) {
+  const path = strandedRename(builder);
+  if (path === null) return;
+  throw new LinqBuildError('JL0102',
+    `renamedFrom() on ${what}.${path} is not written — $model 0.1 carries x-rename on an `
+    + 'entity or a collection declaration, never on a member, so the hint would be lost and '
+    + "a rename the planner cannot see is a drop plus a create; put it on the declaration's "
+    + 'own builder, or rename the member with a migration transform', docPath);
+}

package/src/model/index.js

@@ -0,0 +1,47 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/model` — the database by code. The schema pen's
+ * every name, rebuilt from SUBCLASSES that carry the `x-entity`
+ * vocabulary (`key()`, `identity()`, `unique()`, `index()`, `column()`,
+ * `now()`, `updated()`, `fill()`, `compute()`, `version()`,
+ * `renamedFrom()`), the relation members (`rel.*`), collections and
+ * their indexes, and `defineModel()` — one `$model` 0.1 document that
+ * `openStore` accepts unchanged. Nothing here imports `@jarenjs/db`.
+ */
+
+import {
+  SchemaBuilder, StringBuilder, NumberBuilder, ArrayBuilder, TupleBuilder,
+  ObjectBuilder, WhenBuilder, NeverBuilder,
+} from '../schema/builders.js';
+import { createFactories } from '../schema/factories.js';
+import { withEntity } from './entity.js';
+import { createRelations } from './relation.js';
+
+/** The entity-aware classes: new classes, one mixin, no patched prototype. */
+export const EntityBuilder = withEntity(SchemaBuilder);
+export const EntityStringBuilder = withEntity(StringBuilder);
+export const EntityNumberBuilder = withEntity(NumberBuilder);
+export const EntityArrayBuilder = withEntity(ArrayBuilder);
+export const EntityTupleBuilder = withEntity(TupleBuilder);
+export const EntityObjectBuilder = withEntity(ObjectBuilder);
+export const EntityWhenBuilder = withEntity(WhenBuilder);
+export const EntityNeverBuilder = withEntity(NeverBuilder);
+
+export const {
+  string, number, integer, boolean, nil, literal, enumOf,
+  object, array, tuple, record, union, discriminated, intersection,
+  named, ref, lazy, any, never, when, from, document,
+  datetime, date, time, duration,
+} = /** @type {any} */ (createFactories({
+  Base: EntityBuilder, String: EntityStringBuilder, Number: EntityNumberBuilder,
+  Array: EntityArrayBuilder, Tuple: EntityTupleBuilder, Object: EntityObjectBuilder,
+  When: EntityWhenBuilder, Never: EntityNeverBuilder,
+}));
+
+/** The relation members: `rel.hasMany`, `rel.hasOne`, `rel.belongsToMany`. */
+export const rel = createRelations(EntityBuilder);
+
+export { collection, index, expressionIndex } from './collection.js';
+export { defineModel } from './define.js';
+export { withEntity } from './entity.js';
+export { isSchemaBuilder, schemaOf, SCHEMA_BUILDER } from '../schema/brand.js';

package/src/model/relation.js

@@ -0,0 +1,85 @@
+//@ts-check
+/**
+ * @file Relation members: `rel.hasMany`, `rel.hasOne`, `rel.belongsToMany`
+ * — each a builder of no type (`{}`) whose `x-entity.relation` block is
+ * the whole member, spelled exactly as MODEL-FORMAT §9.4's three kinds.
+ * A relation member is a projection, never stored state, so every
+ * relation builder is `optional()` by construction. The target is an
+ * entity NAME; whether it is declared is `defineModel`'s question.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { initial, requireName } from '../schema/builders.js';
+
+const ON_DELETE = new Set(['cascade', 'restrict', 'setNull']);
+
+/**
+ * @param {any} options
+ * @param {string} what
+ * @returns {{ via: string, onDelete: string }}
+ */
+function foreignKeyOptions(options, what) {
+  if (options === null || typeof options !== 'object') {
+    throw new LinqBuildError('JL0101', `${what} takes { via, onDelete }`);
+  }
+  const via = requireName(options.via, `${what} via`);
+  if (!ON_DELETE.has(options.onDelete)) {
+    throw new LinqBuildError('JL0101',
+      `${what} must declare onDelete: 'cascade', 'restrict' or 'setNull' — a foreign key is `
+      + `never defaulted silently; got ${JSON.stringify(options.onDelete)}`);
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== 'via' && key !== 'onDelete') {
+      throw new LinqBuildError('JL0101', `${what} does not take '${key}'`);
+    }
+  }
+  return { via, onDelete: options.onDelete };
+}
+
+/**
+ * The relation factories for one builder class.
+ * @param {any} Base - the class a relation member is built from
+ */
+export function createRelations(Base) {
+  const member = (relation) => new Base(initial('any', {}))
+    .annotate('x-entity', Object.freeze({ relation: Object.freeze(relation) }))
+    .with({ optional: true });
+  return Object.freeze({
+    /**
+     * One-to-many: `{ to, many: true, via, onDelete }` — `via` names the
+     * foreign key on the TARGET entity.
+     * @param {string} to @param {{ via: string, onDelete: 'cascade' | 'restrict' | 'setNull' }} options
+     */
+    hasMany(to, options) {
+      const { via, onDelete } = foreignKeyOptions(options, 'rel.hasMany()');
+      return member({ to: requireName(to, 'rel.hasMany()'), many: true, via, onDelete });
+    },
+    /**
+     * One-to-one (and the many-to-one side): `{ to, via, onDelete }` —
+     * `via` names the foreign key on the DECLARING entity.
+     * @param {string} to @param {{ via: string, onDelete: 'cascade' | 'restrict' | 'setNull' }} options
+     */
+    hasOne(to, options) {
+      const { via, onDelete } = foreignKeyOptions(options, 'rel.hasOne()');
+      return member({ to: requireName(to, 'rel.hasOne()'), via, onDelete });
+    },
+    /**
+     * Many-to-many: `{ to, many: true, through? }` — a join table, named
+     * `through` or the sorted `<A>_<B>`.
+     * @param {string} to @param {{ through?: string }} [options]
+     */
+    belongsToMany(to, options = {}) {
+      if (options === null || typeof options !== 'object') {
+        throw new LinqBuildError('JL0101', 'rel.belongsToMany() takes { through? }');
+      }
+      for (const key of Object.keys(options)) {
+        if (key !== 'through') {
+          throw new LinqBuildError('JL0101', `rel.belongsToMany() does not take '${key}'`);
+        }
+      }
+      const relation = { to: requireName(to, 'rel.belongsToMany()'), many: true };
+      if (options.through !== undefined) relation.through = requireName(options.through, 'rel.belongsToMany() through');
+      return member(relation);
+    },
+  });
+}

package/src/provider.js

@@ -1,31 +1,70 @@
 //@ts-check
 /**
  * @file The provider seam (D2): a provider is any object exposing
- * `execute(queryDocument, options)` — contract-level coupling, never an
- * import edge. `@jarenjs/db` will implement this interface without
- * either package importing the other. The in-memory runner implements
+ * `execute(queryDocument, options)` — contract-level coupling: the
+ * chain imports no provider. `@jarenjs/db` implements this interface;
+ * the package's one runtime edge — the client subpath `./db` — runs
+ * the other way, toward the store, as declared optional peers, and the
+ * store never imports this package. The in-memory runner implements
  * the SAME interface over an iterable, so it is both the reference
  * semantics every other provider must match and the proof the seam is
  * real.
  *
  * Compiled documents are shared through a bounded LRU keyed by the
- * document's COLLISION-FREE structural identity, one cache per REGISTRY
- * identity — the hooks change what compiles, so two different registries
- * must not share compiled programs.
- * A fingerprint would not do: a 32-bit content hash collides after tens
- * of thousands of documents, and a collision here runs one query's
- * compiled program for another query's document — silently wrong rows.
+ * document's COLLISION-FREE, ORDER-SENSITIVE identity — its exact JSON
+ * text — one cache per REGISTRY identity, because the hooks change what
+ * compiles, so two different registries must not share compiled
+ * programs. A fingerprint would not do: a 32-bit content hash collides
+ * after tens of thousands of documents, and a collision here runs one
+ * query's compiled program for another query's document — silently
+ * wrong rows. Nor would an order-insensitive identity: a constructor's
+ * member order is part of a document's meaning (`{ id, name }` and
+ * `{ name, id }` project different objects), and a cache that keyed them
+ * as one answered the second projection in the first one's order.
  */
 
 import { compileJsonQuery, JsonQueryCompileError } from '@jarenjs/json/query';
-import { createSemanticCache, createWeakCache } from '@jarenjs/core/cache';
+import { createBoundedCache, createWeakCache } from '@jarenjs/core/cache';
 import { LinqBuildError } from './errors.js';
 
 /** Stands in for an absent hook while walking the identity chain. */
 const NO_HOOK = Object.freeze({});
 
 const CACHES = createWeakCache();
-const cacheFor = () => createSemanticCache(512);
+const cacheFor = () => createBoundedCache(512);
+
+/**
+ * The cache identity of one compilation: the document's exact JSON text
+ * beside the declared externals and the limits. `null` when the value
+ * cannot be keyed injectively — a function, an `undefined`, a symbol, a
+ * bigint, a non-finite number, `-0`, or a class instance whose `toJSON`
+ * would otherwise stand in for it — which is a permanent miss, never
+ * someone else's entry.
+ * @param {any} document
+ * @param {readonly string[]} externals
+ * @param {any} limits
+ * @returns {string | null}
+ */
+function compilationKey(document, externals, limits) {
+  try {
+    return JSON.stringify([document, externals, limits ?? null], function (key, value) {
+      const raw = this[key];
+      const type = typeof raw;
+      if (type === 'function' || type === 'undefined' || type === 'symbol' || type === 'bigint'
+        || (type === 'number' && (!Number.isFinite(raw) || Object.is(raw, -0)))) {
+        throw new TypeError('unkeyable');
+      }
+      if (raw !== null && type === 'object' && !Array.isArray(raw)) {
+        const proto = Object.getPrototypeOf(raw);
+        if (proto !== Object.prototype && proto !== null) throw new TypeError('unkeyable');
+      }
+      return value;
+    });
+  }
+  catch {
+    return null;
+  }
+}
 
 /** The root of the hook-identity chain. */
 const REGISTRY_IDS = createWeakCache();
@@ -103,10 +142,7 @@ function registryIdentity(options) {
  */
 export function compileDocument(document, options) {
   const cache = /** @type {any} */ (CACHES.getOrCreate(registryIdentity(options), cacheFor));
-  // the externals and the limits are part of the identity: the same
-  // document compiles differently against a different set of declared
-  // names, and differently again under a step or result bound
-  return cache.getOrCreate([document, options.externals, options.limits ?? null], () => {
+  const compile = () => {
     try {
       return compileJsonQuery(document, {
         ...compileOptionsOf(options),
@@ -123,7 +159,91 @@ export function compileDocument(document, options) {
       }
       throw err;
     }
-  });
+  };
+  // the externals and the limits are part of the identity: the same
+  // document compiles differently against a different set of declared
+  // names, and differently again under a step or result bound
+  const key = compilationKey(document, options.externals, options.limits);
+  return key === null ? compile() : cache.getOrCreate(key, compile);
+}
+
+/**
+ * Whether a source is a provider: an `execute` duck. The one dispatch
+ * both surfaces share — on `fromAsync` it is asked BEFORE the iterable
+ * shapes, so a provider that also happens to be iterable is still a
+ * provider.
+ * @param {any} source
+ * @returns {boolean}
+ */
+export function isProviderSource(source) {
+  return source !== null && typeof source === 'object'
+    && typeof (/** @type {any} */ (source).execute) === 'function';
+}
+
+/**
+ * The root expression a provider's items are bound through (QUERY-PEN
+ * §8): its `root` (`'$.Post[*]'` for an entity set), or `'$[*]'` when it
+ * names none — the whole input, a collection. A provider that serves
+ * SEVERAL roots and none of its own (a store with entities: `roots`) has
+ * nothing a chain could iterate — `$[*]` over the entity map would
+ * answer the rows of every entity, mixed, or count the SETS — so it is
+ * refused here, at `from()` time, naming the roots to chain over.
+ * @param {any} provider
+ * @returns {string}
+ */
+export function providerRoot(provider) {
+  const root = provider.root;
+  if (root === undefined || root === null) {
+    const roots = provider.roots;
+    if (Array.isArray(roots) && roots.length > 0) {
+      throw new LinqBuildError('JL0007',
+        `this provider serves entity roots ${roots.join(', ')} and has no root of its own — `
+        + 'chain over one of them: from(store.entity(name)) (QUERY-PEN.md §8)');
+    }
+    return '$[*]';
+  }
+  if (typeof root !== 'string' || root === '') {
+    throw new LinqBuildError('JL0005',
+      `a provider's root is a path expression string ('$.Post[*]'), got ${typeof root}`);
+  }
+  return root;
+}
+
+/**
+ * The relation context a provider offers (QUERY-PEN §8): its own
+ * relation table — `relations`, keyed by member (MODEL-FORMAT §10.1) —
+ * and a resolver for the tables of the other roots of its scope
+ * (`scope.relations`, keyed by root name: one store's entity sets), so
+ * a hop can continue into another root. `null` when the provider
+ * carries no table: a relation name is then an ordinary member.
+ * @param {any} provider
+ * @returns {{ table: any, resolve: (name: string) => any } | null}
+ */
+export function providerRelations(provider) {
+  const table = provider.relations;
+  if (table === null || typeof table !== 'object') return null;
+  const scope = provider.scope;
+  const scoped = scope !== null && typeof scope === 'object' ? scope.relations : undefined;
+  return {
+    table,
+    resolve: (name) => (scoped !== null && typeof scoped === 'object'
+      && Object.hasOwn(scoped, name) ? scoped[name] : undefined),
+  };
+}
+
+/**
+ * Whether two sources may share one document: the same object, or two
+ * providers carrying one `scope` — one store's entity sets, which are
+ * two roots of ONE multi-entity input (QUERY-PEN §8).
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+export function sharesScope(a, b) {
+  if (a === b) return true;
+  if (!isProviderSource(a) || !isProviderSource(b)) return false;
+  const scope = a.scope;
+  return scope !== undefined && scope !== null && scope === b.scope;
 }
 
 /**
@@ -135,10 +255,7 @@ export function compileDocument(document, options) {
  * @returns {'provider' | 'iterable'}
  */
 export function classifySource(source) {
-  if (source !== null && typeof source === 'object'
-    && typeof (/** @type {any} */ (source).execute) === 'function') {
-    return 'provider';
-  }
+  if (isProviderSource(source)) return 'provider';
   if (source != null && (typeof source === 'string'
     || typeof (/** @type {any} */ (source))[Symbol.iterator] === 'function')) {
     return 'iterable';

package/src/schema/brand.js

@@ -0,0 +1,31 @@
+//@ts-check
+/**
+ * @file The schema-builder brand: how anything outside the pen tells a
+ * builder from the document it writes. The brand is a registry symbol
+ * (`Symbol.for`), so the chain — which imports nothing from this
+ * directory, by the tree-shaking rule — recognises a builder handed to
+ * `ofType`/`cast` by looking the same symbol up; a data object that
+ * merely carries a `toJSON` member is a schema, never a builder.
+ */
+
+/** The brand key every builder answers `true` under. */
+export const SCHEMA_BUILDER = Symbol.for('@jarenjs/linq/schema-builder');
+
+/**
+ * Whether `value` is a schema builder (carries the brand).
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isSchemaBuilder(value) {
+  return value !== null && typeof value === 'object' && value[SCHEMA_BUILDER] === true;
+}
+
+/**
+ * A builder's document, or the value as given: the one call a consumer
+ * needs to accept "a schema, by hand or by pen".
+ * @param {any} value
+ * @returns {any} the JSON Schema document
+ */
+export function schemaOf(value) {
+  return isSchemaBuilder(value) ? value.schema : value;
+}