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:
ed
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?