@mt-tl/tl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Beretta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @mt-tl/tl
+
+TL (Type Language) tooling for MTProto, used alongside `@mt-tl/server`: a `.tl`
+parser/IR, a generic wire codec, value↔JSON helpers, schema-version migrations, a
+**TypeScript type generator**, layer freezing, and the bundled MTProto **protocol**
+schema.
+
+```bash
+npm install -D @mt-tl/tl
+```
+
+Most apps use it for two things:
+
+## 1. Generate types from your `.tl`
+
+```bash
+npx mtproto-tl gen-types ./schema ./src/generated/schema.ts
+```
+
+Emits one interface per constructor, a union per type, and the `RpcMethods` map
+you pass to `createServer<RpcMethods>()`.
+
+## 2. Freeze a layer when you ship one
+
+```bash
+npx mtproto-tl freeze ./schema ./schema/layers 205
+```
+
+Writes `scheme_205.json` (loaded for layered encoding) + a `.tl` mirror.
+
+## Library API
+
+Also exports the building blocks the server uses: `parseSchemaDir`,
+`generateSchemaTs` / `writeSchemaTs`, `freezeLayer`, `MigrationRegistry`,
+`toJson` / `fromJson`, the RPC envelope types, and `protocolSchemaDir` (absolute
+path to the bundled protocol schema).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { writeSchemaTs } from './codegen/gen-types.js';
+import { freezeLayer } from './tools/freeze-layer.js';
+const USAGE = `mtproto-tl — TL tooling
+
+Usage:
+  mtproto-tl gen-types <schemaDir> <outFile>
+      Generate TypeScript types (RpcMethods + interfaces) from a .tl schema.
+
+  mtproto-tl freeze <schemaDir> <outDir> <layer>
+      Freeze the current schema into a per-layer snapshot (scheme_<layer>.json + .tl).
+`;
+function fail(msg) {
+    console.error(msg + '\n\n' + USAGE);
+    process.exit(1);
+}
+const [cmd, ...args] = process.argv.slice(2);
+switch (cmd) {
+    case 'gen-types': {
+        const [schemaDir, outFile] = args;
+        if (!schemaDir || !outFile)
+            fail('gen-types requires <schemaDir> <outFile>');
+        writeSchemaTs(schemaDir, outFile);
+        break;
+    }
+    case 'freeze': {
+        const [schemaDir, outDir, layerStr] = args;
+        if (!schemaDir || !outDir || !layerStr)
+            fail('freeze requires <schemaDir> <outDir> <layer>');
+        const layer = Number(layerStr);
+        if (!Number.isInteger(layer))
+            fail(`freeze: <layer> must be an integer, got "${layerStr}"`);
+        const res = freezeLayer(schemaDir, outDir, layer);
+        console.log(`Froze layer ${layer}: ${res.constructors} constructors, ${res.methods} methods → ${res.out}`);
+        if (res.crcWarnings)
+            console.warn(`  (${res.crcWarnings} CRC warnings)`);
+        break;
+    }
+    case undefined:
+    case '-h':
+    case '--help':
+        console.log(USAGE);
+        break;
+    default:
+        fail(`unknown command: ${cmd}`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAErD,MAAM,KAAK,GAAG;;;;;;;;CAQb,CAAA;AAED,SAAS,IAAI,CAAC,GAAW;IACrB,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,GAAG,KAAK,CAAC,CAAA;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACnB,CAAC;AAED,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AAE5C,QAAQ,GAAG,EAAE,CAAC;IACV,KAAK,WAAW,CAAC,CAAC,CAAC;QACf,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;QACjC,IAAI,CAAC,SAAS,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,0CAA0C,CAAC,CAAA;QAC5E,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjC,MAAK;IACT,CAAC;IACD,KAAK,QAAQ,CAAC,CAAC,CAAC;QACZ,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAA;QAC1C,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,8CAA8C,CAAC,CAAA;QAC5F,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,4CAA4C,QAAQ,GAAG,CAAC,CAAA;QAC3F,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;QACjD,OAAO,CAAC,GAAG,CACP,eAAe,KAAK,KAAK,GAAG,CAAC,YAAY,kBAAkB,GAAG,CAAC,OAAO,cAAc,GAAG,CAAC,GAAG,EAAE,CAChG,CAAA;QACD,IAAI,GAAG,CAAC,WAAW;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,gBAAgB,CAAC,CAAA;QACxE,MAAK;IACT,CAAC;IACD,KAAK,SAAS,CAAC;IACf,KAAK,IAAI,CAAC;IACV,KAAK,QAAQ;QACT,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAClB,MAAK;IACT;QACI,IAAI,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAA;AACvC,CAAC"}

package/dist/codegen/gen-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates TypeScript types from the `.tl` schema in `dir`: one interface per
+ * constructor, a union per type, and the `RpcMethods` map (method → params/result)
+ * you pass to `createServer<RpcMethods>()`. Returns the source as a string; see
+ * {@link writeSchemaTs} to write it to a file. Run via your app's `gen:types` script.
+ */
+export declare function generateSchemaTs(dir?: string): string;
+/** Generates types for the schema in `schemaDir` and writes them to `outPath`. */
+export declare function writeSchemaTs(schemaDir: string, outPath: string): void;
+//# sourceMappingURL=gen-types.d.ts.map

package/dist/codegen/gen-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gen-types.d.ts","sourceRoot":"","sources":["../../src/codegen/gen-types.ts"],"names":[],"mappings":"AA8EA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAyB,GAAG,MAAM,CA4FvE;AASD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAItE"}

package/dist/codegen/gen-types.js

@@ -0,0 +1,190 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseSchemaDir } from '../tl/parser.js';
+import { protocolSchemaDir as bundledSchemaDir } from '../index.js';
+/**
+ * Generates `generated/schema.ts` — TypeScript types for the **newest** layer:
+ * one interface per constructor, a union alias per TL type, and an `RpcMethods`
+ * map (method name → { params; result }) for typed worker handlers.
+ *
+ * Types only (no runtime). Field shapes are the post-`fromJson` values workers
+ * receive: long→bigint, bytes/int128/int256→Buffer, Vector<T>→T[], flags.N?T→
+ * optional. Run `yarn gen:types` after editing the schema.
+ *
+ *   yarn workspace @mt-tl/tl run gen:types
+ */
+const SPECIAL_TYPES = new Set(['Object', 'X', 'Bool', 'Vector t', 'true', '#']);
+function tsName(name) {
+    return name
+        .split('.')
+        .map(s => (s ? s.charAt(0).toUpperCase() + s.slice(1) : s))
+        .join('');
+}
+function mapType(t, known) {
+    switch (t.kind) {
+        case 'int':
+        case 'double':
+        case 'flags':
+            return 'number';
+        case 'long':
+            return 'bigint';
+        case 'bytes':
+        case 'int128':
+        case 'int256':
+            return 'Buffer';
+        case 'string':
+            return 'string';
+        case 'bool':
+            return 'boolean';
+        case 'true':
+            return 'true';
+        case 'vector':
+            return `${wrapUnion(mapType(t.inner, known))}[]`;
+        case 'object':
+            return 'unknown';
+        case 'flag':
+            return mapType(t.inner, known);
+        case 'boxed':
+        case 'bare': {
+            const n = tsName(t.name);
+            return known.has(n) ? n : 'unknown';
+        }
+    }
+}
+function wrapUnion(t) {
+    return t.includes('|') ? `(${t})` : t;
+}
+function fieldLines(def, known) {
+    const out = [];
+    for (const p of def.params) {
+        if (p.type.kind === 'flags')
+            continue; // internal bitmask
+        const prop = /^[A-Za-z_$][\w$]*$/.test(p.name) ? p.name : JSON.stringify(p.name);
+        if (p.type.kind === 'flag') {
+            out.push(`    ${prop}?: ${mapType(p.type.inner, known)}`);
+        }
+        else {
+            out.push(`    ${prop}: ${mapType(p.type, known)}`);
+        }
+    }
+    return out;
+}
+/**
+ * Generates TypeScript types from the `.tl` schema in `dir`: one interface per
+ * constructor, a union per type, and the `RpcMethods` map (method → params/result)
+ * you pass to `createServer<RpcMethods>()`. Returns the source as a string; see
+ * {@link writeSchemaTs} to write it to a file. Run via your app's `gen:types` script.
+ */
+export function generateSchemaTs(dir = bundledSchemaDir) {
+    const { defs } = parseSchemaDir(dir);
+    const ctors = defs.filter(d => d.kind === 'constructor');
+    const methods = defs.filter(d => d.kind === 'method');
+    // Type groups (union of constructors), excluding special types.
+    const typeGroups = new Map();
+    for (const d of ctors) {
+        if (SPECIAL_TYPES.has(d.type))
+            continue;
+        const g = typeGroups.get(d.type) ?? [];
+        g.push(d);
+        typeGroups.set(d.type, g);
+    }
+    // A TL type is a UNION of its constructors, emitted under the bare type name.
+    // The one exception: a type with a single constructor whose name equals the
+    // type name (e.g. `error` = Error) — there the lone interface IS the type, so
+    // no union alias is needed.
+    const unions = new Map();
+    for (const [type, group] of typeGroups) {
+        const name = tsName(type);
+        const soleSelfNamed = group.length === 1 && tsName(group[0].name) === name;
+        if (soleSelfNamed)
+            continue;
+        unions.set(name, group);
+    }
+    const unionNames = new Set(unions.keys());
+    // A constructor's interface name. When it would take a name a union already
+    // owns (the type's "primary" constructor — e.g. `user` in type `User`), suffix
+    // it with `_` so the union keeps the bare name: `User = User_ | UserEmpty | …`.
+    const ctorIface = (d) => {
+        const base = tsName(d.name);
+        return unionNames.has(base) ? `${base}_` : base;
+    };
+    // Interface def per constructor name (dedup; first wins).
+    const ctorByTs = new Map();
+    for (const d of ctors) {
+        const name = ctorIface(d);
+        if (!ctorByTs.has(name))
+            ctorByTs.set(name, d);
+    }
+    const known = new Set([...ctorByTs.keys(), ...unionNames]);
+    const lines = [
+        '// AUTO-GENERATED by `yarn gen:types`. Do not edit by hand.',
+        '// Types for the newest schema layer (post-fromJson shapes).',
+        '/* eslint-disable */',
+        '',
+    ];
+    // Constructor interfaces (sorted).
+    for (const name of [...ctorByTs.keys()].sort()) {
+        const def = ctorByTs.get(name);
+        const fields = fieldLines(def, known);
+        lines.push(`export interface ${name} {`);
+        lines.push(`    _: ${JSON.stringify(def.name)}`);
+        lines.push(...fields);
+        lines.push('}', '');
+    }
+    // Type unions (sorted).
+    for (const name of [...unions.keys()].sort()) {
+        const members = [...new Set(unions.get(name).map(d => ctorIface(d)))];
+        lines.push(`export type ${name} = ${members.join(' | ')}`, '');
+    }
+    // RpcMethods map (sorted by method name; dedup by name — first wins).
+    lines.push('export interface RpcMethods {');
+    const seenMethods = new Set();
+    for (const m of [...methods].sort((a, b) => a.name.localeCompare(b.name))) {
+        if (seenMethods.has(m.name))
+            continue;
+        seenMethods.add(m.name);
+        const paramsName = `${tsName(m.name)}Params`;
+        const result = resultType(m.type, known);
+        lines.push(`    ${JSON.stringify(m.name)}: { params: ${paramsName}; result: ${result} }`);
+    }
+    lines.push('}', '');
+    // Method params interfaces (sorted).
+    const seenParams = new Set();
+    for (const m of [...methods].sort((a, b) => a.name.localeCompare(b.name))) {
+        const paramsName = `${tsName(m.name)}Params`;
+        if (seenParams.has(paramsName))
+            continue;
+        seenParams.add(paramsName);
+        lines.push(`export interface ${paramsName} {`);
+        lines.push(...fieldLines(m, known));
+        lines.push('}', '');
+    }
+    return lines.join('\n');
+}
+function resultType(type, known) {
+    if (type === 'Bool')
+        return 'boolean';
+    if (type === 'Object' || type === 'X')
+        return 'unknown';
+    const n = tsName(type);
+    return known.has(n) ? n : 'unknown';
+}
+/** Generates types for the schema in `schemaDir` and writes them to `outPath`. */
+export function writeSchemaTs(schemaDir, outPath) {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, generateSchemaTs(schemaDir));
+    console.log(`Generated -> ${outPath}`);
+}
+// CLI: `tsx gen-types.ts <schemaDir> <outPath>` (apps wrap this in their own
+// `gen:types` script pointing at their schema). No bundled default — the
+// framework no longer ships business types.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const [schemaDir, outPath] = process.argv.slice(2);
+    if (!schemaDir || !outPath) {
+        console.error('usage: gen-types <schemaDir> <outPath>');
+        process.exit(1);
+    }
+    writeSchemaTs(schemaDir, outPath);
+}
+//# sourceMappingURL=gen-types.js.map

package/dist/codegen/gen-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gen-types.js","sourceRoot":"","sources":["../../src/codegen/gen-types.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './tl/ir.js';
+export * from './tl/value.js';
+export * from './tl/parser.js';
+export * from './tl/crc32.js';
+export * from './rpc.js';
+export * from './wire.js';
+export * from './migrate.js';
+export * from './logger.js';
+export { generateSchemaTs, writeSchemaTs } from './codegen/gen-types.js';
+export { freezeLayer, type FreezeResult } from './tools/freeze-layer.js';
+/** Absolute path to the bundled MTProto protocol `.tl` schema directory. */
+export declare const protocolSchemaDir: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAG5B,cAAc,aAAa,CAAA;AAG3B,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAKxE,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAuD,CAAA"}

package/dist/index.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+export * from './tl/ir.js';
+export * from './tl/value.js';
+export * from './tl/parser.js';
+export * from './tl/crc32.js';
+export * from './rpc.js';
+export * from './wire.js';
+export * from './migrate.js';
+// Shared structured logger — the server engine, the handler layer, and your app
+// import it for one consistent log style (see docs/guide/observability.md).
+export * from './logger.js';
+// Codegen + layer tooling — consumers generate TS types and freeze layer
+// snapshots from THEIR `.tl` schema.
+export { generateSchemaTs, writeSchemaTs } from './codegen/gen-types.js';
+export { freezeLayer } from './tools/freeze-layer.js';
+// @mt-tl/tl ships only the fixed MTProto **protocol** schema; business `.tl`
+// lives in the consumer app. This is the protocol-only default; apps pass their
+// own schema dir to the gateway.
+/** Absolute path to the bundled MTProto protocol `.tl` schema directory. */
+export const protocolSchemaDir = fileURLToPath(new URL('../schema', import.meta.url));
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,gFAAgF;AAChF,4EAA4E;AAC5E,cAAc,aAAa,CAAA;AAC3B,yEAAyE;AACzE,qCAAqC;AACrC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAqB,MAAM,yBAAyB,CAAA;AAExE,6EAA6E;AAC7E,gFAAgF;AAChF,iCAAiC;AACjC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA"}

package/dist/logger.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A tiny dependency-free structured logger, shared across the MTProto packages
+ * (the server engine, the handler layer, and your app — import it for one
+ * consistent log style). Levels gate output; fields are key/value context.
+ *
+ * - `LOG_LEVEL` sets the threshold (`trace`<`debug`<`info`<`warn`<`error`<`silent`).
+ * - `LOG_FORMAT=json` emits one JSON object per line (ship to a log pipeline);
+ *   anything else is a readable line for local dev.
+ * - `LOG_ERROR_STACK=true|false` forces whether `Error.stack` is serialized
+ *   (default: on for `pretty`, off for `json` — prod opts in).
+ * - `pretty` output is ANSI-colored when stdout is a TTY (dim keys, colored
+ *   level) for readability; honors `NO_COLOR` / `FORCE_COLOR`.
+ * - Tests default to `silent` (set `LOG_LEVEL` to override).
+ *
+ * Levels, by convention across this codebase:
+ * - `trace` — byte/hex protocol firehose (every recv, framing headers, decrypt).
+ * - `debug` — useful protocol events (decoded method, salt re-send, handshake step).
+ * - `info`  — request/response one-liners + lifecycle links/unlinks (sockets,
+ *             sessions, auth keys, users) + update deliveries.
+ * - `warn`  — recoverable anomalies (decode failure, unknown method, integrity
+ *             rejection, insecure config).
+ * - `error` — a request that failed or an update that could not be delivered.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export type Fields = Record<string, unknown>;
+export interface Logger {
+    /** Byte/hex protocol firehose — guard heavy field building with {@link isLevelEnabled}. */
+    trace(msg: string, fields?: Fields): void;
+    debug(msg: string, fields?: Fields): void;
+    info(msg: string, fields?: Fields): void;
+    warn(msg: string, fields?: Fields): void;
+    error(msg: string, fields?: Fields): void;
+    /** Returns a logger that merges `bindings` into every line (e.g. a scope/conn id). */
+    child(bindings: Fields): Logger;
+    /** True when a message at `level` would be emitted — guard expensive field building. */
+    isLevelEnabled(level: LogLevel): boolean;
+    /** The active threshold level. */
+    readonly level: LogLevel;
+}
+export interface LoggerOptions {
+    level?: LogLevel;
+    /** 'json' for machine-readable lines, 'pretty' for humans. */
+    format?: 'json' | 'pretty';
+    name?: string;
+    bindings?: Fields;
+    /**
+     * Include `Error.stack` when serializing an Error field. Default: `true` for
+     * `pretty` (dev), `false` for `json` (prod opts in). `LOG_ERROR_STACK` overrides.
+     */
+    errorStack?: boolean;
+    /**
+     * ANSI-color the `pretty` output (dim keys, colored level). Default: auto — on
+     * when stdout is a TTY and `NO_COLOR` is unset (off when a custom `write` is
+     * given). Never colors `json`.
+     */
+    color?: boolean;
+    /** Sink (defaults to stdout/stderr by level). Override in tests. */
+    write?: (line: string) => void;
+}
+export declare function createLogger(options?: LoggerOptions): Logger;
+/** A logger that drops everything (explicit opt-out in tests/embedders). */
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAW/E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE5C,MAAM,WAAW,MAAM;IACnB,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,sFAAsF;IACtF,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAA;IACxC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa;IAC1B,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAkED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAsDhE;AASD,4EAA4E;AAC5E,eAAO,MAAM,UAAU,EAAE,MASxB,CAAA"}

package/dist/logger.js

@@ -0,0 +1,147 @@
+const ORDER = {
+    trace: 5,
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 99,
+};
+function defaultLevel() {
+    const env = process.env.LOG_LEVEL;
+    if (env && env in ORDER)
+        return env;
+    if (process.env.VITEST || process.env.NODE_ENV === 'test')
+        return 'silent';
+    return 'info';
+}
+function defaultFormat() {
+    return process.env.LOG_FORMAT === 'json' ? 'json' : 'pretty';
+}
+function defaultErrorStack(format) {
+    const env = process.env.LOG_ERROR_STACK;
+    if (env === 'true' || env === '1')
+        return true;
+    if (env === 'false' || env === '0')
+        return false;
+    return format === 'pretty';
+}
+function defaultColor(format) {
+    if (format === 'json')
+        return false;
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return !!process.stdout.isTTY;
+}
+// ANSI styling for the pretty (TTY) format.
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const GRAY = '\x1b[90m';
+const LEVEL_COLOR = {
+    trace: '\x1b[90m', // gray
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+};
+function makeSerialize(errorStack) {
+    return function serialize(value) {
+        if (value instanceof Error) {
+            const base = { name: value.name, message: value.message };
+            if (errorStack && value.stack)
+                base.stack = value.stack;
+            return base;
+        }
+        if (typeof value === 'bigint')
+            return value.toString();
+        return value;
+    };
+}
+function prettyFields(fields, serialize, color) {
+    const parts = [];
+    for (const [k, v] of Object.entries(fields)) {
+        const sv = serialize(v);
+        const val = typeof sv === 'object' && sv !== null ? JSON.stringify(sv) : String(sv);
+        // Dim the key so the eye separates key from value; values stay bright.
+        parts.push(color ? `${DIM}${k}=${RESET}${val}` : `${k}=${val}`);
+    }
+    if (!parts.length)
+        return '';
+    // Wider gap between fields when colored (the TTY view we optimize for reading).
+    const sep = color ? '  ' : ' ';
+    return sep + parts.join(sep);
+}
+export function createLogger(options = {}) {
+    const level = options.level ?? defaultLevel();
+    const format = options.format ?? defaultFormat();
+    const errorStack = options.errorStack ?? defaultErrorStack(format);
+    // A custom sink (tests/embedders) gets no color unless explicitly asked.
+    const color = options.color ?? (options.write ? false : defaultColor(format));
+    const name = options.name;
+    const bindings = options.bindings ?? {};
+    const threshold = ORDER[level];
+    const serialize = makeSerialize(errorStack);
+    const emit = (lvl, msg, fields) => {
+        if (ORDER[lvl] < threshold)
+            return;
+        const merged = { ...bindings, ...(fields ?? {}) };
+        const write = options.write ?? (lvl === 'error' || lvl === 'warn' ? errLine : outLine);
+        if (format === 'json') {
+            const obj = { time: new Date().toISOString(), level: lvl, ...(name ? { name } : {}), msg };
+            for (const [k, v] of Object.entries(merged))
+                obj[k] = serialize(v);
+            write(JSON.stringify(obj));
+        }
+        else {
+            const ts = new Date().toISOString().slice(11, 23);
+            const lvlText = lvl.toUpperCase().padEnd(5);
+            if (color) {
+                const tag = name ? ` ${DIM}[${name}]${RESET}` : '';
+                write(`${GRAY}${ts}${RESET} ${LEVEL_COLOR[lvl]}${lvlText}${RESET}${tag} ${BOLD}${msg}${RESET}` +
+                    prettyFields(merged, serialize, true));
+            }
+            else {
+                const tag = name ? ` [${name}]` : '';
+                write(`${ts} ${lvlText}${tag} ${msg}` + prettyFields(merged, serialize, false));
+            }
+        }
+    };
+    return {
+        level,
+        trace: (msg, fields) => emit('trace', msg, fields),
+        debug: (msg, fields) => emit('debug', msg, fields),
+        info: (msg, fields) => emit('info', msg, fields),
+        warn: (msg, fields) => emit('warn', msg, fields),
+        error: (msg, fields) => emit('error', msg, fields),
+        isLevelEnabled: lvl => ORDER[lvl] >= threshold,
+        child: extra => createLogger({
+            ...options,
+            level,
+            format,
+            errorStack,
+            color,
+            name,
+            bindings: { ...bindings, ...extra },
+        }),
+    };
+}
+function outLine(line) {
+    process.stdout.write(line + '\n');
+}
+function errLine(line) {
+    process.stderr.write(line + '\n');
+}
+/** A logger that drops everything (explicit opt-out in tests/embedders). */
+export const noopLogger = {
+    level: 'silent',
+    trace() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+    isLevelEnabled: () => false,
+    child: () => noopLogger,
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/migrate.d.ts

@@ -0,0 +1,37 @@
+import type { TlValue } from './tl/value.js';
+/**
+ * One rung of a predicate's migration ladder. `up` maps THIS version's shape to
+ * the NEXT version's; `down` maps the next version back to this one. The newest
+ * (canonical) rung has neither.
+ */
+export interface MigrationRung {
+    /** Layer this shape was introduced. */
+    since: number;
+    up?: (obj: Record<string, unknown>) => Record<string, unknown>;
+    down?: (obj: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Per-predicate migration ladders. The gateway normalizes inbound values to the
+ * canonical (newest) shape (`up`) before forwarding, and renders canonical values
+ * down to a client's layer (`down`) before encoding — so workers only ever see
+ * the canonical shape. Scales to N versions: one rung per version; adding a
+ * version appends a rung and never touches the others.
+ *
+ * Only non-additively-changed predicates need a ladder; everything else is
+ * handled by decode-union + layered-encode with no rungs (identity here).
+ */
+export declare class MigrationRegistry {
+    private byPredicate;
+    /** Register a predicate's ladder (rungs in any order; sorted by `since`). */
+    register(predicate: string, rungs: MigrationRung[]): this;
+    has(predicate: string): boolean;
+    get size(): number;
+    /** Normalize a value decoded at `fromLayer` up to the canonical shape. */
+    up(value: TlValue, fromLayer: number): TlValue;
+    /** Render a canonical value down to `toLayer`'s shape. */
+    down(value: TlValue, toLayer: number): TlValue;
+    private recurse;
+    private upObject;
+    private downObject;
+}
+//# sourceMappingURL=migrate.d.ts.map