《移动游戏产品的架构·客户端与移动运行时》3.1 引擎负责什么，原生壳负责什么

// file: src/platform/host.ts
// tier: L1
// verify: node --test test/platform/host.test.ts

export type Platform = "android" | "ios";
export type ShellKind = "activity" | "ui-view-controller";
export type Owner = "shell" | "engine" | "shared";

export const CONCERNS = [
  "app-lifecycle",
  "main-thread",
  "render-thread",
  "permissions",
  "billing",
  "push",
  "consent-ui",
  "file-paths",
  "network-transport",
  "sensors",
] as const;

export type Concern = (typeof CONCERNS)[number];

export interface Ownership {
  readonly concern: Concern;
  readonly owner: Owner;
  readonly contract: string;
}

export const OWNERSHIP: readonly Ownership[] = [
  {
    concern: "app-lifecycle",
    owner: "shell",
    contract: "onCreate/onResume/onPause/onDestroy 或 viewDidAppear/viewDidDisappear 转成统一事件",
  },
  {
    concern: "main-thread",
    owner: "shell",
    contract: "UI 与输入只在主线程；引擎每帧回调必须回到主线程",
  },
  {
    concern: "render-thread",
    owner: "engine",
    contract: "渲染循环与 GPU 资源由引擎线程持有，壳不得直接调用",
  },
  {
    concern: "permissions",
    owner: "shell",
    contract: "申请、拒绝与「不再询问」由原生壳处理，引擎只读状态",
  },
  {
    concern: "billing",
    owner: "shell",
    contract: "商店 SDK、订单回调与恢复购买由壳适配，引擎只发商品 id",
  },
  {
    concern: "push",
    owner: "shell",
    contract: "token 注册、通知点击与前后台展示由壳处理",
  },
  {
    concern: "consent-ui",
    owner: "shell",
    contract: "隐私弹窗与系统级跳转由壳渲染，引擎只声明需要哪些同意项",
  },
  {
    concern: "file-paths",
    owner: "shared",
    contract: "壳给出可写目录，引擎只在该目录内创建文件",
  },
  {
    concern: "network-transport",
    owner: "shared",
    contract: "壳提供网络状态与代理配置，引擎持有连接与重试策略",
  },
  {
    concern: "sensors",
    owner: "shared",
    contract: "壳采集原始传感器，引擎负责采样率与降级",
  },
];

export interface OwnershipAudit {
  readonly ok: boolean;
  readonly missing: readonly Concern[];
  readonly duplicated: readonly Concern[];
}

export function ownerOf(concern: Concern): Owner {
  const rule = OWNERSHIP.find((item) => item.concern === concern);
  if (!rule) {
    throw new Error(`unknown concern: ${concern}`);
  }
  return rule.owner;
}

export function auditOwnership(rules: readonly Ownership[] = OWNERSHIP): OwnershipAudit {
  const seen = new Map<Concern, number>();
  for (const rule of rules) {
    seen.set(rule.concern, (seen.get(rule.concern) ?? 0) + 1);
  }
  const missing = CONCERNS.filter((concern) => !seen.has(concern));
  const duplicated = [...seen.entries()]
    .filter(([, count]) => count > 1)
    .map(([concern]) => concern);
  return { ok: missing.length === 0 && duplicated.length === 0, missing, duplicated };
}

export type PermissionKind = "notifications" | "tracking" | "storage" | "network";
export type PermissionState = "granted" | "denied" | "not-determined";

export interface HostSnapshot {
  readonly platform: Platform;
  readonly nowMs: number;
  readonly permissions?: Partial<Record<PermissionKind, PermissionState>>;
}

export interface Host {
  readonly platform: Platform;
  readonly shell: ShellKind;
  readonly mainThread: string;
  readonly renderThread: string;
  nowMs(): number;
  permissionState(kind: PermissionKind): PermissionState;
}

export function shellKindFor(platform: Platform): ShellKind {
  return platform === "android" ? "activity" : "ui-view-controller";
}

export function hostFromSnapshot(snapshot: HostSnapshot): Host {
  const permissions = snapshot.permissions ?? {};
  return {
    platform: snapshot.platform,
    shell: shellKindFor(snapshot.platform),
    mainThread: "main",
    renderThread: "render",
    nowMs: () => snapshot.nowMs,
    permissionState: (kind) => permissions[kind] ?? "not-determined",
  };
}

// file: test/platform/host.test.ts
// tier: L1
// verify: node --test test/platform/host.test.ts

import { test } from "node:test";
import assert from "node:assert/strict";

import {
  CONCERNS,
  OWNERSHIP,
  auditOwnership,
  hostFromSnapshot,
  ownerOf,
  shellKindFor,
} from "../../src/platform/host.ts";

test("android and ios map to different shell kinds", () => {
  assert.equal(shellKindFor("android"), "activity");
  assert.equal(shellKindFor("ios"), "ui-view-controller");
});

test("every concern has exactly one owner", () => {
  const audit = auditOwnership();
  assert.equal(audit.ok, true);
  assert.deepEqual(audit.missing, []);
  assert.deepEqual(audit.duplicated, []);
  assert.equal(OWNERSHIP.length, CONCERNS.length);
});

test("lifecycle, main thread and permissions belong to the shell", () => {
  assert.equal(ownerOf("app-lifecycle"), "shell");
  assert.equal(ownerOf("main-thread"), "shell");
  assert.equal(ownerOf("permissions"), "shell");
  assert.equal(ownerOf("render-thread"), "engine");
});

test("audit reports missing and duplicated concerns", () => {
  const withoutBilling = OWNERSHIP.filter((rule) => rule.concern !== "billing");
  const duplicated = [
    ...withoutBilling,
    { concern: "push" as const, owner: "shell" as const, contract: "dup" },
  ];
  const audit = auditOwnership(duplicated);
  assert.equal(audit.ok, false);
  assert.deepEqual(audit.missing, ["billing"]);
  assert.deepEqual(audit.duplicated, ["push"]);
});

test("snapshot host defaults unset permissions to not-determined", () => {
  const host = hostFromSnapshot({
    platform: "ios",
    nowMs: 1_000,
    permissions: { notifications: "granted" },
  });
  assert.equal(host.shell, "ui-view-controller");
  assert.equal(host.nowMs(), 1_000);
  assert.equal(host.permissionState("notifications"), "granted");
  assert.equal(host.permissionState("tracking"), "not-determined");
  assert.equal(host.mainThread, "main");
  assert.equal(host.renderThread, "render");
});