@dalgo/bigquery 0.0.0-stage → 0.3.0

package/dist/analytical/transport.js

@@ -0,0 +1,224 @@
+import { AnalyticalError, fail, parseJSON } from "./wire.js";
+import { operationDeadline } from "./deadline.js";
+import { same } from "./metadata.js";
+import { validatePrincipal } from "./protocol.js";
+export const realClock = {
+    now: () => Date.now(), sleep: (ms, signal) => new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new AnalyticalError("local_stopped"));
+            return;
+        }
+        const abort = () => { clearTimeout(timer); reject(new AnalyticalError("local_stopped")); };
+        const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);
+        signal?.addEventListener("abort", abort, {
+            once: true
+        });
+    })
+};
+// Bound injected providers/transports too: AbortSignal cooperation alone cannot
+// prove a deadline when an integration accidentally ignores cancellation.
+export function abortable(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(new AnalyticalError("local_stopped"));
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(new AnalyticalError("local_stopped"));
+        signal.addEventListener("abort", abort, {
+            once: true
+        });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort)).catch(() => { });
+    });
+}
+export class Transport {
+    #provider;
+    #fetch;
+    #clock;
+    constructor(provider, fetcher, clock) { this.#provider = provider; this.#fetch = fetcher; this.#clock = clock; }
+    async verify(principal, deadline, signal, rebind = false) {
+        if (signal?.aborted || this.#clock.now() >= deadline)
+            fail("local_stopped");
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        signal?.addEventListener("abort", abort, {
+            once: true
+        });
+        const timer = setTimeout(abort, deadline - this.#clock.now());
+        try {
+            let identity;
+            try {
+                identity = await abortable(this.#provider.authorize(controller.signal), controller.signal);
+            }
+            catch (error) {
+                if (error instanceof AnalyticalError)
+                    throw error;
+                fail("auth_required");
+            }
+            validatePrincipal(identity.principal);
+            if (rebind ? identity.principal.kind !== principal.kind || identity.principal.subject !== principal.subject : !same(identity.principal, principal))
+                fail("approval_changed");
+            if (typeof identity.accessToken !== "string" || !identity.accessToken || /[\r\n]/u.test(identity.accessToken))
+                fail("auth_required");
+            if (!Number.isSafeInteger(identity.expiresAt) || identity.expiresAt <= this.#clock.now())
+                fail("auth_expired");
+            if (!identity.read)
+                fail("scope_missing");
+            if (controller.signal.aborted || this.#clock.now() >= deadline)
+                fail("local_stopped");
+            return {
+                ...identity.principal
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async call(scope, method, path, query, body, control = false, cancel = false, beforeDispatch) {
+        if (!/^projects\/[A-Za-z0-9_-]+\/(?:datasets|queries|jobs)(?:\/[A-Za-z0-9_%./-]+)*$/u.test(path) || path.includes(".."))
+            fail("invalid_input");
+        const controlDeadline = this.#clock.now() + Math.min(15000, scope.bounds.httpMs);
+        const callerDeadline = control ? Math.min(scope.callerDeadline ?? Number.MAX_SAFE_INTEGER, controlDeadline) : scope.callerDeadline;
+        for (let attempt = 0; attempt < (method === "GET" ? 3 : 1); attempt += 1) {
+            if (scope.signal?.aborted)
+                fail("local_stopped");
+            const now = this.#clock.now();
+            const remaining = await scope.remaining();
+            const deadline = operationDeadline({
+                now, executionDeadline: scope.executionDeadline, httpLimitMs: scope.bounds.httpMs, control, bytesRemaining: BigInt(remaining), ...(callerDeadline === undefined ? {} : {
+                    callerDeadline
+                })
+            });
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            scope.signal?.addEventListener("abort", abort, {
+                once: true
+            });
+            const timer = setTimeout(abort, deadline - now);
+            let response;
+            let identity;
+            try {
+                try {
+                    identity = await abortable(this.#provider.authorize(controller.signal), controller.signal);
+                }
+                catch (error) {
+                    if (error instanceof AnalyticalError)
+                        throw error;
+                    fail("auth_required");
+                }
+                validatePrincipal(identity.principal);
+                if (!same(identity.principal, scope.principal))
+                    fail("approval_changed");
+                if (typeof identity.accessToken !== "string" || identity.accessToken.length < 1 || /[\r\n]/u.test(identity.accessToken))
+                    fail("auth_required");
+                if (!Number.isSafeInteger(identity.expiresAt) || identity.expiresAt <= this.#clock.now())
+                    fail("auth_expired");
+                if (!identity.read || (cancel && !identity.cancel))
+                    fail("scope_missing");
+                if (controller.signal.aborted || this.#clock.now() >= deadline)
+                    fail("local_stopped");
+                const url = `https://bigquery.googleapis.com/bigquery/v2/${path}${Object.keys(query).length === 0 ? "" : "?" + new URLSearchParams(query)}`;
+                const requestBody = body === undefined ? undefined : JSON.stringify(body);
+                await scope.beforeDispatch?.();
+                if (controller.signal.aborted || this.#clock.now() >= deadline)
+                    fail("local_stopped");
+                beforeDispatch?.();
+                try {
+                    response = await abortable(this.#fetch(url, {
+                        method, headers: {
+                            Authorization: `Bearer ${identity.accessToken}`, Accept: "application/json", ...(body === undefined ? {} : {
+                                "Content-Type": "application/json"
+                            })
+                        }, redirect: "error", credentials: "omit", cache: "no-store", signal: controller.signal, ...(requestBody === undefined ? {} : {
+                            body: requestBody
+                        })
+                    }), controller.signal);
+                }
+                catch {
+                    if (controller.signal.aborted)
+                        fail("local_stopped");
+                    fail(method === "POST" ? cancel ? "cancellation_unknown" : "submission_unknown" : "remote_failed");
+                }
+                if (controller.signal.aborted || this.#clock.now() >= deadline)
+                    fail("local_stopped");
+                if (response.redirected || response.status >= 300 && response.status < 400)
+                    fail(method === "POST" ? cancel ? "cancellation_unknown" : "submission_unknown" : "remote_failed");
+                const chunks = [];
+                let length = 0;
+                const reader = response.body?.getReader();
+                if (reader !== undefined) {
+                    try {
+                        while (true) {
+                            const item = await abortable(reader.read(), controller.signal);
+                            if (item.done)
+                                break;
+                            const chunk = item.value;
+                            await scope.debit(chunk.byteLength);
+                            length += chunk.byteLength;
+                            if (length > scope.bounds.responseBytes || controller.signal.aborted || this.#clock.now() >= deadline) {
+                                void reader.cancel().catch(() => { });
+                                fail(length > scope.bounds.responseBytes ? "response_limit" : "local_stopped");
+                            }
+                            chunks.push(chunk);
+                        }
+                    }
+                    catch (error) {
+                        try {
+                            void reader.cancel().catch(() => { });
+                        }
+                        catch { /* no provider body retained */ }
+                        if (error instanceof AnalyticalError)
+                            throw error;
+                        fail(method === "POST" ? cancel ? "cancellation_unknown" : "submission_unknown" : "remote_failed");
+                    }
+                    finally {
+                        reader.releaseLock();
+                    }
+                }
+                const raw = new Uint8Array(length);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    raw.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                if (controller.signal.aborted || this.#clock.now() >= deadline)
+                    fail("local_stopped");
+                if (response.status >= 200 && response.status < 300)
+                    return parseJSON(raw, scope.bounds.responseBytes);
+                // Provider bodies are charged but never copied into public errors/logs.
+                if (method === "GET" && [429, 500, 502, 503, 504].includes(response.status) && attempt < 2) {
+                    let delay = 100 * 2 ** attempt;
+                    const retry = response.headers.get("Retry-After");
+                    if (retry !== null) {
+                        if (/^[0-9]+$/u.test(retry))
+                            delay = Number(retry) * 1000;
+                        else {
+                            const date = Date.parse(retry);
+                            if (Number.isFinite(date))
+                                delay = Math.max(0, date - this.#clock.now());
+                        }
+                    }
+                    const next = operationDeadline({
+                        now: this.#clock.now(), executionDeadline: scope.executionDeadline, httpLimitMs: scope.bounds.httpMs, control, bytesRemaining: BigInt(await scope.remaining()), ...(callerDeadline === undefined ? {} : {
+                            callerDeadline
+                        })
+                    });
+                    if (this.#clock.now() + delay >= next)
+                        fail("local_stopped");
+                    await this.#clock.sleep(delay, scope.signal);
+                    continue;
+                }
+                if (response.status === 401)
+                    fail("auth_expired");
+                if (response.status === 403)
+                    fail("scope_missing");
+                if (response.status === 404)
+                    fail(control ? "remote_failed" : "result_expired");
+                fail(method === "POST" ? cancel ? "cancellation_unknown" : "submission_unknown" : "remote_failed");
+            }
+            finally {
+                clearTimeout(timer);
+                scope.signal?.removeEventListener("abort", abort);
+            }
+        }
+        return fail("remote_failed");
+    }
+}

package/dist/analytical/values.d.ts

@@ -0,0 +1,18 @@
+export interface AnalyticalField {
+    readonly name?: string;
+    readonly type: string;
+    readonly mode?: string;
+}
+export interface AnalyticalCell {
+    readonly type: string;
+    readonly value: string | boolean | null;
+}
+/** Preserve SQL NULL, exact decimal strings, JSON text and keyless row order.
+ * TIMESTAMP values use signed epoch microseconds in the foundation contract.
+ */
+export declare function normalizeScalar(field: AnalyticalField, value: unknown): AnalyticalCell;
+/** Fatal UTF-8 boundary for scalar bytes; never normalize replacement decoding. */
+export declare function normalizeScalarBytes(field: AnalyticalField, raw: Uint8Array): AnalyticalCell;
+/** Schema eligibility/precision metadata is a separate gate, not inferred here. */
+export declare function decodeRows(raw: Uint8Array, fields: readonly AnalyticalField[], limit?: number): readonly (readonly AnalyticalCell[])[];
+//# sourceMappingURL=values.d.ts.map

package/dist/analytical/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/analytical/values.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;AAC1G,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;CAAE;AAsClG;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAyEtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,cAAc,CAE5F;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,eAAe,EAAE,EAAE,KAAK,SAAqB,GAAG,SAAS,CAAC,SAAS,cAAc,EAAE,CAAC,EAAE,CAYlJ"}

package/dist/analytical/values.js

@@ -0,0 +1,157 @@
+import { assertUnicodeScalar, decodeUtf8, fail, isObject, MAX_RESPONSE_BYTES, parseJSON } from "./wire.js";
+const integer = /^-?(0|[1-9][0-9]*)$/u;
+const decimal = /^-?[0-9]+(\.[0-9]+)?$/u;
+const float = /^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?$/u;
+const clock = /^([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]{1,6})?$/u;
+const supported = new Set("INT64 NUMERIC BIGNUMERIC FLOAT64 BOOL STRING BYTES DATE TIME DATETIME TIMESTAMP JSON".split(" "));
+const encoder = new TextEncoder();
+/** RegExp $ can match before a trailing newline in JS; require every code unit. */
+function matches(expression, value) {
+    const match = expression.exec(value);
+    return match !== null && match[0].length === value.length;
+}
+function validDate(value) {
+    if (!matches(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, value))
+        return false;
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return year >= 1 && year <= 9999 && month >= 1 && month <= 12 && day >= 1 && day <= (days[month - 1] ?? 0);
+}
+function validClock(value) {
+    if (!matches(clock, value))
+        return false;
+    return Number(value.slice(0, 2)) < 24 && Number(value.slice(3, 5)) < 60 && Number(value.slice(6, 8)) < 60;
+}
+function validBase64(value) {
+    if (!matches(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u, value))
+        return false;
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    if (value.endsWith("=="))
+        return (alphabet.indexOf(value.at(-3) ?? "") & 15) === 0;
+    if (value.endsWith("="))
+        return (alphabet.indexOf(value.at(-2) ?? "") & 3) === 0;
+    return true;
+}
+/** Preserve SQL NULL, exact decimal strings, JSON text and keyless row order.
+ * TIMESTAMP values use signed epoch microseconds in the foundation contract.
+ */
+export function normalizeScalar(field, value) {
+    if (typeof field.type !== "string")
+        fail("invalid_input");
+    let type = field.type.toUpperCase();
+    type = { INTEGER: "INT64", FLOAT: "FLOAT64", BOOLEAN: "BOOL" }[type] ?? type;
+    if (!supported.has(type) || ![undefined, "", "NULLABLE", "REQUIRED"].includes(field.mode))
+        fail("unsupported_type");
+    if (value === null) {
+        if (field.mode === "REQUIRED")
+            fail("malformed_wire");
+        return { type, value: null };
+    }
+    if (typeof value !== "string")
+        fail("malformed_wire");
+    assertUnicodeScalar(value);
+    if (encoder.encode(value).byteLength > 1024 * 1024)
+        fail("response_limit");
+    let normalized = value;
+    switch (type) {
+        case "INT64":
+        case "TIMESTAMP": {
+            if (!matches(integer, value))
+                fail("unsupported_value");
+            const number = BigInt(value);
+            if (number < -9223372036854775808n || number > 9223372036854775807n)
+                fail("unsupported_value");
+            if (type === "TIMESTAMP" && (number < -62135596800000000n || number > 253402300799999999n))
+                fail("unsupported_value");
+            normalized = number.toString();
+            break;
+        }
+        case "NUMERIC":
+        case "BIGNUMERIC": {
+            if (!matches(decimal, value))
+                fail("unsupported_value");
+            const negative = value.startsWith("-");
+            const parts = (negative ? value.slice(1) : value).split(".");
+            const whole = (parts[0] ?? "").replace(/^0+/u, "") || "0";
+            const fraction = parts[1] ?? "";
+            const scale = fraction.length;
+            if (scale > (type === "NUMERIC" ? 9 : 38) || (whole === "0" ? 0 : whole.length) > (type === "NUMERIC" ? 29 : 39))
+                fail("unsupported_value");
+            if (type === "BIGNUMERIC") {
+                const scaled = BigInt(whole + fraction) * 10n ** BigInt(38 - scale);
+                if (scaled > (1n << 255n) - (negative ? 0n : 1n))
+                    fail("unsupported_value");
+            }
+            const trimmed = fraction.replace(/0+$/u, "");
+            normalized = whole + (trimmed === "" ? "" : `.${trimmed}`);
+            if (negative && normalized !== "0")
+                normalized = `-${normalized}`;
+            break;
+        }
+        case "FLOAT64": {
+            if (!matches(float, value))
+                fail("unsupported_value");
+            const number = Number(value);
+            if (!Number.isFinite(number))
+                fail("unsupported_value");
+            normalized = number.toString(); // ECMAScript NumberToString includes -0 -> 0.
+            break;
+        }
+        case "BOOL":
+            if (value !== "true" && value !== "false")
+                fail("unsupported_value");
+            normalized = value === "true";
+            break;
+        case "BYTES":
+            if (!validBase64(value))
+                fail("unsupported_value");
+            break;
+        case "DATE":
+            if (!validDate(value))
+                fail("unsupported_value");
+            break;
+        case "TIME":
+            if (!validClock(value))
+                fail("unsupported_value");
+            break;
+        case "DATETIME": {
+            let parts = value.split("T");
+            if (parts.length !== 2)
+                parts = value.split(" ");
+            if (parts.length !== 2 || !validDate(parts[0] ?? "") || !validClock(parts[1] ?? ""))
+                fail("unsupported_value");
+            normalized = `${parts[0]}T${parts[1]}`;
+            break;
+        }
+        case "JSON":
+            parseJSON(encoder.encode(value), 1024 * 1024);
+            break;
+    }
+    return { type, value: normalized };
+}
+/** Fatal UTF-8 boundary for scalar bytes; never normalize replacement decoding. */
+export function normalizeScalarBytes(field, raw) {
+    return normalizeScalar(field, decodeUtf8(raw));
+}
+/** Schema eligibility/precision metadata is a separate gate, not inferred here. */
+export function decodeRows(raw, fields, limit = MAX_RESPONSE_BYTES) {
+    if (fields.length < 1 || fields.length > 128)
+        fail("invalid_input");
+    const value = parseJSON(raw, limit);
+    if (!Array.isArray(value))
+        fail("malformed_wire");
+    if (value.length > 1000)
+        fail("response_limit");
+    return value.map((row) => {
+        if (!isObject(row) || Object.keys(row).length !== 1 || !Array.isArray(row.f) || row.f.length !== fields.length)
+            fail("malformed_wire");
+        return row.f.map((cell, index) => {
+            if (!isObject(cell) || Object.keys(cell).length !== 1 || !Object.hasOwn(cell, "v"))
+                fail("malformed_wire");
+            return normalizeScalar(fields[index], cell.v);
+        });
+    });
+}

package/dist/analytical/wire.d.ts

@@ -0,0 +1,26 @@
+/** Stable sanitized failures never retain provider bodies or query values. */
+export type AnalyticalErrorCode = "invalid_input" | "malformed_wire" | "response_limit" | "unsupported_type" | "unsupported_value" | "local_stopped" | "unsupported_query" | "policy_denied" | "no_policies" | "auth_required" | "auth_expired" | "scope_missing" | "source_ineligible" | "source_changed" | "approval_required" | "approval_changed" | "estimate_missing" | "cap_exceeded" | "budget_exhausted" | "schema_changed" | "cursor_invalid" | "result_expired" | "submission_unknown" | "remote_failed" | "cancellation_unknown";
+export declare class AnalyticalError extends Error {
+    readonly code: AnalyticalErrorCode;
+    constructor(code: AnalyticalErrorCode);
+}
+export declare function fail(code: AnalyticalErrorCode): never;
+export declare const MAX_RESPONSE_BYTES: number;
+export declare const MAX_DEPTH = 32;
+/** A JSON number token, preserved before any floating-point conversion. */
+export declare class JsonNumber {
+    readonly text: string;
+    constructor(text: string);
+}
+export type JsonValue = null | boolean | string | JsonNumber | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isObject(value: JsonValue): value is {
+    [key: string]: JsonValue;
+};
+/** JS direct strings must contain Unicode scalar values before UTF-8 encoding. */
+export declare function assertUnicodeScalar(value: string): void;
+export declare function decodeUtf8(raw: Uint8Array): string;
+/** Callers must cap decompressed reads before allocating the input buffer. */
+export declare function parseJSON(raw: Uint8Array, limit: number): JsonValue;
+//# sourceMappingURL=wire.d.ts.map

package/dist/analytical/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/analytical/wire.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,GAAG,aAAa,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,cAAc,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,eAAe,GAAG,sBAAsB,CAAC;AAE5gB,qBAAa,eAAgB,SAAQ,KAAK;aACL,IAAI,EAAE,mBAAmB;gBAAzB,IAAI,EAAE,mBAAmB;CAI7D;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,mBAAmB,GAAG,KAAK,CAErD;AAED,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,2EAA2E;AAC3E,qBAAa,UAAU;aACc,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAChD;AAED,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1G,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,IAAI;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAEhF;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAUvD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAKlD;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CA8DnE"}

package/dist/analytical/wire.js

@@ -0,0 +1,141 @@
+export class AnalyticalError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "AnalyticalError";
+    }
+}
+export function fail(code) {
+    throw new AnalyticalError(code);
+}
+export const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+export const MAX_DEPTH = 32;
+/** A JSON number token, preserved before any floating-point conversion. */
+export class JsonNumber {
+    text;
+    constructor(text) {
+        this.text = text;
+        Object.freeze(this);
+    }
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof JsonNumber);
+}
+/** JS direct strings must contain Unicode scalar values before UTF-8 encoding. */
+export function assertUnicodeScalar(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xdc00 && code <= 0xdfff)
+            fail("malformed_wire");
+        if (code >= 0xd800 && code <= 0xdbff) {
+            i += 1;
+            const low = value.charCodeAt(i);
+            if (!(low >= 0xdc00 && low <= 0xdfff))
+                fail("malformed_wire");
+        }
+    }
+}
+export function decodeUtf8(raw) {
+    try {
+        // Preserve BOM so JSON syntax rejects it; never silently strip input bytes.
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+    }
+    catch {
+        return fail("malformed_wire");
+    }
+}
+/** Callers must cap decompressed reads before allocating the input buffer. */
+export function parseJSON(raw, limit) {
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > MAX_RESPONSE_BYTES || raw.byteLength > limit)
+        fail("response_limit");
+    const text = decodeUtf8(raw);
+    let at = 0;
+    const whitespace = () => { while (" \t\r\n".includes(text[at] ?? "\0"))
+        at += 1; };
+    const string = () => {
+        const start = at;
+        at += 1;
+        while (at < text.length) {
+            const character = text[at];
+            at += 1;
+            if (character === "\\") {
+                at += 1;
+                continue;
+            }
+            if (character === '"') {
+                let result;
+                try {
+                    result = JSON.parse(text.slice(start, at));
+                }
+                catch {
+                    return fail("malformed_wire");
+                }
+                assertUnicodeScalar(result);
+                return result;
+            }
+        }
+        return fail("malformed_wire");
+    };
+    const value = (depth) => {
+        if (depth > MAX_DEPTH)
+            fail("response_limit");
+        whitespace();
+        const character = text[at];
+        if (character === '"')
+            return string();
+        if (character === "{" || character === "[") {
+            at += 1;
+            whitespace();
+            const object = character === "{";
+            const close = object ? "}" : "]";
+            const result = object ? Object.create(null) : [];
+            if (text[at] === close) {
+                at += 1;
+                return result;
+            }
+            while (true) {
+                if (object) {
+                    if (text[at] !== '"')
+                        fail("malformed_wire");
+                    const key = string();
+                    if (Object.hasOwn(result, key))
+                        fail("malformed_wire");
+                    whitespace();
+                    if (text[at] !== ":")
+                        fail("malformed_wire");
+                    at += 1;
+                    result[key] = value(depth + 1);
+                }
+                else {
+                    result.push(value(depth + 1));
+                }
+                whitespace();
+                if (text[at] === close) {
+                    at += 1;
+                    return result;
+                }
+                if (text[at] !== ",")
+                    fail("malformed_wire");
+                at += 1;
+                whitespace();
+            }
+        }
+        for (const [literal, result] of [["null", null], ["true", true], ["false", false]]) {
+            if (text.startsWith(literal, at)) {
+                at += literal.length;
+                return result;
+            }
+        }
+        const match = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/u.exec(text.slice(at));
+        if (match === null)
+            return fail("malformed_wire");
+        at += match[0].length;
+        return new JsonNumber(match[0]);
+    };
+    const result = value(0);
+    whitespace();
+    if (at !== text.length)
+        fail("malformed_wire");
+    return result;
+}

package/dist/analytical.d.ts

@@ -0,0 +1,27 @@
+/** Browser-compatible A0 analytical protocol with no DALgo runtime import.
+ * Consumers inject trusted identity, protected read policy and durable session storage.
+ */
+export { canonicalJSON, hashPayload } from "./analytical/canonical.js";
+export type { HashPayloadName, HashedPayload } from "./analytical/canonical.js";
+export { operationDeadline } from "./analytical/deadline.js";
+export type { DeadlineInput } from "./analytical/deadline.js";
+export { decodeRows, normalizeScalar, normalizeScalarBytes } from "./analytical/values.js";
+export type { AnalyticalCell, AnalyticalField } from "./analytical/values.js";
+export { AnalyticalError, JsonNumber, MAX_DEPTH, MAX_RESPONSE_BYTES, parseJSON } from "./analytical/wire.js";
+export type { AnalyticalErrorCode, JsonValue } from "./analytical/wire.js";
+export { BigQueryAnalyticalClient, AnalyticalRun, Approval, ExecutionFailure, queryRequest } from "./analytical/client.js";
+export type { ClientConfig, PreparedRead, OperationOptions, JobStatus, CancelResult } from "./analytical/client.js";
+export { compileReadPlan, bounds } from "./analytical/protocol.js";
+export type { SourceProfile, ReadQuery, ReadPlan, Parameter, CompiledPredicate, Principal, Execution, Bounds, SchemaField, Observation, JobRef, Receipt, Page } from "./analytical/protocol.js";
+export { IndexedDBLedger, MemoryLedger } from "./analytical/ledger.js";
+export type { Ledger, LedgerState, Preview } from "./analytical/ledger.js";
+export type { TrustedIdentity, IdentityProvider, Clock, SafeFetch } from "./analytical/transport.js";
+export { GoogleTokenIdentityProvider, googleAuthorizationScopes } from "./analytical/google-identity.js";
+export type { GoogleTokenResponse, GoogleIdentitySummary, GoogleIdentityConfig } from "./analytical/google-identity.js";
+export { BigQueryMetadataClient } from "./analytical/metadata-client.js";
+export type { MetadataSource, MetadataConsent, MetadataCurrentBinding, MetadataLimits, MetadataClientConfig, MetadataOptions, MetadataDiscovery } from "./analytical/metadata-client.js";
+export { MetadataFixtureHarness } from "./analytical/metadata-harness.js";
+export type { MetadataFixtureHarnessConfig } from "./analytical/metadata-harness.js";
+export { projectFixtureMetadata } from "./analytical/public-metadata.js";
+export type { PublicMetadataObservation, PublicMetadataField } from "./analytical/public-metadata.js";
+//# sourceMappingURL=analytical.d.ts.map

package/dist/analytical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytical.d.ts","sourceRoot":"","sources":["../src/analytical.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC7G,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3H,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACpH,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChM,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACvE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACrG,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AACzG,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACxH,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,sBAAsB,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzL,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,YAAY,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AACrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,YAAY,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/analytical.js

@@ -0,0 +1,14 @@
+/** Browser-compatible A0 analytical protocol with no DALgo runtime import.
+ * Consumers inject trusted identity, protected read policy and durable session storage.
+ */
+export { canonicalJSON, hashPayload } from "./analytical/canonical.js";
+export { operationDeadline } from "./analytical/deadline.js";
+export { decodeRows, normalizeScalar, normalizeScalarBytes } from "./analytical/values.js";
+export { AnalyticalError, JsonNumber, MAX_DEPTH, MAX_RESPONSE_BYTES, parseJSON } from "./analytical/wire.js";
+export { BigQueryAnalyticalClient, AnalyticalRun, Approval, ExecutionFailure, queryRequest } from "./analytical/client.js";
+export { compileReadPlan, bounds } from "./analytical/protocol.js";
+export { IndexedDBLedger, MemoryLedger } from "./analytical/ledger.js";
+export { GoogleTokenIdentityProvider, googleAuthorizationScopes } from "./analytical/google-identity.js";
+export { BigQueryMetadataClient } from "./analytical/metadata-client.js";
+export { MetadataFixtureHarness } from "./analytical/metadata-harness.js";
+export { projectFixtureMetadata } from "./analytical/public-metadata.js";

package/dist/database.d.ts

@@ -0,0 +1,35 @@
+import { Key, type Codec, type Database, type QueryPage, type ReadwriteTransaction, type RecordSnapshot, type StructuredQuery } from "@dalgo/core";
+import type { BigQueryDatabaseOptions } from "./types.js";
+export declare class BigQueryHttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** A completed BigQuery job reported a failure. The API error body is intentionally not retained. */
+/**
+ * DALgo adapter over BigQuery's REST jobs.query and jobs.getQueryResults APIs.
+ * It intentionally never accepts a service-account key or embeds access tokens.
+ */
+export declare class BigQueryDatabase implements Database {
+    #private;
+    constructor(options: BigQueryDatabaseOptions);
+    get<T>(key: Key, codec?: Codec<T>): Promise<RecordSnapshot<T>>;
+    getMany<T>(keys: readonly Key[], codec?: Codec<T>): Promise<readonly RecordSnapshot<T>[]>;
+    query<T>(query: StructuredQuery<T>): Promise<QueryPage<T>>;
+    /** BigQuery cannot atomically enforce a unique key, so DALgo insert is rejected. */
+    insert<T>(_key: Key, _data: T, _codec?: Codec<T>): Promise<void>;
+    /** BigQuery MERGE cannot prove DALgo replacement semantics for non-unique keys. */
+    set<T>(_key: Key, _data: T, _codec?: Codec<T>): Promise<void>;
+    update(_key: Key, _data: Readonly<Record<string, unknown>>): Promise<void>;
+    delete(_key: Key): Promise<void>;
+    runReadwriteTransaction<Result>(callback: (transaction: ReadwriteTransaction) => Promise<Result>): Promise<Result>;
+    private tableFor;
+    private tableForCollection;
+    private fieldForColumn;
+    private selectForTable;
+    private snapshot;
+    private runQuery;
+    private allRows;
+    private request;
+    private withDeadline;
+}
+//# sourceMappingURL=database.d.ts.map