docs: define first-class language parity

README.md

@@ -10,6 +10,8 @@ The initial extractor recognizes Rust, Dart, Python, C/C++,
 JavaScript/TypeScript, and Swift source extensions. Symbol extraction is intentionally conservative and
 lexical in v0.1; every relationship records its backend, confidence, and source
 location so consumers can distinguish it from imported symbolic evidence.
+See [language support and parity](docs/architecture/language-support.md) for the
+construct-level coverage matrix and first-class promotion contract.
 
 ## Quick start
 

docs/architecture/language-support.md

@@ -0,0 +1,65 @@
+# Language support and parity
+
+Brick 0.1 recognizes source-file extensions for Rust, Dart, Python, C/C++,
+JavaScript/TypeScript, and Swift. Recognition does not imply compiler-level
+coverage: the current backend is deliberately lexical, line-oriented, and
+evidence-labeled.
+
+The first-class parity targets are Dart, Rust, C/C++, and
+JavaScript/TypeScript. Python and Swift remain secondary until their extraction
+contracts and fixtures reach the same standard.
+
+## Current coverage
+
+| Language | Useful current coverage | Important gaps | Tier |
+| --- | --- | --- | --- |
+| Dart | Classes, mixins, enums, extensions, many methods, imports, `extends`, and ordinary calls | `with`/`implements`, export/part, named constructors, accessors/operators, and multiline declarations | first-class target |
+| Rust | Structs, enums, traits, ordinary/async functions, simple `use`, calls, and raw-string masking | impl/module ownership, const/unsafe/extern functions, macros, turbofish calls, and braced/glob imports | first-class target |
+| C | Files, basic includes, structs, and narrow function forms through the shared C/C++ profile | distinct C identity, enums/typedefs/function pointers, multiline declarations, macros, and declaration masking | first-class target |
+| C++ | Basic classes/structs, narrow function forms, calls, and local include resolution | templates, constructors/destructors/operators, multiple inheritance, namespaces, overloads, lambdas, qualifiers, and multiline declarations | first-class target |
+| JavaScript | Named functions, simple classes/extends, ES imports, and call-shaped expressions | methods, arrows/function expressions, CommonJS, dynamic imports, re-exports, decorators, and template literals | first-class target |
+| TypeScript | JavaScript basics plus TypeScript file extensions and simple imports | interfaces, type aliases, enums/namespaces, generic/abstract declarations, overloads, decorators, and path mappings | first-class target |
+| Python | Basic classes, functions/async functions, imports, calls, and indentation scopes | multiple bases, qualified ownership, decorators, multiline strings, relative/dynamic imports, and complete multi-import handling | secondary |
+| Swift | File recognition and incidental matching of some class/function syntax | no dedicated patterns; imports, protocols, actors, enums, extensions, async/generic forms, and ownership are incomplete | secondary |
+
+## Cross-language invariants
+
+All extractors must satisfy these rules before first-class parity is claimed:
+
+1. Bare symbol names never resolve across language boundaries. Cross-language
+   edges require explicit import, binding, or FFI evidence.
+2. Recognized methods are owned by their enclosing type rather than only by the
+   source file.
+3. Unsupported declarations do not silently become call edges.
+4. Strings, comments, and language-specific literal forms do not create symbols
+   or calls.
+5. Duplicate names use stable qualified identities and do not resolve
+   ambiguously.
+6. Every edge retains backend, confidence, and source evidence. If multiple
+   source locations are collapsed, the evidence must say so.
+
+## Parity test contract
+
+Each first-class language needs deterministic positive and clean-negative
+fixtures for:
+
+- files, types, functions, methods, and containment;
+- imports and inheritance/implementation relationships;
+- local, qualified, member, ambiguous, and unresolved calls;
+- duplicate symbols, nested scopes, strings, comments, and unsupported syntax;
+- stable graph identities and evidence under repeated scans.
+
+Real-repository benchmarks supplement these fixtures but do not replace them.
+Compare graph counts and health metrics only after confirming that analyzed
+files, constructs, and evidence coverage remain stable. A lower health score can
+be more accurate when a false resolved edge becomes an honest unresolved edge.
+
+## Delivery order
+
+1. Shared resolver and scope foundation.
+2. A golden fixture harness and mixed-language collision corpus.
+3. Dart and Rust parity slices.
+4. Separate C and C++ extraction profiles and parity slices.
+5. Separate JavaScript and TypeScript extraction profiles and parity slices.
+6. Explicit Python and Swift characterization, followed by a separate promotion
+   decision if warranted.