@s2script/sdk 0.8.0 → 0.9.0

package/dist/cli.js

@@ -1074,8 +1074,8 @@ function unzipSync(data, opts) {
 }
 
 // src/build.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync } from "node:fs";
-import { resolve as resolve5, join as join6 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync, rmSync as rmSync2 } from "node:fs";
+import { resolve as resolve5, join as join6, sep, basename } from "node:path";
 
 // src/typecheck/typecheck.ts
 import ts from "typescript";
@@ -1168,6 +1168,10 @@ function localDeclarationFiles(pluginDir) {
   if (!existsSync3(srcDir)) return [];
   return readdirSync(srcDir).filter((f) => f.endsWith(".d.ts")).map((f) => join3(srcDir, f));
 }
+function generatedDeclarationFiles(pluginDir) {
+  const gd = join3(pluginDir, ".s2script", "gamedata.d.ts");
+  return existsSync3(gd) ? [gd] : [];
+}
 function declaredModules(dtsFiles) {
   const out = /* @__PURE__ */ new Set();
   for (const f of dtsFiles) {
@@ -1217,7 +1221,12 @@ function typecheckPlugin(pluginDir, opts) {
       ...contractPaths
     }
   };
-  const rootNames = [entry, join3(packagesDir, "sdk", "globals.d.ts"), ...localDts];
+  const rootNames = [
+    entry,
+    join3(packagesDir, "sdk", "globals.d.ts"),
+    ...localDts,
+    ...generatedDeclarationFiles(absDir)
+  ];
   const tmp = mkdtempSync(join3(tmpdir(), "s2tc-"));
   try {
     if (deps.length) {
@@ -1521,6 +1530,253 @@ async function lintPlugin(pluginDir, program) {
   return { ok: errorCount === 0, output, errorCount };
 }
 
+// src/gamedata/types.ts
+var PLATFORM = "linuxsteamrt64";
+var ARG_KINDS = ["bool", "int", "float", "string", "vector", "entity"];
+var RET_KINDS = ["void", "bool", "int", "float", "entity"];
+var INT_CLASS_ARGS = /* @__PURE__ */ new Set(["bool", "int", "string", "vector", "entity"]);
+var MAX_INT_ARGS = 5;
+var MAX_FLOAT_ARGS = 8;
+
+// src/gamedata/validate.ts
+var ALLOWED_SECTIONS = /* @__PURE__ */ new Set(["signatures", "calls"]);
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var RESERVED_CALL_NAMES = /* @__PURE__ */ new Set(["constructor", "prototype", "__proto__"]);
+var RESOLVE_KINDS = ["direct", "ctor-body-xref", "lea-disp"];
+var KNOWN_PERMISSIONS = ["engine:calls"];
+function validatePluginGamedata(gd, opts) {
+  const errs = [];
+  if (gd == null || typeof gd !== "object" || Array.isArray(gd)) return ["gamedata must be an object"];
+  const g = gd;
+  for (const key of Object.keys(g)) {
+    if (!ALLOWED_SECTIONS.has(key)) {
+      errs.push(`gamedata section '${key}' is not supported in v1 (allowed: signatures, calls)`);
+    }
+  }
+  const sigs = g.signatures ?? {};
+  if (typeof sigs !== "object" || Array.isArray(sigs)) errs.push("signatures must be an object");
+  for (const [name, platforms] of Object.entries(sigs)) {
+    const p = platforms?.[PLATFORM];
+    if (!p) {
+      errs.push(`signature '${name}': missing platform '${PLATFORM}'`);
+      continue;
+    }
+    for (const f of ["module", "pattern", "resolve"]) {
+      if (typeof p[f] !== "string" || !p[f].length) {
+        errs.push(`signature '${name}': '${f}' must be a non-empty string`);
+      }
+    }
+    if (typeof p.resolve === "string" && p.resolve.length && !RESOLVE_KINDS.includes(p.resolve)) {
+      errs.push(
+        `signature '${name}': unknown resolve step ${JSON.stringify(p.resolve)} (allowed: ${RESOLVE_KINDS.join(", ")})`
+      );
+    }
+  }
+  for (const perm of opts.permissions) {
+    if (!KNOWN_PERMISSIONS.includes(perm)) {
+      errs.push(`unknown permission ${JSON.stringify(perm)} (allowed: ${KNOWN_PERMISSIONS.join(", ")})`);
+    }
+  }
+  const calls = g.calls ?? {};
+  const callNames = Object.keys(calls);
+  if (callNames.length && !opts.permissions.includes("engine:calls")) {
+    errs.push('gamedata declares a `calls` section but the manifest does not declare permission "engine:calls"');
+  }
+  for (const [name, rawDecl] of Object.entries(calls)) {
+    const where = `call '${name}'`;
+    if (!IDENTIFIER.test(name)) {
+      errs.push(
+        `${where}: call name must be a plain identifier matching ${IDENTIFIER.source} \u2014 it is emitted verbatim as a TypeScript interface member in the generated .s2script/gamedata.d.ts`
+      );
+      continue;
+    }
+    if (RESERVED_CALL_NAMES.has(name)) {
+      errs.push(`${where}: call name '${name}' is reserved`);
+      continue;
+    }
+    if (rawDecl == null || typeof rawDecl !== "object") {
+      errs.push(`${where}: must be an object`);
+      continue;
+    }
+    const decl = rawDecl;
+    const recv = decl.receiver;
+    if (!recv || recv.kind !== "entity") {
+      errs.push(`${where}: receiver.kind must be "entity" in v1`);
+    } else if (recv.via !== void 0) {
+      const via = recv.via;
+      if (typeof via?.class !== "string" || typeof via?.field !== "string") {
+        errs.push(`${where}: receiver.via requires both 'class' and 'field' strings`);
+      }
+    }
+    const target = decl.target;
+    if (!target) {
+      errs.push(`${where}: missing 'target'`);
+    } else if (target.kind === "signature") {
+      if (typeof target.name !== "string") errs.push(`${where}: target.name must be a string`);
+      else if (!(target.name in sigs)) errs.push(`${where}: target.name '${target.name}' has no entry in 'signatures'`);
+    } else if (target.kind === "vtable") {
+      if (typeof target.class !== "string") errs.push(`${where}: vtable target requires 'class'`);
+      const plat = target[PLATFORM];
+      if (!plat) {
+        errs.push(`${where}: vtable target missing platform '${PLATFORM}'`);
+      } else {
+        if (!Number.isInteger(plat.index) || plat.index < 0) {
+          errs.push(`${where}: vtable index must be a non-negative integer`);
+        }
+        const prologue = plat.validate?.prologue;
+        if (typeof prologue !== "string" || !prologue.length) {
+          errs.push(`${where}: a vtable target REQUIRES validate.prologue (a bare borrowed index is never trusted)`);
+        }
+      }
+    } else {
+      errs.push(`${where}: target.kind must be "signature" or "vtable"`);
+    }
+    const args = decl.args;
+    if (!Array.isArray(args)) {
+      errs.push(`${where}: 'args' must be an array`);
+    } else {
+      let ints = 0, floats = 0;
+      for (const a2 of args) {
+        if (typeof a2 !== "string" || !ARG_KINDS.includes(a2)) {
+          errs.push(`${where}: unknown arg kind ${JSON.stringify(a2)} (allowed: ${ARG_KINDS.join(", ")})`);
+          continue;
+        }
+        if (INT_CLASS_ARGS.has(a2)) ints++;
+        else floats++;
+      }
+      if (ints > MAX_INT_ARGS) {
+        errs.push(`${where}: ${ints} integer-class args exceeds the max of ${MAX_INT_ARGS} (\`this\` occupies rdi)`);
+      }
+      if (floats > MAX_FLOAT_ARGS) {
+        errs.push(`${where}: ${floats} float args exceeds the max of ${MAX_FLOAT_ARGS}`);
+      }
+      if (decl.argNames !== void 0) {
+        const names = decl.argNames;
+        if (!Array.isArray(names)) {
+          errs.push(`${where}: 'argNames' must be an array of parameter names`);
+        } else if (names.length !== args.length) {
+          errs.push(
+            `${where}: 'argNames' has ${names.length} entr${names.length === 1 ? "y" : "ies"} but 'args' has ${args.length} \u2014 they are positionally matched`
+          );
+        } else {
+          const seen = /* @__PURE__ */ new Set();
+          for (const nm of names) {
+            if (typeof nm !== "string" || !IDENTIFIER.test(nm)) {
+              errs.push(
+                `${where}: argName ${JSON.stringify(nm)} must be a plain identifier matching ${IDENTIFIER.source} \u2014 it is emitted as a parameter name in the generated .d.ts`
+              );
+              continue;
+            }
+            if (nm === "self") {
+              errs.push(`${where}: argName 'self' is reserved (it names the receiver parameter)`);
+              continue;
+            }
+            if (seen.has(nm)) errs.push(`${where}: duplicate argName ${JSON.stringify(nm)}`);
+            seen.add(nm);
+          }
+        }
+      }
+    }
+    if (typeof decl.returns !== "string" || !RET_KINDS.includes(decl.returns)) {
+      errs.push(`${where}: 'returns' must be one of ${RET_KINDS.join(", ")}`);
+    }
+  }
+  return errs;
+}
+
+// src/gamedata/gen-types.ts
+var VECTOR_TS = "{ readonly x: number; readonly y: number; readonly z: number }";
+var ARG_TS = {
+  bool: "boolean",
+  int: "number",
+  float: "number",
+  string: "string",
+  vector: VECTOR_TS,
+  entity: "EntityRef | null"
+};
+var RET_TS = {
+  void: "void",
+  bool: "boolean | null",
+  int: "number | null",
+  float: "number | null",
+  entity: "EntityRef | null"
+};
+function generateGamedataTypes(gd) {
+  const calls = gd.calls ?? {};
+  const lines = Object.keys(calls).sort().map((name) => {
+    const decl = calls[name];
+    const names = decl.argNames;
+    const params = [
+      "self: EntityRef",
+      ...decl.args.map((a2, i2) => `${names?.[i2] ?? `a${i2}`}: ${ARG_TS[a2]}`)
+    ];
+    return `    ${name}: (${params.join(", ")}) => ${RET_TS[decl.returns]};`;
+  });
+  const body = lines.length ? `
+${lines.join("\n")}
+  ` : "\n  ";
+  return [
+    "// GENERATED by `s2s build` from the plugin's gamedata \u2014 DO NOT EDIT.",
+    "// The EntityRef import is REQUIRED: a `declare module` augmentation resolves type names in its",
+    "// own file scope, so an un-imported EntityRef degrades to an error skipLibCheck can swallow.",
+    'import type { EntityRef } from "@s2script/sdk/entity";',
+    "",
+    'declare module "@s2script/sdk/unsafe" {',
+    `  interface EngineCalls {${body}}`,
+    "}",
+    ""
+  ].join("\n");
+}
+
+// src/gamedata/jsonc.ts
+function stripJsonComments(src) {
+  let out = "";
+  let i2 = 0;
+  const n3 = src.length;
+  while (i2 < n3) {
+    const c2 = src[i2];
+    if (c2 === '"') {
+      out += c2;
+      i2++;
+      while (i2 < n3) {
+        const s = src[i2];
+        if (s === "\\") {
+          out += src.slice(i2, i2 + 2);
+          i2 += 2;
+          continue;
+        }
+        out += s;
+        i2++;
+        if (s === '"') break;
+      }
+      continue;
+    }
+    if (c2 === "/" && src[i2 + 1] === "/") {
+      while (i2 < n3 && src[i2] !== "\n") {
+        out += " ";
+        i2++;
+      }
+      continue;
+    }
+    if (c2 === "/" && src[i2 + 1] === "*") {
+      out += "  ";
+      i2 += 2;
+      while (i2 < n3 && !(src[i2] === "*" && src[i2 + 1] === "/")) {
+        out += src[i2] === "\n" ? "\n" : " ";
+        i2++;
+      }
+      if (i2 < n3) {
+        out += "  ";
+        i2 += 2;
+      }
+      continue;
+    }
+    out += c2;
+    i2++;
+  }
+  return out;
+}
+
 // src/build.ts
 async function buildPlugin(dir, packagesDir) {
   const absDir = resolve5(dir);
@@ -1533,6 +1789,39 @@ async function buildPlugin(dir, packagesDir) {
     if (cfgErrs.length) throw new Error(`invalid s2script.config:
   ${cfgErrs.join("\n  ")}`);
   }
+  const permissions = Array.isArray(s2.permissions) ? s2.permissions : [];
+  let gamedata;
+  if (typeof s2.gamedata === "string") {
+    const gdPath = resolve5(absDir, s2.gamedata);
+    const dirPrefix = absDir.endsWith(sep) ? absDir : absDir + sep;
+    if (gdPath !== absDir && !gdPath.startsWith(dirPrefix)) {
+      throw new Error(
+        `s2script.gamedata escapes the plugin directory: ${JSON.stringify(s2.gamedata)} resolves to ${gdPath}`
+      );
+    }
+    const unscoped = pkg.name.includes("/") ? pkg.name.slice(pkg.name.lastIndexOf("/") + 1) : pkg.name;
+    const actualBase = basename(gdPath);
+    const allowedBases = [`${unscoped}.gamedata.jsonc`, `${unscoped}.gamedata.json`];
+    if (!allowedBases.includes(actualBase)) {
+      throw new Error(
+        `s2script.gamedata must be named '${unscoped}.gamedata.jsonc' (after the plugin name without its scope, like the framework's own core.gamedata.jsonc), but is '${actualBase}'`
+      );
+    }
+    const raw = stripJsonComments(readFileSync4(gdPath, "utf8"));
+    try {
+      gamedata = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`invalid gamedata ${gdPath}: ${e.message}`);
+    }
+    const gdErrs = validatePluginGamedata(gamedata, { permissions });
+    if (gdErrs.length) throw new Error(`invalid gamedata:
+  ${gdErrs.join("\n  ")}`);
+    const genDir = join6(absDir, ".s2script");
+    mkdirSync(genDir, { recursive: true });
+    writeFileSync2(join6(genDir, "gamedata.d.ts"), generateGamedataTypes(gamedata));
+  } else {
+    rmSync2(join6(absDir, ".s2script", "gamedata.d.ts"), { force: true });
+  }
   const tc = typecheckPlugin(absDir, packagesDir !== void 0 ? { packagesDir } : void 0);
   if (!tc.ok) {
     throw new Error(`typecheck failed (${tc.diagnostics.length} error(s)):
@@ -1642,6 +1931,7 @@ ${lint.output}`);
     manifest.publishes = derivedPublishes;
   }
   if (config !== void 0) manifest.config = config;
+  if (permissions.length > 0) manifest.permissions = permissions;
   const compiledAgainst = {};
   for (const dep of [
     ...Object.keys(pluginDependencies),
@@ -1655,6 +1945,7 @@ ${lint.output}`);
     "manifest.json": Buffer.from(JSON.stringify(manifest, null, 2)),
     "plugin.js": Buffer.from(pluginJs)
   };
+  if (gamedata) zipFiles["gamedata.json"] = Buffer.from(JSON.stringify(gamedata, null, 2));
   if (gate.typesPath !== null && Object.keys(derivedPublishes).length > 0) {
     const contract = readFileSync4(gate.typesPath);
     for (const iface of Object.keys(derivedPublishes)) {
@@ -3134,7 +3425,9 @@ var TIMEOUTS_MS = {
   // up to ~40 MiB on a slow uplink
   resolve: 3e4,
   meta: 3e4,
-  "types download": 12e4
+  plan: 3e4,
+  "types download": 12e4,
+  "s2sp download": 12e4
 };
 function rootCause(err2) {
   let cur = err2;
@@ -3261,6 +3554,20 @@ var RegistryClient = class {
     const res = await this.request("meta", u4);
     return this.json(res, "meta");
   }
+  async plan(name, range = "*") {
+    const u4 = new URL(`${this.baseUrl}/api/v1/plan`);
+    u4.searchParams.set("name", name);
+    u4.searchParams.set("range", range);
+    const res = await this.request("plan", u4);
+    return this.json(res, "plan");
+  }
+  async downloadS2sp(name, version) {
+    const u4 = new URL(`${this.baseUrl}/api/v1/download/s2sp`);
+    u4.searchParams.set("name", name);
+    u4.searchParams.set("version", version);
+    const res = await this.request("s2sp download", u4);
+    return Buffer.from(await res.arrayBuffer());
+  }
 };
 
 // src/registry/deploy.ts
@@ -3493,30 +3800,217 @@ async function run3(argv2) {
   }
 }
 
+// src/commands/install.ts
+import { resolve as resolve11 } from "node:path";
+import { existsSync as existsSync10 } from "node:fs";
+
+// src/registry/install.ts
+import { createHash as createHash2 } from "node:crypto";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync6, renameSync, existsSync as existsSync9 } from "node:fs";
+import { basename as basename2, join as join10, resolve as resolve10, sep as sep2 } from "node:path";
+function parseManifest(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("manifest must be a JSON object");
+  }
+  const plugins = input.plugins;
+  if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) {
+    throw new Error('manifest must have a "plugins" object (name -> version range)');
+  }
+  const out = {};
+  for (const [name, range] of Object.entries(plugins)) {
+    if (typeof range !== "string") throw new Error(`range for ${name} must be a string`);
+    out[name] = range;
+  }
+  return { plugins: out };
+}
+function parseSpec2(spec) {
+  const at = spec.lastIndexOf("@");
+  if (at > 0) return { name: spec.slice(0, at), range: spec.slice(at + 1) || "*" };
+  return { name: spec, range: "*" };
+}
+function mergeSpecs(manifest, args) {
+  const merged = { ...manifest.plugins };
+  for (const a2 of args) {
+    const { name, range } = parseSpec2(a2);
+    merged[name] = range;
+  }
+  return merged;
+}
+function sha256Hex(bytes) {
+  return createHash2("sha256").update(bytes).digest("hex");
+}
+var SAFE_FILENAME_RE = /^[A-Za-z0-9._-]+$/;
+function safeFilename(e) {
+  const raw = e.filename;
+  const base = basename2(raw);
+  if (!base || base === "." || base === ".." || base !== raw || base.includes("/") || base.includes("\\") || base.includes("..") || !SAFE_FILENAME_RE.test(base)) {
+    throw new Error(`refusing ${e.name}@${e.version}: unsafe filename "${raw}"`);
+  }
+  return base;
+}
+async function resolveMerged(client, specs) {
+  const chosen = /* @__PURE__ */ new Map();
+  const warnings = [];
+  const errors = [];
+  for (const [name, range] of Object.entries(specs)) {
+    const plan = await client.plan(name, range);
+    if (plan.errors.length) {
+      errors.push(...plan.errors);
+      continue;
+    }
+    warnings.push(...plan.warnings);
+    for (const entry of plan.install) {
+      const prior = chosen.get(entry.name);
+      if (prior && prior.version !== entry.version) {
+        errors.push(
+          `version conflict for ${entry.name}: ${prior.version} vs ${entry.version} across requested plugins`
+        );
+        continue;
+      }
+      chosen.set(entry.name, entry);
+    }
+  }
+  return {
+    install: [...chosen.values()].sort((a2, b) => a2.name.localeCompare(b.name)),
+    warnings: [...new Set(warnings)],
+    errors: [...new Set(errors)]
+  };
+}
+async function installPlan(opts) {
+  const log3 = opts.log ?? (() => {
+  });
+  const { install, warnings, errors } = await resolveMerged(opts.client, opts.specs);
+  if (errors.length) throw new Error(`cannot resolve plugins:
+  - ${errors.join("\n  - ")}`);
+  if (opts.reviewedOnly) {
+    const unreviewed = install.filter((e) => e.reviewState !== "reviewed");
+    if (unreviewed.length) {
+      throw new Error(
+        `--reviewed-only: refusing unreviewed plugins: ${unreviewed.map((e) => `${e.name}@${e.version}`).join(", ")}`
+      );
+    }
+  }
+  const dirResolved = resolve10(opts.dir);
+  const targets = install.map((e) => {
+    if (!e.sha256) {
+      throw new Error(`refusing ${e.name}@${e.version}: registry did not provide a sha256 to verify against`);
+    }
+    const filename = safeFilename(e);
+    const dest = resolve10(join10(opts.dir, filename));
+    if (dest !== dirResolved && !dest.startsWith(dirResolved + sep2)) {
+      throw new Error(`refusing ${e.name}@${e.version}: destination "${dest}" escapes plugins dir "${dirResolved}"`);
+    }
+    return { entry: e, filename, dest };
+  });
+  for (const w of warnings) log3(`warning: ${w}`);
+  if (opts.dryRun) {
+    for (const e of install) log3(`would install ${e.name}@${e.version} -> ${e.filename}`);
+    return { written: [], skipped: [], warnings };
+  }
+  mkdirSync4(opts.dir, { recursive: true });
+  const written = [];
+  const skipped = [];
+  for (const { entry: e, filename, dest } of targets) {
+    if (existsSync9(dest)) {
+      const have = sha256Hex(readFileSync10(dest));
+      if (have === e.sha256) {
+        skipped.push(filename);
+        log3(`up to date ${filename}`);
+        continue;
+      }
+    }
+    const bytes = await opts.client.downloadS2sp(e.name, e.version);
+    const got = sha256Hex(bytes);
+    if (got !== e.sha256) {
+      throw new Error(`sha256 mismatch for ${e.name}@${e.version}: expected ${e.sha256}, got ${got}`);
+    }
+    const tmp = `${dest}.${process.pid}.tmp`;
+    writeFileSync6(tmp, bytes);
+    renameSync(tmp, dest);
+    written.push(filename);
+    log3(`installed ${e.name}@${e.version} -> ${filename}`);
+  }
+  return { written, skipped, warnings };
+}
+function loadManifestFile(path) {
+  if (!existsSync9(path)) return { plugins: {} };
+  return parseManifest(JSON.parse(readFileSync10(path, "utf8")));
+}
+
+// src/commands/install.ts
+var AUTODETECT = "addons/s2script/plugins";
+async function run4(argv2) {
+  const args = positionals(argv2, ["--dir", "--file", "--registry"]);
+  const file = parseFlag(argv2, "--file") ?? "s2script-plugins.json";
+  const registry = parseFlag(argv2, "--registry") || loadCredentials()?.registryUrl || defaultRegistryUrl();
+  const dryRun = hasFlag(argv2, "--dry-run");
+  const reviewedOnly = hasFlag(argv2, "--reviewed-only");
+  let dir = parseFlag(argv2, "--dir");
+  if (!dir) {
+    if (existsSync10(resolve11(AUTODETECT))) dir = resolve11(AUTODETECT);
+    else {
+      console.error(
+        `Usage: s2s install [name[@range]...] --dir <plugins dir>
+  No --dir given and ./${AUTODETECT} not found. Point --dir at your addons/s2script/plugins directory.`
+      );
+      process.exit(1);
+    }
+  }
+  const client = new RegistryClient({ baseUrl: registry });
+  try {
+    const manifest = loadManifestFile(resolve11(file));
+    const specs = mergeSpecs(manifest, args);
+    if (Object.keys(specs).length === 0) {
+      console.error(
+        `Nothing to install. Add plugins to ${file} or pass names: s2s install rtv@^1.0.0`
+      );
+      process.exit(1);
+    }
+    const res = await installPlan({
+      client,
+      specs,
+      dir,
+      dryRun,
+      reviewedOnly,
+      log: (m) => console.log(m)
+    });
+    if (dryRun) {
+      console.log("dry run \u2014 nothing written");
+    } else {
+      console.log(
+        `done: ${res.written.length} installed, ${res.skipped.length} up to date, in ${dir}`
+      );
+    }
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
+}
+
 // src/create/create.ts
 import {
-  mkdirSync as mkdirSync4,
-  writeFileSync as writeFileSync6,
-  existsSync as existsSync9,
+  mkdirSync as mkdirSync5,
+  writeFileSync as writeFileSync7,
+  existsSync as existsSync11,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   symlinkSync
 } from "node:fs";
-import { dirname as dirname2, join as join10, resolve as resolve10, basename } from "node:path";
+import { dirname as dirname2, join as join11, resolve as resolve12, basename as basename3 } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function readCliVersion() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join10(here, "..", "package.json"),
+    join11(here, "..", "package.json"),
     // dist/cli.js → packages/sdk/package.json
-    join10(here, "..", "..", "package.json")
+    join11(here, "..", "..", "package.json")
     // src/create → packages/sdk/package.json
   ];
   for (const p of candidates) {
-    if (!existsSync9(p)) continue;
+    if (!existsSync11(p)) continue;
     try {
-      const pkg = JSON.parse(readFileSync10(p, "utf8"));
+      const pkg = JSON.parse(readFileSync11(p, "utf8"));
       if (pkg.name === "@s2script/sdk" && pkg.version) return pkg.version;
     } catch {
     }
@@ -3526,18 +4020,18 @@ function readCliVersion() {
 function findLocalPackagesDir() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join10(here, "..", ".."),
+    join11(here, "..", ".."),
     // dist/cli.js → packages
-    join10(here, "..", "..", "..")
+    join11(here, "..", "..", "..")
     // src/create → packages
   ];
   for (const c2 of candidates) {
-    if (isPackagesDir(c2)) return resolve10(c2);
+    if (isPackagesDir(c2)) return resolve12(c2);
   }
   return void 0;
 }
 function defaultNameFromPath(dir) {
-  const base = basename(resolve10(dir));
+  const base = basename3(resolve12(dir));
   const slug = base.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "plugin";
   return `@plugin/${slug}`;
 }
@@ -3565,18 +4059,18 @@ function versionSpecFrom(status, stdout2) {
   const v = (stdout2 ?? "").trim();
   return status === 0 && /^\d+\.\d+\.\d+/.test(v) ? `^${v}` : "latest";
 }
-function registryDevDeps(game, sdkVersion, resolve11 = resolvePublishedVersion) {
+function registryDevDeps(game, sdkVersion, resolve13 = resolvePublishedVersion) {
   const deps = {};
   for (const n3 of createPackageNames(game)) {
-    deps[`@s2script/${n3}`] = n3 === "sdk" ? `^${sdkVersion}` : resolve11(`@s2script/${n3}`);
+    deps[`@s2script/${n3}`] = n3 === "sdk" ? `^${sdkVersion}` : resolve13(`@s2script/${n3}`);
   }
   return deps;
 }
 function fileDevDeps(packagesDir, game) {
   const deps = {};
   for (const n3 of createPackageNames(game)) {
-    const abs = join10(packagesDir, n3);
-    if (!existsSync9(join10(abs, "package.json"))) return void 0;
+    const abs = join11(packagesDir, n3);
+    if (!existsSync11(join11(abs, "package.json"))) return void 0;
     deps[`@s2script/${n3}`] = `file:${abs}`;
   }
   return deps;
@@ -3621,7 +4115,12 @@ function tsconfigJson() {
   return JSON.stringify(
     {
       compilerOptions: sharedCompilerOptionsJson,
-      include: ["src", "node_modules/@s2script/sdk/globals.d.ts"]
+      // `.s2script/gamedata.d.ts` is generated by `s2s build` from a plugin's own gamedata and
+      // augments EngineCalls. It must be in `include` or the EDITOR sees `keyof EngineCalls` as
+      // `never` — every Engine.call() shows as an error while `s2s build` passes, because the build
+      // adds the file to its own program (typecheck.ts) but tsconfig never did. Harmless when the
+      // plugin ships no gamedata: the path simply matches nothing.
+      include: ["src", ".s2script/gamedata.d.ts", "node_modules/@s2script/sdk/globals.d.ts"]
     },
     null,
     2
@@ -3656,10 +4155,10 @@ dist/
 `;
 }
 function linkLocalPackagesForNoInstall(targetPath, localPackagesDir) {
-  const nm = join10(targetPath, "node_modules");
-  mkdirSync4(nm, { recursive: true });
-  const dest = join10(nm, "@s2script");
-  if (!existsSync9(dest)) symlinkSync(localPackagesDir, dest);
+  const nm = join11(targetPath, "node_modules");
+  mkdirSync5(nm, { recursive: true });
+  const dest = join11(nm, "@s2script");
+  if (!existsSync11(dest)) symlinkSync(localPackagesDir, dest);
 }
 function runInstall(dir, pm) {
   if (pm === "none") return;
@@ -3672,7 +4171,7 @@ function runInstall(dir, pm) {
   if (r2.status !== 0) throw new Error(`${pm} install failed (exit ${r2.status})`);
 }
 async function createPlugin(opts = {}) {
-  const targetPath = resolve10(opts.path ?? ".");
+  const targetPath = resolve12(opts.path ?? ".");
   const interactive = isInteractive({ yes: opts.yes });
   let game = assertGame(opts.game);
   let name = opts.name;
@@ -3681,7 +4180,7 @@ async function createPlugin(opts = {}) {
   if (template !== "minimal") {
     throw new Error(`unknown template ${JSON.stringify(template)} (v1 supports: minimal)`);
   }
-  if (existsSync9(targetPath)) {
+  if (existsSync11(targetPath)) {
     const kids = readdirSync2(targetPath);
     const meaningful = kids.filter((k) => k !== ".git");
     if (meaningful.length) {
@@ -3734,15 +4233,15 @@ async function createPlugin(opts = {}) {
   install = install ?? (opts.noInstall ? "none" : "npm");
   const version = readCliVersion();
   const localPackagesDir = findLocalPackagesDir();
-  mkdirSync4(join10(targetPath, "src"), { recursive: true });
-  writeFileSync6(
-    join10(targetPath, "package.json"),
+  mkdirSync5(join11(targetPath, "src"), { recursive: true });
+  writeFileSync7(
+    join11(targetPath, "package.json"),
     packageJsonContent(name, game, version, localPackagesDir)
   );
-  writeFileSync6(join10(targetPath, "tsconfig.json"), tsconfigJson());
-  writeFileSync6(join10(targetPath, "eslint.config.mjs"), eslintConfig());
-  writeFileSync6(join10(targetPath, "src", "plugin.ts"), pluginSource(game));
-  writeFileSync6(join10(targetPath, ".gitignore"), gitignore());
+  writeFileSync7(join11(targetPath, "tsconfig.json"), tsconfigJson());
+  writeFileSync7(join11(targetPath, "eslint.config.mjs"), eslintConfig());
+  writeFileSync7(join11(targetPath, "src", "plugin.ts"), pluginSource(game));
+  writeFileSync7(join11(targetPath, ".gitignore"), gitignore());
   let installed = false;
   if (install !== "none") {
     const pm = install;
@@ -3765,7 +4264,7 @@ async function createPlugin(opts = {}) {
 }
 
 // src/commands/create.ts
-async function run4(argv2) {
+async function run5(argv2) {
   const yes = hasFlag(argv2, "--yes") || hasFlag(argv2, "-y");
   const interactive = isInteractive({ yes });
   const pathArg = argv2.find((a2) => !a2.startsWith("-"));
@@ -3955,7 +4454,7 @@ async function loginInteractive(opts) {
 }
 
 // src/commands/login.ts
-async function run5(argv2) {
+async function run6(argv2) {
   const interactive = isInteractive({ ci: hasFlag(argv2, "--ci") });
   try {
     const creds = await loginInteractive({
@@ -3974,8 +4473,8 @@ async function run5(argv2) {
 }
 
 // src/config/gen.ts
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync7, mkdirSync as mkdirSync5 } from "node:fs";
-import { join as join11 } from "node:path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync8, mkdirSync as mkdirSync6 } from "node:fs";
+import { join as join12 } from "node:path";
 
 // src/config/config-path.ts
 function configFileName(id) {
@@ -4021,13 +4520,13 @@ function genConfigFromManifest(manifest, outDir) {
   }
   const id = typeof manifest.id === "string" ? manifest.id : "";
   if (!id) throw new Error("config gen: manifest declares config but has no id");
-  mkdirSync5(outDir, { recursive: true });
-  const path = join11(outDir, configFileName(id));
-  writeFileSync7(path, generateDefaultJsonc(config));
+  mkdirSync6(outDir, { recursive: true });
+  const path = join12(outDir, configFileName(id));
+  writeFileSync8(path, generateDefaultJsonc(config));
   return path;
 }
 function genConfigForS2sp(s2spPath, outDir) {
-  const entry = unzipSync(readFileSync11(s2spPath))["manifest.json"];
+  const entry = unzipSync(readFileSync12(s2spPath))["manifest.json"];
   if (!entry) throw new Error(`config gen: ${s2spPath} has no manifest.json`);
   const manifest = JSON.parse(Buffer.from(entry).toString("utf8"));
   return genConfigFromManifest(manifest, outDir);
@@ -4044,7 +4543,7 @@ function runConfigGen(s2sps, outDir) {
 }
 
 // src/commands/config.ts
-async function run6(argv2) {
+async function run7(argv2) {
   const rest = argv2[0] === "gen" ? argv2.slice(1) : argv2;
   const interactive = isInteractive();
   const outDir = parseFlag(rest, "--out") ?? process.cwd();
@@ -4074,12 +4573,12 @@ async function run6(argv2) {
 }
 
 // src/commands/codegen.ts
-import { dirname as dirname3, join as join15 } from "node:path";
+import { dirname as dirname3, join as join16 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/schemagen/gen.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "node:fs";
-import { join as join12 } from "node:path";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "node:fs";
+import { join as join13 } from "node:path";
 
 // src/schemagen/model.ts
 var READ = {
@@ -4271,21 +4770,21 @@ function emitJs(model) {
   for (const c2 of model.classes) {
     out.push(`  A[${S(c2.className)}] = {`);
     for (const f of flattenedFields(model, c2.className)) {
-      const resolve11 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+      const resolve13 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
       let entry;
       if (f.accessorKind === "str") {
-        entry = `get: function () { return this.ref.readString(${resolve11}, ${f.strLen}); }`;
+        entry = `get: function () { return this.ref.readString(${resolve13}, ${f.strLen}); }`;
       } else if (f.accessorKind === "u64" || f.accessorKind === "i64") {
-        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve11}); return v === null ? null : v.toString(); }`;
+        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve13}); return v === null ? null : v.toString(); }`;
       } else if (VEC_INFO[f.accessorKind]) {
         const vi = VEC_INFO[f.accessorKind];
-        entry = `get: function () { var a = this.ref.readFloats(${resolve11}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+        entry = `get: function () { var a = this.ref.readFloats(${resolve13}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
       } else {
-        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve11}); }`;
+        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve13}); }`;
       }
       if (f.writable) {
         const wm = WRITE[f.accessorKind];
-        entry += `, set: function (v) { var o = ${resolve11}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
+        entry += `, set: function (v) { var o = ${resolve13}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
       }
       out.push(`    ${S(f.propName)}: { ${entry} },`);
     }
@@ -4311,8 +4810,8 @@ var LIST_PATH = "games/cs2/codegen-classes.json";
 var JS_OUT = "games/cs2/js/schema.generated.js";
 var DTS_OUT = "packages/cs2/schema.generated.d.ts";
 function runGenSchema(repoRoot2, opts) {
-  const catalog = JSON.parse(readFileSync12(join12(repoRoot2, CATALOG_PATH), "utf8"));
-  const list = JSON.parse(readFileSync12(join12(repoRoot2, LIST_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync13(join13(repoRoot2, CATALOG_PATH), "utf8"));
+  const list = JSON.parse(readFileSync13(join13(repoRoot2, LIST_PATH), "utf8"));
   const model = buildModel(catalog, list);
   const dts = emitDts(model);
   const js = emitJs(model);
@@ -4321,16 +4820,16 @@ function runGenSchema(repoRoot2, opts) {
   const drift = [];
   const files = [[JS_OUT, js], [DTS_OUT, dts]];
   for (const [rel, content] of files) {
-    const abs = join12(repoRoot2, rel);
+    const abs = join13(repoRoot2, rel);
     if (opts.check) {
       let cur = "";
       try {
-        cur = readFileSync12(abs, "utf8");
+        cur = readFileSync13(abs, "utf8");
       } catch {
       }
       if (cur !== content) drift.push(rel);
     } else {
-      writeFileSync8(abs, content);
+      writeFileSync9(abs, content);
     }
   }
   if (model.collisions.length) console.error(`gen-schema: ${model.collisions.length} name collision(s) \u2192 raw fallback:
@@ -4340,8 +4839,8 @@ function runGenSchema(repoRoot2, opts) {
 }
 
 // src/eventgen/gen.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "node:fs";
-import { join as join13 } from "node:path";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "node:fs";
+import { join as join14 } from "node:path";
 
 // src/eventgen/model.ts
 var TYPE_TO_GETTER = {
@@ -4426,27 +4925,27 @@ function emitEventDts(model) {
 var CATALOG_PATH2 = "games/cs2/gamedata/event-catalog.json";
 var DTS_OUT2 = "packages/cs2/events.generated.d.ts";
 function runGenEvents(repoRoot2, opts) {
-  const catalog = JSON.parse(readFileSync13(join13(repoRoot2, CATALOG_PATH2), "utf8"));
+  const catalog = JSON.parse(readFileSync14(join14(repoRoot2, CATALOG_PATH2), "utf8"));
   const model = buildEventModel(catalog);
   const dts = emitEventDts(model);
   const drift = [];
-  const abs = join13(repoRoot2, DTS_OUT2);
+  const abs = join14(repoRoot2, DTS_OUT2);
   if (opts.check) {
     let cur = "";
     try {
-      cur = readFileSync13(abs, "utf8");
+      cur = readFileSync14(abs, "utf8");
     } catch {
     }
     if (cur !== dts) drift.push(DTS_OUT2);
   } else {
-    writeFileSync9(abs, dts);
+    writeFileSync10(abs, dts);
   }
   return { events: model.length, drift };
 }
 
 // src/navgen/gen.ts
-import { readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "node:fs";
-import { join as join14 } from "node:path";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync11 } from "node:fs";
+import { join as join15 } from "node:path";
 
 // src/navgen/model.ts
 var SUPPORTED_NAV_KINDS = /* @__PURE__ */ new Set([
@@ -4521,22 +5020,22 @@ function emitNavJs(model) {
     out.push(`  function ${w.wrapper}(root, path) { this.root = root; this.path = path; }`);
     out.push(`  Object.defineProperties(${w.wrapper}.prototype, {`);
     for (const f of w.fields) {
-      const resolve11 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
+      const resolve13 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
       let getter;
       const kind = f.accessorKind;
       if (kind === "u64") {
-        getter = `get: function () { var v = this.root.readUInt64Via(this.path, ${resolve11}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readUInt64Via(this.path, ${resolve13}); return v === null ? null : v.toString(); }`;
       } else if (kind === "i64") {
-        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve11}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve13}); return v === null ? null : v.toString(); }`;
       } else if (VEC_INFO[kind]) {
         const vi = VEC_INFO[kind];
-        getter = `get: function () { var a = this.root.readFloatsChain(this.path, ${resolve11}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+        getter = `get: function () { var a = this.root.readFloatsChain(this.path, ${resolve13}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
       } else if (kind === "handle") {
-        getter = `get: function () { return this.root.readHandleVia(this.path, ${resolve11}); }`;
+        getter = `get: function () { return this.root.readHandleVia(this.path, ${resolve13}); }`;
       } else {
         const method = READ_VIA[kind];
         if (!method) continue;
-        getter = `get: function () { return this.root.${method}(this.path, ${resolve11}); }`;
+        getter = `get: function () { return this.root.${method}(this.path, ${resolve13}); }`;
       }
       out.push(`    ${S2(f.propName)}: { ${getter} },`);
     }
@@ -4608,8 +5107,8 @@ var CATALOG_PATH3 = "games/cs2/gamedata/schema-catalog.json";
 var JS_OUT2 = "games/cs2/js/nav.generated.js";
 var DTS_OUT3 = "packages/cs2/nav.generated.d.ts";
 function runGenNav(repoRoot2, opts) {
-  const config = JSON.parse(readFileSync14(join14(repoRoot2, TARGETS_PATH), "utf8"));
-  const catalog = JSON.parse(readFileSync14(join14(repoRoot2, CATALOG_PATH3), "utf8"));
+  const config = JSON.parse(readFileSync15(join15(repoRoot2, TARGETS_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync15(join15(repoRoot2, CATALOG_PATH3), "utf8"));
   const model = buildNavModel(config, catalog);
   const js = emitNavJs(model);
   const dts = emitNavDts(model);
@@ -4617,16 +5116,16 @@ function runGenNav(repoRoot2, opts) {
   const drift = [];
   const files = [[JS_OUT2, js], [DTS_OUT3, dts]];
   for (const [rel, content] of files) {
-    const abs = join14(repoRoot2, rel);
+    const abs = join15(repoRoot2, rel);
     if (opts.check) {
       let cur = "";
       try {
-        cur = readFileSync14(abs, "utf8");
+        cur = readFileSync15(abs, "utf8");
       } catch {
       }
       if (cur !== content) drift.push(rel);
     } else {
-      writeFileSync10(abs, content);
+      writeFileSync11(abs, content);
     }
   }
   return { wrappers: model.wrappers.length, fields, drift };
@@ -4634,9 +5133,9 @@ function runGenNav(repoRoot2, opts) {
 
 // src/commands/codegen.ts
 function repoRoot() {
-  return join15(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join16(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
-async function run7(kind, argv2) {
+async function run8(kind, argv2) {
   const root = repoRoot();
   const check = argv2[0] === "--check";
   if (kind === "schema") {
@@ -4680,15 +5179,16 @@ async function run7(kind, argv2) {
 
 // src/commands/index.ts
 var COMMANDS = [
-  { name: "create", summary: "Scaffold a new plugin", run: run4 },
+  { name: "create", summary: "Scaffold a new plugin", run: run5 },
   { name: "build", summary: "Build a plugin to a .s2sp", run },
   { name: "deploy", summary: "Publish a plugin to the registry", run: run2 },
   { name: "add", summary: "Add a registry package's types", run: run3 },
-  { name: "login", summary: "Save a registry deploy token", run: run5 },
-  { name: "config", summary: "Emit a plugin's default config file(s)", run: run6 },
-  { name: "gen-schema", summary: "Regenerate schema accessors", run: (a2) => run7("schema", a2) },
-  { name: "gen-events", summary: "Regenerate the event catalog", run: (a2) => run7("events", a2) },
-  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run7("nav", a2) }
+  { name: "install", summary: "Download plugins + their deps into a server", run: run4 },
+  { name: "login", summary: "Save a registry deploy token", run: run6 },
+  { name: "config", summary: "Emit a plugin's default config file(s)", run: run7 },
+  { name: "gen-schema", summary: "Regenerate schema accessors", run: (a2) => run8("schema", a2) },
+  { name: "gen-events", summary: "Regenerate the event catalog", run: (a2) => run8("events", a2) },
+  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run8("nav", a2) }
 ];
 function find(name) {
   if (name === "publish") return COMMANDS.find((c2) => c2.name === "deploy");
@@ -4696,7 +5196,7 @@ function find(name) {
 }
 
 // src/commands/menu.ts
-async function run8() {
+async function run9() {
   intro2("s2script");
   const name = await select2({
     message: "What would you like to do?",
@@ -4711,12 +5211,12 @@ var argv = process.argv.slice(2);
 var command = argv[0];
 function usage() {
   console.error(
-    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir] [--ci] [--registry <url>] [--packages-dir <path>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
+    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir] [--ci] [--registry <url>] [--packages-dir <path>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s install [name[@range]...] [--file <path>] [--dir <plugins dir>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
   );
 }
 if (!command) {
   if (isInteractive()) {
-    await run8();
+    await run9();
   } else {
     usage();
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT OR Apache-2.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",
@@ -111,6 +111,9 @@
     "./transmit": {
       "types": "./transmit.d.ts"
     },
+    "./unsafe": {
+      "types": "./unsafe.d.ts"
+    },
     "./usercmd": {
       "types": "./usercmd.d.ts"
     },

package/unsafe.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @s2script/sdk/unsafe — plugin-declared engine calls. NO runtime code: the engine injects the
+ * implementation at load (`__s2pkg_unsafe`).
+ *
+ * UNSAFE by design. A declared call reaches a real engine function. The framework validates every
+ * descriptor at load and degrades a failure to `null`, but it cannot prove your signature or vtable
+ * index names the function you meant. Requires manifest `permissions: ["engine:calls"]` AND an
+ * operator allow-list entry (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md §6).
+ */
+
+/**
+ * The calls this plugin declares. The base interface is EMPTY — `s2s build` generates
+ * `.s2script/gamedata.d.ts`, which augments this from your gamedata's `calls` section.
+ */
+export interface EngineCalls {}
+
+export declare const Engine: {
+  /**
+   * The declared call, or `null` when its descriptor failed a load-time gate (signature miss,
+   * validator rejection, slot outside `.text`, missing platform entry, or the plugin is not
+   * operator-allow-listed). Guard once at load; the returned function is a plain callable.
+   */
+  call<K extends keyof EngineCalls>(name: K): EngineCalls[K] | null;
+  /** Why a descriptor is unavailable; `"available"` when it resolved. For diagnostics/operator reports. */
+  status(name: string): string;
+};