@series-inc/rundot-syncplay 5.25.0-beta.7 → 5.26.0-beta.0

package/README.md

@@ -1,9 +1,11 @@
 # RUN Syncplay
 
-Syncplay is the orchestration layer over a signed Kinetix runtime. Kinetix owns
-deterministic state, RNG streams, stepping, opaque checkpoints, serialization,
-hydration, and checksums. Syncplay owns inputs, prediction, confirmation,
-rollback policy, replay logs, late join, secrets, and transport.
+Syncplay is the orchestration layer over a signed deterministic runtime. The
+deterministic core ships inside this package under the `/core` subpaths
+(`@series-inc/rundot-syncplay/core/...`): it owns deterministic state, RNG
+streams, stepping, opaque checkpoints, serialization, hydration, and checksums.
+Syncplay owns inputs, prediction, confirmation, rollback policy, replay logs,
+late join, secrets, and transport.
 
 > **Upgrading an existing game?** See
 > [MIGRATING-SESSION-PRIMITIVES.md](./MIGRATING-SESSION-PRIMITIVES.md). Two
@@ -15,9 +17,9 @@ rollback policy, replay logs, late join, secrets, and transport.
 | Concern | Owner |
 |---|---|
 | Committed source capture, upload authority, build lifecycle | Pack API + CLI |
-| Compilation, exact product schema, runtime identity | Kinetix compiler/baker |
+| Compilation, exact product schema, runtime identity | core compiler/baker |
 | Artifact immutability, signing, key trust, catalog eligibility | Pack service + KMS/GCS/Firestore |
-| Deterministic state, RNG streams, step, checkpoint bytes, canonical checksum | Kinetix runtime |
+| Deterministic state, RNG streams, step, checkpoint bytes, canonical checksum | core runtime |
 | Inputs, prediction, confirmation, rollback policy, replay log, late join, secrets, transport | Syncplay |
 | Rendering/interpolation/effects | Presentation adapters outside authoritative state |
 
@@ -25,10 +27,12 @@ There is one session factory:
 
 ```ts
 import { createSyncplaySession } from '@series-inc/rundot-syncplay/browser';
-import { createFixed1000Runtime } from '@series-inc/rundot-kinetix/runtime';
+import { createInstalledPlatformer2dRuntime } from '@series-inc/rundot-syncplay/core/runtime';
 
-const runtime = createFixed1000Runtime({
-  product,
+const runtime = createInstalledPlatformer2dRuntime({
+  pack,
+  levelBytes,
+  identity,
   sessionConfigBytes,
 });
 
@@ -37,16 +41,19 @@ const session = createSyncplaySession(runtime, {
   defaultInput: { throttle: 0, steer: 0, brake: false },
   snapshotBufferSize: 256,
   checksumIntervalFrames: 30,
+  requires: { projection: true },
 });
 ```
 
-The runtime must implement `@series-inc/rundot-kinetix/runtime`. Syncplay never
+The runtime must implement `@series-inc/rundot-syncplay/core/runtime`. Syncplay never
 accepts an initial state, reducer, or creator-authored step callback. There is no
-compatibility mode for the removed reducer API.
+compatibility mode for the removed reducer API. A non-platformer game supplies
+the same ABI through `createInstalledRuntimeAdapter` and binds its source with
+`deriveCustomRuntimeIdentity` plus `kinetixRuntimeModuleManifest`.
 
 ## Runtime and snapshot contract
 
-Live play retains opaque Kinetix checkpoint handles. Rollback restores those
+Live play retains opaque core checkpoint handles. Rollback restores those
 handles directly; it does not serialize or hydrate them. A v2 promotion or
 late-join snapshot contains one opaque `runtimeBytes` payload plus the signed
 runtime identity, canonical session-config digest, frame, and checksum. The
@@ -57,6 +64,23 @@ session-config bytes, asks the game for a matching runtime through its runtime
 factory, and rejects a locally loaded pack mismatch before frame 0. Replays use
 the same identity/config/factory path.
 
+### Capability requirements
+
+Session policies and runner configs accept
+`requires?: { commands?: boolean; projection?: boolean }`. Requirements are
+checked when each offline or networked session is constructed, before any frame
+advances:
+
+| Requirement | Failure |
+|---|---|
+| `projection: true` without `runtime.project` | `SYNCPLAY_PROJECTION_UNSUPPORTED` |
+| `commands: true` with no capabilities declaration | `SYNCPLAY_RUNTIME_CAPABILITY_UNKNOWN` |
+| `commands: true` with `capabilities.commands !== true` | `SYNCPLAY_RUNTIME_COMMANDS_UNSUPPORTED` |
+
+The runner forwards one `requires` policy through both `startOffline()` and
+`startNetworked()`, including reconfigured network sessions. Unknown capability
+metadata never silently passes negotiation.
+
 ## Presentation frames
 
 `session.getState()` returns a detached deep copy of the current frame, which
@@ -113,7 +137,7 @@ npm run test:core
 
 The core suite covers checkpoint ownership/release, frame-zero rollback, v2
 snapshot hydration, replay verification, authority persistence, latency/loss
-convergence, late join, spectators, bots, secrets, and a real Kinetix world
+convergence, late join, spectators, bots, secrets, and a real core world
 driven through `createSyncplaySession`.
 
 ## Unified session runner
@@ -199,8 +223,8 @@ level length — those are game-specific fields inside `sessionConfigBytes`, and
 decode them with your own session-config schema:
 
 ```ts
-import { decodeKinetixSessionConfig } from '@series-inc/rundot-kinetix/runtime';
-import { kinetixPlatformer2dSessionConfigSchema } from '@series-inc/rundot-kinetix/runtime';
+import { decodeKinetixSessionConfig } from '@series-inc/rundot-syncplay/core/runtime';
+import { kinetixPlatformer2dSessionConfigSchema } from '@series-inc/rundot-syncplay/core/runtime';
 
 const prepareNetworkRuntime = async (descriptor, signal) => {
   const session = decodeKinetixSessionConfig(
@@ -241,8 +265,8 @@ permanently unjoinable. `preparePlatformerLevel(api, declaration)` resolves a pi
 and raises the typed `SYNCPLAY_LEVEL_CONTENT_CHANGED` (naming the entry id and the
 edit-vs-pin cause) rather than an opaque `KINETIX_AUX_ASSET_MISMATCH` deep inside
 runtime construction. `declaration.encodeLevel` is an **injected callback**, not a
-static Kinetix import, because Syncplay must compile against both the published
-Kinetix pin and an overlaid local build.
+static core import, so Syncplay's compiled output never hard-binds a specific
+core build.
 
 **Capacity and late-join budgets.** Snapshot transfer defaults are **256 KiB**
 chunks and a **4 MiB** total ceiling; the immutable level payload is fetched and
@@ -252,15 +276,20 @@ protocol/load ceiling, not a 60 Hz performance guarantee for an arbitrary game.
 
 ## Supported correctness kit
 
-`@series-inc/rundot-syncplay/testing` exposes exactly six supported functions —
-no browser or runtime APIs leak through it:
+`@series-inc/rundot-syncplay/testing` exposes exactly nine supported
+entry points — no browser or runtime APIs leak through it:
 
 ```ts
 import {
   assertDeterministic,
   assertLateJoinHydration,
+  assertPresentationParity,
   assertReplayVerifies,
+  assertRunnerLifecycle,
   assertTwoClientConvergence,
+  createSimulatedSyncplayMatch,
+  createSyncplayRunnerHarness,
+  runSyncplaySynctest,
 } from '@series-inc/rundot-syncplay/testing'
 ```
 
@@ -268,5 +297,7 @@ import {
 restore-resim / hydration / replay cert; `assertTwoClientConvergence` and
 `assertLateJoinHydration` run the **real** authority room and networked client
 over a deterministic simulated network (`createSimulatedSyncplayMatch`,
-`runSyncplaySynctest`). Failures name the phase, frame, and disagreeing
-checksums.
+`runSyncplaySynctest`). `createSyncplayRunnerHarness`, `assertRunnerLifecycle`,
+and `assertPresentationParity` cover the runner seam — a real runner driven on
+a fully controlled clock against the simulated match. Failures name the phase,
+frame, and disagreeing checksums.

package/core/authoring.d.ts

@@ -0,0 +1,30 @@
+export type KinetixInstalledProfileName = 'deterministic-f64' | 'fixed-1000-3d';
+
+export type KinetixSessionField =
+  | { type: 'string'; maxBytes: number; required?: boolean }
+  | { type: 'integer'; min: number; max: number; required?: boolean }
+  | { type: 'boolean'; required?: boolean }
+  | { type: 'enum'; values: readonly string[]; required?: boolean };
+
+export interface KinetixSessionConfigSchema {
+  id: string;
+  version: number;
+  maxBytes: number;
+  fields: Readonly<Record<string, KinetixSessionField>>;
+}
+
+export interface KinetixProjectDeclaration {
+  id: string;
+  installedProfile: KinetixInstalledProfileName;
+  tickRate: 10 | 20 | 30 | 60;
+  inputSchema: Readonly<Record<string, unknown>>;
+  sessionConfigSchema: KinetixSessionConfigSchema;
+  mechanics: readonly Readonly<Record<string, unknown>>[];
+  components: readonly Readonly<Record<string, unknown>>[];
+  systems: readonly Readonly<Record<string, unknown>>[];
+  presentationBindings: readonly Readonly<Record<string, unknown>>[];
+}
+
+export function defineKinetixProject<const Project extends KinetixProjectDeclaration>(
+  project: Project,
+): Readonly<Project>;

package/core/deterministic-stdlib.d.ts

@@ -0,0 +1,127 @@
+export interface DeterministicVec2 {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface DeterministicVec3 {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+
+export interface DeterministicQuaternion extends DeterministicVec3 {
+  readonly w: number;
+}
+
+export interface DeterministicMathApi {
+  readonly fixedScale: number;
+  readonly minFixed: number;
+  readonly maxFixed: number;
+  toFixed(value: number): number;
+  fromFixed(value: number): number;
+  add(a: number, b: number): number;
+  sub(a: number, b: number): number;
+  mul(a: number, b: number): number;
+  div(a: number, b: number): number;
+  saturatingAdd(a: number, b: number): number;
+  saturatingSub(a: number, b: number): number;
+  quantize(value: number, engine: number): number;
+  sqrt(value: number): number;
+  integerSqrt(value: number): number;
+  abs(value: number): number;
+  sign(value: number): number;
+  min(a: number, b: number): number;
+  max(a: number, b: number): number;
+  lerp(a: number, b: number, t: number): number;
+  mod(a: number, b: number): number;
+  inverseLerp(a: number, b: number, value: number): number;
+  remap(inMin: number, inMax: number, outMin: number, outMax: number, value: number): number;
+  smoothstep(edge0: number, edge1: number, value: number): number;
+  log2Fixed(value: number): number;
+  log(value: number): number;
+  exp(value: number): number;
+  sinTurns(turns: number): number;
+  cosTurns(turns: number): number;
+  tanTurns(turns: number): number;
+  atan2(y: number, x: number): number;
+  atan2Signed(y: number, x: number): number;
+  wrapTurns(turns: number): number;
+  angleDeltaTurns(a: number, b: number): number;
+  turnsToRadians(turns: number): number;
+  radiansToTurns(radians: number): number;
+  hypot(x: number, y: number): number;
+  vec2(x: number, y: number): DeterministicVec2;
+  vec2Add(a: DeterministicVec2, b: DeterministicVec2): DeterministicVec2;
+  vec2Sub(a: DeterministicVec2, b: DeterministicVec2): DeterministicVec2;
+  vec2Scale(value: DeterministicVec2, scale: number): DeterministicVec2;
+  vec2Dot(a: DeterministicVec2, b: DeterministicVec2): number;
+  vec2Cross(a: DeterministicVec2, b: DeterministicVec2): number;
+  vec2LengthSq(value: DeterministicVec2): number;
+  vec2Length(value: DeterministicVec2): number;
+  vec2DistanceSq(a: DeterministicVec2, b: DeterministicVec2): number;
+  vec2Distance(a: DeterministicVec2, b: DeterministicVec2): number;
+  vec2Normalize(value: DeterministicVec2): DeterministicVec2;
+  vec2Perp(value: DeterministicVec2): DeterministicVec2;
+  vec2Negate(value: DeterministicVec2): DeterministicVec2;
+  vec2Rotate(value: DeterministicVec2, turns: number): DeterministicVec2;
+  vec2FromAngleTurns(turns: number, length: number): DeterministicVec2;
+  vec2AngleTurns(value: DeterministicVec2): number;
+  vec2Lerp(a: DeterministicVec2, b: DeterministicVec2, t: number): DeterministicVec2;
+  vec3(x: number, y: number, z: number): DeterministicVec3;
+  vec3Add(a: DeterministicVec3, b: DeterministicVec3): DeterministicVec3;
+  vec3Sub(a: DeterministicVec3, b: DeterministicVec3): DeterministicVec3;
+  vec3Scale(value: DeterministicVec3, scale: number): DeterministicVec3;
+  vec3Dot(a: DeterministicVec3, b: DeterministicVec3): number;
+  vec3Cross(a: DeterministicVec3, b: DeterministicVec3): DeterministicVec3;
+  vec3LengthSq(value: DeterministicVec3): number;
+  vec3Length(value: DeterministicVec3): number;
+  vec3Distance(a: DeterministicVec3, b: DeterministicVec3): number;
+  vec3Normalize(value: DeterministicVec3): DeterministicVec3;
+  vec3Lerp(a: DeterministicVec3, b: DeterministicVec3, t: number): DeterministicVec3;
+  vec3Negate(value: DeterministicVec3): DeterministicVec3;
+  quatFromYawTurns(turns: number): DeterministicQuaternion;
+  quatLerp(a: DeterministicQuaternion, b: DeterministicQuaternion, t: number): DeterministicQuaternion;
+  clamp(value: number, min: number, max: number): number;
+}
+
+export interface FixedTurnsMathApi {
+  readonly ONE: number;
+  F(value: number): number;
+  mul(a: number, b: number): number;
+  div(a: number, b: number): number;
+  clamp(value: number, min: number, max: number): number;
+  fabs(value: number): number;
+  fsign(value: number): number;
+  lerp(a: number, b: number, t: number): number;
+  fsin(turns: number): number;
+  fcos(turns: number): number;
+}
+
+export interface DeterministicRandomSnapshot {
+  readonly state: number;
+}
+
+export function createDeterministicMath(
+  fixedScale?: number,
+  minFixed?: number,
+  maxFixed?: number,
+): DeterministicMathApi;
+
+export function createFixedTurnsMath(scale: number): FixedTurnsMathApi;
+
+export class DeterministicRandom {
+  state: number;
+  constructor(seed: number);
+  nextUint32(): number;
+  nextInt(minInclusive: number, maxInclusive: number): number;
+  nextFixed(scale?: number): number;
+  fork(label: string): DeterministicRandom;
+  nextBool(): boolean;
+  nextRangeFixed(minFixed: number, maxFixed: number): number;
+  nextAngleTurns(fixedScale: number): number;
+  pickOne<T>(items: readonly T[]): T;
+  weighted<T>(items: readonly T[], weights: readonly number[]): T;
+  gaussian(math: DeterministicMathApi): number;
+  snapshot(): DeterministicRandomSnapshot;
+  restore(snapshot: DeterministicRandomSnapshot): void;
+}