@gnolith/taproot 0.1.0-rc.0 → 0.3.0

package/migrations/0004_canonical_authorization_policy.sql

@@ -0,0 +1,213 @@
+CREATE TABLE IF NOT EXISTS taproot_installation_authorization (
+  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+  installation_id TEXT NOT NULL UNIQUE,
+  authorization_revision INTEGER NOT NULL CHECK (authorization_revision >= 1),
+  search_generation INTEGER NOT NULL CHECK (search_generation >= 1),
+  last_advance_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_entity_authorization (
+  entity_id TEXT PRIMARY KEY,
+  installation_id TEXT NOT NULL,
+  workspace_id TEXT,
+  owner_principal_id TEXT NOT NULL,
+  visibility_json TEXT NOT NULL CHECK (json_valid(visibility_json)),
+  effective_visibility_json TEXT NOT NULL CHECK (json_valid(effective_visibility_json)),
+  source_revision INTEGER NOT NULL,
+  authorization_revision INTEGER NOT NULL,
+  deleted_at TEXT,
+  event_id TEXT NOT NULL UNIQUE,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (entity_id) REFERENCES taproot_entities(entity_id),
+  FOREIGN KEY (event_id) REFERENCES taproot_audit_events(event_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_entity_authorization_revisions (
+  entity_id TEXT NOT NULL,
+  source_revision INTEGER NOT NULL,
+  installation_id TEXT NOT NULL,
+  workspace_id TEXT,
+  owner_principal_id TEXT NOT NULL,
+  visibility_json TEXT NOT NULL CHECK (json_valid(visibility_json)),
+  effective_visibility_json TEXT NOT NULL CHECK (json_valid(effective_visibility_json)),
+  authorization_revision INTEGER NOT NULL,
+  deleted_at TEXT,
+  event_id TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (entity_id, source_revision),
+  FOREIGN KEY (entity_id, source_revision)
+    REFERENCES taproot_entity_revisions(entity_id, revision),
+  FOREIGN KEY (event_id) REFERENCES taproot_audit_events(event_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_statement_authorization (
+  entity_id TEXT NOT NULL,
+  statement_id TEXT NOT NULL,
+  source_revision INTEGER NOT NULL,
+  restrictions_json TEXT NOT NULL CHECK (json_valid(restrictions_json)),
+  effective_visibility_json TEXT NOT NULL CHECK (json_valid(effective_visibility_json)),
+  authorization_revision INTEGER NOT NULL,
+  PRIMARY KEY (entity_id, statement_id),
+  FOREIGN KEY (entity_id) REFERENCES taproot_entities(entity_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_statement_authorization_revisions (
+  entity_id TEXT NOT NULL,
+  source_revision INTEGER NOT NULL,
+  statement_id TEXT NOT NULL,
+  restrictions_json TEXT NOT NULL CHECK (json_valid(restrictions_json)),
+  effective_visibility_json TEXT NOT NULL CHECK (json_valid(effective_visibility_json)),
+  authorization_revision INTEGER NOT NULL,
+  PRIMARY KEY (entity_id, source_revision, statement_id),
+  FOREIGN KEY (entity_id, source_revision)
+    REFERENCES taproot_entity_revisions(entity_id, revision)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_authorization_projection_outbox (
+  event_id TEXT PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  source_revision INTEGER NOT NULL,
+  authorization_revision INTEGER NOT NULL,
+  search_generation INTEGER NOT NULL,
+  operation TEXT NOT NULL CHECK (operation IN ('upsert', 'delete', 'repair', 'backfill')),
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'claimed', 'complete')),
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (event_id) REFERENCES taproot_audit_events(event_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_authorization_backfill_plans (
+  plan_id TEXT PRIMARY KEY,
+  installation_id TEXT NOT NULL,
+  base_authorization_revision INTEGER NOT NULL,
+  manifest_json TEXT NOT NULL CHECK (json_valid(manifest_json)),
+  manifest_hash TEXT NOT NULL,
+  entity_count INTEGER NOT NULL CHECK (entity_count > 0 AND entity_count <= 100),
+  revision_count INTEGER NOT NULL CHECK (revision_count > 0),
+  status TEXT NOT NULL CHECK (status IN ('planned', 'applying', 'complete')),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  completed_at TEXT
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_authorization_admin_audit (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  audit_id TEXT NOT NULL UNIQUE,
+  event_type TEXT NOT NULL CHECK (event_type IN ('backfill-plan', 'backfill-apply')),
+  principal_id TEXT NOT NULL,
+  plan_id TEXT NOT NULL,
+  authorization_revision INTEGER NOT NULL,
+  details_json TEXT NOT NULL CHECK (json_valid(details_json)),
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (plan_id) REFERENCES taproot_authorization_backfill_plans(plan_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS taproot_installation_authorization_advances (
+  advance_id TEXT PRIMARY KEY,
+  installation_id TEXT NOT NULL,
+  from_revision INTEGER NOT NULL,
+  to_revision INTEGER NOT NULL,
+  search_generation INTEGER NOT NULL,
+  domain TEXT NOT NULL,
+  principal_id TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  CHECK (to_revision = from_revision + 1)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS taproot_entity_authorization_candidate_idx
+  ON taproot_entity_authorization(installation_id, deleted_at, entity_id);
+CREATE INDEX IF NOT EXISTS taproot_entity_authorization_revision_idx
+  ON taproot_entity_authorization_revisions(entity_id, source_revision DESC);
+CREATE INDEX IF NOT EXISTS taproot_statement_authorization_candidate_idx
+  ON taproot_statement_authorization(entity_id, source_revision, statement_id);
+CREATE INDEX IF NOT EXISTS taproot_authorization_outbox_state_idx
+  ON taproot_authorization_projection_outbox(state, authorization_revision, event_id);
+
+CREATE TRIGGER IF NOT EXISTS taproot_revisions_no_replace
+  BEFORE INSERT ON taproot_entity_revisions
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_entity_revisions
+    WHERE entity_id = NEW.entity_id AND revision = NEW.revision
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot revisions cannot be replaced'); END;
+
+CREATE TRIGGER IF NOT EXISTS taproot_audit_no_replace
+  BEFORE INSERT ON taproot_audit_events
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_audit_events WHERE event_id = NEW.event_id
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot audit events cannot be replaced'); END;
+
+CREATE TRIGGER IF NOT EXISTS taproot_installation_identity_no_update
+  BEFORE UPDATE OF installation_id ON taproot_installation_authorization
+  BEGIN SELECT RAISE(ABORT, 'taproot installation identity is immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_installation_authorization_no_delete
+  BEFORE DELETE ON taproot_installation_authorization
+  BEGIN SELECT RAISE(ABORT, 'taproot installation authorization is durable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_installation_authorization_no_replace
+  BEFORE INSERT ON taproot_installation_authorization
+  WHEN EXISTS (SELECT 1 FROM taproot_installation_authorization WHERE singleton = NEW.singleton)
+  BEGIN SELECT RAISE(ABORT, 'taproot installation authorization cannot be replaced'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_entity_authorization_revisions_no_update
+  BEFORE UPDATE ON taproot_entity_authorization_revisions
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization revisions are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_entity_authorization_revisions_no_delete
+  BEFORE DELETE ON taproot_entity_authorization_revisions
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization revisions are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_entity_authorization_revisions_no_replace
+  BEFORE INSERT ON taproot_entity_authorization_revisions
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_entity_authorization_revisions
+    WHERE (entity_id = NEW.entity_id AND source_revision = NEW.source_revision)
+       OR event_id = NEW.event_id
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization revisions cannot be replaced'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_statement_authorization_revisions_no_update
+  BEFORE UPDATE ON taproot_statement_authorization_revisions
+  BEGIN SELECT RAISE(ABORT, 'taproot statement authorization revisions are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_statement_authorization_revisions_no_delete
+  BEFORE DELETE ON taproot_statement_authorization_revisions
+  BEGIN SELECT RAISE(ABORT, 'taproot statement authorization revisions are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_statement_authorization_revisions_no_replace
+  BEFORE INSERT ON taproot_statement_authorization_revisions
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_statement_authorization_revisions
+    WHERE entity_id = NEW.entity_id AND source_revision = NEW.source_revision
+      AND statement_id = NEW.statement_id
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot statement authorization revisions cannot be replaced'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_authorization_admin_audit_no_update
+  BEFORE UPDATE ON taproot_authorization_admin_audit
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization administration audit is immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_authorization_admin_audit_no_delete
+  BEFORE DELETE ON taproot_authorization_admin_audit
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization administration audit is immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_authorization_admin_audit_no_replace
+  BEFORE INSERT ON taproot_authorization_admin_audit
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_authorization_admin_audit
+    WHERE sequence = NEW.sequence OR audit_id = NEW.audit_id
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization administration audit cannot be replaced'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_installation_authorization_advances_no_update
+  BEFORE UPDATE ON taproot_installation_authorization_advances
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization advances are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_installation_authorization_advances_no_delete
+  BEFORE DELETE ON taproot_installation_authorization_advances
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization advances are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS taproot_installation_authorization_advances_no_replace
+  BEFORE INSERT ON taproot_installation_authorization_advances
+  WHEN EXISTS (
+    SELECT 1 FROM taproot_installation_authorization_advances
+    WHERE advance_id = NEW.advance_id
+  )
+  BEGIN SELECT RAISE(ABORT, 'taproot authorization advances cannot be replaced'); END;
+
+INSERT INTO taproot_metadata(metadata_key, metadata_value)
+  VALUES ('schema_version', '3')
+  ON CONFLICT(metadata_key) DO UPDATE SET metadata_value = excluded.metadata_value;
+INSERT INTO taproot_migrations(version, name)
+  VALUES (4, 'canonical-authorization-policy')
+  ON CONFLICT(version) DO NOTHING;

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.3.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,11 +70,14 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gnolith/diamond": "^0.3.2",
+    "@gnolith/diamond": "0.4.0",
     "@rdfjs/types": "^2.0.1",
     "rdf-data-factory": "^2.0.2"
   },
   "packageManager": "npm@11.9.0",
+  "overrides": {
+    "sharp": "0.35.3"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.0.0",

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.

package/examples/codex-site/demo.ts

@@ -1,152 +0,0 @@
-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,
-  };
-}