@adobe/ecs 0.0.0-stage → 0.2.0

package/src/interface/rule/rule.type-test.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Resource } from '../resource/resource.js';
+import { Component } from '../component/component.js';
+import { Entity } from '../entity/entity.js';
+import { Finalizer } from '../finalizer/finalizer.js';
+import { System } from '../system/system.js';
+import type { Create } from '../world/create.js';
+import type { World } from '../world/world.js';
+import { Rule } from './rule.js';
+import type { Writable } from '../component/value.js';
+import type { ChangeSet } from '../finalizer/body.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+const source = Symbol("ruleTypeTest/source");
+const hidden = Symbol("ruleTypeTest/hidden");
+const slot = Symbol("ruleTypeTest/slot");
+const parent = Symbol("ruleTypeTest/parent");
+const time = Symbol("ruleTypeTest/time");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [source]: { type: number };
+        [hidden]: { type: true };
+        [slot]: { type: number; derived: true };
+        [parent]: { type: Entity; reference: "owner" };
+    }
+    export interface Resources {
+        [time]: { type: number };
+    }
+}
+
+// Rules derive only derived components.
+const slots = Rule.create({ components: { with: [source], not: [hidden] }, derive: [slot] });
+// @ts-expect-error a rule derives only derived components
+Rule.create({ components: { with: [source] }, derive: [source] });
+
+// A finalizer's context holds every resource, the lookups it declares, and its commands.
+const other = Finalizer.create({ components: { with: [source] } }, (_, context) => {
+    void context.resources;
+    // @ts-expect-error no lookups declared
+    void context.lookup;
+    void context.commands;
+});
+
+// Per-query finalizers read the stopping row; it's read-only.
+Finalizer.create({
+    components: { with: [slot, parent], not: [hidden] },
+    after: [other],
+}, (row, { resources, commands }) => {
+    const value: number = row[slot];
+    const target: Entity = row[parent];
+    const now: number = resources[time];
+    commands.despawn(target);
+    // @ts-expect-error a finalizer's row is read-only
+    row[slot] = 1;
+    // @ts-expect-error only what with requires is in the row
+    void row[source];
+    void value; void now;
+});
+Finalizer.create({
+    components: {},
+}, () => {});
+
+// Changes finalizers see only the essential components they watch.
+Finalizer.changes({ watch: [source, parent] }, (changes, { commands }) => {
+    check<Equal<typeof changes, ChangeSet<typeof source | typeof parent>>>();
+    void commands;
+    for (const group of changes.groups) {
+        check<Equal<typeof group.from, readonly (typeof source | typeof parent)[] | null>>();
+        for (const entity of group.entities) {
+            const before: number | null = changes.previous(entity, source);
+            const after: Entity | null = changes.next(entity, parent);
+            // @ts-expect-error only watched components
+            changes.next(entity, hidden);
+            void before; void after;
+        }
+    }
+});
+// @ts-expect-error changes finalizers don't watch derived components
+Finalizer.changes({ watch: [slot] }, () => {});
+
+// References change only through commands, so systems can't write them.
+System.create({ components: { with: [parent, source] } }, row => { row[source] = row[parent]; });
+System.create({ components: { with: [parent] } }, row => {
+    // @ts-expect-error a reference changes only through commands
+    row[parent] = row.entity;
+});
+check<Equal<Extract<Writable, typeof parent | typeof source>, typeof source>>();
+
+// A rule and a finalizer are the values their constructors return, labeled by their names, which needn't be unique.
+check<Equal<typeof slots, ReturnType<typeof Rule.create>>>();
+check<Equal<typeof slots, { readonly name: string }>>();
+check<Equal<typeof other, Finalizer>>();
+const sameName: Finalizer = Finalizer.create({ components: { with: [source] } }, () => {});
+void sameName;
+
+// Rules and finalizers apply in every world.
+declare const create: Create;
+export const created: World = create();
+
+// Names are optional for rules and finalizers too.
+const unnamedRule = Rule.create({ components: { with: [source] }, derive: [slot] });
+const unnamedFinalizer: Finalizer = Finalizer.create({ components: { with: [source] } }, row => { void row[source]; });
+const unnamedChanges: Finalizer = Finalizer.changes({ watch: [source] }, changes => { void changes.groups; });
+void [unnamedRule, unnamedFinalizer, unnamedChanges];

package/src/interface/schema/is-struct.ts

@@ -0,0 +1,36 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+type Method = (...parameters: never[]) => unknown;
+
+/** Whether an object type has a method of its own, so it isn't data, looked at without recursing. */
+type HasMethod<T> = true extends { [K in keyof T]-?: T[K] extends Method ? true : false }[keyof T] ? true : false;
+
+/**
+ * Whether a value is a struct: numbers, booleans, entities, fixed-length tuples and structs of those, so its schema has
+ * a fixed size. A struct lives in shared memory, where every thread reads it.
+ */
+export type IsStruct<T> =
+    [T] extends [number | boolean] ? true :
+    [T] extends [Method] ? false :
+    [T] extends [readonly unknown[]] ? (number extends T["length"] ? false : IsStruct<T[number]>) :
+    [T] extends [object] ? (HasMethod<T> extends true ? false : false extends { [K in keyof T]-?: IsStruct<T[K]> }[keyof T] ? false : true) :
+    false;
+
+/**
+ * Whether a value is comparable data, which a shared component holds: numbers, booleans, strings, arrays and plain
+ * objects of those, compared by structure. Not `null`, maps, sets, functions or objects with methods.
+ */
+export type IsComparable<T> =
+    [T] extends [number | boolean | string] ? true :
+    [T] extends [Method] ? false :
+    [T] extends [readonly unknown[]] ? IsComparable<T[number]> :
+    [T] extends [object] ? (HasMethod<T> extends true ? false : false extends { [K in keyof T]-?: IsComparable<T[K]> }[keyof T] ? false : true) :
+    false;
+
+/** Whether a value is a string, a union of string literals or a string or `null`. */
+export type IsString<T> = [T] extends [null] ? false : [T] extends [string | null] ? true : false;
+
+/**
+ * Whether a value lives in shared memory, where every thread reads it: a struct or a string. Any other value is an
+ * object, which lives on one logical thread's heap, variable-length arrays included.
+ */
+export type IsShared<T> = IsString<T> extends true ? true : IsStruct<T>;

package/src/interface/schema/schema.ts

@@ -0,0 +1,190 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from '../entity/entity.js';
+
+/** Any value representable in JSON. */
+type JSONValue = string | number | boolean | null | readonly JSONValue[] | { readonly [key: string]: JSONValue };
+
+/**
+ * How a linear value is laid out in memory, and a promise that it's GPU compatible: registration throws if it isn't.
+ * - `storage`: WGSL storage-buffer layout, so a shader's matching `array<T>` reads the column directly.
+ * - `vertex`: tightly packed, as WebGPU vertex buffers expect.
+ * Without it, the value is packed tightly for the CPU and may use any linear type.
+ */
+type GpuLayout = 'storage' | 'vertex';
+
+interface ObjectSchema<K extends string = string> {
+    readonly type: 'object',
+    readonly properties: { readonly [P in K]: Schema };
+    readonly required?: readonly K[];
+    readonly layout?: GpuLayout;
+    readonly default?: never;
+}
+
+interface StringSchema {
+    readonly type: 'string';
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly default?: never;
+}
+
+interface ArraySchema<T extends Schema> {
+    readonly type: 'array';
+    readonly items: T;
+    readonly layout?: GpuLayout;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly default?: never;
+}
+
+interface NumberSchema {
+    readonly type: 'number';
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly precision?: 1 | 2;
+    readonly default?: never;
+}
+
+/** An entity reference, typed `Entity`. Every entity-typed value uses it, so references can be found by schema. */
+interface EntitySchema {
+    readonly type: 'integer';
+    readonly format: 'entity';
+    readonly default?: never;
+}
+
+interface IntegerSchema {
+    readonly type: 'integer';
+    readonly format?: never;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly default?: never;
+}
+
+interface BooleanSchema {
+    readonly type: 'boolean';
+    readonly default?: never;
+}
+
+interface NullSchema {
+    readonly type: 'null';
+    readonly default?: never;
+}
+
+/** A `ReadonlySet` of `items`' values. JSON has no set, so `'set'` isn't a JSON Schema type. */
+interface SetSchema<T extends Schema> {
+    readonly type: 'set';
+    readonly items: T;
+    readonly default?: never;
+}
+
+/** A `ReadonlyMap` from `keys`' values to `values`' values. JSON has no map, so `'map'` isn't a JSON Schema type. */
+interface MapSchema<K extends Schema, V extends Schema> {
+    readonly type: 'map';
+    readonly keys: K;
+    readonly values: V;
+    readonly default?: never;
+}
+
+/** Matches exactly one JSON value of any shape. */
+interface ConstSchema {
+    /** The value alone fully describes the schema; combining it with `type` is redundant and disallowed. */
+    readonly type?: never;
+    readonly const: JSONValue;
+    readonly default?: never;
+}
+
+interface AndSchema {
+    readonly allOf: readonly Schema[];
+    readonly default?: never;
+}
+
+interface OrSchema {
+    readonly anyOf: readonly Schema[];
+    readonly default?: never;
+}
+
+/**
+ * A JSON Schema of the forms the ECS reads, and two forms JSON lacks: `{ type: 'set', items }` and
+ * `{ type: 'map', keys, values }`. A schema describes values and holds no `default`: a value's start comes from its
+ * declaration or its type's namespace, `T.default`.
+ */
+export type Schema = EntitySchema | ObjectSchema | StringSchema | ArraySchema<Schema> | NumberSchema | IntegerSchema | BooleanSchema | NullSchema | SetSchema<Schema> | MapSchema<Schema, Schema> | ConstSchema | AndSchema | OrSchema;
+
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+
+export namespace Schema {
+    /** Object properties are all required unless `required` is present, then only those listed are. */
+    type ObjectToType<T extends ObjectSchema> =
+        T extends { required: readonly (infer R)[] }
+            ? Flat<{ readonly [P in Extract<R, keyof T['properties']>]: Schema.ToType<T['properties'][P]> }
+              & { readonly [P in Exclude<keyof T['properties'], R>]?: Schema.ToType<T['properties'][P]> }>
+            : { readonly [P in keyof T['properties']]: Schema.ToType<T['properties'][P]> };
+
+    /**
+     * One object type with the properties of an intersection, each as optional and read-only as it was. It's a
+     * conditional, so the result is an anonymous object type, which declarations emitted elsewhere can name.
+     */
+    type Flat<T> = T extends unknown ? { [P in keyof T]: T[P] } : never;
+
+    /** An array whose `minItems` and `maxItems` are one literal length is a tuple of that length. */
+    type ArrayToType<T, E> =
+        T extends { readonly minItems: infer N extends number; readonly maxItems: infer M extends number }
+            ? number extends N ? readonly E[] : [N] extends [M] ? [M] extends [N] ? Tuple<N, E> : readonly E[] : readonly E[]
+            : readonly E[];
+
+    type Tuple<N extends number, E, R extends readonly unknown[] = readonly []> =
+        R["length"] extends N ? R : Tuple<N, E, readonly [...R, E]>;
+
+    /**
+     * A literal `const` narrows the type, a fixed-length array is a tuple, and a set or map is a `ReadonlySet` or
+     * `ReadonlyMap`; otherwise the structural type is used.
+     */
+    export type ToType<T extends Schema> =
+        T extends AndSchema ? UnionToIntersection<Schema.ToType<T['allOf'][number]>> :
+        T extends OrSchema ? Schema.ToType<T['anyOf'][number]> :
+        T extends { const: infer C } ? C :
+        T extends EntitySchema ? Entity :
+        T extends ObjectSchema ? ObjectToType<T> :
+        T extends StringSchema ? string :
+        T extends ArraySchema<infer U> ? ArrayToType<T, Schema.ToType<U>> :
+        T extends SetSchema<infer U> ? ReadonlySet<Schema.ToType<U>> :
+        T extends MapSchema<infer K, infer V> ? ReadonlyMap<Schema.ToType<K>, Schema.ToType<V>> :
+        T extends NumberSchema ? number :
+        T extends IntegerSchema ? number :
+        T extends BooleanSchema ? boolean :
+        T extends NullSchema ? null :
+        never;
+
+    /**
+     * The type schema `S` describes, as a plain type: `type Level = Schema.Type<{ type: "integer"; minimum: 0; maximum: 9 }>`
+     * is a `number`. Declarations naming such a type, directly or through aliases, get `S` as their schema from the
+     * build, so a named type carries its precision, width and bounds.
+     */
+    export type Type<S extends Schema> = ToType<S>;
+
+    /** The schemas whose `ToType` is `T`; constrains a schema to describe a known type. */
+    export type ForType<T> = Schema &
+    (
+        [T] extends [boolean] ? ForNonUnion<T> :
+        // A union of strings, such as an augmentable set of names, may also be described as any string.
+        IsUnion<T> extends true ? (OrSchema & { anyOf: readonly ForTypeEach<T>[] }) | ([T] extends [string] ? StringSchema : never) :
+        ForNonUnion<T>
+    );
+
+    type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+    type ForTypeEach<T> = T extends unknown ? ForType<T> : never;
+
+    type ForNonUnion<T> =
+        [T] extends [null] ? NullSchema :
+        [T] extends [true] ? ConstSchema & { const: T } :
+        [T] extends [false] ? ConstSchema & { const: T } :
+        [T] extends [boolean] ? BooleanSchema :
+        [T] extends [Entity] ? EntitySchema :
+        [T] extends [string] ? (string extends T ? StringSchema : ConstSchema & { const: T }) :
+        [T] extends [number] ? (NumberSchema | IntegerSchema) :
+        T extends readonly (infer U)[] ? ArraySchema<ForType<U> & Schema> :
+        T extends ReadonlyMap<infer K, infer V> ? MapSchema<ForType<K> & Schema, ForType<V> & Schema> :
+        T extends ReadonlySet<infer U> ? SetSchema<ForType<U> & Schema> :
+        // An optional property's schema describes its value when present.
+        T extends object ? ObjectSchema<Extract<keyof T, string>> & { properties: { [P in keyof T]-?: ForType<Exclude<T[P], undefined>> } } :
+        never;
+}

package/src/interface/schema/schema.type-test.ts

@@ -0,0 +1,155 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { IsStruct } from "./is-struct.js";
+import type { Schema } from "./schema.js";
+
+// Local copies of the standard compile-time assertion helpers.
+type Equal<X, Y> =
+    (<T>() => T extends X ? 1 : 2) extends
+    (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+// primitives
+check<Equal<Schema.ToType<{ type: 'string' }>, string>>();
+check<Equal<Schema.ToType<{ type: 'number' }>, number>>();
+check<Equal<Schema.ToType<{ type: 'integer' }>, number>>();
+check<Equal<Schema.ToType<{ type: 'boolean' }>, boolean>>();
+check<Equal<Schema.ToType<{ type: 'null' }>, null>>();
+
+// const narrows
+check<Equal<Schema.ToType<{ const: 'a' }>, 'a'>>();
+check<Equal<Schema.ToType<{ const: true }>, true>>();
+
+// standalone const accepts any JSON value
+check<Equal<Schema.ToType<{ const: 'x' }>, 'x'>>();
+check<Equal<Schema.ToType<{ const: readonly [1, 2] }>, readonly [1, 2]>>();
+const okConst: Schema = { const: { a: [1, 'b', null, { c: true }] } };
+// @ts-expect-error undefined is not a JSON value
+const badConstUndefined: Schema = { const: undefined };
+// @ts-expect-error functions are not JSON values
+const badConstFn: Schema = { const: () => 1 };
+// @ts-expect-error nested non-JSON values are rejected
+const badConstNested: Schema = { type: 'object', properties: {}, const: { a: undefined } };
+// @ts-expect-error `type` + `const` is redundant, not a valid Schema
+const badTypeAndConst: Schema = { type: 'boolean', const: true };
+// @ts-expect-error same when written `as const satisfies Schema`
+const badSatisfies = { type: 'boolean', const: true } as const satisfies Schema;
+void [badTypeAndConst, badSatisfies];
+void [okConst, badConstUndefined, badConstFn, badConstNested];
+
+// arrays
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' } }>, readonly number[]>>();
+
+// objects: all required when `required` is absent
+check<Equal<
+    Schema.ToType<{ type: 'object'; properties: { a: { type: 'number' }; b: { type: 'string' } } }>,
+    { readonly a: number; readonly b: string }
+>>();
+// objects: only listed keys required when `required` is present
+check<Equal<
+    Schema.ToType<{ type: 'object'; properties: { a: { type: 'number' }; b: { type: 'string' } }; required: ['a'] }>,
+    { readonly a: number; readonly b?: string }
+>>();
+
+// combinators
+check<Equal<Schema.ToType<{ anyOf: [{ type: 'string' }, { type: 'null' }] }>, string | null>>();
+check<Equal<
+    Schema.ToType<{ allOf: [
+        { type: 'object'; properties: { a: { type: 'number' } } },
+        { type: 'object'; properties: { b: { type: 'string' } } },
+    ] }>,
+    { readonly a: number } & { readonly b: string }
+>>();
+
+// ForType: accepts matching schemas, rejects mismatches
+const okNumber: Schema.ForType<number> = { type: 'integer' };
+const okNull: Schema.ForType<null> = { type: 'null' };
+const okUnion: Schema.ForType<string | null> = { anyOf: [{ type: 'string' }, { type: 'null' }] };
+const okArray: Schema.ForType<readonly string[]> = { type: 'array', items: { type: 'string' } };
+// @ts-expect-error string schema does not describe a number
+const badNumber: Schema.ForType<number> = { type: 'string' };
+// @ts-expect-error union members must describe a branch of the union
+const badUnion: Schema.ForType<string | null> = { anyOf: [{ type: 'number' }] };
+// @ts-expect-error array items must match
+const badArray: Schema.ForType<readonly string[]> = { type: 'array', items: { type: 'number' } };
+void [okNumber, okNull, okUnion, okArray, badNumber, badUnion, badArray];
+
+// every schema form is writable-free, so `as const` literals satisfy Schema
+const asConstObject = { type: 'object', properties: { a: { type: 'number' } }, required: ['a'] } as const satisfies Schema;
+const asConstAnyOf = { anyOf: [{ type: 'string' }, { type: 'null' }] } as const satisfies Schema;
+const asConstAllOf = { allOf: [{ type: 'object', properties: {} }, { const: 1 }] } as const satisfies Schema;
+const asConstArray = { type: 'array', items: { const: [1, { a: null }] } } as const satisfies Schema;
+check<Equal<Schema.ToType<typeof asConstObject>['a'], number>>();
+check<Equal<Schema.ToType<typeof asConstAnyOf>, string | null>>();
+void [asConstObject, asConstAnyOf, asConstAllOf, asConstArray];
+
+// fields are readonly
+declare const stringSchema: Extract<Schema, { type: 'string' }>;
+// @ts-expect-error schemas are immutable
+stringSchema.minLength = 1;
+declare const objectSchema: Extract<Schema, { type: 'object' }>;
+// @ts-expect-error properties are immutable
+objectSchema.properties = {};
+// @ts-expect-error required is a readonly array
+objectSchema.required?.push('x');
+
+// ForType<true> must not admit the redundant type + const form
+// @ts-expect-error redundant
+const badForTypeRedundant: Schema.ForType<true> = { type: 'boolean', const: true };
+void badForTypeRedundant;
+
+// ForType boolean literals: only the matching bare const schema
+const okTrue: Schema.ForType<true> = { const: true };
+const okFalse: Schema.ForType<false> = { const: false };
+const okBoolean: Schema.ForType<boolean> = { type: 'boolean' };
+// @ts-expect-error const false does not describe true
+const badTrue: Schema.ForType<true> = { const: false };
+// @ts-expect-error const true does not describe false
+const badFalse: Schema.ForType<false> = { const: true };
+// @ts-expect-error redundant type + const for false
+const badFalseRedundant: Schema.ForType<false> = { type: 'boolean', const: false };
+// @ts-expect-error a const schema is too narrow for plain boolean
+const badBoolean: Schema.ForType<boolean> = { const: true };
+// @ts-expect-error type without const is too wide for the literal
+const badTrueWide: Schema.ForType<true> = { type: 'boolean' };
+void [okTrue, okFalse, okBoolean, badTrue, badFalse, badFalseRedundant, badBoolean, badTrueWide];
+
+// fixed-length arrays are tuples; any other length is an array
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: 3; maxItems: 3 }>, readonly [number, number, number]>>();
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: 2; maxItems: 3 }>, readonly number[]>>();
+check<Equal<Schema.ToType<{ type: 'array'; items: { type: 'number' }; minItems: number; maxItems: number }>, readonly number[]>>();
+
+// sets and maps, forms JSON lacks, are read-only
+check<Equal<Schema.ToType<{ type: 'set'; items: { type: 'string' } }>, ReadonlySet<string>>>();
+check<Equal<Schema.ToType<{ type: 'map'; keys: { type: 'string' }; values: { type: 'array'; items: { type: 'number' } } }>, ReadonlyMap<string, readonly number[]>>>();
+check<Equal<Schema.ToType<{ type: 'object'; properties: { tags: { type: 'set'; items: { const: 'a' } } } }>, { readonly tags: ReadonlySet<'a'> }>>();
+const okSet: Schema.ForType<ReadonlySet<number>> = { type: 'set', items: { type: 'integer' } };
+const okMap: Schema.ForType<ReadonlyMap<string, boolean>> = { type: 'map', keys: { type: 'string' }, values: { type: 'boolean' } };
+// @ts-expect-error a set's items must match
+const badSet: Schema.ForType<ReadonlySet<number>> = { type: 'set', items: { type: 'string' } };
+// @ts-expect-error a map's values must match
+const badMap: Schema.ForType<ReadonlyMap<string, boolean>> = { type: 'map', keys: { type: 'string' }, values: { type: 'number' } };
+// @ts-expect-error a set has items, not keys and values
+const badSetForm: Schema = { type: 'set', keys: { type: 'string' }, values: { type: 'string' } };
+// @ts-expect-error a map has keys and values
+const badMapForm: Schema = { type: 'map', items: { type: 'string' } };
+void [okSet, okMap, badSet, badMap, badSetForm, badMapForm];
+
+// A set or map isn't a struct: neither lives in shared memory.
+check<Equal<IsStruct<ReadonlySet<number>>, false>>();
+check<Equal<IsStruct<ReadonlyMap<number, number>>, false>>();
+
+// Schema.Type is the plain type a schema describes, so a type named by it is that type: a number or a tuple, unbranded.
+type Level = Schema.Type<{ type: "integer"; minimum: 0; maximum: 9 }>;
+check<Equal<Level, number>>();
+check<Equal<Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 3; maxItems: 3 }>, readonly [number, number, number]>>();
+// @ts-expect-error its argument is a schema
+type NotSchema = Schema.Type<{ type: "integer"; minimum: "zero" }>;
+
+// A schema holds no default, anywhere: a value's start comes from its declaration or its type's namespace.
+// @ts-expect-error a default isn't part of a schema
+const badDefault: Schema = { type: 'number', default: 0 };
+// @ts-expect-error nor of a field's schema
+const badFieldDefault: Schema = { type: 'object', properties: { x: { type: 'number', default: 0 } } };
+// @ts-expect-error Schema.Type takes a schema, so a default fails there too
+type BadType = Schema.Type<{ type: 'integer'; minimum: 1; default: 5 }>;
+void [badDefault, badFieldDefault];

package/src/interface/schema/schemas.type-test.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "./schema.js";
+
+const ok: Schema.ForType<true> = { const: true };
+const okObj: Schema.ForType<{ readonly x: number; readonly tags: readonly string[] }> = {
+    type: 'object',
+    properties: { x: { type: 'number' }, tags: { type: 'array', items: { type: 'string' } } },
+};
+// @ts-expect-error string schema does not describe a number
+const bad: Schema.ForType<number> = { type: 'string' };
+// @ts-expect-error const must match the type
+const badConst: Schema.ForType<true> = { const: false };
+void [ok, okObj, bad, badConst];

package/src/interface/system/access.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { Condition } from '../resource/condition.js';
+import type { Index } from '../indexes/index-type.js';
+import type { Shared } from '../component/value.js';
+import type { ReadResources } from './body.js';
+
+/**
+ * The entities a system runs over: those with every component in `with`, `added` and `changed`, and none in `not`.
+ * What its body reads and writes of them the build infers from the body.
+ */
+export type ComponentAccess = {
+    readonly with?: readonly Component.Key[];
+    /** Components its rows hold where an entity has them, `undefined` where it doesn't; they never narrow what it matches. */
+    readonly optional?: readonly Component.Key[];
+    readonly not?: readonly Component.Key[];
+    /** Passes rows where any of these were added since the system last ran. */
+    readonly added?: readonly Component.Key[];
+    /** Passes rows where any of these may have changed since the system last ran. */
+    readonly changed?: readonly Component.Key[];
+    /**
+     * Keeps the system to the archetypes whose shared components' values pass, each one required as `with` requires
+     * it: a value passes the archetypes holding an equal one, a predicate those it returns true for. A predicate reads
+     * its value and the world's resources, never anything else that may change, and runs as written on the thread
+     * that runs the system, once per archetype as it appears and again whenever a resource it reads changed. With
+     * change filters, an archetype it skipped keeps its rows unseen until it passes again.
+     */
+    readonly where?: { readonly [K in Shared]?: Component.Value<K> | ((value: Component.Value<K>, context: { readonly resources: ReadResources }) => boolean) };
+};
+
+/**
+ * Read-only access to other entities: by entity, matching `with` and `not`, its `optional` components read where an
+ * entity has them, or through an index by key, whose rows hold what every entity the index holds has. What the body reads of them the build infers. A lookup by entity's
+ * `changed` names components in `with`, whose changes its row's `changed` reports, and an index lookup's those of its
+ * rows. Both report as a system's `changed` filter does; its system can't write a key part or what it reads.
+ */
+export type Lookup =
+    | { readonly with?: readonly Component.Key[]; readonly optional?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly changed?: readonly Component.Key[]; readonly index?: never }
+    | { readonly index: Index; readonly changed?: readonly Component.Key[]; readonly with?: never; readonly optional?: never; readonly not?: never };
+
+/**
+ * A system's lookup. An index lookup's `changed: true` makes the index a change filter, as a resource in `changed` is:
+ * every row passes when an entity entered or left the index, or moved to another key or position in it, since the
+ * system last ran. A system whose only change filters these are runs only then, skipped before its body otherwise, as
+ * when a condition fails, keeping its `lastRun`. Its lists' `changed` then reports those changes alone. Only on the
+ * world's thread.
+ */
+export type SystemLookup = Lookup | { readonly index: Index; readonly changed: true };
+
+/**
+ * The parent each row's values flow down from: the entity its `through` reference names, read before the row. Rows
+ * run parent first, so a parent's value is the one written earlier in the same run. The context's `up` holds the
+ * parent's values the body reads, or null for a row without a parent or whose parent lacks one of them.
+ */
+export type Up = { readonly through: Component.With<"reference"> };
+
+/** The resources a system filters and is conditioned on; what its body reads, writes and reduces the build infers. */
+export type ResourceAccess = {
+    /** Passes every row when any of these changed since the system last ran. */
+    readonly changed?: readonly Resource.Key[];
+    /** Runs only while each of these is neither `null` nor `false`, and reads it as such. Otherwise it's skipped, successfully. */
+    readonly is?: readonly Condition[];
+    /** Runs only while each of these is `null` or `false`. Otherwise it's skipped, successfully. */
+    readonly not?: readonly Condition[];
+};
+
+/** A key, as the world takes declarations: their lists come from the build, untyped. */
+type Key = symbol;
+
+/**
+ * What a system reads and writes, as the world takes it: the build's inferred access joined with its declaration.
+ * Matches every component in `read`, `write`, `has`, `added` and `changed` but those in `optional`, and excludes `not`.
+ */
+export type ComponentLists = {
+    /** Members its rows hold only where an entity has them; those it uses are in `read` or `write` too. */
+    readonly optional?: readonly Key[];
+    readonly read?: readonly Key[];
+    readonly write?: readonly Key[];
+    readonly has?: readonly Key[];
+    readonly not?: readonly Key[];
+    readonly added?: readonly Key[];
+    readonly changed?: readonly Key[];
+    /** Its `where`, by shared component: a value, or a predicate of it and the resources. Its keys are in `has` or `read`. */
+    readonly where?: { readonly [key: symbol]: unknown };
+    /** The resources its `where`'s predicates read, which the build infers: when one changed, they're evaluated again. */
+    readonly whereReads?: readonly Key[];
+};
+
+/** A lookup as the world takes it, with what its body reads of its rows in `read`. */
+export type LookupLists =
+    | { readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly optional?: readonly Key[]; readonly not?: readonly Key[]; readonly changed?: readonly Key[] }
+    | { readonly index: Index; readonly read?: readonly Key[]; readonly changed?: readonly Key[] };
+
+export type SystemLookupLists = LookupLists | { readonly index: Index; readonly read?: readonly Key[]; readonly changed: true };
+
+export type UpLists = { readonly through: Key; readonly read?: readonly Key[] };
+
+/** A system's resources as the world takes them. */
+export type ResourceLists = {
+    readonly read?: readonly Key[];
+    readonly write?: readonly Key[];
+    readonly reduce?: readonly Key[];
+    readonly changed?: readonly Key[];
+    readonly is?: readonly Key[];
+    readonly not?: readonly Key[];
+};