boltage/plans/README.md

Plans for the README's limitations

One plan per bullet in the README's Limitations section:

Plan	Limitation	Size
01	RETURN *, EXPLAIN and PROFILE	medium
02	Write statistics	small
03	Multiple labels, pattern comprehensions, temporal and spatial types, indexes and constraints	large, split in parts
04	User and role management, SHOW TRANSACTIONS, :sysinfo	medium
05	TLS (bolt+s://, HTTPS)	small to medium
06	Results fetched fully before streaming	medium

Shared groundwork

Several plans need the same building blocks. Building them once, first, keeps the plans small:

1. Variable scope analysis in cypher.py. RETURN * (01) and general pattern comprehension rewriting (03) both need to know which variables are in scope at a given clause. Today cypher.py only masks strings and tracks bracket depth. A small clause splitter plus a scope tracker (variables introduced by MATCH, OPTIONAL MATCH, UNWIND ... AS, YIELD, WITH projections, path assignments) is enough; a full Cypher parser is not needed yet. If 03's multiple-labels part is ever done, that is the point to reconsider a real parser (for example one generated from the openCypher grammar).
2. One transaction per auto-commit query. Write statistics (02) read transaction-local counters, streaming (06) needs a transaction to keep a server-side cursor open, and PROFILE (01) needs a savepoint. All three want Session.run to wrap auto-commit queries in BEGIN ... COMMIT instead of relying on the connection's autocommit mode. This is done: reads run in a cursor's transaction (06), and queries that can write in one around the statistics (02). Session._script runs such a transaction in one round trip.
3. Unit tests. The only test is the end-to-end tests/smoke_test.py. Most of this work is text rewriting in cypher.py, which is cheap to unit test without a database. Add tests/test_cypher.py (pytest) alongside the first plan that touches cypher.py, and keep extending the smoke test for behaviour that needs AGE.

Suggested order

1. 02 write statistics: small, very visible in neo4j-browser, and introduces the per-query transaction.
2. 06 streaming: builds on the same transaction handling.
3. 01 RETURN * / EXPLAIN / PROFILE: introduces the scope analysis.
4. 03 indexes and constraints (part D), then pattern comprehensions (part B), then temporal types (part C). Multiple labels (part A) and spatial types (part E) last, or not at all.
5. 05 TLS and 04 user management, independent of the rest, whenever they are needed.

Each plan ends with the README changes to make when it lands, so the Limitations section shrinks as the work is done.