From 47bfb0a55c3afa51786d41d64d2ee60081aaddcd Mon Sep 17 00:00:00 2001
From: JohnnyT <ubergeek3141@gmail.com>
Date: Wed, 30 Sep 2026 05:42:01 -0600
Subject: [PATCH] Re-locates the Map-era code cites in ADR-0005, 0017 and 0018

The changes to what the Map draws, the short-form comment in core.send
and the editor's note lookup moved code lines that three accepted
records cite. One dated foot Note per record re-locates each drifted
cite by its anchor, read at d38dfb9, and names the cites that have not
moved: ADR-0018's cites into map/info.ex, editor/map_regions.ex, the
Map hook, describe.ex and editor.ex; ADR-0017's flip-Note cites into
core/send.ex, block_type.ex, palette.ex and describe.ex; ADR-0005's
cites from the decision 7 Amendment on, into the Map hook,
map_regions.ex, editor.ex, inspector.ex, edit.ex and their tests. No
line is removed and no record decides anything new.

Record Notes only; no changelog fragment (changelog.d/README.md
excludes ADRs).

Gate: full mix quality green on this exact staged tree (3,954 of 3,954
tests, 95.3% coverage, dialyzer and credo clean, ADR cites green).

Refs: sb-062y
---
 docs/adr/0005-liveview-editor.md              | 116 ++++++++++++++++++
 .../0017-block-types-explain-themselves.md    |  44 +++++++
 docs/adr/0018-the-map-reads-the-view-model.md |  49 ++++++++
 3 files changed, 209 insertions(+)

diff --git a/docs/adr/0005-liveview-editor.md b/docs/adr/0005-liveview-editor.md
index 835144e7..5130224e 100644
--- a/docs/adr/0005-liveview-editor.md
+++ b/docs/adr/0005-liveview-editor.md
@@ -14282,3 +14282,119 @@ Note states the outcome the sentence is about (`sb-0suc`).
   the note the block held before, and a single redo puts the change back
   (the test "a change applies the command, and undo and redo move the note",
   `note_field_test.exs:66`).
+
+## Note (2026-09-30): cites into the Map hook, the description region and the note command that have moved
+
+A dated Note rather than an amendment: it carries no `Status:` line, decides
+nothing, and edits no line above it. It is added at the foot of the file, so
+no line another record cites moves. Every cite below was read at `d38dfb9`
+and is written anchor first, line second; the lines in brackets are where
+the record placed it, at the commit each section names.
+
+It covers the cites of the Amendments of 2026-09-28 on decisions 7 and 1
+and of 2026-09-29 on the note command and the shell's description region,
+the Notes that flip them, and the two Notes on the Map hook below them.
+Cites above the Amendment of 2026-09-28 on decision 7 (`:13418`) are not
+re-read here. Each anchor still names the thing the record says.
+
+### The flip Note of 2026-09-28, decisions 7 and 1 (read at `362a0e9`)
+
+- `assets/js/statifier_blocks_map.js`: `export const StatifierBlocksMap` is
+  at `:801` (`:721`), its one `this.pushEvent` at `:821` (`:741`), still
+  the only `pushEvent` in the file, and `export function mapGesture` at
+  `:620` (`:557`). The import of the vendored file is still at `:34`.
+- `phx-update="ignore"` on the child marked `data-map-canvas`, which
+  `map_region/1` renders, is at
+  `lib/statifier_blocks/editor/map_regions.ex:183` (`:131`).
+- `test/statifier_blocks/assets_test.exs`: the test "the map hook is its own
+  entry point, with its own default export" is at `:427` (`:344`), and "its
+  one import is the vendored layout library" at `:455` (`:372`). The
+  describe at `:44` and the tests at `:48`, `:69` and `:102` have not moved.
+- `test/statifier_blocks/map_layout_test.exs`: "ten selections cause zero
+  layouts, and a new graph causes one" is at `:1116` (`:1003`; the Note of
+  2026-09-29 on what the hook keeps cites the same line at `2469e01`).
+- `README.md`: the section "Working on the Map in this repository" is at
+  `:1801` (`:1773`), and "The hook, and what it costs" at `:1753` (`:1739`).
+- `export default` in `assets/js/statifier_blocks.js` (`:269`) and CI's
+  `actions/setup-node@v4` step (`.github/workflows/ci.yml:51`) have not
+  moved.
+
+### The note command: the Amendment and its flip rows (read at `8c4d61b`)
+
+- `def handle_event("note-change", ...)` is at
+  `lib/statifier_blocks/editor.ex:1850` (printed `:1810`, read at `:1844`
+  by the flip Note).
+- `lib/statifier_blocks/editor/inspector.ex`: `defp note_section/1` is at
+  `:483` (`:478`), its `read_only: true` clause at `:474` (`:469`), and its
+  call, `<.note_section`, at `:403` (`:398`).
+- `lib/statifier_blocks/edit.ex`: the `{:update_note, _id, _note}` clause of
+  `check_config/3` is at `:350` (`:347`); `defp check_compound/1`'s
+  empty-list clause is at `:410` (`:407`), its list clause, which refuses a
+  nested compound, at `:412` (`:409`), and its not-a-list clause at `:420`
+  (`:417`); `defp find_block/2` is at `:484` (`:481`).
+- `test/statifier_blocks/editor/note_field_test.exs`: the describe "a
+  read-only mount" is at `:213` (`:114`).
+- These have not moved: `Edit.t()` and its `:update_note` member
+  (`edit.ex:172-180`, `:179`), `apply/2`'s `:update_note` clause
+  (`edit.ex:254`), `defp maybe_put_note/2`'s `""` clause
+  (`lib/statifier_blocks/canonical_json.ex:143`), `Validation.note/2`
+  (`lib/statifier_blocks/validation.ex:339`), `defp reach` for
+  `:update_note` (`lib/statifier_blocks/recipe.ex:168`),
+  `@read_only_refused` (`editor.ex:776`) and its refusing clause
+  (`editor.ex:1296`), the describes in
+  `test/statifier_blocks/edit/note_test.exs`, "the note textarea"
+  (`note_field_test.exs:44`) and `defp gen_update_note/1`
+  (`test/support/document_generator.ex:136`).
+
+### The shell's description region: the Amendment and its flip rows (read at `8c4d61b`)
+
+- `lib/statifier_blocks/editor/map_regions.ex`: `def description_region` is
+  at `:227` (printed `:192`, read at `:205`); `attr(:map, :boolean` at
+  `:206` (`:181`, `:187`); the hover layer's and the store's `:if={@map}`
+  at `:254` and `:277` (`:210` and `:229`, `:223` and `:242`);
+  `explanation={@map or @current.kind != :idle}` at `:273` (`:226`,
+  `:239`); the region's `aria-live="polite"` at `:266` (`:235`); and
+  `attr(:label, :string`, defaulting to `"Description"`, at `:213`
+  (`:194`).
+- `defp describable?/2` is at `lib/statifier_blocks/editor.ex:3940`
+  (`:3923`, also read at `40d18cf`).
+- `test/statifier_blocks/editor/map_regions_test.exs`: the describe "the
+  map attr" is at `:502` (`:456`).
+- These have not moved: the `<MapRegions.description_region` call
+  (`editor.ex:1207`), the `.sb-editor__description` rule
+  (`assets/css/statifier_blocks.css:3147`), `Composite.expand/2`
+  (`lib/statifier_blocks/composite.ex:626`), the describes in
+  `test/statifier_blocks/editor/description_region_test.exs` (`:55`,
+  `:148`) and the two tests in
+  `test/statifier_blocks/editor/composite_expand_test.exs` (`:468`,
+  `:486`).
+
+### The Note of 2026-09-29 on what the hook keeps (read at `2469e01`)
+
+In `assets/js/statifier_blocks_map.js`: `export const StatifierBlocksMap` is
+at `:801` (`:723`); in `mounted()`, `this.hover` is built at `:805`
+(`:727`), `this.onOver` and `this.onOut` are set at `:809` and `:810`
+(`:731`, `:732`) and the click listener sets `this.revealInsert` at `:820`
+(`:742`); `destroyed()` is at `:839` (`:761`) and removes the two listeners
+at `:842-843` (`:764-765`); in `draw()`, `this.selected` is set at `:880`
+(`:787`), the unchanged graph is re-marked from `:882` (`:790`),
+`this.source` and `this.drawn` are set at `:887` and `:888` (`:794`,
+`:795`) and a layout that lands marks the selection at `:894` (`:801`);
+`export function hover` is at `:740` (`:672`), and the `data-map-hover`
+mark is written on the layer at `:756` (`:688`). In
+`test/statifier_blocks/map_hover_test.exs`, "pushes nothing to the server"
+is at `:149` (`:148`); "a hover fills the layer from the store and never
+writes the region" is still at `:62`.
+
+At `d38dfb9` `draw()` also sets `this.warnedNoCanvas` (`:852`), a flag
+that warns once when the hook's element has no child marked
+`data-map-canvas`; that Note's list does not name it. This Note only records
+that the flag is there; it does not read it against clause 7f.
+
+### The Note of 2026-09-30 on the hover layer (read at `4fdf7f8`)
+
+The test "the stylesheet stacks the shown layer over the region" is at
+`test/statifier_blocks/editor/map_regions_test.exs:409` (`:404`). That
+Note's other cites have not moved.
+
+Filed with `sb-062y`.
diff --git a/docs/adr/0017-block-types-explain-themselves.md b/docs/adr/0017-block-types-explain-themselves.md
index 0a4d6839..2372b143 100644
--- a/docs/adr/0017-block-types-explain-themselves.md
+++ b/docs/adr/0017-block-types-explain-themselves.md
@@ -273,3 +273,47 @@ decision 2 decides reads as written.
 - Consequences names `ADR-0016`'s Amendment of 2026-09-27 and a dated Note
   on `ADR-0002` pointing here; both are on main. The Amendment is flipped
   to accepted by the same request as this Note.
+
+## Note (2026-09-30): cites that have moved since the flip Note
+
+A dated Note, not an amendment: it carries no `Status:` line and decides
+nothing. The sentences it reads stay as written, and so do the cites it
+re-locates.
+
+The flip Note above read every decision at `12d3d22`. Several of its cites,
+and the matching cites in the record's body, have moved since. Each cite
+below was read at `d38dfb9` and is written anchor first, line second; the
+lines in brackets are where the flip Note placed it, then, where the body
+cites it at another line, the body's. Each anchor still names the thing the
+record says.
+
+- `lib/statifier_blocks/core/send.ex`: `def sentence` is at `:219` (`:216`;
+  Context `:201`), `@short_form` at `:237` (`:229`) and `def delay_words`
+  at `:257` (`:249`; decision 2 `:246`, as `defp delay_words`).
+- `lib/statifier_blocks/block_type.ex`: `defmacro __using__` is at `:113`
+  (`:112`; `:110`), `optional(:description)` at `:645` (`:633`; `:631`),
+  `@callback explain` at `:869` (`:857`), `@optional_callbacks` at `:871`
+  (`:859`), with `explain: 0` at `:880`, `@presentation_cap` at `:1540`
+  (`:1436`), `def sentence` at `:1770` (`:1666`; `:1645`), `def explain` at
+  `:1807` (`:1703`), `defp call_explain` at `:2204` (`:2100`),
+  `defp description` at `:2216` (`:2112`) and `defp line` at `:2228`
+  (`:2124`).
+- `lib/statifier_blocks/palette.ex`: `def call` is at `:607` (`:606`) and
+  `def declares?` at `:649` (`:648`); the seventeen `core.*` types
+  `core_types/0` lists are at `:222-238` (`:221-237`).
+- `lib/statifier_blocks/describe.ex`: `def outline` is at `:219` (`:153`),
+  `defp timer_edges` at `:534` (`:437`), `defp timer_party` at `:555`
+  (`:456`), `defp timer_edge` at `:565` (`:466`), `defp edge_line`'s timer
+  clause, `%Edge{kind: :timer}`, at `:637` (`:534`) and `defp flat` at
+  `:719` (`:569`).
+
+These have not moved since `12d3d22`: `def duration?` in
+`lib/statifier_blocks/core/duration.ex` (`:81`); `defstruct` and
+`@type kind` in `lib/statifier_blocks/describe/edge.ex` (`:58`, `:38`); and
+`@callback timer` and `@optional_callbacks` in
+`lib/statifier_blocks/describe/phrasing.ex` (`:73`, `:75`).
+
+`delay_words/1` is still `def delay_words` with `@doc false`, as the flip
+Note read it.
+
+Filed with `sb-062y`.
diff --git a/docs/adr/0018-the-map-reads-the-view-model.md b/docs/adr/0018-the-map-reads-the-view-model.md
index 29047e8e..1fad3d36 100644
--- a/docs/adr/0018-the-map-reads-the-view-model.md
+++ b/docs/adr/0018-the-map-reads-the-view-model.md
@@ -763,3 +763,52 @@ Where it holds:
   line.
 
 Filed with `sb-r3u4`.
+
+## Note (2026-09-30): cites that have moved since the Note of 2026-09-29 on moved cites
+
+A dated Note, not an amendment: it carries no `Status:` line and decides
+nothing. The sentences it reads stay as written, and so do the cites it
+re-locates.
+
+The Note of 2026-09-29 on the chart-view paragraph re-located this record's
+cites at `9adc029`; several have moved again since, with the changes to what
+the Map draws. Each cite below was read at `d38dfb9` and is written anchor
+first, line second; the line in brackets is where the record last placed
+it. Each anchor still names the thing the record says.
+
+- Context's cite of `StatifierBlocks.Describe.outline/3`: `def outline` is
+  at `lib/statifier_blocks/describe.ex:219` (`:175`, still its line at
+  `9adc029`).
+- `lib/statifier_blocks/map/info.ex`: `def elements` is at `:198` (`:187`),
+  `def idle` at `:220` (`:209`), `defp starts` at `:242` (`:231`),
+  `defp notes` at `:286` (`:273`) and `defp findings` at `:449` (`:436`).
+- `lib/statifier_blocks/editor/map_regions.ex`: `def map_region` is at
+  `:163` (`:143`) and `def description_region` at `:227` (`:205`), the two
+  the Note of 2026-09-29 on a host's description region said would move.
+  The guard is still the file's first line.
+- `assets/js/statifier_blocks_map.js`: `export const StatifierBlocksMap` is
+  at `:801` (`:786`), and its one `this.pushEvent` at `:821` (`:806`),
+  still the only `pushEvent` in the file.
+- `lib/statifier_blocks/editor.ex`: `defp describable?` is at `:3940`
+  (`:3923`, read at `87db41f`).
+
+These have not moved since the commits that last placed them:
+`lib/statifier_blocks/map.ex`'s `def graph` (`:384`), `def caption`
+(`:447`), `defp put_band` (`:565`), `defp put_caption` (`:1019`),
+`defp timer_parties` (`:834`), `@timer_targets` (`:325`) and its aliases
+(`:305-312`); `map/info.ex`'s aliases (`:98-106`); the hook's import of the
+vendored file (`statifier_blocks_map.js:34`); `def build` and
+`defmodule Node` in `lib/statifier_blocks/view_model.ex` (`:519`, `:319`);
+`def explain` in `lib/statifier_blocks/block_type.ex` (`:1807`);
+`def core` in `lib/statifier_blocks/palette.ex` (`:206`); `package()`'s
+`files:` and `licenses:` in `mix.exs` (`:127`, `:115`); CI's
+`actions/setup-node@v4` step (`.github/workflows/ci.yml:51`); and
+`defmodule BrokenSubtree` and the test "the canvas is drawn and the
+description region is left out" in
+`test/statifier_blocks/editor/composite_expand_test.exs` (`:171`, `:468`).
+
+The Note on selection cites `hover/2` and two of its lines at `9a324a2`
+(`:666`, `:686`, `:672`) to say what the hook did before that request; those
+cites describe code that is gone and are not re-located.
+
+Filed with `sb-062y`.