yarramate 1.13.0 → 1.13.1

package/docs/CONSUMING-YARRAMATE.md

@@ -484,6 +484,62 @@ Anything the mapping does not recognise is carried verbatim on `07 Other
 Facts` rather than dropped, so a workbook stays lossless across a compiler
 that grows new predicates.
 
+**Marking up the sheets.** `WorkbookSheet` takes optional `headerStyle`,
+`columnStyles` and `columnWidths`. The styles are a closed set of **roles**
+rather than appearances — `header`, `muted`, `emphasis` — so the test for
+admitting a fourth is whether it can be named without reference to how it
+looks. A request for a colour is the one a closed set exists to refuse,
+because that is what turns a style vocabulary into a styling engine.
+
+The use worth having is not decoration. Where a workbook's columns differ in
+what they reach — some binding to the model, some carried alongside it, some
+computed and ignored on the way back — an editor cannot see which is which,
+and finds out only when an import reports that a cell could not be written
+back. A role in the file says it while they are typing.
+
+**Formatting is not content in either direction, from 1.13.0.** A styled
+workbook reads back exactly as an unstyled one, and an editor's own formatting
+is ignored on import — then lost on the next export, because the workbook is
+regenerated from the model. That last part is why producer-applied styling is
+the only kind that survives.
+
+The version matters here and nowhere else in this section, because this
+sentence is a **guarantee**, and a guarantee's job is to let you decide not to
+write a test. It did not hold in **v1.6.0 through v1.12.0**: a cell carrying
+formatting and no value — which is what Excel writes for a formatted empty
+cell — was read against the previous cell's column, so importing a workbook
+somebody had merely opened and saved could clear a neighbouring value. If you
+are pinned below 1.13.0, that path is the one place this section's promise is
+worth testing rather than taking.
+
+**An optional feature's absence is silent, and that is your test to write.**
+Passing none of these fields produces byte-identical output to a release
+before they existed. That is asserted here by a test that writes the same
+sheet with and without the fields, and it has been checked the way you can
+check it yourself: call `writeXlsx` with the same plain sheets under the
+published 1.12.0 and 1.13.0 packages and hash the results. They are identical,
+byte for byte, and two people have run it with different fixtures. That property is what makes the feature safe to adopt,
+and it is exactly what makes its absence undetectable: if a rename, a bad
+merge or a refactor stops the fields reaching the writer, every test that
+asserts on *behaviour* stays green while the workbook ships with no roles at
+all, because a workbook with no styling is completely valid.
+
+The general form, which reaches past this feature to any optional thing you
+take from a library: **assert the feature arrived, not only that the result
+is well-formed.** One positive test at the consumer that fails when the
+feature stops arriving — the styles part is in the bytes, the header is
+present, the width was applied.
+
+**Assert on the artefact, not on the call.** The obvious test is that you
+passed `columnStyles` — inspect the object you handed the writer, or spy on
+the argument — and it is both the easier test to write and the one that
+passes forever while the feature stops arriving, because it asserts your
+intent rather than the result. Read the produced bytes. An absence-shaped
+regression is invisible to any assertion that never opens the output. Behavioural assertions cannot catch an
+absence-shaped regression, because the behaviour is well-defined in both
+cases. This is the same reason a `?? ''` default hides a missing column: what
+degrades gracefully degrades quietly.
+
 **Reading one back.** `yarramate import xlsx <workbook.xlsx> <workspace.yaml>`
 merges an edited workbook into the model. An unedited round trip changes
 nothing, byte for byte.

package/docs/MODEL-FLOOR.md

@@ -220,6 +220,22 @@ locator against the subject, with the provider named. Core never resolves,
 fetches, or interprets the URI: URI ownership is the provider's (ADR 0068,
 `docs/EVIDENCE.md`).
 
+**So no condition can ask about what is inside it, and that is the design
+rather than a gap.** An annex is not compiled, so nothing about its contents
+reaches the graph the interrogation runs over. A catalogue therefore cannot
+ask "are the field mappings recorded"; it can only ask **who confirmed that
+they are**, which is what `missing-attestation` is for. An attestation names a
+person and a date, and where the substance lives outside the graph that is the
+only honest instrument left — a condition claiming to check annex contents
+would be claiming to check something Core never read.
+
+This is the adopter-facing half of CONTRIBUTING.md's fifth rule, arrived at
+from the other side. There a check could not see what a declaration compiles
+to, by accident. Here it cannot see what was deliberately never compiled, by
+design. Same reach limit, opposite cause, and the remedies differ: that one is
+fixed by reading the graph instead of the vocabulary, and this one is not
+fixed at all, because there is nothing to read.
+
 ## Deliberately open
 
 Two of the refusals above are recorded limits rather than settled doctrine,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {