Lenses / Authored composition

Give the program’s structure a readable arrangement.

The compiler knows which definitions refer to one another. The programmer knows what those definitions mean together. An authored layout supplies names, grouping and spatial placement over the checked graph. It does not change that graph.

Open the separation of concerns examples, expand “Edit this diagram’s composition”, and edit the JSON. Apply validates the layout; Download saves it for version control. The initial implementation uses a grid and an editable file. It has no drag editor or guided playback.

The layout file

schemaVersion is authored-diagram-1. title and description describe the view. columns sets one to six equal-width columns. selected optionally names the region whose relationships are initially highlighted.

regions is an ordered list. Each region has a unique id, a title, a description and a nonempty members list of exact, package-qualified definition identities from the evidence artifact. List order is reading order within each region.

{
  "id": "checks",
  "title": "Admission checks",
  "description": "The implementation reaches limits through these checks.",
  "row": 1,
  "column": 0,
  "members": [
    "Demo/Ledger::within_limits",
    "Demo/Ledger::check_lower",
    "Demo/Ledger::check_upper"
  ],
  "expanded": true
}

row and column start at zero. Optional span extends a region across adjacent columns. Regions cannot overlap. Their rows are chosen by the author; they do not assert dependency depth, execution order or architecture laws. A shared grid preserves positions across the Forum before/after pair.

expanded opens a region’s definition list initially. emphasis gives its border emphasis. Both are optional booleans. For supporting material, context: true puts the region below the canvas instead of assigning grid coordinates. Its crossing relationships remain counted at the visible endpoints and listed with their witnesses.

What a layout cannot hide

Every definition must occur in exactly one region. Unknown identities, omissions, duplicate membership, overlapping positions and unknown fields are rejected. A region must contain real definitions; a label cannot create a missing abstraction. When source changes, resolve the layout against the newly compiled artifact before drawing it.

Initially, only relationships touching the selected region are drawn. “Show all canvas relationships” reveals the remaining arrows. This changes drawing visibility only; the full relationship list remains available. Arrows bundle only equal region endpoints and relationship kinds. Each bundle retains every original relationship. Internal references, self references recorded as edges, and context relationships remain in the complete relationship list even when no arrow is drawn between two visible regions. Composition artifacts also record recursive self references on their definition nodes; inspect the original artifact for those.

Solid arrows are checked source references, including function values. Dashed arrows are declaration or matched-structure relationships; inspect a bundle for its exact kind. Neither style proves execution or permission enforcement. Region descriptions are authored explanations, not verified assertions.

Separate code changes from drawing changes

Forum’s source selector switches between repeated response assembly and the existing shared-fields refactor. The arrangement selector changes the drawing independently. In the refactor, thread_fields names a real reusable definition. A region with the same title in the original program cannot make that helper exist.

The workbench compiles edited source and runs the Forum handlers. The gallery edits presentation over recorded evidence. Its evidence download includes the exact source. Use the workbench’s shared-field, reply-only-field and record-field exercises to test whether an abstraction helps with real changes.

Keep the composition while changing the code

Apply a gallery layout, then follow its workbench link. The link carries the exact layout in its URL fragment, which is not sent to the server. In the workbench, layout.json appears beside the source files. It is presentation metadata and is never passed to the compiler. Edit it and press Apply layout, or edit the Bosatsu source and press Rebuild map. Rebuilding preserves region placement, expansion and surviving selections; it validates the layout against the new artifact.

A new, removed or renamed definition requires an explicit membership edit. The diagram stays blank with a concrete error until the layout accounts for the new source. Download layout saves the current author file. Edits stay in the current page session; refreshing reloads the recorded source and the layout carried by the original link.

Freeze before snapshot validates and saves its layout as well as its compiled artifact, including when the dependency view is selected. Repair an invalid layout before freezing. Before layout and After layout each resolve against their own snapshot. Switch to Dependency map to inspect the existing structural diff and correspondence tools.

The current Icetakes example

Open the Icetakes composition to inspect contribution intake, article retrieval, editorial roles, checked evidence, author withdrawal/control and charter-bound admission. The recorded source comes from the explicit application set in icetakes/sources.json. It covers the whole supplied definition graph; effect expansion is focused on Icetakes/CaseAdmission::admit_case. Download its source and compiler evidence.

The concern labels and positions are authored interpretation. The arrows remain checked definition references. The picture does not claim automatic successor scheduling, whole-application safety, deployed model quality, or implemented edition publication.

The reusable renderer accepts either implementation-comparison-1 or source-composition-1 evidence with a layout: mountAuthoredDiagram(host, artifact, layout, navigation). Its returned destroy() disconnects resize tracking before replacing a diagram. Rendering does not analyze source text or add semantic facts.

Return to the diagrams →