@quillmark/wasm 0.106.0 → 0.108.0

package/CHANGELOG.md

@@ -1,5 +1,325 @@
 # Changelog
 
+## v0.108.0 - 2026-08-18
+
+- fix: **the value ladder is cut per cell, so the plate is total at every
+  depth.** An absent container returned a value instead of descending, and
+  everything below it was decided by that one branch: an absent `contact` never
+  reached `contact.email`'s own `default:`, and a container `default: {name: A}`
+  crossed whole, so a declared property it omitted was **missing from the
+  plate** — a direct Typst read of it a compile error, on an address
+  `form-field` still binds. Two spellings of the same state disagreed:
+  authoring `contact: {}` rendered the leaf defaults that leaving `contact` out
+  did not, and `default: {}` — documented as expanding to the blank-filled
+  shape — emitted `{}` with no declared key at all. Resolution is now a descent:
+  a rung supplies a *seed*, and the same composition runs over it whichever rung
+  it came from, so absence is inherited rather than terminal and each cell cuts
+  its own ladder. A partial element inside an `array` `default:` is completed
+  against `items` as an authored element is. The variant container already
+  worked this way and stops being the special case.
+- **breaking** a `default:`/`example:` on an `object` with `properties` is a
+  load error (`quill::default_on_namespace`, `quill::example_on_namespace`),
+  naming the properties that hold it. A quill declaring one loaded before, so
+  the upgrade reads as a quill that stopped loading rather than as a fix; no
+  in-tree quill declares one. A typed dictionary is a namespace, not a cell:
+  the container literal was a second declaration of a value the property
+  already holds, and the two axes read different ones — `default: {name: A}`
+  rendered `A` while `must_fill` derives per property and still reported `name`
+  unauthored. It was also unchecked, so `default: {nope: 1}` loaded and crossed
+  an undeclared key to the plate. This is the variant container's rule
+  (`quill::default_type_mismatch`) generalized; an `array` keeps its literal,
+  since `items:` fixes the element type but never the arity.
+- **breaking** `must_fill:` is retired: obligation is a reading of `default:`,
+  never a declaration of its own. Declaring the key is a load error
+  (`quill::field_parse_error`) naming the migration that field's shape takes,
+  `FieldSchema::must_fill()` is `default.is_none()`, and the raw
+  `FieldSchema.must_fill` field is gone. Four of the five legacy declarations
+  restate the derivation and migrate by **deletion**: `must_fill:` on a typed
+  dictionary (a namespace carries no obligation — its leaves do), `must_fill:
+  true` with no `default:`, and `must_fill: false` beside one. `must_fill:
+  false` with no `default:` becomes `default: <the type's blank>` (`""`, `[]`,
+  `0`, `false`) — already the corpus's most common `default:`. The fifth,
+  `must_fill: true` beside a `default:`, is the one behavior deleted and the
+  one judgment call: keep the `default:` to render the value unasked, or move
+  it to `example:` to keep the ask. An example fills the blueprint cell the
+  default vacated, seeds *carrying* the `!must_fill` marker where a
+  `default:`-only field seeds nothing, and never renders — so an untouched
+  document renders the blank rather than asserting a value nobody chose. For a
+  `string` or `enum` the blueprint bytes are identical either way; three shapes
+  are not. A `richtext` example never inlines, so its cell becomes a bare
+  marker and the value survives only as the `# e.g.` hint. An
+  `integer`/`number`/`boolean` blank is indistinguishable at the plate from an
+  authored zero. On a variant container the two targets select different
+  worlds: `default: CUI` renders the CUI world and obliges its cells, while
+  `example: CUI` leaves the discriminant blank. Also removed:
+  `quillmark:must_fill` from the transform schema, which is the wire *validity*
+  contract, and an unauthored must-fill cell is wire-valid by design; the
+  declaration view carries `default:` for a consumer that wants to derive.
+  No in-tree quill declared the key and the declaration view emits only what an
+  author wrote, so no emitted JSON changes for any real quill — the WASM
+  `QuillFieldSchema` TS interface loses `must_fill?: boolean`, a compile-time
+  break for editors typed against it.
+- fix: **seeding descends into a container's `example:`.** A dictionary with no
+  `example:` of its own seeded nothing, so a property's `example:` was
+  unreachable at every projection — the render floor never emits an example, and
+  the blueprint is a different document. A seed is now composed from whatever
+  its cells commit, sparse at every depth, and stays absent when none of them
+  commit anything. Markers ride the cell they belong to.
+- fix: `resolve()`'s rung is honest for a container. It has no rung of its own,
+  so it reports the strongest that contributed: `authored` when the document
+  wrote any of it, else `default` when a cell below resolved to one, else the
+  floor. An absent container over defaulted cells read `blank` while rendering
+  those defaults, which is the fact an editor ghosts from. Nothing inside a
+  container the document did not author reads `authored`. A variant container
+  counts its live world's cells the same way, so writing one of them lifts a
+  container whose discriminant fell to the schema's `default:`.
+
+- chore(deps): the Typst floor moves to 0.15.1. The workspace already resolved
+  there under the 0.15.0 caret; the pin now names the version the tree is built
+  and tested against. `pdf-writer` stays at 0.15.0, still the version
+  `typst-pdf` → `krilla` forces and the newest published.
+- docs: `0.107-to-0.108.md`, the guide for this step. It leads with the two load
+  errors, since both reject the quill rather than the document, and gives
+  `must_fill: true` beside a `default:` — the one behavior deleted — the space
+  its judgment call needs. `BLUEPRINT.md` § "Typed dictionaries" loses the `{}`
+  expansion and the container-literal renderings with the cascade that produced
+  them, and states the nesting the 0.107 collapse admits.
+
+## v0.107.0 - 2026-08-17
+
+- fix(typst): `display(field, ..)` validates its address against the schema, the
+  assert `form-field` and `field-region` already carry. It is the one helper keyed
+  by address rather than by value, and it was the one accepting an address the
+  schema does not have: `display("issed", "[year]")` compiled, drew nothing, and
+  reported nothing — the failure a plate author is least placed to see, a card
+  address being a string the plate builds by concatenating `$path`. `_qm-display`
+  cannot catch it, carrying an entry per *present* date, so a blank date and a
+  typo are absent from it alike; `_qm-known-path` answers about the schema and
+  tells the two apart. A known address carrying no date still returns `none`, so
+  a `== none` fallback is unchanged: the assert is about the address, the `none`
+  about the value.
+- fix: **a container's own `default:` reaches the plate as content.** The render
+  floor read `default_content` only for a `richtext`/`plaintext` leaf. An
+  `object` or `array` carrying its `default:` on the container fell through to
+  the raw literal instead, crossing as unimported markdown where every other
+  content position delivers a canonical content object. The companion was
+  already cached and never read. The floor now keys off the cache — present is
+  the form to commit, absent over a content-bearing tree blank-fills — which
+  covers leaf and container alike and drops the type test. `usaf_memo`'s
+  `references` (`array<richtext(inline)>`, `default: []`) carried the same
+  defect, invisible only because the list was empty.
+- **breaking** a container-shaped `default:`/`example:` on a variant-bearing
+  enum is a load error (`quill::default_type_mismatch`,
+  `quill::example_type_mismatch`). A quill declaring one loaded before, so the
+  upgrade reads as a quill that stopped loading rather than as a fix.
+  The container is the shape a *document* writes. As a schema literal it cached
+  no content form and yielded no discriminant, so the field blank-filled in
+  silence as if nothing were declared. The diagnostic names the discriminant
+  spelling instead, which is where a world's cells carry their own literals.
+  Scalar literals are unaffected.
+
+- feat: **every type nests at every depth**. A property or an element is an
+  ordinary field, so it carries whatever a card-level field carries, itself
+  included: `object<array<string>>`, `array<array<integer>>`, a typed table whose
+  row holds a typed dictionary, and a variant cell holding either.
+  `quill::nested_object_not_supported` and `quill::nested_array_not_supported`
+  are gone, and `ShapePosition`'s three positions collapse to the one question
+  the walk still asks — is this card level, where `variants:` and `ui.group` are
+  the two keys that live. A widening: every quill that loaded before loads
+  unchanged.
+  The depth budget was what the flat address tables existed for.
+  `SchemaMeta` carried six name-keyed tables (`array_fields`, `object_fields`
+  and their card twins) so the helper's `_qm-known-path` could enumerate two
+  suffix steps rather than derive a grammar; they are replaced by one address
+  tree — the schema pruned to the steps it offers — that the helper and the span
+  scan both walk, converging on the unbounded descent `pdfform::bind` always
+  had. Three components deriving an address become one walk each side of the
+  seam, and `quillmark/tests/address_grammar.rs` pins the two against the deep
+  shapes as well as the shallow ones.
+  `variants:` stays card-level, now on its own reasoning rather than by
+  inheriting the depth ban: a variant's shape is a function of the schema *and*
+  the discriminant, and the union projection, the once-bound form, the plate's
+  single branch and `validation::out_of_variant` each hold because that gap is
+  one level deep ([SCHEMAS.md](prose/canon/SCHEMAS.md) §"Enum variants"). An
+  array-valued variant cell used to report `nested_array_not_supported`, whose
+  message named array elements and object properties — neither the situation;
+  the shape is now legal and `quill::variant_placement` is left saying only what
+  it means.
+- fix: `blueprint()` expands a container at every depth. `build_property_mapping`
+  spent each property through the scalar builder, so a nested `object` or typed
+  table rendered as `key: null # object` — its own properties, their markers and
+  their annotations absent — where the same shape one level up expanded. It now
+  recurses, and the card-level and nested paths are one implementation, so a
+  `default:` covers its subtree identically wherever it is declared. No
+  document changes shape: the shapes this fixes could not be declared before.
+- fix: a content leaf's `default:` reaches the plate from **every** position it
+  can be declared in, not only card level. The load pass that imports each
+  richtext/plaintext literal into its companion cache walked the card's field
+  map, so an `object` property, a typed-table row property and a variant cell
+  each kept their authored `default:` and cached nothing; the render floor read
+  the leaf's empty companion and blank-filled. A document authoring only the
+  container (`dict: {}`, `rows: [{}]`, `c: {value: CUI}`) rendered correctly
+  with the author's default missing, and nothing upstream had anything to
+  report. The walk now recurses `properties` / `items` / `variants`, the shapes
+  `field_contains_content` already descended, so such a document now renders
+  **with** the author's default — a render-output change for any quill that
+  declared one. Importing a literal is also what checks it, so a nested
+  `richtext(inline)` violation — in a `default:` or an `example:` — now fails
+  load as a card-level one always has, naming the leaf's declaration path.
+  **Breaking on that second count**: the literal loaded before, so a quill
+  carrying one stops loading. Nested `example:` *surfacing* was never broken:
+  the blueprint prints the raw literal at every depth.
+- **breaking** typst: a plate's direct read of a typed-table row cell regions on
+  the cell (`refs.0.org`), where it regioned on the whole array before — a
+  *wrong* address, not a missing one, routing a click on the org cell to the
+  entire table. The span scan was the third component deriving a schema address
+  and the one left at the one-level ceiling: 0.106 lifted the lowering walk and
+  `_qm-known-path` to the row property, so the three no longer agreed, and the
+  scan is the one that decides what a *read* is attributed to. It now takes the
+  index step (`.at(n)`, the only spelling Typst has for an array index) and then
+  the row property, gated on the `array_fields` table. Each step is its own
+  address, so a whole-row read names the row (`refs.0`) and a primitive
+  element's read names the element (`tags.0`); a negative index and an
+  undeclared row key mint nothing and fall back as before. Consumers keying on
+  the array's address for element ink see the narrower address instead. Explicit
+  `field-region` / `form-field` claims are unchanged, and the alias lane keeps
+  parity: `#let row = data.refs.at(0)` … `#row.org` regions on `refs.0.org`.
+- test: one table pins the schema address grammar on both backends
+  (`quillmark/tests/address_grammar.rs`), covering every position the nesting
+  contract admits, each position's card twin, and the rejects that bound each
+  step. `PLATE_DATA.md` promises a plate author that one address binds on
+  either backend, and the grammar is written twice to keep it — an unbounded
+  schema walk in `pdfform::bind`, an enumeration of the suffix forms in the
+  Typst helper's `_qm-known-path` — reading two different projections of the
+  same `QuillConfig`, so either side can move alone. `pdfform` exports
+  `resolves_schema_address` (`#[doc(hidden)]`) so the pin can ask both the same
+  question. A body address is the plate grammar's alone and is pinned as such.
+
+- **breaking** typst: lowering dispatches on the schema node beside each value
+  rather than on tables of top-level field names, so a declared type means the
+  same thing wherever it is declared. A `date`, `richtext` or `plaintext`
+  declared inside an `object` or an `array` row reached the plate as its raw
+  wire value before — a bare string for a date, and for a rich field the
+  *internal canonical-content JSON*, rendered as a Typst dict — while the same
+  type one level up lowered correctly. Ten of the twelve nested positions the
+  schema admits degraded that way, silently: core coerced and validated the
+  value correctly, so nothing upstream had anything to report. `contact.note`
+  is now a markup block, `contact.reply_by` and `rows.0.on` are `datetime`s,
+  and `_qm-plaintext` gains the nested entries that closed the
+  `plaintext(field)` escape hatch. The walk is the inverse of the one
+  `build_transform_schema` builds the node with, so it cannot be shallower than
+  the schema is.
+- **breaking** typst: a `date` / `datetime` field lowers to a **native**
+  `datetime`, not the `(value:, display:)` wrapper. `data.issued.year()`,
+  `data.issued < data.due` and handing the field to a datetime-consuming
+  package are ordinary Typst; `.value` and the paren form `(data.issued.display)(..)`
+  are hard Typst compile errors, never a silent degrade, and all consumers are
+  first party. A date has no canonical rendering the way authored text does —
+  every rendering of `2026-01-02` is a typographic decision the plate owns — so
+  it lowers to its value and reaches ink by address instead.
+- feat(typst): `display(field, ..args)`, a date field's content projection,
+  keyed by schema address rather than carried on the value. It places rendered
+  ink whose glyphs are born in generated source, so a date formatted through a
+  `#let` binding, a per-card loop variable, or a vendored package keeps a
+  region on its schema field — the affordance the value-object existed to buy,
+  now available to any date at any depth without shaping the value. `none` for
+  a blank date, so a `== none` fallback still fires. The rule plates follow:
+  want a value → `data.<field>`; want clickable ink → `display("<field>", ..)`.
+- feat: a variant cell may carry **any type a card field may**, prose and dates
+  included — `quill::variant_field_type` is gone. The load error existed because
+  lowering read flat top-level name tables that could not descend into a
+  container, so a `date` or `richtext` cell inside a variant would have loaded
+  clean and reached the plate as its raw wire value; the schema-node walk reads
+  the cell's own declaration, leaving the ceiling nothing to protect. Every value
+  surface already descended per live-world cell — coercion through
+  `conform_value`, validation through `validate_value`, the render floor through
+  `resolve_value` — so the widening needed one real fix:
+  `field_contains_content` returned `false` for a variant container on the
+  strength of this very guard, which would have silently skipped the content
+  companion caches, the resting-form conversion and the seed path for a variant
+  content cell. It now answers on the union of the worlds' cells. Containers
+  are included: "every type nests at every depth" lands in this same release, so
+  a variant cell holds a typed table or a typed dictionary like any other
+  position. `variants:` itself stays card-level (`quill::variant_placement`) on
+  the reasoning stated there.
+
+- **breaking** typst: the `plaintext(field)` helper and its `_qm-plaintext`
+  table are removed. Shipped in 0.94 as the sanctioned content→`str` coercion,
+  it never acquired a caller: no plate, no vendored package, and no binding
+  surface referenced it, and the `create-auto-grid` consumer its own docstring
+  cited passes an `array<string>` rather than a content field, so the only
+  things exercising it were its three tests. It also carried a three-way name
+  collision with the `plaintext` field type and that type's document-layer
+  resting shape, which took a standing caveat in canon and the template to hold
+  down. A plate that needs a `str` from a content field now has no route, which
+  is the honest state of the requirement: reinstating it is additive and cheap
+  when a plate actually asks.
+- feat(typst): a typed table's row property (`refs.0.org`) is a writable
+  schema address. `form-field(field:)` and `field-region` capped at one suffix
+  step while pdfform's resolver descended unboundedly, so a shape
+  `ShapePosition` explicitly admits bound on one backend only, against
+  `PLATE_DATA.md`'s claim that one address binds on either. `array_fields` now
+  carries each array's row property names, the same shape `object_fields`
+  already had.
+- fix(typst): a non-blank date the shared parsers reject raises
+  `backend::invalid_date` from codegen rather than a pre-pass over top-level
+  name tables, so the check covers every depth. Only a direct `apply` can
+  deliver one; coercion parses the same way.
+- feat(typst): a scalar read through a `let` alias regions on the address the
+  chain it names would carry, so `#let c = data.classification` … `#c.poc`
+  surfaces `classification.poc` where it surfaced nothing at all — not the
+  container's address, absent. Binding a container once and stepping into it
+  three times is the refactor 0.106's property addressing invites, and it cost
+  the address silently, the document still rendering correctly. An alias holds
+  only where the plate binds the name exactly once to one whole `data` chain: a
+  name a second `let`, a closure parameter, a loop pattern, an import, or an
+  assignment could rebind is dropped rather than risk attributing another
+  value's ink to the field, and a wildcard import disqualifies every alias.
+  Which name is followed is half the rule; which *occurrence* is the other half,
+  since a schema field name collides freely with the parameter names of a callee
+  the plate never defines (`date`, `title`, `caption`, `align`, `subject`). Only
+  an occurrence that reads the binding anchors: an identifier spelling the alias
+  as a named argument (`#text(size: 12pt)`), a dict key, another value's field
+  (`#styles.subject`) or an imported item's path draws no ink off the field, and
+  a window minted over one would carry a *wrong* address rather than a missing
+  one.
+  Laundering past that — a function parameter, a destructured binding, a
+  per-card loop variable — is unchanged and still needs a `field-region` claim,
+  now stated for plate authors under "Which Reads Get Regions" in the Typst
+  backend guide. Content and date fields are unaffected: their ink is born in
+  generated code.
+
+- feat(wasm): `VARIANT_DISCRIMINANT_KEY` joins the runtime's static exports,
+  beside `MAIN_CARD_ADDR`. v0.106.0 announced the constant as new API but shipped
+  it to Rust only, leaving a JS consumer reading or writing a variant container
+  to spell `"value"` itself — a hardcoded copy of the one value whose purpose is
+  to not be hardcoded, at the seam where the two can drift unobserved, since the
+  key crosses the boundary inside untyped container data. The `.d.ts` types it as
+  the string *literal*, which `string` would stop narrowing an index into the
+  container. `known_names_drift.rs` pins both spellings against the Rust
+  constant, the guard the hand-spelled name tables beside it already carry.
+  `VariantFields` stays Rust-only: it is a type alias the TypeScript surface
+  already inlines as `QuillFieldSchema.variants`, naming no shape a consumer
+  builds.
+- docs: `0.105-to-0.106.md`, the migration guide v0.106.0 shipped without. It
+  leads with the region-address shift rather than the three `!` entries: the
+  changelog is organized by feature, and the address step is one clause inside a
+  long entry while being the item most likely to break a working consumer, since
+  `FieldRegion.field` is a bare `string` that no type checker reports a grammar
+  change under. The guide states both gates on the step, and points a consumer at
+  `doc.pathFor` for the prefix grammar it would otherwise match as a literal —
+  with that helper's limit stated, a field name passing through it verbatim.
+  `CONTRIBUTING.md` gains the two rules that would have caught the gap: `!` marks
+  an observable-contract shift even where no type changes, and a release carrying
+  one ships its guide.
+- docs: `0.106-to-0.107.md`, this release's guide, under the rule the entry above
+  adds. It leads with the region-address index step — `main.refs[0].org` where
+  `main.refs` stood, a wrong address rather than a missing one — and then with
+  the two schema literals that stop a quill loading, since those read as a build
+  that broke rather than as a fix. `ERROR.md` names `display(..)` as the
+  address-keyed template-author contract, `plaintext(..)` having been removed
+  here.
+
 ## v0.106.0 - 2026-08-16
 
 - feat(typst,pdfform): a schema address may step one property into a declared
@@ -122,22 +442,6 @@
   names, which PyPI rejected the sdist for lacking. v0.104.0 and v0.105.0 are
   wheels only.
 
-<!-- seed: commits since v0.105.0, confirm the entries above cover them, then delete this comment
-- chore(repo): union-merge CHANGELOG.md
-- feat: migrate usaf_memo to enum variants, document the axis
-- feat(core): enum variants — fields that exist only for one enum value
-- fix(fixtures): drop the rule under the indorsement date
-- fix(fixtures): size the indorsement date widget in ems, not inches
-- fix(fixtures): set the memo's indorsement date widget like a date
-- feat(typst,pdf): font, size, and align on injected form fields
-- Make the usaf_memo indorsement's blank date a bound fill-in widget
-- Compress the field-region prose
-- Add `field-region` so plates can tie composed content to a field
-- fix(python): declare license-files so the sdist ships its LICENSE
-- Anchor an undeclared property at the property, not at a bare name
--->
-
-
 ## v0.105.0 - 2026-08-14
 
 - feat(core,wasm,python)!: a `Content` nested inside a composite field is

package/README.md

@@ -396,8 +396,8 @@ that value under a type-only `# <type>` annotation and the render path uses it
 when the document omits the field. Without one, an `example` takes the cell as
 a suggested value, and an absent field blank-fills.
 
-**Obligation** — whether a human must author the field, declared by
-`must_fill:` and deriving from `default:`'s absence when left unset. An obliged
+**Obligation** — whether a human must author the field, read off `default:`'s
+absence: a defaulted field asks nobody, a defaultless one asks. An obliged
 field carries the `!must_fill` marker in `quill.blueprint`, and
 `quill.validate(doc)` emits the non-fatal `validation::must_fill` warning while
 the document leaves it unauthored — from either of two triggers, named by the

package/backends/pdfform/wasm.d.ts

@@ -347,7 +347,14 @@ export interface PaintResult {
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -447,12 +454,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -467,9 +473,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/backends/typst/wasm.d.ts

@@ -347,7 +347,14 @@ export interface PaintResult {
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -447,12 +454,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -467,9 +473,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/core/wasm.d.ts

@@ -292,7 +292,14 @@ export type DocPathSeg =
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -392,12 +399,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -412,9 +418,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.106.0",
+  "version": "0.108.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",

package/runtime/runtime.d.ts

@@ -84,6 +84,16 @@ import type { CardAddr } from '../core/wasm.js';
  */
 export declare const MAIN_CARD_ADDR: CardAddr;
 
+/**
+ * The key carrying the discriminant inside a variant-bearing enum's value. A
+ * field declaring `variants:` rests as `{value: <member>, …that member's
+ * fields}`, so reading or writing one means naming this key; it crosses the
+ * boundary inside untyped container data, with no type to read it off.
+ * Reserved: no variant may declare a field under it, and
+ * {@link QuillFieldSchema.variants}, keyed by member, never contains it.
+ */
+export declare const VARIANT_DISCRIMINANT_KEY: 'value';
+
 // Core-build types consumers read off `Quill`/`Document`.
 export type {
 	Card,

package/runtime/runtime.js

@@ -206,6 +206,23 @@ async function instantiateCore(source) {
  */
 export const MAIN_CARD_ADDR = Object.freeze({});
 
+// ── The variant discriminant key ────────────────────────────────────────────
+/**
+ * The key carrying the discriminant inside a variant-bearing enum's value.
+ *
+ * A field declaring `variants:` rests as a container, `{value: <member>, …that
+ * member's fields}`, so reading or writing one means naming this key:
+ * `doc.storeFields(MAIN_CARD_ADDR, { classification: { [VARIANT_DISCRIMINANT_KEY]: 'CUI' } })`.
+ * It crosses the boundary inside untyped container data, with no type to read
+ * it off.
+ *
+ * Reserved: no variant may declare a field under it
+ * (`quill::variant_reserved_field_name`), and `QuillFieldSchema.variants`,
+ * keyed by member, never contains it.
+ * @type {'value'}
+ */
+export const VARIANT_DISCRIMINANT_KEY = 'value';
+
 /**
  * Narrow an unknown caught value to a `QuillmarkError`, the error every
  * fallible method in this package throws: a real `Error` with a non-empty