@gnolith/taproot 0.1.0-rc.0 → 0.2.0

package/docs/release-policy.md

@@ -11,6 +11,10 @@ inspects the packed artifact, publishes to npm through OIDC trusted publishing,
 and attaches the tarball, SBOM, checksums, and build attestation to a GitHub
 Release.
 
+A Taproot release qualifies the published package and its supported local
+runtime contracts. It does not assemble, provision, deploy, or accept a complete
+Gnolith Site; the Codex agent creating a Site owns those responsibilities.
+
 The current minor line receives fixes. Security support follows `SECURITY.md`.
 Deprecations are announced in the changelog before removal whenever a safe
 migration path exists.

package/docs/testing.md

@@ -11,11 +11,20 @@ projection repair, shared RDF values, and injected RDF failures. The injected
 failure proves that canonical JSON, revisions, audit events, search terms,
 ownership, and Diamond quads roll back as one D1 batch.
 
-`test/example.test.ts` runs the documented Codex Site example and queries its
-Taproot-generated graph through Diamond SPARQL. `consumer:check` packs the
+`test/interop.test.ts` runs the documented local D1 and Diamond interoperability
+example and queries its Taproot-generated graph through Diamond SPARQL.
+
+`test/persistence.test.ts` exercises Diamond's Node SQLite adapter in memory
+and on disk, including read-only planning, immutable identity, close/reopen,
+same-adapter enforcement, late-batch rollback, and concurrent writers.
+`consumer:check` packs the
 package, installs the tarball into a fresh temporary project with registry
 Diamond and Miniflare dependencies, initializes a new D1 database, writes an
 entity, and verifies the RDF through SPARQL using only public package exports.
 
-`npm run check` is the complete local release-quality gate. Coverage thresholds
-are enforced in `vitest.config.ts`; lowering them requires an explained review.
+`npm run check` is the complete local package release-quality gate. Coverage
+thresholds are enforced in `vitest.config.ts`; lowering them requires an
+explained review. Miniflare/Workerd and packed-consumer success verifies the
+package's supported D1 runtime contract, not assembly, provisioning, deployment,
+or acceptance of a complete Gnolith Site. The Codex agent creating a Site owns
+those checks.

package/docs/threat-model.md

@@ -8,9 +8,9 @@ association between an edit and its claimed attribution metadata.
 
 ## Trust boundaries
 
-The host application is trusted to authenticate and authorize callers, select
-the D1 binding, supply an absolute site-owned base IRI, and protect mutation
-routes. Attribution is a stored claim, not proof of identity. Diamond executes
+Taproot assumes its consumer supplies a D1 binding and absolute base IRI, and
+that callers reaching mutations have already been authenticated and authorized.
+Attribution is a stored claim, not proof of identity. Diamond executes
 the RDF patch prepared by Taproot and exposes read-only SPARQL querying; hosts
 must not give untrusted callers an independent write path to Taproot or Diamond
 tables.
@@ -24,8 +24,8 @@ tables.
 - History tampering is deterred and detected by immutable-table triggers,
   SHA-256 content/parent chains, schema inspection, and integrity APIs.
 - Resource exhaustion is bounded by entity, command, page, bulk, redirect, and
-  RDF patch limits. Hosts still need request-size, authentication, and rate
-  limits at the network boundary.
+  RDF patch limits. Request-size, authentication, and network rate limits are
+  outside the package boundary.
 - RDF projection confusion is constrained by strict entity validation,
   deterministic mapping, site-owned namespaces, and per-entity quad ownership.
 - Dependency and release compromise is reduced through locked installs, pinned
@@ -38,3 +38,8 @@ Taproot does not provide authentication, authorization, agent/MCP isolation,
 network rate limiting, D1 backup custody, UI sanitization, or arbitrary SPARQL
 Update. A compromised host with direct D1 access can bypass library controls;
 restore from a trusted backup and verify audit chains after such an incident.
+
+Taproot's local Workerd tests validate its package controls under the supported
+D1 contract. They do not qualify a deployed host. The Codex agent creating a
+Site owns assembly, provisioning, route and security wiring, deployment, backup
+policy, and production acceptance.

package/examples/d1-diamond-interop/README.md

@@ -0,0 +1,11 @@
+# Local D1 and Diamond interoperability example
+
+Pass a D1-compatible database to `runTaprootInteropDemo(db)`. The demo
+initializes Taproot and Diamond in the same database, creates Properties and an
+Item, applies revision-guarded edits, and queries Taproot's RDF projection
+through Diamond SPARQL.
+
+The automated test runs this example locally with Miniflare's Workerd D1
+implementation. It verifies the published package's D1 and Diamond contracts;
+it does not assemble, provision, deploy, or accept a complete Gnolith Site.
+Those responsibilities belong to the Codex agent creating that Site.

package/examples/{codex-site → d1-diamond-interop}/demo.ts

@@ -8,8 +8,8 @@ import {
 } from '@gnolith/taproot';
 import { createSparqlHandler } from '@gnolith/diamond';
 
-export async function runTaprootDemo(db: D1DatabaseLike) {
-  await initializeTaproot(db);
+export async function runTaprootInteropDemo(db: D1DatabaseLike) {
+  await initializeTaproot(db, { baseIri: 'https://knowledge.example' });
   const taproot = new TaprootRepository(db, {
     baseIri: 'https://knowledge.example',
   });
@@ -125,7 +125,7 @@ export async function runTaprootDemo(db: D1DatabaseLike) {
   }`;
   const response = await sparql(
     new Request(
-      `https://site.example/api/sparql?query=${encodeURIComponent(query)}`,
+      `https://interop.example/sparql?query=${encodeURIComponent(query)}`,
       { headers: { accept: 'application/sparql-results+json' } },
     ),
   );

package/migrations/0002_audit_operations.sql

@@ -1,6 +1,7 @@
--- Structural half of the v1 -> v2 migration. initializeTaproot() must run
--- immediately afterward to SHA-256 backfill legacy revisions, create their
--- audit events, install immutability triggers, and verify version metadata.
+-- Historical 0.1 structural migration retained as package documentation.
+-- Taproot 0.2 hosts must use the exported migration/initializer APIs rather
+-- than applying this file directly; checksummed adoption and JavaScript
+-- backfills cannot be represented by this SQL file alone.
 ALTER TABLE taproot_entity_revisions ADD COLUMN attribution_json TEXT CHECK (attribution_json IS NULL OR json_valid(attribution_json));
 ALTER TABLE taproot_entity_revisions ADD COLUMN tags_json TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(tags_json));
 ALTER TABLE taproot_entity_revisions ADD COLUMN event_id TEXT;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@gnolith/taproot",
-  "version": "0.1.0-rc.0",
-  "description": "D1-native Wikibase-compatible knowledge graph and revision layer for Gnolith.",
+  "version": "0.2.0",
+  "description": "Portable SQLite and D1 Wikibase-compatible knowledge graph and revision layer for Gnolith.",
   "author": "Gnolith contributors",
   "keywords": [
     "cloudflare-d1",
+    "sqlite",
     "knowledge-graph",
     "rdf",
     "sparql",
@@ -47,20 +48,21 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "check": "npm run format:check && npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run example:check && npm run pack:check && npm run consumer:check && npm run licenses:check && npm run readiness:check",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run interop:check && npm run pack:check && npm run consumer:check && npm run licenses:check && npm run repository:check",
     "consumer:check": "node scripts/consumer-smoke.mjs",
-    "example:check": "vitest run test/example.test.ts",
+    "interop:check": "vitest run test/interop.test.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "licenses:check": "license-checker-rseidelsohn --production --summary --onlyAllow \"MIT;ISC;BSD-2-Clause;Apache-2.0;BSD-3-Clause;BlueOak-1.0.0;FreeBSD;(WTFPL OR MIT);UNLICENSED\"",
     "lint": "eslint .",
     "pack:check": "npm pack --dry-run",
     "prepack": "npm run build",
-    "readiness:check": "node scripts/readiness-check.mjs",
+    "repository:check": "node scripts/repository-check.mjs",
     "release:check": "node scripts/release-check.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:integration": "vitest run test/repository.test.ts test/example.test.ts",
+    "test:integration": "vitest run test/repository.test.ts test/interop.test.ts",
+    "test:persistence": "vitest run test/persistence.test.ts test/migration-recovery.test.ts",
     "test:unit": "vitest run test/rdf.test.ts test/scaffold.test.ts",
     "typecheck": "tsc --noEmit"
   },
@@ -68,7 +70,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gnolith/diamond": "^0.3.2",
+    "@gnolith/diamond": "0.4.0",
     "@rdfjs/types": "^2.0.1",
     "rdf-data-factory": "^2.0.2"
   },

package/examples/codex-site/.openai/hosting.json

@@ -1,3 +0,0 @@
-{
-  "framework": "nextjs"
-}

package/examples/codex-site/README.md

@@ -1,13 +0,0 @@
-# Codex Site example
-
-Bind a Cloudflare D1 database as `DB`, apply Diamond's and Taproot's numbered
-migrations, call `initializeTaproot`, and run `runTaprootDemo(env.DB)` from a
-trusted setup route or test fixture.
-
-`demo.ts` creates Properties and an Item, adds a qualified and referenced
-statement, changes its rank, adds a `somevalue`, queries the truthy projection
-through Diamond SPARQL, exports canonical JSON, proves that a stale edit is
-rejected, and returns the attribution/audit and integrity records. A production
-site should authenticate every mutation route and can enable
-`requireAttribution`; Taproot deliberately does not own authentication or agent
-transport.