@its-not-rocket-science/ananke 0.1.64 → 0.1.66

package/CHANGELOG.md

@@ -6,6 +6,54 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+
+- **PM-6 — Content-Pack Registry Format (complete):**
+  - `PackRegistryMeta` interface (new): optional `registry` block in `AnankePackManifest` with fields:
+    - `compatRange` (string): semver range enforced at runtime by `validatePack` — rejects packs incompatible with the running engine version.
+    - `stabilityTier` (`"stable"` | `"experimental"` | `"internal"`): controls listing in a public registry.
+    - `requiredExports` (string[]): subpath exports the pack's content depends on — informational.
+    - `checksum` (string): SHA-256 hex digest of the pack JSON — computed by `npx ananke pack bundle`, verified by the host.
+    - `license` (string): SPDX identifier.
+    - `provenance` (object[]): dataset / paper references for empirically grounded content.
+  - `PackStabilityTier` and `PackProvenanceRef` types (new, exported from `"./content-pack"`).
+  - `ANANKE_ENGINE_VERSION = "0.1.65"` constant (new, exported from `"./content-pack"`): current engine version used in `compatRange` evaluation.
+  - `semverSatisfies(version, range)` (new, exported): lightweight semver range evaluator — supports `>=`, `>`, `<=`, `<`, `=`, `^` (caret), `~` (tilde), bare version, and compound space-separated ranges. No external dependencies.
+  - `validatePack` extended to validate all registry sub-fields and reject incompatible `compatRange`.
+  - `tools/pack-cli.ts` `bundle` command: automatically computes SHA-256 checksum and embeds it in `registry.checksum` before writing the bundle.
+  - `schema/pack.schema.json`: `registry` block with full JSON Schema definition for all sub-fields.
+  - `docs/pack-registry-spec.md` (new): full specification — field reference, checksum algorithm, runtime enforcement table, future online registry design.
+- 24 new tests (5,593 total). Coverage: 97.11%/88.07%/95.83%/97.11%. Build: clean.
+
+---
+
 ## [0.1.64] — 2026-04-01
 
 ### Added

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

@@ -1,4 +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.66";
 /** A single actionable validation failure from `validatePack`. */
 export interface PackValidationError {
     /** JSONPath-style location, e.g. `"$.weapons[2].mass_kg"`. */
@@ -6,6 +8,61 @@ export interface PackValidationError {
     /** Human-readable explanation of what is wrong. */
     message: string;
 }
+/** Stability tier for a content pack — controls how it is listed in a registry. */
+export type PackStabilityTier = "stable" | "experimental" | "internal";
+/** Dataset or paper reference for empirically grounded pack content. */
+export interface PackProvenanceRef {
+    /** Short description of the source. */
+    title: string;
+    /** URL of the source, if available. */
+    url?: string;
+    /** DOI of the source, if applicable. */
+    doi?: string;
+    /** Free-text notes about what this source grounds. */
+    notes?: string;
+}
+/**
+ * Registry metadata block — optional top-level section of a pack manifest.
+ *
+ * Including a `registry` block enables:
+ * - Runtime compatibility checking via `compatRange`
+ * - Deterministic integrity verification via `checksum` (SHA-256)
+ * - Licensing and provenance attestation for empirical content
+ *
+ * Generate the checksum with:
+ *   `npx ananke pack bundle <dir>`  (embeds it automatically)
+ *
+ * or manually with `computePackChecksum(manifest)` from `@ananke/content-pack`.
+ */
+export interface PackRegistryMeta {
+    /**
+     * Semver range of Ananke engine versions this pack targets.
+     * Examples: `">=0.1.50"`, `">=0.1 <0.2"`, `"^0.1.60"`.
+     * `validatePack` rejects packs whose `compatRange` excludes the running version.
+     */
+    compatRange?: string;
+    /** Stability guarantee — governs how the pack appears in a public registry. */
+    stabilityTier?: PackStabilityTier;
+    /**
+     * Subpath exports from `@its-not-rocket-science/ananke` that this pack's
+     * content references, e.g. `["./combat", "./catalog"]`.
+     * Informational only — not enforced at runtime.
+     */
+    requiredExports?: string[];
+    /**
+     * SHA-256 hex digest of the pack JSON (with `registry.checksum` set to `""`
+     * before hashing, so the field is present but blank).
+     * Compute with `npx ananke pack bundle` or `computePackChecksum`.
+     */
+    checksum?: string;
+    /** SPDX license identifier, e.g. `"MIT"`, `"CC-BY-4.0"`. */
+    license?: string;
+    /**
+     * Dataset or paper references for empirically grounded pack content.
+     * Include when your pack derives parameters from research data.
+     */
+    provenance?: PackProvenanceRef[];
+}
 /**
  * The `.ananke-pack` manifest schema.
  *
@@ -24,9 +81,14 @@ export interface AnankePackManifest {
     description?: string;
     /**
      * Minimum Ananke version required, as a semver range string.
-     * Used for documentation only — not enforced at runtime in v0.1.
+     * @deprecated since 0.1.65 — use `registry.compatRange` instead. Removes at 0.3.0.
      */
     anankeVersion?: string;
+    /**
+     * Registry metadata — compatibility, checksum, license, and provenance.
+     * `registry.compatRange` is enforced at runtime by `validatePack`.
+     */
+    registry?: PackRegistryMeta;
     /** Weapon definitions — each passed to `registerWeapon`. */
     weapons?: unknown[];
     /** Armour definitions — each passed to `registerArmour`. */
@@ -59,6 +121,11 @@ export interface LoadPackResult {
     /** Validation and registration errors.  Empty on full success. */
     errors: PackValidationError[];
 }
+/**
+ * Test whether `version` satisfies `range`.
+ * Returns `false` if the range string is unparseable.
+ */
+export declare function semverSatisfies(version: string, range: string): boolean;
 /**
  * Validate a pack manifest for structural conformance without loading it.
  *

package/dist/src/content-pack.js

@@ -13,6 +13,95 @@ import { registerWeapon, registerArmour, registerArchetype } from "./catalog.js"
 import { validateScenario, loadScenario } from "./scenario.js";
 import { hashMod } from "./modding.js";
 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.66";
+// ── 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
+// Short forms X.Y and X treated as X.Y.0 and X.0.0 respectively.
+// Compound ranges (space-separated) require all constraints to match.
+function parseSemverTuple(v) {
+    const parts = v.replace(/^v/, "").split(".").map(Number);
+    if (parts.some(isNaN))
+        return null;
+    const [major = 0, minor = 0, patch = 0] = parts;
+    return [major, minor, patch];
+}
+function cmpSemver(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    return a[2] - b[2];
+}
+/**
+ * Test whether `version` satisfies `range`.
+ * Returns `false` if the range string is unparseable.
+ */
+export function semverSatisfies(version, range) {
+    const ver = parseSemverTuple(version);
+    if (!ver)
+        return false;
+    const constraints = range.trim().split(/\s+/);
+    for (const constraint of constraints) {
+        if (!evalConstraint(ver, constraint.trim()))
+            return false;
+    }
+    return true;
+}
+function evalConstraint(ver, c) {
+    // Caret: ^X.Y.Z — compatible within the leftmost non-zero component.
+    // ^1.2.3 → >=1.2.3 <2.0.0 (major locked when major > 0)
+    // ^0.2.3 → >=0.2.3 <0.3.0 (minor locked when major == 0, minor > 0)
+    // ^0.0.3 → >=0.0.3 <0.0.4 (patch locked when both major and minor == 0)
+    if (c.startsWith("^")) {
+        const lo = parseSemverTuple(c.slice(1));
+        if (!lo)
+            return false;
+        let hi;
+        if (lo[0] > 0)
+            hi = [lo[0] + 1, 0, 0];
+        else if (lo[1] > 0)
+            hi = [0, lo[1] + 1, 0];
+        else
+            hi = [0, 0, lo[2] + 1];
+        return cmpSemver(ver, lo) >= 0 && cmpSemver(ver, hi) < 0;
+    }
+    // Tilde: ~X.Y.Z → >=X.Y.Z <X.(Y+1).0
+    if (c.startsWith("~")) {
+        const lo = parseSemverTuple(c.slice(1));
+        if (!lo)
+            return false;
+        const hi = [lo[0], lo[1] + 1, 0];
+        return cmpSemver(ver, lo) >= 0 && cmpSemver(ver, hi) < 0;
+    }
+    // Comparators
+    if (c.startsWith(">=")) {
+        const t = parseSemverTuple(c.slice(2));
+        return t !== null && cmpSemver(ver, t) >= 0;
+    }
+    if (c.startsWith(">")) {
+        const t = parseSemverTuple(c.slice(1));
+        return t !== null && cmpSemver(ver, t) > 0;
+    }
+    if (c.startsWith("<=")) {
+        const t = parseSemverTuple(c.slice(2));
+        return t !== null && cmpSemver(ver, t) <= 0;
+    }
+    if (c.startsWith("<")) {
+        const t = parseSemverTuple(c.slice(1));
+        return t !== null && cmpSemver(ver, t) < 0;
+    }
+    if (c.startsWith("=")) {
+        const t = parseSemverTuple(c.slice(1));
+        return t !== null && cmpSemver(ver, t) === 0;
+    }
+    // Bare version: exact match
+    const t = parseSemverTuple(c);
+    return t !== null && cmpSemver(ver, t) === 0;
+}
 const _packs = new Map();
 // ── Validation ────────────────────────────────────────────────────────────────
 /**
@@ -39,6 +128,75 @@ export function validatePack(manifest) {
         !/^\d+\.\d+(\.\d+)?$/.test(m["version"])) {
         errors.push({ path: "$.version", message: 'must be a semver string like "1.0.0" or "1.0"' });
     }
+    // Optional: registry block
+    if (m["registry"] !== undefined) {
+        if (typeof m["registry"] !== "object" || m["registry"] === null || Array.isArray(m["registry"])) {
+            errors.push({ path: "$.registry", message: "must be a plain object if present" });
+        }
+        else {
+            const reg = m["registry"];
+            // compatRange — semver range string; must include the running engine version
+            if (reg["compatRange"] !== undefined) {
+                if (typeof reg["compatRange"] !== "string") {
+                    errors.push({ path: "$.registry.compatRange", message: "must be a string" });
+                }
+                else if (!semverSatisfies(ANANKE_ENGINE_VERSION, reg["compatRange"])) {
+                    errors.push({
+                        path: "$.registry.compatRange",
+                        message: `engine version ${ANANKE_ENGINE_VERSION} does not satisfy range "${reg["compatRange"]}"`,
+                    });
+                }
+            }
+            // stabilityTier — must be one of the known tiers
+            const TIERS = ["stable", "experimental", "internal"];
+            if (reg["stabilityTier"] !== undefined && !TIERS.includes(reg["stabilityTier"])) {
+                errors.push({
+                    path: "$.registry.stabilityTier",
+                    message: `must be one of: ${TIERS.join(", ")}`,
+                });
+            }
+            // requiredExports — must be array of strings
+            if (reg["requiredExports"] !== undefined) {
+                if (!Array.isArray(reg["requiredExports"])) {
+                    errors.push({ path: "$.registry.requiredExports", message: "must be an array" });
+                }
+                else {
+                    for (let i = 0; i < reg["requiredExports"].length; i++) {
+                        if (typeof reg["requiredExports"][i] !== "string") {
+                            errors.push({ path: `$.registry.requiredExports[${i}]`, message: "must be a string" });
+                        }
+                    }
+                }
+            }
+            // checksum — must be a 64-char hex string (SHA-256) if present
+            if (reg["checksum"] !== undefined) {
+                if (typeof reg["checksum"] !== "string" || !/^[0-9a-f]{64}$/.test(reg["checksum"])) {
+                    errors.push({ path: "$.registry.checksum", message: "must be a 64-character lowercase hex string (SHA-256)" });
+                }
+            }
+            // license — must be a non-empty string
+            if (reg["license"] !== undefined && (typeof reg["license"] !== "string" || reg["license"].trim() === "")) {
+                errors.push({ path: "$.registry.license", message: "must be a non-empty SPDX identifier string" });
+            }
+            // provenance — must be array of objects with at least a title
+            if (reg["provenance"] !== undefined) {
+                if (!Array.isArray(reg["provenance"])) {
+                    errors.push({ path: "$.registry.provenance", message: "must be an array" });
+                }
+                else {
+                    for (let i = 0; i < reg["provenance"].length; i++) {
+                        const ref = reg["provenance"][i];
+                        if (typeof ref !== "object" || ref === null) {
+                            errors.push({ path: `$.registry.provenance[${i}]`, message: "must be an object" });
+                        }
+                        else if (typeof ref["title"] !== "string") {
+                            errors.push({ path: `$.registry.provenance[${i}].title`, message: "must be a string" });
+                        }
+                    }
+                }
+            }
+        }
+    }
     // Optional arrays — must be arrays if present
     for (const key of ["weapons", "armour", "archetypes", "scenarios"]) {
         if (m[key] !== undefined && !Array.isArray(m[key])) {

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/dist/tools/pack-cli.js

@@ -12,6 +12,7 @@
 //   npx ananke replay diff <a.json> <b.json>
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve, extname, basename } from "node:path";
+import { createHash } from "node:crypto";
 import { validatePack, loadPack } from "../src/content-pack.js";
 import { diffReplayJson } from "../src/netcode.js";
 import { q } from "../src/units.js";
@@ -97,6 +98,13 @@ function cmdBundle(args) {
         if (!bundle.name && typeof partial.name === "string")
             bundle.name = partial.name;
     }
+    // Compute SHA-256 checksum: serialise with checksum="" (placeholder), then hash.
+    // Store in registry block so consumers can verify integrity.
+    if (!bundle.registry)
+        bundle.registry = {};
+    bundle.registry.checksum = ""; // placeholder — field present but blank for hashing
+    const checksumInput = JSON.stringify(bundle, null, 2);
+    bundle.registry.checksum = createHash("sha256").update(checksumInput).digest("hex");
     // Pre-validate before writing
     const errors = validatePack(bundle);
     if (errors.length > 0) {
@@ -107,6 +115,7 @@ function cmdBundle(args) {
     writeFileSync(outFile, json, "utf8");
     console.log(`✓  Bundle written to ${outFile}`);
     console.log(`   weapons: ${bundle.weapons.length}, armour: ${bundle.armour.length}, archetypes: ${bundle.archetypes.length}, scenarios: ${bundle.scenarios.length}`);
+    console.log(`   checksum: ${bundle.registry.checksum}`);
 }
 function cmdLoad(args) {
     const filePath = args[0];

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.64",
+  "version": "0.1.66",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -247,7 +247,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",
@@ -298,6 +298,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",

package/schema/pack.schema.json

@@ -26,7 +26,51 @@
     },
     "anankeVersion": {
       "type": "string",
-      "description": "Minimum Ananke version required (semver range), e.g. \">=0.1\"."
+      "description": "Deprecated: use registry.compatRange instead. Minimum Ananke version required (semver range)."
+    },
+    "registry": {
+      "type": "object",
+      "description": "Registry metadata — compatibility, checksum, license, and provenance. registry.compatRange is enforced at runtime by validatePack.",
+      "properties": {
+        "compatRange": {
+          "type": "string",
+          "description": "Semver range of Ananke engine versions this pack targets, e.g. \">=0.1.50\", \"^0.1.60\". Validated at runtime against the running engine version."
+        },
+        "stabilityTier": {
+          "type": "string",
+          "enum": ["stable", "experimental", "internal"],
+          "description": "Stability guarantee — governs how the pack appears in a public registry."
+        },
+        "requiredExports": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Subpath exports from @its-not-rocket-science/ananke this pack's content depends on. Informational only."
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^([0-9a-f]{64}|)$",
+          "description": "SHA-256 hex digest of the pack JSON (with registry.checksum set to \"\" before hashing). Computed by `npx ananke pack bundle`."
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier, e.g. \"MIT\", \"CC-BY-4.0\"."
+        },
+        "provenance": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["title"],
+            "properties": {
+              "title": { "type": "string" },
+              "url":   { "type": "string" },
+              "doi":   { "type": "string" },
+              "notes": { "type": "string" }
+            }
+          },
+          "description": "Dataset or paper references for empirically grounded pack content."
+        }
+      },
+      "additionalProperties": false
     },
     "weapons": {
       "type": "array",