Skip to content

World's first open-source enterprise world model.

Document what exported rule identities currently describe (#904)

Maya Kide4bef19610fe
diff --git a/docs/decisions/0020-an-auditor-reads-it-without-us.md b/docs/decisions/0020-an-auditor-reads-it-without-us.md
index 6e4447bf..0f7a7f9e 100644
--- a/docs/decisions/0020-an-auditor-reads-it-without-us.md
+++ b/docs/decisions/0020-an-auditor-reads-it-without-us.md
@@ -62,6 +62,11 @@ One of the five built-in packs is PROV-O, so a base that has it loaded already k
- **Conflict/review state and chunk identity behind a quote.** Quotes and source
documents are exported, but these are separate gaps; conflict state is tracked
in [#564](https://github.com/deeplethe/utopia/issues/564).
+- **Machine-readable rule definitions.** A generating rule is currently exported
+ as `prov:Activity` with an `rdfs:label`, under `…:rule:{id}`. Its criteria,
+ operands and expressions are not exported; [#902](https://github.com/deeplethe/utopia/issues/902)
+ discusses that extension. Business rules are edited in place, so their stable
+ identifiers do not identify the definitions that were used for older conclusions.
- **Historical proof snapshots.** Premise links can be rewritten when a conclusion
is reproved. The record-time lifetime survives; earlier versions of the proof
do not (0019). RDF's `prov:used` edges identify premises, not their sequence.
diff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.md
index ba52cc2e..3f2150b7 100644
--- a/web/src/docs/mcp.md
+++ b/web/src/docs/mcp.md
@@ -59,9 +59,9 @@ source documents, and derivations linked to their rules and premise statements.
It uses RDF reification, PROV-O and schema.org. This mapping is the compatibility
boundary: a breaking change needs a decision record explaining why.
-Entities, assertions, derivations and documents have UUID-based IRIs:
-`urn:utopia:kb:{kb_id}:entity:{id}`, `…:fact:{id}`, `…:derived:{id}` and
-`…:document:{id}`. The same stored object keeps its identity across exports;
+Entities, assertions, derivations, rules and documents have UUID-based IRIs:
+`urn:utopia:kb:{kb_id}:entity:{id}`, `…:fact:{id}`, `…:derived:{id}`,
+`…:rule:{id}` and `…:document:{id}`. The same stored object keeps its identity across exports;
rebuilding a graph is not an identity-preserving operation. `?base=https://example.org/`
instead mints `https://example.org/kb/{kb_id}/{kind}/{id}`. Keep the same base when
joining exports. Imported classes and relations retain their original IRIs.
@@ -71,6 +71,14 @@ Ontology export includes explicitly stored `owl:inverseOf` and
key-based IRI. It copies declarations within the base; it does not add reciprocal
links or compute a transitive closure.
+A derivation links to `…:rule:{id}` through `prov:wasGeneratedBy`. The rule
+resource is typed `prov:Activity` and carries an `rdfs:label`: the business
+rule's name, or the axiom rule's kind. The label is human-readable text, not a
+machine-readable rule definition; it does not reliably identify the rule family.
+Rule criteria, operands and expressions are not currently exported. Their RDF
+representation is under discussion in [#902](https://github.com/deeplethe/utopia/issues/902).
+A rule IRI identifies the stored rule, not a historical version of its definition.
+
MCP remains the agent-facing surface. The structured results below use the same
UUIDs, so an integration can join a selected result to the exported ledger.
Ordinary `/api/v1` UI response shapes are **not** a compatibility promise: they