docs(serialization): document Protobuf in API, site, and CHANGELOG

- docs/API.md: Protobuf subsection under runtime:serialization (Schema/parse/build,
  decoded value shape, proto3 + edition 2023).
- site: re-add the Protobuf section to the API reference page, a new Protobuf
  guide page (/docs/serialization/protobuf) + nav link, and site-meta entries.
- CHANGELOG: [Unreleased] Added — pure-JS reflective Protobuf.

Author: Thanga-Ganapathy

CHANGELOG.md

@@ -6,6 +6,17 @@ pre-`0.1.0` and the public API is unstable.
 
 ## [Unreleased]
 
+### Added
+
+- **`runtime:serialization` — `Protobuf`.** A pure-JS, reflective Protobuf
+  implementation (no native deps, no codegen). `new Protobuf.Schema(proto)`
+  compiles a `.proto` source string (or a `{ filename: source }` map) at runtime
+  — proto3 and edition 2023; proto2-only constructs are rejected — and
+  `schema.parse(messageName, bytes)` / `schema.build(messageName, value)` decode
+  and encode the binary wire format. Decoded objects use camelCase keys, BigInt
+  for 64-bit ints, enum value-names, and `Uint8Array` for bytes; unknown fields
+  are preserved across re-encode. Byte-for-byte verified against protobuf-es.
+
 ### Changed
 
 - **`runtime:parsers` renamed to `runtime:serialization`** (breaking). One module

docs/API.md

@@ -484,18 +484,25 @@ pub/sub topics are follow-ups (D29).
 
 ## `runtime:serialization`
 
-A high-performance parsing and serialization module for structured data formats: XML, YAML, TOML, JSONL, and MessagePack. These parsers are backed by optimized Rust implementations and are exposed via zero-cost host boundaries.
+A high-performance parsing and serialization module for structured data formats: XML, YAML, TOML, JSONL, MessagePack, and Protobuf. The text/binary parsers are backed by optimized Rust implementations; Protobuf is a pure-JS reflective implementation. All are exposed via zero-cost host boundaries.
 
 - **Capability:** None (pure computation)
 - **Status:** Available
 
 ```js
-import { XML, YAML, TOML, MessagePack } from "runtime:serialization";
+import { XML, YAML, TOML, MessagePack, Protobuf } from "runtime:serialization";
 
 const obj = XML.parse("<root><hello>world</hello></root>");
 const yaml = YAML.parse("hello: world");
 const msgpackBytes = new Uint8Array([0x81, 0xa5, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0xa5, 0x77, 0x6f, 0x72, 0x6c, 0x64]);
 const obj2 = MessagePack.decode(msgpackBytes);
+
+const schema = new Protobuf.Schema(`
+  syntax = "proto3";
+  message Hello { string name = 1; }
+`);
+const pbBytes = schema.build("Hello", { name: "world" });
+const pbObj = schema.parse("Hello", pbBytes); // { name: "world" }
 ```
 
 ### Exports
@@ -529,6 +536,16 @@ For XML, it also provides a `DecoderStream`:
 | --- | --- |
 | `new XML.DecoderStream()` | A `TransformStream` that parses XML chunks. |
 
+For Protobuf, schemas are compiled from `.proto` source at runtime (pure JS, reflective — proto3 and edition 2023; proto2-only constructs are rejected):
+
+| Export | Description |
+| --- | --- |
+| `new Protobuf.Schema(proto, opts?)` | Compiles a `.proto` source string (or a `{ filename: source }` map for multi-file schemas with `import`s; the `google/protobuf/*` well-known types resolve automatically). |
+| `schema.parse(messageName, bytes)` | Decodes a `Uint8Array` for the fully-qualified `messageName`. |
+| `schema.build(messageName, value)` | Encodes a JavaScript object into a `Uint8Array`. |
+
+Decoded value shape: camelCase field names; 64-bit integer fields (`int64`/`uint64`/`sint64`/`fixed64`/`sfixed64`) as **BigInt**; enums as their value-name string (unknown numbers kept as numbers); `bytes` as `Uint8Array`; maps as plain objects; nested messages as plain objects. Fields absent on the wire are omitted.
+
 <!-- Reference links -->
 [D27]: ./DECISIONS.md
 

site/app/api/serialization/page.jsx

@@ -9,7 +9,7 @@ const errors = [
 ];
 
 const IMPORT = `import {
-  JSONL, XML, YAML, TOML, MessagePack
+  JSONL, XML, YAML, TOML, MessagePack, Protobuf
 } from "runtime:serialization";`;
 
 const sections = [
@@ -99,9 +99,18 @@ const sections = [
         options: [
           { name: "detailed", type: "boolean", optional: true, default: "false", desc: "If true, returns an object { valid: boolean, error?: string } instead of a boolean, providing the exact syntax error if validation fails." }
         ],
-        ex: `MessagePack.validate(bytes, { detailed: true });` 
+        ex: `MessagePack.validate(bytes, { detailed: true });`
       },
     ]
+  },
+  {
+    title: "Protobuf",
+    desc: "Schema-aware Protobuf parsing and building. Pure-JS and reflective: the .proto is compiled at runtime (proto3 and edition 2023; proto2-only constructs are rejected). Decoded objects use camelCase keys, BigInt for 64-bit ints, enum value-names, and Uint8Array for bytes.",
+    exports: [
+      { sig: "new Protobuf.Schema(proto, options?)", type: "Schema", desc: "Compiles a .proto source string (or a { filename: source } map for multi-file schemas with imports; google/protobuf well-known types resolve automatically).", ex: `const schema = new Protobuf.Schema('syntax = "proto3"; message Hello { string name = 1; }');` },
+      { sig: "schema.parse(messageName, bytes)", type: "(string, Uint8Array) => object", desc: "Decodes a byte array into a JavaScript object for the fully-qualified message name.", ex: `schema.parse("Hello", bytes);` },
+      { sig: "schema.build(messageName, value)", type: "(string, object) => Uint8Array", desc: "Encodes a JavaScript object into a Protobuf byte array.", ex: `schema.build("Hello", { name: "world" });` },
+    ]
   }
 ];
 

site/app/docs/serialization/protobuf/page.jsx

@@ -0,0 +1,73 @@
+import DocsShell from "../../../../components/DocsShell.jsx";
+import CodeBlock from "../../../../components/CodeBlock.jsx";
+
+export default function ProtobufParserDoc() {
+  return (
+    <DocsShell active="/docs/serialization/protobuf">
+      <p className="text-sm font-medium text-brand-600">Guides</p>
+      <h1 className="mt-2 text-4xl font-bold tracking-tight text-zinc-900">
+        Protobuf Processing
+      </h1>
+      <p className="mt-4 text-lg leading-relaxed text-zinc-600">
+        A pure-JavaScript, reflective Protobuf implementation in <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">runtime:serialization</code>. The <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">.proto</code> schema is compiled at runtime — no codegen, no build step. proto3 and edition 2023 are supported; proto2-only constructs are rejected.
+      </p>
+
+      <h2 className="mt-12 text-2xl font-semibold text-zinc-900">
+        Compiling a schema
+      </h2>
+      <p className="mt-2 text-zinc-600 leading-relaxed">
+        Construct a <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">Protobuf.Schema</code> from <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">.proto</code> source. Pass a single string, or a <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">{`{ filename: source }`}</code> map for multi-file schemas with imports.
+      </p>
+      <div className="mt-6">
+        <CodeBlock code={`import { Protobuf } from "runtime:serialization";
+
+const schema = new Protobuf.Schema(\`
+  syntax = "proto3";
+  package shop;
+  message Book {
+    string id = 1;
+    double price = 5;
+    repeated string tags = 8;
+  }
+\`);`} title="protobuf_schema.js" lang="js" />
+      </div>
+
+      <h2 className="mt-12 text-2xl font-semibold text-zinc-900">
+        Building and parsing
+      </h2>
+      <p className="mt-2 text-zinc-600 leading-relaxed">
+        Use <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">schema.build</code> and <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">schema.parse</code> with a fully-qualified message name.
+      </p>
+      <div className="mt-6">
+        <CodeBlock code={`const bytes = schema.build("shop.Book", {
+  id: "bk1",
+  price: 44.95,
+  tags: ["computer", "xml"],
+});
+
+const book = schema.parse("shop.Book", bytes);
+console.log(book.price); // 44.95
+console.log(book.tags);  // ["computer", "xml"]`} title="protobuf_roundtrip.js" lang="js" />
+      </div>
+
+      <h2 className="mt-12 text-2xl font-semibold text-zinc-900">
+        Decoded value shape
+      </h2>
+      <p className="mt-2 text-zinc-600 leading-relaxed">
+        Decoded objects use camelCase field names (or the explicit <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">json_name</code>). 64-bit integer fields surface as <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">BigInt</code>; enums as their value-name string; <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">bytes</code> as <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[13px]">Uint8Array</code>; maps as plain objects. Fields absent on the wire are omitted.
+      </p>
+      <div className="mt-6">
+        <CodeBlock code={`const schema = new Protobuf.Schema(\`
+  syntax = "proto3";
+  enum Status { ACTIVE = 0; ARCHIVED = 1; }
+  message Account { uint64 id = 1; Status status = 2; }
+\`);
+
+const bytes = schema.build("Account", { id: 9007199254740993n, status: "ARCHIVED" });
+const acct = schema.parse("Account", bytes);
+console.log(typeof acct.id);  // "bigint"
+console.log(acct.status);     // "ARCHIVED"`} title="protobuf_types.js" lang="js" />
+      </div>
+    </DocsShell>
+  );
+}

site/components/DocsShell.jsx

@@ -29,6 +29,7 @@ const NAV = [
       { href: "/docs/serialization/toml", label: "TOML Parser" },
       { href: "/docs/serialization/jsonl", label: "JSONL Parser" },
       { href: "/docs/serialization/msgpack", label: "MessagePack Parser" },
+      { href: "/docs/serialization/protobuf", label: "Protobuf Parser" },
     ],
   },
   {

site/src/site-meta.js

@@ -42,7 +42,7 @@ export const PAGES = {
   "/api/fs": { section: "API reference", title: "runtime:fs", description: "Blob-based async file I/O — `file()` handles, `write()`, `readDir`, `stat`, `mkdir`, `remove`, `rename`, and `Glob`; confined to a root jail. Gated on FileRead/FileWrite." },
   "/api/net": { section: "API reference", title: "runtime:net", description: "TCP sockets following the WinterTC Sockets API — `connect()` and `listen()`. Gated on Net/NetListen." },
   "/api/http": { section: "API reference", title: "runtime:http", description: "an HTTP/1.1 server, `serve((request) => response)`, using the Web `Request`/`Response` objects. Gated on NetListen." },
-  "/api/serialization": { section: "API reference", title: "runtime:serialization", description: "high-performance native parsers for JSONL, XML, YAML, and TOML via streams and synchronous functions." },
+  "/api/serialization": { section: "API reference", title: "runtime:serialization", description: "serialization for JSONL, XML, YAML, TOML, MessagePack (native), and Protobuf (pure-JS, reflective)." },
   "/api/websocket": { section: "API reference", title: "runtime:websocket", description: "WebSocket client and server functionality native to the engine." },
 
   // Comparisons
@@ -63,6 +63,7 @@ export const PAGES = {
   "/docs/serialization/xml": { section: "Guides", title: "XML Parsing", description: "synchronous and streaming fast XML processing." },
   "/docs/serialization/yaml": { section: "Guides", title: "YAML Parsing", description: "synchronous robust YAML processing." },
   "/docs/serialization/msgpack": { section: "Guides", title: "MessagePack Parsing", description: "synchronous fast MessagePack processing." },
+  "/docs/serialization/protobuf": { section: "Guides", title: "Protobuf Processing", description: "pure-JS reflective Protobuf (proto3 + edition 2023): runtime .proto compilation, BigInt 64-bit, no codegen." },
 };
 
 // Static trailing sections of llms.txt (not derived from routes).