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

package/docs/session-api.md

@@ -0,0 +1,127 @@
+# Session API (Tier 2 / experimental)
+
+`@its-not-rocket-science/ananke/session` is a **host-oriented facade** over existing public simulation APIs.
+
+> Stability: this subpath is **Tier 2 / experimental**. It is shipped, but it is not covered by Tier 1 stability guarantees.
+
+## Why this API exists
+
+Most hosts need a consistent lifecycle (`create`, `run`, `fork`, save/load) across different simulation modes.
+The session API wraps that lifecycle so hosts can use one integration shape instead of hand-wiring separate tactical and world-evolution loops.
+
+## When to use this vs. low-level functions
+
+Use `@its-not-rocket-science/ananke/session` when you want:
+
+- a mode-aware session handle (`tactical` or `world_evolution`),
+- a common run/fork/serialize flow,
+- host-level orchestration with minimal glue code.
+
+Use low-level functions from `@its-not-rocket-science/ananke` (and other subpaths) when you need:
+
+- full control over each tick and command map internals,
+- mode-specific custom scheduling,
+- direct access to domain primitives without facade constraints.
+
+## Supported modes
+
+- `"tactical"`
+- `"world_evolution"`
+
+## Runtime portability notes (Node vs browser/worker)
+
+`./session` is designed to be importable in browser/worker embedders, but some behavior still varies by runtime:
+
+- **Portable by default**
+  - Core tactical/session lifecycle (`createSession`, `runSession`, `stepSession`, `forkSession`, `serializeSession`, `deserializeSession`) is runtime-neutral and does not require Node globals.
+- **Optional/conditional behavior**
+  - `runSession` strict determinism env override (`ANANKE_STRICT_DETERMINISM`) now only applies when a Node-style `process.env` exists; browser/worker hosts should set `context.strictDeterminism` explicitly instead.
+  - Pack checksum validation (`registry.checksum`) is available from the session path without Node-only imports.
+- **Current limits**
+  - Session pack loading still mutates in-memory global registries (weapons/armour/archetypes/scenario maps) in-process. This is host-runtime portable, but not yet isolated by namespace/sandbox.
+  - `./session` does not provide fetch/file I/O adapters; hosts must supply already-loaded JSON payloads for scenarios/packs.
+
+## Public API surface
+
+### Types
+
+- `SessionMode = "tactical" | "world_evolution"`
+- `SessionConfig`
+- `SessionHandle`
+- `RunSessionRequest`
+- `RunSessionResult`
+- `SessionSummary`
+- `ForkSessionRequest`
+- `LoadSessionPackResult`
+
+### Functions
+
+- `createSession(config)`
+- `runSession(session, request)`
+- `stepSession(session, request?)`
+- `getSessionSummary(session)`
+- `forkSession(session, request?)`
+- `loadSessionPack(manifestOrRequest)`
+- `serializeSession(session)`
+- `deserializeSession(json)`
+
+## Lifecycle
+
+1. **create** — `createSession(config)`
+2. **run** — `runSession(session, { steps, ... })` (or single-step via `stepSession`)
+3. **fork** — `forkSession(session, { ... })`
+4. **pack load** — `loadSessionPack(packJson, { ... })`
+5. **serialize** — `serializeSession(session)`
+6. **deserialize** — `deserializeSession(serialized)`
+
+## Tactical example
+
+```ts no-check-example
+import { createSession, runSession, forkSession, serializeSession, deserializeSession } from "@its-not-rocket-science/ananke/session";
+
+const tactical = createSession({
+  mode: "tactical",
+  worldSeed: 7,
+  entities: [
+    { id: 1, teamId: 1, seed: 11, archetype: "AMATEUR_BOXER", weaponId: "fists" },
+    { id: 2, teamId: 2, seed: 22, archetype: "AMATEUR_BOXER", weaponId: "fists" },
+  ],
+  enableReplay: true,
+});
+
+runSession(tactical, { steps: 10 });
+const branch = forkSession(tactical, { id: "what-if-branch" });
+
+const snapshot = serializeSession(branch);
+const restored = deserializeSession(snapshot);
+runSession(restored, { steps: 5 });
+```
+
+## World-evolution example
+
+```ts no-check-example
+import { createSession, runSession, serializeSession, deserializeSession } from "@its-not-rocket-science/ananke/session";
+
+const worldEvolution = createSession({
+  mode: "world_evolution",
+  canonicalSnapshot: {
+    tick: 0,
+    worldSeed: 42,
+    settlements: [],
+    actors: [],
+    metrics: {},
+    activeEvents: [],
+  },
+  rulesetId: "standard",
+  checkpointInterval: 25,
+});
+
+runSession(worldEvolution, {
+  steps: 50,
+  evolution: { includeDeltas: true },
+});
+
+const packed = serializeSession(worldEvolution);
+const resumed = deserializeSession(packed);
+runSession(resumed, { steps: 10 });
+```

package/docs/stable-api-manifest.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "package": "@its-not-rocket-science/ananke",
+  "tier": "tier-1",
+  "entrypoint": "src/index.ts",
+  "symbols": [
+    "AnankeScenario",
+    "AnankeScenarioEntity",
+    "AnimationHints",
+    "Command",
+    "CommandMap",
+    "Entity",
+    "EntitySpec",
+    "G_mps2",
+    "I32",
+    "IndividualAttributes",
+    "KernelContext",
+    "LoadedPlugin",
+    "PluginHookContext",
+    "PluginHooks",
+    "PluginManifest",
+    "PluginModule",
+    "PluginPermission",
+    "PluginRuntimeApi",
+    "Q",
+    "Replay",
+    "ReplayFrame",
+    "ReplayRecorder",
+    "RigSnapshot",
+    "SCALE",
+    "WorldState",
+    "clampQ",
+    "createWorld",
+    "deriveAnimationHints",
+    "deserializeReplay",
+    "extractRigSnapshots",
+    "from",
+    "installPluginFromRegistry",
+    "loadPlugin",
+    "loadScenario",
+    "mulDiv",
+    "q",
+    "qDiv",
+    "qMul",
+    "replayTo",
+    "serializeReplay",
+    "sqrtQ",
+    "stepWorld",
+    "to",
+    "validateScenario"
+  ]
+}

package/docs/trust-dashboard.md

@@ -0,0 +1,37 @@
+# Trust Dashboard
+
+> GENERATED FILE: produced by `npm run generate-trust-dashboard`.
+> Do not edit manually; update source artifacts and regenerate.
+
+_Last updated: 2026-04-13T19:44:52.475Z_
+
+## Status rules (machine-derived)
+
+- **verified**: all required artifacts exist and all checks pass.
+- **partially verified**: required artifacts exist, checks are runnable, and coverage is below threshold.
+- **unverified**: one or more required artifacts are missing or required checks fail.
+
+## Thresholds
+
+- docs coherence: semantic inconsistencies must equal **0**.
+- test coverage: line coverage must be **>= 85%**.
+- determinism: CI matrix must pass, wasm coverage must meet threshold (default **90%** unless CI output overrides), and fuzz executions must meet threshold (default **2000** unless CI output overrides).
+
+## Inputs
+
+- CI outputs: `docs/dashboard/ci-trust-report.json`
+- Test coverage: `coverage/coverage-summary.json`
+- Doc validation reports: `docs/doc-consistency-report.json`
+
+## Status matrix
+
+| Area | Status | Computed summary | Evidence |
+| --- | --- | --- | --- |
+| docs coherence | verified | semantic inconsistencies = 0/0 | doc validation report: `docs/doc-consistency-report.json` |
+| test coverage | unverified | missing coverage summary | coverage summary: `coverage/coverage-summary.json` (missing) |
+| determinism | verified | ci matrix passes=true; wasm coverage 90.00%/90%; fuzz executions 2000/2000 | ci output: `docs/dashboard/ci-trust-report.json` |
+
+## CI stale-file rule
+
+- CI must run `npm run check-trust-dashboard-artifacts`.
+- The check re-renders `docs/trust-dashboard.md` in-memory and fails if the committed file differs.