@woosh/meep-engine 3.23.0 → 3.25.0

package/src/core/collection/map/u32_index.js

@@ -0,0 +1,247 @@
+import { assert } from "../../assert.js";
+import { isPowerOfTwo } from "../../math/isPowerOfTwo.js";
+import { lowbias32 } from "../../math/hash/lowbias32.js";
+import { generate_next_linear_congruential_index } from "./generate_next_linear_congruential_index.js";
+
+/**
+ * What {@link u32_index_get} returns for a key the index does not hold.
+ *
+ * Also what a key holding the value `-1` reads back as — the two are deliberately
+ * indistinguishable, which is what lets a caller retire a key without the index needing tombstones.
+ * See {@link u32_index_set}.
+ *
+ * @type {number}
+ */
+export const U32_INDEX_MISS = -1;
+
+/**
+ * `[count, slots]`, then `slots` pairs of `[encoded_key, value]`. Two words rather than one so the
+ * pairs stay 8-byte aligned.
+ * @type {number}
+ */
+const HEADER_WORDS = 2;
+
+const COUNT_WORD = 0;
+const SLOTS_WORD = 1;
+
+/**
+ * Smallest table. Small enough that a table holding a handful of keys is not mostly hole, large
+ * enough that {@link MAX_LOAD_NUMERATOR} leaves slack at this size too.
+ * @type {number}
+ */
+const MIN_SLOTS = 16;
+
+// Grow past 3/5 occupancy. The slack is not only about probe cost: it is what makes the probe
+// terminate at all — see the module docs on u32_index_get.
+const MAX_LOAD_NUMERATOR = 3;
+const MAX_LOAD_DENOMINATOR = 5;
+
+/**
+ * An open-addressed `u32 -> i32` index in a single `Uint32Array`, as free functions over the array
+ * rather than an object wrapping it. Nothing per entry is allocated, so an index that has reached
+ * its working size costs the garbage collector nothing at all; a `Map<number,number>` doing the
+ * same work allocates a fresh backing store every time it is cleared.
+ *
+ * **Keys** are `u32` and stored as `key + 1`, so a zero word is an empty slot and a freshly
+ * allocated array is already a valid empty index — {@link u32_index_clear} is one `fill(0)`, and
+ * creation needs no fill at all. `0xFFFFFFFF` is therefore not a usable key.
+ *
+ * **Values** are `i32`. A caller storing `-1` makes the key read back as {@link U32_INDEX_MISS},
+ * which is how a key is retired: the slot stays claimed, and no tombstone state has to exist for
+ * the probe to step over. Values are not otherwise interpreted.
+ *
+ * The probe is {@link generate_next_linear_congruential_index}, which is full-cycle over a
+ * power-of-two table — it visits every slot before repeating. Combined with the load factor, which
+ * guarantees at least one empty slot at all times, **the probe terminates by construction** and
+ * neither lookup nor insert carries a step limit. Both properties are load-bearing: a table
+ * allowed to fill would let a lookup for an absent key run forever.
+ *
+ * Sized for a key set that turns over completely each frame — build it up, clear it, build it
+ * again — which is what the GPU table upload streams do with it.
+ *
+ * @see cpu_build_hash_table for the same layout in a table the GPU also reads, where the probe
+ * count is instead bounded to match a WGSL twin that cannot grow.
+ */
+
+/**
+ * A new empty index.
+ *
+ * @param {number} [slots] power of two, rounded up to {@link MIN_SLOTS}
+ * @returns {Uint32Array}
+ */
+export function u32_index_create(slots = MIN_SLOTS) {
+    assert.isNonNegativeInteger(slots, 'slots');
+    assert.ok(isPowerOfTwo(slots), `slots must be a power of two, got ${slots}`);
+
+    const size = Math.max(MIN_SLOTS, slots);
+
+    // zero-filled by construction, and a zero key word means empty
+    const table = new Uint32Array(HEADER_WORDS + size * 2);
+
+    table[SLOTS_WORD] = size;
+
+    return table;
+}
+
+/**
+ * How many keys the index holds, retired ones included.
+ *
+ * @param {Uint32Array} table
+ * @returns {number}
+ */
+export function u32_index_count(table) {
+    return table[COUNT_WORD];
+}
+
+/**
+ * The value stored for a key, or {@link U32_INDEX_MISS} if the index does not hold it — or holds
+ * it retired.
+ *
+ * @param {Uint32Array} table
+ * @param {number} key
+ * @returns {number} i32
+ */
+export function u32_index_get(table, key) {
+    const mask = table[SLOTS_WORD] - 1;
+    const encoded = key + 1;
+
+    let slot = lowbias32(key) & mask;
+
+    for (; ;) {
+        const address = HEADER_WORDS + slot * 2;
+        const candidate = table[address];
+
+        if (candidate === 0) {
+            // an empty slot is always reached, because the table is never full
+            return U32_INDEX_MISS;
+        }
+
+        if (candidate === encoded) {
+            return table[address + 1] | 0;
+        }
+
+        slot = generate_next_linear_congruential_index(slot, mask);
+    }
+}
+
+/**
+ * Store a value for a key, replacing whatever the key held.
+ *
+ * Storing `-1` retires the key: it keeps its slot, and {@link u32_index_get} reports it as
+ * {@link U32_INDEX_MISS} from then on. That is the whole of the delete story — an open-addressed
+ * table cannot simply blank a slot without cutting the probe chains that run through it, and the
+ * callers that need removal only ever need the key to stop being found.
+ *
+ * Returns the index to store back: growing reallocates, so the array this hands back is not always
+ * the one it was given. Passing `null` creates one.
+ *
+ * @param {Uint32Array|null} table
+ * @param {number} key
+ * @param {number} value i32
+ * @returns {Uint32Array} the index to keep
+ */
+export function u32_index_set(table, key, value) {
+    if (table === null) {
+        table = u32_index_create();
+    }
+
+    const slots = table[SLOTS_WORD];
+    const mask = slots - 1;
+    const encoded = key + 1;
+
+    let slot = lowbias32(key) & mask;
+
+    for (; ;) {
+        const address = HEADER_WORDS + slot * 2;
+        const candidate = table[address];
+
+        if (candidate === encoded) {
+            table[address + 1] = value;
+
+            return table;
+        }
+
+        if (candidate === 0) {
+            table[address] = encoded;
+            table[address + 1] = value;
+
+            const count = table[COUNT_WORD] + 1;
+
+            table[COUNT_WORD] = count;
+
+            if (count * MAX_LOAD_DENOMINATOR > slots * MAX_LOAD_NUMERATOR) {
+                return u32_index_grow(table);
+            }
+
+            // the invariant every probe above rests on
+            assert.ok(count < slots, `index is full — a lookup for an absent key would not terminate`);
+
+            return table;
+        }
+
+        slot = generate_next_linear_congruential_index(slot, mask);
+    }
+}
+
+/**
+ * Drop every key, keeping the allocation. The index is reusable immediately.
+ *
+ * @param {Uint32Array} table
+ */
+export function u32_index_clear(table) {
+    const slots = table[SLOTS_WORD];
+
+    table.fill(0);
+
+    table[SLOTS_WORD] = slots;
+}
+
+/**
+ * Twice the slots, every live key rehashed into them.
+ *
+ * @param {Uint32Array} table
+ * @returns {Uint32Array}
+ */
+function u32_index_grow(table) {
+    const slots = table[SLOTS_WORD];
+
+    const grown = u32_index_create(slots * 2);
+
+    for (let i = 0; i < slots; i++) {
+        const address = HEADER_WORDS + i * 2;
+        const encoded = table[address];
+
+        if (encoded !== 0) {
+            // the raw word, not `| 0` — a retired key stays retired across a rehash
+            u32_index_place(grown, encoded, table[address + 1]);
+        }
+    }
+
+    return grown;
+}
+
+/**
+ * Claim a slot for a key known to be absent, without touching the load factor check. Only safe
+ * during a rehash, where the destination is half empty by construction and the source held no
+ * duplicates.
+ *
+ * @param {Uint32Array} table
+ * @param {number} encoded already `key + 1`
+ * @param {number} value raw word
+ */
+function u32_index_place(table, encoded, value) {
+    const mask = table[SLOTS_WORD] - 1;
+
+    let slot = lowbias32(encoded - 1) & mask;
+
+    while (table[HEADER_WORDS + slot * 2] !== 0) {
+        slot = generate_next_linear_congruential_index(slot, mask);
+    }
+
+    const address = HEADER_WORDS + slot * 2;
+
+    table[address] = encoded;
+    table[address + 1] = value;
+
+    table[COUNT_WORD] = table[COUNT_WORD] + 1;
+}

package/src/engine/asset/loaders/GLTFSceneBundleAssetLoader.d.ts

@@ -3,8 +3,8 @@
  * holding the scene roots, the skins and the clips that came out of the one file.
  *
  * The asset hands out **that same bundle** to every caller rather than a copy. A bundle is the model
- * as loaded, not a placement of it, and the private copy a placement needs is made by
- * {@link instantiate_scene_bundle} — which is what makes two of one model possible at all. A level
+ * as loaded, not a placement of it: a placement is `prefab_instantiate` over the `Prefab` compiled
+ * from it once — which is what makes two of one model possible at all. A level
  * places the same model hundreds of times over, and copying at this level would be the dominant cost
  * of opening one.
  *

package/src/engine/asset/loaders/GLTFSceneBundleAssetLoader.js

@@ -7,8 +7,8 @@ import { AssetLoader } from "./AssetLoader.js";
  * holding the scene roots, the skins and the clips that came out of the one file.
  *
  * The asset hands out **that same bundle** to every caller rather than a copy. A bundle is the model
- * as loaded, not a placement of it, and the private copy a placement needs is made by
- * {@link instantiate_scene_bundle} — which is what makes two of one model possible at all. A level
+ * as loaded, not a placement of it: a placement is `prefab_instantiate` over the `Prefab` compiled
+ * from it once — which is what makes two of one model possible at all. A level
  * places the same model hundreds of times over, and copying at this level would be the dominant cost
  * of opening one.
  *

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.d.ts

@@ -14,7 +14,7 @@
  *
  * The asset hands out **that same bundle** to every caller rather than a copy, for the reason
  * {@link GLTFSceneBundleAssetLoader} gives: a bundle is the model as loaded, not a placement of it,
- * and {@link instantiate_scene_bundle} is what makes a placement's private copy.
+ * and `prefab_instantiate` over the prefab compiled from it is what makes a placement.
  *
  * @extends AssetLoader<*, SceneBundle>
  */
@@ -41,7 +41,6 @@ export class USDSceneBundleAssetLoader extends AssetLoader<any, SceneBundle> {
      */
     load(scope: AssetRequestScope, path: string, success: (arg0: Asset<any>) => void, failure: Function, progress: (arg0: number, arg1: number) => void): Promise<Asset<any>>;
 }
-import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
 import { AssetLoader } from "./AssetLoader.js";
 import { Asset } from "../Asset.js";
 //# sourceMappingURL=USDSceneBundleAssetLoader.d.ts.map

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"USDSceneBundleAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/loaders/USDSceneBundleAssetLoader.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;IAEI;;;;;;;;OAQG;IACH,6DAOC;IAED;;;;;;;;OAQG;IACH,qCAPW,MAAM,iCACW,IAAI,sCAEZ,MAAM,QAAE,MAAM,KAAG,IAAI,GAE5B,mBAAc,CAgD1B;CACJ;4BAtG2B,+CAA+C;4BAI/C,kBAAkB;sBAHxB,aAAa"}
+{"version":3,"file":"USDSceneBundleAssetLoader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/asset/loaders/USDSceneBundleAssetLoader.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;IAEI;;;;;;;;OAQG;IACH,6DAOC;IAED;;;;;;;;OAQG;IACH,qCAPW,MAAM,iCACW,IAAI,sCAEZ,MAAM,QAAE,MAAM,KAAG,IAAI,GAE5B,mBAAc,CAyC1B;CACJ;4BA3F2B,kBAAkB;sBAHxB,aAAa"}

package/src/engine/asset/loaders/USDSceneBundleAssetLoader.js

@@ -1,5 +1,4 @@
 import { load_usd } from "../../../shade/renderer/loader/usd/load_usd.js";
-import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
 import { Asset } from "../Asset.js";
 import { GameAssetType } from "../GameAssetType.js";
 import { ArrayBufferLoader } from "./ArrayBufferLoader.js";
@@ -21,7 +20,7 @@ import { AssetLoader } from "./AssetLoader.js";
  *
  * The asset hands out **that same bundle** to every caller rather than a copy, for the reason
  * {@link GLTFSceneBundleAssetLoader} gives: a bundle is the model as loaded, not a placement of it,
- * and {@link instantiate_scene_bundle} is what makes a placement's private copy.
+ * and `prefab_instantiate` over the prefab compiled from it is what makes a placement.
  *
  * @extends AssetLoader<*, SceneBundle>
  */
@@ -76,19 +75,12 @@ export class USDSceneBundleAssetLoader extends AssetLoader {
          when none of them match: a text layer behind a byte order mark, or a `.usd` that is text by
          convention. Passing the whole path is fine, the detection takes the extension off it.
         */
-        const roots = await load_usd(buffer, { fileName: path });
-
-        const bundle = new SceneBundle();
-
-        bundle.scenes = roots;
-
         /*
          `usd_build_scene` produces neither skins nor clips: UsdSkel and the time-sampled attributes a
-         clip would come from are not read. Empty is the truth about what came out of the file, not a
-         placeholder — when USD animation lands, it lands by filling these in.
+         clip would come from are not read. The bundle's empty lists are the truth about what came
+         out of the file, not a placeholder — when USD animation lands, it lands by filling them in.
         */
-        bundle.skins = [];
-        bundle.clips = [];
+        const bundle = await load_usd(buffer, { fileName: path });
 
         /*
          There is no honest byte size to report, for the reason {@link GLTFSceneBundleAssetLoader}

package/src/engine/ecs/gpu/GPUStateAuthority.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Which side computes which of an entity's components.
+ *
+ * One `u32`. A set bit means the GPU is authoritative for the component that bit names; a clear bit,
+ * or no component at all, means the CPU is. The bits are assigned in
+ * {@link GPUStateAuthorityFlags}, one per component type.
+ *
+ * **Nothing infers this.** Ownership used to be read off the shape of the world — an entity with an
+ * attachment and an animation binding was taken to be GPU-driven — which makes every reader
+ * re-derive a rule that a bit can simply state, and makes two readers free to disagree. This is the
+ * one statement of it: the rows read it, and infer nothing.
+ *
+ * **Authority decides who computes a value, never what a value is.** Meep's netcode is a
+ * deterministic per-tick rollback on a server-authoritative orchestrator, and a headless server has
+ * no device: it sets no bits, composes every chain itself, and must arrive at the same numbers as a
+ * client that renders. So a component any simulation system reads stays CPU-authoritative, and what
+ * a bit may cover is the reverse direction only — values the GPU produces that no CPU system reads.
+ * Where the simulation does want a GPU-owned pose it evaluates the chain exactly, on the CPU, from
+ * clip state; it never reads one back.
+ *
+ * **Attach it at creation, with zero flags, to anything that may ever be flagged.** Adding and
+ * removing a component is a structural change that relinks systems, and animation starts and stops
+ * constantly — so an authority change has to be a bit write. Absence still means CPU authority, for
+ * the entities that will never be flagged at all.
+ *
+ * **Not simulation state.** It describes a local rendering arrangement: which of two machines in
+ * this process holds a number. It is therefore neither saved nor replicated, on the same footing as
+ * {@link ParentEntity} — a flag that travelled would make a rendering client and a headless server
+ * disagree about a world they are required to agree about.
+ *
+ * @see GPUStateAuthorityFlags
+ * @see gpu_authority_has
+ */
+export class GPUStateAuthority {
+    /**
+     * @param {number} [flags]
+     * @returns {GPUStateAuthority}
+     */
+    static from(flags?: number): GPUStateAuthority;
+    /**
+     * Bitwise OR of {@link GPUStateAuthorityFlags} values.
+     *
+     * Read it through {@link gpu_authority_has} and write it through {@link gpu_authority_grant} /
+     * {@link gpu_authority_revoke}; those check the bit against the assigned set, which a raw `|=`
+     * does not.
+     *
+     * @type {number}
+     */
+    flags: number;
+}
+export namespace GPUStateAuthority {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=GPUStateAuthority.d.ts.map

package/src/engine/ecs/gpu/GPUStateAuthority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUStateAuthority.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthority.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAYI;;;OAGG;IACH,oBAHW,MAAM,GACJ,iBAAiB,CAQ7B;IArBD;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;CAab;;kBAIS,MAAM;sBASN,OAAO"}

package/src/engine/ecs/gpu/GPUStateAuthority.js

@@ -0,0 +1,72 @@
+/**
+ * Which side computes which of an entity's components.
+ *
+ * One `u32`. A set bit means the GPU is authoritative for the component that bit names; a clear bit,
+ * or no component at all, means the CPU is. The bits are assigned in
+ * {@link GPUStateAuthorityFlags}, one per component type.
+ *
+ * **Nothing infers this.** Ownership used to be read off the shape of the world — an entity with an
+ * attachment and an animation binding was taken to be GPU-driven — which makes every reader
+ * re-derive a rule that a bit can simply state, and makes two readers free to disagree. This is the
+ * one statement of it: the rows read it, and infer nothing.
+ *
+ * **Authority decides who computes a value, never what a value is.** Meep's netcode is a
+ * deterministic per-tick rollback on a server-authoritative orchestrator, and a headless server has
+ * no device: it sets no bits, composes every chain itself, and must arrive at the same numbers as a
+ * client that renders. So a component any simulation system reads stays CPU-authoritative, and what
+ * a bit may cover is the reverse direction only — values the GPU produces that no CPU system reads.
+ * Where the simulation does want a GPU-owned pose it evaluates the chain exactly, on the CPU, from
+ * clip state; it never reads one back.
+ *
+ * **Attach it at creation, with zero flags, to anything that may ever be flagged.** Adding and
+ * removing a component is a structural change that relinks systems, and animation starts and stops
+ * constantly — so an authority change has to be a bit write. Absence still means CPU authority, for
+ * the entities that will never be flagged at all.
+ *
+ * **Not simulation state.** It describes a local rendering arrangement: which of two machines in
+ * this process holds a number. It is therefore neither saved nor replicated, on the same footing as
+ * {@link ParentEntity} — a flag that travelled would make a rendering client and a headless server
+ * disagree about a world they are required to agree about.
+ *
+ * @see GPUStateAuthorityFlags
+ * @see gpu_authority_has
+ */
+export class GPUStateAuthority {
+    /**
+     * Bitwise OR of {@link GPUStateAuthorityFlags} values.
+     *
+     * Read it through {@link gpu_authority_has} and write it through {@link gpu_authority_grant} /
+     * {@link gpu_authority_revoke}; those check the bit against the assigned set, which a raw `|=`
+     * does not.
+     *
+     * @type {number}
+     */
+    flags = 0;
+
+    /**
+     * @param {number} [flags]
+     * @returns {GPUStateAuthority}
+     */
+    static from(flags = 0) {
+        const r = new GPUStateAuthority();
+
+        r.flags = flags;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+GPUStateAuthority.typeName = "GPUStateAuthority";
+
+/**
+ * Which machine holds a value is a property of this process, not of the world — see the class
+ * docblock. A saved game that carried it would reload claiming the GPU owns transforms that no
+ * device has ever seen.
+ *
+ * @type {boolean}
+ */
+GPUStateAuthority.serializable = false;

package/src/engine/ecs/gpu/GPUStateAuthorityFlags.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Names of the bits set in `flags`, for assertion messages and debug output.
+ *
+ * @param {number} flags
+ * @returns {string}
+ */
+export function gpu_state_authority_flag_names(flags: number): string;
+/**
+ * One bit per component type the GPU can be authoritative for, and the only place those bits are
+ * assigned.
+ *
+ * A set bit in {@link GPUStateAuthorityflags } means the GPU computes that component's value for
+ * that entity and the CPU does not. A clear bit — or no {@link GPUStateAuthority } at all — means the
+ * CPU does, which is what every entity means until something says otherwise.
+ *
+ * **Every component type gets its own bit, however related two of them look.** {@link Transform64 }
+ * and {@link TransformAttachment } are the case that forces it: an entity's world transform can be
+ * composed on the GPU while its local offset is still authored on the CPU, and a single "transform"
+ * bit could not say that. The pair is not a special case; it is what one-bit-per-component is for.
+ *
+ * **Adding a bit.** Take the next power of two, name it after the component class exactly, and add
+ * it to {@link GPU_STATE_AUTHORITY_FLAGS_ALL }. Do not renumber: nothing persists these values —
+ * {@link GPUStateAuthority } is neither serialized nor replicated — but two names sharing a bit is a
+ * silent aliasing bug that no test outside this file can see.
+ */
+export type GPUStateAuthorityFlags = number;
+export namespace GPUStateAuthorityFlags {
+    let Transform64: number;
+    let TransformAttachment: number;
+}
+/**
+ * Every bit {@link GPUStateAuthorityFlags} assigns, as one mask.
+ *
+ * The grant and revoke helpers check against it so that a mistyped or stale flag fails where it is
+ * written rather than turning into an authority claim nobody named.
+ *
+ * @type {number}
+ */
+export const GPU_STATE_AUTHORITY_FLAGS_ALL: number;
+//# sourceMappingURL=GPUStateAuthorityFlags.d.ts.map

package/src/engine/ecs/gpu/GPUStateAuthorityFlags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUStateAuthorityFlags.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthorityFlags.js"],"names":[],"mappings":"AAoDA;;;;;GAKG;AACH,sDAHW,MAAM,GACJ,MAAM,CAsBlB;;;;;;;;;;;;;;;;;;;qCA5DS,MAAM;;qBAOF,MAAM;6BASN,MAAM;;AAKpB;;;;;;;GAOG;AACH,4CAFU,MAAM,CAKd"}

package/src/engine/ecs/gpu/GPUStateAuthorityFlags.js

@@ -0,0 +1,79 @@
+/**
+ * One bit per component type the GPU can be authoritative for, and the only place those bits are
+ * assigned.
+ *
+ * A set bit in {@link GPUStateAuthority#flags} means the GPU computes that component's value for
+ * that entity and the CPU does not. A clear bit — or no {@link GPUStateAuthority} at all — means the
+ * CPU does, which is what every entity means until something says otherwise.
+ *
+ * **Every component type gets its own bit, however related two of them look.** {@link Transform64}
+ * and {@link TransformAttachment} are the case that forces it: an entity's world transform can be
+ * composed on the GPU while its local offset is still authored on the CPU, and a single "transform"
+ * bit could not say that. The pair is not a special case; it is what one-bit-per-component is for.
+ *
+ * **Adding a bit.** Take the next power of two, name it after the component class exactly, and add
+ * it to {@link GPU_STATE_AUTHORITY_FLAGS_ALL}. Do not renumber: nothing persists these values —
+ * {@link GPUStateAuthority} is neither serialized nor replicated — but two names sharing a bit is a
+ * silent aliasing bug that no test outside this file can see.
+ *
+ * @enum {number}
+ */
+export const GPUStateAuthorityFlags = {
+    /**
+     * The world transform — {@link Transform64} — is composed on the GPU, by the hierarchy pass over
+     * the entity's row and its parent chain.
+     *
+     * @type {number}
+     */
+    Transform64: 1,
+
+    /**
+     * The local offset — {@link TransformAttachment}'s own `transform` — is written on the GPU. This
+     * is what an animation clip drives: the pose accumulator resolves a joint's local TRS into its
+     * row, and a CPU that also wrote it would race the animation it is trying to show.
+     *
+     * @type {number}
+     */
+    TransformAttachment: 2,
+};
+
+/**
+ * Every bit {@link GPUStateAuthorityFlags} assigns, as one mask.
+ *
+ * The grant and revoke helpers check against it so that a mistyped or stale flag fails where it is
+ * written rather than turning into an authority claim nobody named.
+ *
+ * @type {number}
+ */
+export const GPU_STATE_AUTHORITY_FLAGS_ALL = (
+    GPUStateAuthorityFlags.Transform64
+    | GPUStateAuthorityFlags.TransformAttachment
+);
+
+/**
+ * Names of the bits set in `flags`, for assertion messages and debug output.
+ *
+ * @param {number} flags
+ * @returns {string}
+ */
+export function gpu_state_authority_flag_names(flags) {
+    const names = [];
+
+    for (const name in GPUStateAuthorityFlags) {
+        if ((flags & GPUStateAuthorityFlags[name]) !== 0) {
+            names.push(name);
+        }
+    }
+
+    const unknown = flags & ~GPU_STATE_AUTHORITY_FLAGS_ALL;
+
+    if (unknown !== 0) {
+        names.push(`<unassigned bits 0x${unknown.toString(16)}>`);
+    }
+
+    if (names.length === 0) {
+        return '<none>';
+    }
+
+    return names.join('|');
+}

package/src/engine/ecs/gpu/gpu_authority_assert_cpu.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Assert, before reading a component off an entity, that the CPU is the one who wrote it.
+ *
+ * A component the GPU is authoritative for holds whatever the CPU last composed — for the joints
+ * of a playing character, the rest pose under wherever the placement stood when the clip began.
+ * Reading it as if it were current is the failure the whole authority scheme exists to name, and
+ * it is silent: the value is a valid transform, just not this frame's. The simulation gets a
+ * current answer by exact evaluation (`t64_evaluate_world`); a tool or a sound gets one by
+ * readback. Neither goes through the component, so a read that does go through it says so here.
+ *
+ * An `assert.*` call, so a consumer that strips assertions pays nothing.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags the {@link GPUStateAuthorityFlags} bit of the component about to be read
+ */
+export function gpu_authority_assert_cpu(dataset: EntityComponentDataset, entity: number, flags: number): void;
+//# sourceMappingURL=gpu_authority_assert_cpu.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_assert_cpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_assert_cpu.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_assert_cpu.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,kFAHW,MAAM,SACN,MAAM,QAQhB"}

package/src/engine/ecs/gpu/gpu_authority_assert_cpu.js

@@ -0,0 +1,27 @@
+import { assert } from "../../../core/assert.js";
+import { gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+import { gpu_authority_has } from "./gpu_authority_has.js";
+
+/**
+ * Assert, before reading a component off an entity, that the CPU is the one who wrote it.
+ *
+ * A component the GPU is authoritative for holds whatever the CPU last composed — for the joints
+ * of a playing character, the rest pose under wherever the placement stood when the clip began.
+ * Reading it as if it were current is the failure the whole authority scheme exists to name, and
+ * it is silent: the value is a valid transform, just not this frame's. The simulation gets a
+ * current answer by exact evaluation (`t64_evaluate_world`); a tool or a sound gets one by
+ * readback. Neither goes through the component, so a read that does go through it says so here.
+ *
+ * An `assert.*` call, so a consumer that strips assertions pays nothing.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags the {@link GPUStateAuthorityFlags} bit of the component about to be read
+ */
+export function gpu_authority_assert_cpu(dataset, entity, flags) {
+    assert.ok(
+        !gpu_authority_has(dataset, entity, flags),
+        `entity ${entity} is GPU-owned for ${gpu_state_authority_flag_names(flags)}; it holds what the CPU`
+        + ` last composed, not this frame's value — evaluate it exactly (t64_evaluate_world) or read it back`
+    );
+}

package/src/engine/ecs/gpu/gpu_authority_declare.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Give an entity a {@link GPUStateAuthority} with nothing claimed, so that every later authority
+ * change is a bit write.
+ *
+ * **This is the only place the component is added, and it belongs at creation** — in the bulk build
+ * that makes the entity, or at the moment the one system that may flag it first links. Adding and
+ * removing a component is a structural dataset change that relinks systems, and the thing being
+ * described starts and stops constantly: a clip beginning and ending would otherwise churn the
+ * dataset once per transition, for a bit.
+ *
+ * Zero flags is not the same as no component. Both mean the CPU owns everything today; the
+ * difference is that this one is ready to change its mind.
+ *
+ * Idempotent: an entity that already carries the component keeps the flags it has. Two systems may
+ * both know an entity is flaggable, and neither is wrong.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {GPUStateAuthority} the entity's component, existing or newly attached
+ */
+export function gpu_authority_declare(dataset: EntityComponentDataset, entity: number): GPUStateAuthority;
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+//# sourceMappingURL=gpu_authority_declare.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_declare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_declare.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_declare.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+EAHW,MAAM,GACJ,iBAAiB,CAiB7B;kCArCiC,wBAAwB"}