Skip to content

MANIFEST_AND_LOCKFILE_SPEC.md

Latest commit

 

History

History
129 lines (96 loc) · 4.25 KB

MANIFEST_AND_LOCKFILE_SPEC.md

File metadata and controls

129 lines (96 loc) · 4.25 KB
Raw

ProScript manifest and lockfile specification

Status

The core proscript.toml identity/version/dependency form and dependency-free lockfile behavior are decided. External dependency sources and the final native artifact tables remain open; current compiler-only native tables are documented as an implementation profile, not a stable ecosystem format.

Manifest location and syntax

One module root may contain one human-maintained UTF-8 proscript.toml:

[package]
name = "acme.billing_api"
version = "0.3.1"
language = "0.1"

[dependencies]
zstd = "1.2"

The 0.1 parser accepts a deliberately bounded TOML subset: table headers, bare keys, basic quoted strings, blank lines, and # line comments. Unknown, duplicate, malformed, or out-of-table keys are errors rather than ignored extensions.

[package]

All three keys are required exactly once:

  • name: dot-separated nonempty ASCII snake_case components, not rooted at reserved std;
  • version: exactly major.minor.patch, with decimal nonnegative integers and no prerelease/build suffix in the current profile;
  • language: exactly the selected language mode, currently 0.1.

[dependencies]

Each key is an ASCII snake_case dependency identity. std is forbidden because the toolchain selects the standard library. A requirement has the exact current form major.minor and means a compatible semantic-version range whose precise resolution must be recorded in the lockfile.

The presence of a dependency entry does not authorize a compiler to guess its source. Until acquisition forms are decided, ordinary dependency resolution fails closed.

Current native Rust implementation profile

The active compiler additionally recognizes:

[native.rust]
manifest = "native/Cargo.toml"

[native.rust.handles.FileHandle]
shareability = "task-confined" # or "shareable"
cleanup = "inline"             # or "offload"

The manifest path is a portable project-relative path ending in Cargo.toml, with no empty, . or .. component, and must resolve to a regular file inside the project. Handle names are source identifiers and must exactly cover the native handle policy required by the checked package.

This table authorizes one local trusted Rust build. It contains no raw symbol, ABI slot, artifact digest, target override, or arbitrary command. Its spelling is an implementation/tooling profile until a later decision promotes it to the stable ecosystem contract.

Initialization

proscript init <canonical-package-path>

The command validates its single argument before mutation and exclusively creates only proscript.toml in the current directory:

[package]
name = "<canonical-package-path>"
version = "0.1.0"
language = "0.1"

It uses LF newlines and one final LF. It creates no source, directory, lockfile, dependency, native, VCS, or editor artifact. Existing files are preserved. An existing manifest is never overwritten, merged, or repaired. Failure is non-mutating and leaves no partial file.

Lockfile

proscript.lock is generated and must not be edited. It records the exact resolved graph, source identities, versions, integrity, and selected native artifacts once those source forms exist.

For a dependency-free module, format 1 is exactly:

# Generated by ProScript. Do not edit.
format = 1
language = "0.1"

[[package]]
name = "acme.billing_api"
version = "0.3.1"
source = "local"
integrity = "sha256:<64 lowercase hexadecimal digits>"
dependencies = []

The local integrity identity hashes a domain-separated, length-framed sequence of the exact manifest and deterministically selected source relative paths and bytes. Source paths are project-contained. A change in selected bytes or identity changes integrity.

Until external source identities are specified, a compiler must not emit a plausible-looking multi-package lockfile for a dependency-bearing manifest.

Compatibility

The manifest selects source language semantics explicitly. Pre-1.0 minor modes may contain documented breaking changes; patch releases do not intentionally change semantics. After 1.0, breaking source semantics require a new language major. Compiler IR, object files, native images, and caches are not lockfile distribution contracts. Native ABI majors are separate explicit identities.