feat(pbs): support quoted project imports and installed authoring contracts

This commit is contained in:
2026-11-10 15:19:53 +00:00
parent ea1cc26fe3
commit b351f2e582
159 changed files with 11368 additions and 50 deletions
@@ -17,6 +17,17 @@ Its purpose is to make diagnostics stable enough that:
## 2. Scope
The installed `pbs:example:game:1:production/GUIDE.md` reference maps global
initializer, visibility, malformed project-address and unresolved-import
diagnostics to their normative rules and complete positive/negative examples.
Codes retain their existing identity; a bounds fault remains an execution
outcome rather than a fabricated compile-time diagnostic. Blank quoted project
names are source errors, not internal `ModuleReference` construction exceptions.
Existing explanation payloads have no navigable reference-ID field for these
mappings. Tools MUST preserve that limitation and use the explicit installed
guide rather than infer rules from rendered messages or expand a public schema.
This document defines:
- the required external diagnostic phases,
@@ -234,10 +234,27 @@ Imports target modules, never files.
ImportDecl ::= 'import' ( ModuleRef | '{' ImportList '}' 'from' ModuleRef ) ';'
ImportList ::= ImportItem (',' ImportItem)*
ImportItem ::= Identifier ('as' Identifier)?
ModuleRef ::= '@' Identifier ':' ModulePath
ModuleRef ::= '@' ProjectName ':' ModulePath
ProjectName ::= Identifier | StringLiteral
ModulePath ::= Identifier ('/' Identifier)*
```
`StringLiteral` here is the ordinary double-quoted string from section 4, with
only the existing `\\`, `\"`, `\n`, `\r` and `\t` escapes. Text blocks and
expressions are not project names. The decoded value must be nonblank and
identifies the exact manifest project name; delimiters do not become identity.
```pbs
import { Inventory } from @"zelda-1":inventory;
import { Collision } from @"physics-2d":collision;
```
This alternative applies to both module and named imports. Existing identifier
imports remain valid. Quoting is limited to the project segment: module paths
retain identifier segments. Unquoted `@zelda-1:inventory` is malformed; use
`@"zelda-1":inventory`. Quoting does not create a universal current-project alias.
See specification 5 for exact identity and reserved-space resolution.
### 6.1.1 Attributes
Attributes are bracketed compile-time metadata forms.
@@ -335,6 +335,27 @@ Rules:
- `if`,
- and `switch`.
#### Authoring state with private implementation details
Keep state construction and its private helper types in the defining module;
expose operations and public result types rather than requiring consumers to
construct the implementation. File-private declarations stay in their defining
file. Use `mod` barrel entries for admitted sibling-file access and `pub` entries
for importing modules. A private dependency used by a public implementation does
not become a caller-visible declaration.
Use supported direct construction in global initializers and perform procedural
factory calls in admitted executable contexts, including permitted `[Init]`
bodies. This does not admit factory calls into global initializers or provide
automatic placeholder values. The existing transitive init-admission rules and
one-shot bootstrap order in specification 9 still apply. Imports of globals and
services preserve their defining storage and singleton identity.
The installed `pbs:example:game:1:production/GUIDE.md` reference and its complete
projects demonstrate these boundaries, including deliberately rejected controls.
Joining files, exporting helpers or renaming private types is not a language
requirement for the corrected production binding cases.
### 3.5 Enum declarations and values
Rules:
@@ -104,6 +104,27 @@ Rules:
- Module path segments are directory-style segments separated by `/`.
- The syntax is Java-like in organization and JavaScript-like in import surface.
The project segment accepts an identifier or ordinary quoted string, as defined
in specification 3. `@game:state` and `@"game":state` resolve to the same canonical
module; `@"zelda-1":state` represents the exact manifest name `zelda-1`.
The decoded string MUST match the existing resolved project name exactly. There
is no trimming, case folding, slug conversion or path interpretation. Empty or
blank names are source errors. The quoted representation works for the owning
project and ordinary dependencies, including a dependency referencing its own
modules. It does not discover dependencies or change their declared graph.
`@app` is an ordinary project name, not a universal self alias.
Reserved-space checks use the decoded name: `@"sdk":gfx` and `@"core":color`
still resolve exclusively against the selected stdlib. Quoting cannot bypass
visibility, canonical-origin collisions or reserved-space rules. Source producers
MUST quote and escape names that are not legal non-keyword PBS identifiers.
Well-formed but unavailable project/module names fail resolution; malformed
literals fail lexical/syntax analysis. A frontend supporting this additive
syntax is required to consume new quoted sources. Existing sources, the common
manifest name contract, stdlib major, ABI and PBX remain unchanged.
Examples:
- `@game:player/state`
@@ -199,12 +220,18 @@ Rules:
Example:
```pbs
import { Gfx, color } from @sdk:gfx;
import { Gfx } from @sdk:gfx;
import { Color } from @core:color;
let c: color = color.red;
Gfx.draw_pixel(1, 1, c);
[Frame] fn frame() -> void {
Gfx.fill_rect(1, 1, 8, 8, Color.rgb(255, 0, 0));
}
```
This Game source belongs to a module with `pub fn frame() -> void;` in its
`mod.barrel`. The complete manifest and module are installed in the production
Gfx example, indexed through `pbs:example:game:1:production/GUIDE.md`.
Rules:
- `Gfx` is not implicitly in scope.
@@ -371,7 +398,8 @@ Rules:
### 9.4 Example interface module
Illustrative stdlib interface module:
Illustrative stdlib interface module (hypothetical metadata example, not the
distributed Game SDK API; use the actual Gfx/Color imports above for game code):
```pbs
declare enum color(red, green, blue);
@@ -134,6 +134,27 @@ Nominal manifest metadata does not participate in this runtime boot choice.
The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
Boolean `&&` and `and` are equivalent eager conjunction operators; `||` and `or`
are equivalent eager disjunction operators. None provides short-circuit
evaluation. Each operand is evaluated once, left then right, before the operation,
unless abrupt completion prevents subsequent evaluation. A false left operand
of conjunction or true left operand of disjunction does not skip the right one.
Use nested `if` when a later call or access must depend on a prior check:
```pbs
if index >= 0 {
if index < values.length {
if let value = values[index] { consume(value); }
}
}
```
This is an illustrative body fragment; `values`, `index` and `consume` come from
the surrounding program. `index < values.length && read(values[index])` does not
protect the access. The installed production examples count evaluation effects
and distinguish the safe guard from deliberately faulting eager operands.
### 7.2 Call evaluation
For application:
@@ -205,6 +226,11 @@ At minimum, the following are abrupt-completion forms:
`else` is extraction with fallback, not error handling.
In particular, `values[index] else fallback` evaluates the array access first.
A vacant position at a valid index can yield `none` and select the fallback;
an invalid index faults, including in an empty array, before any fallback can
recover a value. See specification 14 for the fixed-array contract.
### 9.4 Trap behavior
`optional` is trap-free by itself.