Composition
wity-rkf documents can embed other <wity-knowledge> representations inline. A single document can contain prose, LaTeX, reactive state machines, and live workbooks, system maps, and decision frameworks — each backed by its own domain library, composed into one knowledge graph.
This is how RKF functions as a composite document format. The pattern arises naturally from the architecture:
- All domain libraries on wity-graph — wity-workbook, wity-system, wity-ideation — serialize to
<wity-knowledge> - RKF also serializes to
<wity-knowledge>(an RKF document is a knowledge graph) - An RKF environment's content blocks can include
embedblocks that store another representation's snapshot as data within the same graph
How it works
An rkf-env carries a blocks[] array (the v2.0 multi-block model). One block kind is embed:
{
kind: 'embed',
id: 'water-network',
application: 'system',
snapshot: { /* wity-system serialized state */ }
}The application field identifies which domain library owns the snapshot. The snapshot is opaque to rkf-core — it passes through evaluation untouched. The renderer decides what to mount.
Supported applications
| Application | Domain library | What it embeds |
|---|---|---|
workbook | wity-workbook | Spreadsheet with formulas, typed cells, cross-sheet references |
system | wity-system | Network graph with typed assets, connections, cascade analysis |
decision-matrix | wity-workbook | Multi-angle structured decision analysis |
swot | wity-workbook | Strengths, weaknesses, opportunities, threats |
eisenhower | wity-workbook | Priority matrix (urgency × importance) |
ooda | wity-workbook | Observe, orient, decide, act loop |
Decision frameworks (decision-matrix, swot, eisenhower, ooda) are implemented as wity-workbook presets — they share the spreadsheet engine but apply different schemas and presentation.
Architecture
┌─────────────────────────────────────────────┐
│ RKF Document (<wity-knowledge>) │
│ │
│ rkf-section │
│ ├── rkf-env (blocks[]) │
│ │ ├── { kind: 'text', ... } │
│ │ ├── { kind: 'math', ... } │
│ │ └── { kind: 'embed', │
│ │ application: 'workbook', │
│ │ snapshot: <wity-knowledge> } │
│ │ ↑ │
│ │ another knowledge graph │
│ │ stored as node data │
│ └── rkf-machine │
│ └── (reactive state, marks, ports) │
└─────────────────────────────────────────────┘The embed snapshot is stored as data on the rkf-env node in the knowledge graph. When the document is serialized via serialize(), the snapshot travels with it. When parsed back via parse(), the snapshot is restored and available for the renderer to hydrate.
Separation of concerns
| Layer | Responsibility |
|---|---|
| rkf-core (L2) | Defines the embed block kind in the schema. Treats the snapshot as opaque data — preserves it through parse/serialize/evaluate without interpreting it. |
| Renderer (L3) | Mounts the appropriate domain editor (e.g. <workbook-editor>, <system-editor>) based on application. Passes snapshot for hydration. Listens for changes and writes them back to the block. |
| Domain library (L2) | Each embedded application (wity-workbook, wity-system) owns its own snapshot format, editor lifecycle, and serialization. It has no knowledge of RKF. |
This keeps each layer independent. RKF doesn't import wity-workbook. wity-workbook doesn't know it's inside an RKF document. The renderer is the only piece that bridges them.
Reactive interaction
Embed blocks currently operate as isolated islands — each embedded editor manages its own state independently. The RKF state machine (vars, gates, transforms) does not directly read from or write to embedded editor state.
Future directions may include typed I/O ports (rkf-port) on embed blocks, enabling reactive data flow between the RKF state machine and embedded representations (e.g. a workbook cell value driving an RKF variable, or a gate controlling embed visibility).