@ankhorage/contracts 14.0.0 → 15.0.0

package/src/infra/isInfraWorkloadValue.ts

@@ -0,0 +1,41 @@
+import { isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import { APP_ENVIRONMENT_IDS } from '../environments';
+import { isInfraShape } from './isInfraShape';
+
+/*** Workload values explicitly distinguish public literals, output dependencies and secret references. */
+export function isInfraWorkloadValue(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  switch (value.kind) {
+    case 'literal':
+      return isInfraShape(value, {
+        kind: (kind) => kind === 'literal',
+        value: (field) => typeof field === 'string',
+      });
+    case 'output':
+      return isInfraShape(value, {
+        kind: (kind) => kind === 'output',
+        resourceId: isNonEmptyString,
+        output: isNonEmptyString,
+      });
+    case 'secret':
+      return isInfraShape(value, {
+        kind: (kind) => kind === 'secret',
+        reference: isSecretReference,
+      });
+    default:
+      return false;
+  }
+}
+
+/*** Managed secret references contain identity only, never privileged payloads. */
+function isSecretReference(value: unknown): boolean {
+  return isInfraShape(value, {
+    source: (source) => source === 'secret-store',
+    projectId: isNonEmptyString,
+    environment: (environment) => APP_ENVIRONMENT_IDS.some((id) => id === environment),
+    ref: isNonEmptyString,
+    key: isNonEmptyString,
+  });
+}

package/src/infra/parseInfraManifest.ts

@@ -0,0 +1,20 @@
+import type { InfraResult } from '../types/infraLifecycle';
+import type { InfraManifest } from '../types/infraManifest';
+import { isInfraManifest } from './isInfraManifest';
+
+/** Parse unknown infrastructure input; package availability and credentials are separate validation stages. */
+export function parseInfraManifest(value: unknown): InfraResult<InfraManifest> {
+  return isInfraManifest(value)
+    ? { ok: true, value, diagnostics: [] }
+    : {
+        ok: false,
+        diagnostics: [
+          {
+            severity: 'error',
+            code: 'invalid_manifest',
+            message:
+              'Expected canonical Infra environments with supported provider configuration and compute/runtime compatibility.',
+          },
+        ],
+      };
+}

package/src/infra/validateInfraAdapterSelection.ts

@@ -0,0 +1,42 @@
+import type { InfraAdapterDescriptor } from '../types/infraAdapters';
+import type { InfraDiagnostic, InfraResult } from '../types/infraLifecycle';
+import type { InfraEnvironmentSpec } from '../types/infraManifest';
+import { INFRA_ADAPTER_CATALOG } from './constants';
+import { isInfraAdapterDescriptor } from './isInfraAdapterDescriptor';
+
+/** Validate supplied installed descriptors without imports or filesystem access; only selected packages matter. */
+export function validateInfraAdapterSelection(
+  environment: InfraEnvironmentSpec,
+  installed: readonly unknown[],
+): InfraResult<readonly InfraAdapterDescriptor[]> {
+  const ids = new Set([
+    environment.deployment.compute.provider,
+    environment.deployment.runtime.provider,
+    environment.database?.provider,
+    environment.objectStorage?.provider,
+    environment.auth?.provider,
+    environment.authz?.provider,
+    environment.secretStore?.provider,
+  ]);
+  const selected = Object.values(INFRA_ADAPTER_CATALOG).filter((entry) => ids.has(entry.id));
+  const descriptors = installed.filter(isInfraAdapterDescriptor);
+  const diagnostics: readonly InfraDiagnostic[] = selected.flatMap((entry) => {
+    const matches = descriptors.filter((descriptor) => descriptor.id === entry.id);
+    return matches.length === 1
+      ? []
+      : [
+          {
+            severity: 'error',
+            code: 'adapter_unavailable',
+            message: `Selected adapter ${entry.id} requires exactly one installed ${entry.package} descriptor matching Contracts config version ${entry.configVersion}; found ${matches.length}.`,
+          },
+        ];
+  });
+  return diagnostics.length > 0
+    ? { ok: false, diagnostics }
+    : {
+        ok: true,
+        value: descriptors.filter((descriptor) => ids.has(descriptor.id)),
+        diagnostics,
+      };
+}

package/src/infra-types.test.ts

@@ -0,0 +1,78 @@
+import { expect, it } from 'bun:test';
+
+import type { AppEnvironmentId } from './environments';
+import type {
+  InfraAdapterDescriptor,
+  InfraAuthSpec,
+  InfraAuthzSpec,
+  InfraControlPlaneCredentialRef,
+  InfraDeploymentSpec,
+  InfraDestroyRequest,
+  InfraManifest,
+  InfraObjectStorageSpec,
+  InfraOutput,
+  InfraRuntimeProviderId,
+} from './infra';
+import type { AppStateSpec } from './state';
+
+type Assignable<T, U> = [T] extends [U] ? true : false;
+interface Deployment<C, R> {
+  readonly compute: C;
+  readonly runtime: R;
+}
+interface Local {
+  readonly provider: 'local';
+}
+interface Hetzner {
+  readonly provider: 'hetzner';
+  readonly location: 'nbg1';
+}
+interface Runtime<P extends InfraRuntimeProviderId> {
+  readonly provider: P;
+}
+
+it('compiles the entire deployment matrix with exact assignability', () => {
+  const matrix: readonly [
+    Assignable<Deployment<Local, Runtime<'minikube'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<Local, Runtime<'k3s'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<Local, Runtime<'docker-compose'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<Hetzner, Runtime<'minikube'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<Hetzner, Runtime<'k3s'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<Hetzner, Runtime<'docker-compose'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<{ provider: 'gcp' }, { provider: 'ecs' }>, InfraDeploymentSpec>,
+    Assignable<Deployment<Hetzner, { provider: 'eks' }>, InfraDeploymentSpec>,
+    Assignable<Deployment<{ provider: 'hetzner' }, Runtime<'k3s'>>, InfraDeploymentSpec>,
+    Assignable<Deployment<{ provider: string }, { provider: string }>, InfraDeploymentSpec>,
+  ] = [true, true, true, false, true, true, false, false, false, false];
+  expect(matrix).toEqual([true, true, true, false, true, true, false, false, false, false]);
+});
+
+it('closes environment, app-state, bootstrap and privileged-output boundaries', () => {
+  const closed: readonly [
+    Assignable<'staging', AppEnvironmentId>,
+    Assignable<{ provider: 'legend'; persistence: 'local' }, AppStateSpec>,
+    Assignable<{ provider: 'custom' }, AppStateSpec>,
+    Assignable<{ source: 'secret-store'; ref: string }, InfraControlPlaneCredentialRef>,
+    Assignable<{ modules: [] }, InfraManifest>,
+    Assignable<{ projectId: string; environment: 'production' }, InfraDestroyRequest>,
+    Assignable<
+      Omit<InfraAdapterDescriptor<'supabase'>, 'package'> & { package: '@ankhorage/supabase-db' },
+      InfraAdapterDescriptor
+    >,
+    Assignable<
+      Omit<Extract<InfraOutput, { visibility: 'secret' }>, 'value'> & { value: string },
+      InfraOutput
+    >,
+  ] = [false, false, false, false, false, false, false, false];
+  expect(closed).toEqual([false, false, false, false, false, false, false, false]);
+});
+
+it('rejects open or fictional service providers in typed selections', () => {
+  const providers: readonly [
+    Assignable<{ provider: string }, InfraAuthSpec>,
+    Assignable<{ provider: 'native'; kind: 'RBAC' }, InfraAuthzSpec>,
+    Assignable<{ provider: 'auto' }, InfraObjectStorageSpec>,
+    Assignable<{ provider: 's3' }, InfraObjectStorageSpec>,
+  ] = [false, false, false, false];
+  expect(providers).toEqual([false, false, false, false]);
+});

package/src/infra-workload.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isAppManifest } from './appManifest';
+import {
+  type InfraWorkloadSpec,
+  isInfraDeploymentSpec,
+  isInfraEnvironmentSpec,
+  isInfraWorkloadSpec,
+} from './infra';
+import type { AppManifest } from './types';
+
+const reference = {
+  source: 'secret-store',
+  projectId: 'example',
+  environment: 'local',
+  ref: 'database',
+  key: 'password',
+} as const;
+const workload = {
+  id: 'backend',
+  artifact: { kind: 'image', image: 'example/backend@sha256:abc' },
+  command: ['server'],
+  args: ['--verbose'],
+  ports: [{ name: 'http', port: 8080 }],
+  environment: {
+    NODE_ENV: { kind: 'literal', value: 'production' },
+    DB_PASSWORD: { kind: 'secret', reference },
+    DB_HOST: { kind: 'output', resourceId: 'database', output: 'host' },
+  },
+  files: [{ path: '/etc/backend/config.json', content: { kind: 'literal', value: '{}' } }],
+  health: { kind: 'http', port: 8080, path: '/health', intervalSeconds: 5 },
+  resources: { cpuMillis: 500, memoryMiB: 256 },
+  persistence: [{ id: 'data', mountPath: '/data', sizeGiB: 10, retention: 'retain' }],
+  exposure: 'public',
+  replicas: 1,
+  dependsOn: ['database'],
+} as const satisfies InfraWorkloadSpec;
+
+const invalidWorkloads = [
+  { artifact: { kind: 'build', dockerfile: 'Dockerfile' } },
+  { artifact: { kind: 'image', image: '' } },
+  { ports: [{ name: 'http', port: 0 }] },
+  { ports: [{ name: 'http', port: 65536 }] },
+  { ports: [{ name: 'http', port: 1.5 }] },
+  { ports: [{ name: 'http', port: 80, protocol: 'sctp' }] },
+  {
+    ports: [
+      { name: 'http', port: 80 },
+      { name: 'http', port: 81 },
+    ],
+  },
+  { replicas: -1 },
+  { replicas: NaN },
+  { replicas: 1.5 },
+  { resources: { memoryMiB: Infinity } },
+  { resources: { cpuMillis: 0 } },
+  { persistence: [{ id: 'data', mountPath: '/data', sizeGiB: 1 }] },
+  { persistence: [{ id: 'data', mountPath: '../data', sizeGiB: 1, retention: 'retain' }] },
+  { files: [{ path: '/etc/../secret', content: { kind: 'literal', value: 'x' } }] },
+  { health: { kind: 'http', port: 80, path: '/health', failureThreshold: 0 } },
+  { health: { kind: 'tcp', port: 80, path: '/health' } },
+  { health: { kind: 'command', command: [] } },
+  { nodeSelector: {} },
+  { apiVersion: 'apps/v1' },
+  { ingressClassName: 'nginx' },
+  { environment: { PASSWORD: 'plaintext' } },
+  { environment: { PASSWORD: { kind: 'secret', reference, value: 'sentinel-secret' } } },
+  {
+    environment: { PASSWORD: { kind: 'secret', reference: { ...reference, token: 'sentinel' } } },
+  },
+  {
+    environment: {
+      TOKEN: { kind: 'secret', reference: { source: 'control-plane', name: 'HCLOUD_TOKEN' } },
+    },
+  },
+];
+
+describe('runtime-neutral workload boundary', () => {
+  it('accepts prebuilt images, dependency outputs, config files and secret references on every runtime', () => {
+    expect(isInfraWorkloadSpec(JSON.parse(JSON.stringify(workload)))).toBe(true);
+    for (const provider of ['minikube', 'k3s', 'docker-compose']) {
+      expect(
+        isInfraEnvironmentSpec({
+          deployment: { compute: { provider: 'local' }, runtime: { provider } },
+          workloads: [workload],
+        }),
+      ).toBe(true);
+    }
+  });
+
+  it.each(invalidWorkloads)(
+    'rejects invalid or runtime-specific workload fields: %j',
+    (override) => {
+      expect(isInfraWorkloadSpec({ ...workload, ...override })).toBe(false);
+    },
+  );
+
+  it('accepts TCP/command health probes and zero replicas for reversible suspension', () => {
+    expect(
+      isInfraWorkloadSpec({ ...workload, health: { kind: 'tcp', port: 8080 }, replicas: 0 }),
+    ).toBe(true);
+    expect(
+      isInfraWorkloadSpec({ ...workload, health: { kind: 'command', command: ['check'] } }),
+    ).toBe(true);
+  });
+
+  it('rejects duplicate workload identities', () => {
+    expect(
+      isInfraEnvironmentSpec({
+        deployment: { compute: { provider: 'local' }, runtime: { provider: 'k3s' } },
+        workloads: [workload, workload],
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('control-plane credential separation', () => {
+  it('accepts a bootstrap reference while rejecting managed-store bootstrap and inline tokens', () => {
+    for (const credentials of [
+      { source: 'control-plane', name: 'HCLOUD' },
+      reference,
+      'secret-token',
+      { source: 'control-plane', name: 'HCLOUD', token: 'sentinel' },
+    ]) {
+      const value = {
+        compute: { provider: 'hetzner', location: 'nbg1', credentials },
+        runtime: { provider: 'k3s' },
+      };
+      expect(isInfraDeploymentSpec(value)).toBe(
+        typeof credentials === 'object' &&
+          'source' in credentials &&
+          credentials.source === 'control-plane' &&
+          !('token' in credentials),
+      );
+    }
+  });
+});
+
+describe('application state boundary', () => {
+  const manifest = {
+    metadata: {
+      name: 'Example',
+      slug: 'example',
+      version: '1.0.0',
+      category: 'developer_tools',
+      themeId: 'default',
+    },
+    themes: [],
+    activeThemeId: 'default',
+    screens: {},
+    navigator: { type: 'stack', routes: [] },
+    infra: {
+      environments: {
+        local: {
+          deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+        },
+      },
+      modules: [],
+    },
+    settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
+  } satisfies AppManifest;
+
+  it('keeps app state optional and accepts only implemented Legend persistence behavior', () => {
+    expect(isAppManifest(manifest)).toBe(true);
+    expect(isAppManifest({ ...manifest, state: { provider: 'legend' } })).toBe(true);
+    expect(isAppManifest({ ...manifest, state: { provider: 'legend', persistence: false } })).toBe(
+      true,
+    );
+  });
+
+  it.each(['none', 'local', 'secure', 'database', true, null])(
+    'rejects unsupported persistence %j',
+    (persistence) => {
+      expect(isAppManifest({ ...manifest, state: { provider: 'legend', persistence } })).toBe(
+        false,
+      );
+    },
+  );
+
+  it('rejects open state providers and the obsolete infra.state placement', () => {
+    expect(isAppManifest({ ...manifest, state: { provider: 'custom' } })).toBe(false);
+    expect(
+      isAppManifest({ ...manifest, infra: { ...manifest.infra, state: { provider: 'legend' } } }),
+    ).toBe(false);
+  });
+});

package/src/infra.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  INFRA_ADAPTER_CATALOG,
+  INFRA_RUNTIME_COMPATIBILITY,
+  type InfraEnvironmentSpec,
+  type InfraManifest,
+  isInfraAdapterDescriptor,
+  isInfraDeploymentSpec,
+  isInfraEnvironmentSpec,
+  isInfraManifest,
+  parseInfraManifest,
+  validateInfraAdapterSelection,
+} from './infra';
+
+const local = {
+  deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+} as const satisfies InfraEnvironmentSpec;
+const production = {
+  deployment: {
+    compute: { provider: 'hetzner', location: 'nbg1' },
+    runtime: { provider: 'k3s', topology: { servers: 1, agents: 0 } },
+  },
+  database: { provider: 'supabase' },
+  auth: { provider: 'supabase' },
+  objectStorage: { provider: 'r2', buckets: ['media'] },
+  authz: { provider: 'cerbos', kind: 'ABAC' },
+  secretStore: { provider: 'supabase-vault' },
+  networking: { domain: 'api.example.ch' },
+} as const satisfies InfraEnvironmentSpec;
+
+describe('standalone Infra environments', () => {
+  it('parses local/preview/production without an AppManifest or Deploy', () => {
+    const manifest = {
+      environments: { local, preview: production, production },
+      modules: [],
+    } satisfies InfraManifest;
+    expect(parseInfraManifest(JSON.parse(JSON.stringify(manifest)))).toEqual({
+      ok: true,
+      value: manifest,
+      diagnostics: [],
+    });
+  });
+
+  it.each([
+    null,
+    {},
+    { modules: [] },
+    { environments: {}, modules: [] },
+    { environments: { production }, modules: [] },
+    { environments: { local, staging: local }, modules: [] },
+    { environments: { local, preview: null }, modules: [] },
+    { environments: { local }, modules: [42] },
+    { environments: { local }, modules: [], modulesConfig: [] },
+    { environments: { local }, modules: [], apis: 'invalid' },
+  ])('rejects invalid environment boundaries: %j', (value) => {
+    expect(isInfraManifest(value)).toBe(false);
+    expect(parseInfraManifest(value).ok).toBe(false);
+  });
+
+  it.each([
+    'deployment',
+    'storage',
+    'state',
+    'auth',
+    'database',
+    'networking',
+    'secretStore',
+    'plugins',
+    'pluginsConfig',
+  ])('rejects removed top-level %s', (key) => {
+    expect(isInfraManifest({ environments: { local }, modules: [], [key]: {} })).toBe(false);
+  });
+
+  it.each(['storage', 'state', 'monitoring', 'observability', 'target'])(
+    'rejects obsolete or speculative environment %s',
+    (key) => {
+      expect(isInfraEnvironmentSpec({ ...local, [key]: {} })).toBe(false);
+    },
+  );
+});
+
+describe('exact deployment compatibility', () => {
+  it('tests every registered compute/runtime pair against the same catalog', () => {
+    const computes = Object.values(INFRA_ADAPTER_CATALOG).filter(
+      (entry) => entry.kind === 'compute',
+    );
+    for (const compute of computes) {
+      for (const [runtime, allowed] of Object.entries(INFRA_RUNTIME_COMPATIBILITY)) {
+        const selection = {
+          compute: {
+            provider: compute.id,
+            ...(compute.id === 'hetzner' ? { location: 'nbg1' } : {}),
+          },
+          runtime: { provider: runtime },
+        };
+        expect(isInfraDeploymentSpec(selection)).toBe(allowed.some((id) => id === compute.id));
+      }
+    }
+  });
+
+  it.each([
+    { compute: { provider: 'gcp' }, runtime: { provider: 'ecs' } },
+    { compute: { provider: 'hetzner', location: 'nbg1' }, runtime: { provider: 'eks' } },
+    { compute: { provider: 'hetzner', location: 'nbg1' }, runtime: { provider: 'minikube' } },
+    { compute: { provider: 'hetzner' }, runtime: { provider: 'k3s' } },
+    { compute: { provider: 'hetzner', location: ' ' }, runtime: { provider: 'k3s' } },
+    { compute: { provider: 'local', location: 'nbg1' }, runtime: { provider: 'k3s' } },
+    { ...local.deployment, monitoring: false },
+    { target: 'minikube', monitoring: true },
+  ])('rejects unsupported/config-mismatched deployment: %j', (value) => {
+    expect(isInfraDeploymentSpec(value)).toBe(false);
+  });
+});
+
+describe('runtime topology configuration', () => {
+  it.each([
+    { provider: 'k3s', topology: { servers: 0, agents: 1 } },
+    { provider: 'k3s', topology: { servers: 1, agents: -1 } },
+    { provider: 'k3s', topology: { servers: 1.5, agents: 0 } },
+    { provider: 'k3s', topology: { servers: 1, agents: Infinity } },
+    { provider: 'k3s', topology: { servers: 1 } },
+    { provider: 'minikube', cpus: 0 },
+    { provider: 'minikube', memoryMiB: NaN },
+    { provider: 'minikube', driver: 'unknown' },
+    { provider: 'docker-compose', profile: 'minikube' },
+  ])('rejects malformed runtime configuration: %j', (runtime) => {
+    expect(isInfraDeploymentSpec({ compute: { provider: 'local' }, runtime })).toBe(false);
+  });
+
+  it('accepts multi-node topology on both supported k3s computes', () => {
+    for (const compute of [{ provider: 'local' }, { provider: 'hetzner', location: 'nbg1' }]) {
+      expect(
+        isInfraDeploymentSpec({
+          compute,
+          runtime: { provider: 'k3s', topology: { servers: 3, agents: 4 } },
+        }),
+      ).toBe(true);
+    }
+  });
+});
+
+describe('sibling service configuration', () => {
+  it('accepts Supabase auth, Cerbos and independent R2 storage', () => {
+    expect(isInfraEnvironmentSpec(production)).toBe(true);
+    expect(isInfraEnvironmentSpec({ ...production, objectStorage: { provider: 'supabase' } })).toBe(
+      true,
+    );
+    expect(isInfraEnvironmentSpec({ ...local, auth: { provider: 'supabase' } })).toBe(true);
+  });
+
+  it.each([
+    { database: { provider: 'postgres' } },
+    { database: { provider: 'supabase', tier: 'enterprise' } },
+    { objectStorage: { provider: 'auto' } },
+    { objectStorage: { provider: 's3' } },
+    { objectStorage: { provider: 'supabase', buckets: [1] } },
+    { objectStorage: { provider: 'supabase', accountId: 'r2-account' } },
+    { auth: { provider: 'custom' } },
+    { auth: { provider: 'supabase', scope: 'unknown' } },
+    { auth: { provider: 'supabase', authorization: { kind: 'ABAC', engine: 'cerbos' } } },
+    { authz: { provider: 'native', kind: 'RBAC' } },
+    { authz: { engine: 'cerbos', kind: 'ABAC' } },
+    { authz: { provider: 'cerbos', kind: 'unknown' } },
+    { secretStore: { provider: 'unknown' } },
+    { secretStore: { provider: 'supabase-vault' } },
+    { networking: { domain: 'example.ch', cdn: true } },
+  ])('rejects unsupported service selection: %j', (selection) => {
+    expect(isInfraEnvironmentSpec({ ...local, ...selection })).toBe(false);
+  });
+});
+
+describe('authentication configuration', () => {
+  it('preserves auth flow, profile and OAuth credential references', () => {
+    expect(
+      isInfraEnvironmentSpec({
+        ...production,
+        auth: {
+          provider: 'supabase',
+          scope: 'global',
+          flow: { signInRoute: '/sign-in', postSignInRoute: '/' },
+          signIn: { identifiers: ['email'] },
+          signUp: { requiredFields: ['email', 'password'], signUpPolicy: 'requireVerification' },
+          profile: {
+            fields: ['email'],
+            primaryKey: 'authUserId',
+            createStrategy: 'trigger',
+            updateStrategy: 'api',
+          },
+          oauth: {
+            enabled: true,
+            callbackRoute: '/auth/callback',
+            providers: [{ id: 'google', credentialsRef: 'auth/oauth/google' }],
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it.each([
+    { flow: { signInRoute: '/' } },
+    { signIn: { identifiers: ['social'] } },
+    { signUp: { requiredFields: [], signUpPolicy: 'unknown' } },
+    { profile: { fields: ['email'], createStrategy: 'unknown' } },
+    {
+      oauth: {
+        enabled: true,
+        callbackRoute: '/',
+        providers: [{ id: 'google', clientSecret: 'sentinel' }],
+      },
+    },
+  ])('rejects malformed auth configuration: %j', (config) => {
+    expect(isInfraEnvironmentSpec({ ...local, auth: { provider: 'supabase', ...config } })).toBe(
+      false,
+    );
+  });
+});
+
+describe('adapter package discovery contracts', () => {
+  it('accepts every canonical descriptor and deduplicates a multi-capability Supabase platform', () => {
+    for (const descriptor of Object.values(INFRA_ADAPTER_CATALOG))
+      expect(isInfraAdapterDescriptor(descriptor)).toBe(true);
+    const environment = { ...production, objectStorage: { provider: 'supabase' } } as const;
+    const result = validateInfraAdapterSelection(environment, Object.values(INFRA_ADAPTER_CATALOG));
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('Expected installed descriptors.');
+    expect(result.value.filter((descriptor) => descriptor.id === 'supabase')).toHaveLength(1);
+    expect(result.value.some((descriptor) => descriptor.id === 'r2')).toBe(false);
+  });
+
+  it.each([
+    { package: '@ankhorage/supabase-db' },
+    { id: 'custom' },
+    { kind: 'runtime' },
+    { configVersion: 2 },
+    { capabilities: ['auth'] },
+    { dependencies: [] },
+    { targets: ['local-host'] },
+    { operations: ['drop-all'] },
+  ])('rejects a mismatched package descriptor: %j', (override) => {
+    expect(isInfraAdapterDescriptor({ ...INFRA_ADAPTER_CATALOG.supabase, ...override })).toBe(
+      false,
+    );
+  });
+
+  it('reports the exact missing selected package without requiring unselected providers', () => {
+    expect(
+      validateInfraAdapterSelection(local, [
+        INFRA_ADAPTER_CATALOG.local,
+        INFRA_ADAPTER_CATALOG.minikube,
+      ]).ok,
+    ).toBe(true);
+    const result = validateInfraAdapterSelection(local, [INFRA_ADAPTER_CATALOG.local]);
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics[0]?.message).toContain('@ankhorage/minikube');
+    expect(result.diagnostics[0]?.code).toBe('adapter_unavailable');
+  });
+
+  it('rejects ambiguous duplicate installed descriptors', () => {
+    expect(
+      validateInfraAdapterSelection(local, [
+        INFRA_ADAPTER_CATALOG.local,
+        INFRA_ADAPTER_CATALOG.local,
+        INFRA_ADAPTER_CATALOG.minikube,
+      ]).ok,
+    ).toBe(false);
+  });
+});

package/src/infra.ts

@@ -0,0 +1,15 @@
+/** Canonical standalone infrastructure contracts, catalog and side-effect-free validation. */
+export { INFRA_ADAPTER_CATALOG, INFRA_RUNTIME_COMPATIBILITY } from './infra/constants';
+export { isInfraAdapterDescriptor } from './infra/isInfraAdapterDescriptor';
+export { isInfraAuthSpec } from './infra/isInfraAuthSpec';
+export { isInfraDeploymentSpec } from './infra/isInfraDeploymentSpec';
+export { isInfraEnvironmentSpec } from './infra/isInfraEnvironmentSpec';
+export { isInfraManifest } from './infra/isInfraManifest';
+export { isInfraWorkloadSpec } from './infra/isInfraWorkloadSpec';
+export { parseInfraManifest } from './infra/parseInfraManifest';
+export { validateInfraAdapterSelection } from './infra/validateInfraAdapterSelection';
+export type * from './types/infraAdapters';
+export type * from './types/infraLifecycle';
+export type * from './types/infraManifest';
+export type * from './types/infraSecrets';
+export type * from './types/infraWorkload';