@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/runtime.js

@@ -0,0 +1,346 @@
+// ../sdk/lib/build/callbacks.js
+var UndeclaredApiUseError = class extends Error {
+  resourceIdentifier;
+  api;
+  constructor(resourceIdentifier, api) {
+    super(`Resource "${resourceIdentifier}" attempted to call callback "${api}" but did not declare it in its bundle's "uses" array. Add "${api}" to the bundle's uses to allow this call.`);
+    this.name = "UndeclaredApiUseError";
+    this.resourceIdentifier = resourceIdentifier;
+    this.api = api;
+  }
+};
+
+// ../sdk/lib/build/tick-validation.js
+var MAX_EFFECTIVE_TICK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
+
+// cli/runtime/guarded-callbacks.ts
+var API_USE_TO_CALLBACK = {
+  generateText: "generateText",
+  extractText: "extractText",
+  generateSpeech: "generateSpeech",
+  writeBlob: "writeBlob"
+};
+function createGuardedCallbacks(callbacks, uses, resourceIdentifier) {
+  const declared = new Set(uses ?? []);
+  const guarded = { ...callbacks };
+  for (const [api, key] of Object.entries(API_USE_TO_CALLBACK)) {
+    if (declared.has(api)) continue;
+    if (callbacks[key] === void 0) continue;
+    guarded[key] = async () => {
+      throw new UndeclaredApiUseError(resourceIdentifier, api);
+    };
+  }
+  return guarded;
+}
+
+// cli/runtime/capability-scope.ts
+function resolveCapabilityScope(definition) {
+  return definition.scope ?? "team";
+}
+
+// cli/runtime/context-merge.ts
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return true;
+  return Object.getPrototypeOf(proto) === null;
+}
+function deepMergeContext(base, patch) {
+  const result = { ...base };
+  for (const key of Object.keys(patch)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    const baseValue = result[key];
+    const patchValue = patch[key];
+    result[key] = isPlainObject(baseValue) && isPlainObject(patchValue) ? deepMergeContext(baseValue, patchValue) : patchValue;
+  }
+  return result;
+}
+function segmentsOf(path) {
+  return typeof path === "string" ? path.split(".") : [...path];
+}
+function deletePath(base, path) {
+  const segments = segmentsOf(path);
+  if (segments.length === 0 || segments.some((segment) => UNSAFE_KEYS.has(segment))) {
+    return base;
+  }
+  const [head, ...rest] = segments;
+  if (!Object.prototype.hasOwnProperty.call(base, head)) return base;
+  if (rest.length === 0) {
+    const result = { ...base };
+    delete result[head];
+    return result;
+  }
+  const child = base[head];
+  if (!isPlainObject(child)) return base;
+  const prunedChild = deletePath(child, rest);
+  if (prunedChild === child) return base;
+  return { ...base, [head]: prunedChild };
+}
+function applyContextUpdate(base, patch, deletes) {
+  const merged = deepMergeContext(base, patch);
+  if (!deletes || deletes.length === 0) return merged;
+  return deletes.reduce((context, path) => deletePath(context, path), merged);
+}
+
+// cli/runtime/context-projection.ts
+function declaredCapabilityIds(args) {
+  const capabilities = args.capabilities;
+  const declared = /* @__PURE__ */ new Set();
+  for (const identifier of [...args.reads ?? [], ...args.writes ?? []]) {
+    const definition = capabilities?.get(identifier);
+    if (definition && !isDeliverableToSurfaces(definition)) continue;
+    declared.add(identifier);
+  }
+  return declared;
+}
+function isDeliverableToSurfaces(definition) {
+  return (definition.scope ?? "team") !== "private";
+}
+function projectContext(context, declared) {
+  const projected = {};
+  for (const identifier of Object.keys(context)) {
+    if (declared.has(identifier)) {
+      projected[identifier] = context[identifier];
+    }
+  }
+  return projected;
+}
+
+// cli/runtime/tick-validation.ts
+var MIN_EFFECTIVE_TICK_INTERVAL_MS = 3e4;
+var MAX_EFFECTIVE_TICK_INTERVAL_MS2 = 7 * 24 * 60 * 60 * 1e3;
+function validateTickControllerResult2(result, options) {
+  const { intervalMs, nextTickAt } = result;
+  if (nextTickAt !== void 0 && (typeof nextTickAt !== "number" || !Number.isFinite(nextTickAt))) {
+    return `Tick controller nextTickAt must be a finite timestamp in milliseconds; got ${describe(nextTickAt)}. See the tick controller guide.`;
+  }
+  const now = options?.now ?? Date.now();
+  const effectiveMs = nextTickAt !== void 0 ? nextTickAt - now : intervalMs ?? NaN;
+  if (nextTickAt !== void 0 && effectiveMs <= 0) {
+    return null;
+  }
+  if ((nextTickAt === void 0 || intervalMs !== void 0) && (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || !Number.isInteger(intervalMs) || intervalMs < 1)) {
+    return `Tick intervalMs must be a finite, positive, whole number of milliseconds; got ${describe(intervalMs)}. Build interval-based results with intervalTick(intervalMs). See the tick controller guide.`;
+  }
+  if (effectiveMs < MIN_EFFECTIVE_TICK_INTERVAL_MS) {
+    return `Effective tick cadence of ${duration(effectiveMs)} is below the 30-second minimum (${MIN_EFFECTIVE_TICK_INTERVAL_MS} ms). Use intervalTick(intervalMs) with at least ${MIN_EFFECTIVE_TICK_INTERVAL_MS}, or schedule nextTickAt further out. See the tick controller guide.`;
+  }
+  if (effectiveMs > MAX_EFFECTIVE_TICK_INTERVAL_MS2) {
+    return `Effective tick cadence of ${duration(effectiveMs)} exceeds the 7-day maximum (${MAX_EFFECTIVE_TICK_INTERVAL_MS2} ms). For longer gaps, set enabled: false and drive ticks by another means. See the tick controller guide.`;
+  }
+  return null;
+}
+function describe(value) {
+  if (value === void 0) return "undefined";
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) return "NaN";
+    if (!Number.isFinite(value)) return value > 0 ? "Infinity" : "-Infinity";
+    return String(value);
+  }
+  return typeof value;
+}
+function duration(ms) {
+  const rounded = Number.isInteger(ms) ? String(ms) : ms.toFixed(1);
+  const seconds = ms / 1e3;
+  const human = seconds >= 86400 ? `${round(seconds / 86400)} days` : seconds >= 3600 ? `${round(seconds / 3600)} hours` : seconds >= 1 ? `${round(seconds)} seconds` : "under a second";
+  return `${rounded} ms (${human})`;
+}
+function round(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+// cli/execution/engine-state.ts
+var ENGINE_STATE_KEY = "$engineState";
+var SHARED_ENGINE_STATE_KEY = "$sharedEngineState";
+var RESERVED_KEYS = /* @__PURE__ */ new Set([ENGINE_STATE_KEY, SHARED_ENGINE_STATE_KEY]);
+function isReservedKey(key) {
+  return RESERVED_KEYS.has(key);
+}
+function assertJsonSerialisable(label, value) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node, path) => {
+    if (node === null || typeof node === "string" || typeof node === "boolean") return;
+    if (typeof node === "number") {
+      if (Number.isFinite(node)) return;
+      throw new Error(`${label} state at ${path} is ${node}, which JSON cannot hold`);
+    }
+    if (typeof node !== "object") {
+      throw new Error(
+        `${label} state at ${path} is a ${typeof node}, which JSON cannot hold`
+      );
+    }
+    if (seen.has(node)) {
+      throw new Error(`${label} state at ${path} refers back to itself`);
+    }
+    seen.add(node);
+    if (Array.isArray(node)) {
+      node.forEach((item, i) => visit(item, `${path}[${i}]`));
+    } else {
+      const tag = Object.prototype.toString.call(node);
+      const prototype = Object.getPrototypeOf(node);
+      if (tag !== "[object Object]" || prototype !== null && prototype.constructor?.name !== "Object") {
+        throw new Error(
+          `${label} state at ${path} is a ${tag.slice(8, -1)}, not a plain object. Engine state must be JSON-serialisable.`
+        );
+      }
+      for (const [key, child] of Object.entries(node)) {
+        if (child === void 0) {
+          throw new Error(
+            `${label} state at ${path}.${key} is undefined, which JSON drops. Use null.`
+          );
+        }
+        visit(child, `${path}.${key}`);
+      }
+    }
+    seen.delete(node);
+  };
+  visit(value, "state");
+}
+
+// cli/execution/logic-result.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readCapabilities(label, result, allowed = ["capabilities", "deletes"]) {
+  if (!isRecord(result)) {
+    throw new Error(`${label} must return an object of the form { capabilities: { ... } }`);
+  }
+  const unknownKeys = Object.keys(result).filter((key) => !allowed.includes(key));
+  if (unknownKeys.length > 0) {
+    const keys = unknownKeys.map((key) => `"${key}"`).join(", ");
+    throw new Error(
+      `${label} returned unknown top-level key${unknownKeys.length === 1 ? "" : "s"} ${keys}. Return capability writes under "capabilities", e.g. { capabilities: { ${unknownKeys[0]}: { ... } } }`
+    );
+  }
+  const capabilities = result.capabilities;
+  if (capabilities === void 0 || capabilities === null) {
+    return {};
+  }
+  if (!isRecord(capabilities)) {
+    throw new Error(`${label} returned "capabilities" that is not an object`);
+  }
+  const reserved = Object.keys(capabilities).find(isReservedKey);
+  if (reserved !== void 0) {
+    throw new Error(
+      `${label} returned "${reserved}" under "capabilities", which is not a capability`
+    );
+  }
+  return capabilities;
+}
+function readDeletes(label, result) {
+  if (!isRecord(result)) return [];
+  const deletes = result.deletes;
+  if (deletes === void 0 || deletes === null) return [];
+  if (!Array.isArray(deletes)) {
+    throw new Error(`${label} returned "deletes" that is not an array of paths`);
+  }
+  return deletes.map((path, i) => {
+    if (typeof path === "string" && path.length > 0) return path;
+    if (Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0)) {
+      return [...path];
+    }
+    throw new Error(
+      `${label} returned "deletes[${i}]" that is not a path: give a non-empty string of segments joined by ".", or a non-empty array of segments`
+    );
+  });
+}
+function readEngineResult(label, result, phase = "init") {
+  const allowed = phase === "tick" ? ["capabilities", "deletes", "state", "complete"] : ["capabilities", "deletes", "state"];
+  const capabilities = readCapabilities(label, result, allowed);
+  const deletes = readDeletes(label, result);
+  const { state, complete } = result;
+  if (complete !== void 0 && typeof complete !== "boolean") {
+    throw new Error(`${label} returned "complete" that is not a boolean`);
+  }
+  return { capabilities, deletes, state, complete: complete === true };
+}
+function readAggregateResult(label, result, teamCount, phase = "init") {
+  if (!isRecord(result)) {
+    throw new Error(
+      `${label} must return { shared: { capabilities }, teams: [{ capabilities }] }`
+    );
+  }
+  const unknownKeys = Object.keys(result).filter((key) => key !== "shared" && key !== "teams");
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `${label} returned unknown top-level key${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.map((key) => `"${key}"`).join(", ")}. Return { shared: { capabilities }, teams: [{ capabilities }] }`
+    );
+  }
+  if (!Array.isArray(result.teams) || result.teams.length !== teamCount) {
+    throw new Error(
+      `${label} must return one entry in "teams" per team passed to it (${teamCount})`
+    );
+  }
+  return {
+    shared: result.shared === void 0 ? { capabilities: {}, deletes: [], state: void 0, complete: false } : readEngineResult(`${label} "shared"`, result.shared, phase),
+    teams: result.teams.map(
+      (team, i) => readEngineResult(`${label} "teams[${i}]"`, team, phase)
+    )
+  };
+}
+var TICK_CONTROLLER_KEYS = ["enabled", "intervalMs", "nextTickAt", "complete"];
+function readTickControllerResult(label, result) {
+  if (!isRecord(result)) {
+    throw new Error(`${label} must return an object of the form { enabled, intervalMs? }`);
+  }
+  const unknownKeys = Object.keys(result).filter((key) => !TICK_CONTROLLER_KEYS.includes(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `${label} returned unknown key${unknownKeys.length === 1 ? "" : "s"} ${unknownKeys.map((key) => `"${key}"`).join(", ")}. A tick controller result holds only ${TICK_CONTROLLER_KEYS.map((key) => `"${key}"`).join(", ")}`
+    );
+  }
+  if (typeof result.enabled !== "boolean") {
+    throw new Error(`${label} returned "enabled" that is not a boolean`);
+  }
+  if (result.complete !== void 0 && typeof result.complete !== "boolean") {
+    throw new Error(`${label} returned "complete" that is not a boolean`);
+  }
+  return result;
+}
+
+// cli/runtime/manifest-version.ts
+var MANIFEST_VERSION = 3;
+var SUPPORTED_FEATURES = [];
+function unsupportedFeatures(manifest) {
+  return (manifest.requires ?? []).filter((feature) => !SUPPORTED_FEATURES.includes(feature));
+}
+var SUPPORTED_SERVICES = [
+  "generateText",
+  "extractText",
+  "generateSpeech",
+  "writeBlob"
+];
+function unsupportedServices(resources, supported = SUPPORTED_SERVICES) {
+  const missing = /* @__PURE__ */ new Map();
+  for (const resource of resources) {
+    for (const service of resource.definition.uses ?? []) {
+      if (supported.includes(service)) continue;
+      const declaring = missing.get(service) ?? [];
+      if (!declaring.includes(resource.definition.identifier)) {
+        declaring.push(resource.definition.identifier);
+      }
+      missing.set(service, declaring);
+    }
+  }
+  return [...missing].map(([service, declaring]) => ({ service, resources: declaring }));
+}
+export {
+  MANIFEST_VERSION,
+  SUPPORTED_FEATURES,
+  SUPPORTED_SERVICES,
+  applyContextUpdate,
+  assertJsonSerialisable,
+  createGuardedCallbacks,
+  declaredCapabilityIds,
+  deepMergeContext,
+  projectContext,
+  readAggregateResult,
+  readEngineResult,
+  readTickControllerResult,
+  resolveCapabilityScope,
+  unsupportedFeatures,
+  unsupportedServices,
+  validateTickControllerResult2 as validateTickControllerResult
+};