@crvouga/atlas 1.14.0 → 1.16.0

package/llms-full.txt

@@ -1850,6 +1850,7 @@ is said in words and the server does not start. The file has a published
 | Whose specs the report is laid over | `outlineBranch` | `--outline-branch <branch>` | `ATLAS_OUTLINE_BRANCH` | `main`, then `master`, then the newest |
 | Only layers recorded on these branches take part | `include.branches` | `--branch <name>` (repeatable) | `ATLAS_ONLY_BRANCH` | all |
 | Leave out layers from modified checkouts and unknown origins | `include.ignoreModified` | `--ignore-modified` | `ATLAS_IGNORE_MODIFIED` | no |
+| Root mappings `from>to` that join spec paths a producer publishes to the paths the specs are recorded under, for the catalog health report (comma-separated; an empty `from` matches every path) | `catalog.roots` |  | `ATLAS_CATALOG_ROOTS` | none |
 | How often (seconds) the backends are looked at for layers written by something else | `refreshSeconds` | `--refresh <seconds>` | `ATLAS_REFRESH_SECONDS` | `10` |
 | Let anyone look, not upload | `auth.anonymousRead` | `--anonymous-read` | `ATLAS_ANONYMOUS_READ` | no |
 | Listen publicly with no tokens (something in front signs people in) | `auth.insecure` | `--insecure` | `ATLAS_INSECURE` | no |
@@ -2090,8 +2091,16 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
   the Tests total. Two spec paths are one logical spec only when a mapping says so
   (`?root=<from>><to>`, for example `?root=%3Especs/` to put `checkout/cart.feature` under `specs/`); similar paths
   are reported as ambiguous and never merged, and a similar title is never an identity. Give a check the label
-  `outline` to say which scenario outline an example belongs to. A domain shared by nearly every spec is flagged, but
-  explicit domain metadata always stays authoritative. The document only reads: it changes no status.
+  `outline` to say which scenario outline an example belongs to, and `behavior-id` / `example-id` to give a behavior
+  or one example a stable id of your own: Atlas counts them and names an id that sits on more than one check (a
+  rename or a move), but a check is still its spec path and id, so nothing is joined by them. A domain shared by nearly
+  every spec is flagged, but explicit domain metadata always stays authoritative. The document only reads: it changes
+  no status.
+- Mappings that should always apply are a setting, not a query parameter: `catalog.roots` in `atlas.server.json` (a list
+  of `from>to`) or `ATLAS_CATALOG_ROOTS` (comma-separated; it replaces the file's list). The health document applies
+  them, then adds the request's `?root=`, and says in `roots[].source` which is which. A mapping with no `>` stops the
+  server starting. The viewer's **Catalog health** tab shows the same document, and its mapping form (the `root`
+  address parameter) tries further mappings without changing the server.
 - The server keeps the newest 100 results of every test (progress reported as `running` is not history) and every run's last result per test, in memory, as layers
   arrive; it is rebuilt from the layers on restart. History never changes a result.
 - Without a published spec set, tests are grouped under the specs their layers recorded (`specs[]`: path, domain,
@@ -3195,7 +3204,7 @@ carry any of these. Every one is optional.
 | `annotations[]` | Notes about the result: a warning, a deprecation, an accessibility finding, a coverage figure. |
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
-| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). |
+| `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. The viewer reads `build`, `platform`, `applies-to` and `applies-to-by` to tell whether evidence applies to a release (see [the viewer conventions](ui.md#behaviors-read-watch-inspect)). `behavior-id` and `example-id` declare a stable id for the behavior and for one example of an outline, and `outline` names the outline; the [catalog health](server.md#reading-the-report-as-an-agent) report counts them and names an id shared by several checks. They never change which check a result belongs to. |
 | `scope{}` | What the evidence does and does not show: surface, device kind, synthetic data, scripted dependencies, audio, pacing, what was asserted and its limits. Unknown when absent. See [Evidence scope](rich-evidence.md#evidence-scope). |
 | `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
@@ -4515,6 +4524,25 @@ when Watch is on screen.
 - The spec index searches titles, paths and declared domains, and can group by the domain from spec metadata (specs with
   none are listed under "No domain declared"; the Tests view reports domain problems).
 
+## Catalog health
+
+The **Catalog health** tab (`explorer/HealthView.tsx`, `?tab=health`; `@crvouga/atlas/reports/catalog-health`) explains why the Specs
+and the Tests disagree. The Specs list links to it ("Why do these counts differ from the Tests?"). On a server it reads
+`GET /api/reports/tests/health`; elsewhere the same document is worked out in the page from the specs and results it holds, and an
+older server without the route is told so in words.
+
+- Denominators are never one number: spec files, defined specs, specs with tests, specs executed and defined but not executed
+  (the coverage gaps, which add to no passed count), tests, outlines, examples and observations (an outline, its examples and
+  their per-environment results are told apart). Each figure has its meaning in its `title`.
+- A table walks from the Specs total to the Tests total, step by step, with the sentences below it. Findings are an `Accordion`
+  (warnings open), each with its severity as text, its code, how many it affects and the paths. Paths that might be one promise
+  are shown as "may be the same promise as ...; not merged": a similar title never joins two specs.
+- Root mappings (`from>to`) join spec paths. Those the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`) are
+  labelled "Configured on the server"; others are tried in the form and kept in the address (`root`), labelled "Tried here", and
+  change nothing on the server. A mapping that matched no path is a warning. Joined specs list every original path.
+- Domains are listed as declared; a domain shared by nearly every spec is a finding, never rewritten. Identity states how many
+  checks are known only by title, how many declare `behavior-id` / `example-id`, and the limits of both.
+
 ## UI catalog
 
 `/catalog` (`catalog/`) is the viewer's inventory of captured UI states ([the guide](ui-catalog.md)). It is computed in the page from
@@ -4562,6 +4590,35 @@ environment) is unknown unless the producer declared it under the `atlas.failure
 wording. Records of one source whose outcome changed are listed oldest first, and a later pass is never called a fix.
 In the explorer the chosen source is the `source` search parameter (a layer id; unlike `layer` it does not pin a run).
 
+## Compare two runs
+
+The **Compare** tab (`explorer/CompareView.tsx`, `explorer/ComparePair.tsx`, `@crvouga/atlas/reports/run-compare`) sets a
+baseline run against a candidate run. Both are pinned in the address (`base` and `cand`, run keys; `change` is the group
+shown and `pair` the behavior opened), so a link reproduces the comparison and a newer run never replaces either. A run
+that is no longer in the report is said to be missing and is never swapped for another. A run's page offers "Compare with
+this run as the baseline / candidate".
+
+- Results are paired by the check they record (spec path and check id), then by the condition they were recorded under
+  (kind, producer, environment, parameters). A title never pairs two results. The same check under another condition is
+  paired and marked "Conditions differ".
+- Every behavior is in one group: newly failing, recovered, still failing, promise or conditions differ, not run or
+  unfinished, not in the candidate run, not in the baseline run, same outcome. A result the candidate did not run is
+  unknown, never regressed or passed; one only the baseline has is "not in the candidate run" (not run, renamed or
+  dropped: the comparison cannot tell). A reworded behavior, or one recorded under different conditions, is not framed as
+  a regression or recovery: both outcomes are shown beside the changed promise. A different spec-file revision with the
+  same wording is disclosed beside the movement (a fingerprint is of the whole file); a revision that was not recorded is
+  unknown, never the same.
+- Opening a behavior shows Mantine `Tabs`: **Promise** (wording, spec revision, recorded steps with the ones only one side
+  has), **Outcomes** (each side's own provenance, execution time and failure), **Recordings** (one `<video>` per side with
+  `preload="metadata"`, read only while that tab is on screen; each keeps its own attempt, spec revision and time
+  origin, they are not synchronized, and "Go to a step in both recordings" seeks each to its own recorded step time when
+  the steps are shared by name and timed; otherwise the page says why they are not aligned) and **Figures**.
+- Figures are compared like for like. Product latency is compared only for the same measurement on the same devices,
+  environments and instrumentation, and reliability only when both sides count at least the minimum of independent
+  executions against the same recorded spec revision (and a difference inside the uncertainty is "cannot be told apart").
+  Otherwise the page says "Not compared" with the reasons and computes no change. Test execution time is labelled as such
+  and is never product latency.
+
 ## Watch a filtered set as a playlist
 
 The Artifacts tab and an opened run have a **Watch these N results** button. It opens a Mantine `Modal` (`explorer/playlist.tsx`)
@@ -4710,7 +4767,7 @@ The narrowly scoped exceptions are:
 | --- | --- | --- |
 | Shared shell | Project switching, spec navigation, run selection, connection status, diagnostics, mobile index | AppShell, Burger, NavLink, Menu, Popover, NativeSelect, Drawer |
 | UI catalog | Captured UI states per profile as cards with coverage badges, filters in the index column, surface coverage, an open state with its profiles side by side and where each picture came from, manifest download | AppShell navbar, SimpleGrid, Card, Image, MultiSelect, TextInput, Drawer, Accordion, Table, Badge, Alert |
-| Project home | Tests/runs/artifacts tabs, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
+| Project home | Tests/runs/artifacts/compare/catalog health tabs, a two-run comparison with promise, outcome, recording and figure tabs per behavior, a run's Artifacts (files of its layers, shared recordings, direct links), Watch playlist of a filtered set, metrics, search, status/environment/domain/artifact-tag filters, run and artifact facets with saved views, grouping, sorting, show more | Container, Tabs, SimpleGrid, Paper, TextInput, MultiSelect, Popover, Button, Accordion, Modal, Grid, Switch |
 | Test detail | Current outcomes, statistics, duration graph, product latency with budgets and baselines, history, artifacts, recording; the `layer` address parameter pins it to one run's result, labelled "This run" against "Latest combined evidence" | Drawer, Table, Badge, Alert, Stage |
 | Specs | All six existing kinds, overview/index with title search and folder or declared-domain grouping, Gherkin rules/scenarios/examples with a coverage summary and Read / Watch / Inspect per behavior, Quint declarations/traces, DMN tables, source text | SpecHeader, Accordion, Tabs, Table, CodeHighlightTabs, ResultRow |
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
@@ -5800,9 +5857,9 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
 
-Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `format` (query): `markdown` for a Markdown report instead of JSON.
 - `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
 
@@ -5816,12 +5873,12 @@ Diagnoses the report's metadata, so a domain filter or a coverage percentage can
 
 `counts` keeps the denominators apart: spec files, defined specs, specs with an executed test (and those without: the defined coverage gaps), tests, outlines, examples and per-environment observations. `reconciliation` walks from the Specs count to the Tests count. `findings` name ambiguous and unmatched spec paths, identical or same-titled specs, a domain shared by nearly every spec, tests with no spec, checks that fall back to their title as identity and root mappings that matched nothing.
 
-Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to. Send `format=markdown` for Markdown.
+Two paths are one logical spec only when a `root` mapping relates them (`from>to`: paths under `from` are the same specs as paths under `to`; an empty `from` matches every path). Without one, similar paths are reported as ambiguous and never merged. A check's label `outline` names the outline its example belongs to; the labels `behavior-id` and `example-id` declare stable ids, which are counted and checked for ids shared by several checks. Send `format=markdown` for Markdown.
 
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
 
 - `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
-- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated.
+- `root` (query): A root mapping `from>to`, URL-encoded. Repeatable or comma-separated. It is added to the mappings the server is configured with (`catalog.roots`, `ATLAS_CATALOG_ROOTS`); `roots[].source` says which is which.
 - `format` (query): `markdown` for a Markdown report instead of JSON.
 
 Responses: `200` The diagnostics.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/catalog-health.schema.json

@@ -229,6 +229,18 @@
           "maximum": 9007199254740991,
           "description": "Checks whose id equals their title"
         },
+        "declaredBehaviorIds": {
+          "description": "Checks that declare a `behavior-id` label",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "declaredExampleIds": {
+          "description": "Checks that declare an `example-id` label",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
         "basis": {
           "type": "string"
         }
@@ -278,6 +290,14 @@
             "minimum": 0,
             "maximum": 9007199254740991,
             "description": "Distinct paths the mapping changed"
+          },
+          "source": {
+            "description": "Where it was declared: the server's `catalog.roots` setting or this request's `root` parameter",
+            "type": "string",
+            "enum": [
+              "configuration",
+              "request"
+            ]
           }
         },
         "required": [

package/packages/schema/schemas/effective-delta.schema.json

@@ -262,7 +262,7 @@
                           },
                           "available": {
                             "type": "boolean",
-                            "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                            "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
                           "scope": {
                             "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
@@ -741,7 +741,7 @@
                         },
                         "available": {
                           "type": "boolean",
-                          "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                          "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
                         "scope": {
                           "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/effective-evidence.schema.json

@@ -262,7 +262,7 @@
                           },
                           "available": {
                             "type": "boolean",
-                            "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                            "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
                           "scope": {
                             "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
@@ -741,7 +741,7 @@
                         },
                         "available": {
                           "type": "boolean",
-                          "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                          "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
                         "scope": {
                           "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/evidence-page.schema.json

@@ -249,7 +249,7 @@
                     },
                     "available": {
                       "type": "boolean",
-                      "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                      "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/layer-rows.schema.json

@@ -253,7 +253,7 @@
                     },
                     "available": {
                       "type": "boolean",
-                      "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                      "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/report-run.schema.json

@@ -161,7 +161,7 @@
               "type": "integer",
               "minimum": 0,
               "maximum": 9007199254740991,
-              "description": "References that name no bytes"
+              "description": "References that name no bytes, or bytes the layer does not hold"
             }
           },
           "required": [
@@ -314,7 +314,7 @@
                 },
                 "available": {
                   "type": "boolean",
-                  "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                  "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                 },
                 "scope": {
                   "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
@@ -420,6 +420,28 @@
               ],
               "additionalProperties": {}
             }
+          },
+          "kind": {
+            "description": "The kind of the part that held it. With the producer, environment and parameters it is the condition the result was recorded under. Absent from an older server",
+            "type": "string"
+          },
+          "parameters": {
+            "description": "The other choices that made it its own result (a device size, a locale…). Absent when there are none, and from an older server",
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "specRevision": {
+            "description": "The fingerprint of its spec file the layer recorded. Absent means not recorded, never \"the same\"",
+            "type": "string"
+          },
+          "recordedTitle": {
+            "description": "The title this run's layer gave the check. `title` is the check's newest title in the whole history; this is the wording as recorded. Absent from an older server",
+            "type": "string"
           }
         },
         "required": [
@@ -494,7 +516,7 @@
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 9007199254740991,
-                "description": "References that name no bytes"
+                "description": "References that name no bytes, or bytes the layer does not hold"
               }
             },
             "required": [

package/packages/schema/schemas/report-runs.schema.json

@@ -169,7 +169,7 @@
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 9007199254740991,
-                "description": "References that name no bytes"
+                "description": "References that name no bytes, or bytes the layer does not hold"
               }
             },
             "required": [

package/packages/schema/schemas/review-collection.schema.json

@@ -194,7 +194,7 @@
                     },
                     "available": {
                       "type": "boolean",
-                      "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                      "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/review-manifest.schema.json

@@ -219,7 +219,7 @@
                     },
                     "available": {
                       "type": "boolean",
-                      "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                      "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/server-config.schema.json

@@ -102,6 +102,23 @@
       },
       "additionalProperties": false
     },
+    "catalog": {
+      "default": {
+        "roots": []
+      },
+      "type": "object",
+      "properties": {
+        "roots": {
+          "default": [],
+          "description": "Root mappings `from>to` that relate spec paths a producer publishes to the paths the specs are recorded under (an empty `from` matches every path). The catalog health report applies them to every request, beside any `root` the request adds",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "refreshSeconds": {
       "default": 10,
       "description": "How often the backends are looked at for layers written by something other than this server",

package/packages/schema/schemas/test-catalog.schema.json

@@ -975,7 +975,7 @@
                           },
                           "available": {
                             "type": "boolean",
-                            "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                            "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                           },
                           "scope": {
                             "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",

package/packages/schema/schemas/test-history.schema.json

@@ -273,7 +273,7 @@
                         },
                         "available": {
                           "type": "boolean",
-                          "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                          "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                         },
                         "scope": {
                           "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",
@@ -926,7 +926,7 @@
                     },
                     "available": {
                       "type": "boolean",
-                      "description": "False when the reference names no bytes (no bundle key, address or inline text)"
+                      "description": "False when the reference names no bytes: no bundle key, address or inline text, or a bundle key that the layer's own bundle does not hold"
                     },
                     "scope": {
                       "description": "What this recording shows as its producer declared it: its own `scope`, else its attempt's, check's, part's or layer's. Absent: the scope is unknown, never live, physical or audible",