@superblocksteam/shared 0.9603.2 → 0.9604.0

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

@@ -0,0 +1,209 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+  CapacityPolicyValidationError,
+  computePhysicalDatabasePoolKey,
+  encodeCapacityPolicyTag,
+  parseCapacityPolicyTag,
+  parseCapacityPolicyTags,
+  type PhysicalDatabaseCapacityPolicy,
+  validateCapacityPolicyCompatibility
+} from './capacityPolicy.js';
+
+describe('capacity policy tags', () => {
+  test('round-trips percentage policies with trimmed case-sensitive agent names', () => {
+    const shared: PhysicalDatabaseCapacityPolicy = {
+      agentName: 'Customer OPA',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 20
+    };
+
+    expect(
+      parseCapacityPolicyTag(
+        encodeCapacityPolicyTag({
+          ...shared,
+          agentName: '  Customer OPA  '
+        })
+      )
+    ).toEqual(shared);
+    expect(encodeCapacityPolicyTag(shared)).toBe('v2|Customer%20OPA|postgres|minAvailableCapacityPercent|20');
+    expect(encodeCapacityPolicyTag({ ...shared, agentName: 'customer opa' })).not.toBe(encodeCapacityPolicyTag(shared));
+  });
+
+  test('parseCapacityPolicyTags returns empty when the tag is omitted', () => {
+    expect(parseCapacityPolicyTags(undefined)).toEqual([]);
+  });
+
+  test('rejects unsupported versions, empty agent names, blank values, and out-of-range thresholds', () => {
+    const agentName = encodeURIComponent('customer-opa');
+
+    expect(() => parseCapacityPolicyTag(`v1|${agentName}|postgres|minAvailableCapacityPercent|20`)).toThrow(/unsupported version/);
+    expect(() => parseCapacityPolicyTag(`v2|%20%20|postgres|minAvailableCapacityPercent|20`)).toThrow(/agentName must be non-empty/);
+    expect(() => parseCapacityPolicyTag(`v2|${agentName}|postgres|minAvailableCapacityPercent|`)).toThrow(
+      /thresholdValue must be a non-empty integer/
+    );
+    expect(() => parseCapacityPolicyTag(`v2|${agentName}|postgres|minAvailableCapacityPercent|101`)).toThrow(/<= 100/);
+    expect(() => parseCapacityPolicyTag(`v2|${agentName}|postgres|minAvailableCapacityPercent|-1`)).toThrow(/>= 0/);
+    expect(() => parseCapacityPolicyTag(`v2|${agentName}|postgres|minEmptyPhysicalInstances|1`)).toThrow(/unknown thresholdType/);
+  });
+
+  test('parseCapacityPolicyTags fails closed on any invalid value', () => {
+    const valid = encodeCapacityPolicyTag({
+      agentName: 'customer-opa',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 20
+    });
+    expect(() => parseCapacityPolicyTags([valid, 'not-a-policy'])).toThrow(CapacityPolicyValidationError);
+  });
+
+  test('rejects duplicate policies for the same agent name and engine', () => {
+    const first = encodeCapacityPolicyTag({
+      agentName: 'Customer OPA',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 20
+    });
+    const duplicate = encodeCapacityPolicyTag({
+      agentName: ' Customer OPA ',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 10
+    });
+
+    try {
+      parseCapacityPolicyTags([first, duplicate]);
+      expect.fail('Expected duplicate capacity policy validation to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(CapacityPolicyValidationError);
+      if (!(error instanceof CapacityPolicyValidationError)) {
+        throw error;
+      }
+      expect(error.details).toEqual([expect.stringContaining('duplicate capacity policy')]);
+    }
+  });
+
+  test('allows distinct agent names for the same engine', () => {
+    const first = encodeCapacityPolicyTag({
+      agentName: 'customer-opa-a',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 20
+    });
+    const second = encodeCapacityPolicyTag({
+      agentName: 'customer-opa-b',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 10
+    });
+
+    expect(parseCapacityPolicyTags([first, second])).toHaveLength(2);
+  });
+
+  test('computePhysicalDatabasePoolKey is trimmed, case-sensitive, and delimiter-safe', () => {
+    expect(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: ' customer:opa ',
+        engine: 'postgres'
+      })
+    ).toBe(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: 'customer:opa',
+        engine: 'postgres'
+      })
+    );
+    expect(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: 'customer:opa',
+        engine: 'postgres'
+      })
+    ).not.toBe(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org',
+        agentName: '1:customer:opa',
+        engine: 'postgres'
+      })
+    );
+    expect(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: 'Customer:OPA',
+        engine: 'postgres'
+      })
+    ).not.toBe(
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: 'customer:opa',
+        engine: 'postgres'
+      })
+    );
+    expect(() =>
+      computePhysicalDatabasePoolKey({
+        organizationId: 'org:1',
+        agentName: '  ',
+        engine: 'postgres'
+      })
+    ).toThrow(/agentName must be non-empty/);
+  });
+
+  test('allows replicas to publish the same pool and threshold', () => {
+    const policy: PhysicalDatabaseCapacityPolicy = {
+      agentName: 'customer-opa',
+      engine: 'postgres',
+      thresholdType: 'minAvailableCapacityPercent',
+      thresholdValue: 20
+    };
+
+    expect(() => validateCapacityPolicyCompatibility([policy], [{ ...policy }])).not.toThrow();
+  });
+
+  test('rejects different thresholds for the same pool', () => {
+    expect(() =>
+      validateCapacityPolicyCompatibility(
+        [
+          {
+            agentName: 'customer-opa',
+            engine: 'postgres',
+            thresholdType: 'minAvailableCapacityPercent',
+            thresholdValue: 20
+          }
+        ],
+        [
+          {
+            agentName: 'customer-opa',
+            engine: 'postgres',
+            thresholdType: 'minAvailableCapacityPercent',
+            thresholdValue: 10
+          }
+        ]
+      )
+    ).toThrow(/different thresholds/);
+  });
+
+  test('allows different agent names and case-distinct agent names for the same engine', () => {
+    expect(() =>
+      validateCapacityPolicyCompatibility(
+        [
+          {
+            agentName: 'Customer OPA',
+            engine: 'postgres',
+            thresholdType: 'minAvailableCapacityPercent',
+            thresholdValue: 20
+          }
+        ],
+        [
+          {
+            agentName: 'customer opa',
+            engine: 'postgres',
+            thresholdType: 'minAvailableCapacityPercent',
+            thresholdValue: 10
+          }
+        ]
+      )
+    ).not.toThrow();
+  });
+});

package/src/database-lifecycle/capacityPolicy.ts

@@ -0,0 +1,197 @@
+/**
+ * Agent tag key for proactive physical-instance capacity thresholds.
+ * Each value encodes one pool policy (see {@link encodeCapacityPolicyTag} /
+ * {@link parseCapacityPolicyTags}).
+ *
+ * Versioned wire format (pipe-delimited, one tag value per pool):
+ *   `v2|{encodedAgentName}|{engine}|{thresholdType}|{thresholdValue}`
+ *
+ * Example:
+ *   `v2|customer-opa|postgres|minAvailableCapacityPercent|20`
+ */
+
+export const DATABASE_LIFECYCLE_TAG_CAPACITY_POLICIES = 'databaseLifecycle:capacityPolicies';
+
+export const DATABASE_ENGINES = ['postgres', 'snowflake', 'snowflake_postgres', 'lakebase'] as const;
+export type DatabaseEngine = (typeof DATABASE_ENGINES)[number];
+
+export const PHYSICAL_DATABASE_CAPACITY_THRESHOLD_TYPES = ['minAvailableCapacityPercent'] as const;
+export type PhysicalDatabaseCapacityThresholdType = (typeof PHYSICAL_DATABASE_CAPACITY_THRESHOLD_TYPES)[number];
+
+export type PhysicalDatabaseCapacityPolicy = {
+  agentName: string;
+  engine: DatabaseEngine;
+  thresholdType: 'minAvailableCapacityPercent';
+  thresholdValue: number;
+};
+
+export type PhysicalDatabasePoolKey = {
+  organizationId: string;
+  agentName: string;
+  engine: DatabaseEngine;
+};
+
+export class CapacityPolicyValidationError extends Error {
+  readonly code = 'capacity_policy_invalid';
+
+  constructor(
+    message: string,
+    readonly details: string[] = []
+  ) {
+    super(message);
+    this.name = 'CapacityPolicyValidationError';
+  }
+}
+
+/** Stable idempotency and identity key for an organization physical pool. */
+export function computePhysicalDatabasePoolKey(pool: PhysicalDatabasePoolKey): string {
+  const agentName = normalizeCapacityPolicyAgentName(pool.agentName);
+  return ['provision_physical_database', encodeURIComponent(pool.organizationId), encodeURIComponent(agentName), pool.engine].join(':');
+}
+
+export function encodeCapacityPolicyTag(policy: PhysicalDatabaseCapacityPolicy): string {
+  const agentName = normalizeCapacityPolicyAgentName(policy.agentName);
+  return ['v2', encodeURIComponent(agentName), policy.engine, policy.thresholdType, String(policy.thresholdValue)].join('|');
+}
+
+/**
+ * Parse and validate capacity-policy tags. Fail closed: any malformed value
+ * throws {@link CapacityPolicyValidationError}. Missing tag key ⇒ empty list
+ * (no proactive provisioning for that agent).
+ */
+export function parseCapacityPolicyTags(published: string[] | undefined): PhysicalDatabaseCapacityPolicy[] {
+  if (published === undefined) {
+    return [];
+  }
+  if (!Array.isArray(published)) {
+    throw new CapacityPolicyValidationError('databaseLifecycle:capacityPolicies must be an array of policy strings.');
+  }
+
+  const policies: PhysicalDatabaseCapacityPolicy[] = [];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+
+  for (const raw of published) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+      errors.push('capacity policy value must be a non-empty string');
+      continue;
+    }
+    try {
+      const policy = parseCapacityPolicyTag(raw);
+      const identity = JSON.stringify([policy.agentName, policy.engine]);
+      if (seen.has(identity)) {
+        errors.push(`duplicate capacity policy for pool ${identity}`);
+        continue;
+      }
+      seen.add(identity);
+      policies.push(policy);
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new CapacityPolicyValidationError(
+      `Invalid databaseLifecycle:capacityPolicies (${errors.length} error${errors.length === 1 ? '' : 's'}).`,
+      errors
+    );
+  }
+
+  return policies;
+}
+
+/**
+ * Detect threshold disagreements for the same physical pool.
+ * Profile tags are routing metadata and do not participate in identity.
+ *
+ * Registration callers soft-skip peer conflicts (rolling threshold updates);
+ * the registering agent's own invalid tags still fail closed.
+ */
+export function validateCapacityPolicyCompatibility(
+  candidatePolicies: readonly PhysicalDatabaseCapacityPolicy[],
+  existingPolicies: readonly PhysicalDatabaseCapacityPolicy[]
+): void {
+  const errors: string[] = [];
+  for (const candidate of candidatePolicies) {
+    const candidateAgentName = normalizeCapacityPolicyAgentName(candidate.agentName);
+    for (const existing of existingPolicies) {
+      const existingAgentName = normalizeCapacityPolicyAgentName(existing.agentName);
+      if (candidate.engine !== existing.engine || candidateAgentName !== existingAgentName) {
+        continue;
+      }
+      if (candidate.thresholdValue !== existing.thresholdValue) {
+        errors.push(
+          `different thresholds for pool ${JSON.stringify([candidateAgentName, candidate.engine])}: ${candidate.thresholdValue} and ${existing.thresholdValue}`
+        );
+      }
+    }
+  }
+  if (errors.length > 0) {
+    throw new CapacityPolicyValidationError(
+      `Conflicting databaseLifecycle:capacityPolicies (${errors.length} conflict${errors.length === 1 ? '' : 's'}): ${errors.join('; ')}`,
+      errors
+    );
+  }
+}
+
+export function parseCapacityPolicyTag(raw: string): PhysicalDatabaseCapacityPolicy {
+  const parts = raw.split('|');
+  if (parts.length !== 5) {
+    throw new Error(
+      `expected 5 pipe-delimited fields (version|agentName|engine|thresholdType|value), got ${parts.length} in ${JSON.stringify(raw)}`
+    );
+  }
+
+  const [version, agentNameEncoded, engineRaw, thresholdTypeRaw, thresholdValueRaw] = parts;
+
+  if (version !== 'v2') {
+    throw new Error(`unsupported version ${JSON.stringify(version)}`);
+  }
+  if (!isKnownValue(engineRaw, DATABASE_ENGINES)) {
+    throw new Error(`unknown engine ${JSON.stringify(engineRaw)}`);
+  }
+  if (!isKnownValue(thresholdTypeRaw, PHYSICAL_DATABASE_CAPACITY_THRESHOLD_TYPES)) {
+    throw new Error(`unknown thresholdType ${JSON.stringify(thresholdTypeRaw)}`);
+  }
+
+  let decodedAgentName: string;
+  try {
+    decodedAgentName = decodeURIComponent(agentNameEncoded);
+  } catch {
+    throw new Error(`agentName is not valid URI encoding: ${JSON.stringify(agentNameEncoded)}`);
+  }
+  const agentName = normalizeCapacityPolicyAgentName(decodedAgentName);
+
+  if (thresholdValueRaw.trim() === '' || !/^-?\d+$/.test(thresholdValueRaw)) {
+    throw new Error('thresholdValue must be a non-empty integer');
+  }
+  const thresholdValue = Number(thresholdValueRaw);
+  if (!Number.isSafeInteger(thresholdValue)) {
+    throw new Error(`thresholdValue must be an integer, got ${JSON.stringify(thresholdValueRaw)}`);
+  }
+  if (thresholdValue < 0) {
+    throw new Error(`thresholdValue must be >= 0, got ${thresholdValue}`);
+  }
+
+  if (thresholdValue > 100) {
+    throw new Error(`minAvailableCapacityPercent must be <= 100, got ${thresholdValue}`);
+  }
+  return {
+    agentName,
+    engine: engineRaw,
+    thresholdType: 'minAvailableCapacityPercent',
+    thresholdValue
+  };
+}
+
+function isKnownValue<T extends string>(value: string, known: readonly T[]): value is T {
+  return known.some((candidate) => candidate === value);
+}
+
+function normalizeCapacityPolicyAgentName(agentName: string): string {
+  const normalized = agentName.trim();
+  if (normalized.length === 0) {
+    throw new CapacityPolicyValidationError('agentName must be non-empty after trimming.');
+  }
+  return normalized;
+}

package/src/database-lifecycle/edit-lifecycle-capability.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+
+import { AgentStatus } from '../types/organization/agent.js';
+import { hasEditLifecycleCapability } from './edit-lifecycle-capability.js';
+import { DATABASE_LIFECYCLE_TAG_OPERATIONS } from './index.js';
+
+describe('hasEditLifecycleCapability', () => {
+  it('is false when no agents are present', () => {
+    expect(hasEditLifecycleCapability(undefined)).toBe(false);
+    expect(hasEditLifecycleCapability([])).toBe(false);
+  });
+
+  it('is false when agents lack databaseLifecycle operations', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: { profile: ['dev'] }
+        }
+      ])
+    ).toBe(false);
+  });
+
+  it('is false when the agent registers other operations but not ensure_database', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: {
+            [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['migrate_schema', 'retire_database'],
+            profile: ['dev']
+          }
+        }
+      ])
+    ).toBe(false);
+  });
+
+  it('is false when ensure_database is registered but the agent serves no profile', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database', 'migrate_schema'] }
+        }
+      ])
+    ).toBe(false);
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database'], profile: [] }
+        }
+      ])
+    ).toBe(false);
+  });
+
+  it('is false when a disconnected agent has lifecycle tags', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.DISCONNECTED,
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database'], profile: ['dev'] }
+        }
+      ])
+    ).toBe(false);
+  });
+
+  it('is false when agent status is missing even if tags would otherwise qualify', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database'], profile: ['dev'] }
+        }
+      ])
+    ).toBe(false);
+  });
+
+  it('is true when an active agent registered ensure_database for any profile', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: {
+            [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database', 'migrate_schema'],
+            profile: ['staging', 'production']
+          }
+        }
+      ])
+    ).toBe(true);
+  });
+
+  // A production-only lifecycle agent still advertises Native DB. Editing is no
+  // longer a separate lifecycle axis, so there is no `edit:` pair to require —
+  // profile-key resolution stays on the server at ensure/dispatch time.
+  it('is true for an agent serving only production', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: AgentStatus.ACTIVE,
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database'], profile: ['production'] }
+        }
+      ])
+    ).toBe(true);
+  });
+
+  it('is true when status is the string Active (CLI wire form)', () => {
+    expect(
+      hasEditLifecycleCapability([
+        {
+          status: 'Active',
+          tags: { [DATABASE_LIFECYCLE_TAG_OPERATIONS]: ['ensure_database'], profile: ['dev'] }
+        }
+      ])
+    ).toBe(true);
+  });
+});

package/src/database-lifecycle/edit-lifecycle-capability.ts

@@ -0,0 +1,34 @@
+import { AgentStatus, type AgentTags } from '../types/organization/agent.js';
+import { DATABASE_LIFECYCLE_TAG_OPERATIONS } from './index.js';
+
+export type AgentLifecycleTagSource = {
+  status?: AgentStatus | string;
+  tags?: AgentTags;
+};
+
+/**
+ * Whether an agent list shows Native DB opted in for provisioning.
+ *
+ * Coarse registration check for product advertising (Clark tools/prompts,
+ * UI Databases entry): an active agent must publish `ensure_database` and
+ * serve at least one profile. Profile-key resolution, engine support, and
+ * managed-IAM admission stay on the server at ensure/dispatch time — this
+ * helper does not re-encode that surface.
+ *
+ * Agents without a confirmed active status are excluded (fail closed).
+ */
+export function hasEditLifecycleCapability(agents: readonly AgentLifecycleTagSource[] | undefined): boolean {
+  if (!agents || agents.length === 0) {
+    return false;
+  }
+  return agents.some((agent) => {
+    if (agent.status === undefined || (agent.status !== AgentStatus.ACTIVE && agent.status !== 'Active')) {
+      return false;
+    }
+    const operations = agent.tags?.[DATABASE_LIFECYCLE_TAG_OPERATIONS] ?? [];
+    if (!operations.includes('ensure_database')) {
+      return false;
+    }
+    return (agent.tags?.profile ?? []).length > 0;
+  });
+}