refactor: enforce conceptual module ownership

Author: Milky2018

README.mbt.md

@@ -1,207 +1,37 @@
-# moon_wgsl
-
-`Milky2018/moon_wgsl` is a MoonBit library for composing WGSL shader modules
-with `naga_oil`-style preprocessing and imports.
-
-Use it when your shaders contain directives such as `#define_import_path`,
-`#ifdef`, `#define`, and `#import`, and you want to resolve them from MoonBit
-without adding a separate shader build step.
-
-## Install
-
-Add the package from Mooncakes, then import the subpackages you need:
-
-```mbt check
-///|
-test "README: package is available" {
-  let value_defines = @common.default_wgsl_value_defines()
-  debug_inspect(value_defines.length() > 0, content="true")
-}
+# moon_wgsl workspace
+
+This repository contains four separately owned MoonBit modules:
+
+- `Milky2018/wgsl` — official WGSL lexer, AST, parser, semantic IR,
+  validation, and runtime writer
+- `Milky2018/moon_wgsl_naga` — Naga-compatible ordering, naming, writer,
+  and trace behavior
+- `Milky2018/moon_wgsl_naga_oil` — naga-oil directives, imports,
+  preprocessing, resolution, composition, export, profiles, and diagnostics
+- `Milky2018/moon_wgsl` — the small user-facing workflow facade
+
+Most applications should import `Milky2018/moon_wgsl`. Its opaque `Composer`
+supports exactly source/module registration, `prepare`, `compose`, and
+`export_wgsl`. Lower-level parser, IR, compatibility, graph, rewrite, and
+diagnostic stages are not facade methods.
+
+```mbt
+let composer = @moon_wgsl.Composer::default()
+composer.register_source("main.wgsl", "fn answer() -> u32 { return 42u; }")
+let source = composer.compose(
+  "main.wgsl",
+  @moon_wgsl.WgslComposeOptions::default(),
+)
 ```
 
-Most users only need these packages:
-
-- `@common` for shared option and result types
-- `@metadata` for inspecting directives and imports
-- `@preprocess` for evaluating one shader source
-- `@resolver` for source registries and source-tree scanning
-- `@compose` for module composition
-- `@export` for single-file export
-
-## Features
-
-- Conditional preprocessing: `#ifdef`, `#ifndef`, `#if`, `#else if`, `#else`,
-  and `#endif`
-- Shader definition values: bools, signed integers, unsigned integers, and raw
-  WGSL text values
-- Grouped, aliased, and quoted-path imports
-- Composer-owned source registries for hermetic composition
-- Optional source-tree scanning through `moonbitlang/x/fs`
-- Single-file WGSL export with source catalog, source map, provenance, and
-  diagnostics
-
-## Quick Start
-
-### Compose Modules
-
-Register WGSL source strings on a `Composer`, then compose the root shader.
-
-```mbt check
-///|
-test "README: compose registered modules" {
-  let composer : @compose.Composer = @compose.Composer::default()
-  composer.clear_sources()
-
-  composer.register_source(
-    "maths.wgsl", "#define_import_path demo::maths\nconst TWO: f32 = 2.0;\n",
-  )
-  composer.register_source(
-    "main.wgsl", "#import demo::maths::TWO\nfn scale(x: f32) -> f32 {\n  return x * TWO;\n}\n",
-  )
-
-  let options : @common.WgslComposeOptions = @common.WgslComposeOptions::default()
-  let composed = composer.compose_wgsl("main.wgsl", options) catch {
-    err => abort(err.message())
-  }
-
-  debug_inspect(composed.contains("fn scale"), content="true")
-  debug_inspect(composed.contains("#import"), content="false")
-}
-```
-
-### Preprocess One Shader
-
-Use `Preprocessor::preprocess` when you only need conditional compilation and
-shader-definition substitution for a single source string.
-
-```mbt check
-///|
-test "README: preprocess one shader" {
-  let defs : Map[String, @common.ShaderDefValue] = Map([])
-  defs.set("TEXTURE", Bool(true))
-
-  let source = "#ifdef TEXTURE\nvar sprite_texture: texture_2d<f32>;\n#else\nvar sprite_texture: texture_2d_array<f32>;\n#endif\n"
-  let output = @preprocess.Preprocessor::default().preprocess(source, defs) catch {
-    _ => abort("preprocess failed")
-  }
-
-  debug_inspect(
-    output.preprocessed_source.contains("texture_2d<f32>"),
-    content="true",
-  )
-}
-```
-
-### Read Metadata
-
-Use metadata extraction when you want to inspect a shader before composing it.
-
-```mbt check
-///|
-test "README: inspect metadata" {
-  let source = "#define_import_path demo::main\n#define HDR\n#import demo::maths::TWO\nfn scale(x: f32) -> f32 {\n  return x * TWO;\n}\n"
-  let metadata = @metadata.get_preprocessor_metadata(source) catch {
-    _ => abort("metadata extraction failed")
-  }
+The synchronized ownership change is intentionally breaking. Legacy package
+paths, compatibility records in WGSL Core, direct directive/import parsers,
+and the re-exported lower-level `Composer` are not retained as aliases. See
+[`docs/ownership-migration.md`](docs/ownership-migration.md) for the complete
+old-to-new mapping and [`docs/adr/0020-enforce-conceptual-ownership-and-deep-interfaces.md`](docs/adr/0020-enforce-conceptual-ownership-and-deep-interfaces.md)
+for the final architecture.
 
-  debug_inspect(metadata.name, content="Some(\"demo::main\")")
-  debug_inspect(metadata.imports.length(), content="1")
-}
-```
-
-### Export One File
-
-Use `export_wgsl_with_options` to compose and tree-shake a root shader into one
-WGSL file.
-
-```mbt check
-///|
-test "README: export single file" {
-  let composer : @compose.Composer = @compose.Composer::default()
-  composer.clear_sources()
-  composer.register_source(
-    "shared.wgsl", "#define_import_path demo::shared\nstruct Value {\n  x: f32,\n}\nfn read(value: Value) -> f32 {\n  return value.x;\n}\n",
-  )
-  composer.register_source(
-    "main.wgsl", "#import demo::shared::{Value, read}\nfn shade(value: Value) -> f32 {\n  return read(value);\n}\n",
-  )
-
-  let compose_options : @common.WgslComposeOptions = @common.WgslComposeOptions::default()
-  let export_options : @common.WgslExportOptions = { root_items: ["shade"] }
-  let output = @export.export_wgsl_with_options(
-    composer, "main.wgsl", compose_options, export_options,
-  ) catch {
-    err => abort(err.message())
-  }
-
-  debug_inspect(output.source.contains("#import"), content="false")
-  debug_inspect(output.source.contains("fn shade"), content="true")
-  debug_inspect(output.diagnostics.length(), content="0")
-}
-```
-
-## Import Syntax
-
-The supported import forms match common `naga_oil` usage:
-
-```wgsl
-#import bevy_render::view::View
-#import bevy_render::maths as maths
-#import bevy_render::{view::View, globals::Globals}
-#import bevy_render::{maths::{PI_2, powsafe}}
-#import "shaders/skills/shared.wgsl" Vertex, VertexOutput
-#import "../shared/common.wgsl" SharedVertex, build_color
-```
-
-Relative quoted imports are resolved against the registered path of the
-importing shader.
-
-## Recommended APIs
-
-- `@compose.Composer::default`
-- `Composer::register_source`
-- `Composer::register_source_files`
-- `Composer::register_source_tree`
-- `Composer::compose_wgsl`
-- `@preprocess.Preprocessor::default`
-- `Preprocessor::preprocess`
-- `@metadata.get_preprocessor_metadata`
-- `@resolver.scan_wgsl_source_files`
-- `@resolver.scan_wgsl_source_files_checked`
-- `@export.export_wgsl_with_options`
-
-Important option/result types live in `@common`, including:
-
-- `WgslComposeOptions`
-- `WgslExportOptions`
-- `WgslSourceFile`
-- `WgslSourceScanOptions`
-- `PreprocessOutput`
-- `PreprocessorMetaData`
-- `PreparedWgslSource`
-- `WgslExportOutput`
-- `WgslDiagnostic`
-- `ShaderDefValue`
-
-## Compatibility
-
-The library aims to preserve the practical `naga_oil` programming model used by
-real shader pipelines. Internally, composition uses structured parsing,
-symbol-identity-aware binding, and an IR-backed validation pipeline before
-returning runtime-oriented WGSL.
-
-For implementation details and parity status, see:
-
-- [`docs/naga_oil-parity.md`](docs/naga_oil-parity.md)
-- [`docs/moon_wgsl-issue-tracker.md`](docs/moon_wgsl-issue-tracker.md)
-
-## Development
-
-Run the test suite from the module root:
-
-```bash
-moon test
-```
+Development and release commands are documented in [`README.md`](README.md).
 
 ## License
 

README.md

@@ -9,13 +9,20 @@ by ownership instead of exposing every internal package through one module.
   and runtime WGSL emission.
 - `Milky2018/moon_wgsl_naga`: Naga-compatible writer and trace entry points.
 - `Milky2018/moon_wgsl_naga_oil`: naga-oil-compatible preprocessing,
-  import resolution, composition, and export.
+  import resolution, composition contracts, explicit project profiles, and
+  export.
 - `Milky2018/moon_wgsl`: thin user-facing facade for ordinary preprocessing and
   composition workflows.
 
 Most users should install `Milky2018/moon_wgsl`. Use the lower-level modules
 only when you need their specific parser, IR, Naga, or naga-oil boundary.
 
+The facade owns an opaque `Composer` with only registration, `prepare`,
+`compose`, and `export_wgsl` workflows. Repository diagnostics use the explicit
+`Milky2018/moon_wgsl_naga_oil/diagnostics` adapter. Naga-oil directive parsing,
+import parsing, substitution, transformation, and source editing are
+compiler-enforced `internal/` packages.
+
 ## Migration
 
 Legacy internal paths such as `Milky2018/moon_wgsl/parser`,
@@ -27,10 +34,20 @@ Use these imports instead:
 ```text
 Milky2018/wgsl/parser
 Milky2018/wgsl/ir
+Milky2018/moon_wgsl_naga_oil/contract
+Milky2018/moon_wgsl_naga_oil/profile
 Milky2018/moon_wgsl_naga_oil/compose
 Milky2018/moon_wgsl_naga_oil/preprocess
 ```
 
+The former `Milky2018/wgsl/common` contracts now belong to
+`Milky2018/moon_wgsl_naga_oil/contract`. The former
+`default_wgsl_value_defines()` policy is now the explicit
+`bevy_wgsl_value_defines()` profile.
+
+See [the ownership migration guide](docs/ownership-migration.md) for the full
+package, type, method, result-accessor, and diagnostics mapping.
+
 ## Development
 
 Run workspace checks from the repository root:

docs/adr/0020-enforce-conceptual-ownership-and-deep-interfaces.md

@@ -0,0 +1,87 @@
+# Enforce conceptual ownership and deep interfaces
+
+The physical workspace split is necessary but not sufficient. A module owns a concept only when its interface and implementation can change for that concept without forcing an unrelated lower-level module to change. The workspace therefore adopts the following final seams and treats deviations as migration debt tracked by ISS-034.
+
+## WGSL Core
+
+`Milky2018/wgsl` owns the Official WGSL Frontend:
+
+- official WGSL lexer, AST, parser, validation, and semantic IR
+- official `enable`, `requires`, and `diagnostic` directives
+- generic semantic analysis and valid-WGSL writing
+- neutral writer mechanics only when their interface contains no Naga or naga-oil policy
+
+WGSL Core does not own preprocessing conditionals, shader definitions, imports, composition descriptors, source registries, symbol redirects, project profiles, generated-import provenance, final names, link graphs, import arena events, or compatibility writer modes.
+
+`parse_wgsl_module_to_ir(source)` is the sole public semantic-lowering entry point. The resulting semantic IR records program meaning and source facts required by official WGSL diagnostics. It contains no compatibility flags, provenance caches, compose graph records, or writer naming policy.
+
+## naga-oil frontend and composer
+
+`Milky2018/moon_wgsl_naga_oil` owns all naga-oil dialect syntax and composition contracts:
+
+- `ifdef`, `ifndef`, conditional expressions, defines, template constants, `define_import_path`, and imports
+- shader-definition values and explicitly selected project profiles
+- preprocess, metadata, source registry, compose, export, source catalog, and compatibility diagnostic contracts
+- Compose Graph, Symbol Graph, Final Name Table, import events, source provenance, emission plans, and source editing
+
+The naga-oil frontend preserves extension-source spans and diagnostics, then produces official WGSL before invoking WGSL Core. It may reuse the neutral lexer, but it must not add dialect variants to the official AST.
+
+Generic defaults are empty and language-neutral. Bevy-compatible defaults live in an explicit profile selected by a caller; they are not implicit WGSL or generic composer facts.
+
+Directive scanning, import syntax parsing, transform, import substitution, and source rewrite are in-process implementation packages under `Milky2018/moon_wgsl_naga_oil/internal/`. MoonBit's `internal` visibility prevents packages outside the owning module from importing them while preserving local package boundaries and white-box invariant tests. Their seams are not external interfaces.
+
+## Naga compatibility
+
+`Milky2018/moon_wgsl_naga` owns Naga-shaped declaration provenance, import ordering events, arena scheduling, final temporary naming, and writer behavior.
+
+Its central seam is conceptually:
+
+```text
+write_naga_compatible_wgsl(
+  module: WgslSemanticIr,
+  context: NagaCompatibilityContext,
+  options: NagaWriterOptions,
+) -> String
+```
+
+`NagaCompatibilityContext` is opaque. Its construction types are Naga-owned compatibility facts, not WGSL IR records and not naga-oil graph implementation types. naga-oil maps its graph into this context. The Naga module derives its compatibility view internally; callers never mutate semantic IR to request compatibility behavior.
+
+Trace and parity inspection belong to a diagnostics package used by repository tools. They are not methods on the normal writer or facade object.
+
+## Moon WGSL Facade
+
+`Milky2018/moon_wgsl` owns its user-facing `Composer` type instead of re-exporting the naga-oil implementation type. The target method interface is:
+
+- `Composer::default`
+- `Composer::register_source`
+- `Composer::register_source_files`
+- `Composer::clear_sources`
+- `Composer::add_module`
+- `Composer::remove_module`
+- `Composer::compose`
+- `Composer::prepare`
+- `Composer::export`
+
+`compose` is the single normal composition entry point. Runtime-valid versus strict compatibility output is selected through `ComposeOptions`, not through additional pipeline-stage methods. Filesystem scanning remains a separate adapter because it introduces I/O and is not required by the in-memory composition seam.
+
+The facade owns its errors and maps lower-level failures. It exposes no before-IR, trace, parity, writer-plan, symbol-graph, source-edit, or internal-stage interface.
+
+## Writer source ownership
+
+Source symlinks are not an ownership mechanism. WGSL Core is the sole source owner for three neutral deep services: `WgslIrReachability` computes semantic root reachability, `WgslIrTypeInference` answers expression type queries, and `WgslIrTypeSpelling` formats types from caller-supplied final-name and global-expression lookups plus two explicit byte spelling choices. These interfaces are much smaller than their implementations and contain no Naga ordering, provenance, temporary naming, or compatibility view.
+
+The Naga adapter consumes those services and owns all compatibility policy. It supplies names and byte choices but cannot mutate semantic IR through the service interfaces. The architecture manifest records each source owner, rejects retired Naga copies even under a new exact-copy path, and forbids all cross-module source symlinks.
+
+## Migration and enforcement
+
+This change is a synchronized breaking release. Compatibility aliases must not remain in WGSL Core merely to preserve old imports.
+
+The architecture manifest records:
+
+- exact package inventories
+- forbidden concept families by owning path
+- complete facade type method inventories, following re-exported types
+- source symlink ownership
+- issue-linked migration exceptions
+
+An exception is valid only while its issue is unresolved. Once the violating code disappears, the exception becomes stale and must be removed. A closed issue with a remaining exception or violation fails the architecture gate.