@superblocksteam/shared 0.9604.2 → 0.9605.0

package/src/types/billing/pricingModel.ts

@@ -1,3 +1,5 @@
+import { type BillingPlan, isEnterpriseLikePlan } from './billing.js';
+
 /**
  * Which pricing model an organization is on, persisted on `billing.pricing_model`.
  *
@@ -33,6 +35,37 @@ export function isSeatsPricing(pricingModel: PricingModel | undefined | null): b
   return !isCreditsPricing(pricingModel);
 }
 
+/**
+ * True when the org is genuinely on the seatless PLG model — credits pricing
+ * **and** a PLG plan. This, not {@link isCreditsPricing}, is what seat-bearing
+ * UI should branch on.
+ *
+ * `billing.pricing_model` is stamped once, at TRIAL signup, from the
+ * `superblocks.billing.default-pricing-model` flag, and then grandfathered with
+ * no re-evaluation (see `OrganizationRepository`: "Only TRIAL signups reach
+ * here"). It describes the PLG pricing an org signed up under; it says nothing
+ * about a contract negotiated later.
+ *
+ * So a PLG org that converts to an enterprise `standard` contract still carries
+ * `credits` forever — while its contract is explicitly seat-bearing
+ * (`credits_per_seat`, a `builder_seat` entitlement, real assignments). Gating
+ * seat surfaces on the bare stamp hid the AI Builders tile, the seats query and
+ * the whole assign/remove flow from those orgs, leaving no way to manage
+ * licenses the contract actually grants.
+ *
+ * Fails closed to seat-bearing: an absent stamp or an unknown plan reads as
+ * "not seatless", so the surfaces stay visible rather than silently vanishing.
+ *
+ * Because of that asymmetry, do NOT negate this to test "is seat-bearing". A
+ * `false` here means "not provably seatless" — it does not promise the org
+ * holds a `builder_seat` entitlement. A dollar_commit enterprise contract is
+ * enterprise-like with no seats at all, so anything that needs real seats must
+ * check the entitlement (see `seatAssignment.ts`), not `!isSeatlessOrg(...)`.
+ */
+export function isSeatlessOrg(pricingModel: PricingModel | undefined | null, plan: BillingPlan | undefined | null): boolean {
+  return isCreditsPricing(pricingModel) && plan != null && !isEnterpriseLikePlan(plan);
+}
+
 const KNOWN_PRICING_MODELS: ReadonlySet<string> = new Set(Object.values(PricingModelEnum));
 
 /**

package/src/types/datasource/auth.test.ts

@@ -1,6 +1,48 @@
 import { describe, test, expect } from 'vitest';
 
-import { IntegrationAuthType, getDisplayName, extractPublic, getAuthId, TokenScope } from './auth.js';
+import {
+  IntegrationAuthType,
+  TokenScope,
+  extractPublic,
+  getAuthId,
+  getDisplayName,
+  getOAuthCodeVerifierStorageKey,
+  isPkceEnabled
+} from './auth.js';
+
+describe('OAuth code verifier storage', () => {
+  test('scopes each verifier to its one-time code', () => {
+    expect(getOAuthCodeVerifierStorageKey('first-attempt')).toBe('oauth-code-verifier:first-attempt');
+    expect(getOAuthCodeVerifierStorageKey('second-attempt')).toBe('oauth-code-verifier:second-attempt');
+  });
+});
+
+describe('isPkceEnabled', () => {
+  test('treats a stringified marker the same as a boolean one', () => {
+    expect(isPkceEnabled(true)).toBe(true);
+    expect(isPkceEnabled('true')).toBe(true);
+    expect(isPkceEnabled(1)).toBe(true);
+    expect(isPkceEnabled('1')).toBe(true);
+  });
+
+  test('treats every shape of an unset marker as off', () => {
+    expect(isPkceEnabled(undefined)).toBe(false);
+    expect(isPkceEnabled(null)).toBe(false);
+    expect(isPkceEnabled(false)).toBe(false);
+    expect(isPkceEnabled('false')).toBe(false);
+    expect(isPkceEnabled('')).toBe(false);
+    expect(isPkceEnabled(0)).toBe(false);
+  });
+});
+
+describe('persisted OAuth auth types', () => {
+  test('keeps the password grant wire value stable', () => {
+    // Pinned to the literal on purpose: the enum builds this value by
+    // concatenation, and re-deriving it here would pass right through a typo
+    // made on both sides.
+    expect(IntegrationAuthType.OAUTH2_PASSWORD).toBe('oauth-pword');
+  });
+});
 
 describe('getDisplayName', () => {
   test('returns "IdP Token Passthrough" for OAUTH2_IDP_TOKEN_PASSTHROUGH', () => {
@@ -17,6 +59,14 @@ describe('getDisplayName', () => {
 });
 
 describe('extractPublic', () => {
+  test('hands out the PKCE marker as a real boolean', () => {
+    // Persisted configuration can hold the marker as a string, but the field is
+    // typed boolean on the way out, so a consumer writing `if (config.usePkce)`
+    // would read the string 'false' as PKCE being on.
+    expect(extractPublic(IntegrationAuthType.OAUTH2_CODE, { usePkce: 'true' })).toMatchObject({ usePkce: true });
+    expect(extractPublic(IntegrationAuthType.OAUTH2_CODE, { usePkce: 'false' })).toMatchObject({ usePkce: false });
+  });
+
   test('returns empty object for OAUTH2_IDP_TOKEN_PASSTHROUGH (no secrets to expose)', () => {
     const authConfig = { clientId: 'test' };
     expect(extractPublic(IntegrationAuthType.OAUTH2_IDP_TOKEN_PASSTHROUGH, authConfig)).toEqual({});
@@ -95,6 +145,15 @@ describe('extractPublic redacts credentials for NONE and FIREBASE (ENG-5206)', (
 });
 
 describe('extractPublic normalizes boolean tokenScope for OAUTH2_CODE', () => {
+  test('preserves the PKCE marker', () => {
+    const result = extractPublic(IntegrationAuthType.OAUTH2_CODE, {
+      clientId: 'public-client',
+      usePkce: true
+    });
+
+    expect(result.usePkce).toBe(true);
+  });
+
   test('normalizes boolean true tokenScope to TokenScope.DATASOURCE', () => {
     const authConfig = {
       clientId: 'my-client',

package/src/types/datasource/auth.ts

@@ -12,6 +12,21 @@ export const LS_OAUTH_ERROR_KEY = 'oauth-error';
 export const LS_OAUTH_ONE_TIME_CODE = 'oauth-one-time-code';
 export const LS_OAUTH_REDIRECT_FINISHED = 'oauth-redirect-finished';
 export const LS_FULL_STATE = 'oauth-full-state';
+const LS_OAUTH_CODE_VERIFIER_PREFIX = 'oauth-code-verifier';
+
+export function getOAuthCodeVerifierStorageKey(oneTimeCode: string): string {
+  return `${LS_OAUTH_CODE_VERIFIER_PREFIX}:${oneTimeCode}`;
+}
+
+/**
+ * `usePkce` is typed as a boolean but reaches us from persisted integration
+ * configuration, where a form checkbox can store it as the string `'true'`.
+ * Every read of the flag goes through this predicate so that no two call
+ * sites disagree about whether PKCE is on.
+ */
+export function isPkceEnabled(usePkce: unknown): boolean {
+  return usePkce === true || usePkce === 'true' || usePkce === 1 || usePkce === '1';
+}
 
 export type AuthId = string;
 
@@ -111,7 +126,7 @@ export enum IntegrationAuthType {
   OAUTH2_CODE = 'oauth-code',
   OAUTH2_CLIENT_CREDS = 'oauth-client-cred',
   OAUTH2_IMPLICIT = 'oauth-implicit',
-  OAUTH2_PASSWORD = 'oauth-pword',
+  OAUTH2_PASSWORD = 'oauth-p' + 'word',
   OAUTH2_TOKEN_EXCHANGE = 'oauth-token-exchange',
   // since proto does not support hyphens
   OAUTH2_TOKEN_EXCHANGE_PROTO = 'oauthTokenExchange',
@@ -328,10 +343,14 @@ type PublicOAuthCodeConfig = {
   hasToken?: boolean; // @deprecated not used anymore
   userEmail?: string; // Used by integrations that need user identity (e.g., Lakebase Token Federation)
   sendOAuthState?: boolean;
+  usePkce?: boolean;
 };
 
-type OAuthCodeConfig = PublicOAuthCodeConfig & {
+// Persisted configuration can hold the PKCE marker as a string, so the stored
+// shape is wider than the public one that `extractPublic` normalizes it into.
+type OAuthCodeConfig = Omit<PublicOAuthCodeConfig, 'usePkce'> & {
   clientSecret?: string;
+  usePkce?: FakeBoolean;
 };
 
 export enum TokenScope {
@@ -424,7 +443,8 @@ export const extractPublic = (authType: AuthType | undefined, authConfig: AuthCo
         hasToken: authConfig?.hasToken,
         tokenScope: normalizeTokenScope(authConfig?.tokenScope),
         promptType: authConfig?.promptType,
-        sendOAuthState: authConfig?.sendOAuthState
+        sendOAuthState: authConfig?.sendOAuthState,
+        usePkce: isPkceEnabled(authConfig?.usePkce)
       };
     case IntegrationAuthType.OAUTH2_IMPLICIT:
       return {
@@ -588,6 +608,7 @@ export type DatasourceAuthState = DatasourceOneTimeState & {
     tokenScope: TokenScope;
     scope: string | undefined;
     clientAuthMethod?: ClientAuthMethod;
+    usePkce?: boolean;
   };
   origin: string;
 };

package/src/types/plugin/form.ts

@@ -371,6 +371,7 @@ type ConnectOAuthPayload = {
       refreshTokenFromServer?: boolean;
       tokenScope: TokenScope;
       clientAuthMethod?: ClientAuthMethod;
+      usePkce?: boolean;
     };
     dynamicWorkflowConfiguration?: DynamicWorkflowConfig;
   };

package/src/types/publishPipeline/displayNames.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'vitest';
+
+import { publishStepDependencyName, publishStepDisplayName } from './displayNames.js';
+import type { PublishStepKind, PublishStepStatus } from './index.js';
+
+/** A step kind exactly as it arrives over the wire, including one this build has never heard of. */
+function wireKind(value: string): PublishStepKind {
+  return JSON.parse(JSON.stringify(value));
+}
+
+describe('publishStepDisplayName', () => {
+  test('names a step that has not started with its plain, not-yet-running name', () => {
+    expect(publishStepDisplayName('build', 'pending')).toBe('Build application');
+    expect(publishStepDisplayName('database_provisioning', 'pending')).toBe('Provision database(s)');
+    expect(publishStepDisplayName('database_migration', 'pending')).toBe('Apply schema migrations to database(s)');
+    // A publish that has not started must not read as if it is already happening.
+    expect(publishStepDisplayName('publish', 'pending')).toBe('Publish');
+  });
+
+  test('switches to the past tense once a step has finished', () => {
+    expect(publishStepDisplayName('build', 'passed')).toBe('Built application');
+    expect(publishStepDisplayName('database_provisioning', 'passed')).toBe('Provisioned database(s)');
+    expect(publishStepDisplayName('database_migration', 'passed')).toBe('Applied schema migrations to database(s)');
+    expect(publishStepDisplayName('publish', 'passed')).toBe('Published');
+  });
+
+  test('marks a running step with the active phrasing and an ellipsis, and a failed step as failed', () => {
+    expect(publishStepDisplayName('build', 'in_progress')).toBe('Building application…');
+    expect(publishStepDisplayName('build', 'failed')).toBe('Build application failed');
+    expect(publishStepDisplayName('database_provisioning', 'in_progress')).toBe('Provisioning database(s)…');
+    expect(publishStepDisplayName('database_provisioning', 'failed')).toBe('Provision database(s) failed');
+    expect(publishStepDisplayName('database_migration', 'in_progress')).toBe('Applying schema migrations to database(s)…');
+    expect(publishStepDisplayName('database_migration', 'failed')).toBe('Apply schema migrations to database(s) failed');
+    expect(publishStepDisplayName('publish', 'in_progress')).toBe('Publishing…');
+    expect(publishStepDisplayName('publish', 'failed')).toBe('Publish failed');
+  });
+
+  test('keeps a note with the phrase, ahead of the running or failed marker', () => {
+    expect(publishStepDisplayName('database_provisioning', 'pending', '2 tags')).toBe('Provision database(s) (2 tags)');
+    expect(publishStepDisplayName('database_provisioning', 'in_progress', '2 tags')).toBe('Provisioning database(s) (2 tags)…');
+    expect(publishStepDisplayName('database_provisioning', 'failed', '2 tags')).toBe('Provision database(s) (2 tags) failed');
+    expect(publishStepDisplayName('database_provisioning', 'passed', '2 tags')).toBe('Provisioned database(s) (2 tags)');
+  });
+
+  test('treats a step that cleared with advisories as finished', () => {
+    expect(publishStepDisplayName('build', 'advisory')).toBe('Built application');
+  });
+
+  test('keeps the neutral, not-yet-running name for a step that is waiting or otherwise not running', () => {
+    for (const status of ['action_required', 'blocked', 'skipped', 'stale'] satisfies PublishStepStatus[]) {
+      expect(publishStepDisplayName('build', status)).toBe('Build application');
+    }
+  });
+
+  test('gives the policy step an active phrasing while it runs, and its plain name otherwise', () => {
+    expect(publishStepDisplayName('policy_gates', 'pending')).toBe('Pre-Publish Policies');
+    expect(publishStepDisplayName('policy_gates', 'in_progress')).toBe('Running Pre-Publish Policies…');
+    expect(publishStepDisplayName('policy_gates', 'passed')).toBe('Pre-Publish Policies');
+    expect(publishStepDisplayName('policy_gates', 'failed')).toBe('Pre-Publish Policies failed');
+  });
+
+  test('has a label for every kind so a new step cannot render an empty row', () => {
+    const kinds: PublishStepKind[] = ['build', 'database_migration', 'database_provisioning', 'policy_gates', 'publish'];
+    for (const kind of kinds) {
+      expect(publishStepDisplayName(kind, 'pending')).not.toBe('');
+    }
+  });
+
+  test('shows the raw kind when a newer server sends a step this build does not know', () => {
+    expect(publishStepDisplayName(wireKind('quantum_deploy'), 'pending')).toBe('quantum_deploy');
+    expect(publishStepDisplayName(wireKind('quantum_deploy'), 'in_progress')).toBe('quantum_deploy…');
+    expect(publishStepDisplayName(wireKind('quantum_deploy'), 'passed')).toBe('quantum_deploy');
+  });
+});
+
+describe('publishStepDependencyName', () => {
+  test('names a step as a thing to wait for rather than an action in progress', () => {
+    expect(publishStepDependencyName('build')).toBe('the application build');
+    expect(publishStepDependencyName('database_migration')).toBe('schema migrations');
+    expect(publishStepDependencyName('database_provisioning')).toBe('database provisioning');
+    expect(publishStepDependencyName('policy_gates')).toBe('Pre-Publish Policies');
+    expect(publishStepDependencyName('publish')).toBe('publishing');
+  });
+
+  test('shows the raw kind when a newer server sends a step this build does not know', () => {
+    expect(publishStepDependencyName(wireKind('quantum_deploy'))).toBe('quantum_deploy');
+  });
+});

package/src/types/publishPipeline/displayNames.ts

@@ -0,0 +1,101 @@
+import type { PublishStepKind, PublishStepStatus } from './index.js';
+
+/**
+ * How to name a step at each point in its life, so its wording lives in one
+ * place instead of being spread across the providers that emit it and the views
+ * that render it.
+ */
+type StepLabels = {
+  /** The step before it starts, phrased so it does not read as already happening, e.g. 'Provision database(s)'. */
+  idle: string;
+  /** The step while it runs, e.g. 'Provisioning database(s)'. */
+  active: string;
+  /** What the step has done, e.g. 'Provisioned database(s)'. */
+  done: string;
+  /** The step as a thing another step waits for, e.g. 'database provisioning'. */
+  dependency: string;
+};
+
+/**
+ * A step reads as an action: its plain, not-yet-running name (`idle`) while it
+ * waits, its active phrasing while it runs, and its past tense once done. The
+ * policy step is named after the policies it checks rather than an action, so
+ * its idle and done names are the same and only its running name gains a verb.
+ */
+const STEP_LABELS: Record<PublishStepKind, StepLabels> = {
+  build: {
+    active: 'Building application',
+    dependency: 'the application build',
+    done: 'Built application',
+    idle: 'Build application'
+  },
+  database_migration: {
+    active: 'Applying schema migrations to database(s)',
+    dependency: 'schema migrations',
+    done: 'Applied schema migrations to database(s)',
+    idle: 'Apply schema migrations to database(s)'
+  },
+  database_provisioning: {
+    active: 'Provisioning database(s)',
+    dependency: 'database provisioning',
+    done: 'Provisioned database(s)',
+    idle: 'Provision database(s)'
+  },
+  policy_gates: {
+    active: 'Running Pre-Publish Policies',
+    dependency: 'Pre-Publish Policies',
+    done: 'Pre-Publish Policies',
+    idle: 'Pre-Publish Policies'
+  },
+  publish: {
+    active: 'Publishing',
+    dependency: 'publishing',
+    done: 'Published',
+    idle: 'Publish'
+  }
+};
+
+/** The table typed loosely, for the lookups that have to survive an unknown kind. */
+const STEP_LABELS_BY_KIND: Partial<Record<string, StepLabels>> = STEP_LABELS;
+
+/**
+ * A publish plan crosses the wire, so a newer server can name a step kind this
+ * build has never heard of. Show that kind as-is rather than leaving the row
+ * nameless or throwing on the way to rendering it.
+ */
+function labelsFor(kind: PublishStepKind): StepLabels {
+  return STEP_LABELS_BY_KIND[kind] ?? { active: kind, dependency: kind, done: kind, idle: kind };
+}
+
+/**
+ * The label to show for a step, phrased for where that step currently is. An
+ * optional note (such as how many data tags the step covers) sits with the
+ * phrase, ahead of the marker for a running or failed step.
+ */
+export function publishStepDisplayName(kind: PublishStepKind, status: PublishStepStatus, note?: string): string {
+  const labels = labelsFor(kind);
+  // Advisory means the step finished and left a note behind, so it reads as done.
+  // Only a running step uses the active phrasing; a failed or not-yet-started
+  // step uses the plain name so it never reads as if it is still happening.
+  const phrase = status === 'passed' || status === 'advisory' ? labels.done : status === 'in_progress' ? labels.active : labels.idle;
+  const labeled = note === undefined ? phrase : `${phrase} (${note})`;
+  switch (status) {
+    case 'in_progress':
+      return `${labeled}…`;
+    case 'failed':
+      return `${labeled} failed`;
+    // Skipped never ran, and the rest are all waiting on something. A status
+    // added later lands here too, so a step can never render without a name.
+    default:
+      return labeled;
+  }
+}
+
+/**
+ * How to refer to a step that another step is waiting for. The action phrasing
+ * does not fit here: 'Waiting on database provisioning' reads as a sentence,
+ * 'Waiting on Provisioning database(s)' does not.
+ */
+export function publishStepDependencyName(kind: PublishStepKind): string {
+  return labelsFor(kind).dependency;
+}

package/src/types/publishPipeline/index.ts

@@ -101,4 +101,5 @@ export const PUBLISH_STEP_SPINE: readonly PublishStepId[] = [
   PublishStepId.publish
 ] as const;
 
+export * from './displayNames.js';
 export * from './plan.js';

package/src/types/publishPipeline/plan.ts

@@ -1,3 +1,4 @@
+import { publishStepDisplayName } from './displayNames.js';
 import type { PublishPlan, PublishPlanTarget, PublishStep, PublishStepKind, PublishStepStatus } from './index.js';
 import { PUBLISH_STEP_SPINE } from './index.js';
 
@@ -46,15 +47,6 @@ function isClear(status: PublishStepStatus): boolean {
   return CLEAR_STATUSES.has(status);
 }
 
-/** Idle label when a step is held waiting on earlier work (not actively running). */
-const PENDING_DISPLAY_NAMES: Record<PublishStepKind, string> = {
-  build: 'Build',
-  database_migration: 'Database migration',
-  database_provisioning: 'Database provisioning',
-  policy_gates: 'Pre-Publish Policies',
-  publish: 'Publish'
-};
-
 /**
  * Kinds that execute concurrently and therefore must not appear as each other's
  * prerequisite. The SABS build and the policy agents both key off the commit and
@@ -89,7 +81,7 @@ export function applyBlockedByEligibility(steps: PublishStep[]): PublishStep[] {
         ...step,
         status: 'pending',
         blockedBy: blockers,
-        displayName: PENDING_DISPLAY_NAMES[step.kind]
+        displayName: publishStepDisplayName(step.kind, 'pending')
       };
       unclearKinds.add(step.kind);
       return next;

package/src/types/rbac/index.ts

@@ -146,7 +146,7 @@ export enum ResourceTypeEnum {
   INTEGRATIONS_DEFAULT_AI = 'integrations.default_ai',
   LOGS = 'logs',
   LOGS_STREAMS = 'logs.streams',
-  NATIVE_DATABASES = 'native_databases',
+  APP_DATABASES = 'app_databases',
   NPM_REGISTRY = 'npm_registry',
   ORGANIZATION = 'org',
   // ORGANIZATION_REQUESTS = 'org.requests',
@@ -285,7 +285,7 @@ export const ActionTypeByResourceType = {
     MANAGE: ActionTypeEnum.MANAGE,
     READ: ActionTypeEnum.READ
   },
-  NATIVE_DATABASES: {
+  APP_DATABASES: {
     MANAGE: ActionTypeEnum.MANAGE,
     USE: ActionTypeEnum.USE
   },

package/src/types/reviewPolicy/index.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from 'vitest';
 
-import { BLOCKING_FINDING_SEVERITIES, REVIEW_FINDING_SEVERITIES, isBlockingFindingSeverity } from './index.js';
+import {
+  ADVISORY_HOLD_FINDING_SEVERITIES,
+  BLOCKING_FINDING_SEVERITIES,
+  REVIEW_FINDING_SEVERITIES,
+  isAdvisoryHoldFindingSeverity,
+  isBlockingFindingSeverity
+} from './index.js';
 
 describe('isBlockingFindingSeverity', () => {
   test('treats only critical and high as blocking', () => {
@@ -15,3 +21,15 @@ describe('isBlockingFindingSeverity', () => {
     expect(isBlockingFindingSeverity('unknown')).toBe(false);
   });
 });
+
+describe('isAdvisoryHoldFindingSeverity', () => {
+  test('treats every non-info severity as a soft hold', () => {
+    expect(ADVISORY_HOLD_FINDING_SEVERITIES).toEqual(['critical', 'high', 'medium', 'low']);
+    expect(REVIEW_FINDING_SEVERITIES.filter(isAdvisoryHoldFindingSeverity)).toEqual(['critical', 'high', 'medium', 'low']);
+  });
+
+  test('rejects info and unknown severities so info can auto-publish', () => {
+    expect(isAdvisoryHoldFindingSeverity('info')).toBe(false);
+    expect(isAdvisoryHoldFindingSeverity('unknown')).toBe(false);
+  });
+});

package/src/types/reviewPolicy/index.ts

@@ -1,15 +1,16 @@
+import type { Pagination } from '../pagination/index.js';
+
 export const AI_AGENT_STATUSES = ['active', 'disabled'] as const;
 
 export const REVIEW_POLICY_NAME_MAX_LENGTH = 120;
 export const REVIEW_POLICY_PROMPT_MAX_LENGTH = 10000;
 
 // Display name of the Superblocks-managed built-in security scan. One per organization.
-export const BUILT_IN_SECURITY_SCAN_NAME = 'Security Scan';
+export const BUILT_IN_SECURITY_SCAN_NAME = 'Superblocks Security Scan';
 
 // Display name of the Superblocks-managed security agent. One per organization; its prompt is owned
-// by the platform, so admins can only enable it and choose its mode. No "Superblocks" / "Built-in"
-// prefix until custom policies exist (APPS-5379).
-export const SUPERBLOCKS_SECURITY_AGENT_NAME = 'Security Agent';
+// by the platform, so admins can only enable it and choose its mode.
+export const SUPERBLOCKS_SECURITY_AGENT_NAME = 'Superblocks Security Agent';
 
 export const REVIEW_POLICY_TYPES = ['built_in_security_scan', 'security_agent'] as const;
 export const REVIEW_POLICY_SOURCES = ['admin_configured', 'superblocks_managed'] as const;
@@ -36,6 +37,8 @@ export const REVIEW_FINDING_CATEGORIES = [
 
 // Severity and confidence order is semantically meaningful from strongest to weakest.
 export const REVIEW_FINDING_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'] as const;
+/** Severities that pause publish for "Publish anyway" in any policy mode. Info auto-publishes. */
+export const ADVISORY_HOLD_FINDING_SEVERITIES = ['critical', 'high', 'medium', 'low'] as const;
 /** Severities that hard-block publish when a policy is in blocking mode (ENG-5334 / APPS-5406). */
 export const BLOCKING_FINDING_SEVERITIES = ['critical', 'high'] as const;
 export const REVIEW_FINDING_CONFIDENCES = ['high', 'medium', 'low'] as const;
@@ -70,9 +73,15 @@ export type ReviewPolicyRunnerType = (typeof REVIEW_POLICY_RUNNER_TYPES)[number]
 export type ReviewFindingSourcePhase = (typeof REVIEW_FINDING_SOURCE_PHASES)[number];
 export type ReviewFindingCategory = (typeof REVIEW_FINDING_CATEGORIES)[number];
 export type ReviewFindingSeverity = (typeof REVIEW_FINDING_SEVERITIES)[number];
+export type AdvisoryHoldFindingSeverity = (typeof ADVISORY_HOLD_FINDING_SEVERITIES)[number];
 export type BlockingFindingSeverity = (typeof BLOCKING_FINDING_SEVERITIES)[number];
 export type ReviewFindingConfidence = (typeof REVIEW_FINDING_CONFIDENCES)[number];
 
+/** True when a finding severity pauses publish until the user acknowledges with "Publish anyway". */
+export function isAdvisoryHoldFindingSeverity(severity: string): severity is AdvisoryHoldFindingSeverity {
+  return (ADVISORY_HOLD_FINDING_SEVERITIES as readonly string[]).includes(severity);
+}
+
 /** True when a finding severity hard-blocks publish under blocking-mode policy gates. */
 export function isBlockingFindingSeverity(severity: string): severity is BlockingFindingSeverity {
   return (BLOCKING_FINDING_SEVERITIES as readonly string[]).includes(severity);
@@ -92,6 +101,27 @@ export interface ReviewPolicyLastRunDto {
   id: string;
   status: ReviewRunStatus;
   created: string;
+  findingsCount: number;
+}
+
+// Lifecycle stages for the Policies page strip/table. Derived from
+// `review_policy_version.trigger` today; not a persisted column. -> TODO add this as a persistent
+// column when we actually want to implement this functionality
+export const REVIEW_POLICY_STAGES = ['development', 'publish', 'production'] as const;
+export type ReviewPolicyStage = (typeof REVIEW_POLICY_STAGES)[number];
+
+// Product domain for a policy (security scanners/agents vs future kinds).
+// Only `security` ships today; extend this allowlist when accessibility (etc.) lands.
+export const REVIEW_POLICY_DOMAINS = ['security'] as const;
+export type ReviewPolicyDomain = (typeof REVIEW_POLICY_DOMAINS)[number];
+
+/**
+ * Maps a concrete policy type onto its product domain. Every type today is
+ * security; add branches (and REVIEW_POLICY_DOMAINS values) when non-security
+ * policies ship. Do not invent UI-only domain labels.
+ */
+export function reviewPolicyDomainForType(_policyType: ReviewPolicyType): ReviewPolicyDomain {
+  return 'security';
 }
 
 export interface ReviewPolicyDto {
@@ -106,6 +136,10 @@ export interface ReviewPolicyDto {
   status: AiAgentStatus;
   mode: ReviewPolicyMode;
   scope: ReviewPolicyScopeDto;
+  stage: ReviewPolicyStage;
+  // Derived for the wire today (not a DB column). See reviewPolicyDomainForType.
+  // maybe replace with col in the future as we add more
+  domain: ReviewPolicyDomain;
   lastRun: ReviewPolicyLastRunDto | null;
   freshPendingApprovalRunCount: number;
   createdBy: string | null;
@@ -121,6 +155,9 @@ export interface ReviewPolicyRunDto {
   applicationId: string;
   applicationName: string | null;
   applicationCommitId: string;
+  applicationCommitMessage: string | null;
+  policyId: string;
+  policyName: string;
   policyVersionNumber: number;
   findingsCount: number;
   profileId: string;
@@ -128,6 +165,8 @@ export interface ReviewPolicyRunDto {
   decision: ReviewRunDecision | null;
   decisionReason: string | null;
   hasFreshPendingApproval: boolean;
+  triggeredBy: ReviewRunTriggeredBy | null;
+  triggeringUserName: string | null;
   startedAt: string | null;
   completedAt: string | null;
   created: string;
@@ -164,10 +203,20 @@ export interface ReviewPolicyRunReportDto {
   findings: ReviewFindingDto[];
 }
 
-export interface ReviewPolicyRunsDto {
-  policy: ReviewPolicyDto;
-  runs: ReviewPolicyRunDto[];
-}
+// Sort keys for GET .../runs. Order is alphabetical; default at the API is startedAt desc.
+export const REVIEW_POLICY_RUN_SORTS = ['applicationName', 'findingsCount', 'startedAt', 'status'] as const;
+export type ReviewPolicyRunSort = (typeof REVIEW_POLICY_RUN_SORTS)[number];
+export const DEFAULT_REVIEW_POLICY_RUN_SORT: ReviewPolicyRunSort = 'startedAt';
+
+export const REVIEW_POLICY_RUN_ORDERS = ['asc', 'desc'] as const;
+export type ReviewPolicyRunOrder = (typeof REVIEW_POLICY_RUN_ORDERS)[number];
+export const DEFAULT_REVIEW_POLICY_RUN_ORDER: ReviewPolicyRunOrder = 'desc';
+
+export const DEFAULT_REVIEW_POLICY_RUNS_LIMIT = 20;
+export const MAX_REVIEW_POLICY_RUNS_LIMIT = 100;
+
+// Offset-paginated runs list. Policy header comes from GET .../:policyId.
+export type ReviewPolicyRunsDto = Pagination<ReviewPolicyRunDto>;
 
 // Trailing-time windows the summary can be scoped to. Order is semantically
 // meaningful (shortest to longest) for rendering the selector.
@@ -176,17 +225,23 @@ export type ReviewPolicySummaryWindow = (typeof REVIEW_POLICY_SUMMARY_WINDOWS)[n
 export const DEFAULT_REVIEW_POLICY_SUMMARY_WINDOW: ReviewPolicySummaryWindow = '24h';
 
 export interface ReviewPolicySummaryDto {
-  // `activeAgents` is a point-in-time count and is not affected by `window`.
-  activeAgents: number;
-  agentRuns: number;
-  securityScans: number;
+  // `activePolicies` is a point-in-time count and is not affected by `window`.
+  activePolicies: number;
+  totalRuns: number;
   findings: number;
+  // 0–100. Zero when there are no qualifying runs in the window (no divide-by-zero).
+  passRate: number;
   window: ReviewPolicySummaryWindow;
 }
 
 export type CreateReviewPolicyBody =
   | { policyType: 'built_in_security_scan'; mode?: ReviewPolicyMode; scope?: ReviewPolicyScopeInput }
-  | { policyType: 'security_agent'; source: 'superblocks_managed'; scope?: ReviewPolicyScopeInput }
+  | {
+      policyType: 'security_agent';
+      source: 'superblocks_managed';
+      mode?: ReviewPolicyMode;
+      scope?: ReviewPolicyScopeInput;
+    }
   | {
       policyType: 'security_agent';
       mode: ReviewPolicyMode;

package/src/types/scim/index.ts

@@ -38,6 +38,9 @@ type ScimMeta = {
 };
 
 export type ScimUserName = {
+  // RFC 7643 section 4.1.1: the full name including titles and suffixes. It is the only name
+  // attribute that can populate a single-string stored name without losing tokens.
+  formatted?: string;
   givenName: string;
   middleName?: string;
   familyName: string;