@superblocksteam/shared 0.9590.9 → 0.9591.1

package/src/database-lifecycle/index.ts

@@ -4,12 +4,32 @@ export const LIFECYCLE_TERMINAL_STATES = ['ready', 'failed', 'cancelled'] as con
 export const LIFECYCLE_NON_TERMINAL_STATES = ['pending', 'provisioning', 'migrating', 'retiring'] as const;
 export const LIFECYCLE_STATES = [...LIFECYCLE_NON_TERMINAL_STATES, ...LIFECYCLE_TERMINAL_STATES] as const;
 export const LIFECYCLE_MIGRATION_STATES = ['pending', 'migrated', 'failed'] as const;
-export const LIFECYCLE_OPERATIONS = ['ensure_dev_database', 'ensure_prod_database', 'migrate_schema', 'retire_database'] as const;
-export const ENVIRONMENT_CLASSES = ['dev', 'staging', 'prod'] as const;
+// The environment axis (edit/preview/deployed) lives on the binding, so a
+// single `ensure_database` covers what used to be split into
+// ensure_dev_database / ensure_prod_database. `migrate_schema` and
+// `retire_database` were always environment-agnostic.
+export const LIFECYCLE_OPERATIONS = ['ensure_database', 'migrate_schema', 'retire_database'] as const;
+// Mirrors the platform's view modes (proto api.v1.ViewMode: VIEW_MODE_EDIT /
+// VIEW_MODE_PREVIEW / VIEW_MODE_DEPLOYED). Working-state migrations and the
+// shared workspace database serve edit/preview; deploy-commit migrations and
+// the deploy gate concern deployed.
+export const LIFECYCLE_ENVIRONMENTS = ['edit', 'preview', 'deployed'] as const;
 export const DATABASE_ENGINES = ['postgres', 'snowflake', 'snowflake_postgres', 'lakebase'] as const;
 export const DATABASE_LIFECYCLE_MANAGED_BY = 'database_lifecycle';
 
-export type EnvironmentClass = (typeof ENVIRONMENT_CLASSES)[number];
+// Agent capability tag keys. A lifecycle worker publishes these in the
+// `tags` map of its agent registration (merged into — never replacing — the
+// tag map the agent already publishes; the existing `profile` tag carries
+// datatag coverage, same meaning it has for execution routing. Lifecycle
+// environment/profile coverage is published as pairs so edit-only staging
+// profiles do not imply deployed staging support. The server matches pending
+// lifecycle requests against these at poll/claim time and gates task creation
+// on "some active org agent supports this".
+export const DATABASE_LIFECYCLE_TAG_OPERATIONS = 'databaseLifecycle:operations';
+export const DATABASE_LIFECYCLE_TAG_ENGINES = 'databaseLifecycle:engines';
+export const DATABASE_LIFECYCLE_TAG_ENVIRONMENT_PROFILES = 'databaseLifecycle:environmentProfiles';
+
+export type LifecycleEnvironment = (typeof LIFECYCLE_ENVIRONMENTS)[number];
 export type DatabaseEngine = (typeof DATABASE_ENGINES)[number];
 export type LifecycleOperation = (typeof LIFECYCLE_OPERATIONS)[number];
 export type LifecycleTerminalState = (typeof LIFECYCLE_TERMINAL_STATES)[number];
@@ -40,22 +60,6 @@ export type CredentialRef = {
   field?: string;
 };
 
-export type CredentialResolverConfig = {
-  type: CredentialResolver;
-  config: Record<string, unknown>;
-};
-
-// Reference to a versioned Terraform module that the lifecycle worker should
-// invoke for one operation in this profile. `baseInputs` are profile-level
-// inputs the org admin sets once (AWS account/region/VPC/subnets/KMS/...);
-// the planner merges these with binding-derived inputs (binding_key,
-// requirement spec, credential refs) when it builds a dispatch payload.
-export type TerraformModuleRef = {
-  source: string;
-  version: string;
-  baseInputs: Record<string, unknown>;
-};
-
 export type DatabaseRequirement = {
   logicalName: string;
   engine: DatabaseEngine;
@@ -66,51 +70,17 @@ export type DatabaseRequirement = {
   migrationDirectory?: string;
 };
 
-export type TerraformDatabaseBackend = {
-  provisioner: 'terraform';
-  provider: 'aws-rds' | 'snowflake' | 'databricks';
-  stateBackend: 's3' | 'gcs' | 'azurerm' | 'local';
-  remoteState: boolean;
-  locking: boolean;
-};
-
-export type DatabaseBackend = TerraformDatabaseBackend;
-
-export type EnvironmentProfile = {
-  id: string;
-  organizationId: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
-  opaAgentId: string;
-  supportedOperations: LifecycleOperation[];
-  supportedEngines: DatabaseEngine[];
-  backend: DatabaseBackend;
-  // V1 stop-gap. Picks the Terraform module the lifecycle worker invokes
-  // per operation. `Partial` because not every operation is Terraform-backed
-  // in V1 — `migrate_schema` is served by the native Go runner inside the
-  // worker (ENG-3415); admins leave it unset and the dispatcher skips
-  // emitting a Terraform dispatch for it.
-  //
-  // TODO(ENG-3456): collapse into per-operation backends when the
-  // shared-vs-isolated admin config lands. Each operation will then carry
-  // its own discriminated kind ('terraform' | 'native-migration-runner'),
-  // with the module reference and Terraform backend config nested under
-  // kind: 'terraform'. The wire protocol picks up a matching discriminant.
-  moduleSelectors: Partial<Record<LifecycleOperation, TerraformModuleRef>>;
-  // Where the worker resolves and writes credential refs. Scoped per profile
-  // because dev/prod profiles may use different resolvers (e.g. opa_local
-  // for dev, aws_secrets_manager for prod).
-  credentialResolver: CredentialResolverConfig;
-};
-
 type DatabaseBindingBase = {
   id: string;
   bindingKey: string;
   requirementKey: string;
   logicalName: string;
   applicationId: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
+  environment: LifecycleEnvironment;
+  // The datatag key (Profile.key, e.g. 'staging' / 'production') this
+  // binding serves. The same datatag can exist across environments, so the
+  // pair (environment, profile) — not either alone — scopes a binding.
+  profile: string;
   desiredSpecHash: string;
   migrationState: LifecycleMigrationState;
 };
@@ -148,47 +118,33 @@ export type LifecycleRequest = {
   state: LifecycleState;
 };
 
-export type TerraformModuleInput = {
-  bindingKey: string;
-  requirement: DatabaseRequirement;
-  credentialRefs: Record<string, CredentialRef>;
-  metadata: Record<string, string>;
-};
-
-export type TerraformModuleOutput = {
-  connection: Record<string, string | number | boolean>;
-  credentialRefs: Record<string, CredentialRef>;
-  resourceKey: string;
-};
+// Physical database instances back the M2 shared-RDS allocation pattern: dev-DB
+// provisioning issues `CREATE DATABASE`/`CREATE ROLE` against a pre-existing
+// physical database instance instead of spinning up a fresh RDS per binding.
+// The control plane is the dumb org-scoped state store (registry + atomic
+// capacity counter); ALL selection and provisioning logic lives in the worker.
+export const PHYSICAL_DATABASE_INSTANCE_STATUSES = ['active', 'draining', 'retired'] as const;
+export type PhysicalDatabaseInstanceStatus = (typeof PHYSICAL_DATABASE_INSTANCE_STATUSES)[number];
 
-// Resolved per-dispatch Terraform module reference. Mirrors the Go worker's
-// `pkg/databaselifecycle.TerraformModule` JSON shape — `MaterializeJob`
-// writes these straight into `terraform.tfvars.json` and the generated root
-// `main.tf` module block.
-export type TerraformModuleDispatch = {
-  source: string;
-  version: string;
-  inputs: Record<string, unknown>;
-};
-
-// Backend config the worker writes into `backend.tfbackend` and passes to
-// `terraform init -backend-config=...`. Derived from the profile's
-// `backend.stateBackend` plus the per-binding state key. `stateBackend` is
-// the discriminant the worker uses to emit the right HCL
-// `terraform { backend "<stateBackend>" {} }` block — same name as on the
-// profile side. `remoteState` and `locking` pass through unchanged. The
-// worker doesn't see `provisioner`/`provider` — those are server-side
-// categorical fields, not backend args.
-export type TerraformBackendDispatch = {
-  stateBackend: TerraformDatabaseBackend['stateBackend'];
-  remoteState: boolean;
-  locking: boolean;
-  key: string;
+export type PhysicalDatabaseInstance = {
+  id: string;
+  organizationId: string;
+  region: string;
+  environment: LifecycleEnvironment;
+  engine: DatabaseEngine; // postgres-only in V1
+  endpoint: string;
+  masterCredentialRef: CredentialRef;
+  capacityMax: number;
+  capacityUsed: number;
+  status: PhysicalDatabaseInstanceStatus;
+  metadata: Record<string, unknown>;
+  created?: Date;
+  updated?: Date;
 };
 
 // One forward-only SQL migration the server attaches to a dispatch
 // payload so the lifecycle worker's migration runner can apply it after
-// `tofu apply` succeeds. `version` is the sort key + the primary key in
+// provisioning succeeds. `version` is the sort key + the primary key in
 // the worker's in-DB `superblocks_schema_migrations` ledger; `filename`
 // is recorded for diagnostics; `sql` is the raw multi-statement SQL.
 // Matches `orchestrator/pkg/databaselifecycle/migrations.Migration`.
@@ -201,32 +157,31 @@ export type LifecycleMigration = {
 // Canonical wire payload for a lifecycle dispatch sent from the server to a
 // lifecycle worker. The worker's `DispatchPayload` struct in
 // orchestrator/pkg/databaselifecycle/dispatch.go decodes this JSON shape;
-// keys and order here are intentional. Replaces three duplicate definitions
-// previously living in dispatchQueue.ts / devPersistence.ts / planner.
+// keys and order here are intentional.
+//
+// The server describes WHAT (binding identity, desired spec, migrations,
+// connection/credential context); the worker owns HOW (Terraform modules,
+// state backends, credential resolvers, shared physical database instances — all resolved from
+// the worker's local config keyed by the payload's environment + profile).
 //
 // `migrations` is present iff the operation should consider migration
-// state — `ensure_dev_database` / `ensure_prod_database` / `migrate_schema`
-// dispatches carry an array (possibly empty); `retire_database` omits it.
-// An omitted slice keeps the worker's `MigrationState` at the default
-// "pending"; an empty slice means "vacuous truth, mark migrated"; a
-// non-empty slice triggers the runner.
+// state — `ensure_database` / `migrate_schema` dispatches carry an array
+// (possibly empty); `retire_database` omits it. An omitted slice keeps the
+// worker's `MigrationState` at the default "pending"; an empty slice means
+// "vacuous truth, mark migrated"; a non-empty slice triggers the runner.
 export type LifecycleDispatchPayload = {
-  agentId: string;
   bindingKey: string;
   connectionMetadata?: Record<string, string | number | boolean>;
   desiredSpec: DatabaseRequirement;
   desiredSpecHash: string;
+  environment: LifecycleEnvironment;
   migrations?: LifecycleMigration[];
   operation: LifecycleOperation;
-  profileId: string;
+  profile: string;
   requestId: string;
   resourceKey: string;
   runtimeCredentialRefs?: Record<string, CredentialRef>;
-  // Present for Terraform-backed operations. Omitted for native migration
-  // dispatches, where the worker skips Terraform materialization and runs the
-  // migration runner directly.
-  terraformBackend?: TerraformBackendDispatch;
-  terraformModule?: TerraformModuleDispatch;
+  migrationCredentialRefs?: Record<string, CredentialRef>;
 };
 
 export function computeRequirementKey(requirement: Pick<DatabaseRequirement, 'logicalName' | 'engine'>): string {
@@ -236,8 +191,8 @@ export function computeRequirementKey(requirement: Pick<DatabaseRequirement, 'lo
 export function computeBindingKey(input: {
   organizationId: string;
   applicationId: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
+  environment: LifecycleEnvironment;
+  profile: string;
   requirementKey: string;
 }): string {
   return [input.organizationId, ...bindingKeySegments(input)].join(':');
@@ -245,8 +200,8 @@ export function computeBindingKey(input: {
 
 export function computeLegacyBindingKeyWithoutOrganization(input: {
   applicationId: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
+  environment: LifecycleEnvironment;
+  profile: string;
   requirementKey: string;
 }): string {
   return bindingKeySegments(input).join(':');
@@ -254,16 +209,11 @@ export function computeLegacyBindingKeyWithoutOrganization(input: {
 
 function bindingKeySegments(input: {
   applicationId: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
+  environment: LifecycleEnvironment;
+  profile: string;
   requirementKey: string;
 }): string[] {
-  return [
-    input.applicationId,
-    input.environmentClass,
-    `${slugify(input.environmentName)}~${encodeURIComponent(input.environmentName)}`,
-    input.requirementKey
-  ];
+  return [input.applicationId, input.environment, `${slugify(input.profile)}~${encodeURIComponent(input.profile)}`, input.requirementKey];
 }
 
 export async function computeDesiredSpecHash(requirement: DatabaseRequirement): Promise<string> {
@@ -273,52 +223,26 @@ export async function computeDesiredSpecHash(requirement: DatabaseRequirement):
 // resource_key identifies the physical resource a binding maps to in
 // customer infrastructure, and is the unit of locking inside the lifecycle
 // worker. Distinct from binding_key (product identity in the control plane)
-// because two different profiles could plausibly target the same logical
-// resource — the planner uses profileId here so a profile swap forces a
-// fresh resource. Shape mirrors planning doc §15.
+// because the worker derives infrastructure identity from it — shape
+// mirrors planning doc §15.
 export function computeResourceKey(input: {
   organizationId: string;
-  profileId: string;
   applicationId: string;
   requirementKey: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
+  environment: LifecycleEnvironment;
+  profile: string;
   actorScope?: string;
 }): string {
   return [
     input.organizationId,
-    input.profileId,
     input.applicationId,
     input.requirementKey,
-    input.environmentClass,
-    `${slugify(input.environmentName)}~${encodeURIComponent(input.environmentName)}`,
+    input.environment,
+    `${slugify(input.profile)}~${encodeURIComponent(input.profile)}`,
     input.actorScope ?? 'default'
   ].join('/');
 }
 
-// Per-binding Terraform state path inside the configured backend. Used to
-// generate the `backend.tfbackend` config that the worker passes to
-// `terraform init -backend-config=...`. Planning doc §9.4.
-export function computeTerraformStateKey(input: {
-  organizationId: string;
-  applicationId: string;
-  requirementKey: string;
-  environmentClass: EnvironmentClass;
-  environmentName: string;
-  actorScope?: string;
-}): string {
-  return [
-    'superblocks/byo-db',
-    input.environmentClass,
-    input.organizationId,
-    input.applicationId,
-    input.requirementKey,
-    `${slugify(input.environmentName)}~${encodeURIComponent(input.environmentName)}`,
-    input.actorScope ?? 'default',
-    'terraform.tfstate'
-  ].join('/');
-}
-
 export function isTerminalLifecycleState(state: LifecycleState): state is LifecycleTerminalState {
   return (LIFECYCLE_TERMINAL_STATES as readonly string[]).includes(state);
 }

package/src/socket/protocol.ts

@@ -37,7 +37,8 @@ import {
   FactCreate,
   FactDto,
   FactListQuery,
-  ListFactsResponse
+  ListFactsResponse,
+  NpmInstallBlockedAuditReport
 } from '../types/index.js';
 import { MethodSchema } from './types.js';
 
@@ -160,6 +161,15 @@ export interface ServerMethods {
       list: ServerMethodSchema<FactListQuery, ListFactsResponse>;
       create: ServerMethodSchema<FactCreate, FactDto>;
     };
+    audit: {
+      /**
+       * Report a controlled-install `NpmInstallBlocked` so the server can write a
+       * throttled OCSF audit row (APPS-4191 / P6.3). Org + actor are derived from
+       * the authenticated connection; `recorded` is false when the event was
+       * dropped by the per-org or global throttle.
+       */
+      npmInstallBlocked: ServerMethodSchema<NpmInstallBlockedAuditReport, { recorded: boolean }>;
+    };
   };
   v2: {
     application: {
@@ -215,7 +225,14 @@ export interface ServerMethods {
          */
         get: ServerMethodSchema<{ applicationId: string; branchName?: string }, { hash: string }>;
         set: ServerMethodSchema<
-          { applicationId: string; branchName?: string; hash: string; source?: string },
+          {
+            applicationId: string;
+            branchName?: string;
+            hash: string;
+            source?: string;
+            targetTemplateName?: string;
+            migrationGeneration?: number;
+          },
           { hash: string; degradedMode?: DegradedMode; commitId?: string; checkpointSkipped?: CheckpointSkipReason }
         >;
       };

package/src/types/ai/index.ts

@@ -123,3 +123,4 @@ export interface AiPromptCostResponse {
 
 export * from './provider-credential.js';
 export * from './quota-paywall.js';
+export * from './safety-classification.js';

package/src/types/ai/quota-paywall.ts

@@ -8,6 +8,26 @@ export type AiQuotaPaywallReason =
   | 'trial_expired'
   | 'user_credit_limit_exceeded';
 
+/**
+ * The complete set of paywall reasons, kept in lockstep with the
+ * `AiQuotaPaywallReason` union above. Shared so that callers parsing
+ * untrusted error payloads (`packages/vite-plugin-file-sync`) can validate
+ * string values against the same source of truth rather than duplicating it.
+ */
+export const AI_QUOTA_PAYWALL_REASONS: ReadonlySet<AiQuotaPaywallReason> = new Set<AiQuotaPaywallReason>([
+  'credit_limit_exceeded',
+  'deploy_quota_exceeded',
+  'dollar_commit_exhausted',
+  'no_seat_assigned',
+  'payment_past_due',
+  'token_limit_exceeded',
+  'trial_expired',
+  'user_credit_limit_exceeded'
+]);
+
+export const isAiQuotaPaywallReason = (value: unknown): value is AiQuotaPaywallReason =>
+  typeof value === 'string' && AI_QUOTA_PAYWALL_REASONS.has(value as AiQuotaPaywallReason);
+
 export const getAiQuotaPaywallReasonFromMessage = (message: string): AiQuotaPaywallReason | undefined => {
   const normalizedMessage = message.toLowerCase();
 

package/src/types/ai/safety-classification.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared constants and types for LLM-based prompt safety classification.
+ *
+ * Used by the Clark AI service (vite-plugin-file-sync) and the server-side
+ * policy-gate prompt check. Each consumer owns its own context-specific
+ * system prompt; only the structural contract (categories, result types,
+ * default results) lives here.
+ */
+
+export const SAFETY_CATEGORIES = [
+  'harmful_instructions',
+  'illegal_activity',
+  'jailbreak_attempt',
+  'malicious_code',
+  'other',
+  'personal_data_extraction',
+  'prompt_injection',
+  'system_extraction'
+] as const;
+
+export type SafetyCategory = (typeof SAFETY_CATEGORIES)[number];
+
+export interface SafetyClassificationResult {
+  safe: boolean;
+  justification: string;
+  categories?: SafetyCategory[];
+}

package/src/types/audit/ocsf.ts

@@ -163,6 +163,7 @@ export const AUDIT_EVENT_TYPE_CATALOG: AuditEventTypeEntry[] = [
       'application.git.connect',
       'application.git.disconnect',
       'application.metadata.update',
+      'application.policy_gate_check.start',
       'application.settings.update',
       'application.undeploy'
     ]
@@ -237,6 +238,7 @@ export const AUDIT_EVENT_TYPE_CATALOG: AuditEventTypeEntry[] = [
     resource_type: 'Organization',
     operations: [
       'organization.npm_allow_install_scripts_changed',
+      'organization.npm_install.blocked',
       'organization.npm_registry.create',
       'organization.npm_registry.delete',
       'organization.npm_registry.update',
@@ -339,3 +341,44 @@ const METADATA: Omit<OCSFMetadata, 'log_name'> = {
 export function buildOCSFMetadata(logName: string): OCSFMetadata {
   return { ...METADATA, log_name: logName };
 }
+
+// ---------------------------------------------------------------------------
+// npm install-blocked audit report (APPS-4191 / P6.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Wire payload for the `v1.audit.npmInstallBlocked` socket method.
+ *
+ * Emitted by the Clark dev-server runtime when the controlled install path
+ * reports `NpmInstallBlocked`. The server derives org + actor from the
+ * authenticated connection (never trusting the client for identity),
+ * throttles per-org and globally, sanitizes via the P6.1 telemetry helpers,
+ * and writes an OCSF `audit_event` row with operation
+ * `organization.npm_install.blocked`.
+ *
+ * Carries only structured, low-risk fields — deliberately NO free-text error
+ * message, so a registry token embedded in CLI output can never reach the wire.
+ */
+export interface NpmInstallBlockedAuditReport {
+  /** `NpmInstallBlocked.reason`; normalized to the shared npm outcome enum server-side. */
+  reason: string;
+  /** Raw registry host; the server buckets it to public_npm | private | unknown. */
+  registryHost?: string;
+  /** Requested package names; the server sanitizes each per P6.1 and caps the array. */
+  packages: string[];
+  /** HTTP status from the failed registry fetch, when known. */
+  httpStatus?: number;
+  /** Underlying npm/pnpm error code (e.g. E404), when known. Server caps length. */
+  npmErrorCode?: string;
+  /**
+   * Which controlled install path produced the block. The server allowlists
+   * against `NPM_INSTALL_RUNNERS` and drops any other value.
+   */
+  runner?: string;
+  /** Epoch ms when the block occurred (client clock). */
+  occurredAt: number;
+  // application attribution: NOT a wire field. The server derives it from the
+  // trusted scoped-JWT claim (`ctx.jwtClaims.app_id`) — a payload-controlled
+  // value would let any authenticated caller forge audit rows against another
+  // app in the same org.
+}

package/src/types/billing/billing.ts

@@ -22,10 +22,21 @@ const ENTERPRISE_LIKE_PLANS: ReadonlySet<BillingPlan> = new Set([
 
 const TRIAL_LIKE_PLANS: ReadonlySet<BillingPlan> = new Set([BillingPlan.TRIAL, BillingPlan.FREE]);
 
+/**
+ * Plans entitled to the Policy Gates MVP. The MVP rollout is limited to
+ * enterprise (and POC) orgs, so this is intentionally narrower than
+ * {@link isEnterpriseLikePlan} (which also covers legacy PRO/STARTER).
+ */
+const POLICY_GATES_ENTITLED_PLANS: ReadonlySet<BillingPlan> = new Set([BillingPlan.ENTERPRISE, BillingPlan.POC]);
+
 export function isEnterpriseLikePlan(plan: BillingPlan | undefined | null): boolean {
   return plan != null && ENTERPRISE_LIKE_PLANS.has(plan);
 }
 
+export function isPolicyGatesEntitledPlan(plan: BillingPlan | undefined | null): boolean {
+  return plan != null && POLICY_GATES_ENTITLED_PLANS.has(plan);
+}
+
 export function isTrialLikePlan(plan: BillingPlan | undefined | null): boolean {
   return plan != null && TRIAL_LIKE_PLANS.has(plan);
 }

package/src/types/billing/index.ts

@@ -1,2 +1,3 @@
 export * from './freeCreditsTier.js';
 export * from './billing.js';
+export * from './spendAlert.js';

package/src/types/billing/spendAlert.ts

@@ -0,0 +1,84 @@
+/**
+ * Spend Alerts — proactive billing alerts admins configure on /spending.
+ *
+ * Wire types shared between client (RTK Query slice in reduxApi/billing) and
+ * server (/v1/billing/spend-alerts controller). The DB stores `thresholds`
+ * and `recipients` as JSONB blobs whose shape matches these types exactly —
+ * see migration 1778896201000-create-spend-alert-table.
+ */
+
+export type SpendAlertType = 'org_spend' | 'per_user_spend' | 'overage_spend' | 'refill_spend';
+
+/**
+ * Unit identifier stored in `threshold.unit`. The client-side modal maps
+ * these to human labels (% of monthly usage / credits used / etc.); the
+ * server treats them opaquely for v1 (no evaluation yet).
+ *
+ * Adding a new unit requires an update here AND on the server-side enum
+ * in `validateThresholdUnit` so persistence rejects unknown values rather
+ * than silently storing them.
+ */
+export type SpendAlertThresholdUnit =
+  // Org spend
+  | 'percent'
+  | 'credits_used'
+  | 'dollars_spent'
+  // Per-user spend
+  | 'credits'
+  | 'dollars'
+  // Overage spend
+  | 'overage_credits'
+  | 'overage_dollars'
+  // Refill spend. Credit-denominated — every refill-eligible plan
+  // (TEAMS / POC) is credit-based, so there's no dollar variant.
+  | 'refill_credits';
+
+export interface SpendAlertThreshold {
+  /** Positive number. Server validates this is > 0. */
+  value: number;
+  unit: SpendAlertThresholdUnit;
+}
+
+export type SpendAlertRecipientKind =
+  /** Everyone with admin role on the org. Resolved at dispatch time. */
+  | 'all_admins'
+  /**
+   * Per-user alerts only. The user whose usage crossed the threshold.
+   * Resolved at dispatch time — not stored as a user_id, since the
+   * recipient depends on which user fired the alert.
+   */
+  | 'triggering_user'
+  /** Specific user by id. Resolved against the user table at dispatch. */
+  | 'user';
+
+export interface SpendAlertRecipient {
+  kind: SpendAlertRecipientKind;
+  /** Required when kind === 'user'. Ignored for other kinds. */
+  userId?: string;
+}
+
+export interface SpendAlertDto {
+  id: string;
+  organizationId: string;
+  alertType: SpendAlertType;
+  thresholds: SpendAlertThreshold[];
+  recipients: SpendAlertRecipient[];
+  created: string;
+  updated: string;
+}
+
+export interface CreateSpendAlertBody {
+  alertType: SpendAlertType;
+  thresholds: SpendAlertThreshold[];
+  recipients: SpendAlertRecipient[];
+}
+
+export type UpdateSpendAlertBody = Partial<Pick<CreateSpendAlertBody, 'thresholds' | 'recipients'>>;
+
+export interface ListSpendAlertsResponseBody {
+  alerts: SpendAlertDto[];
+}
+
+export interface SpendAlertResponseBody {
+  alert: SpendAlertDto;
+}

package/src/types/policyGate/index.ts

@@ -1,3 +1,6 @@
+// Single source of truth for the built-in security scan surfaces; flip to `true` to restore the security-scan UI and execution.
+export const SECURITY_SCANS_ENABLED: boolean = false;
+
 export type PolicyGateReadinessAction =
   | 'contact_admin'
   | 'fix_with_clark'
@@ -16,7 +19,11 @@ export type PolicyGateReadinessFindingSummary = {
 
 export type PolicyGateReadinessFinding = {
   blocking: boolean;
+  humanSummary?: string | null;
+  locationsJson?: unknown[];
+  remediationHintJson?: Record<string, unknown>;
   severity: 'critical' | 'high' | 'info' | 'low' | 'medium';
+  technicalSummary?: string | null;
   title: string;
 };
 
@@ -48,10 +55,24 @@ export type PolicyGateReadinessItem = {
   policyVersionId: string;
   progress?: PolicyGateScanProgress;
   reviewRunId?: string;
+  runs?: PolicyGateReadinessRun[];
   staleReason?: string;
   status: PolicyGateReadinessItemStatus;
 };
 
+export type PolicyGateReadinessRun = {
+  completedAt?: string;
+  createdAt?: string;
+  decision: 'advisory_allowed' | 'allowed' | 'blocked' | 'error_blocked' | 'not_applicable' | null;
+  errorCode?: string;
+  errorMessage?: string;
+  findingSummary: PolicyGateReadinessFindingSummary;
+  reviewRunId: string;
+  startedAt?: string;
+  staleReason?: string | null;
+  status: PolicyGateReadinessItemStatus;
+};
+
 export type PolicyGateReadinessItemStatus =
   | 'advisory_findings'
   | 'approval_required'
@@ -75,3 +96,10 @@ export type PolicyGateReadinessTarget = {
   commitId: string;
   directoryContentsHash: string | null;
 };
+
+/**
+ * Stable error code used in BadRequestError messages when a deploy is rejected
+ * due to unresolved policy gate findings. Both server and client reference this
+ * constant so the contract doesn't rely on fragile string matching.
+ */
+export const POLICY_GATE_BLOCKED_ERROR = 'POLICY_GATE_BLOCKED';