@superblocksteam/shared 0.9603.2 → 0.9604.0

package/src/database-lifecycle/index.ts

@@ -1,43 +1,69 @@
 import { sha256Base64 } from '../signing/hashing.js';
+import { ApiTriggerType } from '../types/api/index.js';
+import type { DatabaseEngine } from './capacityPolicy.js';
 
 export const LIFECYCLE_TERMINAL_STATES = ['ready', 'failed', 'cancelled'] as const;
 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;
-// The environment axis (edit/preview/deployed) lives on the binding, so a
-// single `ensure_database` covers what used to be split into
+// 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;
+// `ensure_physical_database_instance` is claimable pool-level work (wizard /
+// eager provisioning). It is not bound to a database_binding row; the claim
+// payload carries provisioningId instead of binding identity. Appended last
+// because Postgres `ALTER TYPE ... ADD VALUE` appends, and TypeORM's
+// entity-vs-schema check requires this array to match that live order.
+export const LIFECYCLE_OPERATIONS = ['ensure_database', 'migrate_schema', 'retire_database', 'ensure_physical_database_instance'] as const;
 export const DATABASE_LIFECYCLE_MANAGED_BY = 'database_lifecycle';
-export const NATIVE_DB_AUTH_DESCRIPTOR_VERSION = 2 as const;
-export const NATIVE_DB_AUTH_DESCRIPTOR_VERSIONS = [1, NATIVE_DB_AUTH_DESCRIPTOR_VERSION] as const;
+export const NATIVE_DB_AUTH_DESCRIPTOR_VERSION = 3 as const;
 export const NATIVE_DB_CONNECTOR_ROLE_NAME_PREFIX = 'superblocks-native-db-connector';
 export const NATIVE_DB_IAM_AUTH_MODE = 'aws_iam_role' as const;
 export const NATIVE_DB_IDENTIFIER_HASH_DOMAIN = 'superblocks-native-db:v1';
 export const DATABASE_LIFECYCLE_CAPABILITY_MANAGED_IAM_V1 = 'managed-IAM-v1';
 
+export function isLifecycleManagedIntegrationAllowedForApiTrigger(
+  triggerType: ApiTriggerType,
+  managedBy: string | null | undefined
+): boolean {
+  if (managedBy !== DATABASE_LIFECYCLE_MANAGED_BY) {
+    return true;
+  }
+  return triggerType === ApiTriggerType.UI;
+}
+
 // 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".
+// tag map the agent already publishes). The existing `profile` tag carries
+// datatag coverage, same meaning it has for execution routing, and is the
+// sole lifecycle routing key. 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 const DATABASE_LIFECYCLE_TAG_CAPABILITIES = 'databaseLifecycle:capabilities';
+export {
+  CapacityPolicyValidationError,
+  DATABASE_ENGINES,
+  DATABASE_LIFECYCLE_TAG_CAPACITY_POLICIES,
+  PHYSICAL_DATABASE_CAPACITY_THRESHOLD_TYPES,
+  computePhysicalDatabasePoolKey,
+  encodeCapacityPolicyTag,
+  parseCapacityPolicyTag,
+  parseCapacityPolicyTags,
+  validateCapacityPolicyCompatibility,
+  type DatabaseEngine,
+  type PhysicalDatabaseCapacityPolicy,
+  type PhysicalDatabaseCapacityThresholdType,
+  type PhysicalDatabasePoolKey
+} from './capacityPolicy.js';
+// The stable, customer-managed name of the deployment a worker belongs to. It
+// says which physical pool that worker owns, which is what keeps one
+// deployment from being handed work meant for another. The claim path also
+// treats it as the binding-ownership authority, so a client-supplied query
+// value cannot bypass it.
+export { DATABASE_LIFECYCLE_TAG_AGENT_NAME, PhysicalPoolIdentityError, parsePhysicalPoolAgentNameTag } from './physicalPoolIdentity.js';
 
-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];
 export type LifecycleNonTerminalState = (typeof LIFECYCLE_NON_TERMINAL_STATES)[number];
@@ -58,18 +84,15 @@ export type LifecycleErrorCode =
   // the request is cancelled rather than applied to the current binding.
   | 'stale_dispatch';
 
-export const CREDENTIAL_RESOLVERS = ['opa_local', 'aws_secrets_manager', 'gcp_secret_manager', 'vault', 'kubernetes_secret'] as const;
-export type CredentialResolver = (typeof CREDENTIAL_RESOLVERS)[number];
-
-export type CredentialRef = {
-  resolver: CredentialResolver;
+export type PhysicalMasterCredentialRef = {
+  resolver: 'aws_secrets_manager';
   ref: string;
   field?: string;
 };
 
 export type NativeDbIamDescriptor = {
   application_id: string;
-  auth_descriptor_version: (typeof NATIVE_DB_AUTH_DESCRIPTOR_VERSIONS)[number];
+  auth_descriptor_version: typeof NATIVE_DB_AUTH_DESCRIPTOR_VERSION;
   auth_mode: typeof NATIVE_DB_IAM_AUTH_MODE;
   aws_account_id: string;
   binding_id: string;
@@ -98,31 +121,25 @@ type DatabaseBindingBase = {
   requirementKey: string;
   logicalName: string;
   applicationId: 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.
+  // binding serves, and the only axis that scopes it. One profile is one
+  // logical database with one DB user.
   profile: string;
   desiredSpecHash: string;
   migrationState: LifecycleMigrationState;
 };
 
-// A binding that has completed provisioning. The `ready` discriminant
-// guarantees that the OPA returned both `connectionMetadata` and
-// `credentialRefs`, so consumers can rely on those without null checks.
+// A binding that has completed IAM provisioning.
 export type ReadyDatabaseBinding = DatabaseBindingBase & {
   lifecycleState: 'ready';
   connectionMetadata: Record<string, string | number | boolean>;
-  credentialRefs: Record<string, CredentialRef>;
 };
 
-// A binding in any non-ready state. Connection metadata and credential refs
-// may be present from a prior `ready` transition or absent if the binding
-// never reached `ready`.
+// A binding in any non-ready state. Connection metadata may be present from a
+// prior `ready` transition or absent if the binding never reached `ready`.
 export type IncompleteDatabaseBinding = DatabaseBindingBase & {
   lifecycleState: Exclude<LifecycleState, 'ready'>;
   connectionMetadata?: Record<string, string | number | boolean>;
-  credentialRefs?: Record<string, CredentialRef>;
 };
 
 export type DatabaseBinding = ReadyDatabaseBinding | IncompleteDatabaseBinding;
@@ -152,13 +169,15 @@ export type PhysicalDatabaseInstance = {
   id: string;
   organizationId: string;
   region: string;
-  environment: LifecycleEnvironment;
   engine: DatabaseEngine; // postgres-only in V1
   endpoint: string;
-  masterCredentialRef: CredentialRef;
+  masterCredentialRef: PhysicalMasterCredentialRef;
   capacityMax: number;
   capacityUsed: number;
   status: PhysicalDatabaseInstanceStatus;
+  // Stable customer OPA deployment identity that owns this physical pool.
+  // Absent on legacy rows (no backfill); agent-scoped lookups skip those.
+  agentName?: string;
   metadata: Record<string, unknown>;
   created?: Date;
   updated?: Date;
@@ -183,6 +202,57 @@ export type LifecycleDispatchContinuation = {
   reservationId?: string;
 };
 
+// Wizard-facing view of a physical pool provisioning run. Narrower than
+// `LIFECYCLE_STATES` on purpose: the UI only distinguishes "nothing has run"
+// from in-progress, done, and failed. `not_started` is the absence of a row;
+// queued and running both read as `provisioning`.
+export const PHYSICAL_POOL_PROVISIONING_STATUSES = ['not_started', 'provisioning', 'active', 'failed'] as const;
+export type PhysicalPoolProvisioningStatus = (typeof PHYSICAL_POOL_PROVISIONING_STATUSES)[number];
+
+export type PhysicalPoolProvisioningActor = {
+  displayName: string;
+  id: string;
+};
+
+export type PhysicalPoolProvisioningError = {
+  code: string;
+  message: string;
+};
+
+// Stable wizard/admin response for POST/GET physical-pool-provisioning.
+export type PhysicalPoolProvisioningState = {
+  alreadyInProgress?: boolean;
+  completedAt?: string;
+  error?: PhysicalPoolProvisioningError;
+  physicalDatabaseInstanceId?: string;
+  provisioningId?: string;
+  startedAt?: string;
+  startedBy?: PhysicalPoolProvisioningActor;
+  status: PhysicalPoolProvisioningStatus;
+};
+
+// One physical instance as the admin surface reports it. Narrower than
+// `PhysicalDatabaseInstance`: credentials and provider metadata are not part of
+// an admin listing.
+export type PhysicalPoolInstanceSummary = {
+  capacityMax: number;
+  capacityUsed: number;
+  endpoint: string;
+  id: string;
+  region: string;
+  status: PhysicalDatabaseInstanceStatus;
+};
+
+// Every pool an organization has, whether it finished provisioning or not.
+// A pool with no instances is one that is still running or that failed; a pool
+// with instances and no run was provisioned before the wizard existed.
+export type PhysicalPoolSummary = {
+  agentName: string;
+  engine: DatabaseEngine;
+  instances: PhysicalPoolInstanceSummary[];
+  provisioning: PhysicalPoolProvisioningState;
+};
+
 // 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;
@@ -191,13 +261,17 @@ export type LifecycleDispatchContinuation = {
 // 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).
+// the worker's single local lifecycle config, selected by the payload's profile).
 //
 // `migrations` is present iff the operation should consider migration
 // 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.
+//
+// For `ensure_physical_database_instance`, binding identity fields are empty
+// placeholders (the OPA keys the lock on provisioningId) and `provisioningId`
+// is required.
 export type LifecycleDispatchPayload = {
   applicationId: string;
   bindingId: string;
@@ -206,46 +280,46 @@ export type LifecycleDispatchPayload = {
   continuation?: LifecycleDispatchContinuation;
   desiredSpec: DatabaseRequirement;
   desiredSpecHash: string;
-  environment: LifecycleEnvironment;
+  // Emitted only for `ensure_physical_database_instance`, and named to match
+  // the worker's `environment` field. The control plane no longer routes on an
+  // environment, but the worker still validates one before resolving pool
+  // topology and deriving its Terraform state key. It is a fixed value the
+  // server supplies rather than anything a caller picks, and it goes away with
+  // the worker's remaining shims in ENG-5127.
+  environment?: string;
   migrations?: LifecycleMigration[];
   operation: LifecycleOperation;
   profile: string;
+  provisioningId?: string;
   requestId: string;
   resourceKey: string;
-  runtimeCredentialRefs?: Record<string, CredentialRef>;
-  migrationCredentialRefs?: Record<string, CredentialRef>;
 };
 
+export function physicalPoolProvisioningResourceKey(provisioningId: string): string {
+  return `physical-pool-provisioning:${provisioningId}`;
+}
+
 export function computeRequirementKey(requirement: Pick<DatabaseRequirement, 'logicalName' | 'engine'>): string {
   return `${slugify(requirement.logicalName)}~${encodeURIComponent(requirement.logicalName)}:${requirement.engine}`;
 }
 
 // binding_key is the product identity of a database in the control plane, and
-// is deliberately scoped to (organization, application, environment, profile)
-// only — NOT the logical name. This is what makes "one database per profile"
-// enforceable by the plain UNIQUE (binding_key) constraint: asking for another
-// database under a different logical name resolves to the same binding_key
-// instead of minting a new one. The logical name still lives on the binding row
-// and in resource_key (physical identity); it just doesn't grant a second slot.
-export function computeBindingKey(input: {
-  organizationId: string;
-  applicationId: string;
-  environment: LifecycleEnvironment;
-  profile: string;
-}): string {
+// is deliberately scoped to (organization, application, profile) only — NOT the
+// logical name. This is what makes "one database per profile" enforceable by the
+// plain UNIQUE (binding_key) constraint: asking for another database under a
+// different logical name resolves to the same binding_key instead of minting a
+// new one. The logical name still lives on the binding row and in resource_key
+// (physical identity); it just doesn't grant a second slot.
+export function computeBindingKey(input: { organizationId: string; applicationId: string; profile: string }): string {
   return [input.organizationId, ...bindingKeySegments(input)].join(':');
 }
 
-export function computeLegacyBindingKeyWithoutOrganization(input: {
-  applicationId: string;
-  environment: LifecycleEnvironment;
-  profile: string;
-}): string {
+export function computeLegacyBindingKeyWithoutOrganization(input: { applicationId: string; profile: string }): string {
   return bindingKeySegments(input).join(':');
 }
 
-function bindingKeySegments(input: { applicationId: string; environment: LifecycleEnvironment; profile: string }): string[] {
-  return [input.applicationId, input.environment, `${slugify(input.profile)}~${encodeURIComponent(input.profile)}`];
+function bindingKeySegments(input: { applicationId: string; profile: string }): string[] {
+  return [input.applicationId, `${slugify(input.profile)}~${encodeURIComponent(input.profile)}`];
 }
 
 // Hashes only the infrastructure spec. migrationDirectory is deliberately
@@ -279,9 +353,9 @@ export function parseNativeDbIamDescriptor(value: unknown): NativeDbIamDescripto
     return undefined;
   }
 
-  const databaseIdentifier = typeof value.database === 'string' ? /^sbndb_([0-9a-f]{12})_([0-9a-f]{24})$/.exec(value.database) : null;
+  const databaseIdentifier = typeof value.database === 'string' ? /^sbndb_([0-9a-f]{16})_([0-9a-f]{24})$/.exec(value.database) : null;
   const usernameIdentifier =
-    typeof value.username === 'string' ? /^sbndb_([0-9a-f]{12})_([0-9a-f]{24})_runtime$/.exec(value.username) : null;
+    typeof value.username === 'string' ? /^sbndb_([0-9a-f]{16})_([0-9a-f]{24})_runtime$/.exec(value.username) : null;
   const connectorRoleArn =
     typeof value.connector_role_arn === 'string'
       ? /^arn:aws:iam::(\d{12}):role\/(?:[\w+=,.@-]+\/)*[\w+=,.@-]+$/.exec(value.connector_role_arn)
@@ -300,7 +374,7 @@ export function parseNativeDbIamDescriptor(value: unknown): NativeDbIamDescripto
     !databaseIdentifier ||
     !usernameIdentifier ||
     databaseIdentifier[1] !== usernameIdentifier[1] ||
-    (value.auth_descriptor_version === NATIVE_DB_AUTH_DESCRIPTOR_VERSION && databaseIdentifier[2] !== usernameIdentifier[2]) ||
+    usernameIdentifier[0] !== databaseIdentifier[0] + '_runtime' ||
     !isValidNativeDbRdsHostname(value.host, value.region) ||
     typeof value.port !== 'number' ||
     !Number.isInteger(value.port) ||
@@ -331,18 +405,15 @@ export async function computeNativeDbApplicationToken(trustedApplicationId: stri
   return (await computeNativeDbIdentifierToken('application', trustedApplicationId)).slice(0, 24);
 }
 
-export async function computeNativeDbBindingToken(trustedBindingId: string): Promise<string> {
-  return (await computeNativeDbIdentifierToken('database', trustedBindingId)).slice(0, 24);
-}
-
-export async function computeNativeDbDatabaseName(deploymentToken: string, trustedDatabaseId: string): Promise<string> {
-  if (!/^[0-9a-f]{12}$/.test(deploymentToken)) {
-    throw new Error('Native database deployment token must be 12 lowercase hexadecimal characters');
-  }
-  return `sbndb_${deploymentToken}_${await computeNativeDbBindingToken(trustedDatabaseId)}`;
+export async function computeNativeDbProfileToken(profile: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(profile.toLowerCase()));
+  return Array.from(new Uint8Array(digest))
+    .slice(0, 8)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
 }
 
-async function computeNativeDbIdentifierToken(kind: 'application' | 'database', trustedId: string): Promise<string> {
+async function computeNativeDbIdentifierToken(kind: 'application', trustedId: string): Promise<string> {
   if (!isNonEmptyString(trustedId)) {
     throw new Error(`Trusted native database ${kind} ID must be a non-empty string`);
   }
@@ -364,7 +435,6 @@ export function computeResourceKey(input: {
   organizationId: string;
   applicationId: string;
   requirementKey: string;
-  environment: LifecycleEnvironment;
   profile: string;
   actorScope?: string;
 }): string {
@@ -372,7 +442,6 @@ export function computeResourceKey(input: {
     input.organizationId,
     input.applicationId,
     input.requirementKey,
-    input.environment,
     `${slugify(input.profile)}~${encodeURIComponent(input.profile)}`,
     input.actorScope ?? 'default'
   ].join('/');
@@ -424,7 +493,7 @@ function isCommercialAwsRegion(value: unknown): value is string {
 }
 
 function isNativeDbAuthDescriptorVersion(value: unknown): value is NativeDbIamDescriptor['auth_descriptor_version'] {
-  return value === 1 || value === NATIVE_DB_AUTH_DESCRIPTOR_VERSION;
+  return value === NATIVE_DB_AUTH_DESCRIPTOR_VERSION;
 }
 
 function isNonEmptyString(value: unknown): value is string {
@@ -445,20 +514,20 @@ function isValidNativeDbRdsHostname(host: unknown, region: unknown): host is str
   return host.length <= 253 && host === host.toLowerCase() && prefix !== '' && host.split('.').every((label) => validLabel.test(label));
 }
 
-function redact(value: unknown, preserveCredentialRefs = false): unknown {
+function redact(value: unknown, preservePhysicalMasterCredentialRef = false): unknown {
   if (Array.isArray(value)) {
-    return value.map((entry) => redact(entry, preserveCredentialRefs));
+    return value.map((entry) => redact(entry, preservePhysicalMasterCredentialRef));
   }
   if (value && typeof value === 'object') {
     return Object.fromEntries(
       Object.entries(value).map(([key, entryValue]) => {
-        if (isCredentialRefKey(key)) {
+        if (isPhysicalMasterCredentialRefKey(key)) {
           return [key, redact(entryValue, true)];
         }
-        if (!preserveCredentialRefs && SECRET_KEY_PATTERN.test(key)) {
+        if (!preservePhysicalMasterCredentialRef && SECRET_KEY_PATTERN.test(key)) {
           return [key, '[REDACTED]'];
         }
-        return [key, redact(entryValue, preserveCredentialRefs)];
+        return [key, redact(entryValue, preservePhysicalMasterCredentialRef)];
       })
     );
   }
@@ -467,11 +536,9 @@ function redact(value: unknown, preserveCredentialRefs = false): unknown {
 
 // Shared secret-key tripwire: keys whose name strongly suggests a raw secret
 // value. Used by `redactLifecycleSecrets` to scrub logs/error reporting and by
-// the server-side `assertNoRawCredentialMaterial` guard to refuse callbacks
-// that violate the typed-CredentialRef contract. NOT a security boundary --
-// callers must still send `Record<string, string | number | boolean>` for
-// `connectionMetadata` and `CredentialRef` for `credentialRefs`; this catches
-// obvious misuse only.
+// the server-side `assertNoRawCredentialMaterial` guard to refuse callbacks.
+// NOT a security boundary -- callers must still send primitive
+// `connectionMetadata`; this catches obvious misuse only.
 export const SECRET_KEY_PATTERN = /password|secret|token|private[_-]?key|dsn/i;
 
 // Schemes whose URI form embeds credentials before `@`. Used as a value-side
@@ -513,6 +580,6 @@ const DSN_WITH_INLINE_AUTH = new RegExp(`(?:${DSN_SCHEME_GROUP}):\\/\\/[^/@\\s:]
 const CREDENTIAL_KV_PATTERN = /(?:password|pwd|token|secret|private[_-]?key|api[_-]?key)\s*=\s*[^;&\s"]+/i;
 const JSON_ENCODED_SECRET_PATTERN = /["']\s*(?:password|secret|token|private[_-]?key|dsn)\s*["']\s*:/i;
 
-function isCredentialRefKey(key: string): boolean {
-  return /credential[_-]?ref/i.test(key);
+function isPhysicalMasterCredentialRefKey(key: string): boolean {
+  return /^master[_-]?credential[_-]?ref$/i.test(key);
 }

package/src/database-lifecycle/physicalPoolIdentity.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'vitest';
+
+import type { PhysicalDatabaseCapacityPolicy } from './capacityPolicy.js';
+import { PhysicalPoolIdentityError, parsePhysicalPoolAgentNameTag } from './physicalPoolIdentity.js';
+
+const policy = (agentName: string): PhysicalDatabaseCapacityPolicy => ({
+  agentName,
+  engine: 'postgres',
+  thresholdType: 'minAvailableCapacityPercent',
+  thresholdValue: 20
+});
+
+describe('parsePhysicalPoolAgentNameTag', () => {
+  test('reads the pool a deployment named', () => {
+    expect(parsePhysicalPoolAgentNameTag(['customer-opa'])).toBe('customer-opa');
+    expect(parsePhysicalPoolAgentNameTag([' customer-opa '])).toBe('customer-opa');
+  });
+
+  test('reports no identity for a deployment that named no pool', () => {
+    expect(parsePhysicalPoolAgentNameTag(undefined)).toBeUndefined();
+    expect(parsePhysicalPoolAgentNameTag([])).toBeUndefined();
+  });
+
+  test('rejects a tag that is not one non-empty name', () => {
+    expect(() => parsePhysicalPoolAgentNameTag([''])).toThrow(PhysicalPoolIdentityError);
+    expect(() => parsePhysicalPoolAgentNameTag(['   '])).toThrow(PhysicalPoolIdentityError);
+    expect(() => parsePhysicalPoolAgentNameTag(['customer-opa', 'other-opa'])).toThrow(/must name exactly one/);
+  });
+
+  // Replicas of one deployment publish the same registration.
+  test('accepts a name repeated across replicas', () => {
+    expect(parsePhysicalPoolAgentNameTag(['customer-opa', 'customer-opa'])).toBe('customer-opa');
+  });
+
+  describe('agreement with capacity policies', () => {
+    test('accepts a policy for the pool the deployment named', () => {
+      expect(parsePhysicalPoolAgentNameTag(['customer-opa'], [policy('customer-opa')])).toBe('customer-opa');
+    });
+
+    test('rejects a policy for a pool the deployment does not own', () => {
+      expect(() => parsePhysicalPoolAgentNameTag(['customer-opa'], [policy('other-opa')])).toThrow(/must name the same pool/);
+    });
+
+    // A deployment scales the pool it owns and nothing else. Accepting a
+    // foreign policy alongside a matching one would let proactive evaluation
+    // key off a pool the wizard would never resolve to.
+    test('rejects a foreign policy published alongside the deployments own', () => {
+      expect(() => parsePhysicalPoolAgentNameTag(['customer-opa'], [policy('customer-opa'), policy('other-opa')])).toThrow(
+        /must name the same pool/
+      );
+    });
+
+    // Older workers publish identity only inside the policy.
+    test('falls back to the policy name when the deployment published no tag', () => {
+      expect(parsePhysicalPoolAgentNameTag(undefined, [policy('customer-opa')])).toBe('customer-opa');
+    });
+
+    test('refuses to guess when policies alone name two pools', () => {
+      expect(() => parsePhysicalPoolAgentNameTag(undefined, [policy('customer-opa'), policy('other-opa')])).toThrow(
+        /publish databaseLifecycle:agentName/
+      );
+    });
+  });
+});

package/src/database-lifecycle/physicalPoolIdentity.ts

@@ -0,0 +1,75 @@
+import type { PhysicalDatabaseCapacityPolicy } from './capacityPolicy.js';
+
+/**
+ * Agent tag key for the customer-managed deployment name that identifies a
+ * worker's physical database pool, `(organizationId, agentName, engine)`.
+ *
+ * Published on its own rather than read out of
+ * `databaseLifecycle:capacityPolicies`, so a customer who wants no proactive
+ * scaling still gets a resolvable pool. One value, e.g. `customer-opa`.
+ */
+export const DATABASE_LIFECYCLE_TAG_AGENT_NAME = 'databaseLifecycle:agentName';
+
+export class PhysicalPoolIdentityError extends Error {
+  readonly code = 'physical_pool_identity_invalid';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'PhysicalPoolIdentityError';
+  }
+}
+
+/**
+ * The single physical pool a worker's registration names, or undefined when it
+ * published none.
+ *
+ * Throws {@link PhysicalPoolIdentityError} when the registration names more
+ * than one pool. Guessing between them would provision infrastructure under
+ * one deployment's Terraform state and hand it to another, so callers must
+ * either refuse the registration or withhold the identity.
+ *
+ * Falls back to the capacity policy's name when the tag is absent, for a
+ * worker predating {@link DATABASE_LIFECYCLE_TAG_AGENT_NAME} that is still
+ * rolling: the policy names the same pool, so identity stays unambiguous.
+ */
+export function parsePhysicalPoolAgentNameTag(
+  published: string[] | undefined,
+  capacityPolicies: readonly PhysicalDatabaseCapacityPolicy[] = []
+): string | undefined {
+  if (published !== undefined && !Array.isArray(published)) {
+    throw new PhysicalPoolIdentityError(`${DATABASE_LIFECYCLE_TAG_AGENT_NAME} must be an array holding one deployment name.`);
+  }
+  const values = published ?? [];
+  if (values.some((value) => typeof value !== 'string' || value.trim() === '')) {
+    throw new PhysicalPoolIdentityError(`${DATABASE_LIFECYCLE_TAG_AGENT_NAME} must be a non-empty string when provided.`);
+  }
+
+  const declared = new Set(values.map((value) => value.trim()));
+  if (declared.size > 1) {
+    throw new PhysicalPoolIdentityError(
+      `${DATABASE_LIFECYCLE_TAG_AGENT_NAME} names ${declared.size} pools (${[...declared].sort().join(', ')}); it must name exactly one.`
+    );
+  }
+
+  const policyNames = new Set(capacityPolicies.map((policy) => policy.agentName));
+  const [declaredName] = declared;
+  if (declaredName !== undefined) {
+    // Every policy has to be for the pool this deployment owns. A policy for
+    // another pool would have proactive evaluation scaling something the
+    // deployment cannot provision into.
+    if ([...policyNames].some((policyName) => policyName !== declaredName)) {
+      throw new PhysicalPoolIdentityError(
+        `${DATABASE_LIFECYCLE_TAG_AGENT_NAME} is ${declaredName} but databaseLifecycle:capacityPolicies names ${[...policyNames].sort().join(', ')}; they must name the same pool.`
+      );
+    }
+    return declaredName;
+  }
+
+  if (policyNames.size > 1) {
+    throw new PhysicalPoolIdentityError(
+      `databaseLifecycle:capacityPolicies names ${policyNames.size} pools; publish ${DATABASE_LIFECYCLE_TAG_AGENT_NAME} to say which one this deployment owns.`
+    );
+  }
+  const [policyName] = policyNames;
+  return policyName;
+}

package/src/index.ts

@@ -27,3 +27,4 @@ export * from './tracing/errorSanitizer.js';
 export * from './jwt/index.js';
 export * from './org-features/index.js';
 export * from './database-lifecycle/index.js';
+export * from './database-lifecycle/edit-lifecycle-capability.js';