@gnolith/taproot 0.1.0-rc.0

package/examples/codex-site/demo.ts

@@ -0,0 +1,152 @@
+import {
+  RevisionConflictError,
+  TaprootRepository,
+  exportEntityJson,
+  initializeTaproot,
+  type D1DatabaseLike,
+  type Statement,
+} from '@gnolith/taproot';
+import { createSparqlHandler } from '@gnolith/diamond';
+
+export async function runTaprootDemo(db: D1DatabaseLike) {
+  await initializeTaproot(db);
+  const taproot = new TaprootRepository(db, {
+    baseIri: 'https://knowledge.example',
+  });
+
+  await taproot.createProperty({
+    datatype: 'string',
+    labels: { en: { language: 'en', value: 'occupation' } },
+  });
+  await taproot.createProperty({
+    datatype: 'time',
+    labels: { en: { language: 'en', value: 'point in time' } },
+  });
+  await taproot.createProperty({
+    datatype: 'url',
+    labels: { en: { language: 'en', value: 'reference URL' } },
+  });
+
+  const created = await taproot.createItem({
+    labels: { en: { language: 'en', value: 'Ada Lovelace' } },
+    descriptions: {
+      en: { language: 'en', value: 'English mathematician' },
+    },
+    attribution: {
+      id: 'agent:demo-curator',
+      kind: 'agent',
+      tool: 'gnolith-mcp',
+    },
+    requestId: 'demo-request',
+  });
+  const occupation: Statement = {
+    id: `${created.entityId}$occupation`,
+    type: 'statement',
+    rank: 'normal',
+    mainsnak: {
+      snaktype: 'value',
+      property: 'P1',
+      datatype: 'string',
+      datavalue: { type: 'string', value: 'computer programmer' },
+    },
+    qualifiers: {
+      P2: [
+        {
+          snaktype: 'value',
+          property: 'P2',
+          datatype: 'time',
+          datavalue: {
+            type: 'time',
+            value: {
+              time: '+1843-01-01T00:00:00Z',
+              timezone: 0,
+              before: 0,
+              after: 0,
+              precision: 9,
+              calendarmodel: 'http://www.wikidata.org/entity/Q1985727',
+            },
+          },
+        },
+      ],
+    },
+    'qualifiers-order': ['P2'],
+    references: [
+      {
+        hash: 'demo-source',
+        snaks: {
+          P3: [
+            {
+              snaktype: 'value',
+              property: 'P3',
+              datatype: 'url',
+              datavalue: {
+                type: 'string',
+                value: 'https://example.test/source',
+              },
+            },
+          ],
+        },
+        'snaks-order': ['P3'],
+      },
+    ],
+  };
+  const added = await taproot.addStatement(created.entityId, occupation, {
+    expectedRevision: created.newRevision,
+  });
+  const preferred = await taproot.setStatementRank(
+    created.entityId,
+    occupation.id,
+    'preferred',
+    { expectedRevision: added.newRevision },
+  );
+  const unknownOccupation: Statement = {
+    id: `${created.entityId}$unknown-occupation`,
+    type: 'statement',
+    rank: 'normal',
+    mainsnak: {
+      snaktype: 'somevalue',
+      property: 'P1',
+      datatype: 'string',
+    },
+    qualifiers: {},
+    'qualifiers-order': [],
+    references: [],
+  };
+  const special = await taproot.addStatement(
+    created.entityId,
+    unknownOccupation,
+    { expectedRevision: preferred.newRevision },
+  );
+
+  const sparql = createSparqlHandler({ db });
+  const query = `SELECT ?occupation WHERE {
+    <https://knowledge.example/entity/${created.entityId}>
+      <https://knowledge.example/prop/direct/P1> ?occupation
+  }`;
+  const response = await sparql(
+    new Request(
+      `https://site.example/api/sparql?query=${encodeURIComponent(query)}`,
+      { headers: { accept: 'application/sparql-results+json' } },
+    ),
+  );
+
+  let staleRevisionRejected = false;
+  try {
+    await taproot.setLabel(created.entityId, 'en', 'stale edit', {
+      expectedRevision: created.newRevision,
+    });
+  } catch (cause) {
+    staleRevisionRejected = cause instanceof RevisionConflictError;
+  }
+
+  const sparqlResults: unknown = await response.json();
+  const audit = await taproot.listAuditEvents({ entityId: created.entityId });
+  const integrity = await taproot.inspectEntityIntegrity(created.entityId);
+  return {
+    entityJson: exportEntityJson(special.entity),
+    sparqlResults,
+    staleRevisionRejected,
+    audit: audit.items,
+    integrity,
+  };
+}

package/migrations/0001_taproot.sql

@@ -0,0 +1,64 @@
+CREATE TABLE taproot_entities (
+  entity_id TEXT PRIMARY KEY,
+  entity_type TEXT NOT NULL CHECK (entity_type IN ('item', 'property')),
+  datatype TEXT,
+  revision INTEGER NOT NULL,
+  entity_json TEXT NOT NULL CHECK (json_valid(entity_json)),
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  modified_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TEXT,
+  redirect_to TEXT,
+  CHECK (
+    (entity_type = 'item' AND datatype IS NULL)
+    OR (entity_type = 'property' AND datatype IS NOT NULL)
+  )
+) STRICT;
+
+CREATE TABLE taproot_entity_revisions (
+  entity_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  entity_json TEXT NOT NULL CHECK (json_valid(entity_json)),
+  actor TEXT,
+  edit_summary TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (entity_id, revision),
+  FOREIGN KEY (entity_id) REFERENCES taproot_entities(entity_id)
+) STRICT;
+
+CREATE TABLE taproot_id_counters (
+  entity_type TEXT PRIMARY KEY CHECK (entity_type IN ('item', 'property')),
+  next_numeric_id INTEGER NOT NULL CHECK (next_numeric_id > 0)
+) STRICT;
+
+CREATE TABLE taproot_terms (
+  entity_id TEXT NOT NULL,
+  language TEXT NOT NULL,
+  term_type TEXT NOT NULL CHECK (term_type IN ('label', 'description', 'alias')),
+  value TEXT NOT NULL,
+  ordinal INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (entity_id, language, term_type, ordinal),
+  FOREIGN KEY (entity_id) REFERENCES taproot_entities(entity_id)
+) STRICT;
+
+CREATE TABLE taproot_metadata (
+  metadata_key TEXT PRIMARY KEY,
+  metadata_value TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE taproot_assertions (
+  assertion_key TEXT PRIMARY KEY
+) STRICT;
+
+CREATE INDEX taproot_entities_type_idx ON taproot_entities(entity_type, entity_id);
+CREATE INDEX taproot_entities_modified_idx ON taproot_entities(modified_at, entity_id);
+CREATE INDEX taproot_revisions_entity_idx ON taproot_entity_revisions(entity_id, revision DESC);
+CREATE INDEX taproot_terms_lookup_idx ON taproot_terms(language, value COLLATE NOCASE, entity_id);
+
+INSERT INTO taproot_id_counters(entity_type, next_numeric_id)
+VALUES ('item', 1), ('property', 1);
+
+INSERT INTO taproot_metadata(metadata_key, metadata_value)
+VALUES
+  ('schema_version', '1'),
+  ('canonical_json_version', '1'),
+  ('rdf_mapping_version', '1');

package/migrations/0002_audit_operations.sql

@@ -0,0 +1,48 @@
+-- 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.
+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;
+ALTER TABLE taproot_entity_revisions ADD COLUMN content_hash TEXT;
+ALTER TABLE taproot_entity_revisions ADD COLUMN parent_hash TEXT;
+ALTER TABLE taproot_entity_revisions ADD COLUMN deleted_at TEXT;
+ALTER TABLE taproot_entity_revisions ADD COLUMN redirect_to TEXT;
+
+CREATE TABLE taproot_audit_events (
+  event_id TEXT PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  event_type TEXT NOT NULL CHECK (event_type IN ('create', 'update', 'revert', 'delete', 'restore', 'redirect', 'import', 'repair')),
+  attribution_json TEXT CHECK (attribution_json IS NULL OR json_valid(attribution_json)),
+  edit_summary TEXT,
+  tags_json TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(tags_json)),
+  request_id TEXT,
+  content_hash TEXT NOT NULL,
+  parent_hash TEXT,
+  details_json TEXT NOT NULL DEFAULT '{}' CHECK (json_valid(details_json)),
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (entity_id, revision) REFERENCES taproot_entity_revisions(entity_id, revision)
+) STRICT;
+
+CREATE TABLE taproot_migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+) STRICT;
+
+CREATE TABLE taproot_rdf_ownership (
+  entity_id TEXT NOT NULL,
+  subject_key TEXT NOT NULL,
+  predicate_key TEXT NOT NULL,
+  object_key TEXT NOT NULL,
+  graph_key TEXT NOT NULL,
+  PRIMARY KEY (entity_id, subject_key, predicate_key, object_key, graph_key),
+  FOREIGN KEY (entity_id) REFERENCES taproot_entities(entity_id)
+) STRICT;
+
+CREATE INDEX taproot_audit_entity_idx ON taproot_audit_events(entity_id, revision DESC, event_id);
+CREATE INDEX taproot_audit_request_idx ON taproot_audit_events(request_id) WHERE request_id IS NOT NULL;
+CREATE INDEX taproot_rdf_ownership_quad_idx ON taproot_rdf_ownership(subject_key, predicate_key, object_key, graph_key, entity_id);
+
+INSERT INTO taproot_migrations(version, name) VALUES (1, 'initial'), (2, 'audit-and-operations');

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@gnolith/taproot",
+  "version": "0.1.0-rc.0",
+  "description": "D1-native Wikibase-compatible knowledge graph and revision layer for Gnolith.",
+  "author": "Gnolith contributors",
+  "keywords": [
+    "cloudflare-d1",
+    "knowledge-graph",
+    "rdf",
+    "sparql",
+    "wikibase"
+  ],
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gnolith/taproot.git"
+  },
+  "homepage": "https://github.com/gnolith/taproot#readme",
+  "bugs": {
+    "url": "https://github.com/gnolith/taproot/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./migrations/*": "./migrations/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "migrations",
+    "examples",
+    "COMPATIBILITY.md",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "SUPPORT.md"
+  ],
+  "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",
+    "consumer:check": "node scripts/consumer-smoke.mjs",
+    "example:check": "vitest run test/example.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",
+    "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:unit": "vitest run test/rdf.test.ts test/scaffold.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@gnolith/diamond": "^0.3.2",
+    "@rdfjs/types": "^2.0.1",
+    "rdf-data-factory": "^2.0.2"
+  },
+  "packageManager": "npm@11.9.0",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "eslint": "^10.7.0",
+    "license-checker-rseidelsohn": "^4.4.2",
+    "miniflare": "^4.20260714.0",
+    "prettier": "^3.9.5",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT"
+}