@smthrs/gateway 0.33.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@smthrs/gateway",
+  "version": "0.33.0",
+  "description": "Stable Smithers Gateway RPC contracts, auth scopes, and deployment metadata",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./rpc": {
+      "types": "./src/rpc/index.d.ts",
+      "import": "./src/rpc/index.js",
+      "default": "./src/rpc/index.js"
+    },
+    "./auth/scopes": {
+      "types": "./src/auth/scopes.d.ts",
+      "import": "./src/auth/scopes.js",
+      "default": "./src/auth/scopes.js"
+    },
+    "./api": {
+      "types": "./src/api/index.d.ts",
+      "import": "./src/api/index.js",
+      "default": "./src/api/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "openapi.yaml"
+  ],
+  "dependencies": {
+    "@smthrs/protocol": "0.33.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "generate:openapi": "bun run scripts/generate-openapi.ts",
+    "check:openapi": "bun run scripts/generate-openapi.ts --check",
+    "build": "bun run check:openapi && node ../../scripts/clean-dts.mjs src && tsup --dts-only",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests"
+  }
+}

package/src/README.md

@@ -0,0 +1,39 @@
+# @smthrs/gateway — src
+
+The stable Gateway runtime contract package: pure data plus tiny pure
+functions. `@smthrs/protocol/gateway-rpc` owns the canonical
+wire types; this package owns the runtime RPC catalog and JSON schemas, auth
+scopes, compatibility aliases, and API row serializers. Its only runtime
+dependency is `@smthrs/protocol`, and it deliberately has no
+`effect` dependency.
+
+Layout:
+
+- `rpc/index.js` — the frozen v1 runtime catalog: JSON schemas,
+  `GATEWAY_RPC_DEFINITIONS`, the error table, legacy method aliases, and the
+  required-scope lookup (including HTTP-only routes).
+- `rpc/gatewayRpcTypes.ts` — types for the gateway-owned runtime catalog plus
+  compatibility re-exports of the protocol-owned wire types.
+- `auth/scopes.js` — the scope catalog, per-family scope hierarchy, and
+  `hasGatewayScope` enforcement (including legacy `read`/`execute`/`approve`/
+  `admin` grants and per-method name/prefix grants).
+- `api/` — pure DB-row → wire-row serializers for the collection endpoints
+  (see `api/README.md`).
+- `index.js` — re-exports all three; `package.json` also exposes each subpath
+  (`./rpc`, `./auth/scopes`, `./api`) directly.
+
+`@smthrs/gateway/rpc` remains a supported compatibility surface:
+it re-exports the protocol wire types alongside the gateway-owned runtime
+catalog values. The server consumes that runtime catalog. Client code uses
+`@smthrs/gateway-client`, and `gateway-react` consumes
+`gateway-client` instead of importing this package directly.
+
+Gotchas:
+
+- `openapi.yaml` at the package root is generated from
+  `GATEWAY_RPC_DEFINITIONS` by `scripts/generate-openapi.ts` and gated by
+  `check:openapi` — any change to serialized schema content requires
+  regenerating it.
+- Every RPC here is maturity `stable`; adding or renaming a method or scope is
+  a contract change pinned by `tests/rpc-contract.test.ts` (exact method list
+  and per-method required scopes).

package/src/api/README.md

@@ -0,0 +1,23 @@
+# api/
+
+Pure serializers that turn raw DB rows (snake_case keys, driver-typed values)
+into the stable camelCase wire rows served by the Gateway HTTP/Electric
+collection endpoints. `apiCollectionNames.ts` lists the served collection
+names.
+
+How it fits together:
+
+- `normalizeApiRow.ts` (internal — not re-exported from `index.ts`) does the
+  shared work: snake→camel keys, and bigint→number (or a decimal string when
+  the value is not a safe integer).
+- Each `serializeXRow.ts` then pins the exact wire shape for one collection —
+  picking fields, defaulting missing ones, and parsing embedded JSON columns
+  (e.g. approval `request_json`, run-event `payload_json`).
+- One `serializeXRow` exists per collection even when it is a bare
+  `normalizeApiRow` pass-through (account/prompt/workflow): a deliberate
+  family, so every collection has a named seam to pin its shape later.
+
+Consumers: `packages/server/src/gateway.js` and `packages/gateway-client`
+(whose `mapSmithersElectricRow` plus the electric-row-parity and
+local-import-boundary tests assert parity), so the output shapes are contract,
+not implementation detail.

package/src/api/apiCollectionNames.js

@@ -0,0 +1,10 @@
+export const apiCollectionNames = /** @type {const} */ ([
+  "runs",
+  "run_events",
+  "nodes",
+  "node_outputs",
+  "approvals",
+  "crons",
+  "tickets",
+  "docs",
+]);

package/src/api/index.d.ts

@@ -0,0 +1,126 @@
+import { GatewayComparisonScoreRow as GatewayComparisonScoreRow$1, GatewayScoreDetail as GatewayScoreDetail$1 } from '@smthrs/protocol/gateway-rpc';
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeAccountRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+declare const apiCollectionNames: readonly ["runs", "run_events", "nodes", "node_outputs", "approvals", "crons", "tickets", "docs"];
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {{
+ *   runId: unknown,
+ *   workflowKey?: unknown,
+ *   nodeId: unknown,
+ *   iteration: unknown,
+ *   requestTitle: unknown,
+ *   requestSummary: unknown,
+ *   requestedAtMs: unknown,
+ *   approvalMode: unknown,
+ *   options: unknown,
+ *   allowedScopes: unknown,
+ *   allowedUsers: unknown,
+ *   autoApprove: unknown,
+ * }}
+ */
+declare function serializeApprovalRow(row: Record<string, unknown>): {
+    runId: unknown;
+    workflowKey?: unknown;
+    nodeId: unknown;
+    iteration: unknown;
+    requestTitle: unknown;
+    requestSummary: unknown;
+    requestedAtMs: unknown;
+    approvalMode: unknown;
+    options: unknown;
+    allowedScopes: unknown;
+    allowedUsers: unknown;
+    autoApprove: unknown;
+};
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeCronRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeDocRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeMemoryFactRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializePromptRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeRunEventRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeRunRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/** @typedef {import("../rpc/gatewayRpcTypes.ts").GatewayComparisonScoreRow} GatewayComparisonScoreRow */
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {GatewayComparisonScoreRow}
+ */
+declare function serializeComparisonScoreRow(row: Record<string, unknown>): GatewayComparisonScoreRow;
+type GatewayComparisonScoreRow = GatewayComparisonScoreRow$1;
+
+/** @typedef {import("../rpc/gatewayRpcTypes.ts").GatewayScoreDetail} GatewayScoreDetail */
+/**
+ * Serialize an already-decoded score detail row. JSON parsing deliberately
+ * stays in the server so malformed persistence can fail explicitly instead of
+ * being hidden by a wire serializer.
+ * @param {Record<string, unknown>} row
+ * @returns {GatewayScoreDetail}
+ */
+declare function serializeScoreDetailRow(row: Record<string, unknown>): GatewayScoreDetail;
+type GatewayScoreDetail = GatewayScoreDetail$1;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeScoreRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeTicketRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+declare function serializeWorkflowRow<Row extends Record<string, unknown>>(row: Row): Row;
+
+export { apiCollectionNames, serializeAccountRow, serializeApprovalRow, serializeComparisonScoreRow, serializeCronRow, serializeDocRow, serializeMemoryFactRow, serializePromptRow, serializeRunEventRow, serializeRunRow, serializeScoreDetailRow, serializeScoreRow, serializeTicketRow, serializeWorkflowRow };

package/src/api/index.js

@@ -0,0 +1,14 @@
+export { serializeAccountRow } from "./serializeAccountRow.js";
+export { apiCollectionNames } from "./apiCollectionNames.js";
+export { serializeApprovalRow } from "./serializeApprovalRow.js";
+export { serializeCronRow } from "./serializeCronRow.js";
+export { serializeDocRow } from "./serializeDocRow.js";
+export { serializeMemoryFactRow } from "./serializeMemoryFactRow.js";
+export { serializePromptRow } from "./serializePromptRow.js";
+export { serializeRunEventRow } from "./serializeRunEventRow.js";
+export { serializeRunRow } from "./serializeRunRow.js";
+export { serializeComparisonScoreRow } from "./serializeComparisonScoreRow.js";
+export { serializeScoreDetailRow } from "./serializeScoreDetailRow.js";
+export { serializeScoreRow } from "./serializeScoreRow.js";
+export { serializeTicketRow } from "./serializeTicketRow.js";
+export { serializeWorkflowRow } from "./serializeWorkflowRow.js";

package/src/api/normalizeApiRow.js

@@ -0,0 +1,36 @@
+const SNAKE_SEGMENT = /_([a-z0-9])/g;
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function toCamelKey(key) {
+  return key.replace(SNAKE_SEGMENT, (_, /** @type {string} */ char) => char.toUpperCase());
+}
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function normalizeValue(value) {
+  if (typeof value === "bigint") {
+    const number = Number(value);
+    return Number.isSafeInteger(number) ? number : value.toString();
+  }
+  return value;
+}
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeApiRow(row) {
+  /** @type {Record<string, unknown>} */
+  const normalized = {};
+  for (const [key, value] of Object.entries(row)) {
+    const camelKey = toCamelKey(key);
+    normalized[camelKey] = normalizeValue(value);
+  }
+  return normalized;
+}

package/src/api/serializeAccountRow.js

@@ -0,0 +1,10 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeAccountRow(row) {
+  return /** @type {Row} */ (normalizeApiRow(row));
+}

package/src/api/serializeApprovalRow.js

@@ -0,0 +1,53 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function parseJson(value) {
+  if (!value || typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? /** @type {Record<string, unknown>} */ (parsed)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {{
+ *   runId: unknown,
+ *   workflowKey?: unknown,
+ *   nodeId: unknown,
+ *   iteration: unknown,
+ *   requestTitle: unknown,
+ *   requestSummary: unknown,
+ *   requestedAtMs: unknown,
+ *   approvalMode: unknown,
+ *   options: unknown,
+ *   allowedScopes: unknown,
+ *   allowedUsers: unknown,
+ *   autoApprove: unknown,
+ * }}
+ */
+export function serializeApprovalRow(row) {
+  const normalized = normalizeApiRow(row);
+  const request = parseJson(normalized.requestJson);
+  return {
+    runId: normalized.runId,
+    ...(normalized.workflowKey === undefined ? {} : { workflowKey: normalized.workflowKey }),
+    nodeId: normalized.nodeId,
+    iteration: normalized.iteration ?? 0,
+    requestTitle: normalized.requestTitle ?? request.title,
+    requestSummary: normalized.requestSummary ?? request.summary,
+    requestedAtMs: normalized.requestedAtMs ?? null,
+    approvalMode: normalized.approvalMode ?? request.mode,
+    options: normalized.options ?? request.options,
+    allowedScopes: normalized.allowedScopes ?? request.allowedScopes,
+    allowedUsers: normalized.allowedUsers ?? request.allowedUsers,
+    autoApprove: normalized.autoApprove ?? request.autoApprove,
+  };
+}

package/src/api/serializeComparisonScoreRow.js

@@ -0,0 +1,18 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+import { serializeScoreRow } from "./serializeScoreRow.js";
+
+/** @typedef {import("../rpc/gatewayRpcTypes.ts").GatewayComparisonScoreRow} GatewayComparisonScoreRow */
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {GatewayComparisonScoreRow}
+ */
+export function serializeComparisonScoreRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {GatewayComparisonScoreRow} */ (
+    /** @type {unknown} */ ({
+      scoreId: normalized.scoreId ?? normalized.id,
+      ...serializeScoreRow(row),
+    })
+  );
+}

package/src/api/serializeCronRow.js

@@ -0,0 +1,30 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeCronRow(row) {
+  const normalized = normalizeApiRow(row);
+  const workflowPath = typeof normalized.workflowPath === "string" ? normalized.workflowPath : "";
+  const workflow =
+    typeof normalized.workflow === "string"
+      ? normalized.workflow
+      : workflowPath.startsWith("gateway:")
+        ? workflowPath.slice("gateway:".length)
+        : workflowPath;
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      cronId: normalized.cronId,
+      pattern: normalized.pattern,
+      workflowPath,
+      workflow,
+      enabled: normalized.enabled === true || normalized.enabled === 1,
+      createdAtMs: normalized.createdAtMs,
+      lastRunAtMs: normalized.lastRunAtMs ?? null,
+      nextRunAtMs: normalized.nextRunAtMs ?? null,
+      errorJson: normalized.errorJson ?? null,
+    })
+  );
+}

package/src/api/serializeDocRow.js

@@ -0,0 +1,20 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeDocRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      path: normalized.path,
+      kind: normalized.kind,
+      content: normalized.content,
+      contentHash: normalized.contentHash,
+      updatedAtMs: normalized.updatedAtMs,
+      deletedAtMs: normalized.deletedAtMs ?? null,
+    })
+  );
+}

package/src/api/serializeMemoryFactRow.js

@@ -0,0 +1,21 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeMemoryFactRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      namespace: normalized.namespace,
+      key: normalized.key,
+      valueJson: normalized.valueJson,
+      schemaSig: normalized.schemaSig ?? null,
+      createdAtMs: normalized.createdAtMs,
+      updatedAtMs: normalized.updatedAtMs,
+      ttlMs: normalized.ttlMs ?? null,
+    })
+  );
+}

package/src/api/serializePromptRow.js

@@ -0,0 +1,10 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializePromptRow(row) {
+  return /** @type {Row} */ (normalizeApiRow(row));
+}

package/src/api/serializeRunEventRow.js

@@ -0,0 +1,28 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeRunEventRow(row) {
+  const normalized = normalizeApiRow(row);
+  const payloadJson = normalized.payloadJson;
+  let payload = normalized.payload;
+  if (payload === undefined && typeof payloadJson === "string") {
+    try {
+      payload = JSON.parse(payloadJson);
+    } catch {
+      payload = payloadJson;
+    }
+  }
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      runId: normalized.runId,
+      seq: normalized.seq,
+      event: normalized.event ?? normalized.type,
+      payload,
+      ...(normalized.timestampMs === undefined ? {} : { timestampMs: normalized.timestampMs }),
+    })
+  );
+}

package/src/api/serializeRunRow.js

@@ -0,0 +1,61 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/** @param {unknown} value */
+function validStartedBy(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const source = /** @type {Record<string, unknown>} */ (value);
+  const known = ["harness", "sessionId", "prompt", "detected"];
+  if (Object.keys(source).some((key) => !known.includes(key))) return undefined;
+  if (["harness", "sessionId", "prompt"].some((key) => source[key] !== undefined && typeof source[key] !== "string"))
+    return undefined;
+  if (source.detected !== undefined && source.detected !== true) return undefined;
+  const harness = typeof source.harness === "string" ? source.harness : undefined;
+  const sessionId = typeof source.sessionId === "string" ? source.sessionId : undefined;
+  const prompt = typeof source.prompt === "string" ? source.prompt : undefined;
+  if (!harness && !sessionId && prompt === undefined) return undefined;
+  if (source.detected === true && !harness && !sessionId) return undefined;
+  return {
+    ...(harness ? { harness } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    ...(prompt !== undefined ? { prompt } : {}),
+    ...(source.detected === true ? { detected: true } : {}),
+  };
+}
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeRunRow(row) {
+  const normalized = normalizeApiRow(row);
+  let config;
+  if (typeof normalized.configJson === "string") {
+    try {
+      config = /** @type {{ gatewayWorkflowKey?: unknown; gatewaySystem?: unknown; startedBy?: unknown }} */ (
+        JSON.parse(normalized.configJson)
+      );
+    } catch {
+      // Malformed run config stays opaque on the wire.
+    }
+  }
+  if (normalized.workflowKey === undefined && typeof config?.gatewayWorkflowKey === "string") {
+    normalized.workflowKey = config.gatewayWorkflowKey;
+  }
+  const startedBy = validStartedBy(config?.startedBy);
+  if (startedBy) normalized.startedBy = startedBy;
+  // Visibility is fail-closed. New gateway runs persist a boolean stamp;
+  // historical or malformed rows are internal until an explicit debug list
+  // opts into them. Preserve an already-projected trusted server response
+  // (launch/get/list) which carries no configJson.
+  normalized.system =
+    typeof config?.gatewaySystem === "boolean"
+      ? config.gatewaySystem
+      : typeof normalized.system === "boolean"
+        ? normalized.system
+        : true;
+  if (normalized.workflowKey === undefined && typeof normalized.workflowName === "string") {
+    normalized.workflowKey = normalized.workflowName;
+  }
+  return /** @type {Row} */ (normalized);
+}

package/src/api/serializeScoreDetailRow.js

@@ -0,0 +1,25 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+import { serializeComparisonScoreRow } from "./serializeComparisonScoreRow.js";
+
+/** @typedef {import("../rpc/gatewayRpcTypes.ts").GatewayScoreDetail} GatewayScoreDetail */
+
+/**
+ * Serialize an already-decoded score detail row. JSON parsing deliberately
+ * stays in the server so malformed persistence can fail explicitly instead of
+ * being hidden by a wire serializer.
+ * @param {Record<string, unknown>} row
+ * @returns {GatewayScoreDetail}
+ */
+export function serializeScoreDetailRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {GatewayScoreDetail} */ (
+    /** @type {unknown} */ ({
+      ...serializeComparisonScoreRow(row),
+      meta: normalized.meta ?? null,
+      input: normalized.input ?? null,
+      output: normalized.output ?? null,
+      groundTruth: normalized.groundTruth ?? null,
+      context: normalized.context ?? null,
+    })
+  );
+}

package/src/api/serializeScoreRow.js

@@ -0,0 +1,26 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeScoreRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      runId: normalized.runId,
+      nodeId: normalized.nodeId,
+      iteration: normalized.iteration ?? 0,
+      attempt: normalized.attempt ?? 0,
+      scorerId: normalized.scorerId,
+      scorerName: normalized.scorerName,
+      source: normalized.source,
+      score: normalized.score,
+      reason: normalized.reason ?? null,
+      scoredAtMs: normalized.scoredAtMs,
+      latencyMs: normalized.latencyMs ?? null,
+      durationMs: normalized.durationMs ?? null,
+    })
+  );
+}

package/src/api/serializeTicketRow.js

@@ -0,0 +1,20 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeTicketRow(row) {
+  const normalized = normalizeApiRow(row);
+  return /** @type {Row} */ (
+    /** @type {unknown} */ ({
+      path: normalized.path,
+      kind: normalized.kind,
+      content: normalized.content,
+      contentHash: normalized.contentHash,
+      status: normalized.status ?? null,
+      updatedAtMs: normalized.updatedAtMs,
+    })
+  );
+}

package/src/api/serializeWorkflowRow.js

@@ -0,0 +1,10 @@
+import { normalizeApiRow } from "./normalizeApiRow.js";
+
+/**
+ * @template {Record<string, unknown>} Row
+ * @param {Row} row
+ * @returns {Row}
+ */
+export function serializeWorkflowRow(row) {
+  return /** @type {Row} */ (normalizeApiRow(row));
+}

package/src/auth/scopes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @param {string} scope
+ * @returns {scope is GatewayScope}
+ */
+declare function isGatewayScope(scope: string): scope is GatewayScope;
+/**
+ * @param {readonly string[]} grantedScopes
+ * @param {GatewayScope} requiredScope
+ * @param {string} [methodName]
+ * @returns {boolean}
+ */
+declare function hasGatewayScope(grantedScopes: readonly string[], requiredScope: GatewayScope, methodName?: string): boolean;
+/** @typedef {(typeof GATEWAY_SCOPE_VALUES)[number]} GatewayScope */
+declare const GATEWAY_SCOPE_VALUES: readonly ["run:read", "run:write", "run:admin", "approval:submit", "signal:submit", "cron:read", "cron:write", "account:read", "memory:read", "prompt:read", "score:read", "ticket:read", "ticket:write", "observability:read"];
+/** @type {Record<GatewayScope, string>} */
+declare const GATEWAY_SCOPE_DESCRIPTIONS: Record<GatewayScope, string>;
+type GatewayScope = (typeof GATEWAY_SCOPE_VALUES)[number];
+
+export { GATEWAY_SCOPE_DESCRIPTIONS, GATEWAY_SCOPE_VALUES, type GatewayScope, hasGatewayScope, isGatewayScope };