@volter/project 0.0.0-stage → 0.5.203

package/src/adapter/system-seam-contract.ts

@@ -0,0 +1,138 @@
+/** Exhaustive proof requirements for mounted SystemAdapters. A bound slot is
+ * availability, not success: each nested operation has its own required proof
+ * stage and therefore cannot hide behind `active[slot] != null`. */
+
+import type { PhysicsAdapter2D } from './physics-adapter-2d';
+import { defineSeamShape, type SeamShape } from './seam-evidence';
+import type {
+  AudioAdapter,
+  CameraAdapter,
+  DebugAdapter,
+  NavigationAdapter,
+  NetworkingAdapter,
+  PhysicsAdapter,
+  RenderDebugAdapter,
+  SystemAdapters,
+} from './system-adapter';
+
+export const SYSTEM_ADAPTERS_SHAPE = defineSeamShape<SystemAdapters>()({
+  physics: { optional: true, kind: 'value', required: 'effect' },
+  networking: { optional: true, kind: 'value', required: 'operation' },
+  navigation: { optional: true, kind: 'value', required: 'operation' },
+  audio: { optional: true, kind: 'value', required: 'effect' },
+  camera: { optional: true, kind: 'value', required: 'effect' },
+  debug: { optional: true, kind: 'value', required: 'operation' },
+  renderDebug: { optional: true, kind: 'value', required: 'effect' },
+});
+
+export const PHYSICS_ADAPTER_SHAPE = defineSeamShape<PhysicsAdapter>()({
+  keyedBy: { optional: true, kind: 'value', required: 'shape' },
+  ownerOf: { optional: false, kind: 'function', required: 'operation' },
+  freeze: { optional: false, kind: 'function', required: 'effect' },
+  commit: { optional: false, kind: 'function', required: 'effect' },
+  unfreeze: { optional: false, kind: 'function', required: 'effect' },
+  debugDraw: { optional: true, kind: 'function', required: 'operation' },
+  setDebugDrawEnabled: { optional: true, kind: 'function', required: 'effect' },
+  contactPoints: { optional: true, kind: 'function', required: 'operation' },
+  colliders: { optional: true, kind: 'function', required: 'operation' },
+  previewCollider: { optional: true, kind: 'function', required: 'effect' },
+  joints: { optional: true, kind: 'function', required: 'operation' },
+  previewJointAnchor: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const PHYSICS_2D_ADAPTER_SHAPE = defineSeamShape<PhysicsAdapter2D>()({
+  keyedBy: { optional: false, kind: 'value', required: 'shape' },
+  ownerOf: { optional: false, kind: 'function', required: 'operation' },
+  freeze: { optional: false, kind: 'function', required: 'effect' },
+  commit: { optional: false, kind: 'function', required: 'effect' },
+  unfreeze: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const NETWORKING_ADAPTER_SHAPE = defineSeamShape<NetworkingAdapter>()({
+  peers: { optional: false, kind: 'function', required: 'operation' },
+  networkId: { optional: false, kind: 'function', required: 'operation' },
+  authority: { optional: false, kind: 'function', required: 'operation' },
+  editable: { optional: false, kind: 'function', required: 'operation' },
+  getConnectionState: { optional: true, kind: 'function', required: 'operation' },
+  getRoomInfo: { optional: true, kind: 'function', required: 'operation' },
+  getReplicationStats: { optional: true, kind: 'function', required: 'operation' },
+  subscribe: { optional: false, kind: 'function', required: 'effect' },
+  getStateSnapshot: { optional: true, kind: 'function', required: 'operation' },
+  messageEvents: { optional: true, kind: 'function', required: 'operation' },
+  getRates: { optional: true, kind: 'function', required: 'operation' },
+  getConditioning: { optional: true, kind: 'function', required: 'operation' },
+  setConditioning: { optional: true, kind: 'function', required: 'effect' },
+  getServerConfig: { optional: true, kind: 'function', required: 'operation' },
+  getPlayerIdentity: { optional: true, kind: 'function', required: 'operation' },
+  setPlayerIdentity: { optional: true, kind: 'function', required: 'effect' },
+  getTrafficByType: { optional: true, kind: 'function', required: 'operation' },
+  sendMessage: { optional: true, kind: 'function', required: 'effect' },
+  getConditioningLimits: { optional: true, kind: 'function', required: 'operation' },
+  ping: { optional: true, kind: 'function', required: 'effect' },
+  inspectServer: { optional: true, kind: 'function', required: 'operation' },
+  disconnectClient: { optional: true, kind: 'function', required: 'effect' },
+  editServerState: { optional: true, kind: 'function', required: 'effect' },
+  deleteServerState: { optional: true, kind: 'function', required: 'effect' },
+  sendToClient: { optional: true, kind: 'function', required: 'effect' },
+  broadcast: { optional: true, kind: 'function', required: 'effect' },
+  disposeRoom: { optional: true, kind: 'function', required: 'effect' },
+  stateFieldType: { optional: true, kind: 'function', required: 'operation' },
+  clearTraffic: { optional: true, kind: 'function', required: 'effect' },
+  getTrafficByEntity: { optional: true, kind: 'function', required: 'operation' },
+  isRecording: { optional: true, kind: 'function', required: 'operation' },
+  setRecording: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const NAVIGATION_ADAPTER_SHAPE = defineSeamShape<NavigationAdapter>()({
+  hasNavMesh: { optional: false, kind: 'function', required: 'operation' },
+  findPath: { optional: false, kind: 'function', required: 'effect' },
+  debugMesh: { optional: false, kind: 'function', required: 'operation' },
+  bake: { optional: true, kind: 'function', required: 'effect' },
+  exportData: { optional: true, kind: 'function', required: 'operation' },
+  clear: { optional: true, kind: 'function', required: 'effect' },
+  crowdAgents: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const AUDIO_ADAPTER_SHAPE = defineSeamShape<AudioAdapter>()({
+  resume: { optional: true, kind: 'function', required: 'effect' },
+  setMuted: { optional: false, kind: 'function', required: 'effect' },
+  isMuted: { optional: false, kind: 'function', required: 'operation' },
+  graphSnapshot: { optional: true, kind: 'function', required: 'operation' },
+  transportState: { optional: true, kind: 'function', required: 'operation' },
+  acquireMeters: { optional: true, kind: 'function', required: 'effect' },
+  acquireRecordingStream: { optional: true, kind: 'function', required: 'effect' },
+  renderOffline: { optional: true, kind: 'function', required: 'operation' },
+  audioEvents: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const CAMERA_ADAPTER_SHAPE = defineSeamShape<CameraAdapter>()({
+  snapshot: { optional: false, kind: 'function', required: 'operation' },
+  subscribe: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const DEBUG_ADAPTER_SHAPE = defineSeamShape<DebugAdapter>()({
+  providers: { optional: false, kind: 'function', required: 'operation' },
+  state: { optional: false, kind: 'function', required: 'operation' },
+  stateAll: { optional: false, kind: 'function', required: 'operation' },
+  commands: { optional: false, kind: 'function', required: 'operation' },
+  invoke: { optional: false, kind: 'function', required: 'effect' },
+  events: { optional: false, kind: 'function', required: 'operation' },
+});
+
+export const RENDER_DEBUG_ADAPTER_SHAPE = defineSeamShape<RenderDebugAdapter>()({
+  captureFrame: { optional: false, kind: 'function', required: 'effect' },
+  memorySnapshot: { optional: true, kind: 'function', required: 'operation' },
+});
+
+type NonPhysicsSystemSlot = Exclude<keyof SystemAdapters, 'physics'>;
+
+export const SYSTEM_PROVIDER_SHAPES: {
+  readonly [K in NonPhysicsSystemSlot]: SeamShape<NonNullable<SystemAdapters[K]>>;
+} = {
+  networking: NETWORKING_ADAPTER_SHAPE,
+  navigation: NAVIGATION_ADAPTER_SHAPE,
+  audio: AUDIO_ADAPTER_SHAPE,
+  camera: CAMERA_ADAPTER_SHAPE,
+  debug: DEBUG_ADAPTER_SHAPE,
+  renderDebug: RENDER_DEBUG_ADAPTER_SHAPE,
+};

package/src/adapter/system-slot.ts

@@ -0,0 +1,301 @@
+/**
+ * `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/adapter/transform.ts

@@ -0,0 +1,35 @@
+/**
+ * The neutral transform value used across adapter interfaces. Position + scale
+ * are xyz; rotation is a quaternion (xyzw) — matching `Object3D.quaternion`, so
+ * adapters never have to agree on an Euler convention.
+ */
+export interface Transform {
+  position: [number, number, number];
+  rotation: [number, number, number, number];
+  scale: [number, number, number];
+}
+
+/**
+ * Who currently owns an object's transform — i.e. what writes it each frame.
+ * The editor uses this to decide whether a gizmo edit is durable (`editor`),
+ * needs simulation coordination (`physics`), or is best-effort/inspect-only
+ * (`script`/`network`/`external`).
+ */
+/**
+ * Who drives a node's transform right now.
+ *
+ * `'unresolved'` is the answer for a node THIS ADAPTER DOES NOT KNOW, and it is
+ * a distinct answer on purpose: every other member names a driver, so returning
+ * one of them for an unknown id is a positive claim about a node the
+ * implementer has never seen. A game-scoped physics adapter is asked about
+ * every node the editor touches, including nodes belonging to another root —
+ * "not mine" has to be sayable.
+ */
+export type TransformOwner =
+  | 'editor'
+  | 'physics'
+  | 'animation'
+  | 'script'
+  | 'network'
+  | 'external'
+  | 'unresolved';

package/src/adapter/workspace-arrangement.ts

@@ -0,0 +1,92 @@
+/** The editor's OWN captured dock arrangements (Animate, Look), shared data used by
+ * imported layout components. A package's workspace ships its own beside its
+ * layout contribution (`@volter/editor-blender`'s `model-arrangement.json`). */
+
+/**
+ * ONE EDITOR AREA of a workspace, and the document that fills it.
+ *
+ * **A Blender editor AREA is an editor group; the drawer holds utilities**
+ * (orchestrator ruling 2026-09-19, WORK.md I5). Blender's UV Editing is a
+ * side-by-side split of the centre (786/785 measured on the engine), Shading
+ * and Animation a top/bottom split, and both the dock and the frame have
+ * exactly that shape in editor groups — a second group beside or below the
+ * document, with the workspace's own split ratio. So the UV editor, the node
+ * editor and the image view are DOCUMENTS a workspace opens
+ * into editor groups, never drawer views; the drawer keeps the utilities that
+ * are not Blender areas (Console, Profiler, Network).
+ *
+ * THIS AMENDS "a workspace positions chrome and dock groups only; it never
+ * opens documents" (ARCHITECTURE-CORE §Editor chrome, 2026-08-30), and the
+ * amendment is narrow: a workspace opens the documents ITS OWN REFERENCE
+ * FRAME'S SCREEN HAS, named here, and never a session's content. That is why
+ * `normalizePresetLayout` still strips every `kind: 'document'` panel out of a
+ * captured arrangement — the capture carries the GROUP and its settled size,
+ * this list carries which document fills it, and the two never overlap.
+ */
+export interface WorkspaceAreaContribution {
+  /** Stable area id, scoped to the workspace. BOTH hosts key an editor group by
+   *  it: the dock's group id is `volter:area:<id>`, and under the Code-OSS frame
+   *  it is the key of `volterDocuments.ts`'s `Map<areaId, IEditorGroup>` — the
+   *  group `IEditorGroupsService.addGroup` created from this area's `place`
+   *  (WORK.md §THE TIMELINE item 1, landed 2026-09-20). */
+  readonly id: string;
+  /** The `workspace.document` CONTRIBUTION id this area opens (the
+   *  contribution's file-derived id, e.g. `blender-uv-editor.document`), not a
+   *  document id: the document is minted per open subject. */
+  readonly document: string;
+  /** Where the group sits relative to the centre document's group. */
+  readonly place: 'left' | 'right' | 'above' | 'below';
+  /** The area's share of that split, 0..1 — Blender's own measured ratio,
+   *  cited by the workspace that declares it. It is the BOOTSTRAP size only:
+   *  once a capture of this workspace exists, the captured leaf's own size
+   *  wins, exactly as the drawer's captured height wins over its default.
+   *  Under the frame the same rule is `setSize` applied ONCE at group
+   *  creation, against the two groups' combined extent — a person's drag on
+   *  the sash is never overwritten, and a group they closed is re-created at
+   *  this ratio on the next reconcile, because a Blender area is resized or
+   *  joined, never closed. The one other stand-up is the area's document
+   *  changing its job and asking for that job's size
+   *  (`@volter/sdk/kit/workspace-areas`' `setWorkspaceAreaRatio`). */
+  readonly ratio: number;
+}
+
+export interface WorkspaceArrangement {
+  /** Persistence identity, not a lookup key for an engine-owned implementation. */
+  readonly id: string;
+  readonly title: string;
+  readonly regions?: {
+    /** The WORKSPACE tab strip in the top bar (Blender's); a click on a tab
+     *  is the explicit act that switches. Absent means hidden. */
+    readonly workspaceTabs?: 'shown' | 'hidden';
+    readonly header?: 'shown' | 'hidden';
+    readonly shelf?: 'shown' | 'hidden';
+    readonly inspector?: 'column' | 'properties';
+    readonly drawer?: 'shown' | 'hidden';
+    /** The top bar's runtime TELEMETRY cluster — the frame-rate readout, its
+     *  sparkline and the audio meter. `hidden` leaves the corner to the quiet
+     *  product controls (Invite, Account); the Profiler utility remains the
+     *  door to the same numbers. Absent means shown. */
+    readonly telemetry?: 'shown' | 'hidden';
+    /** The `·TypeName` a component-instance row prints after its name in the
+     *  hierarchy. `hidden` leaves the row its NAME alone, the way Blender's
+     *  Outliner does — there the type is the glyph. The type stays reachable
+     *  through the row's own tooltip and the inspector. Absent means shown. */
+    readonly hierarchyTypeSuffix?: 'shown' | 'hidden';
+    /** The dotted RULE a component-instance row draws under its name in the
+     *  hierarchy. `hidden` leaves the name unmarked, the way Blender's Outliner
+     *  does — it marks an instance nowhere in that panel, in any selection
+     *  state. The fact stays reachable through the row's own tooltip, its Go to
+     *  Callsite / Open Component Source actions and the inspector. Absent means
+     *  shown. */
+    readonly hierarchyInstanceRule?: 'shown' | 'hidden';
+    /** Which restriction columns a hierarchy row carries at its right edge:
+     *  this editor's selection lock beside the eye (`select+viewport`), or
+     *  Blender's default filter (`viewport+render`) — the eye in its own
+     *  column with the render column reserved and blank, three.js having one
+     *  visibility flag for viewport and render alike. Absent means the pair. */
+    readonly hierarchyRestrictions?: 'select+viewport' | 'viewport+render';
+  };
+  /** The workspace's EDITOR AREAS beside the centre document — see
+   *  {@link WorkspaceAreaContribution}. Absent: the centre document alone. */
+  readonly areas?: readonly WorkspaceAreaContribution[];
+}

package/src/core/system-phase.ts

@@ -0,0 +1,52 @@
+/**
+ * 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;
+}