aiecsjs 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,292 +0,0 @@
-# Changelog
-
-[English](CHANGELOG.md) | [繁體中文](CHANGELOG_ZHTW.md)
-
-All notable changes to `aiecsjs` are recorded in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.4.0] - 2026-05-29
-
-### Added
-
-- **`getRelationData(world, source, rel, target)`**: new stable export on `aiecsjs/relations`. Returns the `data` payload attached via `addRelation`, or `undefined` when no such edge exists or no data was stored. Closes the write-only-data asymmetry present since 0.1: `addRelation` accepted a data argument but there was no corresponding public read path.
-
-### Changed
-
-- **`aiecsjs/relations` graduated from experimental to stable.** The graph API (`defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `getRelationData`) and the built-in `ChildOf` relation are now frozen for the 1.x track. See [`STABILITY.md`](./STABILITY.md) for the full stability contract, including the raw slot-keying ABA semantic.
-- **`aiecsjs/worker` remains experimental.** True SAB shared-memory column aliasing is deferred; the worker sub-path continues on snapshot-copy semantics.
-
-### Build & Tooling
-
-- **size-limit → `scripts/check-size.mjs`**: replaced the `size-limit` + `@size-limit/file` dev dependencies with a zero-dependency script that measures transitive chunk-closure gzip size per ESM entry. Required because `tsup splitting: true` (introduced in 0.3.1) makes each entry a thin re-export shell; the vanilla single-file measurement reported ~899 B for index when the true closure is ~7295 B. The new script resolves chunk imports recursively via BFS, sums per-file gzip, and enforces per-entry budgets.
-- **npm → pnpm**: migrated from `package-lock.json` to `pnpm-lock.yaml`. Added `"packageManager": "pnpm@9.12.3"` and `"publishConfig": { "access": "public" }`. CI and publish workflows updated to use `pnpm/action-setup@v6` + `pnpm install --frozen-lockfile`. `npm publish --provenance --access public` in the publish workflow is intentionally preserved (OIDC trusted publishing requires npm CLI, not pnpm publish).
-- **Coverage tests added + unreachable gaps documented**: new tests cover previously-unreachable paths in `serialize.ts`, `component.ts`, `query.ts`, and `loop.ts`. Thresholds updated to the honestly-achieved floor (statements 95 / branches 81 / functions 98 / lines 99). Unreachable-by-design gaps are now documented in `vitest.config.ts` with Chesterton rationale.
-
-## [0.3.1] - 2026-05-29
-
-### Fixed
-
-- **Packed EntityId signed-overflow for generation ≥ 128**: `createEntity` returned a negative number diverging from the unsigned value stored in archetype row arrays (`Uint32Array`), so query iteration (`runQuery`/`iterQuery`/`forEachEntity`) yielded an eid that failed `entityRow` lookups; `refOf`/`entityExists`/`deref` on a query-iterated high-generation entity misbehaved (`refOf` threw on a live entity). `packEid`/`packEntity` now normalise with `>>> 0`. No public-bundle behaviour change beyond the corrected eid representation (EntityId is opaque + in-memory-only).
-- **`toJSON` silently dropped high-generation entities** (gen ≥ 128 with default 8-bit generation): `toJSON` contained its own inline pack expression that produced a signed (negative) result, diverging from the unsigned key stored in `arch.entityRow`. The affected entity passed the archetype check but failed `entityRow.has()`, so it was omitted from every snapshot and `serializeWorld` call. Fixed by replacing the inline expression with the canonical `packEid` (which applies `>>> 0`). SPOT principle: one pack source of truth.
-- **Cross-subpath registry isolation** (`tsup splitting: false` → `splitting: true`): each compiled entry point (`dist/index.js`, `dist/serialize.js`, etc.) previously bundled its own private copy of `internal/world.ts`, including the module-scope `worldRegistry`. A world created via the core subpath was invisible to `serializeWorld`/`getRelationTargets`/`transferableSnapshot` imported from their respective subpaths, causing `world N is destroyed or unknown` at runtime. With `splitting: true`, esbuild extracts a shared chunk used by all entries; ESM and CJS are both verified by the new `scripts/check-dist-subpaths.mjs` smoke script.
-- **`getRelationTargets` returned raw index as `EntityId`** (gen always 0): `addRelation` stores the target as a raw slot index (`& indexMask`). The previous return path cast this raw index directly to `EntityId`, which is equivalent to a packed id with generation 0. For any target that had been recycled (gen > 0), callers received a stale id that failed `entityExists`, `entityRow` lookups, and component access. Fixed by re-packing each raw index against the current generation via `packEid` before returning.
-- **`resolveOptions` did not validate `indexBits + generationBits ≤ 32`**: the individual range checks (`indexBits ∈ [1, 24]`, `generationBits ∈ [0, 16]`) allowed combinations such as `indexBits=24, generationBits=16` (40 bits), where `gen << 24` silently overflowed and high-generation bits were lost. A sum check is now enforced with a clear error message. The `[Unreleased]` example corrected accordingly (`indexBits: 16, generationBits: 16` = 32 bits).
-
-### Known Limitations
-
-- **`createDeltaSerializer.apply` with a recycled target world**: `apply` uses the raw entity index from the delta snapshot as the `EntityId` directly. When the target world has already recycled any of those slots (generation > 0), component operations silently act on the wrong packed id. This is a known limitation of the experimental delta API; the common usage (delta → a fresh gen-0 render-mirror world) is unaffected. A proper raw-index-to-packed-id mapping is planned for 0.4. Avoid `apply` against a world that has previously destroyed entities.
-
-### Documentation
-
-- README / README_ZHTW updated to reflect the shipped 0.3.0 `EntityRef` API: the previous README still described EntityRef as "targeted for 0.3+" and `getEntityGeneration`/`packEntity` as experimental. Both files now correctly state EntityId has been packed since 0.3, and `EntityRef` / `refOf` / `deref` / `aliveRef` / `EntityNotAliveError` are all stable since 0.3.0. API table entries for these symbols added.
-
-### Build & Tooling
-
-- Coverage gate: `@vitest/coverage-v8` installed and wired into `prepublishOnly` (replaces `npm run test`) and CI. Thresholds: statements 95 / branches 80 / functions 97 / lines 98 — the achievable bar on pristine source. The branch figure honours the `?? 0` / `noUncheckedIndexedAccess` idiom on TypedArray reads (nullish-fallback branches unreachable by design); thresholds are raised only by adding tests, never by stripping defensive guards or scattering `/* v8 ignore */`.
-- `fast-check` property tests (`tests/properties.test.ts`): pack/unpack round-trip invariant (asserts `e >= 0` to guard the P0 regression) and ABA-deref always-null invariant.
-- Dispose three-cycle tests, error-path tests, and observer handler-throw behaviour documented in `tests/world.test.ts` / `tests/observers.test.ts`.
-- `scripts/check-dist-subpaths.mjs` (`npm run verify:dist`): post-build smoke test that imports `createWorld`+`createEntity` from the core subpath and calls `serializeWorld`, `addRelation`/`getRelationTargets`, and `transferableSnapshot` from their respective subpaths for both ESM (`dist/*.js`) and CJS (`dist/*.cjs`). Wired into `prepublishOnly` (after `build`) and CI.
-
-## [Unreleased]
-
-### Planned for 0.4+
-
-- Add `pipeAsync` for async system composition.
-- Doc-test harness so README code blocks are mechanically verified.
-- Promote `aiecsjs/worker` to `stable` once true SAB shared-memory column aliasing is implemented.
-- Document the 8-bit generation wrap caveat in [STABILITY.md](./STABILITY.md): with the
-  default `generationBits=8`, a single slot recycled 256 times wraps back to its
-  starting generation, briefly re-opening the ABA window. Safe for v0.5 shmup
-  workloads (~5000 frame to wrap a single slot at 60 fps × ~1k destroys); high-churn
-  pools should set `createWorld({ indexBits: 16, generationBits: 16 })` (16 + 16 = 32 bits;
-  65 536 entities × 65 536 generations). See test
-  [tests/ref.test.ts](./tests/ref.test.ts) `generation wrap` describe block.
-
-## [0.3.0] - 2026-05-29
-
-### Added (API)
-
-- **`EntityRef<T>`** — ABA-safe entity reference. `refOf(world, eid)` builds one;
-  `deref(world, ref)` returns the entity id when still alive (generation match)
-  or `null` otherwise; `aliveRef(world, ref)` is the boolean guard form. Phantom
-  type `T` lets callers distinguish ref kinds (e.g. `EntityRef<'bullet'>`) without
-  runtime cost. Refs are in-memory only — not serializable across worker / disk.
-- **`EntityNotAliveError`** — thrown by `refOf` when the entity is dead or invalid.
-  `deref` / `aliveRef` never throw.
-
-### Changed
-
-- **`EntityId` now packs index + generation** into a single 32-bit number
-  `(generation << indexBits) | index` (default `indexBits=24, generationBits=8`).
-  `EntityId` remains opaque per STABILITY contract; the layout is implementation
-  detail. **Migration note**: do not compare `EntityId` numbers directly
-  (`eid === 42` will break across slot recycles); use
-  `getEntityIndex(eid)` for index comparison or `refOf(world, eid).id` for
-  identity matching that survives slot reuse.
-- **`getEntityGeneration` / `packEntity` graduate to `stable`** (were `experimental`
-  since 0.2.0). Both now return real values. These functions use default 24/8 bit
-  layout; for non-default `createWorld({ indexBits, generationBits })`, use
-  `EntityRef` and `deref` instead of manual unpacking.
-
-### Fixed
-
-- **ABA bug on entity slot recycle**: previously `entityExists` and `isAliveInternal`
-  only checked archetype membership; a stale `EntityId` pointing at a recycled slot
-  would silently report alive. With packed generation + `deref` generation match,
-  stale refs now correctly invalidate.
-- **`destroyEntity` generation wrap mask aligned with `options.generationBits`**
-  (was hard-coded `& 0xffff`). The mask now correctly uses
-  `state.options.generationMask`, fixing inconsistency for non-default
-  `generationBits` values.
-
-### Documentation
-
-- `onSet` JSDoc clarifies that `addComponent` does NOT trigger `onSet`, and
-  direct writes to column views returned by `getComponent` (e.g. `col.x[idx] = 5`)
-  also do NOT trigger `onSet`. Only `setComponent` on an already-present
-  component fires the callback. Anti-pattern example included.
-
-### Compatibility
-
-- `EntityId` layout change is **not** breaking at the type system level (opaque
-  branded number), but consumers who relied on `eid === N` direct comparison
-  will need to migrate (see Migration note above).
-- All existing `stable` exports unchanged.
-- `aiecsjs/worker` snapshot wire format unchanged (still uses raw indices).
-- `aiecsjs/serialize` wire format unchanged.
-
-### Build & tooling
-
-- `VERSION` constant bumped to `0.3.0`.
-
-## [0.2.1] - 2026-05-28
-
-### Security
-
-- **Resolve two Dependabot moderate advisories** on the transitive dev-only graph by upgrading `vitest` 1.6.0 → 4.1.7. Adds `vite` 8.0.14 as a direct devDependency to satisfy vitest 4's peer range (`^6 || ^7 || ^8`). These are dev-only — runtime surface unchanged.
-  - [GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99) `esbuild <=0.24.2` CORS development server data leak (fixed in 0.25.0).
-  - [GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9) `vite <=6.4.1` path traversal in optimized deps `.map` handling (fixed in 6.4.2 / 7.3.2 / 8.0.5).
-
-### Changed
-
-- **README opening unified across the ai*js family**: five-badge shields row (npm + CI + License + AI Generated + 繁體中文/English), one-line tagline as blockquote, ecosystem footer linking to the other two packages. Replaces the previous mixed style (text language switcher + 5 ad-hoc badges).
-- **`VERSION` constant bumped to 0.2.1** ([src/version.ts](src/version.ts)) so `world.version` and snapshot meta reflect this release.
-
-Runtime surface unchanged. Production bundles are byte-identical to 0.2.0.
-
-## [0.2.0] - 2026-05-28
-
-### Fixed (correctness + security)
-
-- **Prototype-pollution hardening in AoS `writeInitial`** ([src/internal/component.ts](src/internal/component.ts)): replaced `Object.assign(inst, initial)` with an explicit own-key copy that filters `__proto__` / `constructor` / `prototype`. Closes a path where a malicious `JSON.parse` payload reaching `addComponent` / `setComponent` / `fromJSON` / `deserializeWorld` could clobber the per-instance prototype.
-- **Observer dispatch is now safe against unsubscribe-during-iteration** ([src/observers.ts](src/observers.ts)): every `fire*` walks a snapshot of `state.observers` (`Array.from(...)` + `includes` guard) so a handler that calls its own returned disposer no longer skips sibling observers in the same fire round.
-- **`removeComponent` writes the new entity mask BEFORE firing observers** ([src/internal/component.ts](src/internal/component.ts)): query-targeted `remove` observers read `state.entityMask` to decide if the entity left the matching set; with the previous ordering the bit was still set during dispatch and the remove never fired. Brings `removeComponent` in line with `addComponent`'s "mutate then fire" order.
-- **`destroyEntity` now emits query-targeted `remove` events** ([src/observers.ts](src/observers.ts) `dispatchDestroyObservers`): in addition to per-component `onRemove`, the destroy hook now walks query observers and fires `remove` for any query the entity was matching pre-destroy. `wasMatch` is computed against a **snapshot of the pre-destroy mask** (not live `state.entityMask`) so a Phase 1 reentrant handler that mutates the entity's mask cannot suppress query removes in Phase 2 (regression caught by the round-2 review).
-- **`deserializeWorld` / `attachWorld` / `adoptSnapshot` binary length fields are bounds-checked** ([src/serialize.ts](src/serialize.ts)): `verLen` and `jsonLen` carry explicit `off + len <= bytes.length` assertions and a 64 MiB cap. `attachWorld` and `adoptSnapshot` ([src/worker.ts](src/worker.ts)) both carry SECURITY JSDocs that document the trust boundary expectation for SAB / TransferableSnapshot transports.
-
-### Added (API)
-
-- **`disposeWorld(world)`** — new export that aliases `destroyWorld`. Aligns with the ai*js ecosystem `dispose()` convention (`aifsmjs.Runtime.dispose`, `aibridgejs.Bridge.dispose`). Prefer this name in new code; `destroyWorld` is retained as a deprecated alias and is scheduled for removal in 1.0.
-- **`{ signal?: AbortSignal }` on every observer**: `onAdd`, `onRemove`, `onSet`, and `observe` now accept an options object. When the signal aborts, the observer auto-unsubscribes. The returned unsubscribe function remains valid and idempotent. New exported type `ObserverOptions` documents the shape. This closes a long-running gap noted in the AI ecosystem audit — long-lived observers on user-controlled lifecycles (UI components, async pipelines) no longer require manual cleanup wiring.
-
-### Changed (stability)
-
-- `getEntityGeneration` and `packEntity` re-classified from `stable` → `experimental` in `STABILITY.md` and `api.json`. In 0.1 these returned `0` / identity and that has not changed — the relabel honestly admits the deferred encoding work. Real values arrive when ABA-safe `EntityRef` lands.
-- `destroyWorld` re-classified from `stable` → `deprecated`. Behaviour unchanged; the deprecation is the API-naming alignment described above. Use `disposeWorld` instead.
-
-### Documentation
-
-- `onSet` now carries a JSDoc and README paragraph clarifying that it is a **low-level mutation hook**, not a reactive value-predicate query. `enterQuery` / `exitQuery` continue to be the structural-change surface; reactive value tracking remains an explicit non-goal of the core.
-- README observer section gains an `AbortController`-based unsubscribe example.
-
-### Build & tooling
-
-- Added [Biome](https://biomejs.dev/) lint + format (`biome.json`, `npm run lint`, `npm run format`). Brings parity with `aifsmjs` and `aibridgejs` and surfaces `noExplicitAny` warnings in legacy `src/internal/*` for follow-up cleanup.
-- Added `scripts/verify-exports.mjs` and the `npm run verify:exports` script; gates that every `package.json#exports` entry has a real file in `dist/`. Wired into `prepublishOnly`.
-- New `CONTRIBUTING.md` with the same shape used by `aifsmjs` (quick start, scope policy, release flow).
-
-### Compatibility
-
-This release is **non-breaking at runtime**. All existing code that called `destroyWorld(world)`, registered observers without options, or read `getEntityGeneration` continues to work. The stability label change is documentation-only.
-
-## [0.1.4] - 2026-05-28
-
-Docs-only release. Adds a cross-package integration section pointing at the `aibridgejs` JSON envelope contract; no source code changes.
-
-### Documentation
-
-- README and README_ZHTW gained an "Integration with aibridgejs" section explaining that `bridge.call` / `bridge.emit` enforce JSON-safe payloads and silently drop `Date`, `Map`, `Set`, and class instances. The correct shape for streaming world state across the bridge is `toJSON(world)` (or `serializeWorld(world)` wrapped in a JSON envelope) before emitting, not `getComponent(...)` direct. See [aiecsjs README · Integration with aibridgejs](README.md#integration-with-aibridgejs).
-- Verified via the `aijs-integration-smoke` companion project: every named export from `aifsmjs@0.1.2`, `aibridgejs@0.1.3`, and `aiecsjs@0.1.3` can coexist in a single TypeScript module with zero identifier collisions under `tsc --noEmit --strict`.
-
-## [0.1.3] - 2026-05-28
-
-A "no known silent bugs" release. Two correctness fixes, one hot-path allocation removal, and a small batch of style cleanups. No public API behaviour changes; `_getWorldState` is removed from the root export (was undocumented, unused by every sub-path, leading underscore signalled internal).
-
-### Fixed
-
-- `aiecsjs/relations` relation data store no longer keys edges by `srcEid * worldCapacity + tgtEid`. After the world grew, the same `(src, tgt)` pair computed a different key and earlier entries became orphaned. Storage is now a nested `Map<srcEid, Map<tgtEid, data>>`, independent of capacity. The cleanup hook on `destroyEntity` was updated to match. v0.1 has no public retrieve API so the bug was user-invisible, but it would have surfaced the moment a retrieve surface landed in 0.2.
-- Per-world resolved query bitmasks no longer live on the module-global `QueryInternal`. When the same `defineQuery(...)` handle was used by two worlds whose component registration orders differed, the second world's per-world mask overwrote the first world's, and `runQuery` silently returned wrong rows in world A. Masks now live in `WorldState.queryMasks: Map<queryId, QueryMaskBundle>`, isolated per world. Regression test in `tests/multi-world.test.ts` exercises the cross-order scenario.
-
-### Changed (internal)
-
-- Observer dispatch (`dispatchQueryObservers`) no longer allocates a temporary `Uint32Array` on every mutation event. Added `matchesEntityMask` helper in `bitmask.ts` that reads directly from `state.entityMask` at a base offset.
-- Shared bit-iteration extracted as `forEachSetBit(mask, base, words, fn)` in `bitmask.ts`. `clearAllEntityStorages` (`component.ts`) and `dispatchDestroyObservers` (`observers.ts`) now share that single implementation instead of inlining the same `word & -word` / `Math.clz32` pattern three times.
-- `state.generations[idx]` is written without an `as any` cast. `Uint8Array | Uint16Array` already supports indexed read/write.
-- Removed the `void oldCap` no-op from `growEntityArrays`.
-- Removed `_getWorldState` from the root `aiecsjs` export. Sub-paths (`aiecsjs/serialize`, `aiecsjs/worker`) already import `getWorldState` directly from the internal module; the leading-underscore root re-export had no consumer.
-
-### Planned for 0.3
-
-- Promote `aiecsjs/relations` and `aiecsjs/worker` to `stable`.
-- Stabilize the network delta wire format.
-- Add automated benchmark suite committed to repo.
-
-### Planned for 1.0
-
-- API freeze for the 1.x line.
-- Drop the experimental status label.
-
-## [0.1.2] - 2026-05-28
-
-CI/CD smoke-test release. No user-facing source or behavioural changes since 0.1.1; this bump exists solely to validate the tag-triggered publish workflow (see `.github/workflows/publish.yml`) end-to-end against the npm registry with provenance attestation.
-
-### Build & tooling
-
-- Confirmed that pushing a `v*.*.*` tag triggers `.github/workflows/publish.yml`, runs `prepublishOnly` (typecheck + tests + build + size budget), and publishes to npm with sigstore provenance.
-
-## [0.1.1] - 2026-05-28
-
-The "documentation honesty + test backstop" release. No new public APIs; this is the version of 0.1.0 that ships with the public surface, the documentation, and the test coverage in agreement.
-
-### Fixed
-
-- `destroyEntity` now clears the SoA columns and undefines the AoS slots that the destroyed entity owned. Previously only the entity mask was cleared, leaving stale data at the slot visible to debug snapshots and the serialisation path. Public `hasComponent` / query behaviour was already correct, so user-visible behaviour is unchanged; this closes the gap surfaced by the new `destroyEntity zeroes the destroyed entity’s SoA slot` test.
-
-### Changed (docs hygiene)
-
-- README and STABILITY now describe `aiecsjs/worker` honestly as a snapshot-copy transport for 0.1; true shared columns remain a 0.2 target. README description and `package.json` description updated accordingly.
-- README clarifies that 0.1 `EntityId` is a bare slot index; internal generation is tracked for slot reuse but not encoded in the ID. ABA-safe `EntityRef` is on the 0.2 roadmap.
-- Sub-paths (`loop` / `commands` / `observers` / `serialize` / `worker` / `relations`) re-positioned in STABILITY as utility / adapter sub-paths; the root `aiecsjs` is the stable core surface. Tree-shakers should drop any sub-path the app does not import.
-- README adds a "What aiecsjs does NOT do" section listing explicit non-goals (system scheduler, render binding, physics, network replication, value-predicate reactive queries, prefab/inheritance).
-- Language version filenames renamed from `*.zh-TW.md` to `*_ZHTW.md`. Cross-links, `llms.txt`, and `package.json` `files` updated. Future language variants follow the same uppercase ISO 639-1 pattern.
-- Removed emoji from documentation prose (language switchers, status banners).
-
-### Build & tooling
-
-- tsup build now runs with `minify: true`.
-- `size-limit` added as a dev dependency; per-export gzip budgets enforced via `npm run size`. Current measurements: core 5.49 kB, all sub-paths combined 12.6 kB gzip.
-- GitHub Actions CI workflow added: typecheck → test → build → size check on push and PR to `main`.
-- `prepublishOnly` now runs typecheck, tests, build, and the size budget gate before allowing publish.
-
-### Tests
-
-- Test count increased from 84 to 140. New file `tests/internal/bitmask.test.ts` covers the multi-word bitmask helpers in isolation (27 cases including `matches` truth table). New file `tests/multi-world.test.ts` covers per-world isolation when the same component is reused. Existing files gained: naive linear-filter cross-check against `runQuery` for all clause combinations, archetype migration boundary path, query mid-traversal stability and lazy cache behaviour, SoA field clear assertions on both `removeComponent` and `destroyEntity`, SoA vector-length round trip, `maxEntities` / `maxComponents` boundary throws, observer fan-out for destroy across multiple components, `onSet` value content, query observer ignores unrelated mutation, relation source-side destroy cleanup, exclusive relation storage resize, worker `readOnly` rejects add / remove / destroy, serialize `options.components` filter, `onUnknownVersion: throw | best-effort` paths, command buffer placeholder resolves into a queryable entity, slot-reuse limitation made explicit. Loop tests rewritten on top of `vi.useFakeTimers({ toFake: ['performance', ...] })` for deterministic dt validation.
-
-## [0.1.0] - 2026-05-27
-
-**Initial release.** All 50 documented exports across 7 modules are implemented and covered by 84 passing Vitest behaviour tests. Built with tsup to dual ESM + CJS, ships `.d.ts` declarations and source maps.
-
-### Implementation notes
-
-- **Storage**: world-level TypedArray columns per SoA component field, sized to world capacity. Archetypes track entity membership (a `Uint32Array entities[]`) but do not own column data. This makes archetype migration O(1) and lets `Position.x[eid]` work directly without per-archetype indirection. Trade-off: iteration over archetypes reads columns at potentially non-contiguous offsets; for hot data this stays in L1.
-- **EntityId is unversioned in 0.1**: `EntityId` is the entity index. Generation is tracked internally for slot reuse but not encoded in the ID. `getEntityIndex` / `getEntityGeneration` / `packEntity` are identity helpers. ABA-safe references via a separate `EntityRef` type are planned for 0.2.
-- **Bitmask queries**: multi-word Uint32 masks, default 8 words (256 components). Per-world bit allocation, global component identity.
-- **Worker / SAB**: 0.1 implements snapshot-copy semantics (serialize-into-SAB on send, deserialize-on-adopt) rather than true shared-memory column aliasing. The API surface matches the documented contract; true shared columns ship in 0.2.
-- **Binary serialization**: a JSON payload wrapped in a 4-byte magic + version header. Compact binary column encoding is planned for 0.2.
-
-### Added
-
-- `README.md` (English) and `README_ZHTW.md` (Traditional Chinese) with quick start, guide, API reference, performance notes, multi-threading guide, WebGPU interop section, serialization guide, migration guides, and "For AI Agents" section.
-- `llms.txt` — Jeremy Howard format AI-discovery file.
-- `llms-full.txt` — Single-file complete reference for LLM consumption.
-- `api.json` — Machine-readable export manifest with stability and `since` fields on every entry.
-- `STABILITY.md` and `STABILITY_ZHTW.md` — Per-export stability contract.
-- `docs/MIGRATION.md` and `docs/MIGRATION_ZHTW.md` — Migration guides from bitECS 0.4, miniplex 2.0, and ECSY.
-
-### API surface declared
-
-- Core: `createWorld`, `destroyWorld`, `resetWorld`, `getWorldSize`, `getWorldCapacity`.
-- Entity: `createEntity`, `destroyEntity`, `entityExists`, `getEntityIndex`, `getEntityGeneration`, `packEntity`.
-- Component: `defineComponent`, `defineTag`, `defineObjectComponent`, `addComponent`, `removeComponent`, `hasComponent`, `getComponent`, `setComponent`, `Types`.
-- Query: `defineQuery`, `runQuery`, `forEachEntity`, `iterQuery`, `enterQuery`, `exitQuery`, `queryArchetypes` (experimental).
-- System: `pipe`.
-- Subpath `aiecsjs/loop`: `createLoop`.
-- Subpath `aiecsjs/commands`: `createCommandBuffer`, `flush`, `withCommandBuffer`.
-- Subpath `aiecsjs/observers`: `observe`, `onAdd`, `onRemove`, `onSet`.
-- Subpath `aiecsjs/serialize`: `serializeWorld`, `deserializeWorld`, `toJSON`, `fromJSON`, `createDeltaSerializer` (experimental).
-- Subpath `aiecsjs/worker` (experimental): `transferableSnapshot`, `adoptSnapshot`, `attachWorld`, `detachWorld`.
-- Subpath `aiecsjs/relations` (experimental, not implemented): `defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `ChildOf`.
-- Utility: `VERSION`, `IS_SAB_SUPPORTED`, `isWorld`, `isEntity`.
-
-### Known limitations in 0.1
-
-- `aiecsjs/relations` and `aiecsjs/worker` are implemented but tagged experimental; API may shift.
-- Network delta wire format is JSON-based; binary patch format is planned for 0.2.
-- AoS components are main-thread only; cannot be shared via SharedArrayBuffer.
-- No automatic system scheduler / parallel execution.
-- Worker/SAB uses snapshot-copy in 0.1 rather than true shared-memory aliasing.
-- EntityId is unversioned; ABA-safe references arrive with `EntityRef` in 0.2.
-
-[Unreleased]: https://github.com/yshengliao/aiecsjs/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/yshengliao/aiecsjs/releases/tag/v0.1.0

package/STABILITY.md

@@ -1,156 +0,0 @@
-# Stability Contract
-
-[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
-
-This document is the per-export stability promise for `aiecsjs`. It is the contract AI tools and human users can rely on when pinning versions and writing import paths.
-
-## Policy
-
-aiecsjs follows [semver](https://semver.org/). Within the **0.x** series:
-- **`stable`** exports do not change in breaking ways across minor versions (e.g. 0.1 → 0.2).
-- **`experimental`** exports may change shape, name, or behaviour in any minor release. Pin the exact version if you depend on them.
-- **`internal`** is not part of the API. May change in any patch release. Do not import.
-- **`deprecated`** still works as documented but is scheduled for removal. The deprecation notice states the target version.
-
-At **1.0**, the `stable` surface freezes for the entire 1.x series.
-
-The full machine-readable export list lives in [`api.json`](./api.json), with the `stability` and `since` fields on every entry.
-
-## By module
-
-The **root** entry (`aiecsjs`) is the stable core: world, entity, component, query, system. Everything under a sub-path (`aiecsjs/<name>`) is a **utility or adapter sub-path** — useful but non-essential, decoupled from the core, and importable a la carte. Tree-shakers should be able to drop any sub-path the application does not import.
-
-### `aiecsjs` (root core)
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createWorld` | stable | 0.1.0 | |
-| `disposeWorld` | stable | 0.2.0 | Alias for `destroyWorld`; aligns with the ai*js ecosystem `dispose()` convention. Prefer this name in new code. |
-| `destroyWorld` | **deprecated** | 0.1.0 | Use `disposeWorld` instead. Scheduled for removal in 1.0. |
-| `resetWorld` | stable | 0.1.0 | |
-| `getWorldSize` | stable | 0.1.0 | |
-| `getWorldCapacity` | stable | 0.1.0 | |
-| `createEntity` | stable | 0.1.0 | |
-| `destroyEntity` | stable | 0.1.0 | |
-| `entityExists` | stable | 0.1.0 | |
-| `getEntityIndex` | stable | 0.1.0 | |
-| `getEntityGeneration` | stable | 0.3.0 | Returns real generation value packed into EntityId (default 24-bit index, 8-bit generation). For non-default `createWorld({ indexBits, generationBits })`, use `EntityRef` + `deref` instead. |
-| `packEntity` | stable | 0.3.0 | Packs index + generation into an EntityId using default 24/8 bit layout. For non-default bit sizes, use `EntityRef` + `deref` instead. |
-| `refOf` | stable | 0.3.0 | Throws `EntityNotAliveError` for dead entity. |
-| `deref` | stable | 0.3.0 | Returns null for stale / cross-world refs; never throws. |
-| `aliveRef` | stable | 0.3.0 | Boolean guard form of `deref`; never throws. |
-| `EntityRef` (type) | stable | 0.3.0 | In-memory only; not serializable. |
-| `EntityNotAliveError` | stable | 0.3.0 | Thrown only by `refOf`. |
-| `defineComponent` | stable | 0.1.0 | |
-| `defineTag` | stable | 0.1.0 | |
-| `defineObjectComponent` | stable | 0.1.0 | AoS components are main-thread only; not SAB-shareable. |
-| `addComponent` | stable | 0.1.0 | Argument order `(world, eid, component, init?)` is final. |
-| `removeComponent` | stable | 0.1.0 | |
-| `hasComponent` | stable | 0.1.0 | |
-| `getComponent` | stable | 0.1.0 | |
-| `setComponent` | stable | 0.1.0 | |
-| `Types` | stable | 0.1.0 | Constant map; field names are part of the contract. |
-| `defineQuery` | stable | 0.1.0 | |
-| `runQuery` | stable | 0.1.0 | |
-| `forEachEntity` | stable | 0.1.0 | |
-| `iterQuery` | stable | 0.1.0 | |
-| `enterQuery` | stable | 0.1.0 | |
-| `exitQuery` | stable | 0.1.0 | |
-| `queryArchetypes` | **experimental** | 0.1.0 | `Archetype.id` is opaque-internal; the shape of `Archetype` may grow. |
-| `pipe` | stable | 0.1.0 | |
-| `VERSION` | stable | 0.1.0 | |
-| `IS_SAB_SUPPORTED` | stable | 0.1.0 | |
-| `isWorld` | stable | 0.1.0 | |
-| `isEntity` | stable | 0.1.0 | |
-
-### `aiecsjs/loop` (utility sub-path)
-
-Fixed-timestep accumulator loop. Drop this sub-path if you already drive frame updates yourself (PixiJS `Ticker`, requestAnimationFrame, server-side simulation).
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createLoop` | stable | 0.1.0 | |
-
-### `aiecsjs/commands` (utility sub-path)
-
-Deferred structural mutations so systems can mutate world structure mid-iteration without invalidating queries.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createCommandBuffer` | stable | 0.1.0 | |
-| `flush` | stable | 0.1.0 | |
-| `withCommandBuffer` | stable | 0.1.0 | |
-
-### `aiecsjs/observers` (utility sub-path)
-
-Component lifecycle hooks. The core does not require observers; install this sub-path only if a system needs add/remove/set callbacks.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `observe` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onAdd` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onRemove` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onSet` | stable | 0.1.0 | Low-level mutation hook; NOT a reactive value-predicate query. Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-
-### `aiecsjs/serialize` (utility sub-path)
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `serializeWorld` | stable | 0.1.0 | Binary format includes a version stamp. |
-| `deserializeWorld` | stable | 0.1.0 | |
-| `toJSON` | stable | 0.1.0 | |
-| `fromJSON` | stable | 0.1.0 | |
-| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format may change before 1.0. |
-
-### `aiecsjs/worker` (experimental adapter sub-path)
-
-The entire subpath is **experimental** in 0.x. **In 0.x the implementation is a snapshot-copy transport** — serialize the world into the SAB on send, deserialize into a fresh world on adopt. It is not true shared-memory column aliasing. The API surface matches the documented contract; true shared columns are targeted for **0.3+**. Snapshot layout and capability flags may change.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `transferableSnapshot` | experimental | 0.1.0 | |
-| `adoptSnapshot` | experimental | 0.1.0 | |
-| `attachWorld` | experimental | 0.1.0 | |
-| `detachWorld` | experimental | 0.1.0 | |
-
-### `aiecsjs/relations` (stable sub-path since 0.4.0)
-
-The relations sub-path is **stable** as of 0.4.0. The graph API (`defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `getRelationData`) and the built-in `ChildOf` relation are frozen for the 1.x track.
-
-**Raw slot-keying ABA semantic:** relation storage keys edges by raw entity slot index (`entityId & indexMask`), not by the full packed EntityId (which includes a generation counter). If entity A is destroyed and a different entity B is later created occupying the same slot, B will inherit A's outgoing and incoming edges unless the destroy cleanup hook ran. The cleanup hook fires automatically when `destroyEntity` is called, so normal usage is safe. Callers holding cached EntityId values across destroy/recreate cycles should validate liveness with `entityExists` before reading relation data if ABA is a concern.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `defineRelation` | stable | 0.1.0 | |
-| `addRelation` | stable | 0.1.0 | |
-| `removeRelation` | stable | 0.1.0 | |
-| `getRelationTargets` | stable | 0.1.0 | |
-| `ChildOf` (constant) | stable | 0.1.0 | Built-in exclusive relation. |
-| `getRelationData` | stable | 0.4.0 | Returns the data payload attached via `addRelation`, or `undefined` if no such edge or no data was stored. Subject to the raw slot-keying ABA semantic described above. |
-
-### `aiecsjs/internal/*`
-
-Everything under this prefix is **internal**. It exists for the implementation's own use and may break in any release. Do not import.
-
-## Roadmap
-
-| Version | Focus | Stability shift |
-|---|---|---|
-| 0.1.x | Core surface (world, entity, component, query, system, loop, commands, observers, serialize) | Initial publish; all marked experimental at the package level but per-export stable where listed. |
-| 0.2.0 | Safety + alignment | Prototype-pollution hardening, observer `{ signal? }`, `disposeWorld` alias, `getEntityGeneration` / `packEntity` re-labelled experimental, `verify:llms` gate. See [CHANGELOG.md](./CHANGELOG.md#020---2026-05-28). |
-| 0.3.x | EntityRef + generation packing | ABA-safe; `getEntityGeneration` / `packEntity` → stable. |
-| 0.4.0 | Relations stabilisation | `aiecsjs/relations` graduated to stable; `getRelationData` added. `aiecsjs/worker` remains experimental (true SAB shared-memory columns deferred). |
-| 0.6+ | Multi-World snapshot diff transport (placeholder) | experimental — design TBD. |
-| 1.0.0 | API freeze | All `stable` exports frozen for 1.x. |
-
-## How to check stability at runtime
-
-```ts
-import { VERSION } from 'aiecsjs'
-
-if (VERSION.startsWith('0.')) {
-  console.warn('aiecsjs is in pre-1.0; API surface may shift')
-}
-```
-
-For programmatic introspection, parse [`api.json`](./api.json) — each entry has `stability` and `since` fields.

package/STABILITY_ZHTW.md

@@ -1,155 +0,0 @@
-# 穩定度契約
-
-[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
-
-本文件為 `aiecsjs` 中各匯出的穩定度承諾。AI 工具與人類使用者可依此契約來鎖定版本與書寫 import 路徑。
-
-## 規範
-
-aiecsjs 遵循 [semver](https://semver.org/)。在 **0.x** 系列內：
-- **`stable`** 匯出於 minor 版本之間（例如 0.1 → 0.2）不會破壞性變更。
-- **`experimental`** 匯出可能在任何 minor 釋出時改變形狀、命名或行為。若有依賴請鎖定明確版本。
-- **`internal`** 不屬於 API 表面，可能在任何 patch 釋出時改變。請勿匯入。
-- **`deprecated`** 仍可正常運作但已排入移除計畫。棄用通知中會載明目標版本。
-
-至 **1.0** 時，`stable` 表面為整個 1.x 系列凍結。
-
-完整機器可讀的匯出清單位於 [`api.json`](./api.json)，每筆都有 `stability` 與 `since` 欄位。
-
-## 依模組分類
-
-**根目錄** entry（`aiecsjs`）為穩定核心：world、entity、component、query、system。任何 sub-path（`aiecsjs/<名稱>`）為 **utility 或 adapter sub-path** — 實用但非核心，與 core 解耦，可單獨 a la carte import。Tree-shaker 應能丟掉未引用的任何 sub-path。
-
-### `aiecsjs`（根核心）
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createWorld` | stable | 0.1.0 | |
-| `destroyWorld` | **deprecated** | 0.1.0 | 請改用 `disposeWorld`。預計於 1.0 移除。 |
-| `resetWorld` | stable | 0.1.0 | |
-| `getWorldSize` | stable | 0.1.0 | |
-| `getWorldCapacity` | stable | 0.1.0 | |
-| `createEntity` | stable | 0.1.0 | |
-| `destroyEntity` | stable | 0.1.0 | |
-| `entityExists` | stable | 0.1.0 | |
-| `getEntityIndex` | stable | 0.1.0 | |
-| `getEntityGeneration` | stable | 0.3.0 | 回傳 EntityId 中實際打包的 generation 值（預設 24-bit index、8-bit generation）。若使用非預設 `createWorld({ indexBits, generationBits })`，請改用 `EntityRef` + `deref`。 |
-| `packEntity` | stable | 0.3.0 | 使用預設 24/8 bit 佈局將 index + generation 打包為 EntityId。若使用非預設 bit 大小，請改用 `EntityRef` + `deref`。 |
-| `refOf` | stable | 0.3.0 | entity 不存活時拋出 `EntityNotAliveError`。 |
-| `deref` | stable | 0.3.0 | 對過期或跨 world 的 ref 回傳 null；絕不拋出錯誤。 |
-| `aliveRef` | stable | 0.3.0 | `deref` 的布林 guard 形式；絕不拋出錯誤。 |
-| `EntityRef`（type） | stable | 0.3.0 | 僅限記憶體內使用；不可序列化。 |
-| `EntityNotAliveError` | stable | 0.3.0 | 僅由 `refOf` 拋出。 |
-| `defineComponent` | stable | 0.1.0 | |
-| `defineTag` | stable | 0.1.0 | |
-| `defineObjectComponent` | stable | 0.1.0 | AoS 元件僅限主執行緒；不可跨 SAB 共享。 |
-| `addComponent` | stable | 0.1.0 | 參數順序 `(world, eid, component, init?)` 為最終定義。 |
-| `removeComponent` | stable | 0.1.0 | |
-| `hasComponent` | stable | 0.1.0 | |
-| `getComponent` | stable | 0.1.0 | |
-| `setComponent` | stable | 0.1.0 | |
-| `Types` | stable | 0.1.0 | 常數對應表；欄位名稱屬於契約。 |
-| `defineQuery` | stable | 0.1.0 | |
-| `runQuery` | stable | 0.1.0 | |
-| `forEachEntity` | stable | 0.1.0 | |
-| `iterQuery` | stable | 0.1.0 | |
-| `enterQuery` | stable | 0.1.0 | |
-| `exitQuery` | stable | 0.1.0 | |
-| `queryArchetypes` | **experimental** | 0.1.0 | `Archetype.id` 為 opaque 內部值；`Archetype` 的形狀可能增加欄位。 |
-| `pipe` | stable | 0.1.0 | |
-| `VERSION` | stable | 0.1.0 | |
-| `IS_SAB_SUPPORTED` | stable | 0.1.0 | |
-| `isWorld` | stable | 0.1.0 | |
-| `isEntity` | stable | 0.1.0 | |
-
-### `aiecsjs/loop`（utility sub-path）
-
-定步長累加迴圈。若應用層已自有 frame 更新驅動（PixiJS `Ticker`、requestAnimationFrame、伺服端模擬），可直接略過本 sub-path。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createLoop` | stable | 0.1.0 | |
-
-### `aiecsjs/commands`（utility sub-path）
-
-延後的結構性變更，讓系統可在迭代中安全改動 world 結構而不會讓查詢失效。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createCommandBuffer` | stable | 0.1.0 | |
-| `flush` | stable | 0.1.0 | |
-| `withCommandBuffer` | stable | 0.1.0 | |
-
-### `aiecsjs/observers`（utility sub-path）
-
-元件生命週期 hook。Core 不依賴 observers；只在系統需要 add/remove/set callback 時才安裝本 sub-path。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `observe` | stable | 0.1.0 | |
-| `onAdd` | stable | 0.1.0 | |
-| `onRemove` | stable | 0.1.0 | |
-| `onSet` | stable | 0.1.0 | |
-
-### `aiecsjs/serialize`（utility sub-path）
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `serializeWorld` | stable | 0.1.0 | 二進位格式包含版本戳記。 |
-| `deserializeWorld` | stable | 0.1.0 | |
-| `toJSON` | stable | 0.1.0 | |
-| `fromJSON` | stable | 0.1.0 | |
-| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format 在 1.0 之前可能改變。 |
-
-### `aiecsjs/worker`（experimental adapter sub-path）
-
-整個 subpath 在 0.x 為 **experimental**。**0.x 的實作為 snapshot-copy 傳輸**——傳送時將 world 序列化進 SAB，接收端反序列化成全新 world，並非真正的共享記憶體欄位 aliasing。API 表面符合文件契約；真正的共享欄位預計 **0.3+** 推出。Snapshot 佈局與能力旗標可能改變。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `transferableSnapshot` | experimental | 0.1.0 | |
-| `adoptSnapshot` | experimental | 0.1.0 | |
-| `attachWorld` | experimental | 0.1.0 | |
-| `detachWorld` | experimental | 0.1.0 | |
-
-### `aiecsjs/relations`（stable sub-path，自 0.4.0 起）
-
-relations sub-path 自 **0.4.0** 起為 **stable**。圖形 API（`defineRelation`、`addRelation`、`removeRelation`、`getRelationTargets`、`getRelationData`）以及內建 `ChildOf` 關係已為 1.x 凍結。
-
-**原始 slot 鍵值的 ABA 語意：** relation storage 以原始 entity slot index（`entityId & indexMask`）作為 edge 的鍵，而非包含 generation counter 的完整 packed EntityId。若 entity A 被銷毀後，另一個 entity B 在同一個 slot 被建立，B 將繼承 A 的所有進出 edge——除非 destroy cleanup hook 已執行（呼叫 `destroyEntity` 時會自動執行）。一般使用下是安全的；若在 destroy/recreate 循環中持有快取的 EntityId，讀取 relation data 前應以 `entityExists` 確認活躍狀態。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `defineRelation` | stable | 0.1.0 | |
-| `addRelation` | stable | 0.1.0 | |
-| `removeRelation` | stable | 0.1.0 | |
-| `getRelationTargets` | stable | 0.1.0 | |
-| `ChildOf`（常數） | stable | 0.1.0 | 內建獨佔關係。 |
-| `getRelationData` | stable | 0.4.0 | 回傳透過 `addRelation` 附加的 data payload，或在 edge 不存在 / 未儲存 data 時回傳 `undefined`。受上述原始 slot 鍵值 ABA 語意影響。 |
-
-### `aiecsjs/internal/*`
-
-此前綴底下的所有內容皆為 **internal**。它存在於實作自用，可能在任何 release 變更。請勿匯入。
-
-## Roadmap
-
-| 版本 | 焦點 | 穩定度變動 |
-|---|---|---|
-| 0.1.x | 核心表面（world、entity、component、query、system、loop、commands、observers、serialize） | 初次發佈；package 整體標 experimental，但各 export 表中列為 stable 者皆穩定。 |
-| 0.2.0 | 安全與生態對齊 | 原型污染強化、observer `{ signal? }`、`disposeWorld` 別名、`getEntityGeneration` / `packEntity` 改 experimental、`verify:llms` gate。詳見 [CHANGELOG.md](./CHANGELOG.md#020---2026-05-28)。 |
-| 0.3.x | EntityRef + generation packing | ABA-safe；`getEntityGeneration` / `packEntity` → stable。 |
-| 0.4.0 | Relations 穩定化 | `aiecsjs/relations` 升為 stable；新增 `getRelationData`。`aiecsjs/worker` 維持 experimental（真正 SAB 共享記憶體欄位延後）。 |
-| 0.6+ | Multi-World snapshot diff transport（佔位） | experimental — 設計待定。 |
-| 1.0.0 | API 凍結 | 所有 `stable` 匯出於 1.x 系列凍結。 |
-
-## 在執行時檢查穩定度
-
-```ts
-import { VERSION } from 'aiecsjs'
-
-if (VERSION.startsWith('0.')) {
-  console.warn('aiecsjs 處於 1.0 前；API 表面可能調整')
-}
-```
-
-如需程式化檢視，請解析 [`api.json`](./api.json) — 每筆都有 `stability` 與 `since` 欄位。