@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/game-action-runtime.mjs

@@ -0,0 +1,869 @@
+export const GAME_ACTION_SCHEMA_VERSION = 'aurajs.game-action-schema.v1';
+export const GAME_ACTION_REQUEST_SCHEMA_VERSION = 'aurajs.game-action-request.v1';
+export const GAME_ACTION_RESULT_SCHEMA_VERSION = 'aurajs.game-action-result.v1';
+
+const ACTION_CONTRACT_STORAGE_KEY = '__gameActionContract';
+const ACTION_SCHEMA_KEY_ORDER = ['schemaVersion', 'actions'];
+const ACTION_DEFINITION_KEY_ORDER = ['id', 'title', 'description', 'inputSchema'];
+const ACTION_RESULT_KEY_ORDER = ['schemaVersion', 'ok', 'reasonCode', 'actionId', 'detail', 'output'];
+
+export function createGameActionRuntimeHooks({ aura } = {}) {
+  if (!aura || typeof aura !== 'object') {
+    throw new Error('createGameActionRuntimeHooks requires an aura runtime object.');
+  }
+
+  return {
+    defineActionContract(contract) {
+      return defineGameActionContract(aura, contract);
+    },
+    getActionSchema() {
+      return exportCanonicalGameActionSchema(aura);
+    },
+    runAction(request) {
+      return runCanonicalGameAction(aura, request);
+    },
+  };
+}
+
+export function installGameActionRuntimeBootstrap(aura) {
+  const schemaVersion = 'aurajs.game-action-schema.v1';
+  const requestSchemaVersion = 'aurajs.game-action-request.v1';
+  const resultSchemaVersion = 'aurajs.game-action-result.v1';
+  const storageKey = '__gameActionContract';
+  const schemaKeyOrder = ['schemaVersion', 'actions'];
+  const definitionKeyOrder = ['id', 'title', 'description', 'inputSchema'];
+  const resultKeyOrder = ['schemaVersion', 'ok', 'reasonCode', 'actionId', 'detail', 'output'];
+
+  const isPlainObjectLocal = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+  const sanitizeJsonValueLocal = (value) => {
+    if (value === null) return null;
+    if (typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number') {
+      return Number.isFinite(value) ? Number(value) : null;
+    }
+    if (Array.isArray(value)) {
+      return value.map((entry) => sanitizeJsonValueLocal(entry));
+    }
+    if (isPlainObjectLocal(value)) {
+      const out = {};
+      const keys = Object.keys(value).sort();
+      for (const key of keys) {
+        const next = sanitizeJsonValueLocal(value[key]);
+        if (next === undefined) continue;
+        out[key] = next;
+      }
+      return out;
+    }
+    return null;
+  };
+  const orderPayloadLocal = (payload, keyOrder) => {
+    const ordered = {};
+    for (const key of keyOrder) {
+      if (Object.prototype.hasOwnProperty.call(payload, key)) {
+        ordered[key] = payload[key];
+      }
+    }
+    return ordered;
+  };
+  const createActionResultLocal = ({ ok, reasonCode, actionId = null, detail = null, output = undefined }) => {
+    const payload = {
+      schemaVersion: resultSchemaVersion,
+      ok: ok === true,
+      reasonCode: typeof reasonCode === 'string' && reasonCode
+        ? reasonCode
+        : ok === true
+          ? 'action_run_ok'
+          : 'action_run_failed',
+    };
+    if (typeof actionId === 'string' && actionId) {
+      payload.actionId = actionId;
+    }
+    if (typeof detail === 'string' && detail.trim()) {
+      payload.detail = detail.trim();
+    }
+    if (output !== undefined) {
+      payload.output = sanitizeJsonValueLocal(output);
+    }
+    return orderPayloadLocal(payload, resultKeyOrder);
+  };
+  const normalizeActionDefinitionsLocal = (actionEntries) => {
+    if (!Array.isArray(actionEntries)) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: 'action contract actions must resolve to an array',
+      };
+    }
+
+    const normalizedActions = [];
+    const seenIds = new Set();
+
+    for (let index = 0; index < actionEntries.length; index += 1) {
+      const entry = actionEntries[index];
+      if (!isPlainObjectLocal(entry)) {
+        return {
+          ok: false,
+          reasonCode: 'invalid_action_contract',
+          detail: `action at index ${index} must be an object`,
+        };
+      }
+
+      const id = typeof entry.id === 'string' ? entry.id.trim() : '';
+      if (!id) {
+        return {
+          ok: false,
+          reasonCode: 'invalid_action_contract',
+          detail: `action at index ${index} requires a non-empty id`,
+        };
+      }
+      if (seenIds.has(id)) {
+        return {
+          ok: false,
+          reasonCode: 'invalid_action_contract',
+          detail: `duplicate action id "${id}"`,
+        };
+      }
+      if (!isPlainObjectLocal(entry.inputSchema)) {
+        return {
+          ok: false,
+          reasonCode: 'invalid_action_contract',
+          detail: `action "${id}" requires inputSchema object`,
+        };
+      }
+
+      seenIds.add(id);
+      const normalizedAction = {
+        id,
+        inputSchema: sanitizeJsonValueLocal(entry.inputSchema),
+      };
+      if (typeof entry.title === 'string' && entry.title.trim()) {
+        normalizedAction.title = entry.title.trim();
+      }
+      if (typeof entry.description === 'string' && entry.description.trim()) {
+        normalizedAction.description = entry.description.trim();
+      }
+
+      normalizedActions.push(orderPayloadLocal(normalizedAction, definitionKeyOrder));
+    }
+
+    return {
+      ok: true,
+      actions: normalizedActions,
+    };
+  };
+  const normalizeActionContractLocal = (contract) => {
+    if (!isPlainObjectLocal(contract)) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: 'action contract must be an object',
+      };
+    }
+
+    const actions = contract.actions;
+    if (!Array.isArray(actions) && typeof actions !== 'function') {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: 'action contract requires actions array or function',
+      };
+    }
+    if (typeof contract.run !== 'function') {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: 'action contract requires run(action, context)',
+      };
+    }
+
+    if (Array.isArray(actions)) {
+      const normalized = normalizeActionDefinitionsLocal(actions);
+      if (!normalized.ok) {
+        return normalized;
+      }
+      return {
+        ok: true,
+        contract: Object.freeze({
+          actions: Object.freeze(normalized.actions),
+          run: contract.run,
+        }),
+      };
+    }
+
+    return {
+      ok: true,
+      contract: Object.freeze({
+        actions,
+        run: contract.run,
+      }),
+    };
+  };
+  const resolveActionSchemaPayloadLocal = () => {
+    const contract = aura && typeof aura === 'object' ? aura[storageKey] : null;
+    if (!contract || typeof contract !== 'object') {
+      return {
+        ok: false,
+        reasonCode: 'action_contract_unavailable',
+        detail: 'game did not define aura.action contract',
+      };
+    }
+
+    let actionEntries;
+    try {
+      actionEntries = typeof contract.actions === 'function'
+        ? contract.actions({ aura })
+        : contract.actions;
+    } catch (error) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    const normalized = normalizeActionDefinitionsLocal(actionEntries);
+    if (!normalized.ok) {
+      return normalized;
+    }
+
+    return {
+      ok: true,
+      contract,
+      payload: orderPayloadLocal({
+        schemaVersion,
+        actions: normalized.actions,
+      }, schemaKeyOrder),
+    };
+  };
+  const validateActionRequestLocal = (request, actions) => {
+    if (!isPlainObjectLocal(request)) {
+      return {
+        ok: false,
+        result: createActionResultLocal({
+          ok: false,
+          reasonCode: 'invalid_action_request',
+          detail: 'request must be an object',
+        }),
+      };
+    }
+    if (request.schemaVersion !== requestSchemaVersion) {
+      return {
+        ok: false,
+        result: createActionResultLocal({
+          ok: false,
+          reasonCode: 'schema_version_mismatch',
+          detail: `expected ${requestSchemaVersion}`,
+        }),
+      };
+    }
+    if (!isPlainObjectLocal(request.action)) {
+      return {
+        ok: false,
+        result: createActionResultLocal({
+          ok: false,
+          reasonCode: 'invalid_action_request',
+          detail: 'request.action must be an object',
+        }),
+      };
+    }
+
+    const actionId = typeof request.action.id === 'string' ? request.action.id.trim() : '';
+    if (!actionId) {
+      return {
+        ok: false,
+        result: createActionResultLocal({
+          ok: false,
+          reasonCode: 'invalid_action_request',
+          detail: 'request.action.id must be a non-empty string',
+        }),
+      };
+    }
+
+    const action = Array.isArray(actions) ? actions.find((entry) => entry.id === actionId) : null;
+    if (!action) {
+      return {
+        ok: false,
+        result: createActionResultLocal({
+          ok: false,
+          reasonCode: 'action_unknown_id',
+          actionId,
+          detail: `unknown action "${actionId}"`,
+        }),
+      };
+    }
+
+    return {
+      ok: true,
+      request,
+      action: {
+        id: actionId,
+        args: sanitizeJsonValueLocal(request.action.args),
+      },
+    };
+  };
+  const normalizeActionRunResultLocal = (rawResult, actionId) => {
+    if (rawResult && typeof rawResult === 'object' && rawResult.schemaVersion === resultSchemaVersion) {
+      return rawResult;
+    }
+    if (rawResult === false) {
+      return createActionResultLocal({
+        ok: false,
+        actionId,
+        reasonCode: 'action_run_failed',
+      });
+    }
+    if (!isPlainObjectLocal(rawResult)) {
+      return createActionResultLocal({
+        ok: true,
+        actionId,
+        reasonCode: 'action_run_ok',
+        output: rawResult,
+      });
+    }
+    if (rawResult.ok === true) {
+      return createActionResultLocal({
+        ok: true,
+        actionId,
+        reasonCode: typeof rawResult.reasonCode === 'string' ? rawResult.reasonCode : 'action_run_ok',
+        output: rawResult.output,
+      });
+    }
+    return createActionResultLocal({
+      ok: false,
+      actionId,
+      reasonCode: typeof rawResult.reasonCode === 'string' ? rawResult.reasonCode : 'action_run_failed',
+      detail: rawResult.detail || rawResult.error || null,
+      output: rawResult.output,
+    });
+  };
+  const normalizeThrownActionErrorLocal = (error, actionId) => createActionResultLocal({
+    ok: false,
+    actionId,
+    reasonCode: 'action_run_failed',
+    detail: error instanceof Error ? error.message : String(error),
+  });
+  const defineActionContractLocal = (contract) => {
+    const normalized = normalizeActionContractLocal(contract);
+    if (!normalized.ok) {
+      return normalized;
+    }
+    aura[storageKey] = normalized.contract;
+    return {
+      ok: true,
+      reasonCode: 'action_contract_defined',
+    };
+  };
+  const exportCanonicalGameActionSchemaLocal = () => {
+    const resolved = resolveActionSchemaPayloadLocal();
+    if (!resolved.ok) {
+      return resolved;
+    }
+    return {
+      ok: true,
+      reasonCode: 'action_schema_ok',
+      payload: resolved.payload,
+    };
+  };
+  const runCanonicalGameActionLocal = async (request) => {
+    const resolved = resolveActionSchemaPayloadLocal();
+    if (!resolved.ok) {
+      return createActionResultLocal({
+        ok: false,
+        reasonCode: resolved.reasonCode || 'action_contract_unavailable',
+        detail: resolved.detail || null,
+      });
+    }
+
+    const validated = validateActionRequestLocal(request, resolved.payload.actions);
+    if (!validated.ok) {
+      return validated.result;
+    }
+
+    try {
+      const rawResult = await Promise.resolve(
+        resolved.contract.run(validated.action, {
+          aura,
+          request: validated.request,
+          schema: resolved.payload,
+        }),
+      );
+      return normalizeActionRunResultLocal(rawResult, validated.action.id);
+    } catch (error) {
+      return normalizeThrownActionErrorLocal(error, validated.action.id);
+    }
+  };
+
+  const actionNamespace = aura && typeof aura.action === 'object' ? aura.action : {};
+  actionNamespace.schemaVersion = schemaVersion;
+  if (typeof actionNamespace.define !== 'function') {
+    actionNamespace.define = (contract) => defineActionContractLocal(contract);
+  }
+  if (typeof actionNamespace.schema !== 'function') {
+    actionNamespace.schema = () => {
+      const result = exportCanonicalGameActionSchemaLocal();
+      return result.ok === true ? result.payload : result;
+    };
+  }
+  if (typeof actionNamespace.getSchema !== 'function') {
+    actionNamespace.getSchema = () => exportCanonicalGameActionSchemaLocal();
+  }
+  if (typeof actionNamespace.run !== 'function') {
+    actionNamespace.run = (request) => runCanonicalGameActionLocal(request);
+  }
+  if (typeof actionNamespace.runAction !== 'function') {
+    actionNamespace.runAction = (request) => runCanonicalGameActionLocal(request);
+  }
+  aura.action = actionNamespace;
+  return actionNamespace;
+}
+
+export function buildGameActionRuntimeBootstrapSource() {
+  return `(${installGameActionRuntimeBootstrap.toString()})(aura);`;
+}
+
+export function defineGameActionContract(aura, contract) {
+  if (!aura || typeof aura !== 'object') {
+    throw new Error('defineGameActionContract requires an aura runtime object.');
+  }
+
+  const normalized = normalizeActionContract(contract);
+  if (!normalized.ok) {
+    return normalized;
+  }
+
+  aura[ACTION_CONTRACT_STORAGE_KEY] = normalized.contract;
+  return {
+    ok: true,
+    reasonCode: 'action_contract_defined',
+  };
+}
+
+export function exportCanonicalGameActionSchema(aura) {
+  const resolved = resolveActionSchemaPayload(aura);
+  if (!resolved.ok) {
+    return resolved;
+  }
+
+  return {
+    ok: true,
+    reasonCode: 'action_schema_ok',
+    payload: resolved.payload,
+  };
+}
+
+export async function runCanonicalGameAction(aura, request) {
+  const resolved = resolveActionSchemaPayload(aura);
+  if (!resolved.ok) {
+    return createActionResult({
+      ok: false,
+      reasonCode: resolved.reasonCode || 'action_contract_unavailable',
+      detail: resolved.detail || null,
+    });
+  }
+
+  const validated = validateActionRequest(request, resolved.payload.actions);
+  if (!validated.ok) {
+    return validated.result;
+  }
+
+  const contract = resolved.contract;
+  try {
+    const rawResult = await Promise.resolve(
+      contract.run(validated.action, {
+        aura,
+        request: validated.request,
+        schema: resolved.payload,
+      }),
+    );
+    return normalizeActionRunResult(rawResult, validated.action.id);
+  } catch (error) {
+    return normalizeThrownActionError(error, validated.action.id);
+  }
+}
+
+function normalizeActionContract(contract) {
+  if (!isPlainObject(contract)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: 'action contract must be an object',
+    };
+  }
+
+  const actions = contract.actions;
+  if (!Array.isArray(actions) && typeof actions !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: 'action contract requires actions array or function',
+    };
+  }
+
+  if (typeof contract.run !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: 'action contract requires run(action, context)',
+    };
+  }
+
+  if (Array.isArray(actions)) {
+    const normalizedActions = normalizeActionDefinitions(actions);
+    if (!normalizedActions.ok) {
+      return normalizedActions;
+    }
+    return {
+      ok: true,
+      contract: Object.freeze({
+        actions: Object.freeze(normalizedActions.actions),
+        run: contract.run,
+      }),
+    };
+  }
+
+  return {
+    ok: true,
+    contract: Object.freeze({
+      actions,
+      run: contract.run,
+    }),
+  };
+}
+
+function resolveActionSchemaPayload(aura) {
+  const contract = aura && typeof aura === 'object'
+    ? aura[ACTION_CONTRACT_STORAGE_KEY]
+    : null;
+  if (!contract || typeof contract !== 'object') {
+    return {
+      ok: false,
+      reasonCode: 'action_contract_unavailable',
+      detail: 'game did not define aura.action contract',
+    };
+  }
+
+  let actionEntries;
+  try {
+    actionEntries = typeof contract.actions === 'function'
+      ? contract.actions({ aura })
+      : contract.actions;
+  } catch (error) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const normalized = normalizeActionDefinitions(actionEntries);
+  if (!normalized.ok) {
+    return normalized;
+  }
+
+  return {
+    ok: true,
+    contract,
+    payload: orderActionSchemaPayload({
+      schemaVersion: GAME_ACTION_SCHEMA_VERSION,
+      actions: normalized.actions,
+    }),
+  };
+}
+
+function normalizeActionDefinitions(actionEntries) {
+  if (!Array.isArray(actionEntries)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: 'action contract actions must resolve to an array',
+    };
+  }
+
+  const normalizedActions = [];
+  const seenIds = new Set();
+
+  for (let index = 0; index < actionEntries.length; index += 1) {
+    const entry = actionEntries[index];
+    if (!isPlainObject(entry)) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: `action at index ${index} must be an object`,
+      };
+    }
+
+    const id = typeof entry.id === 'string' ? entry.id.trim() : '';
+    if (!id) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: `action at index ${index} requires a non-empty id`,
+      };
+    }
+    if (seenIds.has(id)) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: `duplicate action id "${id}"`,
+      };
+    }
+
+    if (!isPlainObject(entry.inputSchema)) {
+      return {
+        ok: false,
+        reasonCode: 'invalid_action_contract',
+        detail: `action "${id}" requires inputSchema object`,
+      };
+    }
+
+    seenIds.add(id);
+
+    const normalizedAction = {
+      id,
+      inputSchema: sanitizeJsonValue(entry.inputSchema),
+    };
+
+    if (typeof entry.title === 'string' && entry.title.trim()) {
+      normalizedAction.title = entry.title.trim();
+    }
+    if (typeof entry.description === 'string' && entry.description.trim()) {
+      normalizedAction.description = entry.description.trim();
+    }
+
+    normalizedActions.push(orderActionDefinition(normalizedAction));
+  }
+
+  return {
+    ok: true,
+    actions: normalizedActions,
+  };
+}
+
+function validateActionRequest(request, actions) {
+  if (!isPlainObject(request)) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        detail: 'request must be an object',
+      }),
+    };
+  }
+
+  if (request.schemaVersion !== GAME_ACTION_REQUEST_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        detail: `expected ${GAME_ACTION_REQUEST_SCHEMA_VERSION}`,
+      }),
+    };
+  }
+
+  if (!isPlainObject(request.action)) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        detail: 'action must be an object',
+      }),
+    };
+  }
+
+  const actionId = typeof request.action.id === 'string' ? request.action.id.trim() : '';
+  if (!actionId) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        detail: 'action.id must be a non-empty string',
+      }),
+    };
+  }
+
+  const args = request.action.args == null ? {} : request.action.args;
+  if (!isPlainObject(args)) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        actionId,
+        detail: 'action.args must be an object',
+      }),
+    };
+  }
+
+  const knownActionIds = new Set(actions.map((action) => action.id));
+  if (!knownActionIds.has(actionId)) {
+    return {
+      ok: false,
+      result: createActionResult({
+        ok: false,
+        reasonCode: 'invalid_action_request',
+        actionId,
+        detail: `action "${actionId}" is not declared in schema`,
+      }),
+    };
+  }
+
+  const normalizedAction = {
+    id: actionId,
+    args: sanitizeJsonValue(args),
+  };
+
+  return {
+    ok: true,
+    action: normalizedAction,
+    request: {
+      schemaVersion: GAME_ACTION_REQUEST_SCHEMA_VERSION,
+      action: normalizedAction,
+    },
+  };
+}
+
+function normalizeActionRunResult(rawResult, actionId) {
+  if (rawResult === false) {
+    return createActionResult({
+      ok: false,
+      reasonCode: 'action_run_failed',
+      actionId,
+    });
+  }
+
+  if (rawResult == null || rawResult === true) {
+    return createActionResult({
+      ok: true,
+      reasonCode: 'action_run_ok',
+      actionId,
+    });
+  }
+
+  if (isPlainObject(rawResult) && typeof rawResult.ok === 'boolean') {
+    return createActionResult({
+      ok: rawResult.ok,
+      reasonCode: typeof rawResult.reasonCode === 'string' && rawResult.reasonCode
+        ? rawResult.reasonCode
+        : rawResult.ok === true
+          ? 'action_run_ok'
+          : 'action_run_failed',
+      actionId,
+      detail: typeof rawResult.detail === 'string' ? rawResult.detail : null,
+      output: Object.prototype.hasOwnProperty.call(rawResult, 'output') ? rawResult.output : undefined,
+    });
+  }
+
+  return createActionResult({
+    ok: true,
+    reasonCode: 'action_run_ok',
+    actionId,
+    output: rawResult,
+  });
+}
+
+function normalizeThrownActionError(error, actionId) {
+  if (error && typeof error === 'object' && typeof error.reasonCode === 'string' && error.reasonCode) {
+    return createActionResult({
+      ok: false,
+      reasonCode: error.reasonCode,
+      actionId,
+      detail: typeof error.detail === 'string'
+        ? error.detail
+        : typeof error.message === 'string'
+          ? error.message
+          : null,
+      output: Object.prototype.hasOwnProperty.call(error, 'output') ? error.output : undefined,
+    });
+  }
+
+  return createActionResult({
+    ok: false,
+    reasonCode: 'action_run_failed',
+    actionId,
+    detail: error instanceof Error ? error.message : String(error),
+  });
+}
+
+function createActionResult({ ok, reasonCode, actionId = null, detail = null, output = undefined }) {
+  const payload = {
+    schemaVersion: GAME_ACTION_RESULT_SCHEMA_VERSION,
+    ok: ok === true,
+    reasonCode: typeof reasonCode === 'string' && reasonCode
+      ? reasonCode
+      : ok === true
+        ? 'action_run_ok'
+        : 'action_run_failed',
+  };
+
+  if (typeof actionId === 'string' && actionId) {
+    payload.actionId = actionId;
+  }
+  if (typeof detail === 'string' && detail.trim()) {
+    payload.detail = detail.trim();
+  }
+  if (output !== undefined) {
+    payload.output = sanitizeJsonValue(output);
+  }
+
+  return orderActionResultPayload(payload);
+}
+
+function orderActionSchemaPayload(payload) {
+  const ordered = {};
+  for (const key of ACTION_SCHEMA_KEY_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) {
+      ordered[key] = payload[key];
+    }
+  }
+  return ordered;
+}
+
+function orderActionDefinition(action) {
+  const ordered = {};
+  for (const key of ACTION_DEFINITION_KEY_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(action, key)) {
+      ordered[key] = action[key];
+    }
+  }
+  return ordered;
+}
+
+function orderActionResultPayload(payload) {
+  const ordered = {};
+  for (const key of ACTION_RESULT_KEY_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) {
+      ordered[key] = payload[key];
+    }
+  }
+  return ordered;
+}
+
+function sanitizeJsonValue(value) {
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? Number(value) : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeJsonValue(entry));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    const keys = Object.keys(value).sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+      const next = sanitizeJsonValue(value[key]);
+      if (next === undefined) continue;
+      out[key] = next;
+    }
+    return out;
+  }
+  return null;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}