@oxilite/d1 0.2.2 → 0.5.0

package/README.md

@@ -23,6 +23,20 @@ npx oxilite-d1 schema > migrations/0001_oxilite.sql          # --no-graph-index
 npx wrangler d1 migrations apply my-graph --remote
 ```
 
+> **Upgrading to 0.3.0 from 0.2.x:** 0.3.0 adds the `schema_graphs`, `shapes_index`,
+> `shapes_in` and `datalog_work` tables. A D1 store is opened with `open_existing`, so no
+> DDL runs per request and an existing database will report `no such table: schema_graphs`
+> until you apply a new migration. Regenerate and apply it:
+>
+> ```bash
+> npx wrangler d1 migrations create my-graph oxilite-0-3-0
+> npx oxilite-d1 schema > migrations/0002_oxilite-0-3-0.sql
+> npx wrangler d1 migrations apply my-graph --remote
+> ```
+>
+> Every statement is `CREATE TABLE IF NOT EXISTS`, so re-applying it is safe and your data
+> is untouched.
+
 ## 2. Query it from a Worker
 
 ```ts
@@ -84,13 +98,32 @@ The same store runs on a Durable Object's embedded SQLite through a small adapte
 
 ## API
 
-`D1Store` mirrors Oxigraph's JavaScript `Store`, asynchronously: `query`, `queryJson`, `update`, `load`, `bulkLoad`, `dump`, `add`, `delete`, `has`, `match`, `size`, `clear`, plus `cypher`, `explain`, `explainUpdate`, `explainCypher`, `optimize`, `materialize` (OWL 2 RL as SQL rules), `clearInferences`, `jsonld(options)` and `credentials(options)`. Query options add `reasoning: "rdfs" | "owl-ql"` and `include_inferred`; create the store with `textIndex: true` for FTS5 search with `oxl:textMatch`.
+`D1Store` mirrors Oxigraph's JavaScript `Store`, asynchronously: `query`, `queryJson`, `update`, `load`, `bulkLoad`, `dump`, `add`, `delete`, `has`, `match`, `size`, `clear`, plus `cypher`, `explain`, `explainUpdate`, `explainCypher`, `optimize`, `materialize` (OWL 2 RL as SQL rules), `clearInferences`, `jsonld(options)` and `credentials(options)`. The [schema registry](https://github.com/Volland/oxilite/blob/main/docs/schema-registry.md) is there too: `registerSchemaGraph(graph, role, { appliesTo })`, `schemaGraphs()`, `setSchemaGraphActive`, `unregisterSchemaGraph`, `dropSchemaGraph`, `shapeIndex()`; registrations are RDF in `<oxilite:schema>`, written with the same portable SPARQL as on Oxigraph. `D1Store.open(db, { systemGraphs: true })` (or `npx oxilite-d1 schema --system-graphs`) starts a blank database with the `oxl:` vocabulary in `<oxilite:vocabulary>`; `installSystemGraphs()` adds it to an existing one. Query options add `reasoning: "rdfs" | "owl-ql"`, `include_inferred` and `include_schema_graphs`; create the store with `textIndex: true` for FTS5 search with `oxl:textMatch`.
 
 | Import | Use |
 |---|---|
 | `@oxilite/d1` | Workers: pass the wasm module (`@oxilite/d1/oxilite.wasm`) to `D1Store.open` |
 | `@oxilite/d1/node` | Node.js, tests and Miniflare: the wasm core loads itself |
-| `npx oxilite-d1 schema [--jsonld]` | Print the schema as a D1 migration (with the JSON-LD tables) |
+| `npx oxilite-d1 schema [--jsonld] [--versioning log]` | Print the schema as a D1 migration (with the JSON-LD tables, with versioning) |
+| `npx oxilite-d1 versioning-migration --from off --to log` | Print the migration that changes an existing database's versioning level |
+
+### Versioning
+
+Open or create the store with `versioning: "stamped"` (a store clock) or `"log"` (an immutable change log). Every D1 batch is then one commit:
+
+```ts
+const store = await D1Store.open(env.DB, { wasm, versioning: "log" });
+await store.withCommit({ author: "ada", message: "close t1" }, (s) => s.update(closeTicket));
+const before = await store.query(sparql, { as_of: "HEAD~1" });     // or "#42", "@2026-09-01T12:00:00Z"
+const diff = await store.diff("HEAD~1");                            // [{ tick, added, quad }]
+const log = await store.history(20);                                // [{ tick, time, kind, author, message, added, removed }]
+```
+
+`versioning()`, `setVersioning(level, { allowLoss })`, `setCommitInfo`, `changes(after)`, `resolveVersion` and `purge(pattern, reason)` complete the API. `SERVICE <oxilite:version/HEAD~1> { … }` compares versions inside one query, `GRAPH <oxilite:history>` reads commits and changes as RDF, and `cypher(q, {}, { asOf: "HEAD~1" })` matches the past. Measured on D1: `stamped` writes 4.82 rows per triple against 4.81 for a plain store, `log` 6.82 and `log` with `asOfIndex` 8.82. A store keeps its level: change an existing database with a migration.
+
+### Upgrading a 0.4 database
+
+0.5 moves the schema registry into the RDF graph `<oxilite:schema>` and adds a scope column to the reasoning cache. `D1Store.open(env.DB, { wasm })` (without `migrated: true`) upgrades a 0.4 database in one batch: registrations become triples, the `schema_graphs` table goes, and the cache is rebuilt. Do it once (for example from a one-off script or a deploy step), then keep opening with `migrated: true`; `openExisting` on a database that was not upgraded fails with a message saying so. New databases: regenerate `migrations/0001_oxilite.sql` with `npx oxilite-d1 schema`.
 
 ## Tips
 

package/bin/oxilite-d1.mjs

@@ -1,16 +1,55 @@
 #!/usr/bin/env node
-// Usage: npx oxilite-d1 schema [--no-graph-index] [--jsonld] [--no-metadata-indexes] > migrations/0001_oxilite.sql
+// Usage:
+//   npx oxilite-d1 schema [--no-graph-index] [--jsonld] [--no-metadata-indexes]
+//                         [--versioning off|stamped|log] [--as-of-index] [--stamp-index]
+//                         [--system-graphs] > migrations/0001_oxilite.sql
+//   npx oxilite-d1 versioning-migration --from off --to log [--as-of-index] [--stamp-index]
+//                         [--allow-loss] [--stamp-column] [--frozen-history] > migrations/0002_versioning.sql
 import { D1Store } from "../dist/node.js";
 
 const [command, ...args] = process.argv.slice(2);
+const value = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const usage = `usage:
+  oxilite-d1 schema [--no-graph-index] [--jsonld] [--no-metadata-indexes] [--versioning off|stamped|log] [--as-of-index] [--stamp-index] [--system-graphs]
+  oxilite-d1 versioning-migration --from LEVEL --to LEVEL [--as-of-index] [--stamp-index] [--allow-loss] [--stamp-column] [--frozen-history]`;
+
 if (command === "schema") {
   const jsonld = args.includes("--jsonld")
     ? args.includes("--no-metadata-indexes")
       ? { issuer: false, subject: false, validUntil: false }
       : true
     : false;
-  process.stdout.write(D1Store.schemaSql({ graphIndex: !args.includes("--no-graph-index"), jsonld }));
+  process.stdout.write(
+    D1Store.schemaSql({
+      graphIndex: !args.includes("--no-graph-index"),
+      jsonld,
+      versioning: value("--versioning") ?? "off",
+      asOfIndex: args.includes("--as-of-index"),
+      stampIndex: args.includes("--stamp-index"),
+      systemGraphs: args.includes("--system-graphs"),
+    }),
+  );
+} else if (command === "versioning-migration") {
+  const from = value("--from");
+  const to = value("--to");
+  if (!from || !to) {
+    console.error(usage);
+    process.exit(1);
+  }
+  process.stdout.write(`-- oxilite: versioning ${from} -> ${to} (generated by oxilite-d1 versioning-migration)\n`);
+  process.stdout.write(
+    D1Store.levelChangeSql(from, to, {
+      asOfIndex: args.includes("--as-of-index") || undefined,
+      stampIndex: args.includes("--stamp-index") || undefined,
+      allowLoss: args.includes("--allow-loss"),
+      stampColumn: args.includes("--stamp-column"),
+      history: args.includes("--frozen-history") ? "frozen" : "none",
+    }),
+  );
 } else {
-  console.error("usage: oxilite-d1 schema [--no-graph-index] [--jsonld] [--no-metadata-indexes]");
+  console.error(usage);
   process.exit(1);
 }

package/dist/driver.d.ts

@@ -1,4 +1,4 @@
-import { type CypherOptions, type CypherResult, type CypherValue, type CredentialOptions, type DocumentFilter, type Drift, type JsonLdOptions, type PresentationKeys, type StoredDocument, type Term, type DumpOptions, type LoadData, type LoadOptions, type Quad, type QueryOptions, type QueryResult, type TermLike } from "@oxilite/common";
+import { type CypherOptions, type DatalogMaterializeResult, type DatalogOptions, type DatalogResult, type CypherResult, type CypherValue, type CredentialOptions, type DocumentFilter, type Drift, type JsonLdOptions, type PresentationKeys, type StoredDocument, type Term, type DumpOptions, type LoadData, type LoadOptions, type Quad, type QueryOptions, type QueryResult, type TermLike, type Change, type CommitInfo, type CommitRecord, type LevelChange, type Versioning, type VersionStatus, type GraphArg, type PropertyShapeEntry, type SchemaGraphEntry, type SchemaRegistration, type SchemaRole } from "@oxilite/common";
 /** The subset of the Cloudflare D1 binding API used by oxilite. */
 export interface D1PreparedStatementLike {
     raw(): Promise<unknown[][]>;
@@ -26,6 +26,9 @@ export interface WasmEngine {
     queryJson(sparql: string): WasmJob;
     explain(sparql: string): string;
     cypher(query: string, params?: string | null, options?: string | null): WasmJob;
+    datalog?(program: string, options?: string | null): WasmJob;
+    datalog_materialize?(program: string, options?: string | null): WasmJob;
+    explain_datalog?(program: string, options?: string | null): string;
     explainCypher(query: string, params?: string | null, options?: string | null): string;
     update(sparql: string, baseIri?: string | null): WasmJob;
     explainUpdate(sparql: string): string;
@@ -40,7 +43,27 @@ export interface WasmEngine {
     clear(): WasmJob;
     materialize(): WasmJob;
     clearInferences(): WasmJob;
+    registerSchemaGraphSparql(graph: string, role: string, registration?: string | null): string;
+    unregisterSchemaGraphSparql(graph: string): string;
+    setSchemaGraphActiveSparql(graph: string, active: boolean): string;
+    dropSchemaGraphSparql(graph: string): string;
+    schemaGraphRegisteredSparql(graph: string): string;
+    graphSizeSparql(graph: string): string;
+    schemaGraphsSparql(): string;
+    schemaGraphsFromOutput(output: string): string;
+    systemGraphsSparql(): string;
+    systemGraphsReadySparql(): string;
+    shapeIndex(): WasmJob;
     schemaSql(): string;
+    versioning(): WasmJob;
+    setVersioning(level: string, change?: string | null): WasmJob;
+    levelChangeSql(from: string, to: string, change?: string | null, state?: string | null): string;
+    setCommitInfo(info?: string | null): void;
+    history(limit: number): WasmJob;
+    resolveVersion(version: string): WasmJob;
+    changes(after: number, until?: number | null): WasmJob;
+    diff(from: string, to: string): WasmJob;
+    purge(pattern: string, reason?: string | null): WasmJob;
     jsonld(op: string, args: string, options?: string | null): WasmJob;
     jsonldSchemaSql(indexes?: string | null): string;
 }
@@ -55,6 +78,22 @@ export interface D1StoreOptions {
     migrated?: boolean;
     /** Create the FTS5 full-text index over string literals (for `oxl:textMatch`). */
     textIndex?: boolean;
+    /**
+     * Versioning of a new store: `"off"` (default), `"stamped"` (a store clock and the tick that
+     * added each quad) or `"log"` (an immutable change log: history and time travel). An existing
+     * store keeps its level: change it with `setVersioning` or a migration.
+     */
+    versioning?: Versioning;
+    /** With `"log"`: index the change log by predicate and object (faster as-of queries). */
+    asOfIndex?: boolean;
+    /** With `"stamped"` or `"log"`: index the tick that added each quad. */
+    stampIndex?: boolean;
+    /**
+     * Install the system graphs in a blank store: the oxilite vocabulary in `<oxilite:vocabulary>`
+     * and the schema registry's own description in `<oxilite:schema>` (default false, so a new
+     * store is empty as in Oxigraph).
+     */
+    systemGraphs?: boolean;
 }
 /** An oxilite RDF store on a Cloudflare D1 database. */
 export declare class D1Store {
@@ -85,6 +124,28 @@ export declare class D1Store {
      * writing statement reads, then applies its changes as one D1 batch.
      */
     cypher(query: string, params?: Record<string, CypherValue>, options?: CypherOptions): Promise<CypherResult>;
+    /** The tick a version reference (`"HEAD~2"`, `"#42"`, `"@2026-09-01T00:00:00Z"`) designates. */
+    resolveVersion(version: string): Promise<number>;
+    /**
+     * A Datalog program over the same quads: recursive rules with stratified negation,
+     * constraints and aggregation. A program whose recursion is linear is one SQL statement, so
+     * it costs one round trip here as it does anywhere; a component that has to be iterated
+     * costs one per round, which `rounds` reports.
+     */
+    datalog(program: string, options?: DatalogOptions): Promise<DatalogResult>;
+    /**
+     * Stores what a Datalog program derives as inferences, in the table OWL 2 RL
+     * materialization uses, so SPARQL and Cypher see them with `includeInferred`. The writes
+     * are one D1 batch.
+     */
+    datalogMaterialize(program: string, options?: DatalogOptions): Promise<DatalogMaterializeResult>;
+    /** How a Datalog program runs: its strata, the strategy per recursive component, the SQL. */
+    explainDatalog(program: string, options?: DatalogOptions): string;
+    /**
+     * The Datalog frontend is an opt-in feature of the WebAssembly core, so say which build is
+     * needed rather than failing with "not a function".
+     */
+    private requireDatalog;
     /** How a Cypher statement runs: its SPARQL, the SQL, and what runs in Rust. */
     explainCypher(query: string, params?: Record<string, CypherValue>, options?: CypherOptions): string;
     /** SPARQL query: `Map[]` for SELECT, `boolean` for ASK, `Quad[]` for CONSTRUCT/DESCRIBE, or a string with `results_format`. */
@@ -93,6 +154,35 @@ export declare class D1Store {
     queryJson(query: string): Promise<string>;
     /** The SQL a query compiles to, with join orders and warnings. */
     explain(query: string): string;
+    /** The versioning level of the store and where its clock and history stand. */
+    versioning(): Promise<VersionStatus>;
+    /**
+     * Changes the versioning level. Upgrades keep every quad (the upgrade to `"log"` records the
+     * whole store as its genesis commit); a downgrade freezes the history and stops the clock,
+     * and deletes them only with `allowLoss`. On a production D1 database prefer a migration
+     * (`npx oxilite-d1 versioning-migration`).
+     */
+    setVersioning(level: Versioning, change?: LevelChange): Promise<VersionStatus>;
+    /** Author and message recorded on the commits of the following writes (until changed). */
+    setCommitInfo(info?: CommitInfo): void;
+    /** Runs `f` with `info` recorded on its writes. */
+    withCommit<T>(info: CommitInfo, f: (store: this) => Promise<T>): Promise<T>;
+    /** The latest commits and level changes, newest first. */
+    history(limit?: number): Promise<CommitRecord[]>;
+    /** The changes after tick `after` (up to `until`), in order. */
+    changes(after?: number, until?: number): Promise<Change[]>;
+    /** The net difference between two versions (`"HEAD~1"`, `"#42"`, `"@2026-09-01T00:00:00Z"`). */
+    diff(from: string, to?: string): Promise<Change[]>;
+    /**
+     * Removes the quads matching the pattern from the store and from its whole history, for
+     * erasure requests; the purge is recorded without the removed content.
+     */
+    purge(pattern: {
+        subject?: TermLike;
+        predicate?: TermLike;
+        object?: TermLike;
+        graph?: TermLike;
+    }, reason?: string): Promise<void>;
     /** SPARQL update, applied atomically in one D1 batch. */
     update(update: string, options?: {
         base_iri?: string;
@@ -121,6 +211,28 @@ export declare class D1Store {
     materialize(): Promise<number>;
     /** Removes every materialized inference. */
     clearInferences(): Promise<void>;
+    /**
+     * Declares a graph to hold an ontology, SHACL shapes or a ShEx schema, and (`appliesTo`) the
+     * graphs it describes. One atomic batch that also rebuilds the reasoning closure and the
+     * shape index; the graph's triples stay where they are.
+     */
+    registerSchemaGraph(graph: GraphArg, role: SchemaRole, registration?: SchemaRegistration): Promise<void>;
+    /** The schema registry, ordered by role and graph. */
+    schemaGraphs(): Promise<SchemaGraphEntry[]>;
+    private registered;
+    /** Activates or deactivates a registration; returns whether one was found. */
+    setSchemaGraphActive(graph: GraphArg, active: boolean): Promise<boolean>;
+    /** Removes a registration, keeping the graph's triples; returns whether one was found. */
+    unregisterSchemaGraph(graph: GraphArg): Promise<boolean>;
+    /** Removes a registration and every quad of its graph; returns how many quads it held. */
+    dropSchemaGraph(graph: GraphArg): Promise<number>;
+    /**
+     * Installs or refreshes the system graphs (`<oxilite:vocabulary>`, `<oxilite:schema>`'s own
+     * description) in an existing database; returns `false` when they were already current.
+     */
+    installSystemGraphs(): Promise<boolean>;
+    /** The compiled SHACL property shapes of the registered shapes graphs. */
+    shapeIndex(): Promise<PropertyShapeEntry[]>;
     /** Refreshes planner statistics (run after large imports). */
     optimize(): Promise<void>;
     clear(): Promise<void>;

package/dist/driver.js

@@ -3,7 +3,7 @@
 // The core (WebAssembly) never touches the database. Each operation is a job: the driver
 // feeds it the response of every request it asks for, until it is done. Atomic requests
 // become one `db.batch()` — D1's only transaction.
-import { JsonLdError, cypherResult, documentText, filterJson, fromJson, jsonLdError, storedDocument, loadDataToString, outputToResult, toJson, } from "@oxilite/common";
+import { JsonLdError, cypherResult, datalogResult, documentText, filterJson, fromJson, jsonLdError, storedDocument, graphJson, registrationJson, toSchemaGraphs, toShapeIndex, toChanges, loadDataToString, outputToResult, toJson, } from "@oxilite/common";
 /** A term hash collision (two different terms with the same 59-bit id). */
 export class OxiliteCollisionError extends Error {
 }
@@ -11,6 +11,8 @@ function mapError(e) {
     const message = e instanceof Error ? e.message : String(e);
     if (message.includes("oxilite: term hash collision"))
         return new OxiliteCollisionError(message);
+    if (message.includes("no such column: scope"))
+        return new Error("this D1 database has the oxilite 0.4 schema: open it once with D1Store.open(db) (without `migrated`) to upgrade it, then regenerate your migration with `npx oxilite-d1 schema`");
     if (message.includes("graph_does_not_exist"))
         return new Error("the graph does not exist");
     if (message.includes("graph_already_exists"))
@@ -32,7 +34,14 @@ export class D1Store {
         this.engine = engine;
     }
     static async openWith(Engine, db, options = {}) {
-        const engine = new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true, textIndex: options.textIndex ?? false }));
+        const engine = new Engine(null, JSON.stringify({
+            graphIndex: options.graphIndex ?? true,
+            textIndex: options.textIndex ?? false,
+            versioning: options.versioning ?? "off",
+            asOfIndex: options.asOfIndex ?? false,
+            stampIndex: options.stampIndex ?? false,
+            systemGraphs: options.systemGraphs ?? false,
+        }));
         const store = new D1Store(db, engine);
         await store.run(options.migrated ? engine.openExisting() : engine.open());
         return store;
@@ -107,9 +116,52 @@ export class D1Store {
      * writing statement reads, then applies its changes as one D1 batch.
      */
     async cypher(query, params = {}, options = {}) {
-        const out = (await this.run(this.engine.cypher(query, JSON.stringify(params), JSON.stringify(options))));
+        // A version is resolved once, so every read of the statement sees the same tick.
+        const opts = { ...options };
+        if (options.asOf !== undefined) {
+            opts.asOfTick = await this.resolveVersion(options.asOf);
+        }
+        const out = (await this.run(this.engine.cypher(query, JSON.stringify(params), JSON.stringify(opts))));
         return cypherResult(out);
     }
+    /** The tick a version reference (`"HEAD~2"`, `"#42"`, `"@2026-09-01T00:00:00Z"`) designates. */
+    async resolveVersion(version) {
+        return (await this.run(this.engine.resolveVersion(version))).value;
+    }
+    /**
+     * A Datalog program over the same quads: recursive rules with stratified negation,
+     * constraints and aggregation. A program whose recursion is linear is one SQL statement, so
+     * it costs one round trip here as it does anywhere; a component that has to be iterated
+     * costs one per round, which `rounds` reports.
+     */
+    async datalog(program, options = {}) {
+        const datalog = this.requireDatalog(this.engine.datalog);
+        const out = (await this.run(datalog(program, JSON.stringify(options))));
+        return datalogResult(out);
+    }
+    /**
+     * Stores what a Datalog program derives as inferences, in the table OWL 2 RL
+     * materialization uses, so SPARQL and Cypher see them with `includeInferred`. The writes
+     * are one D1 batch.
+     */
+    async datalogMaterialize(program, options = {}) {
+        const materialize = this.requireDatalog(this.engine.datalog_materialize);
+        return (await this.run(materialize(program, JSON.stringify(options))));
+    }
+    /** How a Datalog program runs: its strata, the strategy per recursive component, the SQL. */
+    explainDatalog(program, options = {}) {
+        return this.requireDatalog(this.engine.explain_datalog)(program, JSON.stringify(options));
+    }
+    /**
+     * The Datalog frontend is an opt-in feature of the WebAssembly core, so say which build is
+     * needed rather than failing with "not a function".
+     */
+    requireDatalog(method) {
+        if (method === undefined) {
+            throw new Error("this build of the oxilite WebAssembly core has no Datalog frontend; rebuild it with the `datalog` feature");
+        }
+        return method.bind(this.engine);
+    }
     /** How a Cypher statement runs: its SPARQL, the SQL, and what runs in Rust. */
     explainCypher(query, params = {}, options = {}) {
         return this.engine.explainCypher(query, JSON.stringify(params), JSON.stringify(options));
@@ -136,6 +188,57 @@ export class D1Store {
     explain(query) {
         return this.engine.explain(query);
     }
+    // ---------------------------------------------------------------------------- versioning
+    /** The versioning level of the store and where its clock and history stand. */
+    async versioning() {
+        return (await this.run(this.engine.versioning()));
+    }
+    /**
+     * Changes the versioning level. Upgrades keep every quad (the upgrade to `"log"` records the
+     * whole store as its genesis commit); a downgrade freezes the history and stops the clock,
+     * and deletes them only with `allowLoss`. On a production D1 database prefer a migration
+     * (`npx oxilite-d1 versioning-migration`).
+     */
+    async setVersioning(level, change = {}) {
+        return (await this.run(this.engine.setVersioning(level, JSON.stringify(change))));
+    }
+    /** Author and message recorded on the commits of the following writes (until changed). */
+    setCommitInfo(info = {}) {
+        this.engine.setCommitInfo(JSON.stringify(info));
+    }
+    /** Runs `f` with `info` recorded on its writes. */
+    async withCommit(info, f) {
+        this.setCommitInfo(info);
+        try {
+            return await f(this);
+        }
+        finally {
+            this.setCommitInfo({});
+        }
+    }
+    /** The latest commits and level changes, newest first. */
+    async history(limit = 20) {
+        return (await this.run(this.engine.history(limit)));
+    }
+    /** The changes after tick `after` (up to `until`), in order. */
+    async changes(after = 0, until) {
+        return toChanges(await this.run(this.engine.changes(after, until ?? null)));
+    }
+    /** The net difference between two versions (`"HEAD~1"`, `"#42"`, `"@2026-09-01T00:00:00Z"`). */
+    async diff(from, to = "HEAD") {
+        return toChanges(await this.run(this.engine.diff(from, to)));
+    }
+    /**
+     * Removes the quads matching the pattern from the store and from its whole history, for
+     * erasure requests; the purge is recorded without the removed content.
+     */
+    async purge(pattern, reason) {
+        const json = {};
+        for (const [k, v] of Object.entries(pattern))
+            if (v)
+                json[k] = toJson(v);
+        await this.run(this.engine.purge(JSON.stringify(json), reason ?? null));
+    }
     /** SPARQL update, applied atomically in one D1 batch. */
     async update(update, options = {}) {
         await this.run(this.engine.update(update, options.base_iri ?? null));
@@ -195,6 +298,58 @@ export class D1Store {
     async clearInferences() {
         await this.run(this.engine.clearInferences());
     }
+    // The schema registry is RDF in <oxilite:schema>: the core builds the portable SPARQL, and
+    // this driver runs it like any other query or update.
+    /**
+     * Declares a graph to hold an ontology, SHACL shapes or a ShEx schema, and (`appliesTo`) the
+     * graphs it describes. One atomic batch that also rebuilds the reasoning closure and the
+     * shape index; the graph's triples stay where they are.
+     */
+    async registerSchemaGraph(graph, role, registration = {}) {
+        await this.update(this.engine.registerSchemaGraphSparql(graphJson(graph), role, registrationJson(registration)));
+    }
+    /** The schema registry, ordered by role and graph. */
+    async schemaGraphs() {
+        const out = await this.run(this.engine.query(this.engine.schemaGraphsSparql()));
+        return toSchemaGraphs(JSON.parse(this.engine.schemaGraphsFromOutput(JSON.stringify(out))));
+    }
+    async registered(graph) {
+        return (await this.query(this.engine.schemaGraphRegisteredSparql(graphJson(graph)))) === true;
+    }
+    /** Activates or deactivates a registration; returns whether one was found. */
+    async setSchemaGraphActive(graph, active) {
+        if (!(await this.registered(graph)))
+            return false;
+        await this.update(this.engine.setSchemaGraphActiveSparql(graphJson(graph), active));
+        return true;
+    }
+    /** Removes a registration, keeping the graph's triples; returns whether one was found. */
+    async unregisterSchemaGraph(graph) {
+        if (!(await this.registered(graph)))
+            return false;
+        await this.update(this.engine.unregisterSchemaGraphSparql(graphJson(graph)));
+        return true;
+    }
+    /** Removes a registration and every quad of its graph; returns how many quads it held. */
+    async dropSchemaGraph(graph) {
+        const rows = (await this.query(this.engine.graphSizeSparql(graphJson(graph))));
+        await this.update(this.engine.dropSchemaGraphSparql(graphJson(graph)));
+        return Number(rows[0]?.get("n")?.value ?? 0);
+    }
+    /**
+     * Installs or refreshes the system graphs (`<oxilite:vocabulary>`, `<oxilite:schema>`'s own
+     * description) in an existing database; returns `false` when they were already current.
+     */
+    async installSystemGraphs() {
+        if ((await this.query(this.engine.systemGraphsReadySparql())) === true)
+            return false;
+        await this.update(this.engine.systemGraphsSparql());
+        return true;
+    }
+    /** The compiled SHACL property shapes of the registered shapes graphs. */
+    async shapeIndex() {
+        return toShapeIndex(await this.run(this.engine.shapeIndex()));
+    }
     /** Refreshes planner statistics (run after large imports). */
     async optimize() {
         await this.run(this.engine.optimize());

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { D1Store as Base, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+import type { LevelChange, Versioning } from "@oxilite/common";
 export * from "@oxilite/common";
 export { OxiliteCollisionError, D1Credentials, D1JsonLdDocuments, type D1DatabaseLike, type D1StoreOptions, } from "./driver.js";
 /** Initializes the WebAssembly core (a `WebAssembly.Module`, bytes, or a URL/Response). */
@@ -19,6 +20,19 @@ export declare class D1Store {
             subject?: boolean;
             validUntil?: boolean;
         };
+        versioning?: Versioning;
+        asOfIndex?: boolean;
+        stampIndex?: boolean;
+        systemGraphs?: boolean;
+        wasm?: WebAssembly.Module | BufferSource;
+    }): Promise<string>;
+    /**
+     * The SQL that changes the versioning level of an existing D1 database (for
+     * `wrangler d1 migrations`). `state` describes the database when it was lowered before.
+     */
+    static levelChangeSql(from: Versioning, to: Versioning, options?: LevelChange & {
+        stampColumn?: boolean;
+        history?: "none" | "frozen";
         wasm?: WebAssembly.Module | BufferSource;
     }): Promise<string>;
 }

package/dist/index.js

@@ -4,10 +4,19 @@
 //   import wasm from "@oxilite/d1/oxilite.wasm";
 //   const store = await D1Store.open(env.DB, { wasm });
 import init, { Engine, initSync } from "../wasm/web/oxilite_wasm.js";
-import { D1Store as Base } from "./driver.js";
+import { D1Store as Base, } from "./driver.js";
 export * from "@oxilite/common";
 export { OxiliteCollisionError, D1Credentials, D1JsonLdDocuments, } from "./driver.js";
 let ready = false;
+function engineOptions(o) {
+    return JSON.stringify({
+        graphIndex: o.graphIndex ?? true,
+        versioning: o.versioning ?? "off",
+        asOfIndex: o.asOfIndex ?? false,
+        stampIndex: o.stampIndex ?? false,
+        systemGraphs: o.systemGraphs ?? false,
+    });
+}
 /** Initializes the WebAssembly core (a `WebAssembly.Module`, bytes, or a URL/Response). */
 export async function initOxilite(wasm) {
     if (ready)
@@ -32,9 +41,19 @@ export class D1Store {
      */
     static async schemaSql(options = {}) {
         await initOxilite(options.wasm);
-        const e = new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true }));
+        const e = new Engine(null, engineOptions(options));
         if (options.jsonld)
             return e.jsonldSchemaSql(JSON.stringify(options.jsonld === true ? {} : options.jsonld));
         return e.schemaSql();
     }
+    /**
+     * The SQL that changes the versioning level of an existing D1 database (for
+     * `wrangler d1 migrations`). `state` describes the database when it was lowered before.
+     */
+    static async levelChangeSql(from, to, options = {}) {
+        await initOxilite(options.wasm);
+        const { stampColumn, history, wasm: _wasm, ...change } = options;
+        const e = new Engine(null, null);
+        return e.levelChangeSql(from, to, JSON.stringify(change), JSON.stringify({ stampColumn, history }));
+    }
 }

package/dist/node.d.ts

@@ -1,4 +1,5 @@
 import { D1Store as Base, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+import type { LevelChange, Versioning } from "@oxilite/common";
 export * from "@oxilite/common";
 export { OxiliteCollisionError, D1Credentials, D1JsonLdDocuments, type D1DatabaseLike, type D1StoreOptions, } from "./driver.js";
 export declare class D1Store {
@@ -11,5 +12,17 @@ export declare class D1Store {
             subject?: boolean;
             validUntil?: boolean;
         };
+        versioning?: Versioning;
+        asOfIndex?: boolean;
+        stampIndex?: boolean;
+        systemGraphs?: boolean;
+    }): string;
+    /**
+     * The SQL that changes the versioning level of an existing D1 database (for
+     * `wrangler d1 migrations`). `stampColumn` / `history` describe a database lowered before.
+     */
+    static levelChangeSql(from: Versioning, to: Versioning, options?: LevelChange & {
+        stampColumn?: boolean;
+        history?: "none" | "frozen";
     }): string;
 }

package/dist/node.js

@@ -1,6 +1,6 @@
 // @oxilite/d1 for Node.js (tests, scripts, Miniflare): the WebAssembly core loads itself.
 import { createRequire } from "node:module";
-import { D1Store as Base } from "./driver.js";
+import { D1Store as Base, } from "./driver.js";
 export * from "@oxilite/common";
 export { OxiliteCollisionError, D1Credentials, D1JsonLdDocuments, } from "./driver.js";
 const require = createRequire(import.meta.url);
@@ -11,9 +11,24 @@ export class D1Store {
     }
     /** The schema as SQL; `jsonld` adds the JSON-LD document tables. */
     static schemaSql(options = {}) {
-        const e = new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true }));
+        const e = new Engine(null, JSON.stringify({
+            graphIndex: options.graphIndex ?? true,
+            versioning: options.versioning ?? "off",
+            asOfIndex: options.asOfIndex ?? false,
+            stampIndex: options.stampIndex ?? false,
+            systemGraphs: options.systemGraphs ?? false,
+        }));
         if (options.jsonld)
             return e.jsonldSchemaSql(JSON.stringify(options.jsonld === true ? {} : options.jsonld));
         return e.schemaSql();
     }
+    /**
+     * The SQL that changes the versioning level of an existing D1 database (for
+     * `wrangler d1 migrations`). `stampColumn` / `history` describe a database lowered before.
+     */
+    static levelChangeSql(from, to, options = {}) {
+        const { stampColumn, history, ...change } = options;
+        const e = new Engine(null, null);
+        return e.levelChangeSql(from, to, JSON.stringify(change), JSON.stringify({ stampColumn, history }));
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxilite/d1",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "oxilite on Cloudflare D1 and Durable Objects: an Oxigraph-compatible SPARQL 1.1 and openCypher store (WebAssembly core)",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -32,7 +32,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@oxilite/common": "0.2.2"
+    "@oxilite/common": "0.5.0"
   },
   "devDependencies": {
     "miniflare": "^4"