@its-not-rocket-science/ananke 0.1.65 → 0.1.67

package/CHANGELOG.md

@@ -6,6 +6,48 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.67] — 2026-04-01
+
+### Added
+
+- **PM-8 — Scenario Corpus as Shared Benchmark and Pedagogy Asset (complete):**
+  - `corpus/` directory with 5 canonical deterministic scenarios, each carrying a `corpus.json` manifest (`version`, `id`, `title`, `tags`, `stabilityStatus`, `scenario`, `expectedOutputHash`, `performanceClass`, `replayFixture`, `bridgeExpected`).
+  - Tags: `tutorial`, `benchmark`, `validation`, `networking`, `bridge`, `content-pack`.
+  - Entries: `basic-duel` (tutorial, 30 ticks), `armoured-combat` (validation+content-pack, 50 ticks), `lockstep-replay` (networking, 10 ticks + replay.json fixture), `bridge-snapshot` (bridge, 0 ticks), `ai-benchmark` (benchmark, 20 ticks).
+  - `tools/generate-corpus.ts`: regenerates all corpus entries from scenario definitions; computes world-state hashes, replay fixtures, and bridge-frame invariants. Run after any change to `stepWorld`, `hashWorldState`, or equipment constants.
+  - `tools/verify-corpus.ts`: verifies all corpus entries against the live engine; checks world-state hash, replay parity (networking), and bridge frame shape (bridge). Supports `--id=<entry>` and `--json` flags.
+  - npm scripts: `generate-corpus`, `verify-corpus`.
+  - `corpus` added to `package.json` `files` array (shipped with the npm package).
+  - Links added to README "Further Reading" table and `docs/cookbook.md` "Further reading" table.
+- 0 new tests (5,593 total). Coverage: 97.11%/88.07%/95.83%/97.11%. Build: clean.
+
+---
+
+## [0.1.66] — 2026-04-01
+
+### Added
+
+- **PM-7 — API Deprecation Framework (complete):**
+  - `tools/audit-deprecations.ts` (new): scans all `src/` TypeScript files for `@deprecated` JSDoc tags and outputs a structured table of `{ symbol, file, line, since, removeAfter, replacement, overdue }`.
+    - `--json` flag: machine-readable JSON output with timestamp, engine version, and full entry list.
+    - `--check` flag: exits 1 if any symbol's `removeAfter` version ≤ current engine version (overdue).
+  - `prepublishOnly` now includes `npm run audit-deprecations -- --check`: `npm publish` fails if any symbol is overdue for removal.
+  - npm script: `audit-deprecations`.
+  - Structured `@deprecated` convention defined: `@deprecated since {version} — use {replacement} instead. Removes at {removeAfter}.`
+  - All three existing `@deprecated` tags in `src/` updated to the new structured format:
+    - `anankeVersion` in `content-pack.ts`: since 0.1.65, removes at 0.3.0
+    - `Perception` type alias in `sim/ai/perception.ts`: since 0.1.0, removes at 0.3.0
+    - `mkWorld(seed, loadout)` overload in `sim/testing.ts`: since 0.1.0, removes at 0.2.0
+  - `docs/versioning.md`: new "Deprecation lifecycle" section documenting the three-phase pattern (mark → migration window → remove), the required tag format, and the audit checklist.
+  - `docs/module-index.md`: new "Deprecated exports" table surfacing all known deprecated symbols with since/removeAfter/replacement.
+- 0 new tests (5,593 total). Coverage: 97.11%/88.07%/95.83%/97.11%. Build: clean.
+
+### Deprecated
+
+- `AnankePackManifest.anankeVersion` — since 0.1.65, use `registry.compatRange` instead. Removes at 0.3.0.
+
+---
+
 ## [0.1.65] — 2026-04-01
 
 ### Added

package/README.md

@@ -418,6 +418,7 @@ Ananke's outputs are validated against historical and experimental sources:
 |---|---|
 | [`docs/recipes-matrix.md`](docs/recipes-matrix.md) | **Start here** — use case → package → stability → example → performance in one table |
 | [`docs/cookbook.md`](docs/cookbook.md) | Task-oriented recipes — duel, 500-agent battle, species, renderer, campaign, replay, and more |
+| [`corpus/README.md`](corpus/README.md) | Scenario corpus — 5 canonical deterministic scenarios (tutorial, benchmark, validation, networking, bridge); run `npm run verify-corpus` |
 | [`docs/module-index.md`](docs/module-index.md) | All 41 entry points — stability tier, use case, key exports, doc links |
 | [`docs/host-contract.md`](docs/host-contract.md) | Stable integration surface — everything needed to embed Ananke without reading `src/` |
 | [`docs/integration-primer.md`](docs/integration-primer.md) | Data-flow diagrams, type glossary, gotchas |

package/corpus/README.md

@@ -0,0 +1,47 @@
+# Ananke — Scenario Corpus
+
+Each subdirectory contains a `corpus.json` manifest describing a canonical
+deterministic scenario.  Run `npm run verify-corpus` to verify all entries
+against the reference engine.
+
+## Entries
+
+| ID | Tags | Ticks | Description |
+|----|------|-------|-------------|
+| `basic-duel` | `tutorial` | 30 | Basic 1v1 Duel (No AI) |
+| `armoured-combat` | `validation`, `content-pack` | 50 | Armoured 1v1 Combat (Line Infantry AI) |
+| `lockstep-replay` | `networking` | 10 | Lockstep Replay Parity (10 Ticks) |
+| `bridge-snapshot` | `bridge` | 0 | Renderer Bridge Snapshot |
+| `ai-benchmark` | `benchmark` | 20 | AI Skirmish Benchmark (20 Ticks) |
+
+## Tag meanings
+
+| Tag | Purpose |
+|-----|---------|
+| `tutorial` | Entry-level; no prior knowledge required |
+| `benchmark` | Stable timing baseline; detect performance regressions |
+| `validation` | Compared against empirical data |
+| `networking` | Exercises replay, hash, lockstep |
+| `bridge` | Exercises the renderer bridge |
+| `content-pack` | Exercises equipment loading and composition |
+
+## Verifying
+
+```bash
+npm run build
+npm run verify-corpus              # all entries
+npm run verify-corpus -- --id=basic-duel   # single entry
+npm run verify-corpus -- --json    # machine-readable
+```
+
+## Regenerating
+
+Re-run after any change to `stepWorld`, `hashWorldState`, or equipment constants:
+
+```bash
+npm run build && npm run generate-corpus
+```
+
+## Corpus format version
+
+All manifests carry `"version": "corpus/v1"`.

package/corpus/ai-benchmark/corpus.json

@@ -0,0 +1,36 @@
+{
+  "version": "corpus/v1",
+  "id": "ai-benchmark",
+  "title": "AI Skirmish Benchmark (20 Ticks)",
+  "description": "Two line-infantry entities engaging over 20 ticks. Benchmark scenario: exercises the full AI decision + physics + injury path. Use the timing result to detect performance regressions between engine versions.",
+  "tags": [
+    "benchmark"
+  ],
+  "stabilityStatus": "stable",
+  "scenario": {
+    "seed": 42,
+    "tractionCoeff_Q": 9000,
+    "entities": [
+      {
+        "id": 1,
+        "teamId": 1,
+        "x_m": -0.5,
+        "weapon": "wpn_longsword"
+      },
+      {
+        "id": 2,
+        "teamId": 2,
+        "x_m": 0.5,
+        "weapon": "wpn_longsword"
+      }
+    ],
+    "aiPolicy": "lineInfantry",
+    "tickCount": 20
+  },
+  "expectedOutputHash": "0xacb04548fd68a7fb",
+  "performanceClass": {
+    "entityCount": 2,
+    "expectedTickBudgetMs": 150
+  },
+  "replayFixture": null
+}

package/corpus/armoured-combat/corpus.json

@@ -0,0 +1,39 @@
+{
+  "version": "corpus/v1",
+  "id": "armoured-combat",
+  "title": "Armoured 1v1 Combat (Line Infantry AI)",
+  "description": "Two entities equipped with chainmail armour and longswords, driven by lineInfantry AI. Validation scenario: armour damage absorption, shock accumulation, and equipment interaction over 50 ticks.",
+  "tags": [
+    "validation",
+    "content-pack"
+  ],
+  "stabilityStatus": "stable",
+  "scenario": {
+    "seed": 42,
+    "tractionCoeff_Q": 9000,
+    "entities": [
+      {
+        "id": 1,
+        "teamId": 1,
+        "x_m": -0.5,
+        "weapon": "wpn_longsword",
+        "armour": "arm_chainmail"
+      },
+      {
+        "id": 2,
+        "teamId": 2,
+        "x_m": 0.5,
+        "weapon": "wpn_longsword",
+        "armour": "arm_chainmail"
+      }
+    ],
+    "aiPolicy": "lineInfantry",
+    "tickCount": 50
+  },
+  "expectedOutputHash": "0x8231f53b3211a379",
+  "performanceClass": {
+    "entityCount": 2,
+    "expectedTickBudgetMs": 200
+  },
+  "replayFixture": null
+}

package/corpus/basic-duel/corpus.json

@@ -0,0 +1,36 @@
+{
+  "version": "corpus/v1",
+  "id": "basic-duel",
+  "title": "Basic 1v1 Duel (No AI)",
+  "description": "Two entities face off with longswords and no AI commands. Entry-level tutorial: demonstrates combat resolution, injury accumulation, and deterministic world-state hashing over 30 ticks.",
+  "tags": [
+    "tutorial"
+  ],
+  "stabilityStatus": "stable",
+  "scenario": {
+    "seed": 42,
+    "tractionCoeff_Q": 9000,
+    "entities": [
+      {
+        "id": 1,
+        "teamId": 1,
+        "x_m": -0.5,
+        "weapon": "wpn_longsword"
+      },
+      {
+        "id": 2,
+        "teamId": 2,
+        "x_m": 0.5,
+        "weapon": "wpn_longsword"
+      }
+    ],
+    "aiPolicy": "noMove",
+    "tickCount": 30
+  },
+  "expectedOutputHash": "0x7d82acd3d1966c61",
+  "performanceClass": {
+    "entityCount": 2,
+    "expectedTickBudgetMs": 100
+  },
+  "replayFixture": null
+}

package/corpus/bridge-snapshot/corpus.json

@@ -0,0 +1,42 @@
+{
+  "version": "corpus/v1",
+  "id": "bridge-snapshot",
+  "title": "Renderer Bridge Snapshot",
+  "description": "Two entities at tick 0 serialized through serializeBridgeFrame. Bridge scenario: verifies the BridgeFrame schema version, tick, entity count, and entity IDs. Baseline for renderer integration testing.",
+  "tags": [
+    "bridge"
+  ],
+  "stabilityStatus": "stable",
+  "scenario": {
+    "seed": 42,
+    "tractionCoeff_Q": 9000,
+    "entities": [
+      {
+        "id": 1,
+        "teamId": 1,
+        "x_m": -0.5,
+        "weapon": "wpn_longsword"
+      },
+      {
+        "id": 2,
+        "teamId": 2,
+        "x_m": 0.5,
+        "weapon": "wpn_longsword"
+      }
+    ],
+    "aiPolicy": "noMove",
+    "tickCount": 0
+  },
+  "expectedOutputHash": "0xec578e005fcbef34",
+  "performanceClass": {
+    "entityCount": 2,
+    "expectedTickBudgetMs": 10
+  },
+  "replayFixture": null,
+  "bridgeExpected": {
+    "schema": "ananke.bridge.frame.v1",
+    "tick": 0,
+    "entityCount": 2,
+    "scenarioId": "corpus-bridge"
+  }
+}

package/corpus/lockstep-replay/corpus.json

@@ -0,0 +1,36 @@
+{
+  "version": "corpus/v1",
+  "id": "lockstep-replay",
+  "title": "Lockstep Replay Parity (10 Ticks)",
+  "description": "Two entities with noMove commands over 10 ticks. Networking scenario: records a reference replay and verifies that replayTo() reproduces identical world-state hashes at each tick. Use as a correctness check when porting to a new host environment.",
+  "tags": [
+    "networking"
+  ],
+  "stabilityStatus": "stable",
+  "scenario": {
+    "seed": 42,
+    "tractionCoeff_Q": 9000,
+    "entities": [
+      {
+        "id": 1,
+        "teamId": 1,
+        "x_m": -0.5,
+        "weapon": "wpn_longsword"
+      },
+      {
+        "id": 2,
+        "teamId": 2,
+        "x_m": 0.5,
+        "weapon": "wpn_longsword"
+      }
+    ],
+    "aiPolicy": "noMove",
+    "tickCount": 10
+  },
+  "expectedOutputHash": "0x8fe5f3eba59e0b75",
+  "performanceClass": {
+    "entityCount": 2,
+    "expectedTickBudgetMs": 200
+  },
+  "replayFixture": "replay.json"
+}

package/corpus/lockstep-replay/replay.json

@@ -0,0 +1 @@
+{"initialState":{"tick":0,"seed":42,"entities":[{"id":1,"teamId":1,"attributes":{"morphology":{"stature_m":17400,"mass_kg":74977,"actuatorMass_kg":30125,"actuatorScale":9946,"structureScale":20000,"reachScale":10233},"performance":{"peakForce_N":165802,"peakPower_W":3600,"continuousPower_W":128,"reserveEnergy_J":15800,"conversionEfficiency":8651},"control":{"controlQuality":6848,"reactionTime_s":2329,"stability":6855,"fineControl":7624},"resilience":{"surfaceIntegrity":9459,"bulkIntegrity":9437,"structureIntegrity":10163,"distressTolerance":4629,"shockTolerance":5169,"concussionTolerance":5526,"heatTolerance":4758,"coldTolerance":4505,"fatigueRate":9668,"recoveryRate":10195},"perception":{"visionRange_m":2000000,"visionArcDeg":120,"halfArcCosQ":5000,"hearingRange_m":500000,"decisionLatency_s":5000,"attentionDepth":4,"threatHorizon_m":400000},"cognition":{"linguistic":6500,"logicalMathematical":6000,"spatial":6000,"bodilyKinesthetic":6000,"musical":5000,"interpersonal":6000,"intrapersonal":5500,"naturalist":5000,"interSpecies":3500}},"energy":{"reserveEnergy_J":15800,"fatigue":0},"loadout":{"items":[{"id":"wpn_longsword","kind":"weapon","name":"Longsword","mass_kg":1500,"bulk":15000,"reach_m":9000,"handedness":"twoHand","momentArm_m":5500,"handlingMul":10500,"strikeEffectiveMassFrac":1500,"strikeSpeedMul":10000,"readyTime_s":7500,"damage":{"surfaceFrac":3500,"internalFrac":4500,"structuralFrac":2000,"bleedFactor":7000,"penetrationBias":4000}}]},"traits":[],"position_m":{"x":-5000,"y":0,"z":0},"velocity_mps":{"x":0,"y":0,"z":0},"intent":{"move":{"dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"},"defence":{"mode":"none","intensity":0},"prone":false},"action":{"attackCooldownTicks":0,"defenceCooldownTicks":0,"grappleCooldownTicks":0,"facingDirQ":{"x":10000,"y":0,"z":0},"weaponBindPartnerId":0,"weaponBindTicks":0,"swingMomentumQ":0,"shootCooldownTicks":0,"aimTicks":0,"aimTargetId":0},"condition":{"onFire":0,"corrosiveExposure":0,"radiation":0,"electricalOverload":0,"suffocation":0,"stunned":0,"prone":false,"pinned":false,"standBlockedTicks":0,"unconsciousTicks":0,"suppressedTicks":0,"blindTicks":0,"fearQ":0,"suppressionFearMul":10000,"recentAllyDeaths":0,"lastAllyDeathTick":-1,"surrendered":false,"rallyCooldownTicks":0},"injury":{"byRegion":{"head":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"torso":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"leftArm":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"rightArm":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"leftLeg":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"rightLeg":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0}},"fluidLoss":0,"shock":0,"consciousness":10000,"dead":false,"hemolymphLoss":0},"grapple":{"holdingTargetId":0,"heldByIds":[],"gripQ":0,"position":"standing"}},{"id":2,"teamId":2,"attributes":{"morphology":{"stature_m":17440,"mass_kg":74182,"actuatorMass_kg":29420,"actuatorScale":9904,"structureScale":20000,"reachScale":9895},"performance":{"peakForce_N":154468,"peakPower_W":3600,"continuousPower_W":129,"reserveEnergy_J":14502,"conversionEfficiency":8557},"control":{"controlQuality":7058,"reactionTime_s":2091,"stability":6517,"fineControl":7109},"resilience":{"surfaceIntegrity":9544,"bulkIntegrity":10338,"structureIntegrity":9742,"distressTolerance":5605,"shockTolerance":5235,"concussionTolerance":4836,"heatTolerance":5353,"coldTolerance":4988,"fatigueRate":9233,"recoveryRate":9064},"perception":{"visionRange_m":2000000,"visionArcDeg":120,"halfArcCosQ":5000,"hearingRange_m":500000,"decisionLatency_s":5000,"attentionDepth":4,"threatHorizon_m":400000},"cognition":{"linguistic":6500,"logicalMathematical":6000,"spatial":6000,"bodilyKinesthetic":6000,"musical":5000,"interpersonal":6000,"intrapersonal":5500,"naturalist":5000,"interSpecies":3500}},"energy":{"reserveEnergy_J":14502,"fatigue":0},"loadout":{"items":[{"id":"wpn_longsword","kind":"weapon","name":"Longsword","mass_kg":1500,"bulk":15000,"reach_m":9000,"handedness":"twoHand","momentArm_m":5500,"handlingMul":10500,"strikeEffectiveMassFrac":1500,"strikeSpeedMul":10000,"readyTime_s":7500,"damage":{"surfaceFrac":3500,"internalFrac":4500,"structuralFrac":2000,"bleedFactor":7000,"penetrationBias":4000}}]},"traits":[],"position_m":{"x":5000,"y":0,"z":0},"velocity_mps":{"x":0,"y":0,"z":0},"intent":{"move":{"dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"},"defence":{"mode":"none","intensity":0},"prone":false},"action":{"attackCooldownTicks":0,"defenceCooldownTicks":0,"grappleCooldownTicks":0,"facingDirQ":{"x":10000,"y":0,"z":0},"weaponBindPartnerId":0,"weaponBindTicks":0,"swingMomentumQ":0,"shootCooldownTicks":0,"aimTicks":0,"aimTargetId":0},"condition":{"onFire":0,"corrosiveExposure":0,"radiation":0,"electricalOverload":0,"suffocation":0,"stunned":0,"prone":false,"pinned":false,"standBlockedTicks":0,"unconsciousTicks":0,"suppressedTicks":0,"blindTicks":0,"fearQ":0,"suppressionFearMul":10000,"recentAllyDeaths":0,"lastAllyDeathTick":-1,"surrendered":false,"rallyCooldownTicks":0},"injury":{"byRegion":{"head":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"torso":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"leftArm":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"rightArm":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"leftLeg":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0},"rightLeg":{"surfaceDamage":0,"internalDamage":0,"structuralDamage":0,"bleedingRate":0,"fractured":false,"infectedTick":-1,"bleedDuration_ticks":0,"permanentDamage":0}},"fluidLoss":0,"shock":0,"consciousness":10000,"dead":false,"hemolymphLoss":0},"grapple":{"holdingTargetId":0,"heldByIds":[],"gripQ":0,"position":"standing"}}]},"frames":[{"tick":0,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":1,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":2,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":3,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":4,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":5,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":6,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":7,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":8,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]},{"tick":9,"commands":[[1,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]],[2,[{"kind":"move","dir":{"x":0,"y":0,"z":0},"intensity":0,"mode":"walk"}]]]}]}

package/dist/src/content-pack.d.ts

@@ -1,6 +1,6 @@
 import type { WorldState } from "./sim/world.js";
 /** Current Ananke engine version — used to evaluate pack compatRange at runtime. */
-export declare const ANANKE_ENGINE_VERSION = "0.1.65";
+export declare const ANANKE_ENGINE_VERSION = "0.1.67";
 /** A single actionable validation failure from `validatePack`. */
 export interface PackValidationError {
     /** JSONPath-style location, e.g. `"$.weapons[2].mass_kg"`. */
@@ -81,7 +81,7 @@ export interface AnankePackManifest {
     description?: string;
     /**
      * Minimum Ananke version required, as a semver range string.
-     * @deprecated Use `registry.compatRange` instead — this field is informational only.
+     * @deprecated since 0.1.65 — use `registry.compatRange` instead. Removes at 0.3.0.
      */
     anankeVersion?: string;
     /**

package/dist/src/content-pack.js

@@ -16,7 +16,7 @@ import { registerWorldArchetype, registerWorldItem } from "./world-factory.js";
 // ── Version constant ──────────────────────────────────────────────────────────
 // Must be kept in sync with package.json "version" field.
 /** Current Ananke engine version — used to evaluate pack compatRange at runtime. */
-export const ANANKE_ENGINE_VERSION = "0.1.65";
+export const ANANKE_ENGINE_VERSION = "0.1.67";
 // ── Semver utilities ──────────────────────────────────────────────────────────
 // Lightweight range evaluator — no external dependencies.
 // Supports: >=X.Y.Z  >X.Y.Z  <=X.Y.Z  <X.Y.Z  =X.Y.Z  ^X.Y.Z  ~X.Y.Z

package/dist/src/sim/ai/perception.d.ts

@@ -7,6 +7,6 @@ export interface LocalPerception {
     enemies: Entity[];
     allies: Entity[];
 }
-/** @deprecated Use LocalPerception */
+/** @deprecated since 0.1.0 — use `LocalPerception` instead. Removes at 0.3.0. */
 export type Perception = LocalPerception;
 export declare function perceiveLocal(world: WorldState | undefined, self: Entity, index: WorldIndex, spatial: SpatialIndex, radius_m: number, maxCount?: number, env?: SensoryEnvironment): LocalPerception;

package/dist/src/sim/testing.d.ts

@@ -8,6 +8,6 @@ import { ImpactEvent } from "./events.js";
  */
 export declare function mkHumanoidEntity(id: number, teamId: number, x_m: number, y_m: number, z_m?: number): Entity;
 export declare function mkWorld(seed: number, entities: Entity[]): WorldState;
-/** @deprecated Pass an explicit entity array instead: mkWorld(seed, [a, b]) */
+/** @deprecated since 0.1.0 — use `mkWorld(seed, entities[])` instead. Removes at 0.2.0. */
 export declare function mkWorld(seed: number, loadoutA: Loadout): WorldState;
 export declare function mkImpactEvent(attackerId: number, targetId: number, region?: string, energy_J?: number, protectedByArmour?: boolean, blocked?: boolean, parried?: boolean, weaponId?: string, wpn?: Weapon, hitQuality?: number, shieldBlocked?: boolean): ImpactEvent;

package/docs/versioning.md

@@ -179,3 +179,67 @@ body plan hooks):
 3. Keep an `UPSTREAM.md` at your fork root noting your base version and a diff summary
 4. Periodically rebase onto upstream Tier 3 commits to collect non-breaking improvements;
    treat Tier 1/2 commits as explicit migration tasks to schedule
+
+---
+
+## Deprecation lifecycle
+
+Symbols are deprecated rather than removed immediately so downstream projects have time
+to migrate.  The lifecycle follows a three-phase pattern:
+
+### 1 — Mark deprecated (current version)
+
+Add a structured JSDoc tag to the symbol:
+
+```typescript
+/**
+ * @deprecated since 0.1.50 — use `newFunction` instead. Removes at 0.3.0.
+ */
+export function oldFunction() { … }
+```
+
+The **required format** is:
+
+```
+@deprecated since {version} — use {replacement} instead. Removes at {removeAfter}.
+```
+
+| Field | Meaning |
+|-------|---------|
+| `since` | Version in which the deprecation was introduced |
+| `replacement` | Short description or code reference of what to use instead |
+| `removeAfter` | Version at which the symbol will be deleted — must be a future version |
+
+`removeAfter` must satisfy `> current` at publish time; `npm publish` runs
+`audit-deprecations --check` and fails if any symbol is overdue.
+
+### 2 — Migration window
+
+During the migration window the symbol still works but emits a TypeScript deprecation
+warning in IDEs (the `@deprecated` tag triggers the strikethrough).
+
+The migration window is at least one **minor** version for Tier 2 symbols
+and at least one **major** version for Tier 1 (Stable) symbols.
+
+### 3 — Remove at removeAfter
+
+When the engine reaches `removeAfter`, the symbol is deleted and a CHANGELOG entry is
+added under a `### Removed` heading.  The `since` version and the replacement are
+included in the removal note so the changelog is self-contained.
+
+### Auditing
+
+```bash
+npm run audit-deprecations             # human-readable table
+npm run audit-deprecations -- --json   # machine-readable JSON
+npm run audit-deprecations -- --check  # exit 1 if any overdue
+```
+
+The `--check` flag is run automatically by `npm run prepublishOnly`.
+
+### Adding a new deprecation (checklist)
+
+- [ ] Add the structured `@deprecated` JSDoc tag with `since`, replacement, and `removeAfter`.
+- [ ] Run `npm run audit-deprecations` to confirm the tag is detected and not overdue.
+- [ ] Add a CHANGELOG entry under `### Deprecated`.
+- [ ] Surface the replacement in the relevant `docs/` file or `STABLE_API.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -214,6 +214,7 @@
     "dist/src",
     "dist/as",
     "conformance",
+    "corpus",
     "docs/project-overview.md",
     "docs/host-contract.md",
     "docs/integration-primer.md",
@@ -247,7 +248,7 @@
     "game-engine"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build && npm run test:coverage",
+    "prepublishOnly": "npm run build && npm run test:coverage && npm run audit-deprecations -- --check",
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -286,6 +287,8 @@
     "generate-recipes-matrix": "node dist/tools/generate-recipes-matrix.js",
     "generate-conformance-fixtures": "node dist/tools/generate-conformance-fixtures.js",
     "conformance-runner": "node dist/tools/conformance-runner.js",
+    "generate-corpus": "node dist/tools/generate-corpus.js",
+    "verify-corpus": "node dist/tools/verify-corpus.js",
     "pack": "node dist/tools/pack-cli.js pack",
     "generate-fixtures": "node dist/tools/generate-fixtures.js",
     "generate-zoo": "node dist/tools/generate-zoo.js",
@@ -298,6 +301,7 @@
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",
     "benchmark-check:update": "node dist/tools/benchmark-check.js --update-baseline",
+    "audit-deprecations": "node dist/tools/audit-deprecations.js",
     "benchmark:guide": "node dist/tools/benchmark-guide.js",
     "benchmark:parallel": "node dist/tools/benchmark-parallel.js",
     "run:renderer-bridge": "node dist/tools/renderer-bridge.js",