# Diagrams — DD-13: OpenHarness (Academic Baseline) All diagrams use a consistent color code: - **Teal (#5eead4)** — OpenHarness's designed/inspectable/explicit mechanisms (its strengths). - **Warn/orange (#f0a868)** — the contrasted pole or transition (production harnesses, recovery-only compaction, human-readable logs). - **Danger/red (#f08080)** — the production gap (what is missing if misused as production). --- ## Diagram 1 — Inspectability as the Design Goal (not the score) **Type**: Concept map. **Purpose**: Show that OpenHarness's value is inspectability-as-product, and that the 30/60 score reflects "not production" rather than design failure — the same pattern as DD-01 (Pi). **Reading**: - OpenHarness's defining property is what you can isolate, not what you can ship — the box itself is open, not just the telemetry about it. - The 30/60 score reflects the rubric measuring production-readiness across all dimensions; OpenHarness is deliberately not optimizing for all dimensions. - The low-score-for-legibility pattern is shared with DD-01 (Pi): a low absolute number that reflects "not trying to be production," not a design failure. ```mermaid flowchart TB OH["OpenHarness (HKUDS)
academic harness
30/60"] OH --> I1["Modular components
each individually examinable"] OH --> I2["Every decision logged
at source with inputs"] OH --> I3["Auto-compaction
research-grade, inspectable"] OH --> I4["ohmo: built-in personal agent
demonstrates the design"] OH --> NOTE["Score reflects NOT-PRODUCTION
not design failure
(same pattern as DD-01 Pi)"] style OH fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style I1 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style I2 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style I3 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style I4 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style NOTE fill:#0d1b2a,stroke:#f0a868,color:#f0a868,stroke-dasharray:3 3 ``` --- ## Diagram 2 — Architecture: Swappable Modular Components **Type**: Component architecture. **Purpose**: Show OpenHarness's swappable-component architecture — each Module 0.1 job (loop, tools, safety, context, memory) is a separate component with a documented interface, examinable in isolation. **Reading**: - Each component is a separate box you can study without the others — you can examine the compaction mechanism without the tool layer, the memory model without the loop. - The Loop is a thin orchestrator that calls the model, dispatches tools, and observes stop conditions; the other four are the data planes the Loop reads from and writes to. - ohmo (the built-in personal agent) is the reference demonstration that exercises every component — like Pi is to the minimal-harness category. ```mermaid flowchart TB LOOP["The Loop
(calls model · dispatches tools · observes stop conditions)"] LOOP --> TR["Tool Registry
small · stable
research-minimal surface"] LOOP --> CM["Context Manager
auto-compaction
four-part mechanism"] LOOP --> MEM["Memory
explicit tiered stores
working · episodic · semantic"] LOOP --> DL["Decision Log
transparent
logged at source"] OHMO["ohmo
built-in personal agent
reference demonstration"] OHMO -.->|exercises every component| LOOP style LOOP fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style TR fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style CM fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style MEM fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style DL fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style OHMO fill:#0d1b2a,stroke:#f0a868,color:#f0a868,stroke-dasharray:3 3 ``` --- ## Diagram 3 — The Auto-Compaction Four-Part Mechanism (Module 3 Reference) **Type**: Mechanism flow. **Purpose**: Show OpenHarness's headline contribution — auto-compaction implemented as a designed four-part mechanism (trigger predicate, selection policy, summarization step, non-destructive record) — and contrast it with production harnesses where compaction is an emergent recovery behavior. **Reading**: - The four parts are individually examinable: trigger decides *when*, selection decides *what*, summarization does the work, record preserves the original for analysis. - The non-destructive record is the load-bearing detail — the original context survives compaction so a researcher can ask "did compaction change the outcome?" (mirrors DD-21's `replaces_entry_ids` and Module 8's event-sourcing principle). - Production harnesses fold all four parts into an emergent recovery behavior entangled with the session store, the provider's token accounting, and the framework's retry logic — examinable only with instrumentation. ```mermaid flowchart LR IN["Context fills
(history growing)"] T1["1. Trigger predicate
declared condition
token count / message count"] T2["2. Selection policy
named · parameterized
what summarized · what preserved · what dropped"] T3["3. Summarization step
model-based
inputs + outputs logged"] T4["4. Non-destructive record
original retained
in-context view swapped"] OUT["Compacted context
+ original retained for analysis"] IN --> T1 --> T2 --> T3 --> T4 --> OUT ORIG["Original context
retained on disk
(truth never rewritten)"] T4 -.->|preserves| ORIG style IN fill:#0d1b2a,stroke:#e0e0e0,color:#e0e0e0 style T1 fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style T2 fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style T3 fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style T4 fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style OUT fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style ORIG fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0,stroke-dasharray:3 3 ``` --- ## Diagram 4 — Explicit Tiered Memory (Module 4 / 4.3 Reference) **Type**: Layered architecture. **Purpose**: Show OpenHarness's explicit tiered memory model — separate stores with declared interfaces (working, episodic, semantic) — and contrast with production harnesses that conflate the tiers into one buffer. **Reading**: - Three separate stores (working / episodic / semantic) with declared interfaces — not three layers of the same buffer. - Separate stores buy individually-auditable read path and write path — the property Module 4.3 (write-gating) wants but that production harnesses usually blur. - The cost is integration friction: production harnesses conflate the tiers because doing so is faster and cheaper; OpenHarness pays the friction to buy the inspectability. ```mermaid flowchart TB subgraph OH["OpenHarness — explicit tiered stores"] WK["Working memory
current context window
post-compaction"] EP["Episodic memory
prior turns · sessions
retrievable, not in-context"] SE["Semantic memory
distilled facts
keyed for retrieval"] end WK <-.->|declared interface| EP EP <-.->|declared interface| SE PROD["Production harnesses
conflated buffer
(faster, cheaper, blurred)"] OH -.->|trades friction for inspectability| PROD style WK fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style EP fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style SE fill:#0d1b2a,stroke:#5eead4,color:#5eead4 style PROD fill:#0d1b2a,stroke:#f0a868,color:#f0a868,stroke-dasharray:3 3 ``` --- ## Diagram 5 — The OpenHarness-vs-Tau Inspectability Axis **Type**: Pole-pair contrast. **Purpose**: Show the contrast between OpenHarness (legibility-of-behavior) and DD-21 (Tau) (legibility-of-code) — the two most inspectable harnesses in the roster, optimizing for complementary properties. This is the inspectability axis the roster defines. **Reading**: - Both harnesses are inspectability-first, but they inspect different things: OpenHarness makes *what the harness did* visible; Tau makes *what the harness is* (code structure, session tree) visible. - The non-destructive compaction record is the shared design — both refuse to overwrite the on-disk truth; OpenHarness retains the original context, Tau retains `CompactionEntry` with `replaces_entry_ids`. - OpenHarness produces human-readable logs; Tau produces a machine-readable event union — the gap OpenHarness would need to close to meet the DD-14 observability standard. ```mermaid flowchart LR OH["OpenHarness
legibility-of-BEHAVIOR
what the harness did"] TAU["Tau (DD-21)
legibility-of-CODE
what the harness is"] SHARED["Shared design
non-destructive record
(original context retained
on-disk truth never rewritten)"] OH -->|inspectability axis| TAU OH -.->|both| SHARED TAU -.->|both| SHARED style OH fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style TAU fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style SHARED fill:#0d1b2a,stroke:#f0a868,color:#f0a868 ``` --- ## Diagram 6 — The Production Gap (what is missing if misused as production) **Type**: Gap analysis. **Purpose**: Show the production modules OpenHarness deliberately omits because they are not the research question — sandbox (Module 5: 1/5), permission model (Module 6: 2/5), security (Module 11: 1/5) — and why misusing the academic baseline as a production harness is dangerous. **Reading**: - OpenHarness's strengths (Module 3 Context, Module 4 Memory, Module 10 Observability) cluster on the research axis; the production modules (5, 6, 9, 11) are deliberately minimal or absent. - The MLSecOps reading is that inspectability is a research property, not a security property — a visible compaction mechanism is not a safe compaction mechanism. - The cure is methodological, not architectural: treat OpenHarness as a research and pedagogical tool, never as a production harness; for production, use a harness with the security modules implemented. ```mermaid flowchart TB OH["OpenHarness
30/60"] OH --> S1["Module 3 Context · 4/5
auto-compaction reference"] OH --> S2["Module 4 Memory · 4/5
explicit tiered stores"] OH --> S3["Module 10 Observability · 4/5
inspectability-as-product"] OH --> G1["Module 5 Sandbox · 1/5
bash/exec without containment"] OH --> G2["Module 6 Permission · 2/5
below floor"] OH --> G3["Module 9 Verification · 1/5
none"] OH --> G4["Module 11 Security · 1/5
not the research question"] NOTE["For production:
use NemoClaw (DD-09) governance ·
Agents SDK (DD-11) sandboxing ·
not the academic baseline"] G1 -.-> NOTE G2 -.-> NOTE G4 -.-> NOTE style OH fill:#0d1b2a,stroke:#5eead4,color:#5eead4,stroke-width:2px style S1 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style S2 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style S3 fill:#0d1b2a,stroke:#5eead4,color:#e0e0e0 style G1 fill:#0d1b2a,stroke:#f08080,color:#f08080 style G2 fill:#0d1b2a,stroke:#f08080,color:#f08080 style G3 fill:#0d1b2a,stroke:#f08080,color:#f08080 style G4 fill:#0d1b2a,stroke:#f08080,color:#f08080 style NOTE fill:#0d1b2a,stroke:#f0a868,color:#f0a868,stroke-dasharray:3 3 ``` --- ## Diagram 7 — n8n Workflow: OpenHarness Auto-Compaction (reference pipeline) **Type**: n8n workflow JSON. **Purpose**: Provide the n8n workflow that demonstrates the four-part compaction mechanism as an inspectable pipeline — the same mechanism Module 3 teaches, executable in n8n. **Reading**: - The four nodes map onto the four parts: History Size (trigger check), Over-threshold gate (predicate), Auto-Compact (summarization, every step logged), Output (record emitted with before/after counts). - The workflow is intentionally inspectable — every node is named, every condition is visible, every output is a first-class record — mirroring OpenHarness's design philosophy. - This is the reference pipeline for the lab: students implement the four parts in Python (07-lab-spec.md) and can compare against this n8n version. ```json { "name": "OpenHarness Auto-Compaction — DD-13", "nodes": [ { "parameters": { "assignments": { "assignments": [{ "id": "h", "name": "history_tokens", "value": "={{ $json.body.tokens || 55000 }}", "type": "number" }]}, "options": {} }, "id": "init", "name": "1. History Size (trigger check)", "type": "n8n-nodes-base.set", "typeVersion": 3.4, "position": [160, 300] }, { "parameters": { "conditions": { "combinator": "any", "conditions": [{ "id": "over", "leftValue": "={{ $json.history_tokens }}", "rightValue": 50000, "operator": { "type": "number", "operation": "gt" } }] } }, "id": "check", "name": "2. Trigger predicate (over threshold?)", "type": "n8n-nodes-base.if", "typeVersion": 2.2, "position": [380, 300], "notesInFlow": true, "notes": "OpenHarness compaction fires at a DECLARED threshold. The predicate is a function you can read — not magic, not buried." }, { "parameters": { "model": "gpt-4o-mini", "messages": "={{ [{role:'system',content:'OpenHarness selection policy: summarize older history into compact decision records. Preserve task, decisions, errors. Compress verbose outputs. Drop redundant tool echoes. Every step logged for research.'}] }}", "options": {} }, "id": "compact", "name": "3. Summarization step (logged)", "type": "@n8n/n8n-nodes-langchain.toolExecuteTool", "typeVersion": 1.1, "position": [600, 300], "notesInFlow": true, "notes": "Model-based summarization with inputs + outputs logged. The non-destructive record retains the original context for analysis — mirrors DD-21's replaces_entry_ids." }, { "parameters": { "content": "={{ JSON.stringify({ compacted: true, before: $json.history_tokens, after: Math.round($json.history_tokens * 0.5), original_retained: true, note: 'OpenHarness four-part compaction — trigger · selection · summarization · non-destructive record' }) }}", "options": {} }, "id": "out", "name": "4. Non-destructive record (output)", "type": "n8n-nodes-base.respondToWebhook", "typeVersion": 1, "position": [820, 300] } ], "connections": { "1. History Size (trigger check)": { "main": [ [ { "node": "2. Trigger predicate (over threshold?)", "type": "main", "index": 0 } ] ] }, "2. Trigger predicate (over threshold?)": { "main": [ [ { "node": "3. Summarization step (logged)", "type": "main", "index": 0 } ], [ { "node": "4. Non-destructive record (output)", "type": "main", "index": 0 } ] ] }, "3. Summarization step (logged)": { "main": [ [ { "node": "4. Non-destructive record (output)", "type": "main", "index": 0 } ] ] } }, "settings": { "executionOrder": "v1" }, "meta": { "templateCreatedBy": "Harness Engineering Master Course — DD-13 OpenHarness (academic baseline)" } } ```