claude: fold in old sow-tools

2026-06-13 09:49:29 +02:00
parent cdabf69aa2
commit cf89c166fe
112 changed files with 70812 additions and 74 deletions
@@ -0,0 +1,78 @@
+# Topdata Inheritance Contract
+
+## Status Snapshot
+
+Current state as of 2026-05-13:
+
+- Implemented.
+- `native.go` supports both row-sugar inheritance and generic object
+  inheritance, including cycle detection and missing-target failures.
+- Validation and build regression coverage live in `topdata_test.go`.
+
+Native topdata now supports two inheritance forms:
+
+## 1. Row Sugar Compatibility
+
+This is the existing narrow row helper:
+
+```json
+{
+  "PARENT": { "id": "custom:parent" },
+  "inherit": {
+    "from": "PARENT",
+    "fields": ["VALUE", "ICON"]
+  }
+}
+```
+
+It remains supported for row-local field copying.
+
+## 2. Generic Object Inheritance
+
+This is the new reusable primitive:
+
+```json
+{
+  "inherit": {
+    "ref": "masterfeats:skillfocus"
+  },
+  "LABEL": "FEAT_SKILL_FOCUS_ATHLETICS"
+}
+```
+
+Or for a nested object:
+
+```json
+{
+  "DETAILS": {
+    "inherit": {
+      "ref": "custom:parent",
+      "field": "DETAILS"
+    },
+    "meta": {
+      "cost": "9"
+    }
+  }
+}
+```
+
+## Rules
+
+- `inherit.ref` must use stable `dataset:key` identity.
+- `inherit.field` is optional and selects an object-valued field on the target row.
+- Generic inheritance can appear on any authored object, not only top-level rows.
+- Merge precedence is `local overrides inherited`.
+- Scalars replace inherited values.
+- Arrays replace inherited values.
+- Objects merge recursively unless the local object is an atomic topdata value object such as:
+  - TLK payloads
+  - row refs
+  - table refs
+- Cycles fail the build.
+- Missing targets fail the build.
+
+## Current Intended Consumer
+
+`feat` is the first dataset expected to use this primitive heavily, especially for
+borrowing shared properties from `masterfeats` while keeping `feat`'s own dataset
+contract and row model.