@datadog/apps-frontend 0.0.1 → 0.0.3

package/dist/src/embedding/react/provider.d.ts

@@ -0,0 +1,8 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { ComponentType, PropsWithChildren } from 'react';
+/** Owns the shared embedding connection for all descendant Datadog App hooks. */
+export declare const DatadogAppProvider: ComponentType<PropsWithChildren>;

package/dist/src/embedding/react/use-datadog-app-embedding.d.ts

@@ -0,0 +1,29 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { EmbeddingMetadata } from '../index.js';
+export interface UseDatadogAppEmbeddingOptions {
+    /**
+     * Suspend (throw a promise) while the connection is still settling
+     * (`connecting`/`reconnecting`), and throw an `Error` for a terminal
+     * failure (`rejected`/`closed`) so the nearest error boundary catches it.
+     * Only `connected`/`not-embedded` -- both legitimate states to render
+     * against -- are ever returned. Defaults to `false`.
+     */
+    readonly suspense?: boolean;
+}
+type SettledEmbeddingMetadata = Extract<EmbeddingMetadata, {
+    state: 'connected' | 'not-embedded';
+}>;
+/**
+ * Tracks this app's embedding connection: its lifecycle state, any connection
+ * error, and which product surface the host embedded it into. Must be called
+ * below `DatadogAppProvider`.
+ */
+export declare function useDatadogAppEmbedding(options: Readonly<{
+    suspense: true;
+}>): SettledEmbeddingMetadata;
+export declare function useDatadogAppEmbedding(options?: UseDatadogAppEmbeddingOptions): EmbeddingMetadata;
+export {};

package/dist/src/embedding/types.d.ts

@@ -0,0 +1,392 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export type Unsubscribe = () => void;
+export type Result<TValue, TError> = Readonly<{
+    ok: true;
+    value: TValue;
+}> | Readonly<{
+    ok: false;
+    error: TError;
+}>;
+/**
+ * A synchronous, deterministic, validation-only Standard Schema.
+ *
+ * Both embedding peers validate independently. Schemas must therefore have
+ * identical input/output types and must not coerce or transform accepted
+ * values.
+ */
+export type ValueSchema<TValue> = StandardSchemaV1<TValue, TValue>;
+export type AnySchema = StandardSchemaV1;
+export type InferOf<TSchema extends AnySchema> = StandardSchemaV1.InferOutput<TSchema>;
+export type ValidationOnlySchema<TSchema extends AnySchema> = StandardSchemaV1.InferInput<TSchema> extends StandardSchemaV1.InferOutput<TSchema> ? StandardSchemaV1.InferOutput<TSchema> extends StandardSchemaV1.InferInput<TSchema> ? TSchema : never : never;
+export type ContractVersion = number;
+export interface ValueField<TSchema extends AnySchema> {
+    readonly kind: 'value';
+    readonly schema: ValidationOnlySchema<TSchema>;
+}
+export interface FunctionField<TInputs extends Readonly<Record<string, AnySchema>>, TResult extends AnySchema> {
+    readonly kind: 'function';
+    readonly inputs: {
+        readonly [TName in keyof TInputs]: ValidationOnlySchema<TInputs[TName]>;
+    };
+    readonly result: ValidationOnlySchema<TResult>;
+    /**
+     * How long this function may run before it times out, overriding the
+     * default `FUNCTION_CALL_TIMEOUT_MS`. A fast lookup can ask for seconds
+     * instead of inheriting a ten-minute budget.
+     *
+     * Never sent over the wire. The app arms its wait from the contract it
+     * claims and the host arms its watchdog from the contract it registers, so
+     * two peers on different contract revisions may use different numbers.
+     * That needs no reconciling: whichever watchdog fires first wins through
+     * the normal `TIMED_OUT` path, as it already did with the default alone.
+     *
+     * Must be positive and no larger than `MAX_TIMER_DELAY_MS`. Outside that
+     * range no call could ever meet it -- at `0` the host's deadline checks are
+     * already past, and beyond the timer ceiling `setTimeout` overflows and
+     * fires almost at once -- so `defineContract()` rejects it outright.
+     */
+    readonly timeoutMs?: number;
+}
+export type AnyFunctionField = FunctionField<Readonly<Record<string, AnySchema>>, AnySchema>;
+export type AnyField = ValueField<AnySchema> | AnyFunctionField;
+export interface Contract<TFields extends Record<string, AnyField>> {
+    readonly identifier: string;
+    readonly version: ContractVersion;
+    readonly fields: TFields;
+}
+export type AnyContract = Contract<Record<string, AnyField>>;
+export interface LiveValue<TValue> {
+    get(): TValue;
+    subscribe(onChange: () => void): Unsubscribe;
+}
+export interface HostFunctionContext {
+    /**
+     * Aborts once the call is cancelled or its deadline passes. An async
+     * implementation should check or listen for this to stop early. A
+     * *synchronous* implementation has no way to observe it mid-call: JS
+     * can't preempt a running function, so a synchronous handler that blocks
+     * past the deadline still runs to completion and produces its value --
+     * the caller is simply told the call timed out and never sees that
+     * value, rather than the value being prevented from being computed.
+     */
+    readonly signal: AbortSignal;
+}
+export interface HostFunction {
+    invoke(inputs: Readonly<Record<string, unknown>>, context: HostFunctionContext): unknown;
+}
+export type FunctionInputs<TInputs extends Readonly<Record<string, AnySchema>>> = {
+    readonly [TName in keyof TInputs as undefined extends InferOf<TInputs[TName]> ? TName : never]?: InferOf<TInputs[TName]>;
+} & {
+    readonly [TName in keyof TInputs as undefined extends InferOf<TInputs[TName]> ? never : TName]: InferOf<TInputs[TName]>;
+};
+/** Resolves a contract field to the plain value/callable shape a claimant receives, ignoring subscription. */
+type FieldValue<TField extends AnyField> = TField extends ValueField<infer TSchema> ? InferOf<TSchema> : TField extends FunctionField<infer TInputs, infer TResult> ? (inputs: FunctionInputs<TInputs>) => Promise<InferOf<TResult>> : never;
+type ClaimedField<TField extends AnyField> = TField extends ValueField<infer TSchema> ? LiveValue<InferOf<TSchema>> : FieldValue<TField>;
+/** The live, per-field view of a claim: subscribable `LiveValue`s for value fields, callables for function fields. */
+export type ClaimedFields<TContract extends AnyContract> = {
+    readonly [TKey in keyof TContract['fields']]: ClaimedField<TContract['fields'][TKey]>;
+};
+declare const hostModuleBrand: unique symbol;
+/**
+ * One contract version, live and ready to serve claims. Nominally branded --
+ * `hostModuleBrand` is declared but never exported, so only this package can
+ * produce a `HostModule`, and only through `createHostModule()`. That is what
+ * keeps a host from assembling a module for one hand-picked version: the
+ * single supported way in is to provide an inputs definition, which mints a
+ * module for *every* version that definition still converts to. The brand has
+ * no runtime representation.
+ */
+export interface HostModule {
+    readonly [hostModuleBrand]: true;
+    readonly contract: AnyContract;
+    readonly implementation: Readonly<Record<string, LiveValue<unknown> | HostFunction>>;
+    readonly signal?: AbortSignal;
+}
+export interface Issue {
+    readonly message: string;
+    readonly path: readonly (string | number)[];
+}
+export type AnyError = Readonly<{
+    code: 'ORIGIN_REJECTED';
+    origin: string;
+}> | Readonly<{
+    code: 'APP_PROTOCOL_TOO_OLD';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'HOST_PROTOCOL_TOO_OLD';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'PROTOCOL_INCOMPATIBLE';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'PEER_LACKS_MODULE';
+    identifier: string;
+}> | Readonly<{
+    code: 'APP_MAJOR_TOO_OLD';
+    wanted: ContractVersion;
+    hostVersions: readonly ContractVersion[];
+}> | Readonly<{
+    code: 'HOST_MAJOR_TOO_OLD';
+    wanted: ContractVersion;
+    hostVersions: readonly ContractVersion[];
+}> | Readonly<{
+    code: 'CONTRACT_INCOMPATIBLE';
+    field: string;
+}> | Readonly<{
+    code: 'INVALID_ARGUMENT';
+    issues: readonly Issue[];
+}> | Readonly<{
+    code: 'FUNCTION_FAILED';
+    field: string;
+}> | Readonly<{
+    code: 'INVALID_RESULT';
+    issues: readonly Issue[];
+}> | Readonly<{
+    code: 'TIMED_OUT';
+    timeoutMs: number;
+}> | Readonly<{
+    code: 'TRANSPORT_FAILED';
+    cause: unknown;
+}> | Readonly<{
+    code: 'ABORTED';
+}> | Readonly<{
+    code: 'DISCONNECTED';
+}> | Readonly<{
+    code: 'UNRECOGNIZED';
+    rawCode: string;
+    raw: unknown;
+}>;
+export type ErrorOf<TCode extends AnyError['code']> = Extract<AnyError, {
+    code: TCode;
+}>;
+export type ConnectError = ErrorOf<'ORIGIN_REJECTED' | 'APP_PROTOCOL_TOO_OLD' | 'HOST_PROTOCOL_TOO_OLD' | 'PROTOCOL_INCOMPATIBLE' | 'TIMED_OUT' | 'TRANSPORT_FAILED' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type WireClaimError = ErrorOf<'PEER_LACKS_MODULE' | 'APP_MAJOR_TOO_OLD' | 'HOST_MAJOR_TOO_OLD' | 'CONTRACT_INCOMPATIBLE' | 'INVALID_RESULT' | 'TIMED_OUT' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type WireFunctionError = ErrorOf<'CONTRACT_INCOMPATIBLE' | 'INVALID_ARGUMENT' | 'FUNCTION_FAILED' | 'INVALID_RESULT' | 'TIMED_OUT' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type ClaimInvalidationError = ErrorOf<'INVALID_RESULT' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export interface Claimed<TContract extends AnyContract> {
+    readonly fields: ClaimedFields<TContract>;
+    release(): void;
+    onValuesChanged(listener: () => void): Unsubscribe;
+    onInvalidated(listener: (error: ClaimInvalidationError) => void): Unsubscribe;
+}
+export interface ClaimOptions {
+    /**
+     * Local claim deadline. Must be finite, non-negative, and no larger than
+     * the platform timer ceiling (`2_147_483_647`).
+     */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AppConnection {
+    claim<TContract extends AnyContract>(contract: TContract, options?: ClaimOptions): Promise<Result<Claimed<TContract>, WireClaimError>>;
+}
+/**
+ * Identifies which product surface a Datadog App is embedded into (e.g. the
+ * Service Catalog side panel vs. IDP), so an app can render surface-specific
+ * content. Each value matches the `identifier` of the inputs schema that
+ * surface provides -- see `../inputs/schemas`. Sent host-to-app as part of
+ * the embedding connection handshake.
+ */
+/**
+ * Every surface, as a tuple rather than a bare union so it can also serve as a
+ * type: `DatadogAppInputsSchema` defaults its `surfaces` to this, which makes
+ * an IDE print the members in full on hover instead of collapsing them to the
+ * `SurfaceId` alias.
+ */
+export declare const EVERY_SURFACE: readonly [
+    'datadog.idp.homepage',
+    'datadog.idp.service-panel',
+    'datadog.idp.self-service',
+    'datadog.app-builder',
+    'datadog.appsec',
+    'datadog.notebook',
+    'datadog.dashboard'
+];
+/**
+ * Where an app is running. Derived from `EVERY_SURFACE`, so there is one
+ * list, but widened to arbitrary strings: it is inert metadata forwarded to
+ * `listen()`, never used to gate whether embedding connects, so a host is
+ * free to pass a value with no matching surface (e.g. an unmapped view
+ * context) rather than going without one.
+ */
+export type SurfaceId = (typeof EVERY_SURFACE)[number] | (string & {});
+export type AppConnectionState = Readonly<{
+    state: 'connecting';
+    error?: ConnectError;
+}> | Readonly<{
+    state: 'connected';
+    connection: AppConnection;
+    surfaceId?: SurfaceId;
+}> | Readonly<{
+    state: 'reconnecting';
+    lastError: ConnectError;
+}> | Readonly<{
+    state: 'rejected';
+    error: ConnectError;
+}> | Readonly<{
+    state: 'not-embedded';
+}> | Readonly<{
+    state: 'closed';
+}>;
+/**
+ * Public-safe view of `AppConnectionState`: the same lifecycle cases, minus
+ * the raw `AppConnection` a consumer would otherwise have no use for outside
+ * of claiming a contract.
+ */
+export type EmbeddingMetadata = Readonly<{
+    state: 'connecting';
+    error?: ConnectError;
+}> | Readonly<{
+    state: 'connected';
+    surfaceId?: SurfaceId;
+}> | Readonly<{
+    state: 'reconnecting';
+    lastError: ConnectError;
+}> | Readonly<{
+    state: 'rejected';
+    error: ConnectError;
+}> | Readonly<{
+    state: 'not-embedded';
+}> | Readonly<{
+    state: 'closed';
+}>;
+export interface EmbeddingMetadataStore {
+    readonly getSnapshot: () => EmbeddingMetadata;
+    readonly subscribe: (onChange: () => void) => Unsubscribe;
+}
+export interface AppConnectionHandle {
+    getSnapshot(): AppConnectionState;
+    subscribe(onChange: () => void): Unsubscribe;
+    close(): void;
+}
+export interface AppConnectionFactory {
+    connect(): AppConnectionHandle;
+}
+export interface HostListenOptions {
+    /** Security boundary for the app-created bootstrap port. */
+    readonly peer: Readonly<{
+        frame: HTMLIFrameElement;
+        appOrigin: string;
+        /**
+         * Set when the iframe is intentionally configured with an opaque
+         * sandboxed origin, so the host should accept a `"null"` origin from
+         * it in place of an exact match against `appOrigin`.
+         */
+        allowOpaqueOrigin?: boolean;
+    }>;
+    readonly modules: readonly HostModule[];
+    readonly surfaceId?: SurfaceId;
+    /**
+     * Local compatibility and establishment deadline for each phase. Must be
+     * finite, non-negative, and no larger than the platform timer ceiling
+     * (`2_147_483_647`).
+     */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface HostListener {
+    onError(listener: (error: ConnectError) => void): Unsubscribe;
+    /**
+     * Fires exactly once per successful operational session: after permanent
+     * bootstrap and compatibility negotiation complete, before any
+     * per-module claim resolves. Not a one-shot for the listener's whole
+     * lifetime -- if this session is later superseded (a new bootstrap
+     * replaces it, see `close()`'s effect on an active connection) and a new
+     * session establishes, this fires again for that new session. Never
+     * fires for an attempt that fails, or after `close()`. A subscriber that
+     * calls `onReady` while a session is already active is notified
+     * immediately upon subscribing, so a late subscriber cannot miss an
+     * already-established session.
+     */
+    onReady(listener: () => void): Unsubscribe;
+    close(): void;
+}
+export type EmbeddingError = Readonly<{
+    code: 'TIMED_OUT';
+    message: string;
+    action: 'retry';
+}> | Readonly<{
+    code: 'ORIGIN_REJECTED';
+    message: string;
+    action: 'contact-support';
+}> | Readonly<{
+    code: 'APP_PROTOCOL_TOO_OLD';
+    message: string;
+    action: 'update-app';
+}> | Readonly<{
+    code: 'HOST_PROTOCOL_TOO_OLD' | 'PROTOCOL_INCOMPATIBLE';
+    message: string;
+    action: 'contact-support';
+}> | Readonly<{
+    code: 'CONNECTION_LOST';
+    message: string;
+    action: 'retry';
+}> | Readonly<{
+    code: 'UNKNOWN';
+    message: string;
+    action: 'contact-support';
+}>;
+export type ClaimError = EmbeddingError | Readonly<{
+    code: 'APP_MAJOR_TOO_OLD';
+    action: 'update-app';
+    requestedVersion: ContractVersion;
+    availableVersions: readonly ContractVersion[];
+    message: string;
+}> | Readonly<{
+    code: 'HOST_MAJOR_TOO_OLD';
+    action: 'contact-support';
+    requestedVersion: ContractVersion;
+    availableVersions: readonly ContractVersion[];
+    message: string;
+}>;
+export type ClaimedValues<TContract extends AnyContract> = Readonly<{
+    [TKey in keyof TContract['fields']]: FieldValue<TContract['fields'][TKey]>;
+}>;
+export type ClaimState<TContract extends AnyContract> = Readonly<{
+    status: 'pending';
+}> | Readonly<{
+    status: 'ready';
+    fields: ClaimedValues<TContract>;
+}> | Readonly<{
+    status: 'unavailable';
+}> | Readonly<{
+    status: 'failed';
+    error: ClaimError;
+}>;
+export interface ClaimStore<TContract extends AnyContract> {
+    readonly getSnapshot: () => ClaimState<TContract>;
+    readonly subscribe: (onChange: () => void) => Unsubscribe;
+}
+/** Framework-neutral claim capability consumed by feature modules. */
+export interface AppClaims {
+    getClaim<TContract extends AnyContract>(contract: TContract): ClaimStore<TContract>;
+}
+/** Owns the lifecycle of one concrete embedding implementation. */
+export interface AppEmbedding extends AppClaims {
+    start(): Unsubscribe;
+    getEmbeddingMetadata(): EmbeddingMetadataStore;
+}
+/**
+ * One established connection, owned by the caller that opened it. These say
+ * nothing about which operational protocol produced them, so the connection
+ * lifecycle does not change when a protocol is added or retired.
+ */
+export type ManagedAppConnection = Readonly<{
+    connection: AppConnection;
+    surfaceId?: SurfaceId;
+    closeSignal: AbortSignal;
+    close(): void;
+}>;
+export type ManagedHostConnection = Readonly<{
+    closeSignal: AbortSignal;
+    close(): void;
+}>;
+export {};

package/dist/src/embedding/versioning.d.ts

@@ -0,0 +1,104 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { AnyContract, AnyField, FunctionField, FunctionInputs, HostFunctionContext, HostModule, InferOf, LiveValue, ValueField } from './types.js';
+type HostFieldImplementation<TField extends AnyField> = TField extends ValueField<infer TSchema> ? LiveValue<InferOf<TSchema>> : TField extends FunctionField<infer TInputs, infer TResult> ? (inputs: FunctionInputs<TInputs>, context: HostFunctionContext) => InferOf<TResult> | Promise<InferOf<TResult>> : never;
+/** The live host-side implementation of a raw field map: `LiveValue`s for value fields, plain callables for function fields. */
+export type HostFieldsFor<TFields extends Record<string, AnyField>> = Readonly<{
+    [TName in keyof TFields]: HostFieldImplementation<TFields[TName]>;
+}>;
+/** The live host-side implementation of a whole contract's fields. */
+export type HostFields<TContract extends AnyContract> = HostFieldsFor<TContract['fields']>;
+/**
+ * A `LiveValue` that recomputes from `sources` on every `get()` rather than
+ * caching, so it always reflects whichever of `sources` last changed without
+ * needing its own dedupe or disposal bookkeeping -- that already lives on
+ * `sources` themselves.
+ */
+export declare function deriveLiveValue<TValue>(sources: readonly LiveValue<unknown>[], compute: () => TValue): LiveValue<TValue>;
+/**
+ * One older version of `TLatest`: its own frozen contract, the extra live
+ * inputs its `convert` needs beyond what `TLatest` already carries, and the
+ * function that derives its fields from `TLatest` plus those extras. Runs
+ * once, at `buildModules()` time, and must return live fields -- typically
+ * built with `deriveLiveValue()` -- so the older version stays exactly as
+ * reactive as `TLatest`, with `TLatest`'s own implementation untouched.
+ */
+export interface OlderContractVersion<TLatest extends AnyContract, TOlder extends AnyContract, TExtraInputs extends Record<string, AnyField>> {
+    readonly contract: TOlder;
+    readonly extraInputs: TExtraInputs;
+    convert(latest: HostFields<TLatest>, extra: HostFieldsFor<TExtraInputs>): HostFields<TOlder>;
+}
+export type AnyOlderContractVersion<TLatest extends AnyContract> = OlderContractVersion<TLatest, AnyContract, Record<string, AnyField>>;
+/**
+ * Declares and validates one `OlderContractVersion`. Takes `latest` as its
+ * own argument -- rather than only through `definition.convert`'s parameter
+ * type -- so `TLatest` can be inferred directly from a value in covariant
+ * position; inference can't otherwise recover it from `convert`'s parameter,
+ * a contravariant position, and silently falls back to `AnyContract`.
+ */
+export declare function olderVersion<TLatest extends AnyContract, TOlder extends AnyContract, const TExtraInputs extends Record<string, AnyField>>(_latest: TLatest, definition: OlderContractVersion<TLatest, TOlder, TExtraInputs>): OlderContractVersion<TLatest, TOlder, TExtraInputs>;
+export interface VersionedContract<TLatest extends AnyContract, TOlderVersions extends readonly AnyOlderContractVersion<TLatest>[]> {
+    readonly identifier: TLatest['identifier'];
+    /**
+     * The version an up-to-date peer claims. Read by the claiming side to
+     * know what it is asking for; never a way to *provide* one version alone,
+     * since `buildModules()` is all-or-nothing.
+     */
+    readonly latest: TLatest;
+    readonly olderVersions: TOlderVersions;
+    /**
+     * `X`: every field needed to serve every version, in one flat namespace.
+     * A provider populates exactly this and learns nothing about how many
+     * versions sit behind it.
+     */
+    readonly fields: VersionedContractFields<TLatest, TOlderVersions>;
+    /**
+     * Mints one live module per version -- latest plus every version that
+     * still has a converter -- from one flat field record. There is
+     * deliberately no way to ask for a subset: supporting a version and
+     * serving it are the same act.
+     */
+    buildModules(fields: HostFieldsFor<VersionedContractFields<TLatest, TOlderVersions>>, signal?: AbortSignal): readonly HostModule[];
+}
+/**
+ * Structural bound for "some versioned contract", used where generic code
+ * needs to accept any of them. Deliberately forgetful about `buildModules`'s
+ * parameter and about `olderVersions`' element type: both are contravariant,
+ * so naming them would make every concrete contract fail to satisfy this.
+ * Callers recover the precise field types from the generic parameter itself
+ * (see `DatadogAppInputImplementations`), not from this bound.
+ */
+export type AnyVersionedContract = Readonly<{
+    identifier: string;
+    latest: AnyContract;
+    olderVersions: readonly unknown[];
+    fields: Readonly<Record<string, AnyField>>;
+    buildModules: (fields: never, signal?: AbortSignal) => readonly HostModule[];
+}>;
+export type UnionToIntersection<TUnion> = (TUnion extends unknown ? (key: TUnion) => void : never) extends (key: infer TIntersection) => void ? TIntersection : never;
+type OlderVersionsExtraFieldsUnion<TLatest extends AnyContract, TOlderVersions extends readonly AnyOlderContractVersion<TLatest>[]> = {
+    [TIndex in keyof TOlderVersions]: TOlderVersions[TIndex] extends OlderContractVersion<TLatest, AnyContract, infer TExtraInputs> ? TExtraInputs : never;
+}[number];
+/**
+ * Every field needed to construct every version this contract declares,
+ * flattened into one namespace: `latest`'s own fields plus each older
+ * version's `extraInputs`. This is `giving` values' whole contract with
+ * versioning -- a caller populates this one flat record with no notion that
+ * more than one version exists behind it. Field names must therefore be
+ * unique across `latest` and every older version's `extraInputs`; two older
+ * versions may reuse the same name only when it means the same schema, since
+ * flattening gives it exactly one slot.
+ */
+export type VersionedContractFields<TLatest extends AnyContract, TOlderVersions extends readonly AnyOlderContractVersion<TLatest>[]> = OlderVersionsExtraFieldsUnion<TLatest, TOlderVersions> extends never ? TLatest['fields'] : TLatest['fields'] & UnionToIntersection<OlderVersionsExtraFieldsUnion<TLatest, TOlderVersions>>;
+/**
+ * Ties a latest contract to any number of older versions it stays willing to
+ * serve. `buildModules()` derives each older version's fields from the
+ * latest implementation plus that version's own extra inputs and returns one
+ * independent, fully live `HostModule` per version -- ready to hand to a
+ * host listener alongside modules for any other contract.
+ */
+export declare function defineVersionedContract<TLatest extends AnyContract, const TOlderVersions extends readonly AnyOlderContractVersion<TLatest>[]>(latest: TLatest, ...olderVersions: TOlderVersions): VersionedContract<TLatest, TOlderVersions>;
+export {};