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

package/CHANGELOG.md

@@ -6,6 +6,29 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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.65";
 /** 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 Use `registry.compatRange` instead — this field is informational only.
      */
     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.65";
+// ── 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.64",
+  "version": "0.1.65",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",

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",