@fairfox/polly 0.20.1 → 0.22.0

package/dist/src/shared/lib/pairing.d.ts

@@ -0,0 +1,170 @@
+/**
+ * pairing — Phase 2 first-cut pairing flow for $meshState.
+ *
+ * Two devices that want to share a $meshState document must exchange three
+ * things before sync can begin: the issuer's Ed25519 signing public key
+ * (so the receiver can verify ops authored by the issuer), the symmetric
+ * document encryption key (so both sides can encrypt and decrypt the
+ * shared document), and the issuer's stable peer id (so the receiver
+ * knows which entry in its keyring the public key belongs to). This
+ * module packs all three into a {@link PairingToken}, serialises it to a
+ * compact binary format suitable for QR codes or copy-paste, and provides
+ * the matching parse-and-apply flow on the receiving side.
+ *
+ * Threat model: pairing tokens are transmitted over an out-of-band channel
+ * that the user can authenticate visually — typically a QR code on the
+ * issuer's device, scanned by the receiver. Because anyone with the token
+ * can decrypt and impersonate, the OOB channel is the only authentication.
+ * The token includes a TTL (default 10 minutes) so that a token displayed
+ * briefly and then dismissed cannot be replayed by an attacker who later
+ * gains access to a screenshot. A production deployment would layer a
+ * Short Authentication String (SAS) on top — both devices display a code
+ * derived from the shared state, and the user verifies they match — but
+ * that is a follow-up.
+ *
+ * The pairing flow is one-way in the Phase 2 first cut. The issuer
+ * generates a token and displays it; the receiver applies it and picks
+ * up the issuer's keys. The receiver's own keys reach the issuer through
+ * the access set: when the receiver sends its first signed op, the issuer
+ * records the receiver's public key alongside its peer id and adds it to
+ * the keyring. A bidirectional pairing flow that exchanges both sides'
+ * keys in a single QR exchange is straightforward to add later but adds
+ * UX surface area that is not needed for the mesh transport to work.
+ */
+import type { MeshKeyring } from "./mesh-network-adapter";
+import { type SigningKeyPair } from "./signing";
+/** Current pairing-token format version. Bumped if the wire format changes. */
+export declare const PAIRING_TOKEN_VERSION = 1;
+/** Magic header bytes for sanity-checking parsed tokens. ASCII "PPT1". */
+export declare const PAIRING_TOKEN_MAGIC: Uint8Array<ArrayBuffer>;
+/** Length of the random nonce embedded in every token. */
+export declare const PAIRING_NONCE_BYTES = 16;
+/** Default TTL applied when {@link createPairingToken} is called without an
+ * explicit `ttlMs` option. */
+export declare const DEFAULT_PAIRING_TTL_MS: number;
+/**
+ * The contents of a pairing token. Both sides operate on this shape; the
+ * binary serialisation is purely for transport.
+ */
+export interface PairingToken {
+    /** Format version. {@link PAIRING_TOKEN_VERSION} at the time of writing. */
+    version: number;
+    /** Stable peer id of the issuing device. The receiver records this as
+     * the lookup key for the issuer's public key in its keyring. */
+    issuerPeerId: string;
+    /** Issuer's Ed25519 signing public key (32 bytes). */
+    issuerPublicKey: Uint8Array;
+    /** Shared document encryption key (32 bytes). The receiver stores this
+     * under {@link documentKeyId} in its keyring. */
+    documentKey: Uint8Array;
+    /** Identifier under which the receiver stores the document key. For the
+     * Phase 2 first cut this is typically the well-known DEFAULT_MESH_KEY_ID
+     * from mesh-network-adapter; per-document keys (one entry per Automerge
+     * document) are a follow-up. */
+    documentKeyId: string;
+    /** Unix timestamp (milliseconds) after which the token is considered
+     * expired and {@link applyPairingToken} refuses to use it. */
+    expiresAt: number;
+    /** 16-byte random nonce. Carried through serialisation so two tokens
+     * with otherwise-identical contents are still distinguishable. */
+    nonce: Uint8Array;
+}
+/** Errors thrown by the pairing subsystem. */
+export declare class PairingError extends Error {
+    readonly code: "expired" | "wrong-magic" | "unknown-version" | "truncated" | "invalid-public-key" | "invalid-document-key" | "invalid-nonce";
+    constructor(message: string, code: PairingError["code"]);
+}
+/**
+ * Options for {@link createPairingToken}. The signing identity and the
+ * document key are required; everything else is optional with sensible
+ * defaults.
+ */
+export interface CreatePairingTokenOptions {
+    /** The issuing device's signing keypair. Only the public key ends up in
+     * the token; the secret never leaves the issuer. */
+    identity: SigningKeyPair;
+    /** Stable peer id for the issuing device. */
+    issuerPeerId: string;
+    /** The symmetric document key the receiver should adopt. If omitted, a
+     * fresh key is generated and the caller is responsible for using the
+     * same key on the issuing side too. */
+    documentKey?: Uint8Array;
+    /** Identifier under which the receiver stores the document key. */
+    documentKeyId: string;
+    /** Time-to-live in milliseconds. Defaults to {@link DEFAULT_PAIRING_TTL_MS}. */
+    ttlMs?: number;
+    /** Override the current time. Intended for tests; production code should
+     * not pass this. */
+    now?: () => number;
+}
+/**
+ * Generate a fresh {@link PairingToken}. The token is ready to be
+ * serialised and displayed to the receiver via an OOB channel.
+ */
+export declare function createPairingToken(options: CreatePairingTokenOptions): PairingToken;
+/**
+ * Generate a fresh pairing token *and* a fresh signing keypair in one call.
+ * Convenience for first-time setup where the device has no existing
+ * identity yet. Returns both so the caller can persist the keypair and
+ * then display the token.
+ */
+export declare function createPairingTokenWithFreshIdentity(args: {
+    issuerPeerId: string;
+    documentKeyId: string;
+    ttlMs?: number;
+    now?: () => number;
+}): {
+    identity: SigningKeyPair;
+    token: PairingToken;
+};
+/**
+ * Check whether a token has expired against the current wall-clock time
+ * (or an injected `now`).
+ */
+export declare function isPairingTokenExpired(token: PairingToken, now?: () => number): boolean;
+/**
+ * Apply a parsed and validated token to a {@link MeshKeyring}. Mutates the
+ * keyring in place: adds the issuer's public key to {@link MeshKeyring.knownPeers}
+ * and the document key to {@link MeshKeyring.documentKeys}.
+ *
+ * Throws {@link PairingError} with code "expired" if the token's TTL has
+ * elapsed. The receiver is expected to apply the token promptly after
+ * scanning; rejecting expired tokens prevents replay of long-lived
+ * captures.
+ */
+export declare function applyPairingToken(token: PairingToken, keyring: MeshKeyring, options?: {
+    now?: () => number;
+}): void;
+/**
+ * Serialise a token to a binary blob. The wire format is:
+ *
+ *   [4 bytes:  magic "PPT1"]
+ *   [1 byte:   version]
+ *   [4 bytes BE: issuer id byte length]
+ *   [N bytes:  issuer id UTF-8]
+ *   [32 bytes: issuer public key]
+ *   [32 bytes: document key]
+ *   [4 bytes BE: document key id byte length]
+ *   [M bytes:  document key id UTF-8]
+ *   [8 bytes BE: expiresAt (uint64 milliseconds)]
+ *   [16 bytes: nonce]
+ *
+ * Use {@link encodePairingToken} to round-trip through a base64 string.
+ */
+export declare function serialisePairingToken(token: PairingToken): Uint8Array;
+/**
+ * Inverse of {@link serialisePairingToken}. Throws {@link PairingError} on
+ * malformed input.
+ */
+export declare function parsePairingToken(bytes: Uint8Array): PairingToken;
+/**
+ * Serialise a token and base64-encode it for QR-code or copy-paste display.
+ * The encoding uses the standard base64 alphabet (not URL-safe) because
+ * QR codes encode bytes directly and do not care about URL safety.
+ */
+export declare function encodePairingToken(token: PairingToken): string;
+/**
+ * Decode a base64-encoded pairing token produced by {@link encodePairingToken}.
+ * Throws {@link PairingError} on malformed input.
+ */
+export declare function decodePairingToken(encoded: string): PairingToken;

package/dist/src/shared/lib/peer-relay-adapter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * peer-relay-adapter — Phase 1 client helper for connecting a Polly $peerState
+ * application to an Automerge-Repo relay server over WebSocket.
+ *
+ * The Phase 0 base $crdtState and the Phase 1 $peerState wrapper both consume
+ * a caller-supplied `Repo` via `configurePeerState`. This module provides the
+ * one-call factory that builds a Repo wired to the relay transport: a
+ * `WebSocketClientAdapter` from `@automerge/automerge-repo-network-websocket`
+ * pointed at the server URL, an `IndexedDBStorageAdapter` for client-side
+ * persistence, and a Polly-shaped connection-state signal that the application
+ * can render as a diagnostic UI or feed into reconnection logic.
+ *
+ * The mirror server-side factory is in {@link peer-repo-server}.
+ *
+ * @example
+ * ```ts
+ * import { configurePeerState } from "@fairfox/polly";
+ * import { createPeerStateClient } from "@fairfox/polly";
+ *
+ * const { repo, connectionState } = await createPeerStateClient({
+ *   url: "wss://yourapp.example.com/polly/peer",
+ * });
+ * configurePeerState(repo);
+ *
+ * // connectionState is a Signal<"connecting" | "connected" | "disconnected">
+ * ```
+ */
+import { Repo } from "@automerge/automerge-repo";
+import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
+import { type Signal } from "@preact/signals";
+import { type MeshKeyring } from "./mesh-network-adapter";
+export type PeerRelayConnectionState = "connecting" | "connected" | "disconnected";
+export interface CreatePeerStateClientOptions {
+    /** WebSocket URL of the Polly peer-relay server. Use `ws://` for local
+     * development and `wss://` for any deployment that terminates TLS. */
+    url: string;
+    /** Reconnect interval in milliseconds. Defaults to Automerge-Repo's own
+     * default (5 seconds at the time of writing). */
+    retryInterval?: number;
+    /** Optional storage adapter. Applications running in a browser typically
+     * pass an `IndexedDBStorageAdapter`; tests pass nothing for a local-only
+     * Repo. The default is no storage, which keeps the client purely in-memory. */
+    storage?: ConstructorParameters<typeof Repo>[0] extends infer C ? C extends {
+        storage?: infer S;
+    } ? S : never : never;
+    /** Enable Ed25519 signing on every sync message. Adds Byzantine defence:
+     * a compromised client cannot push unsigned writes through the relay.
+     * Requires a keyring with the local peer's signing identity and the
+     * public keys of peers whose ops should be accepted. The server can
+     * still read and mutate document contents because the payload is
+     * signed, not encrypted. */
+    sign?: boolean;
+    /** Keyring for the signing layer. Required when `sign` is true. */
+    keyring?: MeshKeyring;
+}
+export interface PeerStateClient {
+    /** A configured Repo backed by the WebSocket relay. Pass to
+     * {@link configurePeerState}. */
+    repo: Repo;
+    /** Reactive connection state. Updates as the underlying WebSocket opens,
+     * closes, and reconnects. */
+    connectionState: Signal<PeerRelayConnectionState>;
+    /** The underlying network adapter, exposed for advanced use. */
+    adapter: WebSocketClientAdapter;
+    /** True if the client was constructed with `sign: true`. Used by
+     * $peerState primitives to validate per-primitive sign options. */
+    signEnabled: boolean;
+    /** Disconnect from the relay and tear down the Repo. Awaiting the
+     * returned promise drains the Repo's subsystems cleanly. */
+    close: () => Promise<void>;
+}
+/**
+ * Construct a Polly-flavoured client for the peer-relay transport.
+ *
+ * The returned object includes the Repo, a connection-state signal, the
+ * underlying network adapter, and a close function. Production code typically
+ * passes the Repo to {@link configurePeerState} and renders the connection
+ * state somewhere visible.
+ */
+export declare function createPeerStateClient(options: CreatePeerStateClientOptions): PeerStateClient;

package/dist/src/shared/lib/peer-repo-server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * peer-repo-server — Phase 1 server-side factory for the Polly peer-relay
+ * transport. Constructs an Automerge-Repo `Repo` wired to a WebSocket server
+ * and a NodeFS storage backend, ready to relay sync messages between
+ * connected $peerState clients.
+ *
+ * The "always-on peer" role for $peerState lives here. The server holds a
+ * full Automerge replica of every document, participates in the sync protocol
+ * as an ordinary peer, and persists state to disk so the next process restart
+ * picks up where the previous one left off. Server-side cron, HTTP handlers,
+ * and other compute can open document handles on the returned Repo and mutate
+ * them; mutations propagate to connected clients through the same sync
+ * protocol that handles client-to-client traffic.
+ *
+ * The plan originally called this an "Elysia plugin," but Automerge's
+ * `WebSocketServerAdapter` requires an `isomorphic-ws` `WebSocketServer`
+ * instance — not Elysia's native WebSocket — so the cleanest first cut is a
+ * standalone factory that runs its own `ws` server. Elysia integration for
+ * authenticated upgrades is a Phase 1.1 follow-up that wraps this factory.
+ *
+ * @example
+ * ```ts
+ * import { createPeerRepoServer } from "@fairfox/polly";
+ *
+ * const server = await createPeerRepoServer({
+ *   port: 3030,
+ *   storagePath: "./data/polly-peer",
+ * });
+ *
+ * // Open a document handle on the server's Repo for cron or compute work.
+ * const handle = server.repo.create({ counter: 0 });
+ *
+ * // On shutdown:
+ * await server.close();
+ * ```
+ */
+import { Repo } from "@automerge/automerge-repo";
+import { WebSocketServerAdapter } from "@automerge/automerge-repo-network-websocket";
+import { NodeFSStorageAdapter } from "@automerge/automerge-repo-storage-nodefs";
+import * as ws from "ws";
+type WebSocketServer = ws.WebSocketServer;
+export interface CreatePeerRepoServerOptions {
+    /** Port to listen on. The factory creates its own `WebSocketServer` and
+     * binds to this port. */
+    port: number;
+    /** Filesystem directory for the NodeFS storage adapter. The directory is
+     * created on demand. Defaults to `./automerge-repo-data` (Automerge's own
+     * default). */
+    storagePath?: string;
+    /** Hostname interface to bind to. Defaults to all interfaces. */
+    host?: string;
+    /** Override the `WebSocketServer` instance entirely. When provided, `port`
+     * and `host` are ignored and the caller is responsible for the lifecycle.
+     * Useful for tests that want to bind to a random port. */
+    webSocketServer?: WebSocketServer;
+}
+export interface PeerRepoServer {
+    /** A configured Repo participating as the always-on peer. Server-side
+     * cron and HTTP handlers can open document handles on this directly. */
+    repo: Repo;
+    /** The underlying WebSocket server. Exposed for advanced use such as
+     * health checks or graceful shutdown coordination. */
+    webSocketServer: WebSocketServer;
+    /** The Automerge network adapter wrapping the WebSocket server. */
+    adapter: WebSocketServerAdapter;
+    /** The NodeFS storage adapter writing to {@link CreatePeerRepoServerOptions.storagePath}. */
+    storage: NodeFSStorageAdapter;
+    /** Tear down the server: disconnect peers, flush storage, close the
+     * underlying WebSocket server. Returns a promise that resolves once the
+     * tear-down is complete. */
+    close: () => Promise<void>;
+}
+/**
+ * Construct a Polly peer-relay server. Returns a Repo that participates as
+ * the always-on peer, the underlying WebSocket server and storage adapter
+ * for advanced use, and a close function for orderly shutdown.
+ *
+ * Applications typically call this once at startup, hold the returned
+ * `repo` reference for cron and compute work, and wire the close function
+ * into their process shutdown signal handlers.
+ */
+export declare function createPeerRepoServer(options: CreatePeerRepoServerOptions): Promise<PeerRepoServer>;
+export {};

package/dist/src/shared/lib/peer-state.d.ts

@@ -0,0 +1,117 @@
+/**
+ * peer-state — Phase 1 wrappers exposing $peerState, $peerText, $peerCounter,
+ * and $peerList. These are the application-facing constructors for the middle
+ * resilience tier in RFC-041: every device is a full Automerge replica, the
+ * server included, and server-side code can read and mutate document contents
+ * because the server participates in the data plane as an ordinary peer.
+ *
+ * Each primitive wraps the corresponding Phase 0 base ($crdtState, $crdtText,
+ * $crdtCounter, $crdtList) with three additions:
+ *
+ *   1. The `primitive` label is hard-coded to "peerState" so the
+ *      primitive-registry collision detection knows which family the key
+ *      belongs to.
+ *
+ *   2. A handle factory that resolves the application's logical key to an
+ *      Automerge DocumentId via a per-Repo key map. The first time a key is
+ *      registered, the factory creates a new document on the configured Repo
+ *      and records the mapping. On subsequent constructions of the same key,
+ *      the factory looks up the existing DocumentId and finds the handle.
+ *
+ *   3. The `sign` option field validates that the configured Repo was
+ *      created with signing enabled (via createPeerStateClient with
+ *      `sign: true`). Signing adds Byzantine defence at the transport
+ *      level without preventing the server from reading document
+ *      contents. Encryption is not offered on $peerState because it
+ *      would prevent the server from participating as an Automerge
+ *      peer; applications that want encrypted state should use $meshState.
+ *
+ * The Repo itself is supplied by the application via {@link configurePeerState}
+ * or per-call via the `repo` option. There is no transport in this Phase 1
+ * cut — applications use a local-only Repo and document operations stay
+ * inside the calling process. Phase 1's WebSocket relay adapter will plug in
+ * via the same configuration path; Phase 2's mesh adapter does the same for
+ * $meshState.
+ */
+import type { Repo } from "@automerge/automerge-repo";
+import type { Access } from "./access";
+import { type SpecialisedPrimitive } from "./crdt-specialised";
+import { type CrdtPrimitive } from "./crdt-state";
+import type { Migrations, VersionedDoc } from "./schema-version";
+/** Common option shape across all four $peer* primitives. */
+export interface PeerStateOptions<T> {
+    /** Override the default Repo for this primitive. Useful for tests and for
+     * applications that maintain multiple Repos (rare). */
+    repo?: Repo;
+    /** Request per-op Ed25519 signing for this primitive. Signing is a
+     * transport-level concern: pass `sign: true` to `createPeerStateClient`
+     * to enable it for all primitives on that Repo. Passing `sign: true`
+     * here validates that the configured Repo was created with signing
+     * enabled and throws if it was not. */
+    sign?: boolean;
+    /** Schema version target for the application. Migrations run on load. */
+    schemaVersion?: number;
+    /** Migration table keyed by target version. Required if schemaVersion is set. */
+    migrations?: Migrations;
+    /** Declarative read/write access. Compiled into a server share policy
+     * once the relay transport is wired in. */
+    access?: Access;
+    /** Initial value used when this primitive's key has not been registered
+     * before. Phase 0 callers passed this positionally; Phase 1 application
+     * code does the same. */
+    initialValue?: T;
+}
+/**
+ * Set the default Repo that the $peer* primitives use when no `repo` option
+ * is supplied. Calling this with a new Repo clears the per-Repo key map so
+ * that tests start each scenario with a fresh document space.
+ *
+ * Production code typically calls this once at application startup with a
+ * Repo configured for the relay transport. Tests call it before each scenario
+ * with an in-memory Repo.
+ */
+export declare function configurePeerState(repo: Repo, options?: {
+    signEnabled?: boolean;
+}): void;
+/**
+ * Reset the peer-state subsystem to its initial unconfigured state. Intended
+ * for tests; production code should not call this.
+ */
+export declare function resetPeerState(): void;
+/**
+ * Create a peer-replicated state primitive backed by Automerge. Every device
+ * holds a full replica; the server, when one is configured via the relay
+ * transport, holds one too and participates in the sync protocol as an
+ * ordinary peer. Server-side code can read and mutate document contents.
+ *
+ * @example
+ * ```ts
+ * const settings = $peerState<Settings>("settings", { theme: "dark" });
+ * await settings.loaded;
+ * settings.value = { theme: "light" };
+ * ```
+ */
+export declare function $peerState<T extends VersionedDoc>(key: string, initialValue: T, options?: PeerStateOptions<T>): CrdtPrimitive<T>;
+export interface PeerTextOptions extends Omit<PeerStateOptions<unknown>, "initialValue"> {
+}
+/**
+ * Create a peer-replicated text primitive. Concurrent character-level edits
+ * from peers merge cleanly via Automerge's updateText splicing.
+ */
+export declare function $peerText(key: string, initialValue: string, options?: PeerTextOptions): SpecialisedPrimitive<string>;
+export interface PeerCounterOptions extends Omit<PeerStateOptions<unknown>, "initialValue"> {
+}
+/**
+ * Create a peer-replicated counter primitive. Concurrent increments from
+ * peers commute, so two clients each adding 1 to a counter at 5 produce a
+ * counter at 7 after merging.
+ */
+export declare function $peerCounter(key: string, initialValue: number, options?: PeerCounterOptions): SpecialisedPrimitive<number>;
+export interface PeerListOptions extends Omit<PeerStateOptions<unknown>, "initialValue"> {
+}
+/**
+ * Create a peer-replicated list primitive. The Phase 0 base uses naive
+ * whole-array replacement; Phase 1.1 will refine the write path with
+ * structural diff-to-splice for concurrent insert/remove preservation.
+ */
+export declare function $peerList<T>(key: string, initialValue: T[], options?: PeerListOptions): SpecialisedPrimitive<T[]>;

package/dist/src/shared/lib/primitive-registry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PrimitiveRegistry — runtime namespace collision detection across Polly's
+ * synced state primitives.
+ *
+ * The three primitive families ($sharedState, $peerState, $meshState) each store
+ * data under a developer-chosen logical key. If two different primitives both
+ * claim the same key, the developer almost certainly has a bug: the on-disk
+ * formats are incompatible, no sync happens between them, and whichever primitive
+ * resolves first silently "wins" from the developer's perspective. By the time
+ * the mistake is noticed, data has diverged.
+ *
+ * The registry catches the mistake at the first mismatched registration and
+ * throws a structured error naming the key, both primitives, and (when available)
+ * the call site of each registration. This is run-to-failure by design: a
+ * collision is always a bug, and the failure should be loud.
+ *
+ * Same primitive re-registering the same key is allowed and is a no-op — it
+ * supports hot module reloading and component re-mounts without spurious errors.
+ * Changing the primitive kind of an existing key is still an error; developers
+ * doing that during local HMR should hard-reload to reset the registry.
+ *
+ * @example
+ * ```ts
+ * primitiveRegistry.register("notes", "sharedState", "src/app.ts:10");
+ * primitiveRegistry.register("notes", "peerState", "src/other.ts:22");
+ * // throws PrimitiveCollisionError — names both primitives and both call sites
+ * ```
+ */
+/**
+ * Canonical identifiers for Polly's synced state primitives. The registry
+ * uses these as opaque labels; nothing else in Polly needs to match them.
+ */
+export type PrimitiveKind = "sharedState" | "syncedState" | "persistedState" | "state" | "peerState" | "meshState";
+/**
+ * Thrown when a logical key is registered under more than one primitive.
+ * The message names the key, both primitives, and (when available) the
+ * call site of each registration, so the developer can navigate to both
+ * sites from the error output.
+ */
+export declare class PrimitiveCollisionError extends Error {
+    readonly key: string;
+    readonly firstPrimitive: PrimitiveKind;
+    readonly firstCallSite: string | undefined;
+    readonly secondPrimitive: PrimitiveKind;
+    readonly secondCallSite: string | undefined;
+    constructor(key: string, firstPrimitive: PrimitiveKind, firstCallSite: string | undefined, secondPrimitive: PrimitiveKind, secondCallSite: string | undefined);
+}
+/**
+ * A small Map-backed registry of "logical key → primitive kind". Exported as
+ * a class so tests can construct fresh instances without sharing state; the
+ * module-level {@link primitiveRegistry} singleton is what application code
+ * actually uses.
+ */
+export declare class PrimitiveRegistry {
+    private readonly entries;
+    /**
+     * Register a key under a primitive kind. Re-registering the same key under
+     * the same primitive is a no-op, which is what hot module reloading and
+     * component re-mounts produce.
+     *
+     * @throws {PrimitiveCollisionError} if the key is already registered under
+     *   a different primitive kind.
+     */
+    register(key: string, primitive: PrimitiveKind, callSite?: string): void;
+    /**
+     * True if the key has been registered (under any primitive kind).
+     */
+    has(key: string): boolean;
+    /**
+     * Look up the primitive kind a key is registered under, if any.
+     * Returns undefined for unregistered keys.
+     */
+    kindOf(key: string): PrimitiveKind | undefined;
+    /**
+     * Drop every registration. Intended for test setup and teardown; application
+     * code should not call this.
+     */
+    clear(): void;
+    /**
+     * Number of registered keys. Intended for tests.
+     */
+    get size(): number;
+}
+/**
+ * The process-wide primitive registry. Application code registers here
+ * implicitly via primitive constructors; tests can reset it with `clear()`.
+ */
+export declare const primitiveRegistry: PrimitiveRegistry;