Skip to content

docs: explain structural search concepts and analyser internals - #483

Draft
j-emberton wants to merge 2 commits into
mainfrom
docs/structural-search-concepts-and-internals
Draft

j-emberton wants to merge 2 commits into
mainfrom
docs/structural-search-concepts-and-internals

Conversation

@j-emberton

@j-emberton j-emberton commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add a concise conceptual explanation of Bilt structural search in docs/guide/structural-search.md, including incidence graphs, eager request-scoped child expansion, DM validation, conservative coupled detection, matching biases and retry/pruning behaviour.
  • Add a complementary code-focused reference in docs/development/structural-analysis.md describing module and object ownership, request lifecycle, sequence and lifetime diagrams, caches, tests and debugging.
  • Add docs/development/computational-planning-and-lowering.md explaining plans, realisation, symbolic Tree, transform AST, linear blocks, and the current Python-AST backend boundary.
  • Add all three pages to docs/index.md and zensical.toml under distinct Bilt user guide and Developer internals sections.

Documentation design

  • Keep the algorithmic explanation separate from the source-level walkthrough.
  • Minimise duplicate narrative and diagrams; use graph illustrations in the conceptual guide, sequence and ownership diagrams in the developer page.
  • Explicitly distinguish request-scoped eager structural expansion from optional child ordering hints.
  • Explain computational planning, realisation and the present Python-AST backend boundary in a third, separate developer guide.
  • Do not include the unmerged experimental port-alias contraction as production behaviour.

Validation

  • Checked against main at 25806b9 and the current structural-analysis modules and tests.
  • Verified all five updated files exist on the branch.
  • Checked new documentation cross-links and balanced fenced code blocks.
  • Not run: Zensical site build or full CI (local GitHub checkout and access to its dependencies were unavailable). Please allow CI to validate the rendered Mermaid diagrams and navigation.

Scope

Documentation only: no changes to structural search or execution behaviour.

This branch has not been deployed

No deployments
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