Skip to content

Section 8: Modules, Imports, and Visibility

TECHSPEC-08 — Section 8 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Module Philosophy

Programs must be divided into clearly defined modules.

Each module owns its declarations and exposes only the functionality intended for use by other modules.

The language must prevent accidental access to internal implementation details.

2. Module Declaration

Every source file must declare its module.

Example:

MODULE BankAccount

Rules: - Every source file belongs to exactly one module. - Module names must be unique within their package. - Module names must follow the language naming conventions. - A module cannot silently redefine another module.

3. Imports

Modules must explicitly import other modules before using their declarations.

Example:

MODULE AccountService

IMPORT BankAccount
IMPORT Logging

FUNCTION getBalance(
    account: BankAccount.Account
) -> Decimal

    RETURN BankAccount.getBalance(account)

END FUNCTION

Rules: - Dependencies must be explicitly declared. - Unimported declarations cannot be accessed. - Imports must resolve to valid modules. - Circular dependencies must be detected. - Importing a module does not automatically grant access to its internal declarations.

4. Visibility

Every declaration must have a defined visibility level.

The initial language supports:

  • PUBLIC: Accessible to importing modules.
  • PRIVATE: Accessible only inside its declaring module.

Example:

MODULE BankAccount

PUBLIC TYPE Account:
    balance: Decimal

PRIVATE FUNCTION validateAccount(
    account: Account
) -> Boolean

    RETURN account.balance >= 0

END FUNCTION

Rules: - Declarations must have explicit visibility. - Private declarations cannot be accessed externally. - Public declarations form the module's external interface. - Internal implementation details should remain private unless intentionally exposed.

5. Module Interfaces

A module's public declarations define its interface.

Rules: - Public functions must have complete type signatures and contracts. - Public types must define their accessible fields and constraints. - Changes to public interfaces must be checked for compatibility. - Internal implementation changes must not silently alter public behavior. - Interface compatibility does not automatically establish behavioral compatibility.

6. Dependency Management

Dependencies must be explicit and reproducible.

Each dependency must identify: - Package or module identity. - Required version or version range. - Resolved version. - Integrity information. - Required permissions and effects.

Rules: - Dependency versions must be recorded in the build. - Unresolved dependencies must prevent a validated build. - Dependency updates must trigger compatibility checks. - Dependencies must not inherit permissions automatically. - The same dependency declaration must resolve reproducibly under the same locked environment.

7. Compiler Responsibilities

The compiler must: - Resolve module declarations and imports. - Detect duplicate module names. - Detect missing dependencies. - Enforce visibility restrictions. - Detect circular dependencies. - Validate public interfaces. - Check dependency compatibility. - Record resolved dependency versions.

8. Design Goal

AI agents must be able to understand exactly where declarations come from, which dependencies a module uses, and which parts of a program it is permitted to access.

Source file: TECHSPEC-8.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.