iOS conforms on duplicate metadata; validators learn the at-most-once rule

The iOS development branch now tolerates duplicated root metadata with
last-wins semantics (efff512c), scoped to the six metadata children -
every implementation agrees, so the duplicate-root-elements entry is
deleted per the mechanism, and the duplicate-metadata-last-wins rule's
state records the fix.

The constraint itself becomes checkable: the grammar cannot express
at-most-once (root children are folded into a repeated choice for
libxml2), so the Schematron gains the root-metadata-once pattern and
validate_experiments a check_root_once pass, both flagging a duplicated
title, state-title, category, icon, color or description. A new corpus
fixture (invalid/state-title-duplicate.phyphox, parser: accepts) pins
both sides: validators flag it, the app suites assert it loads.

Also document the unattended-launch seam next to phyphox://asset=: iOS
takes -phyphoxUrl as a launch argument (simctl/devicectl) because the
openurl confirmation dialog cannot be suppressed; Android deliberately
has no counterpart - adb shell am start is dialog-free. Recorded so
nobody goes looking for the missing half.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Staacks

corpus/README.md

@@ -19,11 +19,13 @@ format surface that the shipped experiments alone never touch.
   `gcd`/`lcm`, `butterworth`, the `events` block of saved states, `appleBan`,
   and a set of rarely used view, network and I/O attributes. Each file states
   its purpose in a comment.
-- `invalid/` — real files carrying a documented defect each: dead draft
-  syntax that never shipped (`mode="trigger"` on a network connection, the
-  pre-BLE Bluetooth syntax, the 2018 device-specific conversion draft,
-  dev-era camera attributes, `precisionX`), typos (`cycle=` for `cycles=`,
-  `site=` for `size=`), and attributes applied to the wrong element.
+- `invalid/` — files carrying a documented defect each, nearly all
+  collected from real use: dead draft syntax that never shipped
+  (`mode="trigger"` on a network connection, the pre-BLE Bluetooth syntax,
+  the 2018 device-specific conversion draft, dev-era camera attributes,
+  `precisionX`), typos (`cycle=` for `cycles=`, `site=` for `size=`),
+  attributes applied to the wrong element, and a duplicated `state-title`
+  in the shape old Android re-saves wrote.
   `expected.yml` records the findings each file must produce and what the
   app parsers do with it (`parser: rejects|accepts` — see its header);
   names are flattened to the defect, so file names carry no trace of where
@@ -76,8 +78,9 @@ Both apps run this corpus in their own test suites (test-matrix rows
   do splits per the unknown-attribute-ignored rule, recorded as `parser:`
   in `expected.yml`: files marked `rejects` must fail to load (any error;
   message texts are platform wording and never asserted), files marked
-  `accepts` must LOAD — their only defects are unknown or misapplied
-  attributes, which the parsers ignore for compatibility, and that
+  `accepts` must LOAD — their defects are tolerated for compatibility:
+  unknown or misapplied attributes (which the parsers ignore) or
+  duplicated root metadata (where the last occurrence wins), and that
   tolerance is itself contract worth pinning. The classification was
   measured on the Android development branch (2026-08-24); an app runner
   disagreeing with it is a finding to report, not to code around.

corpus/invalid/expected.yml

@@ -16,10 +16,12 @@
 #               rejects - the real loading path refuses the file (structural
 #                         defects, invalid enum values, unknown conversion
 #                         functions, the graph pairing rules)
-#               accepts - the file LOADS: its only defects are unknown or
-#                         misapplied attributes, which parsers ignore for
-#                         compatibility. The app suites assert the load
-#                         succeeds - that tolerance is itself contract.
+#               accepts - the file LOADS: its defects are tolerated for
+#                         compatibility - unknown or misapplied attributes
+#                         (unknown-attribute-ignored) or duplicated root
+#                         metadata (duplicate-metadata-last-wins). The app
+#                         suites assert the load succeeds - that tolerance
+#                         is itself contract.
 #             Classification measured on the Android development branch
 #             2026-08-24 (corpus runner); iOS confirms with its own runner
 #             and any disagreement is a finding to report, not to paper over.
@@ -106,6 +108,12 @@ analysis-optimization.phyphox:       # stale attribute no parser ever read
   parser: accepts
   findings:
     - '<analysis>: optimization='
+state-title-duplicate.phyphox:       # old Android re-saves appended a fresh
+  parser: accepts                     # state-title instead of replacing it;
+  findings:                           # parsers tolerate the duplicate, last
+    - 'state-title appears 2 times'   # occurrence wins (rule
+                                      # duplicate-metadata-last-wins,
+                                      # decided 2026-08-24)
 graph-unused-x.phyphox:              # x inputs no y input uses (decided 2026-08-20)
   parser: rejects
   findings:

corpus/invalid/state-title-duplicate.phyphox

@@ -0,0 +1,26 @@
+<phyphox xmlns="http://phyphox.org/xml" version="1.5" locale="en">
+    <title>Pendulum</title>
+    <state-title>Measurement 1/23/18 21:13</state-title>
+    <state-title>Pendulum on the swing</state-title>
+    <category>Saved states</category>
+    <description>
+        A saved state whose re-save appended a second state-title instead of
+        replacing the first, the shape old Android versions wrote (and the
+        current writer can still produce, see the live-NodeList removal skip
+        in PhyphoxExperiment.java). Parsers tolerate the duplicate and the
+        last occurrence wins (rule duplicate-metadata-last-wins); writing
+        one remains an error, which is what the validators flag here.
+    </description>
+    <data-containers>
+        <container size="0">t</container>
+        <container size="0">x</container>
+    </data-containers>
+    <views>
+        <view label="Data">
+            <graph label="x(t)" labelX="t" labelY="x">
+                <input axis="x">t</input>
+                <input axis="y">x</input>
+            </graph>
+        </view>
+    </views>
+</phyphox>

docs/file-format/index.md

@@ -35,8 +35,6 @@ The title of the experiment. This is just a simple string. Try to keep it short
 
 This should not be used for an experiment which will be distributed. This tag contains the title given by the user when saving the state of an experiment. If this is set, the app will show this experiment in the saved-states section. A file may carry at most one `state-title` — like the other metadata tags of the root element, it must not be repeated. If a legacy file nevertheless carries a duplicate (old versions of the app could write one when re-saving a state), the app tolerates it and the last occurrence wins.
 
-{{inconsistency:duplicate-root-elements}}
-
 {{spec:root/phyphox/state-title}}
 
 ### Tag: category

docs/transferring-experiments.md

@@ -45,6 +45,18 @@ phyphox://asset=bluetooth%2Fphyphox_m_bmp581.phyphox
 
 This is meant for links in worksheets, documentation and classroom materials that should land the user directly in the right bundled experiment, and it is what automated testing uses to drive the app. It is deliberately limited to the bundled collection: experiment titles are not unique, and files elsewhere on the device keep going through the regular file-opening routes. An unknown path shows the app's normal "could not load" message.
 
+#### Launching from automation
+
+Scripted testing needs to open such a URL without anyone tapping a dialog, and the two platforms get there differently — deliberately, so do not look for the missing half:
+
+- **Android needs no special mechanism.** `adb shell am start -a android.intent.action.VIEW -d "phyphox://asset=accelerometer.phyphox"` delivers the URL to the app without any confirmation dialog.
+- **iOS confirms opening a URL from `simctl openurl` with a system dialog that cannot be suppressed**, so the app instead accepts the URL as a launch argument: `-phyphoxUrl <url>` behaves exactly as if the URL had been opened from outside the app, and goes through the same handler, so the semantics cannot drift (AppDelegate.swift).
+
+```
+xcrun simctl launch <udid> de.rwth-aachen.physics.phyphox -phyphoxUrl "phyphox://asset=accelerometer.phyphox"
+xcrun devicectl device process launch --device <udid> de.rwth-aachen.physics.phyphox -phyphoxUrl "phyphox://asset=accelerometer.phyphox"
+```
+
 ### Online QR-Codes (recommended)
 
 If your audience has internet access, this is the recommended method and the QR code can be created directly from our editor. This method is very similar to the phyphox:// URL, but the URL is encoded into a QR code, which can simply be scanned from the phyphox main menu. If you want to or need to create the QR code yourself, simply create a QR-Code that contains a link starting with phyphox://, <http://> or <https://> and phyphox should simply download the experiment after scanning the QR code.

inconsistencies.yml

@@ -89,44 +89,3 @@
     A non-power-of-two number of input samples yields a different output
     length and different values on the two platforms; a power-of-two input
     gives identical results on both.
-
-- id: duplicate-root-elements
-  title: Duplicated metadata elements in a saved state
-  area: file-format
-  status: decided
-  canonical: >-
-    Tolerated, last occurrence wins (rule duplicate-metadata-last-wins in
-    spec/rules.yml, decided 2026-08-24): a repeated metadata child of the
-    root element does not reject the file, and the last occurrence is
-    used. Android's behavior is canonical; iOS's rejection is the bug.
-    Writers must still emit exactly one - the tolerance exists for legacy
-    saved states, not for new files.
-  affects:
-    android: >-
-      Last occurrence wins: the parser overwrites the previously read value
-      for each repeated metadata child (PhyphoxFile.java,
-      phyphoxBlockParser, e.g. case "state-title" assigns
-      experiment.stateTitle unconditionally), so a file with two
-      state-title elements loads and shows the second.
-    ios: >-
-      Rejects the file: every single-slot child handler throws
-      ElementHandlerError.duplicateElement on a second occurrence
-      (Serialization/ElementHandler.swift infrastructure, reached via
-      PhyphoxElementHandler's stateTitleHandler and the other metadata
-      handlers).
-  verified: >-
-    iOS behavior observed 2026-08-24 by the corpus runner
-    (CorpusConformanceTests, commit f393ae8c) on the original
-    taipei101_down fixture; Android's runner loaded the same file the same
-    day.
-  summary: >-
-    The format allows each metadata child of the root element - state-title,
-    title, category and the like - at most once (ruled 2026-08-24), but
-    files with a duplicated state-title exist in the wild: old Android
-    versions appended a new state-title on re-saving a state without
-    removing the previous one, and the current Android save path can still
-    leave a stale element behind (live-NodeList removal skip in
-    PhyphoxExperiment.java). Android loads such files, last occurrence
-    winning; iOS refuses them, so a legacy recording can be unreadable on
-    iOS only - the compatibility break the last-wins ruling exists to
-    prevent.

spec/rules.yml

@@ -338,19 +338,21 @@ rules:
         that produces the duplicates is a separate fix (handed off
         2026-08-24).
       ios: >-
-        Does not conform: every single-slot child handler throws
-        ElementHandlerError.duplicateElement on a second occurrence
-        (Serialization/ElementHandler.swift infrastructure), rejecting the
-        file. Recorded as duplicate-root-elements in inconsistencies.yml
-        until fixed.
+        Conforms as of the development branch (efff512c, 2026-08-24): the
+        six root metadata handlers read lastResult() instead of
+        expectOptionalResult() (DocumentParser+Extensions.swift,
+        PhyphoxElementHandler.swift), scoped so that a duplicate of any
+        other element stays an ElementHandlerError.duplicateElement, with
+        tests pinning both directions.
     check: >-
-      The published validators cannot flag a duplicate today: the grammar
-      deliberately folds the root's children into a repeated choice
-      ((a | b | ...)*) to sidestep libxml2's interleave blowup, and neither
-      the Schematron nor validate_experiments checks cardinality yet. A
-      corpus fixture pinning last-wins should follow once one of them does
-      - and once iOS conforms, so its runner can assert the load rather
-      than record a divergence.
+      The grammar cannot express the at-most-once constraint (the root's
+      children are deliberately folded into a repeated choice to sidestep
+      libxml2's interleave blowup), so the Schematron carries it (pattern
+      root-metadata-once) and validate_experiments checks it
+      (check_root_once). The corpus fixture
+      invalid/state-title-duplicate.phyphox pins both sides: the
+      validators flag it, the app suites assert it loads
+      (parser: accepts).
     applies_to: every element name in the format
     state:
       android: >-

test-matrix.yml

@@ -60,11 +60,11 @@ tests:
     status: active
     description: >-
       Every corpus/invalid file whose expected.yml entry says
-      `parser: accepts` LOADS successfully: its only defects are unknown or
-      misapplied attributes, which the parsers ignore per the
-      unknown-attribute-ignored rule (spec/rules.yml). This pins the
+      `parser: accepts` LOADS successfully: its defects are tolerated for
+      compatibility per the unknown-attribute-ignored and
+      duplicate-metadata-last-wins rules (spec/rules.yml). This pins the
       compatibility guarantee - a parser that starts rejecting unknown
-      attributes breaks files in the wild.
+      attributes or legacy duplicates breaks files in the wild.
 
   - id: corpus-version-gate
     area: file-format

tools/generate_validators.py

@@ -657,6 +657,21 @@ def assert_(r, test, text, warning=False):
                "normalize-space(current())]) = 1",
             "Data container names must be unique.")
 
+    # --- root metadata appears at most once ------------------------------
+    # The grammar cannot express this: the root's children are deliberately
+    # folded into one repeated choice to sidestep libxml2's interleave
+    # blowup. Rule duplicate-metadata-last-wins (spec/rules.yml): apps
+    # tolerate a legacy duplicate - the last occurrence wins - but nothing
+    # may write one, so a duplicate is an authoring error.
+    p = pattern("root-metadata-once")
+    for name in ("title", "state-title", "category", "icon", "color",
+                 "description"):
+        r = rule(p, f"/{ln('phyphox')}/{ln(name)}")
+        assert_(r, f"count(../{ln(name)}) = 1",
+                f"The {name} element may appear at most once; apps "
+                "tolerate a legacy duplicate (the last occurrence wins) "
+                "but nothing may write one.")
+
     # --- graph dataset pairing (decided and amended 2026-08-20) ----------
     p = pattern("graph-dataset-pairing")
     ax = lambda v: ("translate(@axis,'ABCDEFGHIJKLMNOPQRSTUVWXYZ',"

tools/hooks.py

@@ -424,6 +424,7 @@ def _check_corpus():
         # unknown camera component can never be matched here (gap found
         # 2026-08-24 when exactly that expectation failed)
         ve.check_slots(root, slots, components, rep, n)
+        ve.check_root_once(root, rep, n)
         details = [f"{kind}: {d}" for kind, lst in rep.items.items()
                    for _, d in lst]
         if not details: