Skip to content

refactor(core): DagNode field layers, GWT test naming, lockstep consumption docs - #135

Merged
mvallebr merged 1 commit into
mainfrom
chore/audit-final-cleanup
Sep 20, 2026
Merged

mvallebr merged 1 commit into
mainfrom
chore/audit-final-cleanup

Conversation

@mvallebr

Copy link
Copy Markdown
Contributor

Summary

Final batch of audit follow-ups: #130 (DagNode), #132 (test naming + factory marker), and the #128 documentation note. Also refreshes uv.lock for v0.32.4.

Changes

#130 — DagNode

  • Dropped the stringly-typed __getitem__/__setitem__/get proxies and the unused Dag.pop — zero callers in src or tests; three test call sites migrated to attribute access
  • Grouped the 28 fields into five labeled layers (identity → user policy → compiled contracts → private diagnostics → scope metadata) so the distinct reasons to change are visible at a glance; the module docstring now states where "immutability" actually lives (frozen contract dataclasses like OutputContract/PublishPlan, not the mutable record itself)
  • Assessed and deferred: the full StepSpec/CompiledNode split would rename attribute access across every executor and test construction site for zero behavioral gain. The field grouping makes that split mechanical if it's ever wanted — flagged in the code and in refactor(core): split DagNode god object; drop stringly-typed accessors #130.

#132 — test naming + factory marker

  • 61 test functions renamed to test_given_X_when_Y_then_Z across the concentrated files (error threshold ×2 engines, wait_for_workers_after_shutdown, lifecycle stream ×2, each-resource lifecycle ×2, tee concurrency, expansion, observer runtime). Renames are mirrored across engines; the parity meta-test exception lists were updated accordingly
  • Additive mark_as_factory() / FACTORY_MARKER protocol: materializer factories whose signature cannot be sniffed (partials over plain callables, callable objects) can now be tagged explicitly. Signature sniffing remains the default — nothing existing changes

#128 — docs

  • New DESIGN_PHILOSOPHY §3.17 Bounded Lockstep Consumption Contract: sibling fan-out branches must be consumed in lockstep; sequential consumption circular-backpressures a bounded push runtime and is mathematically guaranteed to deadlock (the complex_parallel case — unfixable without unbounded buffering, hence documented instead)
  • ROADMAP: completed bullets for sync/async parity enforcement, loud post-run streams, and fail-loud build validation

Tests

  • 834 passing (was 832; +2 factory-marker tests)
  • Full suite, corpus spec tests, sync/async parity meta-tests, ruff format/lint, mkdocs build --strict, and the pre-commit coverage gate all green
  • No behavioral changes: accessor removal is dead-code deletion, renames are test-only, the marker protocol is additive, and docs are prose

…renames; docs: lockstep contract

Closes the remaining audit items: #130, #132 (renames + factory marker),
and the #128 documentation note.  Also refreshes uv.lock for v0.32.4.

#130 — DagNode:
- drop the stringly-typed __getitem__/__setitem__/get proxies and the
  unused Dag.pop (zero callers in src or tests; three test call sites
  migrated to attribute access)
- group the 28 fields into five labeled layers (identity, user policy,
  compiled contracts, private diagnostics, scope metadata) so the four
  distinct reasons to change are visible; module docstring now states
  where 'immutability' actually lives (frozen contract dataclasses, not
  the mutable record)
- NOTE: the full StepSpec/CompiledNode split was assessed and deferred —
  it would rename attribute access across every executor and test
  construction site for zero behavioral gain; the field grouping makes
  that split mechanical if ever wanted

#132 — test naming + factory marker:
- 61 test functions renamed to test_given_X_when_Y_then_Z across the
  concentrated files (threshold x2 engines, wait_for_workers,
  lifecycle_stream x2, each_resource_lifecycle x2, tee, expansion,
  observer runtime); renames mirrored across engines and the
  parity meta-test exception lists updated
- additive mark_as_factory()/FACTORY_MARKER protocol: callables whose
  signature cannot be sniffed (partials, callable objects) can be
  tagged explicitly; signature sniffing remains the default

#128 — docs:
- new DESIGN_PHILOSOPHY section 3.17 (Bounded Lockstep Consumption
  Contract): sibling fan-out branches must be consumed in lockstep;
  sequential consumption circular-backpressures a bounded push runtime
  and is mathematically guaranteed to deadlock (the complex_parallel
  case)
- ROADMAP: completed bullets for parity enforcement, loud post-run
  streams, and fail-loud build validation

Tests: 834 passing (was 832; +2 factory marker tests).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant