numtypes 0.0.0

package/docs/project-structure.md

@@ -0,0 +1,52 @@
+# Project Structure
+
+`numtypes` is centered on the transformer. The public library symbols exist so
+that user code can express numeric intent in TypeScript, but transformed output
+must not retain imports or function calls from `numtypes`.
+
+The staged transformer implementation plan lives in `docs/implementation-plan.md`.
+
+## Top-Level Layout
+
+```text
+src/
+  lib/             Public phantom symbols imported by user code.
+  transformer/     TypeScript transformer entrypoint and implementation.
+
+test/
+  unit/            Small deterministic tests for tables and helpers.
+  transformer/     Fixture-based source-to-source transform tests.
+  engine/v8/       Opt-in V8 lowering probes using Node/V8 flags.
+
+bench/
+  *.bench.ts       Opt-in performance tests and regression benchmarks.
+```
+
+## Public Symbols
+
+User code imports from the package root:
+
+```typescript
+import { f32, i32, type u32 } from "numtypes";
+```
+
+Those imports are only meaningful before transformation. Calls such as
+`i32(value)` and `Math.imul(i32(a), i32(b))` are compile-time cast markers. The
+transformer lowers them to JavaScript coercion idioms and removes the original
+package import when no runtime value remains.
+
+## Test Layers
+
+Default tests should be deterministic:
+
+- unit tests for domain tables, diagnostics, symbol resolution, and operator
+  rules;
+- fixture tests that compare transformed source text and diagnostics.
+
+Engine probes are separate because they depend on the exact Node/V8 version and
+on unstable diagnostic flags. They should test whether important output shapes
+still lower as expected, not whether JavaScript semantics are correct.
+
+Benchmarks are separate from tests. They should compare transformed output
+against baseline JavaScript and track transformer overhead on large source
+files.