@rippling/rippling-sdk 0.2.0-alpha.109 → 0.2.0-alpha.110

package/src/lib/manifest/definitions/_object-records.ts

@@ -0,0 +1,218 @@
+import {
+  createCustomObjectRecordAdapter,
+  CustomObjectRecordValidationError,
+} from '../../../core/platform/custom-objects/manager';
+import {
+  validateCreateInput,
+  validateUpdateInput,
+  type ValidationIssue,
+} from '../../../core/platform/custom-objects/validation';
+import type {
+  AnyCustomObjectDefinition,
+  AnyFieldDefinition,
+  CreateInput,
+  UpdateInput,
+  FieldValue,
+  RecordShape,
+} from '../../../core/platform/custom-objects/types';
+import type { CustomObjectDataRow } from '../../../resources/custom-objects/records';
+import type { ObjectRecords, ObjectRecordsContext } from './custom-object';
+
+type NullableFields<D extends AnyCustomObjectDefinition> = {
+  [K in keyof D['fields']]: D['fields'][K] extends { writable: true; required: false } ? K : never;
+}[keyof D['fields']];
+
+/** Definition-based writes accept null for writable, non-required custom fields. */
+export type ObjectCreateInput<D extends AnyCustomObjectDefinition> = Omit<
+  CreateInput<D>,
+  NullableFields<D>
+> & {
+  [K in NullableFields<D>]?: FieldValue<D['fields'][K]> | null;
+};
+
+export type ObjectUpdateInput<D extends AnyCustomObjectDefinition> = Omit<
+  UpdateInput<D>,
+  NullableFields<D>
+> & {
+  [K in NullableFields<D>]?: FieldValue<D['fields'][K]> | null;
+};
+
+export type ObjectBulkUpdateInput<D extends AnyCustomObjectDefinition> = {
+  readonly id: string;
+} & ObjectUpdateInput<D>;
+
+/** Reuse the existing value checks, excluding only explicitly allowed null custom-field values. */
+function inputIssues(
+  definition: AnyCustomObjectDefinition,
+  input: Record<string, unknown>,
+  operation: 'create' | 'update',
+): readonly ValidationIssue[] {
+  if (input == null || typeof input !== 'object' || Array.isArray(input))
+    return [{ path: '', message: 'Expected a record object.' }];
+  const checked = { ...input };
+  for (const [key, field] of Object.entries(definition.fields)) {
+    if (field.writable && !field.required && checked[key] === null) delete checked[key];
+  }
+  return (operation === 'create' ? validateCreateInput : validateUpdateInput)(definition, checked).issues;
+}
+
+export function assertObjectInput(
+  definition: AnyCustomObjectDefinition,
+  input: Record<string, unknown>,
+  operation: 'create' | 'update',
+): void {
+  const issues = inputIssues(definition, input, operation);
+  if (issues.length > 0) throw new CustomObjectRecordValidationError(definition, operation, issues);
+}
+
+function referenceID(value: unknown): unknown {
+  return value != null && typeof value === 'object' && 'id' in value ? value.id : value;
+}
+
+function serializeInput(
+  definition: AnyCustomObjectDefinition,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const wire: Record<string, unknown> = {};
+  for (const key of ['name', 'external_id', 'owner_role']) {
+    if (Object.prototype.hasOwnProperty.call(input, key) && input[key] !== undefined)
+      wire[key] = key === 'owner_role' ? referenceID(input[key]) : input[key];
+  }
+  for (const [key, field] of Object.entries(definition.fields)) {
+    if (!Object.prototype.hasOwnProperty.call(input, key) || input[key] === undefined) continue;
+    wire[field.apiName] =
+      field.kind === 'lookup' || field.kind === 'parent-child' || field.kind === 'file' ?
+        referenceID(input[key])
+      : input[key];
+  }
+  return wire;
+}
+
+function lookup(value: unknown, apiName: string) {
+  if (typeof value === 'string') return { id: value, apiName };
+  if (value != null && typeof value === 'object' && 'id' in value && typeof value.id === 'string') {
+    return {
+      id: value.id,
+      apiName: 'apiName' in value && typeof value.apiName === 'string' ? value.apiName : apiName,
+    };
+  }
+  return null;
+}
+
+function fieldValue(field: AnyFieldDefinition, value: unknown): unknown {
+  if (value == null) return null;
+  switch (field.kind) {
+    case 'lookup':
+    case 'parent-child':
+      return lookup(value, field.targetApiName ?? 'unknown');
+    case 'file':
+      return (
+        typeof value === 'string' ? value
+        : value != null && typeof value === 'object' && 'id' in value && typeof value.id === 'string' ?
+          { id: value.id }
+        : null
+      );
+    case 'number':
+    case 'currency':
+    case 'percentage':
+    case 'formula-number':
+    case 'formula-currency':
+    case 'formula-percentage': {
+      const numeric =
+        typeof value === 'number' ? value
+        : typeof value === 'string' && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value) ?
+          Number(value)
+        : NaN;
+      if (!Number.isFinite(numeric))
+        throw new TypeError(`Invalid numeric value for ${field.apiName}: expected a finite number.`);
+      return numeric;
+    }
+    default:
+      return value;
+  }
+}
+
+function decodeRecord<D extends AnyCustomObjectDefinition>(
+  definition: D,
+  row: CustomObjectDataRow,
+): RecordShape<D> {
+  const record: Record<string, unknown> = { id: row.id, name: row.name };
+  for (const key of ['created_at', 'updated_at', 'system_updated_at', 'external_id'])
+    record[key] = typeof row[key] === 'string' ? row[key] : null;
+  for (const key of ['owner_role', 'created_by', 'last_modified_by'])
+    record[key] = lookup(row[key], 'Employee');
+  for (const [key, field] of Object.entries(definition.fields))
+    record[key] = fieldValue(field as AnyFieldDefinition, row[field.apiName]);
+  return record as RecordShape<D>;
+}
+
+/** Definition-specific nullability and decoding; the shared manager and legacy constructors are unchanged. */
+export function createObjectRecords<D extends AnyCustomObjectDefinition>(
+  definition: D,
+): Readonly<ObjectRecords<D>> {
+  const adapter = (ctx: ObjectRecordsContext) => createCustomObjectRecordAdapter(ctx.customObjects.records);
+  const decode = (row: CustomObjectDataRow) => decodeRecord(definition, row);
+  const serializeBatch = (rows: readonly Record<string, unknown>[], operation: 'create' | 'update') => {
+    const issues = rows.flatMap((row, index) => {
+      if (row == null || typeof row !== 'object' || Array.isArray(row))
+        return [{ path: `[${index}]`, message: 'Expected a record object.' }];
+      const { id, ...patch } = row;
+      return [
+        ...(operation === 'update' && (typeof id !== 'string' || id.length === 0) ?
+          [{ path: `[${index}].id`, message: 'Expected a record id string.' }]
+        : []),
+        ...inputIssues(definition, operation === 'update' ? patch : row, operation).map((issue) => ({
+          ...issue,
+          path: `[${index}].${issue.path}`,
+        })),
+      ];
+    });
+    if (issues.length > 0)
+      throw new CustomObjectRecordValidationError(
+        definition,
+        operation === 'create' ? 'bulk-create' : 'bulk-update',
+        issues,
+      );
+    return rows.map((row) =>
+      operation === 'create' ?
+        serializeInput(definition, row)
+      : { id: row['id'], ...serializeInput(definition, row) },
+    );
+  };
+  const query = async (ctx: ObjectRecordsContext, options: Parameters<ObjectRecords<D>['query']>[1]) => {
+    const page = await adapter(ctx).query(definition.apiName, options ?? {});
+    return { cursor: page.cursor, results: page.results.map(decode) };
+  };
+  return Object.freeze<ObjectRecords<D>>({
+    async create(ctx, input) {
+      assertObjectInput(definition, input, 'create');
+      return decode(await adapter(ctx).create(definition.apiName, serializeInput(definition, input)));
+    },
+    async createMany(ctx, rows, options) {
+      const rowsToWrite = serializeBatch(rows, 'create');
+      return (await adapter(ctx).bulkCreate(definition.apiName, { ...options, rowsToWrite })).map(decode);
+    },
+    async get(ctx, recordID) {
+      return decode(await adapter(ctx).retrieve(definition.apiName, recordID));
+    },
+    async getByExternalID(ctx, externalID) {
+      return decode(await adapter(ctx).retrieveByExternalID(definition.apiName, externalID));
+    },
+    async update(ctx, recordID, patch) {
+      assertObjectInput(definition, patch, 'update');
+      return decode(
+        await adapter(ctx).update(definition.apiName, recordID, serializeInput(definition, patch)),
+      );
+    },
+    async updateMany(ctx, rows, options) {
+      const rowsToUpdate = serializeBatch(rows, 'update');
+      return (await adapter(ctx).bulkUpdate(definition.apiName, { ...options, rowsToUpdate })).map(decode);
+    },
+    delete: (ctx, recordID) => adapter(ctx).delete(definition.apiName, recordID),
+    deleteMany: (ctx, recordIDs, options) =>
+      adapter(ctx).bulkDelete(definition.apiName, { ...options, rowsToDelete: recordIDs }),
+    list: (ctx, { where, ...options } = {}) =>
+      query(ctx, { ...options, ...(where === undefined ? {} : { query: where.text }) }),
+    query,
+  });
+}

package/src/lib/manifest/definitions/action.ts

@@ -0,0 +1,31 @@
+import { defineComponent, withApiName, validateCustomApiName, type ComponentDefinition } from './component';
+import { CustomObjectAction, type CustomObjectActionProps } from '../custom-object-action';
+import { manifestObject, type ObjectReference } from './custom-object';
+
+export type DefineActionProps = Omit<CustomObjectActionProps, 'actionId' | 'apiName'> & {
+  apiName: `${string}__c`;
+};
+
+export function defineAction(object: ObjectReference, props: DefineActionProps): CustomObjectAction {
+  validateCustomApiName(props.apiName);
+  const action = withApiName(
+    new CustomObjectAction(manifestObject(object), { ...props, actionId: props.apiName }),
+    props.apiName,
+  );
+  currentFunction.set(action, props.function);
+  const setFunction = action.setFunction.bind(action);
+  action.setFunction = (definition) => {
+    setFunction(definition);
+    currentFunction.set(action, definition);
+    return action;
+  };
+  return actionComponent.register(action, object, props);
+}
+
+const currentFunction = new WeakMap<CustomObjectAction, CustomObjectActionProps['function']>();
+
+const actionComponent: ComponentDefinition<typeof defineAction> = defineComponent({
+  type: 'CUSTOM_OBJECT_ACTION',
+  define: defineAction,
+  references: (definition, object) => () => [object, currentFunction.get(definition)!],
+});

package/src/lib/manifest/definitions/agent.ts

@@ -0,0 +1,149 @@
+import { ACPAgent, type ACPAgentProps, type ACPAgentSourceFile } from '../acp-agent';
+import { detachedManifestScope, defineComponent, sourceEntry, validateCustomApiName } from './component';
+import type { RipplingSDK } from '../../../client';
+import type { RequestOptions } from '../../../internal/request-options';
+import type {
+  SessionCreateParams,
+  SessionListParams,
+  SessionCreateResponse,
+  SessionListResponse,
+  SessionListResponsesPageCursorURL,
+} from '../../../resources/agents/sessions/sessions';
+import type { AgentRetrieveResponse } from '../../../resources/agents/agents';
+import type { APIPromise } from '../../../core/api-promise';
+import type { PagePromise } from '../../../core/pagination';
+
+export type DefinedAgentProps = { apiName: `${string}__c` } & (
+  | (ACPAgentProps & { source?: never })
+  | (Omit<ACPAgentProps, 'files' | 'entrypoint'> & { source: URL; files?: never; entrypoint?: never })
+);
+
+/** Authenticated agent resources supplied per call. */
+export interface AgentOperationsContext {
+  readonly agents: {
+    readonly retrieve: RipplingSDK['agents']['retrieve'];
+    readonly sessions: Pick<RipplingSDK['agents']['sessions'], 'create' | 'list'>;
+  };
+}
+
+export interface AgentSessions {
+  create(
+    ctx: AgentOperationsContext,
+    params: Omit<SessionCreateParams, 'agent_id'>,
+    options?: RequestOptions,
+  ): APIPromise<SessionCreateResponse>;
+  list(
+    ctx: AgentOperationsContext,
+    params?: SessionListParams,
+    options?: RequestOptions,
+  ): PagePromise<SessionListResponsesPageCursorURL, SessionListResponse>;
+}
+
+export interface AgentOperations {
+  retrieve(ctx: AgentOperationsContext, options?: RequestOptions): APIPromise<AgentRetrieveResponse>;
+  sessions: AgentSessions;
+}
+
+export interface AgentClient {
+  retrieve(options?: RequestOptions): APIPromise<AgentRetrieveResponse>;
+  sessions: {
+    create(
+      params: Omit<SessionCreateParams, 'agent_id'>,
+      options?: RequestOptions,
+    ): APIPromise<SessionCreateResponse>;
+    list(
+      params?: SessionListParams,
+      options?: RequestOptions,
+    ): PagePromise<SessionListResponsesPageCursorURL, SessionListResponse>;
+  };
+}
+
+export function defineAgent(props: DefinedAgentProps): DefinedAgent {
+  if (props.source !== undefined && (props.files !== undefined || props.entrypoint !== undefined))
+    throw new Error('Define an agent with either source or files/entrypoint, not both.');
+  return agentComponent.register(new DefinedAgent(props), props);
+}
+
+export class DefinedAgent extends ACPAgent {
+  private _source: URL | undefined;
+  readonly retrieve: (
+    ctx: AgentOperationsContext,
+    options?: RequestOptions,
+  ) => APIPromise<AgentRetrieveResponse>;
+  readonly sessions: AgentSessions;
+  constructor(props: DefinedAgentProps) {
+    validateCustomApiName(props.apiName);
+    if (props.source !== undefined && props.source.protocol !== 'file:')
+      throw new Error('Component source must be a file URL.');
+    super(
+      detachedManifestScope,
+      props.source !== undefined ? { ...props, files: [], entrypoint: 'index.ts' } : (props as ACPAgentProps),
+    );
+    this._source = props.source === undefined ? undefined : new URL(props.source.href);
+    const operations = createAgentOperations(this);
+    this.retrieve = operations.retrieve;
+    this.sessions = operations.sessions;
+  }
+
+  get source(): URL | undefined {
+    return this._source;
+  }
+
+  /** Replaces inline files or a file-backed source with the supplied files and entrypoint. */
+  override setSource(files: ACPAgentSourceFile[], entrypoint: string): this {
+    super.setSource(files, entrypoint);
+    this._source = undefined;
+    return this;
+  }
+}
+
+interface AgentMetadata {
+  type: 'ACP_AGENT';
+  api_name: string;
+  source_agent_id: string;
+  name: string;
+  entrypoint: string;
+  files: { type: 'ACP_AGENT'; path: string; content: string; kind: string }[];
+}
+
+/** @internal Shared with the legacy client helper, including constructor-based agent references. */
+function createAgentOperations(definition: ACPAgent): AgentOperations {
+  return {
+    retrieve: (ctx: AgentOperationsContext, options?: RequestOptions) =>
+      ctx.agents.retrieve(definition.getApiName(), options),
+    sessions: {
+      create: (
+        ctx: AgentOperationsContext,
+        params: Omit<SessionCreateParams, 'agent_id'>,
+        options?: RequestOptions,
+      ) => ctx.agents.sessions.create({ ...params, agent_id: definition.getApiName() }, options),
+      list: (ctx: AgentOperationsContext, params?: SessionListParams, options?: RequestOptions) =>
+        ctx.agents.sessions.list(definition.getApiName(), params, options),
+    },
+  };
+}
+
+const agentComponent = defineComponent({
+  type: 'ACP_AGENT',
+  define: defineAgent,
+  serialize: (definition) =>
+    sourceEntry(definition.toDict() as AgentMetadata, definition.source, (config, content) => ({
+      ...config,
+      files: [{ type: 'ACP_AGENT' as const, path: 'index.ts', content, kind: 'typescript' }],
+      entrypoint: 'index.ts',
+    })),
+});
+
+/** @internal Forward client helpers to the definition operations. */
+export function createAgentClient(ctx: AgentOperationsContext, definition: ACPAgent): AgentClient {
+  const operations = createAgentOperations(definition);
+  return {
+    retrieve: (options?: RequestOptions) => operations.retrieve(ctx, options),
+    sessions: {
+      create: (params: Omit<SessionCreateParams, 'agent_id'>, options?: RequestOptions) =>
+        operations.sessions.create(ctx, params, options),
+      list: (params?: SessionListParams, options?: RequestOptions) =>
+        operations.sessions.list(ctx, params, options),
+    },
+  };
+}

package/src/lib/manifest/definitions/app.ts

@@ -0,0 +1,12 @@
+import { defineComponent, detachedManifestScope, type ComponentDefinition } from './component';
+import { App, type AppProps } from '../app';
+
+export function defineApp(props: AppProps): App {
+  return appComponent.register(new App(detachedManifestScope, props), props);
+}
+
+const appComponent: ComponentDefinition<typeof defineApp> = defineComponent({
+  type: 'CUSTOM_APP',
+  define: defineApp,
+  references: (_definition, props) => props.pages,
+});

package/src/lib/manifest/definitions/category.ts

@@ -0,0 +1,35 @@
+import type { CustomObjectCategoryDefinition } from '../../../core/platform/custom-objects/category';
+import { Category, type CategoryProps } from '../category';
+import { detachedManifestScope, defineComponent, validateCustomApiName } from './component';
+
+export type DefineCustomObjectCategoryProps<TApiName extends `${string}__c` = `${string}__c`> =
+  CategoryProps & { apiName: TApiName };
+
+export function defineCategory<const TApiName extends `${string}__c`>(
+  props: DefineCustomObjectCategoryProps<TApiName>,
+): Category & CustomObjectCategoryDefinition<TApiName extends `${infer N}__c` ? N : never>;
+export function defineCategory(props: CategoryProps): Category | CustomObjectCategoryDefinition {
+  validateCustomApiName(props.apiName);
+  return categoryComponent.register(
+    Object.assign(new Category(detachedManifestScope, props), {
+      apiName: props.apiName,
+      name: props.apiName.replace(/__c$/, ''),
+      displayName: props.name,
+      description: props.description,
+    }),
+    props,
+  );
+}
+
+export const defineCustomObjectCategory = defineCategory;
+
+export const categoryComponent = defineComponent({
+  type: 'CUSTOM_CATEGORY',
+  define: defineCategory,
+  serialize: (definition) => ({
+    type: 'CUSTOM_CATEGORY',
+    api_name: definition.apiName,
+    name: definition.displayName,
+    description: definition.description ?? '',
+  }),
+});

package/src/lib/manifest/definitions/component.ts

@@ -0,0 +1,241 @@
+import type { ManifestComponentType, ManifestScope, ManifestComponent } from '../manifest-builder';
+
+export type ComponentType = ManifestComponentType | 'CUSTOM_OBJECT_SETTINGS' | 'CUSTOM_OBJECT_SEARCH_CONFIG';
+
+/** New definitions compose explicitly; legacy constructors still register through their original scopes. */
+export const detachedManifestScope: ManifestScope = { _register() {} };
+
+/** Shared by components whose backend writers require the custom API-name suffix. */
+export function validateCustomApiName(apiName: string): void {
+  if (typeof apiName !== 'string' || !apiName.endsWith('__c'))
+    throw new Error(`apiName must end with __c: ${apiName}`);
+}
+
+/** Decorate only a newly created instance; the existing class and serializer stay unchanged. */
+export function withApiName<D extends ManifestComponent>(
+  definition: D,
+  apiName: string,
+  extra: Record<string, unknown> = {},
+) {
+  const serialize = definition.toDict.bind(definition);
+  return Object.assign(definition, {
+    getApiName: () => apiName,
+    toDict: () => ({ ...serialize(), ...extra, api_name: apiName, identity_format_version: 2 as const }),
+  });
+}
+
+/** Identifying fields belong to the component's serialized metadata. */
+export type MetadataConfig =
+  | {
+      readonly type: Exclude<
+        ComponentType,
+        | 'CUSTOM_OBJECT_FIELD'
+        | 'CUSTOM_OBJECT_FIELD_SECTION'
+        | 'CUSTOM_OBJECT_ACTION'
+        | 'CUSTOM_OBJECT_LIST_VIEW'
+        | 'CUSTOM_OBJECT_PAGE_LAYOUT'
+        | 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'
+        | 'CUSTOM_OBJECT_VALIDATION_RULE'
+        | 'CUSTOM_FIELD_SECTION'
+        | 'CUSTOM_FIELD_V2'
+        | 'CUSTOM_OBJECT_SETTINGS'
+        | 'CUSTOM_OBJECT_SEARCH_CONFIG'
+      >;
+      readonly api_name: string;
+    }
+  | {
+      readonly type: 'CUSTOM_OBJECT_FIELD';
+      readonly custom_object_api_name: string;
+      readonly field_api_name: string;
+    }
+  | {
+      readonly type: 'CUSTOM_OBJECT_FIELD_SECTION';
+      readonly api_name: string;
+      readonly model_name: string;
+    }
+  | {
+      readonly type: 'CUSTOM_OBJECT_ACTION' | 'CUSTOM_OBJECT_LIST_VIEW' | 'CUSTOM_OBJECT_PAGE_LAYOUT';
+      readonly api_name: string;
+      readonly object_rql_name: string;
+    }
+  | {
+      readonly type:
+        | 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'
+        | 'CUSTOM_OBJECT_VALIDATION_RULE'
+        | 'CUSTOM_FIELD_SECTION'
+        | 'CUSTOM_FIELD_V2';
+      readonly api_name: string;
+      readonly model_rql_name: string;
+    }
+  | { readonly type: 'CUSTOM_OBJECT_SETTINGS'; readonly object_rql_name: string; readonly setting_id: string }
+  | { readonly type: 'CUSTOM_OBJECT_SEARCH_CONFIG'; readonly model_rql_name: string };
+
+export interface BuildContext {
+  bundle(entrypoint: URL): Promise<string>;
+}
+
+export interface MetadataEntry<W extends MetadataConfig = MetadataConfig> {
+  readonly config: W;
+  /** Generated defaults yield to authored metadata with the same type, parent, and API name. */
+  readonly fallback?: boolean;
+  readonly buildKey?: string;
+  readonly build?: (context: BuildContext) => Promise<W>;
+}
+
+export interface CompileContext {
+  readonly definitions: readonly object[];
+}
+
+type DefinitionFactory = (...args: never[]) => object;
+
+interface ComponentFactory<F extends DefinitionFactory> {
+  /** Wire kind used to register this adapter; does not register an API endpoint. */
+  readonly type: ComponentType;
+  /** Creates the public definition. The wrapper registers the result without adding public properties. */
+  readonly define: F;
+  /**
+   * Receives the factory result and its original arguments. Return fixed references
+   * or a callback that reads current dependencies when setters can change them.
+   */
+  references?(
+    definition: ReturnType<F>,
+    ...args: Parameters<F>
+  ): readonly object[] | (() => readonly object[]);
+}
+
+/** Use a single-definition serializer normally; batch compilers handle schema expansion and merging. */
+export type ComponentImplementation<
+  F extends DefinitionFactory,
+  W extends MetadataConfig,
+> = ComponentFactory<F> &
+  (
+    | {
+        serialize(definition: ReturnType<F>): W | MetadataEntry<W>;
+        compileBatch?: never;
+      }
+    | {
+        serialize?: never;
+        compileBatch(
+          definitions: readonly ReturnType<F>[],
+          context: CompileContext,
+        ): readonly (W | MetadataEntry<W>)[];
+      }
+    | (ReturnType<F> extends ManifestComponent ? { serialize?: never; compileBatch?: never } : never)
+  );
+
+/** Keep public declarations compact without expanding generic factories into their field unions. */
+export interface ComponentDefinition<F extends DefinitionFactory> {
+  readonly define: F;
+  /** @internal Register a constructed value, preserving its concrete generic type. */
+  register<D extends object>(definition: D, ...args: unknown[]): D;
+}
+
+interface RegisteredComponent {
+  readonly type: ComponentType;
+  references(): readonly object[];
+  readonly implementation: {
+    readonly batchKey: object;
+    compileBatch(
+      definitions: readonly object[],
+      context: CompileContext,
+    ): readonly (MetadataConfig | MetadataEntry)[];
+  };
+}
+
+// Shared across SDK copies, and works for frozen schema definitions without mutating them.
+const registryKey = Symbol.for('@rippling/sdk/component-registry/v3');
+const shared = globalThis as typeof globalThis & { [registryKey]?: WeakMap<object, RegisteredComponent> };
+const registry = (shared[registryKey] ??= new WeakMap());
+
+export function registeredComponent(definition: object): RegisteredComponent | undefined {
+  return registry.get(definition);
+}
+
+/** Retains the exact factory signature, including its generic type parameters. */
+export function defineComponent<F extends DefinitionFactory, W extends MetadataConfig = MetadataConfig>(
+  implementation: ComponentImplementation<F, W>,
+): ComponentDefinition<F> {
+  const adapter = {
+    batchKey: implementation.compileBatch ?? implementation,
+    compileBatch(
+      definitions: readonly object[],
+      context: CompileContext,
+    ): readonly (MetadataConfig | MetadataEntry)[] {
+      // Type erasure is confined to registry dispatch; authoring and each implementation stay typed.
+      const typed = definitions as ReturnType<F>[];
+      if (implementation.compileBatch != null) return implementation.compileBatch(typed, context);
+      return typed.map((definition) =>
+        implementation.serialize != null ?
+          implementation.serialize(definition)
+        : ((definition as ManifestComponent).toDict() as W),
+      );
+    },
+  };
+  const register = <D extends object>(definition: D, ...args: unknown[]): D => {
+    const references =
+      implementation.references?.(definition as ReturnType<F>, ...(args as Parameters<F>)) ?? [];
+    const snapshot = typeof references === 'function' ? references : Object.freeze([...references]);
+    registry.set(definition, {
+      type: implementation.type,
+      references: typeof snapshot === 'function' ? snapshot : () => snapshot,
+      implementation: adapter,
+    });
+    return definition;
+  };
+  const define = new Proxy(implementation.define, {
+    apply(target, receiver, args) {
+      return register(Reflect.apply(target, receiver, args) as ReturnType<F>, ...(args as Parameters<F>));
+    },
+  });
+  return { define, register };
+}
+
+/** Mirror backend identity and installation-map scopes, using wire fields rather than source IDs. */
+export function entryKey({ config }: MetadataEntry): string {
+  switch (config.type) {
+    case 'CUSTOM_OBJECT_FIELD':
+      return JSON.stringify([config.type, config.custom_object_api_name, config.field_api_name]);
+    case 'CUSTOM_OBJECT_FIELD_SECTION':
+    case 'CUSTOM_OBJECT_ACTION':
+    case 'CUSTOM_OBJECT_LIST_VIEW':
+    case 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW':
+    case 'CUSTOM_OBJECT_VALIDATION_RULE':
+      // These components still use company-wide API-name lookups or installation maps.
+      return JSON.stringify([config.type, config.api_name]);
+    case 'CUSTOM_OBJECT_PAGE_LAYOUT':
+      return JSON.stringify([config.type, config.object_rql_name, config.api_name]);
+    case 'CUSTOM_FIELD_SECTION':
+    case 'CUSTOM_FIELD_V2':
+      return JSON.stringify([config.type, config.model_rql_name, config.api_name]);
+    case 'CUSTOM_OBJECT_SETTINGS':
+      return JSON.stringify([config.type, config.object_rql_name]);
+    case 'CUSTOM_OBJECT_SEARCH_CONFIG':
+      return JSON.stringify([config.type, config.model_rql_name]);
+    default:
+      return JSON.stringify([config.type, config.api_name]);
+  }
+}
+
+/** Deferred builds must retain the same detached configuration snapshot as manifest composition. */
+function snapshotMetadata<W extends MetadataConfig>(config: W): W {
+  return JSON.parse(JSON.stringify(config)) as W;
+}
+
+/** Shared source-build plumbing; each component supplies its own wire format. */
+export function sourceEntry<W extends MetadataConfig>(
+  metadata: W,
+  source: URL | undefined,
+  build: (config: W, content: string) => W,
+): MetadataEntry<W> {
+  const config = snapshotMetadata(metadata);
+  const href = source?.href;
+  return {
+    config,
+    ...(href === undefined ?
+      {}
+    : {
+        buildKey: href,
+        build: async ({ bundle }: BuildContext) => build(config, await bundle(new URL(href))),
+      }),
+  };
+}