orez-sync-cf-host 0.5.19 → 0.5.21

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createSyncDurableObject, createSyncWorker } from './host.js';
+export { createQueryCompiler } from './query-compiler.js';
+export { MutationApplicationError, isMutationApplicationError, registerMutators, } from './types.js';
+export { DEFAULT_TRANSACTION_QUERY_BUDGET, TransactionQueryBudgetError, executeTransactionQueryPlan, executeTransactionQueryPlanAsync, } from './transaction-query.js';
+export type { DeferredEffect, JsonPrimitive, JsonValue, MutatorContext, MutatorRegistry, MutatorSql, NormalizedClaims, PullCaps, QueryResolver, RegisteredMutator, SyncHostConfig, SyncHostEnv, ServiceBinding, SQLiteExecResult, SqlStatementMetadata, SyncSql, UpstreamConfig, VisibilityConfig, VisibilityFilter, ZeroSchemaConfig, } from './types.js';
+export type { SyncDurableObjectConstructor } from './host.js';
+export type { CompiledTransactionQueryNode, CompiledTransactionQueryPlan, CompiledTransactionQueryRelationship, TransactionQueryBinding, TransactionQueryBudget, TransactionQueryColumn, TransactionQueryColumnType, TransactionQueryExecutionOptions, TransactionQueryFormat, TransactionQueryWireValue, } from './transaction-query.js';
+export type { TransactionQueryCompiler } from './query-compiler.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createSyncDurableObject, createSyncWorker } from './host.js';
+export { createQueryCompiler } from './query-compiler.js';
+export { MutationApplicationError, isMutationApplicationError, registerMutators, } from './types.js';
+export { DEFAULT_TRANSACTION_QUERY_BUDGET, TransactionQueryBudgetError, executeTransactionQueryPlan, executeTransactionQueryPlanAsync, } from './transaction-query.js';

package/dist/mutation-error.d.ts

@@ -0,0 +1,9 @@
+export declare class MutationApplicationError extends Error {
+    readonly details: string;
+    constructor(details: string, message?: string);
+}
+export declare function isMutationApplicationError(error: unknown): error is {
+    name: string;
+    message: string;
+    details: string;
+};

package/dist/mutation-error.js

@@ -0,0 +1,23 @@
+// the app-rejection contract shared by every orez sync host and by
+// protocol-neutral authoring layers (on-zero adapters). classification is
+// STRUCTURAL, never instanceof: adapters must not depend on orez to reject a
+// mutation, and instanceof breaks across package copies (dual-package
+// installs, --into tarballs, workspace duplication). any error whose name is
+// 'MutationApplicationError' with string details/message is claiming this
+// contract deliberately.
+export class MutationApplicationError extends Error {
+    details;
+    constructor(details, message = details) {
+        super(message);
+        this.details = details;
+        this.name = 'MutationApplicationError';
+    }
+}
+export function isMutationApplicationError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const shaped = error;
+    return (shaped.name === 'MutationApplicationError' &&
+        typeof shaped.message === 'string' &&
+        typeof shaped.details === 'string');
+}

package/dist/node-wasm-loader.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node-wasm-loader.js

@@ -0,0 +1,22 @@
+import { Buffer } from 'node:buffer';
+import { readFileSync } from 'node:fs';
+import * as nodeModule from 'node:module';
+import { fileURLToPath } from 'node:url';
+const wasmModuleID = 'orez-sync-cf-host/wasm-module.wasm';
+const wasmModulePath = fileURLToPath(import.meta.resolve(wasmModuleID));
+const wasmBase64 = readFileSync(wasmModulePath).toString('base64');
+const wasmModuleSource = `import { Buffer } from 'node:buffer'
+export default new WebAssembly.Module(Buffer.from('${wasmBase64}', 'base64'))
+`;
+const virtualWasmModuleURL = `data:text/javascript;base64,${Buffer.from(wasmModuleSource).toString('base64')}`;
+const registerHooks = Reflect.get(nodeModule, 'registerHooks');
+if (!registerHooks) {
+    throw new Error('orez-sync-cf-host/node-wasm-loader requires Node 22.15 or newer');
+}
+registerHooks({
+    resolve(specifier, context, nextResolve) {
+        return specifier === wasmModuleID
+            ? { shortCircuit: true, url: virtualWasmModuleURL }
+            : nextResolve(specifier, context);
+    },
+});

package/dist/post-commit.d.ts

@@ -0,0 +1,13 @@
+export type DeferredEffect = () => void | Promise<void>;
+export type PostCommitEffects = {
+    /** discard effects from a storage-transaction attempt before starting another */
+    beginAttempt(): void;
+    defer(effect: DeferredEffect): void;
+    /** run the committed attempt's effects in order without rejecting */
+    runAfterCommit(onError: (error: unknown) => void): Promise<void>;
+};
+/**
+ * collect external work during a retryable transaction and run only the effects
+ * belonging to the attempt that commits.
+ */
+export declare function createPostCommitEffects(): PostCommitEffects;

package/dist/post-commit.js

@@ -0,0 +1,31 @@
+/**
+ * collect external work during a retryable transaction and run only the effects
+ * belonging to the attempt that commits.
+ */
+export function createPostCommitEffects() {
+    const effects = [];
+    return {
+        beginAttempt() {
+            effects.length = 0;
+        },
+        defer(effect) {
+            effects.push(effect);
+        },
+        async runAfterCommit(onError) {
+            const committed = effects.splice(0);
+            for (const effect of committed) {
+                try {
+                    await effect();
+                }
+                catch (error) {
+                    try {
+                        onError(error);
+                    }
+                    catch {
+                        // reporting must not turn a committed effect failure into a rejection
+                    }
+                }
+            }
+        },
+    };
+}

package/dist/query-compiler.d.ts

@@ -0,0 +1,4 @@
+import type { CompiledTransactionQueryPlan, TransactionQueryFormat } from './transaction-query.js';
+import type { ZeroSchemaConfig } from './types.js';
+export type TransactionQueryCompiler = (ast: unknown, format: TransactionQueryFormat) => CompiledTransactionQueryPlan;
+export declare function createQueryCompiler(schema: ZeroSchemaConfig): TransactionQueryCompiler;

package/dist/query-compiler.js

@@ -0,0 +1,4 @@
+import { engine_compile_query } from './wasm.js';
+export function createQueryCompiler(schema) {
+    return (ast, format) => engine_compile_query(schema, ast, format);
+}

package/dist/sql-storage-adapter.d.ts

@@ -0,0 +1,69 @@
+import type { CompiledTransactionQueryPlan, TransactionQueryBudget, TransactionQueryFormat } from './transaction-query.js';
+import type { MutatorSql, SQLiteExecResult, SqlStatementMetadata, SyncSql } from './types.js';
+type WireValue = {
+    kind: 'null';
+} | {
+    kind: 'integer';
+    value: string;
+} | {
+    kind: 'real';
+    value: number;
+} | {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'blob';
+    value: number[];
+};
+type WireRow = {
+    columns: string[];
+    values: WireValue[];
+};
+interface JsSyncDb {
+    exec(sql: string, params: WireValue[]): void;
+    query(sql: string, params: WireValue[]): WireRow[];
+}
+export type AdapterStats = {
+    execCalls: number;
+    queryCalls: number;
+    sqlMs: number;
+};
+export declare function assertHostSql(sql: string): void;
+export declare function decodeSqlParams(value: unknown): unknown[];
+/**
+ * The sole JS SQL adapter used by wasm. It is synchronous, consumes every
+ * cursor before returning, accepts positional `?` only, and never starts or
+ * finishes a transaction.
+ */
+export declare class SqlStorageSyncDb implements JsSyncDb {
+    private readonly sql;
+    private readonly recordRowsWritten;
+    readonly stats: AdapterStats;
+    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void);
+    resetStats(): void;
+    exec(sql: string, params: WireValue[]): void;
+    query(sql: string, params: WireValue[]): WireRow[];
+}
+/** Direct application SQL surface used for initialization and admin reads. */
+export declare class SqlStorageDirect implements SyncSql {
+    private readonly sql;
+    private readonly recordRowsWritten;
+    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void);
+    exec(sql: string, params?: readonly unknown[], _metadata?: SqlStatementMetadata): SQLiteExecResult;
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Row[];
+}
+/**
+ * Async-compatible consumer mutator surface. Each method fully completes and
+ * materializes its SqlStorage operation before its promise resolves, so an
+ * existing `await tx.query(...)` cannot carry a cursor across an await.
+ */
+export declare class SqlStorageMutatorTransaction implements MutatorSql {
+    private readonly direct;
+    private readonly compileQuery;
+    private readonly queryBudget?;
+    constructor(direct: SqlStorageDirect, compileQuery: (ast: unknown, format: TransactionQueryFormat) => CompiledTransactionQueryPlan, queryBudget?: Partial<TransactionQueryBudget> | undefined);
+    exec(sql: string, params?: readonly unknown[], metadata?: SqlStatementMetadata): Promise<SQLiteExecResult>;
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<Row[]>;
+    queryAst<Result = unknown>(ast: unknown, format: TransactionQueryFormat, queryName?: string): Promise<Result>;
+}
+export {};

package/dist/sql-storage-adapter.js

@@ -0,0 +1,194 @@
+import { executeTransactionQueryPlan } from './transaction-query.js';
+import { trackBillableCursorRows } from './write-safeguards.js';
+// Match transaction control only as the statement itself. CREATE TRIGGER uses
+// `... BEGIN ... END` for its body, which is valid DO SQL and not a transaction.
+const TX_SQL = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)(?=\s|;|$)/i;
+const NUMBERED_PARAMETER = /\?[0-9]+/;
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+export function assertHostSql(sql) {
+    if (TX_SQL.test(sql)) {
+        throw new TypeError('transaction SQL is host-owned and forbidden');
+    }
+    if (NUMBERED_PARAMETER.test(sql)) {
+        throw new TypeError('numbered parameters are forbidden; use positional ? bindings');
+    }
+}
+function decodeBinding(value, path = 'binding') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${path} must be a typed SQL value`);
+    }
+    const binding = value;
+    const keys = Object.keys(binding);
+    const assertValueShape = () => {
+        if (keys.length !== 2 || !keys.includes('kind') || !keys.includes('value')) {
+            throw new TypeError(`${path} must contain only kind and value`);
+        }
+    };
+    switch (binding.kind) {
+        case 'null':
+            if (keys.length !== 1 || keys[0] !== 'kind') {
+                throw new TypeError(`${path} null binding must contain only kind`);
+            }
+            return null;
+        case 'integer': {
+            assertValueShape();
+            if (typeof binding.value !== 'string') {
+                throw new TypeError(`${path}.value must be an i64 decimal string`);
+            }
+            if (!/^-?\d+$/.test(binding.value)) {
+                throw new TypeError(`${path}.value must be an i64 decimal string`);
+            }
+            let exact;
+            try {
+                exact = BigInt(binding.value);
+            }
+            catch {
+                throw new TypeError(`${path}.value must be an i64 decimal string`);
+            }
+            if (exact < -(1n << 63n) || exact > (1n << 63n) - 1n) {
+                throw new TypeError(`${path}.value is outside the i64 range`);
+            }
+            // SqlStorage does not accept bigint. Safe values can use Number; unsafe
+            // values use decimal text and rely on the destination's INTEGER affinity.
+            return exact >= MIN_SAFE && exact <= MAX_SAFE ? Number(exact) : binding.value;
+        }
+        case 'real': {
+            assertValueShape();
+            if (typeof binding.value !== 'number' || !Number.isFinite(binding.value)) {
+                throw new TypeError(`${path}.value must be a finite number`);
+            }
+            return binding.value;
+        }
+        case 'text': {
+            assertValueShape();
+            if (typeof binding.value !== 'string') {
+                throw new TypeError(`${path}.value must be a string`);
+            }
+            return binding.value;
+        }
+        case 'blob': {
+            assertValueShape();
+            if (!Array.isArray(binding.value) ||
+                binding.value.some((byte) => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
+                throw new TypeError(`${path}.value must be an array of bytes`);
+            }
+            return Uint8Array.from(binding.value).buffer;
+        }
+        default:
+            throw new TypeError(`${path}.kind must be null, integer, real, text, or blob`);
+    }
+}
+export function decodeSqlParams(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError('params must be an array');
+    return value.map((binding, index) => decodeBinding(binding, `params[${index}]`));
+}
+function encodeResult(value) {
+    if (value === null)
+        return { kind: 'null' };
+    if (typeof value === 'number') {
+        return Number.isInteger(value)
+            ? { kind: 'integer', value: String(value) }
+            : { kind: 'real', value };
+    }
+    if (typeof value === 'string')
+        return { kind: 'text', value };
+    if (value instanceof ArrayBuffer) {
+        return { kind: 'blob', value: Array.from(new Uint8Array(value)) };
+    }
+    if (ArrayBuffer.isView(value)) {
+        return {
+            kind: 'blob',
+            value: Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)),
+        };
+    }
+    throw new TypeError(`unsupported SqlStorage result: ${Object.prototype.toString.call(value)}`);
+}
+/**
+ * The sole JS SQL adapter used by wasm. It is synchronous, consumes every
+ * cursor before returning, accepts positional `?` only, and never starts or
+ * finishes a transaction.
+ */
+export class SqlStorageSyncDb {
+    sql;
+    recordRowsWritten;
+    stats = { execCalls: 0, queryCalls: 0, sqlMs: 0 };
+    constructor(sql, recordRowsWritten = () => { }) {
+        this.sql = sql;
+        this.recordRowsWritten = recordRowsWritten;
+    }
+    resetStats() {
+        this.stats.execCalls = 0;
+        this.stats.queryCalls = 0;
+        this.stats.sqlMs = 0;
+    }
+    exec(sql, params) {
+        assertHostSql(sql);
+        const start = performance.now();
+        trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten);
+        this.stats.execCalls++;
+        this.stats.sqlMs += performance.now() - start;
+    }
+    query(sql, params) {
+        assertHostSql(sql);
+        const start = performance.now();
+        const cursor = trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten);
+        const columns = [...cursor.columnNames];
+        // A SqlStorage cursor must be fully consumed before any await. Returning a
+        // materialized array here makes that property structural.
+        const rows = Array.from(cursor.raw()).map((values) => ({
+            columns,
+            values: values.map(encodeResult),
+        }));
+        this.stats.queryCalls++;
+        this.stats.sqlMs += performance.now() - start;
+        return rows;
+    }
+}
+/** Direct application SQL surface used for initialization and admin reads. */
+export class SqlStorageDirect {
+    sql;
+    recordRowsWritten;
+    constructor(sql, recordRowsWritten = () => { }) {
+        this.sql = sql;
+        this.recordRowsWritten = recordRowsWritten;
+    }
+    exec(sql, params = [], _metadata) {
+        assertHostSql(sql);
+        trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten).toArray();
+        const changes = Number(this.sql.exec('SELECT changes() AS changes').one()?.changes ?? 0);
+        return { changes };
+    }
+    query(sql, params = []) {
+        assertHostSql(sql);
+        return trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten).toArray();
+    }
+}
+/**
+ * Async-compatible consumer mutator surface. Each method fully completes and
+ * materializes its SqlStorage operation before its promise resolves, so an
+ * existing `await tx.query(...)` cannot carry a cursor across an await.
+ */
+export class SqlStorageMutatorTransaction {
+    direct;
+    compileQuery;
+    queryBudget;
+    constructor(direct, compileQuery, queryBudget) {
+        this.direct = direct;
+        this.compileQuery = compileQuery;
+        this.queryBudget = queryBudget;
+    }
+    async exec(sql, params = [], metadata) {
+        return this.direct.exec(sql, params, metadata);
+    }
+    async query(sql, params = []) {
+        return this.direct.query(sql, params);
+    }
+    async queryAst(ast, format, queryName) {
+        const compiled = this.compileQuery(ast, format);
+        return executeTransactionQueryPlan(compiled, (sql, params) => this.direct.query(sql, params), { queryName, budget: this.queryBudget });
+    }
+}

package/dist/transaction-query.d.ts

@@ -0,0 +1,72 @@
+export type TransactionQueryWireValue = {
+    kind: 'null';
+} | {
+    kind: 'integer';
+    value: string;
+} | {
+    kind: 'real';
+    value: number;
+} | {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'blob';
+    value: number[];
+};
+export type TransactionQueryBinding = {
+    kind: 'literal';
+    value: TransactionQueryWireValue;
+} | {
+    kind: 'parent_field';
+    field: string;
+};
+export type TransactionQueryColumnType = 'string' | 'number' | 'boolean' | 'json' | 'null';
+export type TransactionQueryColumn = {
+    name: string;
+    columnType: TransactionQueryColumnType;
+};
+export type CompiledTransactionQueryRelationship = {
+    name: string;
+    node: CompiledTransactionQueryNode;
+};
+export type CompiledTransactionQueryNode = {
+    table: string;
+    singular: boolean;
+    sql: string;
+    bindings: TransactionQueryBinding[];
+    columns: TransactionQueryColumn[];
+    relationships: CompiledTransactionQueryRelationship[];
+};
+export type CompiledTransactionQueryPlan = {
+    rootTable: string;
+    planHash: string;
+    root: CompiledTransactionQueryNode;
+};
+export type TransactionQueryBudget = {
+    maxSelects: number;
+    maxRows: number;
+};
+export type TransactionQueryExecutionOptions = {
+    queryName?: string;
+    budget?: Partial<TransactionQueryBudget>;
+};
+export type TransactionQueryFormat = {
+    singular: boolean;
+    relationships: Readonly<Record<string, TransactionQueryFormat>>;
+};
+export declare const DEFAULT_TRANSACTION_QUERY_BUDGET: TransactionQueryBudget;
+export declare class TransactionQueryBudgetError extends Error {
+    readonly query: string;
+    readonly selects: number;
+    readonly rows: number;
+    readonly maxSelects: number;
+    readonly maxRows: number;
+    readonly code = "transaction_query_budget_exceeded";
+    constructor(query: string, selects: number, rows: number, maxSelects: number, maxRows: number);
+}
+type MaterializedRow = Record<string, unknown>;
+type ExecuteSelect = (sql: string, params: readonly unknown[]) => readonly MaterializedRow[];
+type ExecuteSelectAsync = (sql: string, params: readonly unknown[]) => readonly MaterializedRow[] | Promise<readonly MaterializedRow[]>;
+export declare function executeTransactionQueryPlan<Result = unknown>(plan: CompiledTransactionQueryPlan, execute: ExecuteSelect, options?: TransactionQueryExecutionOptions): Result;
+export declare function executeTransactionQueryPlanAsync<Result = unknown>(plan: CompiledTransactionQueryPlan, execute: ExecuteSelectAsync, options?: TransactionQueryExecutionOptions): Promise<Result>;
+export {};