@rse/ase 2.0.5 → 2.0.6

package/plugin/meta/ase-format-specbook.yaml

@@ -789,6 +789,9 @@
   desc: >
     The access rights of the solution, granted to the roles of the User Personas and stating for each role the operations it may perform on each entity, confined to the lifecycle states of the entity and to a further condition where necessary, so that "who may do what on which entity in which state" is answered in one place instead of being scattered over the actors of the state transitions, the actors of the use cases, and the prose of the domain rules. The model is closed: an operation not granted to a role is forbidden, exactly like a move not listed as a state transition.
   optional: true
+  coverage:
+    - "[[DM.ENTITY:*]]"
+    - "[[USE-CASE:*]]"
   children:
     - kind: PERMISSION
       desc: >
@@ -1194,6 +1197,8 @@
   desc: >
     The sequenced visual or textual depiction of a specific dialog flow, illustrating how an interaction unfolds screen by screen or turn by turn.
   optional: true
+  coverage:
+    - "[[USE-CASE:*]]"
   children:
     - kind: STORYBOARD
       desc: >
@@ -1433,6 +1438,9 @@
   desc: >
     The functional components of the solution, their responsibilities, interfaces, and primary interactions, describing *how* the solution's runtime elements are structured and which responsibility each owns, delivering the behaviors the Functional Requirements state.
   optional: true
+  coverage:
+    - "[[FR.REQUIREMENT:*]]"
+    - "[[DM.ENTITY:*]]"
   children:
     - kind: COMPONENT
       desc: >
@@ -1473,7 +1481,7 @@
           optional: true
         - name: PROVIDES
           desc: >
-            Comma-separated references to the INTERFACE-MODEL objects the component provides, i.e. through which other components and external entities interact with it; omitted when the component provides no modeled interface (e.g. a user interface or an internal module).
+            Comma-separated references to the INTERFACE-MODEL objects the component provides, i.e. through which other components and external entities interact with it, which are always `Provided` ones, as a `Required` interface is offered by an external entity instead; omitted when the component provides no modeled interface (e.g. a user interface or an internal module).
           value: list([[INTERFACE:*]])
           optional: true
         - name: CONSUMES
@@ -1487,10 +1495,150 @@
           value: list([[FV.COMPONENT:*]])
           optional: true
 
+- kind: ARCH
+  name: Runtime View
+  id: RV
+  file: 26-ARCH-RV-Runtime-View.md
+  desc: >
+    The runtime interactions of the solution: for each significant use case scenario or technical situation, the ordered messages its participants -- roles, Functionality View components, and Context View entities -- exchange, describing *how* the components collaborate at runtime to deliver the behaviors their static structure merely enables.
+  optional: true
+  coverage:
+    - "[[USE-CASE:*]]"
+    - "[[SCENARIO:*]]"
+  children:
+    - kind: INTERACTION
+      desc: >
+        A single runtime interaction, named with a short (2-5 word) summary of the situation it shows (e.g. `Ask a Question`, `Login with Token`) and described in a concise (1-3 sentence) paragraph by its trigger and its outcome, plus a 1-sentence rationale ("why") stating what the interaction makes explicit, while its MESSAGE children, in document order, are the messages its participants exchange.
+      optional: true
+      props:
+        - name: REALIZES
+          desc: >
+            Comma-separated references to the USE-CASES objects (use cases or their scenarios) the interaction realizes, tracing the runtime behavior back to the behavior the requirements state; omitted for a purely technical interaction (e.g. a startup or a failover).
+          value: list([[USE-CASE:*]], [[SCENARIO:*]])
+          optional: true
+      children:
+        - kind: MESSAGE
+          desc: >
+            A single message of the interaction, named with a short (1-4 word), per-interaction unique summary of the operation, event, or response it carries (e.g. `submit question`, `question stored`) and described by a 1-sentence description of its effect.
+          props:
+            - name: FROM
+              desc: >
+                Reference to the participant sending the message: a USER-PERSONAS role, a FUNCTIONALITY-VIEW component, or a CONTEXT-VIEW entity.
+              value: list([[ROLE:*]], [[FV.COMPONENT:*]], [[CV.ENTITY:*]])
+            - name: TO
+              desc: >
+                Comma-separated references to the participants receiving the message (several ones yielding one message each): USER-PERSONAS roles, FUNCTIONALITY-VIEW components, or CONTEXT-VIEW entities.
+              value: list([[ROLE:*]], [[FV.COMPONENT:*]], [[CV.ENTITY:*]])
+            - name: KIND
+              desc: |
+                The kind of the message, one of:
+                -   `Call`:    Synchronous request the sender waits for (the default).
+                -   `Signal`:  Asynchronous notification the sender does not wait for.
+                -   `Return`:  Response to the latest unanswered call of its receiver.
+                -   `Create`:  Instantiation of its receiver, which starts there.
+                -   `Destroy`: Termination of its receiver, which ends there.
+              value: enum(Call,Signal,Return,Create,Destroy)
+              optional: true
+            - name: DURATION
+              desc: >
+                Duration constraint of a call up to its return (e.g. `< 200ms`), drawn as a bracket beside the lifeline of the caller.
+              optional: true
+            - name: TIME
+              desc: >
+                Time constraint or observation at the start of the message (e.g. `t = now`), drawn beside the lifeline of the sender.
+              optional: true
+
+- kind: ARCH
+  name: Concurrency View
+  id: CO
+  file: 27-ARCH-CO-Concurrency-View.md
+  desc: >
+    The concurrency structure of the solution, mapping functional components to processes and threads, and defining how they coordinate and communicate. The artifact is absent when the solution runs as a single sequential unit of execution and has no concurrency structure worth describing.
+  optional: true
+  coverage:
+    - "[[FV.COMPONENT:*]]"
+  children:
+    - kind: RESOURCE
+      desc: >
+        A single coordination resource the concurrency units share, named with a short (2-5 word) summary (e.g. `Ingest Queue`, `Database Connections`, `Render Lock`) and described in a concise (1-3 sentence) paragraph by what its items are and how full it may get, plus a 1-sentence rationale ("why") for its bound.
+
+        The resources and the units form a Petri net: a resource is a place holding items (tokens), a unit a transition taking items out of the resources it names in `CONSUMES` and putting items into the resources it names in `PRODUCES`, so the analysis of the net reveals unbounded resources (missing backpressure), deadlocks, and units never or no longer able to work.
+      optional: true
+      props:
+        - name: KIND
+          desc: |
+            The kind of the coordination resource, one of:
+
+            -   `Queue`:     A buffer of work items between producers and consumers.
+            -   `Topic`:     A publish/subscribe channel delivering messages.
+            -   `Pool`:      A bounded set of reusable instances (e.g. connections).
+            -   `Mutex`:     An exclusive lock (a single token).
+            -   `Semaphore`: A counting lock (several tokens).
+          value: enum(Queue,Topic,Pool,Mutex,Semaphore)
+        - name: CAPACITY
+          desc: >
+            The maximum number of items the resource holds (e.g. a queue limit or the size of a pool), omitted for an unbounded resource.
+          value: /^[1-9][0-9]*$/
+          optional: true
+        - name: TOKENS
+          desc: >
+            The number of items the resource initially holds (e.g. the free connections of a pool or the `1` of a free mutex), omitted for none.
+          value: /^(?:0|[1-9][0-9]*)$/
+          optional: true
+    - kind: UNIT
+      desc: >
+        A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise (1-3 sentence) paragraph by how it executes and how it avoids or manages contention, races, and deadlocks (including its start order and failure/restart behavior where non-obvious), plus a 1-sentence rationale ("why") for the chosen concurrency structure.
+
+        A unit executes work at runtime: a queue or channel between units is not a unit but the coordination mechanism stated in `COORDINATION`, its contract an Interface Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element hosting a managed broker a Deployment View `Managed` node -- only the executing structure itself belongs to the Concurrency View.
+      optional: true
+      props:
+        - name: KIND
+          desc: |
+            The kind of the concurrency unit, one of:
+
+            -   `Process`:   An independent OS process with its own address space.
+            -   `Thread`:    A thread of execution within a process.
+            -   `Task`:      A lightweight cooperative task (e.g. coroutine, fiber).
+            -   `Pool`:      A managed group of interchangeable workers.
+            -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
+          value: enum(Process,Thread,Task,Pool,EventLoop)
+        - name: PART-OF
+          desc: >
+            Reference to the CONCURRENCY-VIEW object this unit is contained in, expressing the containment the kinds imply: a `Thread`, `Task`, `Pool`, or `EventLoop` references the `Process` it executes within, and a `Task` the `EventLoop` or `Pool` scheduling it; omitted for a top-level unit.
+          value: "[[UNIT:*]]"
+          optional: true
+          acyclic: true
+        - name: HOSTS
+          desc: >
+            Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside this concurrency unit; omitted when no modeled component runs inside it.
+          value: list([[FV.COMPONENT:*]])
+          optional: true
+        - name: MULTIPLICITY
+          desc: >
+            How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n auto-scaled`).
+        - name: COORDINATES-WITH
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW objects this unit coordinates or communicates with at runtime, naming the peer unit only (e.g. a producer names the consumer it feeds through a shared queue), while the mechanism is stated by `COORDINATION`.
+          value: list([[UNIT:*]])
+          optional: true
+        - name: COORDINATION
+          desc: >
+            The mechanism by which the unit coordinates or communicates with other units, usually those referenced in `COORDINATES-WITH` (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
+        - name: CONSUMES
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW resources the unit takes work items or instances out of (e.g. the queue it drains, the pool it takes a connection from), modeling the unit as a transition of the Petri net its resources form; omitted when it consumes from none.
+          value: list([[RESOURCE:*]])
+          optional: true
+        - name: PRODUCES
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW resources the unit puts work items or freed instances into (e.g. the queue it feeds, the pool it returns a connection to); omitted when it produces into none.
+          value: list([[RESOURCE:*]])
+          optional: true
+
 - kind: ARCH
   name: Technology Stack
   id: TS
-  file: 26-ARCH-TS-Technology-Stack.md
+  file: 28-ARCH-TS-Technology-Stack.md
   desc: >
     The concrete technology products the solution is built upon, organized by tier and lifecycle phase, recording for each component its chosen product, its purpose, and the alternatives that were considered but not chosen.
   optional: true
@@ -1764,7 +1912,7 @@
 - kind: ARCH
   name: Development Aspects
   id: DA
-  file: 27-ARCH-DA-Development-Aspects.md
+  file: 29-ARCH-DA-Development-Aspects.md
   desc: >
     The architecture supporting the software development process, defining the module organization, build approach, and codeline conventions. The artifact is absent when the development conventions are governed outside the specification (e.g. by repository-level contributor instructions).
   optional: true
@@ -1786,61 +1934,15 @@
           value: list([[MAXIM:*]], [[AT.PRINCIPLE:*]])
           optional: true
 
-- kind: ARCH
-  name: Concurrency View
-  id: CO
-  file: 28-ARCH-CO-Concurrency-View.md
-  desc: >
-    The concurrency structure of the solution, mapping functional components to processes and threads, and defining how they coordinate and communicate. The artifact is absent when the solution runs as a single sequential unit of execution and has no concurrency structure worth describing.
-  optional: true
-  children:
-    - kind: UNIT
-      desc: >
-        A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise (1-3 sentence) paragraph by how it executes and how it avoids or manages contention, races, and deadlocks (including its start order and failure/restart behavior where non-obvious), plus a 1-sentence rationale ("why") for the chosen concurrency structure.
-
-        A unit executes work at runtime: a queue or channel between units is not a unit but the coordination mechanism stated in `COORDINATION`, its contract an Interface Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element hosting a managed broker a Deployment View `Managed` node -- only the executing structure itself belongs to the Concurrency View.
-      optional: true
-      props:
-        - name: KIND
-          desc: |
-            The kind of the concurrency unit, one of:
-
-            -   `Process`:   An independent OS process with its own address space.
-            -   `Thread`:    A thread of execution within a process.
-            -   `Task`:      A lightweight cooperative task (e.g. coroutine, fiber).
-            -   `Pool`:      A managed group of interchangeable workers.
-            -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
-          value: enum(Process,Thread,Task,Pool,EventLoop)
-        - name: PART-OF
-          desc: >
-            Reference to the CONCURRENCY-VIEW object this unit is contained in, expressing the containment the kinds imply: a `Thread`, `Task`, `Pool`, or `EventLoop` references the `Process` it executes within, and a `Task` the `EventLoop` or `Pool` scheduling it; omitted for a top-level unit.
-          value: "[[UNIT:*]]"
-          optional: true
-          acyclic: true
-        - name: HOSTS
-          desc: >
-            Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside this concurrency unit; omitted when no modeled component runs inside it.
-          value: list([[FV.COMPONENT:*]])
-          optional: true
-        - name: MULTIPLICITY
-          desc: >
-            How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n auto-scaled`).
-        - name: COORDINATES-WITH
-          desc: >
-            Comma-separated references to the CONCURRENCY-VIEW objects this unit coordinates or communicates with at runtime, naming the peer unit only (e.g. a producer names the consumer it feeds through a shared queue), while the mechanism is stated by `COORDINATION`.
-          value: list([[UNIT:*]])
-          optional: true
-        - name: COORDINATION
-          desc: >
-            The mechanism by which the unit coordinates or communicates with other units, usually those referenced in `COORDINATES-WITH` (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
-
 - kind: ARCH
   name: Deployment View
   id: DV
-  file: 29-ARCH-DV-Deployment-View.md
+  file: 30-ARCH-DV-Deployment-View.md
   desc: >
     The environment into which the solution is deployed, partitioning it into tiers and mapping software elements to the runtime platform, hardware, and network topology.
   optional: true
+  coverage:
+    - "[[UNIT:*]]"
   children:
     - kind: TIER
       desc: >
@@ -1870,6 +1972,27 @@
 
         An area is a logically distinct, domain-induced partition of the solution deployed as physical units of its own, the *vertical* split when drawn (a `TIER` is the *horizontal*, technology-induced one): a node dedicated to the area references it via its `AREA`, a node shared by several areas references none, and a domain grouping without deployment units of its own is a Functionality View `Subsystem` instead. The kind is absent when the solution is not split vertically.
       optional: true
+    - kind: NETWORK
+      desc: >
+        A single network segment the deployment nodes are attached to, named with a short (2-5 word) summary (e.g. `Public Internet`, `Backend VLAN`, `Database Subnet`) and described in a concise (1-3 sentence) paragraph by its reach, its isolation from the other segments, and the traffic it carries, plus a 1-sentence rationale ("why") for the segmentation.
+
+        A segment is the medium the nodes communicate over: the attached nodes reference it via `NETWORKS`, the directed links between them are their `CONNECTS-TO` references, and the contract of the carried traffic is an Interface Model interface -- only the network itself belongs here. The kind is absent when the topology has no segmentation worth describing.
+      optional: true
+      props:
+        - name: SCOPE
+          desc: |
+            The reach of the segment, one of:
+            -   `Public`:   Reachable from the Internet.
+            -   `Private`:  Reachable from the solution's own nodes only.
+            -   `Isolated`: Reachable from selected nodes only (e.g. a database subnet).
+          value: enum(Public,Private,Isolated)
+        - name: PROTOCOLS
+          desc: >
+            The protocols and ports carried by the segment (e.g. `HTTPS 443, WSS 443`, `HTTP, WS, TCP 5432`).
+        - name: ADDRESSING
+          desc: >
+            The address range or naming of the segment (e.g. `10.0.0.0/8`, `public IPv4 and IPv6`, `*.example.com`).
+          optional: true
     - kind: NODE
       desc: >
         A single deployment node, named with a short (2-5 word) summary (e.g. `Web Servers`, `Database Cluster`, `Edge CDN`) and described in a concise (1-3 sentence) paragraph by the node, its sizing, and its place in the deployment topology, plus a 1-sentence rationale ("why") for the node's placement and platform choice.
@@ -1925,32 +2048,11 @@
             Comma-separated references to the DEPLOYMENT-VIEW network segments the node is attached to (e.g. a public ingress and a private backend network); omitted when the topology models no network segments.
           value: list([[NETWORK:*]])
           optional: true
-    - kind: NETWORK
-      desc: >
-        A single network segment the deployment nodes are attached to, named with a short (2-5 word) summary (e.g. `Public Internet`, `Backend VLAN`, `Database Subnet`) and described in a concise (1-3 sentence) paragraph by its reach, its isolation from the other segments, and the traffic it carries, plus a 1-sentence rationale ("why") for the segmentation.
-
-        A segment is the medium the nodes communicate over: the attached nodes reference it via `NETWORKS`, the directed links between them are their `CONNECTS-TO` references, and the contract of the carried traffic is an Interface Model interface -- only the network itself belongs here. The kind is absent when the topology has no segmentation worth describing.
-      optional: true
-      props:
-        - name: SCOPE
-          desc: |
-            The reach of the segment, one of:
-            -   `Public`:   Reachable from the Internet.
-            -   `Private`:  Reachable from the solution's own nodes only.
-            -   `Isolated`: Reachable from selected nodes only (e.g. a database subnet).
-          value: enum(Public,Private,Isolated)
-        - name: PROTOCOLS
-          desc: >
-            The protocols and ports carried by the segment (e.g. `HTTPS 443, WSS 443`, `HTTP, WS, TCP 5432`).
-        - name: ADDRESSING
-          desc: >
-            The address range or naming of the segment (e.g. `10.0.0.0/8`, `public IPv4 and IPv6`, `*.example.com`).
-          optional: true
 
 - kind: ARCH
   name: Operations View
   id: OV
-  file: 30-ARCH-OV-Operations-View.md
+  file: 31-ARCH-OV-Operations-View.md
   desc: >
     The way the solution is operated, administered, and supported in production, defining the standing procedures by which the operating organization installs, configures, migrates, observes, protects, upgrades, scales, and supports the running solution.
   optional: true
@@ -2012,7 +2114,7 @@
 - kind: ARCH
   name: Quality Perspectives
   id: QP
-  file: 31-ARCH-QP-Quality-Perspectives.md
+  file: 32-ARCH-QP-Quality-Perspectives.md
   desc: >
     How the Non-Functional Requirements (NR) are addressed by the architecture, through the tactics built into the solution across the views.
   optional: true
@@ -2070,7 +2172,7 @@
 - kind: ARCH
   name: Design Decisions
   id: DD
-  file: 32-ARCH-DD-Design-Decisions.md
+  file: 33-ARCH-DD-Design-Decisions.md
   desc: >
     The major decisions related to the solution design, each recording the forces at play, the chosen response, and the reasoning that justifies it. The artifact is the last decision-level one of the architecture, as a decision references the requirements forcing it, the elements it shapes, and the tactics and products it chose, all of which precede it, while the Code Patterns following it reference the decisions they implement.
   optional: true
@@ -2257,7 +2359,7 @@
 - kind: ARCH
   name: Code Patterns
   id: CP
-  file: 33-ARCH-CP-Code-Patterns.md
+  file: 34-ARCH-CP-Code-Patterns.md
   desc: >
     The implementation patterns the source code of the solution follows, each prescribing how one recurring concern (e.g. authorization enforcement, entity persistence, error propagation) is coded and showing it as a code listing. The artifact follows the Design Decisions, as a pattern is the coded form of the tactics and decisions preceding it, and is absent when the coding conventions are governed outside the specification (e.g. by repository-level contributor instructions).
   optional: true
@@ -2304,7 +2406,7 @@
 - kind: TEST
   name: Test Cases
   id: TC
-  file: 34-TEST-TC-Test-Cases.md
+  file: 35-TEST-TC-Test-Cases.md
   desc: >
     The verifiable conditions and steps used to confirm that requirements, domain rules, use case scenarios, state transitions, and the mechanisms, procedures, and decisions of the architecture are correctly implemented, with mandatory defined inputs, mandatory expected outcomes, and optional pre- and post-conditions. The artifact is the last one, as a test case verifies objects of every preceding kind.
 

package/plugin/mods/ase-mods-common.ts

@@ -5,11 +5,12 @@
 */
 
 /*  Claude Code function hooks module ("mod", EARLY ACCESS):
-    Common parts, shared by the grill table, the intent help, the synopsis
-    form, the manual band, the manpage browser, and the hint band: the styled
-    characters of the terminal drawing, their Markdown conversion, wrapping,
-    and framing, and the contract, keys, geometry, and drawing of the
-    master/detail view in the band above the prompt.  */
+    Common parts, shared by the grill table, the decision matrix, the intent
+    help, the synopsis form, the manual band, the manpage browser, and the hint
+    band: the rows of the Markdown tables, the styled characters of the terminal
+    drawing, their Markdown conversion, wrapping, and framing, and the contract,
+    keys, geometry, and drawing of the master/detail view in the band above the
+    prompt.  */
 
 import type { Elements, Frozen, MatchedEvent, ModelCompleteRequest, ModelForkResult,
     PromptBox, PromptEditInput, PromptFilled, RenderElement } from "claude-code"
@@ -100,6 +101,35 @@ export const decode = (e: Frozen<PromptEditInput>): Key => {
     }
 }
 
+/*  a row and the delimiter row of a Markdown table  */
+export const ROW  = /^ *\|.*\| *$/
+export const RULE = /^ *\|(?: *:?-+:? *\|)+ *$/
+
+/*  split a Markdown table row into its cells  */
+export const cells = (line: string): string[] => {
+    const result: string[] = []
+    const body = line.trim().replace(/^\|/, "").replace(/\|$/, "")
+    let cell = ""
+    let code = false
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i]!
+        if (ch === "`")
+            code = !code
+        if (!code && ch === "\\" && body[i + 1] === "|") {
+            cell += "|"
+            i++
+        }
+        else if (!code && ch === "|") {
+            result.push(cell.trim())
+            cell = ""
+        }
+        else
+            cell += ch
+    }
+    result.push(cell.trim())
+    return result
+}
+
 /*  a single styled character of the terminal drawing  */
 export type Char = { ch: string, bold: boolean, color: string | undefined }
 
@@ -214,7 +244,7 @@ export const uniform = (text: string, bold: boolean, color: string | undefined):
     Array.from(text, (ch) => ({ ch, bold, color }))
 
 /*  strip the single-asterisk emphasis outside the code spans of inline Markdown  */
-const strip = (text: string): string =>
+export const strip = (text: string): string =>
     text.split("`").map((part, i) => i % 2 === 0 ? part.replace(/(?<!\*)\*(?!\*)/g, "") : part).join("`")
 
 /*  convert the Markdown blocks of a manual page section (paragraphs, list items,

package/plugin/mods/ase-mods-evaluate.ts

@@ -0,0 +1,227 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+
+/*  Claude Code function hooks module ("mod", EARLY ACCESS):
+    Decision matrix, redrawing the weighted decision matrices of the
+    "ase-meta-evaluate" skill as a grid and rendering in blue and bold the
+    column of the best alternative (resp. of all tied best ones). Its
+    header cells are clickable and sort the criteria rows by their column
+    (cycling the primary, the reverse, and the original order), while the
+    rating row stays the last one.  */
+
+import type { Elements, Frozen, MatchedEvent, RenderElement } from "claude-code"
+import { type Engine, type Char, ROW, RULE, cells, strip, style, width, wrap, split, paint } from "./ase-mods-common.ts"
+
+/*  the marker line above a decision matrix  */
+const MARKER = /\*{0,2}EVALUATION\*{0,2}:\s+\*{0,2}Weighted Multi-Criteria Decision Matrix/
+
+/*  the color of the best alternatives, and the rating distance (relative to
+    the best rating) below which alternatives tie (as in "ase-meta-evaluate")  */
+const WINNER = "blue"
+const TIE    = 0.01
+
+/*  the sort marks of the orders (each taking the same columns)  */
+const MARK = { desc: " ▼", asc: " ▲", none: "  " } as const
+
+/*  the indent of the wrapped lines of a criterion, the narrowest criteria
+    column, and the size limit of a single "Markdown" element  */
+const INDENT = 2
+const NARROW = 12
+const LIMIT  = 10000
+
+/*  a decision matrix with the Markdown text before and after it: its header
+    cells, its criteria rows (with the values of their weight and evaluations),
+    its rating row, and the columns of the best alternatives  */
+type Matrix = {
+    before:  string,
+    after:   string,
+    header:  string[],
+    rows:    { cells: string[], values: number[] }[],
+    rating:  string[],
+    winners: Set<number>
+}
+
+/*  the sort of a matrix: the sorted column and its order  */
+type Order = "desc" | "asc"
+type Sort  = { column: number, order: Order }
+
+/*  read the number of a cell (without bold markup and a leading plus sign)  */
+const number = (cell: string): number => {
+    const text = cell.replace(/\*/g, "").trim().replace(/^\+/, "")
+    return text !== "" ? Number(text) : NaN
+}
+
+/*  parse the decision matrix out of the text of a reply  */
+const parse = (text: string): Matrix | undefined => {
+    const lines = text.split("\n")
+    const m = lines.findIndex((line) => MARKER.test(line))
+    const h = lines.findIndex((line, i) => m !== -1 && i > m && ROW.test(line))
+    if (h === -1 || !RULE.test(lines[h + 1] ?? ""))
+        return undefined
+    const header = cells(lines[h]!).map((cell) => cell.replace(/\*/g, ""))
+    if (header.length < 3 || !/Criteria/.test(header[0]!) || !/Weight/.test(header[1]!))
+        return undefined
+    let end = h + 2
+    while (end < lines.length && ROW.test(lines[end]!))
+        end++
+    const rows   = lines.slice(h + 2, end).map((line) => cells(line))
+    const rating = rows.pop() ?? []
+    if (rows.length === 0 || rows.some((row) => row.length !== header.length)
+        || rating.length !== header.length || rating[0]!.replace(/\*/g, "") !== "RATING")
+        return undefined
+    const values  = rows.map((row) => row.slice(1).map(number))
+    const ratings = rating.slice(2).map(number)
+    if ([ ...values.flat(), ...ratings ].some((value) => !Number.isFinite(value)))
+        return undefined
+    const best = Math.max(...ratings)
+    return {
+        before:  lines.slice(0, h).join("\n").trim(),
+        after:   lines.slice(end).join("\n").replace(/^\n+/, "").trimEnd(),
+        header,
+        rows:    rows.map((row, k) => ({ cells: row, values: values[k]! })),
+        rating,
+        winners: new Set(ratings.flatMap((value, j) =>
+            value === best || best - value < TIE * Math.abs(best) ? [ j + 2 ] : []))
+    }
+}
+
+/*  advance the sort by a clicked column: its primary order (ascending for
+    the criteria names, descending for the values), then its reverse order,
+    and then the original order again  */
+const advance = (sort: Sort | undefined, column: number): Sort | undefined => {
+    const primary: Order = column === 0 ? "asc"  : "desc"
+    const reverse: Order = column === 0 ? "desc" : "asc"
+    if (sort?.column !== column)
+        return { column, order: primary }
+    return sort.order === primary ? { column, order: reverse } : undefined
+}
+
+/*  order the criteria rows by the sort (stable, so equal rows keep their original order)  */
+const order = (rows: Matrix["rows"], sort: Sort | undefined): Matrix["rows"] => {
+    if (sort === undefined)
+        return rows
+    const sign = sort.order === "asc" ? 1 : -1
+    return [ ...rows ].sort((a, b) => sign * (sort.column === 0 ?
+        strip(a.cells[0]!).localeCompare(strip(b.cells[0]!)) :
+        a.values[sort.column - 1]! - b.values[sort.column - 1]!))
+}
+
+/*  the decision matrix: its state and its operations  */
+export const modEvaluate = () => {
+    /*  the last known width of the terminal and the sorts of the matrices  */
+    let columns = 80
+    const sorts = new Map<string, Sort>()
+
+    /*  sort the criteria rows of a matrix by a clicked header cell and redraw it  */
+    const press = (engine: Pick<Engine, "invalidate">, request: string, column: number) => () => {
+        const sort = advance(sorts.get(request), column)
+        if (sort !== undefined)
+            sorts.set(request, sort)
+        else
+            sorts.delete(request)
+        engine.invalidate()
+    }
+
+    /*  redraw a reply which contains a decision matrix (terminal only),
+        resp. draw nothing for any other reply  */
+    const render = (e: Frozen<MatchedEvent<"ui.render", { component: "AssistantMessage", surface: "terminal" }>>,
+        ui: Elements["terminal"], engine: Pick<Engine, "invalidate">): RenderElement | undefined => {
+        /*  act on decision matrices only  */
+        columns = e.viewport?.columns ?? columns
+        const matrix = parse(e.props.text)
+        if (matrix === undefined || matrix.before.length > LIMIT || matrix.after.length > LIMIT)
+            return undefined
+
+        /*  style the cells: the header ones in bold, the criteria rows in their sort
+            order, and the columns of the best alternatives in blue and bold  */
+        const sort = sorts.get(e.requestId)
+        const tint = (chars: Char[], column: number): Char[] =>
+            matrix.winners.has(column) ? chars.map((char) => ({ ...char, bold: true, color: WINNER })) : chars
+        const head = matrix.header.map((cell, c) => tint(style(`**${cell}**`, undefined), c))
+        const body = [ ...order(matrix.rows, sort).map((row) => row.cells), matrix.rating ]
+            .map((row) => row.map((cell, c) => tint(style(c === 0 ? strip(cell) : cell, undefined), c)))
+
+        /*  determine the column widths: the value columns at their natural width
+            (the header cells with room for the sort mark), the criteria column
+            within the remaining columns (gutter, grid lines, cell paddings, and a
+            spare column subtracted), else leave the matrix to the engine  */
+        const widths = head.map((cell, c) =>
+            Math.max(width(cell) + MARK.none.length, ...body.map((row) => width(row[c]!))))
+        const avail  = columns - 2 - (3 * head.length + 1) - 1 - widths.slice(1).reduce((sum, w) => sum + w, 0)
+        if (avail < Math.max(NARROW, width(head[0]!) + MARK.none.length))
+            return undefined
+        widths[0] = Math.min(widths[0]!, avail)
+
+        /*  resolve the UI elements  */
+        const { Box, Text, Button, Markdown } = ui
+
+        /*  pad the parts of a cell line of the given width to its column width:
+            left-aligned for the criteria, right-aligned for the values  */
+        const align = <T>(c: number, used: number, parts: T[]): (T | string)[] => {
+            const pad = " ".repeat(Math.max(0, widths[c]! - used))
+            return c === 0 ? [ ...parts, pad ] : [ pad, ...parts ]
+        }
+
+        /*  draw a header cell: its styled text inside a hover-scoping box, which while
+            hovered reveals a row of clickable plain buttons (one per styled run, as in
+            the grill table) on top of it, followed by its sort mark  */
+        const heading = (c: number): RenderElement[] => {
+            const group   = `h${c}`
+            const onPress = press(engine, e.requestId, c)
+            const buttons = split(head[c]!).map(({ text, bold }, r) =>
+                Button({ key: `${group}/${r}`, label: text, plain: true, onPress,
+                    hover: { scope: group, inverse: true, bold } }))
+            return align(c, width(head[c]!) + MARK.none.length, [
+                Box({ key: group, hover: { scope: group }, children: [
+                    Text({ children: paint(Text, head[c]!) }),
+                    Box({ position: "absolute", top: 0, left: 0, display: "none",
+                        hover: { scope: group, display: "flex" }, flexDirection: "row", children: buttons })
+                ] }),
+                Text({ children: sort?.column === c ? MARK[sort.order] : MARK.none })
+            ]).map((part) => typeof part === "string" ? Text({ children: part }) : part)
+        }
+
+        /*  draw a line of the grid out of the parts of its cells, resp. a rule  */
+        const draw = (parts: RenderElement[][]) => Box({ flexDirection: "row", children: [
+            Text({ children: "│ " }),
+            ...parts.flatMap((part, c) => c > 0 ? [ Text({ children: " │ " }), ...part ] : part),
+            Text({ children: " │" })
+        ] })
+        const rule = (l: string, m: string, r: string) =>
+            Text({ wrap: "truncate-end", children: l + widths.map((w) => "─".repeat(w + 2)).join(m) + r })
+
+        /*  draw the matrix as a grid: a rule below the header and above the rating
+            row, and the criteria wrapped within their column  */
+        const grid: RenderElement[] = [
+            rule("┌", "┬", "┐"),
+            draw(head.map((_, c) => heading(c))),
+            rule("├", "┼", "┤")
+        ]
+        body.forEach((row, k) => {
+            if (k === body.length - 1)
+                grid.push(rule("├", "┼", "┤"))
+            wrap(row[0]!, widths[0]!, INDENT).forEach((line, i) =>
+                grid.push(draw(row.map((cell, c) => {
+                    const chars = c === 0 ? line : i === 0 ? cell : []
+                    return [ Text({ children: align(c, width(chars), paint(Text, chars)) }) ]
+                }))))
+        })
+        grid.push(rule("└", "┴", "┘"))
+
+        /*  mimic the reply row of the engine: blank row above and bullet gutter  */
+        return Box({ flexDirection: "row", marginTop: 1, width: "100%", children: [
+            Box({ flexShrink: 0, minWidth: 2, children: Text({ children: e.props.isFirstOfReply ? "⏺" : " " }) }),
+            Box({ flexDirection: "column", flexGrow: 1, flexShrink: 1, children: [
+                ...(matrix.before !== "" ? [ Markdown({ text: matrix.before }) ] : []),
+                Box({ flexDirection: "column", marginTop: matrix.before !== "" ? 1 : 0, children: grid }),
+                ...(matrix.after !== "" ? [ Box({ marginTop: 1, children: Markdown({ text: matrix.after }) }) ] : [])
+            ] })
+        ] })
+    }
+
+    return { render }
+}
+