A few fixes

Author: Mohammad Fawaz

documentation/language/02_structure.md

@@ -15,45 +15,11 @@ If you need a declaration from another Leo file, you must import it.
 
 ### Program
 
-A program is a collection of code (its functions) and data (its types) that resides at a
-[program ID](#program-id) on the Aleo blockchain. A program is declared as `program {name}.{network} { ... }`.
-The body of the program is delimited by curly braces `{}`.
+A program is a collection of code (its functions) and data (its types) that resides at a program ID on the Aleo blockchain. A program is declared as `program {name}.{network} { ... }`, with the body delimited by curly braces.
 
-```leo file=../code_snippets/layout/main_example/src/main.leo#file
-```
-
-The following must be declared inside the scope of a program in a Leo file:
-
-- mappings
-- storage variables
-- record types
-- entry point `fn` declarations
-
-The following must be declared outside the scope of a program in a Leo file:
-
-- imports
-- struct types
-- helper `fn` definitions
-- `final fn` definitions
-- `interface` definitions
+For the canonical list of which declarations belong inside vs. outside the `program { ... }` block, the program-ID naming rules, and import semantics, see [Project Layout](./01_layout.md#programs).
 
-#### Program ID
-
-A program ID is declared as `{name}.{network}`.
-
-The first character of a `name` must be a lowercase letter.
-`name` can only contain lowercase letters, numbers, and underscores, and must not contain a double underscore (`__`) or the keyword `aleo` in it.
-
-Currently, `aleo` is the only supported `network` domain.
-
-```leo showLineNumbers
-program hello.aleo; // valid
-
-program Foo.aleo;   // invalid
-program baR.aleo;   // invalid
-program 0foo.aleo;  // invalid
-program 0_foo.aleo; // invalid
-program _foo.aleo;  // invalid
+```leo file=../code_snippets/layout/main_example/src/main.leo#file
 ```
 
 ### Constant
@@ -63,10 +29,10 @@ Constants are immutable, and the right-hand side must be an expression evaluatab
 
 Constants can be declared in four scopes:
 
-- **Global scope** (outside all program blocks in a program file): accessible anywhere in the same file.
+- **Global scope** (outside the `program` block in `main.leo`): accessible anywhere in the same file.
 - **Program scope** (inside a `program` block, outside any function): accessible within that program.
 - **Local scope** (inside a function body): accessible only within that function.
-- **Module scope** (in a module file within the same package, i.e. a `.leo` file with no `program` block): accessible within the same package via `path::to::module::CONST_NAME`. See [Modules](./01_layout.md#modules) for details.
+- **Module scope** (any non-`main.leo` source file in the package; module files do not contain a `program` block and may only declare `const`, `struct`, `fn`, and `interface`): accessible within the same package via `path::to::module::CONST_NAME`. See [Modules](./01_layout.md#modules) for details.
 
 Constants are also supported in [libraries](./06_libraries.md), which are separate packages containing reusable code. A library's root file and its submodules may declare constants, accessible from any dependent package as `library::CONST_NAME` or `library::path::to::submodule::CONST_NAME`.
 
@@ -94,9 +60,7 @@ See [ProvableHQ/leo#29274](https://github.com/ProvableHQ/leo/issues/29274).
 
 ### Import
 
-You can import dependencies that are downloaded to the `imports` directory.
-An import is declared as `import {filename}.aleo;`
-The dependency resolver will pull the imported program from the network or the local filesystem.
+An import is declared as `import {filename}.aleo;`. See [Imports](./01_layout.md#imports) for resolution rules and the `imports/` directory layout.
 
 ```leo file=../code_snippets/layout/import_only/src/main.leo#snippet showLineNumbers
 ```
@@ -131,7 +95,7 @@ Structs contain component declarations `{name}: {type},`.
 
 ### Record
 
-A [record](https://developer.aleo.org/concepts/fundamentals/records) data type is declared as `record {name} {}`. A record name must not contain the keyword `aleo`, and must not be a prefix of any other record name.
+A [record](https://developer.aleo.org/concepts/fundamentals/records) data type is declared as `record {name} {}`. A record name must not contain the keyword `aleo`, and must not be a prefix of any other record name **declared in the same program** (the check does not extend across imported programs). The constraint exists because records lower to Aleo identifiers with a `.record` suffix, and prefix collisions would produce ambiguous lowered names.
 
 Records contain component declarations `{visibility} {name}: {type},`. Names of record components must not contain the keyword `aleo`.
 

documentation/language/07_style.md

@@ -128,10 +128,7 @@ The goal is to only have the interface of the program in `main.leo`. Every funct
 
 ### Blank lines
 
-A single blank line should separate the top-level declarations in a `program` scope,
-namely `fn`, `record`, and `mapping` declarations, as well as module-level `struct` and helper `fn` declarations.
-Multiple imports can be optionally separated by a single blank line;
-the last import at the top of the file should be followed by a blank line.
+A single blank line should separate top-level declarations within a `program` scope (entry `fn`, `record`, and `mapping` declarations) and module-level declarations (`struct`, helper `fn`, `final fn`, `interface`). For the canonical ordering of these categories within a file, see [Layout](#layout) below. Multiple imports may optionally be separated by a single blank line; the last import at the top of the file should be followed by a blank line.
 
 ```leo title="Yes:"
 import std.io.Write;
@@ -237,37 +234,17 @@ Start by forking off of the `mainnet` branch to make your changes. Commit messag
 If you need to pull in any changes from the `mainnet` branch after making your fork (for example, to resolve potential merge conflicts),
 please avoid using git merge and instead, git rebase your branch. Rebasing will help us review your changes easily.
 
-#### Tools Required
+For build, formatting, test, and grammar conventions, see [`CONTRIBUTING.md`](https://github.com/ProvableHQ/leo/blob/mainnet/CONTRIBUTING.md) in the repository root. The canonical commands for validation are:
 
-To build Leo from source you will need the following tools:
-
-- The latest Rust stable version and nightly version.
-  - Recommend that you install multiple versions using `rustup`.
-- Cargo
-  - Rusty Hook install via `cargo install rusty-hook`.
-- Clippy
-  - Via rustup, if you didn't do the default rustup install `rustup component add clippy`.
-
-#### Formatting
-
-Please do the following before opening a PR.
-
-- `cargo +nightly fmt --all` will format all your code.
-- `cargo clippy --all-features --examples --all --benches`
-
-#### Tests
-
-If your code adds new functionality, please write tests to confirm the new features function as expected. Refer to existing tests for examples of how tests are expected to be written. Please refer to the [parser tests section](#parser-tests). To run the tests please use the following command `cargo test --all --features ci_skip --no-fail-fast`.
-
-##### **Parser Tests**
-
-In the root directory of the repository, there is a "tests" directory.
-To add a parser test, look at the Example Leo files in the parser sub-directory.
-Then when running the test command, make sure you have the environment variable `CLEAR_LEO_TEST_EXPECTATIONS` set to true. For example, on a UNIX environment, you could run the following command `CLEAR_LEO_TEST_EXPECTATIONS=true cargo test --all --features ci_skip --no-fail-fast`.
+```bash
+cargo check
+cargo clippy -- -D warnings
+cargo +nightly fmt --check
+cargo test
+```
 
-#### Grammar
+To update parser expectation files after intentional grammar changes, run `UPDATE_EXPECT=1 cargo test -p leo-parser`.
 
-[The `grammars` repository](https://github.com/ProvableHQ/grammars) contains a file [`leo.abnf`](https://github.com/ProvableHQ/grammars/blob/master/leo.abnf) that has the Leo grammar rules in the ABNF format.
-If your changes affect a grammar rule, we may ask you to modify it in that `.abnf` file.
+The Leo grammar is maintained in the [`grammars` repository](https://github.com/ProvableHQ/grammars) (`leo.abnf`).
 
 We appreciate your hard work!

documentation/language/operators/standard_operators.md

@@ -983,7 +983,7 @@ height in a program.
 
 :::info
 
-- The `block.height` operator can only be used inside a `final { }` block or inside a `final fn`. Using it outside will result in a compilation error.
+- The `block.height` operator can only be used inside a `final { }` block or a `final fn`. It is rejected in entry `fn` bodies, helper `fn`s, and constant initialisers, since chain state is only observable in the finalization context.
 - The `block.height` operator doesn't take any parameters.
 
   :::
@@ -1001,7 +1001,7 @@ The `block.timestamp` operator is used to fetch the UNIX timestamp of the latest
 
 :::info
 
-- The `block.timestamp` operator can only be used inside a `final { }` block or inside a `final fn`. Using it outside will result in a compilation error.
+- The `block.timestamp` operator can only be used inside a `final { }` block or a `final fn`. It is rejected in entry `fn` bodies, helper `fn`s, and constant initialisers, since chain state is only observable in the finalization context.
 - The `block.timestamp` operator doesn't take any parameters.
 
   :::

documentation/language/programs_in_practice/limitations.md

@@ -8,25 +8,24 @@ toc_max_heading_level: 3
 
 snarkVM imposes the following limits on Aleo programs:
 
-- the maximum size of the program is 100 KB, by the number of characters.
-- the maximum number of mappings is 31.
-- the maximum number of imports is 64.
-- the maximum length of a program name is 30 characters (excluding the `.aleo` suffix).
-- the maximum import depth is 64.
-- the maximum call depth is 31.
-- the maximum number of functions is 31.
-- the maximum number of structs is 310.
-- the maximum number of records is 310.
-- the maximum number of closures is 62.
+- the maximum size of the compiled program is **512 KB** by character count (was 100 KB before consensus version V14).
+- the maximum number of mappings is **31**. Each `storage` singleton consumes one mapping slot, and each `storage` vector consumes two (one for values, one for length), so storage declarations share this budget with explicit `mapping` declarations.
+- the maximum number of imports is **64**.
+- the maximum length of a program name is **30 characters** (excluding the `.aleo` suffix). Identifiers (including struct, record, mapping, and function names) are limited to **31 ASCII alphanumeric or underscore characters** by the Aleo identifier rules.
+- the maximum number of functions is **31** (entry `fn`s plus the synthesised on-chain functions produced by `final { }` blocks and `constructor`).
+- the maximum number of structs is **310** (`10 × MAX_FUNCTIONS`).
+- the maximum number of records is **310**.
+- the maximum number of closures is **62** (`2 × MAX_FUNCTIONS`).
+- the maximum number of inputs and outputs **per entry point** is **16** each.
 
 **If your _compiled_ Leo program exceeds these limits, then consider modularizing or rearchitecting your program.** The only way these limits can be increased is through a formal protocol upgrade via the governance process defined by the Aleo Network Foundation.
 
 Some other protocol-level limits to be aware of are:
 
-- **the maximum transaction size is 128 KB.** If your program exceeds this, perhaps by requiring large inputs or producing large outputs, consider optimizing the data types in your Leo code.
-- **the maximum number of micro-credits your transaction can consume for on-chain execution is `100_000_000`.**. If your program exceeds this, consider optimizing on-chain components of your Leo code.
+- **the maximum transaction size is 768 KB** (was 128 KB before consensus version V14). If your program exceeds this — for example by requiring large inputs or producing large outputs — consider optimizing the data types in your Leo code.
+- **the maximum number of micro-credits your transaction can consume for on-chain execution is `100_000_000`.** If your program exceeds this, consider optimizing on-chain components of your Leo code.
 
-As with the above restrictions, these limits can only be increased via the governance process.
+As with the above restrictions, these limits can only be increased via the governance process. Authoritative values live in `snarkvm-console-network` (`MAX_PROGRAM_SIZE`, `MAX_MAPPINGS`, `MAX_FUNCTIONS`, etc.).
 
 ## Compiling Conditional On-Chain Code