docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -20,10 +20,10 @@ This document defines syntax only. Runtime behavior, optimizer policy, and bytec
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
1. Runtime authority ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
|
||||
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/ISA_CORE.md))
|
||||
3. This document
|
||||
4. Legacy references (`docs/specs/random/pbs_old/*`)
|
||||
4. Retired PBS drafts are historical context only and carry no normative authority.
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
@@ -76,8 +76,8 @@ Keywords are not valid identifiers.
|
||||
Active keywords in `.pbs`:
|
||||
|
||||
- `import`, `from`, `as`
|
||||
- `service`, `host`, `fn`, `apply`, `bind`, `new`, `implements`, `using`, `ctor`
|
||||
- `declare`, `struct`, `contract`, `error`, `enum`, `callback`, `global`, `Self`, `this`
|
||||
- `service`, `host`, `fn`, `apply`, `new`, `implements`, `using`, `ctor`
|
||||
- `declare`, `struct`, `contract`, `error`, `enum`, `global`, `Self`, `this`
|
||||
- `pub`, `mut`
|
||||
- `let`, `const`
|
||||
- `if`, `else`, `switch`, `default`, `for`, `from`, `until`, `step`, `while`, `break`, `continue`, `return`
|
||||
@@ -96,6 +96,10 @@ Reserved (not active syntax in v1 core):
|
||||
- `spawn`, `yield`, `sleep`
|
||||
- `match`
|
||||
|
||||
Retired source forms `declare callback` and `bind(...)` MUST be rejected;
|
||||
[function values and captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
|
||||
defines their replacement. Retired tokens are not active declaration/call syntax.
|
||||
|
||||
Note:
|
||||
|
||||
- `host` is used only by reserved SDK/toolchain `declare host` surfaces in v1 core; ordinary user-authored modules MUST reject those declarations.
|
||||
@@ -366,7 +370,7 @@ Rules:
|
||||
|
||||
### 7.2 First-class function values
|
||||
|
||||
Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) -> Return { ... }`; `[]` and all signature annotations are mandatory. See [First-class functions and explicit value captures](../../../compiler/pbs/specs/first-class-functions-and-captures.md).
|
||||
Function types use `Fn(T1, T2) -> R`. Lambdas use `fn [captures](name: Type) -> Return { ... }`; `[]` and all signature annotations are mandatory. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
|
||||
|
||||
### 7.3 Services
|
||||
|
||||
@@ -380,7 +384,7 @@ ServiceMember ::= 'fn' Identifier ParamList ReturnAnn? Block | ConstDecl
|
||||
Rules:
|
||||
|
||||
- `declare service Name { ... }` declares a nominal service type together with its canonical module-owned singleton value `Name`.
|
||||
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](../../../compiler/pbs/specs/service-constants-and-runtime-math.md).
|
||||
- A service body contains method declarations and `declare const` members. SDK service intrinsic signatures may terminate with `;`; see [Service constants and runtime math](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md).
|
||||
- Service methods have an implicit receiver binding `this` of type `Self` and do not declare `this: Self` explicitly.
|
||||
- Services do not declare fields.
|
||||
- Services do not declare `ctor`.
|
||||
@@ -446,7 +450,7 @@ Rules:
|
||||
- A `declare const` initializer is required unless another specification explicitly permits a reserved declaration-only shell such as builtin constant metadata.
|
||||
- A `declare const` initializer, when present, MUST be a constant expression as defined by static semantics.
|
||||
- `declare const` values are compile-time constants, not runtime-initialized module storage.
|
||||
- A reserved top-level builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
|
||||
- A reserved top-level or SDK service builtin constant shell MAY use attributes such as `BuiltinConst(...)` and omit the initializer when another specification explicitly defines VM-owned materialization.
|
||||
|
||||
## 8. Type syntax
|
||||
|
||||
@@ -611,7 +615,7 @@ Rules:
|
||||
- `new Type(args...)` is the canonical struct construction surface.
|
||||
- `new Type.ctorName(args...)` is the canonical named-constructor surface.
|
||||
- Struct construction arguments are positional and follow the declared struct field order.
|
||||
- `as` is reserved in expressions for explicit contract-view conversion only; it does not denote a general cast surface in v1 core.
|
||||
- `as` expresses explicit contract-view conversion or the supported numeric conversions defined by [input and value alignment](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md). It is not an unrestricted cast.
|
||||
- A contract-view `as` target is a visible contract type, including explicit arguments such as `Identity<int>`, never a qualified module path. Existing numeric conversions retain their value-alignment rules.
|
||||
- `this` is an implicit receiver name available only inside struct method, service method, and `ctor` bodies.
|
||||
- `Self` is valid only inside struct method declarations, service method declarations, and `ctor` declarations.
|
||||
@@ -1199,25 +1203,27 @@ fn test(e: Enum) -> str {
|
||||
|
||||
## Typed arrays and optional execution extension
|
||||
|
||||
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
||||
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
|
||||
defines the complete type, optional-flow and storage contract.
|
||||
This chapter owns the source syntax and spans consumed by that feature.
|
||||
|
||||
Retired `declare callback`, callback exports and `bind(...)` are rejected. They do not provide alternative spellings for Fn or lambdas.
|
||||
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
||||
|
||||
|
||||
## Parameterized contracts
|
||||
|
||||
Parameterized contracts use explicit angular arguments in annotations, nested types, implements and as. Barrels export the ordered parameter list. Raw generic uses, empty argument lists and default arguments are invalid; existing contextual closers and Array construction sugars remain unchanged.
|
||||
|
||||
See [PBS generic contracts](../../../compiler/pbs/specs/generic-contracts.md).
|
||||
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
|
||||
|
||||
|
||||
## Concrete generic structs and free functions
|
||||
|
||||
Struct and module-level free-function declarations and their barrel items accept ordered type parameters. Explicit function applications are reference expressions; calls use existing parentheses/apply. Generic construction supports explicit arguments and contextual diamond/omission. Owner-bound `implements` accepts its own parameter binder and a full applied owner. Independent method parameters, function diamond/inference and polymorphic Fn remain invalid. The owner specification defines exact arity, comparison disambiguation and recovery.
|
||||
|
||||
See [Concrete generic structs and free functions](../../../compiler/pbs/specs/generic-structs-and-free-functions.md).
|
||||
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
|
||||
|
||||
|
||||
## Controlled guest lifecycle marker syntax
|
||||
|
||||
Reference in New Issue
Block a user