@ankhorage/contracts 13.0.1 → 15.0.0

package/src/infra/isInfraManifest.ts

@@ -0,0 +1,29 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import { isApiDefinitionList } from '../appManifest/apis';
+import { APP_ENVIRONMENT_IDS } from '../environments';
+import type { InfraManifest } from '../types/infraManifest';
+import type { InfraShape } from '../types/infraValidation';
+import { infraFields } from './infraFields';
+import { isInfraEnvironmentSpec } from './isInfraEnvironmentSpec';
+import { isInfraShape } from './isInfraShape';
+
+/*** Validate standalone infrastructure without AppManifest, Deploy or provider package side effects. */
+export function isInfraManifest(value: unknown): value is InfraManifest {
+  return isInfraShape(value, {
+    environments: isEnvironments,
+    apis: (apis) => apis === undefined || isApiDefinitionList(apis),
+    modules: infraFields.strings,
+    modulesConfig: (config) => config === undefined || isRecord(config),
+  } satisfies InfraShape<InfraManifest>);
+}
+
+/*** Local is required; preview and production are optional but never inferred from arbitrary keys. */
+function isEnvironments(value: unknown): boolean {
+  if (!isRecord(value) || !isInfraEnvironmentSpec(value.local)) return false;
+  return Object.entries(value).every(
+    ([key, environment]) =>
+      APP_ENVIRONMENT_IDS.some((id) => id === key) &&
+      ((environment === undefined && key !== 'local') || isInfraEnvironmentSpec(environment)),
+  );
+}

package/src/infra/isInfraShape.ts

@@ -0,0 +1,16 @@
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+
+/*** Validate an exact Infra object shape, rejecting unknown and superseded configuration keys. */
+export function isInfraShape(
+  value: unknown,
+  fields: Readonly<Record<string, (field: unknown) => boolean>>,
+): boolean {
+  if (!isRecord(value)) return false;
+  const entries = Object.entries(fields);
+  return (
+    hasOnlyKeys(value, Object.keys(fields)) &&
+    entries.every(([key, validate]) =>
+      validate(Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined),
+    )
+  );
+}

package/src/infra/isInfraWorkloadHealth.ts

@@ -0,0 +1,38 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import { infraFields } from './infraFields';
+import { isInfraShape } from './isInfraShape';
+
+/*** Validate runtime-neutral readiness probes and bounded numeric parameters. */
+export function isInfraWorkloadHealth(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const timing = {
+    intervalSeconds: infraFields.optionalPositiveInteger,
+    timeoutSeconds: infraFields.optionalPositiveInteger,
+    failureThreshold: infraFields.optionalPositiveInteger,
+  };
+  switch (value.kind) {
+    case 'http':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'http',
+        port: infraFields.port,
+        path: (path) => typeof path === 'string' && path.startsWith('/'),
+      });
+    case 'tcp':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'tcp',
+        port: infraFields.port,
+      });
+    case 'command':
+      return isInfraShape(value, {
+        ...timing,
+        kind: (kind) => kind === 'command',
+        command: (command) =>
+          Array.isArray(command) && command.length > 0 && infraFields.strings(command),
+      });
+    default:
+      return false;
+  }
+}

package/src/infra/isInfraWorkloadSpec.ts

@@ -0,0 +1,87 @@
+import { isStringArray } from '@ankhorage/utility/array';
+import { isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import type { InfraShape } from '../types/infraValidation';
+import type { InfraWorkloadSpec } from '../types/infraWorkload';
+import { infraFields } from './infraFields';
+import { isInfraShape } from './isInfraShape';
+import { isInfraWorkloadHealth } from './isInfraWorkloadHealth';
+import { isInfraWorkloadValue } from './isInfraWorkloadValue';
+
+/*** Validate the portable desired workload; runtime-specific fields and plaintext secret objects fail. */
+export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec {
+  return isInfraShape(value, {
+    id: isNonEmptyString,
+    artifact: (artifact) =>
+      isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),
+    command: infraFields.optionalStrings,
+    args: (args) => args === undefined || isStringArray(args),
+    ports: (ports) =>
+      ports === undefined ||
+      (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),
+    environment: (environment) =>
+      environment === undefined ||
+      (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),
+    files: (files) =>
+      files === undefined ||
+      (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),
+    health: (health) => health === undefined || isInfraWorkloadHealth(health),
+    resources: (resources) =>
+      resources === undefined ||
+      isInfraShape(resources, {
+        cpuMillis: infraFields.optionalPositiveInteger,
+        memoryMiB: infraFields.optionalPositiveInteger,
+      }),
+    persistence: (volumes) =>
+      volumes === undefined ||
+      (Array.isArray(volumes) &&
+        volumes.every(isVolume) &&
+        hasUniqueField(volumes, 'id') &&
+        hasUniqueField(volumes, 'mountPath')),
+    exposure: (exposure) =>
+      exposure === undefined || exposure === 'internal' || exposure === 'public',
+    replicas: infraFields.optionalNonnegativeInteger,
+    dependsOn: infraFields.optionalStrings,
+  } satisfies InfraShape<InfraWorkloadSpec>);
+}
+
+/*** Named transport ports stay independent from runtime resource types. */
+function isPort(value: unknown): boolean {
+  return isInfraShape(value, {
+    name: isNonEmptyString,
+    port: infraFields.port,
+    protocol: (protocol) => protocol === undefined || protocol === 'tcp' || protocol === 'udp',
+  });
+}
+
+/*** Portable files model policy/config materialization without host filesystem access. */
+function isFile(value: unknown): boolean {
+  return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });
+}
+
+/*** Persistence has explicit ownership-local identity and a retention policy. */
+function isVolume(value: unknown): boolean {
+  return isInfraShape(value, {
+    id: isNonEmptyString,
+    mountPath: isAbsoluteWorkloadPath,
+    sizeGiB: infraFields.positiveInteger,
+    retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',
+  });
+}
+
+/*** Workload paths are absolute container paths, never relative host traversal. */
+function isAbsoluteWorkloadPath(value: unknown): boolean {
+  return (
+    typeof value === 'string' &&
+    value.startsWith('/') &&
+    value.length > 1 &&
+    !value.split('/').includes('..')
+  );
+}
+
+/*** Duplicate workload-local identities would make runtime projection ambiguous. */
+function hasUniqueField(values: readonly unknown[], field: string): boolean {
+  const ids = values.map((value) => (isRecord(value) ? Reflect.get(value, field) : undefined));
+  return new Set(ids).size === ids.length;
+}

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);
+  });
+});