ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(ssdl): rename SSDL shape symbols to concise form (o->, o=>)

Browse Source 
Final vocabulary:
- ===>        -> ->        (codepath)
- ===>W===>  -> =>        (wide codepath)
- o==>       -> o->       (codecycle)
- oo==>oo    -> o=>       (wide codecycle)
- ===>B===>  -> ->B->     (codepath with branch)
- ===>M===>  -> ->M->     (codepath with merge)

Composites ===>B===> and ===>M===> preserved as ->B->/->M-> so the
branch/merge markers stay visible (vs. dropping them entirely).

Scope: 3 reports files (computational_shapes_ssdl_digest,
proposed_new_tracks, session_synthesis), 4 intent_dsl_survey files
(plan, report, report_v1.1, report_v1.2), 3 nagent_review files
(state.toml description, v2_2, v2_3). All old symbols verified gone
via grep; all new symbols verified present at expected locations.
This commit is contained in:
Edward R. Gonzalez
2026-06-12 12:52:20 -04:00
parent dff97b15c3
commit c4085319ff
10 changed files with 740 additions and 738 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reports/computational_shapes_ssdl_digest_20260608.md
+20 -20
View File
@@ -38,10 +38,10 @@ A *computation shape* is a high-level concept, not a physical thing. The diagram
| # | Shape | One-line definition | SSDL symbol |
|---|---|---|---|
| 1 | **Instruction** | A single unit of computation. Reads data, writes data, or both. | `[I]` |
| 2 | **Codepath** | A sequential list of instructions that *terminates*. No loops. | `===>` |
| 3 | **Wide codepath** | A codepath whose execution *causes* several other codepaths to occur simultaneously. | `===>W===>` (codepaths fan out) |
| 4 | **Codecycle** | A circular structure — a codepath that *repeats* at its first instruction after its last. | `o==>` (arrow returns to start) |
| 5 | **Wide codecycle** | Multiple codecycles performing the same task simultaneously. | `oo==>oo` (parallel cycles) |
| 2 | **Codepath** | A sequential list of instructions that *terminates*. No loops. | `->` |
| 3 | **Wide codepath** | A codepath whose execution *causes* several other codepaths to occur simultaneously. | `=>` (codepaths fan out) |
| 4 | **Codecycle** | A circular structure — a codepath that *repeats* at its first instruction after its last. | `o->` (iterator with path) |
| 5 | **Wide codecycle** | Multiple codecycles performing the same task simultaneously. | `o=>` (parallel cycles) |
| 6 | **Codecycle graph** | Multiple codecycles + the data they read and write. | `boxes + arrows` |
**Modifiers** (not shapes, but used to annotate them):
@@ -59,19 +59,19 @@ A *computation shape* is a high-level concept, not a physical thing. The diagram
**Legend**:
```
[I] = single instruction
===> = codepath (linear, terminates at T)
===>W===> = wide codepath (causes parallel codepaths)
o==> = codecycle (loops back to start)
oo==>oo = wide codecycle (parallel codecycles doing the same task)
[T] = terminator (return/exit)
[B] = branch (if/else/switch)
[M] = merge (control flow reconverges)
[S] = state mutation
[Q] = state query
[N] = nil sentinel (defuses branches)
─── = data (read or write)
[•] = codepath that is *defused* (collapses to 1 effective codepath)
[I] = single instruction
-> = codepath (linear, terminates at T)
=> = wide codepath (causes parallel codepaths)
o-> = codecycle (loops back to start)
o=> = wide codecycle (parallel codecycles doing the same task)
[T] = terminator (return/exit)
[B] = branch (if/else/switch)
[M] = merge (control flow reconverges)
[S] = state mutation
[Q] = state query
[N] = nil sentinel (defuses branches)
─── = data (read or write)
[•] = codepath that is *defused* (collapses to 1 effective codepath)
```
---
@@ -242,7 +242,7 @@ USER CODE: SUBSYSTEM:
[T]
```
The user's code is now `===> [T]` (one straight line, one terminator). The subsystem absorbed the branches. **The number of *user-visible* effective codepaths went from 4 to 1.** The total number of codepaths in the program didn't decrease — but the *exposed surface area* did, and that's what matters for the caller's cognitive load, testing burden, and bug surface.
The user's code is now `-> [T]` (one straight line, one terminator). The subsystem absorbed the branches. **The number of *user-visible* effective codepaths went from 4 to 1.** The total number of codepaths in the program didn't decrease — but the *exposed surface area* did, and that's what matters for the caller's cognitive load, testing burden, and bug surface.
#### Technique 4: Immediate-mode API (collapses "did I create/destroy this?" to "no, it's managed for me")
@@ -478,8 +478,8 @@ The 6 primitives + 7 modifiers are enough to sketch any computational shape. The
1. **Top to bottom is time** (instructions happen in order, top first).
2. **`[B]` branches fan out, `[M]` merges reconverge** (control flow).
3. **`[N]` collapses a branch** (the branch exists in the subsystem but not in the user's codepath).
4. **`o==>` means "this is the main loop, it repeats forever"** (codecycle).
5. **`===>W===>` means "this codepath causes parallelism"** (wide).
4. **`o->` means "this is the main loop, it repeats forever"** (codecycle).
5. **`=>` means "this codepath causes parallelism"** (wide).
6. **A subsystem that returns a value valid in all cases** is a black box that the user never has to inspect.
When sketching a feature, *start* with the user's codepath. If it has branches, the question is: "where does the branch live, in user code or in a subsystem?" If the answer is "in a subsystem," sketch the subsystem separately. If the answer is "in user code," *reconsider* — is there a way to push it into a subsystem?
docs/reports/proposed_new_tracks_20260608.md
+1 -1
View File
@@ -31,7 +31,7 @@
# Replace the existing "review UX" approach with the ASCII-sketch workflow
# documented in docs/reports/ascii_sketch_ux_workflow_20260608.md
method = "ASCII-sketch + MiniMax understand_image verification"
vocabulary = "[I], ===>, o==>, [B], [M], [S], [Q], [N], --" # 6 primitives + 7 modifiers
vocabulary = "[I], ->, o->, [B], [M], [S], [Q], [N], --" # 6 primitives + 7 modifiers
first_target = "Discussion Hub per-entry panel" # gui_2.py:3770
source_of_truth = "docs/guide_discussions.md §Per-Entry Operations (A1-A7 matrix)"
docs/reports/session_synthesis_20260608.md
+1 -1
View File
@@ -222,7 +222,7 @@ Each got ~4 surgical spec edits + See Also cross-references. No plan/task change
### The 5 open questions the report surfaces
1. **Vocabulary preference** — the §2 vocabulary (`[I]`, `===>`, `o==>`, etc.) is a proposal. Alternatives: box-drawing characters (`┌─┐│└─┘`) for more ASCII-art look; Markdown tables for tabular content; hybrid (ASCII boxes for layout, tables for tabular data).
1. **Vocabulary preference** — the §2 vocabulary (`[I]`, `->`, `o->`, etc.) is a proposal. Alternatives: box-drawing characters (`┌─┐│└─┘`) for more ASCII-art look; Markdown tables for tabular content; hybrid (ASCII boxes for layout, tables for tabular data).
2. **Comparison policy** — after locking a design, do we always verify with `MiniMax understand_image` (slow but accurate)? Only when the design uses color/custom drawing? Only when the implementing Tier-3 reports a mismatch?