@cohesivesystems/relations 0.1.0-alpha.15 → 0.1.0-alpha.150

package/src/generated/relations.shapes.generated.ts

@@ -1,9 +1,386 @@
 /* <auto-generated/> */
 
+export type GraphDeltaKind = 'Unspecified' | 'Overlay' | 'Version';
+
+export const graphDeltaKinds = {
+  unspecified: 'Unspecified',
+  overlay: 'Overlay',
+  version: 'Version',
+} as const satisfies Record<string, GraphDeltaKind>;
+
+export const graphDeltaKindLabels: Record<GraphDeltaKind, string> = {
+  Unspecified: 'Unspecified',
+  Overlay: 'Overlay',
+  Version: 'Version',
+};
+
 export type GraphId = string;
 
+export type GraphDeltaOperation = {
+  readonly $operation: 'addShape';
+} & AddShapeOperation | {
+  readonly $operation: 'removeShape';
+} & RemoveShapeOperation | {
+  readonly $operation: 'replaceShape';
+} & ReplaceShapeOperation | {
+  readonly $operation: 'setGraphAnnotation';
+} & SetGraphAnnotationOperation | {
+  readonly $operation: 'removeGraphAnnotation';
+} & RemoveGraphAnnotationOperation | {
+  readonly $operation: 'addNamedType';
+} & AddNamedTypeOperation | {
+  readonly $operation: 'removeNamedType';
+} & RemoveNamedTypeOperation | {
+  readonly $operation: 'replaceNamedType';
+} & ReplaceNamedTypeOperation | {
+  readonly $operation: 'addShapeField';
+} & AddShapeFieldOperation | {
+  readonly $operation: 'removeShapeField';
+} & RemoveShapeFieldOperation | {
+  readonly $operation: 'replaceShapeField';
+} & ReplaceShapeFieldOperation | {
+  readonly $operation: 'addTypeField';
+} & AddTypeFieldOperation | {
+  readonly $operation: 'removeTypeField';
+} & RemoveTypeFieldOperation | {
+  readonly $operation: 'replaceTypeField';
+} & ReplaceTypeFieldOperation | {
+  readonly $operation: 'setFieldType';
+} & SetFieldTypeOperation | {
+  readonly $operation: 'setFieldPresence';
+} & SetFieldPresenceOperation | {
+  readonly $operation: 'setFieldCardinality';
+} & SetFieldCardinalityOperation | {
+  readonly $operation: 'setFieldNullability';
+} & SetFieldNullabilityOperation | {
+  readonly $operation: 'addFieldConstraint';
+} & AddFieldConstraintOperation | {
+  readonly $operation: 'removeFieldConstraint';
+} & RemoveFieldConstraintOperation | {
+  readonly $operation: 'setShapeAnnotation';
+} & SetShapeAnnotationOperation | {
+  readonly $operation: 'removeShapeAnnotation';
+} & RemoveShapeAnnotationOperation | {
+  readonly $operation: 'setTypeAnnotation';
+} & SetTypeAnnotationOperation | {
+  readonly $operation: 'removeTypeAnnotation';
+} & RemoveTypeAnnotationOperation | {
+  readonly $operation: 'setFieldAnnotation';
+} & SetFieldAnnotationOperation | {
+  readonly $operation: 'removeFieldAnnotation';
+} & RemoveFieldAnnotationOperation | {
+  readonly $operation: 'restrictAllowedValues';
+} & RestrictAllowedValuesOperation | {
+  readonly $operation: 'extendAllowedValues';
+} & ExtendAllowedValuesOperation | {
+  readonly $operation: 'addEnumValue';
+} & AddEnumValueOperation | {
+  readonly $operation: 'removeEnumValue';
+} & RemoveEnumValueOperation;
+
+export interface AddShapeOperation {
+  shape: Shape;
+  ordinal?: number | null;
+  note?: string | null;
+}
+
+export interface RemoveShapeOperation {
+  note?: string | null;
+  shapeId: ShapeId;
+}
+
+export interface ReplaceShapeOperation {
+  note?: string | null;
+  shape: Shape;
+}
+
+export interface SetGraphAnnotationOperation {
+  note?: string | null;
+  key: AnnotationKey;
+  value: AnnotationValue;
+}
+
+export interface RemoveGraphAnnotationOperation {
+  note?: string | null;
+  key: AnnotationKey;
+}
+
+export interface AddNamedTypeOperation {
+  type: TypeDefinition;
+  ordinal?: number | null;
+  note?: string | null;
+}
+
+export interface RemoveNamedTypeOperation {
+  note?: string | null;
+  typeId: TypeId;
+}
+
+export interface ReplaceNamedTypeOperation {
+  note?: string | null;
+  type: TypeDefinition;
+}
+
+export interface AddShapeFieldOperation {
+  shapeId: ShapeId;
+  field: FieldDefinition;
+  ordinal?: number | null;
+  note?: string | null;
+}
+
+export interface RemoveShapeFieldOperation {
+  note?: string | null;
+  shapeId: ShapeId;
+  fieldName: FieldName;
+  replacementPath?: string | null;
+}
+
+export interface ReplaceShapeFieldOperation {
+  note?: string | null;
+  shapeId: ShapeId;
+  field: FieldDefinition;
+}
+
+export interface AddTypeFieldOperation {
+  typeId: TypeId;
+  field: StructuralField;
+  ordinal?: number | null;
+  note?: string | null;
+}
+
+export interface RemoveTypeFieldOperation {
+  note?: string | null;
+  typeId: TypeId;
+  fieldName: FieldName;
+  replacementPath?: string | null;
+}
+
+export interface ReplaceTypeFieldOperation {
+  note?: string | null;
+  typeId: TypeId;
+  field: StructuralField;
+}
+
+export interface SetFieldTypeOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  type: TypeRef;
+}
+
+export interface SetFieldPresenceOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  presence: FieldPresence;
+}
+
+export interface SetFieldCardinalityOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  cardinality: FieldCardinality;
+}
+
+export interface SetFieldNullabilityOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  nullability: FieldNullability;
+}
+
+export interface AddFieldConstraintOperation {
+  target: GraphFieldPath;
+  constraint: ShapeConstraint;
+  note?: string | null;
+}
+
+export interface RemoveFieldConstraintOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  constraint: ShapeConstraint;
+}
+
+export interface SetShapeAnnotationOperation {
+  note?: string | null;
+  shapeId: ShapeId;
+  key: AnnotationKey;
+  value: AnnotationValue;
+}
+
+export interface RemoveShapeAnnotationOperation {
+  note?: string | null;
+  shapeId: ShapeId;
+  key: AnnotationKey;
+}
+
+export interface SetTypeAnnotationOperation {
+  note?: string | null;
+  typeId: TypeId;
+  key: AnnotationKey;
+  value: AnnotationValue;
+}
+
+export interface RemoveTypeAnnotationOperation {
+  note?: string | null;
+  typeId: TypeId;
+  key: AnnotationKey;
+}
+
+export interface SetFieldAnnotationOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  key: AnnotationKey;
+  value: AnnotationValue;
+}
+
+export interface RemoveFieldAnnotationOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  key: AnnotationKey;
+}
+
+export interface RestrictAllowedValuesOperation {
+  note?: string | null;
+  target: GraphFieldPath;
+  values: string[];
+}
+
+export interface ExtendAllowedValuesOperation {
+  target: GraphFieldPath;
+  values: string[];
+  note?: string | null;
+}
+
+export interface AddEnumValueOperation {
+  typeId: TypeId;
+  value: EnumValue;
+  note?: string | null;
+}
+
+export interface RemoveEnumValueOperation {
+  note?: string | null;
+  typeId: TypeId;
+  valueName: string;
+}
+
+export type AnnotationKey = string;
+
+export type AnnotationValue = unknown;
+
 export type ShapeId = string;
 
+export interface ShapeGraphDocumentMetadata {
+  origin: DocumentOrigin;
+  name?: string | null;
+  description?: string | null;
+  sourceUri?: string | null;
+  createdAtUtc?: string | null;
+  updatedAtUtc?: string | null;
+  annotations: Record<string, AnnotationValue>;
+}
+
+export interface ShapeGraph {
+  id: GraphId;
+  shapes: Shape[];
+  namedTypes: TypeDefinition[];
+  annotations: Record<string, AnnotationValue>;
+  diagnostics: GraphDiagnostic[];
+  hasErrors: boolean;
+}
+
+export type TypeRef = {
+  readonly $type: 'named';
+} & NamedTypeRef | {
+  readonly $type: 'opaque';
+} & OpaqueRuntimeTypeRef | {
+  readonly $type: 'scalar';
+} & ScalarTypeRef | {
+  readonly $type: 'enum';
+} & EnumTypeRef | {
+  readonly $type: 'entityRef';
+} & EntityReferenceTypeRef | {
+  readonly $type: 'array';
+} & ArrayTypeRef | {
+  readonly $type: 'object';
+} & ObjectTypeRef | {
+  readonly $type: 'quantity';
+} & QuantityTypeRef | {
+  readonly $type: 'json';
+} & JsonTypeRef;
+
+export interface NamedTypeRef {
+  typeId: TypeId;
+}
+
+export interface OpaqueRuntimeTypeRef {
+  runtimeType: string;
+  inferenceDiagnostic?: TypeInferenceDiagnostic | null;
+}
+
+export interface ScalarTypeRef {
+  kind: ScalarTypeKind;
+  format: PrimitiveFormat;
+}
+
+export interface EnumTypeRef {
+  name: string;
+  members: string[];
+}
+
+export interface EntityReferenceTypeRef {
+  entity: EntityTypeName;
+}
+
+export interface ArrayTypeRef {
+  elementType: TypeRef;
+}
+
+export interface ObjectTypeRef {
+  fields: ObjectFieldTypeDef[];
+}
+
+export interface QuantityTypeRef {
+  quantity: string;
+  baseKind: ScalarTypeKind;
+}
+
+export interface JsonTypeRef {
+  kind: JsonTypeKind;
+}
+
+export type FieldCardinality = 'Single' | 'Many';
+
+export const fieldCardinalities = {
+  single: 'Single',
+  many: 'Many',
+} as const satisfies Record<string, FieldCardinality>;
+
+export const fieldCardinalityLabels: Record<FieldCardinality, string> = {
+  Single: 'Single',
+  Many: 'Many',
+};
+
+export type FieldPresence = 'Required' | 'Optional';
+
+export const fieldPresences = {
+  required: 'Required',
+  optional: 'Optional',
+} as const satisfies Record<string, FieldPresence>;
+
+export const fieldPresenceLabels: Record<FieldPresence, string> = {
+  Required: 'Required',
+  Optional: 'Optional',
+};
+
+export type FieldNullability = 'NonNullable' | 'Nullable';
+
+export const fieldNullabilities = {
+  nonNullable: 'NonNullable',
+  nullable: 'Nullable',
+} as const satisfies Record<string, FieldNullability>;
+
+export const fieldNullabilityLabels: Record<FieldNullability, string> = {
+  NonNullable: 'NonNullable',
+  Nullable: 'Nullable',
+};
+
 export type RelationQueryExplainStage = {
   readonly $stage: 'staticCompilation';
 } & RelationQueryStaticCompilationExplainStage | {
@@ -388,6 +765,7 @@ export interface QueryDefinition {
   id: QueryId;
   name: QueryName;
   results: QueryResultDefinition[];
+  assembly?: NestedQueryResultAssembly | null;
   body: LogicalQueryDefinition;
 }
 
@@ -431,6 +809,270 @@ export interface RelationshipCatalogDocumentMetadata {
   annotations: Record<string, AnnotationValue>;
 }
 
+export interface Shape {
+  id: ShapeId;
+  fields: FieldDefinition[];
+  constraints: ShapeConstraint[];
+  annotations: Record<string, AnnotationValue>;
+  role?: string | null;
+  entityType?: EntityTypeName | null;
+}
+
+export type TypeDefinition = {
+  readonly $typeDef: 'structural';
+} & Structural | {
+  readonly $typeDef: 'enum';
+} & Enum | {
+  readonly $typeDef: 'union';
+} & Union;
+
+export interface Structural {
+  id: TypeId;
+  name: string;
+  fields: StructuralField[];
+  constraints: ShapeConstraint[];
+  annotations: Record<string, AnnotationValue>;
+}
+
+export interface Enum {
+  id: TypeId;
+  name: string;
+  underlying: PrimitiveType;
+  values: EnumValue[];
+  annotations: Record<string, AnnotationValue>;
+}
+
+export interface Union {
+  id: TypeId;
+  name: string;
+  discriminator: UnionDiscriminator;
+  cases: UnionCase[];
+  annotations: Record<string, AnnotationValue>;
+}
+
+export type TypeId = string;
+
+export interface FieldDefinition {
+  name: FieldName;
+  type: TypeRef;
+  cardinality: FieldCardinality;
+  presence: FieldPresence;
+  role: FieldRole;
+  nullability: FieldNullability;
+  mutability: FieldMutability;
+  compute?: ComputeDefinition | null;
+  constraints: ShapeConstraint[];
+  annotations: Record<string, AnnotationValue>;
+}
+
+export type FieldName = string;
+
+export interface StructuralField {
+  name: FieldName;
+  type: TypeRef;
+  cardinality: FieldCardinality;
+  presence: FieldPresence;
+  nullability: FieldNullability;
+  role: FieldRole;
+  constraints: ShapeConstraint[];
+  annotations: Record<string, AnnotationValue>;
+}
+
+export interface GraphFieldPath {
+  shapeId?: ShapeId | null;
+  typeId?: TypeId | null;
+  path: FieldPath;
+}
+
+export type ShapeConstraint = {
+  readonly $constraint: 'required';
+} & RequiredConstraint | {
+  readonly $constraint: 'minLength';
+} & MinLengthConstraint | {
+  readonly $constraint: 'maxLength';
+} & MaxLengthConstraint | {
+  readonly $constraint: 'range';
+} & RangeConstraint | {
+  readonly $constraint: 'regex';
+} & RegexConstraint | {
+  readonly $constraint: 'allowedValues';
+} & AllowedValuesConstraint | {
+  readonly $constraint: 'occurrence';
+} & OccurrenceConstraint;
+
+export interface RequiredConstraint {
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface MinLengthConstraint {
+  value: number;
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface MaxLengthConstraint {
+  value: number;
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface RangeConstraint {
+  minimum?: number | null;
+  maximum?: number | null;
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface RegexConstraint {
+  pattern: string;
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface AllowedValuesConstraint {
+  values: string[];
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface OccurrenceConstraint {
+  minimum?: number | null;
+  maximum?: number | null;
+  field?: FieldPath | null;
+  message?: string | null;
+}
+
+export interface EnumValue {
+  name: string;
+  value?: string | null;
+  label?: string | null;
+  description?: string | null;
+}
+
+export type DocumentOrigin = 'Unknown' | 'User' | 'System' | 'Imported' | 'Generated' | 'Compiled' | 'Extracted';
+
+export const documentOrigins = {
+  unknown: 'Unknown',
+  user: 'User',
+  system: 'System',
+  imported: 'Imported',
+  generated: 'Generated',
+  compiled: 'Compiled',
+  extracted: 'Extracted',
+} as const satisfies Record<string, DocumentOrigin>;
+
+export const documentOriginLabels: Record<DocumentOrigin, string> = {
+  Unknown: 'Unknown',
+  User: 'User',
+  System: 'System',
+  Imported: 'Imported',
+  Generated: 'Generated',
+  Compiled: 'Compiled',
+  Extracted: 'Extracted',
+};
+
+export interface GraphDiagnostic {
+  id: DiagnosticId;
+  severity: DiagnosticSeverity;
+  message: string;
+  shapeId?: ShapeId | null;
+  fieldIdentity?: string | null;
+  typeId?: TypeId | null;
+}
+
+export interface TypeInferenceDiagnostic {
+  reason: string;
+  message?: string | null;
+}
+
+export type ScalarTypeKind = 'Bool' | 'Int32' | 'Int64' | 'Decimal' | 'String' | 'Guid' | 'Date' | 'DateTime' | 'Instant' | 'Bytes';
+
+export const scalarTypeKinds = {
+  bool: 'Bool',
+  int32: 'Int32',
+  int64: 'Int64',
+  decimal: 'Decimal',
+  string: 'String',
+  guid: 'Guid',
+  date: 'Date',
+  dateTime: 'DateTime',
+  instant: 'Instant',
+  bytes: 'Bytes',
+} as const satisfies Record<string, ScalarTypeKind>;
+
+export const scalarTypeKindLabels: Record<ScalarTypeKind, string> = {
+  Bool: 'Bool',
+  Int32: 'Int32',
+  Int64: 'Int64',
+  Decimal: 'Decimal',
+  String: 'String',
+  Guid: 'Guid',
+  Date: 'Date',
+  DateTime: 'DateTime',
+  Instant: 'Instant',
+  Bytes: 'Bytes',
+};
+
+export type PrimitiveFormat = 'None' | 'Uuid' | 'IsoDate' | 'IsoDateTime' | 'IsoInstant' | 'CurrencyCode' | 'CountryCode' | 'Email' | 'Uri' | 'Base64';
+
+export const primitiveFormats = {
+  none: 'None',
+  uuid: 'Uuid',
+  isoDate: 'IsoDate',
+  isoDateTime: 'IsoDateTime',
+  isoInstant: 'IsoInstant',
+  currencyCode: 'CurrencyCode',
+  countryCode: 'CountryCode',
+  email: 'Email',
+  uri: 'Uri',
+  base64: 'Base64',
+} as const satisfies Record<string, PrimitiveFormat>;
+
+export const primitiveFormatLabels: Record<PrimitiveFormat, string> = {
+  None: 'None',
+  Uuid: 'Uuid',
+  IsoDate: 'IsoDate',
+  IsoDateTime: 'IsoDateTime',
+  IsoInstant: 'IsoInstant',
+  CurrencyCode: 'CurrencyCode',
+  CountryCode: 'CountryCode',
+  Email: 'Email',
+  Uri: 'Uri',
+  Base64: 'Base64',
+};
+
+export type EntityTypeName = string;
+
+export interface ObjectFieldTypeDef {
+  name: string;
+  type: TypeRef;
+  cardinality: FieldCardinality;
+  presence: FieldPresence;
+  nullability: FieldNullability;
+  annotations: Record<string, AnnotationValue>;
+}
+
+export type JsonTypeKind = 'Any' | 'Object' | 'Array' | 'String' | 'Number' | 'Boolean';
+
+export const jsonTypeKinds = {
+  any: 'Any',
+  object: 'Object',
+  array: 'Array',
+  string: 'String',
+  number: 'Number',
+  boolean: 'Boolean',
+} as const satisfies Record<string, JsonTypeKind>;
+
+export const jsonTypeKindLabels: Record<JsonTypeKind, string> = {
+  Any: 'Any',
+  Object: 'Object',
+  Array: 'Array',
+  String: 'String',
+  Number: 'Number',
+  Boolean: 'Boolean',
+};
+
 export type RelationQueryExplainStageStatus = 'Complete' | 'Unavailable' | 'Invalid' | 'Incomplete' | 'Failed';
 
 export const relationQueryExplainStageStatuses = {
@@ -1140,32 +1782,6 @@ export interface InvariantDefinition {
   message?: string | null;
 }
 
-export type DocumentOrigin = 'Unknown' | 'User' | 'System' | 'Imported' | 'Generated' | 'Compiled' | 'Extracted';
-
-export const documentOrigins = {
-  unknown: 'Unknown',
-  user: 'User',
-  system: 'System',
-  imported: 'Imported',
-  generated: 'Generated',
-  compiled: 'Compiled',
-  extracted: 'Extracted',
-} as const satisfies Record<string, DocumentOrigin>;
-
-export const documentOriginLabels: Record<DocumentOrigin, string> = {
-  Unknown: 'Unknown',
-  User: 'User',
-  System: 'System',
-  Imported: 'Imported',
-  Generated: 'Generated',
-  Compiled: 'Compiled',
-  Extracted: 'Extracted',
-};
-
-export type AnnotationKey = string;
-
-export type AnnotationValue = unknown;
-
 export interface RelationDraftProducerArtifactReference {
   kind: string;
   value: string;
@@ -1187,35 +1803,120 @@ export interface RelationOutputDefinition {
   key?: Expr | null;
 }
 
-export type QueryId = string;
+export type QueryId = string;
+
+export type QueryName = string;
+
+export type QueryResultDefinition = {
+  readonly $result: 'rows';
+} & RowsQueryResultDefinition | {
+  readonly $result: 'aggregation';
+} & AggregationQueryResultDefinition;
+
+export interface RowsQueryResultDefinition {
+  id: QueryResultId;
+  input: QueryNodeId;
+}
+
+export interface AggregationQueryResultDefinition {
+  id: QueryResultId;
+  input: QueryNodeId;
+}
+
+export interface NestedQueryResultAssembly {
+  result: QueryResultId;
+  shape: QualifiedShapeId;
+  identity: FieldPath;
+  fields: QueryResultFieldMapping[];
+  collections: QueryResultCollectionAssembly[];
+}
+
+export interface RelationshipDefinition {
+  id: RelationshipId;
+  sourceShape: QualifiedShapeId;
+  sourceReference: FieldPath;
+  targetShape: QualifiedShapeId;
+  targetKey: RelationshipTargetKey;
+  sourceReferenceUniqueness: SourceReferenceUniqueness;
+}
+
+export type PrimitiveType = 'Bool' | 'Int32' | 'Int64' | 'Decimal' | 'String' | 'Guid' | 'Date' | 'DateTime' | 'Instant' | 'Bytes';
+
+export const primitiveTypes = {
+  bool: 'Bool',
+  int32: 'Int32',
+  int64: 'Int64',
+  decimal: 'Decimal',
+  string: 'String',
+  guid: 'Guid',
+  date: 'Date',
+  dateTime: 'DateTime',
+  instant: 'Instant',
+  bytes: 'Bytes',
+} as const satisfies Record<string, PrimitiveType>;
+
+export const primitiveTypeLabels: Record<PrimitiveType, string> = {
+  Bool: 'Bool',
+  Int32: 'Int32',
+  Int64: 'Int64',
+  Decimal: 'Decimal',
+  String: 'String',
+  Guid: 'Guid',
+  Date: 'Date',
+  DateTime: 'DateTime',
+  Instant: 'Instant',
+  Bytes: 'Bytes',
+};
+
+export interface UnionDiscriminator {
+  fieldName: string;
+  type: PrimitiveType;
+}
+
+export interface UnionCase {
+  name: string;
+  type: TypeRef;
+  discriminatorValue: string;
+}
+
+export type FieldRole = 'Data' | 'Identity' | 'Reference' | 'Computed' | 'Metadata';
 
-export type QueryName = string;
+export const fieldRoles = {
+  data: 'Data',
+  identity: 'Identity',
+  reference: 'Reference',
+  computed: 'Computed',
+  metadata: 'Metadata',
+} as const satisfies Record<string, FieldRole>;
 
-export type QueryResultDefinition = {
-  readonly $result: 'rows';
-} & RowsQueryResultDefinition | {
-  readonly $result: 'aggregation';
-} & AggregationQueryResultDefinition;
+export const fieldRoleLabels: Record<FieldRole, string> = {
+  Data: 'Data',
+  Identity: 'Identity',
+  Reference: 'Reference',
+  Computed: 'Computed',
+  Metadata: 'Metadata',
+};
 
-export interface RowsQueryResultDefinition {
-  id: QueryResultId;
-  input: QueryNodeId;
-}
+export type FieldMutability = 'Mutable' | 'WriteOnce' | 'Computed';
 
-export interface AggregationQueryResultDefinition {
-  id: QueryResultId;
-  input: QueryNodeId;
-}
+export const fieldMutabilities = {
+  mutable: 'Mutable',
+  writeOnce: 'WriteOnce',
+  computed: 'Computed',
+} as const satisfies Record<string, FieldMutability>;
 
-export interface RelationshipDefinition {
-  id: RelationshipId;
-  sourceShape: QualifiedShapeId;
-  sourceReference: FieldPath;
-  targetShape: QualifiedShapeId;
-  targetKey: RelationshipTargetKey;
-  sourceReferenceUniqueness: SourceReferenceUniqueness;
+export const fieldMutabilityLabels: Record<FieldMutability, string> = {
+  Mutable: 'Mutable',
+  WriteOnce: 'WriteOnce',
+  Computed: 'Computed',
+};
+
+export interface ComputeDefinition {
+  expression: Expr;
 }
 
+export type DiagnosticId = string;
+
 export interface RelationQueryLogicalPlan {
   nodes: RelationQueryLogicalPlanNode[];
   retainedNodes: QueryNodeId[];
@@ -1387,7 +2088,7 @@ export const relationQueryBoundAssessmentStatusLabels: Record<RelationQueryBound
   Blocked: 'Blocked',
 };
 
-export type RelationQueryLogicalCapabilityKind = 'Source' | 'Filter' | 'RelationshipTraversal' | 'ForwardRelationshipTraversal' | 'InverseRelationshipTraversal' | 'AtMostOneRelationshipTraversal' | 'ManyRelationshipTraversal' | 'RequiredRelationshipTraversal' | 'OptionalRelationshipTraversal' | 'Join' | 'InnerJoin' | 'LeftOuterJoin' | 'RightOuterJoin' | 'FullOuterJoin' | 'TemporalJoin' | 'ExpandCollection' | 'Projection' | 'ProjectionAssignment' | 'DistinctRows' | 'DistinctKeys' | 'Aggregation' | 'AggregateGrouping' | 'AggregateFilter' | 'CountAggregate' | 'SumAggregate' | 'MinimumAggregate' | 'MaximumAggregate' | 'AnyAggregate' | 'AllAggregate' | 'Ordering' | 'AscendingOrdering' | 'DescendingOrdering' | 'NullsFirst' | 'NullsLast' | 'StableTieOrdering' | 'OffsetPaging' | 'KeysetPaging' | 'OnePerRootRelationOutput' | 'ZeroOrOnePerRootRelationOutput' | 'ManyPerRootRelationOutput' | 'SetRelationOutput' | 'RelationOutputIdentity' | 'RelationInvariant' | 'QueryRowsResult' | 'QueryAggregationResult' | 'AlwaysPresentBinding' | 'MayBeAbsentBinding' | 'AverageAggregate';
+export type RelationQueryLogicalCapabilityKind = 'Source' | 'Filter' | 'RelationshipTraversal' | 'ForwardRelationshipTraversal' | 'InverseRelationshipTraversal' | 'AtMostOneRelationshipTraversal' | 'ManyRelationshipTraversal' | 'RequiredRelationshipTraversal' | 'OptionalRelationshipTraversal' | 'Join' | 'InnerJoin' | 'LeftOuterJoin' | 'RightOuterJoin' | 'FullOuterJoin' | 'TemporalJoin' | 'ExpandCollection' | 'Projection' | 'ProjectionAssignment' | 'DistinctRows' | 'DistinctKeys' | 'Aggregation' | 'AggregateGrouping' | 'AggregateFilter' | 'CountAggregate' | 'SumAggregate' | 'MinimumAggregate' | 'MaximumAggregate' | 'AnyAggregate' | 'AllAggregate' | 'Ordering' | 'AscendingOrdering' | 'DescendingOrdering' | 'NullsFirst' | 'NullsLast' | 'StableTieOrdering' | 'OffsetPaging' | 'KeysetPaging' | 'OnePerRootRelationOutput' | 'ZeroOrOnePerRootRelationOutput' | 'ManyPerRootRelationOutput' | 'SetRelationOutput' | 'RelationOutputIdentity' | 'RelationInvariant' | 'QueryRowsResult' | 'QueryAggregationResult' | 'AlwaysPresentBinding' | 'MayBeAbsentBinding' | 'AverageAggregate' | 'SelectRepresentative';
 
 export const relationQueryLogicalCapabilityKinds = {
   source: 'Source',
@@ -1438,6 +2139,7 @@ export const relationQueryLogicalCapabilityKinds = {
   alwaysPresentBinding: 'AlwaysPresentBinding',
   mayBeAbsentBinding: 'MayBeAbsentBinding',
   averageAggregate: 'AverageAggregate',
+  selectRepresentative: 'SelectRepresentative',
 } as const satisfies Record<string, RelationQueryLogicalCapabilityKind>;
 
 export const relationQueryLogicalCapabilityKindLabels: Record<RelationQueryLogicalCapabilityKind, string> = {
@@ -1489,6 +2191,7 @@ export const relationQueryLogicalCapabilityKindLabels: Record<RelationQueryLogic
   AlwaysPresentBinding: 'AlwaysPresentBinding',
   MayBeAbsentBinding: 'MayBeAbsentBinding',
   AverageAggregate: 'AverageAggregate',
+  SelectRepresentative: 'SelectRepresentative',
 };
 
 export interface ExprCapabilityId {
@@ -1742,6 +2445,8 @@ export type LogicalQueryNode = {
 } & ProjectQueryNode | {
   readonly $node: 'distinct';
 } & DistinctQueryNode | {
+  readonly $node: 'selectRepresentative';
+} & SelectRepresentativeQueryNode | {
   readonly $node: 'aggregate';
 } & AggregateQueryNode | {
   readonly $node: 'order';
@@ -1794,6 +2499,7 @@ export interface ExpandCollectionQueryNode {
   collection: Expr;
   itemBinding: ValueBindingId;
   itemType: TypeRef;
+  itemShape?: QualifiedShapeId | null;
   id: QueryNodeId;
 }
 
@@ -1811,6 +2517,13 @@ export interface DistinctQueryNode {
   id: QueryNodeId;
 }
 
+export interface SelectRepresentativeQueryNode {
+  id: QueryNodeId;
+  input: QueryNodeId;
+  keys: Expr[];
+  orderings: QueryOrdering[];
+}
+
 export interface AggregateQueryNode {
   input: QueryNodeId;
   resultBinding: ValueBindingId;
@@ -1889,66 +2602,6 @@ export const binaryOperatorLabels: Record<BinaryOperator, string> = {
   Div: 'Div',
 };
 
-export type TypeRef = {
-  readonly $type: 'named';
-} & NamedTypeRef | {
-  readonly $type: 'opaque';
-} & OpaqueRuntimeTypeRef | {
-  readonly $type: 'scalar';
-} & ScalarTypeRef | {
-  readonly $type: 'enum';
-} & EnumTypeRef | {
-  readonly $type: 'entityRef';
-} & EntityReferenceTypeRef | {
-  readonly $type: 'array';
-} & ArrayTypeRef | {
-  readonly $type: 'object';
-} & ObjectTypeRef | {
-  readonly $type: 'quantity';
-} & QuantityTypeRef | {
-  readonly $type: 'json';
-} & JsonTypeRef;
-
-export interface NamedTypeRef {
-  typeId: TypeId;
-}
-
-export interface OpaqueRuntimeTypeRef {
-  runtimeType: string;
-  inferenceDiagnostic?: TypeInferenceDiagnostic | null;
-}
-
-export interface ScalarTypeRef {
-  kind: ScalarTypeKind;
-  format: PrimitiveFormat;
-}
-
-export interface EnumTypeRef {
-  name: string;
-  members: string[];
-}
-
-export interface EntityReferenceTypeRef {
-  entity: EntityTypeName;
-}
-
-export interface ArrayTypeRef {
-  elementType: TypeRef;
-}
-
-export interface ObjectTypeRef {
-  fields: ObjectFieldTypeDef[];
-}
-
-export interface QuantityTypeRef {
-  quantity: string;
-  baseKind: ScalarTypeKind;
-}
-
-export interface JsonTypeRef {
-  kind: JsonTypeKind;
-}
-
 export type AggregateOperator = 'Count' | 'Sum' | 'Min' | 'Max' | 'Any' | 'All' | 'Average';
 
 export const aggregateOperators = {
@@ -1979,6 +2632,17 @@ export type RelationDraftCandidateId = string;
 
 export type QueryResultId = string;
 
+export interface QueryResultFieldMapping {
+  source: FieldPath;
+  target: FieldPath;
+}
+
+export interface QueryResultCollectionAssembly {
+  target: FieldPath;
+  identity: FieldPath;
+  fields: QueryResultFieldMapping[];
+}
+
 export type RelationshipId = string;
 
 export type RelationshipTargetKey = {
@@ -2252,6 +2916,12 @@ export interface ProjectionAssignment {
   value: Expr;
 }
 
+export interface QueryOrdering {
+  key: Expr;
+  direction: QuerySortDirection;
+  nullPlacement: QueryNullPlacement;
+}
+
 export interface QueryGrouping {
   id: QueryAssignmentId;
   target: FieldPath;
@@ -2266,12 +2936,6 @@ export interface QueryAggregateAssignment {
   filter?: Expr | null;
 }
 
-export interface QueryOrdering {
-  key: Expr;
-  direction: QuerySortDirection;
-  nullPlacement: QueryNullPlacement;
-}
-
 export type QueryPageDefinition = {
   readonly $page: 'offset';
 } & OffsetPageDefinition | {
@@ -2290,18 +2954,6 @@ export interface KeysetPageDefinition {
 
 export type QueryParameterId = string;
 
-export type FieldPresence = 'Required' | 'Optional';
-
-export const fieldPresences = {
-  required: 'Required',
-  optional: 'Optional',
-} as const satisfies Record<string, FieldPresence>;
-
-export const fieldPresenceLabels: Record<FieldPresence, string> = {
-  Required: 'Required',
-  Optional: 'Optional',
-};
-
 export type QueryParameterDefaultKind = 'None' | 'Value';
 
 export const queryParameterDefaultKinds = {
@@ -2343,100 +2995,6 @@ export interface AmbiguousRelationDraftAssignmentResolution {
   candidateIds: RelationDraftCandidateId[];
 }
 
-export type TypeId = string;
-
-export interface TypeInferenceDiagnostic {
-  reason: string;
-  message?: string | null;
-}
-
-export type ScalarTypeKind = 'Bool' | 'Int32' | 'Int64' | 'Decimal' | 'String' | 'Guid' | 'Date' | 'DateTime' | 'Instant' | 'Bytes';
-
-export const scalarTypeKinds = {
-  bool: 'Bool',
-  int32: 'Int32',
-  int64: 'Int64',
-  decimal: 'Decimal',
-  string: 'String',
-  guid: 'Guid',
-  date: 'Date',
-  dateTime: 'DateTime',
-  instant: 'Instant',
-  bytes: 'Bytes',
-} as const satisfies Record<string, ScalarTypeKind>;
-
-export const scalarTypeKindLabels: Record<ScalarTypeKind, string> = {
-  Bool: 'Bool',
-  Int32: 'Int32',
-  Int64: 'Int64',
-  Decimal: 'Decimal',
-  String: 'String',
-  Guid: 'Guid',
-  Date: 'Date',
-  DateTime: 'DateTime',
-  Instant: 'Instant',
-  Bytes: 'Bytes',
-};
-
-export type PrimitiveFormat = 'None' | 'Uuid' | 'IsoDate' | 'IsoDateTime' | 'IsoInstant' | 'CurrencyCode' | 'CountryCode' | 'Email' | 'Uri' | 'Base64';
-
-export const primitiveFormats = {
-  none: 'None',
-  uuid: 'Uuid',
-  isoDate: 'IsoDate',
-  isoDateTime: 'IsoDateTime',
-  isoInstant: 'IsoInstant',
-  currencyCode: 'CurrencyCode',
-  countryCode: 'CountryCode',
-  email: 'Email',
-  uri: 'Uri',
-  base64: 'Base64',
-} as const satisfies Record<string, PrimitiveFormat>;
-
-export const primitiveFormatLabels: Record<PrimitiveFormat, string> = {
-  None: 'None',
-  Uuid: 'Uuid',
-  IsoDate: 'IsoDate',
-  IsoDateTime: 'IsoDateTime',
-  IsoInstant: 'IsoInstant',
-  CurrencyCode: 'CurrencyCode',
-  CountryCode: 'CountryCode',
-  Email: 'Email',
-  Uri: 'Uri',
-  Base64: 'Base64',
-};
-
-export type EntityTypeName = string;
-
-export interface ObjectFieldTypeDef {
-  name: string;
-  type: TypeRef;
-  cardinality: FieldCardinality;
-  presence: FieldPresence;
-  nullability: FieldNullability;
-  annotations: Record<string, AnnotationValue>;
-}
-
-export type JsonTypeKind = 'Any' | 'Object' | 'Array' | 'String' | 'Number' | 'Boolean';
-
-export const jsonTypeKinds = {
-  any: 'Any',
-  object: 'Object',
-  array: 'Array',
-  string: 'String',
-  number: 'Number',
-  boolean: 'Boolean',
-} as const satisfies Record<string, JsonTypeKind>;
-
-export const jsonTypeKindLabels: Record<JsonTypeKind, string> = {
-  Any: 'Any',
-  Object: 'Object',
-  Array: 'Array',
-  String: 'String',
-  Number: 'Number',
-  Boolean: 'Boolean',
-};
-
 export interface RelationQueryLogicalPlanInput {
   canonicalInput: QueryNodeId;
   effectiveInput: QueryNodeId;
@@ -2489,7 +3047,7 @@ export const relationQueryRealizationTraceStepKindLabels: Record<RelationQueryRe
   Terminal: 'Terminal',
 };
 
-export type RelationQueryExpressionSiteKind = 'FilterPredicate' | 'JoinPredicate' | 'ExpandCollection' | 'ProjectionAssignmentValue' | 'DistinctKey' | 'AggregateGroupingKey' | 'AggregateAssignmentValue' | 'AggregateAssignmentFilter' | 'OrderKey' | 'KeysetBoundary' | 'RelationOutputKey' | 'RelationInvariant' | 'TemporalJoinCorrelation' | 'TemporalJoinPoint' | 'TemporalJoinIntervalLowerBound' | 'TemporalJoinIntervalUpperBound';
+export type RelationQueryExpressionSiteKind = 'FilterPredicate' | 'JoinPredicate' | 'ExpandCollection' | 'ProjectionAssignmentValue' | 'DistinctKey' | 'AggregateGroupingKey' | 'AggregateAssignmentValue' | 'AggregateAssignmentFilter' | 'OrderKey' | 'KeysetBoundary' | 'RelationOutputKey' | 'RelationInvariant' | 'TemporalJoinCorrelation' | 'TemporalJoinPoint' | 'TemporalJoinIntervalLowerBound' | 'TemporalJoinIntervalUpperBound' | 'RepresentativeKey';
 
 export const relationQueryExpressionSiteKinds = {
   filterPredicate: 'FilterPredicate',
@@ -2508,6 +3066,7 @@ export const relationQueryExpressionSiteKinds = {
   temporalJoinPoint: 'TemporalJoinPoint',
   temporalJoinIntervalLowerBound: 'TemporalJoinIntervalLowerBound',
   temporalJoinIntervalUpperBound: 'TemporalJoinIntervalUpperBound',
+  representativeKey: 'RepresentativeKey',
 } as const satisfies Record<string, RelationQueryExpressionSiteKind>;
 
 export const relationQueryExpressionSiteKindLabels: Record<RelationQueryExpressionSiteKind, string> = {
@@ -2527,6 +3086,7 @@ export const relationQueryExpressionSiteKindLabels: Record<RelationQueryExpressi
   TemporalJoinPoint: 'TemporalJoinPoint',
   TemporalJoinIntervalLowerBound: 'TemporalJoinIntervalLowerBound',
   TemporalJoinIntervalUpperBound: 'TemporalJoinIntervalUpperBound',
+  RepresentativeKey: 'RepresentativeKey',
 };
 
 export type ExprSiteId = string;
@@ -2586,30 +3146,6 @@ export const relationDraftUnresolvedReasonLabels: Record<RelationDraftUnresolved
   MultipleCandidates: 'MultipleCandidates',
 };
 
-export type FieldCardinality = 'Single' | 'Many';
-
-export const fieldCardinalities = {
-  single: 'Single',
-  many: 'Many',
-} as const satisfies Record<string, FieldCardinality>;
-
-export const fieldCardinalityLabels: Record<FieldCardinality, string> = {
-  Single: 'Single',
-  Many: 'Many',
-};
-
-export type FieldNullability = 'NonNullable' | 'Nullable';
-
-export const fieldNullabilities = {
-  nonNullable: 'NonNullable',
-  nullable: 'Nullable',
-} as const satisfies Record<string, FieldNullability>;
-
-export const fieldNullabilityLabels: Record<FieldNullability, string> = {
-  NonNullable: 'NonNullable',
-  Nullable: 'Nullable',
-};
-
 export interface RelationQueryLogicalBypass {
   kind: RelationQueryLogicalBypassKind;
   node: QueryNodeId;
@@ -2700,11 +3236,36 @@ export const temporalNullBoundBehaviorLabels: Record<TemporalNullBoundBehavior,
   Unbounded: 'Unbounded',
 };
 
+export interface GraphDelta {
+  id: string;
+  kind: GraphDeltaKind;
+  sourceGraphId?: GraphId | null;
+  targetGraphId?: GraphId | null;
+  sourceVersion?: string | null;
+  targetVersion?: string | null;
+  operations: GraphDeltaOperation[];
+  annotations: Record<string, AnnotationValue>;
+}
+
 export interface QualifiedShapeId {
   graphId: GraphId;
   shapeId: ShapeId;
 }
 
+export interface ShapeGraphDocument {
+  schemaVersion: string;
+  metadata: ShapeGraphDocumentMetadata;
+  graph: ShapeGraph;
+}
+
+export interface ValueContract {
+  type?: TypeRef | null;
+  shape?: QualifiedShapeId | null;
+  cardinality: FieldCardinality;
+  presence: FieldPresence;
+  nullability: FieldNullability;
+}
+
 export interface RelationQueryExplainArtifact {
   schemaVersion: string;
   stages: RelationQueryExplainStage[];