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

package/dist/writer.d.ts

@@ -0,0 +1,662 @@
+/**
+ * The write half of XCDR, implemented from DDS-XTypes 1.3 §7.4.
+ *
+ * The fifth independent runtime beside `crates/wire`, `runtime/c`,
+ * `runtime/cpp`, `runtime/java` and `runtime/python`. None of them
+ * calls another, and that is the point: a difference between two of
+ * them is a finding about the clause, not about a shared bug.
+ *
+ * What TypeScript decides differently from the others:
+ *
+ * - a `number` is an IEEE 754 binary64, so every integer narrower than
+ *   2^53 is one and everything wider is a `bigint`. The boundary is the
+ *   type's, not the wire's — `long long` is a `bigint` because a
+ *   binary64 cannot hold every `i64`, and `long` is a `number` because
+ *   it can hold every `i32`;
+ * - a range check happens at the point of the write. In Rust an `i16`
+ *   is an `i16` and the compiler has refused the value already; here
+ *   `70000` is as much a `number` as `7` is, and `& 0xffff` would put
+ *   `4464` on the wire and report success;
+ * - a `long double` never becomes a `number`. Sixteen octets in and
+ *   sixteen octets out; a binary64 would drop sixty bits of the
+ *   significand at the assignment.
+ */
+import { Endianness } from "./endianness.js";
+import { FixedDigitCount, ParameterRole, WcharFraming, WcharWidth, WstringLengthPolicy, WstringUnitOrder } from "./policy.js";
+/** The parameter id that introduces the extended form. §7.4.1.2.2. */
+export declare const PID_EXTENDED = 16129;
+/** The parameter id that ends a parameter list. §7.4.1.2.4. */
+export declare const PID_LIST_END = 16130;
+/**
+ * The highest member id a short parameter header can carry.
+ *
+ * §7.4.1.2.2 gives the range as 0 to 0x3F00 *inclusive*, and
+ * PID_EXTENDED is one above it.
+ */
+export declare const PID_SHORT_MAX_ID = 16128;
+/** The implementation-extension flag of a parameter id. */
+export declare const PID_IMPL_EXTENSION = 32768;
+/** The must-understand flag of a parameter id. */
+export declare const PID_MUST_UNDERSTAND = 16384;
+/** How many octets a KeyHash holder has. RTPS 2.5 §9.6.3.3. */
+export declare const KEY_HASH_LEN = 16;
+/**
+ * Where a framing may put flags.
+ *
+ * Wider than `ParameterRole` in `policy.ts`, which is what a
+ * *generated codec* names: a sentinel and an extended marker are the
+ * framing's own parameters and no member is ever one.
+ */
+export type FlagPosition = "member" | "sentinel" | "extended-marker";
+/** Where a framing puts its flags on a parameter id. */
+export interface PidFlags {
+    readonly member: number;
+    readonly sentinel: number;
+    readonly extendedMarker: number;
+}
+/** No flags anywhere, which is Fast DDS's framing. */
+export declare const PID_FLAGS_NONE: PidFlags;
+/** The name `PidFlagPolicy::Bare` gives {@link PID_FLAGS_NONE}. */
+export declare const PID_FLAGS_BARE: PidFlags;
+/**
+ * A bare member id, the must-understand bit on the sentinel and on the
+ * extended marker. Cyclone DDS and RTI Connext 7.7. The default.
+ *
+ * Measured, on `struct-mutable` and `annotation-hashid-implicit` under
+ * XCDR1: both write `7f02` for the sentinel and `7f01` for the extended
+ * marker — the must-understand bit alone. The implementation-extension
+ * bit is **not** on either of them, and a runtime that also set it wrote
+ * `ff02` and `ff01`, which is what OpenDDS writes for the marker and
+ * nobody writes for the sentinel.
+ */
+export declare const PID_FLAGS_SENTINEL_MUST_UNDERSTAND: PidFlags;
+/**
+ * Both flags on every member id whatever the member declared, a bare
+ * sentinel, and both on the extended marker. OpenDDS.
+ *
+ * `annotation-hashid-implicit` is `ff010008 0343172c 00000004`: both
+ * flags on the marker, and a **bare** `eMemberHeader` behind it for a
+ * member that declares nothing.
+ */
+export declare const PID_FLAGS_IMPL_EXTENSION_ON_MEMBERS: PidFlags;
+/** The flags a framing puts on a parameter in `role`. */
+export declare function pidFlagsAt(flags: PidFlags, role: FlagPosition): number;
+/**
+ * The parts of PL_CDR1 framing a plan cannot answer.
+ *
+ * Every field is a measured divergence between implementations, not a
+ * reading of the clause: §7.4.1.2 leaves the padding of a declared
+ * length open, and the flags a vendor puts on every id are its own.
+ */
+export interface PlCdr1Framing {
+    /** Which flags ride on every parameter id, by role. */
+    readonly pidFlags: PidFlags;
+    /**
+     * The highest id written in the short form. `writePid` refuses an id
+     * above it: §7.4.1.2.2 reserves the range above for the protocol's
+     * own parameters.
+     */
+    readonly shortMaxId: number;
+    /** Whether a declared length covers the value's trailing padding. */
+    readonly padsDeclaredLength: boolean;
+    /** The same, for an `@optional` member outside a `@mutable` type. */
+    readonly padsOptionalLength: boolean;
+    /** Whether a member's own must-understand reaches its id. */
+    readonly memberMustUnderstand: boolean;
+    /**
+     * Whether the parameter that just ended writes its own trailing
+     * padding to the next four-byte boundary. Every header writer aligns
+     * itself, so the two readings only part at the end of the stream:
+     * RTI pads after a final `@optional` parameter, Fast DDS does not.
+     */
+    readonly padAfterValue: boolean;
+}
+/** The framing every field of which is the specification's reading. */
+export declare const PL_CDR1_DEFAULT: PlCdr1Framing;
+/**
+ * What `writeDheader` hands back, to be given to `finishDheader`.
+ *
+ * A `@final` aggregate has none, and the walk still declares one and
+ * finishes it — so the absence is a value of this type rather than
+ * `undefined`. `at` below zero is that absence; `finishDheader`
+ * ignores it. The alternative is `DHeader | undefined` in every
+ * generated signature and a null check at every finish, for a case the
+ * layout plan already decided.
+ */
+export interface DHeader {
+    readonly at: number;
+}
+/** The DHEADER a `@final` aggregate does not write. */
+export declare function noDheader(): DHeader;
+/** What `writeEmheader` hands back. */
+export interface EmHeader {
+    /** Where the NEXTINT is, or `undefined` where the code carries it. */
+    readonly nextInt: number | undefined;
+    /** Where the header word is, so a short code can rewrite it. */
+    readonly word: number;
+    /**
+     * The code the header was written with, so that `finishEmheader` can
+     * hold the member's value to the length the code declares. Codes 0 to
+     * 3 are lengths; anything else declares nothing of its own.
+     */
+    readonly lengthCode: number;
+}
+/** What `writePid` and `writePidExtended` hand back. */
+export interface Pid {
+    readonly at: number;
+    readonly extended: boolean;
+    readonly savedOrigin: number;
+    /**
+     * What the parameter frames.
+     *
+     * A {@link ParameterRole} and not a {@link FlagPosition}: whether the
+     * declared length covers the value's trailing padding is answered
+     * differently for an `@optional` member outside a `@mutable` type than
+     * for a member of one, and {@link Writer.finishPid} needs the answer
+     * after the value has been written. A header that carried the flag
+     * position instead had no way to reach `padsOptionalLength` at all,
+     * so every `@optional` under XCDR1 took the member's padding rule.
+     */
+    readonly role: ParameterRole;
+    readonly pid: number;
+    readonly mustUnderstand: boolean;
+}
+/**
+ * An IDL `long double`, as the sixteen octets it is.
+ *
+ * Declared here beside {@link Writer.writeF128} and `Reader.readF128`,
+ * the two operations that traffic in it, rather than in `float128.ts`
+ * with the decimal converter. The converter answers a `Uint8Array` and
+ * needs no name for the wrapper; a reader that had to import the
+ * wrapper from a third module would be one more edge for no gain.
+ */
+export interface Float128 {
+    /** The sixteen octets, in the order the wire carries them. */
+    readonly octets: Uint8Array;
+}
+export declare class Writer {
+    readonly order: Endianness;
+    readonly plCdr1: PlCdr1Framing;
+    shortLengthCodes: boolean;
+    private out;
+    private origin;
+    private readonly maxAlignment;
+    /**
+     * A writer in `order` whose alignment is capped at `maxAlign`.
+     *
+     * Four for XCDR2, eight for XCDR1. §7.4.1: `ALIGN(N)` aligns to
+     * `MIN(N, XCDR.maxalign)`. A writer that did not know this padded an
+     * eight-octet primitive to eight under XCDR2 and put four octets on
+     * the wire that no peer expects.
+     */
+    constructor(order: Endianness, maxAlign?: number, plCdr1?: PlCdr1Framing, shortLengthCodes?: boolean);
+    /** The alignment cap in force. */
+    get maxAlign(): number;
+    /** How many octets have been written. */
+    position(): number;
+    /** The octets written so far. */
+    finish(): Uint8Array;
+    /** Pad to `align`, counted from the stream's origin. */
+    alignTo(align: number): void;
+    /**
+     * Move the alignment origin to the current position.
+     *
+     * `ElementPadding::Packed` is HDDS's measured departure from XTypes 1.3
+     * §7.4.1, which counts every element's alignment from the encapsulation:
+     * each collection element and each aggregate value counts its own
+     * alignment from its own first octet instead. `array-1d-struct-final` is
+     * `01000000 0200 03000000 0400 77`, the second `Cell`'s `long` at offset
+     * six where the clause puts it at eight, and `typedef-of-struct` is the
+     * same inside two `@final` members.
+     *
+     * Returns the origin displaced, for {@link finishPackedElement}.
+     */
+    beginPackedElement(): number;
+    /** Restore the origin {@link beginPackedElement} displaced. */
+    finishPackedElement(saved: number): void;
+    private refuse;
+    private check;
+    private checkBig;
+    private raw;
+    /** An integer of `width` octets, in the stream's order. */
+    private writeInt;
+    /**
+     * An integer of `width` octets in a named order, with no alignment.
+     *
+     * The order is an argument because two forms fix it against the
+     * stream: CORBA's length-prefixed `wchar` and the `wstring` unit
+     * orders. Everything else goes through {@link writeInt}.
+     */
+    private rawInt;
+    /** `boolean`, one octet, 0 or 1. */
+    writeBool(value: boolean): void;
+    /** `octet` and `uint8`. */
+    writeU8(value: number): void;
+    /** `int8`. */
+    writeI8(value: number): void;
+    /**
+     * `char`, one octet.
+     *
+     * A code point above 255 is refused rather than truncated: a `char`
+     * field holding `ä` from a UTF-8 source is a mistake worth stopping
+     * on, and `0xe4` is a different character.
+     */
+    writeChar(value: string): void;
+    /**
+     * `wchar`, at `width` octets and in the shape `framing` gives it.
+     *
+     * Two octets under Table 31 and for seven of the nine measured
+     * implementations; four under RTI's XCDR1, under TAO and under
+     * `rosidl_typesupport_fastrtps_c`. The width is an argument of its
+     * own and not a reading of the `wstring` policy, because
+     * `rmw_cyclonedds_cpp` writes two here and four inside a `wstring`.
+     *
+     * The BMP restriction of §7.2.2.2.1.2.5 is a property of the type
+     * and not of the width: the four-octet form zero-extends a code
+     * unit, it does not carry a code point.
+     *
+     * `order` reaches only the length-prefixed form: a scalar cannot
+     * carry a byte order mark, so anything but the stream's order means
+     * CORBA's default, which is big-endian.
+     */
+    writeWchar(value: string, width?: WcharWidth, framing?: WcharFraming, order?: WstringUnitOrder): void;
+    /** `short`. */
+    writeI16(value: number): void;
+    /** `unsigned short`. */
+    writeU16(value: number): void;
+    /** `long`. */
+    writeI32(value: number): void;
+    /** `unsigned long`. */
+    writeU32(value: number): void;
+    /** `long long`, which is a `bigint` because a binary64 is not one. */
+    writeI64(value: bigint): void;
+    /** `unsigned long long`. */
+    writeU64(value: bigint): void;
+    /**
+     * The Cyclone union overlay: the low `octets` of `pattern`, written
+     * as one unsigned integer of that width in the stream's byte order.
+     *
+     * A discriminator carrying a label the `union-labels` dialect axis
+     * says selects nothing makes the peer fall through to `default:` and
+     * serialise its one C union storage *as that arm* — the selected
+     * member's octets, reinterpreted. The pattern is the `bigint` whose
+     * little-endian bytes are the selected member's little-endian
+     * storage octets, zero-extended; the `bitPattern*` functions
+     * produce it.
+     */
+    writeUnionOverlay(pattern: bigint, octets: number): void;
+    /**
+     * `float`, a binary32.
+     *
+     * The value is rounded once, here, and not by the caller: a `number`
+     * is a binary64 and the narrowing is part of writing the field.
+     */
+    writeF32(value: number): void;
+    /** `double`, a binary64. */
+    writeF64(value: number): void;
+    /**
+     * `long double`, as the sixteen octets it is.
+     *
+     * The octets arrive in the order the wire carries them for a
+     * little-endian stream, which is how `ZdFloat128` holds them, and are
+     * reversed for a big-endian one. A `number` never appears: a binary64
+     * would drop sixty bits of the significand.
+     */
+    writeF128(value: Float128): void;
+    /**
+     * `string`: a four-octet length that **includes** the terminator,
+     * then the octets, then a NUL. §7.4.1.1.1.
+     */
+    writeString(value: string): void;
+    /**
+     * A bounded `string`: the same bytes {@link writeString} writes. The
+     * bound is a promise about the source and not a difference on the
+     * wire, so this is the only place it can be enforced — refused rather
+     * than cut at a character boundary, which would put a sample on the
+     * wire nobody wrote. The bound counts octets, which is what a
+     * `string<N>` bound counts for every measured implementation.
+     */
+    writeStringBounded(value: string, bound: number): void;
+    /**
+     * A bounded `wstring`, as {@link writeStringBounded} is to
+     * {@link writeString}. The bound counts UTF-16 code units, not
+     * characters and not octets, whatever `policy` puts on the wire.
+     */
+    writeWstringBounded(value: string, bound: number, policy: WstringLengthPolicy, order: WstringUnitOrder): void;
+    /**
+     * The count check every bounded `sequence` makes before a byte of it
+     * is written. Table 17 makes `O2.length <= T1.length` the condition
+     * for constructing a `sequence<T, N>`, and the wire carries no bound
+     * to compare against: a sender whose count already exceeds its own
+     * declaration has written a value of a type nobody declared.
+     */
+    checkSequenceBound(actual: number, bound: number): void;
+    /**
+     * The count check every bounded `map` makes before a byte of it is
+     * written. Its own message and not {@link checkSequenceBound}'s: the
+     * unit is an entry and not an element, per XTypes 1.3 §7.4.1.1.4's
+     * map-as-a-sequence-of-pairs equivalence.
+     */
+    checkMapBound(actual: number, bound: number): void;
+    /**
+     * `wstring`: a four-octet **octet** count, then UTF-16 code units.
+     *
+     * No BOM and no terminator — §7.4.1.1.2 forbids both outright. The
+     * order the units go out in is the stream's, which the encapsulation
+     * identifier already announced.
+     *
+     * The specification cell of {@link writeWstringUtf8}, kept as a
+     * method of its own because it is the one every reader of this file
+     * looks for.
+     */
+    writeWstring(value: string): void;
+    /**
+     * A `wstring` in the form `policy` and `order` name.
+     *
+     * {@link WstringLengthPolicy.Specification} is a four-octet octet
+     * count and then UTF-16 code units. No BOM and no terminator —
+     * §7.4.1.1.2 forbids both outright: "The UTF-16 representation … shall
+     * not include a Byte Order Mark (BOM). The representation shall also
+     * not include any terminating NUL character(s)."
+     *
+     * The count is of **octets** under that policy and not of characters:
+     * §7.4.1.1.2 says "This is twice the number of characters in the
+     * string", with the clause's own rationale being that a code point
+     * outside the Basic Multilingual Plane takes two units and an octet
+     * count still reaches the end. So `"𝄞"` is a length of four.
+     *
+     * A TypeScript `string` already holds UTF-16 code units, which is the
+     * one thing this column gets for free — `charCodeAt` is the unit and
+     * `codePointAt` the character, and the two differ exactly where the
+     * policies do.
+     */
+    writeWstringUtf8(value: string, policy: WstringLengthPolicy, order: WstringUnitOrder): void;
+    /**
+     * A `wstring` whose characters go out as their own UTF-8 octets.
+     *
+     * `WstringCodeUnits::Utf8` is the measured departure of one product's
+     * generated serialiser: XTypes 1.3 Table 31 gives a `wstring`'s code unit
+     * as `Char16` and §7.4.1.1.2 makes the length "twice the number of
+     * characters", so the clause has no UTF-8 form at all. The declared length
+     * is the UTF-8 octet count and only C2 — the terminator — still reaches
+     * the wire. `wstring-member` is `04 00 00 00 61 62 63 00` for `"abc"`:
+     * three octets, a NUL, and the four declares both.
+     */
+    writeWstringUtf8Octets(value: string, policy: WstringLengthPolicy): void;
+    /**
+     * A bounded UTF-8-octet `wstring`. The bound still counts UTF-16 code
+     * units, which is what a `wstring<N>` bound means, while the wire carries
+     * the UTF-8 octets.
+     */
+    writeWstringUtf8OctetsBounded(value: string, bound: number, policy: WstringLengthPolicy): void;
+    /**
+     * Refuses a `wstring<N>` value longer than its bound. The bound counts
+     * UTF-16 code units, whatever form the wire carries.
+     */
+    private checkWstringBound;
+    /** One `wstring` code unit, at its width and in its order. */
+    private writeWstringUnit;
+    /**
+     * `fixed<digits, scale>` as packed BCD. [CDR] §9.3.2.8.
+     *
+     * DDS-XTypes 1.3 does not carry the type at all — §7.2.2 has no
+     * fixed-point kind and §7.4.3.5.3 has no rule whose left-hand side
+     * matches one — so the form is CORBA's, which is where an IDL `fixed`
+     * came from and the only wire definition it has.
+     *
+     * The value arrives as a `string` because a `number` is a binary64 and
+     * `fixed<31, 2>` is exactly the case a binary64 cannot carry. It is
+     * not parsed through anything either: a parser that accepted an
+     * exponent or normalised a scale would change the digit count, which
+     * is the measured axis {@link FixedDigitCount} names.
+     *
+     * Aligned to one. [CDR] §9.3.2.8 gives a fixed-point value an
+     * alignment of one octet, so a `fixed` never pads.
+     */
+    writeFixed(value: string, digits: number, scale: number, count: FixedDigitCount): void;
+    /**
+     * The BCD nibbles of `text` under `fixed<digits, scale>`.
+     *
+     * [CDR] §9.3.2.8: digit nibbles most-significant first, then a sign
+     * nibble — `0xc` for positive or zero, `0xd` for negative — with a
+     * leading zero nibble prepended when the nibble count is odd so the
+     * nibbles pair up.
+     *
+     * Neither half is padded in the direction that would lose a digit: a
+     * value too long for its integer part or its fraction is one this type
+     * cannot represent, and is refused.
+     *
+     * How many digits go out is {@link FixedDigitCount}: the clause gives
+     * the packing and says nothing about the count, and the four
+     * implementations that write a `fixed` split two and two.
+     */
+    private fixedNibbles;
+    /** A DHEADER: a four-octet length of what follows. §7.4.3.5.3. */
+    writeDheader(): DHeader;
+    /**
+     * Patch a DHEADER with the length of what followed it.
+     *
+     * A header from {@link noDheader} is not there and is ignored, which
+     * is what lets a generated codec write the same two lines for a
+     * `@final` aggregate and an `@appendable` one.
+     */
+    finishDheader(header: DHeader): void;
+    /**
+     * An XCDR2 EMHEADER: the member id, its length code and the
+     * must-understand flag in one 32-bit word. §7.4.3.4.2.
+     *
+     * The length code is the layout plan's decision and arrives here as
+     * a number; this runtime does not choose one.
+     *
+     * LC0 through LC3 carry the length in the code itself. LC4 is
+     * followed by a NEXTINT. LC5 through LC7 also have one, and
+     * §7.4.3.4.2 says it "shall be reused also as part of the serialized
+     * member", so no placeholder is reserved for them: the member's own
+     * leading word lands in that position and *is* the NEXTINT.
+     */
+    writeEmheader(memberId: number, lengthCode: number, mustUnderstand: boolean): EmHeader;
+    /**
+     * Patch an EMHEADER's NEXTINT with the length of what followed.
+     *
+     * Under {@link shortLengthCodes} an LC4 header whose member turned
+     * out to be 1, 2, 4 or 8 octets instead loses its NEXTINT and states
+     * the length in the code, which is what Fast DDS does.
+     */
+    finishEmheader(header: EmHeader): void;
+    /**
+     * Remove an LC4 header's NEXTINT and raise its length code.
+     *
+     * Every octet of the member's value is unchanged and only its
+     * position moves, which is safe for one reason and only under XCDR2:
+     * MAXALIGN is four there, so the value began at a four-aligned
+     * offset with the NEXTINT in front of it and begins at a four-aligned
+     * offset without it.
+     */
+    private shortenEmheader;
+    /**
+     * A PL_CDR1 parameter header, short form: `[id:u16][length:u16]`.
+     *
+     * `mustUnderstand` is bit 14 of the id. §7.4.1.2.2: the flag "shall
+     * be set if and only if the must_understand property of the member is
+     * set to true".
+     */
+    writePid(pid: number, role?: ParameterRole, mustUnderstand?: boolean): Pid;
+    /**
+     * A PL_CDR1 parameter header, extended form.
+     *
+     * `[PID_EXTENDED][8][id:u32][length:u32]`, required when the id
+     * reaches the reserved range or the value is longer than `0xFFFF`.
+     * §7.4.1.2.
+     */
+    writePidExtended(pid: number, role?: ParameterRole, mustUnderstand?: boolean): Pid;
+    /**
+     * Start a parameter's value, returning the origin it replaces.
+     *
+     * "Each element, or parameter, within a parameter list data
+     * structure is simply a CDR-encapsulated block of data" — §7.4.1.2.
+     * A block counts alignment from its own start, so an eight-octet
+     * member at the head of one is already aligned and takes no padding
+     * inside its own length.
+     */
+    private beginParameterValue;
+    /**
+     * Patch a parameter header with its value's length.
+     *
+     * The declared length covers the value's trailing padding or stops at
+     * the value, depending on the framing — and which of the two framing
+     * flags answers is the header's own {@link Pid.role}, not an argument
+     * the caller has to remember. A generated codec calls
+     * `w.finishPid(h)`, exactly as the C and Java columns do; a runtime
+     * that took the answer as a defaulted parameter never reached
+     * `padsOptionalLength` at all.
+     *
+     * The padding itself starts the next parameter at a four-octet offset
+     * measured from the enclosing stream, so the origin goes back before
+     * it is written.
+     */
+    finishPid(header: Pid): void;
+    /**
+     * Rewrite a short parameter header as the extended form.
+     *
+     * §7.4.1.2.2's `ssize` is sixteen bits, and which values overrun it is
+     * a property of the sample rather than of the type. So the plan writes
+     * the short form for an unbounded member and the fallback lives here,
+     * where the length is known. Without it a value over 64 KiB had its
+     * length silently truncated to sixteen bits and the payload still
+     * looked well-formed — a reader would take the next parameter from
+     * inside this one.
+     *
+     * Eight octets are inserted between the header and the value. The
+     * value's own octets do not change: XCDR1's MAXALIGN is eight and the
+     * insertion is eight, so every offset inside it keeps its remainder.
+     */
+    private promotePid;
+    /** The `[PID_LIST_END][0]` that ends a parameter list. §7.4.1.2.4. */
+    writeSentinel(): void;
+    /**
+     * An enumerator, as the integer its bit bound calls for.
+     *
+     * §7.4.3.5.3 rule (5) is
+     * `XCDR << {O : ENUM_TYPE} = XCDR << {O.value : O.holder_type}`, and
+     * the ENUM_TYPE row of the same clause's table says "O.holder_type is
+     * either Int8, Int16 or Int32 depending on the value of the
+     * `@bit_bound` annotation". A **signed** holder: `@value(-1)` is the
+     * two's complement of one, so at the default bound it goes out as
+     * `ffffffff`.
+     *
+     * What fits is everything expressible in the bound's bits, signed or
+     * unsigned — `-2^(n-1) ..= 2^n - 1`. RTI Connext 7.7 accepts
+     * `@value(-1)` at the default bound and Cyclone accepts `@value(200)`
+     * under `@bit_bound(8)`; a signed-only range would reject the second
+     * and a wider one would accept values neither can express.
+     *
+     * §7.3.1.2.1.5 caps the bound itself at 1 to 32, so a bound outside
+     * that has no holder and is refused rather than widened.
+     *
+     * The bound comes **first**, which is the order the shared walk in
+     * `crates/lang-rules/src/emit/encode.rs` calls it in and the order
+     * `zdw_write_enum` and Java's `writeEnum` take. When both arguments
+     * were a `number` a swapped pair was a legal call that wrote a
+     * plausible octet — the Java column found exactly that, at run time.
+     *
+     * The value is a `bigint` and the bound a `number`, which is the same
+     * widened holder `zdw_write_enum`'s `int64_t` and Java's `long` are:
+     * the walk casts the enumerator to `Scalar::Int64` before the call, so
+     * the two arguments now have different types and a swap does not
+     * compile.
+     */
+    writeEnum(bitBound: number, value: bigint): void;
+    /**
+     * A bitmask, as the unsigned integer its bit bound calls for.
+     *
+     * §7.4.3.5.3 rule (6) writes `O.value` as `O.holder_type`, and Table
+     * 33 of §7.4.1.1.3.2 gives the holder: `UInt8` for a bound of 1 to 8,
+     * `UInt16` to 16, `UInt32` to 32 and `UInt64` to 64. The same clause
+     * fixes the direction — "Bit indexes are counted from zero starting at
+     * the least-significant bit of the full byte size of the bitmask" — so
+     * bit `n` is `1 << n` whatever the holder's width.
+     *
+     * A bit at or past the bound is refused: the clause says those bits
+     * "are not considered to be part of the bitmask", so setting one would
+     * put a value on the wire no peer must read back.
+     *
+     * The value is a `bigint` at every bound and not only at 64, because
+     * the caller is a generated codec that casts once. The bound comes
+     * first, as it does for {@link writeEnum}.
+     */
+    writeBitmask(bitBound: number, bits: bigint): void;
+    /**
+     * One bitfield, shifted into the accumulator a bitset packs into.
+     *
+     * The counterpart of `zdw_bitfield` and of Java's `Writer.bitfield`.
+     * A method of the writer and not a free function, because the shared
+     * walk emits it as a call on the writer — `call_expr` in
+     * `crates/lang-rules/src/emit/encode.rs` is `T::runtime("w", …)` — and
+     * a free function of that name would be a second `bitfield` the
+     * generated code never reaches.
+     *
+     * A value wider than the field is refused rather than masked: masking
+     * would put a different number on the wire than the caller asked for,
+     * and the caller would never find out.
+     */
+    bitfield(value: bigint, width: number, position: number): bigint;
+    /**
+     * A bitset, as the anchor integer its bitfields pack into.
+     *
+     * DDS-XTypes 1.3 has no serialisation rule for a bitset — §7.4.3.5.3
+     * runs from rule (1) to rule (30) and no left-hand side matches one.
+     * How wide the anchor is comes from the layout planner and arrives
+     * here as a count of **octets**, not of bits: `zerodds_ast_layout`'s
+     * `Extent::Sized` is an octet count and the shared walk passes it
+     * through. A runtime that read it as a bit count answered "8" for an
+     * eight-octet anchor and wrote one octet where the plan said eight.
+     */
+    writeBitset(anchorOctets: number, bits: bigint): void;
+    private patch;
+    private read;
+    /**
+     * The holder as a KeyHash, zero-padded to sixteen octets.
+     *
+     * For a holder of sixteen octets or fewer. DDSI-RTPS 2.5 §9.6.3.8.
+     */
+    zeroPadded(): Uint8Array;
+    /**
+     * The MD5 of the holder, for one longer than sixteen octets.
+     *
+     * MD5 because DDSI-RTPS 2.5 §9.6.3.8 names it, not as a security claim:
+     * the KeyHash identifies an instance and is not a signature.
+     */
+    md5(): Uint8Array;
+}
+/**
+ * The MD5 a KeyHash is made of. RFC 1321.
+ *
+ * Hand-rolled rather than a call into a platform digest, for the same
+ * reason `runtime/csharp`'s `Md5.cs` gives and not `runtime/java`'s: this
+ * runtime is isomorphic (Node, a browser, `runtime/typescript`'s own WASM
+ * bridge in `wasm.ts`), and the Web Crypto API a browser exposes has no
+ * MD5 at all — `SubtleCrypto.digest` supports only the SHA family — so
+ * there is no single platform primitive to call from every environment
+ * this package runs in, unlike Java's `MessageDigest` or even C#'s
+ * FIPS-mode-sensitive one. `WireSelfTest`'s Java and C# counterparts check
+ * RFC 1321's own test vectors; `against-recorded-values.ts` does the same
+ * here, so the arithmetic is asserted and not assumed.
+ *
+ * Not a security primitive here and not used as one: the specification
+ * names MD5 for this, and a different digest would produce hashes that no
+ * other vendor agrees with. DDSI-RTPS 2.5 §9.6.3.8.
+ */
+export declare function md5(input: Uint8Array): Uint8Array;
+/**
+ * The low `octets` of `value`'s two's-complement bits, zero-extended —
+ * {@link Writer.writeUnionOverlay}'s pattern for an integer, character,
+ * enumeration or bitmask arm. The mask is the function: `-2` in four
+ * octets has to come out `0x00000000fffffffen`.
+ */
+export declare function bitPatternInt(value: bigint, octets: number): bigint;
+/** One octet, 0 or 1 — the boolean overlay pattern. */
+export declare function bitPatternBool(value: boolean): bigint;
+/** The IEEE 754 binary32 bits, zero-extended. */
+export declare function bitPatternF32(value: number): bigint;
+/** The IEEE 754 binary64 bits. */
+export declare function bitPatternF64(value: number): bigint;