@its-not-rocket-science/ananke 0.1.68 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,280 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+## [0.5.1] — 2026-06-14
+
+### Added
+
+- **STABLE_API.md** — new "Tier-2 stable" section promoting `sim/combat`, `sim/disease`, and `sim/hazard` subpaths to explicit API-stable status (`@minor`-bounded, no breaking changes without a CHANGELOG entry). Includes stable usage examples and a "Path to Tier-1" note.
+- **docs/api/index.html** — new styled API reference landing page: Tier-1/Tier-2 export tables, install CTA with copy button, live npm registry version check, links to TypeDoc generation instructions.
+- **docs/map/index.html** — explanation banner describing the 180-day world simulation; new "Polity Tools" panel for adding custom polities (name, position, colour), linking trade or war routes between any two polities, and clearing custom overlays.
+- **docs/mythology/index.html** — complete JS for chronicle/legend system: `renderChronicle`, `renderLegends`, `addChronicle`, `deleteChronicle`, `promoteToLegend`, `saveChronicle` (localStorage `ananke_chronicles`), `exportChronicle` (JSON download), `importChronicle` (paste JSON), delete and promote buttons per entry.
+
+### Changed
+
+- **docs/conformance/index.html** — combat, disease, and hazard subpaths now shown as "Tier 2 stable ✓" with key exports and coverage detail cards.
+- **docs/editors/scenario-builder.html** — added editor CTA links, Generated TypeScript CTAs (Copy, Download, Save to localStorage, Load), Empirical Reference explanation with 11-dataset dropdown.
+- **docs/data-governance/index.html** — added "What is data governance?" section explaining the three layers: physics provenance, API stability, and release integrity.
+- **docs/world-evolution/index.html** — added "What is world evolution?" section covering Session, Checkpoint, Fork, Diff, and Replay with code references and a typical host workflow walkthrough.
+- **docs/narrative-stress/index.html** — added real-film/book push-scale examples (Gladiator → Dragon Ball Z), completed the beat sequence editor (add + delete beats, live average push display), updated Tier-3 note.
+- **docs/combat/index.html** — added "Your saved archetypes" panel reading `ananke_species`/`ananke_bodyplan` from localStorage; import JSON and clear CTAs; PR contribution instructions.
+- **docs/zoo/index.html** — added three new scenarios (Acid Pool Exposure, Cavalry Charge vs Infantry, Untreated Wound Infection); save/download/import scenario CTAs; contribute sidebar panel.
+- **docs/arena/index.html** — auto-populates fighter selects from saved archetypes; Generate run plan + Execute plan CTAs; import archetype JSON.
+- **docs/environment/index.html** — expanded all five hazard type cards with full effect rows; added three new weather conditions (Hurricane, Extreme Humidity, Rarified Atmosphere); custom hazard creator form (save to localStorage `ananke_hazards`, download `.ts` snippet, import JSON); PR instructions.
+- **docs/epidemiology/index.html** — custom disease profile form (save to `ananke_diseases`, download `.ts` snippet, import JSON) with all DiseaseProfile fields.
+- **docs/economy/index.html** — custom catalogue item form (save to `ananke_items`, download JSON, import JSON).
+- **docs/world-client/index.html** and **docs/world-client/replication-client.html** — added server-requirement banners explaining WebSocket server setup (local `ts-node`, Fly.io/Railway for deployment).
+
+## [0.5.0] — 2026-04-23
+
+### Added
+
+- Expanded the Tier-2 experimental session facade documentation and plan artifacts for embedders (`docs/session-api.md`, `docs/session-api-plan.md`) with an explicit contract-level API inventory for the `@its-not-rocket-science/ananke/session` subpath.
+- Added additional world-evolution alias coverage in `test/session-facade.test.ts` to assert `runSession(..., { worldEvolution })` behavior for host-side JSON-first integrations.
+
+### Changed
+
+- Bumped package version to `0.5.0` and synchronized runtime version source-of-truth files for tag-driven CI/npm release flow alignment.
+- Refreshed release preparation evidence (`docs/release-prep-session-api.md`) to track the current tag-driven release path (`scripts/tag-release.sh` + `.github/workflows/release.yml`).
+
+---
+
+## [0.4.1] — 2026-04-23
+
+### Changed
+
+- Normalized documentation version references to use `package.json` as canonical source, replaced stale hard-coded Ananke versions in companion docs, and added `npm run check-doc-version-sync` to catch future markdown drift.
+- Performed adopter-confidence docs hardening across README/first-hour/stable API/module/bridge/wire docs and added `docs/support-boundaries.md` to make maintainer promises, exclusions, and version-pinning guidance explicit.
+- Wired the shipped `./session` subpath into host-facing docs (`docs/session-api.md`, module index, and integration primer), explicitly labeling it Tier 2 / experimental and documenting the host lifecycle (`create`, `run`, `fork`, pack load, serialize/deserialize).
+- Added `examples/session-embedding-minimal/` as the canonical NPM-package-style embedding template for the new session facade, covering tactical + world-evolution create/run/fork/serialize workflows using public imports.
+- Refined Tier-2 session facade ergonomics after embedding validation: `runSession` now defaults to one step, request aliases were added (`commandFrames`, `context`, `worldEvolution`), and `loadSessionPack` accepts either `{ manifest, ... }` or a raw manifest for lower-ceremony JSON-first host usage.
+- Added a session subpath consumer smoke test (`test/session-subpath-smoke.test.ts`) and wired it into CI so `@its-not-rocket-science/ananke/session` imports plus `examples/session-embedding-minimal` execution are continuously verified under build/test/coverage gates.
+- Improved `./session` runtime portability for browser/worker embedders by removing a transitive Node-only `node:crypto` dependency from pack checksum logic and guarding `process.env` determinism reads in the tactical kernel.
+
+---
+
+## [0.4.0] — 2026-04-22
+
+### Added
+
+- Added a new Tier-2 / experimental session facade subpath: `@its-not-rocket-science/ananke/session` (`./session` in package exports) so hosts can opt into a unified session workflow without changing Tier-1 root imports.
+- Added `src/session.ts` with JSON-first session types and helpers: `SessionMode`, `SessionConfig`, `SessionHandle`, `RunSessionRequest`, `RunSessionResult`, `SessionSummary`, `ForkSessionRequest`, and `LoadSessionPackResult`.
+- Added session facade functions: `createSession`, `runSession`, `stepSession`, `getSessionSummary`, `forkSession`, `loadSessionPack`, `serializeSession`, and `deserializeSession`.
+- Added tactical-mode initialization adapters for explicit `WorldState` and scenario JSON (plus optional seed/entity convenience bootstrap).
+- Added world-evolution-mode initialization adapters for canonical snapshots with `ruleset` / `rulesetId`, delegating to existing world-evolution orchestration.
+- Added deterministic serialization envelopes with explicit `schemaVersion`, `engineVersion`, `mode`, and `payload`.
+- Added content-pack integration via `loadSessionPack` that delegates to existing content-pack validation/loading/scenario instantiation APIs.
+
+### Changed
+
+- Bumped package version to `0.4.0` to reflect the additive new public subpath/API while preserving backward compatibility for existing Tier-1 imports.
+
+---
+
+## [0.3.0] — 2026-04-04
+
+### Added
+
+- Added a new AssemblyScript WASM core in `as/world.ts`, `as/combat.ts`, `as/movement.ts`, and `as/ananke-core.ts`, compiled to `wasm/ananke-core.wasm` via `npm run build:wasm:core`.
+- Added TypeScript↔WASM bridge (`src/wasm/bridge.ts`) with automatic TS fallback and new bridge tests (`test/wasm/bridge.test.ts`).
+- Added WASM benchmark runner (`tools/wasm-benchmark.ts`), WASM adapter (`benchmarks/adapters/wasm.ts`), and generated comparison output support under `benchmarks/results/wasm-vs-ts-*.json`.
+- Added cross-platform CI workflow `.github/workflows/wasm-build.yml` for Linux/macOS/Windows WASM builds and determinism fuzzing.
+- Added advanced WASM integration docs and runnable examples (`docs/wasm-integration.md`, `examples/wasm-node.ts`, `examples/wasm-browser.html`).
+
+---
+
+## [0.2.11] — 2026-04-04
+
+### Fixed
+
+- Corrected Windows-specific doubled-path bug in `tools/generate-release-dashboard.mjs` (replaced `.pathname` with `fileURLToPath` to avoid `C:\C:\...` on Windows).
+- Removed `docs/release-dashboard.md` from `.gitignore`; the file is fully deterministic (derived from `CHANGELOG.md` and `package.json` only, no timestamps) and must be committed for the CI freshness check to work.
+- Fixed API diff workflow: handle missing `docs/api-diff-report.md` gracefully in PR comment step; relax semver enforcement when the Tier-1 API surface is unchanged; correct version-output quoting in the API diff workflow.
+
+---
+
+## [0.2.10] — 2026-04-03
+
+### Added
+
+- Automated Tier-1 API surface governance in CI (`enforce-api-surface.yml`): generates an API diff on every PR, posts a comment summarising additions/removals, and fails the build when breaking changes are detected without a major-version bump.
+- Semver policy check script (`scripts/check-semver-policy.sh`) that gates merges requiring incompatible API changes.
+
+### Fixed
+
+- Switched all non-publish CI workflows from `npm ci` to `npm install` so branches adding new workspace packages do not hard-fail before a lockfile regeneration commit.
+- Synced `package-lock.json` with the `packages/cli` workspace that was added in v0.2.x.
+
+---
+
+## [0.2.9] — 2026-04-02
+
+### Changed
+
+- Added a strict first-hour adopter guide in `docs/first-hour-adopter-path.md` focused on stable Tier-1 onboarding and deterministic success criteria.
+- Added `examples/guided-first-hour.ts` as a guided runnable example that uses only stable root APIs (`createWorld`, `stepWorld`, `ReplayRecorder`, `serializeReplay`, `deserializeReplay`, `replayTo`).
+- Updated `README.md` with a "Start here" onboarding section and aligned the core simulation loop snippet with stable `createWorld` usage.
+- Added `npm run example:first-hour` and bumped package version to `0.2.9` with synchronized lockfile.
+
+---
+
+## [0.2.8] — 2026-04-02
+
+### Changed
+
+- Reworked `examples/reference/tactical-duel` into a minimal polished reference app that runs a full deterministic duel loop using only Tier-1 stable root APIs (`createWorld`, `stepWorld`, `ReplayRecorder`, `serializeReplay`, `q`).
+- Added a dedicated CI smoke test (`test/reference-tactical-duel-smoke.test.ts`) and wired it into `.github/workflows/ci.yml`.
+- Updated tactical-duel usage documentation to describe the stable-API loop and quick determinism verification workflow.
+- Bumped package version to `0.2.8` and synced lockfile.
+
+---
+
+## [0.2.7] — 2026-04-02
+
+### Changed
+
+- Added `docs/completion-evidence-dashboard.md`: an evidence-first completion dashboard that scans repository signals, links roadmap-level claims to concrete artifacts, and explicitly flags weak credibility areas without binary over-claiming.
+- Bumped package version to `0.2.7` and synced lockfile.
+
+---
+
+## [0.2.6] — 2026-04-02
+
+### Changed
+
+- Added runtime conformance regression harness coverage in `test/conformance-runtime.test.ts` to validate phase-order stability and execute all state-hash fixtures as deterministic checkpoints.
+- Added `phase-order.json` conformance fixture and runner support for the new `phase-order` fixture kind.
+- Expanded state-hash coverage with a second fixture (`state-hash-regression.json`) covering AI-driven checkpoints at ticks 0/1/5/10/20.
+- Refactored conformance fixture generation to use shared state-hash fixture builders for maintainable fixture expansion.
+- Bumped package version to `0.2.6` and synced lockfile.
+
+---
+
+## [0.2.5] — 2026-04-02
+
+### Changed
+
+- Externalized package-boundary mapping and allowed-dependency graph into `tools/package-boundaries.config.json` so boundary definitions are versioned as data.
+- Upgraded `tools/check-package-boundaries.ts` to load mapping config, support markdown report generation (`--report-md=...`), and keep warning-mode as the default while retaining strict mode (`--strict`) for future hard enforcement.
+- Added `npm run check-boundaries:report` and CI integration in `.github/workflows/ci.yml` to run boundary checks on every PR/push and publish the generated report as an artifact (warning mode initially).
+- Generated `docs/package-boundary-report.md` with current cross-package violations and unmapped-file inventory for migration planning.
+- Bumped package version to `0.2.5` and synced lockfile.
+
+---
+
+## [0.2.4] — 2026-04-02
+
+### Changed
+
+- Replaced roadmap-wide uppercase **COMPLETE** status claims with maturity-language equivalents (`M4 VALIDATED`) to avoid binary completion framing while preserving historical phase context in narrative text.
+- Added explicit maturity definitions (`M0`..`M4`) to `ROADMAP.md` and linked roadmap status language to subsystem evidence artifacts.
+- Added subsystem maturity matrix in both machine-readable JSON (`docs/maturity-matrix.json`) and human-readable markdown (`docs/maturity-matrix.md`) with evidence pointers to tests, conformance fixtures, source modules, and validation reports.
+- Bumped package version to `0.2.4` and synced lockfile.
+
+---
+
+## [0.2.3] — 2026-04-02
+
+### Changed
+
+- Moved legacy entity/world normalization out of `stepWorld` into dedicated normalization utilities (`src/sim/normalization.ts`) so default-repair logic no longer runs in the per-tick hot path.
+- Applied normalization at load/reconstruction boundaries:
+  - world construction (`createWorld`, `mkWorld`)
+  - scenario loading (`loadScenario`)
+  - replay deserialization/replay startup (`deserializeReplay`, `replayTo`)
+  - snapshot reconstruction (`applyDiff`)
+- Added migration-focused regression tests for legacy shape normalization across these boundaries in `test/normalization-migration.test.ts`.
+- Bumped package version to `0.2.3` and synced lockfile.
+
+---
+
+## [0.2.2] — 2026-04-02
+
+### Changed
+
+- Replaced hidden `__*` world runtime side-channel fields with explicit `world.runtimeState` typing via new `WorldRuntimeState` in `src/sim/world.ts`.
+- Updated kernel, AI, team hostility, snapshot diffing, and serialization pathways to read/write runtime subsystem data through `runtimeState`, preserving deterministic core hashing behavior.
+- Added lint guardrails in `eslint.config.mjs` and regression test `test/no-hidden-runtime-fields.test.ts` to block reintroduction of legacy hidden runtime fields.
+- Updated integration and protocol docs to document the explicit runtime-state pattern.
+
+---
+
+## [0.2.1] — 2026-04-02
+
+### Changed
+
+- Introduced deterministic world-step pipeline scaffolding with explicit `WorldStepContext` and stable phase ordering metadata in `src/sim/step/world-step-context.ts` and `src/sim/step/world-phases.ts`.
+- Added regression coverage for phase order in `test/kernel_phase_order.test.ts`.
+- No gameplay mechanics changed; this release is an internal kernel-structure refactor foundation.
+
+---
+
+## [0.2.0] — 2026-04-02
+
+### Changed
+
+- **Tier-1 API contraction (host-contract hardening):** root export `@its-not-rocket-science/ananke` now contains only the minimal stable host-facing contract:
+  - fixed-point utilities
+  - core host-required types
+  - world creation / scenario loading
+  - stepping
+  - replay / serialization
+  - bridge extraction
+- Added `docs/stable-api-manifest.json` as the machine-readable Tier-1 source of truth.
+- Added CI guard `check-stable-api` to fail builds if `src/index.ts` exports drift from the manifest.
+- Added explicit aggregate subpaths:
+  - `@its-not-rocket-science/ananke/tier2`
+  - `@its-not-rocket-science/ananke/tier3`
+
+### Migration guide
+
+If you previously imported non-core symbols from the root path, migrate as follows:
+
+1. **Keep root imports only for Tier-1 symbols** listed in `STABLE_API.md`.
+2. Move removed root imports to explicit subpaths:
+   - Tier 2: `@its-not-rocket-science/ananke/tier2` (or existing domain subpaths such as `/combat`, `/campaign`, `/social`, `/narrative`, `/anatomy`, `/crafting`, `/competence`, `/species`, `/polity`, `/catalog`).
+   - Tier 3: `@its-not-rocket-science/ananke/tier3`.
+3. Example:
+
+```ts
+// before
+import { stepWorld, BridgeEngine, resolveTacticalEngagement } from "@its-not-rocket-science/ananke";
+
+// after
+import { stepWorld } from "@its-not-rocket-science/ananke";
+import { BridgeEngine } from "@its-not-rocket-science/ananke/tier2";
+import { resolveTacticalEngagement } from "@its-not-rocket-science/ananke/tier3";
+```
+
+### Notes
+
+- This release intentionally tightens the semver-stable surface to improve long-term supportability.
+- No Tier-1 symbol was removed without a documented migration path.
+
+---
+
+## [0.1.69] — 2026-04-01
+
+### Added
+
+- **PM-10 — Maintenance Budget Roadmap (complete):**
+  - `docs/maintenance-policy.md` (new): standing maintenance commitments covering:
+    - **Docs reconciliation** — `generate-module-index` + `generate-recipes-matrix` must match committed files before every release.
+    - **Issue triage cadence** — P0 (regression) same day; P1 (correctness) within one week; P2 (enhancement) roadmap-tracked; P3 (docs) best-effort.
+    - **Migration maintenance** — every minor version bump that changes a `@core` field must ship a registered migration in `src/schema-migration.ts`.
+    - **SDK parity policy** — Unity, Godot, and Web sidecars must update to the current `BRIDGE_SCHEMA_VERSION` within one minor release.
+    - **Example and corpus upkeep** — all `examples/` compile cleanly; `npm run verify-corpus` passes on every release.
+    - **Content-pack schema evolution** — minor bumps are backward-compatible; major bumps ship a migration tool.
+    - **Coverage floor** — statements 90%, branches 80%, functions 85%, lines 90%.
+    - **Deprecation budget** — no more than 10 symbols in deprecated state at once.
+  - `docs/maintenance-checklist.md` (new): per-release preparation checklist (10 sections, 30 items) operationalising the policy; includes a hotfix fast-path for P0 regressions.
+  - Link added to `README.md` Further Reading table.
+- 0 new tests (5,593 total). Coverage: 97.06%/88.06%/95.83%/97.06%. Build: clean.
+
+---
+
 ## [0.1.68] — 2026-04-01
 
 ### Added