@atolljs/core 0.1.0 → 0.1.1

package/dist/index6.js

@@ -1,23 +1,493 @@
-import { z as e } from "zod";
-//#region src/contract/mz.ts
-var t = {
-	i8: () => e.number().int().min(-128).max(127),
-	u8: () => e.number().int().min(0).max(255),
-	i16: () => e.number().int().min(-32768).max(32767),
-	u16: () => e.number().int().min(0).max(65535),
-	i32: () => e.int32(),
-	u32: () => e.uint32(),
-	f32: () => e.float32(),
-	f64: () => e.float64(),
-	i64: () => e.int64(),
-	u64: () => e.uint64(),
-	int: (t, n) => e.number().int().min(t).max(n),
-	boolean: () => e.boolean(),
-	string: (t) => e.string().refine((e) => new TextEncoder().encode(e).byteLength <= t, `exceeds ${t} UTF-8 bytes`).meta({ bytes: t }),
-	object: (t) => e.object(t),
-	array: (t) => e.array(t)
+import { msgpackrCodec as e } from "./index2.js";
+import { z as t } from "./index3.js";
+import { memberToSpec as n, zodArrayInfo as r, zodObjectShape as i, zodStringBytes as a } from "./index4.js";
+import { fmtBytes as o, scoped as s } from "./index5.js";
+//#region src/contract/sharedMemory.ts
+var c = s("memory"), l = 8, u = (e, t) => e + t - 1 & ~(t - 1), d = (e) => u(e, l), f = (e) => typeof e == "object" && !!e && typeof e.kind == "string" && typeof e.byteLength == "number";
+function p(e) {
+	let t = [];
+	for (let [n, r] of Object.entries(e)) if (f(r)) t.push({
+		path: n,
+		descriptor: r
+	});
+	else for (let [e, i] of Object.entries(r)) {
+		if (!f(i)) throw TypeError(`shared memory "${n}.${e}" is not a field descriptor — intent groups nest one level only`);
+		t.push({
+			path: `${n}.${e}`,
+			descriptor: i
+		});
+	}
+	return t;
+}
+var m = new TextEncoder(), h = new TextDecoder(), g = {
+	encode: (e) => m.encode(JSON.stringify(e)),
+	decode: (e) => JSON.parse(h.decode(e))
+}, _ = /* @__PURE__ */ new Map();
+function v(e, t) {
+	_.set(e, t);
+}
+var y = {
+	i8: 1,
+	u8: 1,
+	i16: 2,
+	u16: 2,
+	i32: 4,
+	u32: 4,
+	f32: 4,
+	f64: 8,
+	i64: 8,
+	u64: 8
+}, b = (e) => typeof e == "string" ? y[e] : "string" in e ? e.string : 1, x = (e) => typeof e == "string" ? y[e] : 1;
+function S(e) {
+	let t = {}, r = {}, i = 0;
+	for (let a of Object.keys(e)) {
+		let o = n(e[a], String(a));
+		r[a] = o, i = u(i, x(o)), t[a] = i, i += b(o);
+	}
+	return {
+		layout: r,
+		offsets: t,
+		recordSize: d(i)
+	};
+}
+var C = {
+	number: () => ({
+		kind: "number",
+		byteLength: 8
+	}),
+	boolean: () => ({
+		kind: "boolean",
+		byteLength: 8
+	}),
+	string: (e) => {
+		let { schema: t, maxBytes: n } = e;
+		if (n !== void 0) return {
+			kind: "string",
+			byteLength: 4 + n,
+			schema: t
+		};
+		let r = t ? a(t) : null;
+		if (r !== null) return {
+			kind: "string",
+			byteLength: 4 + r,
+			schema: t
+		};
+		throw TypeError("field.string: pass { maxBytes } or a schema carrying a byte budget — mz.string(n) / z.string().meta({ bytes: n })");
+	},
+	object: (e) => {
+		let { schema: t, maxBytes: n } = e;
+		if (n === void 0 && t) {
+			let e = i(t);
+			if (e) {
+				let { layout: n, offsets: r, recordSize: i } = S(e);
+				return {
+					kind: "object",
+					byteLength: 8 + i,
+					schema: t,
+					layout: n,
+					offsets: r,
+					recordSize: i
+				};
+			}
+			throw TypeError("field.object: schema can't derive a fixed byte width (not a zod object of fixed-width members) — pass { maxBytes } for codec-encoded storage");
+		}
+		if (n === void 0) throw TypeError("field.object: pass { schema } for a fixed-layout field or { maxBytes } for a codec-encoded field");
+		return {
+			kind: "object",
+			byteLength: 4 + n,
+			schema: t
+		};
+	},
+	array: (e) => {
+		let { schema: t, maxBytes: i } = e;
+		if (i === void 0 && t) {
+			let e = r(t);
+			if (e) {
+				if (e.capacity === null) throw TypeError("field.array: z.array() needs .max(n) or .length(n) — bounded arrays are fixed-width");
+				let r;
+				try {
+					r = n(e.element, "array element");
+				} catch (e) {
+					throw TypeError(`field.array: element isn't a fixed-width member — use field.list for arrays of records (${e.message})`);
+				}
+				let i = u(b(r), x(r));
+				return {
+					kind: "array",
+					byteLength: 8 + e.capacity * i,
+					schema: t,
+					element: r,
+					elementStride: i,
+					capacity: e.capacity
+				};
+			}
+			throw TypeError("field.array: schema can't derive a fixed byte width (not a bounded zod array) — pass { maxBytes } for codec-encoded storage");
+		}
+		if (i === void 0) throw TypeError("field.array: pass { schema } for a fixed-layout field or { maxBytes } for a codec-encoded field");
+		return {
+			kind: "array",
+			byteLength: 4 + i,
+			schema: t
+		};
+	},
+	int32Array: ({ length: e }) => ({
+		kind: "Int32",
+		byteLength: e * 4
+	}),
+	float64Array: ({ length: e }) => ({
+		kind: "Float64",
+		byteLength: e * 8
+	}),
+	bigInt64Array: ({ length: e }) => ({
+		kind: "BigInt64",
+		byteLength: e * 8
+	}),
+	uint8Array: ({ length: e }) => ({
+		kind: "Uint8",
+		byteLength: e
+	}),
+	list: ({ schema: e, count: t }) => {
+		let n = i(e);
+		if (!n) throw TypeError("field.list: schema must be an mz.object() of fixed-width members");
+		let { layout: r, offsets: a, recordSize: o } = S(n);
+		return {
+			kind: "list",
+			byteLength: o * t,
+			schema: e,
+			layout: r,
+			offsets: a,
+			recordSize: o,
+			count: t
+		};
+	}
+}, w = {
+	Int32: Int32Array,
+	Float64: Float64Array,
+	BigInt64: BigInt64Array,
+	Uint8: Uint8Array
 };
+v("number", (e, t, n) => {
+	let r = new Float64Array(t.buffer, n, 1);
+	return {
+		byteOffset: n,
+		byteLength: e.byteLength,
+		read: () => r[0],
+		write: (e) => {
+			r[0] = e;
+		}
+	};
+}), v("boolean", (e, t, n) => {
+	let r = new Uint8Array(t.buffer, n, 1);
+	return {
+		byteOffset: n,
+		byteLength: e.byteLength,
+		read: () => r[0] === 1,
+		write: (e) => {
+			r[0] = +!!e;
+		}
+	};
+});
+for (let e of Object.keys(w)) v(e, (t, n, r) => {
+	let i = w[e], a = new i(n.buffer, r, t.byteLength / i.BYTES_PER_ELEMENT);
+	return {
+		byteOffset: r,
+		byteLength: t.byteLength,
+		read: () => a,
+		write: (e) => a.set(e)
+	};
+});
+v("string", (e, t, n) => {
+	let r = new TextEncoder(), i = new TextDecoder(), a = e.byteLength - 4, o = new Uint32Array(t.buffer, n, 1), s = (e) => {
+		if (e.byteLength > a) throw Error(`Encoded value of ${e.byteLength} bytes exceeds field capacity of ${a} bytes at offset ${n}`);
+		o[0] = e.byteLength, new Uint8Array(t.buffer, n + 4, e.byteLength).set(e);
+	}, c = () => new Uint8Array(t.buffer, n + 4, o[0]).slice();
+	return {
+		byteOffset: n,
+		byteLength: e.byteLength,
+		read: () => i.decode(c()),
+		write: (t) => s(r.encode(e.schema ? e.schema.parse(t) : t))
+	};
+});
+function T(e) {
+	let t = new DataView(e.buffer), n = new Uint8Array(e.buffer), r = new TextEncoder(), i = new TextDecoder(), a = {
+		i8: {
+			get: (e) => t.getInt8(e),
+			set: (e, n) => t.setInt8(e, n)
+		},
+		u8: {
+			get: (e) => t.getUint8(e),
+			set: (e, n) => t.setUint8(e, n)
+		},
+		i16: {
+			get: (e) => t.getInt16(e),
+			set: (e, n) => t.setInt16(e, n)
+		},
+		u16: {
+			get: (e) => t.getUint16(e),
+			set: (e, n) => t.setUint16(e, n)
+		},
+		i32: {
+			get: (e) => t.getInt32(e),
+			set: (e, n) => t.setInt32(e, n)
+		},
+		u32: {
+			get: (e) => t.getUint32(e),
+			set: (e, n) => t.setUint32(e, n)
+		},
+		f32: {
+			get: (e) => t.getFloat32(e),
+			set: (e, n) => t.setFloat32(e, n)
+		},
+		f64: {
+			get: (e) => t.getFloat64(e),
+			set: (e, n) => t.setFloat64(e, n)
+		},
+		i64: {
+			get: (e) => t.getBigInt64(e),
+			set: (e, n) => t.setBigInt64(e, n)
+		},
+		u64: {
+			get: (e) => t.getBigUint64(e),
+			set: (e, n) => t.setBigUint64(e, n)
+		}
+	}, o = (e, t) => {
+		let r = n.indexOf(0, e), a = r === -1 || r - e >= t ? t : r - e;
+		return i.decode(n.slice(e, e + a));
+	}, s = /* @__PURE__ */ new Uint8Array(64), c = (e, t, i) => {
+		s.length < t && (s = new Uint8Array(t));
+		let { read: a, written: o } = r.encodeInto(i, s);
+		if (a < i.length || o > t) throw Error(`String exceeds inline field capacity of ${t} bytes`);
+		n.set(s.subarray(0, o), e), o < t && n.fill(0, e + o, e + t);
+	}, l = (e) => {
+		if (typeof e == "string") {
+			let t = a[e];
+			return {
+				get: (e) => t.get(e),
+				set: (e, n) => t.set(e, n)
+			};
+		}
+		return "bool" in e ? {
+			get: (e) => !!t.getUint8(e),
+			set: (e, n) => t.setUint8(e, +!!n)
+		} : {
+			get: (t) => o(t, e.string),
+			set: (t, n) => c(t, e.string, n)
+		};
+	};
+	return {
+		ops: l,
+		compile: (e, t) => {
+			let n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+			for (let i of Object.keys(e)) {
+				let { get: a, set: o } = l(e[i]), s = t[i];
+				n.set(i, (e, t) => {
+					t[i] = a(e + s);
+				}), r.set(i, (e, t) => o(e + s, t[i]));
+			}
+			let i = [...n.values()], a = [...r.values()];
+			return {
+				read(e, t = {}, r) {
+					if (r) for (let i of r) n.get(i)(e, t);
+					else for (let n of i) n(e, t);
+					return t;
+				},
+				write(e, t, n) {
+					if (n) for (let i of n) r.get(i)(e, t);
+					else for (let n of a) n(e, t);
+				}
+			};
+		}
+	};
+}
+var E = (e, t, n) => {
+	let { schema: r, byteLength: i, kind: a } = e, o = e;
+	if (o.layout && o.offsets && o.recordSize !== void 0) {
+		let e = new Uint32Array(t.buffer, n, 2), a = n + 8, s = T(t).compile(o.layout, o.offsets);
+		return {
+			byteOffset: n,
+			byteLength: i,
+			read: () => e[0] ? s.read(a, {}) : void 0,
+			write: (t) => {
+				s.write(a, r ? r.parse(t) : t), e[0] = 1;
+			}
+		};
+	}
+	if (o.element !== void 0 && o.elementStride !== void 0 && o.capacity !== void 0) {
+		let e = new Uint32Array(t.buffer, n, 1), a = new Uint32Array(t.buffer, n + 4, 1), s = T(t).ops(o.element), c = o.elementStride, l = o.capacity, u = n + 8;
+		return {
+			byteOffset: n,
+			byteLength: i,
+			read: () => {
+				if (!e[0]) return;
+				let t = a[0];
+				return Array.from({ length: t }, (e, t) => s.get(u + t * c));
+			},
+			write: (t) => {
+				let n = r ? r.parse(t) : t;
+				if (n.length > l) throw Error(`${n.length} elements exceeds array capacity of ${l}`);
+				n.forEach((e, t) => s.set(u + t * c, e)), a[0] = n.length, e[0] = 1;
+			}
+		};
+	}
+	let s = i - 4, c = new Uint32Array(t.buffer, n, 1), l = (e) => {
+		if (e.byteLength > s) throw Error(`Encoded value of ${e.byteLength} bytes exceeds field capacity of ${s} bytes at offset ${n}`);
+		c[0] = e.byteLength, new Uint8Array(t.buffer, n + 4, e.byteLength).set(e);
+	}, u = () => new Uint8Array(t.buffer, n + 4, c[0]).slice();
+	return {
+		byteOffset: n,
+		byteLength: i,
+		read: () => {
+			let e = u();
+			if (e.byteLength === 0) return;
+			let n = t.codec.decode(e);
+			return r ? r.parse(n) : n;
+		},
+		write: (e) => l(t.codec.encode(r ? r.parse(e) : e))
+	};
+};
+v("object", E), v("array", E);
+function D(e, t, n) {
+	let r = e, { offsets: i, recordSize: a, count: o } = r, s = T(t).compile(r.layout, i), c = (e) => {
+		if (e < 0 || e >= o) throw RangeError(`Record index ${e} out of bounds (0..${o - 1})`);
+	}, l = (e, t = {}, r) => (c(e), s.read(n + e * a, t, r)), u = (e, t, r) => {
+		c(e), s.write(n + e * a, t, r);
+	};
+	return {
+		byteOffset: n,
+		byteLength: e.byteLength,
+		recordCount: o,
+		recordSize: a,
+		readAt: l,
+		writeAt: u,
+		commit: () => {
+			t.version && (Atomics.add(t.version.view, t.version.index, 1), Atomics.notify(t.version.view, t.version.index));
+		},
+		read: () => Array.from({ length: o }, (e, t) => l(t)),
+		write: (e) => {
+			if (e.length > o) throw Error(`${e.length} records exceeds list array capacity of ${o}`);
+			e.forEach((e, t) => u(t, e));
+		}
+	};
+}
+v("list", D);
+var O = [];
+function k(e) {
+	let t = {};
+	for (let [n, r] of Object.entries(e)) t[n] = f(r) ? A(r) : Object.fromEntries(Object.entries(r).map(([e, t]) => [e, A(t)]));
+	return t;
+}
+function A(e) {
+	if (e.schema) return e.schema;
+	switch (e.kind) {
+		case "number": return t.number();
+		case "boolean": return t.boolean();
+		case "string": return t.string();
+		case "Int32": return t.instanceof(Int32Array);
+		case "Float64": return t.instanceof(Float64Array);
+		case "BigInt64": return t.instanceof(BigInt64Array);
+		case "Uint8": return t.instanceof(Uint8Array);
+		default: return t.unknown();
+	}
+}
+var j = class {
+	totalBytes;
+	spec;
+	schemas;
+	codec;
+	plugins;
+	entries;
+	offsets = /* @__PURE__ */ new Map();
+	versionOffset;
+	connectors = /* @__PURE__ */ new Map();
+	boundListeners = /* @__PURE__ */ new Set();
+	isBound = !1;
+	boundBuffer;
+	constructor(t, n = {}) {
+		this.spec = t, this.codec = n.codec ?? e, this.plugins = n.plugins, this.entries = p(t), this.schemas = k(t);
+		let r = 0;
+		for (let { path: e, descriptor: t } of this.entries) r = d(r), this.offsets.set(e, r), r += t.byteLength;
+		this.versionOffset = d(r), this.totalBytes = this.versionOffset + d(this.entries.length * 4), O.push(this), c.info(`contract defined: ${this.entries.length} field(s), ${o(this.totalBytes)}`, {
+			fields: Object.fromEntries(this.entries.map((e) => [e.path, `${e.descriptor.kind}@${this.offsets.get(e.path)?.toLocaleString()}+${o(e.descriptor.byteLength)}`])),
+			pluginOverrides: Object.keys(this.plugins ?? {})
+		});
+	}
+	bind(e) {
+		this.connectors.clear();
+		let t = new Int32Array(e, this.versionOffset, this.entries.length);
+		this.entries.forEach(({ path: n, descriptor: r }, i) => {
+			let a = this.plugins?.[r.kind] ?? _.get(r.kind);
+			if (!a) throw Error(`Unknown shared memory field kind: ${r.kind}`);
+			c.debug(`bind "${n}" (${r.kind}, ${o(r.byteLength)}) via ${this.plugins?.[r.kind] ? "plugin" : "built-in"} factory`);
+			let s = a(r, {
+				buffer: e,
+				codec: this.codec,
+				version: {
+					view: t,
+					index: i
+				}
+			}, this.offsets.get(n));
+			this.connectors.set(n, {
+				...s,
+				write: (e) => {
+					s.write(e), Atomics.add(t, i, 1), Atomics.notify(t, i);
+				},
+				_version: {
+					view: t,
+					index: i
+				}
+			});
+		}), this.isBound = !0, this.boundBuffer = e;
+		for (let e of [...this.boundListeners]) e();
+	}
+	get bound() {
+		return this.isBound;
+	}
+	get buffer() {
+		if (!this.boundBuffer) throw Error("Shared memory contract is not bound to a buffer on this thread.");
+		return this.boundBuffer;
+	}
+	fields() {
+		return this.entries.map(({ path: e, descriptor: t }) => ({
+			path: e,
+			byteOffset: this.offsets.get(e),
+			byteLength: t.byteLength
+		}));
+	}
+	onBound(e) {
+		return this.isBound ? (e(), () => {}) : (this.boundListeners.add(e), () => this.boundListeners.delete(e));
+	}
+	connector(e) {
+		let t = String(e), n = this.connectors.get(t);
+		if (!n) throw Error(`Shared memory field "${t}" was accessed before the buffer was bound on this thread.`);
+		return n;
+	}
+};
+function M(e, t = {}) {
+	let n = new j(e, t);
+	for (let [t, r] of Object.entries(e)) if (f(r)) Object.defineProperty(n, t, {
+		enumerable: !0,
+		get: () => n.connector(t)
+	});
+	else {
+		let e = {};
+		for (let i of Object.keys(r)) Object.defineProperty(e, i, {
+			enumerable: !0,
+			get: () => n.connector(`${t}.${i}`)
+		});
+		Object.defineProperty(n, t, {
+			enumerable: !0,
+			get: () => e
+		});
+	}
+	return n;
+}
+function N(e) {
+	for (let t of O) t.bind(e);
+	c.info(`bound ${O.length} contract(s) — ${o(e.byteLength)} buffer`);
+}
+function P() {
+	return O.length;
+}
 //#endregion
-export { t as mz };
+export { j as SharedMemory, N as bindSharedMemories, M as defineSharedMemory, C as field, P as getDefinedSharedMemoryCount, g as jsonCodec, v as registerConnectorFactory };
 
 //# sourceMappingURL=index6.js.map

package/dist/index7.js

@@ -1,10 +1,23 @@
-import { decode as e, encode as t } from "@msgpack/msgpack";
-//#region src/contract/msgpackCodec.ts
-var n = {
-	encode: t,
-	decode: e
+import { z as e } from "./index3.js";
+//#region src/contract/mz.ts
+var t = {
+	i8: () => e.number().int().min(-128).max(127),
+	u8: () => e.number().int().min(0).max(255),
+	i16: () => e.number().int().min(-32768).max(32767),
+	u16: () => e.number().int().min(0).max(65535),
+	i32: () => e.int32(),
+	u32: () => e.uint32(),
+	f32: () => e.float32(),
+	f64: () => e.float64(),
+	i64: () => e.int64(),
+	u64: () => e.uint64(),
+	int: (t, n) => e.number().int().min(t).max(n),
+	boolean: () => e.boolean(),
+	string: (t) => e.string().refine((e) => new TextEncoder().encode(e).byteLength <= t, `exceeds ${t} UTF-8 bytes`).meta({ bytes: t }),
+	object: (t) => e.object(t),
+	array: (t) => e.array(t)
 };
 //#endregion
-export { n as msgpackCodec };
+export { t as mz };
 
 //# sourceMappingURL=index7.js.map

package/dist/index8.js

@@ -1,37 +1,10 @@
-//#region src/pool/memory.ts
-var e = class {
-	memory;
-	maxPages;
-	constructor(e = {}) {
-		let t = e.initialPages ?? 16;
-		this.maxPages = e.maximumPages ?? 16384, this.memory = new WebAssembly.Memory({
-			initial: t,
-			maximum: this.maxPages,
-			shared: !0
-		});
-	}
-	ensureCapacity(e) {
-		let t = this.memory.buffer.byteLength;
-		if (t >= e) return;
-		let n = e - t, r = Math.ceil(n / 65536);
-		if (this.memory.buffer.byteLength / 65536 + r > this.maxPages) throw Error(`Cannot grow memory: exceeds maximum page limit of ${this.maxPages}`);
-		this.memory.grow(r);
-	}
-	getView(e, t = 0, n) {
-		let r = this.memory.buffer;
-		switch (e) {
-			case "Int32": return new Int32Array(r, t, n);
-			case "Float64": return new Float64Array(r, t, n);
-			case "BigInt64": return new BigInt64Array(r, t, n);
-			case "Uint8": return new Uint8Array(r, t, n);
-			default: throw Error(`Unsupported view type: ${e}`);
-		}
-	}
-	getBuffer() {
-		return this.memory.buffer;
-	}
+import { decode as e, encode as t } from "@msgpack/msgpack";
+//#region src/contract/msgpackCodec.ts
+var n = {
+	encode: t,
+	decode: e
 };
 //#endregion
-export { e as MemoryManager };
+export { n as msgpackCodec };
 
 //# sourceMappingURL=index8.js.map

package/dist/index9.js

@@ -1,22 +1,37 @@
-//#region src/pool/errors.ts
-var e = class extends Error {
-	constructor(e = "WorkerPool task queue is full") {
-		super(e), this.name = "PoolQueueFullError";
+//#region src/pool/memory.ts
+var e = class {
+	memory;
+	maxPages;
+	constructor(e = {}) {
+		let t = e.initialPages ?? 16;
+		this.maxPages = e.maximumPages ?? 16384, this.memory = new WebAssembly.Memory({
+			initial: t,
+			maximum: this.maxPages,
+			shared: !0
+		});
 	}
-}, t = class extends Error {
-	constructor(e = "task aborted") {
-		super(e), this.name = "AbortError";
+	ensureCapacity(e) {
+		let t = this.memory.buffer.byteLength;
+		if (t >= e) return;
+		let n = e - t, r = Math.ceil(n / 65536);
+		if (this.memory.buffer.byteLength / 65536 + r > this.maxPages) throw Error(`Cannot grow memory: exceeds maximum page limit of ${this.maxPages}`);
+		this.memory.grow(r);
 	}
-}, n = class extends Error {
-	constructor(e = "task timed out") {
-		super(e), this.name = "TaskTimeoutError";
+	getView(e, t = 0, n) {
+		let r = this.memory.buffer;
+		switch (e) {
+			case "Int32": return new Int32Array(r, t, n);
+			case "Float64": return new Float64Array(r, t, n);
+			case "BigInt64": return new BigInt64Array(r, t, n);
+			case "Uint8": return new Uint8Array(r, t, n);
+			default: throw Error(`Unsupported view type: ${e}`);
+		}
 	}
-}, r = class extends Error {
-	constructor(e = "worker crashed") {
-		super(e), this.name = "WorkerCrashedError";
+	getBuffer() {
+		return this.memory.buffer;
 	}
 };
 //#endregion
-export { e as PoolQueueFullError, t as TaskAbortedError, n as TaskTimeoutError, r as WorkerCrashedError };
+export { e as MemoryManager };
 
 //# sourceMappingURL=index9.js.map

package/dist/log.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Scoped, leveled logging for the SDK. Default level is `info` — lifecycle
+ * events (pool spawn, memory bind, seed phases) are always visible; `debug`
+ * adds per-task dispatch/completion and `trace` adds per-message detail.
+ *
+ *   import { setLogLevel } from '…/index';
+ *   setLogLevel('debug'); // or 'trace', 'warn', 'off'
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'off';
+export interface LogEntry {
+    level: LogLevel;
+    scope: string;
+    message: string;
+    data?: unknown;
+    /** Which side of the boundary emitted this entry. */
+    thread: 'main' | 'worker';
+    /** performance.now() at emission — useful for sequencing across threads. */
+    at: number;
+}
+export type LogSink = (entry: LogEntry) => void;
+export declare const setLogLevel: (level: LogLevel) => void;
+export declare const getLogLevel: () => LogLevel;
+/** Replace the console sink (e.g. collect entries for a UI panel); null restores it. */
+export declare const setLogSink: (custom: LogSink | null) => void;
+export declare function log(level: Exclude<LogLevel, 'off'>, scope: string, message: string, data?: unknown): void;
+/** A logger bound to a subsystem scope: `poolLog.info('spawned')`. */
+export declare function scoped(scope: string): {
+    trace: (message: string, data?: unknown) => void;
+    debug: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+};
+/** Compact byte formatting for log output. */
+export declare const fmtBytes: (bytes: number) => string;