@gmb/bitmark-parser 7.2.0 → 7.3.0

package/README.md

@@ -69,9 +69,9 @@ runtime — the API surface never changes:
 
 | Feature                          | Contents                                                                                                                                                                                               | Size (approx.)         |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
-| `full` (Node default)            | everything: rich `info` metadata + built-in translations + the semantic `diff`                                                                                                                         | ~1025 KB (~395 KB gzip) |
-| `browser-full` (browser default) | the same conversions and `diff`, without either                                                                                                                                                        | ~818 KB (~333 KB gzip) |
-| `bitmark-json`                   | bitmark ↔ JSON only: `convert`/`canonicalize`/`transform` (formats `auto`/`bitmark`/`json`, plus the `text`, `semantic-tokens` and `diagnostics` outputs), the editor services, `info` (JSON only), breakscape, text fragments — no `diff` | ~599 KB (~239 KB gzip) |
+| `full` (Node default)            | everything: rich `info` metadata + built-in translations + the semantic `diff`                                                                                                                         | ~1044 KB (~410 KB gzip) |
+| `browser-full` (browser default) | the same conversions and `diff`, without either                                                                                                                                                        | ~855 KB (~353 KB gzip) |
+| `bitmark-json`                   | bitmark ↔ JSON only: `convert`/`canonicalize`/`transform` (formats `auto`/`bitmark`/`json`, plus the `text`, `semantic-tokens` and `diagnostics` outputs), the editor services, `info` (JSON only), breakscape, text fragments — no `diff` | ~629 KB (~256 KB gzip) |
 
 **The rule.** _Every build includes every feature, except the two
 browser-targeted variants, which each carry an explicit exclusion list._ That
@@ -82,7 +82,7 @@ below:
 | -------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | native CLI, daemon, docgen, schemagen, wasm `full` | **all**                                                                             |
 | wasm `browser-full`                                | all **except** `info-meta` (bit + tag prose) and `translations` (the baked table)   |
-| wasm `bitmark-json`                                | all **except** the above and `markup`, `mapping-report`, `diff`, `lex`, `info-text` |
+| wasm `bitmark-json`                                | all **except** the above and `markup`, `mapping-report`, `diff`, `lex` (with `ast`), `info-text` |
 
 So, not in `bitmark-json`: the markup formats (`html`, `xml`,
 `xml-niso-iec`, …) as input or output (they throw an `unsupported` error), the
@@ -192,9 +192,10 @@ Convert between bitmark, JSON, and the mapped markup formats (html/xml/…).
 
 A JSON input may be an array or a single value, each entry a `{ bit: {…} }`
 envelope (the forward output) or a bare bit object. An entry that is not a
-bit produces no bitmark: it is skipped and reported as an `unknown-bit-type`
-issue naming its JSON path (`$[2] is not a bit: no "type" — skipped`) on the
-warnings channel of the CLI (`--warnings`) and the daemon; the bits beside it
+bit produces no bitmark: it is skipped and reported as a `bit-invalid` issue
+(or `bit-type-invalid` when it has a `type` the registry does not know) naming
+its JSON path (`$[2] is not a bit: expected a bit object with "type" —
+ignored`) on the warnings channel of the CLI (`--warnings`) and the daemon; the bits beside it
 still convert, and a document in which nothing is a bit converts to empty
 output. This `convert` returns a bare string and so cannot show the skip.
 Only malformed JSON *text* throws (`invalid-json`).
@@ -202,7 +203,7 @@ Only malformed JSON *text* throws (`invalid-json`).
 Options:
 
 - `inputFormat` — `"auto"` (default), `"bitmark"`, `"json"`, or a mapping id (`"html"`, `"xml"`, …)
-- `outputFormat` — `"auto"` (default: the opposite direction), `"text"` (lossy plain-text extraction; output-only), `"semantic-tokens"` / `"diagnostics"` / `"lex"` (output-only, bitmark input only — see their sections), or as above
+- `outputFormat` — `"auto"` (default: the opposite direction), `"text"` (lossy plain-text extraction; output-only), `"semantic-tokens"` / `"diagnostics"` / `"lex"` / `"ast"` (output-only, bitmark input only — see their sections), or as above
 - `mode` — `"optimized"` (default) or `"full"`
 - `warnings` — include validation warnings (default: `false`)
 - `plainText` — output text as plain text (default: `false`)
@@ -255,7 +256,7 @@ Options:
 For bitmark input, output is a JSON array of entries with:
 
 - `bit` — serialized bit payload
-- `parser` — parser metadata, `errors` / `warnings`, and `infos` (informational notices for recoveries that are not necessarily wrong: text kept as text because it only looks like an unclosed tag, `unclosed-tag`, or a formatting mark with no partner, `unclosed-formatting` — in bitmark malformed markup is text, not an error). Each issue carries a stable machine-readable `code` (`"unknown-property"`, `"missing-required-tag"`, …) beside its human-readable `message`, plus `text` and `location`. **Branch on `code`** — a shipped code never changes meaning, whereas the message text is not contractual and may be reworded in any release
+- `parser` — parser metadata, `errors` / `warnings`, and `infos` (informational notices for recoveries that are not necessarily wrong: text kept as text because it only looks like an unclosed tag, `tag-unclosed`, or a formatting mark with no partner, `formatting-unclosed` — in bitmark malformed markup is text, not an error). Each issue carries a stable machine-readable `code` (`"tag-invalid"`, `"tag-missing"`, …) and a `scope` (`"bit"`, `"card"`, `"bit-chain"` or `"card-chain"` — where the issue sits) beside its human-readable `message`, plus `text` and `location`. **Branch on `code` and `scope`** — a shipped code never changes meaning, whereas the message text is not contractual and may be reworded in any release. `bitmark info error-codes` lists every code with its severity and message template (see `info` below)
 - `bitmark` — source bitmark text (a convenience echo; every bit is fully described by `bit` alone)
 
 A region the parser could not read — an unknown bit type, or non-blank text
@@ -266,6 +267,17 @@ commented-out bit and any `:format` / `&resource` suffix; absent when there
 was no header) and `body` (the raw text after it, as a plain string), so
 generating bitmark from it reproduces the original region.
 
+The other direction reports too. Going **to** bitmark (from JSON or from
+markup), an inline mark that has no bitmark form is dropped — the forward
+parser would not read it back as that mark, so writing it would corrupt the
+surrounding text. The text it decorated is always kept, and the loss is
+reported: `mark-dropped` when the whole mark goes, `mark-reduced` when it
+survives in a lesser form (its value cleared, or one of its segments dropped).
+Both arrive on the conversion's warnings, like every other issue. In practice
+they are rare — a `href` holding a line terminator, a mark kind the grammar has
+no tag for — so treat either as a signal that the JSON holds something bitmark
+cannot express, not as routine noise.
+
 #### canonicalize(input: string, options?: CanonicalizeOptions): string
 
 Re-emit input in its own format in canonical form — the single same-format surface. `mode`: `"optimized"` (default, omit natural defaults) or `"full"` (all keys).
@@ -277,7 +289,17 @@ Apply a patch document to a document, bit by bit, and re-emit it.
 
 - `patch` — a `PatchDocument`, or the shorthand: a bare array of entries
   applied to every bit (build entries with `patchEntry`). Either form may be
-  a JSON string
+  a JSON string. An entry's `path` is in one of two languages, told apart by
+  its first character (one language per call; a mixed call is refused):
+  - a **JSON path** addresses the bit JSON (`title`,
+    `quizzes[0].choices[1].choice`, `table.data[1][1]`, `id[-1]`) and the
+    value is a JSON value;
+  - a **bitmark path** addresses the bit as an author writes it and the value
+    is bitmark source (see *Bitmark paths* below). Bitmark paths need
+    bitmark input
+- a skipped entry — a bad path, an index out of range, a value the engine
+  refuses — **throws `PatchError`** (`diagnostics: { path, kind, message }[]`)
+  rather than returning a document with the edit silently missing
 - `preHook` / `postHook` — per-bit hooks; the pre-hook may return patches, an
   output-format override or `drop`. Hooks see the original bits, in order,
   before the document reshapes anything; a hook's patches apply after the
@@ -286,13 +308,14 @@ Apply a patch document to a document, bit by bit, and re-emit it.
   `spacesAroundValues` — as for `convert`. `outputFormat` (default `"json"`)
   takes every per-bit format: `"json"`, `"bitmark"`, `"text"` or a mapping id
   such as `"html"` (per-bit text outputs are joined with newlines). The
-  whole-document outputs `"lex"`, `"semantic-tokens"` and `"diagnostics"` are
-  refused with an `unsupported` error in every driver — use `convert`. An
-  explicit `inputFormat` is honoured as given, patch or hooks or not; it is
-  never re-detected from the content
+  whole-document outputs `"lex"`, `"ast"`, `"semantic-tokens"` and
+  `"diagnostics"` are refused with an `unsupported` error in every driver —
+  use `convert`. An explicit `inputFormat` is honoured as given, patch or
+  hooks or not; it is never re-detected from the content
 
 A patch document addresses bits by their position (or id) in the input
-**before** any entry is applied, so it reads like a diff:
+**before** any entry is applied, so it reads like a diff. An inserted `bit`
+is a JSON bit, or a string holding one bit of bitmark source:
 
 ```json
 {
@@ -319,6 +342,53 @@ or `-1` for the document start. A bit may be the target of at most one
 and moving it are all rejected, naming the second of the conflicting entries.
 `diff` produces such a document from two versions of a file (below).
 
+#### Bitmark paths
+
+A bitmark path spells the thing it names the way an author writes it, so the
+same path works for every bit type and no JSON key name is needed:
+
+| Path | Addresses |
+| --- | --- |
+| `[@id]`, `[!]`, `[#]`, `[&image]` | the bit's first such tag; `[@id][-1]` the last, `[-][1]` the second `[-…]` |
+| `[&image][@width]` | `[@width]` in the run after `[&image]` — a chain is spelled like the chain |
+| `$body` | the bit's own text (tags, cards and footer untouched) |
+| `$raw` | everything after the bit header |
+| `$card[1]` | the whole second card; `$card[1][0]` its first side, `$card[1][0][1]` a variant |
+| `$card[1][!]`, `$card[1][-][1]` | tags inside a card, by occurrence |
+| `$card[1]$body`, `$card[1]$raw` | a card's own text / whole content |
+| `$footer` | the `==== footer ====` section |
+
+Values are bitmark source, breakscaped as an author would write it (a bare
+`]` or a trailing `^` in a tag value is refused — use `breakscapeText` with
+`location: "tag"` for user data, and add `subLocation: "attrValue"` when the
+value is an inline-attr chain value such as a `link:` href); `null` is a
+valueless tag (`[@x]`). The
+four ops are the JSON engine's: `set` replaces a tag's value, a section's
+content or a scope's text; `create` sets only when absent; `delete` removes
+a tag (**a run head takes its whole run** — `[&image:u][@width:1]` minus
+`[&image]` leaves nothing behind), a section, a body; `append` adds another
+occurrence after the last one on its own line (`$card[1][-]` twice gives
+white, green, blue, red), a sibling section after `$card[c]`, or a new last
+card for a bare `$card`.
+
+Every edit is a splice of the bit's own source: the parser's tree is the
+address map, the rest of the bit keeps its formatting, and an edit that
+would change the structure outside the addressed scope — a `==== text ====`
+or `==== footer ====` that would swallow the cards after it, a bit header in
+a value — is refused with the bit untouched. `convert(…, { outputFormat:
+"ast" })` shows the tree a path resolves against.
+
+```js
+transform(doc, {
+  outputFormat: "bitmark",
+  patch: [
+    { path: "$card[1][-]", op: "append", value: "green" },
+    { path: "$card[0][!]", op: "set", value: "Milk (cold)" },
+    { path: "$body", op: "set", value: "Think **twice**." },
+  ],
+});
+```
+
 #### diff(a: string, b: string, options?: DiffOptions): string
 
 Semantic diff of two documents. Both sides are re-canonicalized and
@@ -458,10 +528,10 @@ const { positionEncoding, diagnostics: list } = diagnostics(source);
 // list[i] = {
 //   range: { start: { line, character }, end: { line, character } },  // 0-based, UTF-16 units
 //   severity: 2,                        // DiagnosticSeverity.Warning
-//   code: "unknown-property",           // the contract — branch on this
+//   code: "tag-invalid",                // the contract — branch on this
 //   source: "bitmark",
-//   message: "[@nope] is an unknown property …",   // prose, may change
-//   data: { bit: 0 },                   // the bit's index in the JSON array
+//   message: "[@nope] is not valid for [.article]",   // prose, may change
+//   data: { bit: 0, scope: "bit" },     // the bit's index in the JSON array; the issue's scope
 // }
 ```
 
@@ -552,7 +622,7 @@ offers the bit types). The CLI has the same three services under one
 command: `bitmark editor diagnostics|complete|resolve|hover`. The contract is
 `.zen/specs/API-EDT-editor-services.tsp`.
 
-#### The `lex` output format
+#### The `lex` and `ast` output formats
 
 `convert(input, { inputFormat: "bitmark", outputFormat: "lex" })` returns the
 lexer's token stream as a JSON array: one `{ kind, span, text }` per token
@@ -563,19 +633,59 @@ so a highlighter should use `semantic-tokens` instead. Bitmark input only; a
 JSON or markup document has no source text to lex. The former `lex()` export
 and `bitmark lex` command were removed in 7.0 (see the migration guide).
 
+`convert(input, { inputFormat: "bitmark", outputFormat: "ast" })` returns the
+parser's tree as JSON — bits, their blocks (tag runs, body text, dividers)
+and inlines, every node with its byte `span`. Debug tooling like `lex`: the
+shape follows the parser and is not a contract. It shows what a bitmark
+patch path addresses (a run is one `TagChain`; a card is what sits between
+divider blocks). Not to be confused with the legacy entry point's "ast",
+which is bit JSON. Bitmark input only; in the same builds as `lex`.
+
 #### breakscapeText(input: string, options?: BreakscapeOptions): string
 
 Breakscape text (escape bitmark special characters).
 
 - `format` — `"bitmark++"` (default) or `"plainText"`
-- `location` — `"body"` (default) or `"tag"`
+- `location` — `"body"` (default), `"cardBody"` or `"tag"`
+- `subLocation` — `"text"` (default) or `"attrValue"`
+
+`subLocation` REFINES `location`, it does not replace it. `"attrValue"` means
+the string is the value half of an inline-attr chain segment
+(`==t==|link:VALUE|`): it adds the chain delimiter `|` to the escaped set and
+drops the running-text rules (inline doubles, block markers), while `location`
+keeps deciding the tag rules — a `[`+trigger is escaped in `body` and inert in
+`tag`, a `]` is inert in `body` and escaped in `tag`.
+
+`"cardBody"` is a card side or variant body. It has the `body` rules plus the
+card dividers `--` and `++`, which are markup only inside a card set and only
+at the start of a line, where they break to `-^-` and `+^+`.
+
+Reach for `subLocation: "attrValue"` when building a chain value for the patch
+API by hand; without it, an href containing `[@` cannot be written correctly.
+
+```ts
+breakscapeText("http://x/a[@b]", { location: "body", subLocation: "attrValue" });
+// → "http://x/a[^@b]"
+```
+
+Carets themselves follow one rule: **a literal `^` is written `^^` except with
+`format: "plainText"` and `location: "body"`, where it is written `^`.** Three
+cases land on the `^^` side although they read as though they would not — a tag
+value in a plain-format bit (the `:text` suffix switches the body only), an
+inline `code` mark (ordinary bitmark text carrying a mark), and an attr value
+or bare URL. A `|code` *block* body is raw, but it has no public `format`: the
+parser and generator apply that rule themselves at the block boundary.
 
 #### unbreakscapeText(input: string, options?: BreakscapeOptions): string
 
 Unbreakscape text (unescape bitmark special characters).
 
 - `format` — `"bitmark++"` (default) or `"plainText"`
-- `location` — `"body"` (default) or `"tag"`
+- `location` — `"body"` (default), `"cardBody"` or `"tag"`
+- `subLocation` — accepted and **ignored**
+
+For `bitmark++` the rule is "remove one caret from each run" whatever the
+context, so a single inverse undoes every breakscape mode.
 
 #### info(options?: InfoOptions): string
 
@@ -588,7 +698,10 @@ defaults), JSON keys, per-context overrides, and the card set structure. `"depre
 version and (separately) any migration target.
 
 - `infoType` — `"list"` (default), `"bit"`, `"all"`, `"deprecated"`,
-  `"bit-groups"`, `"resource-groups"`, or `"languages"`
+  `"bit-groups"`, `"resource-groups"`, `"languages"`, or `"error-codes"`
+  (every issue code the parser can emit, with its severity and its message
+  templates per scope — `ErrorCodesInfo`; read from the validator's own
+  message table, so it is what the envelope emits, in every variant)
 - `format` — `"text"` (default) or `"json"`
 - `bit` — filter to a specific bit type (when `infoType` is `"bit"`)
 - `pretty` — prettify JSON output (default: `false`)
@@ -791,6 +904,21 @@ with each release (the site root hosts the bitmark language docs), or build
 it locally with `npm run docs` (→ `docs/api/`) and preview it with
 `npm run docs:serve` (http://localhost:8080, `--port` to change).
 
+### Resolved config document
+
+The package ships the resolved bitmark configuration its parser was compiled
+against — every bit type, tag group and card set with descriptions, formats,
+defaults and mapping keys — as `bitmark.json`, with its TypeSpec contract
+beside it:
+
+```ts
+import config from "@gmb/bitmark-parser/bitmark.json" with { type: "json" };
+// contract: node_modules/@gmb/bitmark-parser/config/bitmark-json.tsp
+```
+
+It is generated by the build (`bitmark-confgen`) from the repo's jsonc config
+tree, never hand-edited, and its `label` is a content hash of that tree.
+
 ### JSON Schema
 
 The package also ships a JSON Schema (Draft 2020-12) describing the parser's
@@ -827,7 +955,7 @@ A tag whose configured format is `number` accepts what JavaScript's
 
 `NaN`, `Infinity`, an exponent beyond ±4000, and a radix literal past 64 bits
 are **rejected**: the tag is dropped from the output and a
-`property-format-mismatch` warning names it, exactly like any other value that
+`tag-value-invalid` warning names it, exactly like any other value that
 does not fit its format.
 
 Accepted values print in JavaScript's `JSON.stringify` form — `0.5`, `1.5`,
@@ -953,6 +1081,10 @@ bitmark convert input.bitmark --input-format bitmark --output-format lex --prett
 # Breakscape / unbreakscape text
 bitmark breakscape input.txt
 bitmark breakscape input.txt --format plainText --location tag
+# a card side / variant body, where the card dividers are live
+bitmark breakscape input.txt --location cardBody
+# a value for an inline-attr chain segment (==t==|link:VALUE|)
+bitmark breakscape input.txt --location body --sub-location attrValue
 bitmark unbreakscape input.txt
 
 # Query bit type information

package/config/bitmark-json.tsp

@@ -0,0 +1,330 @@
+/**
+ * bitmark.json — the resolved bitmark configuration document.
+ *
+ * `bitmark-confgen` resolves the hand-edited jsonc config tree
+ * (`resources/bitmark-configurator/config`) plus `manifest.jsonc` into this
+ * one document at build time (PLAN-144, PLAN-207). The parser's lookup tables,
+ * the JSON Schema, the TypeScript types and the docs site are all generated
+ * from it, and the npm package ships the exact document its parser was
+ * compiled against as `@gmb/bitmark-parser/bitmark.json`, with this file
+ * beside it as `@gmb/bitmark-parser/bitmark-json.tsp`.
+ *
+ * Prose spec with the derivation algorithms: `.zen/specs/BITMARK-JSON-FORMAT.md`.
+ * Shape source of truth: `crates/app/bitmark_confgen/src/model.rs` — any change
+ * there updates this file in the same PR.
+ *
+ * Conventions:
+ * - Identity is text. Root entities are keyed by name in sorted maps; every
+ *   single-parent construct nests inside its owner. There are no numeric ids.
+ * - Optional members are omitted when absent, never `null`. Two exceptions:
+ *   flag booleans (`bodyRequired`, `alwaysEmit`, …) are present only when
+ *   `true`, and `TagDef.default` is `null` to mean "omit".
+ * - Arrays are in semantic (declaration) order; maps are sorted by key.
+ * - Derived members (`allTags`, `usedBy`, `parentOverrides`, `resources`) are
+ *   computed by confgen, never authored.
+ */
+namespace BitmarkConfig;
+
+/** A mapping-id → key-pattern record. Ids are registered in `mappingTypes`;
+ *  a pattern is the verbatim authored JSON value (string, object or array of
+ *  predicate records — see `crates/lib/jsonkey_parser/doc/`). */
+model MappingKeys is Record<unknown>;
+
+/** The document. */
+model BitmarkJson {
+  /** App semver, from `manifest.jsonc` (kept in lockstep with the packages). */
+  version: string;
+
+  /** Provenance: `fnv1a64:<16 hex>` over every input file keyed by its
+   *  config-relative path, plus the manifest. Independent of where the tree
+   *  lives on disk; no wall clock. */
+  label: string;
+
+  /** Manifest order, verbatim. */
+  locales: Locale[];
+
+  /** Manifest order, verbatim. */
+  mappingTypes: MappingType[];
+
+  /** Bits by technical name (sorted). Abstract base definitions are absent. */
+  bits: Record<Bit>;
+
+  /** Tag groups by name (sorted). */
+  groups: Record<Group>;
+
+  /** Card sets by key (sorted). */
+  cardSets: Record<CardSet>;
+
+  /** Resource catalog by resource type (sorted); derived from the
+   *  `resource-<type>` groups minus the manifest's `resourceUtilityGroups`. */
+  resources: Record<Resource>;
+
+  /** Bit-group registry by key (sorted). Metadata only: membership lives on
+   *  each bit's `bitGroups`. */
+  bitGroups: Record<BitGroup>;
+
+  /** Resource-group registry by key (sorted). Here the member list is
+   *  authoritative. */
+  resourceGroups: Record<ResourceGroup>;
+}
+
+model Locale {
+  /** BCP-47 language code, e.g. "en". */
+  code: string;
+  isBase: boolean;
+  /** English label, e.g. "English". */
+  label: string;
+}
+
+/** A registered mapping id and its representation type. */
+model MappingType {
+  /** Mapping id used as a key in every `mappingKeys` record, e.g. "json". */
+  id: string;
+
+  /** Representation type: "json" | "html" | "xml" (open set); informational. */
+  type: string;
+
+  /** Parent mapping id: key lookups under this id fall back to the base
+   *  (publisher overrides). */
+  `extends`?: string;
+}
+
+model Bit {
+  description: string;
+
+  /** English display name; other languages come from `translations.json`.
+   *  Absent when unauthored. */
+  title?: string;
+
+  /** Bit-group memberships, sorted — the single home of that fact. Omitted
+   *  when the bit is deliberately ungrouped. */
+  bitGroups?: string[];
+
+  /** Author-facing usage notes, one bullet per entry; docs-only. */
+  usageNotes?: string[];
+
+  /** "bitmark" | "text" | "latex" | "json" | "xml". */
+  bodyFormat: string;
+
+  /** Flag booleans: present only when `true`. */
+  bodyRequired?: true;
+  bodyForbidden?: true;
+  footerRequired?: true;
+  footerForbidden?: true;
+
+  /** Version string at which the bit was deprecated; docs-only. */
+  deprecated?: string;
+
+  /** Migration target: engines re-emit input using this (deprecated) bit
+   *  type under the named bit. */
+  migrateTo?: string;
+
+  /** "all" | "none". */
+  resourceAttachmentAllowed: string;
+
+  /** Required resource type (a key of `resources`); omitted when none. */
+  resourceRequired?: string;
+
+  /** Key of `cardSets`; omitted when the bit has no card set. */
+  cardSet?: string;
+
+  /** Bit-level named element keys for markup import; omitted when empty. */
+  mappingKeys?: MappingKeys;
+
+  /** Ordered declaration list: inline tag definitions and group references. */
+  tags: TagRef[];
+
+  /** Computed transitive closure of tags, as scoped keys, in declaration-DFS
+   *  order with name dedup (first position kept, later declaration wins).
+   *  A scoped key is `<kind>:<ownerPath>.<tag>` — `bit:article.#`,
+   *  `group:article.#`, `variant:flashcard.default.question.1.@example` —
+   *  and a chain child appends to its parent's key. */
+  allTags: string[];
+}
+
+/** One entry of a `tags` / `chain` array: an inline definition or a group
+ *  reference, told apart by which of `tag` / `group` is present. */
+union TagRef {
+  TagDef,
+  GroupRef,
+}
+
+model TagDef {
+  /** Config key including its sigil (`@example`, `#`, `&image`, `%`, …) —
+   *  the identity within the owner scope. */
+  tag: string;
+
+  description: string;
+
+  /** "string" | "bitmark+" | "boolean" | "number" | "numberList4" | "enum". */
+  format: string;
+
+  /** Enum vocabulary: present (non-empty, unique) exactly when `format` is
+   *  "enum". */
+  values?: string[];
+
+  min: int64;
+
+  /** -1 = unlimited. */
+  max: int64;
+
+  /** Always present. `null` means OMIT: absence is the canonical state and a
+   *  present value is never stripped nor an absent one materialised.
+   *  Otherwise the format's natural value ("false" / "0" / "") or an
+   *  authored non-natural value, which requires `alwaysEmit`. */
+  default: string | null;
+
+  /** Flag boolean: pin the key even in optimised mode, materialising the
+   *  default when absent. */
+  alwaysEmit?: true;
+
+  /** Version string at which the tag was deprecated; docs-only. */
+  deprecated?: string;
+
+  /** Omitted when none. A `json` member may be the string "@ignore": the
+   *  tag takes no value. */
+  mappingKeys?: MappingKeys;
+
+  /** Ordered chain children; omitted when empty. */
+  chain?: TagRef[];
+
+  /** Computed: overrides this tag receives from each parent context, sorted
+   *  by (parentType, parent). Omitted when empty. */
+  parentOverrides?: ParentOverride[];
+}
+
+/** A reference to a group, with optional link overrides. */
+model GroupRef {
+  /** A key of `groups`. */
+  group: string;
+  mappingKeys?: MappingKeys;
+  min?: int64;
+  max?: int64;
+}
+
+model ParentOverride {
+  /** "bit" | "group" | "tag" | "variant" (never "cardSet"). */
+  parentType: string;
+
+  /** Name (bit / group), variant path, or — for `tag` — the parent tag's
+   *  scoped key (`group:person.@partner`). */
+  parent: string;
+
+  /** At least one of the three is present. */
+  mappingKeys?: MappingKeys;
+  min?: int64;
+  max?: int64;
+}
+
+model Group {
+  description: string;
+  tags: TagRef[];
+  allTags: string[];
+
+  /** Computed reverse references; omitted when nothing references the group. */
+  usedBy?: UsedBy;
+}
+
+/** Reverse references; each member sorted lexicographically and omitted when
+ *  empty. */
+model UsedBy {
+  bits?: string[];
+  cardSets?: string[];
+  /** `<cardSetKey>.<cardName>.<sideName>.<variantIndex>` (1-based). */
+  variants?: string[];
+  groups?: string[];
+  /** Scoped keys (`group:person.@partner`) of the tags whose chains
+   *  reference the group. */
+  tags?: string[];
+}
+
+model CardSet {
+  mappingKeys?: MappingKeys;
+
+  /** Card-set-level references; omitted when empty. */
+  tags?: TagRef[];
+  allTags?: string[];
+
+  /** Bits using this card set, sorted; omitted when none. */
+  usedBy?: UsedBy;
+
+  /** Ordered. */
+  cards: Card[];
+}
+
+model Card {
+  name: string;
+  isDefault: boolean;
+
+  /** 0 = no lower bound. */
+  min: int64;
+
+  /** 0 = unbounded (cards use 0, not -1). */
+  max: int64;
+
+  mappingKeys?: MappingKeys;
+
+  /** Ordered. */
+  sides: Side[];
+}
+
+model Side {
+  name: string;
+
+  /** -1 = repeat forever; omitted when none. */
+  repeatCount?: int64;
+
+  mappingKeys?: MappingKeys;
+
+  /** Ordered; a variant's identity is its 1-based index. */
+  variants: Variant[];
+}
+
+model Variant {
+  bodyFormat: string;
+  bodyRequired?: true;
+  bodyForbidden?: true;
+
+  /** -1 = infinite; omitted when none. */
+  repeatCount?: int64;
+
+  mappingKeys?: MappingKeys;
+  tags: TagRef[];
+  allTags: string[];
+}
+
+model Resource {
+  /** Name of the defining `resource-<type>` group. */
+  group: string;
+
+  /** Component resource types of a composed resource; omitted when empty. */
+  composedOf?: string[];
+}
+
+/** A search/filter category over bit types. Deliberately no member list:
+ *  membership is authored per bit (`Bit.bitGroups`). */
+model BitGroup {
+  /** English display name; other languages come from `translations.json`. */
+  title: string;
+  description: string;
+
+  /** Alternative keys accepted by lookups; omitted when empty. */
+  aliases?: string[];
+
+  /** Informational parent group; never implies membership. */
+  subgroupOf?: string;
+
+  /** Flag boolean: the group is allowed to have no members. */
+  allowEmpty?: true;
+}
+
+/** A search/filter category over resource types. The member list is the
+ *  single home of that fact. */
+model ResourceGroup {
+  title: string;
+  description: string;
+  aliases?: string[];
+
+  /** Member resource types, sorted; each is a key of `resources`. */
+  resourceTypes: string[];
+}