@auersperg/flare 0.0.0-stage → 0.3.1

package/dist/sdk/database.js

@@ -0,0 +1,265 @@
+import { FlareError, boundedJson, stableJson } from "./protocol.js";
+import {
+  documentValue,
+  fieldSql,
+  quote
+} from "./schema.js";
+const scalar = (v) => v === null || typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+const bind = (v) => typeof v === "boolean" ? Number(v) : v;
+const checkedId = (id) => {
+  if (typeof id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id))
+    throw new FlareError("INVALID_INPUT", "Invalid document ID");
+};
+const size = (limit) => {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new FlareError("INVALID_INPUT", "Page size must be 1..100");
+};
+export function database(sql, schema, writable, touched = new Set, changed = new Set) {
+  let active = true;
+  const pending = new Set;
+  let operations = 0;
+  const check = () => {
+    if (!active)
+      throw new FlareError("CAPABILITY_EXPIRED", "Database invocation ended");
+  };
+  const writing = () => {
+    check();
+    if (!writable)
+      throw new FlareError("READ_ONLY", "Queries cannot write");
+  };
+  function table(name) {
+    check();
+    if (!Object.hasOwn(schema, name))
+      throw new FlareError("INVALID_TABLE", "Unknown table");
+    touched.add(name);
+    return schema[name];
+  }
+  const task = (fn, count = true) => {
+    if (count && ++operations > 1000) {
+      const rejected = Promise.reject(new FlareError("LIMIT_EXCEEDED", "Maximum 1000 database operations per invocation"));
+      rejected.catch(() => {
+        return;
+      });
+      pending.add(rejected);
+      return rejected;
+    }
+    const promise = fn();
+    pending.add(promise);
+    promise.then(() => pending.delete(promise), () => {
+      return;
+    });
+    return promise;
+  };
+  const decode = (row) => ({
+    ...JSON.parse(String(row._data)),
+    _id: String(row._id),
+    _creationTime: Number(row._creationTime)
+  });
+  const get = (name, id) => task(async () => {
+    table(name);
+    checkedId(id);
+    const row = sql.exec(`SELECT * FROM ${quote(name)} WHERE _id=?`, id).toArray()[0];
+    return row ? decode(row) : null;
+  });
+  function query(name) {
+    const definition = table(name);
+    function make(index, filters, direction) {
+      const page = (options) => task(async () => {
+        table(name);
+        size(options.limit);
+        const fields = [
+          ...index ? definition.indexes[index] : [],
+          "_creationTime",
+          "_id"
+        ];
+        const expressions = fields.map(fieldSql);
+        const signature = stableJson({ name, index, filters, direction });
+        const where = filters.map((f) => `${fieldSql(f.field)} ${f.operator === "=" ? "IS" : f.operator} ?`);
+        const bindings = filters.map((f) => bind(f.value));
+        if (options.cursor != null) {
+          let token;
+          try {
+            if (options.cursor.length > 8192)
+              throw Error();
+            token = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(options.cursor), (c) => c.charCodeAt(0))));
+          } catch {
+            throw new FlareError("INVALID_CURSOR", "Invalid cursor");
+          }
+          if (token.signature !== signature || !Array.isArray(token.values) || token.values.length !== fields.length || !token.values.every(scalar))
+            throw new FlareError("INVALID_CURSOR", "Cursor belongs to a different query");
+          const terms = expressions.map((expr, i) => {
+            const prefix = expressions.slice(0, i).map((e) => `${e} IS ?`);
+            bindings.push(...token.values.slice(0, i).map(bind));
+            const value = token.values[i];
+            if (value === null)
+              prefix.push(direction === "asc" ? `${expr} IS NOT NULL` : "0");
+            else {
+              prefix.push(direction === "asc" ? `${expr} > ?` : `(${expr} < ? OR ${expr} IS NULL)`);
+              bindings.push(bind(value));
+            }
+            return "(" + prefix.join(" AND ") + ")";
+          });
+          where.push("(" + terms.join(" OR ") + ")");
+        }
+        const rows = sql.exec(`SELECT *,${expressions.map((e, i) => `${e} AS __k${i}`).join(",")} FROM ${quote(name)} ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY ${expressions.map((e) => `${e} ${direction}`).join(",")} LIMIT ?`, ...bindings, options.limit + 1).toArray();
+        let more = rows.length > options.limit;
+        if (more)
+          rows.pop();
+        const docs = [];
+        let bytes = 2;
+        for (const row of rows) {
+          const doc = decode(row), length = new TextEncoder().encode(JSON.stringify(doc)).length + (docs.length ? 1 : 0);
+          if (bytes + length > 262144) {
+            more = true;
+            break;
+          }
+          docs.push(doc);
+          bytes += length;
+        }
+        const last = rows[docs.length - 1];
+        const continueCursor = more && last ? btoa(String.fromCharCode(...new TextEncoder().encode(boundedJson({
+          signature,
+          values: expressions.map((_, i) => last[`__k${i}`])
+        }, 6144)))) : null;
+        boundedJson(docs, 262144);
+        return { page: docs, continueCursor, isDone: !more };
+      });
+      return Object.freeze({
+        withIndex(next, range) {
+          check();
+          if (index || !Object.hasOwn(definition.indexes, next))
+            throw new FlareError("INVALID_INDEX", "Unknown or duplicate index");
+          const selected = [], fields = definition.indexes[next];
+          let pos = 0, open = true;
+          const bounds = new Set;
+          const add = (operator) => (field, value) => {
+            if (!open)
+              throw new FlareError("CAPABILITY_EXPIRED", "Index range declaration ended");
+            if (!scalar(value) || operator !== "=" && value === null || !fields.includes(field) || field !== fields[pos])
+              throw new FlareError("INVALID_INPUT", "Index range must follow its field order");
+            const bound = operator === "=" ? "equal" : operator.startsWith(">") ? "lower" : "upper";
+            if (bound === "equal" && bounds.size || bounds.has(bound))
+              throw new FlareError("INVALID_INPUT", "Duplicate or mixed index bounds");
+            selected.push({ field, operator, value });
+            if (operator === "=") {
+              pos++;
+              bounds.clear();
+            } else
+              bounds.add(bound);
+            if (selected.length > fields.length + 2)
+              throw new FlareError("INVALID_INPUT", "Index range exceeds limits");
+            return q;
+          };
+          const q = Object.freeze({
+            eq: add("="),
+            gt: add(">"),
+            gte: add(">="),
+            lt: add("<"),
+            lte: add("<=")
+          });
+          try {
+            if (range && range(q) !== q)
+              throw new FlareError("INVALID_INPUT", "Invalid index range");
+          } finally {
+            open = false;
+          }
+          return make(next, Object.freeze([...selected]), direction);
+        },
+        order(next) {
+          check();
+          if (!["asc", "desc"].includes(next))
+            throw new FlareError("INVALID_INPUT", "Invalid order");
+          return make(index, filters, next);
+        },
+        paginate: page,
+        take(limit) {
+          return task(async () => {
+            const result = await page({ limit });
+            if (!result.isDone && result.page.length < limit)
+              throw new FlareError("TOO_LARGE", "Use paginate for large documents");
+            return result.page;
+          }, false);
+        },
+        first() {
+          return task(async () => (await page({ limit: 1 })).page[0] ?? null, false);
+        }
+      });
+    }
+    return make(null, [], "asc");
+  }
+  const read = { get, query };
+  const write = {
+    insert(name, input) {
+      return task(async () => {
+        writing();
+        const definition = table(name), value = await documentValue(definition, input);
+        writing();
+        const id = crypto.randomUUID();
+        sql.exec(`INSERT INTO ${quote(name)} VALUES (?,?,?)`, id, Date.now(), stableJson(value));
+        changed.add(name);
+        return id;
+      });
+    },
+    patch(name, id, patch) {
+      return task(async () => {
+        writing();
+        const definition = table(name);
+        checkedId(id);
+        boundedJson(patch, 65536);
+        if (!patch || Array.isArray(patch) || typeof patch !== "object")
+          throw new FlareError("INVALID_INPUT", "Invalid patch");
+        const row = sql.exec(`SELECT _data FROM ${quote(name)} WHERE _id=?`, id).toArray()[0];
+        if (!row)
+          throw new FlareError("NOT_FOUND", "Document not found");
+        const value = await documentValue(definition, {
+          ...JSON.parse(String(row._data)),
+          ...patch
+        });
+        writing();
+        sql.exec(`UPDATE ${quote(name)} SET _data=? WHERE _id=?`, stableJson(value), id);
+        changed.add(name);
+      });
+    },
+    replace(name, id, input) {
+      return task(async () => {
+        writing();
+        const definition = table(name);
+        checkedId(id);
+        const value = await documentValue(definition, input);
+        writing();
+        const rows = sql.exec(`UPDATE ${quote(name)} SET _data=? WHERE _id=? RETURNING _id`, stableJson(value), id).toArray();
+        if (!rows.length)
+          throw new FlareError("NOT_FOUND", "Document not found");
+        changed.add(name);
+      });
+    },
+    delete(name, id) {
+      return task(async () => {
+        writing();
+        table(name);
+        checkedId(id);
+        if (!sql.exec(`DELETE FROM ${quote(name)} WHERE _id=? RETURNING _id`, id).toArray().length)
+          throw new FlareError("NOT_FOUND", "Document not found");
+        changed.add(name);
+      });
+    }
+  };
+  return {
+    db: Object.freeze(writable ? { ...read, ...write } : read),
+    async finish() {
+      try {
+        while (pending.size) {
+          const settled = await Promise.allSettled([...pending]);
+          const failed = settled.find((result) => result.status === "rejected");
+          if (failed?.status === "rejected")
+            throw failed.reason;
+        }
+      } finally {
+        active = false;
+      }
+    },
+    revoke() {
+      active = false;
+    }
+  };
+}

package/dist/sdk/protocol.d.ts

@@ -0,0 +1,47 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type FunctionKind = "query" | "mutation" | "action";
+export type Auth = {
+    subject: string;
+    issuer: string;
+    expiresAt: number;
+    claims: Record<string, Json>;
+};
+export declare const LIMITS: Readonly<{
+    inputBytes: 65536;
+    outputBytes: 262144;
+    frameBytes: 8192;
+    subscriptions: 64;
+    fileBytes: 10485760;
+}>;
+export interface FunctionRef<I = Json, O = Json> {
+    readonly path: string;
+    readonly kind: FunctionKind;
+    readonly __input?: I;
+    readonly __output?: O;
+}
+export declare class FlareError extends Error {
+    readonly code: string;
+    readonly ambiguous: boolean;
+    constructor(code: string, message: string, ambiguous?: boolean);
+}
+/** SDK entrypoints and retained pre-rename releases are separately bundled.
+ * Keep their bounded error-code wire contract, never their private messages. */
+export declare function errorCode(error: unknown): string;
+export declare function assertPath(path: string): void;
+export declare function reference<I, O>(path: string, kind: FunctionKind): FunctionRef<I, O>;
+/** Lossless JSON only: no implicit Date, undefined, NaN or prototype coercion. */
+export declare function stableJson(value: unknown): string;
+export declare function boundedJson(value: unknown, maxBytes: number): string;
+export interface FunctionContract {
+    kind: FunctionKind;
+    auth: "required" | "public" | "internal";
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+}
+export interface Manifest {
+    protocol: 1;
+    runtimeAbi: 4;
+    functions: Record<string, FunctionContract>;
+}

package/dist/sdk/protocol.js

@@ -0,0 +1,76 @@
+export const LIMITS = Object.freeze({
+  inputBytes: 65536,
+  outputBytes: 262144,
+  frameBytes: 8192,
+  subscriptions: 64,
+  fileBytes: 10485760
+});
+
+export class FlareError extends Error {
+  code;
+  ambiguous;
+  constructor(code, message, ambiguous = false) {
+    super(message);
+    this.code = code;
+    this.ambiguous = ambiguous;
+    this.name = "FlareError";
+  }
+}
+export function errorCode(error) {
+  if (error instanceof Error && ["FlareError", "FlaredError"].includes(error.name)) {
+    const code = error.code;
+    if (typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code))
+      return code;
+  }
+  return "OPERATION_FAILED";
+}
+export function assertPath(path) {
+  if (path.length > 256 || !/^[A-Za-z][A-Za-z0-9_]*(\/[A-Za-z][A-Za-z0-9_]*)*$/.test(path) || path.split("/").some((p) => ["__proto__", "prototype", "constructor"].includes(p))) {
+    throw new FlareError("INVALID_PATH", "Invalid function path");
+  }
+}
+export function reference(path, kind) {
+  assertPath(path);
+  return Object.freeze({ path, kind });
+}
+export function stableJson(value) {
+  const ancestors = new Set;
+  function visit(v, depth) {
+    if (depth > 40)
+      throw new FlareError("INVALID_JSON", "JSON nesting limit exceeded");
+    if (v === null || typeof v === "string" || typeof v === "boolean")
+      return v;
+    if (typeof v === "number" && Number.isFinite(v))
+      return v;
+    if (typeof v !== "object" || v === null || ancestors.has(v))
+      throw new FlareError("INVALID_JSON", "Expected lossless JSON");
+    if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+      throw new FlareError("INVALID_JSON", "Expected plain JSON object");
+    }
+    if (Object.getOwnPropertySymbols(v).length)
+      throw new FlareError("INVALID_JSON", "Symbol keys are unsupported");
+    ancestors.add(v);
+    let result;
+    if (Array.isArray(v)) {
+      result = Array.from(v, (item) => visit(item, depth + 1));
+    } else {
+      const out = Object.create(null);
+      for (const key of Object.keys(v).sort()) {
+        const descriptor = Object.getOwnPropertyDescriptor(v, key);
+        if (!("value" in descriptor))
+          throw new FlareError("INVALID_JSON", "Getters are unsupported");
+        out[key] = visit(descriptor.value, depth + 1);
+      }
+      result = out;
+    }
+    ancestors.delete(v);
+    return result;
+  }
+  return JSON.stringify(visit(value, 0));
+}
+export function boundedJson(value, maxBytes) {
+  const json = stableJson(value);
+  if (new TextEncoder().encode(json).byteLength > maxBytes)
+    throw new FlareError("TOO_LARGE", "JSON payload exceeds limit");
+  return json;
+}

package/dist/sdk/react.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { FlareClient } from "./client.js";
+import { FlareError, type FunctionRef } from "./protocol.js";
+/** The application owns the client; the provider never creates or disposes it. */
+export declare function FlareProvider({ client, children, }: {
+    client: FlareClient;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<{
+    query: <I, O>(ref: FunctionRef<I, O>, args: I) => Promise<O>;
+    mutation: <I, O>(ref: FunctionRef<I, O>, args: I) => Promise<O>;
+    action: <I, O>(ref: FunctionRef<I, O>, args: I) => Promise<O>;
+    onUpdate<I, O>(ref: FunctionRef<I, O>, args: I, next: (value: O) => void, error?: (error: FlareError) => void): () => void;
+    refreshAuth(): void;
+    dispose(): void;
+} | null>>;
+export declare function useFlare(): FlareClient;
+/** Initial snapshot and updates in one subscription. Undefined means loading/skipped. */
+export declare function useQuery<I, O>(ref: FunctionRef<I, O>, args: I | "skip"): O | undefined;

package/dist/sdk/react.js

@@ -0,0 +1,46 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import { FlareError, stableJson } from "./protocol.js";
+const ClientContext = createContext(null);
+export function FlareProvider({
+  client,
+  children
+}) {
+  return createElement(ClientContext.Provider, { value: client }, children);
+}
+export function useFlare() {
+  const client = useContext(ClientContext);
+  if (!client)
+    throw new FlareError("MISSING_PROVIDER", "Wrap your app in FlareProvider");
+  return client;
+}
+export function useQuery(ref, args) {
+  const client = useFlare();
+  if (ref.kind !== "query")
+    throw new FlareError("INVALID_KIND", "useQuery requires a query");
+  const key = args === "skip" ? undefined : stableJson(args);
+  const stableArgs = useMemo(() => key === undefined ? undefined : JSON.parse(key), [key]);
+  const identity = useMemo(() => ({ client, path: ref.path, args: key }), [client, ref.path, key]);
+  const [state, setState] = useState({ identity });
+  useEffect(() => {
+    setState({ identity });
+    if (key === undefined)
+      return;
+    return client.onUpdate(ref, stableArgs, (value) => setState({ identity, value }), (error) => {
+      if (["LIVE_DISCONNECTED", "LIVE_UNAVAILABLE"].includes(error.code))
+        return;
+      setState({ identity, error });
+    });
+  }, [client, ref.path, stableArgs, key, identity]);
+  if (key === undefined || state.identity !== identity)
+    return;
+  if (state.error)
+    throw state.error;
+  return state.value;
+}

package/dist/sdk/schema.d.ts

@@ -0,0 +1,43 @@
+import type { StandardSchemaV1, StandardJSONSchemaV1 } from "@standard-schema/spec";
+import { type Json } from "./protocol.js";
+export type SqlValue = ArrayBuffer | string | number | null;
+/** The small structural portion of native storage needed by the adapter; no Worker globals in public types. */
+export interface NativeSql {
+    exec<T extends Record<string, SqlValue> = Record<string, SqlValue>>(query: string, ...bindings: SqlValue[]): {
+        toArray(): T[];
+        one(): T;
+    };
+}
+export interface NativeStorage {
+    sql: NativeSql;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    sync(): Promise<void>;
+}
+export type Validator<I = unknown, O = I> = StandardSchemaV1<I, O> & StandardJSONSchemaV1<I, O>;
+export interface Table<V extends Validator = Validator<any, any>, I extends Record<string, readonly string[]> = Record<string, readonly string[]>> {
+    readonly validator: V;
+    readonly indexes: I;
+    index<const N extends string, const F extends readonly (keyof StandardSchemaV1.InferOutput<V> & string)[]>(name: N, fields: F): Table<V, I & Record<N, F>>;
+}
+/** Runtime schema needs only immutable validators and indexes, not builder methods. */
+export type TableDefinition = Pick<Table, "validator" | "indexes">;
+export type Schema = Record<string, TableDefinition>;
+export type Value<T extends TableDefinition> = StandardSchemaV1.InferOutput<T["validator"]>;
+export type Input<T extends TableDefinition> = StandardSchemaV1.InferInput<T["validator"]>;
+export type Doc<T extends TableDefinition> = Value<T> & {
+    readonly _id: string;
+    readonly _creationTime: number;
+};
+export type SchemaContract = Record<string, {
+    document: Record<string, any>;
+    indexes: Record<string, readonly string[]>;
+}>;
+export declare function identifier(name: string): string;
+export declare const quote: (name: string) => string;
+export declare const fieldSql: (field: string) => string;
+export declare function defineTable<V extends Validator>(validator: V): Table<V, {}>;
+export declare function schemaContract(schema: Schema): SchemaContract;
+export declare function assertSchemaContract(contract: SchemaContract): void;
+export declare function defineSchema<const S extends Schema>(schema: S): S;
+export declare function documentValue(table: TableDefinition, input: unknown): Promise<Record<string, Json>>;
+export declare function applySchema(storage: NativeStorage, schema: Schema): Promise<void>;

package/dist/sdk/schema.js

@@ -0,0 +1,143 @@
+import { FlareError, boundedJson, stableJson } from "./protocol.js";
+export function identifier(name) {
+  if (!/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/.test(name) || name.toLowerCase().startsWith("sqlite_"))
+    throw new FlareError("INVALID_SCHEMA", "Invalid table, index or field name");
+  return name;
+}
+export const quote = (name) => {
+  if (!/^[a-zA-Z][a-zA-Z0-9_]{0,127}$/.test(name))
+    throw new FlareError("INVALID_SCHEMA", "Invalid SQL identifier");
+  return `"${name}"`;
+};
+export const fieldSql = (field) => field === "_id" || field === "_creationTime" ? `"${field}"` : `json_extract("_data", '$.${identifier(field)}')`;
+const indexName = (table, index) => `idx_${table.length}_${table}_${index}`;
+const creationIndex = (table) => `creation_${table}`;
+export function defineTable(validator) {
+  function table(indexes) {
+    return Object.freeze({
+      validator,
+      indexes: Object.freeze(indexes),
+      index(name, fields) {
+        identifier(name);
+        if (Object.hasOwn(indexes, name) || !fields.length || fields.length > 4 || new Set(fields).size !== fields.length)
+          throw new FlareError("INVALID_SCHEMA", "Invalid index");
+        fields.forEach(identifier);
+        return table({ ...indexes, [name]: Object.freeze([...fields]) });
+      }
+    });
+  }
+  return table({});
+}
+export function schemaContract(schema) {
+  const out = Object.create(null);
+  if (Object.keys(schema).length > 100)
+    throw new FlareError("INVALID_SCHEMA", "Maximum 100 tables");
+  for (const [name, table] of Object.entries(schema)) {
+    identifier(name);
+    const document = table.validator["~standard"].jsonSchema.output({
+      target: "draft-2020-12"
+    });
+    out[name] = { document, indexes: table.indexes };
+  }
+  assertSchemaContract(out);
+  return out;
+}
+export function assertSchemaContract(contract) {
+  boundedJson(contract, 1048576);
+  if (!contract || Array.isArray(contract) || typeof contract !== "object" || Object.keys(contract).length > 100)
+    throw new FlareError("INVALID_SCHEMA", "Invalid schema");
+  const names = new Set;
+  for (const [name, table] of Object.entries(contract)) {
+    if (names.has(name.toLowerCase()))
+      throw new FlareError("INVALID_SCHEMA", "SQLite table names are case-insensitive");
+    names.add(name.toLowerCase());
+    identifier(name);
+    const doc = table?.document;
+    if (!doc || doc.type !== "object" || !doc.properties || doc.additionalProperties !== false)
+      throw new FlareError("INVALID_SCHEMA", "Tables require a closed object validator");
+    for (const field of Object.keys(doc.properties))
+      identifier(field);
+    if (Object.keys(doc.properties).length > 64 || !table.indexes || Object.keys(table.indexes).length > 20)
+      throw new FlareError("INVALID_SCHEMA", "Schema exceeds limits");
+    const indexes = new Set;
+    for (const [index, fields] of Object.entries(table.indexes)) {
+      if (indexes.has(index.toLowerCase()))
+        throw new FlareError("INVALID_SCHEMA", "SQLite index names are case-insensitive");
+      indexes.add(index.toLowerCase());
+      identifier(index);
+      if (!Array.isArray(fields) || fields.length < 1 || fields.length > 4 || new Set(fields).size !== fields.length)
+        throw new FlareError("INVALID_SCHEMA", "Invalid index fields");
+      for (const field of fields) {
+        identifier(field);
+        const p = doc.properties[field];
+        const scalar = (s) => Array.isArray(s?.type) && s.type.every((type) => ["string", "number", "integer", "boolean", "null"].includes(type)) || ["string", "number", "integer", "boolean", "null"].includes(s?.type) || Array.isArray(s?.anyOf) && s.anyOf.every(scalar);
+        if (!p || !scalar(p))
+          throw new FlareError("INVALID_SCHEMA", "Indexes require declared scalar fields");
+      }
+    }
+  }
+}
+export function defineSchema(schema) {
+  schemaContract(schema);
+  return Object.freeze(schema);
+}
+const documents = new WeakMap;
+function documentSchema(table) {
+  let doc = documents.get(table.validator);
+  if (!doc) {
+    doc = table.validator["~standard"].jsonSchema.output({
+      target: "draft-2020-12"
+    });
+    documents.set(table.validator, doc);
+  }
+  return doc;
+}
+export async function documentValue(table, input) {
+  boundedJson(input, 65536);
+  const properties = documentSchema(table).properties ?? {};
+  if (!input || Array.isArray(input) || typeof input !== "object" || Object.keys(input).some((k) => !Object.hasOwn(properties, k)))
+    throw new FlareError("INVALID_INPUT", "Unknown document field");
+  const result = await table.validator["~standard"].validate(input);
+  if (result.issues || !result.value || Array.isArray(result.value) || typeof result.value !== "object" || Object.keys(result.value).some((k) => !Object.hasOwn(properties, k)))
+    throw new FlareError("INVALID_INPUT", "Document failed schema validation");
+  return JSON.parse(boundedJson(result.value, 65536));
+}
+export async function applySchema(storage, schema) {
+  const contract = schemaContract(schema), encoded = stableJson(contract);
+  await storage.transaction(async () => {
+    storage.sql.exec("CREATE TABLE IF NOT EXISTS _flared_schema (id INTEGER PRIMARY KEY CHECK(id=1), contract TEXT NOT NULL)");
+    const oldRow = storage.sql.exec("SELECT contract FROM _flared_schema WHERE id=1").toArray()[0];
+    if (oldRow?.contract === encoded)
+      return;
+    const old = oldRow ? JSON.parse(String(oldRow.contract)) : {};
+    for (const name of Object.keys(old))
+      if (!Object.hasOwn(schema, name)) {
+        if (storage.sql.exec(`SELECT 1 FROM ${quote(name)} LIMIT 1`).toArray().length)
+          throw new FlareError("INVALID_SCHEMA", "Cannot remove a nonempty table; explicitly clear it first");
+        storage.sql.exec(`DROP TABLE ${quote(name)}`);
+      }
+    for (const [name, definition] of Object.entries(contract)) {
+      storage.sql.exec(`CREATE TABLE IF NOT EXISTS ${quote(name)} (_id TEXT PRIMARY KEY, _creationTime REAL NOT NULL, _data TEXT NOT NULL CHECK(json_valid(_data)))`);
+      let cursor = "";
+      while (!old[name] || stableJson(old[name].document) !== stableJson(definition.document)) {
+        const rows = storage.sql.exec(`SELECT _id,_data FROM ${quote(name)} WHERE _id > ? ORDER BY _id LIMIT 100`, cursor).toArray();
+        for (const row of rows) {
+          const value = await documentValue(schema[name], JSON.parse(String(row._data)));
+          if (stableJson(value) !== stableJson(JSON.parse(String(row._data))))
+            storage.sql.exec(`UPDATE ${quote(name)} SET _data=? WHERE _id=?`, stableJson(value), row._id);
+        }
+        if (rows.length < 100)
+          break;
+        cursor = String(rows.at(-1)._id);
+      }
+      storage.sql.exec(`CREATE INDEX IF NOT EXISTS ${quote(creationIndex(name))} ON ${quote(name)} (_creationTime,_id)`);
+      for (const [index, fields] of Object.entries(old[name]?.indexes ?? {}))
+        if (stableJson(definition.indexes[index] ?? null) !== stableJson(fields))
+          storage.sql.exec(`DROP INDEX IF EXISTS ${quote(indexName(name, index))}`);
+      for (const [index, fields] of Object.entries(definition.indexes))
+        storage.sql.exec(`CREATE INDEX IF NOT EXISTS ${quote(indexName(name, index))} ON ${quote(name)} (${[...fields.map(fieldSql), "_creationTime", "_id"].join(",")})`);
+    }
+    storage.sql.exec("INSERT INTO _flared_schema VALUES (1,?) ON CONFLICT(id) DO UPDATE SET contract=excluded.contract", encoded);
+  });
+  await storage.sync();
+}