@volter/project 0.5.210 → 0.5.212

package/src/adapter/loop-gate-report.ts

@@ -1,53 +0,0 @@
-/**
- * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
- * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) on
- * its own: a `self-driven` world (an ingested game
- * driving its own rAF/ticker) pauses for real ONLY if its adapter implements an
- * explicit loop-gate capability (`MountedRootBase.setPaused`/`step`) —
- * otherwise it "honestly reports so" rather than a silent no-op (the
- * D5 §5.2 finding: gating a raw-rAF loop from outside was
- * demonstrated and REJECTED). The audio seam (`SystemAdapters.AudioAdapter`)
- * has the identical shape: absent or unable to silence a world's audio on pause
- * must report, not pretend.
- *
- * Pure compute + message-formatting — callers own the actual
- * `console.warn`/`editorConsole.warn` call; this module never logs.
- */
-
-/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
- *  could not actually be gated). */
-export const LOOP_GATE_PREFIX = 'loop-gate';
-
-/** Greppable prefix for an audio-gate shortfall (pause requested, world's
- *  audio could not actually be silenced). */
-export const AUDIO_GATE_PREFIX = 'audio-gate';
-
-/** One shortfall instance: which world, and why the capability wasn't there. */
-export interface CapabilityGateReport {
-  readonly worldId: string;
-  readonly reason: string;
-}
-
-function formatGateMessage(
-  prefix: string,
-  capability: string,
-  report: CapabilityGateReport,
-): string {
-  return (
-    `${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
-    `(${report.reason}) — reporting honestly instead of silently no-op-ing. ` +
-    `${prefix} ${JSON.stringify(report)}`
-  );
-}
-
-/** Format a loop-gate shortfall message (a `self-driven` world with no
- *  working pause capability). */
-export function formatLoopGateMessage(report: CapabilityGateReport): string {
-  return formatGateMessage(LOOP_GATE_PREFIX, "this world's loop", report);
-}
-
-/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
- *  whose adapter cannot actually silence it). */
-export function formatAudioGateMessage(report: CapabilityGateReport): string {
-  return formatGateMessage(AUDIO_GATE_PREFIX, "this world's audio", report);
-}

package/src/adapter/native-entry-surface.ts

@@ -1,100 +0,0 @@
-/**
- * THE ENTRY MODULE'S DECLARED SURFACE — what a project's root entry may export
- * for its own debugger, and the already-validated bindings a host hands on.
- *
- * This is the contract, not an implementation: a root entry writes
- *
- *   export { debug } from './commands';
- *
- * and the command module imports no Volter API — its functions are the
- * application's own functions over its own stores. The READER that validates
- * one of these exports, and the adapter that projects it onto the session's
- * debug/input doors, are the game runtime's
- * (`@volter/editor-game/runtime/adapter/native-debug-module`).
- */
-
-import type { ContractSystemEmptySlot } from './ingest/contract-system-slots';
-import type { SystemAdapters } from './system-adapter';
-
-export const NATIVE_INPUT_VALUE_TYPES = [
-  'digital',
-  'scalar',
-  'vector2',
-  'pointerDelta',
-  'pointerPosition',
-] as const;
-export type NativeInputValueType = (typeof NATIVE_INPUT_VALUE_TYPES)[number];
-export type NativeInputValue = boolean | number | { readonly x: number; readonly y: number };
-
-/** A table may be a THUNK, evaluated once at install (after every project
- *  module has run), so a game whose declarations accrete during module
- *  evaluation — the dev-tools registry's `stat()`/`cheat()` lines beside each
- *  mechanic — hands a complete snapshot without ordering its own imports
- *  around the debugger. */
-export type NativeTable<T> = Readonly<Record<string, T>> | (() => Readonly<Record<string, T>>);
-
-/** A command is a plain function, or `{ description, run }` when it wants the
- *  session's `game.commands()` listing to say what it does. Argument
- *  validation stays inside the function — the game's words at the game's
- *  door. */
-export type NativeCommandEntry =
-  | ((...args: unknown[]) => unknown)
-  | { readonly description?: string; readonly run: (...args: unknown[]) => unknown };
-
-export interface NativeDebugModule {
-  readonly commands?: NativeTable<NativeCommandEntry>;
-  readonly state?: NativeTable<() => unknown>;
-  readonly input?: {
-    /** May be a thunk, read LIVE on every use — an app whose action set loads
-     *  asynchronously (an input map fetched at boot) answers with what it has
-     *  NOW rather than freezing the empty pre-load set at install. */
-    readonly actions:
-      | Readonly<Record<string, NativeInputValueType>>
-      | (() => Readonly<Record<string, NativeInputValueType>>);
-    readonly set: (action: string, value: NativeInputValue) => void;
-    readonly clear: () => void;
-    /** Optional native-scheduler operation. The adapter never synthesizes one. */
-    readonly tap?: (action: string) => void;
-    /** Optional native-scheduler operation. The adapter never adds a host phase. */
-    readonly scheduleAtTick?: (tick: number, action: string, value: NativeInputValue) => void;
-  };
-  /** The app's own EVENT STREAM, bridged into the session's tick-stamped
-   *  event log at install — the entry-export replacement for the react
-   *  emit hook. The app owns the emitter; the host only forwards. */
-  readonly events?: {
-    readonly subscribe: (listener: (event: string, detail?: unknown) => void) => () => void;
-  };
-  /**
-   * `false` while the app is intentionally BETWEEN worlds — a scene remount in flight (a
-   * `reload_current_scene`-style restart unmounts the running scene and the fresh one arrives
-   * on an ASYNC React commit). Session tick drivers (`runTicksWhenSettled`, behind both
-   * run-ticks doors) wait for `true` before each tick, so which tick first runs the fresh
-   * world is a function of the sim, never of wall timing between driver calls. Omitted =
-   * always settled.
-   */
-  readonly settled?: () => boolean;
-}
-
-/** One root's `debug` export, already read and validated, with the root it came from. */
-export interface NativeDebugBinding {
-  readonly rootId: string;
-  readonly debug: NativeDebugModule;
-}
-
-/** One root's statically declared, already-validated system-adapter slots. */
-export interface NativeSystemsBinding {
-  readonly rootId: string;
-  readonly slots: Readonly<Partial<SystemAdapters>>;
-  /**
-   * The slots this root's `systems` table answered with `absent(reason)` — the
-   * positive absences, in the game's own words.
-   *
-   * They are carried rather than dropped because they are the ONLY thing that
-   * can tell a coverage reader "this game has no networking" apart from "nobody
-   * ever looked". Nothing is installed for them (that would be the stub adapter
-   * `absent()`'s own comment forbids); they exist to be READ — through
-   * `binding.observation.entrySystems`, which is the product door the coverage
-   * table renders from.
-   */
-  readonly absent: readonly ContractSystemEmptySlot[];
-}

package/src/adapter/render-audio.ts

@@ -1,20 +0,0 @@
-/**
- * The offline-audio seam: what a caller's renderer hands back, and the
- * function shape that produces it. The contract owns both because
- * `SystemAdapters`'s audio door names them; the gameplay export
- * (`editor-game/src/host/gameplay-export.ts`) is what drives a renderer.
- */
-
-/** What a caller's renderer hands back: real PCM in a native `AudioBuffer`.
- *  `AudioBuffer` — not a volter type — is the point: any offline audio path in
- *  the platform already produces one. */
-export interface RenderedAudio {
-  readonly buffer: AudioBuffer;
-  readonly durationSeconds: number;
-}
-
-/** Render `[start, end)` (absolute/canonical seconds) offline and
- *  deterministically. The offset trap in the module doc is the renderer's to
- *  honour: identical `(start, end)` on an unchanged score must produce
- *  identical samples, since the capture driver relies on it. */
-export type OfflineAudioRenderer = (start: number, end: number) => Promise<RenderedAudio>;

package/src/adapter/render-memory.ts

@@ -1,34 +0,0 @@
-/**
- * What a render-memory reading IS — the shape `SystemAdapters`'s memory door
- * answers with. The contract owns the shape; the measurement that fills it
- * walks a live three.js scene and is the game runtime's
- * (`@volter/editor-game/runtime/dev/render-memory`).
- */
-
-export interface RenderMemoryEntry {
-  readonly name: string;
-  readonly bytes: number;
-}
-
-export interface RenderMemoryUnestimated {
-  readonly name: string;
-  readonly reason: string;
-}
-
-export interface RenderMemorySnapshot {
-  readonly counts: {
-    readonly geometries: number;
-    readonly textures: number;
-    /** Compiled program count, or `null` when the renderer doesn't expose it
-     *  (`renderer.info.programs` is populated only after the first render). */
-    readonly programs: number | null;
-  };
-  /** Sum of every ESTIMABLE texture (nulls excluded — they are in
-   *  `unestimated`). */
-  readonly estimatedTextureBytes: number;
-  /** Exact sum of geometry attribute + index buffers. */
-  readonly estimatedGeometryBytes: number;
-  readonly topTextures: readonly RenderMemoryEntry[];
-  readonly topGeometries: readonly RenderMemoryEntry[];
-  readonly unestimated: readonly RenderMemoryUnestimated[];
-}

package/src/adapter/renderer-config.ts

@@ -1,84 +0,0 @@
-/**
- * `WorldRendererConfig` — what a WORLD may declare about the renderer that
- * draws it, and therefore part of the ROOT CONTRACT: `MountedThreeRoot
- * .rendererConfig` reports it (`./root-adapter.ts`) and
- * `./root-seam-contract.ts` lists it as a contract field.
- *
- * The contract owns the SHAPE and no three.js code: the function that applies
- * it to a live `WebGLRenderer` (and restores what it found on dispose) is the
- * three.js twin's, `@volter/threejs-runtime/adapter/renderer-config`. The host
- * owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it
- * with this engine's defaults: ACES tone mapping, sRGB output, PCF-soft
- * shadows. Those defaults are right for a world authored against them and
- * WRONG for a world authored against a different engine's pipeline — an
- * imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper at
- * all, so ACES quietly desaturates and darkens every colour its author picked.
- *
- * Three properties of the shape are load-bearing:
- *
- *  - **It is per-renderer, never engine-wide.** Every field is a
- *    `WebGLRenderer` instance property, and a play root gets its own renderer.
- *    Nothing here reaches a module-level three global, so one world's
- *    declaration cannot change how the editor's own viewport, another root, or
- *    a thumbnail bake renders.
- *  - **Absent means "leave the host's value alone".** Every field is optional
- *    and an omitted one is never written, so declaring a tone mapping does not
- *    silently reset the clear colour.
- *  - **It is restored on dispose.** The renderer outlives the mount, so a
- *    world that did not put back what it found would leak its pipeline into
- *    whatever mounts next.
- *
- * This is deliberately NOT a general render-settings system. It carries what a
- * world can honestly state about its own colour pipeline and nothing else; a
- * property the host fixes at CONSTRUCTION (the WebGL context's `antialias`
- * attribute, and therefore the MSAA sample count) cannot be declared here,
- * because there would be no honest moment to apply it.
- */
-
-/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
-export type WorldToneMapping =
-  | 'none'
-  | 'linear'
-  | 'reinhard'
-  | 'cineon'
-  | 'aces'
-  | 'agx'
-  | 'neutral';
-
-/**
- * The output transfer function the frame is written with.
- *
- *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
- *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
- *    result is already in display space and encoding it a second time washes the frame out.
- */
-export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
-
-/**
- * The shadow-map filter, named as data rather than as three's numeric enum.
- *
- * This is a renderer INSTANCE property (`WebGLRenderer.shadowMap.type`), not a context attribute,
- * so unlike MSAA it has an honest moment at which a world can ask for it — which is the whole test
- * this file's header states. A source engine that declares its own shadow filter (Godot 3's
- * `rendering/quality/shadows/filter_mode`) would otherwise inherit whatever the host built with.
- */
-export type WorldShadowMapType = 'basic' | 'pcf' | 'pcf-soft' | 'vsm';
-
-/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
-export interface WorldRendererConfig {
-  readonly toneMapping?: WorldToneMapping | undefined;
-  readonly toneMappingExposure?: number | undefined;
-  readonly outputColorSpace?: WorldOutputColorSpace | undefined;
-  /**
-   * `WebGLRenderer.shadowMap.type`. Writing it after a shadow map has already been built needs
-   * `shadowMap.needsUpdate`, which this function sets — three caches the compiled depth material
-   * per type and would otherwise keep filtering with the previous one.
-   */
-  readonly shadowMapType?: WorldShadowMapType | undefined;
-  /**
-   * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
-   * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
-   * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
-   */
-  readonly clearColor?: string | undefined;
-}

package/src/adapter/system-slot.ts

@@ -1,301 +0,0 @@
-/**
- * `createSystemSlot` — THE implementation of the declared-slot façade, the
- * seam between a STATIC `systems` declaration and a LIVE adapter that only
- * exists once the world tree is mounted.
- *
- * WHY IT EXISTS. An entry declares its systems statically
- * (`export const systems = { networking: networkingSystem() }`), while the
- * thing being declared — a joined Colyseus room, a baked navmesh, a mounted
- * `<Physics>`, a cutscene's camera ownership — is built inside the world tree,
- * later, and may be replaced (reconnect, remount, hot restart) or go away
- * (stop). The slot is a stable object the host installs at mount and holds
- * forever; every call forwards to whatever is attached right now.
- *
- * ── THE HONESTY RULE, STATED IN ONE PLACE ───────────────────────────────────
- * This is why the pattern is centralized: five hand-rolled copies disagreed
- * about it, and each disagreement was found by a separate review.
- *
- *  - An **action** with no live target REFUSES BY NAME
- *    (`<name>: <unattachedMessage>`). Never a silent no-op — a caller that
- *    told the game to DO something must learn that it did not happen. An
- *    action against a live adapter that lacks the member refuses the same
- *    way, naming the member.
- *  - A **read** answers its declared HONEST EMPTY — `'disconnected'`, `[]`,
- *    `null`, `false`. That is not a fabrication: it is the truth of the
- *    not-attached state, in the same vocabulary the editor's own edit-mode
- *    adapters use. Reads are also the only kind safe to call from a per-frame
- *    debug draw, which is why a throw into a rAF loop is never the answer.
- *  - An **optional** member MIRRORS THE LIVE ADAPTER'S PRESENCE: absent while
- *    unattached, and absent afterwards when the live adapter itself does not
- *    provide it. Presence IS the consume-by-presence protocol's signal, so
- *    the slot may never invent it. Each presence read CAPTURES the adapter it
- *    saw and forwards to that same instance, so a detach between the read and
- *    the call answers as the adapter the caller was handed rather than a
- *    mid-flight swap.
- *  - A **subscribe** member SURVIVES REATTACHMENT: listeners live on the
- *    slot, never on the instance, and the slot re-binds its own single
- *    subscription on every attach/detach. A panel that subscribed once to the
- *    stable slot object is therefore never left holding a disposed system, and
- *    it is notified when the live half appears or disappears.
- *  - A member the config DOES NOT LIST does not exist on the slot at all.
- *    That is how the anti-shim rule spells omission — e.g. `PhysicsAdapter`'s
- *    `debugDraw`/`contactPoints` over `@react-three/rapier`, whose debug line
- *    segments live inside the fiber tree and expose no handle. Absence is a
- *    capability answer; a stub is a lie.
- *
- * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
- * OWNER: whoever built the live adapter (the hook, the bridge component). The
- * slot owns only the POINTER to it plus its own listener set and its own
- * subscription to the live half. SHARERS: every reader of the declared
- * system — editor inspectors, instruments. TEARDOWN: the function `attach`
- * returns, and nothing else. It is IDENTITY-GUARDED — it clears only while
- * the same instance is still attached, so a replace-then-teardown-the-old
- * ordering cannot detach the new one — and detaching never disposes the
- * adapter, because the slot did not create it.
- *
- * Static declarations shared across mounts must use `declareScopedSystem`.
- * The adapter supplies an opaque mount scope and the host resolves the declaration
- * once per root. A slot then belongs to that evaluation, never to the page.
- *
- * NOT A WRAPPER. The slot's members have the adapter interface's own exact
- * signatures and hand back the implementation's own values; nothing stands
- * between a caller and the live library object.
- */
-
-import type { VolterGameSystemEmpty } from './ingest/game-contract';
-
-/**
- * `absent(reason)` — THE WHOLE-SLOT counterpart of the four per-member policies
- * above, and the fifth line of the same honesty rule.
- *
- * The four policies answer "this slot exists but nothing is attached yet". This
- * one answers a different question entirely: **this game will never have that
- * subsystem, and here is what was searched.** A slot simply left out of the
- * `systems` table cannot say that — an omitted key means "unsupported", which is
- * the same shape as "nobody looked", and the coverage report has to file it as a
- * work order forever. Declaring the absence turns an UNANSWERED row into a
- * terminal one.
- *
- * ```ts
- * export const systems = {
- *   navigation: createNavigationAdapter(navigation),
- *   networking: absent('single-player: no Colyseus client anywhere in `src/`'),
- * };
- * ```
- *
- * ## It is a CONSTRUCTOR for the shape that already exists, not a second one
- *
- * The returned value IS `VolterGameSystemEmpty` — the plain
- * `{ present: false, evidence }` record an INGESTED game declares on
- * `window.volterGame.systems.systemAdapters`, validated by the same single
- * projection (`ingest/contract-system-adapters.ts`). There is one shape law, not
- * two: a foreign game cannot import this helper and must stay able to write the
- * record by hand, so nothing here may brand the runtime value. What the helper
- * buys a FIRST-PARTY author is the reason-quality check moved to the call site —
- * our own code failing its own contract fails fast, where an ingested game's
- * same mistake is filed as a `malformed` verdict for its coverage report.
- *
- * ## It is a MARKER, never a stub adapter
- *
- * Do not answer an absent slot with an adapter whose methods return zeros. A
- * `getConnectionState()` of `'disconnected'` on a game with no transport implies
- * a connection that could exist; that is the fabrication the anti-shim rule
- * forbids. The absence is STATED, and the host installs nothing for it.
- *
- * @param reason What was searched and what was found, in the game's own source
- *   terms. "no netcode anywhere in `src/`" is a finished answer a reviewer can
- *   re-run; "not implemented yet" is a plan, and is rejected here.
- */
-export function absent(reason: string): VolterGameSystemEmpty {
-  if (typeof reason !== 'string' || reason.trim() === '') {
-    throw new Error(
-      'absent(): an absence needs evidence — say what was searched and what was found ' +
-        '(e.g. "no Colyseus client anywhere in `src/`"), so a reviewer can re-run it. ' +
-        'An unevidenced absence asserts something nobody can re-check.',
-    );
-  }
-  return { present: false, evidence: reason };
-}
-
-/** Any adapter member. `never[]` args make the conditional match contravariantly. */
-type AnyFn = (...args: never[]) => unknown;
-
-/** The declared member's return type, used to type a `read`'s honest empty. */
-type MemberReturn<F> = NonNullable<F> extends (...args: never[]) => infer R ? R : never;
-
-/**
- * The per-member policy. There are exactly four, and every member of every
- * declared slot in the repo is one of them — see the honesty rule above.
- */
-export type SystemSlotMemberSpec<F> =
-  | { readonly kind: 'action' }
-  | { readonly kind: 'read'; readonly empty: MemberReturn<F> }
-  | { readonly kind: 'subscribe' }
-  | { readonly kind: 'optional' };
-
-/** The keys of `T` whose values are callable (data properties are not slottable). */
-type FunctionMemberKeys<T> = {
-  [K in keyof T]-?: NonNullable<T[K]> extends AnyFn ? K : never;
-}[keyof T];
-
-/** Per-member policies. A member left out is left OFF the slot entirely. */
-export type SystemSlotMembers<T> = {
-  readonly [K in FunctionMemberKeys<T>]?: SystemSlotMemberSpec<T[K]>;
-};
-
-export interface SystemSlotConfig<T extends object> {
-  /**
-   * The slot's own name, used as the prefix of every refusal so a stack-less
-   * error still names the seam (`'networkingSystem'`).
-   */
-  readonly name: string;
-  /**
-   * The rest of an action's refusal while nothing is attached — the DOMAIN
-   * half of the message, naming what has not happened yet ("the world is not
-   * playing, or the navmesh has not finished building").
-   */
-  readonly unattachedMessage: string;
-  readonly members: SystemSlotMembers<T>;
-}
-
-export interface SystemSlot<T extends object> {
-  /**
-   * Publish `live` as the slot's target. Returns the ONE detach path, which
-   * is identity-guarded: it clears only while `live` is still the attached
-   * instance, and never disposes it.
-   */
-  attach(live: T): () => void;
-  /** The stable declared object. Hand THIS to the entry's `systems` map. */
-  readonly slot: T;
-}
-
-export function createSystemSlot<T extends object>(config: SystemSlotConfig<T>): SystemSlot<T> {
-  const { name, unattachedMessage, members } = config;
-
-  let live: T | null = null;
-  /** Subscribers to the stable slot object; they outlive any one live instance. */
-  const listeners = new Set<() => void>();
-  /** The slot's own single subscription to whatever is attached. */
-  let liveUnsubscribe: (() => void) | null = null;
-  let subscribeMember: string | null = null;
-
-  const asRecord = (value: object): Record<string, unknown> =>
-    value as unknown as Record<string, unknown>;
-
-  const liveMember = (member: string): AnyFn | undefined => {
-    if (!live) return undefined;
-    const value = asRecord(live)[member];
-    return typeof value === 'function' ? (value as AnyFn) : undefined;
-  };
-
-  const notify = (): void => {
-    for (const listener of [...listeners]) listener();
-  };
-
-  const bindLive = (): void => {
-    liveUnsubscribe?.();
-    liveUnsubscribe = null;
-    if (!live || subscribeMember === null || listeners.size === 0) return;
-    const subscribe = liveMember(subscribeMember);
-    if (!subscribe) return;
-    const result = subscribe.call(live, notify as never);
-    liveUnsubscribe = typeof result === 'function' ? (result as () => void) : null;
-  };
-
-  const target: Record<string, unknown> = {};
-
-  const declared = Object.entries(members) as [string, SystemSlotMemberSpec<unknown>][];
-  for (const [member, spec] of declared) {
-    switch (spec.kind) {
-      case 'action': {
-        // Refuse by name, twice over: no live adapter at all, or a live
-        // adapter that does not carry this member (only ever a foreign
-        // replacement — the blessed implementations carry all of theirs).
-        target[member] = (...args: never[]): unknown => {
-          if (!live) throw new Error(`${name}: ${unattachedMessage}`);
-          const fn = liveMember(member);
-          if (!fn) throw new Error(`${name}: the live adapter has no ${member}().`);
-          return fn.apply(live, args);
-        };
-        break;
-      }
-      case 'read': {
-        const { empty } = spec;
-        target[member] = (...args: never[]): unknown => {
-          const current = live;
-          const fn = liveMember(member);
-          const value = fn ? fn.apply(current, args) : undefined;
-          return value ?? empty;
-        };
-        break;
-      }
-      case 'subscribe': {
-        if (subscribeMember !== null) {
-          throw new Error(
-            `${name}: a slot declares at most one 'subscribe' member (${subscribeMember} and ${member}).`,
-          );
-        }
-        subscribeMember = member;
-        target[member] = (listener: () => void): (() => void) => {
-          listeners.add(listener);
-          bindLive();
-          return () => {
-            listeners.delete(listener);
-            bindLive();
-          };
-        };
-        break;
-      }
-      case 'optional': {
-        Object.defineProperty(target, member, {
-          enumerable: true,
-          configurable: true,
-          get(): AnyFn | undefined {
-            const current = live;
-            const fn = liveMember(member);
-            if (!fn) return undefined;
-            return (...args: never[]): unknown => fn.apply(current, args);
-          },
-        });
-        break;
-      }
-    }
-  }
-
-  const attach = (next: T): (() => void) => {
-    live = next;
-    bindLive();
-    notify();
-    return () => {
-      if (live !== next) return;
-      live = null;
-      bindLive();
-      notify();
-    };
-  };
-
-  // THE ONE CAST. `exactOptionalPropertyTypes` forbids an optional member
-  // whose getter can yield `undefined`, but that is precisely the honest
-  // shape here — the getter IS how presence mirrors the live adapter — and a
-  // reflectively built object cannot be typed structurally anyway. Callers
-  // see exactly the absent/present behavior the adapter interface documents.
-  return { attach, slot: target as T };
-}
-
-/** Optional mount binding for a static system declaration. The contract knows
- * only an opaque identity; the implementing adapter owns its native scope. */
-const scopedSystems = new WeakMap<object, (scope: object) => object>();
-
-export function declareScopedSystem<T extends object>(
-  declaration: T,
-  bind: (scope: object) => T,
-): T {
-  scopedSystems.set(declaration, bind);
-  return declaration;
-}
-
-/** Ordinary, already-bound adapters retain their exact identity. */
-export function bindScopedSystem<T extends object>(declaration: T, scope: object): T {
-  const bind = scopedSystems.get(declaration);
-  return bind ? (bind(scope) as T) : declaration;
-}

package/src/core/system-phase.ts

@@ -1,52 +0,0 @@
-/**
- * THE SYSTEM-PHASE VOCABULARY — the order a frame runs in, and the shape a
- * project's own system declares itself with.
- *
- * It lives in the CONTRACT because two runtimes speak it and neither owns it:
- * `@volter/game-runtime`'s loop and system runner schedule by phase, and
- * `@volter/threejs-runtime`'s animation clock orders its evaluators by the same
- * `PHASE_ORDER`. A vocabulary two shipped twins both read is the contract's,
- * or it is a value edge between twins — and that edge is the one thing the
- * twin row may not have (docs/ARCHITECTURE-CORE.md §The target shape: a twin
- * depends on the project contract and its medium's libraries).
- *
- * `scripts/generate-engine-manifest.ts` renders this file into
- * `packages/project/schemas/engine-api.json`.
- */
-
-/**
- * System execution phases, in order.
- * Each frame, systems run in this exact sequence.
- */
-export const SystemPhase = {
-  INPUT: 'input',
-  PRE_PHYSICS: 'prePhysics',
-  PHYSICS: 'physics',
-  POST_PHYSICS: 'postPhysics',
-  GAME_LOGIC: 'gameLogic',
-  ANIMATION: 'animation',
-  PRE_RENDER: 'preRender',
-  RENDER: 'render',
-} as const;
-
-export type SystemPhaseName = (typeof SystemPhase)[keyof typeof SystemPhase];
-
-/** Order of phase execution */
-export const PHASE_ORDER: SystemPhaseName[] = [
-  SystemPhase.INPUT,
-  SystemPhase.PRE_PHYSICS,
-  SystemPhase.PHYSICS,
-  SystemPhase.POST_PHYSICS,
-  SystemPhase.GAME_LOGIC,
-  SystemPhase.ANIMATION,
-  SystemPhase.PRE_RENDER,
-  SystemPhase.RENDER,
-];
-
-/** A system is just a function that takes delta time */
-export type SystemFn = (dt: number) => void;
-
-export interface SystemOptions {
-  /** Stable diagnostic label; falls back to the function name. */
-  readonly name?: string;
-}