@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/component-default-fallback.ts

@@ -0,0 +1,236 @@
+// @forgeax/engine-ecs - Layer-3 default-value SSOT helper (feat-20260517-
+// spawn-default-fallback / M1).
+//
+// AI users: this file is the SINGLE PHYSICAL LOCATION of the layer-3
+// `typeDefault(fieldType)` table. Three runtime paths consume it (D-2
+// / plan-strategy §2.1 / AC-05):
+//
+//   - `world.spawn(...)`               (M2 — t9)
+//   - `world.addComponent(...)`        (M2 — t9, ComponentData<S> shared)
+//
+// Two-layer split (D-3 / plan-strategy §2.2 — DELIBERATELY NOT MERGED):
+//
+//   layer-3 (this file)
+//     "raw value fallback" — fills missing schema fields with the
+//     spawn-data raw shape: 0 / false / ENTITY_NULL_RAW / [] / 0 (slot
+//     id placeholder). The output is the input shape `world.spawn`
+//     receives (`Partial<ShapeOf<S>>` -> `Record<string, unknown>` with
+//     all schema keys present).
+//
+//   layer-4 (silent fallback inside writeRow / write{Buffer,Array,
+//            UniqueRef}Field)
+//     "column-store value fallback" — when raw === 0 hits a managed-
+//     family arm (string / unique<T> / buffer / buffer<N> / array<T> for
+//     T != entity), the column store routes 0 to "empty slot" semantics
+//     (UniqueRefStore handle 0 / BufferPool slot 0 / array slot
+//     length === 0). The two layers are NEVER merged — layer-3 stays
+//     pure / unaware of column physics; layer-4 stays inside writeRow
+//     where the column instance is in scope.
+//
+// The 14-vocab x default-value table (AC-06 closed table, grep-gate t2
+// keyword "layer-3 typeDefault table"):
+//
+//   ScalarFieldType (11 arms):
+//     f32 / f64 / i32 / u32 / i16 / u16 / i8 / u8       -> 0
+//     bool                                              -> false
+//     enum / ref (legacy scalar)                        -> 0
+//
+//   SchemaVocabKeyword (8 arms; one "buffer" + one "buffer<N>"; one
+//   "ref<T>" + one "handle<T>"; one "entity" + one "string"; two array
+//   variants — array<T,N> / array<T> — collapse to two table arms:
+//     'string'                  -> 0  (uniqueRefs handle slot;
+//                                       resolved payload '' on read)
+//     'entity'                  -> ENTITY_NULL_RAW (NULL_ENTITY u32
+//                                       = 0xffffffff)
+//     'array<entity>'           -> []  (THE ONLY array<T> arm with []
+//                                       — entity[] runtime shape is a
+//                                       JS array of Entity, not a
+//                                       BufferPool slot id)
+//     'array<T>'  (T != entity) -> 0  (BufferPool slot id; layer-4
+//                                       writeArrayField bottoms out to
+//                                       empty slot — D-2 asymmetric;
+//                                       SceneAsset byte-equivalence,
+//                                       OOS-6 letter)
+//     'array<T, N>' (any T)     -> 0  (inline stride-N column,
+//                                       feat-20260602; fallback writes the
+//                                       zeroed row, not a slot id)
+//     'buffer'                  -> 0  (BufferPool slot id; variable
+//                                       byte capacity)
+//     'buffer<N>'               -> 0  (inline stride-N u8 column,
+//                                       feat-20260602; fallback writes the
+//                                       zeroed row, not a slot id)
+//     'unique<T>'                  -> 0  (UniqueRefStore handle slot)
+//     'handle<T>'               -> 0  (unmanaged handle phantom u32;
+//                                       schema-level nullable -> NULL
+//                                       sentinel 0)
+//
+// Brand-class semantics (AC-10 / requirements §A-3 reframe round 2):
+// `handle<T>` and `ref<T>` are SCHEMA-LEVEL nullable. Spawn `data: {}`
+// is legal; layer-3 fills 0 (NULL sentinel for unmanaged handles) /
+// 0 (uniqueRefs handle slot, '' payload). SceneAsset.instantiate
+// produces byte-equivalent column state.
+//
+// Anchors:
+//   - requirements §AC-05 (helper SSOT) + §AC-06 (closed 14-vocab table)
+//     + §AC-09 (SceneAsset byte-equiv) + §AC-10 (brand-class nullable)
+//   - plan-strategy §2.1 (helper file location decision)
+//             §2.2 (two-layer split JSDoc declaration)
+//             §2.3 (array<T> T!=entity asymmetric raw 0)
+//             §3.1 (helper node in component graph)
+//             §8.2 (naming rules: fillComponentDefaults / typeDefault)
+//             §8.4 (head JSDoc as discovery anchor)
+
+import type { Component, ComponentSchema } from './component';
+import { componentSchema } from './component';
+import { componentDefinition } from './component-schema';
+import { ENTITY_NULL_RAW } from './entity-handle';
+import { SpawnDataUnknownFieldError } from './errors';
+
+/**
+ * Layer-3 silent default for a single schema field type. Returned when
+ * the spawn-data raw input (layer 1) and the owner definition defaults
+ * map (layer 2) both omit a known schema field.
+ *
+ * Pure function — runs once per missing field per (component, spawn /
+ * instantiate) call. No `BufferPool` / `UniqueRefStore` / `World`
+ * dependency: the helper hands back raw column-shape values (u32 / bool
+ * / number array literal); the layer-4 silent fallback inside
+ * `writeRow` / `write{Buffer,Array,UniqueRef}Field` turns raw `0` into
+ * the live column-store value (unique-ref handle 0 / BufferPool slot
+ * id 0 / array slot length 0).
+ *
+ * Mapping is the same closed table the head-JSDoc table documents.
+ *
+ * @internal — helper-private; AI users call `fillComponentDefaults`.
+ */
+function typeDefault(fieldType: string): unknown {
+  // bool is the only scalar arm with a non-zero default.
+  if (fieldType === 'bool') return false;
+  // 'entity' uses the runtime NULL_ENTITY sentinel (0xffffffff).
+  if (fieldType === 'entity') return ENTITY_NULL_RAW;
+  // 'array<entity>' is the only array<T> arm whose layer-3 default is a
+  // JS array literal — entity[] runtime shape is a JS Array<Entity>,
+  // not a BufferPool slot id (D-2 asymmetric pivot).
+  if (fieldType === 'array<entity>') return [];
+  // every other vocab keyword (incl. 'string' / 'unique<T>' / 'handle<T>'
+  // / 'buffer' / 'buffer<N>' / 'array<T>' (T!=entity) / 'array<T, N>')
+  // and every remaining ScalarFieldType (f* / i* / u* / enum / ref)
+  // defaults to numeric 0 at the spawn-data raw surface. Layer-4
+  // silent fallback inside writeRow turns 0 into the empty-slot
+  // shape on the column-store side when applicable.
+  return 0;
+}
+
+/**
+ * Fill missing schema fields on a partial spawn-data raw with their
+ * layer-2 / layer-3 defaults. Public surface used by:
+ *
+ *   - `World.spawn`                            (writeRow entry, M2)
+ *   - `World.addComponent`                     (writeRow entry, M2)
+ *
+ * Resolution order (matches scene-instance-container.ts JSDoc):
+ *
+ *   layer 1 — explicit raw value (caller passed `data[field] = v`).
+ *             Carrier: the raw input itself; not handled by this
+ *             helper — copied through the `if (key in raw)` branch.
+ *             SceneAsset.instantiate additionally remaps `entity` /
+ *             `array<entity>` LocalEntityId values BEFORE handing the raw
+ *             to the helper (the entity-remap layer is NOT this
+ *             helper's responsibility).
+ *
+ *   layer 2 — owner definition defaults (declared via
+ *             `defineComponent(name, schema, { defaults })`). Layer-2
+ *             defaults beat layer-3.
+ *
+ *   layer 3 — `typeDefault(fieldType)` (this file's private dispatch).
+ *
+ * Returns a fresh `Record<string, unknown>` carrying every schema
+ * field. The output is column-shape raw — the caller's writeRow path
+ * walks it field-by-field and applies layer-4 silent fallback when a
+ * raw `0` lands on a managed-family arm.
+ *
+ * Pure: no World / store side effect. Thread-safety irrelevant (single-
+ * thread JS engine), but the helper allocates one `Object.create(null)`
+ * per call so repeated invocations cannot share a mutable record.
+ *
+ * @param token  Component token (name + schema + optional defaults).
+ * @param raw    Partial spawn-data raw — caller's `Partial<ShapeOf<S>>`.
+ *               Keys not present in the schema are passed through
+ *               unchanged (the spawn write path will emit a write-time
+ *               error if applicable; helper does not validate keys).
+ * @returns      Record with every schema field populated by layer-1 /
+ *               layer-2 / layer-3 defaults in that order.
+ */
+export function fillComponentDefaults<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+): Record<string, unknown> {
+  const schema = componentSchema(token) as Record<string, string>;
+  const layer2 = componentDefinition(token).defaults;
+  const out: Record<string, unknown> = Object.create(null);
+  const rawObj = (raw as Record<string, unknown> | undefined) ?? undefined;
+  for (const fieldName of Object.keys(schema)) {
+    const fieldType = schema[fieldName];
+    if (fieldType === undefined) continue;
+    // layer 1 — explicit raw value (caller may pass undefined to mean
+    // "use default"; mirror the existing scene-instance-container
+    // behaviour where the gate is `fieldName in raw`).
+    if (rawObj !== undefined && fieldName in rawObj) {
+      out[fieldName] = rawObj[fieldName];
+      continue;
+    }
+    // layer 2 — component-level defaults map.
+    if (layer2 !== undefined && fieldName in layer2) {
+      out[fieldName] = layer2[fieldName];
+      continue;
+    }
+    // layer 3 — TS type defaults (silent — no error code).
+    out[fieldName] = typeDefault(fieldType);
+  }
+  return out;
+}
+
+// Re-export the private dispatch for unit-test introspection (t1
+// keyword pin — every vocab arm gets a one-liner it() block). The
+// helper-private arity is preserved at callers via the
+// `fillComponentDefaults` boundary.
+export { typeDefault };
+
+/**
+ * Validate that every key in `raw` is a declared schema field on `token`.
+ *
+ * Returned as a `SpawnDataUnknownFieldError` on the FIRST offending key
+ * (deterministic for AI users; subsequent unknown keys surface on the next
+ * spawn after the first is fixed). Pre-fix the unknown key was silently
+ * dropped inside `fillComponentDefaults` (which iterates only schema keys),
+ * routing typos like `MeshRenderer { material }` (singular legacy field name)
+ * into the empty-default path and producing invisible / mid-grey entities
+ * downstream.
+ *
+ * Pure: no World / store side effect; allocates no closure on the hot path
+ * (early-returns null when raw is undefined / empty).
+ *
+ * Call order at every spawn / addComponent / SceneAsset.instantiate /
+ * Commands.spawn site: validate FIRST, then `fillComponentDefaults`. The
+ * split keeps `fillComponentDefaults` pure (charter P3 SSOT — a fill helper
+ * never validates) while every layer-1 raw key reaches one validator gate.
+ *
+ * @param token  Component token (name + schema).
+ * @param raw    Caller's `Partial<ShapeOf<S>>` — raw spawn payload.
+ * @returns      `null` on success; `SpawnDataUnknownFieldError` on the first
+ *               key not declared in `componentSchema(token)`.
+ */
+export function validateComponentDataKeys<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+): SpawnDataUnknownFieldError | null {
+  if (raw === undefined) return null;
+  const schema = componentSchema(token) as Record<string, unknown>;
+  const rawObj = raw as Record<string, unknown>;
+  for (const fieldName of Object.keys(rawObj)) {
+    if (!(fieldName in schema)) {
+      return new SpawnDataUnknownFieldError(token.name, fieldName, Object.keys(schema));
+    }
+  }
+  return null;
+}

package/src/component-schema.ts

@@ -0,0 +1,92 @@
+import type { Component, FieldReflection, SchemaFieldType } from './component';
+
+/** The complete storage placement vocabulary owned by ECS schema. */
+export type ComponentStorageKind = 'table' | 'sparse';
+
+/** The stable public facts needed to describe a component schema offline. */
+export interface ComponentSchemaDefinition {
+  readonly name: string;
+  readonly fields: Readonly<Record<string, SchemaFieldType>>;
+  readonly storage: ComponentStorageKind;
+}
+
+/**
+ * Serialization facts owned beside schema registration, not carried by the
+ * public component token. Queries and storage only need the token's schema
+ * vocabulary; domain validation and lifecycle belong to their owners.
+ */
+export interface ComponentPolicy {
+  readonly transient: boolean;
+  readonly meta: Record<string, unknown>;
+}
+
+/** Immutable schema reflection plus non-token policy projection. */
+export interface ComponentDefinition {
+  readonly fields: Readonly<Record<string, FieldReflection>>;
+  readonly defaults: Readonly<Record<string, unknown>> | undefined;
+  readonly policy: ComponentPolicy;
+}
+
+// Component tokens can cross independently bundled ECS entry points. Share
+// the owner registry through globalThis rather than attaching a hidden symbol
+// to each token; `Reflect.ownKeys(token)` must remain exactly the three public
+// facts name/fields/storage.
+const COMPONENT_REGISTRY = Symbol.for('forgeax.ecs.componentRegistry');
+interface ComponentRegistry {
+  readonly definitions: WeakMap<object, ComponentDefinition>;
+}
+const globalSymbols = globalThis as typeof globalThis & { [key: symbol]: unknown };
+const definitions =
+  (globalSymbols[COMPONENT_REGISTRY] as ComponentRegistry | undefined) ??
+  (() => {
+    const registry: ComponentRegistry = { definitions: new WeakMap<object, ComponentDefinition>() };
+    globalSymbols[COMPONENT_REGISTRY] = registry;
+    return registry;
+  })();
+
+export function registerComponentDefinition(
+  component: Component,
+  definition: ComponentDefinition,
+): void {
+  definitions.definitions.set(component, definition);
+}
+
+/** Read the definition-time schema/policy projection for a component token. */
+export function componentDefinition(component: Component): ComponentDefinition {
+  const definition = definitions.definitions.get(component);
+  if (definition === undefined) {
+    throw new Error(`Component definition missing for '${component.name}'.`);
+  }
+  return definition;
+}
+
+/**
+ * Freeze a schema value recursively.  Component descriptors are authored data,
+ * so nested defaults and enum label maps must not become mutation channels.
+ */
+export function deepFreeze<T>(value: T): Readonly<T> {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+    return value as Readonly<T>;
+  }
+  // Non-empty TypedArrays reject Object.freeze and their indexed elements
+  // remain writable even when the wrapper is frozen. Treat binary views as
+  // immutable leaf projections; the authored descriptor around them is still
+  // recursively frozen by this function.
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return value as Readonly<T>;
+  }
+  const object = value as object;
+  for (const key of Reflect.ownKeys(object)) {
+    const child = (object as Record<PropertyKey, unknown>)[key];
+    if (child !== null && (typeof child === 'object' || typeof child === 'function')) {
+      deepFreeze(child);
+    }
+  }
+  return Object.freeze(value) as Readonly<T>;
+}
+
+export function assertComponentStorage(value: string): asserts value is ComponentStorageKind {
+  if (value !== 'table' && value !== 'sparse') {
+    throw new Error(`Unsupported component storage '${value}'. Expected 'table' or 'sparse'.`);
+  }
+}

package/src/component-value-validate.ts

@@ -0,0 +1,135 @@
+// feat-20260713-mount-override-component-add-and-shared-ref-round M2 / w9 —
+// P3 shared-field value gate.
+//
+// `validateComponentDataKeys` (component-default-fallback.ts) checks that every
+// key in a spawn / addComponent / set payload is a declared schema field. It
+// does NOT check value TYPES. A `shared<T>` scalar / `array<shared<T>>` element
+// must be a resolved numeric Handle; a raw GUID string / `{ guid }` / `{ kind }`
+// object (the pre-resolution shape a sidecar hands an AI user) was silently
+// coerced to the all-zero sentinel by the column packer
+// (`typed[i] = typeof val === 'number' ? val : 0`) / scalar write path, so a
+// mis-bound reference read back as `0` / `[0,0,0,0]` and rendered blank with no
+// error.
+//
+// This module closes that value-type gap. It is a pure validator (no World /
+// store side effect) invoked at all three write entries (spawn / addComponent /
+// set) BEFORE any archetype mutation, mirroring the validate-first ordering of
+// `validateComponentDataKeys`. §2.5: it depends only on the schema field-type
+// SHAPE (`shared<...>` / `array<shared<...>>`), never on any GUID / asset
+// concretion — the GUID domain stays sealed in assets-runtime; ecs only sees a
+// numeric handle vs a non-handle.
+
+import type { Component, ComponentSchema } from './component';
+import { componentSchema } from './component';
+import { componentDefinition } from './component-schema';
+import { ManagedArrayInvalidValueError, SharedFieldInvalidValueError } from './errors';
+
+/** A resolved shared handle is a plain number (the branded Handle bit pattern). */
+function isNumericHandle(v: unknown): boolean {
+  return typeof v === 'number';
+}
+
+/** `shared<T>` scalar field type. */
+function isSharedScalarType(fieldType: string): boolean {
+  return fieldType.startsWith('shared<') && fieldType.endsWith('>');
+}
+
+/**
+ * `array<shared<T>>` / `array<shared<T>, N>` field type. The inner element type
+ * is a `shared<...>` template; we test the array wrapper and the `shared<`
+ * infix rather than fully re-parsing (parseManagedArraySchema owns the strict
+ * grammar — here we only need the coarse "is this an array of shared refs"
+ * discriminant).
+ */
+function isSharedArrayType(fieldType: string): boolean {
+  if (!fieldType.startsWith('array<') || !fieldType.endsWith('>')) return false;
+  const inner = fieldType.slice(6, -1);
+  const head = inner.indexOf(',') === -1 ? inner : inner.slice(0, inner.indexOf(',')).trim();
+  return head.startsWith('shared<') && head.endsWith('>');
+}
+
+function isArrayPayload(value: unknown): boolean {
+  if (Array.isArray(value)) return true;
+  // DataView and ArrayBuffer are views/buffers without an element `length`;
+  // the storage writer cannot interpret them as a managed array payload.
+  return ArrayBuffer.isView(value) && typeof (value as { length?: unknown }).length === 'number';
+}
+
+/**
+ * Validate the outer value shape for every managed `array<T>` field present in
+ * a write payload. This is deliberately a preflight-only check: element
+ * coercion remains owned by the column writer, while arbitrary objects are
+ * rejected before any row, buffer slot, retain, or epoch mutation can occur.
+ */
+export function validateManagedArrayValues<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+): ManagedArrayInvalidValueError | null {
+  if (raw === undefined) return null;
+  const fields = componentDefinition(token).fields as Readonly<
+    Record<string, { readonly type: string; readonly arrayMeta?: unknown }>
+  >;
+  const rawObj = raw as Record<string, unknown>;
+  for (const fieldName of Object.keys(rawObj)) {
+    const reflection = fields[fieldName];
+    if (reflection?.arrayMeta === undefined) continue;
+    const value = rawObj[fieldName];
+    // `fillComponentDefaults` deliberately uses numeric zero as the layer-3
+    // raw sentinel for every non-entity array vocabulary. The column writer
+    // owns translating that sentinel into an empty variable slot or a
+    // zero-filled fixed row, so it must pass this preflight just like an
+    // omitted/null value. Other scalar/object values remain invalid.
+    if (value === 0) continue;
+    if (value === undefined || value === null || isArrayPayload(value)) continue;
+    return new ManagedArrayInvalidValueError(token.name, fieldName, reflection.type, value);
+  }
+  return null;
+}
+
+/**
+ * Validate that every `shared<T>` scalar / `array<shared<T>>` element present in
+ * `raw` is a resolved numeric Handle. Returns the FIRST offending field's
+ * `SharedFieldInvalidValueError` (deterministic for AI users), or `null` on
+ * success.
+ *
+ * Pure: no World / store side effect. Only fields PRESENT in `raw` are checked
+ * (an omitted shared field takes its schema default — a numeric sentinel — via
+ * `fillComponentDefaults`, so it is never a non-handle). `undefined` / `null`
+ * values are treated as "omitted" (the write path routes them to the sentinel
+ * intentionally); only a concrete non-numeric value (string / object) is a
+ * mis-bound GUID and fails fast.
+ *
+ * @param token  Component token (name + schema).
+ * @param raw    Caller's raw payload (spawn / addComponent / set value).
+ * @returns      `null` on success; `SharedFieldInvalidValueError` on the first
+ *               shared field bound to a non-handle value.
+ */
+export function validateSharedFieldValues<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+): SharedFieldInvalidValueError | null {
+  if (raw === undefined) return null;
+  const schema = componentSchema(token) as Record<string, string>;
+  const rawObj = raw as Record<string, unknown>;
+  for (const fieldName of Object.keys(rawObj)) {
+    const fieldType = schema[fieldName];
+    if (fieldType === undefined) continue; // key validation owns unknown keys.
+    const value = rawObj[fieldName];
+    if (value === undefined || value === null) continue; // omitted -> sentinel default.
+    if (isSharedScalarType(fieldType)) {
+      if (!isNumericHandle(value)) {
+        return new SharedFieldInvalidValueError(token.name, fieldName, fieldType, value);
+      }
+    } else if (isSharedArrayType(fieldType)) {
+      if (!Array.isArray(value)) continue; // non-array raw for an array field: write path no-ops.
+      for (let i = 0; i < value.length; i++) {
+        const el = value[i];
+        if (el === undefined || el === null) continue;
+        if (!isNumericHandle(el)) {
+          return new SharedFieldInvalidValueError(token.name, fieldName, fieldType, el, i);
+        }
+      }
+    }
+  }
+  return null;
+}