@adhd/apigen-core-client 0.1.0

package/lib/plugin.d.ts

@@ -0,0 +1,446 @@
+import { PluginLanguage } from './types';
+import { Operation, JSONSchema } from './descriptor';
+
+/**
+ * The four canonical transport carriers apigen knows about (SPEC §5/§7/§9.1).
+ *
+ * A `MountedOperation` may opt in to a subset — `transports` omitted → all.
+ */
+export type Transport = 'http' | 'grpc' | 'mcp' | 'cli';
+/**
+ * A type-keyed, mutable-during-compose map threaded through every Layer and
+ * into the dispatch function as `ctx` (SPEC §8.1).
+ *
+ * Layers insert typed values with a class or symbol key and downstream layers /
+ * the function implementation read them back — the same mental model as
+ * `http::Extensions` (Rust) and `AsyncLocalStorage` (Node).
+ *
+ * @example
+ * ```ts
+ * // insert (in a Layer):
+ * call.ctx.set(Logger, new Logger({ level: 'info' }))
+ * // read (in a Layer or dispatch):
+ * const log = call.ctx.get(Logger)
+ * ```
+ */
+export interface Extensions {
+    /**
+     * Retrieve the value stored under the given class constructor or symbol key.
+     * Returns `undefined` when the key has not been set.
+     */
+    get<T>(key: abstract new (...args: never[]) => T): T | undefined;
+    /**
+     * Store a value under the given class constructor or symbol key.
+     * Overwrites any existing value for that key.
+     */
+    set<T>(key: abstract new (...args: never[]) => T, value: T): void;
+}
+/**
+ * The inbound call descriptor passed to every layer and ultimately to dispatch
+ * (SPEC §7.1 / §8.1).
+ *
+ * `data` contains the bare domain params (envelope dissolved); `envelope`
+ * contains transport-native side-channel fields (session, auth tokens, …).
+ * `raw` is an escape hatch for transport-specific adapters that need access to
+ * the native request object — ordinary plugins should never need it.
+ */
+export interface Call {
+    /** The operation being invoked (from the merged canonical descriptor). */
+    operation: Operation;
+    /** Bare domain params (the `data`-wrapper is dissolved; ctx excluded). */
+    data: Record<string, unknown>;
+    /**
+     * Side-channel metadata from the transport-native carrier, keyed as
+     * `x-<pluginId>-<field>` (SPEC §9 / §9.1).
+     */
+    envelope: Record<string, unknown>;
+    /**
+     * Typed request-extensions map — threaded `mw → mw → fn` (SPEC §8.1).
+     * Layers insert context values; downstream layers and the domain function
+     * read them back.
+     */
+    ctx: Extensions;
+    /** Which transport delivered this call. */
+    transport: Transport;
+    /**
+     * Cancellation signal — wired to the transport's native cancellation
+     * mechanism (HTTP abort, gRPC cancel, MCP cancel, Ctrl-C for CLI).
+     * Layers must propagate it to any async work they initiate (SPEC §11).
+     */
+    signal: AbortSignal;
+    /**
+     * Transport-native request object — escape hatch for adapters that need
+     * raw access to e.g. a Fastify `Request` or an MCP `CallToolRequest`.
+     * Ordinary plugins must NOT depend on this; it degrades portability.
+     */
+    raw?: unknown;
+}
+/**
+ * A single chunk emitted by a streaming operation (SPEC §11).
+ *
+ * The type is intentionally open (`unknown`) because the per-chunk element
+ * type is described by `operation.output` (JSON Schema) — static typing is
+ * achieved per-plugin via generics when the element type is known.
+ */
+export type Chunk = unknown;
+/**
+ * The non-streaming result of a Layer invocation — the value that flows
+ * back out to the transport adapter.
+ */
+export type Result = unknown;
+/**
+ * The continuation function passed to a Layer.
+ *
+ * Calling `next()` invokes the **remaining** layers and ultimately `dispatch`.
+ * A Layer may call it at most once per request.  Not calling it short-circuits
+ * all downstream layers and dispatch (SPEC §8.1 rule 1).
+ *
+ * The return type is a union to support both unary and streaming operations
+ * from a single `LayerCapability.layer` signature (SPEC §11).
+ */
+export type Next = () => Promise<Result> | AsyncIterable<Chunk>;
+/**
+ * A single emitted file produced by {@link TargetCapability.generate}.
+ *
+ * `content` is always a UTF-8 string — plugins emit source code, config,
+ * or structured text in any language (TS, Python, proto, YAML, …).
+ * Nothing in core restricts the language (SPEC [inv:language-agnostic-output]).
+ */
+export interface File {
+    /** Relative or absolute path where the file should be written. */
+    path: string;
+    /** UTF-8 string content to write. */
+    content: string;
+}
+/**
+ * Opaque handle returned by {@link TargetCapability.serve}.
+ *
+ * The minimal contract is `close()` for graceful shutdown.  Plugins may
+ * extend this with transport-specific members (e.g. `port`, `url`).
+ */
+export interface Server {
+    /** Gracefully shut down the server and release all resources. */
+    close(): Promise<void>;
+}
+/**
+ * The runtime harness injected into {@link TargetCapability.serve}.
+ *
+ * Provides `invoke` — the composed Layer stack that wraps `dispatch`.
+ * Transports call `harness.invoke(op, partialCall)` once per inbound request;
+ * the harness threads the active plugins' layers around the operation and
+ * returns/streams the result (SPEC §8).
+ */
+export interface Harness {
+    /**
+     * Invoke the full composed-Layer stack for `op` with the given call context.
+     * Partial — the harness fills in `operation`, `ctx`, and wires `signal`.
+     *
+     * Returns a `Promise<Result>` for unary operations or an
+     * `AsyncIterable<Chunk>` for streaming operations (SPEC §11).
+     */
+    invoke(op: Operation, call: Omit<Call, 'operation' | 'ctx'>): Promise<Result> | AsyncIterable<Chunk>;
+}
+/**
+ * The merged canonical descriptor: the full set of `Operation`s produced by
+ * merging one or more per-language extractors (SPEC §4).
+ *
+ * Plugins receive a `Descriptor` at generate/serve time; they **must not**
+ * modify it — it is the single source of truth.
+ */
+export interface Descriptor {
+    /** All extracted operations, across all host languages, in insertion order. */
+    operations: Operation[];
+    /**
+     * The host tag of the primary language runtime, e.g. `'ts'`, `'py'`.
+     * Plugins may use this to restrict generated code to the primary host.
+     */
+    host: string;
+    /**
+     * Optional namespace segment from `--namespace` or the tsconfig root folder.
+     * Typically the npm package name or a short domain slug.
+     */
+    namespace?: string;
+}
+/**
+ * **`target`** capability — project the descriptor to a transport or format
+ * (SPEC §7.1).
+ *
+ * A `TargetCapability` is selected by `--type <name>` at CLI time.  It
+ * optionally both *generates* (emits static files) and *serves* (runs a live
+ * server hosting the domain functions in-process).
+ *
+ * @typeParam Opts - Plugin-specific options, validated via `optionsSchema`.
+ *
+ * @remarks
+ * **v1 compatibility:** The v1 `OutputPlugin` interface (`generate(PluginInput)`)
+ * is the direct precursor.  v2 `TargetCapability.generate` receives a
+ * `Descriptor` instead of `PluginInput` — the richer, host-agnostic contract.
+ * v1 plugins migrate by wrapping their `PluginInput` construction in the new
+ * `generate` signature.  `serve()` is the new addition for live server targets.
+ */
+export interface TargetCapability<Opts = Record<string, unknown>> {
+    /**
+     * Short identifier for this target — the value the user passes to `--type`.
+     * Examples: `'mcp'`, `'http-fastify'`, `'http-express'`, `'cli'`, `'proto'`.
+     */
+    name: string;
+    /**
+     * Project the descriptor to a set of static files (generate mode).
+     *
+     * Called once per `apigen generate` invocation with the full merged
+     * descriptor and the resolved plugin options.  The returned `File[]` is
+     * written to the output directory by the CLI.
+     *
+     * @param descriptor - The merged canonical descriptor (read-only).
+     * @param opts       - Plugin-specific options (already validated).
+     * @returns           Array of files to emit (may be empty; never `null`).
+     */
+    generate(descriptor: Descriptor, opts: Opts): File[] | Promise<File[]>;
+    /**
+     * Start a live server hosting the domain functions in-process (run mode).
+     *
+     * Called once per `apigen run` invocation.  The transport adapter wires the
+     * harness's `invoke()` to the native request/response cycle.
+     *
+     * Optional — omit for codegen-only plugins (clients, proto, docs).
+     *
+     * @param descriptor - The merged canonical descriptor (read-only).
+     * @param harness    - The composed Layer stack; call `harness.invoke()` per request.
+     * @param opts       - Plugin-specific options (already validated).
+     * @returns           A {@link Server} handle; the CLI calls `server.close()` on SIGINT/SIGTERM.
+     */
+    serve?(descriptor: Descriptor, harness: Harness, opts: Opts): Promise<Server>;
+}
+/**
+ * **`layer`** capability — wrap operations (the onion) (SPEC §7.1 / §8 / §8.1).
+ *
+ * A `LayerCapability` is loaded via `--use <plugin>` and is composed by the
+ * harness around the `dispatch` call.  Hook sugar (`onRequest`/`onResponse`/
+ * `onError`) compiles to a `LayerCapability` — one execution model (SPEC §7.1).
+ *
+ * @remarks
+ * **Streaming:** `layer` may return an `AsyncIterable<Chunk>` — making it an
+ * `async function*` that wraps `next()` with `for await … yield` — to
+ * participate in the full per-chunk stream lifecycle (SPEC §11).
+ */
+export interface LayerCapability {
+    /**
+     * Extra envelope fields this layer needs on the request side — merged into
+     * the effective descriptor's envelope schema before serving begins.
+     *
+     * Keys are bare field names; values are JSON Schema fragments.
+     * Example: `{ session: { type: 'string', description: 'session token' } }`.
+     */
+    envelopeFields?: Record<string, JSONSchema>;
+    /**
+     * The layer function — owns the continuation.
+     *
+     * Call `next()` to invoke the remaining layers and `dispatch`.  Not calling
+     * `next()` short-circuits all downstream layers (SPEC §8.1 rule 1).
+     *
+     * For streaming operations, return an `AsyncIterable<Chunk>` wrapping the
+     * iterable returned by `next()` (SPEC §11).
+     *
+     * @param call - The inbound call descriptor.
+     * @param next - The continuation — call at most once.
+     * @returns     `Promise<Result>` for unary operations; `AsyncIterable<Chunk>`
+     *              for streaming operations.
+     */
+    layer(call: Call, next: Next): Promise<Result> | AsyncIterable<Chunk>;
+}
+/**
+ * **`mount`** capability — add synthetic operations to the descriptor
+ * (SPEC §7.1 / §7.2b / §7.2c).
+ *
+ * A `MountCapability` is loaded via `--use <plugin>` and contributes extra
+ * `Operation`-like entries (with an in-process `handler`) that flow through the
+ * harness and Layer stack exactly like extracted operations.  Typical uses:
+ * `/meta/openapi`, `/meta/health`, version endpoints.
+ */
+export interface MountCapability {
+    /**
+     * Return the set of synthetic operations this plugin contributes.
+     *
+     * `MountedOperation` extends `Operation` with an in-process `handler` and
+     * an optional `transports` filter (default: all transports).
+     *
+     * @param descriptor - The current merged descriptor (read-only).
+     * @param opts       - Plugin-specific options.
+     * @returns           Array of `MountedOperation`s; may be empty.
+     */
+    operations(descriptor: Descriptor, opts?: Record<string, unknown>): MountedOperation[];
+}
+/**
+ * A synthetic operation contributed by a {@link MountCapability}.
+ *
+ * Extends the base {@link Operation} with:
+ * - `transports` — optional filter to restrict which transports expose this
+ *   operation (default: all four, matching the host plugin's transport set).
+ * - `handler`    — the in-process function called when a request arrives.
+ *   Called with the same {@link Call} context as extracted operations; the
+ *   returned value is marshalled by the transport adapter.
+ */
+export type MountedOperation = Operation & {
+    /**
+     * Optional transport filter.  When omitted the operation is exposed on all
+     * transports supported by the active target plugin.
+     */
+    transports?: Transport[];
+    /**
+     * The in-process handler for this synthetic operation.
+     *
+     * Called with the full {@link Call} context (same as extracted operations)
+     * after the composed Layer stack has run.  The return value is serialised by
+     * the transport adapter and may be a `Promise` or an `AsyncIterable` for
+     * streaming mounts.
+     */
+    handler(call: Call): unknown | Promise<unknown> | AsyncIterable<Chunk>;
+};
+/**
+ * **`envelope`** capability — declare request/response side-channel fields
+ * (SPEC §7.1 / §9 / §9.1).
+ *
+ * A plugin with an `envelope` capability advertises the transport-agnostic
+ * side-channel fields it reads from (request) or writes to (response) without
+ * wrapping the operation in a Layer.  The harness merges these schemas into the
+ * effective descriptor's envelope before serving.
+ *
+ * Canonical field identity is `(pluginId, field)` (SPEC §9.1); fields declared
+ * here are surfaced by each transport adapter per the binding table:
+ * - HTTP/gRPC/MCP: `x-<pluginId>-<field>` header/metadata/`_meta` key
+ * - CLI: `--<pluginId>-<field>` flag + `APIGEN_<PLUGINID>_<FIELD>` env var
+ */
+export interface EnvelopeCapability {
+    /**
+     * JSON Schema fragments for fields this plugin reads from the incoming
+     * transport-native metadata (HTTP headers, gRPC metadata, MCP `_meta`,
+     * CLI flags/env).
+     *
+     * Keys are bare field names (e.g. `'session'`); the adapter prepends
+     * `x-<pluginId>-` when surfacing on k/v carriers.
+     */
+    request?: Record<string, JSONSchema>;
+    /**
+     * JSON Schema fragments for fields this plugin writes to the outgoing
+     * transport-native metadata (response headers, trailers, `_meta`, stderr).
+     *
+     * Keys follow the same `x-<pluginId>-<field>` convention as `request`.
+     */
+    response?: Record<string, JSONSchema>;
+}
+/**
+ * The v2 plugin interface (SPEC §7.1).
+ *
+ * Every apigen plugin is an object that satisfies this interface.  A plugin
+ * declares one or more **capabilities** — the harness fans them out at compose
+ * time.  All four capability slots are optional; a minimal "noop" plugin omits
+ * all of them (useful as a template).
+ *
+ * @typeParam Opts - Plugin-specific CLI options, validated against
+ *   `capabilities.target.optionsSchema` (if present) before being passed to
+ *   `generate` / `serve` / `mount.operations`.
+ *
+ * @example Logger layer (SPEC §7.2a)
+ * ```ts
+ * export default {
+ *   id: 'logger',
+ *   capabilities: {
+ *     layer: {
+ *       layer: async (call, next) => {
+ *         const t = Date.now()
+ *         console.error(`→ ${call.operation.id}`)
+ *         try { const r = await next(); console.error(`← ${call.operation.id} ${Date.now()-t}ms`); return r }
+ *         catch (e) { console.error(`✗ ${call.operation.id}`); throw e }
+ *       },
+ *     },
+ *   },
+ * } satisfies Plugin
+ * ```
+ *
+ * @example OpenAPI mount (SPEC §7.2b)
+ * ```ts
+ * import { toOpenApi } from '@adhd/apigen-openapi'
+ * export default {
+ *   id: 'openapi',
+ *   capabilities: {
+ *     mount: {
+ *       operations: (d) => [{
+ *         ...syntheticOp('_meta/openapi', d),
+ *         handler: () => toOpenApi(d),
+ *       }],
+ *     },
+ *   },
+ * } satisfies Plugin
+ * ```
+ */
+export interface Plugin<Opts = Record<string, unknown>> {
+    /**
+     * Canonical fully-qualified plugin identifier (SPEC §7.1).
+     *
+     * Use the package name (e.g. `'@adhd/apigen-ts-plugin-logger'`) or a short
+     * slug (e.g. `'logger'`).  The CLI accepts either as the `--use` / `--type`
+     * argument.  The id is also used as the `pluginId` in envelope field naming
+     * (`x-<id>-<field>`, SPEC §9.1).
+     */
+    id: string;
+    /**
+     * Optional human-readable description shown in `apigen plugins list` output
+     * and generated documentation.
+     */
+    description?: string;
+    /**
+     * The source language this plugin consumes.
+     *
+     * Used by the `serve` command to route each source file to the plugin(s)
+     * whose `language` matches its extension (`.ts`/`.tsx`/`.mts`/`.cts` → `'ts'`,
+     * `.py` → `'py'`, etc.).
+     *
+     * Defaults to `'ts'` when omitted for backward-compatibility with plugins
+     * authored before this field was introduced.  All first-party plugins
+     * explicitly declare `language: 'ts'`.
+     */
+    language?: PluginLanguage;
+    /**
+     * Optional JSON Schema for plugin-specific options.
+     *
+     * When provided, the CLI validates the `--opt` values supplied via
+     * `--use <plugin> --opt key=value` before constructing `opts`.
+     */
+    optionsSchema?: Record<string, unknown>;
+    /**
+     * The set of capabilities this plugin contributes.  All four are optional.
+     *
+     * At least one capability is expected in practice; the harness warns
+     * (at debug level) when a loaded plugin declares no capabilities.
+     */
+    capabilities: {
+        /**
+         * Target capability — project the descriptor to a transport/format and/or
+         * host domain functions in-process (SPEC §7.1 / §5).
+         *
+         * Selected by `--type <plugin>`.
+         */
+        target?: TargetCapability<Opts>;
+        /**
+         * Layer capability — wrap all operations in the onion (SPEC §7.1 / §8).
+         *
+         * Loaded by `--use <plugin>` when the plugin declares this capability.
+         */
+        layer?: LayerCapability;
+        /**
+         * Mount capability — add synthetic operations to the descriptor
+         * (SPEC §7.1).  Typical uses: `/meta/openapi`, `/meta/health`.
+         *
+         * Loaded by `--use <plugin>`.
+         */
+        mount?: MountCapability;
+        /**
+         * Envelope capability — declare request/response side-channel fields
+         * (SPEC §7.1 / §9.1).  Loaded by `--use <plugin>`.
+         *
+         * A plugin may combine `envelope` with `layer` to both *declare* the
+         * fields it needs and *read/write* them in its layer function.
+         */
+        envelope?: EnvelopeCapability;
+    };
+}

package/lib/schema-builders/map-set-tuple.d.ts

@@ -0,0 +1,19 @@
+/** Async element-schema builder — the `buildSchema` entrypoint, injected to avoid a circular import. */
+export type RecurseBuildSchema = (typeText: string) => Promise<Record<string, unknown>>;
+/**
+ * If `typeText` is a `Map` / `Set` / tuple, build the canonical
+ * array-compatible JSON-Schema fragment (recursing into element types via
+ * `recurse`). Returns `undefined` for any other type so the caller can fall
+ * through to its normal generator path.
+ *
+ * Schemas produced:
+ *   - `Map<K, V>` → `{ type:'array', items:{ type:'array', items:[Kschema, Vschema],
+ *                       minItems:2, maxItems:2 } }`
+ *   - `Set<T>`    → `{ type:'array', items:Tschema, uniqueItems:true }`
+ *   - `[A, B, C]` → `{ type:'array', items:[Aschema, Bschema, Cschema],
+ *                       minItems:N, maxItems:N }`  (positional / "prefixItems" form)
+ *
+ * The tuple positional `items` array is exactly what Ajv (draft-07) validates
+ * positionally, and what the runtime transcoder walks position-by-position.
+ */
+export declare function buildMapSetTupleSchema(typeText: string, recurse: RecurseBuildSchema): Promise<Record<string, unknown> | undefined>;

package/lib/schema-builders/morph-fallback.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Recursive fallback schema builder for primitive, array, union, and anonymous object types.
+ *
+ * @param typeText  - The TypeScript type text to convert (already alias-normalised by the caller).
+ * @param depth     - Recursion depth guard (max 6).
+ * @param aliases   - Optional local-name → canonical-key alias map from `extractScalarAliases`.
+ *                    When provided, bare local names (e.g. `D2`) are resolved to their canonical
+ *                    SCALAR_SCHEMAS key before the lookup.  The caller (buildSchema) already
+ *                    applies `applyAliasesToTypeText` to the top-level typeText, so aliases are
+ *                    only needed here as a fallback for any residual non-canonical names that
+ *                    survive deep inside the type text (e.g. union branches).
+ */
+export declare function morphFallback(typeText: string, depth: number, aliases?: ReadonlyMap<string, string>): Record<string, unknown>;

package/lib/schema-builders/morph-walk.d.ts

@@ -0,0 +1,59 @@
+import { Project, SourceFile, Type } from 'ts-morph';
+
+/** Async element-schema builder — the shared `buildSchema` entrypoint, injected to avoid a circular import. */
+export type RecurseBuildSchema = (typeText: string) => Promise<Record<string, unknown>>;
+/**
+ * Resolve a TypeScript type-text string into a ts-morph {@link Type}, evaluated
+ * in the lexical scope of `sf` (so the source file's imports and local
+ * declarations — `Decimal`, `Box`, `Point`, … — are all in scope).
+ *
+ * We add a throwaway `type __ApigenProbe_N = <typeText>` alias to the IN-MEMORY
+ * source file, read its `.getType()`, run the supplied visitor while the alias
+ * node is still live (ts-morph `Type` objects are only meaningfully walkable
+ * while their owning node exists), then remove the alias. The file is never
+ * `.save()`d, so the user's source on disk is untouched, and re-running the
+ * extractor sees the original file.
+ *
+ * Returns `undefined` if the alias cannot be created or its type cannot be
+ * resolved, so the caller can fall through to its text-based fallback.
+ */
+export declare function withResolvedType<T>(_project: Project, sf: SourceFile, typeText: string, visit: (type: Type) => Promise<T>): Promise<T | undefined>;
+/**
+ * Walk a ts-morph {@link Type} and build the canonical JSON-Schema fragment for
+ * the *structural* shapes that the scalar / Map-Set-tuple handlers don't own:
+ * anonymous objects, index signatures (`Record`), arrays, tuples, and unions.
+ *
+ * Every nested type is routed back through `recurse` (the shared `buildSchema`)
+ * via its type-text so scalar formats, Map/Set/tuple wire, aliases, and
+ * readonly arrays continue to flow through their existing handlers — this
+ * function never re-implements those rules.
+ *
+ * @param type    The resolved ts-morph Type (live; from {@link withResolvedType}).
+ * @param recurse The shared buildSchema entrypoint (resolves nested type-text).
+ * @param depth   Recursion guard.
+ * @returns A JSON-Schema fragment, or `{}` for genuinely opaque types — matching
+ *          the prior permissive fallback (e.g. an unresolvable generic).
+ */
+export declare function walkType(type: Type, recurse: RecurseBuildSchema, depth: number): Promise<Record<string, unknown>>;
+/** Advisory discriminator metadata attached to a `oneOf` union fragment. */
+export interface InlineDiscriminator {
+    /** Name of the property shared by every branch that carries a distinct literal value. */
+    propertyName: string;
+    /**
+     * Literal value → JSON-Pointer into this schema's own `oneOf` array
+     * (e.g. `"dog": "#/oneOf/0"`). Inline branches have no `$ref`/`$defs`
+     * identity of their own, so — unlike `union.ts`'s $ref-based
+     * `buildUnionSchema` — the mapping target is a same-document pointer.
+     */
+    mapping: Record<string, string>;
+}
+/**
+ * Looks for a property name present in EVERY variant's schema whose value is
+ * a single-value string/number `enum` (i.e. a literal, such as `kind: 'dog'`)
+ * and whose literal values are pairwise distinct across variants. When found,
+ * returns the discriminator metadata; otherwise `undefined` — a plain `oneOf`
+ * (no discriminator) still correctly models "exactly one of these variants"
+ * even when the variants have no shared literal tag (e.g. a domain interface
+ * unioned with `Record<string, unknown>`).
+ */
+export declare function detectDiscriminator(variants: ReadonlyArray<Record<string, unknown>>): InlineDiscriminator | undefined;

package/lib/schema-builders/nominal.d.ts

@@ -0,0 +1,95 @@
+import { X_APIGEN_LOGICAL, X_APIGEN_CODEC, X_APIGEN_CTOR, X_APIGEN_TOJSON } from '@adhd/apigen-base-logical';
+
+/**
+ * Information about one field of a nominal class, already expressed as a JSON
+ * Schema fragment (typically produced by `buildSchema` from ts-json-schema.ts).
+ */
+export interface NominalField {
+    /** Original field name as declared in source. */
+    name: string;
+    /** JSON Schema fragment for the field's type. */
+    schema: Record<string, unknown>;
+    /** True when the field has a `?` modifier or default value. */
+    optional?: boolean;
+}
+/**
+ * Extracted class descriptor handed to `buildNominalSchema`.
+ *
+ * All ts-morph work is done upstream (in `extract-classes.ts` or the
+ * caller). This record is the minimal slice needed to emit the schema.
+ */
+export interface NominalClassInfo {
+    /** Source-level class name, e.g. `"User"`. */
+    className: string;
+    /**
+     * Namespace qualifier prepended to `className` to form the stable
+     * `LogicalTypeId` (e.g. `"cli"` → `"cli.User"`). Pass `""` for
+     * top-level / unnamespaced classes.
+     */
+    namespace: string;
+    /** Ordered list of public serializable fields. */
+    fields: NominalField[];
+    /**
+     * Names of static/instance methods declared on the class (used to derive
+     * the optional `x-apigen-ctor` / `x-apigen-tojson` hints).
+     */
+    methodNames?: string[];
+}
+/** The JSON Schema for a single field inside a `$def`. */
+export type FieldSchema = Record<string, unknown>;
+/**
+ * The `$def` schema for the class — an object schema with `properties`,
+ * `required`, and optional `x-apigen-*` hints.
+ */
+export interface NominalDef {
+    type: 'object';
+    properties: Record<string, FieldSchema>;
+    required: string[];
+    [X_APIGEN_LOGICAL]: 'nominal';
+    [X_APIGEN_CODEC]: string;
+    [X_APIGEN_CTOR]?: string;
+    [X_APIGEN_TOJSON]?: string;
+}
+/**
+ * The full result of `buildNominalSchema`:
+ *   - `def`: the `$def` object to register under `$defs[className]`.
+ *   - `ref`: the `$ref` fragment for inline use (`#/$defs/<ClassName>`).
+ *   - `defKey`: the key to use under `$defs` (the class name).
+ *   - `codecId`: the qualified `LogicalTypeId` (e.g. `"cli.User"`).
+ */
+export interface NominalSchema {
+    /** Key under `$defs` (`className`). */
+    defKey: string;
+    /** The `$def` schema fragment — register as `$defs[defKey]`. */
+    def: NominalDef;
+    /** Inline `$ref` schema for positions that hold this nominal type. */
+    ref: {
+        $ref: string;
+    };
+    /** Stable, namespace-qualified `LogicalTypeId`. */
+    codecId: string;
+}
+/**
+ * Given an extracted nominal class descriptor, emit the canonical descriptor
+ * schema fragment: a named `$def` (object schema with fields + `x-apigen-*`
+ * hints) and a `$ref` pointing at it.
+ *
+ * Per invariant `[inv:hints-advisory]` the `x-apigen-*` keys are advisory —
+ * see `stripHints` to obtain a pure structural schema.
+ *
+ * @param info - Class info produced by the extractor.
+ * @returns `{ defKey, def, ref, codecId }` ready for insertion into a descriptor.
+ */
+export declare function buildNominalSchema(info: NominalClassInfo): NominalSchema;
+declare const HINT_KEYS: readonly ["x-apigen-logical", "x-apigen-codec", "x-apigen-ctor", "x-apigen-tojson"];
+/**
+ * Return a copy of `def` with all `x-apigen-*` advisory keys removed.
+ *
+ * The result is a plain JSON Schema object schema — valid and structurally
+ * authoritative without any apigen extension keys.  Proves invariant
+ * `[inv:hints-advisory]`: stripping hints MUST leave a structurally-complete
+ * schema (type + properties + required) that a standard JSON-Schema validator
+ * can consume.
+ */
+export declare function stripHints(def: NominalDef): Omit<NominalDef, (typeof HINT_KEYS)[number]>;
+export {};