Skip to content

docs: codify repository responsibility map and extension points (#413) #421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dowdiness merged 2 commits into from
May 31, 2026
Merged

docs: codify repository responsibility map and extension points (#413) #421

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c1b4c1
docs: codify repository responsibility map and extension points (#413)
dowdiness May 31, 2026
ef9b4f9
docs: fix submodule inventory in responsibility map (#413 review)
dowdiness May 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 77 additions & 11 deletions docs/architecture/responsibility-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,59 @@ This note records the practical architecture conclusions from the 2026-05-31
cross-repository audit of Canopy, `dowdiness/incr`, `dowdiness/moondsp`, and
Canopy's parser/CRDT submodules.

It is not a full package inventory. For the detailed module list, see
[Module Structure](modules.md). This document answers a narrower question:
which layer should own new work, which existing APIs should be reused first,
and which follow-up issues should be handled before larger feature work.
It is the **ownership decision guide**: which layer should own new work, which
existing APIs should be reused first, and which follow-up issues should be
handled before larger feature work. For the full package inventory, pipeline
overview, extension points, and non-goals, see [Architecture](../architecture.md).
For a reuse index of public APIs, see [API Map](../api-map.md). For the detailed
module list, see [Module Structure](modules.md).

## Current Stance

### Implemented (code-backed)

- Canopy is currently text-first: text CRDT state is the durable document, while
CST, projection, semantic data, and rendered views are derived.
- `NodeId`, `ProjNode`, and `SourceMap` are the main extension anchors for
projection, semantic annotations, structural edits, and UI overlays.
- `protocol.ViewNode` and `ViewPatch` are the UI boundary. New renderers should
consume protocol output instead of inventing a parallel view tree.
- `dowdiness/incr` is the intended computation model for semantic passes,
projection caches, long-lived editor subscriptions, and future cognition
pipelines.
- `event-graph-walker` owns CRDT semantics. Canopy should compose its text,
tree, container, undo, and history APIs rather than reimplementing them.
- `loom` and `seam` own lossless CST, parser recovery, syntax nodes, and parser
reuse. Canopy owns app-level projection identity and language behavior.
- `dowdiness/incr` backs incremental projection today: memo-based `FlatProj`
updates in `editor` and `lang/lambda/flat`. Reuse its `Input`, `Derived`,
`DerivedMap`, `ReachableDerived`, and `Watch` primitives for incremental work.
- MoonDsp should remain owner of DSP runtime safety, `CompiledTemplate`, voice
scheduling, and audio-thread constraints. Any Canopy integration must be an
authoring/editor shell boundary, not a runtime rewrite.

### Planned / Aspirational

These directions are supported by design notes but are not yet implemented:

- Expanding `@incr` from today's incremental projection to a general
semantic-annotation pipeline (see #416) and future cognition pipelines —
informed by [extensible ASTs](extensible-asts.md), [multi-representation system](multi-representation-system.md),
[anamorphism discipline](anamorphism-discipline.md).
- AST-as-source-of-truth promotion once the semantic pipeline is stable (see
[product vision](product-vision.md), [projectional bridge](vision-projectional-bridge.md)).

### Source of Truth on Drift

When docs and code diverge, **the code and generated `.mbti` interface files
are authoritative**. `../api-map.md` is a reuse index, not authority over
implementation.

## Owner Selection / Reuse First

Before opening code, answer "where should this feature live?" in order:

1. Consult this responsibility map (boundaries table below).
2. Check `../api-map.md` for existing public APIs to reuse.
3. Inspect implementation files or `moon ide` output for concrete types.

## Responsibility Boundaries

| Owner | Owns | Reuse first | Does not own |
Expand All @@ -45,6 +74,42 @@ and which follow-up issues should be handled before larger feature work.
| `dowdiness/incr` | Incremental runtime and lifecycle primitives | `Input`, `Derived`, `DerivedMap`, `ReachableDerived`, `Watch` | Canopy-specific semantic data shapes |
| `dowdiness/moondsp` | Pattern engine, DSP graph, `CompiledTemplate`, scheduler, voice pool | Authoring docs and stable domain IDs | Canopy view protocol or editor shell |

## Supporting Libraries and Submodule Boundaries

The git submodules (repository boundaries, per `.gitmodules`) are:
`event-graph-walker`, `loom`, `svg-dsl`, `graphviz`, `rle`, `order-tree`,
`alga`, and `rabbita`. `event-graph-walker` and `loom`/`seam` are covered in the
Responsibility Boundaries table above. **`loom` is itself a submodule** that
contains `seam`, `incr`, `text-change`, `moji`, `pretty`, and `lambda` as
packages — update those through the `loom` submodule, not separate repositories.

The libraries below are all implemented and wired into Canopy. The "Repository"
column is the actual update boundary; "Integration" is where Canopy consumes it.

**Group A — Direct dependencies** (in canopy root `moon.mod.json`):

| Library | Responsibility | Repository | Integration |
|---|---|---|---|
| `text-change` (`dowdiness/text_change`) | Pure contiguous text-change utilities | package in `loom` submodule | `editor`, `lang/*` |
| `moji` (`dowdiness/moji`) | UAX #29 grapheme-cluster and word-boundary segmentation, UTF-16 indexed | package in `loom` submodule | `editor`, `lang/*` |
| `pretty` (`dowdiness/pretty`) | Wadler-Lindig pretty-printer, generic `Layout[A]` + annotation support | package in `loom` submodule | `lang/*`, formatting passes |
| `order-tree` (`dowdiness/order-tree`) | Order-statistic B-tree, O(log n) position-indexed operations | standalone submodule | root dep; backs `event-graph-walker` |

**Group B — CRDT internals** (pulled in via `event-graph-walker`):

| Library | Responsibility | Repository | Integration |
|---|---|---|---|
| `rle` (`dowdiness/rle`) | Generic run-length-encoded sequence, O(log n) position lookup | standalone submodule | backs `event-graph-walker`, `order-tree`, btree |
| `alga` (`dowdiness/alga`) | Algebraic graphs — directed graph trait + algorithms | standalone submodule | `event-graph-walker`, `graphviz`, visualizer |

**Group C — Visualization / UI tooling** (not on the core editor runtime path):

| Library | Responsibility | Repository | Integration |
|---|---|---|---|
| `graphviz` (`dowdiness/graphviz`) | DOT parser + layout engine + SVG renderer | standalone submodule | loom viz, `lib/visualizer`, `examples/ideal`; depends on `svg-dsl` |
| `svg-dsl` (`dowdiness/svg-dsl`) | Programmatic SVG generation DSL | standalone submodule | base layer under `graphviz` |
| `rabbita` (`moonbit-community/rabbita`) | Functional Web UI framework (TEA) for MoonBit; submodule also holds `warren` | standalone submodule (vendored community lib) | `lib/rabbita_codemirror` adapter + `examples/*` |

## Priority Issues

The audit led to these Canopy issues:
Expand All @@ -54,9 +119,9 @@ The audit led to these Canopy issues:
2. [#414](https://github.com/dowdiness/canopy/issues/414) - centralize
projection construction and `SourceMap` helper APIs.
3. [#416](https://github.com/dowdiness/canopy/issues/416) - define semantic
annotation flow over `NodeId` side tables and `@incr`.
annotation flow over `NodeId` side tables and `@incr`. *(planned)*
4. [#418](https://github.com/dowdiness/canopy/issues/418) - plan migration
from `incr` 0.5.x to the 0.6 target facade.
from `incr` 0.5.x to the 0.6 target facade. *(planned)*
Comment on lines 123 to +124
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify current incr versions and migration wording references.
rg -n -C2 'dowdiness/incr@|incr 0\.5|0\.6 target facade|`#418`'

Repository: dowdiness/canopy

Length of output: 1757

Clarify incr migration baseline for #418 to avoid roadmap drift.

Line 117 states the migration from incr 0.5.x → 0.6 target facade is (planned), but the current code already references dowdiness/incr@0.6.0 in lib/cognition/moon.mod. Reword #418 to describe what’s still planned on top of 0.6 (e.g., facade stabilization/completion) so the roadmap matches reality.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture/responsibility-map.md` around lines 116 - 117, Update the
responsibility-map entry for issue `#418` so it no longer claims a 0.5.x→0.6
migration is merely "planned" when the code already depends on
dowdiness/incr@0.6.0 (see lib/cognition/moon.mod); instead, reword the item to
state what remaining work is planned on top of v0.6 (for example, "facade
stabilization/completion, integration tests, and cleanup") so the roadmap
accurately reflects that the repo has adopted v0.6 but still requires additional
facade stabilization tasks.

5. [#417](https://github.com/dowdiness/canopy/issues/417) - specify
WebSocket recovery and text/tree CRDT boundaries.
6. [#415](https://github.com/dowdiness/canopy/issues/415) - inventory and
Expand Down Expand Up @@ -89,7 +154,7 @@ When adding semantic overlays:
- Store semantic facts in side tables keyed by `NodeId` or source spans.
- Do not add a new field to `ProjNode` for every annotation category.
- Schedule nontrivial derived facts through `@incr`; avoid bespoke dirty flags
or side-channel caches.
or side-channel caches. *(semantic pipeline via `@incr` is planned — see #416)*
- Treat parse errors and incomplete CSTs as normal input states.

When adding collaboration features:
Expand All @@ -109,6 +174,7 @@ When exploring MoonDsp integration:
contract is explicitly designed.
- Preserve the MoonDsp runtime boundary: authoring changes should cross through
`CompiledTemplate`, scheduler snapshots, or documented control APIs.
*(Canopy-as-MoonDsp-shell is a planned spike — see #419)*

## Anti-Patterns

Expand All @@ -119,4 +185,4 @@ When exploring MoonDsp integration:
- Adding language-specific state to generic editor/core packages.
- Building MoonDsp audio-runtime assumptions into Canopy editor packages.
- Optimizing incremental behavior before profiling or before the dependency
graph shape is stable.
graph shape is stable. *(incr 0.6 migration tracked in #418 — planned)*
Loading