Enforce file-local module scopes and preserve reference identities

Resolve imported declarations in their defining scopes, enforce L76 import locality, and retain immutable generic alias obligations and direct global allocation identities.

Qualified frozen source passed all release checks: 3756 tests and one expected failure, 51 examples in every profile, installed packages, site and dependency/security checks. Later documentation checks passed separately; V1 remains incomplete.

Author: code5717

README.md

@@ -99,8 +99,12 @@ instantiations. String comparison uses byte contents. Read the [language tour](e
 and [specification](docs/SPEC.md) together with [Status](docs/STATUS.md).
 
 Local bindings cannot reuse an import alias from their own file. This includes
-function parameters, loop bindings and match captures. Full module namespace
-isolation remains unfinished.
+function parameters, loop bindings and match captures. Each file has its own
+namespace. Imported declarations use `alias.name`; top-level `_name` is private,
+and struct fields remain visible. Qualified types and struct literals retain
+their defining file's identity. Import aliases remain local to the file that
+declares them. See [qualification](docs/audits/2026-10-07/qualification.md) and
+[Status](docs/STATUS.md) for the source-specific verification boundary.
 
 Use `usize` for sizes, lengths and indices. Use `isize` for signed pointer-sized
 offsets and position differences. A7 source recursion is rejected; use loops or
@@ -121,11 +125,16 @@ Heap values currently require `del` or `defer del`. Pass lvalues directly to
 public address-of or dereference operators. Heap fixed arrays, `new [N]T`, are
 rejected. Direct reference aliases share deletion state, and guarded reference
 fields are checked. Alias and lifetime checks remain incomplete for array
-elements and fields reached through joined allocation sets. Automatic memory
-management is not implemented.
-
-The current stdlib provides `io` and `math`. Simple file imports share one
-emitted Zig file; full per-module scopes remain unfinished. Some accepted forms
+elements and fields reached through joined allocation sets. Known direct global
+reference stores now propagate allocation identity through calls, so deleting a
+stored allocation invalidates its caller aliases. Global nil-state and parameter
+proofs remain incomplete. Automatic memory management is not implemented.
+
+The current stdlib provides `io` and `math`. File imports share one emitted Zig
+file after per-file semantic checking. Selected imports and `using import`
+remain incomplete. Forwarding another file's import alias is rejected under
+L76. Unsupported multi-dot type annotations and struct literals still fail
+parsing. Some accepted forms
 still fail later in compilation. The [gap list](docs/STATUS.md) records those
 cases and the remaining generic and numeric limits.
 

a7/compile.py

@@ -510,6 +510,7 @@ def compile_file_detailed(
                     type_map = type_checker.node_types
 
                     if tc_ok:
+                        self._lower_file_module_bindings(ast, symbol_table)
                         validator = SemanticValidationPass(
                             symbol_table, type_checker.node_types
                         )
@@ -1019,32 +1020,90 @@ def _combined_program_for_file_modules(
         module_resolver: Any,
     ) -> ASTNode:
         module_decls: list[ASTNode] = []
-        seen_paths: set[str] = set()
-        for module_info in loaded_modules:
-            if module_info.ast is None or module_resolver.is_virtual_module(module_info.path):
-                continue
-            # Key on the resolved file path, not the import spelling, so one
-            # file loaded under two spellings still merges once. Same-file
-            # double imports are rejected earlier as a compile error.
-            if module_info.file_path in seen_paths:
+        files = [(info.ast, info.file_path) for info in loaded_modules
+                 if info.ast is not None and not module_resolver.is_virtual_module(info.path)]
+        files.append((ast, str(module_resolver.entry_root / "<entry>")))
+        written_names = set()
+        work = [program for program, _ in files]
+        while work:
+            node = work.pop()
+            if node.name:
+                written_names.add(node.name)
+            for value in vars(node).values():
+                if isinstance(value, ASTNode):
+                    work.append(value)
+                elif isinstance(value, list):
+                    work.extend(child for child in value if isinstance(child, ASTNode))
+        seen_paths = set()
+        for index, (program, path) in enumerate(files):
+            if path in seen_paths:
                 continue
-            seen_paths.add(module_info.file_path)
-            prefix = self._module_emit_prefix(module_info.path)
-            for decl in module_info.ast.declarations or []:
-                if decl.kind == NodeKind.IMPORT:
-                    continue
-                if decl.kind == NodeKind.FUNCTION:
-                    decl.module_emit_prefix = prefix
+            seen_paths.add(path)
+            for decl in program.declarations or []:
+                decl.file_scope = path
+                decl.module_index = index
+                decl.module_entry = program is ast
+                if decl.name and program is not ast:
+                    module_path = Path(path).relative_to(module_resolver.entry_root).with_suffix("").as_posix()
+                    identity = self._module_emit_prefix(module_path) + decl.name
+                    while identity in written_names:
+                        identity += "_"
+                    written_names.add(identity)
+                    decl.module_identity_name = identity
+                if decl.kind == NodeKind.IMPORT and not module_resolver.is_virtual_module(decl.module_path or ""):
+                    module = module_resolver.get_module(decl.module_path, path if program is not ast else None)
+                    decl.target_file_scope = module.file_path
                 module_decls.append(decl)
-
-        if not module_decls:
-            return ast
-
-        return ASTNode(
-            kind=NodeKind.PROGRAM,
-            declarations=module_decls + list(ast.declarations or []),
-            span=ast.span,
-        )
+            work = list(program.declarations or [])
+            while work:
+                node = work.pop()
+                vars(node).pop("file_module_call", None)
+                vars(node).pop("module_emit_prefix", None)
+                for value in vars(node).values():
+                    if isinstance(value, ASTNode):
+                        work.append(value)
+                    elif isinstance(value, list):
+                        work.extend(child for child in value if isinstance(child, ASTNode))
+        return ASTNode(kind=NodeKind.PROGRAM, declarations=module_decls, span=ast.span)
+
+    def _lower_file_module_bindings(self, program: ASTNode, symbols: Any) -> None:
+        # File scopes have already resolved every use. The later whole-program
+        # passes receive unique declaration keys in original emission order.
+        if not symbols.file_scopes:
+            return
+        work = list(program.declarations or [])
+        while work:
+            node = work.pop()
+            for value in vars(node).values():
+                if isinstance(value, ASTNode):
+                    work.append(value)
+                elif isinstance(value, list):
+                    work.extend(child for child in value if isinstance(child, ASTNode))
+            bound = symbols.resolved_uses.get(id(node))
+            target = bound.node if bound is not None else None
+            identity = getattr(target, "module_identity_name", None)
+            if identity:
+                node.source_name = node.name or node.field or node.struct_type
+                if node.kind == NodeKind.FIELD_ACCESS:
+                    node.kind = NodeKind.IDENTIFIER
+                    node.name = identity
+                    node.object = None
+                    node.field = None
+                elif node.kind in {NodeKind.IDENTIFIER, NodeKind.TYPE_IDENTIFIER, NodeKind.PATTERN_IDENTIFIER}:
+                    node.name = identity
+                elif node.kind == NodeKind.STRUCT_INIT:
+                    node.struct_type = identity
+                elif node.kind == NodeKind.PATTERN_ENUM:
+                    node.enum_type = identity
+            if getattr(node, "module_identity_name", None):
+                node.source_name = node.name
+                node.name = node.module_identity_name
+        for scope in symbols.file_scopes.values():
+            for symbol in scope.symbols.values():
+                identity = getattr(symbol.node, "module_identity_name", None)
+                if identity:
+                    symbols.global_scope.symbols[identity] = symbol
+        symbols.global_scope.symbols.update(symbols.current_scope.symbols)
 
     def _backend_unsupported_feature_errors(
         self,

a7/exact_constants.py

@@ -144,6 +144,13 @@ def evaluate(root, lookup, bindings):
                 if value is None:
                     return None
                 values[key] = value
+            elif node.kind == NodeKind.FIELD_ACCESS and node.object is not None and node.object.kind == NodeKind.IDENTIFIER:
+                symbol = lookup(f"{node.object.name}.{node.field}")
+                value = bindings.get(id(symbol.node)) if symbol and symbol.node else None
+                if value is None:
+                    return None
+                values[key] = value
+                node.exact_constant = value
             elif node.kind == NodeKind.UNARY and node.operator == UnaryOp.NEG:
                 # `~` is not folded here: `flags & ~1` on a `u8` relies on
                 # the typed operator, and -2 would not fit `u8`.

a7/formatters/console_formatter.py

@@ -134,14 +134,14 @@ def _display_semantic(self, results: dict):
                 sym_table.add_column("Name", style="yellow", width=20)
                 sym_table.add_column("Kind", style="cyan", width=14)
                 sym_table.add_column("Type", style="green")
-                sym_table.add_column("Scope", style="dim", width=12)
+                sym_table.add_column("Scope", style="dim", min_width=12, overflow="fold")
 
                 for sym in symbols[:30]:  # Limit to 30 symbols
                     sym_table.add_row(
                         Text(sym.get("name", "?")),
                         sym.get("kind", "?"),
                         Text(sym.get("type", "?")),
-                        Text(sym.get("scope", "global")),
+                        Text(sym.get("scope", "global"), overflow="fold"),
                     )
 
                 self.console.print(sym_table)
@@ -232,12 +232,19 @@ def _display_pipeline_summary(self, tokens, ast, semantic_results, codegen_resul
     def _collect_symbols(self, symbol_table) -> list:
         """Collect symbols from a symbol table for display."""
         symbols = []
-        scope = symbol_table.current_scope if hasattr(symbol_table, 'current_scope') else None
-        if scope is None and hasattr(symbol_table, 'global_scope'):
-            scope = symbol_table.global_scope
-
+        file_scopes = getattr(symbol_table, "file_scopes", {})
         visited = set()
-        self._walk_scope(scope, symbols, "global", visited)
+        if file_scopes:
+            for filename, scope in file_scopes.items():
+                start = len(symbols)
+                self._walk_scope(scope, symbols, "global", visited)
+                for row in symbols[start:]:
+                    row["scope"] = f"{filename}::{row['scope']}"
+        else:
+            scope = getattr(symbol_table, "current_scope", None)
+            if scope is None:
+                scope = getattr(symbol_table, "global_scope", None)
+            self._walk_scope(scope, symbols, "global", visited)
         return symbols
 
     def _walk_scope(self, scope, symbols: list, scope_name: str, visited: set):

a7/formatters/markdown_formatter.py

@@ -6,6 +6,7 @@
 """
 
 from datetime import datetime
+from html import escape
 from typing import Optional, List, Dict
 
 from .ast_walk import iter_children
@@ -135,7 +136,10 @@ def format_compilation_doc(
                     lines.append("| Name | Kind | Type | Scope |")
                     lines.append("|------|------|------|-------|")
                     for sym in symbols:
-                        lines.append(f"| `{sym['name']}` | {sym['kind']} | `{sym['type']}` | {sym['scope']} |")
+                        scope = escape(sym["scope"], quote=False)
+                        for delimiter in "\\`*_[]|~":
+                            scope = scope.replace(delimiter, "\\" + delimiter)
+                        lines.append(f"| `{sym['name']}` | {sym['kind']} | `{sym['type']}` | {scope} |")
                     lines.append("")
 
             # Errors
@@ -242,11 +246,19 @@ def _format_ast_tree(self, node, lines: list, indent: int = 0) -> None:
     def _collect_symbols(self, symbol_table) -> list:
         """Collect symbols from symbol table."""
         symbols = []
-        scope = symbol_table.current_scope if hasattr(symbol_table, 'current_scope') else None
-        if scope is None and hasattr(symbol_table, 'global_scope'):
-            scope = symbol_table.global_scope
+        file_scopes = getattr(symbol_table, "file_scopes", {})
         visited = set()
-        self._walk_scope(scope, symbols, "global", visited)
+        if file_scopes:
+            for filename, scope in file_scopes.items():
+                start = len(symbols)
+                self._walk_scope(scope, symbols, "global", visited)
+                for row in symbols[start:]:
+                    row["scope"] = f"{filename}::{row['scope']}"
+        else:
+            scope = getattr(symbol_table, "current_scope", None)
+            if scope is None:
+                scope = getattr(symbol_table, "global_scope", None)
+            self._walk_scope(scope, symbols, "global", visited)
         return symbols
 
     def _walk_scope(self, scope, symbols: list, scope_name: str, visited: set):

a7/parser.py

@@ -1309,6 +1309,9 @@ def _expression_steps(self, action, payload):
                 if self.match(TokenType.IDENTIFIER):
                     type_name_token = self.advance()
                     type_name = type_name_token.value
+                    if self.match(TokenType.DOT):
+                        self.advance()
+                        type_name += "." + self.consume(TokenType.IDENTIFIER, "Expected a qualified type name").value
 
                     # Check for generic parameters: Type(T1, T2, ...)
                     if self.match(TokenType.LEFT_PAREN):
@@ -1591,6 +1594,15 @@ def _expression_steps(self, action, payload):
             # Identifiers, cast expressions, or struct literals
             if self.match(TokenType.IDENTIFIER):
                 name = self.advance().value
+                if self.match(TokenType.DOT) and self.peek().type == TokenType.IDENTIFIER:
+                    after = self.position + 2
+                    close = self._close_at.get(after)
+                    literal = self.tokens[after].type == TokenType.LEFT_BRACE or (
+                        self.tokens[after].type == TokenType.LEFT_PAREN and close is not None
+                        and self.tokens[close + 1].type == TokenType.LEFT_BRACE)
+                    if literal and self._should_parse_struct_literal():
+                        self.advance()
+                        name += "." + self.advance().value
 
                 # Check for cast expression: cast(type, expr)
                 if name == "cast" and self.match(TokenType.LEFT_PAREN):
@@ -1999,10 +2011,15 @@ def _expression_steps(self, action, payload):
                             self.current(), self.filename
                         )
                     variant_identifier = self.advance()
+                    enum_name = first_identifier.value
+                    if self.match(TokenType.DOT):
+                        self.advance()
+                        enum_name += "." + variant_identifier.value
+                        variant_identifier = self.consume(TokenType.IDENTIFIER, "Expected a qualified variant name")
 
                     return ASTNode(
                         kind=NodeKind.PATTERN_ENUM,
-                        enum_type=first_identifier.value,
+                        enum_type=enum_name,
                         variant=variant_identifier.value,
                         span=create_span_from_token(start_token),
                     )

a7/passes/name_resolution.py

@@ -96,8 +96,12 @@ def visit_program(self, node: ASTNode) -> None:
         # then tell a constant declared below it from a new name: `case LIMIT:`
         # compares with LIMIT wherever LIMIT is declared in the file.
         for decl in node.declarations or []:
+            if getattr(decl, "file_scope", None):
+                self.symbols.select_file_scope(decl.file_scope)
             self._predeclare(decl)
         for decl in node.declarations or []:
+            if getattr(decl, "file_scope", None):
+                self.symbols.select_file_scope(decl.file_scope)
             self.visit_declaration(decl)
         root_stack = self.symbols.scope_stack
         while self._nested_functions:
@@ -110,6 +114,9 @@ def visit_program(self, node: ASTNode) -> None:
 
     def _predeclare(self, node: ASTNode) -> None:
         """Define a declaration in the current scope without visiting its body."""
+        if node.kind == NodeKind.IMPORT and node.alias and node.alias.startswith("__") and self.symbols.current_scope.parent is None:
+            self.add_error(SemanticErrorType.UNSUPPORTED_FEATURE, node.span,
+                           f"Top-level name '{node.alias}' is reserved for the compiler")
         described = {
             NodeKind.FUNCTION: (SymbolKind.FUNCTION, "Function", False),
             NodeKind.STRUCT: (SymbolKind.STRUCT, "Struct", False),
@@ -124,8 +131,14 @@ def _predeclare(self, node: ASTNode) -> None:
         kind, label, mutable = described
         fallback = "<unknown>" if node.kind in (NodeKind.CONST, NodeKind.VAR) else "<anonymous>"
         name = node.name or fallback
+        if name.startswith("__") and self.symbols.current_scope.parent is None:
+            self.add_error(SemanticErrorType.UNSUPPORTED_FEATURE, node.span,
+                           f"Top-level name '{name}' is reserved for the compiler")
         self._predeclared.add(id(node))
         symbol = Symbol(name=name, kind=kind, type=UNKNOWN, node=node, is_mutable=mutable)
+        identity = getattr(node, "module_identity_name", None)
+        if identity:
+            self.symbols.identity_symbols[identity] = symbol
         if not self.symbols.define(symbol):
             self._rejected.add(id(node))
             self.add_error(SemanticErrorType.ALREADY_DEFINED, node.span, f"{label} '{name}'")