Skip to content

Commit 4b136ba

Browse files
frankhaugenfrankhaugen
committed
docs: spread docs-for-spreading into topic pages and sync checklist
Move mission, design principles, pipeline boundaries, lowering, IL set, built-ins/world contracts, and spec order into dedicated docs. Replace docs-for-spreading with a redirect and mapping tables. Update README, architecture, lessons index, and documentation-todo. Made-with: Cursor
1 parent 46fe439 commit 4b136ba

15 files changed

Lines changed: 536 additions & 12 deletions

‎RoboSharp.slnx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<File Path="docs/build.md" />
66
<File Path="docs/docs-for-spreading.md" />
77
<File Path="docs/documentation-todo.md" />
8+
<File Path="docs/implementation-gaps.md" />
89
<File Path="docs/nuget.md" />
910
<File Path="docs/repository-layout.md" />
1011
</Folder>
@@ -27,6 +28,7 @@
2728
<File Path="docs/architecture/dependency-rules.md" />
2829
<File Path="docs/architecture/io-abstractions.md" />
2930
<File Path="docs/architecture/io-workspace-overview.md" />
31+
<File Path="docs/architecture/pipeline-boundaries.md" />
3032
<File Path="docs/architecture/runtime-hosts.md" />
3133
<File Path="docs/architecture/solution-structure.md" />
3234
<File Path="docs/architecture/workspace-model.md" />
@@ -38,6 +40,7 @@
3840
<File Path="docs/compiler/lexical-analysis.md" />
3941
<File Path="docs/compiler/parsing.md" />
4042
<File Path="docs/compiler/semantic-analysis.md" />
43+
<File Path="docs/compiler/syntax-to-il-lowering.md" />
4144
<File Path="docs/compiler/syntax-tree.md" />
4245
</Folder>
4346
<Folder Name="/docs/debugger/">

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ The **authoritative** rules for architecture, dependencies, and agent behavior l
1313
| [Repository layout](repository-layout.md) | Solution structure, projects, and dependency direction |
1414
| [NuGet and packages](nuget.md) | Central package management, allowed packages, feed policy |
1515
| [Architecture overview](architecture.md) | High-level pipeline and layer responsibilities (summary only) |
16+
| [Mission (teaching goals)](governance/mission.md) | Why RoboSharp exists; links to design principles |
17+
| [Pipeline boundaries](architecture/pipeline-boundaries.md) | Syntax, semantics, IL, world, built-in contracts (end-to-end model) |
1618
| [IO layer](io/README.md) | `RoboSharp.IO`: filesystem abstractions, physical/in-memory/overlay |
1719
| [Workspaces](workspaces/README.md) | `RoboSharp.Workspaces`: projects, sessions, artifacts on top of IO |
1820
| [IO ↔ workspace boundary](architecture/io-workspace-overview.md) | How IO and workspaces divide responsibility (start here) |
@@ -23,6 +25,7 @@ The **authoritative** rules for architecture, dependencies, and agent behavior l
2325
| [Lessons, goals, and content packs](lessons/README.md) | Profiles, goals, lesson definitions, packs, JSON direction (`docs/lessons/`) |
2426
| [RoboSharp.Player](player/README.md) | Compiled-artifact host; lesson run mode (`docs/player/`) |
2527
| [RoboSharp Studio](studio/README.md) | IDE host specifications (topic index; former `general-specs.md`) |
28+
| [Implementation gaps](implementation-gaps.md) | What is specified vs implemented in `src/` (missing pipeline, hosts, lessons) |
2629
| [Documentation stubs — fill order](documentation-todo.md) | Checklist and suggested sequence for authoring the skeleton below |
2730
| [Agent workflows](agents/README.md) | Repeatable agent tasks (e.g. syncing the documentation checklist with `tools/doc-checklist.ps1`) |
2831

‎docs/architecture.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,10 @@ Source
3131

3232
## Where to go next
3333

34+
- Pipeline ownership (syntax, semantics, IL, world, built-ins): [Pipeline boundaries](architecture/pipeline-boundaries.md)
3435
- Policy and testing philosophy: [`AGENTS.md`](../AGENTS.md)
3536
- Language vs semantics detail: [RoboSharp.Language](language/README.md), [RoboSharp.Semantics](semantics/README.md)
3637
- Teaching layer (profiles, goals, lessons, packs): [Lessons and content](lessons/README.md)
38+
- Spec vs `src/` (missing pipeline and features): [Implementation gaps](implementation-gaps.md)
3739
- Building and artifacts: [Build and test](build.md)
3840
- Packages: [NuGet and packages](nuget.md)

‎docs/architecture/pipeline-boundaries.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Pipeline boundaries — who owns what
2+
3+
This document **freezes responsibility** between syntax, semantics, IL, world, and built-ins so implementations stay aligned. It generalizes ideas from the teaching mission; see [governance/mission.md](../governance/mission.md).
4+
5+
## End-to-end interaction model
6+
7+
```text
8+
Syntax
9+
↓
10+
Bound semantic form
11+
↓
12+
IL lowering
13+
↓
14+
Interpreter dispatch
15+
↓
16+
Built-in runtime handler (or user function body)
17+
↓
18+
RobotWorld mutation (when applicable)
19+
↓
20+
Snapshot / render projection
21+
```
22+
23+
The interpreter is a **plain C# state machine** over fake IL, not CLR emission. Built-ins run as handlers against execution state and world contracts.
24+
25+
## The key rule: syntax does not talk to the world
26+
27+
Syntax expresses declarations, statements, expressions, and **calls**. The parser does **not** know about lessons, profiles, or grid state.
28+
29+
- `move()` parses as a normal **call expression**.
30+
- **Semantic analysis** decides whether `move` resolves to a user function or a profile **built-in**.
31+
- **IL generation** emits **`Call`** for user functions or **`CallBuiltin`** for built-ins (see below).
32+
- **Runtime** dispatches to the handler, which may mutate **`RobotWorld`**.
33+
- **UI** sees **snapshots**, not live mutable engine internals.
34+
35+
## Freeze: `Call` vs `CallBuiltin`
36+
37+
| Callee kind | IL form |
38+
| ----------- | ------- |
39+
| User-defined function | `Call` (or equivalent direct call to function metadata) |
40+
| Built-in from active profile | `CallBuiltin` (operand identifies built-in) |
41+
42+
Robot commands stay **ordinary calls** in source—no special parser syntax for `move` or `turnLeft`.
43+
44+
Examples in source (all parse as calls):
45+
46+
```text
47+
move()
48+
turnLeft()
49+
frontIsClear()
50+
print("x")
51+
count(values)
52+
takeLast(values)
53+
```
54+
55+
Binding chooses user vs built-in; lowering chooses `Call` vs `CallBuiltin`.
56+
57+
## What each layer owns
58+
59+
### Syntax spec
60+
61+
- Grammar, precedence, statement/expression kinds, type syntax, parse recovery.
62+
63+
### Semantic spec
64+
65+
- Symbol resolution, built-in **availability** (profile), type checking, assignability, legality of calls/index/return.
66+
67+
### IL spec
68+
69+
- Opcode inventory, operand shapes, calling convention, evaluation stack / locals, function metadata, debug mapping hooks, meaning of **`CallBuiltin`**.
70+
71+
### World spec
72+
73+
- Grids/layers, actor state, movement / item / terrain rules, metrics hooks, **snapshot** format.
74+
75+
### Built-in spec
76+
77+
- Built-in ids, signatures, semantic meaning, **runtime handler** behavior (return value, world mutation, stdout/stderr).
78+
79+
## IL and world: explicit non-goals
80+
81+
- **IL never renders** — it only advances execution state.
82+
- **IL does not inspect syntax** — source is gone after lowering except via debug metadata.
83+
- **World mutations** go through **runtime handlers**, not parser or syntax visitors.
84+
- **Snapshots are the UI contract** — hosts consume runtime/world snapshots, not ad hoc shared mutable graphs.
85+
86+
## World interaction (spec direction)
87+
88+
The interpreter affects the world only through **defined APIs** (e.g. `IRobotWorld` / built-in handlers). Layered storage (`TerrainGrid`, `ItemGrid`, `ActorGrid`, `ActorsById`) stays authoritative; rendering uses **projection** over snapshots. Details: [world model](../world/world-model.md), [world actions](../world/world-actions.md), [movement rules](../world/movement-rules.md), [render projection](../rendering/render-projection.md).
89+
90+
## Related
91+
92+
- [Syntax-to-IL lowering](../compiler/syntax-to-il-lowering.md)
93+
- [IL instruction set (inventory)](../runtime/il-instruction-set.md)
94+
- [Built-ins and profiles](../semantics/builtins-and-profiles.md)
95+
- [Compilation pipeline](../compiler/compilation-pipeline.md)

‎docs/compiler/compilation-pipeline.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Compilation pipeline (teaching)
2+
3+
RoboSharp’s **compiler** is the stretch from **source text** to **fake IL** ready for the interpreter. It is split across projects and docs so each stage stays visible.
4+
5+
## Stages
6+
7+
```text
8+
SourceText
9+
→ Lexer / parser → Syntax tree + parse diagnostics (RoboSharp.Language)
10+
→ Semantic analysis → Bound tree + semantic diagnostics (RoboSharp.Semantics)
11+
→ IL generation → Fake executable / IL blobs (RoboSharp.IL)
12+
```
13+
14+
Orchestration (open project, diagnostics aggregation, emit paths) lives in **`RoboSharp.Toolchain`** and host-facing flows in **`RoboSharp.Application`**—see [Architecture overview](../architecture.md).
15+
16+
## Bridge documents
17+
18+
| Topic | Document |
19+
| ----- | -------- |
20+
| Lex / parse / syntax tree (host view) | [lexical-analysis.md](lexical-analysis.md), [parsing.md](parsing.md), [syntax-tree.md](syntax-tree.md) |
21+
| Binding and diagnostics | [semantic-analysis.md](semantic-analysis.md), [diagnostics.md](diagnostics.md) |
22+
| **Syntax → IL shape (examples)** | [syntax-to-il-lowering.md](syntax-to-il-lowering.md) |
23+
| Opcode / operand model | [../runtime/il-instruction-set.md](../runtime/il-instruction-set.md) |
24+
| Layer ownership (syntax vs semantics vs IL vs world) | [../architecture/pipeline-boundaries.md](../architecture/pipeline-boundaries.md) |
25+
26+
## Teaching note
27+
28+
Students should be able to open **each** artifact (tokens, tree, bound nodes, IL listing) in Studio or similar hosts without those concerns being merged into one opaque “compile” step.

‎docs/compiler/syntax-to-il-lowering.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Syntax-to-IL lowering (v1 direction)
2+
3+
This document is the **bridge** between surface syntax and fake IL: it keeps syntax “honest” relative to the execution model. It complements [IL instruction set](../runtime/il-instruction-set.md) and [pipeline boundaries](../architecture/pipeline-boundaries.md).
4+
5+
Lowering is defined on the **bound** program (after types and symbols are known), not on raw syntax.
6+
7+
## Variable declaration
8+
9+
Source:
10+
11+
```text
12+
integer x = 5
13+
```
14+
15+
Illustrative IL sequence:
16+
17+
```text
18+
PushConstant 5
19+
StoreLocal x
20+
```
21+
22+
## Assignment
23+
24+
Source:
25+
26+
```text
27+
x = x + 1
28+
```
29+
30+
Illustrative IL:
31+
32+
```text
33+
LoadLocal x
34+
PushConstant 1
35+
Add
36+
StoreLocal x
37+
```
38+
39+
## If / else (built-in condition)
40+
41+
Source:
42+
43+
```text
44+
if (frontIsClear())
45+
{
46+
move()
47+
}
48+
else
49+
{
50+
turnLeft()
51+
}
52+
```
53+
54+
Illustrative pattern (labels symbolic):
55+
56+
```text
57+
CallBuiltin FrontIsClear
58+
JumpIfFalse elseLabel
59+
CallBuiltin Move
60+
Jump endLabel
61+
elseLabel:
62+
CallBuiltin TurnLeft
63+
endLabel:
64+
```
65+
66+
User-defined predicates would use `Call` and the same branching opcodes.
67+
68+
## While loop
69+
70+
Source:
71+
72+
```text
73+
while (condition)
74+
{
75+
body
76+
}
77+
```
78+
79+
Illustrative pattern:
80+
81+
```text
82+
loopHead:
83+
… evaluate condition …
84+
JumpIfFalse loopEnd
85+
… body …
86+
Jump loopHead
87+
loopEnd:
88+
```
89+
90+
Exact encodings depend on the frozen opcode set and whether conditions leave a boolean on the stack or use compare + branch.
91+
92+
## Calls: user vs built-in
93+
94+
- **User function** → `Call` target function metadata.
95+
- **Built-in** (from active profile) → `CallBuiltin` with built-in id / operand form per IL spec.
96+
97+
See [Built-ins and profiles](../semantics/builtins-and-profiles.md).
98+
99+
## Related
100+
101+
- [Compilation pipeline](compilation-pipeline.md)
102+
- [IL instruction set](../runtime/il-instruction-set.md)
103+
- [Parser](parsing.md), [Semantic analysis](semantic-analysis.md)

‎docs/docs-for-spreading.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,31 @@
1-
# Moved: lesson and content specification
1+
# Redirect: content has been spread
22

3-
The material that lived here was split into focused pages under **`docs/lessons/`** and related docs.
3+
Material formerly accumulated here now lives in **focused pages**. Do not add new specification here.
4+
5+
## Lessons and lesson-adjacent (original split)
46

57
**Start here:** [lessons/README.md](lessons/README.md)
68

7-
| Former topic | New location |
8-
| ------------ | ------------ |
9-
| Profiles, provider, starter profile names | [lessons/builtin-profiles.md](lessons/builtin-profiles.md) |
9+
| Topic | Location |
10+
| ----- | -------- |
11+
| Profiles, provider, starter names | [lessons/builtin-profiles.md](lessons/builtin-profiles.md) |
1012
| Goals, evaluation, source-shape goals | [lessons/goals-and-evaluation.md](lessons/goals-and-evaluation.md) |
11-
| Hints, help, lesson record, UI policy, progression | [lessons/lesson-model.md](lessons/lesson-model.md) |
13+
| Hints, lesson record, UI policy, progression | [lessons/lesson-model.md](lessons/lesson-model.md) |
1214
| Content packs, sessions, metrics | [lessons/content-packs-sessions-and-metrics.md](lessons/content-packs-sessions-and-metrics.md) |
1315
| JSON examples | [lessons/json-formats.md](lessons/json-formats.md) |
1416
| Semantic built-in + profile bridge | [semantics/builtins-and-profiles.md](semantics/builtins-and-profiles.md) |
1517
| Workspace seam | [workspaces/lesson-metadata.md](workspaces/lesson-metadata.md) |
1618
| Studio behavior | [studio/lesson-profiles.md](studio/lesson-profiles.md) |
1719
| Player lesson mode | [player/README.md](player/README.md) |
1820

19-
Do not add new specification content to this file; extend the targets above.
21+
## Product mission and pipeline doctrine (spread from the long-form draft)
22+
23+
| Topic | Location |
24+
| ----- | -------- |
25+
| Teaching goals, robot world, IDE intent, one-sentence mission | [governance/mission.md](governance/mission.md) |
26+
| Pipeline integrity, parser neutrality | [governance/design-principles.md](governance/design-principles.md) |
27+
| Syntax / semantics / IL / world / built-in ownership, `Call` vs `CallBuiltin` | [architecture/pipeline-boundaries.md](architecture/pipeline-boundaries.md) |
28+
| Compiler stages + links | [compiler/compilation-pipeline.md](compiler/compilation-pipeline.md) |
29+
| Syntax-to-IL examples | [compiler/syntax-to-il-lowering.md](compiler/syntax-to-il-lowering.md) |
30+
| IL opcode inventory direction | [runtime/il-instruction-set.md](runtime/il-instruction-set.md) |
31+
| Spec order vs `src/` reality | [implementation-gaps.md](implementation-gaps.md) |

‎docs/documentation-todo.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Working index for `docs/`: what exists, how complete it is, and how it lines up
44

55
Many paths are also sketched in [README.md](README.md). Authoritative policy remains [AGENTS.md](../AGENTS.md).
66

7+
For a **single view of missing product features** (pipeline stages, hosts, lessons, debugger) versus current `src/` code, see [implementation-gaps.md](implementation-gaps.md).
8+
79
## How to read the columns
810

911
| Column | Meaning |
@@ -20,7 +22,8 @@ Re-scan after large doc or code changes: line counts and `src/` contents drift.
2022
| Document | Have content | Implemented |
2123
| -------- | ------------ | ----------- |
2224
| [README.md](README.md) | Yes | N/A |
23-
| [docs-for-spreading.md](docs-for-spreading.md) | Stub | N/A |
25+
| [implementation-gaps.md](implementation-gaps.md) | Yes | N/A |
26+
| [docs-for-spreading.md](docs-for-spreading.md) | Yes | N/A |
2427
| [build.md](build.md) | Yes | N/A |
2528
| [repository-layout.md](repository-layout.md) | Yes | Partial |
2629
| [nuget.md](nuget.md) | Yes | N/A |
@@ -37,8 +40,8 @@ Policy detail lives in [AGENTS.md](../AGENTS.md); these pages are optional elabo
3740

3841
| Document | Have content | Implemented |
3942
| -------- | ------------ | ----------- |
40-
| [governance/mission.md](governance/mission.md) | No | N/A |
41-
| [governance/design-principles.md](governance/design-principles.md) | No | N/A |
43+
| [governance/mission.md](governance/mission.md) | Yes | N/A |
44+
| [governance/design-principles.md](governance/design-principles.md) | Yes | N/A |
4245
| [governance/dependency-policy.md](governance/dependency-policy.md) | No | N/A |
4346
| [governance/implementation-order.md](governance/implementation-order.md) | No | N/A |
4447

@@ -53,6 +56,7 @@ Policy detail lives in [AGENTS.md](../AGENTS.md); these pages are optional elabo
5356
| [architecture/workspace-model.md](architecture/workspace-model.md) | Stub | No |
5457
| [architecture/io-abstractions.md](architecture/io-abstractions.md) | Stub | Yes |
5558
| [architecture/runtime-hosts.md](architecture/runtime-hosts.md) | No | Partial |
59+
| [architecture/pipeline-boundaries.md](architecture/pipeline-boundaries.md) | Yes | N/A |
5660

5761
## IO layer (`docs/io/`)
5862

@@ -159,7 +163,8 @@ Index: [semantics/README.md](semantics/README.md).
159163

160164
| Document | Have content | Implemented |
161165
| -------- | ------------ | ----------- |
162-
| [compiler/compilation-pipeline.md](compiler/compilation-pipeline.md) | No | Partial |
166+
| [compiler/compilation-pipeline.md](compiler/compilation-pipeline.md) | Yes | Partial |
167+
| [compiler/syntax-to-il-lowering.md](compiler/syntax-to-il-lowering.md) | Yes | No |
163168
| [compiler/lexical-analysis.md](compiler/lexical-analysis.md) | Stub | Yes |
164169
| [compiler/parsing.md](compiler/parsing.md) | Stub | Yes |
165170
| [compiler/syntax-tree.md](compiler/syntax-tree.md) | Stub | Yes |
@@ -171,7 +176,7 @@ Index: [semantics/README.md](semantics/README.md).
171176

172177
| Document | Have content | Implemented |
173178
| -------- | ------------ | ----------- |
174-
| [runtime/il-instruction-set.md](runtime/il-instruction-set.md) | No | No |
179+
| [runtime/il-instruction-set.md](runtime/il-instruction-set.md) | Yes | No |
175180
| [runtime/interpreter.md](runtime/interpreter.md) | No | No |
176181
| [runtime/execution-model.md](runtime/execution-model.md) | No | No |
177182
| [runtime/runtime-state.md](runtime/runtime-state.md) | No | No |

0 commit comments

Comments
 (0)