// engineering field notebook / howlframe dogfood consumer

HowlNotes ハウルノーツ // 2026

Name: HowlNotes
Author: William Elias

HowlNotes is a genuinely complete notes web application built as an external dogfood consumer of HowlFrame, engineered by William Elias. It determines how much ordinary application development can be expressed through HowlFrame DSLs and verifies persistent record stores under capability boundaries.

AXIOM // FULL-STACK HOWLFRAME. HowlNotes does not reside inside the HowlFrame compiler tree or fake execution with handwritten wrappers. The backend runs on HowlFrame's standalone bytecode VM, the frontend is compiled from web_app DSL definitions, and data is stored in HowlFrame's native record store.

[ CLONE REPOSITORY ] [ SYSTEM ARCHITECTURE ] [ DOGFOOD FINDINGS ]

DATA_FLOW // BROWSER CLIENT ↔ BYTECODE VM ↔ PERSISTENT STORE PERSISTENCE: ATOMIC JSON

01 // CLIENT

web_app DSL

Compiled to vanilla browser JavaScript (static/app.js). Handles DOM updates and async fetch.

[TARGET: JAVASCRIPT]

02 // ROUTER

Notes API Gateway

HTTP listener handling REST/RPC routes, CORS middleware, and input sanitization.

[PORT: 8088]

03 // RUNTIME

HowlFrame VM

Executes build/backend.hfbc under explicit runner capabilities: network, database, filesystem.

[CAPS: ENFORCED]

04 // PERSIST

Native Store

Atomically synchronized structured records at file://data/notes.json. Survives restarts.

[STATE: DURABLE]

SECTION // 01 Dogfood Mission & Verified Revision

HN-MOD-OVERVIEW

HowlNotes was created as an honest, external testbed to evaluate the HowlFrame language and toolchain under realistic full-stack application conditions. By building a complete, functioning CRUD application with persistent data storage and a responsive web interface, HowlNotes surfaces real compiler bugs, AST ergonomics friction, and capability boundary semantics.

Pinned Toolchain Revision

HowlNotes is tested and verified against HowlFrame 0.1.0 (HFBC Bytecode Format v1) at commit 7cdc5116d426cc05c505d6457dc24aeb4fcc2046.

Feature	Implementation Target	HowlFrame Primitive	Verification Status
Notes CRUD	Backend API & Frontend	`store_put`, `store_get`, `store_delete`	PASS (100%)
Data Persistence	Local Disk (`file://data/notes.json`)	`store_open`	DURABLE
Capability Boundary	Bytecode VM Execution	`-allow-caps network,database,filesystem`	FAIL CLOSED
Browser Interface	Static Web UI	`(web_app ...)` → JS Emit	VANILLA JS

SECTION // 02 Architecture & Data Model

HN-MOD-SCHEMA

Notes are persisted as structured records with millisecond Unix timestamps:

[JSON // RECORD_SCHEMA]

{
  "id": "1",
  "content": "Verify capability boundaries across Howl ecosystem",
  "created_at": "1787190354",
  "updated_at": "1787190354"
}

Store State Layout (`file://data/notes.json`)

_seq: {"val": <integer>} — Auto-incrementing sequence counter.
_all_ids: {"ids": ["1", "2", ...]} — Active note ID registry for full list scans.
"<id>": Structured note payload object.

HTTP API Contract

Method	Path	Description	Payload	Response
`GET`	`/api/health`	Health & storage status	None	`200 {"status":"ok","app":"howlnotes"}`
`GET`	`/api/notes`	List all notes	None	`200 {"notes":[...]}`
`POST`	`/api/notes`	Create new note	`{"content":"..."}`	`201 {"id":"...","content":"..."}`
`PUT`	`/api/notes`	Update note	`{"id":"...","content":"..."}`	`200 {...}` or `404`
`DELETE`	`/api/notes`	Delete note	`{"id":"..."}`	`200 {"status":"ok"}` or `404`

SECTION // 03 Compilation & Execution Pipeline

HN-MOD-PIPELINE

Frontend Compilation: Source in app/frontend.howl uses the (web_app ...) DSL and compiles via HowlFrame's JavaScript backend into static/app.js with DOM event bindings.
Backend Compilation: Source in app/backend.howl uses the (http_server ...) DSL and compiles into standalone bytecode build/backend.hfbc via howlframe -compile-bc.
Runtime Execution: The backend is executed via howlframe -run-bc -allow-caps network,database,filesystem build/backend.hfbc. The VM verifies capabilities before allowing socket binding or file writes.

SECTION // 04 Capability Boundaries & Validation

HN-MOD-SECURITY

In accordance with the Howl principle "Intent is not authority", all client input is treated as untrusted and validated before storage mutations occur:

Malformed JSON: Caught via try_let returning 400 {"error":"invalid_json"}.
Empty Content: Validated via length check returning 400 {"error":"content_required"}.
Oversized Content: Enforces ≤ 10,000 character maximum returning 400 {"error":"content_too_long"}.
Capability Enforcement: If database or filesystem capability is omitted at launch, store initialization fails closed immediately.

SECTION // 05 Dogfooding Insights & Language Evolution

HN-MOD-DOGFOOD

Building HowlNotes directly uncovered concrete opportunities to improve HowlFrame:

String Interpolation Ergonomics

Deeply nested (str "..." (str "..." ...)) expressions are verbose in Lisp syntax. Recommended adding template strings to HowlFrame's parser.

Native JSON Deserialization

Parsing nested JSON payloads inside bytecode handlers requires explicit dictionary walks. Recommended adding typed struct schema bridging.

Array Iteration Primitives

Iterating over store keys required manual index counter loops. Highlighted the value of standard map/filter collection primitives.

Single-Process Persistence

HowlFrame's file-backed store provides atomic local persistence, ideal for single-node tools and edge applications.

SECTION // 06 Quick Start & Local Execution

HN-MOD-RUN

[BASH // BUILD_AND_TEST]

# 1. Clone repository
git clone https://github.com/howlcipher/howlnotes.git
cd howlnotes

# 2. Bootstrap HowlFrame compiler toolchain
./scripts/bootstrap.sh

# 3. Build frontend and backend targets
./scripts/build.sh

# 4. Run automated test suite
./scripts/test.sh

# 5. Start server on localhost:8088
./scripts/run.sh

SECTION // 07 Technical Reports Index

HN-MOD-DOCS

Architecture Specification Document — Detailed breakdown of bytecode runtime, store mechanics, and API routing.
Dogfooding Journal — Complete catalog of discovered friction points, workarounds, and classification categories.
v1 Final Evaluation Report — Comprehensive answers to the 9 core dogfooding questions and future HFIR roadmap.

SECTION // 08 Technical Q&A: Full-Stack Dogfooding & Storage Persistence

HN-MOD-QA

How does HowlNotes prove HowlFrame's full-stack application readiness?

HowlNotes serves as the canonical real-world dogfood application for the HowlFrame toolchain. Rather than trivial benchmark examples, it runs a complete notes system with dual targets: the frontend compiles to browser JavaScript via web_app DSL while the backend executes entirely on the standalone sandboxed bytecode VM.

How is data persisted without external database dependencies?

In systems engineered by William Elias, operational simplicity and sandboxed execution are core principles. HowlNotes uses HowlFrame's native record store with atomic JSON disk writes and write-ahead validation, ensuring notes persist across VM restarts while operating under strict capability boundaries.

Where does HowlNotes fit in the Howl autonomous engineering ecosystem?

As part of the Howl ecosystem, HowlNotes serves as the shared engineering field notebook, collaborating with HowlBoard for state evaluation, HowlPlane for control orchestration, and HowlRelay for immutable audit logging.