@seedprotocol/rdf 0.0.0-stage → 0.8.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+## Unreleased
+
+- New package. `exportSeeds(seedUids, { chainId })` reads seeds with `getSeedAttestations` from @seedprotocol/query and returns their state graph: each seed's values at its head Version, with IRIs minted from the on-chain schemas (`{base}c/{model}`, `{base}p/{easType}/{easName}`, `{base}eas/{chainId}/{uid}`). `toQuads` gives RDF/JS quads; `toNQuads`, `toTurtle` and `toJsonLd` write RDF 1.1 N-Quads, Turtle and JSON-LD 1.1. `seedVocabulary` gives the Seed vocabulary in Turtle. The base IRI defaults to `PROVISIONAL_BASE_IRI`, which isn't registered yet.
+- New `lens` option on `exportSeeds` and `stateGraph`: `{ schema, sidecar }` maps models and properties, by id, to terms such as `schema:headline`, and types Numbers (`xsd:integer`, `xsd:decimal`, canonical `xsd:double`) and Dates (`xsd:dateTime`). `StateGraph.warnings` lists terms it couldn't use.
+- `toShacl(lens)` writes SHACL 2017 shapes in Turtle for exports made with that lens: a `sh:NodeShape` per model targeting its class, and per property its predicate, `sh:datatype`, `sh:maxCount 1`, `sh:minCount 1` when `required`, and `rdf:List` checks for Lists.
+- `sidecarContext(lens)` generates a type-scoped JSON-LD `@context` from the sidecar's `terms` and the schema's current names. `checkSidecar` lists stale terms, unreadable terms and unmapped models and properties; `syncSidecar` regenerates `@context` and sets the new optional `schemaVersion`; `suggestTerms` drafts schema.org and dcterms terms for common names.
+- An export with a lens includes a `prov:Activity` at `{base}export/{sha256}` with `prov:used <ni:///sha-256;…>`, the hash of the sidecar's `schemaId`, `terms` and `@context` as canonical JSON. The same sidecar always gives the same node; it has no time or agent.
+- `exportSeeds` takes `asOf` (unix seconds) and exports what EAS held then, the same attestations as a reproducible archive bag with that `Seed-Bag-As-Of`. It reads EAS and refuses `source: 'local'`.
+- The state graph has the seed's Version history: each live Version up to the head is a `seed:Version` with `prov:generatedAtTime`, `prov:wasAttributedTo` and `prov:wasRevisionOf` the Version before. Revoked Versions are left out.
+- Properties are written in name order, so the same state gives the same bytes from every writer whatever order EAS returns attestations in.
+- New `seed-rdf` bin: `seed-rdf check` (exits 1 on stale or unreadable terms, for CI), `seed-rdf sync [--write]` and `seed-rdf suggest [--write]`.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @seedprotocol/rdf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+RDF export for [Seed Protocol](https://seedprotocol.io) items. It reads seeds through
+[`@seedprotocol/query`](https://www.npmjs.com/package/@seedprotocol/query) and gives their current
+values as a graph: RDF/JS quads, N-Quads, Turtle or JSON-LD. It doesn't depend on the SDK.
+
+Every IRI comes from what is on chain, so an app gets RDF for its own models without registering
+anything. **The base IRI is provisional:** `https://w3id.org/seedprotocol/` isn't registered yet,
+so don't write exports into anything you can't replace later, such as an archive on Arweave.
+
+## Installation
+
+```bash
+npm install @seedprotocol/rdf
+```
+
+## Export
+
+```ts
+import { exportSeeds, toTurtle, toJsonLd, toNQuads, toQuads } from '@seedprotocol/rdf'
+
+const graph = await exportSeeds([seedUid], { chainId: 11155420 })
+
+toTurtle(graph)   // Turtle (RDF 1.1)
+toNQuads(graph)   // N-Quads
+toJsonLd(graph)   // JSON-LD 1.1 object with an inline @context
+toQuads(graph)    // RDF/JS quads for N3.js, Comunica, Oxigraph or rdf-ext
+```
+
+`exportSeeds` takes the `source` and `pins` options of `getSeeds`, plus:
+
+| Option | |
+|---|---|
+| `asOf` | Unix seconds. The graph EAS held then: attestations made later are left out, and one revoked later counts. Reads EAS, so `source: 'local'` is refused. See [A graph beside an archive bag](#a-graph-beside-an-archive-bag). |
+| `chainId` | The chain the seeds were attested on. Required: EAS uids don't include it. |
+| `base` | Base of the minted IRIs, ending in `/`. Default `PROVISIONAL_BASE_IRI`. |
+| `contentUrl` | `(transactionId) => string`, an `https://` URL for stored content, written as `schema:contentUrl`. |
+| `lens` | `{ schema, sidecar }`: maps your models and properties to terms and types Numbers and Dates. See [Lens](#lens). |
+
+To export seeds you have already read, pass the entries of `getSeedAttestations` to `stateGraph`.
+
+## What the graph contains
+
+For each seed, at its head Version (or the pinned one):
+
+| Seed | RDF |
+|---|---|
+| The seed | `{base}eas/{chainId}/{seedUid}`, typed `seed:Seed` and `{base}c/{model}` |
+| Its attester and creation time | `prov:wasAttributedTo <did:pkh:eip155:{chainId}:{address}>`, `prov:generatedAtTime` |
+| Its head Version | `seed:currentVersion` |
+| Its Versions up to the head | Each a `seed:Version` with `seed:versionOf` the seed, `prov:generatedAtTime`, `prov:wasAttributedTo` its attester and `prov:wasRevisionOf` the Version before. Revoked Versions and Versions from other attesters are left out. |
+| A property `string title` | `{base}p/string/title` with the newest value the seed's attester attested |
+| A relation | The related seed's IRI |
+| A list of relations | An RDF list of seed IRIs, in order |
+| An Image, File, Html or Json seed | `seed:content <ar://{transactionId}>` beside its `storage_transaction_id` |
+
+Literals are typed from the EAS type: `bool` is `xsd:boolean`, integer types are `xsd:integer`,
+`bytes` values are `xsd:hexBinary`, and everything else is `xsd:string`. A Number is an EAS
+`string` (ADR 0010) and a Date a `uint256` of seconds, so without a [lens](#lens) they come out
+as `xsd:string` and `xsd:integer`. A removed value (ADR 0021) is left out. The graph has no blank
+nodes except the cells of lists.
+
+`seedVocabulary()` returns the `seed:` terms in Turtle.
+
+The same seeds, `asOf`, options and sidecar give the same bytes from `toJsonLd`, `toTurtle` and
+`toNQuads`, whatever order EAS returns attestations in. Seeds are written in the order you pass
+them.
+
+## A graph beside an archive bag
+
+A reproducible archive bag from `@seedprotocol/archive` records the seed, the time it covers and
+the chain in bag-info.txt. Export with that time and the graph holds the same attestations as the
+bag, plus the Version history. Anyone can rebuild it from EAS and compare bytes.
+
+```ts
+import { readBagInfo } from '@seedprotocol/archive'
+import { exportSeeds, toJsonLd } from '@seedprotocol/rdf'
+
+const info = readBagInfo(bag)
+const graph = await exportSeeds([info.get('Seed-Uid')!], {
+  chainId: Number(info.get('EAS-Chain-Id')),
+  asOf: Date.parse(info.get('Seed-Bag-As-Of')!) / 1000,
+  lens,
+})
+const jsonld = JSON.stringify(toJsonLd(graph))
+```
+
+The graph goes beside the bag, not in it: the bag's `tagmanifest-sha256.txt` hash and its anchor
+don't cover it, and its IRIs use the provisional base. Neither package imports the other; your
+app reads bag-info with archive and passes the three values to rdf.
+
+rdf doesn't read the Html's h-entry. To give a title as `dcterms:title`, map the property in the
+sidecar:
+
+```json
+{
+  "schemaId": "blog-schema-id",
+  "@context": { "dcterms": "http://purl.org/dc/terms/" },
+  "terms": {
+    "<title property id>": "dcterms:title",
+    "<author property id>": "dcterms:creator",
+    "<published at property id>": "dcterms:issued"
+  }
+}
+```
+
+## Lens
+
+A protocol predicate such as `{base}p/string/title` says what is on chain, not what it means. A
+lens adds that: pass your Schema and a sidecar, a JSON file that lives beside it.
+
+```json
+{
+  "schemaId": "my-schema-id",
+  "@context": { "schema": "https://schema.org/", "dcterms": "http://purl.org/dc/terms/" },
+  "terms": {
+    "<Post model id>": "schema:BlogPosting",
+    "<title property id>": "schema:headline",
+    "<publishedAt property id>": "schema:datePublished",
+    "<authors property id>": "dcterms:creator"
+  }
+}
+```
+
+```ts
+const graph = await exportSeeds([seedUid], { chainId, lens: { schema, sidecar } })
+graph.warnings // terms it couldn't use, values that don't fit their type
+```
+
+`terms` is keyed by the `id` of a model or property in the Schema file, so renaming either keeps its
+term. Values are a prefixed name, using the top-level strings of `@context`, or an absolute IRI.
+
+- A mapped model's class replaces `{base}c/{model}`, and a mapped property's term replaces its
+  protocol predicate. `seed:Seed` stays, and anything unmapped keeps its protocol IRI.
+- A Number is typed per value: `xsd:integer`, `xsd:decimal`, or `xsd:double` in its canonical form
+  (`1e+21` becomes `1.0E21`). A value that isn't a number stays an `xsd:string`, with a warning.
+- A Date is an `xsd:dateTime` in UTC.
+- On-chain names are matched to the Schema the way sync matches them, including `nameMatch`. An
+  attestation made under a name the Schema no longer matches keeps its protocol predicate.
+
+The graph also records which mapping it used: a `prov:Activity` at `{base}export/{sha256}`
+with `prov:used <ni:///sha-256;…>` (RFC 6920), the SHA-256 of the sidecar's `schemaId`, `terms`
+and `@context` as JSON with sorted keys. The node stands for the mapping, not for one export, so
+two exports with the same sidecar name the same node, and it has no time or agent. Like every
+minted IRI it uses the provisional base; keep it out of anything anchored.
+
+A sidecar whose `schemaId` isn't the Schema's `id` throws. A term with no matching id or a prefix
+`@context` doesn't define is a warning, and the export goes on without it.
+
+## SHACL
+
+```ts
+import { toShacl } from '@seedprotocol/rdf'
+
+const shapes = toShacl({ schema, sidecar }) // Turtle
+```
+
+`toShacl` describes the graphs `exportSeeds` gives with the same lens, in SHACL 2017. Each model is a
+`sh:NodeShape` targeting the class its seeds get, and each property a property shape on the
+predicate they get:
+
+| Schema | Shape |
+|---|---|
+| Text, Boolean, Date | `sh:datatype` `xsd:string`, `xsd:boolean`, `xsd:dateTime` |
+| Number | `sh:or` of `xsd:integer`, `xsd:decimal` and `xsd:double` |
+| Relation, Image, File, Html, Json | `sh:nodeKind sh:IRI` |
+| List | every cell of the `rdf:List` has one `rdf:first` and one `rdf:rest`; a List of relations' members are IRIs |
+| `required: true` | `sh:minCount 1` |
+
+Every property has `sh:maxCount 1`. A relation's class isn't checked, because the related seed is
+often not in the export. For shapes over the protocol IRIs, pass a sidecar with empty `terms`.
+
+## Keeping the sidecar current
+
+The sidecar's own `@context` can carry a type-scoped context with your local names, for tools
+that read the file as JSON-LD. It's generated from `terms`, so it goes stale when a model or
+property is renamed; `terms` doesn't, because it's keyed by id.
+
+```bash
+seed-rdf check              # stale and unreadable terms, unmapped properties; exits 1 on the first two
+seed-rdf sync --write       # regenerate @context and schemaVersion from terms and the current names
+seed-rdf suggest            # draft schema.org / dcterms terms for unmapped names such as title or author
+seed-rdf suggest --write    # add them to the sidecar, creating it if needed
+```
+
+Each command reads `seedSchema.json` and `seedSchema.context.jsonld` in the working directory;
+`--schema` and `--sidecar` take other paths. `sync` and `suggest` print what they would write
+unless given `--write`, and `sync` keeps stale terms: removing a mapping is your call. The same
+functions are exported as `checkSidecar`, `syncSidecar`, `suggestTerms` and `sidecarContext`.
+
+`seedVitePlugin` from `@seedprotocol/vite` runs the check on the dev server and warns when the
+schema or sidecar changes.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { a as e, i as t, n, t as r } from "./sidecar-BjHSnqHK.js";
+import i from "node:process";
+import { readFile as a, writeFile as o } from "node:fs/promises";
+import s from "node:path";
+import { parseArgs as c } from "node:util";
+//#region src/cli.ts
+var l = "Usage:\n  seed-rdf check   [--schema <file>] [--sidecar <file>] [--base <iri>]\n      List stale terms, terms that aren't IRIs, and unmapped models and properties.\n      Exits 1 when there are stale or unreadable terms.\n\n  seed-rdf sync    [--schema <file>] [--sidecar <file>] [--base <iri>] [--write]\n      Regenerate the sidecar's @context from its terms and the schema's current names, and set\n      schemaVersion. Prints the result, or writes it to the sidecar with --write.\n\n  seed-rdf suggest [--schema <file>] [--sidecar <file>] [--base <iri>] [--write]\n      Draft schema.org and dcterms terms for unmapped names with a common meaning. Prints them,\n      or adds them to the sidecar (creating it if needed) with --write. Review before committing.\n\nDefault --schema: seedSchema.json. Default --sidecar: the schema's path with .context.jsonld\nin place of .json.", u = class extends Error {
+	showUsage;
+	constructor(e, t = !1) {
+		super(e), this.showUsage = t;
+	}
+};
+async function d(e, t) {
+	let n;
+	try {
+		n = await a(e, "utf8");
+	} catch (n) {
+		throw n.code === "ENOENT" ? new u(`No ${t} at ${e}`) : n;
+	}
+	try {
+		return JSON.parse(n);
+	} catch (n) {
+		throw new u(`The ${t} at ${e} isn't JSON: ${n.message}`);
+	}
+}
+var f = (e) => `${JSON.stringify(e, null, 2)}\n`, p = (e) => e.property ? `${e.model}.${e.property}` : e.model;
+async function m(i, a) {
+	try {
+		let { positionals: m, values: h } = c({
+			args: [...i],
+			allowPositionals: !0,
+			options: {
+				schema: { type: "string" },
+				sidecar: { type: "string" },
+				base: { type: "string" },
+				write: { type: "boolean" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			}
+		}), [g, ..._] = m;
+		if (h.help) return a.out(l), 0;
+		if (!g || _.length > 0 || ![
+			"check",
+			"sync",
+			"suggest"
+		].includes(g)) throw new u(g ? `Unknown command: ${[g, ..._].join(" ")}` : "No command given", !0);
+		if (g === "check" && h.write) throw new u("check never writes; use sync --write");
+		let v = s.resolve(a.cwd, h.schema ?? "seedSchema.json"), y = h.sidecar ? s.resolve(a.cwd, h.sidecar) : v.replace(/(\.json)?$/, ".context.jsonld"), b = await d(v, "schema");
+		if (!b.id) throw new u(`The schema at ${v} has no id; the SDK assigns one when it writes the schema`);
+		let x = { base: h.base };
+		if (g === "suggest") {
+			let n = await d(y, "sidecar").catch((e) => {
+				if (!(e instanceof u && e.message.startsWith("No sidecar"))) throw e;
+			}) ?? {
+				schemaId: b.id,
+				terms: {}
+			}, i = t({
+				schema: b,
+				sidecar: n
+			});
+			if (!h.write) {
+				i.length === 0 && a.out("No suggestions.");
+				for (let e of i) a.out(`${p(e)} (${e.id}): ${e.term}`);
+				return 0;
+			}
+			let s = {
+				...n.terms,
+				...Object.fromEntries(i.map((e) => [e.id, e.term]))
+			}, c = {
+				...r,
+				...n["@context"]
+			};
+			return await o(y, f(e({
+				schema: b,
+				sidecar: {
+					...n,
+					terms: s,
+					"@context": c
+				}
+			}, x))), a.out(`Added ${i.length} term${i.length === 1 ? "" : "s"} to ${y}. Review them before committing.`), 0;
+		}
+		let S = await d(y, "sidecar");
+		if (g === "sync") {
+			let t = e({
+				schema: b,
+				sidecar: S
+			}, x);
+			return h.write ? (await o(y, f(t)), a.out(`Wrote ${y}`), 0) : (a.out(f(t).trimEnd()), 0);
+		}
+		let C = n({
+			schema: b,
+			sidecar: S
+		}, x);
+		if (C.stale.length > 0) {
+			a.err("Stale terms (no model or property in the schema has this id):");
+			for (let { id: e, term: t } of C.stale) a.err(`  ${e}: ${t}`);
+		}
+		if (C.invalid.length > 0) {
+			a.err("Terms that aren't an IRI or a name with a prefix in @context:");
+			for (let { id: e, term: t } of C.invalid) a.err(`  ${e}: ${t}`);
+		}
+		if (C.unmapped.length > 0) {
+			a.out("Unmapped (exported under protocol IRIs):");
+			for (let e of C.unmapped) a.out(`  ${p(e)}${e.id ? ` (${e.id})` : " (no id yet)"}`);
+		}
+		return (C.contextOutdated || C.versionOutdated) && a.out("The sidecar is behind the schema; run `seed-rdf sync --write` to update @context and schemaVersion."), +(C.stale.length > 0 || C.invalid.length > 0);
+	} catch (e) {
+		if (!(e instanceof u) && !(e instanceof TypeError)) throw e;
+		return a.err(`[Seed Protocol] ${e.message}`), e instanceof u && e.showUsage && a.err(l), 2;
+	}
+}
+//#endregion
+//#region src/bin.ts
+i.exitCode = await m(i.argv.slice(2), {
+	cwd: i.cwd(),
+	out: (e) => console.log(e),
+	err: (e) => console.error(e)
+});
+//#endregion
+
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","names":["syncSidecar","suggestTerms","SUGGESTED_PREFIXES","process","path","USAGE","UsageError","message","showUsage","readJson","text","readFile","file","error","what","json","value","target","t","runRdfCli","parseArgs","args","command","extra","positionals","values","io","schemaFile","sidecarFile","schema","options","sidecar","suggestions","s","terms","context","writeFile","synced","report","checkSidecar","id","term","line"],"sources":["../src/cli.ts","../src/bin.ts"],"sourcesContent":["import { readFile, writeFile } from 'node:fs/promises'\nimport path from 'node:path'\nimport { parseArgs } from 'node:util'\nimport type { RdfSidecar } from './lens.js'\nimport { SUGGESTED_PREFIXES, checkSidecar, suggestTerms, syncSidecar, type SidecarSchema } from './sidecar.js'\n\nconst USAGE = `Usage:\n  seed-rdf check   [--schema <file>] [--sidecar <file>] [--base <iri>]\n      List stale terms, terms that aren't IRIs, and unmapped models and properties.\n      Exits 1 when there are stale or unreadable terms.\n\n  seed-rdf sync    [--schema <file>] [--sidecar <file>] [--base <iri>] [--write]\n      Regenerate the sidecar's @context from its terms and the schema's current names, and set\n      schemaVersion. Prints the result, or writes it to the sidecar with --write.\n\n  seed-rdf suggest [--schema <file>] [--sidecar <file>] [--base <iri>] [--write]\n      Draft schema.org and dcterms terms for unmapped names with a common meaning. Prints them,\n      or adds them to the sidecar (creating it if needed) with --write. Review before committing.\n\nDefault --schema: seedSchema.json. Default --sidecar: the schema's path with .context.jsonld\nin place of .json.`\n\nexport type CliIo = {\n  readonly cwd: string\n  readonly out: (line: string) => void\n  readonly err: (line: string) => void\n}\n\nclass UsageError extends Error {\n  constructor(\n    message: string,\n    readonly showUsage = false,\n  ) {\n    super(message)\n  }\n}\n\nasync function readJson<T>(file: string, what: string): Promise<T> {\n  let text: string\n  try {\n    text = await readFile(file, 'utf8')\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new UsageError(`No ${what} at ${file}`)\n    throw error\n  }\n  try {\n    return JSON.parse(text) as T\n  } catch (error) {\n    throw new UsageError(`The ${what} at ${file} isn't JSON: ${(error as Error).message}`)\n  }\n}\n\nconst json = (value: unknown) => `${JSON.stringify(value, null, 2)}\\n`\nconst target = (t: { model: string; property?: string }) => (t.property ? `${t.model}.${t.property}` : t.model)\n\n/**\n * Runs `seed-rdf` with `args` (without the program name) and returns its exit code: 0 when done,\n * 1 when `check` finds stale or unreadable terms, 2 on a usage or input error.\n */\nexport async function runRdfCli(args: readonly string[], io: CliIo): Promise<number> {\n  try {\n    const { positionals, values } = parseArgs({\n      args: [...args],\n      allowPositionals: true,\n      options: {\n        schema: { type: 'string' },\n        sidecar: { type: 'string' },\n        base: { type: 'string' },\n        write: { type: 'boolean' },\n        help: { type: 'boolean', short: 'h' },\n      },\n    })\n    const [command, ...extra] = positionals\n    if (values.help) {\n      io.out(USAGE)\n      return 0\n    }\n    if (!command || extra.length > 0 || !['check', 'sync', 'suggest'].includes(command)) {\n      throw new UsageError(command ? `Unknown command: ${[command, ...extra].join(' ')}` : 'No command given', true)\n    }\n    if (command === 'check' && values.write) throw new UsageError('check never writes; use sync --write')\n\n    const schemaFile = path.resolve(io.cwd, values.schema ?? 'seedSchema.json')\n    const sidecarFile = values.sidecar\n      ? path.resolve(io.cwd, values.sidecar)\n      : schemaFile.replace(/(\\.json)?$/, '.context.jsonld')\n    const schema = await readJson<SidecarSchema>(schemaFile, 'schema')\n    if (!schema.id) throw new UsageError(`The schema at ${schemaFile} has no id; the SDK assigns one when it writes the schema`)\n    const options = { base: values.base }\n\n    if (command === 'suggest') {\n      const existing = await readJson<RdfSidecar>(sidecarFile, 'sidecar').catch((error: unknown) => {\n        if (error instanceof UsageError && error.message.startsWith('No sidecar')) return undefined\n        throw error\n      })\n      const sidecar = existing ?? { schemaId: schema.id, terms: {} }\n      const suggestions = suggestTerms({ schema, sidecar })\n      if (!values.write) {\n        if (suggestions.length === 0) io.out('No suggestions.')\n        for (const s of suggestions) io.out(`${target(s)} (${s.id}): ${s.term}`)\n        return 0\n      }\n      const terms = { ...sidecar.terms, ...Object.fromEntries(suggestions.map((s) => [s.id, s.term])) }\n      const context = { ...SUGGESTED_PREFIXES, ...sidecar['@context'] }\n      await writeFile(sidecarFile, json(syncSidecar({ schema, sidecar: { ...sidecar, terms, '@context': context } }, options)))\n      io.out(`Added ${suggestions.length} term${suggestions.length === 1 ? '' : 's'} to ${sidecarFile}. Review them before committing.`)\n      return 0\n    }\n\n    const sidecar = await readJson<RdfSidecar>(sidecarFile, 'sidecar')\n    if (command === 'sync') {\n      const synced = syncSidecar({ schema, sidecar }, options)\n      if (!values.write) {\n        io.out(json(synced).trimEnd())\n        return 0\n      }\n      await writeFile(sidecarFile, json(synced))\n      io.out(`Wrote ${sidecarFile}`)\n      return 0\n    }\n\n    const report = checkSidecar({ schema, sidecar }, options)\n    if (report.stale.length > 0) {\n      io.err('Stale terms (no model or property in the schema has this id):')\n      for (const { id, term } of report.stale) io.err(`  ${id}: ${term}`)\n    }\n    if (report.invalid.length > 0) {\n      io.err(`Terms that aren't an IRI or a name with a prefix in @context:`)\n      for (const { id, term } of report.invalid) io.err(`  ${id}: ${term}`)\n    }\n    if (report.unmapped.length > 0) {\n      io.out('Unmapped (exported under protocol IRIs):')\n      for (const t of report.unmapped) io.out(`  ${target(t)}${t.id ? ` (${t.id})` : ' (no id yet)'}`)\n    }\n    if (report.contextOutdated || report.versionOutdated) {\n      io.out('The sidecar is behind the schema; run `seed-rdf sync --write` to update @context and schemaVersion.')\n    }\n    return report.stale.length > 0 || report.invalid.length > 0 ? 1 : 0\n  } catch (error) {\n    if (!(error instanceof UsageError) && !(error instanceof TypeError)) throw error\n    io.err(`[Seed Protocol] ${error.message}`)\n    if (error instanceof UsageError && error.showUsage) io.err(USAGE)\n    return 2\n  }\n}\n","/** `seed-rdf check|sync|suggest`: keeps an app's RDF sidecar in step with its schema. */\nimport process from 'node:process'\nimport { runRdfCli } from './cli.js'\n\nprocess.exitCode = await runRdfCli(process.argv.slice(2), {\n  cwd: process.cwd(),\n  out: (line) => console.log(line),\n  err: (line) => console.error(line),\n})\n"],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+export type CliIo = {
+    readonly cwd: string;
+    readonly out: (line: string) => void;
+    readonly err: (line: string) => void;
+};
+/**
+ * Runs `seed-rdf` with `args` (without the program name) and returns its exit code: 0 when done,
+ * 1 when `check` finds stale or unreadable terms, 2 on a usage or input error.
+ */
+export declare function runRdfCli(args: readonly string[], io: CliIo): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC,CAAA;AA6BD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAqFnF"}

package/dist/graph.d.ts

@@ -0,0 +1,65 @@
+import type { SeedAttestations } from '@seedprotocol/query';
+import { type IriScheme } from './iri.js';
+import { type RdfLens } from './lens.js';
+/** An IRI, a typed literal, or an RDF list of either. */
+export type RdfObject = {
+    readonly kind: 'iri';
+    readonly iri: string;
+} | {
+    readonly kind: 'literal';
+    readonly value: string;
+    readonly datatype: string;
+} | {
+    readonly kind: 'list';
+    readonly items: readonly RdfObject[];
+};
+/** One subject and its statements, predicates in the order they were added. */
+export type RdfNode = {
+    readonly id: string;
+    readonly properties: ReadonlyMap<string, readonly RdfObject[]>;
+};
+/**
+ * A state graph: each seed's current values at its head Version, in the default graph. Every
+ * subject is an IRI; the only blank nodes are the cells of RDF lists, which writers create.
+ */
+export type StateGraph = {
+    readonly iris: IriScheme;
+    readonly nodes: readonly RdfNode[];
+    /** Prefixes from the lens, for the writers. */
+    readonly prefixes: ReadonlyMap<string, string>;
+    /** Lens terms that couldn't be used, and values that don't fit their data type. Empty without a lens. */
+    readonly warnings: readonly string[];
+};
+export type StateGraphOptions = {
+    /** The chain the seeds were attested on. EAS uids don't include it, so every IRI does. */
+    chainId: number;
+    /** Base of the minted IRIs. Default PROVISIONAL_BASE_IRI. */
+    base?: string;
+    /**
+     * An `https://` URL for an Arweave transaction, given as `schema:contentUrl` beside the
+     * `ar://` content IRI, since most RDF tools can't fetch `ar://`. None by default.
+     */
+    contentUrl?: (transactionId: string) => string;
+    /**
+     * The app's Schema and sidecar. Mapped classes and predicates replace the protocol IRIs in the
+     * graph, and a Number or Date gets its literal type. None by default.
+     */
+    lens?: RdfLens;
+};
+/**
+ * The state graph of `seeds` (from `getSeedAttestations` in @seedprotocol/query). Each seed is
+ * typed `seed:Seed` and its model class (`{base}c/{model}`), attributed to its attester as a
+ * `did:pkh`, and linked to its head Version (`seed:currentVersion`). Its live Versions up to the head
+ * are `seed:Version`s with `prov:generatedAtTime`, `prov:wasAttributedTo`, and `prov:wasRevisionOf`
+ * the Version before; revoked Versions are left out, as in an archive bag. Each property is one statement with the protocol
+ * predicate `{base}p/{easType}/{easName}`. Relations are Seed IRIs, lists are RDF lists, and an
+ * Image, File, Html or Json seed's `storage_transaction_id` also gives `seed:content <ar://…>`.
+ * Without a lens, values are typed from the EAS type alone: a Number (an EAS `string`, ADR 0010)
+ * is an `xsd:string`, and a Date (`uint256` seconds) an `xsd:integer`. With one, a Number is typed
+ * per value and a Date is an `xsd:dateTime`, and mapped terms replace the protocol IRIs, and the
+ * graph gets a `prov:Activity` `{base}export/{sha256}` whose `prov:used` is the sidecar's hash as
+ * an RFC 6920 `ni:///sha-256;…` IRI. That IRI is under the provisional base: keep it out of
+ * anything anchored, such as an archive bag.
+ */
+export declare function stateGraph(seeds: readonly SeedAttestations[], options: StateGraphOptions): StateGraph;
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAmD,MAAM,qBAAqB,CAAA;AAC5G,OAAO,EAA6C,KAAK,SAAS,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EAAiD,KAAK,OAAO,EAAmB,MAAM,WAAW,CAAA;AAExG,yDAAyD;AACzD,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,CAAA;AAEnE,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC,CAAA;CAC/D,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9C,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AA8GD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAgErG"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { type GetSeedAttestationsOptions } from '@seedprotocol/query';
+import { type StateGraph, type StateGraphOptions } from './graph.js';
+export { PROVISIONAL_BASE_IRI, iriScheme } from './iri.js';
+export type { IriScheme } from './iri.js';
+export { stateGraph } from './graph.js';
+export type { RdfNode, RdfObject, StateGraph, StateGraphOptions } from './graph.js';
+export type { LensSchema, RdfLens, RdfSidecar } from './lens.js';
+export { toQuads, toNQuads } from './quads.js';
+export { toTurtle } from './turtle.js';
+export { toJsonLd } from './jsonld.js';
+export type { JsonLdDocument } from './jsonld.js';
+export { seedVocabulary } from './vocabulary.js';
+export { toShacl } from './shacl.js';
+export type { ShaclOptions } from './shacl.js';
+export { SUGGESTED_PREFIXES, checkSidecar, sidecarContext, suggestTerms, syncSidecar } from './sidecar.js';
+export type { SchemaTarget, SidecarContext, SidecarContextOptions, SidecarReport, SidecarSchema, TermSuggestion, } from './sidecar.js';
+export type ExportSeedsOptions = StateGraphOptions & Pick<GetSeedAttestationsOptions, 'source' | 'pins' | 'asOf'>;
+/**
+ * The state graph of the seeds, read with `getSeedAttestations` from @seedprotocol/query (same
+ * sources and pins as `getSeeds`). Seeds that aren't found are left out. With `asOf` (unix
+ * seconds), the graph is what EAS held then, the same attestations a reproducible archive bag with
+ * that `Seed-Bag-As-Of` holds; it reads EAS and refuses `source: 'local'`. Two exports with the
+ * same seeds, `asOf`, options and sidecar give the same bytes from every writer.
+ */
+export declare function exportSeeds(seedUids: readonly string[], options: ExportSeedsOptions): Promise<StateGraph>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAC1F,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEhF,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAC1D,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnF,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1G,YAAY,EACV,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAA;AAErB,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,IAAI,CAAC,0BAA0B,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC,CAAA;AAEjH;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAIrB"}