solidcraft-upstream/docs/drawing-foundations.md

Drawing foundations: first geometry slice

This is the W00 bootstrap ledger for the published Drawing plan in #860. The first implementation is W01a, #2053 / PR #2085, owned by 0xlillith: neutral section-geometry records, structural validation and conversion to existing planar types. Its concrete API and limitations are in the geometry contract.

W01a is part of W01, not completion of W00, the full W01 contract, Stage A, or the Drawing workspace. It does not extract a body section, calculate visibility, register inspect.section_curves or drawing.view, export a drawing, or save a Drawing document. The independent formatter slice W09a is tracked in #2054 / PR #2086; it is not a module supplied by W01a.

Scope, sources and status

The initial scope was checked against upstream f7343e9161bc6243cdb076d3b6c3594db97279ff. Recheck the implementation revision, current claims, AGENTS and CONTRIBUTING before taking the next slice. Local plan/ documents were unavailable when this work began; this file does not reconstruct them or replace project instructions.

The published plan reconciles the original RFC, SychPL's investigation, NOWN-DEV's two-stage proposal and CamWight's study and questionnaire. The attachment retains the detailed requirements, alternatives and sources. Product research is requirements evidence; its descriptions and proposed standards rules are not implementation code, independently verified conformance or permission to copy protected content.

Here, W01a means code in this slice; future means a requirement still to implement or decide. A merged representation or validator does not establish a geometry producer's capability. Drawing milestones in the RFC are distinct from the repository roadmap's M0-M14; the Drawing workspace remains roadmap M11.

First-section requirements and fixtures

Fixture IDs below identify checks, not saved designs or registered commands. The current fixture details and future producer gates are in the geometry contract.

ID	Requirement and source	Package	Fixture / status
S01	Model mm/radians, explicit plane axes and correct XZ sign; plan §4.1/W01	W01a	F01: plane validation and coordinates; W01a
S02	Reuse supported analytic/conic/Bézier representations without silently fitting them; plan §4.1/W01	W01a, then W02-W03	F02: representation/serde checks; W01a. Producing exact sections is future
S03	Keep accuracy categories explicit; plan §4.1/W01	W01a, then W02-W03	F02/F04: analytic/bounded/sampled metadata and finite values; W01a. Evidence for producer bounds is future
S04	Indexed curves, oriented wire uses and region references; plan W01 and study §§10-12	W01a	F03: manually constructed rectangle with a hole, orientation-preserving conversion; W01a
S05	Certify closed section boundaries, winding, nesting, material regions and areas; plan W03	W03	F05/F06: body-derived hole/oblique-cylinder sections; future. PR #2068 proposes producer tests for review. Structural validation alone does not meet this requirement
S06	Empty, tangent, open, coincident, degenerate and unsupported cuts are distinguishable; plan W03	W01 follow-up, W02-W03	F07: producer outcomes; future. Current empty vectors/contact points are only representable data
S07	Complete source/body/occurrence identity, provenance and freshness; plan §4.1/W01, NOWN-DEV Stage A	W01 follow-up, W02-W04	F08: repeated placements and failure in one selected body; future. Current indices are result-local
S08	Bound input/work and fail without mutation or partial success; project rules, plan W01-W04	W01a, then W02-W04	F04: structural bounds; W01a. Byte/allocation limits, producer work budgets and cancellation are future caller responsibilities
S09	Standalone read-only inspect.section_curves, existing plane forms, explicit selection and no sketch/viewport prerequisite; NOWN-DEV Stage A	W04 after W03	F09: command/CLI/MCP parity, unchanged document/undo and error cases; future
S10	SVG/DXF with units, source groups/layers, declared format accuracy and atomic optional file output; NOWN-DEV Stage A	W04, W10 geometry subset	F09: physical coordinates and complete output; future
S11	One section provider shared with the visibility investigation; SychPL/NOWN-DEV and plan W03/W05	W02-W06	F05-F08 and a reviewed capability matrix; future
S12	Transient dimensioned snapshots remain distinct from associative drawings; NOWN-DEV Stage B	W07-W08	Future snapshot/measurement/output fixtures after their contracts settle

The remaining industrial requirements are retained in the published plan's coverage ledger and W09-W47: formatting, persistent sheets/references, dimensions, BOM/balloons, standards, derived views, production output and specialist domains. Expanding this bootstrap into atomic traceability for all 48 packages is remaining W00 work; absence from this first-section table does not remove a requirement.

Dependencies, ownership and review

Claim links below identify the bounded slices already tracked here. Other rows do not reserve work or assign the contributors who proposed it. Check live issues and draft PRs before claiming. Review columns name the expertise needed, not reviewers who have already agreed to an assignment.

Package	Depends on	Ownership / scope here	Review and next handoff
W00	RFC and project rules	Bootstrap in W01a; full ledger/decision ownership remains open	Integration review: preserve sources, unresolved decisions and child-issue boundaries
W01	W00 immediate scope	0xlillith, #2053/#2085, W01a only	Geometry/kernel and engine review: validate representation limits; finish source/provenance/outcome contracts before producer handoff
W02	Reviewed W01 producer contract and backend placement	Review overlap with NOWN-DEV's #2068 before another claim	Kernel/solidcore review: guarded live-body adapter, supported surfaces, complete source identity and no cache-byte authority
W03	W02	Review/reuse producer proposal #2068; exact supported subset remains to be agreed	Geometry/document review: analytic cuts, classified outcomes, winding/nesting/material checks and error evidence
W04	W03 and W10 geometry-only subset	NOWN-DEV's #2068 proposes Stage A command/output; not merged at the recorded review	Engine/IO review: explicit selection, request limits, no mutation, physical SVG/DXF, DTO adaptation and complete-or-error output
W05	Reviewed W01; W02 where extraction is needed	Coordinate with SychPL's offer; this is not an assignment	Geometry/kernel review: bounded HLR investigation and findings in the RFC before a substantial backend proposal
W06	Reviewed W05 findings and W02	Future projection/visibility slice	Geometry/document review: supported scene-wide visibility, split intervals, provenance and cache keys
W07	W01, W09; W03 for cuts; an agreed preview adapter or W06	Future transient drawing.view	Engine/presentation review: meaningful measurements, snapshot status and explicit approximation
W08	W07 and W10 text/dimension subset; W04 adapters as reused	Future preview and SVG/DXF/PNG slice	UI/IO review: shared navigation/layout, output scale and UI/CLI/MCP parity

Stage A does not depend on persistent Drawing storage, PDF, fonts, a drafting profile or the W09 formatter. W10's geometry-only primitives are a separate increment from its text/dimension layout. W09a's independent PR can advance in parallel without introducing a dependency into W01a.

NOWN-DEV's PR #2068 is an overlapping Stage A producer/export proposal to review before further W02-W04 claims. It was open and ready, not merged, when inspected at head 4e945d8af594b8cc252cc4e5ffede3684b7bf3bd on 2026-10-17. It proposes doc/project_section.rs and the inspect.section_curves engine command with mesh/fitted loops and SVG/DXF. Its body-name/loop JSON and sweep_deg angles do not imply compatibility with W01a's radians, accuracy records and indexed regions. Agree an explicit adapter, accuracy and source/provenance contract before integration; preserve that contributor's claim and branch. Its tilted-cylinder test is proposed producer evidence to review, not an implemented W01a or current-main capability.

Decision ledger

An implemented slice choice below describes W01a, not approval of every proposal in the RFC. Record later decisions with their evidence, reviewer, date, affected contract revision and dependent child issues.

Decision	Current disposition	Next owner/review and gate
D01: representation placement	W01a uses existing geom::Plane, Seg2, Loop2 and Region2; neutral section records live at L0	W01a geometry review. This does not decide the section/HLR algorithm's kernel placement
D02: identity/status scope	W01a has only indices within one value and per-curve accuracy metadata; no persistent source names, provenance or freshness record	W01 follow-up with kernel/document/engine reviewers before W02-W04 depend on source contracts
D03: validity claim	W01a validates structure and preserves supplied orientation. It does not certify winding, nesting, self-intersections or a material section	W03 owns producer/geometric validity evidence; callers must not promote structure checks into manufacturing certification
D04: shared producer/backend	One reusable section provider is the plan; guarded extraction and substantial HLR placement must be coordinated with solidcore	Kernel/solidcore and integration review before W02/W05 expand into a substantial backend
D05: supported geometry/accuracy	Representation support is documented; producer surface/curve coverage and defensible approximation bounds remain future	W02-W03 publish per-case capabilities and F05-F08 results; W05 does the same for visibility
D06: public commands	#2068 proposes inspect.section_curves; transient drawing.view remains future. W01a registers neither	Review #2068's distinct output schema before W04 integration; live registry/claim check in W04/W07; preserve existing viewport commands
D07: later Drawing choices	Storage/undo, PDF/fonts, standards/profile semantics and release rules remain in the RFC decision register	Their relevant later packages decide them; none blocks this representation slice or standalone section work

Completion and handoff

Each subsequent child issue should state supported cases, owned paths, contract revision, exact dependencies, analytic expectations, error behavior and required cross-lane review. Follow current draft-claim, isolation and quality-gate rules; use Refs #860 and close the bounded child issue rather than the umbrella RFC.

Report what was actually tested at the proposed merge revision. A structure-only API has no new CAD result to photograph; later producer, command and UI changes need real app evidence when their effect can be shown. Keep generated reference documentation, assets and native-format changes outside this slice. Root project instructions govern any later change to those areas.