@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/src/routes/event-triggers.ts

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import type { Cursor, TenantId, TriggerId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type {
+  EventTriggerRecord,
+  RegisterEventTriggerInput,
+  TriggerRegistryBinding,
+  UpdateEventTriggerInput,
+} from '../trigger-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Event triggers — fire a flow run when a matching event arrives on
+ * the framework event bus.
+ *
+ * Seven routes, mirroring the schedules surface. This surface registers
+ * triggers; it does not publish events.
+ */
+export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- POST / (register) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const flowId = requireString(body, 'flowId');
+    const flowVersion = requireString(body, 'flowVersion');
+    const eventKind = requireString(body.config, 'config.eventKind');
+    if (flowId.kind === 'err') return bad(c, requestId, flowId.message);
+    if (flowVersion.kind === 'err') return bad(c, requestId, flowVersion.message);
+    if (eventKind.kind === 'err') return bad(c, requestId, eventKind.message);
+
+    const rawConfig = (body.config ?? {}) as Record<string, unknown>;
+    const registerInput: RegisterEventTriggerInput = {
+      kind: 'event',
+      tenantId,
+      flowId: flowId.value,
+      flowVersion: flowVersion.value,
+      config: {
+        eventKind: eventKind.value,
+        ...('input' in rawConfig && { input: rawConfig.input }),
+      },
+      ...(typeof body.label === 'string' && body.label.length > 0 && { label: body.label }),
+    };
+
+    const result = await binding.register(registerInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError({ code: result.error.code, message: result.error.message }, requestId),
+      );
+    }
+    c.status(201);
+    return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
+  });
+
+  // ---------- GET / (list) ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+    const cursorRaw = c.req.query('cursor');
+    const statusRaw = c.req.query('status');
+
+    let statusFilter: 'active' | 'paused' | undefined;
+    if (statusRaw === 'active' || statusRaw === 'paused') statusFilter = statusRaw;
+
+    const page = await binding.list({
+      tenantId,
+      kind: 'event',
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(statusFilter !== undefined && { status: statusFilter }),
+    });
+    return c.json({
+      data: page.data.map((row) => serializeEventTrigger(row as EventTriggerRecord)),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:triggerId (get) ----------
+  r.get('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const rec = await binding.get({ tenantId, triggerId });
+    if (rec === null || rec.kind !== 'event') return notFound(c, requestId, triggerId);
+    return c.json(serializeEventTrigger(rec));
+  });
+
+  // ---------- PATCH /:triggerId (update) ----------
+  r.patch('/:triggerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+
+    const parsed = await parseJsonObject(c, requestId);
+    if (parsed.kind === 'err') return parsed.response;
+    const body = parsed.value;
+
+    const patchConfig = body.config as Record<string, unknown> | undefined;
+    const cfg: Partial<{ eventKind: string; input: unknown }> = {};
+    if (patchConfig !== undefined) {
+      if (typeof patchConfig.eventKind === 'string') cfg.eventKind = patchConfig.eventKind;
+      if ('input' in patchConfig) cfg.input = patchConfig.input;
+    }
+
+    const updateInput: UpdateEventTriggerInput = {
+      kind: 'event',
+      tenantId,
+      triggerId,
+      ...(Object.keys(cfg).length > 0 && { config: cfg }),
+      ...('label' in body && { label: body.label === null ? null : (body.label as string) }),
+      ...(typeof body.flowVersion === 'string' && { flowVersion: body.flowVersion }),
+    };
+
+    const result = await binding.update(updateInput);
+    if (result.kind === 'err') {
+      c.status(statusFor(result.error.code) as never);
+      return c.json(
+        toWireError(
+          {
+            code: result.error.code,
+            message: result.error.message,
+            triggerId: triggerId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/pause ----------
+  r.post('/:triggerId/pause', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.pause({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/resume ----------
+  r.post('/:triggerId/resume', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const result = await binding.resume({ tenantId, triggerId });
+    if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
+    return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
+  });
+
+  // ---------- POST /:triggerId/unregister (soft delete) ----------
+  r.post('/:triggerId/unregister', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const triggerId = c.req.param('triggerId') as TriggerId;
+    const outcome = await binding.unregister({ tenantId, triggerId });
+    return c.json({
+      eventTriggerId: triggerId as unknown as string,
+      unregistered: outcome.unregistered,
+    });
+  });
+
+  return r;
+}
+
+function serializeEventTrigger(r: EventTriggerRecord): Record<string, unknown> {
+  return {
+    eventTriggerId: r.triggerId as unknown as string,
+    triggerId: r.triggerId as unknown as string,
+    flowId: r.flowId,
+    flowVersion: r.flowVersion,
+    eventKind: r.config.eventKind,
+    ...(r.config.input !== undefined && { input: r.config.input }),
+    label: r.label,
+    status: r.status,
+    lastFiredAt: r.lastFiredAt,
+    createdAt: r.createdAt,
+    updatedAt: r.updatedAt,
+  };
+}
+
+type ParseOk<T> = { readonly kind: 'ok'; readonly value: T };
+type ParseErr = { readonly kind: 'err'; readonly response: Response };
+
+async function parseJsonObject(
+  c: Context<AppEnv>,
+  requestId: string,
+): Promise<ParseOk<Record<string, unknown>> | ParseErr> {
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      ),
+    };
+  }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    c.status(statusFor('bad-input') as never);
+    return {
+      kind: 'err',
+      response: c.json(
+        toWireError(
+          { code: 'bad-input', message: 'Request body must be a JSON object' },
+          requestId,
+        ),
+      ),
+    };
+  }
+  return { kind: 'ok', value: body as Record<string, unknown> };
+}
+
+function requireString(
+  obj: unknown,
+  path: string,
+):
+  | { readonly kind: 'ok'; readonly value: string }
+  | { readonly kind: 'err'; readonly message: string } {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== 'object') {
+      return { kind: 'err', message: `\`${path}\` is required` };
+    }
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  if (typeof cur !== 'string' || cur.length === 0) {
+    return { kind: 'err', message: `\`${path}\` is required` };
+  }
+  return { kind: 'ok', value: cur };
+}
+
+function bad(c: Context<AppEnv>, requestId: string, message: string): Response {
+  c.status(statusFor('bad-input') as never);
+  return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+
+function notFound(c: Context<AppEnv>, requestId: string, triggerId: TriggerId): Response {
+  c.status(statusFor('trigger-not-found') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'trigger-not-found',
+        message: `No trigger with id "${triggerId as unknown as string}"`,
+        triggerId: triggerId as unknown as string,
+      },
+      requestId,
+    ),
+  );
+}
+
+function lifecycleError(
+  c: Context<AppEnv>,
+  requestId: string,
+  error: { readonly code: string; readonly message: string },
+  triggerId: TriggerId,
+): Response {
+  c.status(statusFor(error.code) as never);
+  return c.json(
+    toWireError(
+      { code: error.code, message: error.message, triggerId: triggerId as unknown as string },
+      requestId,
+    ),
+  );
+}

package/src/routes/flows.ts

@@ -0,0 +1,423 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import { type Principal, ref, tuplesForCreate } from '@kindgi/authz';
+import { type Flow, type FlowError, loadFlow } from '@kindgi/flow';
+import type { Cursor, FlowId, ProjectId, TenantId, UserId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+import { parseScopeParams } from './scope-params.js';
+
+/**
+ * Flows resource routes.
+ *
+ * Registry storage is caller-plugged via `FlowRegistryBinding`,
+ * mirroring `AgentRegistryBinding` 1:1. The API package does not own
+ * persistence — the binding implementation supplies the store (tests
+ * wrap an in-memory `Map`-backed adapter).
+ *
+ * Publish is data-as-code: the body is a full `Flow` definition
+ * (`@kindgi/specs/flow.schema.json`). Validation runs through
+ * `@kindgi/flow.loadFlow(...)` so a flow published through the
+ * API is byte-identical to one constructed in-process.
+ *
+ * Run initiation stays at `POST /v1/runs` (one primitive,
+ * discriminated subject). No
+ * `/v1/flows/:flowId/run` route is added here.
+ */
+export function flowsRouter(binding: FlowRegistryBinding, authorizer?: Authorizer): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // Authorization — mirrors agents 1:1. Check the resource directly;
+  // permissions cascade from the parent project because publish writes
+  // the parent tuple in the same transaction.
+  if (authorizer !== undefined) {
+    r.use('/', async (c, next) => {
+      if (c.req.method !== 'POST') return next();
+      const tenantId = c.get('tenantId') as TenantId;
+      const mw = authorizer.authorize('admin', async () => {
+        try {
+          const body = await c.req.json();
+          const pid =
+            body !== null && typeof body === 'object'
+              ? (body as Record<string, unknown>).projectId
+              : undefined;
+          if (typeof pid === 'string' && pid.length > 0) return ref('project', pid);
+        } catch {
+          // POST handler validates + returns 400
+        }
+        return ref('tenant', tenantId as unknown as string);
+      });
+      return mw(c, next);
+    });
+    r.use('/', async (c, next) => {
+      if (c.req.method !== 'GET') return next();
+      // A project filter needs read on that project. Parse it as the
+      // handler does (`?scopeKind=project&scopeId=`).
+      const s = parseScopeParams((n) => c.req.query(n), {
+        tenantId: c.get('tenantId') as TenantId,
+      });
+      if (s.kind !== 'ok' || s.scope?.kind !== 'project') return next();
+      const scopeProjectId = s.scope.projectId as unknown as string;
+      const mw = authorizer.authorize('read', () => ref('project', scopeProjectId));
+      return mw(c, next);
+    });
+    r.use('/:flowId/*', async (c, next) => {
+      const action = c.req.method === 'GET' ? 'read' : 'admin';
+      const flowId = c.req.param('flowId') ?? '';
+      const mw = authorizer.authorize(action, () => ref('flow', flowId));
+      return mw(c, next);
+    });
+    r.use('/:flowId', async (c, next) => {
+      if (c.req.method !== 'GET') return next();
+      const flowId = c.req.param('flowId') ?? '';
+      const mw = authorizer.authorize('read', () => ref('flow', flowId));
+      return mw(c, next);
+    });
+  }
+
+  // ---------- GET / (list, cursor-paginated) ----------
+  r.get('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+
+    const cursorRaw = c.req.query('cursor');
+    const nameRaw = c.req.query('name');
+
+    const scopeParsed = parseScopeParams(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
+    const page = await binding.list({
+      tenantId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(nameRaw !== undefined && nameRaw.length > 0 && { nameFilter: nameRaw }),
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
+      ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+    });
+    return c.json({
+      data: page.data.map(serializeGraph),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:flowId (latest version) ----------
+  r.get('/:flowId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const flowId = c.req.param('flowId') as FlowId;
+
+    const flow = await binding.get({ tenantId, flowId });
+    if (flow === null) {
+      // 410 gone (head exists, no active version) vs 404 not-found
+      // (never registered).
+      const exists = await binding.headExists({ tenantId, flowId });
+      if (exists) {
+        c.status(statusFor('flow-gone') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'flow-gone',
+              message: `Flow "${flowId as unknown as string}" has no active versions; reinstate a tombstoned version or publish a new one`,
+              flowId: flowId as unknown as string,
+            },
+            requestId,
+          ),
+        );
+      }
+      c.status(statusFor('flow-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-not-found',
+            message: `No flow registered with id "${flowId as unknown as string}"`,
+            flowId: flowId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeGraph(flow));
+  });
+
+  // ---------- GET /:flowId/versions (list versions) ----------
+  r.get('/:flowId/versions', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const flowId = c.req.param('flowId') as FlowId;
+    const limit = clampLimit(c.req.query('limit'));
+    const cursorRaw = c.req.query('cursor');
+
+    // Confirm the id exists at all — an empty versions list from the
+    // binding is ambiguous (no versions vs. unknown id), so we do a
+    // preliminary `get` to flip an unknown id to a `404`.
+    const latest = await binding.get({ tenantId, flowId });
+    if (latest === null) {
+      c.status(statusFor('flow-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-not-found',
+            message: `No flow registered with id "${flowId as unknown as string}"`,
+            flowId: flowId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+
+    const page = await binding.listVersions({
+      tenantId,
+      flowId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+    });
+    return c.json({
+      data: page.data.map(serializeGraph),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:flowId/versions/:version ----------
+  r.get('/:flowId/versions/:version', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const flowId = c.req.param('flowId') as FlowId;
+    const version = c.req.param('version');
+
+    const flow = await binding.getVersion({ tenantId, flowId, version });
+    if (flow === null) {
+      c.status(statusFor('flow-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-not-found',
+            message: `No flow "${flowId as unknown as string}" at version "${version}"`,
+            flowId: flowId as unknown as string,
+            version: version,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeGraph(flow));
+  });
+
+  // ---------- POST / (publish) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      );
+    }
+    if (body === null || typeof body !== 'object') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be an object' }, requestId),
+      );
+    }
+
+    // `projectId` is REQUIRED on the POST body.
+    // Missing / empty / non-string → 400 bad-input. Absent from the
+    // flow-shape validator on purpose — the caller controls what
+    // project the flow lands in; the flow definition itself is
+    // project-agnostic.
+    const bodyObj = body as Record<string, unknown>;
+    const projectIdRaw = bodyObj.projectId;
+    if (typeof projectIdRaw !== 'string' || projectIdRaw.length === 0) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: '`projectId` is required' }, requestId),
+      );
+    }
+    const projectId = projectIdRaw as ProjectId;
+
+    // Validate via loadFlow — same rules as the runtime loader, so a
+    // flow published through the API is byte-identical to one
+    // constructed in-process. `loadFlow` returns a Result rather than
+    // throwing. `projectId` is stripped from the wire body before
+    // validation — the flow definition itself is project-agnostic
+    // (loadFlow rejects unknown top-level keys).
+    const { projectId: _pid, ...bodyWithoutProjectId } = bodyObj;
+    const loaded = loadFlow(bodyWithoutProjectId);
+    if (loaded.kind === 'err') {
+      c.status(statusFor('validation-failed') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'validation-failed',
+            message: loaded.error.message,
+            issues: toIssues(loaded.error) as unknown as Record<string, unknown>[],
+          },
+          requestId,
+        ),
+      );
+    }
+
+    const principal = c.get('principal') as Principal | undefined;
+    const creatorUserId =
+      principal?.actor.kind === 'user' ? (principal.actor.id as UserId) : undefined;
+    const outcome = await binding.publish({
+      tenantId,
+      projectId,
+      flow: loaded.value,
+      enqueueTuples: (flowId) =>
+        tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId }, creatorUserId),
+    });
+    if (outcome.kind === 'already-registered') {
+      c.status(statusFor('flow-already-registered') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-already-registered',
+            message: `Flow "${outcome.flowId as unknown as string}" version "${outcome.version}" is already registered`,
+            flowId: outcome.flowId as unknown as string,
+            version: outcome.version,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'project-not-found') {
+      // Caller supplied a `projectId` that does not resolve within
+      // this tenant. Distinct signal from `already-registered` so the
+      // client can prompt for a valid project rather than assume the
+      // version was already used. Answered as `400 bad-input`; the
+      // caller learns from the message which field was invalid.
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`projectId\` "${outcome.projectId as unknown as string}" does not resolve to a project in this tenant`,
+          },
+          requestId,
+        ),
+      );
+    }
+    c.status(201);
+    return c.json({
+      flowId: outcome.flowId as unknown as string,
+      version: outcome.version,
+    });
+  });
+
+  // ---------- POST /:flowId/versions/:version/unregister ----------
+  r.post('/:flowId/versions/:version/unregister', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const flowId = c.req.param('flowId') as FlowId;
+    const version = c.req.param('version');
+
+    const outcome = await binding.unregister({ tenantId, flowId, version });
+    if (!outcome.unregistered) {
+      c.status(statusFor('flow-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-not-found',
+            message: `No flow "${flowId as unknown as string}" at version "${version}" to unregister`,
+            flowId: flowId as unknown as string,
+            version: version,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json({
+      flowId: flowId as unknown as string,
+      version: version,
+      unregistered: true,
+    });
+  });
+
+  // ---------- POST /:flowId/versions/:version/reinstate ----------
+  r.post('/:flowId/versions/:version/reinstate', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const flowId = c.req.param('flowId') as FlowId;
+    const version = c.req.param('version');
+    const outcome = await binding.reinstateVersion({ tenantId, flowId, version });
+    if (outcome.kind === 'not-found') {
+      c.status(statusFor('flow-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'flow-not-found',
+            message: `No flow "${flowId as unknown as string}" at version "${version}" to reinstate`,
+            flowId: flowId as unknown as string,
+            version,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json({
+      flowId: outcome.flowId as unknown as string,
+      version: outcome.version,
+      wasTombstoned: outcome.wasTombstoned,
+    });
+  });
+
+  return r;
+}
+
+function serializeGraph(g: Flow): Record<string, unknown> {
+  return {
+    id: g.id as unknown as string,
+    version: g.version,
+    ...(g.name !== undefined && { name: g.name }),
+    ...(g.description !== undefined && { description: g.description }),
+    nodes: g.nodes,
+    edges: g.edges,
+    ...(g.maxParallelism !== undefined && { maxParallelism: g.maxParallelism }),
+    ...(g.metadata !== undefined && { metadata: g.metadata }),
+  };
+}
+
+/**
+ * Normalize any `FlowError` to a flat `issues[]` list so the wire
+ * response shape is uniform. Errors that already carry an `issues`
+ * array (schema-validation-failed, loop-invalid-output-schema) pass
+ * through unchanged; the discrete errors project their structural
+ * fields into a single-element issues list keyed by the natural path.
+ */
+function toIssues(err: FlowError): readonly { readonly path: string; readonly message: string }[] {
+  if ('issues' in err) return err.issues;
+  const path = derivePath(err);
+  return [{ path, message: err.message }];
+}
+
+function derivePath(err: FlowError): string {
+  if ('edgeId' in err && err.edgeId !== undefined) {
+    return `edges/${err.edgeId as unknown as string}`;
+  }
+  if ('nodeId' in err && err.nodeId !== undefined) {
+    return `nodes/${err.nodeId as unknown as string}`;
+  }
+  if ('loopNodeId' in err && err.loopNodeId !== undefined) {
+    return `nodes/${err.loopNodeId as unknown as string}`;
+  }
+  return '';
+}