bazis 0.96.1

package/core/grpc/ProtoCodec.ts

@@ -0,0 +1,225 @@
+import { ProtoReader } from "./ProtoReader";
+import { resolveProtoType, type ProtoSchema, type ProtoField, type ProtoLoaderOptions } from "./ProtoSchema";
+
+type Field = ProtoField & { readonly resolved: string; readonly jsName: string };
+const MAX_BYTES = 64 * 1024 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+/** Local proto3 codec: scalar/nested/repeated/packed/map/oneof fields. */
+export class ProtoCodec {
+  private readonly plans = new Map<string, { fields: Field[]; byNumber: Map<number, Field> }>();
+  constructor(private readonly schema: ProtoSchema, private readonly options: ProtoLoaderOptions) {
+    for (const message of schema.messages.values()) {
+      const fields = message.fields.map((field) => ({
+        ...field, resolved: resolveProtoType(schema, field.type, message.name),
+        jsName: options.keepCase ? field.name : camel(field.name),
+      }));
+      if (new Set(fields.map((field) => field.jsName)).size !== fields.length) throw new TypeError("Protobuf field names collide after case conversion.");
+      this.plans.set(message.name, { fields, byNumber: new Map(fields.map((field) => [field.number, field])) });
+    }
+  }
+
+  encode(name: string, value: unknown, depth = 0): Buffer {
+    this.depth(depth);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Expected protobuf message object.");
+    const input = value as Record<string, unknown>;
+    const fields = this.plans.get(name)?.fields;
+    if (!fields) throw new TypeError("Unknown protobuf message " + name);
+    const parts: Buffer[] = [];
+    let size = 0;
+    const push = (part: Buffer): void => {
+      if ((size += part.length) > MAX_BYTES) throw new TypeError("Protobuf message exceeds 64 MiB.");
+      parts.push(part);
+    };
+    const oneofs = new Set<string>();
+    for (const field of fields) {
+      if (!Object.hasOwn(input, field.jsName) || input[field.jsName] === undefined || input[field.jsName] === null) continue;
+      const item = input[field.jsName];
+      if (field.oneof) {
+        if (oneofs.has(field.oneof)) throw new TypeError("Multiple protobuf oneof values.");
+        oneofs.add(field.oneof);
+      }
+      if (field.mapKey) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) throw new TypeError("Expected protobuf map.");
+        for (const [key, value] of Object.entries(item)) {
+          const keyValue = field.mapKey === "bool" ? key === "true" ? true : key === "false" ? false : invalid("Invalid boolean map key.") : key;
+          const keyBytes = this.scalar(field.mapKey, keyValue, depth + 1);
+          const valueBytes = this.scalar(field.resolved, value, depth + 1);
+          const entry = Buffer.concat([tag(1, this.wire(field.mapKey)), keyBytes, tag(2, this.wire(field.resolved)), valueBytes]);
+          push(tag(field.number, 2)); push(lengthPrefix(entry));
+        }
+      } else if (field.repeated) {
+        if (!Array.isArray(item)) throw new TypeError("Expected repeated protobuf field.");
+        if (field.packed && this.wire(field.resolved) !== 2) {
+          const values: Buffer[] = []; let packedSize = 0;
+          for (const element of item) {
+            const bytes = this.scalar(field.resolved, element, depth + 1);
+            if ((packedSize += bytes.length) > MAX_BYTES) throw new TypeError("Packed protobuf field exceeds limit.");
+            values.push(bytes);
+          }
+          if (item.length) { push(tag(field.number, 2)); push(lengthPrefix(Buffer.concat(values))); }
+        } else for (const element of item) { push(tag(field.number, this.wire(field.resolved))); push(this.scalar(field.resolved, element, depth + 1)); }
+      } else {
+        push(tag(field.number, this.wire(field.resolved)));
+        push(this.scalar(field.resolved, item, depth + 1));
+      }
+    }
+    return Buffer.concat(parts, size);
+  }
+
+  decode(name: string, buffer: Buffer, depth = 0, target?: Record<string, unknown>): Record<string, unknown> {
+    this.depth(depth);
+    if (buffer.length > MAX_BYTES) throw new TypeError("Protobuf message exceeds 64 MiB.");
+    const plan = this.plans.get(name);
+    if (!plan) throw new TypeError("Unknown protobuf message " + name);
+    const result = target ?? {};
+    if (!target) for (const field of plan.fields) {
+      if (field.mapKey && (this.options.defaults || this.options.objects)) set(result, field.jsName, {});
+      else if (field.repeated && (this.options.defaults || this.options.arrays)) set(result, field.jsName, []);
+      else if (this.options.defaults && !field.repeated && !field.mapKey && !field.oneof && !field.optional) set(result, field.jsName, this.default(field.resolved));
+    }
+    const reader = new ProtoReader(buffer);
+    while (!reader.done) {
+      const raw = reader.varint();
+      const number = Number(raw >> 3n), wire = Number(raw & 7n);
+      if (number < 1 || number > 536870911) throw new TypeError("Invalid protobuf field tag.");
+      const field = plan.byNumber.get(number);
+      if (!field) { reader.skip(wire); continue; }
+      if (field.mapKey) {
+        if (wire !== 2) throw new TypeError("Invalid protobuf map wire type.");
+        const entry = new ProtoReader(reader.delimited());
+        let key = this.default(field.mapKey), value = this.default(field.resolved);
+        while (!entry.done) {
+          const entryTag = entry.varint(), number = Number(entryTag >> 3n), wire = Number(entryTag & 7n);
+          if (number === 1) key = this.readScalar(field.mapKey, wire, entry, depth + 1);
+          else if (number === 2) value = this.readScalar(field.resolved, wire, entry, depth + 1);
+          else { if (number < 1) throw new TypeError("Invalid map entry."); entry.skip(wire); }
+        }
+        const map = Object.hasOwn(result, field.jsName) ? result[field.jsName] as Record<string, unknown> : {};
+        set(map, String(key), value); set(result, field.jsName, map);
+      } else if (field.repeated) {
+        const values = Object.hasOwn(result, field.jsName) ? result[field.jsName] as unknown[] : [];
+        if (wire === 2 && this.wire(field.resolved) !== 2) {
+          const packed = new ProtoReader(reader.delimited());
+          while (!packed.done) values.push(this.readScalar(field.resolved, this.wire(field.resolved), packed, depth + 1));
+        } else values.push(this.readScalar(field.resolved, wire, reader, depth + 1));
+        set(result, field.jsName, values);
+      } else {
+        if (field.oneof) {
+          for (const sibling of plan.fields) if (sibling.oneof === field.oneof && sibling !== field) delete result[sibling.jsName];
+          if (this.options.oneofs) set(result, this.options.keepCase ? field.oneof : camel(field.oneof), field.jsName);
+        }
+        const previous = this.schema.messages.has(field.resolved) && Object.hasOwn(result, field.jsName) ? result[field.jsName] as Record<string, unknown> | null : undefined;
+        set(result, field.jsName, this.readScalar(field.resolved, wire, reader, depth + 1, previous ?? undefined));
+      }
+    }
+    return result;
+  }
+
+  private scalar(type: string, value: unknown, depth: number): Buffer {
+    if (this.schema.messages.has(type)) return lengthPrefix(this.encode(type, value, depth));
+    if (this.schema.enums.has(type)) {
+      if (typeof value === "string") {
+        const values = this.schema.enums.get(type)!.values;
+        if (!Object.hasOwn(values, value)) throw new TypeError("Unknown protobuf enum value.");
+        value = values[value];
+      }
+      return varint(BigInt.asUintN(64, integer(value, 32, true)));
+    }
+    if (type === "string") {
+      if (typeof value !== "string") throw new TypeError("Expected protobuf string.");
+      return lengthPrefix(Buffer.from(value, "utf8"));
+    }
+    if (type === "bytes") {
+      if (typeof value === "string") return lengthPrefix(Buffer.from(value, "base64"));
+      if (!(value instanceof Uint8Array) && !Array.isArray(value)) throw new TypeError("Expected protobuf bytes.");
+      return lengthPrefix(Buffer.from(value));
+    }
+    if (type === "bool") {
+      if (typeof value !== "boolean") throw new TypeError("Expected protobuf boolean.");
+      return Buffer.from([value ? 1 : 0]);
+    }
+    if (type === "float" || type === "double") {
+      if (typeof value !== "number") throw new TypeError("Expected protobuf number.");
+      const bytes = Buffer.alloc(type === "float" ? 4 : 8);
+      if (type === "float") bytes.writeFloatLE(value); else bytes.writeDoubleLE(value);
+      return bytes;
+    }
+    const bits = type.endsWith("64") ? 64 : 32;
+    const signed = !type.startsWith("uint") && !type.startsWith("fixed");
+    const number = integer(value, bits, signed);
+    if (type.includes("fixed")) {
+      const bytes = Buffer.alloc(bits / 8);
+      if (bits === 64) bytes.writeBigUInt64LE(BigInt.asUintN(64, number));
+      else bytes.writeUInt32LE(Number(BigInt.asUintN(32, number)));
+      return bytes;
+    }
+    return varint(type.startsWith("sint") ? (number << 1n) ^ (number >> BigInt(bits - 1)) : BigInt.asUintN(64, number));
+  }
+  private readScalar(type: string, wire: number, reader: ProtoReader, depth: number, target?: Record<string, unknown>): unknown {
+    if (wire !== this.wire(type)) throw new TypeError("Incorrect protobuf wire type.");
+    if (this.schema.messages.has(type)) return this.decode(type, reader.delimited(), depth, target);
+    if (type === "string") return utf8.decode(reader.delimited());
+    if (type === "bytes") {
+      const value = reader.delimited();
+      return this.options.bytes === String ? value.toString("base64") : this.options.bytes === Array ? [...value] : Buffer.from(value);
+    }
+    if (type === "double") return reader.bytes(8).readDoubleLE();
+    if (type === "float") return reader.bytes(4).readFloatLE();
+    if (type === "bool") return reader.varint() !== 0n;
+    let value = wire === 1 ? reader.bytes(8).readBigUInt64LE() : wire === 5 ? BigInt(reader.bytes(4).readUInt32LE()) : reader.varint();
+    if (this.schema.enums.has(type)) {
+      const number = Number(BigInt.asIntN(32, value));
+      return this.options.enums === String ? Object.entries(this.schema.enums.get(type)!.values).find(([, n]) => n === number)?.[0] ?? number : number;
+    }
+    const bits = type.endsWith("64") ? 64 : 32;
+    if (type.startsWith("sint")) value = (value >> 1n) ^ -(value & 1n);
+    value = type.startsWith("uint") || type.startsWith("fixed") ? BigInt.asUintN(bits, value) : BigInt.asIntN(bits, value);
+    if (bits === 32 || this.options.longs === Number) return Number(value);
+    return this.options.longs === String ? value.toString() : value;
+  }
+  private wire(type: string): number {
+    if (type === "double" || type.endsWith("fixed64")) return 1;
+    if (type === "float" || type.endsWith("fixed32")) return 5;
+    if (type === "string" || type === "bytes" || this.schema.messages.has(type)) return 2;
+    return 0;
+  }
+  private default(type: string): unknown {
+    if (this.schema.messages.has(type)) return null;
+    if (this.schema.enums.has(type)) return this.options.enums === String ? Object.keys(this.schema.enums.get(type)!.values)[0] : 0;
+    if (type === "string") return "";
+    if (type === "bool") return false;
+    if (type === "bytes") return this.options.bytes === String ? "" : this.options.bytes === Array ? [] : Buffer.alloc(0);
+    if (type.endsWith("64")) return this.options.longs === String ? "0" : this.options.longs === Number ? 0 : 0n;
+    return 0;
+  }
+  private depth(depth: number): void { if (depth > 64) throw new TypeError("Protobuf message nesting exceeds 64."); }
+}
+
+function integer(value: unknown, bits: number, signed: boolean): bigint {
+  if (typeof value === "number" && !Number.isSafeInteger(value)) throw new TypeError("Use bigint or string for exact protobuf 64-bit integers.");
+  if (typeof value !== "number" && typeof value !== "bigint" && (typeof value !== "string" || !/^-?\d+$/.test(value))) throw new TypeError("Expected protobuf integer.");
+  const number = BigInt(value);
+  const min = signed ? -(1n << BigInt(bits - 1)) : 0n;
+  const max = (1n << BigInt(signed ? bits - 1 : bits)) - 1n;
+  if (number < min || number > max) throw new TypeError("Protobuf integer out of range.");
+  return number;
+}
+function varint(value: bigint): Buffer {
+  const bytes: number[] = [];
+  do {
+    const byte = Number(value & 127n); value >>= 7n;
+    bytes.push(value ? byte | 128 : byte);
+  } while (value !== 0n);
+  return Buffer.from(bytes);
+}
+function tag(number: number, wire: number): Buffer { return varint(BigInt(number) * 8n + BigInt(wire)); }
+function lengthPrefix(bytes: Buffer): Buffer {
+  if (bytes.length > MAX_BYTES) throw new TypeError("Protobuf field exceeds 64 MiB.");
+  return Buffer.concat([varint(BigInt(bytes.length)), bytes]);
+}
+function camel(name: string): string { return name.replace(/_([a-z])/g, (_match, letter: string) => letter.toUpperCase()); }
+function set(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+function invalid(message: string): never { throw new TypeError(message); }

package/core/grpc/ProtoParser.ts

@@ -0,0 +1,192 @@
+import type { ProtoSchema, ProtoMessage, ProtoField, ProtoRpc } from "./ProtoSchema";
+
+/** Bounded proto3 parser. Unsupported dialects fail instead of changing the wire contract. */
+export class ProtoParser {
+  private readonly tokens: string[] = [];
+  private cursor = 0;
+  private packageName = "";
+  readonly imports: string[] = [];
+
+  constructor(source: string, private readonly schema: ProtoSchema, private readonly filename: string) {
+    if (source.length > 4 * 1024 * 1024) this.fail("Schema exceeds 4 MiB.");
+    const lexer = /\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[A-Za-z_][A-Za-z_0-9]*|0[xX][0-9a-fA-F]+|\d+|[{}()[\];=.,<>:+-]/gy;
+    let offset = 0;
+    while (offset < source.length) {
+      lexer.lastIndex = offset;
+      const match = lexer.exec(source);
+      if (!match) this.fail("Unexpected character at offset " + offset + ".");
+      const token = match![0];
+      offset = lexer.lastIndex;
+      if (!/^\s|^\/\//.test(token) && !token.startsWith("/*")) this.tokens.push(token);
+    }
+  }
+
+  parse(): void {
+    this.expect("syntax"); this.expect("=");
+    if (this.string() !== "proto3") this.fail("Only syntax = proto3 is supported.");
+    this.expect(";");
+    while (this.peek() !== undefined) {
+      switch (this.take()) {
+        case "package": this.packageName = this.type(); this.expect(";"); break;
+        case "import":
+          if (this.peek() === "public") this.take();
+          if (this.peek() === "weak") this.fail("Weak imports are not supported.");
+          this.imports.push(this.string()); this.expect(";"); break;
+        case "message": this.message(this.packageName, 0); break;
+        case "enum": this.enumeration(this.packageName); break;
+        case "service": this.service(); break;
+        case "option": this.skipStatement(); break;
+        case ";": break;
+        default: this.fail("Unsupported top-level declaration.");
+      }
+    }
+  }
+  private message(parent: string, depth: number): void {
+    if (depth >= 64) this.fail("Schema nesting exceeds 64.");
+    const name = qualify(parent, this.identifier());
+    this.unique(name);
+    const message: ProtoMessage = { name, fields: [] };
+    this.schema.messages.set(name, message);
+    this.expect("{");
+    while (!this.accept("}")) {
+      if (this.accept("message")) this.message(name, depth + 1);
+      else if (this.accept("enum")) this.enumeration(name);
+      else if (this.accept("option") || this.accept("reserved")) this.skipStatement();
+      else if (this.accept("oneof")) {
+        const oneof = this.identifier(); this.expect("{");
+        while (!this.accept("}")) {
+          if (this.accept("option")) this.skipStatement();
+          else message.fields.push(this.field(oneof));
+        }
+      } else if (!this.accept(";")) message.fields.push(this.field());
+    }
+    const numbers = new Set<number>(), names = new Set<string>();
+    for (const field of message.fields) {
+      if (numbers.has(field.number) || names.has(field.name)) this.fail("Duplicate field in " + name + ".");
+      numbers.add(field.number); names.add(field.name);
+      if (field.oneof && message.fields.some((entry) => entry.name === field.oneof)) this.fail("oneof name collides with a field.");
+    }
+  }
+  private field(oneof?: string): ProtoField {
+    const repeated = this.accept("repeated");
+    const optional = this.accept("optional");
+    if (repeated && optional) this.fail("A field cannot be both repeated and optional.");
+    if (oneof && (repeated || optional)) this.fail("oneof fields cannot have labels.");
+    let type: string, mapKey: string | undefined;
+    if (this.accept("map")) {
+      if (repeated || optional || oneof) this.fail("Invalid map field label.");
+      this.expect("<"); mapKey = this.type(); this.expect(","); type = this.type(); this.expect(">");
+      if (!/^(?:u?int(?:32|64)|sint(?:32|64)|s?fixed(?:32|64)|bool|string)$/.test(mapKey)) this.fail("Invalid map key type.");
+    } else type = this.type();
+    const name = this.identifier(); this.expect("=");
+    const number = this.number();
+    if (number < 1 || number > 536870911 || number >= 19000 && number <= 19999) this.fail("Invalid protobuf field number.");
+    let packed = true;
+    if (this.accept("[")) {
+      while (!this.accept("]")) {
+        if (this.accept("packed")) {
+          this.expect("=");
+          const value = this.take();
+          if (value !== "true" && value !== "false") this.fail("Invalid packed option.");
+          packed = value === "true";
+        } else this.skipFieldOption();
+        if (this.peek() !== "]") this.expect(",");
+      }
+    }
+    this.expect(";");
+    return { name, number, type, repeated, optional, oneof, mapKey, packed };
+  }
+  private enumeration(parent: string): void {
+    const name = qualify(parent, this.identifier());
+    this.unique(name);
+    const values: Record<string, number> = Object.create(null);
+    this.expect("{");
+    while (!this.accept("}")) {
+      if (this.accept("option") || this.accept("reserved")) { this.skipStatement(); continue; }
+      if (this.accept(";")) continue;
+      const key = this.identifier(); this.expect("="); const value = this.number();
+      if (value < -2147483648 || value > 2147483647 || Object.hasOwn(values, key)) this.fail("Invalid enum entry.");
+      if (Object.keys(values).length === 0 && value !== 0) this.fail("The first proto3 enum value must be zero.");
+      values[key] = value;
+      if (this.accept("[")) { while (!this.accept("]")) this.take(); }
+      this.expect(";");
+    }
+    if (Object.keys(values).length === 0) this.fail("Empty protobuf enum.");
+    this.schema.enums.set(name, { name, values });
+  }
+  private service(): void {
+    const name = qualify(this.packageName, this.identifier());
+    this.unique(name);
+    const methods: ProtoRpc[] = [];
+    this.expect("{");
+    while (!this.accept("}")) {
+      if (this.accept("option")) { this.skipStatement(); continue; }
+      if (this.accept(";")) continue;
+      this.expect("rpc");
+      const method = this.identifier();
+      if (methods.some((entry) => entry.name === method)) this.fail("Duplicate RPC method.");
+      this.expect("("); const requestStream = this.accept("stream"); const input = this.type(); this.expect(")");
+      this.expect("returns"); this.expect("("); const responseStream = this.accept("stream"); const output = this.type(); this.expect(")");
+      if (this.accept("{")) {
+        while (!this.accept("}")) { this.expect("option"); this.skipStatement(); }
+      } else this.expect(";");
+      methods.push({ name: method, input, output, requestStream, responseStream });
+    }
+    this.schema.services.set(name, methods);
+  }
+  private skipStatement(): void {
+    let depth = 0;
+    while (true) {
+      const token = this.take();
+      if (token === ";" && depth === 0) return;
+      if (["{", "(", "["].includes(token)) depth++;
+      if (["}", ")", "]"].includes(token) && --depth < 0) this.fail("Unbalanced option.");
+      if (depth > 64) this.fail("Option nesting exceeds 64.");
+    }
+  }
+  private skipFieldOption(): void {
+    let depth = 0;
+    while (depth > 0 || this.peek() !== "," && this.peek() !== "]") {
+      const token = this.take();
+      if (["{", "(", "["].includes(token)) depth++;
+      if (["}", ")", "]"].includes(token) && --depth < 0) this.fail("Unbalanced field option.");
+    }
+  }
+  private unique(name: string): void {
+    if (this.schema.messages.has(name) || this.schema.enums.has(name) || this.schema.services.has(name)) this.fail("Duplicate protobuf symbol " + name + ".");
+  }
+  private type(): string {
+    let value = this.accept(".") ? "." : "";
+    value += this.identifier();
+    while (this.accept(".")) value += "." + this.identifier();
+    return value;
+  }
+  private identifier(): string {
+    const value = this.take();
+    if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(value)) this.fail("Expected identifier.");
+    return value;
+  }
+  private number(): number {
+    const sign = this.accept("-") ? -1 : 1;
+    const text = this.take();
+    if (!/^(?:\d+|0[xX][0-9a-fA-F]+)$/.test(text)) this.fail("Expected integer.");
+    const value = sign * Number(text);
+    if (!Number.isSafeInteger(value)) this.fail("Integer out of range.");
+    return value;
+  }
+  private string(): string {
+    const value = this.take();
+    if (!value.startsWith('"')) this.fail("Expected double-quoted string.");
+    try { return JSON.parse(value) as string; } catch { return this.fail("Invalid quoted string."); }
+  }
+  private peek(): string | undefined { return this.tokens[this.cursor]; }
+  private take(): string {
+    const value = this.tokens[this.cursor++];
+    if (value === undefined) this.fail("Unexpected end of schema.");
+    return value!;
+  }
+  private accept(value: string): boolean { if (this.peek() !== value) return false; this.cursor++; return true; }
+  private expect(value: string): void { if (!this.accept(value)) this.fail("Expected " + value + ", got " + String(this.peek()) + "."); }
+  private fail(message: string): never { throw new TypeError(this.filename + ": " + message); }
+}
+function qualify(parent: string, name: string): string { return parent ? parent + "." + name : name; }

package/core/grpc/ProtoReader.ts

@@ -0,0 +1,34 @@
+/** Bounds-checked protobuf wire reader; every loop consumes bytes or throws. */
+export class ProtoReader {
+  offset = 0;
+  constructor(readonly buffer: Buffer) {}
+  get done(): boolean { return this.offset === this.buffer.length; }
+  varint(): bigint {
+    let value = 0n;
+    for (let i = 0; i < 10; i++) {
+      const byte = this.bytes(1)[0]!;
+      if (i === 9 && byte > 1) throw new TypeError("Protobuf varint exceeds 64 bits.");
+      value |= BigInt(byte & 127) << BigInt(i * 7);
+      if (byte < 128) return value;
+    }
+    throw new TypeError("Invalid protobuf varint.");
+  }
+  bytes(length: number): Buffer {
+    if (!Number.isSafeInteger(length) || length < 0 || length > this.buffer.length - this.offset) throw new TypeError("Truncated protobuf field.");
+    const result = this.buffer.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return result;
+  }
+  delimited(): Buffer {
+    const length = this.varint();
+    if (length > BigInt(this.buffer.length - this.offset)) throw new TypeError("Truncated protobuf field.");
+    return this.bytes(Number(length));
+  }
+  skip(wire: number): void {
+    if (wire === 0) this.varint();
+    else if (wire === 1) this.bytes(8);
+    else if (wire === 2) this.delimited();
+    else if (wire === 5) this.bytes(4);
+    else throw new TypeError("Unsupported protobuf wire type.");
+  }
+}

package/core/grpc/ProtoSchema.ts

@@ -0,0 +1,52 @@
+export interface ProtoField {
+  readonly name: string;
+  readonly number: number;
+  readonly type: string;
+  readonly repeated: boolean;
+  readonly optional: boolean;
+  readonly oneof?: string;
+  readonly mapKey?: string;
+  readonly packed: boolean;
+}
+export interface ProtoMessage { readonly name: string; readonly fields: ProtoField[] }
+export interface ProtoEnum { readonly name: string; readonly values: Record<string, number> }
+export interface ProtoRpc { readonly name: string; readonly input: string; readonly output: string; readonly requestStream: boolean; readonly responseStream: boolean }
+export interface ProtoSchema {
+  readonly messages: Map<string, ProtoMessage>;
+  readonly enums: Map<string, ProtoEnum>;
+  readonly services: Map<string, ProtoRpc[]>;
+}
+export interface ProtoLoaderOptions {
+  readonly keepCase?: boolean;
+  readonly defaults?: boolean;
+  readonly arrays?: boolean;
+  readonly objects?: boolean;
+  readonly oneofs?: boolean;
+  /** Exact 64-bit values are bigint by default; String and Number are opt-in. */
+  readonly longs?: typeof String | typeof Number | typeof BigInt;
+  readonly enums?: typeof String | typeof Number;
+  readonly bytes?: typeof String | typeof Array | typeof Buffer;
+  readonly includeDirs?: readonly string[];
+}
+
+export const SCALAR_TYPES = new Set([
+  "double", "float", "int32", "int64", "uint32", "uint64", "sint32", "sint64",
+  "fixed32", "fixed64", "sfixed32", "sfixed64", "bool", "string", "bytes",
+]);
+
+export function resolveProtoType(schema: ProtoSchema, type: string, owner: string): string {
+  if (SCALAR_TYPES.has(type)) return type;
+  const has = (name: string): boolean => schema.messages.has(name) || schema.enums.has(name);
+  if (type.startsWith(".")) {
+    if (has(type.slice(1))) return type.slice(1);
+  } else {
+    const parts = owner.split(".");
+    while (parts.length > 0) {
+      const name = [...parts, type].join(".");
+      if (has(name)) return name;
+      parts.pop();
+    }
+    if (has(type)) return type;
+  }
+  throw new TypeError("Unknown protobuf type " + type + " in " + owner + ".");
+}

package/core/grpc/ServerCredentials.ts

@@ -0,0 +1,30 @@
+import type { SecureServerOptions } from "node:http2";
+
+/** TLS configuration uses only the runtime's built-in HTTP/2/TLS implementation. */
+export class ServerCredentials {
+  private constructor(private readonly settings: SecureServerOptions | undefined) {}
+
+  static createInsecure(): ServerCredentials { return new ServerCredentials(undefined); }
+  static createSsl(
+    rootCerts: Buffer | null,
+    keyCertPairs: readonly { private_key: Buffer; cert_chain: Buffer }[],
+    checkClientCertificate = false,
+  ): ServerCredentials {
+    if (rootCerts !== null && !Buffer.isBuffer(rootCerts)) throw new TypeError("TLS rootCerts must be Buffer or null.");
+    if (!Array.isArray(keyCertPairs) || keyCertPairs.length === 0
+      || keyCertPairs.some((pair) => !Buffer.isBuffer(pair.private_key) || !Buffer.isBuffer(pair.cert_chain))) {
+      throw new TypeError("TLS requires private_key/cert_chain Buffer pairs.");
+    }
+    if (typeof checkClientCertificate !== "boolean") throw new TypeError("Invalid TLS client certificate policy.");
+    return new ServerCredentials({
+      ca: rootCerts === null ? undefined : Buffer.from(rootCerts),
+      key: keyCertPairs.map((pair) => Buffer.from(pair.private_key)),
+      cert: keyCertPairs.map((pair) => Buffer.from(pair.cert_chain)),
+      requestCert: checkClientCertificate,
+      rejectUnauthorized: checkClientCertificate,
+      allowHTTP1: false,
+    });
+  }
+  /** @internal Snapshot for this listener; not a second networking stack. */
+  http2Options(): SecureServerOptions | undefined { return this.settings && { ...this.settings }; }
+}

package/core/grpc/clientContracts.ts

@@ -0,0 +1,39 @@
+import type { Metadata } from "./Metadata";
+
+/** TLS always verifies the server certificate; plaintext requires an http address. */
+export interface GrpcClientTlsOptions {
+  readonly ca?: string | Buffer;
+  readonly cert?: string | Buffer;
+  readonly key?: string | Buffer;
+  readonly servername?: string;
+}
+
+export interface GrpcClientOptions {
+  readonly address: string;
+  readonly tls?: GrpcClientTlsOptions;
+  readonly metadata?: Metadata;
+  readonly timeoutMs?: number;
+  readonly maxSendMessageLength?: number;
+  readonly maxReceiveMessageLength?: number;
+  readonly maxConcurrentCalls?: number;
+}
+
+export interface GrpcCallOptions {
+  readonly metadata?: Metadata;
+  readonly timeoutMs?: number;
+  readonly deadline?: Date | number;
+  readonly signal?: AbortSignal;
+}
+
+export interface GrpcResponse<T> {
+  readonly data: T;
+  readonly metadata: Metadata;
+  readonly trailers: Metadata;
+}
+
+/** Consume once. Early for-await exit cancels the call, as does cancel(). */
+export interface GrpcResponseStream<T> extends AsyncIterable<T> {
+  readonly metadata: Promise<Metadata>;
+  readonly trailers: Promise<Metadata>;
+  cancel(): void;
+}

package/core/grpc/contracts.ts

@@ -0,0 +1,45 @@
+import type { Metadata } from "./Metadata";
+import type { ServerCredentials } from "./ServerCredentials";
+import type { ServerOptions, ServiceDefinition } from "./serviceDefinition";
+import type { Class, BazisModuleRef } from "../di";
+import type { ModelValidator } from "../http/Binding/modelValidator";
+import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+
+/** One instance per RPC, including the complete lifetime of a streaming RPC. */
+export interface GrpcContext {
+  readonly metadata: Metadata;
+  readonly signal: AbortSignal;
+  readonly deadline: Date | number;
+  readonly peer: string;
+  readonly path: string;
+  sendMetadata(metadata: Metadata): void;
+}
+
+export interface GrpcModuleOptions {
+  readonly imports?: readonly BazisModuleRef[];
+  /** Normally contributed by feature-module grpcControllers. */
+  readonly controllers?: readonly Class<object>[];
+  /** DTO validation, captured per server. Default: Bazis's modelValidatorAdapter. */
+  readonly validator?: ModelValidator;
+  /** host:port or [IPv6]:port, default 127.0.0.1:50051. Port 0 selects a free port. */
+  readonly address?: string;
+  /** Default: plaintext. Pass ServerCredentials.createSsl(...) for TLS/mTLS. */
+  readonly credentials?: ServerCredentials;
+  /** Bazis transport limits; unknown options fail at startup. */
+  readonly serverOptions?: ServerOptions;
+  /** Includes handlers still running after client cancellation. Default 1024. */
+  readonly maxConcurrentCalls?: number;
+  /** Grace period before forced transport shutdown. Default 5000 ms. */
+  readonly shutdownTimeoutMs?: number;
+  /** Hosted service startup phase, default 10 (after infrastructure). */
+  readonly phase?: number;
+}
+
+export interface GrpcControllerDefinition {
+  readonly controller: Class<object>;
+  readonly service: ServiceDefinition;
+  /** Service method key -> instance method name. */
+  readonly methods: ReadonlyMap<string, string | symbol>;
+  /** Explicit DTO overrides keyed by instance method; optional for compatibility. */
+  readonly requestModels?: ReadonlyMap<string | symbol, RequestModelClass>;
+}