@wildwinter/toolkit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# @wildwinter/toolkit
+
+## 0.2.0
+
+### Added
+
+- **`@wildwinter/toolkit/extensions`**: the shared spec and merge for Patter extensions and Storylet
+  extensions ([extensions.md](extensions.md)). The manifest and its checks (`manifestProblems`), the value types
+  and their checks (`valueProblems`, `entryProblems`) on the kernel's `valueFits`, `qualityDeclarationProblems`
+  and `stagesEitherSide`, defaults (`defaultOf`, through `defaultFor`), what a bundle carries (`compiledTarget`,
+  `compileEntry`), stage renames (`renameStages`), claims on host fields (`resolvedClaims`, `claimClashes`), the
+  three-way merge engine (`mergeTree`) and its manifest-built strategies (`mergeExtensionData`), the
+  `unresolved` mark (`markUnresolved`, `unresolvedProblems`) and orphaned entries (`orphanedEntries`).
+  Hand-written conformance cases in `conformance/extensions/`. `@wildwinter/expr` and
+  `@wildwinter/scoperegistry` are optional peer dependencies, needed by this entry only.
+
+## 0.1.0
+
+First release. Small shared pieces of the authoring tooling, each of which
+arrived by being found duplicated across the two consuming product families
+rather than by being anticipated.
+
+Nothing here runs in a game, and nothing here is about the expression language:
+that is `@wildwinter/expr`, and game-side sharing is the vendored source in
+`expr/ports`, because C++, C# and GDScript cannot consume an npm package.
+
+### Added
+
+- **`newId` / `slug`** (`ids.ts`): opaque, rejection-sampled base-36 ids, so
+  every alphabet character is equally likely. A plain `byte % 36` over-weights
+  the first four.
+- **`fnv32`** (`hash.ts`): FNV-1a, for short stable handles and change
+  detection. Not cryptographic.
+- **`parseSource`** (`source.ts`): JSON5 with a tolerated byte-order mark, which
+  JSON5 alone will not accept and Windows editors add.
+- **`findMatcher`** (`find.ts`): the escaped, global find regex behind find and
+  replace, so a query of `a.b` means those three characters.
+- **`@wildwinter/toolkit/archive`**: the zip entry guards (`isUnsafeEntry`,
+  `escapesTarget`) and the settings that make an archive byte-reproducible. A
+  separate entry point because it needs `node:path`, and the main entry stays
+  isomorphic so a browser bundle can take it.
+
+  The guards were correct in both families before this, which is the state
+  BEFORE a drift rather than evidence there will not be one: a subtle weakening
+  of one copy is a vulnerability nobody reads a diff for.

package/README.md

@@ -3,7 +3,8 @@
 Small shared pieces of the **authoring tooling** behind
 [Storylet Studio](https://github.com/storylet-studio) and
 [Patter](https://patterkit.com): opaque ids, a stable hash, JSON5 source parsing,
-find/replace matching, and the archive guards.
+find/replace matching, the archive guards, and (in `./extensions`) the spec and merge
+for Patter extensions and Storylet extensions.
 
 **Nothing here runs in a game.** This is the editor/CLI/pipeline side. The
 runtime language lives in [`@wildwinter/expr`](../expr), and unlike that package
@@ -15,7 +16,21 @@ Each was found duplicated, almost but not exactly, across both families. That
 one careless edit away from being correct in one, and nobody reads the diff of a
 file they believe is a copy.
 
-ESM + CJS + types. `json5` is the only dependency.
+ESM + CJS + types. `json5` is the only dependency of the main entry.
+
+## Extensions (`@wildwinter/toolkit/extensions`)
+
+The one part with shared semantics: the manifest a Patter extension or a Storylet extension ships, the types its
+values take, the checks both editors and both command lines run, and the type-driven three-way merge both formats
+use for extension data, with the `unresolved` mark an unresolved merge leaves in a shard. The spec is
+[extensions.md](extensions.md) and its contract the hand-written cases in `conformance/extensions/`.
+
+It is built on the kernel's own value and ladder rules, so it needs `@wildwinter/expr` and
+`@wildwinter/scoperegistry`: optional peer dependencies, which every host of it already has.
+
+```ts
+import { manifestProblems, mergeExtensionData } from "@wildwinter/toolkit/extensions";
+```
 
 ```ts
 import { newId, slug, fnv32, parseSource, findMatcher } from "@wildwinter/toolkit";

package/conformance/extensions/defaults.json

@@ -0,0 +1,69 @@
+{
+  "about": "Defaults, compilation and stage renames. `defaults`: defaultOf for a declaration. `compile`: compiledTarget (declarations as a bundle carries them: editor-only fields gone, every default resolved, label, help, valueHelp and group gone) and compileEntry (a node's values as a bundle carries them: editor-only and undeclared fields gone, renamed stages renamed, otherwise raw). `renames`: renameStages over an entry, with the renames it made.",
+  "defaults": [
+    { "name": "a given default wins", "decl": { "name": "a", "type": "number", "default": 4 }, "default": 4 },
+    { "name": "text", "decl": { "name": "a", "type": "text" }, "default": "" },
+    { "name": "multiline", "decl": { "name": "a", "type": "multiline" }, "default": "" },
+    { "name": "number", "decl": { "name": "a", "type": "number" }, "default": 0 },
+    { "name": "boolean", "decl": { "name": "a", "type": "boolean" }, "default": false },
+    { "name": "enum: the first value", "decl": { "name": "a", "type": "enum", "values": ["x", "y"] }, "default": "x" },
+    { "name": "an enum may default to none chosen", "decl": { "name": "a", "type": "enum", "values": ["x", "y"], "default": "" }, "default": "" },
+    { "name": "flags: none", "decl": { "name": "a", "type": "flags", "values": ["x"] }, "default": [] },
+    { "name": "quality: the first stage", "decl": { "name": "a", "type": "quality", "stages": ["p", "q"] }, "default": "p" },
+    { "name": "reference: none", "decl": { "name": "a", "type": "reference", "to": "card" }, "default": "" },
+    { "name": "record: each field's default", "decl": { "name": "a", "type": "record", "fields": [
+      { "name": "s", "type": "text" }, { "name": "n", "type": "number", "default": 2 }, { "name": "q", "type": "quality", "stages": ["p", "q"] }
+    ] }, "default": { "n": 2, "q": "p", "s": "" } },
+    { "name": "record: a given default wins whole", "decl": { "name": "a", "type": "record", "fields": [{ "name": "s", "type": "text" }], "default": { "s": "x" } }, "default": { "s": "x" } },
+    { "name": "map: empty", "decl": { "name": "a", "type": "map", "key": { "type": "text" }, "of": { "type": "number" } }, "default": {} },
+    { "name": "list: empty", "decl": { "name": "a", "type": "list", "of": { "type": "number" } }, "default": [] }
+  ],
+  "compile": [
+    {
+      "name": "a target as the bundle carries it",
+      "target": { "fields": [
+        { "name": "note", "type": "text", "label": "Note", "help": "Help.", "group": "G", "required": true },
+        { "name": "draft", "type": "multiline", "editorOnly": true },
+        { "name": "tone", "type": "enum", "values": ["calm", "tense"], "valueHelp": { "calm": "x" } },
+        { "name": "act", "type": "quality", "stages": ["setup", "turn"], "renamedStages": { "opening": "setup" } },
+        { "name": "cue", "type": "record", "fields": [{ "name": "gain", "type": "number", "min": 0, "help": "Loudness." }] }
+      ], "claims": [{ "setting": "moodField", "type": "text" }] },
+      "compiled": [
+        { "name": "note", "type": "text", "default": "", "required": true },
+        { "name": "tone", "type": "enum", "values": ["calm", "tense"], "default": "calm" },
+        { "name": "act", "type": "quality", "stages": ["setup", "turn"], "default": "setup" },
+        { "name": "cue", "type": "record", "fields": [{ "name": "gain", "type": "number", "min": 0, "default": 0 }], "default": { "gain": 0 } }
+      ],
+      "entry": { "note": "n", "draft": "only in the editor", "act": "opening", "stray": 1, "cue": { "gain": 2 } },
+      "compiledEntry": { "act": "setup", "cue": { "gain": 2 }, "note": "n" }
+    },
+    {
+      "name": "an entry with nothing compiled compiles to nothing",
+      "target": { "fields": [{ "name": "draft", "type": "text", "editorOnly": true }] },
+      "compiled": [],
+      "entry": { "draft": "x" },
+      "compiledEntry": null
+    }
+  ],
+  "renames": [
+    {
+      "name": "stages renamed wherever a quality is, at any depth",
+      "target": { "fields": [
+        { "name": "act", "type": "quality", "stages": ["setup", "turn"], "renamedStages": { "opening": "setup", "middle": "turn" } },
+        { "name": "beats", "type": "list", "id": "id", "of": { "type": "record", "fields": [
+          { "name": "id", "type": "text" },
+          { "name": "phase", "type": "quality", "stages": ["in", "out"], "renamedStages": { "enter": "in" } }
+        ] } },
+        { "name": "byTag", "type": "map", "key": { "type": "text" }, "of": { "type": "quality", "stages": ["lo", "hi"], "renamedStages": { "low": "lo" } } },
+        { "name": "tone", "type": "text" }
+      ] },
+      "entry": { "act": "middle", "beats": [{ "id": "b1", "phase": "enter" }, { "id": "b2", "phase": "out" }], "byTag": { "a": "low", "b": "hi" }, "tone": "opening" },
+      "renamed": { "act": "turn", "beats": [{ "id": "b1", "phase": "in" }, { "id": "b2", "phase": "out" }], "byTag": { "a": "lo", "b": "hi" }, "tone": "opening" },
+      "renames": [
+        { "path": "act", "from": "middle", "to": "turn" },
+        { "path": "beats[0].phase", "from": "enter", "to": "in" },
+        { "path": "byTag.a", "from": "low", "to": "lo" }
+      ]
+    }
+  ]
+}

package/conformance/extensions/manifest.json

@@ -0,0 +1,264 @@
+{
+  "about": "Manifest validation. Each case gives a manifest and every problem manifestProblems reports for it, by path and code, in the order reported. A case with no problems is a manifest that must pass.",
+  "cases": [
+    {
+      "name": "a minimal manifest passes",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [{ "name": "mood", "type": "text" }] } } } },
+      "problems": []
+    },
+    {
+      "name": "every type, a claim and a setting pass together",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "2.1.0",
+        "docs": "https://example.com/probe",
+        "settings": [{ "name": "moodField", "label": "Mood field", "default": "mood" }],
+        "targets": {
+          "storylets": {
+            "card": {
+              "fields": [
+                { "name": "note", "type": "text", "label": "Note", "help": "A line for the crew." },
+                { "name": "body", "type": "multiline", "editorOnly": true },
+                { "name": "weight", "type": "number", "min": 0, "max": 10, "default": 1 },
+                { "name": "loud", "type": "boolean", "required": true },
+                { "name": "tone", "type": "enum", "values": ["calm", "tense"], "valueHelp": { "calm": "Unhurried." } },
+                { "name": "marks", "type": "flags", "values": ["night", "rain"], "default": ["rain"] },
+                { "name": "act", "type": "quality", "stages": ["setup", "turn", "close"], "renamedStages": { "opening": "setup" } },
+                { "name": "next", "type": "reference", "to": "card" },
+                { "name": "cue", "type": "record", "fields": [{ "name": "sound", "type": "text" }, { "name": "gain", "type": "number" }] },
+                { "name": "byTag", "type": "map", "key": { "type": "reference", "to": "tag" }, "of": { "type": "number" } },
+                { "name": "byName", "type": "map", "key": { "type": "text" }, "of": { "type": "record", "fields": [{ "name": "look", "type": "text" }] } },
+                { "name": "beats", "type": "list", "id": "id", "of": { "type": "record", "fields": [{ "name": "id", "type": "text" }, { "name": "at", "type": "number" }] } },
+                { "name": "words", "type": "list", "of": { "type": "text" } }
+              ],
+              "claims": [{ "setting": "moodField", "type": "enum", "values": ["calm", "tense"], "help": "The card's mood." }]
+            },
+            "project": { "fields": [{ "name": "studio", "type": "text" }] }
+          },
+          "patter": { "line": { "fields": [{ "name": "to", "type": "reference", "to": "cast" }] } }
+        } },
+      "problems": []
+    },
+    {
+      "name": "identity is checked",
+      "manifest": { "schema": "wildwinter/extension@1", "id": "Probe Two", "name": " ", "version": "1.0", "docs": 3,
+        "targets": { "storylets": { "card": { "fields": [] } } } },
+      "problems": [
+        { "path": "schema", "code": "schema" },
+        { "path": "id", "code": "id" },
+        { "path": "name", "code": "name" },
+        { "path": "version", "code": "version" },
+        { "path": "docs", "code": "docs" }
+      ]
+    },
+    {
+      "name": "a manifest must target something it knows",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "ink": { "knot": {} }, "storylets": { "scene": {} } } },
+      "problems": [
+        { "path": "targets.ink", "code": "unknown-host" },
+        { "path": "targets.storylets.scene", "code": "unknown-kind" }
+      ]
+    },
+    {
+      "name": "no targets at all",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0", "targets": {} },
+      "problems": [{ "path": "targets", "code": "no-targets" }]
+    },
+    {
+      "name": "field names are identifiers, once each",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "mood", "type": "text" }, { "name": "mood", "type": "number" }, { "name": "9lives", "type": "text" }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[1].name", "code": "duplicate-field" },
+        { "path": "targets.storylets.card.fields[2].name", "code": "field-name" }
+      ]
+    },
+    {
+      "name": "the text type is spelled text, and an unknown type is refused",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "a", "type": "string" }, { "name": "b", "type": "colour" }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].type", "code": "string-type" },
+        { "path": "targets.storylets.card.fields[1].type", "code": "unknown-type" }
+      ]
+    },
+    {
+      "name": "enum and flags values: some, none empty, none twice",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "a", "type": "enum", "values": [] },
+          { "name": "b", "type": "flags", "values": ["x", "", "x"] },
+          { "name": "c", "type": "enum" }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].values", "code": "values-empty" },
+        { "path": "targets.storylets.card.fields[1].values[1]", "code": "value-empty" },
+        { "path": "targets.storylets.card.fields[1].values[2]", "code": "value-duplicate" },
+        { "path": "targets.storylets.card.fields[2].values", "code": "values-empty" }
+      ]
+    },
+    {
+      "name": "a quality's ladder follows the kernel's rule",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "a", "type": "quality", "stages": ["only"] },
+          { "name": "b", "type": "quality", "stages": ["x", "x"] },
+          { "name": "c", "type": "quality", "stages": ["x", "y"], "default": "z" }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].stages", "code": "quality-too-few-stages" },
+        { "path": "targets.storylets.card.fields[1].stages", "code": "quality-duplicate-stage" },
+        { "path": "targets.storylets.card.fields[2].default", "code": "default-misfit" }
+      ]
+    },
+    {
+      "name": "renamed stages map old names to current stages",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "act", "type": "quality", "stages": ["setup", "turn"], "renamedStages": { "turn": "setup", "old": "gone" } },
+          { "name": "tone", "type": "enum", "values": ["a", "b"], "renamedStages": { "x": "a" } }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].renamedStages.turn", "code": "renamed-stages" },
+        { "path": "targets.storylets.card.fields[0].renamedStages.old", "code": "renamed-stages" },
+        { "path": "targets.storylets.card.fields[1].renamedStages", "code": "renamed-stages" }
+      ]
+    },
+    {
+      "name": "value help names only values the field has",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "tone", "type": "enum", "values": ["a", "b"], "valueHelp": { "a": "Fine.", "c": "No such value." } },
+          { "name": "n", "type": "number", "valueHelp": { "1": "One." } }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].valueHelp.c", "code": "value-help" },
+        { "path": "targets.storylets.card.fields[1].valueHelp", "code": "value-help" }
+      ]
+    },
+    {
+      "name": "a reference names a kind its host can point at",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": {
+          "storylets": { "card": { "fields": [{ "name": "who", "type": "reference", "to": "cast" }, { "name": "where", "type": "reference" }] } },
+          "patter": { "line": { "fields": [{ "name": "card", "type": "reference", "to": "card" }] } }
+        } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].to", "code": "reference-to" },
+        { "path": "targets.storylets.card.fields[1].to", "code": "reference-to" },
+        { "path": "targets.patter.line.fields[0].to", "code": "reference-to" }
+      ]
+    },
+    {
+      "name": "structured types need their parts",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "r", "type": "record", "fields": [] },
+          { "name": "m", "type": "map", "key": { "type": "number" }, "of": { "type": "text" } },
+          { "name": "m2", "type": "map", "key": { "type": "text" } },
+          { "name": "l", "type": "list", "id": "id", "of": { "type": "record", "fields": [{ "name": "at", "type": "number" }] } },
+          { "name": "l2", "type": "list", "id": "id", "of": { "type": "text" } },
+          { "name": "l3", "type": "list" }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].fields", "code": "record-empty" },
+        { "path": "targets.storylets.card.fields[1].key", "code": "map-key" },
+        { "path": "targets.storylets.card.fields[2].of", "code": "missing-of" },
+        { "path": "targets.storylets.card.fields[3].id", "code": "list-id" },
+        { "path": "targets.storylets.card.fields[4].id", "code": "list-id" },
+        { "path": "targets.storylets.card.fields[5].of", "code": "missing-of" }
+      ]
+    },
+    {
+      "name": "problems inside a structured type are found where they are",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "m", "type": "map", "key": { "type": "text" }, "of": { "type": "record", "fields": [
+            { "name": "a", "type": "enum", "values": [] }, { "name": "a", "type": "text", "editorOnly": true }
+          ] } }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].of.fields[0].values", "code": "values-empty" },
+        { "path": "targets.storylets.card.fields[0].of.fields[1].name", "code": "duplicate-field" },
+        { "path": "targets.storylets.card.fields[0].of.fields[1].editorOnly", "code": "editor-only-nested" }
+      ]
+    },
+    {
+      "name": "a given default must fit, in every type",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "a", "type": "number", "default": "1" },
+          { "name": "b", "type": "enum", "values": ["x"], "default": "y" },
+          { "name": "c", "type": "enum", "values": ["x"], "default": "" },
+          { "name": "d", "type": "flags", "values": ["x"], "default": ["x", "z"] },
+          { "name": "e", "type": "number", "min": 1, "default": 0 },
+          { "name": "f", "type": "record", "fields": [{ "name": "g", "type": "boolean" }], "default": { "g": 1 } },
+          { "name": "h", "type": "list", "of": { "type": "number" }, "default": [1, "2"] }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].default", "code": "default-misfit" },
+        { "path": "targets.storylets.card.fields[1].default", "code": "default-misfit" },
+        { "path": "targets.storylets.card.fields[3].default", "code": "default-misfit" },
+        { "path": "targets.storylets.card.fields[4].default", "code": "default-misfit" },
+        { "path": "targets.storylets.card.fields[5].default", "code": "default-misfit" },
+        { "path": "targets.storylets.card.fields[6].default", "code": "default-misfit" }
+      ]
+    },
+    {
+      "name": "ranges apply to numbers and run upwards",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [
+          { "name": "a", "type": "number", "min": 5, "max": 1 },
+          { "name": "b", "type": "text", "max": 3 }
+        ] } } } },
+      "problems": [
+        { "path": "targets.storylets.card.fields[0].max", "code": "range" },
+        { "path": "targets.storylets.card.fields[1].max", "code": "range" }
+      ]
+    },
+    {
+      "name": "a misspelt attribute is a warning, not silence",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "targets": { "storylets": { "card": { "fields": [{ "name": "a", "type": "text", "requird": true }] } } } },
+      "problems": [{ "path": "targets.storylets.card.fields[0].requird", "code": "unknown-key", "severity": "warning" }]
+    },
+    {
+      "name": "claims: a claimable kind, a declared setting, a scalar, once per setting",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "settings": [{ "name": "moodField", "default": "mood" }],
+        "targets": {
+          "storylets": {
+            "deck": { "claims": [{ "setting": "moodField", "type": "text" }] },
+            "card": { "claims": [
+              { "setting": "moodField", "type": "text" },
+              { "setting": "moodField", "type": "text" },
+              { "setting": "nope", "type": "text" },
+              { "setting": "moodField", "type": "record", "fields": [{ "name": "a", "type": "text" }] }
+            ] }
+          }
+        } },
+      "problems": [
+        { "path": "targets.storylets.deck.claims[0]", "code": "claim-kind" },
+        { "path": "targets.storylets.card.claims[1].setting", "code": "claim-duplicate" },
+        { "path": "targets.storylets.card.claims[2].setting", "code": "claim-setting" },
+        { "path": "targets.storylets.card.claims[3].type", "code": "claim-type" },
+        { "path": "targets.storylets.card.claims[3].setting", "code": "claim-duplicate" }
+      ]
+    },
+    {
+      "name": "settings: named once each, defaulting to a field name",
+      "manifest": { "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+        "settings": [{ "name": "a", "default": "x" }, { "name": "a", "default": "y" }, { "name": "b" }, { "name": "c", "default": "not a name" }],
+        "targets": { "storylets": { "card": {} } } },
+      "problems": [
+        { "path": "settings[1].name", "code": "setting-duplicate" },
+        { "path": "settings[2].default", "code": "setting-default" },
+        { "path": "settings[3].default", "code": "setting-default" }
+      ]
+    }
+  ]
+}

package/conformance/extensions/merge.json

@@ -0,0 +1,154 @@
+{
+  "about": "The merge. `tree` cases run mergeTree with a strategy given as data, expecting the merged value and each clash's path and kind. `data` cases run mergeExtensionData over extension shards, with the manifest (or null for none), expecting the merged shard, `unresolved` mark included. A base of {} is a shard that did not exist at the base.",
+  "tree": [
+    { "name": "atomic: one side's change wins", "strategy": { "kind": "atomic" },
+      "base": 1, "ours": 1, "theirs": 2, "merged": 2, "conflicts": [] },
+    { "name": "atomic: the same change on both sides is no clash", "strategy": { "kind": "atomic" },
+      "base": 1, "ours": 3, "theirs": 3, "merged": 3, "conflicts": [] },
+    { "name": "atomic: two different changes clash and keep ours", "strategy": { "kind": "atomic" },
+      "base": 1, "ours": 2, "theirs": 3, "merged": 2, "conflicts": [{ "path": "", "kind": "both-changed" }] },
+    { "name": "atomic: objects compare by content, not key order", "strategy": { "kind": "atomic" },
+      "base": { "a": 1, "b": 2 }, "ours": { "b": 2, "a": 1 }, "theirs": { "a": 1, "b": 3 }, "merged": { "a": 1, "b": 3 }, "conflicts": [] },
+    { "name": "map: different keys merge", "strategy": { "kind": "map", "of": { "kind": "atomic" } },
+      "base": { "a": 1 }, "ours": { "a": 1, "b": 2 }, "theirs": { "a": 5, "c": 3 }, "merged": { "a": 5, "b": 2, "c": 3 }, "conflicts": [] },
+    { "name": "map: a delete against an edit clashes", "strategy": { "kind": "map", "of": { "kind": "atomic" } },
+      "base": { "a": 1 }, "ours": {}, "theirs": { "a": 2 }, "merged": {}, "conflicts": [{ "path": ".a", "kind": "delete-vs-edit" }] },
+    { "name": "set: additions union, deletions respected", "strategy": { "kind": "set" },
+      "base": ["a", "b"], "ours": ["a", "b", "c"], "theirs": ["b", "d"], "merged": ["b", "c", "d"], "conflicts": [] },
+    { "name": "keyed, sorted: union by key, each item merged", "strategy": { "kind": "keyed", "key": "id", "of": { "kind": "object", "fields": {} } },
+      "base": [{ "id": "b", "n": 1, "m": 1 }],
+      "ours": [{ "id": "c" }, { "id": "b", "n": 2, "m": 1 }],
+      "theirs": [{ "id": "b", "n": 1, "m": 2 }, { "id": "a" }],
+      "merged": [{ "id": "a" }, { "id": "b", "n": 2, "m": 2 }, { "id": "c" }], "conflicts": [] },
+    { "name": "keyed: the same key added twice differently clashes", "strategy": { "kind": "keyed", "key": "id", "of": { "kind": "atomic" } },
+      "base": [], "ours": [{ "id": "a", "n": 1 }], "theirs": [{ "id": "a", "n": 2 }],
+      "merged": [{ "id": "a", "n": 1 }], "conflicts": [{ "path": "[a]", "kind": "added-both" }] },
+    { "name": "keyed: a delete against an edit clashes and keeps ours", "strategy": { "kind": "keyed", "key": "id", "of": { "kind": "atomic" } },
+      "base": [{ "id": "a", "n": 1 }], "ours": [], "theirs": [{ "id": "a", "n": 2 }],
+      "merged": [], "conflicts": [{ "path": "[a]", "kind": "delete-vs-edit" }] },
+    { "name": "keyed, preserved: theirs reordered, ours added; the order is theirs with ours's addition after its neighbour",
+      "strategy": { "kind": "keyed", "key": "id", "order": "preserve", "of": { "kind": "atomic" } },
+      "base": [{ "id": "a" }, { "id": "b" }, { "id": "c" }],
+      "ours": [{ "id": "a" }, { "id": "x" }, { "id": "b" }, { "id": "c" }],
+      "theirs": [{ "id": "c" }, { "id": "a" }, { "id": "b" }],
+      "merged": [{ "id": "c" }, { "id": "a" }, { "id": "x" }, { "id": "b" }], "conflicts": [] },
+    { "name": "keyed, preserved: an addition at the front stays at the front",
+      "strategy": { "kind": "keyed", "key": "id", "order": "preserve", "of": { "kind": "atomic" } },
+      "base": [{ "id": "a" }], "ours": [{ "id": "a" }], "theirs": [{ "id": "z" }, { "id": "a" }],
+      "merged": [{ "id": "z" }, { "id": "a" }], "conflicts": [] },
+    { "name": "keyed, preserved: both reordered differently clashes and keeps ours",
+      "strategy": { "kind": "keyed", "key": "id", "order": "preserve", "of": { "kind": "atomic" } },
+      "base": [{ "id": "a" }, { "id": "b" }, { "id": "c" }],
+      "ours": [{ "id": "b" }, { "id": "a" }, { "id": "c" }],
+      "theirs": [{ "id": "a" }, { "id": "c" }, { "id": "b" }],
+      "merged": [{ "id": "b" }, { "id": "a" }, { "id": "c" }], "conflicts": [{ "path": ":order", "kind": "both-changed" }] },
+    { "name": "object: named keys by their strategy, others atomic", "strategy": { "kind": "object", "fields": { "tags": { "kind": "set" } } },
+      "base": { "tags": ["a"], "n": 1 }, "ours": { "tags": ["a", "b"], "n": 2 }, "theirs": { "tags": ["c"], "n": 1 },
+      "merged": { "n": 2, "tags": ["b", "c"] }, "conflicts": [] },
+    { "name": "object: other keys take `other` when it is given", "strategy": { "kind": "object", "fields": {}, "other": { "kind": "map", "of": { "kind": "atomic" } } },
+      "base": { "k": { "a": 1 } }, "ours": { "k": { "a": 2 } }, "theirs": { "k": { "a": 1, "b": 1 } },
+      "merged": { "k": { "a": 2, "b": 1 } }, "conflicts": [] },
+    { "name": "a value whose shape no longer fits its strategy merges as one value", "strategy": { "kind": "map", "of": { "kind": "atomic" } },
+      "base": { "a": 1 }, "ours": "gone", "theirs": { "a": 2 }, "merged": "gone", "conflicts": [{ "path": "", "kind": "both-changed" }] }
+  ],
+  "manifest": {
+    "schema": "wildwinter/extension@0", "id": "probe", "name": "Probe", "version": "1.0.0",
+    "targets": { "storylets": {
+      "card": { "fields": [
+        { "name": "note", "type": "text" },
+        { "name": "loud", "type": "boolean" },
+        { "name": "marks", "type": "flags", "values": ["a", "b", "c"] },
+        { "name": "cue", "type": "record", "fields": [{ "name": "sound", "type": "text" }, { "name": "gain", "type": "number" }] },
+        { "name": "perf", "type": "map", "key": { "type": "reference", "to": "tag" }, "of": { "type": "record", "fields": [{ "name": "look", "type": "text" }, { "name": "gesture", "type": "text" }] } },
+        { "name": "beats", "type": "list", "id": "id", "of": { "type": "record", "fields": [{ "name": "id", "type": "text" }, { "name": "at", "type": "number" }] } },
+        { "name": "words", "type": "list", "of": { "type": "text" } }
+      ] }
+    } }
+  },
+  "data": [
+    { "name": "different nodes never clash",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" }, "c_2": { "note": "z" } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" }, "c_2": { "note": "z" } } } } },
+    { "name": "different fields of one node merge",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a", "loud": true } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "loud": true, "note": "b" } } } } },
+    { "name": "flags merge value by value",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "marks": ["a"] } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "marks": ["a", "b"] } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "marks": ["c"] } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "marks": ["b", "c"] } } } } },
+    { "name": "a record merges field by field",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "cue": { "sound": "bell", "gain": 1 } } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "cue": { "sound": "gong", "gain": 1 } } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "cue": { "sound": "bell", "gain": 2 } } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "cue": { "gain": 2, "sound": "gong" } } } } } },
+    { "name": "a map merges key by key, then by the value's type: different characters merge, one character's two looks clash",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "perf": { "v_ann": { "look": "down" }, "v_bo": { "look": "up" } } } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "perf": { "v_ann": { "look": "left" }, "v_bo": { "look": "up", "gesture": "shrug" } } } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "perf": { "v_ann": { "look": "right" }, "v_bo": { "look": "away" } } } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "perf": { "v_ann": { "look": "left" }, "v_bo": { "gesture": "shrug", "look": "away" } } } } },
+        "unresolved": [{ "path": "entries.card.c_1.perf.v_ann.look", "kind": "both-changed", "base": "down", "ours": "left", "theirs": "right" }] } },
+    { "name": "a list with ids merges by id and keeps the authored order",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "beats": [{ "id": "b2", "at": 1 }, { "id": "b1", "at": 2 }] } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "beats": [{ "id": "b2", "at": 5 }, { "id": "b1", "at": 2 }] } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "beats": [{ "id": "b2", "at": 1 }, { "id": "b1", "at": 2 }, { "id": "b0", "at": 9 }] } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "beats": [{ "id": "b2", "at": 5 }, { "id": "b1", "at": 2 }, { "id": "b0", "at": 9 }] } } } } },
+    { "name": "a list without ids merges whole",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "words": ["a"] } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "words": ["a", "b"] } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "words": ["c", "a"] } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "words": ["a", "b"] } } },
+        "unresolved": [{ "path": "entries.card.c_1.words", "kind": "both-changed", "base": ["a"], "ours": ["a", "b"], "theirs": ["c", "a"] }] } },
+    { "name": "a node's entry deleted on one side while edited on the other clashes, keeps ours, and the mark holds theirs",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } } },
+      "ours": { "extension": "probe", "entries": { "card": {} } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" } } } },
+      "merged": { "extension": "probe", "entries": { "card": {} },
+        "unresolved": [{ "path": "entries.card.c_1", "kind": "delete-vs-edit", "base": { "note": "a" }, "theirs": { "note": "b" } }] } },
+    { "name": "without the manifest, a node's whole entry merges as one value",
+      "manifest": null,
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" }, "c_2": { "note": "a" } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" }, "c_2": { "note": "a" } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a", "loud": true }, "c_2": { "note": "z" } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" }, "c_2": { "note": "z" } } },
+        "unresolved": [{ "path": "entries.card.c_1", "kind": "both-changed", "base": { "note": "a" }, "ours": { "note": "b" }, "theirs": { "loud": true, "note": "a" } }] } },
+    { "name": "a kind the manifest does not target merges per node as one value",
+      "base": { "extension": "probe", "entries": { "deck": { "k_1": { "x": 1 } } } },
+      "ours": { "extension": "probe", "entries": { "deck": { "k_1": { "x": 2 } } } },
+      "theirs": { "extension": "probe", "entries": { "deck": { "k_1": { "x": 1 }, "k_2": { "x": 3 } } } },
+      "merged": { "extension": "probe", "entries": { "deck": { "k_1": { "x": 2 }, "k_2": { "x": 3 } } } } },
+    { "name": "a shard added on both sides merges two-sided",
+      "base": {},
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } } },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_2": { "note": "b" } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" }, "c_2": { "note": "b" } } } } },
+    { "name": "a mark already on one side is carried until it is resolved",
+      "base": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } } },
+      "ours": { "extension": "probe", "entries": { "card": { "c_1": { "note": "a" } } },
+        "unresolved": [{ "path": "entries.card.c_9.note", "kind": "both-changed", "ours": "x", "theirs": "y" }] },
+      "theirs": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" } } } },
+      "merged": { "extension": "probe", "entries": { "card": { "c_1": { "note": "b" } } },
+        "unresolved": [{ "path": "entries.card.c_9.note", "kind": "both-changed", "ours": "x", "theirs": "y" }] } },
+    { "name": "a mark one side resolved stays resolved",
+      "base": { "extension": "probe", "entries": { "card": {} },
+        "unresolved": [{ "path": "entries.card.c_9.note", "kind": "both-changed", "ours": "x", "theirs": "y" }] },
+      "ours": { "extension": "probe", "entries": { "card": { "c_9": { "note": "x" } } } },
+      "theirs": { "extension": "probe", "entries": { "card": {} },
+        "unresolved": [{ "path": "entries.card.c_9.note", "kind": "both-changed", "ours": "x", "theirs": "y" }] },
+      "merged": { "extension": "probe", "entries": { "card": { "c_9": { "note": "x" } } } } }
+  ],
+  "unresolved": [
+    { "name": "a shard with no mark passes", "shard": { "extension": "probe", "entries": {} }, "problems": [] },
+    { "name": "a shard carrying the mark is refused, once per clash",
+      "shard": { "extension": "probe", "entries": {}, "unresolved": [
+        { "path": "entries.card.c_1.note", "kind": "both-changed", "ours": "a", "theirs": "b" },
+        { "path": "entries.card.c_2", "kind": "delete-vs-edit", "theirs": {} }
+      ] },
+      "problems": [{ "path": "entries.card.c_1.note", "code": "unresolved" }, { "path": "entries.card.c_2", "code": "unresolved" }] },
+    { "name": "an empty mark is still a mark", "shard": { "unresolved": [] }, "problems": [{ "path": "unresolved", "code": "unresolved" }] }
+  ]
+}