@axpecter/lync 2.3.2 → 3.0.0

package/codec/Text.luau

@@ -0,0 +1,89 @@
+--!strict
+--!optimize 2
+-- Strings and bytes: the two counted kinds, and the five symbol sets the library names.
+
+local Base = require (script.Parent.Base)
+local Legality = require (script.Parent.Legality)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Text = {}
+
+-- Constants -----------------------------------------------------------
+
+--[[
+    The five sets a caller never writes, which is the point of them. A set is a layout, since a
+    symbol's place in it is the index it encodes as, so the order inside each is arbitrary and it is
+    pinned: a preset a caller could spell differently would be two layouts under one name.
+]]
+const ALPHANUM = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+const DIGITS = "0123456789"
+const HEX = "0123456789abcdef"
+
+-- Private -------------------------------------------------------------
+
+--[[
+    A symbol set indexes its own characters, so a character appearing twice is two indices decoding
+    to one value and an encode with no answer to give. Walked a byte at a time because the set is
+    bytes: a character past the ASCII range is several of them, and each is a symbol.
+]]
+local function symbolic (symbols: string)
+    if type (symbols) ~= "string" then
+        Log.refuse (`an alphabet takes a symbol set, not a {typeof (symbols)}`)
+    end
+    if symbols == "" then Log.refuse ("an alphabet takes at least one symbol") end
+
+    local seen = {}
+    for at = 1, #symbols do
+        local byte = string.byte (symbols, at)
+        if seen[byte] ~= nil then
+            Log.refuse (`an alphabet takes each symbol once, and {string.char (byte)} is twice`)
+        end
+        seen[byte] = true
+    end
+end
+
+local function alphabet (symbols: string, min: number, max: number): Types.Codec<string>
+    symbolic (symbols)
+    Legality.counts ("str", min, max)
+
+    return Base.make ("str", { symbols = symbols, min = min, max = max })
+end
+
+-- A preset is one of the sets above with the general form behind it, so every set is one path.
+local function preset (symbols: string): (number, number) -> Types.Codec<string>
+    return function (min: number, max: number): Types.Codec<string>
+        return alphabet (symbols, min, max)
+    end
+end
+
+-- The bare name, reached through the metamethod, which is handed the table before the bounds.
+local function called (_: any, min: number, max: number): Types.Codec<string>
+    Legality.counts ("str", min, max)
+    return Base.make ("str", { min = min, max = max })
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    One name carrying seven forms: the bare one, the general alphabet, and the five presets. What
+    tells a plain string from an alphabet downstream is whether a symbol set was recorded.
+]]
+Text.str = table.freeze (setmetatable ({
+    alphabet = alphabet,
+    alphanum = preset (ALPHANUM),
+    base32 = preset (BASE32),
+    base64 = preset (BASE64),
+    digits = preset (DIGITS),
+    hex = preset (HEX),
+}, { __call = called }))
+
+-- Bytes nobody opens, counted the same way and carrying no set to be outside of.
+function Text.buffer (min: number, max: number): Types.Codec<buffer>
+    Legality.counts ("buffer", min, max)
+    return Base.make ("buffer", { min = min, max = max })
+end
+
+return table.freeze (Text)

package/codec/init.luau

@@ -0,0 +1,39 @@
+--!strict
+--!optimize 2
+-- Every constructor a schema is written from, in one frozen table.
+
+local Composites = require (script.Composites)
+local Datatypes = require (script.Datatypes)
+local Scalars = require (script.Scalars)
+local Text = require (script.Text)
+
+local Codecs = {
+    bool = Scalars.bool,
+    int = Scalars.int,
+    quant = Scalars.quant,
+    angle = Scalars.angle,
+    f32 = Scalars.f32,
+    f64 = Scalars.f64,
+    vlq = Scalars.vlq,
+    vli = Scalars.vli,
+
+    str = Text.str,
+    buffer = Text.buffer,
+
+    struct = Composites.struct,
+    array = Composites.array,
+    map = Composites.map,
+    optional = Composites.optional,
+    tagged = Composites.tagged,
+    enum = Composites.enum,
+    bitfield = Composites.bitfield,
+
+    vec2 = Datatypes.vec2,
+    vec3 = Datatypes.vec3,
+    cframe = Datatypes.cframe,
+    rotation = Datatypes.rotation,
+    color3 = Datatypes.color3,
+    inst = Datatypes.inst,
+}
+
+return table.freeze (Codecs)

package/index.d.ts

@@ -0,0 +1,285 @@
+/// <reference types="@rbxts/types" />
+
+declare namespace Lync {
+    /** Opaque codec brand. `_nominal_codec` never exists at runtime. */
+    interface Codec<T> {
+        /** @hidden */ readonly _nominal_codec: T;
+        /** Runs on decode. Return a reason to reject or nil to accept. The first reason wins. */
+        validate(this: Codec<T>, check: (value: T, context: ValidateContext) => string | undefined): Codec<T>;
+        /** Set fields only. The field never decreases, and an update that would lower it throws. */
+        monotonic(this: Codec<number>): Codec<number>;
+        /** Set fields only: lossy latest-wins replication, rate-capped when hz is given. */
+        newest(this: Codec<T>, hz?: number): Codec<T>;
+        /** Domain transform: `to` lifts after decode, `from` lowers before encode. */
+        as<U>(this: Codec<T>, to: (value: T) => U, from: (value: U) => T): Codec<U>;
+    }
+
+    /** Reused between decodes, so copy anything kept. */
+    interface ValidateContext {
+        readonly player?: Player;
+        readonly now: number;
+        readonly last?: number;
+    }
+
+    interface Connection {
+        readonly connected: boolean;
+        disconnect(this: Connection): void;
+    }
+
+    /** @hidden */ interface None {
+        readonly _nominal_none: never;
+    }
+    /** @hidden */ interface All {
+        readonly _nominal_all: never;
+    }
+    /** @hidden */ interface Except {
+        readonly _nominal_except: never;
+    }
+
+    type Recipient = All | Player | ReadonlyArray<Player> | Group | Except;
+
+    type LogKind = "warn" | "error" | "debug";
+    type Cause = "removed" | "cleared";
+    type OutcomeCode = "timeout" | "unanswered" | "leave" | "shutdown";
+
+    interface OutcomeData {
+        readonly definition: string;
+        readonly elapsed?: number;
+    }
+
+    interface LogData {
+        readonly [key: string]: unknown;
+        readonly file: string;
+        readonly line: number;
+        readonly player?: Player;
+        readonly definition?: string;
+    }
+
+    interface DefinitionStats {
+        readonly sent: number;
+        readonly sentBytes: number;
+        readonly received: number;
+        readonly receivedBytes: number;
+        readonly drops: number;
+    }
+
+    interface Stats {
+        readonly flushes: number;
+        readonly sentBytes: number;
+        readonly receivedBytes: number;
+        readonly drops: number;
+        readonly definitions: ReadonlyMap<string, DefinitionStats>;
+    }
+
+    interface Packet<T> {
+        /** Declaration: lossy, unordered, every fire still sent. */
+        unreliable(this: Packet<T>): Packet<T>;
+        /** Declaration: lossy latest-wins, rate-capped when hz is given. */
+        newest(this: Packet<T>, hz?: number): Packet<T>;
+        /** Declaration: stamps every fire with its flush's shared send instant. */
+        timestamped(this: Packet<T>): Packet<T>;
+        fireServer(this: Packet<T>, value: T): void;
+        fireClient(this: Packet<T>, recipient: Recipient, value: T): void;
+        /** `sent` is the fire's instant, and arrives only where the packet declared a stamp. */
+        onServer(this: Packet<T>, fn: (value: T, player: Player, sent?: number) => void): Connection;
+        /** `sent` is the fire's instant, and arrives only where the packet declared a stamp. */
+        onClient(this: Packet<T>, fn: (value: T, sent?: number) => void): Connection;
+        describe(this: Packet<T>): string;
+    }
+
+    /** The completion triple: `(true, reply)` or `(false, code, data)`, never a throw. */
+    type Outcome<R> = (...result: [true, R] | [false, OutcomeCode, OutcomeData]) => void;
+
+    interface Query<Q, R> {
+        /** The one responder for client requests. What it returns is the reply. Before start only. */
+        onServer(this: Query<Q, R>, fn: (value: Q, player: Player) => R): void;
+        /** The one responder for server requests. Before start only. */
+        onClient(this: Query<Q, R>, fn: (value: Q) => R): void;
+        /** Server form. Never yields, and `complete` receives the outcome exactly once. */
+        request(
+            this: Query<Q, R>,
+            client: Player,
+            value: Q,
+            complete: Outcome<R>,
+            timeout?: number,
+        ): void;
+        /** Client form: yields until the reply or an outcome code. No ending throws, and it never hangs. */
+        request(
+            this: Query<Q, R>,
+            value: Q,
+            timeout?: number,
+        ): LuaTuple<[true, R] | [false, OutcomeCode, OutcomeData]>;
+        describe(this: Query<Q, R>): string;
+    }
+
+    /** `Lync.none` clears an optional field. A required field rejects it at the type level. */
+    type Update<T> = {
+        [K in keyof T]?: undefined extends T[K] ? T[K] | None : T[K];
+    };
+
+    type KeyableField<T> = {
+        [K in keyof T]: T[K] extends boolean | number | string ? K & string : never;
+    }[keyof T];
+
+    interface Set<T, K = never> extends Iterable<LuaTuple<[number, T]>> {
+        /** Declaration: partitions records by the field's value. Unkeyed sets have no audiences. */
+        keyBy<F extends KeyableField<T>>(this: Set<T, never>, field: F): Set<T, T[F & keyof T]>;
+        /** On first sight, which is an add, a late join, or a record coming into view. */
+        onAdded(this: Set<T, K>, fn: (id: number, record: T) => void): Connection;
+        onChanged(this: Set<T, K>, fn: (id: number, record: T, old?: T) => void): Connection;
+        onRemoved(this: Set<T, K>, fn: (id: number, cause: Cause) => void): Connection;
+        /** Server only. Throws on a live id. */
+        add(this: Set<T, K>, id: number, record: T): void;
+        /** Server only. Throws on an absent id. */
+        update(this: Set<T, K>, id: number, fields: Update<T>): void;
+        /** Server only. Throws on an absent id. */
+        remove(this: Set<T, K>, id: number): void;
+        /** Server only. Empties the whole set. */
+        clear(this: Set<T, K>): void;
+        /** Server only, keyed sets only. A later assignment replaces the earlier one. */
+        audience(this: Set<T, K>, key: K, recipient: Recipient): void;
+        /** The live record or nil. This is the library's own storage, so read it and never write. */
+        get(this: Set<T, K>, id: number): T | undefined;
+        size(this: Set<T, K>): number;
+        describe(this: Set<T, K>): string;
+    }
+
+    interface Group extends Iterable<Player> {
+        add(this: Group, player: Player): void;
+        remove(this: Group, player: Player): void;
+        has(this: Group, player: Player): boolean;
+        size(this: Group): number;
+        /** Empties the group. Any later use throws. */
+        destroy(this: Group): void;
+    }
+
+    interface Str {
+        (this: void, min: number, max: number): Codec<string>;
+        /** Every character drawn from the symbol set. The smaller the set, the fewer the bits. */
+        alphabet(this: void, symbols: string, min: number, max: number): Codec<string>;
+        alphanum(this: void, min: number, max: number): Codec<string>;
+        base32(this: void, min: number, max: number): Codec<string>;
+        base64(this: void, min: number, max: number): Codec<string>;
+        digits(this: void, min: number, max: number): Codec<string>;
+        hex(this: void, min: number, max: number): Codec<string>;
+    }
+
+    interface Vec3 {
+        (this: void, component?: Codec<number>): Codec<Vector3>;
+        /** A direction at the angular precision. Any nonzero vector normalizes at encode. */
+        unit(this: void, precision: number): Codec<Vector3>;
+        /** A direction at the implied precision and a quantized magnitude. */
+        bounded(this: void, max: number, step: number): Codec<Vector3>;
+    }
+
+    /** Zero, one, two, or three degrees of freedom, in that order. */
+    interface Rotation {
+        none(this: void): Codec<CFrame>;
+        axis(this: void, axis: Vector3, precision: number): Codec<CFrame>;
+        direction(this: void, precision: number): Codec<CFrame>;
+        quat(this: void, precision: number): Codec<CFrame>;
+    }
+
+    interface Color3Codec {
+        (this: void): Codec<Color3>;
+        rgb565(this: void): Codec<Color3>;
+        palette(this: void, colors: ReadonlyArray<Color3>): Codec<Color3>;
+    }
+
+    type Infer<C> = C extends Codec<infer T> ? T : never;
+
+    /** @hidden */ type Flat<T> = { [K in keyof T]: T[K] };
+
+    /** A field whose codec is `optional` is omittable, as a Luau `{ tag: string? }` is. */
+    type Schema<S extends Record<string, Codec<unknown>>> = Flat<
+        { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]> } & {
+            [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]>;
+        }
+    >;
+}
+
+interface LyncModule {
+    /** Opens a namespace. The returned table is pure data, required by both machines. */
+    define<T extends Record<string, Lync.Packet<any> | Lync.Query<any, any> | Lync.Set<any, any>>>(
+        this: void,
+        name: string,
+        defs: T,
+    ): Readonly<T>;
+    /** Seals, compiles, opens transports, runs the handshake. Exactly once per machine. */
+    start(this: void): void;
+    /** Sends everything buffered. Nothing goes out without it, and an empty flush is free. */
+    flush(this: void): void;
+    /** The byte budget caps replicated state only. Packets and requests always send in full. */
+    flush(this: void, maxBytes: number): void;
+    /** One namespace, on a cadence of its own. */
+    flush(this: void, name: string, maxBytes?: number): void;
+    /** One final flush. Outstanding requests resolve as shutdown and the transports go. */
+    close(this: void): void;
+
+    packet<T>(this: void, codec: Lync.Codec<T>): Lync.Packet<T>;
+    query<Q, R>(this: void, request: Lync.Codec<Q>, response: Lync.Codec<R>): Lync.Query<Q, R>;
+    replicate<T extends object>(this: void, struct: Lync.Codec<T>): Lync.Set<T>;
+    group(this: void): Lync.Group;
+
+    readonly all: Lync.All;
+    except(this: void, target: Player | ReadonlyArray<Player> | Lync.Group): Lync.Except;
+    /** The clear sentinel: an update writes it to empty an optional field. */
+    readonly none: Lync.None;
+
+    onLog(this: void, fn: (kind: Lync.LogKind, message: string, data: Lync.LogData) => void): Lync.Connection;
+    /** The default printer. Disconnect it to format records yourself. */
+    readonly console: Lync.Connection;
+    /** A frozen snapshot of monotonic counters, so any two of them diff into exact rates. */
+    stats(this: void, name: string): Lync.Stats;
+
+    bool(this: void): Lync.Codec<boolean>;
+    int(this: void, min: number, max: number): Lync.Codec<number>;
+    quant(this: void, min: number, max: number, step: number): Lync.Codec<number>;
+    /** Degrees, cyclic, wrapping at a whole turn. */
+    angle(this: void, precision: number): Lync.Codec<number>;
+    f32(this: void): Lync.Codec<number>;
+    f64(this: void): Lync.Codec<number>;
+    /** Unsigned integer exact to 2^53. */
+    vlq(this: void): Lync.Codec<number>;
+    /** Signed integer exact to 2^53. */
+    vli(this: void): Lync.Codec<number>;
+    readonly str: Lync.Str;
+    buffer(this: void, min: number, max: number): Lync.Codec<buffer>;
+
+    struct<S extends Record<string, Lync.Codec<unknown>>>(
+        this: void,
+        fields: S,
+    ): Lync.Codec<Lync.Schema<S>>;
+    array<T>(this: void, element: Lync.Codec<T>, min: number, max: number): Lync.Codec<T[]>;
+    map<K, V>(
+        this: void,
+        key: Lync.Codec<K>,
+        value: Lync.Codec<V>,
+        min: number,
+        max: number,
+    ): Lync.Codec<Map<K, V>>;
+    optional<T>(this: void, inner: Lync.Codec<T>): Lync.Codec<T | undefined>;
+    tagged<F extends string, V extends Record<string, Lync.Codec<object>>>(
+        this: void,
+        field: F,
+        variants: V,
+    ): Lync.Codec<
+        { [K in keyof V & string]: { [P in F]: K } & Lync.Infer<V[K]> }[keyof V & string]
+    >;
+    enum<const T extends readonly string[]>(this: void, names: T): Lync.Codec<T[number]>;
+    bitfield<const T extends readonly string[]>(
+        this: void,
+        names: T,
+    ): Lync.Codec<{ [K in T[number]]: boolean }>;
+
+    vec2(this: void, component?: Lync.Codec<number>): Lync.Codec<Vector2>;
+    readonly vec3: Lync.Vec3;
+    cframe(this: void, position: Lync.Codec<Vector3>, rotation: Lync.Codec<CFrame>): Lync.Codec<CFrame>;
+    readonly rotation: Lync.Rotation;
+    readonly color3: Lync.Color3Codec;
+    /** Decodes to the instance or nil when the receiver cannot see it. */
+    inst<T extends Instance = Instance>(this: void, className?: string): Lync.Codec<T | undefined>;
+}
+
+declare const Lync: LyncModule;
+export = Lync;

package/init.luau

@@ -0,0 +1,91 @@
+--!strict
+--!optimize 2
+-- The public binding: every name the surface offers, bound once and frozen.
+
+local Codecs = require (script.codec)
+local Define = require (script.api.Define)
+local Group = require (script.channel.Group)
+local Lifecycle = require (script.api.Lifecycle)
+local Log = require (script.kernel.Log)
+local Packet = require (script.api.Packet)
+local Query = require (script.api.Query)
+local Recipients = require (script.channel.Recipients)
+local Set = require (script.api.Set)
+local Types = require (script.Types)
+-- Types ---------------------------------------------------------------
+
+--[[
+    Infer, Schema, and Update are absent because Luau cannot alias a type function: `export type
+    Infer<C> = Types.Infer<C>` reduces to an error type. A consumer that needs to name one requires
+    the Types module beside this one.
+]]
+
+export type All = Types.All
+export type Cause = Types.Cause
+export type Codec<T> = Types.Codec<T>
+export type Connection = Types.Connection
+export type DefinitionStats = Types.DefinitionStats
+export type Except = Types.Except
+export type Group = Types.Group
+export type LogData = Types.LogData
+export type LogKind = Types.LogKind
+export type None = Types.None
+export type Outcome<R> = Types.Outcome<R>
+export type OutcomeCode = Types.OutcomeCode
+export type OutcomeData = Types.OutcomeData
+export type Packet<T> = Types.Packet<T>
+export type Query<Q, R> = Types.Query<Q, R>
+export type Recipient = Types.Recipient
+export type Set<T> = Types.Set<T>
+export type Stats = Types.Stats
+export type ValidateContext = Types.ValidateContext
+
+-- Public --------------------------------------------------------------
+
+local Lync = {
+    define = Define.define,
+    start = Lifecycle.start,
+    flush = Lifecycle.flush,
+    close = Lifecycle.close,
+    stats = Lifecycle.stats,
+
+    packet = Packet.new,
+    query = Query.new,
+    replicate = Set.new,
+    group = Group.new,
+
+    all = Recipients.ALL,
+    except = Recipients.except,
+    none = Set.NONE,
+
+    onLog = Log.onLog,
+    console = Log.console,
+
+    bool = Codecs.bool,
+    int = Codecs.int,
+    quant = Codecs.quant,
+    angle = Codecs.angle,
+    f32 = Codecs.f32,
+    f64 = Codecs.f64,
+    vlq = Codecs.vlq,
+    vli = Codecs.vli,
+    str = Codecs.str,
+    buffer = Codecs.buffer,
+
+    struct = Codecs.struct,
+    array = Codecs.array,
+    map = Codecs.map,
+    optional = Codecs.optional,
+    tagged = Codecs.tagged,
+    enum = Codecs.enum,
+    bitfield = Codecs.bitfield,
+
+    vec2 = Codecs.vec2,
+    vec3 = Codecs.vec3,
+    cframe = Codecs.cframe,
+    rotation = Codecs.rotation,
+    color3 = Codecs.color3,
+    inst = Codecs.inst,
+}
+
+return table.freeze (Lync)

package/kernel/Bits.luau

@@ -0,0 +1,16 @@
+--!strict
+--!optimize 2
+-- The ranged-int bit width: the bits needed to address a span of values.
+
+local Bits = {}
+
+--[[
+    A logarithm rounds short from two to the forty-ninth up, and a width a bit short encodes cleanly
+    and decodes as a different value.
+]]
+function Bits.width (span: number): number
+    if span <= 0 then return 0 end
+    return (select (2, math.frexp (span)))
+end
+
+return table.freeze (Bits)

package/kernel/Catalog.luau

@@ -0,0 +1,121 @@
+--!strict
+--!optimize 2
+--[[
+    Every diagnosis the library can reach, as the code a caller branches on and the line it reads.
+
+    One home, a code being part of the surface: two spellings of one is a caller's branch that
+    quietly stops matching.
+]]
+
+local Catalog = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    A site raising a code with no row here does not compile, which is the half of a closed
+    catalogue a type checker can hold on its own.
+]]
+export type Code =
+    "drop.tag"
+    | "drop.defid"
+    | "drop.count"
+    | "drop.varint"
+    | "drop.pad"
+    | "drop.map-order"
+    | "drop.sidecar"
+    | "drop.bounds"
+    | "drop.section"
+    | "drop.validate"
+    | "drop.hello"
+    | "drop.unready"
+    | "drop.mismatch"
+
+--[[
+    The template is prose and may be reworded in any release. The keys are what a caller may hold
+    to, each reaching `data` under its own name.
+]]
+export type Entry = {
+    read template: string,
+    read keys: { string },
+}
+
+-- Public --------------------------------------------------------------
+
+-- Every code, under the name a raising site reaches it by.
+Catalog.TAG = "drop.tag" :: Code
+Catalog.DEFID = "drop.defid" :: Code
+Catalog.COUNT = "drop.count" :: Code
+Catalog.VARINT = "drop.varint" :: Code
+Catalog.PAD = "drop.pad" :: Code
+Catalog.MAP_ORDER = "drop.map-order" :: Code
+Catalog.SIDECAR = "drop.sidecar" :: Code
+Catalog.BOUNDS = "drop.bounds" :: Code
+Catalog.SECTION = "drop.section" :: Code
+Catalog.VALIDATE = "drop.validate" :: Code
+Catalog.HELLO = "drop.hello" :: Code
+Catalog.UNREADY = "drop.unready" :: Code
+Catalog.MISMATCH = "drop.mismatch" :: Code
+
+--[[
+    Every row, and the whole of what a drop can be. The first seven are shape violations, six of
+    them saying the field, what the schema wanted and what the bytes had, since there are only
+    three things to say. The last six are about a frame rather than a field and name no path. A
+    section is one row, its ways of failing being settled phrases nobody should branch on.
+]]
+Catalog.entries = table.freeze ({
+    [Catalog.TAG] = table.freeze ({
+        template = "{path} expected {expected}, got {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.COUNT] = table.freeze ({
+        template = "{path} expected a count within {expected}, got {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.VARINT] = table.freeze ({
+        template = "{path} expected {expected}, got a varint that {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.PAD] = table.freeze ({
+        template = "{path} expected nothing but zeroes after {expected}, got {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.MAP_ORDER] = table.freeze ({
+        template = "{path} expected a key above {expected}, got {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.SIDECAR] = table.freeze ({
+        template = "{path} expected {expected}, got an instance of {got}",
+        keys = table.freeze ({ "path", "expected", "got" }),
+    }),
+    [Catalog.VALIDATE] = table.freeze ({
+        template = "{path} was turned away: {reason}",
+        keys = table.freeze ({ "path", "reason" }),
+    }),
+
+    [Catalog.BOUNDS] = table.freeze ({
+        template = "a frame ran past the bytes it arrived with, and said {said}",
+        keys = table.freeze ({ "said" }),
+    }),
+    [Catalog.SECTION] = table.freeze ({
+        template = "a state section is not one this definition could have written, and said {said}",
+        keys = table.freeze ({ "said" }),
+    }),
+    [Catalog.DEFID] = table.freeze ({
+        template = "a frame named definition {id}, and this namespace has {count}",
+        keys = table.freeze ({ "id", "count" }),
+    }),
+    [Catalog.HELLO] = table.freeze ({
+        template = "the handshake lane carried something that is no hello",
+        keys = table.freeze ({}),
+    }),
+    [Catalog.UNREADY] = table.freeze ({
+        template = "a frame arrived before this client was told it could send one",
+        keys = table.freeze ({}),
+    }),
+    [Catalog.MISMATCH] = table.freeze ({
+        template = "this namespace hashes {ours} and the other machine says {theirs}",
+        keys = table.freeze ({ "ours", "theirs" }),
+    }),
+}) :: { [Code]: Entry }
+
+return table.freeze (Catalog)