@gnolith/taproot 0.1.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- Complete Wikibase Item/Property JSON model and validated editing API.
+- Atomic current entities, immutable revisions, terms, RDF, and ownership.
+- Structured attribution, tags, request correlation, audit events, and
+  SHA-256 parent chains.
+- Lifecycle history, redirect resolution/cycle prevention, cursor reads,
+  multi-command edits, bounded bulk import/upsert, and NDJSON export.
+- Schema/RDF migration, integrity inspection, audit verification, and repair.
+- Wikibase-compatible truthy/full RDF mapping version 2 and shared-value safety.
+- Host validators, attribution enforcement, observations, deterministic test
+  injection, Workerd/D1 tests, Node 22/24 CI, and pack validation.

package/COMPATIBILITY.md

@@ -0,0 +1,42 @@
+# Wikibase compatibility target
+
+Taproot targets the canonical entity shapes and RDF vocabulary paths used by
+the Wikibase API/RDF model, with site-owned entity/property namespaces. The
+fixtures under `test/fixtures` are the named interoperability baseline.
+
+Intentional differences:
+
+- Taproot is a library over D1, not a MediaWiki or Wikibase HTTP server.
+- Local Q/P IDs, base IRI, revision numbers, statement IDs, and reference
+  hashes belong to the site. Imported values are preserved; Taproot does not
+  call Wikidata to resolve or rewrite them.
+- Sitelinks round-trip in canonical JSON but are not wiki-page storage and do
+  not emit MediaWiki page metadata.
+- Redirect and soft-delete state live beside canonical JSON and project only
+  lifecycle RDF; deleted content remains available in immutable revisions.
+- Search is a deterministic D1 term projection using case-insensitive
+  substring matching. FTS5 is not required.
+- Taproot stores attribution claims but does not authenticate them. Identity
+  verification, authorization, and agent/MCP transport remain host concerns.
+- The compatibility target is Wikibase core Items and Properties. Lexemes,
+  Forms, Senses, EntitySchemas, MediaInfo, MediaWiki page metadata, and
+  normalized external-ID formatter URLs are not claimed as supported entity
+  surfaces.
+- Item/Property statements can nevertheless store and project the standard
+  `wikibase-lexeme`, `wikibase-form`, `wikibase-sense`, and `entity-schema`
+  link datatypes without claiming storage for those target entity documents.
+- Math, musical notation, geo-shape, and tabular-data values round-trip and
+  project with Wikibase property types. Geo-shape/tabular-data values use
+  Commons data IRIs; deployments remain responsible for those resources.
+- Taproot adds a site-owned mapping-version triple and retains
+  `schema:isBasedOn` beside standard `prov:wasDerivedFrom` for backward
+  compatibility. These additive triples do not change Wikibase query paths.
+- Shared full-value/reference RDF nodes are reference-owned internally so
+  incremental edits never remove a quad still used by another entity. The
+  ownership table is projection bookkeeping, not an authoritative statement
+  store.
+
+Interoperability means canonical Item/Property JSON round-trip and equivalent
+Wikibase query paths (`wdt`, `p`, `ps`, `psv`, `pq`, `pqv`, `pr`, `prv`,
+`wdno`) under a site-owned base IRI. It does not mean Taproot implements the
+MediaWiki/Wikibase HTTP APIs or every extension entity type.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gnolith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Taproot
+
+**The D1-native, Wikibase-compatible knowledge layer for Gnolith.**
+
+Taproot gives a Codex Site one authoritative Wikibase-shaped Item/Property
+document, tamper-evident revision and attribution history, typed and batched
+editing commands, term search, repairable projections, and a deterministic RDF projection stored and queried by
+[`@gnolith/diamond`](https://github.com/gnolith/diamond).
+
+> One canonical entity document, one deterministic RDF projection, one atomic
+> revision boundary.
+
+## Status
+
+Version `0.1.0` is the first public release. Taproot supports Node 22 and 24 and
+depends on the registry release of Diamond that exposes transaction-composable
+quad patches.
+
+## What it owns
+
+- Items and Properties with Wikibase-style canonical JSON.
+- Labels, descriptions, aliases, sitelinks, statements, qualifiers,
+  references, ranks, and all three snak types.
+- Item, Property, Lexeme, Form, Sense, and EntitySchema links; string,
+  external ID, URL, Commons media, monolingual text, time,
+  quantity, coordinate, math, musical notation, geo-shape, and tabular-data
+  datatypes.
+- Atomic Q/P ID allocation, current documents, immutable revisions, lifecycle
+  history, structured human/agent/import/system attribution, tags, request
+  correlation, audit events, and the term-search projection in D1.
+- A complete deterministic Wikibase-shaped RDF closure with truthy/best-rank,
+  special-value, and full-value behavior.
+- Cursor reads, bounded import/upsert and NDJSON export, multi-command edits,
+  redirect resolution, integrity verification, deterministic repair, schema/RDF
+  migrations, validation policies, and write observations.
+
+It does not own authentication, MCP, agents, tasks, UI, wiki articles, media
+bytes, or arbitrary SPARQL Update. Canonical entity JSON is authoritative;
+there is no relational statement store.
+
+## Setup
+
+Taproot requires Diamond's transaction-composable quad-patch API. Initialize a
+D1 binding once; the programmatic initializer creates both Diamond and Taproot
+tables idempotently:
+
+```ts
+import { TaprootRepository, initializeTaproot } from '@gnolith/taproot';
+
+await initializeTaproot(env.DB);
+const knowledge = new TaprootRepository(env.DB, {
+  baseIri: 'https://knowledge.example',
+});
+
+const property = await knowledge.createProperty({
+  datatype: 'string',
+  labels: { en: { language: 'en', value: 'occupation' } },
+});
+const item = await knowledge.createItem({
+  labels: { en: { language: 'en', value: 'Ada Lovelace' } },
+});
+```
+
+For migration-driven deployments, apply Diamond's migrations and the numbered
+Taproot SQL files, then call `initializeTaproot()`. The initializer performs
+the application-level SHA-256 backfill that SQLite SQL alone cannot perform,
+reprojects older RDF mapping versions, installs immutability triggers, and is
+safe to run on every startup/deploy.
+
+## Editing
+
+Every mutation after creation requires `expectedRevision`. Taproot loads the
+current document, validates the typed change and all referenced Property
+datatypes, serializes canonical JSON, rebuilds the complete old/new RDF
+closures, and batches the current row, immutable revision, search terms, and
+Diamond patch together. A stale guard or any SQL/RDF failure rolls the whole
+batch back.
+
+```ts
+const edited = await knowledge.setLabel(item.entityId, 'fr', 'Ada Lovelace', {
+  expectedRevision: item.newRevision,
+  attribution: {
+    id: 'agent:cataloguer',
+    kind: 'agent',
+    tool: 'gnolith-mcp',
+  },
+  editSummary: 'add French label',
+  tags: ['agent'],
+  requestId: 'mcp-request-123',
+});
+```
+
+The public API includes reads/search; create/import/replace; soft delete,
+restore, and redirect; all term/sitelink commands; complete statement,
+qualifier, reference, and rank commands; audit/history and integrity reads;
+bulk workflows; and canonical JSON parse, validate, create, and export helpers. Top-level function forms are exported alongside
+`TaprootRepository`.
+
+Set `requireAttribution: true` to reject unattributed writes. `validators`
+provide host policy checks without coupling Taproot to authentication, and
+`observe` receives isolated success/error timing records for committed writes.
+
+## SPARQL prefixes
+
+`wikibasePrefixes(baseIri)` returns site-owned `wd:`, `wds:`, `wdv:`,
+`wdref:`, `wdt:`, `p:`, `ps:`, `psv:`, `pq:`, `pqv:`, `pr:`, `prv:`, and
+`wdno:` namespaces. Pass the D1 binding to Diamond's read-only SPARQL handler
+to query them.
+
+## Limits
+
+Canonical entity JSON defaults to 1.8 MB, below D1's 2 MB bound-value limit.
+Diamond enforces a 1.9 MB aggregate encoded quad-patch limit; Taproot reports
+that as `QuadPatchTooLargeError`. Store PDFs, images, audio, OCR, transcripts,
+and article bodies externally and represent them as knowledge Items.
+
+Bulk imports default to create-only, can opt into `upsert`, are capped at 100
+entities by default, and commit one entity atomically at a time. Multi-command
+edits apply up to 100 commands in one revision. All list limits are capped at 500.
+
+See the [Codex Site example](examples/codex-site/README.md),
+[`COMPATIBILITY.md`](COMPATIBILITY.md), and the architecture, API, operations,
+and release documents under `docs/`. Run `npm run check` for the complete local
+release-quality gate.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security
+
+Report vulnerabilities privately through GitHub Security Advisories. Do not
+open a public issue for an undisclosed vulnerability.
+
+The latest published minor line receives security fixes. Older pre-1.0 minor
+lines are unsupported unless a security advisory explicitly says otherwise.
+
+Include the affected API, a minimal D1/entity reproduction, impact on
+canonical history or RDF query results, and whether untrusted JSON or SPARQL
+input is required. Do not include production data or credentials.
+
+Taproot records attribution claims but does not authenticate identities or
+authorize writes. Hosts must keep mutation routes trusted. Canonical JSON,
+revision/audit immutability, size limits, optimistic revision guards, and
+read-only Diamond SPARQL are security boundaries; projection tables are not.
+
+The threat model and host responsibilities are documented in
+`docs/threat-model.md`.

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# Support
+
+Use GitHub Issues for reproducible defects and scoped feature requests. Include
+the Taproot, Diamond, Node, Workerd/Wrangler, and schema versions; the smallest
+canonical entity or command that reproduces the problem; and observed versus
+expected behavior.
+
+Only versions listed as supported in `SECURITY.md` receive security fixes.
+There is no guaranteed response time or commercial support commitment.
+Do not disclose vulnerabilities publicly; use GitHub private vulnerability
+reporting instead.

package/dist/canonical.d.ts

@@ -0,0 +1,16 @@
+import { type DataValueValue, type EntityId, type PropertyId, type Reference, type Snak, type Statement, type WikibaseEntity } from './types.js';
+export declare const MAX_ENTITY_BYTES = 1800000;
+export declare function parseEntityJson(json: string): WikibaseEntity;
+export declare function validateEntity(value: unknown): asserts value is WikibaseEntity;
+export declare function exportEntityJson(entity: WikibaseEntity, maxBytes?: number): string;
+export declare function canonicalizeEntity(entity: WikibaseEntity): WikibaseEntity;
+export declare function validateSnak(value: unknown): asserts value is Snak;
+export declare function entityNumericId(id: EntityId): number;
+export declare function cloneEntity(entity: WikibaseEntity): WikibaseEntity;
+export declare function cloneDataValue(value: DataValueValue): DataValueValue;
+export declare function createStatement(entityId: EntityId, mainsnak: Snak, options?: {
+    id?: string;
+    rank?: Statement['rank'];
+}): Statement;
+export declare function createReference(snaks: Record<PropertyId, Snak[]>, hash?: string): Reference;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,QAAQ,EAIb,KAAK,UAAU,EAGf,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,UAAY,CAAC;AAQ1C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAW5D;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,KAAK,IAAI,cAAc,CAoDjC;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,QAAQ,SAAmB,GAC1B,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAyBzE;AA2MD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAkClE;AA0PD,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAElE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAEpE;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,IAAI,EACd,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAO,GACtD,SAAS,CAWX;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EACjC,IAAI,SAAyC,GAC5C,SAAS,CASX"}