datanotes 3.1.0 → 3.2.0

package/dist/docs/guides/database-objects/relations.md

@@ -1,6 +1,6 @@
 # Relations and hierarchies
 
-> Link rows to rows of other tables, keep two-way links in step, take allowed values from a table, build trees and limit link targets.
+> Link rows to rows of other tables, keep two-way links in step, take allowed values from a table, build trees, keep dependencies free of cycles and limit link targets.
 
 A link column holds a wikilink to a note, such as `[[Charade]]`, and `ref` names the table that note must be a row of. The link points to a row of the other table, and you reach that row’s columns through the link.
 
@@ -56,7 +56,7 @@ Answer:
   "op": "create_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.watch", "version": 0, "operation": "CREATE TABLE" }],
-  "migration_id": "20261014T191519-create_table-create-table-main-public-watch"
+  "migration_id": "20261019T040640-create_table-create-table-main-public-watch"
 }
 ```
 
@@ -85,7 +85,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/watch/2026-03-14T2030.md"],
   "commits": [{ "table": "main.public.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261014T191519-insert_row-insert-into-watch"
+  "migration_id": "20261019T040640-insert_row-insert-into-watch"
 }
 ```
 
@@ -94,7 +94,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-29c4-790f-bb11-5bcb70ba79cf
+id: 01a15257-1334-78ef-a884-7dec625383fb
 film: "[[His Girl Friday]]"
 where: cinema
 place: the film club downtown
@@ -189,7 +189,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.actor", "version": 4, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261014T191519-add_column-add-column-films-to-actor"
+  "migration_id": "20261019T040640-add_column-add-column-films-to-actor"
 }
 ```
 
@@ -217,7 +217,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 4, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261014T191519-add_column-add-column-cast-to-film"
+  "migration_id": "20261019T040640-add_column-add-column-cast-to-film"
 }
 ```
 
@@ -259,7 +259,7 @@ Answer:
     { "table": "main.public.actor", "version": 5, "operation": "UPDATE" },
     { "table": "main.public.film", "version": 5, "operation": "UPDATE" }
   ],
-  "migration_id": "20261014T191519-update_row-update-film"
+  "migration_id": "20261019T040640-update_row-update-film"
 }
 ```
 
@@ -268,7 +268,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-299b-7edc-b1ed-cf26ab668970
+id: 01a15257-1318-7711-9b6a-1133ed5ade2a
 title: Charade
 year: 1963
 minutes: 113
@@ -291,7 +291,7 @@ Answer:
 ```markdown
 ---
 table: main.public.actor
-id: 01a13bd7-294c-784d-8436-19760ff440a9
+id: 01a15257-12f4-74ff-9c67-ad018a33f0ad
 name: Cary Grant
 born: 1904-01-18
 films:
@@ -359,7 +359,7 @@ Answer:
         {
           "path": "datanotes/main/public/actor/Cary Grant.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-294c-784d-8436-19760ff440a9",
+          "id": "01a15257-12f4-74ff-9c67-ad018a33f0ad",
           "name": "Cary Grant",
           "born": "1904-01-18",
           "films": ["[[Charade]]", "[[His Girl Friday]]"]
@@ -367,7 +367,7 @@ Answer:
         {
           "path": "datanotes/main/public/actor/Audrey Hepburn.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-2978-7561-9e4e-769c1a55fe6e",
+          "id": "01a15257-1302-766a-9b85-dcc175445424",
           "name": "Audrey Hepburn",
           "born": "1929-05-04",
           "films": ["[[Charade]]"]
@@ -423,7 +423,7 @@ Answer:
   "op": "alter_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 9, "operation": "CHANGE COLUMN" }],
-  "migration_id": "20261014T191519-alter_column-alter-column-see_also-in-film"
+  "migration_id": "20261019T040640-alter_column-alter-column-see_also-in-film"
 }
 ```
 
@@ -479,7 +479,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 10, "operation": "ALIGN RELATIONS" }
   ],
-  "migration_id": "20261014T191519-align_relations-align-inverse-links-of-main-pu"
+  "migration_id": "20261019T040640-align_relations-align-inverse-links-of-main-pu"
 }
 ```
 
@@ -573,7 +573,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 11, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261014T191519-add_column-add-column-tags-to-film"
+  "migration_id": "20261019T040640-add_column-add-column-tags-to-film"
 }
 ```
 
@@ -629,7 +629,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 12, "operation": "UPDATE" }],
-  "migration_id": "20261014T191519-update_row-update-film-4"
+  "migration_id": "20261019T040640-update_row-update-film-4"
 }
 ```
 
@@ -677,7 +677,7 @@ Answer:
   "op": "create_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.genre", "version": 0, "operation": "CREATE TABLE" }],
-  "migration_id": "20261014T191519-create_table-create-table-main-public-genre"
+  "migration_id": "20261019T040640-create_table-create-table-main-public-genre"
 }
 ```
 
@@ -753,10 +753,130 @@ Refused:
 ```text
 update_row refused — nothing was written:
 invalid datanotes/main/public/genre/Cinema.md: parent would make "Cinema" its own ancestor (Cinema → Screwball comedy → Sound film → Cinema)
-Hint: A row cannot be its own ancestor: point the hierarchy column to a row that is not below this one. Then call update_row again (dry_run: true checks without writing).
+Hint: A row cannot be its own ancestor in a hierarchy column, nor depend on itself through an acyclic column: the message shows the path. Point the column to a row that is not on that path. Then call update_row again (dry_run: true checks without writing).
 Docs: https://datanotes.dev/guides/database-objects/relations.md#build-a-tree-of-rows-with-a-parent-link (offline: read_docs("guides/database-objects/relations#build-a-tree-of-rows-with-a-parent-link"))
 ```
 
+## Keep dependencies free of cycles with `acyclic`
+
+`acyclic: true` keeps the links of a column free of cycles. It works on a link, or a list of links, to the same table (`ref: self`). Here `watch_after` lists the films to watch first, and `watch_before` is its inverse.
+
+The engine refuses a write that closes a cycle:
+
+* **Through the column**: a film can’t wait for a film that already waits for it
+* **Through the inverse**: `watch_before` adds the matching `watch_after` link, and the engine checks that link too
+* **On existing rows**: `alter_column` refuses `acyclic: true` while rows already form a cycle, and lists them
+
+`hierarchy` refuses cycles too, but takes one parent per row. `acyclic` takes any number of links.
+
+**`add_column`**
+
+```json
+{
+  "table": "film",
+  "column": {
+    "name": "watch_after",
+    "type": "list",
+    "items": "link",
+    "ref": "self",
+    "acyclic": true,
+    "description": "Films to watch before this one"
+  }
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "add_column",
+  "planned_texts": ["datanotes/metastore.yaml"],
+  "commits": [{ "table": "main.public.film", "version": 13, "operation": "ADD COLUMNS" }],
+  "migration_id": "20261019T040640-add_column-add-column-watch_after-to-film"
+}
+```
+
+**`add_column`**
+
+```json
+{
+  "table": "film",
+  "column": {
+    "name": "watch_before",
+    "type": "list",
+    "items": "link",
+    "ref": "self",
+    "inverse": "watch_after",
+    "description": "Films to watch after this one"
+  }
+}
+```
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Night of the Living Dead.md",
+  "set": { "watch_after": ["[[Charade]]"] }
+}
+```
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Charade.md",
+  "set": { "watch_after": ["[[His Girl Friday]]"] }
+}
+```
+
+His Girl Friday can’t wait for Night of the Living Dead, which waits for it through Charade:
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/His Girl Friday.md",
+  "set": { "watch_after": ["[[Night of the Living Dead]]"] }
+}
+```
+
+Refused:
+
+```text
+update_row refused — nothing was written:
+invalid datanotes/main/public/film/His Girl Friday.md: watch_after would close a cycle in "watch_after" (His Girl Friday → Night of the Living Dead → Charade → His Girl Friday)
+invalid datanotes/main/public/film/Night of the Living Dead.md: watch_after would close a cycle in "watch_after" (Night of the Living Dead → Charade → His Girl Friday → Night of the Living Dead)
+Hint: A row cannot depend on itself through an acyclic column: the message shows the cycle. Remove one of its links, or link to a row that is not on it; check_table lists the cycles already there. Then call update_row again (dry_run: true checks without writing).
+Docs: https://datanotes.dev/guides/database-objects/relations.md#keep-dependencies-free-of-cycles-with-acyclic (offline: read_docs("guides/database-objects/relations#keep-dependencies-free-of-cycles-with-acyclic"))
+```
+
+Setting the inverse closes the same cycle, so the engine refuses it too:
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Night of the Living Dead.md",
+  "set": { "watch_before": ["[[His Girl Friday]]"] }
+}
+```
+
+Refused:
+
+```text
+update_row refused — nothing was written:
+invalid datanotes/main/public/film/His Girl Friday.md: watch_after would close a cycle in "watch_after" (His Girl Friday → Night of the Living Dead → Charade → His Girl Friday)
+invalid datanotes/main/public/film/Night of the Living Dead.md: watch_after would close a cycle in "watch_after" (Night of the Living Dead → Charade → His Girl Friday → Night of the Living Dead)
+Hint: A row cannot depend on itself through an acyclic column: the message shows the cycle. Remove one of its links, or link to a row that is not on it; check_table lists the cycles already there. Then call update_row again (dry_run: true checks without writing).
+Docs: https://datanotes.dev/guides/database-objects/relations.md#keep-dependencies-free-of-cycles-with-acyclic (offline: read_docs("guides/database-objects/relations#keep-dependencies-free-of-cycles-with-acyclic"))
+```
+
 ## Limit link targets with `ref_by` and `ref_where`
 
 A link column can limit which rows it points to, without a CHECK. `ref_by` reads a column of the row itself. With `levels: [cinema, era, genre]`, Cinema has no parent, an era’s parent must be Cinema, and a genre’s parent must be an era.
@@ -787,7 +907,7 @@ Answer:
   "commits": [
     { "table": "main.public.genre", "version": 10, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261014T191521-alter_column-alter-column-parent-in-genre"
+  "migration_id": "20261019T040642-alter_column-alter-column-parent-in-genre"
 }
 ```
 
@@ -944,8 +1064,8 @@ Answer:
   "ok": true,
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "commits": [{ "table": "main.public.film", "version": 13, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261014T191521-add_column-add-column-genre-to-film"
+  "commits": [{ "table": "main.public.film", "version": 17, "operation": "ADD COLUMNS" }],
+  "migration_id": "20261019T040642-add_column-add-column-genre-to-film"
 }
 ```
 
@@ -1027,7 +1147,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.watch", "version": 3, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261014T191521-add_column-add-column-on_day-to-watch"
+  "migration_id": "20261019T040642-add_column-add-column-on_day-to-watch"
 }
 ```
 
@@ -1056,7 +1176,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/watch/2026-10-31T2300.md"],
   "commits": [{ "table": "main.public.watch", "version": 4, "operation": "WRITE" }],
-  "migration_id": "20261014T191521-insert_row-insert-into-watch"
+  "migration_id": "20261019T040642-insert_row-insert-into-watch"
 }
 ```
 
@@ -1065,7 +1185,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-31d3-73b7-b24a-735b30d93502
+id: 01a15257-1c26-7cdc-8409-61767eceb696
 film: "[[Night of the Living Dead]]"
 where: cinema
 place: the film club downtown
@@ -1094,7 +1214,7 @@ Refused:
 
 ```text
 delete_rows refused — nothing was written:
-conflict datanotes/main/public/film/Charade.md: referenced by datanotes/main/public/actor/Audrey Hepburn.md, datanotes/main/public/actor/Cary Grant.md, datanotes/main/public/film/His Girl Friday.md, datanotes/main/public/watch/2026-09-26T2130.md
+conflict datanotes/main/public/film/Charade.md: referenced by datanotes/main/public/actor/Audrey Hepburn.md, datanotes/main/public/actor/Cary Grant.md, datanotes/main/public/film/His Girl Friday.md, datanotes/main/public/film/Night of the Living Dead.md, datanotes/main/public/watch/2026-09-26T2130.md
 Hint: Other rows link to it: pass on_referenced ("set_null" or "ignore"), or change those rows first.
 Docs: https://datanotes.dev/guides/database-objects/relations.md#delete-a-row-that-other-notes-link-to (offline: read_docs("guides/database-objects/relations#delete-a-row-that-other-notes-link-to"))
 ```
@@ -1135,20 +1255,20 @@ Delete the viewing and the film together with `batch`. The viewing goes first, t
 }
 ```
 
-Answer (72 lines)
+Answer (77 lines)
 
 ```json
 {
   "ok": true,
   "op": "batch",
   "dry_run": false,
-  "migration_id": "20261014T191521-batch-remove-charade-and-its-viewing",
+  "migration_id": "20261019T040643-batch-remove-charade-and-its-viewing",
   "steps": [
     {
       "index": 0,
       "op": "delete_rows",
       "ok": true,
-      "migration_id": "20261014T191521-delete_rows-archive-1-rows-of-watch",
+      "migration_id": "20261019T040643-delete_rows-archive-1-rows-of-watch",
       "result": {
         "ok": true,
         "op": "delete_rows",
@@ -1160,18 +1280,18 @@ Answer (72 lines)
           }
         ],
         "commits": [{ "table": "main.public.watch", "version": 5, "operation": "DELETE" }],
-        "migration_id": "20261014T191521-delete_rows-archive-1-rows-of-watch"
+        "migration_id": "20261019T040643-delete_rows-archive-1-rows-of-watch"
       }
     },
     {
       "index": 1,
       "op": "delete_rows",
       "ok": true,
-      "migration_id": "20261014T191521-delete_rows-archive-1-rows-of-film",
+      "migration_id": "20261019T040643-delete_rows-archive-1-rows-of-film",
       "result": {
         "ok": true,
         "op": "delete_rows",
-        "notes_changed": 4,
+        "notes_changed": 5,
         "files_moved": 1,
         "planned_edits": [
           {
@@ -1186,7 +1306,12 @@ Answer (72 lines)
           },
           {
             "path": "datanotes/main/public/film/His Girl Friday.md",
-            "set": { "see_also": [] },
+            "set": { "see_also": [], "watch_before": [] },
+            "remove": []
+          },
+          {
+            "path": "datanotes/main/public/film/Night of the Living Dead.md",
+            "set": { "watch_after": [] },
             "remove": []
           },
           {
@@ -1203,9 +1328,9 @@ Answer (72 lines)
         ],
         "commits": [
           { "table": "main.public.actor", "version": 7, "operation": "DELETE" },
-          { "table": "main.public.film", "version": 14, "operation": "DELETE" }
+          { "table": "main.public.film", "version": 18, "operation": "DELETE" }
         ],
-        "migration_id": "20261014T191521-delete_rows-archive-1-rows-of-film"
+        "migration_id": "20261019T040643-delete_rows-archive-1-rows-of-film"
       }
     }
   ]
@@ -1223,7 +1348,7 @@ Answer:
 ```markdown
 ---
 table: main.public.actor
-id: 01a13bd7-294c-784d-8436-19760ff440a9
+id: 01a15257-12f4-74ff-9c67-ad018a33f0ad
 name: Cary Grant
 born: 1904-01-18
 films:
@@ -1237,7 +1362,7 @@ The engine wrote this file with the relations from this page:
 
 * **Link columns**: each with its `ref`, and `self` kept as written
 * **`inverse`**: on one side only
-* **`vocabulary`, `hierarchy` and `ref_where`**: as declared
+* **`vocabulary`, `hierarchy`, `acyclic` and `ref_where`**: as declared
 * **`ref_by`**: with the `levels` shortcut kept as written
 * **Generated link**: the `on_day` column with its template
 
@@ -1245,7 +1370,7 @@ The engine wrote this file with the relations from this page:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-28e9-7fae-aac4-f73856dcd3a3
+id: 01a15257-12e1-7b62-b27c-c29567a21bea
 config:
   history: true
 
@@ -1323,6 +1448,18 @@ catalogs:
                 items: string
                 description: My tags for the film, from the tag table
                 vocabulary: main.public.tag
+              - name: watch_after
+                type: list
+                items: link
+                ref: self
+                description: Films to watch before this one
+                acyclic: true
+              - name: watch_before
+                type: list
+                items: link
+                ref: self
+                description: Films to watch after this one
+                inverse: watch_after
               - name: genre
                 type: link
                 ref: main.public.genre