@zerodds/wire 0.0.0-stage → 1.0.0-rc.7

package/dist/registry.d.ts

@@ -0,0 +1,84 @@
+import type { DdsTypeDescriptor, GuardedTypeOf } from "./types.js";
+/**
+ * Add a descriptor to the registry.
+ *
+ * DDS-TS 1.0 §8.7. Registering the same type twice is silent — a module
+ * imported from two places runs its registration twice and that is not
+ * an error. Registering a **different** type under a name already taken
+ * throws, and it has to: the second registration would otherwise decide
+ * what every `{ kind: "ref" }` to that name resolves to, and every
+ * consumer downstream would read one type's samples through another
+ * type's members with nothing reporting it.
+ *
+ * @throws TypeError when the name is taken by a structurally different
+ * descriptor.
+ */
+export declare function registerType(d: DdsTypeDescriptor): void;
+/**
+ * The descriptor registered under a qualified IDL name, or `undefined`.
+ *
+ * DDS-TS 1.0 §8.7. `undefined` and not a throw: a consumer that reached
+ * a `ref` to a type whose module was never imported is asking a question
+ * this can answer, and the caller decides whether that is a failure.
+ */
+export declare function lookupType(qualifiedName: string): DdsTypeDescriptor | undefined;
+/**
+ * The values of a sample's key members, in declaration order.
+ *
+ * DDS-TS 1.0 §8.7. Declaration order is the order the descriptor lists
+ * them, which is the order the IDL declared them and the order X-Types
+ * 1.3 §7.6.8 hashes them in — so the array can be fed to a key hash
+ * without being sorted first.
+ *
+ * The sample's shape is **not** checked. A caller that does not trust
+ * where the sample came from runs `descriptor.typeGuard` first; one that
+ * just decoded it through the generated codec already knows.
+ *
+ * A type with no `@key` member returns `[]`, which is the whole of the
+ * DDS single-instance case and not an error.
+ */
+export declare function getKey<T>(sample: T, descriptor: DdsTypeDescriptor<T>): ReadonlyArray<unknown>;
+/**
+ * The topic name the type is bound to, or `undefined`.
+ *
+ * DDS-TS 1.0 §8.7. `descriptor.topic` unchanged — a function rather than
+ * a property access so that a consumer holding only the reflection API
+ * has one, and so that the `@topic` binding has a name to be looked up
+ * by.
+ */
+export declare function getTopic<T>(descriptor: DdsTypeDescriptor<T>): string | undefined;
+/**
+ * A partial value, completed from the descriptor's `@default` values.
+ *
+ * DDS-TS 1.0 §8.7. Every member the descriptor records a
+ * non-`undefined` `default` for and `partial` does not carry is filled
+ * from that default. A member with neither stays **absent** — not
+ * `undefined`, absent — because a `@optional` member that is present and
+ * undefined is a different sample from one that is not there at all, and
+ * under XCDR2 the two are different octets.
+ */
+export declare function withDefaults<T>(descriptor: DdsTypeDescriptor<T>, partial: Partial<T>): T;
+/**
+ * Whether a rejection carries one of a set of IDL exceptions.
+ *
+ * DDS-TS 1.0 §8.7. A generated Operations-Profile client rejects with an
+ * `Error` whose `cause` is the decoded IDL exception payload, so a
+ * catch-handler asks this and gets the union of the listed types back as
+ * a narrowing:
+ *
+ * ```ts
+ * catch (err) {
+ *   if (isOneOf(err, [NotFoundType, DeniedType])) {
+ *     err.cause; // NotFound | Denied
+ *   }
+ * }
+ * ```
+ *
+ * Never throws. A `catch` block is the one place where a helper that
+ * threw would replace the error being handled with its own, so anything
+ * that is not an `Error` — a thrown string, a rejected `undefined` — is
+ * simply `false`.
+ */
+export declare function isOneOf<DS extends ReadonlyArray<DdsTypeDescriptor>>(err: unknown, descriptors: DS): err is Error & {
+    cause: GuardedTypeOf<DS[number]>;
+};

package/dist/registry.js

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 ZeroDDS Contributors
+/**
+ * The reflection half of the descriptor runtime.
+ *
+ * DDS-TS 1.0 §8.7. A registry keyed by qualified IDL name, and the five
+ * functions that read a descriptor: the key members out of a sample, the
+ * topic name off the type, the defaults into a partial value, and — in
+ * `./dds_any.js` and `./equal.js` — the box and the key comparison.
+ *
+ * # Why there is a registry at all
+ *
+ * Because `DdsTypeRef.kind === "ref"` carries a **name** and not a
+ * descriptor (§8.2). That is what makes a descriptor graph acyclic and
+ * therefore JSON-roundtrippable, and it is what lets two structs refer to
+ * each other when neither can be initialised first. The cost is that a
+ * consumer walking the graph has to resolve those names somewhere, and
+ * this is the somewhere: every generated module ends with
+ * `registerType(<Type>Type)`, and {@link lookupType} answers.
+ */
+import { descriptorsEqual } from "./equal.js";
+/**
+ * Every descriptor registered so far, by qualified IDL name.
+ *
+ * One map for the module graph. Two bundles that each carry their own
+ * copy of this runtime have two registries and each sees its own
+ * registrations, which §8.7 names as out of scope for the equivalence
+ * check.
+ */
+const registry = new Map();
+/**
+ * Add a descriptor to the registry.
+ *
+ * DDS-TS 1.0 §8.7. Registering the same type twice is silent — a module
+ * imported from two places runs its registration twice and that is not
+ * an error. Registering a **different** type under a name already taken
+ * throws, and it has to: the second registration would otherwise decide
+ * what every `{ kind: "ref" }` to that name resolves to, and every
+ * consumer downstream would read one type's samples through another
+ * type's members with nothing reporting it.
+ *
+ * @throws TypeError when the name is taken by a structurally different
+ * descriptor.
+ */
+export function registerType(d) {
+    const seen = registry.get(d.name);
+    if (seen === undefined) {
+        registry.set(d.name, d);
+        return;
+    }
+    if (descriptorsEqual(seen, d)) {
+        return;
+    }
+    throw new TypeError(`registerType: \`${d.name}\` is already registered as a different type`);
+}
+/**
+ * The descriptor registered under a qualified IDL name, or `undefined`.
+ *
+ * DDS-TS 1.0 §8.7. `undefined` and not a throw: a consumer that reached
+ * a `ref` to a type whose module was never imported is asking a question
+ * this can answer, and the caller decides whether that is a failure.
+ */
+export function lookupType(qualifiedName) {
+    return registry.get(qualifiedName);
+}
+/**
+ * The values of a sample's key members, in declaration order.
+ *
+ * DDS-TS 1.0 §8.7. Declaration order is the order the descriptor lists
+ * them, which is the order the IDL declared them and the order X-Types
+ * 1.3 §7.6.8 hashes them in — so the array can be fed to a key hash
+ * without being sorted first.
+ *
+ * The sample's shape is **not** checked. A caller that does not trust
+ * where the sample came from runs `descriptor.typeGuard` first; one that
+ * just decoded it through the generated codec already knows.
+ *
+ * A type with no `@key` member returns `[]`, which is the whole of the
+ * DDS single-instance case and not an error.
+ */
+export function getKey(sample, descriptor) {
+    const bag = sample;
+    const out = [];
+    for (const member of descriptor.fields) {
+        if (member.base === true && member.type.kind === "ref") {
+            // The keys of the base come first, as they are written first (§7.4.1.1.5.1).
+            const base = lookupType(member.type.name);
+            const held = bag[member.name];
+            if (base !== undefined && held !== undefined) {
+                out.push(...getKey(held, base));
+            }
+            continue;
+        }
+        if (member.key) {
+            out.push(bag[member.name]);
+        }
+    }
+    return out;
+}
+/**
+ * The topic name the type is bound to, or `undefined`.
+ *
+ * DDS-TS 1.0 §8.7. `descriptor.topic` unchanged — a function rather than
+ * a property access so that a consumer holding only the reflection API
+ * has one, and so that the `@topic` binding has a name to be looked up
+ * by.
+ */
+export function getTopic(descriptor) {
+    return descriptor.topic;
+}
+/**
+ * A partial value, completed from the descriptor's `@default` values.
+ *
+ * DDS-TS 1.0 §8.7. Every member the descriptor records a
+ * non-`undefined` `default` for and `partial` does not carry is filled
+ * from that default. A member with neither stays **absent** — not
+ * `undefined`, absent — because a `@optional` member that is present and
+ * undefined is a different sample from one that is not there at all, and
+ * under XCDR2 the two are different octets.
+ */
+export function withDefaults(descriptor, partial) {
+    const out = { ...partial };
+    for (const member of descriptor.fields) {
+        if (member.base === true && member.type.kind === "ref") {
+            const base = lookupType(member.type.name);
+            if (base !== undefined) {
+                const held = (out[member.name] ?? {});
+                out[member.name] = withDefaults(base, held);
+            }
+            continue;
+        }
+        if (member.default === undefined || member.name in out) {
+            continue;
+        }
+        out[member.name] = member.default;
+    }
+    return out;
+}
+/**
+ * Whether a rejection carries one of a set of IDL exceptions.
+ *
+ * DDS-TS 1.0 §8.7. A generated Operations-Profile client rejects with an
+ * `Error` whose `cause` is the decoded IDL exception payload, so a
+ * catch-handler asks this and gets the union of the listed types back as
+ * a narrowing:
+ *
+ * ```ts
+ * catch (err) {
+ *   if (isOneOf(err, [NotFoundType, DeniedType])) {
+ *     err.cause; // NotFound | Denied
+ *   }
+ * }
+ * ```
+ *
+ * Never throws. A `catch` block is the one place where a helper that
+ * threw would replace the error being handled with its own, so anything
+ * that is not an `Error` — a thrown string, a rejected `undefined` — is
+ * simply `false`.
+ */
+export function isOneOf(err, descriptors) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const cause = err.cause;
+    return descriptors.some((descriptor) => descriptor.typeGuard(cause));
+}

package/dist/test_backend.d.ts

@@ -0,0 +1,9 @@
+import type { WasmBackend } from "./wasm.js";
+/**
+ * An in-memory {@link WasmBackend}.
+ *
+ * Handles start at 1 and are never reused, so a handle that has been
+ * deleted names nothing else afterwards — which is what lets the
+ * binding layer's `RangeError` say which handle it was.
+ */
+export declare function createTestBackend(): WasmBackend;

package/dist/test_backend.js

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 ZeroDDS Contributors
+/**
+ * A DDS data path in TypeScript, for measuring the binding layer against.
+ *
+ * DDS-TS 1.0 §C.5 requires a conformant WASM binding to pass four tests:
+ * a publish/subscribe round trip, a listener that fires, a delete that
+ * cascades, and a boxed `any` that survives the trip. Those are tests of
+ * {@link bindWasmBackend} — the handle checks, the cascade, the copies,
+ * the deferral — and running them against a real `.wasm` module would
+ * measure the module as well, in a test that needs a build of it to fail
+ * or pass.
+ *
+ * So this: a {@link WasmBackend} that keeps its samples in a `Map`.
+ * Every rule Annex C states about the *binding* is measurable against
+ * it, and a failure is the binding's, because there is no wire and no
+ * module.
+ *
+ * What it is not: a DDS implementation. There is no discovery, no
+ * reliability, no history depth, no QoS at all. Matching is by domain
+ * and topic name, delivery is immediate and in order, and the sample
+ * states it reports are the ones a fresh take produces. A test that
+ * needs any of the rest belongs against the Rust core.
+ *
+ * It is deliberately synchronous — `writeSample` runs the listener
+ * straight through, in the writer's own turn. That is precisely what
+ * §C.2.4 forbids a *binding* from doing, and it is what makes the
+ * deferral in {@link bindWasmBackend} measurable: if the wrapper ever
+ * stopped queueing, this backend would deliver inside `writeSample` and
+ * the C.5.2 test would see it.
+ */
+import { makeDdsGuid } from "./wasm.js";
+/** The twelve-octet prefix every writer of one backend instance shares. */
+const GUID_PREFIX_LENGTH = 12;
+/**
+ * An in-memory {@link WasmBackend}.
+ *
+ * Handles start at 1 and are never reused, so a handle that has been
+ * deleted names nothing else afterwards — which is what lets the
+ * binding layer's `RangeError` say which handle it was.
+ */
+export function createTestBackend() {
+    const participants = new Map();
+    const topics = new Map();
+    const publishers = new Map();
+    const subscribers = new Map();
+    const writers = new Map();
+    const readers = new Map();
+    let nextHandle = 1;
+    /** The next unused handle. */
+    function fresh() {
+        const handle = nextHandle;
+        nextHandle += 1;
+        return handle;
+    }
+    /** The domain a topic sits in. */
+    function domainOf(topic) {
+        return participants.get(topic.participant)?.domainId ?? -1;
+    }
+    /** A GUID that names one writer and no other. */
+    function guidOf(writer) {
+        const prefix = new Uint8Array(GUID_PREFIX_LENGTH);
+        // Octets 0..1 are the vendor id in DDSI-RTPS 2.5 §8.2.4.1; the
+        // rest of the prefix is this backend's own numbering, which is all
+        // an in-memory data path has to tell its writers apart with.
+        prefix[0] = 0x01;
+        prefix[1] = 0x20;
+        prefix[8] = (writer >>> 24) & 0xff;
+        prefix[9] = (writer >>> 16) & 0xff;
+        prefix[10] = (writer >>> 8) & 0xff;
+        prefix[11] = writer & 0xff;
+        // The entity kind of a user-defined writer with key: DDSI-RTPS 2.5
+        // §9.3.1.2, `0x02` in the low octet.
+        return makeDdsGuid(prefix, ((writer << 8) >>> 0) | 0x02);
+    }
+    return {
+        createParticipant(domainId) {
+            const handle = fresh();
+            participants.set(handle, { domainId });
+            return handle;
+        },
+        deleteParticipant(p) {
+            participants.delete(p);
+        },
+        createTopic(p, name, typeName) {
+            const handle = fresh();
+            topics.set(handle, { participant: p, name, typeName });
+            return handle;
+        },
+        deleteTopic(t) {
+            topics.delete(t);
+        },
+        createPublisher(p) {
+            const handle = fresh();
+            publishers.set(handle, { participant: p });
+            return handle;
+        },
+        createSubscriber(p) {
+            const handle = fresh();
+            subscribers.set(handle, { participant: p });
+            return handle;
+        },
+        deletePublisher(pub) {
+            publishers.delete(pub);
+        },
+        deleteSubscriber(sub) {
+            subscribers.delete(sub);
+        },
+        createDataWriter(pub, topic) {
+            const handle = fresh();
+            writers.set(handle, { publisher: pub, topic, next: 1n });
+            return handle;
+        },
+        createDataReader(sub, topic) {
+            const handle = fresh();
+            readers.set(handle, { subscriber: sub, topic, queue: [], listener: null });
+            return handle;
+        },
+        writeSample(w, xcdr2) {
+            const writer = writers.get(w);
+            const topic = writer === undefined ? undefined : topics.get(writer.topic);
+            if (writer === undefined || topic === undefined) {
+                throw new RangeError(`writer ${w} has no topic`);
+            }
+            const sequenceNumber = writer.next;
+            writer.next += 1n;
+            const info = {
+                validData: true,
+                sampleState: "not_read",
+                viewState: "new",
+                instanceState: "alive",
+                sourceTimestampNs: BigInt(Date.now()) * 1000000n,
+                sequenceNumber,
+                publicationHandle: guidOf(w),
+                instanceHandle: BigInt(w),
+            };
+            for (const [handle, reader] of readers) {
+                const other = topics.get(reader.topic);
+                if (other === undefined ||
+                    other.name !== topic.name ||
+                    domainOf(other) !== domainOf(topic)) {
+                    continue;
+                }
+                // A copy per reader: two readers that were handed one array
+                // would see each other's writes into it.
+                reader.queue.push({ bytes: xcdr2.slice(), info });
+                // Straight through, in the writer's turn. See the file comment:
+                // the deferral is the binding layer's and this is what proves
+                // it happens.
+                reader.listener?.(handle);
+            }
+        },
+        takeSamples(r, max) {
+            const reader = readers.get(r);
+            if (reader === undefined) {
+                return [];
+            }
+            return reader.queue.splice(0, max);
+        },
+        deleteDataWriter(w) {
+            writers.delete(w);
+        },
+        deleteDataReader(r) {
+            readers.delete(r);
+        },
+        setDataAvailableListener(r, cb) {
+            const reader = readers.get(r);
+            if (reader !== undefined) {
+                reader.listener = cb;
+            }
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+/**
+ * The descriptor side-table, as the values a TypeScript program can read.
+ *
+ * DDS-TS 1.0 chapter 8. A TypeScript `interface` is erased at compile
+ * time and a plain object literal carries no run-time type identity, so
+ * the identity travels beside the data as a first-class value: one
+ * {@link DdsTypeDescriptor} per IDL type, emitted by the code generator
+ * and registered with the process-wide registry
+ * (`registerType` in `./registry.js`).
+ *
+ * The content set is deliberately close to the `TypeObject` /
+ * `MinimalTypeObject` structures of OMG X-Types 1.3 §7.3 — extensibility,
+ * member ids, key membership, type references — so that a descriptor can
+ * be turned into a `TypeObject` and back without losing anything
+ * (DDS-TS 1.0 §6.2).
+ *
+ * Nothing in this file has a run-time representation: it is types only.
+ * The functions that read these shapes live in `./registry.js`,
+ * `./dds_any.js` and `./equal.js`.
+ */
+/**
+ * The three extensibility kinds of OMG X-Types 1.3 §7.2.2.4.4.
+ *
+ * DDS-TS 1.0 §8.1. Spelled in lower case rather than as the
+ * `FINAL`/`APPENDABLE`/`MUTABLE` of the IDL annotation, because the
+ * descriptor is JSON-roundtrippable and these are its values.
+ */
+export type ExtensibilityKind = "final" | "appendable" | "mutable";
+/**
+ * The IDL primitive types, under the names the descriptor uses.
+ *
+ * DDS-TS 1.0 §8.2. `int16` and not `short`: the IDL 4.2 §7.4.1.4.4.2
+ * explicit-width spellings are unambiguous, and a descriptor that said
+ * `long` would be read differently by a C consumer than by a Java one.
+ * `longDouble` is the sixteen-octet carrier of §8.6, not a `number`.
+ *
+ * `int8` is one name past the list §8.2 gives. IDL 4.2 §7.4.1.4.4.2
+ * declares `int8` alongside `uint8`, the list names `octet` — which is
+ * `uint8` — and names nothing for the signed one. A generator meeting
+ * `int8 v;` has three choices: write `octet`, which is the wrong
+ * signedness; refuse the member, which drops a type IDL admits; or
+ * carry a name the list does not have. The third is the only one that
+ * does not lose something, and it is additive: every value §8.2 lists
+ * still means what §8.2 says.
+ */
+export type PrimitiveName = "boolean" | "octet" | "int8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float" | "double" | "longDouble" | "char" | "wchar";
+/**
+ * The type of one member, in side-table form.
+ *
+ * DDS-TS 1.0 §8.2. A discriminated union over `kind`, which is what lets
+ * a consumer walk a descriptor graph with the compiler checking every
+ * arm.
+ *
+ * The `ref` kind carries the **qualified IDL name** of the referenced
+ * type and not a descriptor reference. That rule is normative and it
+ * buys three things: mutually-recursive struct and union references that
+ * no source-line order could initialise, a value graph with no cycles in
+ * it (so `JSON.stringify` round-trips a descriptor), and the same shape
+ * OMG X-Types 1.3 uses for `TypeIdentifier` lookup. Resolution happens at
+ * use time, through `lookupType(name)`.
+ *
+ * The `any` kind carries no name at all: the run-time identity of an IDL
+ * `any` is by construction not known statically, and a consumer that
+ * reaches one defers to the boxed value's `typeId` (DDS-TS 1.0 §7.3.4).
+ */
+export type DdsTypeRef = {
+    kind: "primitive";
+    name: PrimitiveName;
+}
+/** A bitset member or a bitmask bit value; `width` is 1..64. */
+ | {
+    kind: "bitfield";
+    width: number;
+} | {
+    kind: "string";
+    bound?: number | undefined;
+    wide: boolean;
+} | {
+    kind: "sequence";
+    element: DdsTypeRef;
+    bound?: number | undefined;
+} | {
+    kind: "array";
+    element: DdsTypeRef;
+    lengths: ReadonlyArray<number>;
+} | {
+    kind: "map";
+    key: DdsTypeRef;
+    value: DdsTypeRef;
+    bound?: number | undefined;
+}
+/** A qualified IDL name; resolve through `lookupType`. */
+ | {
+    kind: "ref";
+    name: string;
+} | {
+    kind: "any";
+};
+/**
+ * One member of a type, with the annotation metadata that governs it.
+ *
+ * DDS-TS 1.0 §8.3. `unit`, `min` and `max` are carried for a consumer
+ * that wants them and are **not** enforced by the type guard: a guard
+ * that rejected an out-of-range value would refuse a sample the wire
+ * accepted, which is a different contract from the one the IDL wrote.
+ */
+export interface DdsMemberDescriptor {
+    /** The IDL member name, as declared. */
+    readonly name: string;
+    /** The effective member id — `@id`, `@autoid`, or the position. */
+    readonly id: number;
+    /** What the member holds. */
+    readonly type: DdsTypeRef;
+    /** `@key`. */
+    readonly key: boolean;
+    /** `@optional`. */
+    readonly optional: boolean;
+    /** `@must_understand`. */
+    readonly mustUnderstand: boolean;
+    /** `@default(V)`, or an enumerator's ordinal, or a bit position. */
+    readonly default?: unknown;
+    /** `@unit("…")` — documentation, never validated. */
+    readonly unit?: string | undefined;
+    /** `@min(V)` — documentation, never validated. */
+    readonly min?: unknown;
+    /** `@max(V)` — documentation, never validated. */
+    readonly max?: unknown;
+    /** `@hashid("…")`, the string the id was hashed from. */
+    readonly hashid?: string | undefined;
+    /**
+     * The case labels that select this member. Union descriptors only
+     * (DDS-TS 1.0 §7.5.1); `undefined` marks the `default:` case.
+     *
+     * `bigint` is one member past the element type §8.3 gives. A
+     * `union U switch (long long)` is legal IDL 4.2 and its case labels
+     * reach past 2^53, where a `number` holds two of them as one value;
+     * the arm's `discriminator` property is a `bigint` for that reason
+     * (§7.5), and a label list that could not carry one would disagree
+     * with the type it describes. Additive: every label §8.3 admits is
+     * still admitted.
+     */
+    readonly labels?: ReadonlyArray<number | string | boolean | bigint> | undefined;
+    /**
+     * A map key whose JavaScript equality is not value equality — a
+     * struct, an array, a sequence (DDS-TS 1.0 §7.9.1, diagnostic
+     * `DDS-TS-W003`). A `Map` keyed by one compares its keys by
+     * reference; the flag is what tells a consumer to compare with
+     * `equalKey` instead.
+     */
+    readonly keyEqualityHazard?: boolean | undefined;
+    /**
+     * The member is the base structure, the first member `parent` (XTypes
+     * 1.3 §7.5.1.4.1.3): its type is the `ref` to the base, and the members
+     * of that type are members of this one for `getKey` and `withDefaults`.
+     */
+    readonly base?: boolean | undefined;
+}
+/**
+ * Which IDL declaration a descriptor came from.
+ *
+ * DDS-TS 1.0 §8.3. `exception` and not a flag on `struct`: an exception
+ * maps to the same shape but crosses an Operations-Profile boundary
+ * differently, and a consumer switching on `kind` should see the
+ * difference.
+ */
+export type DescriptorKind = "struct" | "union" | "enum" | "bitset" | "bitmask" | "exception" | "alias" | "interface";
+/**
+ * One IDL type, as the value that carries its metadata.
+ *
+ * DDS-TS 1.0 §8.3. The generated `export const <Type>Type` constant.
+ *
+ * `typeGuard` is the one member that is not data: a function the
+ * generator emits beside the descriptor, checking the presence and type
+ * of every **required** member. It does not check `@unit`, `@min` or
+ * `@max`, and it does not require optional members.
+ */
+export interface DdsTypeDescriptor<T = unknown> {
+    /** Which IDL declaration this is. */
+    readonly kind: DescriptorKind;
+    /** The qualified IDL name — `robot::Pose`, not `Pose`. */
+    readonly name: string;
+    /** `@final` / `@appendable` / `@mutable`, resolved. */
+    readonly extensibility: ExtensibilityKind;
+    /** `@nested` — whether the type may stand as a topic type. */
+    readonly nested: boolean;
+    /** `@topic("…")`, where the IDL bound one. */
+    readonly topic?: string | undefined;
+    /** `@autoid(SEQUENTIAL|HASH)`, where the IDL set one. */
+    readonly autoid?: "sequential" | "hash" | undefined;
+    /**
+     * `@bit_bound(N)`. An enumeration's effective bound (default 32), a
+     * bitmask's, or a bitset's total width.
+     */
+    readonly bitBound?: number | undefined;
+    /** A union with a `default:` case (DDS-TS 1.0 §7.5.1). */
+    readonly hasDefault?: boolean | undefined;
+    /**
+     * A union with no `default:` case whose listed cases do not exhaust
+     * the discriminator (DDS-TS 1.0 §7.5.2, diagnostic `DDS-TS-W004`).
+     */
+    readonly hasImplicitDefault?: boolean | undefined;
+    /**
+     * The members, in declaration order. Empty for an enumeration's
+     * holder-only forms and for an `interface`, whose operations live in
+     * a Service Descriptor instead.
+     */
+    readonly fields: ReadonlyArray<DdsMemberDescriptor>;
+    /** The emitted `is<Type>` predicate. */
+    readonly typeGuard: (v: unknown) => v is T;
+}
+/**
+ * The marker every generated IDL `exception` interface extends.
+ *
+ * DDS-TS 1.0 §8.3.1. A property and not a class: TypeScript's structural
+ * typing has nothing else that separates an exception payload from an
+ * ordinary struct at compile time, and this PSM emits no classes.
+ */
+export interface DdsException {
+    readonly __dds_exception: true;
+}
+/**
+ * A boxed IDL `any`: a value together with the identity of its type.
+ *
+ * DDS-TS 1.0 §8.4 and §7.3.4. `typeId` is the qualified IDL name and
+ * indexes the registry, so `lookupType(box.typeId)` answers with the
+ * descriptor that describes `value`.
+ *
+ * Construct with `boxAny`, narrow with `unboxAny` — both in
+ * `./dds_any.js`. Reading `value` directly is legal and gives back
+ * `unknown`, which is the point: an IDL `any` mapped to TypeScript `any`
+ * would switch the checking off rather than carry the identity.
+ */
+export interface DdsAny {
+    /** The qualified IDL name of the boxed value's type. */
+    readonly typeId: string;
+    /** The payload. `unknown`, and narrowed through the descriptor. */
+    readonly value: unknown;
+}
+/**
+ * The type a descriptor guards.
+ *
+ * DDS-TS 1.0 §8.7. `GuardedTypeOf<typeof PoseType>` is `Pose`, which is
+ * what lets `isOneOf` state the union of a list of exception
+ * descriptors as one narrowed type.
+ */
+export type GuardedTypeOf<D> = D extends DdsTypeDescriptor<infer T> ? T : never;

package/dist/types.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 ZeroDDS Contributors
+export {};