create-safest-tools 0.2.0

package/template/src/platform-registry.ts

@@ -0,0 +1,753 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+import { validateJsonSchemaValue } from "./workflow-expressions";
+import type { JsonObject, JsonValue } from "./workflow-platform-types";
+import type {
+  ComponentCreateInput,
+  ComponentVersionInput,
+  ConnectionCreateInput,
+  ConnectionVersionInput,
+} from "./platform-registry-validation";
+
+interface MutationRow {
+  action: string;
+  actor_id: string;
+  response_json: string;
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function parsedJson<T>(value: string | null, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+async function replay(db: D1Database, key: string, action: string, actorId: string): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`SELECT action, actor_id, response_json FROM configuration_mutations WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(key).first<MutationRow>();
+  if (!row) return null;
+  if (row.action !== action || row.actor_id !== actorId) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another registry mutation.");
+  return parsedJson(row.response_json, {});
+}
+
+function audit(
+  db: D1Database,
+  session: OperatorSession,
+  key: string,
+  action: string,
+  targetType: string,
+  targetId: string,
+  details: unknown,
+  createdAt: string,
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT OR IGNORE INTO audit_events (
+      id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(crypto.randomUUID(), key, action, session.actor.type, session.actor.id, targetType, targetId, canonicalJson(details), createdAt);
+}
+
+function connectionVersionInsert(
+  db: D1Database,
+  definitionId: string,
+  versionId: string,
+  version: number,
+  input: ConnectionVersionInput,
+  actorId: string,
+  createdAt: string,
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO connection_versions (
+      id, connection_id, version, base_url, service_binding_name,
+      allowed_hosts_json, allowed_methods_json, allowed_path_prefixes_json,
+      redirect_policy_json, request_limit_bytes, response_limit_bytes,
+      response_content_types_json, timeout_ms, concurrency_limit,
+      requests_per_window, window_seconds, credential_strategy, secret_reference,
+      signing_strategy_json, oauth_configuration_json, published_at, created_by, created_at
+    ) VALUES (
+      ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, '{"follow":false,"maximum":0}',
+      ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?21, ?20
+    )
+  `).bind(
+    versionId, definitionId, version, input.baseUrl, input.serviceBindingName,
+    canonicalJson(input.allowedHosts), canonicalJson(input.allowedMethods),
+    canonicalJson(input.allowedPathPrefixes), input.requestLimitBytes, input.responseLimitBytes,
+    canonicalJson(input.responseContentTypes), input.timeoutMs, input.concurrencyLimit,
+    input.requestsPerWindow, input.windowSeconds, input.credentialStrategy, input.secretReference,
+    canonicalJson(input.signingStrategy), canonicalJson(input.oauthConfiguration), createdAt, actorId,
+  );
+}
+
+export async function listConnections(db: D1Database, includeArchived = false): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    SELECT d.id, d.connection_key AS key, d.name, d.description, d.kind, d.status,
+      d.active_version_id AS activeVersionId, d.created_by AS createdBy,
+      d.created_at AS createdAt, d.updated_at AS updatedAt,
+      v.version, v.base_url AS baseUrl, v.service_binding_name AS serviceBindingName,
+      v.credential_strategy AS credentialStrategy, v.published_at AS publishedAt,
+      h.state AS healthState, h.last_success_at AS lastSuccessAt,
+      h.last_error_code AS lastErrorCode,
+      (SELECT COUNT(*) FROM component_versions cv WHERE cv.connection_version_id = v.id) AS dependencyCount
+    FROM connection_definitions d
+    LEFT JOIN connection_versions v ON v.id = d.active_version_id
+    LEFT JOIN connection_health h ON h.connection_version_id = v.id
+    WHERE (?1 = 1 OR d.status != 'archived')
+    ORDER BY d.name, d.id
+  `).bind(includeArchived ? 1 : 0).all<Record<string, unknown>>();
+  return rows.results;
+}
+
+export async function loadConnection(db: D1Database, id: string): Promise<Record<string, unknown> | null> {
+  const definition = await db.prepare(`SELECT * FROM connection_definitions WHERE id = ?1 LIMIT 1`).bind(id).first<Record<string, unknown>>();
+  if (!definition) return null;
+  const versions = await db.prepare(`
+    SELECT v.id, v.version, v.base_url AS baseUrl, v.service_binding_name AS serviceBindingName,
+      v.allowed_hosts_json AS allowedHostsJson, v.allowed_methods_json AS allowedMethodsJson,
+      v.allowed_path_prefixes_json AS allowedPathPrefixesJson,
+      v.request_limit_bytes AS requestLimitBytes, v.response_limit_bytes AS responseLimitBytes,
+      v.response_content_types_json AS responseContentTypesJson, v.timeout_ms AS timeoutMs,
+      v.concurrency_limit AS concurrencyLimit, v.requests_per_window AS requestsPerWindow,
+      v.window_seconds AS windowSeconds, v.credential_strategy AS credentialStrategy,
+      v.secret_reference AS secretReference, v.signing_strategy_json AS signingStrategyJson,
+      v.oauth_configuration_json AS oauthConfigurationJson,
+      v.published_at AS publishedAt, v.retired_at AS retiredAt,
+      v.created_by AS createdBy, h.state AS healthState,
+      h.consecutive_failures AS consecutiveFailures, h.last_success_at AS lastSuccessAt,
+      h.last_error_code AS lastErrorCode
+    FROM connection_versions v LEFT JOIN connection_health h ON h.connection_version_id = v.id
+    WHERE v.connection_id = ?1 ORDER BY v.version DESC, v.id DESC
+  `).bind(id).all<Record<string, unknown>>();
+  return {
+    definition,
+    versions: versions.results.map((version) => ({
+      ...version,
+      allowedHosts: parsedJson(String(version.allowedHostsJson ?? ""), []),
+      allowedMethods: parsedJson(String(version.allowedMethodsJson ?? ""), []),
+      allowedPathPrefixes: parsedJson(String(version.allowedPathPrefixesJson ?? ""), []),
+      responseContentTypes: parsedJson(String(version.responseContentTypesJson ?? ""), []),
+      signingStrategy: parsedJson(String(version.signingStrategyJson ?? ""), {}),
+      oauthConfiguration: parsedJson(String(version.oauthConfigurationJson ?? ""), {}),
+      secretReference: version.secretReference ? "configured" : null,
+      allowedHostsJson: undefined,
+      allowedMethodsJson: undefined,
+      allowedPathPrefixesJson: undefined,
+      responseContentTypesJson: undefined,
+      signingStrategyJson: undefined,
+      oauthConfigurationJson: undefined,
+    })),
+  };
+}
+
+function metadataText(value: unknown, field: string, minimum: number, maximum: number): string {
+  if (typeof value !== "string" || value.trim().length < minimum || value.trim().length > maximum || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new ApiError(400, "registry_metadata_invalid", `${field} must contain ${minimum} to ${maximum} safe characters.`);
+  }
+  return value.trim();
+}
+
+export async function updateConnectionDefinition(
+  db: D1Database,
+  connectionId: string,
+  input: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ connectionId: string; name: string; description: string; status: string; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "connection.update", session.actor.id);
+  if (existing) return {
+    connectionId: String(existing.connectionId), name: String(existing.name), description: String(existing.description),
+    status: String(existing.status), idempotentReplay: true,
+  };
+  const unsupported = Object.keys(input).find((key) => !["name", "description", "status"].includes(key));
+  if (unsupported) throw new ApiError(400, "registry_metadata_invalid", `Unsupported connection field: ${unsupported}.`);
+  const current = await db.prepare(`SELECT name, description, status, active_version_id AS activeVersionId FROM connection_definitions WHERE id = ?1 LIMIT 1`)
+    .bind(connectionId).first<{ name: string; description: string; status: string; activeVersionId: string | null }>();
+  if (!current) throw new ApiError(404, "connection_not_found", "The connection does not exist.");
+  if (current.status === "archived") throw new ApiError(409, "connection_archived", "Archived connections are immutable.");
+  const name = input.name === undefined ? current.name : metadataText(input.name, "name", 2, 160);
+  const description = input.description === undefined ? current.description : metadataText(input.description, "description", 0, 2_000);
+  const status = input.status === undefined ? current.status : String(input.status);
+  if (!["paused", "archived"].includes(status) && status !== current.status) {
+    throw new ApiError(409, "connection_lifecycle_invalid", "Use the health-checked resume endpoint to activate a connection.");
+  }
+  if (status === "archived") {
+    const dependency = await db.prepare(`
+      SELECT COUNT(*) AS count FROM component_versions cv JOIN connection_versions v ON v.id = cv.connection_version_id
+      WHERE v.connection_id = ?1 AND cv.retired_at IS NULL
+    `).bind(connectionId).first<{ count: number }>();
+    if (Number(dependency?.count ?? 0) > 0) throw new ApiError(409, "connection_has_dependencies", "Retire dependent component versions before archiving this connection.");
+  }
+  const timestamp = now();
+  const response = { connectionId, name, description, status };
+  const statements = [
+    db.prepare(`UPDATE connection_definitions SET name = ?2, description = ?3, status = ?4, updated_at = ?5 WHERE id = ?1`).bind(connectionId, name, description, status, timestamp),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'connection.update', ?2, ?3, ?4, ?5)`)
+      .bind(idempotencyKey, session.actor.id, connectionId, canonicalJson(response), timestamp),
+    audit(db, session, `connection-update:${idempotencyKey}`, "connection.updated", "connection", connectionId, { name, status }, timestamp),
+  ];
+  if (current.activeVersionId && status === "paused") statements.push(
+    db.prepare(`UPDATE connection_health SET state = 'paused', last_error_code = 'manually_paused', revision = revision + 1, updated_at = ?2 WHERE connection_version_id = ?1`)
+      .bind(current.activeVersionId, timestamp),
+  );
+  await db.batch(statements);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function createConnection(
+  db: D1Database,
+  input: ConnectionCreateInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ connectionId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existingMutation = await replay(db, idempotencyKey, "connection.create", session.actor.id);
+  if (existingMutation) return {
+    connectionId: String(existingMutation.connectionId), versionId: String(existingMutation.versionId),
+    version: Number(existingMutation.version), idempotentReplay: true,
+  };
+  if (await db.prepare(`SELECT id FROM connection_definitions WHERE installation_id = 'default' AND connection_key = ?1`).bind(input.key).first()) {
+    throw new ApiError(409, "connection_key_exists", "A connection with this key already exists.");
+  }
+  const connectionId = crypto.randomUUID();
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { connectionId, versionId, version: 1 };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO connection_definitions (
+        id, installation_id, connection_key, name, description, kind, status,
+        active_version_id, created_by, created_at, updated_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, 'active', ?6, ?7, ?8, ?8)
+    `).bind(connectionId, input.key, input.name, input.description, input.kind, versionId, session.actor.id, createdAt),
+    connectionVersionInsert(db, connectionId, versionId, 1, input.version, session.actor.id, createdAt),
+    db.prepare(`
+      INSERT INTO connection_health (connection_version_id, state, consecutive_failures, revision, updated_at)
+      VALUES (?1, 'unknown', 0, 1, ?2)
+    `).bind(versionId, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'connection.create', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, connectionId, canonicalJson(response), createdAt),
+    audit(db, session, `connection-create:${idempotencyKey}`, "connection.created", "connection", connectionId, {
+      key: input.key, kind: input.kind, versionId, credentialStrategy: input.version.credentialStrategy,
+    }, createdAt),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function publishConnectionVersion(
+  db: D1Database,
+  connectionId: string,
+  input: ConnectionVersionInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ connectionId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existingMutation = await replay(db, idempotencyKey, "connection.version.publish", session.actor.id);
+  if (existingMutation) return {
+    connectionId: String(existingMutation.connectionId), versionId: String(existingMutation.versionId),
+    version: Number(existingMutation.version), idempotentReplay: true,
+  };
+  const definition = await db.prepare(`SELECT status FROM connection_definitions WHERE id = ?1`).bind(connectionId).first<{ status: string }>();
+  if (!definition) throw new ApiError(404, "connection_not_found", "The connection does not exist.");
+  if (definition.status === "archived") throw new ApiError(409, "connection_archived", "Archived connections cannot receive versions.");
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM connection_versions WHERE connection_id = ?1`)
+    .bind(connectionId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { connectionId, versionId, version };
+  await db.batch([
+    connectionVersionInsert(db, connectionId, versionId, version, input, session.actor.id, createdAt),
+    db.prepare(`INSERT INTO connection_health (connection_version_id, state, consecutive_failures, revision, updated_at) VALUES (?1, 'unknown', 0, 1, ?2)`).bind(versionId, createdAt),
+    db.prepare(`UPDATE connection_definitions SET active_version_id = ?2, status = 'active', updated_at = ?3 WHERE id = ?1`).bind(connectionId, versionId, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'connection.version.publish', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, versionId, canonicalJson(response), createdAt),
+    audit(db, session, `connection-publish:${idempotencyKey}`, "connection.version_published", "connection", connectionId, {
+      versionId, version, credentialStrategy: input.credentialStrategy,
+    }, createdAt),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function setConnectionStatus(
+  db: D1Database,
+  connectionId: string,
+  status: "active" | "paused",
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ connectionId: string; status: string; idempotentReplay: boolean }> {
+  const action = `connection.${status}`;
+  const existing = await replay(db, idempotencyKey, action, session.actor.id);
+  if (existing) return { connectionId: String(existing.connectionId), status: String(existing.status), idempotentReplay: true };
+  const definition = await db.prepare(`SELECT active_version_id AS activeVersionId, status FROM connection_definitions WHERE id = ?1 LIMIT 1`)
+    .bind(connectionId).first<{ activeVersionId: string | null; status: string }>();
+  if (!definition) throw new ApiError(404, "connection_not_found", "The connection does not exist.");
+  if (definition.status === "archived") throw new ApiError(409, "connection_archived", "Archived connections cannot change status.");
+  if (!definition.activeVersionId) throw new ApiError(409, "connection_version_missing", "The connection has no active version.");
+  const timestamp = now();
+  const response = { connectionId, status };
+  await db.batch([
+    db.prepare(`UPDATE connection_definitions SET status = ?2, updated_at = ?3 WHERE id = ?1`).bind(connectionId, status, timestamp),
+    db.prepare(`UPDATE connection_health SET state = ?2, consecutive_failures = CASE WHEN ?2 = 'paused' THEN consecutive_failures ELSE 0 END, opened_at = NULL, next_probe_at = NULL, last_error_code = CASE WHEN ?2 = 'paused' THEN 'manually_paused' ELSE NULL END, revision = revision + 1, updated_at = ?3 WHERE connection_version_id = ?1`)
+      .bind(definition.activeVersionId, status === "paused" ? "paused" : "unknown", timestamp),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6)`)
+      .bind(idempotencyKey, action, session.actor.id, connectionId, canonicalJson(response), timestamp),
+    audit(db, session, `${action}:${idempotencyKey}`, `connection.${status}`, "connection", connectionId, { activeVersionId: definition.activeVersionId }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function connectionDependencies(db: D1Database, connectionId: string): Promise<Record<string, unknown>> {
+  const definition = await db.prepare(`SELECT id FROM connection_definitions WHERE id = ?1 LIMIT 1`).bind(connectionId).first();
+  if (!definition) throw new ApiError(404, "connection_not_found", "The connection does not exist.");
+  const [components, workflows, modelAliases] = await Promise.all([
+    db.prepare(`
+      SELECT d.id AS componentId, d.name, v.id AS componentVersionId, v.version
+      FROM component_versions v JOIN component_definitions d ON d.id = v.definition_id
+      JOIN connection_versions cv ON cv.id = v.connection_version_id
+      WHERE cv.connection_id = ?1 AND v.retired_at IS NULL ORDER BY d.name, v.version DESC
+    `).bind(connectionId).all<Record<string, unknown>>(),
+    db.prepare(`
+      SELECT DISTINCT d.id AS workflowId, d.name, wv.id AS workflowVersionId, wv.version
+      FROM workflow_dependencies dep
+      JOIN workflow_versions wv ON wv.id = dep.workflow_version_id
+      JOIN workflow_definitions d ON d.id = wv.workflow_id
+      JOIN connection_versions cv ON cv.id = dep.dependency_version_id
+      WHERE dep.dependency_type = 'connection' AND cv.connection_id = ?1
+      ORDER BY d.name, wv.version DESC
+    `).bind(connectionId).all<Record<string, unknown>>(),
+    db.prepare(`
+      SELECT a.id AS aliasId, a.name, v.id AS aliasVersionId, v.version
+      FROM model_alias_versions v JOIN model_aliases a ON a.id = v.alias_id
+      JOIN connection_versions cv ON cv.id = v.connection_version_id
+      WHERE cv.connection_id = ?1 AND v.retired_at IS NULL ORDER BY a.name, v.version DESC
+    `).bind(connectionId).all<Record<string, unknown>>(),
+  ]);
+  return { components: components.results, workflows: workflows.results, modelAliases: modelAliases.results };
+}
+
+export async function validateConnectionDefinition(db: D1Database, connectionId: string): Promise<Record<string, unknown>> {
+  const row = await db.prepare(`
+    SELECT d.status, d.active_version_id AS activeVersionId, v.base_url AS baseUrl,
+      v.service_binding_name AS serviceBindingName, v.allowed_hosts_json AS allowedHostsJson,
+      v.allowed_methods_json AS allowedMethodsJson, v.allowed_path_prefixes_json AS allowedPathsJson,
+      v.credential_strategy AS credentialStrategy, v.secret_reference AS secretReference,
+      h.state AS healthState
+    FROM connection_definitions d LEFT JOIN connection_versions v ON v.id = d.active_version_id
+    LEFT JOIN connection_health h ON h.connection_version_id = v.id
+    WHERE d.id = ?1 LIMIT 1
+  `).bind(connectionId).first<Record<string, unknown>>();
+  if (!row) throw new ApiError(404, "connection_not_found", "The connection does not exist.");
+  const errors: string[] = [];
+  if (!row.activeVersionId) errors.push("active_version_missing");
+  if (Boolean(row.baseUrl) === Boolean(row.serviceBindingName)) errors.push("destination_invalid");
+  if (!parsedJson(String(row.allowedMethodsJson ?? ""), [] as string[]).length) errors.push("allowed_methods_empty");
+  if (!parsedJson(String(row.allowedPathsJson ?? ""), [] as string[]).length) errors.push("allowed_paths_empty");
+  if (!["none", "oauth2_authorization_code", "service_binding"].includes(String(row.credentialStrategy)) && !row.secretReference) errors.push("secret_reference_missing");
+  return { valid: errors.length === 0, errors, activeVersionId: row.activeVersionId, status: row.status, healthState: row.healthState };
+}
+
+function fixtureEvidence(input: ComponentVersionInput): boolean {
+  const evidence = input.compatibility.fixture_evidence;
+  return Boolean(evidence && typeof evidence === "object" && !Array.isArray(evidence) && evidence.passed === true);
+}
+
+function componentFixtureStatements(
+  db: D1Database,
+  versionId: string,
+  input: ComponentVersionInput,
+  actorId: string,
+  createdAt: string,
+): D1PreparedStatement[] {
+  const evidence = input.compatibility.fixture_evidence;
+  const fixtures = evidence && typeof evidence === "object" && !Array.isArray(evidence) && Array.isArray(evidence.fixtures)
+    ? evidence.fixtures : [];
+  return fixtures.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+    const fixtureId = crypto.randomUUID();
+    const testRunId = crypto.randomUUID();
+    const name = typeof entry.name === "string" ? entry.name : "fixture";
+    const fixtureInput = entry.input && typeof entry.input === "object" && !Array.isArray(entry.input) ? entry.input : {};
+    const expected = entry.expected_output && typeof entry.expected_output === "object" && !Array.isArray(entry.expected_output) ? entry.expected_output : {};
+    const expectedStatus = typeof entry.expected_status === "string" ? entry.expected_status : "succeeded";
+    return [
+      db.prepare(`
+        INSERT INTO component_fixtures (
+          id, component_version_id, name, input_json, expected_json,
+          expected_status, created_by, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+      `).bind(fixtureId, versionId, name, canonicalJson(fixtureInput), canonicalJson(expected), expectedStatus, actorId, createdAt),
+      db.prepare(`
+        INSERT INTO component_test_runs (
+          id, component_version_id, fixture_id, status, output_json,
+          started_by, started_at, finished_at
+        ) VALUES (?1, ?2, ?3, 'passed', ?4, ?5, ?6, ?6)
+      `).bind(testRunId, versionId, fixtureId, canonicalJson({
+        validation: "schema_only",
+        expectedStatus,
+        mode: typeof entry.mode === "string" ? entry.mode : "simulated",
+      }), actorId, createdAt),
+    ];
+  });
+}
+
+async function requireComponentConnection(db: D1Database, input: ComponentVersionInput): Promise<void> {
+  if (!input.connectionVersionId) return;
+  const connection = await db.prepare(`
+    SELECT v.id FROM connection_versions v JOIN connection_definitions d ON d.id = v.connection_id
+    WHERE v.id = ?1 AND v.retired_at IS NULL AND d.status = 'active' LIMIT 1
+  `).bind(input.connectionVersionId).first();
+  if (!connection) throw new ApiError(409, "component_connection_unavailable", "The pinned connection version is unavailable.");
+}
+
+function componentVersionInsert(
+  db: D1Database,
+  definitionId: string,
+  versionId: string,
+  version: number,
+  input: ComponentVersionInput,
+  actorId: string,
+  createdAt: string,
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO component_versions (
+      id, definition_id, version, implementation_kind, implementation_reference,
+      input_schema_json, output_schema_json, allowed_input_fields_json,
+      data_classifications_json, connection_version_id, risk_class,
+      timeout_policy_json, retry_policy_json, cache_policy_json,
+      concurrency_policy_json, budget_policy_json, approval_policy_json,
+      tool_manifest_json, compatibility_json, published_at, created_by, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?21, ?20)
+  `).bind(
+    versionId, definitionId, version, input.implementationKind, input.implementationReference,
+    canonicalJson(input.inputSchema), canonicalJson(input.outputSchema), canonicalJson(input.allowedInputFields),
+    canonicalJson(input.dataClassifications), input.connectionVersionId, input.riskClass,
+    canonicalJson(input.timeoutPolicy), canonicalJson(input.retryPolicy), canonicalJson(input.cachePolicy),
+    canonicalJson(input.concurrencyPolicy), canonicalJson(input.budgetPolicy), canonicalJson(input.approvalPolicy),
+    canonicalJson(input.toolManifest), canonicalJson(input.compatibility), createdAt, actorId,
+  );
+}
+
+export async function listComponents(db: D1Database, includeArchived = false): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    SELECT d.id, d.component_key AS key, d.name, d.description,
+      d.component_kind AS kind, d.effect_class AS effectClass,
+      d.owner_kind AS ownerKind, d.status, d.active_version_id AS activeVersionId,
+      d.created_by AS createdBy, d.created_at AS createdAt, d.updated_at AS updatedAt,
+      v.version, v.implementation_kind AS implementationKind,
+      v.risk_class AS riskClass, v.connection_version_id AS connectionVersionId,
+      v.published_at AS publishedAt,
+      (SELECT COUNT(*) FROM workflow_dependencies wd
+       WHERE wd.dependency_type = 'component' AND wd.dependency_version_id = v.id) AS dependencyCount
+    FROM component_definitions d LEFT JOIN component_versions v ON v.id = d.active_version_id
+    WHERE (?1 = 1 OR d.status != 'archived')
+    ORDER BY d.name, d.id
+  `).bind(includeArchived ? 1 : 0).all<Record<string, unknown>>();
+  return rows.results;
+}
+
+export async function loadComponent(db: D1Database, id: string): Promise<Record<string, unknown> | null> {
+  const definition = await db.prepare(`SELECT * FROM component_definitions WHERE id = ?1 LIMIT 1`).bind(id).first<Record<string, unknown>>();
+  if (!definition) return null;
+  const [versions, fixtures, testRuns] = await Promise.all([db.prepare(`
+    SELECT id, version, implementation_kind AS implementationKind,
+      implementation_reference AS implementationReference,
+      input_schema_json AS inputSchemaJson, output_schema_json AS outputSchemaJson,
+      allowed_input_fields_json AS allowedInputFieldsJson,
+      data_classifications_json AS dataClassificationsJson,
+      connection_version_id AS connectionVersionId, risk_class AS riskClass,
+      timeout_policy_json AS timeoutPolicyJson, retry_policy_json AS retryPolicyJson,
+      cache_policy_json AS cachePolicyJson, concurrency_policy_json AS concurrencyPolicyJson,
+      budget_policy_json AS budgetPolicyJson, approval_policy_json AS approvalPolicyJson,
+      tool_manifest_json AS toolManifestJson, compatibility_json AS compatibilityJson,
+      published_at AS publishedAt, retired_at AS retiredAt, created_by AS createdBy
+    FROM component_versions WHERE definition_id = ?1 ORDER BY version DESC, id DESC
+  `).bind(id).all<Record<string, unknown>>(),
+  db.prepare(`
+    SELECT f.id, f.component_version_id AS componentVersionId, f.name,
+      f.input_json AS inputJson, f.expected_json AS expectedJson,
+      f.expected_status AS expectedStatus, f.created_by AS createdBy,
+      f.created_at AS createdAt
+    FROM component_fixtures f JOIN component_versions v ON v.id = f.component_version_id
+    WHERE v.definition_id = ?1 ORDER BY f.created_at DESC, f.id DESC
+  `).bind(id).all<Record<string, unknown>>(),
+  db.prepare(`
+    SELECT t.id, t.component_version_id AS componentVersionId, t.fixture_id AS fixtureId,
+      t.status, t.output_json AS outputJson, t.error_code AS errorCode,
+      t.started_by AS startedBy, t.started_at AS startedAt, t.finished_at AS finishedAt
+    FROM component_test_runs t JOIN component_versions v ON v.id = t.component_version_id
+    WHERE v.definition_id = ?1 ORDER BY t.started_at DESC, t.id DESC LIMIT 200
+  `).bind(id).all<Record<string, unknown>>()]);
+  const jsonFields = ["inputSchema", "outputSchema", "allowedInputFields", "dataClassifications", "timeoutPolicy", "retryPolicy", "cachePolicy", "concurrencyPolicy", "budgetPolicy", "approvalPolicy", "toolManifest", "compatibility"];
+  return {
+    definition,
+    versions: versions.results.map((version) => {
+      const output: Record<string, unknown> = { ...version };
+      for (const field of jsonFields) {
+        const source = `${field}Json`;
+        output[field] = parsedJson(String(output[source] ?? ""), field.endsWith("Fields") || field === "toolManifest" ? [] : {});
+        delete output[source];
+      }
+      return output;
+    }),
+    fixtures: fixtures.results.map((fixture) => ({
+      ...fixture,
+      input: parsedJson(String(fixture.inputJson ?? ""), {}),
+      expected: parsedJson(String(fixture.expectedJson ?? ""), {}),
+      inputJson: undefined,
+      expectedJson: undefined,
+    })),
+    testRuns: testRuns.results.map((testRun) => ({
+      ...testRun,
+      output: testRun.outputJson ? parsedJson(String(testRun.outputJson), {}) : null,
+      outputJson: undefined,
+    })),
+  };
+}
+
+export async function updateComponentDefinition(
+  db: D1Database,
+  componentId: string,
+  input: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ componentId: string; name: string; description: string; status: string; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "component.update", session.actor.id);
+  if (existing) return {
+    componentId: String(existing.componentId), name: String(existing.name), description: String(existing.description),
+    status: String(existing.status), idempotentReplay: true,
+  };
+  const unsupported = Object.keys(input).find((key) => !["name", "description", "status"].includes(key));
+  if (unsupported) throw new ApiError(400, "registry_metadata_invalid", `Unsupported component field: ${unsupported}.`);
+  const current = await db.prepare(`SELECT name, description, status FROM component_definitions WHERE id = ?1 LIMIT 1`)
+    .bind(componentId).first<{ name: string; description: string; status: string }>();
+  if (!current) throw new ApiError(404, "component_not_found", "The component does not exist.");
+  if (current.status === "archived") throw new ApiError(409, "component_archived", "Archived components are immutable.");
+  const name = input.name === undefined ? current.name : metadataText(input.name, "name", 2, 160);
+  const description = input.description === undefined ? current.description : metadataText(input.description, "description", 0, 2_000);
+  const status = input.status === undefined ? current.status : String(input.status);
+  if (![current.status, "paused", "deprecated", "archived"].includes(status)) {
+    throw new ApiError(409, "component_lifecycle_invalid", "Use the readiness-checked resume endpoint to activate a component.");
+  }
+  if (status === "archived") {
+    const dependency = await db.prepare(`
+      SELECT COUNT(*) AS count FROM workflow_dependencies dep JOIN component_versions v ON v.id = dep.dependency_version_id
+      WHERE dep.dependency_type = 'component' AND v.definition_id = ?1
+    `).bind(componentId).first<{ count: number }>();
+    if (Number(dependency?.count ?? 0) > 0) throw new ApiError(409, "component_has_dependencies", "Retire dependent workflow versions before archiving this component.");
+  }
+  const timestamp = now();
+  const response = { componentId, name, description, status };
+  await db.batch([
+    db.prepare(`UPDATE component_definitions SET name = ?2, description = ?3, status = ?4, updated_at = ?5 WHERE id = ?1`).bind(componentId, name, description, status, timestamp),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, 'component.update', ?2, ?3, ?4, ?5)`)
+      .bind(idempotencyKey, session.actor.id, componentId, canonicalJson(response), timestamp),
+    audit(db, session, `component-update:${idempotencyKey}`, "component.updated", "component", componentId, { name, status }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function createComponent(
+  db: D1Database,
+  input: ComponentCreateInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ componentId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existingMutation = await replay(db, idempotencyKey, "component.create", session.actor.id);
+  if (existingMutation) return {
+    componentId: String(existingMutation.componentId), versionId: String(existingMutation.versionId),
+    version: Number(existingMutation.version), idempotentReplay: true,
+  };
+  if (!fixtureEvidence(input.version)) throw new ApiError(409, "component_fixture_gate_not_met", "Passing fixture evidence is required before component publication.");
+  await requireComponentConnection(db, input.version);
+  if (await db.prepare(`SELECT id FROM component_definitions WHERE installation_id = 'default' AND component_key = ?1`).bind(input.key).first()) {
+    throw new ApiError(409, "component_key_exists", "A component with this key already exists.");
+  }
+  const componentId = crypto.randomUUID();
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { componentId, versionId, version: 1 };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO component_definitions (
+        id, installation_id, component_key, name, description, component_kind,
+        effect_class, owner_kind, status, active_version_id, created_by, created_at, updated_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, 'active', ?8, ?9, ?10, ?10)
+    `).bind(
+      componentId, input.key, input.name, input.description, input.kind,
+      input.effectClass, input.ownerKind, versionId, session.actor.id, createdAt,
+    ),
+    componentVersionInsert(db, componentId, versionId, 1, input.version, session.actor.id, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'component.create', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, componentId, canonicalJson(response), createdAt),
+    audit(db, session, `component-create:${idempotencyKey}`, "component.created", "component", componentId, {
+      key: input.key, kind: input.kind, effectClass: input.effectClass, versionId,
+    }, createdAt),
+    ...componentFixtureStatements(db, versionId, input.version, session.actor.id, createdAt),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function publishComponentVersion(
+  db: D1Database,
+  componentId: string,
+  input: ComponentVersionInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ componentId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existingMutation = await replay(db, idempotencyKey, "component.version.publish", session.actor.id);
+  if (existingMutation) return {
+    componentId: String(existingMutation.componentId), versionId: String(existingMutation.versionId),
+    version: Number(existingMutation.version), idempotentReplay: true,
+  };
+  const definition = await db.prepare(`SELECT status, effect_class FROM component_definitions WHERE id = ?1`)
+    .bind(componentId).first<{ status: string; effect_class: string }>();
+  if (!definition) throw new ApiError(404, "component_not_found", "The component does not exist.");
+  if (definition.status === "archived") throw new ApiError(409, "component_archived", "Archived components cannot receive versions.");
+  if (!fixtureEvidence(input)) throw new ApiError(409, "component_fixture_gate_not_met", "Passing fixture evidence is required before component publication.");
+  if (definition.effect_class === "side_effecting" && !["human", "bounded_auto"].includes(String(input.approvalPolicy.mode))) throw new ApiError(409, "action_approval_policy_required", "A side-effecting version must preserve its approval policy.");
+  await requireComponentConnection(db, input);
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM component_versions WHERE definition_id = ?1`)
+    .bind(componentId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { componentId, versionId, version };
+  await db.batch([
+    componentVersionInsert(db, componentId, versionId, version, input, session.actor.id, createdAt),
+    db.prepare(`UPDATE component_definitions SET active_version_id = ?2, status = 'active', updated_at = ?3 WHERE id = ?1`).bind(componentId, versionId, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'component.version.publish', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, versionId, canonicalJson(response), createdAt),
+    audit(db, session, `component-publish:${idempotencyKey}`, "component.version_published", "component", componentId, {
+      versionId, version, implementationKind: input.implementationKind,
+    }, createdAt),
+    ...componentFixtureStatements(db, versionId, input, session.actor.id, createdAt),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function setComponentStatus(
+  db: D1Database,
+  componentId: string,
+  status: "active" | "paused",
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ componentId: string; status: string; idempotentReplay: boolean }> {
+  const action = `component.${status}`;
+  const existing = await replay(db, idempotencyKey, action, session.actor.id);
+  if (existing) return { componentId: String(existing.componentId), status: String(existing.status), idempotentReplay: true };
+  const definition = await db.prepare(`SELECT status, active_version_id AS activeVersionId FROM component_definitions WHERE id = ?1 LIMIT 1`)
+    .bind(componentId).first<{ status: string; activeVersionId: string | null }>();
+  if (!definition) throw new ApiError(404, "component_not_found", "The component does not exist.");
+  if (["archived", "deprecated"].includes(definition.status)) throw new ApiError(409, "component_lifecycle_invalid", "Archived or deprecated components cannot change status.");
+  if (!definition.activeVersionId) throw new ApiError(409, "component_version_missing", "The component has no active version.");
+  const timestamp = now();
+  const response = { componentId, status };
+  await db.batch([
+    db.prepare(`UPDATE component_definitions SET status = ?2, updated_at = ?3 WHERE id = ?1`).bind(componentId, status, timestamp),
+    db.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6)`)
+      .bind(idempotencyKey, action, session.actor.id, componentId, canonicalJson(response), timestamp),
+    audit(db, session, `${action}:${idempotencyKey}`, `component.${status}`, "component", componentId, { activeVersionId: definition.activeVersionId }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function componentDependencies(db: D1Database, componentId: string): Promise<Record<string, unknown>> {
+  const definition = await db.prepare(`SELECT id FROM component_definitions WHERE id = ?1 LIMIT 1`).bind(componentId).first();
+  if (!definition) throw new ApiError(404, "component_not_found", "The component does not exist.");
+  const workflows = await db.prepare(`
+    SELECT DISTINCT d.id AS workflowId, d.name, wv.id AS workflowVersionId, wv.version,
+      wv.authority_mode AS authorityMode, wv.published_at AS publishedAt,
+      wv.retired_at AS retiredAt
+    FROM workflow_dependencies dep
+    JOIN workflow_versions wv ON wv.id = dep.workflow_version_id
+    JOIN workflow_definitions d ON d.id = wv.workflow_id
+    JOIN component_versions cv ON cv.id = dep.dependency_version_id
+    WHERE dep.dependency_type = 'component' AND cv.definition_id = ?1
+    ORDER BY d.name, wv.version DESC
+  `).bind(componentId).all<Record<string, unknown>>();
+  return { workflows: workflows.results };
+}
+
+export async function validateComponentDefinition(db: D1Database, componentId: string): Promise<Record<string, unknown>> {
+  const row = await db.prepare(`
+    SELECT d.status, d.effect_class AS effectClass, d.active_version_id AS activeVersionId,
+      v.implementation_kind AS implementationKind, v.implementation_reference AS implementationReference,
+      v.input_schema_json AS inputSchemaJson, v.output_schema_json AS outputSchemaJson,
+      v.connection_version_id AS connectionVersionId,
+      (SELECT COUNT(*) FROM component_fixtures f WHERE f.component_version_id = v.id) AS fixtureCount,
+      (SELECT COUNT(*) FROM component_test_runs t WHERE t.component_version_id = v.id AND t.status = 'passed') AS passingTestCount
+    FROM component_definitions d LEFT JOIN component_versions v ON v.id = d.active_version_id
+    WHERE d.id = ?1 LIMIT 1
+  `).bind(componentId).first<Record<string, unknown>>();
+  if (!row) throw new ApiError(404, "component_not_found", "The component does not exist.");
+  const errors: string[] = [];
+  if (!row.activeVersionId) errors.push("active_version_missing");
+  if (!parsedJson(String(row.inputSchemaJson ?? ""), null)) errors.push("input_schema_invalid");
+  if (!parsedJson(String(row.outputSchemaJson ?? ""), null)) errors.push("output_schema_invalid");
+  if (["webhook", "external_api"].includes(String(row.implementationKind)) && !row.connectionVersionId) errors.push("connection_version_missing");
+  if (Number(row.fixtureCount ?? 0) < 1) errors.push("fixture_missing");
+  if (Number(row.passingTestCount ?? 0) < 1) errors.push("passing_test_missing");
+  return { valid: errors.length === 0, errors, ...row };
+}
+
+export async function testComponentDefinition(
+  db: D1Database,
+  componentId: string,
+  session: OperatorSession,
+): Promise<{ passed: boolean; componentVersionId: string; results: Record<string, unknown>[] }> {
+  const version = await db.prepare(`
+    SELECT d.active_version_id AS componentVersionId, v.input_schema_json AS inputSchemaJson,
+      v.output_schema_json AS outputSchemaJson
+    FROM component_definitions d JOIN component_versions v ON v.id = d.active_version_id
+    WHERE d.id = ?1 AND d.status != 'archived' LIMIT 1
+  `).bind(componentId).first<{ componentVersionId: string; inputSchemaJson: string; outputSchemaJson: string }>();
+  if (!version) throw new ApiError(404, "component_not_found", "The component or active version does not exist.");
+  const fixtures = await db.prepare(`
+    SELECT id, name, input_json AS inputJson, expected_json AS expectedJson,
+      expected_status AS expectedStatus FROM component_fixtures
+    WHERE component_version_id = ?1 ORDER BY name, id
+  `).bind(version.componentVersionId).all<{ id: string; name: string; inputJson: string; expectedJson: string; expectedStatus: string }>();
+  if (!fixtures.results.length) throw new ApiError(409, "component_fixture_missing", "The active component version has no fixtures.");
+  const inputSchema = parsedJson<JsonObject>(version.inputSchemaJson, {});
+  const outputSchema = parsedJson<JsonObject>(version.outputSchemaJson, {});
+  const timestamp = now();
+  const results: Record<string, unknown>[] = [];
+  const statements: D1PreparedStatement[] = [];
+  for (const fixture of fixtures.results) {
+    let inputValue: JsonValue = null;
+    let expectedValue: JsonValue = null;
+    const errors: string[] = [];
+    try { inputValue = JSON.parse(fixture.inputJson) as JsonValue; } catch { errors.push("fixture_input_json_invalid"); }
+    try { expectedValue = JSON.parse(fixture.expectedJson) as JsonValue; } catch { errors.push("fixture_expected_json_invalid"); }
+    errors.push(...validateJsonSchemaValue(inputValue, inputSchema).map((entry) => `input:${entry}`));
+    if (fixture.expectedStatus === "succeeded") errors.push(...validateJsonSchemaValue(expectedValue, outputSchema).map((entry) => `output:${entry}`));
+    const passed = errors.length === 0;
+    const testRunId = crypto.randomUUID();
+    results.push({ fixtureId: fixture.id, name: fixture.name, passed, errors });
+    statements.push(db.prepare(`
+      INSERT INTO component_test_runs (
+        id, component_version_id, fixture_id, status, output_json,
+        error_code, started_by, started_at, finished_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8)
+    `).bind(
+      testRunId, version.componentVersionId, fixture.id, passed ? "passed" : "failed",
+      canonicalJson({ fixture_validation: true, errors }), passed ? null : "fixture_schema_mismatch",
+      session.actor.id, timestamp,
+    ));
+  }
+  statements.push(audit(db, session, `component-test:${componentId}:${timestamp}:${session.actor.id}`, "component.tested", "component", componentId, { componentVersionId: version.componentVersionId, results }, timestamp));
+  await db.batch(statements);
+  return { passed: results.every((result) => result.passed === true), componentVersionId: version.componentVersionId, results };
+}