Symbols, not timelines; no symbol is special

Everything that holds nodes is a symbol (domain/timeline -> domain/symbol,
:timelines -> :symbols) and a node that places one is :kind :instance. The
reserved :main root is gone: which symbol is on screen is editor state
([:ui :open]), every domain function that needs a symbol is told which, and
a document opens on the longest symbol nothing else places.

Saved projects move to schema 2 through migration 0007, which rewrites leaf
paths, instance kinds and the feature :symbol key; the client refuses a
schema it does not read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

clips/migrations/0007_symbols_not_timelines.py

@@ -0,0 +1,75 @@
+"""Schema 2: a document holds symbols, not timelines, and no symbol is reserved.
+
+Three renames, each in the stored transit and nowhere else:
+
+  clip/<cid>/timeline/...          ->  clip/<cid>/symbol/...
+  a node leaf's  :kind :symbol     ->  :kind :instance
+  a feature leaf's :timeline key   ->  :symbol
+
+A leaf value is transit's map form, ["^ ", k1, v1, k2, v2, ...]. Only TOP-LEVEL
+pairs are rewritten, and only literal ones: transit caches a repeated keyword as
+"^N", and a rename that met a cache reference where it expected the keyword would
+be guessing. Every saved leaf at the time of writing had these as literals; if one
+does not, the migration stops rather than writing a document that decodes to
+something else.
+
+Renaming a cached keyword in place is safe because the cache is positional: the
+literal keeps its slot, so any later "^N" that referred to it now refers to the
+new name, which is what it meant.
+"""
+
+import re
+
+from django.db import migrations, models
+
+PATH = re.compile(r"^(clip/[^/]+/)timeline(/|$)")
+
+
+def _rename_pair(value, key, old, new, path):
+    if not (isinstance(value, list) and value[:1] == ["^ "]):
+        return value
+    out = list(value)
+    for i in range(1, len(out) - 1, 2):
+        if out[i] != key:
+            continue
+        if old is None:
+            out[i] = new
+        elif out[i + 1] == old:
+            out[i + 1] = new
+        elif isinstance(out[i + 1], str) and out[i + 1].startswith("^") and out[i + 1] != "^ ":
+            raise RuntimeError(f"leaf {path!r} has a cached {key} value; migrate it by hand")
+    return out
+
+
+def forwards(apps, schema_editor):
+    Leaf = apps.get_model("clips", "Leaf")
+    Project = apps.get_model("clips", "Project")
+    for leaf in Leaf.objects.all():
+        path = PATH.sub(r"\1symbol\2", leaf.path)
+        value = leaf.value
+        parts = path.split("/")
+        if len(parts) == 6 and parts[2] == "symbol" and parts[4] == "node":
+            value = _rename_pair(value, "~:kind", "~:symbol", "~:instance", leaf.path)
+        if len(parts) == 4 and parts[2] == "feature":
+            value = _rename_pair(value, "~:timeline", None, "~:symbol", leaf.path)
+        if path != leaf.path or value != leaf.value:
+            leaf.path = path
+            leaf.value = value
+            leaf.version += 1
+            leaf.save(update_fields=["path", "value", "version"])
+    Project.objects.update(schema_version=2)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("clips", "0006_project_schema_version"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="project",
+            name="schema_version",
+            field=models.PositiveIntegerField(default=2),
+        ),
+        migrations.RunPython(forwards, migrations.RunPython.noop),
+    ]

clips/models.py

@@ -206,7 +206,7 @@ class Project(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     name = models.CharField(max_length=200, default="untitled")
-    schema_version = models.PositiveIntegerField(default=1)
+    schema_version = models.PositiveIntegerField(default=2)
     seq = models.PositiveBigIntegerField(default=0)
     palette = models.CharField(max_length=64, default="arthur/default")
     created = models.DateTimeField(auto_now_add=True)

clips/tests/test_api.py

@@ -382,13 +382,13 @@ class DocumentTests(TestCase):
         # cache marker, keyword keys, and a frame-keyed inner map.
         return {
             "clip/c1/timing": ["^ ", "~:fps", 30],
-            "clip/c1/timeline/main": ["^ ", "~:frames", 48],
-            "clip/c1/timeline/main/node/mouth": ["^ ", "~:id", "~:mouth", "~:z", "a1"],
-            "clip/c1/timeline/main/channel/mouth/geom.pts": [
+            "clip/c1/symbol/main": ["^ ", "~:frames", 48],
+            "clip/c1/symbol/main/node/mouth": ["^ ", "~:id", "~:mouth", "~:z", "a1"],
+            "clip/c1/symbol/main/channel/mouth/geom.pts": [
                 "^ ", "~:animated?", True, "~:dense",
                 ["^ ", "~:store", self.block, "~:offset", 0, "~:stride", 16],
             ],
-            "clip/c1/timeline/main/channel/mouth-in/vis": [
+            "clip/c1/symbol/main/channel/mouth-in/vis": [
                 "^ ", "~:animated?", True, "~:keys", ["^ ", "~i0", True, "~i12", False],
             ],
         }
@@ -407,7 +407,7 @@ class DocumentTests(TestCase):
         self.assertEqual(5, len(response.json()["written"]))
 
         loaded = self.client.get(f"/api/projects/{self.project.id}").json()
-        self.assertEqual(1, loaded["schema_version"])
+        self.assertEqual(2, loaded["schema_version"])
         self.assertEqual(1, len(loaded["clips"]))
         clip = loaded["clips"][0]
         self.assertEqual("c1", clip["cid"])
@@ -424,22 +424,22 @@ class DocumentTests(TestCase):
         self.save()
         first = {leaf.path: leaf.version for leaf in Leaf.objects.all()}
         moved = self.leaves()
-        moved["clip/c1/timeline/main/channel/mouth-in/vis"] = [
+        moved["clip/c1/symbol/main/channel/mouth-in/vis"] = [
             "^ ", "~:animated?", True, "~:keys", ["^ ", "~i0", False],
         ]
         response = self.save(moved)
-        self.assertEqual(["clip/c1/timeline/main/channel/mouth-in/vis"], response.json()["written"])
+        self.assertEqual(["clip/c1/symbol/main/channel/mouth-in/vis"], response.json()["written"])
         self.assertEqual(4, response.json()["unchanged"])
         after = {leaf.path: leaf.version for leaf in Leaf.objects.all()}
-        self.assertEqual(2, after["clip/c1/timeline/main/channel/mouth-in/vis"])
+        self.assertEqual(2, after["clip/c1/symbol/main/channel/mouth-in/vis"])
         self.assertEqual(first["clip/c1/timing"], after["clip/c1/timing"])
 
     def test_a_removed_node_removes_its_leaf(self):
         self.save()
         fewer = {k: v for k, v in self.leaves().items()
-                 if k != "clip/c1/timeline/main/node/mouth"}
+                 if k != "clip/c1/symbol/main/node/mouth"}
         response = self.save(fewer)
-        self.assertEqual(["clip/c1/timeline/main/node/mouth"], response.json()["removed"])
+        self.assertEqual(["clip/c1/symbol/main/node/mouth"], response.json()["removed"])
         self.assertEqual(4, Leaf.objects.count())
 
     def test_a_save_does_not_disturb_another_clip(self):
@@ -472,7 +472,7 @@ class DocumentTests(TestCase):
 
     def test_a_leaf_write_carries_an_etag(self):
         self.save()
-        url = f"/api/projects/{self.project.id}/leaves/clip/c1/timeline/main/node/mouth"
+        url = f"/api/projects/{self.project.id}/leaves/clip/c1/symbol/main/node/mouth"
         got = self.client.get(url)
         self.assertEqual('"1"', got["ETag"])
 
@@ -488,7 +488,7 @@ class DocumentTests(TestCase):
         # take-theirs. A PUT that replaced unconditionally is the bug where the
         # loser's work disappears silently.
         self.save()
-        url = f"/api/projects/{self.project.id}/leaves/clip/c1/timeline/main/node/mouth"
+        url = f"/api/projects/{self.project.id}/leaves/clip/c1/symbol/main/node/mouth"
         self.put(url, {"value": ["^ ", "~:z", "a2"]}, HTTP_IF_MATCH='"1"')
         stale = self.put(url, {"value": ["^ ", "~:z", "a3"]}, HTTP_IF_MATCH='"1"')
         self.assertEqual(409, stale.status_code)