@ankhorage/contracts 22.0.4 → 22.1.0

package/src/structure/isStructureDescriptorDocument.ts

@@ -0,0 +1,164 @@
+import { hasOnlyKeys, isRecord } from '@ankhorage/utility/object';
+import { isNonEmptyString } from '@ankhorage/utility/string';
+
+import { isStructureDescriptor } from './isStructureDescriptor';
+import type {
+  StructureDescriptor,
+  StructureDescriptorDefinition,
+  StructureDescriptorDocument,
+  StructureDescriptorId,
+  StructureDescriptorRegistry,
+} from './types';
+
+/*** Validate a complete package structural-descriptor document and all resolvable references. */
+export function isStructureDescriptorDocument(
+  value: unknown,
+): value is StructureDescriptorDocument {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'protocolVersion',
+      'packageName',
+      'packageVersion',
+      'roots',
+      'descriptors',
+    ]) ||
+    value.protocolVersion !== 1 ||
+    !isNonEmptyString(value.packageName) ||
+    !isNonEmptyString(value.packageVersion) ||
+    !isRootMap(value.roots) ||
+    !isDescriptorRegistry(value.descriptors)
+  ) {
+    return false;
+  }
+
+  const document: StructureDescriptorDocument = {
+    protocolVersion: 1,
+    packageName: value.packageName,
+    packageVersion: value.packageVersion,
+    roots: value.roots,
+    descriptors: value.descriptors,
+  };
+  return hasResolvableRoots(document) && isDescriptorGraphValid(document);
+}
+
+/*** Validate the root-name to local-descriptor-ID map. */
+function isRootMap(value: unknown): value is Readonly<Record<string, StructureDescriptorId>> {
+  return (
+    isRecord(value) &&
+    Object.keys(value).length > 0 &&
+    Object.entries(value).every(
+      ([name, descriptorId]) => isNonEmptyString(name) && isNonEmptyString(descriptorId),
+    )
+  );
+}
+
+/*** Validate descriptor definitions and enforce record-key to definition-ID identity. */
+function isDescriptorRegistry(value: unknown): value is StructureDescriptorRegistry {
+  return (
+    isRecord(value) &&
+    Object.keys(value).length > 0 &&
+    Object.entries(value).every(([descriptorId, definition]) =>
+      isDefinition(definition, descriptorId),
+    )
+  );
+}
+
+/*** Validate one descriptor definition against its stable registry key. */
+function isDefinition(
+  value: unknown,
+  descriptorId: string,
+): value is StructureDescriptorDefinition {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['id', 'descriptor']) &&
+    value.id === descriptorId &&
+    isNonEmptyString(value.id) &&
+    isStructureDescriptor(value.descriptor)
+  );
+}
+
+/*** Require every document root to resolve to one local descriptor definition. */
+function hasResolvableRoots(document: StructureDescriptorDocument): boolean {
+  const descriptors = new Map(Object.entries(document.descriptors));
+  return Object.values(document.roots).every((descriptorId) => descriptors.has(descriptorId));
+}
+
+/*** Validate local references, recursive graphs, and string-only collection key/member descriptors. */
+function isDescriptorGraphValid(document: StructureDescriptorDocument): boolean {
+  const definitions = new Map(Object.entries(document.descriptors));
+  return Array.from(definitions.values()).every((definition) =>
+    validateGraphNode(definition.descriptor, document, new Set()),
+  );
+}
+
+/*** Validate one graph node while treating revisited local refs as a valid recursive cycle. */
+function validateGraphNode(
+  descriptor: StructureDescriptor,
+  document: StructureDescriptorDocument,
+  visitedRefs: Set<string>,
+): boolean {
+  switch (descriptor.kind) {
+    case 'object':
+      return Object.values(descriptor.fields).every((field) =>
+        validateGraphNode(field.value, document, new Set(visitedRefs)),
+      );
+    case 'entity-registry':
+    case 'value-map':
+      return (
+        isStringCompatible(descriptor.key, document, new Set()) &&
+        validateGraphNode(descriptor.value, document, new Set(visitedRefs))
+      );
+    case 'set':
+      return isStringCompatible(descriptor.member, document, new Set());
+    case 'ordered-list':
+      return validateGraphNode(descriptor.item, document, new Set(visitedRefs));
+    case 'union':
+      return descriptor.variants.every((variant) =>
+        validateGraphNode(variant, document, new Set(visitedRefs)),
+      );
+    case 'ref':
+      return validateReference(descriptor, document, visitedRefs);
+    default:
+      return true;
+  }
+}
+
+/*** Resolve and validate one local reference while deferring package-qualified refs to composition. */
+function validateReference(
+  descriptor: Extract<StructureDescriptor, { readonly kind: 'ref' }>,
+  document: StructureDescriptorDocument,
+  visitedRefs: Set<string>,
+): boolean {
+  if (descriptor.packageName && descriptor.packageName !== document.packageName) return true;
+  if (visitedRefs.has(descriptor.id)) return true;
+
+  const definition = new Map(Object.entries(document.descriptors)).get(descriptor.id);
+  if (!definition) return false;
+
+  const nextRefs = new Set(visitedRefs);
+  nextRefs.add(descriptor.id);
+  return validateGraphNode(definition.descriptor, document, nextRefs);
+}
+
+/*** Prove that a collection key/member descriptor is string-valued when locally resolvable. */
+function isStringCompatible(
+  descriptor: StructureDescriptor,
+  document: StructureDescriptorDocument,
+  visitedRefs: Set<string>,
+): boolean {
+  if (descriptor.kind === 'scalar') return descriptor.type === 'string';
+  if (descriptor.kind === 'enum') {
+    return descriptor.values.every((value) => typeof value === 'string');
+  }
+  if (descriptor.kind !== 'ref') return false;
+  if (descriptor.packageName && descriptor.packageName !== document.packageName) return true;
+  if (visitedRefs.has(descriptor.id)) return false;
+
+  const definition = new Map(Object.entries(document.descriptors)).get(descriptor.id);
+  if (!definition) return false;
+
+  const nextRefs = new Set(visitedRefs);
+  nextRefs.add(descriptor.id);
+  return isStringCompatible(definition.descriptor, document, nextRefs);
+}

package/src/structure/types.ts

@@ -0,0 +1,92 @@
+import type { EntityRegistry, ValueMap } from '../collections';
+
+export type StructureDescriptorId = string;
+
+export type StructureScalarType = 'boolean' | 'integer' | 'null' | 'number' | 'string';
+
+export type StructureLiteralValue = boolean | number | string | null;
+
+export interface StructureScalarDescriptor {
+  readonly kind: 'scalar';
+  readonly type: StructureScalarType;
+}
+
+export interface StructureEnumDescriptor {
+  readonly kind: 'enum';
+  readonly values: readonly StructureLiteralValue[];
+}
+
+export interface StructureObjectField {
+  readonly value: StructureDescriptor;
+  readonly optional?: boolean;
+}
+
+export interface StructureObjectDescriptor {
+  readonly kind: 'object';
+  readonly fields: ValueMap<string, StructureObjectField>;
+}
+
+export interface StructureEntityRegistryDescriptor {
+  readonly kind: 'entity-registry';
+  readonly key: StructureDescriptor;
+  readonly value: StructureDescriptor;
+  readonly identityField?: string;
+}
+
+export interface StructureValueMapDescriptor {
+  readonly kind: 'value-map';
+  readonly key: StructureDescriptor;
+  readonly value: StructureDescriptor;
+}
+
+export interface StructureSetDescriptor {
+  readonly kind: 'set';
+  readonly member: StructureDescriptor;
+}
+
+export interface StructureOrderedListDescriptor {
+  readonly kind: 'ordered-list';
+  readonly item: StructureDescriptor;
+}
+
+export interface StructureUnionDescriptor {
+  readonly kind: 'union';
+  readonly variants: readonly StructureDescriptor[];
+  readonly discriminator?: string;
+}
+
+export interface StructureReferenceDescriptor {
+  readonly kind: 'ref';
+  readonly id: StructureDescriptorId;
+  readonly packageName?: string;
+}
+
+export type StructureDescriptor =
+  | StructureEntityRegistryDescriptor
+  | StructureEnumDescriptor
+  | StructureObjectDescriptor
+  | StructureOrderedListDescriptor
+  | StructureReferenceDescriptor
+  | StructureScalarDescriptor
+  | StructureSetDescriptor
+  | StructureUnionDescriptor
+  | StructureValueMapDescriptor;
+
+export interface StructureDescriptorDefinition {
+  readonly id: StructureDescriptorId;
+  readonly descriptor: StructureDescriptor;
+}
+
+export type StructureDescriptorRegistry = EntityRegistry<
+  StructureDescriptorId,
+  StructureDescriptorDefinition,
+  'id'
+>;
+
+export interface StructureDescriptorDocument {
+  readonly protocolVersion: 1;
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly roots: ValueMap<string, StructureDescriptorId>;
+  readonly descriptors: StructureDescriptorRegistry;
+}

package/src/structure.test.ts

@@ -0,0 +1,255 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { expect, test } from 'bun:test';
+
+import {
+  isStructureDescriptor,
+  isStructureDescriptorDocument,
+  type StructureDescriptorDocument,
+} from './structure';
+
+test('accepts scalar, enum and object descriptors', () => {
+  expect(isStructureDescriptor({ kind: 'scalar', type: 'string' })).toBe(true);
+  expect(isStructureDescriptor({ kind: 'enum', values: ['light', 'dark'] })).toBe(true);
+  expect(
+    isStructureDescriptor({
+      kind: 'object',
+      fields: {
+        name: { value: { kind: 'scalar', type: 'string' } },
+        enabled: { value: { kind: 'scalar', type: 'boolean' }, optional: true },
+      },
+    }),
+  ).toBe(true);
+});
+
+test('accepts registry, map, set and ordered-list descriptors', () => {
+  expect(
+    isStructureDescriptor({
+      kind: 'entity-registry',
+      key: { kind: 'scalar', type: 'string' },
+      value: { kind: 'ref', id: 'theme' },
+      identityField: 'id',
+    }),
+  ).toBe(true);
+  expect(
+    isStructureDescriptor({
+      kind: 'value-map',
+      key: { kind: 'scalar', type: 'string' },
+      value: { kind: 'scalar', type: 'number' },
+    }),
+  ).toBe(true);
+  expect(
+    isStructureDescriptor({
+      kind: 'set',
+      member: { kind: 'enum', values: ['camera', 'microphone'] },
+    }),
+  ).toBe(true);
+  expect(
+    isStructureDescriptor({
+      kind: 'ordered-list',
+      item: { kind: 'scalar', type: 'string' },
+    }),
+  ).toBe(true);
+});
+
+test('accepts unions and references', () => {
+  expect(
+    isStructureDescriptor({
+      kind: 'union',
+      discriminator: 'kind',
+      variants: [
+        { kind: 'ref', id: 'literal-source' },
+        { kind: 'ref', id: 'state-source' },
+      ],
+    }),
+  ).toBe(true);
+  expect(
+    isStructureDescriptor({
+      kind: 'ref',
+      packageName: '@ankhorage/example-owner',
+      id: 'external-config',
+    }),
+  ).toBe(true);
+});
+
+test('rejects malformed scalar and union declarations', () => {
+  expect(isStructureDescriptor({ kind: 'unknown' })).toBe(false);
+  expect(isStructureDescriptor({ kind: 'enum', values: [] })).toBe(false);
+  expect(isStructureDescriptor({ kind: 'enum', values: ['x', 'x'] })).toBe(false);
+  expect(isStructureDescriptor({ kind: 'enum', values: [Number.NaN] })).toBe(false);
+  expect(
+    isStructureDescriptor({
+      kind: 'union',
+      variants: [{ kind: 'scalar', type: 'string' }],
+    }),
+  ).toBe(false);
+});
+
+test('rejects non-string map keys and set members', () => {
+  expect(
+    isStructureDescriptor({
+      kind: 'value-map',
+      key: { kind: 'scalar', type: 'number' },
+      value: { kind: 'scalar', type: 'string' },
+    }),
+  ).toBe(false);
+  expect(
+    isStructureDescriptor({
+      kind: 'set',
+      member: { kind: 'scalar', type: 'boolean' },
+    }),
+  ).toBe(false);
+});
+
+test('rejects cyclic inline object graphs without overflowing', () => {
+  const cyclic: Record<string, unknown> = {
+    kind: 'object',
+    fields: {},
+  };
+  cyclic.fields = {
+    self: { value: cyclic },
+  };
+
+  expect(isStructureDescriptor(cyclic)).toBe(false);
+});
+
+test('accepts recursive local and package-qualified references', () => {
+  expect(isStructureDescriptorDocument(STRUCTURE_DOCUMENT_FIXTURE)).toBe(true);
+  expect(JSON.parse(JSON.stringify(STRUCTURE_DOCUMENT_FIXTURE))).toEqual(
+    STRUCTURE_DOCUMENT_FIXTURE,
+  );
+});
+
+test('rejects unresolved local roots and references', () => {
+  expect(
+    isStructureDescriptorDocument({
+      ...STRUCTURE_DOCUMENT_FIXTURE,
+      roots: { app: 'missing' },
+    }),
+  ).toBe(false);
+  expect(
+    isStructureDescriptorDocument({
+      ...STRUCTURE_DOCUMENT_FIXTURE,
+      descriptors: {
+        ...STRUCTURE_DOCUMENT_FIXTURE.descriptors,
+        app: {
+          id: 'app',
+          descriptor: { kind: 'ref', id: 'missing' },
+        },
+      },
+    }),
+  ).toBe(false);
+});
+
+test('rejects registry key and definition identity mismatches', () => {
+  expect(
+    isStructureDescriptorDocument({
+      ...STRUCTURE_DOCUMENT_FIXTURE,
+      descriptors: {
+        ...STRUCTURE_DOCUMENT_FIXTURE.descriptors,
+        app: {
+          id: 'different-id',
+          descriptor: { kind: 'scalar', type: 'string' },
+        },
+      },
+    }),
+  ).toBe(false);
+});
+
+test('proves referenced set members are strings', () => {
+  expect(
+    isStructureDescriptorDocument({
+      ...STRUCTURE_DOCUMENT_FIXTURE,
+      descriptors: {
+        ...STRUCTURE_DOCUMENT_FIXTURE.descriptors,
+        numeric: {
+          id: 'numeric',
+          descriptor: { kind: 'scalar', type: 'number' },
+        },
+        app: {
+          id: 'app',
+          descriptor: {
+            kind: 'set',
+            member: { kind: 'ref', id: 'numeric' },
+          },
+        },
+      },
+    }),
+  ).toBe(false);
+});
+
+test('publishes the dedicated structure subpath', async () => {
+  const packageJson = JSON.parse(await readFile(join(process.cwd(), 'package.json'), 'utf8')) as {
+    exports?: Readonly<Record<string, { default?: string; types?: string }>>;
+  };
+  const exports = new Map(Object.entries(packageJson.exports ?? {}));
+
+  expect(exports.get('./structure')).toEqual({
+    types: './dist/structure/index.d.ts',
+    default: './dist/structure/index.js',
+  });
+});
+
+const STRUCTURE_DOCUMENT_FIXTURE = {
+  protocolVersion: 1,
+  packageName: '@ankhorage/contracts',
+  packageVersion: '0.0.0-test',
+  roots: { app: 'app' },
+  descriptors: {
+    app: {
+      id: 'app',
+      descriptor: {
+        kind: 'object',
+        fields: {
+          themes: {
+            value: {
+              kind: 'entity-registry',
+              key: { kind: 'scalar', type: 'string' },
+              value: { kind: 'ref', id: 'theme' },
+              identityField: 'id',
+            },
+          },
+          permissions: {
+            optional: true,
+            value: {
+              kind: 'set',
+              member: { kind: 'ref', id: 'permission-name' },
+            },
+          },
+          external: {
+            optional: true,
+            value: {
+              kind: 'ref',
+              packageName: '@ankhorage/example-owner',
+              id: 'external-config',
+            },
+          },
+        },
+      },
+    },
+    theme: {
+      id: 'theme',
+      descriptor: {
+        kind: 'object',
+        fields: {
+          id: { value: { kind: 'scalar', type: 'string' } },
+          children: {
+            optional: true,
+            value: {
+              kind: 'ordered-list',
+              item: { kind: 'ref', id: 'theme' },
+            },
+          },
+        },
+      },
+    },
+    'permission-name': {
+      id: 'permission-name',
+      descriptor: {
+        kind: 'enum',
+        values: ['camera', 'microphone'],
+      },
+    },
+  },
+} as const satisfies StructureDescriptorDocument;

package/src/theme.ts

@@ -1,8 +1,10 @@
+import type { ValueMap } from './collections';
+
 /** Numeric token values authored at theme level. */
-export type ThemeNumericTokenOverrides = Readonly<Record<string, number>>;
+export type ThemeNumericTokenOverrides = ValueMap<string, number>;
 
 /** String token values authored at theme level. */
-export type ThemeStringTokenOverrides = Readonly<Record<string, string>>;
+export type ThemeStringTokenOverrides = ValueMap<string, string>;
 
 /** Partial authored override for one semantic heading recipe. */
 export interface ThemeTypographyHeadingOverrides {
@@ -13,7 +15,7 @@ export interface ThemeTypographyHeadingOverrides {
 
 /** Theme-global typography source overrides. Font installation remains module-owned. */
 export interface ThemeTypographyTokenOverrides {
-  readonly headings?: Readonly<Record<string, ThemeTypographyHeadingOverrides>>;
+  readonly headings?: ValueMap<string, ThemeTypographyHeadingOverrides>;
   readonly sizes?: ThemeNumericTokenOverrides;
   readonly weights?: ThemeStringTokenOverrides;
 }
@@ -36,7 +38,7 @@ export interface ThemeGlobalTokenOverrides {
 export type ThemeRecipeOverrideValue = boolean | string;
 
 /** Persisted values for one component or pattern recipe. */
-export type ThemeRecipeFieldOverrides = Readonly<Record<string, ThemeRecipeOverrideValue>>;
+export type ThemeRecipeFieldOverrides = ValueMap<string, ThemeRecipeOverrideValue>;
 
 /**
  * Generic persisted recipe values.
@@ -45,6 +47,6 @@ export type ThemeRecipeFieldOverrides = Readonly<Record<string, ThemeRecipeOverr
  * relationships. Contracts stores selected values only and does not duplicate that metadata.
  */
 export interface ThemeRecipeOverrides {
-  readonly components?: Readonly<Record<string, ThemeRecipeFieldOverrides>>;
-  readonly patterns?: Readonly<Record<string, ThemeRecipeFieldOverrides>>;
+  readonly components?: ValueMap<string, ThemeRecipeFieldOverrides>;
+  readonly patterns?: ValueMap<string, ThemeRecipeFieldOverrides>;
 }

package/src/types/infraManifest.ts

@@ -1,5 +1,5 @@
 import type { AuthFlowConfig, AuthOAuthConfig } from '../auth';
-import type { SerializableSet } from '../collections';
+import type { EntityRegistry, SerializableSet, ValueMap } from '../collections';
 import type { ApiDefinitionRegistry, DataContractValue } from '../data';
 import type { AppEnvironmentId } from '../environments';
 import type { INFRA_ADAPTER_CATALOG, INFRA_RUNTIME_COMPATIBILITY } from '../infra/constants';
@@ -109,7 +109,7 @@ export interface InfraAuthConfigMap {
 export interface InfraAuthzConfigMap {
   readonly cerbos: {
     readonly kind: 'RBAC' | 'ABAC';
-    readonly policies?: Readonly<Record<string, string>>;
+    readonly policies?: ValueMap<string, string>;
   };
 }
 export interface InfraSecretStoreConfigMap {
@@ -167,7 +167,7 @@ export interface InfraModuleSpec {
   readonly config?: DataContractValue;
 }
 
-export type InfraModuleRegistry = Readonly<Record<InfraModuleId, InfraModuleSpec>>;
+export type InfraModuleRegistry = EntityRegistry<InfraModuleId, InfraModuleSpec>;
 
 export interface InfraManifest {
   readonly environments: Readonly<

package/src/types/infraWorkload.ts

@@ -1,4 +1,4 @@
-import type { SerializableSet } from '../collections';
+import type { EntityRegistry, SerializableSet, ValueMap } from '../collections';
 import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';
 
 export interface InfraWorkloadArtifact {
@@ -58,9 +58,9 @@ export interface InfraWorkloadVolumeSpec {
 }
 
 export type InfraWorkloadId = string;
-export type InfraWorkloadPortRegistry = Readonly<Record<string, InfraWorkloadPort>>;
-export type InfraWorkloadFileMap = Readonly<Record<string, InfraWorkloadValue>>;
-export type InfraWorkloadVolumeRegistry = Readonly<Record<string, InfraWorkloadVolumeSpec>>;
+export type InfraWorkloadPortRegistry = EntityRegistry<string, InfraWorkloadPort>;
+export type InfraWorkloadFileMap = ValueMap<string, InfraWorkloadValue>;
+export type InfraWorkloadVolumeRegistry = EntityRegistry<string, InfraWorkloadVolumeSpec, 'id'>;
 
 export interface InfraWorkloadSpec {
   readonly id: InfraWorkloadId;
@@ -68,7 +68,7 @@ export interface InfraWorkloadSpec {
   readonly command?: readonly string[];
   readonly args?: readonly string[];
   readonly ports?: InfraWorkloadPortRegistry;
-  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;
+  readonly environment?: ValueMap<string, InfraWorkloadValue>;
   readonly files?: InfraWorkloadFileMap;
   readonly health?: InfraWorkloadHealthSpec;
   readonly resources?: InfraWorkloadResourceSpec;
@@ -79,4 +79,4 @@ export interface InfraWorkloadSpec {
   readonly dependsOn?: SerializableSet;
 }
 
-export type InfraWorkloadRegistry = Readonly<Record<InfraWorkloadId, InfraWorkloadSpec>>;
+export type InfraWorkloadRegistry = EntityRegistry<InfraWorkloadId, InfraWorkloadSpec, 'id'>;

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
   ComponentDataBindingRegistry,
   ScreenDataLoaderDefinition,
 } from './bindings';
+import type { EntityRegistry } from './collections';
 import type { DataSourceRegistry } from './data';
 import type { AppDeployManifest } from './deploy';
 import type { InfraManifest } from './infra';
@@ -36,7 +37,7 @@ export interface ThemeConfig {
   recipes?: ThemeRecipeOverrides;
 }
 
-export type ThemeRegistry = Readonly<Record<ThemeId, ThemeConfig>>;
+export type ThemeRegistry = EntityRegistry<ThemeId, ThemeConfig, 'id'>;
 
 export type ActionType =
   'navigate' | 'alert' | 'console' | 'toggleDarkMode' | 'setLanguage' | 'search' | 'filter';
@@ -286,7 +287,7 @@ export interface AppManifest {
   state?: AppStateSpec;
   infra: InfraManifest;
   navigator: AppNavigatorManifest;
-  screens: Readonly<Record<string, ScreenSpec>>;
+  screens: EntityRegistry<string, ScreenSpec, 'id'>;
   dataSources?: DataSourceRegistry;
   dataBindings?: ComponentDataBindingRegistry;
   repository?: RepositoryManifest;