RFC 0003: Modules, Packages, and Supply-Chain Metadata

Status: Accepted
Areas: Appendix G.2, G.4; Appendix H.6, H.11, H.14, H.17

Decision: Accepted by the project owner on 2026-10-23. This approves the design direction; implementation and conformance evidence remain outstanding.

Implementation progress

• 2026-10-26 — Source-rooted layer enforcement: compile_source locates the nearest ancestor containing both yaza.toml and src/ by walking upward from the source file path, then applies the declared architecture policy. This closes the bypass where yaza check /path/to/project/src/main.yz run from another working directory silently skipped the project's layer rules. tests/api-layer-conformance-smoke.sh checks a valid API project from outside its root and adds a forbidden controllers -> repositories import; the invalid project is rejected with the source path and layer edge. This does not add package-root imports, symlink-aware resolution, dependency locking, or supply-chain verification.

Summary

Define package/module boundaries, enforceable layered architecture rules, reproducible dependency resolution, and a verifiable package supply chain. A YAZA project should build from a checked-in lockfile without executing arbitrary dependency code by default.

Motivation

Current imports are limited to relative function files. yaza.toml describes starter metadata but does not resolve packages or enforce layer rules. There is no lockfile, package registry, signature verification, SBOM, or dependency advisory workflow.

Proposal

1. A package is rooted at yaza.toml; modules map to directories and .yz files. Import paths are package-relative and explicit; ambient filesystem search is not used.
2. The manifest declares package name/version, minimum compiler version, source root, targets, dependencies, development dependencies, and optional layer rules.
3. Architecture policies describe permitted import edges (for example, controllers -> services -> repositories) and are checked during yaza check and yaza build. The current implementation finds the project root from an explicit source path, even when the command runs from another working directory, and enforces relative source imports there. Package-root import resolution, symlink-aware canonicalization, and interface-only cycle rules remain future work.
4. yaza add resolves compatible versions and updates both the manifest and yaza.lock; ordinary yaza build uses exact locked sources and does not silently upgrade.
5. Lock entries record immutable source identity and cryptographic content hashes. Registry packages are verified against publisher signatures and transparency/provenance metadata when available. Local path dependencies are clearly marked and excluded from portable release guarantees.
6. Build scripts are disabled by default. If a package requires one, the manifest must declare it and the build tool must show the requested capabilities before execution; a later sandbox design must restrict filesystem, network, and process access.
7. yaza audit reports lockfile integrity, known advisories when an advisory source is configured, unsafe blocks, and missing release metadata. Output is machine-readable as JSON as well as human-readable.
8. Release artifacts include an SBOM, source revision, toolchain identity, build settings, and provenance statement. Signing keys remain outside the build job; published binaries and packages are signed.

Illustrative manifest:

[package]
name = "catalog-api"
version = "0.1.0"
compiler = ">=0.2.0"

[architecture]
layers = ["routes", "controllers", "services", "repositories", "models"]
allow = ["routes -> controllers", "controllers -> services", "services -> repositories"]

[dependencies]
http = "^1.2"

Exact manifest syntax, registry protocol, and trust-root distribution are deliberately open until a prototype and threat review exist.

Security considerations

Hash pinning alone does not prove a source is safe or its publisher is trustworthy. Signature verification must identify the trust root and revocation behavior. Build scripts, compiler plugins, and native FFI code are executable attack surfaces and must never inherit unrestricted authority silently.

Staged implementation

1. Specify package/module resolution and layer-policy diagnostics without external dependencies.
2. Add lockfile generation and deterministic offline builds for local packages.
3. Add a test registry and signature verification with documented trust roots.
4. Add advisory ingestion, build isolation, SBOM, provenance, and signed release automation before public registry launch.

Acceptance criteria

• Two clean builds from the same lockfile resolve identical source bytes and produce recorded toolchain metadata.
• Architecture violations fail with an import path and policy explanation.
• Tampered lock entries and invalid/untrusted signatures fail closed.
• Dependency audit explains data source, timestamp, and limitations; offline audit remains usable.
• No public package registry launches without a disclosure process, namespace policy, and recovery plan for compromised credentials.

Open questions

• How are compiler versions and standard-library versions pinned together?
• Which registry trust root and key-rotation mechanism are acceptable?
• What sandbox is available on macOS, Linux, and Windows for build scripts?

← Kembali ke semua dokumentasiVersi dan status rilis →