@ankhorage/contracts 19.3.0 → 19.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/contracts
 
+## 19.4.0
+
+### Minor Changes
+
+- 59277a2: Add portable image-seeded initialization for persistent workload volumes.
+
 ## 19.3.0
 
 ### Minor Changes

package/dist/infra/isInfraWorkloadSpec.js

@@ -66,12 +66,13 @@ function hasValidPublishedPorts(workload) {
 function isFile(value) {
     return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });
 }
-/*** Persistence has explicit ownership-local identity and a retention policy. */
+/*** Persistence has explicit ownership-local identity, optional initialization and retention policy. */
 function isVolume(value) {
     return isInfraShape(value, {
         id: isNonEmptyString,
         mountPath: isAbsoluteWorkloadPath,
         sizeGiB: infraFields.positiveInteger,
+        seed: (seed) => seed === undefined || seed === 'image',
         retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',
     });
 }

package/dist/infra/isInfraWorkloadSpec.js.map

@@ -1 +1 @@
-{"version":3,"file":"isInfraWorkloadSpec.js","sourceRoot":"","sources":["../../src/infra/isInfraWorkloadSpec.ts"],"names":[],"mappings":"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","sourcesContent":["import { isStringArray } from '@ankhorage/utility/array';\nimport { isRecord } from '@ankhorage/utility/object';\nimport { isNonEmptyString } from '@ankhorage/utility/string';\n\nimport type { InfraShape } from '../types/infraValidation';\nimport type { InfraWorkloadSpec } from '../types/infraWorkload';\nimport { infraFields } from './infraFields';\nimport { isInfraShape } from './isInfraShape';\nimport { isInfraWorkloadHealth } from './isInfraWorkloadHealth';\nimport { isInfraWorkloadValue } from './isInfraWorkloadValue';\n\n/*** Validate the portable desired workload; runtime-specific fields and plaintext secret objects fail. */\nexport function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec {\n  if (\n    !isInfraShape(value, {\n      id: isNonEmptyString,\n      artifact: (artifact) =>\n        isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),\n      command: infraFields.optionalStrings,\n      args: (args) => args === undefined || isStringArray(args),\n      ports: (ports) =>\n        ports === undefined ||\n        (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),\n      environment: (environment) =>\n        environment === undefined ||\n        (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),\n      files: (files) =>\n        files === undefined ||\n        (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),\n      health: (health) => health === undefined || isInfraWorkloadHealth(health),\n      resources: (resources) =>\n        resources === undefined ||\n        isInfraShape(resources, {\n          cpuMillis: infraFields.optionalPositiveInteger,\n          memoryMiB: infraFields.optionalPositiveInteger,\n        }),\n      persistence: (volumes) =>\n        volumes === undefined ||\n        (Array.isArray(volumes) &&\n          volumes.every(isVolume) &&\n          hasUniqueField(volumes, 'id') &&\n          hasUniqueField(volumes, 'mountPath')),\n      exposure: (exposure) =>\n        exposure === undefined || exposure === 'internal' || exposure === 'public',\n      replicas: infraFields.optionalNonnegativeInteger,\n      dependsOn: infraFields.optionalStrings,\n    } satisfies InfraShape<InfraWorkloadSpec>)\n  ) {\n    return false;\n  }\n  return hasValidPublishedPorts(value);\n}\n\n/*** Named transport ports stay independent from runtime resource types. */\nfunction isPort(value: unknown): boolean {\n  return isInfraShape(value, {\n    name: isNonEmptyString,\n    port: infraFields.port,\n    protocol: (protocol) => protocol === undefined || protocol === 'tcp' || protocol === 'udp',\n    publishedPort: infraFields.optionalPort,\n  });\n}\n\n/*** Require fixed external listeners to belong to one public workload replica. */\nfunction hasValidPublishedPorts(workload: unknown): boolean {\n  if (!isRecord(workload)) return false;\n  const ports = Array.isArray(workload.ports) ? workload.ports : [];\n  const published = ports.flatMap((port) => {\n    if (!isRecord(port) || typeof port.publishedPort !== 'number') return [];\n    return [port.publishedPort];\n  });\n  return (\n    new Set(published).size === published.length &&\n    (published.length === 0 ||\n      (workload.exposure === 'public' &&\n        (workload.replicas === undefined ||\n          (typeof workload.replicas === 'number' && workload.replicas <= 1))))\n  );\n}\n\n/*** Portable files model policy/config materialization without host filesystem access. */\nfunction isFile(value: unknown): boolean {\n  return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });\n}\n\n/*** Persistence has explicit ownership-local identity and a retention policy. */\nfunction isVolume(value: unknown): boolean {\n  return isInfraShape(value, {\n    id: isNonEmptyString,\n    mountPath: isAbsoluteWorkloadPath,\n    sizeGiB: infraFields.positiveInteger,\n    retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',\n  });\n}\n\n/*** Workload paths are absolute container paths, never relative host traversal. */\nfunction isAbsoluteWorkloadPath(value: unknown): boolean {\n  return (\n    typeof value === 'string' &&\n    value.startsWith('/') &&\n    value.length > 1 &&\n    !value.split('/').includes('..')\n  );\n}\n\n/*** Duplicate workload-local identities would make runtime projection ambiguous. */\nfunction hasUniqueField(values: readonly unknown[], field: string): boolean {\n  const ids = values.map((value) => (isRecord(value) ? Reflect.get(value, field) : undefined));\n  return new Set(ids).size === ids.length;\n}\n"]}
+{"version":3,"file":"isInfraWorkloadSpec.js","sourceRoot":"","sources":["../../src/infra/isInfraWorkloadSpec.ts"],"names":[],"mappings":"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","sourcesContent":["import { isStringArray } from '@ankhorage/utility/array';\nimport { isRecord } from '@ankhorage/utility/object';\nimport { isNonEmptyString } from '@ankhorage/utility/string';\n\nimport type { InfraShape } from '../types/infraValidation';\nimport type { InfraWorkloadSpec } from '../types/infraWorkload';\nimport { infraFields } from './infraFields';\nimport { isInfraShape } from './isInfraShape';\nimport { isInfraWorkloadHealth } from './isInfraWorkloadHealth';\nimport { isInfraWorkloadValue } from './isInfraWorkloadValue';\n\n/*** Validate the portable desired workload; runtime-specific fields and plaintext secret objects fail. */\nexport function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec {\n  if (\n    !isInfraShape(value, {\n      id: isNonEmptyString,\n      artifact: (artifact) =>\n        isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),\n      command: infraFields.optionalStrings,\n      args: (args) => args === undefined || isStringArray(args),\n      ports: (ports) =>\n        ports === undefined ||\n        (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),\n      environment: (environment) =>\n        environment === undefined ||\n        (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),\n      files: (files) =>\n        files === undefined ||\n        (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),\n      health: (health) => health === undefined || isInfraWorkloadHealth(health),\n      resources: (resources) =>\n        resources === undefined ||\n        isInfraShape(resources, {\n          cpuMillis: infraFields.optionalPositiveInteger,\n          memoryMiB: infraFields.optionalPositiveInteger,\n        }),\n      persistence: (volumes) =>\n        volumes === undefined ||\n        (Array.isArray(volumes) &&\n          volumes.every(isVolume) &&\n          hasUniqueField(volumes, 'id') &&\n          hasUniqueField(volumes, 'mountPath')),\n      exposure: (exposure) =>\n        exposure === undefined || exposure === 'internal' || exposure === 'public',\n      replicas: infraFields.optionalNonnegativeInteger,\n      dependsOn: infraFields.optionalStrings,\n    } satisfies InfraShape<InfraWorkloadSpec>)\n  ) {\n    return false;\n  }\n  return hasValidPublishedPorts(value);\n}\n\n/*** Named transport ports stay independent from runtime resource types. */\nfunction isPort(value: unknown): boolean {\n  return isInfraShape(value, {\n    name: isNonEmptyString,\n    port: infraFields.port,\n    protocol: (protocol) => protocol === undefined || protocol === 'tcp' || protocol === 'udp',\n    publishedPort: infraFields.optionalPort,\n  });\n}\n\n/*** Require fixed external listeners to belong to one public workload replica. */\nfunction hasValidPublishedPorts(workload: unknown): boolean {\n  if (!isRecord(workload)) return false;\n  const ports = Array.isArray(workload.ports) ? workload.ports : [];\n  const published = ports.flatMap((port) => {\n    if (!isRecord(port) || typeof port.publishedPort !== 'number') return [];\n    return [port.publishedPort];\n  });\n  return (\n    new Set(published).size === published.length &&\n    (published.length === 0 ||\n      (workload.exposure === 'public' &&\n        (workload.replicas === undefined ||\n          (typeof workload.replicas === 'number' && workload.replicas <= 1))))\n  );\n}\n\n/*** Portable files model policy/config materialization without host filesystem access. */\nfunction isFile(value: unknown): boolean {\n  return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });\n}\n\n/*** Persistence has explicit ownership-local identity, optional initialization and retention policy. */\nfunction isVolume(value: unknown): boolean {\n  return isInfraShape(value, {\n    id: isNonEmptyString,\n    mountPath: isAbsoluteWorkloadPath,\n    sizeGiB: infraFields.positiveInteger,\n    seed: (seed) => seed === undefined || seed === 'image',\n    retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',\n  });\n}\n\n/*** Workload paths are absolute container paths, never relative host traversal. */\nfunction isAbsoluteWorkloadPath(value: unknown): boolean {\n  return (\n    typeof value === 'string' &&\n    value.startsWith('/') &&\n    value.length > 1 &&\n    !value.split('/').includes('..')\n  );\n}\n\n/*** Duplicate workload-local identities would make runtime projection ambiguous. */\nfunction hasUniqueField(values: readonly unknown[], field: string): boolean {\n  const ids = values.map((value) => (isRecord(value) ? Reflect.get(value, field) : undefined));\n  return new Set(ids).size === ids.length;\n}\n"]}

package/dist/types/infraWorkload.d.ts

@@ -54,6 +54,8 @@ export interface InfraWorkloadVolumeSpec {
     readonly id: string;
     readonly mountPath: string;
     readonly sizeGiB: number;
+    /** Seed a newly created empty volume from the image contents at mountPath before workload start. */
+    readonly seed?: 'image';
     /** Persistence survives down and is retained by default on destroy. */
     readonly retention: 'retain' | 'delete-on-destroy';
 }

package/dist/types/infraWorkload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"infraWorkload.d.ts","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"infraWorkload.d.ts","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"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"}

package/dist/types/infraWorkload.js.map

@@ -1 +1 @@
-{"version":3,"file":"infraWorkload.js","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"","sourcesContent":["import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';\n\nexport interface InfraWorkloadArtifact {\n  readonly kind: 'image';\n  /** Prebuilt image, optionally pinned by digest. No registry/build provider requirement. */\n  readonly image: string;\n}\n\nexport type InfraWorkloadScalarValue =\n  | { readonly kind: 'literal'; readonly value: string }\n  | { readonly kind: 'secret'; readonly reference: InfraSecretReference }\n  | {\n      readonly kind: 'credential';\n      readonly reference: InfraControlPlaneCredentialRef;\n      readonly key: string;\n    }\n  | { readonly kind: 'output'; readonly resourceId: string; readonly output: string };\n\nexport type InfraWorkloadValue =\n  | InfraWorkloadScalarValue\n  | {\n      readonly kind: 'template';\n      /** Ordered scalar segments materialized into one value only at the runtime boundary. */\n      readonly segments: readonly InfraWorkloadScalarValue[];\n    };\n\nexport interface InfraWorkloadPort {\n  readonly name: string;\n  readonly port: number;\n  readonly protocol?: 'tcp' | 'udp';\n  /** Exact external listener port requested for a public single-replica workload. */\n  readonly publishedPort?: number;\n}\n\nexport type InfraWorkloadHealthSpec = {\n  readonly intervalSeconds?: number;\n  readonly timeoutSeconds?: number;\n  readonly failureThreshold?: number;\n} & (\n  | { readonly kind: 'http'; readonly port: number; readonly path: string }\n  | { readonly kind: 'tcp'; readonly port: number }\n  | { readonly kind: 'command'; readonly command: readonly string[] }\n);\n\nexport interface InfraWorkloadResourceSpec {\n  readonly cpuMillis?: number;\n  readonly memoryMiB?: number;\n}\n\nexport interface InfraWorkloadVolumeSpec {\n  readonly id: string;\n  readonly mountPath: string;\n  readonly sizeGiB: number;\n  /** Persistence survives down and is retained by default on destroy. */\n  readonly retention: 'retain' | 'delete-on-destroy';\n}\n\n/** Portable config/policy files; secret values are materialized by the runtime. */\nexport interface InfraWorkloadFileSpec {\n  readonly path: string;\n  readonly content: InfraWorkloadValue;\n}\n\nexport interface InfraWorkloadSpec {\n  readonly id: string;\n  readonly artifact: InfraWorkloadArtifact;\n  readonly command?: readonly string[];\n  readonly args?: readonly string[];\n  readonly ports?: readonly InfraWorkloadPort[];\n  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;\n  readonly files?: readonly InfraWorkloadFileSpec[];\n  readonly health?: InfraWorkloadHealthSpec;\n  readonly resources?: InfraWorkloadResourceSpec;\n  readonly persistence?: readonly InfraWorkloadVolumeSpec[];\n  readonly exposure?: 'internal' | 'public';\n  readonly replicas?: number;\n  /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */\n  readonly dependsOn?: readonly string[];\n}\n"]}
+{"version":3,"file":"infraWorkload.js","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"","sourcesContent":["import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';\n\nexport interface InfraWorkloadArtifact {\n  readonly kind: 'image';\n  /** Prebuilt image, optionally pinned by digest. No registry/build provider requirement. */\n  readonly image: string;\n}\n\nexport type InfraWorkloadScalarValue =\n  | { readonly kind: 'literal'; readonly value: string }\n  | { readonly kind: 'secret'; readonly reference: InfraSecretReference }\n  | {\n      readonly kind: 'credential';\n      readonly reference: InfraControlPlaneCredentialRef;\n      readonly key: string;\n    }\n  | { readonly kind: 'output'; readonly resourceId: string; readonly output: string };\n\nexport type InfraWorkloadValue =\n  | InfraWorkloadScalarValue\n  | {\n      readonly kind: 'template';\n      /** Ordered scalar segments materialized into one value only at the runtime boundary. */\n      readonly segments: readonly InfraWorkloadScalarValue[];\n    };\n\nexport interface InfraWorkloadPort {\n  readonly name: string;\n  readonly port: number;\n  readonly protocol?: 'tcp' | 'udp';\n  /** Exact external listener port requested for a public single-replica workload. */\n  readonly publishedPort?: number;\n}\n\nexport type InfraWorkloadHealthSpec = {\n  readonly intervalSeconds?: number;\n  readonly timeoutSeconds?: number;\n  readonly failureThreshold?: number;\n} & (\n  | { readonly kind: 'http'; readonly port: number; readonly path: string }\n  | { readonly kind: 'tcp'; readonly port: number }\n  | { readonly kind: 'command'; readonly command: readonly string[] }\n);\n\nexport interface InfraWorkloadResourceSpec {\n  readonly cpuMillis?: number;\n  readonly memoryMiB?: number;\n}\n\nexport interface InfraWorkloadVolumeSpec {\n  readonly id: string;\n  readonly mountPath: string;\n  readonly sizeGiB: number;\n  /** Seed a newly created empty volume from the image contents at mountPath before workload start. */\n  readonly seed?: 'image';\n  /** Persistence survives down and is retained by default on destroy. */\n  readonly retention: 'retain' | 'delete-on-destroy';\n}\n\n/** Portable config/policy files; secret values are materialized by the runtime. */\nexport interface InfraWorkloadFileSpec {\n  readonly path: string;\n  readonly content: InfraWorkloadValue;\n}\n\nexport interface InfraWorkloadSpec {\n  readonly id: string;\n  readonly artifact: InfraWorkloadArtifact;\n  readonly command?: readonly string[];\n  readonly args?: readonly string[];\n  readonly ports?: readonly InfraWorkloadPort[];\n  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;\n  readonly files?: readonly InfraWorkloadFileSpec[];\n  readonly health?: InfraWorkloadHealthSpec;\n  readonly resources?: InfraWorkloadResourceSpec;\n  readonly persistence?: readonly InfraWorkloadVolumeSpec[];\n  readonly exposure?: 'internal' | 'public';\n  readonly replicas?: number;\n  /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */\n  readonly dependsOn?: readonly string[];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "19.3.0",
+  "version": "19.4.0",
   "main": "./dist/index.js",
   "ankh": {
     "category": "contracts",

package/src/infra/isInfraWorkloadSpec.ts

@@ -83,12 +83,13 @@ function isFile(value: unknown): boolean {
   return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });
 }
 
-/*** Persistence has explicit ownership-local identity and a retention policy. */
+/*** Persistence has explicit ownership-local identity, optional initialization and retention policy. */
 function isVolume(value: unknown): boolean {
   return isInfraShape(value, {
     id: isNonEmptyString,
     mountPath: isAbsoluteWorkloadPath,
     sizeGiB: infraFields.positiveInteger,
+    seed: (seed) => seed === undefined || seed === 'image',
     retention: (retention) => retention === 'retain' || retention === 'delete-on-destroy',
   });
 }

package/src/infra-workload-persistence.test.ts

@@ -0,0 +1,30 @@
+import { expect, it } from 'bun:test';
+
+import { isInfraWorkloadSpec } from './infra';
+
+const workload = {
+  id: 'database',
+  artifact: { kind: 'image', image: 'example/database:1' },
+  persistence: [
+    {
+      id: 'config',
+      mountPath: '/etc/database-custom',
+      sizeGiB: 1,
+      seed: 'image',
+      retention: 'retain',
+    },
+  ],
+} as const;
+
+it('accepts image-seeded persistence initialization', () => {
+  expect(isInfraWorkloadSpec(workload)).toBe(true);
+});
+
+it('rejects unsupported persistence initialization modes', () => {
+  expect(
+    isInfraWorkloadSpec({
+      ...workload,
+      persistence: [{ ...workload.persistence[0], seed: 'empty' }],
+    }),
+  ).toBe(false);
+});

package/src/infra.test.ts

@@ -140,39 +140,6 @@ describe('runtime topology configuration', () => {
   });
 });
 
-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 } },
-    { networking: { publicBaseUrl: 'ftp://api.example.ch' } },
-    { networking: { publicBaseUrl: 'https://api.example.ch/auth/v1' } },
-    { networking: { publicBaseUrl: 'https://api.example.ch/' } },
-  ])('rejects unsupported service selection: %j', (selection) => {
-    expect(isInfraEnvironmentSpec({ ...local, ...selection })).toBe(false);
-  });
-});
-
 describe('Cerbos policy configuration', () => {
   it('accepts portable policy files', () => {
     expect(

package/src/infraServices.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'bun:test';
+
+import { type InfraEnvironmentSpec, isInfraEnvironmentSpec } 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', publicBaseUrl: 'https://api.example.ch' },
+} as const satisfies InfraEnvironmentSpec;
+
+const invalidServiceSelections: Record<string, unknown>[] = [
+  { 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' } },
+];
+
+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(invalidServiceSelections)('rejects unsupported service selection: %j', (selection) => {
+    expect(isInfraEnvironmentSpec({ ...local, ...selection })).toBe(false);
+  });
+});

package/src/types/infraWorkload.ts

@@ -51,6 +51,8 @@ export interface InfraWorkloadVolumeSpec {
   readonly id: string;
   readonly mountPath: string;
   readonly sizeGiB: number;
+  /** Seed a newly created empty volume from the image contents at mountPath before workload start. */
+  readonly seed?: 'image';
   /** Persistence survives down and is retained by default on destroy. */
   readonly retention: 'retain' | 'delete-on-destroy';
 }