import {
  buildProvisionableFieldParams,
  buildCustomObjectNameFieldDetails,
} from '../../../core/platform/custom-objects/provisioning';
import { Category } from '../category';
import {
  CustomObject,
  type CustomObjectFieldInput,
  type CustomObjectStandardFieldIdentifier,
} from '../custom-object';
import { Field } from '../field';
import { CustomObjectFieldSection } from '../custom-object-field-section';
import { CustomObjectPageLayout } from '../custom-object-page-layout';
import type { ManifestComponent } from '../manifest-builder';
import type { RipplingSDK } from '../../../client';
import {
  defineCustomObject as createObject,
  extendCustomObject as extendObject,
} from '../../../core/platform/custom-objects/definition';
import type { CustomObjectCategoryDefinition } from '../../../core/platform/custom-objects/category';
import type {
  CustomObjectRecordsClient,
  TypedBatchWriteOptions,
  TypedRecordPageOptions,
  TypedRecordQueryOptions,
  TypedRecordPage,
  TypedRecordWriteResult,
} from '../../../core/platform/custom-objects/manager';
import {
  createRqlHelpers,
  type RqlFieldToken,
  type RqlComparableValue,
  type RqlFragment,
} from '../../../core/platform/custom-objects/rql';
import type {
  AnyCustomObjectDefinition,
  AnyFieldDefinition,
  CustomObjectDefinition,
  FieldDefinitions,
  SectionDefinitions,
  NameFieldDefinition,
  RecordShape,
  LogicalCustomObjectName,
  LogicalCategoryName,
} from '../../../core/platform/custom-objects/types';
import type { RequestOptions } from '../../../internal/request-options';
import type {
  FieldListParams,
  CustomObjectField,
  CustomObjectFieldsPageCursorURL,
} from '../../../resources/custom-objects/fields';
import type { CustomObject as DeployedCustomObject } from '../../../resources/custom-objects/custom-objects';
import type { APIPromise } from '../../../core/api-promise';
import type { PagePromise } from '../../../core/pagination';
import { categoryComponent, defineCategory } from './category';
import {
  defineComponent,
  detachedManifestScope,
  withApiName,
  validateCustomApiName,
  type MetadataConfig,
  registeredComponent,
  type CompileContext,
  type ComponentDefinition,
} from './component';
import type { ValueParser } from './function';
import {
  assertObjectInput,
  createObjectRecords,
  type ObjectCreateInput,
  type ObjectUpdateInput,
  type ObjectBulkUpdateInput,
} from './_object-records';

export type { ObjectCreateInput, ObjectUpdateInput, ObjectBulkUpdateInput } from './_object-records';

export type DefineCustomObjectProps<
  A extends `${string}__c`,
  F extends FieldDefinitions,
  C extends string = `${Unsuffixed<A>}_category`,
  S extends SectionDefinitions = {},
  N extends NameFieldDefinition = { kind: 'text' },
> = Omit<ObjectOptions<S, F, N>, 'pluralLabel'> & {
  apiName: A;
  name: string;
  pluralName?: string;
  category?: CategoryInput<C>;
};

export type DefinedCustomObject<D extends { fields: object; apiName: string }> = Omit<
  D,
  'fields' | 'inputs' | 'records' | 'schema'
> & {
  readonly fields: {
    readonly [K in keyof D['fields']]: Omit<D['fields'][K], 'apiName'> & {
      readonly apiName: `${Unsuffixed<Extract<K, string>>}__c`;
      readonly objectApiName: D['apiName'];
    };
  };
  readonly records: D extends AnyCustomObjectDefinition ? Readonly<ObjectRecords<D>> : never;
  readonly schema: D extends AnyCustomObjectDefinition ? Readonly<ObjectSchema> : never;
  readonly inputs: D extends AnyCustomObjectDefinition ?
    {
      readonly create: ValueParser<ObjectCreateInput<D>>;
      readonly update: ValueParser<ObjectUpdateInput<D>>;
    }
  : never;
};

/** Authenticated records transport supplied at the operation's call site. */
export interface ObjectRecordsContext {
  readonly customObjects: { readonly records: CustomObjectRecordsClient };
}

/** Schema resources supplied at the operation's call site. */
export interface ObjectSchemaContext {
  readonly customObjects: Pick<RipplingSDK['customObjects'], 'retrieve' | 'fields'>;
}

export type ObjectRecordListOptions<D extends AnyCustomObjectDefinition> = TypedRecordPageOptions & {
  where?: ObjectFilter<D['apiName']>;
};

/** Typed record operations; writes return readable records or ID-only receipts. Supply an authenticated client at each call. */
export interface ObjectRecords<D extends AnyCustomObjectDefinition> {
  create(ctx: ObjectRecordsContext, input: ObjectCreateInput<D>): Promise<TypedRecordWriteResult<D>>;
  createMany(
    ctx: ObjectRecordsContext,
    rows: readonly ObjectCreateInput<D>[],
    options?: TypedBatchWriteOptions,
  ): Promise<readonly TypedRecordWriteResult<D>[]>;
  get(ctx: ObjectRecordsContext, recordID: string): Promise<RecordShape<D>>;
  getByExternalID(ctx: ObjectRecordsContext, externalID: string): Promise<RecordShape<D>>;
  update(
    ctx: ObjectRecordsContext,
    recordID: string,
    patch: ObjectUpdateInput<D>,
  ): Promise<TypedRecordWriteResult<D>>;
  updateMany(
    ctx: ObjectRecordsContext,
    rows: readonly ObjectBulkUpdateInput<D>[],
    options?: TypedBatchWriteOptions,
  ): Promise<readonly TypedRecordWriteResult<D>[]>;
  delete(ctx: ObjectRecordsContext, recordID: string): Promise<void>;
  deleteMany(
    ctx: ObjectRecordsContext,
    recordIDs: readonly string[],
    options?: TypedBatchWriteOptions,
  ): Promise<void>;
  /** List records with optional typed filters and cursor pagination. */
  list(ctx: ObjectRecordsContext, options?: ObjectRecordListOptions<D>): Promise<TypedRecordPage<D>>;
  /** Run a raw RQL filter with cursor pagination. */
  query(ctx: ObjectRecordsContext, options?: TypedRecordQueryOptions): Promise<TypedRecordPage<D>>;
}

/** Deployed object metadata, separate from the local field definitions. */
export interface ObjectSchema {
  retrieve(ctx: ObjectSchemaContext, options?: RequestOptions): APIPromise<DeployedCustomObject>;
  readonly fields: Readonly<ObjectSchemaFields>;
}

export interface ObjectSchemaFields {
  list(
    ctx: ObjectSchemaContext,
    params?: FieldListParams,
    options?: RequestOptions,
  ): PagePromise<CustomObjectFieldsPageCursorURL, CustomObjectField>;
}

export interface CustomObjectOperations<D extends AnyCustomObjectDefinition> {
  readonly records: Readonly<ObjectRecords<D>>;
  readonly schema: Readonly<ObjectSchema>;
}

/** The same operations with the authenticated client supplied by client.objects(definition). */
export interface ObjectClient<D extends AnyCustomObjectDefinition> {
  create(input: ObjectCreateInput<D>): Promise<TypedRecordWriteResult<D>>;
  createMany(
    rows: readonly ObjectCreateInput<D>[],
    options?: TypedBatchWriteOptions,
  ): Promise<readonly TypedRecordWriteResult<D>[]>;
  get(recordID: string): Promise<RecordShape<D>>;
  getByExternalID(externalID: string): Promise<RecordShape<D>>;
  update(recordID: string, patch: ObjectUpdateInput<D>): Promise<TypedRecordWriteResult<D>>;
  updateMany(
    rows: readonly ObjectBulkUpdateInput<D>[],
    options?: TypedBatchWriteOptions,
  ): Promise<readonly TypedRecordWriteResult<D>[]>;
  delete(recordID: string): Promise<void>;
  deleteMany(recordIDs: readonly string[], options?: TypedBatchWriteOptions): Promise<void>;
  list(options?: ObjectRecordListOptions<D>): Promise<TypedRecordPage<D>>;
  query(options?: TypedRecordQueryOptions): Promise<TypedRecordPage<D>>;
  schema: { retrieve(options?: RequestOptions): APIPromise<DeployedCustomObject> };
  fields: {
    list(
      params?: FieldListParams,
      options?: RequestOptions,
    ): PagePromise<CustomObjectFieldsPageCursorURL, CustomObjectField>;
  };
}

export type ObjectFilter<A extends string> = RqlFragment & { readonly [filterOwner]: A };

export function defineCustomObject<
  const A extends `${string}__c`,
  const F extends FieldDefinitions,
  C extends string = `${Unsuffixed<A>}_category`,
  S extends SectionDefinitions = {},
  N extends NameFieldDefinition = { kind: 'text' },
>(
  props: DefineCustomObjectProps<A, F, C, S, N>,
): DefinedCustomObject<
  CustomObjectDefinition<LogicalCustomObjectName<Unsuffixed<A>>, LogicalCategoryName<C>, S, F, N>
>;
export function defineCustomObject(props: Record<string, any>): object {
  const apiName = props['apiName'] as string;
  validateCustomApiName(apiName);
  const name = apiName.slice(0, -3);
  const sourceFields = props['fields'] as FieldDefinitions;
  const fields = normalizeFieldNames(sourceFields);
  validateSections(props['sections']);
  const category =
    props['category'] ??
    defineCategory({
      apiName: `${name}_category__c`,
      name: props['name'],
      description: props['description'],
    });
  validateCustomApiName(typeof category === 'string' ? category : category.apiName);
  const definition = createObject({
    ...props,
    name,
    displayName: props['name'],
    ...(props['pluralName'] === undefined ? {} : { pluralLabel: props['pluralName'] }),
    category: typeof category === 'string' ? category.slice(0, -3) : category,
    fields,
  } as Parameters<typeof createObject>[0]);
  return customObjectComponent.register(withInputs(definition, Object.keys(sourceFields)), props);
}

/** Existing extension semantics, with the same additive field tokens and parsers. */
export function extendCustomObject<
  B extends AnyCustomObjectDefinition,
  S extends SectionDefinitions = {},
  F extends FieldDefinitions = {},
>(
  base: B,
  extension: Omit<Parameters<typeof extendObject<B, S, F>>[1], 'fields'> & {
    fields?: Extract<keyof B['fields'], keyof F> extends never ? F & ApiNamedMap<F> : never;
    sections?: ApiNamedMap<S>;
  },
): DefinedCustomObject<ReturnType<typeof extendObject<B, S, F>>> {
  const fields = normalizeFieldNames(base.fields);
  const addedFields = normalizeFieldNames<AnyFieldDefinition>(extension.fields ?? {});
  validateSections(extension.sections);
  for (const key of Object.keys(extension.fields ?? {})) {
    if (Object.prototype.hasOwnProperty.call(fields, key.replace(/__c$/, '')))
      throw new Error(`Cannot replace existing custom field ${key} on ${base.apiName}.`);
  }
  const definition = extendObject(
    { ...base, fields } as B,
    { ...extension, fields: addedFields } as unknown as Parameters<typeof extendObject<B, S, F>>[1],
  ) as unknown as AnyCustomObjectDefinition;
  const keys = [...Object.keys(base.fields), ...Object.keys(extension.fields ?? {})];
  return extendedObjectComponent.register(
    withInputs(definition, keys),
    base,
    extension,
  ) as unknown as DefinedCustomObject<ReturnType<typeof extendObject<B, S, F>>>;
}

export const eq = <T, const A extends string>(
  field: FieldToken<T, A>,
  value: RqlComparableValue<NoInfer<T>> | null,
) => query.eq(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const ne = <T, const A extends string>(
  field: FieldToken<T, A>,
  value: RqlComparableValue<NoInfer<T>> | null,
) => query.ne(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const lt = <T extends string | number, const A extends string>(
  field: FieldToken<T | null, A>,
  value: NoInfer<T>,
) => query.lt(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const lte = <T extends string | number, const A extends string>(
  field: FieldToken<T | null, A>,
  value: NoInfer<T>,
) => query.lte(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const gt = <T extends string | number, const A extends string>(
  field: FieldToken<T | null, A>,
  value: NoInfer<T>,
) => query.gt(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const gte = <T extends string | number, const A extends string>(
  field: FieldToken<T | null, A>,
  value: NoInfer<T>,
) => query.gte(field as unknown as RqlFieldToken<T>, value) as ObjectFilter<A>;

export const inArray = <T, const A extends string>(
  field: FieldToken<T, A>,
  values: readonly RqlComparableValue<NoInfer<T>>[],
) => query.in(field as unknown as RqlFieldToken<T>, values) as ObjectFilter<A>;

export const notInArray = <T, const A extends string>(
  field: FieldToken<T, A>,
  values: readonly RqlComparableValue<NoInfer<T>>[],
) => query.notIn(field as unknown as RqlFieldToken<T>, values) as ObjectFilter<A>;

export const isNull = <T, const A extends string>(field: FieldToken<T, A>) =>
  query.isNull(field as unknown as RqlFieldToken<T>) as ObjectFilter<A>;

export const isNotNull = <T, const A extends string>(field: FieldToken<T, A>) =>
  query.isNotNull(field as unknown as RqlFieldToken<T>) as ObjectFilter<A>;

export const and = <const A extends string>(first: ObjectFilter<A>, ...rest: ObjectFilter<NoInfer<A>>[]) =>
  query.and(first, ...rest) as ObjectFilter<A>;

export const or = <const A extends string>(first: ObjectFilter<A>, ...rest: ObjectFilter<NoInfer<A>>[]) =>
  query.or(first, ...rest) as ObjectFilter<A>;

export const not = <const A extends string>(filter: ObjectFilter<A>) => query.not(filter) as ObjectFilter<A>;

type Unsuffixed<N extends string> = N extends `${infer Name}__c` ? Name : N;

/** Enrich the existing immutable schema; normalization and validation stay in the existing factory. */
function withInputs<D extends AnyCustomObjectDefinition>(
  definition: D,
  keys = Object.keys(definition.fields),
): DefinedCustomObject<D> {
  const fields = Object.freeze(
    Object.fromEntries(
      keys.map((key) => [
        key,
        Object.freeze({
          ...definition.fields[key.replace(/__c$/, '')]!,
          logicalName: key,
          objectApiName: definition.apiName,
        }),
      ]),
    ),
  );
  const enriched = { ...definition, fields } as D;
  const parser = <T>(operation: 'create' | 'update'): ValueParser<T> => ({
    parse(value) {
      if (value == null || typeof value !== 'object' || Array.isArray(value))
        throw new TypeError('Expected a record object.');
      assertObjectInput(enriched, value as Record<string, unknown>, operation);
      return value as T;
    },
  });
  return Object.freeze({
    ...enriched,
    ...createObjectOperations(enriched),
    fields,
    inputs: Object.freeze({
      create: parser<ObjectCreateInput<D>>('create'),
      update: parser<ObjectUpdateInput<D>>('update'),
    }),
  }) as DefinedCustomObject<D>;
}

function normalizeFieldNames<T>(fields: Readonly<Record<string, T>>) {
  return Object.fromEntries(
    Object.entries(fields).map(([apiName, field]) => {
      validateCustomApiName(apiName);
      return [apiName.slice(0, -3), field];
    }),
  );
}

function validateSections(sections: SectionDefinitions = {}): void {
  for (const [apiName, section] of Object.entries(sections)) {
    validateCustomApiName(apiName);
    if (section.sectionId !== undefined) validateCustomApiName(section.sectionId);
  }
}

type ApiNamedMap<T> = {
  [K in keyof T]: string extends K ? T[K]
  : K extends `${string}__c` ? T[K]
  : never;
};

type CategoryInput<N extends string> = `${N}__c` | CustomObjectCategoryDefinition<LogicalCategoryName<N>>;

type ObjectOptions<
  S extends SectionDefinitions,
  F extends FieldDefinitions,
  N extends NameFieldDefinition,
> = Pick<
  AnyCustomObjectDefinition,
  'description' | 'pluralLabel' | 'icon' | 'ownerRole' | 'enableHistory'
> & {
  sections?: S & ApiNamedMap<S>;
  fields: F &
    ApiNamedMap<F> & {
      [K in keyof F]: string extends Exclude<F[K]['section'], undefined> ? F[K]
      : Exclude<F[K]['section'], undefined> extends keyof NoInfer<S> ? F[K]
      : never;
    };
  nameField?: N;
};

/** Operations capture only the definition; each call supplies its own authenticated transport. */
function createObjectOperations<D extends AnyCustomObjectDefinition>(
  definition: D,
): CustomObjectOperations<D> {
  return {
    records: createObjectRecords(definition),
    schema: Object.freeze<ObjectSchema>({
      retrieve: (ctx, options) => ctx.customObjects.retrieve(definition.apiName, options),
      fields: Object.freeze<ObjectSchemaFields>({
        list: (ctx, params, options) => ctx.customObjects.fields.list(definition.apiName, params, options),
      }),
    }),
  };
}

/** @internal Forward client helpers to the definition operations. */
export function createObjectClient<D extends AnyCustomObjectDefinition>(
  ctx: ObjectRecordsContext & ObjectSchemaContext,
  definition: D,
): ObjectClient<D> {
  const { records, schema } = createObjectOperations(definition);
  return {
    create: (input) => records.create(ctx, input),
    createMany: (rows, options) => records.createMany(ctx, rows, options),
    get: (recordID) => records.get(ctx, recordID),
    getByExternalID: (externalID) => records.getByExternalID(ctx, externalID),
    update: (recordID, patch) => records.update(ctx, recordID, patch),
    updateMany: (rows, options) => records.updateMany(ctx, rows, options),
    delete: (recordID) => records.delete(ctx, recordID),
    deleteMany: (recordIDs, options) => records.deleteMany(ctx, recordIDs, options),
    list: (options) => records.list(ctx, options),
    query: (options) => records.query(ctx, options),
    schema: { retrieve: (options) => schema.retrieve(ctx, options) },
    fields: {
      list: (params, options) => schema.fields.list(ctx, params, options),
    },
  };
}

// Reuse the existing operators, carrying the schema's object identity through typed filters.
const query = createRqlHelpers({ fields: {} } as AnyCustomObjectDefinition);

declare const filterOwner: unique symbol;

type FieldToken<T, A extends string> = Pick<RqlFieldToken<T>, 'apiName' | '__valueType__'> & {
  readonly objectApiName: A;
};

declare const objectScope: unique symbol;

/** Carry parent identity through helpers while still accepting existing constructor instances. */
export type ObjectScoped<TObject extends ObjectReference, TDefinition> = TDefinition & {
  readonly [objectScope]: TObject['apiName'];
};

export function scopedDefinition<TObject extends ObjectReference, TDefinition extends object>(
  _object: TObject,
  definition: TDefinition,
): ObjectScoped<TObject, TDefinition> {
  return definition as ObjectScoped<TObject, TDefinition>;
}

/** A complete schema is a local dependency; an identity-only target names an existing resource. */
function isObjectDefinition(value: object): value is AnyCustomObjectDefinition {
  return 'fields' in value && 'nameField' in value && 'categoryApiName' in value;
}

export function fieldReferences<TObject extends ObjectReference>(
  owner: TObject,
  field: DefinitionFieldReference<TObject>,
): object[] {
  return [typeof field === 'object' && 'getApiName' in field ? field : owner];
}

const currentFieldSections = new WeakMap<Field, CustomObjectFieldSection | undefined>();

/** Keep dependency collection in sync with layout-driven field moves. */
export function trackFieldSection<T extends Field>(field: T, section: CustomObjectFieldSection): T {
  currentFieldSections.set(field, section);
  const assignSection = field._assignSection.bind(field);
  field._assignSection = (section) => {
    assignSection(section);
    currentFieldSections.set(field, typeof section === 'string' ? undefined : section);
  };
  return field;
}

export function fieldSectionReferences(field: Field): object[] {
  const section = currentFieldSections.get(field);
  // Schema-owned sections are emitted by the object compiler; authored sections are dependencies.
  return section != null && registeredComponent(section) != null ? [section] : [];
}

/** Shared by section serialization and authored/default conflict detection. */
function fieldSectionApiName(definition: AnyCustomObjectDefinition, key: string): string {
  const apiName = definition.sections[key]?.sectionId ?? key;
  validateCustomApiName(apiName);
  return apiName;
}

/** Reuse the typed SDK's field compiler and the metadata SDK's serializers. */
function objectMetadata(definition: AnyCustomObjectDefinition): ObjectMetadata {
  const existing = registrations.get(definition);
  if (existing != null) return existing;
  if (
    definition.ownerRole != null ||
    definition.enableHistory != null ||
    Object.values(definition.fields).some(
      (field) => field.enableHistory != null || field.restSection != null || field.rqlDefinition != null,
    )
  )
    throw new Error('REST-only object options cannot be compiled to metadata.');
  const category = new Category(detachedManifestScope, {
    apiName: definition.categoryApiName,
    name: definition.categoryDefinition?.displayName ?? definition.category,
    description: definition.categoryDefinition?.description ?? '',
  });
  const components: ManifestComponent[] = [];
  const object = new CustomObject(
    {
      _register(component) {
        components.push(component);
      },
    },
    {
      apiName: definition.apiName,
      name: definition.displayName,
      category,
      description: definition.description,
      ...(definition.pluralLabel == null ? {} : { pluralLabel: definition.pluralLabel }),
      ...(definition.icon == null ? {} : { icon: definition.icon }),
      nameFieldDetails: buildCustomObjectNameFieldDetails(definition) ?? null,
    },
  );
  const sections = Object.fromEntries(
    Object.entries(definition.sections).map(([key, section]) => {
      const apiName = fieldSectionApiName(definition, key);
      return [
        key,
        withApiName(
          new CustomObjectFieldSection(object, { name: section.name, sectionId: apiName }),
          apiName,
        ),
      ];
    }),
  );
  const needsFallback =
    Object.keys(sections).length === 0 ||
    Object.values(definition.fields).some((field) => field.section == null);
  const generalKey = `${definition.name}_general__c`;
  const defaultSectionApiName = fieldSectionApiName(definition, generalKey);
  const defaultSection =
    needsFallback ?
      sections[generalKey] ??
      withApiName(
        new CustomObjectFieldSection(object, { name: 'General', sectionId: defaultSectionApiName }),
        defaultSectionApiName,
      )
    : undefined;
  const firstSection = defaultSection ?? Object.values(sections)[0]!;
  withApiName(object, definition.apiName, { default_field_section_api_name: firstSection.getSectionId() });
  // Provisioning needs section handles; here they are deterministic API names instead of destination IDs.
  const provisionable = {
    ...definition,
    sections: Object.fromEntries(
      Object.entries(sections).map(([key, section]) => [
        key,
        { name: section.getName(), sectionId: section.getSectionId() },
      ]),
    ),
  };
  const fields = Object.fromEntries(
    Object.entries(definition.fields).map(([key, field]) => {
      const section = field.section == null ? defaultSection : sections[field.section];
      if (section == null) throw new Error(`Unknown section ${field.section} on ${definition.apiName}.`);
      const { create } = buildProvisionableFieldParams(provisionable, key);
      return [
        key,
        trackFieldSection(
          new Field(object, {
            apiName: field.apiName,
            displayName: field.displayName,
            description: field.description,
            section,
            dataType: create.data_type,
            required: field.writable ? field.required : null,
            unique: create.is_unique ?? null,
            derivedFieldFormula: create.derived_field_formula ?? null,
            ...(field.formulaAttributeMetas == null ? {} : { formulaAttrMetas: field.formulaAttributeMetas }),
            ...(field.derivedAggregatedField == null ?
              {}
            : { derivedAggregatedField: field.derivedAggregatedField }),
          }),
          section,
        ),
      ];
    }),
  );
  const layoutSections = [
    ...new Set([...Object.values(sections), ...(defaultSection == null ? [] : [defaultSection])]),
  ];
  const layout = withApiName(
    new CustomObjectPageLayout(object, {
      apiName: 'default',
      layoutId: 'default',
      name: `${definition.displayName} Layout`,
      tabEdits: {
        newTabs: [
          {
            key: 'details',
            name: 'Details',
            type: 'tab_with_sections',
            sections: layoutSections.map((section, index) => ({
              name: section.getName(),
              type: 'fields_section',
              section,
              fields: [
                ...(index === 0 ? [object.standardFields.name] : []),
                ...Object.values(fields).filter((field) => field.getSectionId() === section.getSectionId()),
              ],
            })),
          },
        ],
        systemTabEdits: {},
        tabsOrder: ['details'],
      },
    }),
    'default',
  );
  const metadata = {
    object,
    sections,
    defaultSection,
    fields,
    layout,
    components: [...components],
    defaultFieldSectionApiName: firstSection.getSectionId(),
  };
  registrations.set(definition, metadata);
  return metadata;
}

export type ObjectReference = AnyCustomObjectDefinition;

export type DefinitionFieldReference<TObject extends ObjectReference> =
  | TObject['fields'][keyof TObject['fields']]
  | ObjectScoped<TObject, Field>
  | CustomObjectStandardFieldIdentifier;

interface ObjectMetadata {
  object: CustomObject;
  sections: Record<string, CustomObjectFieldSection>;
  defaultSection: CustomObjectFieldSection | undefined;
  fields: Record<string, Field>;
  layout: CustomObjectPageLayout;
  components: ManifestComponent[];
  defaultFieldSectionApiName: string;
}

const registrations = new WeakMap<AnyCustomObjectDefinition, ObjectMetadata>();

export type SectionReference<TObject extends ObjectReference> =
  | ObjectScoped<TObject, CustomObjectFieldSection>
  | Extract<keyof TObject['sections'], string>
  | 'general';

export function manifestSection<TObject extends ObjectReference>(
  object: TObject,
  reference: SectionReference<TObject>,
): CustomObjectFieldSection {
  if (typeof reference !== 'string') {
    if (reference.getModelApiName() !== manifestObject(object).getApiName())
      throw new Error('Section reference belongs to another object.');
    return reference;
  }
  const registration = objectMetadata(object);
  const section =
    registration.sections[reference] ?? (reference === 'general' ? registration.defaultSection : undefined);
  if (section == null) throw new Error(`Unknown section ${reference} on ${object.apiName}.`);
  return section;
}

/** References and compilation reuse one materialized schema; authored children remain explicit roots. */
export function manifestObject(reference: ObjectReference): CustomObject {
  return objectMetadata(reference).object;
}

/** Adapts a typed schema field to the existing layout, view, and rule component APIs. */
export function manifestField<TObject extends ObjectReference>(
  object: TObject,
  field: NoInfer<DefinitionFieldReference<TObject>>,
): Field {
  const metadata = objectMetadata(object);
  const resolved = metadata.object;
  const candidate = field as CustomObjectFieldInput | AnyCustomObjectDefinition['fields'][string];
  if (typeof candidate === 'string') return resolved.standardField(candidate);
  if ('getApiName' in candidate) {
    if (candidate.getCustomObjectApiName() !== resolved.getApiName())
      throw new Error('Field reference belongs to another object.');
    return candidate;
  }
  if ('objectApiName' in candidate && candidate.objectApiName !== object.apiName)
    throw new Error('Field reference belongs to another object.');
  const registered = metadata.fields[candidate.logicalName];
  if (registered == null) throw new Error(`Unknown field ${candidate.logicalName} on ${object.apiName}.`);
  return registered;
}

const behavior = {
  type: 'CUSTOM_OBJECT' as const,
  references(definition: AnyCustomObjectDefinition): () => object[] {
    const category = definition.categoryDefinition;
    if (category != null && registeredComponent(category) == null)
      categoryComponent.register(category, category);
    return () => [
      ...(category == null ? [] : [category]),
      ...Object.values(registrations.get(definition)?.fields ?? {}).flatMap(fieldSectionReferences),
      ...(Object.values(definition.fields) as AnyFieldDefinition[]).flatMap((field) =>
        field.kind === 'lookup' || field.kind === 'parent-child' ?
          isObjectDefinition(field.target) ? [field.target]
          : []
        : [],
      ),
    ];
  },
  compileBatch(definitions: readonly AnyCustomObjectDefinition[], context: CompileContext) {
    const categories = new Set(
      context.definitions
        .filter((definition) => registeredComponent(definition)?.type === 'CUSTOM_CATEGORY')
        .flatMap((definition) => ('apiName' in definition ? [definition.apiName] : [])),
    );
    // Generate defaults from the complete schema, including base definitions reached through children.
    const schemas = new Map<string, AnyCustomObjectDefinition>();
    for (const definition of definitions) {
      const previous = schemas.get(definition.apiName);
      if (previous == null) {
        schemas.set(definition.apiName, definition);
        continue;
      }
      schemas.set(definition.apiName, {
        ...previous,
        sections: { ...previous.sections, ...definition.sections },
        fields: Object.fromEntries(
          [...Object.values(previous.fields), ...Object.values(definition.fields)].map((field) => [
            field.apiName,
            field,
          ]),
        ),
      });
    }
    const defaults = new Map([...schemas].map(([apiName, schema]) => [apiName, objectMetadata(schema)]));
    return definitions.flatMap((definition) => {
      if (!categories.has(definition.categoryApiName))
        throw new Error(
          `Include a category definition for ${definition.categoryApiName}, or use a typed category in ${definition.apiName}.`,
        );
      const generated = defaults.get(definition.apiName)!;
      const authoredSections = new Set(
        Object.keys(definition.sections).map((key) => fieldSectionApiName(definition, key)),
      );
      const metadata = objectMetadata(definition);
      return metadata.components.map((component) => {
        const config = (component === metadata.layout ? generated.layout : component).toDict();
        if (component === metadata.object)
          config['default_field_section_api_name'] = generated.defaultFieldSectionApiName;
        return {
          config: config as MetadataConfig,
          fallback:
            component === metadata.layout ||
            (component === metadata.defaultSection && !authoredSections.has(config['api_name'])),
        };
      });
    });
  },
};

const customObjectComponent: ComponentDefinition<typeof defineCustomObject> = defineComponent({
  ...behavior,
  define: defineCustomObject,
});

const extendedObjectComponent = defineComponent({
  ...behavior,
  define: extendCustomObject,
});