create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/slack-notify.ts

@@ -0,0 +1,240 @@
+/**
+ * @file slack-notify.ts
+ * @description The operator's one free action per application (#4999): post
+ * a new `ProjectListing` to the site's Slack channel with Approve/Reject
+ * buttons, then update that SAME message in place once a decision lands.
+ *
+ * A thin `fetch` client over the Slack Web API — no Slack SDK (this
+ * environment's contract). `AILK_SLACK_BOT_TOKEN`/`AILK_SLACK_CHANNEL_ID`
+ * absent means Slack is off: both exports become no-ops that log
+ * `slack-skipped` (id only) and never throw — a create must never fail
+ * because Slack is unconfigured (or down), and a decision must always be
+ * appliable even if the outcome can't be posted back.
+ *
+ * PII boundary: only `listingId` (plus a Slack API `error` code, never a
+ * response body) ever reaches a log line here — never `founderEmail`,
+ * `founderName`, `oneLiner`, `problem`, or any other applicant-authored text.
+ * The Block Kit body sent TO Slack necessarily carries that text (that's the
+ * point of the notification) — Slack, not this process's own logs, is the
+ * destination for it.
+ *
+ * Security note (PR #4999 review): every applicant-authored string
+ * (`oneLiner`/`problem`/`founderName`/`founderCompany`/`url`) is
+ * submitted by an ANONYMOUS, unauthenticated caller (`POST
+ * /v1/project-listings`) and lands in `mrkdwn` fields, which Slack parses for
+ * `<!channel>`/`<!here>`/`<@U…>` mentions and `<url|label>` masked links — an
+ * applicant could otherwise mass-ping the channel or mask a phishing link
+ * behind innocuous-looking text. `escapeMrkdwn` (Slack's own documented
+ * escaping: `&` -> `&amp;`, `<` -> `&lt;`, `>` -> `&gt;`, in that order) runs
+ * on every such string, and on the Slack-supplied `decidedByName` too (lower
+ * risk — only a member of the notified channel controls it — but the same
+ * fix applies for defense in depth).
+ */
+import { logger } from "@working-theory/observability";
+
+import { config } from "../config/index.js";
+import { prisma } from "../lib/prisma.js";
+
+const SLACK_API_BASE = "https://slack.com/api";
+
+/** The subset of a ProjectListing this module ever renders into a Slack message. */
+export type ProjectListingSlackInfo = {
+  id: string;
+  /**
+   * Nullable since #5036 D1: every application field is nullable at rest so a
+   * half-filled draft is storable. A listing only reaches Slack once it has
+   * been SUBMITTED, so in practice these are set — the nulls are rendered as
+   * an em dash rather than asserted away, because a `!` here would turn a data
+   * surprise into a crash inside a notifier that is not allowed to throw.
+   */
+  name: string | null;
+  oneLiner: string | null;
+  problem: string | null;
+  url: string | null;
+  /** The six-rung product ladder that replaced `stage` (#5036 D2). */
+  product: string | null;
+  founderName: string;
+  founderCompany: string | null;
+};
+
+/** What an absent field renders as in a Slack field. */
+const ABSENT = "—";
+
+type SlackApiResult = {
+  ok: boolean;
+  error?: string;
+  ts?: string;
+  channel?: string;
+};
+
+/**
+ * Slack's own documented `mrkdwn` escaping — `&` first, then `<`/`>` — so an
+ * applicant-authored string can never open a `<!channel>`/`<@U…>` mention or
+ * a `<url|label>` masked link inside a `mrkdwn` field.
+ */
+function escapeMrkdwn(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+async function callSlackApi(
+  token: string,
+  method: "chat.postMessage" | "chat.update",
+  body: Record<string, unknown>,
+): Promise<SlackApiResult> {
+  const res = await fetch(`${SLACK_API_BASE}/${method}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+  });
+  return (await res.json()) as SlackApiResult;
+}
+
+/**
+ * The header + info-fields blocks shared by the initial post and the decided
+ * update. Every applicant-authored string is `escapeMrkdwn`-ed before it
+ * enters a `mrkdwn` field (see the module doc's security note) — an
+ * anonymous applicant's `oneLiner`/`problem`/`founderName`/
+ * `founderCompany`/`url` can otherwise inject a Slack mention or a masked
+ * phishing link. `listing.name` is NOT escaped here — it renders in the
+ * `header` block as `plain_text`, which Slack never interprets as markup.
+ */
+function infoBlocks(listing: ProjectListingSlackInfo): unknown[] {
+  const fields = [
+    { type: "mrkdwn", text: `*One-liner:*\n${escapeMrkdwn(listing.oneLiner ?? ABSENT)}` },
+    { type: "mrkdwn", text: `*Problem:*\n${escapeMrkdwn(listing.problem ?? ABSENT)}` },
+    { type: "mrkdwn", text: `*Product:*\n${escapeMrkdwn(listing.product ?? ABSENT)}` },
+    ...(listing.url ? [{ type: "mrkdwn", text: `*URL:*\n${escapeMrkdwn(listing.url)}` }] : []),
+    {
+      type: "mrkdwn",
+      text: `*Founder:*\n${escapeMrkdwn(listing.founderName)}${
+        listing.founderCompany ? ` (${escapeMrkdwn(listing.founderCompany)})` : ""
+      }`,
+    },
+  ];
+
+  return [
+    { type: "header", text: { type: "plain_text", text: listing.name ?? ABSENT, emoji: true } },
+    { type: "section", fields },
+  ];
+}
+
+/**
+ * Posts the new application to Slack (`chat.postMessage`) with Approve/Reject
+ * buttons carrying the listing id as `value`. On success, stamps the
+ * returned `channel`/`ts` onto the row so `updateListingMessage` can later
+ * target the same message. No-op (logs `slack-skipped`) when Slack env is
+ * absent; never throws — a Slack failure (missing config, API error, network
+ * error) never fails the create that already succeeded.
+ */
+export async function postListingApplication(listing: ProjectListingSlackInfo): Promise<void> {
+  const token = config.AILK_SLACK_BOT_TOKEN;
+  const channel = config.AILK_SLACK_CHANNEL_ID;
+  if (!token || !channel) {
+    logger.info({ listingId: listing.id }, "slack-skipped");
+    return;
+  }
+
+  try {
+    const result = await callSlackApi(token, "chat.postMessage", {
+      channel,
+      // `text:` is mrkdwn-parsed and is what Slack shows in the notification
+      // fallback, so the applicant-authored name is escaped here even though
+      // the same value is safe unescaped in the `plain_text` header block
+      // (PR #5042 security review, finding 5).
+      text: `New project application: ${escapeMrkdwn(listing.name ?? ABSENT)}`,
+      blocks: [
+        ...infoBlocks(listing),
+        {
+          type: "actions",
+          block_id: "listing_decision",
+          elements: [
+            {
+              type: "button",
+              text: { type: "plain_text", text: "Approve", emoji: true },
+              style: "primary",
+              action_id: "listing_approve",
+              value: listing.id,
+            },
+            {
+              type: "button",
+              text: { type: "plain_text", text: "Reject", emoji: true },
+              style: "danger",
+              action_id: "listing_reject",
+              value: listing.id,
+            },
+          ],
+        },
+      ],
+    });
+
+    if (!result.ok) {
+      logger.warn({ listingId: listing.id, slackError: result.error }, "slack post failed");
+      return;
+    }
+
+    await prisma.projectListing.update({
+      where: { id: listing.id },
+      data: { slackChannel: result.channel ?? channel, slackTs: result.ts ?? null },
+    });
+  } catch (err) {
+    logger.warn(
+      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
+      "slack post threw",
+    );
+  }
+}
+
+/**
+ * Replaces the posted message's actions block with an outcome line
+ * (`chat.update`) — same header + info fields, Approve/Reject buttons gone.
+ * No-op (logs `slack-skipped`) when Slack env is absent OR the row never
+ * carries `slackChannel`/`slackTs` (the post was skipped or failed); never
+ * throws — the decision has already been applied by the time this runs.
+ */
+export async function updateListingMessage(
+  listing: ProjectListingSlackInfo & { slackChannel: string | null; slackTs: string | null },
+  /** The stored decision status (#5033 — `active` is the approved state). */
+  outcome: "active" | "rejected",
+  decidedByName: string,
+): Promise<void> {
+  const token = config.AILK_SLACK_BOT_TOKEN;
+  if (!token || !listing.slackChannel || !listing.slackTs) {
+    logger.info({ listingId: listing.id }, "slack-skipped");
+    return;
+  }
+
+  // decidedByName is Slack-supplied (payload.user.username/name) — escaped
+  // for the same reason applicant text is (see the module doc's security
+  // note), even though only a member of the notified channel controls it.
+  const safeDecidedByName = escapeMrkdwn(decidedByName);
+  // The operator-facing copy stays "Approved" — the vocabulary change is in
+  // the stored status, not in what a human reads in the channel.
+  const outcomeLine =
+    outcome === "active"
+      ? `:white_check_mark: Approved by ${safeDecidedByName}`
+      : `:x: Rejected by ${safeDecidedByName}`;
+
+  try {
+    const result = await callSlackApi(token, "chat.update", {
+      channel: listing.slackChannel,
+      ts: listing.slackTs,
+      text: `${escapeMrkdwn(listing.name ?? ABSENT)} — ${outcomeLine}`,
+      blocks: [
+        ...infoBlocks(listing),
+        { type: "section", text: { type: "mrkdwn", text: outcomeLine } },
+      ],
+    });
+
+    if (!result.ok) {
+      logger.warn({ listingId: listing.id, slackError: result.error }, "slack update failed");
+    }
+  } catch (err) {
+    logger.warn(
+      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
+      "slack update threw",
+    );
+  }
+}

package/templates/apps/api/src/services/tenant-context.ts

@@ -0,0 +1,451 @@
+// oss: false
+/**
+ * Tenant-context service — the multi-tenant module's guard + tenancy assembly
+ * (FEAT-042, design decision (a): row-level isolation at ONE data-access
+ * boundary + a default-deny scope layer + a guard).
+ *
+ * This module and `../lib/tenant-db.ts` are the ONLY two files allowed to
+ * touch tenancy/domain Prisma models directly (enforced by the
+ * `forbidden_pattern` tenant-scope rule in architecture.yaml). Everything
+ * here follows the ADR 0009 D3 service-layer convention: cross-namespace
+ * assembly (auth-namespace Membership/Workspace/Session ↔ content-namespace
+ * AgentSession/Artifact) happens only in `apps/api/src/services/`.
+ *
+ * The guard model (default-deny — every branch that is not an explicit grant
+ * is a denial):
+ *
+ *   1. `resolveActiveTenant` — validates the caller's OWN session context:
+ *      cookie session present (bearer tokens carry no workspace binding —
+ *      #3591), an active workspace set, the workspace row exists, the
+ *      session's activeOrganizationId matches the workspace's organization,
+ *      and a Membership(user, org) row exists. Result: a `TenantContext`
+ *      every downstream domain query is scoped by.
+ *   2. Workspace-target routes compare the URL's workspaceId against the
+ *      resolved context — mismatch is `forbidden` WITHOUT looking the target
+ *      up (no tenant enumeration).
+ *   3. Session/artifact-target routes never load the target unscoped at the
+ *      route layer; `tenant-db.ts` scopes every lookup by workspaceId, so a
+ *      foreign target is indistinguishable from a missing one (`not_found`).
+ *
+ * Service results use the discriminated `{ ok } | { ok: false, error }`
+ * convention from `lead-routing.ts`; routes translate kinds to HTTP statuses.
+ */
+import {
+  DEFAULT_ORG_ID,
+  DEFAULT_WORKSPACE_ID,
+  OPERATOR_MEMBERSHIP_ID,
+} from "@working-theory/database/tenancy";
+import { isSentinel, type Id } from "@working-theory/ids";
+
+import { prisma } from "../lib/prisma.js";
+import type { SessionTenant } from "../middleware/auth.js";
+
+export type MembershipRole = "owner" | "admin" | "member";
+
+/**
+ * The tenant scope every domain query is bound to. Ids carry the ADR-0031
+ * brand; values originating from Prisma reads are brand-asserted at the read
+ * edge (the DB CHECK constraints are the runtime guarantee).
+ */
+export interface TenantContext {
+  userId: Id<"user">;
+  organizationId: Id<"organization">;
+  workspaceId: Id<"workspace">;
+  role: MembershipRole;
+}
+
+export type TenantErrorKind = "forbidden" | "not_found" | "conflict";
+
+export type TenantResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { kind: TenantErrorKind; message: string } };
+
+function deny<T>(kind: TenantErrorKind, message: string): TenantResult<T> {
+  return { ok: false, error: { kind, message } };
+}
+
+/**
+ * TOFU-binds the operator Membership for a single-tenant deployment (spec
+ * D1–D4) — the replacement for the deleted user-agnostic `owner` grant. The
+ * Membership is created with a fixed, well-known id
+ * (`OPERATOR_MEMBERSHIP_ID`); the `Membership.id` primary-key uniqueness —
+ * not a read-then-write "is this the first user?" guard — enforces exactly
+ * one owner under a concurrent first-login race. The losing caller's
+ * `create` raises `P2002`, swallowed here: that caller is then unbound and
+ * denied by the `membership.findUnique` the caller of this function runs
+ * next.
+ *
+ * Idempotent + at-most-once: a caller who already holds the Membership (a
+ * repeat call, or the deployment's steady state after the first bind) hits
+ * the same `P2002` path and is a no-op. Reachable ONLY from
+ * `resolveSingleTenantDefault`, itself gated by the
+ * `count === 1 && default-workspace-exists` check — unreachable from any
+ * multi-tenant state (`count > 1`).
+ *
+ * When `AILK_OPERATOR_EMAIL` is set (spec D4 — trimmed + lowercased before
+ * comparison), the bind is attempted ONLY for the caller whose `User.email`
+ * matches it; every other caller returns without writing and is denied
+ * downstream. An empty/whitespace-only `AILK_OPERATOR_EMAIL` normalizes to
+ * `""`, which is falsy — treated as unset (pure TOFU), so a blank pin can
+ * never "match" a blank `User.email`. When unset, the bind is pure TOFU —
+ * first caller wins.
+ */
+async function bindOperatorMembership(userId: Id<"user">): Promise<void> {
+  const pinnedEmail = process.env.AILK_OPERATOR_EMAIL?.trim().toLowerCase();
+  if (pinnedEmail) {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { email: true },
+    });
+    if (!user || user.email.trim().toLowerCase() !== pinnedEmail) {
+      return;
+    }
+  }
+  try {
+    await prisma.membership.create({
+      data: {
+        id: OPERATOR_MEMBERSHIP_ID,
+        organizationId: DEFAULT_ORG_ID,
+        userId,
+        role: "owner",
+      },
+    });
+  } catch (error) {
+    if (!isUniqueViolation(error)) {
+      throw error;
+    }
+    // Another caller already holds OPERATOR_MEMBERSHIP_ID (the TOFU race
+    // winner, or a prior deployment run) — swallow and fall through.
+  }
+}
+
+/**
+ * Resolves the default single-tenant scope when the deployment is
+ * unambiguously single-tenant — the default Workspace (`DEFAULT_WORKSPACE_ID`)
+ * exists AND it is the ONLY Workspace (`workspace.count() === 1`), the exact
+ * mirror of the Phase-1 provision guard's `count === 0` check (spec D2).
+ * Returns `null` (never grants) the instant a second Workspace exists, or the
+ * sole Workspace is not the well-known default — the caller falls through to
+ * the existing multi-tenant default-deny in that case.
+ *
+ * Converges on the SAME Membership-based authz the multi-tenant path uses
+ * (spec D1 — the fix): attempts to TOFU-bind the caller as operator
+ * (`bindOperatorMembership`, a no-op once an operator is already bound or
+ * the caller doesn't match the optional env pin), then runs the real
+ * `membership.findUnique` check. A caller holding no Membership on the
+ * default Org — including every caller after the first once TOFU has bound
+ * someone else — resolves `null` here, and `resolveActiveTenant` denies.
+ * There is no more user-agnostic `owner` grant.
+ */
+async function resolveSingleTenantDefault(
+  userId: Id<"user">,
+): Promise<TenantContext | null> {
+  const workspaceCount = await prisma.workspace.count();
+  if (workspaceCount !== 1) {
+    return null;
+  }
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: DEFAULT_WORKSPACE_ID },
+    select: { id: true, organizationId: true },
+  });
+  // The default workspace must hang off the sentinel default Organization
+  // (ADR-0031 rule 7): keyed on the reserved-range predicate, not a literal.
+  if (!workspace || !isSentinel(workspace.organizationId)) {
+    return null;
+  }
+  await bindOperatorMembership(userId);
+  const membership = await prisma.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId,
+      },
+    },
+    select: { role: true },
+  });
+  if (!membership) {
+    return null;
+  }
+  return {
+    userId,
+    organizationId: workspace.organizationId as Id<"organization">,
+    workspaceId: workspace.id as Id<"workspace">,
+    role: membership.role as MembershipRole,
+  };
+}
+
+/**
+ * Validate the caller's active tenant context. See the guard model above.
+ * `sessionTenant` is undefined for bearer-authenticated requests — denied
+ * here (default-deny) until agent tokens carry a workspace binding (#3591).
+ */
+export async function resolveActiveTenant(params: {
+  userId: Id<"user">;
+  sessionTenant: SessionTenant | undefined;
+}): Promise<TenantResult<TenantContext>> {
+  const { userId, sessionTenant } = params;
+  if (!sessionTenant) {
+    return deny("forbidden", "Tenant context requires a cookie session");
+  }
+  const { activeOrganizationId, activeWorkspaceId } = sessionTenant;
+  if (!activeWorkspaceId || !activeOrganizationId) {
+    // Single-tenant default resolution (spec D1/D2) — only on the previously
+    // unconditional-deny branch, so multi-tenant explicit-binding paths below
+    // add zero extra queries. Falls through to the deny below in any
+    // multi-tenant state (count > 1, or count === 1 but not the default).
+    const singleTenantDefault = await resolveSingleTenantDefault(userId);
+    if (singleTenantDefault) {
+      return { ok: true, value: singleTenantDefault };
+    }
+    return deny("forbidden", "No active workspace");
+  }
+
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: activeWorkspaceId },
+    select: { id: true, organizationId: true },
+  });
+  if (!workspace) {
+    return deny("forbidden", "Active workspace no longer exists");
+  }
+  if (workspace.organizationId !== activeOrganizationId) {
+    return deny("forbidden", "Stale session tenant context");
+  }
+
+  const membership = await prisma.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId,
+      },
+    },
+    select: { role: true },
+  });
+  if (!membership) {
+    return deny("forbidden", "Not a member of the active organization");
+  }
+
+  return {
+    ok: true,
+    value: {
+      userId,
+      organizationId: workspace.organizationId as Id<"organization">,
+      workspaceId: workspace.id as Id<"workspace">,
+      role: membership.role as MembershipRole,
+    },
+  };
+}
+
+/** The switcher payload: every org the user belongs to, with its workspaces. */
+export interface TenancyListing {
+  activeOrganizationId: Id<"organization"> | null;
+  activeWorkspaceId: Id<"workspace"> | null;
+  organizations: Array<{
+    id: Id<"organization">;
+    name: string;
+    slug: string;
+    role: MembershipRole;
+    workspaces: Array<{ id: Id<"workspace">; name: string; slug: string }>;
+  }>;
+}
+
+/**
+ * List the caller's organizations + workspaces (WorkspaceSwitcher hydration).
+ * Membership-scoped by construction: starts from Membership rows, so no org
+ * outside the caller's memberships can appear.
+ */
+export async function listTenancy(params: {
+  userId: Id<"user">;
+  sessionTenant: SessionTenant | undefined;
+}): Promise<TenantResult<TenancyListing>> {
+  const memberships = await prisma.membership.findMany({
+    where: { userId: params.userId },
+    select: {
+      role: true,
+      organization: {
+        select: {
+          id: true,
+          name: true,
+          slug: true,
+          workspaces: {
+            select: { id: true, name: true, slug: true },
+            orderBy: { createdAt: "asc" },
+          },
+        },
+      },
+    },
+    orderBy: { createdAt: "asc" },
+  });
+
+  return {
+    ok: true,
+    value: {
+      activeOrganizationId: params.sessionTenant?.activeOrganizationId ?? null,
+      activeWorkspaceId: params.sessionTenant?.activeWorkspaceId ?? null,
+      organizations: memberships.map((m) => ({
+        id: m.organization.id as Id<"organization">,
+        name: m.organization.name,
+        slug: m.organization.slug,
+        role: m.role as MembershipRole,
+        workspaces: m.organization.workspaces as Array<{
+          id: Id<"workspace">;
+          name: string;
+          slug: string;
+        }>,
+      })),
+    },
+  };
+}
+
+/**
+ * Switch the caller's active workspace (and, implicitly, organization).
+ * Grant requires the target workspace to exist AND the caller to hold a
+ * Membership in its organization — both failures return `not_found` so a
+ * non-member cannot distinguish "exists" from "doesn't" (no enumeration).
+ * The update is server-side on the Session row (the thin activeWorkspaceId
+ * session extension the apps/workspace auth config declares).
+ */
+export async function activateWorkspace(params: {
+  userId: Id<"user">;
+  sessionTenant: SessionTenant | undefined;
+  workspaceId: Id<"workspace">;
+}): Promise<TenantResult<TenantContext>> {
+  const { userId, sessionTenant, workspaceId } = params;
+  if (!sessionTenant) {
+    return deny("forbidden", "Tenant context requires a cookie session");
+  }
+
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: workspaceId },
+    select: { id: true, organizationId: true },
+  });
+  if (!workspace) {
+    return deny("not_found", "Workspace not found");
+  }
+
+  const membership = await prisma.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId,
+      },
+    },
+    select: { role: true },
+  });
+  if (!membership) {
+    return deny("not_found", "Workspace not found");
+  }
+
+  await prisma.session.update({
+    where: { id: sessionTenant.sessionRowId },
+    data: {
+      activeWorkspaceId: workspace.id,
+      activeOrganizationId: workspace.organizationId,
+    },
+  });
+
+  return {
+    ok: true,
+    value: {
+      userId,
+      organizationId: workspace.organizationId as Id<"organization">,
+      workspaceId: workspace.id as Id<"workspace">,
+      role: membership.role as MembershipRole,
+    },
+  };
+}
+
+/**
+ * Create a workspace in an organization. Role floor: admin (owner > admin).
+ * Non-members get `not_found` (no org enumeration); members below the floor
+ * get `forbidden`.
+ */
+export async function createWorkspace(params: {
+  userId: Id<"user">;
+  organizationId: Id<"organization">;
+  name: string;
+}): Promise<
+  TenantResult<{
+    id: Id<"workspace">;
+    name: string;
+    slug: string;
+    organizationId: Id<"organization">;
+  }>
+> {
+  const { userId, organizationId, name } = params;
+
+  const membership = await prisma.membership.findUnique({
+    where: { organizationId_userId: { organizationId, userId } },
+    select: { role: true },
+  });
+  if (!membership) {
+    return deny("not_found", "Organization not found");
+  }
+  if (membership.role !== "owner" && membership.role !== "admin") {
+    return deny("forbidden", "Creating a workspace requires the admin role");
+  }
+
+  const slug = slugify(name);
+  try {
+    const workspace = await prisma.workspace.create({
+      data: { organizationId, name, slug },
+      select: { id: true, name: true, slug: true, organizationId: true },
+    });
+    return {
+      ok: true,
+      value: {
+        ...workspace,
+        id: workspace.id as Id<"workspace">,
+        organizationId: workspace.organizationId as Id<"organization">,
+      },
+    };
+  } catch (error) {
+    if (isUniqueViolation(error)) {
+      return deny(
+        "conflict",
+        "A workspace with this name already exists in the organization",
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Delete-cascade for a workspace's site config — the service-layer replacement
+ * for the dropped cross-namespace FK (ADR-0009 D3 / #3634 D3). Removes the
+ * workspace's `WorkspaceTheme` / `WorkspaceSiteIdentity` / `WorkspaceSEO` rows,
+ * each scoped by `workspaceId` (the `@unique` key), so it can never touch
+ * another workspace's rows.
+ *
+ * OPTION 1 (Sam-disposed, #3634): this is a HELPER ONLY — no DELETE route,
+ * caller, or invocation exists in this phase. The destructive owner-gated
+ * entry-point that will call it is a separate, parked, Sam-reviewed issue. It
+ * takes a bare `workspaceId` (not a `TenantContext`) because that future caller
+ * has already authorized the delete; scope-safety is the caller's contract.
+ *
+ * Lives here (a `tenant-scope`-excluded file) so the raw `prisma.workspace*`
+ * calls pass the architecture lint.
+ */
+export async function deleteWorkspaceConfig(workspaceId: string): Promise<void> {
+  await prisma.workspaceTheme.deleteMany({ where: { workspaceId } });
+  await prisma.workspaceSiteIdentity.deleteMany({ where: { workspaceId } });
+  await prisma.workspaceSEO.deleteMany({ where: { workspaceId } });
+}
+
+function slugify(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 48) || "workspace"
+  );
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "P2002"
+  );
+}