@smithers-orchestrator/control-plane 0.20.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@smithers-orchestrator/control-plane",
+  "version": "0.20.4",
+  "description": "Durable organization, project, billing, usage, secret-reference, and audit primitives for hosted Smithers control planes.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@smithers-orchestrator/errors": "0.20.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,152 @@
+import { Database } from 'bun:sqlite';
+
+type ControlPlaneSqlite = Database | {
+  exec(sql: string): unknown;
+  query(sql: string): {
+    run(...params: unknown[]): unknown;
+    get(...params: unknown[]): Record<string, unknown> | null;
+    all(...params: unknown[]): Array<Record<string, unknown>>;
+  };
+};
+
+type ControlPlaneOrg = {
+  orgId: string;
+  slug: string;
+  name: string;
+  createdAtMs: number;
+};
+
+type ControlPlaneTeam = {
+  orgId: string;
+  teamId: string;
+  slug: string;
+  name: string;
+  createdAtMs: number;
+};
+
+type ControlPlaneProject = {
+  orgId: string;
+  projectId: string;
+  slug: string;
+  name: string;
+  metadata: Record<string, unknown>;
+  createdAtMs: number;
+};
+
+type ControlPlaneBillingAccount = {
+  orgId: string;
+  plan: string;
+  billingCustomerId: string | null;
+  status: string;
+  updatedAtMs: number;
+};
+
+type ControlPlaneIdentityProvider = {
+  orgId: string;
+  providerId: string;
+  type: string;
+  issuer: string;
+  ssoUrl: string | null;
+  certificateRef: string | null;
+  status: string;
+  metadata: Record<string, unknown>;
+  createdAtMs: number;
+  updatedAtMs: number;
+};
+
+type ControlPlaneUsageEvent = {
+  id: number;
+  orgId: string;
+  projectId: string | null;
+  runId: string | null;
+  metric: string;
+  quantity: number;
+  unit: string;
+  observedAtMs: number;
+  metadata: Record<string, unknown>;
+};
+
+type ControlPlaneUsageLimit = {
+  orgId: string;
+  projectId: string | null;
+  metric: string;
+  unit: string;
+  period: string;
+  limitQuantity: number;
+  updatedAtMs: number;
+};
+
+type ControlPlaneUsageLimitCheck = ControlPlaneUsageLimit & {
+  usedQuantity: number;
+  remainingQuantity: number;
+  exceeded: boolean;
+};
+
+type ControlPlaneUsageSummary = {
+  orgId: string;
+  metric: string;
+  unit: string;
+  quantity: number;
+};
+
+type ControlPlaneSecretRef = {
+  orgId: string;
+  projectId: string | null;
+  name: string;
+  provider: string;
+  ref: string;
+  createdBy: string | null;
+  createdAtMs: number;
+  rotatedAtMs: number | null;
+};
+
+type ControlPlaneAuditEvent = {
+  id: number;
+  orgId: string;
+  projectId: string | null;
+  actorId: string | null;
+  action: string;
+  targetType: string;
+  targetId: string | null;
+  occurredAtMs: number;
+  metadata: Record<string, unknown>;
+};
+
+type ControlPlaneExport = {
+  exportedAtMs: number;
+  org: ControlPlaneOrg;
+  projects: ControlPlaneProject[];
+  teams: ControlPlaneTeam[];
+  billing: ControlPlaneBillingAccount | null;
+  identityProviders: ControlPlaneIdentityProvider[];
+  usage: ControlPlaneUsageSummary[];
+  usageLimits: ControlPlaneUsageLimit[];
+  secretRefs: ControlPlaneSecretRef[];
+  auditEvents: ControlPlaneAuditEvent[];
+};
+
+declare function ensureControlPlaneTables(sqlite: ControlPlaneSqlite): void;
+
+declare class ControlPlaneStore {
+  constructor(sqlite: ControlPlaneSqlite);
+
+  createOrg(input: { orgId?: string; slug: string; name: string; createdAtMs?: number }): ControlPlaneOrg;
+  getOrg(orgId: string): ControlPlaneOrg | null;
+  createTeam(input: { orgId: string; teamId?: string; slug: string; name: string; createdAtMs?: number }): ControlPlaneTeam;
+  addTeamMember(input: { orgId: string; teamId: string; userId: string; role?: string; createdAtMs?: number }): void;
+  createProject(input: { orgId: string; projectId?: string; slug: string; name: string; metadata?: Record<string, unknown>; createdAtMs?: number }): ControlPlaneProject;
+  addProjectTeam(input: { orgId: string; projectId: string; teamId: string; role?: string; createdAtMs?: number }): void;
+  upsertBillingAccount(input: { orgId: string; plan: string; billingCustomerId?: string | null; status?: string; updatedAtMs?: number }): ControlPlaneBillingAccount;
+  upsertIdentityProvider(input: { orgId: string; providerId?: string; type: string; issuer: string; ssoUrl?: string | null; certificateRef?: string | null; status?: string; metadata?: Record<string, unknown>; createdAtMs?: number; updatedAtMs?: number }): ControlPlaneIdentityProvider;
+  listIdentityProviders(input: { orgId: string; status?: string }): ControlPlaneIdentityProvider[];
+  recordUsage(input: { orgId: string; projectId?: string | null; runId?: string | null; metric: string; quantity: number; unit?: string; observedAtMs?: number; metadata?: Record<string, unknown> }): ControlPlaneUsageEvent;
+  summarizeUsage(input: { orgId: string; sinceMs?: number; untilMs?: number }): ControlPlaneUsageSummary[];
+  setUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; limitQuantity: number; updatedAtMs?: number }): ControlPlaneUsageLimit;
+  checkUsageLimit(input: { orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; sinceMs?: number; untilMs?: number }): ControlPlaneUsageLimitCheck | null;
+  putSecretRef(input: { orgId: string; projectId?: string | null; name: string; provider: string; ref: string; createdBy?: string | null; createdAtMs?: number; rotatedAtMs?: number | null }): ControlPlaneSecretRef;
+  listSecretRefs(input: { orgId: string; projectId?: string | null }): ControlPlaneSecretRef[];
+  recordAuditEvent(input: { orgId: string; projectId?: string | null; actorId?: string | null; action: string; targetType: string; targetId?: string | null; occurredAtMs?: number; metadata?: Record<string, unknown> }): ControlPlaneAuditEvent;
+  exportOrgAudit(input: { orgId: string; sinceMs?: number; untilMs?: number; exportedAtMs?: number }): ControlPlaneExport;
+}
+
+export { type ControlPlaneAuditEvent, type ControlPlaneBillingAccount, type ControlPlaneExport, type ControlPlaneIdentityProvider, type ControlPlaneOrg, type ControlPlaneProject, type ControlPlaneSecretRef, type ControlPlaneSqlite, ControlPlaneStore, type ControlPlaneTeam, type ControlPlaneUsageEvent, type ControlPlaneUsageLimit, type ControlPlaneUsageLimitCheck, type ControlPlaneUsageSummary, ensureControlPlaneTables };

package/src/index.js

@@ -0,0 +1,1064 @@
+import { randomUUID } from "node:crypto";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+/**
+ * @typedef {import("./index.d.ts").ControlPlaneSqlite} ControlPlaneSqlite
+ * @typedef {import("./index.d.ts").ControlPlaneOrg} ControlPlaneOrg
+ * @typedef {import("./index.d.ts").ControlPlaneTeam} ControlPlaneTeam
+ * @typedef {import("./index.d.ts").ControlPlaneProject} ControlPlaneProject
+ * @typedef {import("./index.d.ts").ControlPlaneBillingAccount} ControlPlaneBillingAccount
+ * @typedef {import("./index.d.ts").ControlPlaneIdentityProvider} ControlPlaneIdentityProvider
+ * @typedef {import("./index.d.ts").ControlPlaneUsageEvent} ControlPlaneUsageEvent
+ * @typedef {import("./index.d.ts").ControlPlaneUsageLimit} ControlPlaneUsageLimit
+ * @typedef {import("./index.d.ts").ControlPlaneUsageLimitCheck} ControlPlaneUsageLimitCheck
+ * @typedef {import("./index.d.ts").ControlPlaneUsageSummary} ControlPlaneUsageSummary
+ * @typedef {import("./index.d.ts").ControlPlaneSecretRef} ControlPlaneSecretRef
+ * @typedef {import("./index.d.ts").ControlPlaneAuditEvent} ControlPlaneAuditEvent
+ * @typedef {import("./index.d.ts").ControlPlaneExport} ControlPlaneExport
+ */
+
+const SLUG_RE = /^(?:[a-z0-9]|[a-z0-9][a-z0-9-]{0,62}[a-z0-9])$/;
+const ID_RE = /^[A-Za-z0-9:_-]{1,128}$/;
+
+/**
+ * @param {ControlPlaneSqlite} sqlite
+ */
+export function ensureControlPlaneTables(sqlite) {
+    sqlite.exec("PRAGMA foreign_keys = ON");
+    sqlite.exec(`
+CREATE TABLE IF NOT EXISTS _smithers_cp_orgs (
+  org_id TEXT PRIMARY KEY,
+  slug TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_teams (
+  org_id TEXT NOT NULL,
+  team_id TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, team_id),
+  UNIQUE (org_id, slug),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_team_members (
+  org_id TEXT NOT NULL,
+  team_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, team_id, user_id),
+  FOREIGN KEY (org_id, team_id) REFERENCES _smithers_cp_teams(org_id, team_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_projects (
+  org_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  name TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, project_id),
+  UNIQUE (org_id, slug),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_project_teams (
+  org_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  team_id TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, project_id, team_id),
+  FOREIGN KEY (org_id, project_id) REFERENCES _smithers_cp_projects(org_id, project_id) ON DELETE CASCADE,
+  FOREIGN KEY (org_id, team_id) REFERENCES _smithers_cp_teams(org_id, team_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_billing_accounts (
+  org_id TEXT PRIMARY KEY,
+  plan TEXT NOT NULL,
+  billing_customer_id TEXT,
+  status TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_identity_providers (
+  org_id TEXT NOT NULL,
+  provider_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  issuer TEXT NOT NULL,
+  sso_url TEXT,
+  certificate_ref TEXT,
+  status TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, provider_id),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS _smithers_cp_idp_org_status_idx
+  ON _smithers_cp_identity_providers(org_id, status);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_usage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  org_id TEXT NOT NULL,
+  project_id TEXT,
+  run_id TEXT,
+  metric TEXT NOT NULL,
+  quantity REAL NOT NULL,
+  unit TEXT NOT NULL,
+  observed_at_ms INTEGER NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE,
+  FOREIGN KEY (org_id, project_id) REFERENCES _smithers_cp_projects(org_id, project_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS _smithers_cp_usage_org_time_idx
+  ON _smithers_cp_usage_events(org_id, observed_at_ms);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_usage_limits (
+  org_id TEXT NOT NULL,
+  project_key TEXT NOT NULL,
+  project_id TEXT,
+  metric TEXT NOT NULL,
+  unit TEXT NOT NULL,
+  period TEXT NOT NULL,
+  limit_quantity REAL NOT NULL,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY (org_id, project_key, metric, unit, period),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS _smithers_cp_usage_limits_org_idx
+  ON _smithers_cp_usage_limits(org_id, metric, unit, period);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_secret_refs (
+  org_id TEXT NOT NULL,
+  project_key TEXT NOT NULL,
+  project_id TEXT,
+  name TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  ref TEXT NOT NULL,
+  created_by TEXT,
+  created_at_ms INTEGER NOT NULL,
+  rotated_at_ms INTEGER,
+  PRIMARY KEY (org_id, project_key, name),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE,
+  FOREIGN KEY (org_id, project_id) REFERENCES _smithers_cp_projects(org_id, project_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS _smithers_cp_audit_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  org_id TEXT NOT NULL,
+  project_id TEXT,
+  actor_id TEXT,
+  action TEXT NOT NULL,
+  target_type TEXT NOT NULL,
+  target_id TEXT,
+  occurred_at_ms INTEGER NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE,
+  FOREIGN KEY (org_id, project_id) REFERENCES _smithers_cp_projects(org_id, project_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS _smithers_cp_audit_org_time_idx
+  ON _smithers_cp_audit_events(org_id, occurred_at_ms);
+`);
+    migrateSecretRefsProjectKey(sqlite);
+}
+
+/**
+ * @param {ControlPlaneSqlite} sqlite
+ */
+function migrateSecretRefsProjectKey(sqlite) {
+    const columns = sqlite.query("PRAGMA table_info(_smithers_cp_secret_refs)").all();
+    if (columns.some((column) => String(column.name) === "project_key")) {
+        return;
+    }
+    sqlite.exec(`
+ALTER TABLE _smithers_cp_secret_refs RENAME TO _smithers_cp_secret_refs_legacy;
+
+CREATE TABLE _smithers_cp_secret_refs (
+  org_id TEXT NOT NULL,
+  project_key TEXT NOT NULL,
+  project_id TEXT,
+  name TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  ref TEXT NOT NULL,
+  created_by TEXT,
+  created_at_ms INTEGER NOT NULL,
+  rotated_at_ms INTEGER,
+  PRIMARY KEY (org_id, project_key, name),
+  FOREIGN KEY (org_id) REFERENCES _smithers_cp_orgs(org_id) ON DELETE CASCADE,
+  FOREIGN KEY (org_id, project_id) REFERENCES _smithers_cp_projects(org_id, project_id) ON DELETE CASCADE
+);
+
+INSERT OR REPLACE INTO _smithers_cp_secret_refs (
+  org_id, project_key, project_id, name, provider, ref, created_by, created_at_ms, rotated_at_ms
+)
+SELECT
+  org_id,
+  COALESCE(project_id, '__org__') AS project_key,
+  project_id,
+  name,
+  provider,
+  ref,
+  created_by,
+  created_at_ms,
+  rotated_at_ms
+FROM _smithers_cp_secret_refs_legacy
+ORDER BY created_at_ms;
+
+DROP TABLE _smithers_cp_secret_refs_legacy;
+`);
+}
+
+/**
+ * @param {string} field
+ * @param {unknown} value
+ */
+function nonEmptyString(field, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new SmithersError("INVALID_INPUT", `${field} is required.`);
+    }
+    return value.trim();
+}
+
+/**
+ * @param {string} field
+ * @param {unknown} value
+ */
+function optionalId(field, value) {
+    const id = typeof value === "string" && value.trim() ? value.trim() : randomUUID();
+    if (!ID_RE.test(id)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must match ${ID_RE}.`, { field });
+    }
+    return id;
+}
+
+/**
+ * @param {string} field
+ * @param {unknown} value
+ */
+function requiredId(field, value) {
+    const id = nonEmptyString(field, value);
+    if (!ID_RE.test(id)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must match ${ID_RE}.`, { field });
+    }
+    return id;
+}
+
+/**
+ * @param {string} field
+ * @param {unknown} value
+ */
+function slug(field, value) {
+    const out = nonEmptyString(field, value);
+    if (!SLUG_RE.test(out)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be a lowercase slug.`, { field });
+    }
+    return out;
+}
+
+/**
+ * @param {unknown} value
+ */
+function jsonObject(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new SmithersError("INVALID_INPUT", "metadata must be a JSON object.");
+    }
+    return value;
+}
+
+/**
+ * @param {unknown} value
+ */
+function parseJsonObject(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return {};
+    }
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+
+/**
+ * @param {unknown} value
+ */
+function timestamp(value) {
+    const n = value === undefined ? Date.now() : Number(value);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new SmithersError("INVALID_INPUT", "timestamp must be a non-negative finite number.");
+    }
+    return Math.floor(n);
+}
+
+/**
+ * @param {unknown} value
+ */
+function quantity(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new SmithersError("INVALID_INPUT", "quantity must be a non-negative finite number.");
+    }
+    return n;
+}
+
+/**
+ * @param {string | null} projectId
+ */
+function projectKey(projectId) {
+    return projectId ?? "__org__";
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneOrg}
+ */
+function orgRow(row) {
+    return {
+        orgId: String(row.orgId),
+        slug: String(row.slug),
+        name: String(row.name),
+        createdAtMs: Number(row.createdAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneTeam}
+ */
+function teamRow(row) {
+    return {
+        orgId: String(row.orgId),
+        teamId: String(row.teamId),
+        slug: String(row.slug),
+        name: String(row.name),
+        createdAtMs: Number(row.createdAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneProject}
+ */
+function projectRow(row) {
+    return {
+        orgId: String(row.orgId),
+        projectId: String(row.projectId),
+        slug: String(row.slug),
+        name: String(row.name),
+        metadata: parseJsonObject(row.metadataJson),
+        createdAtMs: Number(row.createdAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneBillingAccount}
+ */
+function billingRow(row) {
+    return {
+        orgId: String(row.orgId),
+        plan: String(row.plan),
+        billingCustomerId: row.billingCustomerId === null ? null : String(row.billingCustomerId),
+        status: String(row.status),
+        updatedAtMs: Number(row.updatedAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneIdentityProvider}
+ */
+function identityProviderRow(row) {
+    return {
+        orgId: String(row.orgId),
+        providerId: String(row.providerId),
+        type: String(row.type),
+        issuer: String(row.issuer),
+        ssoUrl: row.ssoUrl === null ? null : String(row.ssoUrl),
+        certificateRef: row.certificateRef === null ? null : String(row.certificateRef),
+        status: String(row.status),
+        metadata: parseJsonObject(row.metadataJson),
+        createdAtMs: Number(row.createdAtMs),
+        updatedAtMs: Number(row.updatedAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneUsageEvent}
+ */
+function usageRow(row) {
+    return {
+        id: Number(row.id),
+        orgId: String(row.orgId),
+        projectId: row.projectId === null ? null : String(row.projectId),
+        runId: row.runId === null ? null : String(row.runId),
+        metric: String(row.metric),
+        quantity: Number(row.quantity),
+        unit: String(row.unit),
+        observedAtMs: Number(row.observedAtMs),
+        metadata: parseJsonObject(row.metadataJson),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneUsageLimit}
+ */
+function usageLimitRow(row) {
+    return {
+        orgId: String(row.orgId),
+        projectId: row.projectId === null ? null : String(row.projectId),
+        metric: String(row.metric),
+        unit: String(row.unit),
+        period: String(row.period),
+        limitQuantity: Number(row.limitQuantity),
+        updatedAtMs: Number(row.updatedAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneSecretRef}
+ */
+function secretRefRow(row) {
+    return {
+        orgId: String(row.orgId),
+        projectId: row.projectId === null ? null : String(row.projectId),
+        name: String(row.name),
+        provider: String(row.provider),
+        ref: String(row.ref),
+        createdBy: row.createdBy === null ? null : String(row.createdBy),
+        createdAtMs: Number(row.createdAtMs),
+        rotatedAtMs: row.rotatedAtMs === null ? null : Number(row.rotatedAtMs),
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} row
+ * @returns {ControlPlaneAuditEvent}
+ */
+function auditRow(row) {
+    return {
+        id: Number(row.id),
+        orgId: String(row.orgId),
+        projectId: row.projectId === null ? null : String(row.projectId),
+        actorId: row.actorId === null ? null : String(row.actorId),
+        action: String(row.action),
+        targetType: String(row.targetType),
+        targetId: row.targetId === null ? null : String(row.targetId),
+        occurredAtMs: Number(row.occurredAtMs),
+        metadata: parseJsonObject(row.metadataJson),
+    };
+}
+
+/**
+ * @param {ControlPlaneSqlite} sqlite
+ * @param {string} orgId
+ * @param {string} projectId
+ */
+function assertProjectExists(sqlite, orgId, projectId) {
+    const row = sqlite.query(`
+SELECT 1 AS ok
+FROM _smithers_cp_projects
+WHERE org_id = ? AND project_id = ?
+LIMIT 1
+`).get(orgId, projectId);
+    if (!row) {
+        throw new SmithersError("INVALID_INPUT", `Control-plane project not found: ${projectId}`, { orgId, projectId });
+    }
+}
+
+export class ControlPlaneStore {
+    /** @type {ControlPlaneSqlite} */
+    sqlite;
+
+    /**
+     * @param {ControlPlaneSqlite} sqlite
+     */
+    constructor(sqlite) {
+        this.sqlite = sqlite;
+        ensureControlPlaneTables(sqlite);
+    }
+
+    /**
+     * @param {{ orgId?: string; slug: string; name: string; createdAtMs?: number }} input
+     * @returns {ControlPlaneOrg}
+     */
+    createOrg(input) {
+        const orgId = optionalId("orgId", input.orgId);
+        const createdAtMs = timestamp(input.createdAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_orgs (org_id, slug, name, created_at_ms)
+VALUES (?, ?, ?, ?)
+`).run(orgId, slug("slug", input.slug), nonEmptyString("name", input.name), createdAtMs);
+        this.recordAuditEvent({
+            orgId,
+            actorId: "system",
+            action: "org.create",
+            targetType: "org",
+            targetId: orgId,
+            occurredAtMs: createdAtMs,
+        });
+        return this.getOrg(orgId);
+    }
+
+    /**
+     * @param {string} orgId
+     * @returns {ControlPlaneOrg | null}
+     */
+    getOrg(orgId) {
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, slug, name, created_at_ms AS createdAtMs
+FROM _smithers_cp_orgs
+WHERE org_id = ?
+LIMIT 1
+`).get(requiredId("orgId", orgId));
+        return row ? orgRow(row) : null;
+    }
+
+    /**
+     * @param {{ orgId: string; teamId?: string; slug: string; name: string; createdAtMs?: number }} input
+     * @returns {ControlPlaneTeam}
+     */
+    createTeam(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const teamId = optionalId("teamId", input.teamId);
+        const createdAtMs = timestamp(input.createdAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_teams (org_id, team_id, slug, name, created_at_ms)
+VALUES (?, ?, ?, ?, ?)
+`).run(orgId, teamId, slug("slug", input.slug), nonEmptyString("name", input.name), createdAtMs);
+        this.recordAuditEvent({
+            orgId,
+            action: "team.create",
+            targetType: "team",
+            targetId: teamId,
+            occurredAtMs: createdAtMs,
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, team_id AS teamId, slug, name, created_at_ms AS createdAtMs
+FROM _smithers_cp_teams
+WHERE org_id = ? AND team_id = ?
+LIMIT 1
+`).get(orgId, teamId);
+        return teamRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; teamId: string; userId: string; role?: string; createdAtMs?: number }} input
+     */
+    addTeamMember(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const teamId = requiredId("teamId", input.teamId);
+        const userId = requiredId("userId", input.userId);
+        const role = nonEmptyString("role", input.role ?? "member");
+        const createdAtMs = timestamp(input.createdAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_team_members (org_id, team_id, user_id, role, created_at_ms)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(org_id, team_id, user_id) DO UPDATE SET role = excluded.role
+`).run(orgId, teamId, userId, role, createdAtMs);
+        this.recordAuditEvent({
+            orgId,
+            actorId: userId,
+            action: "team.member.upsert",
+            targetType: "team",
+            targetId: teamId,
+            occurredAtMs: createdAtMs,
+            metadata: { role },
+        });
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string; slug: string; name: string; metadata?: Record<string, unknown>; createdAtMs?: number }} input
+     * @returns {ControlPlaneProject}
+     */
+    createProject(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = optionalId("projectId", input.projectId);
+        const metadata = jsonObject(input.metadata);
+        const createdAtMs = timestamp(input.createdAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_projects (org_id, project_id, slug, name, metadata_json, created_at_ms)
+VALUES (?, ?, ?, ?, ?, ?)
+`).run(orgId, projectId, slug("slug", input.slug), nonEmptyString("name", input.name), JSON.stringify(metadata), createdAtMs);
+        this.recordAuditEvent({
+            orgId,
+            projectId,
+            action: "project.create",
+            targetType: "project",
+            targetId: projectId,
+            occurredAtMs: createdAtMs,
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, slug, name, metadata_json AS metadataJson, created_at_ms AS createdAtMs
+FROM _smithers_cp_projects
+WHERE org_id = ? AND project_id = ?
+LIMIT 1
+`).get(orgId, projectId);
+        return projectRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; projectId: string; teamId: string; role?: string; createdAtMs?: number }} input
+     */
+    addProjectTeam(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = requiredId("projectId", input.projectId);
+        const teamId = requiredId("teamId", input.teamId);
+        const role = nonEmptyString("role", input.role ?? "viewer");
+        const createdAtMs = timestamp(input.createdAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_project_teams (org_id, project_id, team_id, role, created_at_ms)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(org_id, project_id, team_id) DO UPDATE SET role = excluded.role
+`).run(orgId, projectId, teamId, role, createdAtMs);
+        this.recordAuditEvent({
+            orgId,
+            projectId,
+            action: "project.team.upsert",
+            targetType: "team",
+            targetId: teamId,
+            occurredAtMs: createdAtMs,
+            metadata: { role },
+        });
+    }
+
+    /**
+     * @param {{ orgId: string; plan: string; billingCustomerId?: string | null; status?: string; updatedAtMs?: number }} input
+     * @returns {ControlPlaneBillingAccount}
+     */
+    upsertBillingAccount(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const updatedAtMs = timestamp(input.updatedAtMs);
+        const status = nonEmptyString("status", input.status ?? "active");
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_billing_accounts (org_id, plan, billing_customer_id, status, updated_at_ms)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(org_id) DO UPDATE SET
+  plan = excluded.plan,
+  billing_customer_id = excluded.billing_customer_id,
+  status = excluded.status,
+  updated_at_ms = excluded.updated_at_ms
+`).run(orgId, nonEmptyString("plan", input.plan), input.billingCustomerId ?? null, status, updatedAtMs);
+        this.recordAuditEvent({
+            orgId,
+            action: "billing.account.upsert",
+            targetType: "billing_account",
+            targetId: orgId,
+            occurredAtMs: updatedAtMs,
+            metadata: { plan: input.plan, status },
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, plan, billing_customer_id AS billingCustomerId, status, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_billing_accounts
+WHERE org_id = ?
+LIMIT 1
+`).get(orgId);
+        return billingRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; providerId?: string; type: "saml" | "oidc" | string; issuer: string; ssoUrl?: string | null; certificateRef?: string | null; status?: string; metadata?: Record<string, unknown>; createdAtMs?: number; updatedAtMs?: number }} input
+     * @returns {ControlPlaneIdentityProvider}
+     */
+    upsertIdentityProvider(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const providerId = optionalId("providerId", input.providerId);
+        const metadata = jsonObject(input.metadata);
+        const updatedAtMs = timestamp(input.updatedAtMs);
+        const createdAtMs = timestamp(input.createdAtMs ?? updatedAtMs);
+        const status = nonEmptyString("status", input.status ?? "active");
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_identity_providers (
+  org_id, provider_id, type, issuer, sso_url, certificate_ref, status, metadata_json, created_at_ms, updated_at_ms
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(org_id, provider_id) DO UPDATE SET
+  type = excluded.type,
+  issuer = excluded.issuer,
+  sso_url = excluded.sso_url,
+  certificate_ref = excluded.certificate_ref,
+  status = excluded.status,
+  metadata_json = excluded.metadata_json,
+  updated_at_ms = excluded.updated_at_ms
+`).run(
+            orgId,
+            providerId,
+            nonEmptyString("type", input.type),
+            nonEmptyString("issuer", input.issuer),
+            input.ssoUrl ? nonEmptyString("ssoUrl", input.ssoUrl) : null,
+            input.certificateRef ? nonEmptyString("certificateRef", input.certificateRef) : null,
+            status,
+            JSON.stringify(metadata),
+            createdAtMs,
+            updatedAtMs,
+        );
+        this.recordAuditEvent({
+            orgId,
+            action: "identity_provider.upsert",
+            targetType: "identity_provider",
+            targetId: providerId,
+            occurredAtMs: updatedAtMs,
+            metadata: { type: input.type, status },
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, provider_id AS providerId, type, issuer, sso_url AS ssoUrl, certificate_ref AS certificateRef, status, metadata_json AS metadataJson, created_at_ms AS createdAtMs, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_identity_providers
+WHERE org_id = ? AND provider_id = ?
+LIMIT 1
+`).get(orgId, providerId);
+        return identityProviderRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; status?: string }} input
+     * @returns {ControlPlaneIdentityProvider[]}
+     */
+    listIdentityProviders(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const status = input.status ? nonEmptyString("status", input.status) : null;
+        const sql = status
+            ? `
+SELECT org_id AS orgId, provider_id AS providerId, type, issuer, sso_url AS ssoUrl, certificate_ref AS certificateRef, status, metadata_json AS metadataJson, created_at_ms AS createdAtMs, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_identity_providers
+WHERE org_id = ? AND status = ?
+ORDER BY provider_id
+`
+            : `
+SELECT org_id AS orgId, provider_id AS providerId, type, issuer, sso_url AS ssoUrl, certificate_ref AS certificateRef, status, metadata_json AS metadataJson, created_at_ms AS createdAtMs, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_identity_providers
+WHERE org_id = ?
+ORDER BY provider_id
+`;
+        const args = status ? [orgId, status] : [orgId];
+        return this.sqlite.query(sql).all(...args).map(identityProviderRow);
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null; runId?: string | null; metric: string; quantity: number; unit?: string; observedAtMs?: number; metadata?: Record<string, unknown> }} input
+     * @returns {ControlPlaneUsageEvent}
+     */
+    recordUsage(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        const observedAtMs = timestamp(input.observedAtMs);
+        const metadata = jsonObject(input.metadata);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_usage_events (org_id, project_id, run_id, metric, quantity, unit, observed_at_ms, metadata_json)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`).run(
+            orgId,
+            projectId,
+            input.runId ? requiredId("runId", input.runId) : null,
+            nonEmptyString("metric", input.metric),
+            quantity(input.quantity),
+            nonEmptyString("unit", input.unit ?? "count"),
+            observedAtMs,
+            JSON.stringify(metadata),
+        );
+        const id = this.sqlite.query("SELECT last_insert_rowid() AS id").get().id;
+        const row = this.sqlite.query(`
+SELECT id, org_id AS orgId, project_id AS projectId, run_id AS runId, metric, quantity, unit, observed_at_ms AS observedAtMs, metadata_json AS metadataJson
+FROM _smithers_cp_usage_events
+WHERE id = ?
+LIMIT 1
+`).get(id);
+        return usageRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; sinceMs?: number; untilMs?: number }} input
+     * @returns {ControlPlaneUsageSummary[]}
+     */
+    summarizeUsage(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const sinceMs = input.sinceMs === undefined ? 0 : timestamp(input.sinceMs);
+        const untilMs = input.untilMs === undefined ? Number.MAX_SAFE_INTEGER : timestamp(input.untilMs);
+        return this.sqlite.query(`
+SELECT org_id AS orgId, metric, unit, SUM(quantity) AS quantity
+FROM _smithers_cp_usage_events
+WHERE org_id = ? AND observed_at_ms >= ? AND observed_at_ms <= ?
+GROUP BY org_id, metric, unit
+ORDER BY metric, unit
+`).all(orgId, sinceMs, untilMs).map((row) => ({
+            orgId: String(row.orgId),
+            metric: String(row.metric),
+            unit: String(row.unit),
+            quantity: Number(row.quantity),
+        }));
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; limitQuantity: number; updatedAtMs?: number }} input
+     * @returns {ControlPlaneUsageLimit}
+     */
+    setUsageLimit(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        if (projectId) {
+            assertProjectExists(this.sqlite, orgId, projectId);
+        }
+        const metric = nonEmptyString("metric", input.metric);
+        const unit = nonEmptyString("unit", input.unit ?? "count");
+        const period = nonEmptyString("period", input.period ?? "monthly");
+        const limitValue = quantity(input.limitQuantity);
+        const updatedAtMs = timestamp(input.updatedAtMs);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_usage_limits (org_id, project_key, project_id, metric, unit, period, limit_quantity, updated_at_ms)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(org_id, project_key, metric, unit, period) DO UPDATE SET
+  project_id = excluded.project_id,
+  limit_quantity = excluded.limit_quantity,
+  updated_at_ms = excluded.updated_at_ms
+`).run(orgId, projectKey(projectId), projectId, metric, unit, period, limitValue, updatedAtMs);
+        this.recordAuditEvent({
+            orgId,
+            projectId,
+            action: "usage_limit.upsert",
+            targetType: "usage_limit",
+            targetId: projectId ?? orgId,
+            occurredAtMs: updatedAtMs,
+            metadata: { metric, unit, period, limitQuantity: limitValue },
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, metric, unit, period, limit_quantity AS limitQuantity, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_usage_limits
+WHERE org_id = ? AND project_key = ? AND metric = ? AND unit = ? AND period = ?
+LIMIT 1
+`).get(orgId, projectKey(projectId), metric, unit, period);
+        return usageLimitRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null; metric: string; unit?: string; period?: string; sinceMs?: number; untilMs?: number }} input
+     * @returns {ControlPlaneUsageLimitCheck | null}
+     */
+    checkUsageLimit(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        const metric = nonEmptyString("metric", input.metric);
+        const unit = nonEmptyString("unit", input.unit ?? "count");
+        const period = nonEmptyString("period", input.period ?? "monthly");
+        const limitRowRaw = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, metric, unit, period, limit_quantity AS limitQuantity, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_usage_limits
+WHERE org_id = ? AND project_key = ? AND metric = ? AND unit = ? AND period = ?
+LIMIT 1
+`).get(orgId, projectKey(projectId), metric, unit, period);
+        if (!limitRowRaw) {
+            return null;
+        }
+        const sinceMs = input.sinceMs === undefined ? 0 : timestamp(input.sinceMs);
+        const untilMs = input.untilMs === undefined ? Number.MAX_SAFE_INTEGER : timestamp(input.untilMs);
+        const usageSql = projectId
+            ? `
+SELECT COALESCE(SUM(quantity), 0) AS usedQuantity
+FROM _smithers_cp_usage_events
+WHERE org_id = ? AND project_id = ? AND metric = ? AND unit = ? AND observed_at_ms >= ? AND observed_at_ms <= ?
+`
+            : `
+SELECT COALESCE(SUM(quantity), 0) AS usedQuantity
+FROM _smithers_cp_usage_events
+WHERE org_id = ? AND metric = ? AND unit = ? AND observed_at_ms >= ? AND observed_at_ms <= ?
+`;
+        const usageArgs = projectId
+            ? [orgId, projectId, metric, unit, sinceMs, untilMs]
+            : [orgId, metric, unit, sinceMs, untilMs];
+        const usageRowRaw = this.sqlite.query(usageSql).get(...usageArgs);
+        const limit = usageLimitRow(limitRowRaw);
+        const usedQuantity = Number(usageRowRaw?.usedQuantity ?? 0);
+        const remainingQuantity = Math.max(0, limit.limitQuantity - usedQuantity);
+        return {
+            ...limit,
+            usedQuantity,
+            remainingQuantity,
+            exceeded: usedQuantity > limit.limitQuantity,
+        };
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null; name: string; provider: string; ref: string; createdBy?: string | null; createdAtMs?: number; rotatedAtMs?: number | null }} input
+     * @returns {ControlPlaneSecretRef}
+     */
+    putSecretRef(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        if (projectId) {
+            assertProjectExists(this.sqlite, orgId, projectId);
+        }
+        const secretProjectKey = projectKey(projectId);
+        const name = nonEmptyString("name", input.name);
+        const createdAtMs = timestamp(input.createdAtMs);
+        const rotatedAtMs = input.rotatedAtMs === undefined || input.rotatedAtMs === null
+            ? null
+            : timestamp(input.rotatedAtMs);
+        const provider = nonEmptyString("provider", input.provider);
+        const ref = nonEmptyString("ref", input.ref);
+        const createdBy = input.createdBy ? requiredId("createdBy", input.createdBy) : null;
+        this.sqlite.query(`
+DELETE FROM _smithers_cp_secret_refs
+WHERE org_id = ? AND project_key = ? AND name = ?
+`).run(orgId, secretProjectKey, name);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_secret_refs (org_id, project_key, project_id, name, provider, ref, created_by, created_at_ms, rotated_at_ms)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+`).run(
+            orgId,
+            secretProjectKey,
+            projectId,
+            name,
+            provider,
+            ref,
+            createdBy,
+            createdAtMs,
+            rotatedAtMs,
+        );
+        this.recordAuditEvent({
+            orgId,
+            projectId,
+            actorId: createdBy,
+            action: "secret_ref.upsert",
+            targetType: "secret_ref",
+            targetId: name,
+            occurredAtMs: rotatedAtMs ?? createdAtMs,
+            metadata: { provider },
+        });
+        const row = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, name, provider, ref, created_by AS createdBy, created_at_ms AS createdAtMs, rotated_at_ms AS rotatedAtMs
+FROM _smithers_cp_secret_refs
+WHERE org_id = ? AND project_key = ? AND name = ?
+LIMIT 1
+`).get(orgId, secretProjectKey, name);
+        return secretRefRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null }} input
+     * @returns {ControlPlaneSecretRef[]}
+     */
+    listSecretRefs(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId === undefined ? undefined : input.projectId;
+        const sql = projectId === undefined
+            ? `
+SELECT org_id AS orgId, project_id AS projectId, name, provider, ref, created_by AS createdBy, created_at_ms AS createdAtMs, rotated_at_ms AS rotatedAtMs
+FROM _smithers_cp_secret_refs
+WHERE org_id = ?
+ORDER BY name
+`
+            : `
+SELECT org_id AS orgId, project_id AS projectId, name, provider, ref, created_by AS createdBy, created_at_ms AS createdAtMs, rotated_at_ms AS rotatedAtMs
+FROM _smithers_cp_secret_refs
+WHERE org_id = ? AND project_key = ?
+ORDER BY name
+`;
+        const args = projectId === undefined ? [orgId] : [orgId, projectKey(projectId ? requiredId("projectId", projectId) : null)];
+        return this.sqlite.query(sql).all(...args).map(secretRefRow);
+    }
+
+    /**
+     * @param {{ orgId: string; projectId?: string | null; actorId?: string | null; action: string; targetType: string; targetId?: string | null; occurredAtMs?: number; metadata?: Record<string, unknown> }} input
+     * @returns {ControlPlaneAuditEvent}
+     */
+    recordAuditEvent(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const projectId = input.projectId ? requiredId("projectId", input.projectId) : null;
+        const occurredAtMs = timestamp(input.occurredAtMs);
+        const metadata = jsonObject(input.metadata);
+        this.sqlite.query(`
+INSERT INTO _smithers_cp_audit_events (org_id, project_id, actor_id, action, target_type, target_id, occurred_at_ms, metadata_json)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`).run(
+            orgId,
+            projectId,
+            input.actorId ? requiredId("actorId", input.actorId) : null,
+            nonEmptyString("action", input.action),
+            nonEmptyString("targetType", input.targetType),
+            input.targetId ? requiredId("targetId", input.targetId) : null,
+            occurredAtMs,
+            JSON.stringify(metadata),
+        );
+        const id = this.sqlite.query("SELECT last_insert_rowid() AS id").get().id;
+        const row = this.sqlite.query(`
+SELECT id, org_id AS orgId, project_id AS projectId, actor_id AS actorId, action, target_type AS targetType, target_id AS targetId, occurred_at_ms AS occurredAtMs, metadata_json AS metadataJson
+FROM _smithers_cp_audit_events
+WHERE id = ?
+LIMIT 1
+`).get(id);
+        return auditRow(row);
+    }
+
+    /**
+     * @param {{ orgId: string; sinceMs?: number; untilMs?: number; exportedAtMs?: number }} input
+     * @returns {ControlPlaneExport}
+     */
+    exportOrgAudit(input) {
+        const orgId = requiredId("orgId", input.orgId);
+        const org = this.getOrg(orgId);
+        if (!org) {
+            throw new SmithersError("INVALID_INPUT", `Control-plane org not found: ${orgId}`, { orgId });
+        }
+        const sinceMs = input.sinceMs === undefined ? 0 : timestamp(input.sinceMs);
+        const untilMs = input.untilMs === undefined ? Number.MAX_SAFE_INTEGER : timestamp(input.untilMs);
+        const projects = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, slug, name, metadata_json AS metadataJson, created_at_ms AS createdAtMs
+FROM _smithers_cp_projects
+WHERE org_id = ?
+ORDER BY slug
+`).all(orgId).map(projectRow);
+        const teams = this.sqlite.query(`
+SELECT org_id AS orgId, team_id AS teamId, slug, name, created_at_ms AS createdAtMs
+FROM _smithers_cp_teams
+WHERE org_id = ?
+ORDER BY slug
+`).all(orgId).map(teamRow);
+        const billingRaw = this.sqlite.query(`
+SELECT org_id AS orgId, plan, billing_customer_id AS billingCustomerId, status, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_billing_accounts
+WHERE org_id = ?
+LIMIT 1
+`).get(orgId);
+        const identityProviders = this.sqlite.query(`
+SELECT org_id AS orgId, provider_id AS providerId, type, issuer, sso_url AS ssoUrl, certificate_ref AS certificateRef, status, metadata_json AS metadataJson, created_at_ms AS createdAtMs, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_identity_providers
+WHERE org_id = ?
+ORDER BY provider_id
+`).all(orgId).map(identityProviderRow);
+        const usageLimits = this.sqlite.query(`
+SELECT org_id AS orgId, project_id AS projectId, metric, unit, period, limit_quantity AS limitQuantity, updated_at_ms AS updatedAtMs
+FROM _smithers_cp_usage_limits
+WHERE org_id = ?
+ORDER BY project_key, metric, unit, period
+`).all(orgId).map(usageLimitRow);
+        const auditEvents = this.sqlite.query(`
+SELECT id, org_id AS orgId, project_id AS projectId, actor_id AS actorId, action, target_type AS targetType, target_id AS targetId, occurred_at_ms AS occurredAtMs, metadata_json AS metadataJson
+FROM _smithers_cp_audit_events
+WHERE org_id = ? AND occurred_at_ms >= ? AND occurred_at_ms <= ?
+ORDER BY occurred_at_ms, id
+`).all(orgId, sinceMs, untilMs).map(auditRow);
+        return {
+            exportedAtMs: timestamp(input.exportedAtMs),
+            org,
+            projects,
+            teams,
+            billing: billingRaw ? billingRow(billingRaw) : null,
+            identityProviders,
+            usage: this.summarizeUsage({ orgId, sinceMs, untilMs }),
+            usageLimits,
+            secretRefs: this.listSecretRefs({ orgId }),
+            auditEvents,
+        };
+    }
+}