chore: code hygiene sweep — dead code, residual DAG terminology, repo clutter #30

New issue

Open

opened 2026-05-13 13:05:03 +00:00 by timur · 0 comments

timur commented

2026-05-13 13:05:03 +00:00

Owner

Companion to #29. Pure cleanup — no behaviour changes (or only behaviour changes that fall out of removing unused code).

1. Residual DAG / legacy terminology

Codebase still describes itself as a "DAG control flow engine" in several places. The DAG era ended at #21; the model is Python flows. Update:

Cargo.toml (workspace) — description field
crates/hero_logic/Cargo.toml — description = "DAG control flow engine — Hero RPC service" → match PRD framing
crates/hero_logic/src/main.rs — const DESCRIPTION string
Makefile — banner / help text mentions "DAG control flow engine"
crates/hero_logic_admin/src/main.rs — comments and .well-known/heroservice.json description ("Manage and monitor DAG workflows and plays")
Grep for DAG, node_run, node_executor, template_loader, {{outputs.X}} references in comments and remove where stale.

2. Repo-root clutter

Cargo.toml.hero_builder_backup — looks abandoned; verify and delete.
anthropic_screenshot.png — appears to be a stray screenshot; verify and delete.
apikeys.db — SQLite (?) at repo root; do NOT commit secrets/keys to the repo. Move to a dev-local path (e.g. ~/.hero/var/hero_logic/apikeys.db) and add the filename to .gitignore. Confirm no credentials have leaked into git history; if they have, rotate.
logs/ at repo root — should probably be .gitignored; verify nothing important lives there.
Empty-ish or stale src/ at repo root (src/logic/{osis_server_generated.rs, rpc.rs, rpc_generated.rs, types.rs, types_generated.rs}) — looks like an orphan duplicate of crates/hero_logic/src/logic/... left over from before the workspace split. Confirm and delete if dead.

3. OTOML round-trip workaround

crates/hero_logic/src/engine/python_executor.rs documents and implements a base64 encoding (b64: prefix) for WorkflowVersion.python_source to dodge an OTOML multiline-string escape bug. Mirrored in hero_tracing.py::_decode_b64_source. Two options:

Fix upstream: teach the OTOML serializer to pick '''...''' (literal multiline) for backslash-bearing content. Removes the workaround entirely.
Keep, hide: drop all user-facing documentation of the workaround (PRD says nothing about it). Remove the _otoml_field back-compat alias from hero_tracing.py.

PRD never mentions OTOML — pick one approach so reality matches.

4. Authoring-surface unification (lands with #29)

Remove the from <flow_name> import <fn> meta-path importer in hero_tracing.py (_HeroFlowImporter) if the decision in #29 is to keep flow.invoke(name, ...) as the single sub-flow API.
Drop the older PRD-style examples that mix flow.invoke() and import-syntax.

5. Dead / unused module audit

Go through and confirm what's actually used:

crates/hero_logic/src/services/mod.rs is very thin — what's it for, can it be folded into lib.rs?
crates/hero_logic/src/seed.rs vs seed_flows/ — clarify ownership boundary.
crates/hero_logic/Cargo.toml: the [features] default = ["logic"]; logic = [] flag is no-op — remove or document why it exists.
crates/hero_logic/src/lib.rs: #[cfg(feature = "logic")] gating on logic mod is gated on a default-on feature with no off-path use; simplify.
crates/hero_logic/sdk/js/types_generated.js — used by anyone? If not, drop.
Any other pub fns with zero callers across the workspace.

6. Comment + doc polish

Pass through doc-comments referencing old phase numbers (Phase C, Phase F4, etc.) — keep them when they explain WHY, drop them when they only explain WHAT was done in the past.
Confirm hero_tracing.py's docstring lists flow.pause / ask_user once those land (#29).

Acceptance

rg -i 'DAG' . returns only hits that legitimately describe a directed-acyclic-graph concept (e.g. "the span tree is a DAG") — zero hits describing the engine itself.
Repo root contains no abandoned artifacts (no .hero_builder_backup, no stray PNGs, no committed dev databases).
apikeys.db is in .gitignore and not tracked.
src/logic/ at repo root either explained or deleted.
The base64 b64: workaround is either gone or undocumented in user-facing surfaces (no mention in PRD, README, or comments outside the executor's internal explanation).
cargo build --release succeeds with no warnings about dead code in unmodified modules.

Companion to #29. Pure cleanup — no behaviour changes (or only behaviour changes that fall out of removing unused code). ## 1. Residual DAG / legacy terminology Codebase still describes itself as a "DAG control flow engine" in several places. The DAG era ended at #21; the model is Python flows. Update: - `Cargo.toml` (workspace) — `description` field - `crates/hero_logic/Cargo.toml` — `description = "DAG control flow engine — Hero RPC service"` → match PRD framing - `crates/hero_logic/src/main.rs` — `const DESCRIPTION` string - `Makefile` — banner / help text mentions "DAG control flow engine" - `crates/hero_logic_admin/src/main.rs` — comments and `.well-known/heroservice.json` description ("Manage and monitor DAG workflows and plays") - Grep for `DAG`, `node_run`, `node_executor`, `template_loader`, `{{outputs.X}}` references in comments and remove where stale. ## 2. Repo-root clutter - `Cargo.toml.hero_builder_backup` — looks abandoned; verify and delete. - `anthropic_screenshot.png` — appears to be a stray screenshot; verify and delete. - `apikeys.db` — SQLite (?) at repo root; do NOT commit secrets/keys to the repo. Move to a dev-local path (e.g. `~/.hero/var/hero_logic/apikeys.db`) and add the filename to `.gitignore`. Confirm no credentials have leaked into git history; if they have, rotate. - `logs/` at repo root — should probably be `.gitignore`d; verify nothing important lives there. - Empty-ish or stale `src/` at repo root (`src/logic/{osis_server_generated.rs, rpc.rs, rpc_generated.rs, types.rs, types_generated.rs}`) — looks like an orphan duplicate of `crates/hero_logic/src/logic/...` left over from before the workspace split. Confirm and delete if dead. ## 3. OTOML round-trip workaround `crates/hero_logic/src/engine/python_executor.rs` documents and implements a base64 encoding (`b64:` prefix) for `WorkflowVersion.python_source` to dodge an OTOML multiline-string escape bug. Mirrored in `hero_tracing.py::_decode_b64_source`. Two options: - **Fix upstream**: teach the OTOML serializer to pick `'''...'''` (literal multiline) for backslash-bearing content. Removes the workaround entirely. - **Keep, hide**: drop all user-facing documentation of the workaround (PRD says nothing about it). Remove the `_otoml_field` back-compat alias from `hero_tracing.py`. PRD never mentions OTOML — pick one approach so reality matches. ## 4. Authoring-surface unification (lands with #29) - Remove the `from <flow_name> import <fn>` meta-path importer in `hero_tracing.py` (`_HeroFlowImporter`) if the decision in #29 is to keep `flow.invoke(name, ...)` as the single sub-flow API. - Drop the older PRD-style examples that mix `flow.invoke()` and import-syntax. ## 5. Dead / unused module audit Go through and confirm what's actually used: - `crates/hero_logic/src/services/mod.rs` is very thin — what's it for, can it be folded into `lib.rs`? - `crates/hero_logic/src/seed.rs` vs `seed_flows/` — clarify ownership boundary. - `crates/hero_logic/Cargo.toml`: the `[features] default = ["logic"]; logic = []` flag is no-op — remove or document why it exists. - `crates/hero_logic/src/lib.rs`: `#[cfg(feature = "logic")]` gating on `logic` mod is gated on a default-on feature with no off-path use; simplify. - `crates/hero_logic/sdk/js/types_generated.js` — used by anyone? If not, drop. - Any other `pub fn`s with zero callers across the workspace. ## 6. Comment + doc polish - Pass through doc-comments referencing old phase numbers (`Phase C`, `Phase F4`, etc.) — keep them when they explain WHY, drop them when they only explain WHAT was done in the past. - Confirm `hero_tracing.py`'s docstring lists `flow.pause` / `ask_user` once those land (#29). ## Acceptance - `rg -i 'DAG' .` returns only hits that legitimately describe a directed-acyclic-graph concept (e.g. "the span tree is a DAG") — zero hits describing the engine itself. - Repo root contains no abandoned artifacts (no `.hero_builder_backup`, no stray PNGs, no committed dev databases). - `apikeys.db` is in `.gitignore` and not tracked. - `src/logic/` at repo root either explained or deleted. - The base64 `b64:` workaround is either gone or undocumented in user-facing surfaces (no mention in PRD, README, or comments outside the executor's internal explanation). - `cargo build --release` succeeds with no warnings about dead code in unmodified modules.