feat(package): lock v3 package-instance graph and strict sync (B-02 B-03 B-04)

- lock the full transitive closure with per-instance alias edges, root
  manifest digest, full content digests and structured path/git sources
- reject v1/v2 locks; validate ids, digests, edges, reachability and sources
- resolve every locked edge by (parent instance, alias) and fail closed on
  missing locks/edges/records, digest or source drift and root drift
- require a lock for run/check/inspect when dependencies exist and map lock
  errors to exit 1
- make sync strict in both modes, never rewrite the lock, and materialize the
  whole closure with env.json schema 2
- verify Git cache markers, require full commit hashes and confirm HEAD
- stop add/remove from patching the lock; regenerate example locks
- update package-format.md and STATUS for S1
This commit is contained in:
cflmy committed 2026-11-20 12:55:30 +08:00
1 parent cd90f38ce1
commit 6fed396d20
8 files changed
+1243 -275

No files matched your search

+56 -52
View File
@@ -144,7 +144,11 @@ fn load_project(file: Option<&Path>, json: bool) -> Result<LoadedProject, i32> {
} else {
eprintln!("error: {error}");
}
Err(2)
if error.contains("marqdo.lock") || error.contains("lockfile") {
Err(1)
} else {
Err(2)
}
}
}
}
@@ -1081,15 +1085,21 @@ pub fn lock(json: bool) -> i32 {
return 2;
}
};
let lockfile = match build_lockfile(&root, &manifest) {
Ok(lockfile) => lockfile,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let graph =
match marqdo_package::PackageResolver::new(root.clone(), Some(manifest.clone()), None)
.with_fetch(true)
.with_unlocked(true)
.resolve_lock_graph()
{
Ok(graph) => graph,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let lockfile = graph.lock;
let path = root.join(marqdo_package::LOCK_FILE);
if let Err(error) = std::fs::write(&path, lockfile.to_yaml()) {
if let Err(error) = write_atomic(&path, lockfile.to_yaml().as_bytes()) {
eprintln!("error: cannot write {}: {error}", path.display());
return 1;
}
@@ -1140,23 +1150,14 @@ pub fn sync(locked: bool, json: bool) -> i32 {
return 1;
}
};
let expected = match build_lockfile(&root, &manifest) {
Ok(lockfile) => lockfile,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
if locked && expected != lockfile {
eprintln!(
"error: lockfile is out of date or dependency contents changed; run `marqdo lock`"
);
if let Err(error) = lockfile.validate_root(&manifest) {
eprintln!("error: {error}");
return 1;
}
let resolver =
marqdo_package::PackageResolver::new(root, Some(manifest.clone()), Some(lockfile))
.with_fetch(true);
if let Err(error) = resolver.materialize_env(&manifest, &expected) {
marqdo_package::PackageResolver::new(root, Some(manifest.clone()), Some(lockfile.clone()))
.with_fetch(!locked);
if let Err(error) = resolver.materialize_env(&lockfile) {
eprintln!("error: cannot materialize project environment: {error}");
return 1;
}
@@ -1165,12 +1166,12 @@ pub fn sync(locked: bool, json: bool) -> i32 {
"command": "sync",
"success": true,
"locked": locked,
"packages": expected.packages,
"packages": lockfile.packages,
}));
} else {
println!(
"synchronized {} package(s){} into {}",
expected.packages.len(),
lockfile.packages.len(),
if locked { " (locked)" } else { "" },
resolver.env_root().display()
);
@@ -1189,27 +1190,34 @@ fn discover_project_root() -> Result<PathBuf, String> {
})
}
fn build_lockfile(
root: &Path,
manifest: &marqdo_package::Manifest,
) -> Result<marqdo_package::LockFile, String> {
let resolver =
marqdo_package::PackageResolver::new(root, Some(manifest.clone()), None).with_fetch(true);
let mut packages = Vec::new();
for name in manifest.dependencies.keys() {
let resolved = resolver.resolve_alias(name)?;
packages.push(marqdo_package::LockedPackage {
name: name.clone(),
instance_id: resolved.package.instance_id,
source: resolved.package.origin.source(),
sha256: resolved.package.content_digest,
});
fn write_atomic(path: &Path, contents: &[u8]) -> Result<(), String> {
let file_name = path
.file_name()
.map(|name| name.to_string_lossy().to_string())
.unwrap_or_else(|| "marqdo.lock".to_string());
let temp = path.with_file_name(format!(
".{file_name}.tmp-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_nanos())
.unwrap_or(0)
));
let result = (|| -> Result<(), String> {
let mut file = std::fs::File::create(&temp)
.map_err(|error| format!("cannot create {}: {error}", temp.display()))?;
std::io::Write::write_all(&mut file, contents)
.map_err(|error| format!("cannot write {}: {error}", temp.display()))?;
file.sync_all()
.map_err(|error| format!("cannot sync {}: {error}", temp.display()))?;
std::fs::rename(&temp, path)
.map_err(|error| format!("cannot publish {}: {error}", path.display()))?;
Ok(())
})();
if result.is_err() {
let _ = std::fs::remove_file(&temp);
}
packages.sort_by(|a, b| a.name.cmp(&b.name));
Ok(marqdo_package::LockFile {
lock_version: 2,
packages,
})
result
}
/// `marqdo add <name> --path <dir> [--git URL --rev SHA]`.
@@ -1295,13 +1303,8 @@ pub fn remove(name: &str, json: bool) -> i32 {
eprintln!("error: cannot write {}: {error}", manifest_path.display());
return 1;
}
// Keep the lockfile consistent by removing the stale entry if present.
let lock_path = root.join(marqdo_package::LOCK_FILE);
if let Ok(lock) = marqdo_package::LockFile::load(&lock_path) {
let mut updated = lock.clone();
updated.packages.retain(|package| package.name != name);
let _ = std::fs::write(&lock_path, updated.to_yaml());
}
// The lock is a graph, not a per-name list: regenerating it here would
// require resolving the new manifest. Leave it stale and tell the user.
if json {
output::print_json(&json!({
"command": "remove",
@@ -1310,6 +1313,7 @@ pub fn remove(name: &str, json: bool) -> i32 {
}));
} else {
println!("removed dependency `{name}`");
println!("run `marqdo lock` to refresh {}", marqdo_package::LOCK_FILE);
}
0
}
+17 -1
View File
@@ -146,8 +146,24 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
None
};
let lock = if root.join(LOCK_FILE).is_file() {
Some(LockFile::load(&root.join(LOCK_FILE))?)
let lock = LockFile::load(&root.join(LOCK_FILE))
.map_err(|error| format!("{LOCK_FILE}: {error}"))?;
if let Some(manifest) = &manifest {
lock.validate_root(manifest)
.map_err(|error| format!("{LOCK_FILE}: {error}"))?;
}
Some(lock)
} else {
if manifest
.as_ref()
.map(|manifest| !manifest.dependencies.is_empty())
.unwrap_or(false)
{
return Err(
"marqdo.lock is missing; run `marqdo lock` before checking or running this project"
.to_string(),
);
}
None
};
let resolver = PackageResolver::new(root.clone(), manifest, lock);
+147 -3
View File
@@ -97,6 +97,13 @@ fn transitive_path_dependency_resolves_from_its_own_manifest() {
&root.join("index.mq.md"),
"---\nimport:\n a: \"@a\"\n---\n\n## main\n\n> 打印(a.outer())\n",
);
let lock = cli(root, &["lock"]);
assert_eq!(
lock.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&lock.stderr)
);
let output = cli(root, &["run", "index.mq.md"]);
assert_eq!(
output.status.code(),
@@ -160,9 +167,11 @@ fn pinned_git_dependency_locks_syncs_and_runs() {
String::from_utf8_lossy(&lock.stderr)
);
let lock_text = std::fs::read_to_string(root.join("marqdo.lock")).unwrap();
assert!(lock_text.contains("lock_version: 2"));
assert!(lock_text.contains("lock_version: 3"));
assert!(lock_text.contains("root_dependencies:"));
assert!(lock_text.contains("instance_id: dep:remote@0.3.0#"));
assert!(lock_text.contains("source: git:"));
assert!(lock_text.contains("kind: git"));
assert!(lock_text.contains("content_digest: "));
let sync = cli(&root, &["sync", "--locked"]);
assert_eq!(
@@ -202,6 +211,141 @@ fn check_does_not_fetch_a_missing_git_revision() {
let output = cli(root, &["check", "index.mq.md"]);
assert_eq!(output.status.code(), Some(1));
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(stderr.contains("not cached") || stderr.contains("cannot open dependency"));
assert!(stderr.contains("marqdo.lock is missing"), "{stderr}");
assert!(!root.join(".marqdo/cache/git").exists());
}
#[test]
fn run_and_check_require_a_lock_when_dependencies_exist() {
let dir = TempDir::new("no-lock");
let root = dir.path();
write(
&root.join("marqdo.yaml"),
"project:\n name: root\n version: 0.1.0\ndependencies:\n dep:\n path: ./dep\n",
);
write(&root.join("dep/index.mq.md"), "## value\n\n*1*\n");
write(
&root.join("index.mq.md"),
"---\nimport:\n dep: \"@dep\"\n---\n\n## main\n\n*1*\n",
);
for command in ["check", "run"] {
let output = cli(root, &[command, "index.mq.md"]);
assert_eq!(output.status.code(), Some(1), "{command}");
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(stderr.contains("marqdo.lock is missing"), "{stderr}");
}
}
#[test]
fn sync_is_strict_and_never_rewrites_the_lock() {
let dir = TempDir::new("strict-sync");
let root = dir.path();
write(
&root.join("marqdo.yaml"),
"project:\n name: root\n version: 0.1.0\ndependencies:\n dep:\n path: ./dep\n",
);
write(&root.join("dep/index.mq.md"), "## value\n\n*1*\n");
write(&root.join("index.mq.md"), "## main\n\n*1*\n");
let lock = cli(root, &["lock"]);
assert_eq!(lock.status.code(), Some(0));
let original = std::fs::read(root.join("marqdo.lock")).unwrap();
write(&root.join("dep/index.mq.md"), "## value\n\n*2*\n");
let stale = cli(root, &["sync"]);
assert_eq!(stale.status.code(), Some(1), "plain sync must be strict");
let stderr = String::from_utf8_lossy(&stale.stderr);
assert!(stderr.contains("lockfile is out of date"), "{stderr}");
assert_eq!(
std::fs::read(root.join("marqdo.lock")).unwrap(),
original,
"sync must never rewrite the lock"
);
let relock = cli(root, &["lock"]);
assert_eq!(relock.status.code(), Some(0));
let after_relock = std::fs::read(root.join("marqdo.lock")).unwrap();
let synced = cli(root, &["sync"]);
assert_eq!(synced.status.code(), Some(0));
assert_eq!(
std::fs::read(root.join("marqdo.lock")).unwrap(),
after_relock
);
}
#[test]
fn lock_records_transitive_closure_and_sync_materializes_it() {
let dir = TempDir::new("closure");
let root = dir.path();
write(
&root.join("marqdo.yaml"),
"project:\n name: root\n version: 0.1.0\ndependencies:\n a:\n path: ./deps/a\n",
);
write(
&root.join("deps/a/marqdo.yaml"),
"project:\n name: a\n version: 0.1.0\ndependencies:\n b:\n path: ./b\n",
);
write(&root.join("deps/a/index.mq.md"), "## a\n\n*1*\n");
write(
&root.join("deps/a/b/marqdo.yaml"),
"project:\n name: b\n version: 0.1.0\n",
);
write(&root.join("deps/a/b/index.mq.md"), "## b\n\n*2*\n");
write(&root.join("index.mq.md"), "## main\n\n*1*\n");
let lock = cli(root, &["lock"]);
assert_eq!(lock.status.code(), Some(0));
let lock_text = std::fs::read_to_string(root.join("marqdo.lock")).unwrap();
assert!(lock_text.contains("name: a"), "{lock_text}");
assert!(lock_text.contains("name: b"), "{lock_text}");
assert!(lock_text.contains("b: dep:b"), "{lock_text}");
let sync = cli(root, &["sync", "--locked"]);
assert_eq!(
sync.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&sync.stderr)
);
let env: serde_json::Value =
serde_json::from_str(&std::fs::read_to_string(root.join(".marqdo/env/env.json")).unwrap())
.unwrap();
assert_eq!(env["schema_version"], 2);
assert_eq!(
env["packages"].as_array().map(|packages| packages.len()),
Some(2)
);
assert!(env["lock_digest"].as_str().unwrap().len() == 64);
}
#[test]
fn deleted_lock_edge_fails_check_and_run() {
let dir = TempDir::new("missing-edge");
let root = dir.path();
write(
&root.join("marqdo.yaml"),
"project:\n name: root\n version: 0.1.0\ndependencies:\n dep:\n path: ./dep\n",
);
write(&root.join("dep/index.mq.md"), "## value\n\n*1*\n");
write(
&root.join("index.mq.md"),
"---\nimport:\n dep: \"@dep\"\n---\n\n## main\n\n*1*\n",
);
assert_eq!(cli(root, &["lock"]).status.code(), Some(0));
let lock = std::fs::read_to_string(root.join("marqdo.lock")).unwrap();
let head = &lock[..lock.find("root_dependencies:").unwrap()];
write(
&root.join("marqdo.lock"),
&format!("{head}root_dependencies: {{}}\n"),
);
for command in ["check", "run"] {
let output = cli(root, &[command, "index.mq.md"]);
assert_eq!(output.status.code(), Some(1), "{command}");
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
stderr.contains("not recorded in marqdo.lock")
|| stderr.contains("not reachable from root_dependencies"),
"{stderr}"
);
}
}
File diff suppressed because it is too large. Load diff
+32 -2
View File
@@ -60,17 +60,47 @@ CI run URL: not yet available from this environment; record the first pushed
run here before treating H0 as CI-verified. The local gate is reproducible with
`CARGO_HOME=.cache/cargo CARGO_TARGET_DIR=.cache/target`.
S0 fix commit: `74e34c6` (`fix(ci): remove empty-directory dependency from prose
property test (B-01)`).
### S1/H1-A record (current)
Implemented the lock v3 package-instance graph and fail-closed reproducibility
contract from ADR-0016:
* `marqdo lock` traverses the full dependency closure, records root and
per-instance `(alias → instance)` edges, the root manifest digest, full
content digests and structured path/Git sources, then writes atomically.
* `run`/`call`/`check`/`inspect` require a lock whenever dependencies are
declared, never fetch or rewrite it, and validate every `(parent, alias)`
edge. Missing edges/records, digest or source drift, root-manifest drift and
v1/v2 locks fail closed (exit 1).
* `sync` is strict in both modes and never rewrites the lock; it materializes
the entire locked closure into `.marqdo/env` with `env.json` schema 2 and
atomic publication.
* Git cache entries carry a marker and are reverified by URL, revision,
profile and content digest; revisions must be full lowercase commit hashes.
* `content_profile_version: 1` unifies hashing and materialization (B-05).
* `add`/`remove` no longer patch the lock; a stale graph is rejected with a
relock instruction.
Tests added: package file-set selection/encoding/budgets, transitive closure,
missing-edge fail-closed, root-manifest invalidation, strict sync without
`--locked`, full-closure env materialization, missing-lock and deleted-edge CLI
failures.
### M0.6 implementation progress
| Step | State | Evidence |
|---|---|---|
| S0/H0 CI baseline | **Done locally** | B-01 fixed in `crates/cli/tests/properties.rs`; fresh-clone path no longer needs an empty directory; full local gate green (see §S0/H0) |
| S1/H1-A lock v3 graph | **Done** | ADR-0016; full-closure `marqdo.lock` v3; fail-closed edge lookup; strict non-rewriting `sync`; verified Git cache; unified file-set profile (see §S1/H1-A) |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
| R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction |
| R5 environment/isolation | **Partial** | Pinned Git fetch/cache, transitive `@alias` resolution, atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) |
| R5 environment/isolation | **Partial** | Pinned Git fetch with verified cache markers, transitive `@alias` resolution, full-closure atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) |
| R6 release/consumers | **Done for Linux** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas; CI Linux gate + Windows/macOS `cargo check`; R6 example tests |
Reproduce the evidence:
+6 -1
View File
@@ -1,2 +1,7 @@
lock_version: 1
lock_version: 3
content_profile_version: 1
root:
package: root:multi-module@0.1.0
manifest_digest: 3d11906f34641802949b75de4728ea66a3557671db5c1ca89d6359d58a7a6936
packages: []
root_dependencies: {}
@@ -0,0 +1,27 @@
lock_version: 3
content_profile_version: 1
root:
package: root:multi-version@0.1.0
manifest_digest: 959bfcdd1f8174365e43a2690d80bb61ea2b7c9ca5e1476abc582600551a0d40
packages:
- instance_id: dep:geometry@1.0.0#76cb510d5f6ef15845a648ddf20749bc5a87bbce04008f4666cf9ac9ea14f643
name: geometry
version: 1.0.0
source:
kind: path
path: packages/geometry-v1
content_digest: 76cb510d5f6ef15845a648ddf20749bc5a87bbce04008f4666cf9ac9ea14f643
manifest_digest: 3049840e18aefb2766c62406db0545cb9cc100d9d12b1dd9585e6ecb358c321a
dependencies: {}
- instance_id: dep:geometry@2.0.0#f364164e6b6927e85bd9e4c360de575ee7bef2b3e8bd30180cab04052ceaff29
name: geometry
version: 2.0.0
source:
kind: path
path: packages/geometry-v2
content_digest: f364164e6b6927e85bd9e4c360de575ee7bef2b3e8bd30180cab04052ceaff29
manifest_digest: b206f83f82af59995a6bda82a36627d98deb709cfac36c684ced1531f4afba2a
dependencies: {}
root_dependencies:
geometry_v1: dep:geometry@1.0.0#76cb510d5f6ef15845a648ddf20749bc5a87bbce04008f4666cf9ac9ea14f643
geometry_v2: dep:geometry@2.0.0#f364164e6b6927e85bd9e4c360de575ee7bef2b3e8bd30180cab04052ceaff29
+106 -53
View File
@@ -1,9 +1,10 @@
# Marqdo Project Package Format v2
# Marqdo Project Package Format v3
Status: **lock_version 2 as implemented by M0.6 R1.** Path sources and
package-instance identity are implemented; pinned Git sources, registries,
transitive dependency solving and environment materialization are added in R5
or later; see §8.
Status: **lock_version 3 package-instance graph as implemented by S1
(ADR-0016).** Path and pinned Git sources, transitive closure locking,
fail-closed locked resolution, strict `sync`, and content-profile-1 file-set
hashing/materialization are implemented. Registries and SemVer solving remain
out of scope; see §8.
Implementation: `crates/marqdo-package/src/lib.rs` (manifest/lock types and
validation), `crates/cli/src/commands.rs` (`init`, `add`, `remove`, `lock`,
@@ -91,32 +92,77 @@ grants (`spec/security.md` §2). `net` has no implementing host op, and
## 3. `marqdo.lock`
`lock_version: 2`, packages sorted by name:
`lock_version: 3` records the complete package-instance closure reachable from
the root manifest. Packages are sorted by `instance_id`:
```yaml
lock_version: 2
lock_version: 3
content_profile_version: 1
root:
package: root:quantum@0.1.0
manifest_digest: 4f5c...
packages:
- name: geo
instance_id: dep:geo@0.1.0#101a6f6db4cc
source: path:./packages/geo
sha256: 101a6f6db4cc48d8c138b4716028da9bc8934b5f02b2235e020fbcabba15b757
- instance_id: dep:math@1.0.0#9e2...
name: math
version: 1.0.0
source:
kind: path
path: deps/math
content_digest: 9e2...
manifest_digest: 7a1...
dependencies:
helper: dep:helper@2.0.0#1b3...
- instance_id: dep:helper@2.0.0#1b3...
name: helper
version: 2.0.0
source:
kind: git
url: https://example.invalid/helper.git
rev: 0123456789abcdef0123456789abcdef01234567
content_digest: 1b3...
manifest_digest: 3c9...
dependencies: {}
root_dependencies:
math: dep:math@1.0.0#9e2...
```
| Field | Semantics |
|---|---|
| `lock_version` | writers emit `2`; readers accept `1` and `2` and migrate v1 entries by deriving an instance id |
| `packages[].name` | dependency name from the manifest |
| `packages[].instance_id` | logical `dep:<name>@<version>#<digest-prefix>` identity (ADR-0008) |
| `packages[].source` | `path:<manifest path as written>`; a Git source is `git:<url>@<rev>` |
| `packages[].sha256` | optional; lowercase hex SHA-256 of the dependency tree |
| `lock_version` | writers emit `3`; readers accept only `3` and tell v1/v2 users to run `marqdo lock` |
| `content_profile_version` | file-set/digest profile; only `1` is accepted |
| `root.package` | logical root instance `root:<name>@<version>` |
| `root.manifest_digest` | lowercase hex SHA-256 of the canonical `marqdo.yaml` |
| `packages[].instance_id` | `dep:<name>@<version>#<full content digest>` |
| `packages[].source` | `{kind: path, path}` (project-relative) or `{kind: git, url, rev}` (full commit hash) |
| `packages[].content_digest` | 64-character lowercase hex SHA-256 of the package file set |
| `packages[].manifest_digest` | optional lowercase hex digest of the dependency's own manifest |
| `packages[].dependencies` | this instance's alias → target instance edges |
| `root_dependencies` | root manifest alias → target instance edges |
### 3.1 Deterministic serialization
The graph is the unit of reproducibility: a transitive dependency that can be
imported is also locked. Edges are keyed by `(parent instance, alias)`, so the
same alias in two packages may resolve to different instances.
`LockFile::to_yaml` sorts packages by name before serializing. The format
contains no timestamps, no absolute paths and no machine-specific values, so
repeated `marqdo lock` runs over unchanged dependencies are byte-identical.
`LockFile::from_yaml` also sorts packages on load, so equality comparison is
order-insensitive.
### 3.1 Serialization and validation
`lock` writes atomically (temporary file, `sync_all`, rename); a failed
resolution leaves the previous lock untouched. `LockFile::to_yaml` sorts
packages by `instance_id`. The format contains no timestamps, absolute paths or
machine-specific values, so repeated `lock` runs over unchanged inputs are
byte-identical.
`LockFile::from_yaml` validates before returning:
* `lock_version == 3`, `content_profile_version == 1`;
* unique ids, each consistent with `dep:<name>@<version>#<content_digest>`;
* every digest is 64 lowercase hex characters;
* every source is normalized (path relative to the project root without `..`,
Git revision a full lowercase 40/64-character hash);
* every edge target exists and every package is reachable from
`root_dependencies`; empty aliases and self-edges are errors.
v1/v2 locks are rejected, not silently upgraded: a flat lock cannot represent
the closure and treating it as complete would re-open fail-open loading.
### 3.2 Tree hash
@@ -149,42 +195,49 @@ are normalized on materialization (`0644` files, `0755` directories on Unix).
1. discovers the project root from the cwd;
2. loads and validates `marqdo.yaml`;
3. for each manifest dependency, in map (sorted) order:
* a `path` source: the directory/file must exist; its tree is hashed;
* a `git` source: an exact `rev` is required. `lock` clones it into
`.marqdo/cache/git/<url-digest>-<rev>`, checks out that revision, strips
`.git`, and hashes the tree. Install hooks and submodules are not run;
* no source → error;
4. records `instance_id`, `source` and `sha256` for each package;
5. writes `marqdo.lock` (exit 0, `locked N package(s)`).
3. traverses the full dependency closure in sorted manifest order:
* a `path` source must resolve inside the project root; its module root is
hashed and recorded as a project-relative path;
* a `git` source requires a full lowercase commit hash. `lock` clones into
`.marqdo/cache/git/<url-digest>-<rev>`, checks out the revision, verifies
`git rev-parse HEAD` equals it, strips `.git`, hashes the tree, and writes
a sibling `.meta.json` marker (`url`, `rev`, profile, digest). Install
hooks and submodules are not run;
* package cycles, duplicate ids with conflicting content, depth >128 and
more than 4096 instances are errors;
4. records every package instance with its alias→instance edges, plus the root
manifest digest and root edges;
5. validates the graph and atomically writes `marqdo.lock` (exit 0,
`locked N package(s)`).
What it does **not** do: resolve SemVer ranges, download a registry, verify
package signatures, install packages or run dependency scripts. A dependency's
own `marqdo.yaml` is used for transitive `@alias` imports (R1/R5); the lock is
still a flat direct-dependency record.
publisher signatures, install packages or run dependency scripts. A dependency's
own `marqdo.yaml` supplies its dependency edges.
## 4. `sync`
`marqdo sync [--locked]` (run in a project):
1. discovers the root; loads the manifest and the existing `marqdo.lock`
(missing lock → error "run `marqdo lock` first", exit 1);
2. recomputes the expected lock file exactly as `lock` would (including Git
cache resolution and tree hashes);
3. with `--locked`, compares the expected lock with the on-disk lock; a
difference (manifest change, source change or dependency content change)
prints "lockfile is out of date or dependency contents changed; run
`marqdo lock`" and exits 1;
4. materializes the locked packages into a project-private
`.marqdo/env/<instance-id>/` tree, writes `.marqdo/env/env.json`, and
publishes it atomically (staging + rename, old env restored on failure);
5. without `--locked`, also refreshes the env; with `--locked`, the materialized
content must match the lock. `run`/`check` prefer a materialized copy only
when its tree digest matches the resolved package digest.
1. discovers the root; loads and validates the existing `marqdo.lock`
(missing or v1/v2 lock → exit 1 with a relock instruction);
2. verifies the lock belongs to the current root manifest
(`root.package` and `root.manifest_digest`); drift fails closed;
3. materializes **every** package in the locked closure into a project-private
`.marqdo/env/pkg-<sha256(instance-id)>/` tree using the profile-1 file set
and the lock's content digest;
4. writes `.marqdo/env/env.json` schema 2 with the content profile, canonical
lock digest, root edges and one record per package; publishes via staging +
rename, restoring the previous environment on failure;
5. never rewrites the lock. Plain `sync` may fetch a pinned Git revision named
by the lock; `--locked` forbids fetching. Both modes verify contents and
fail with "lockfile is out of date or dependency contents changed; run
`marqdo lock`" on drift.
`sync` never rewrites the lock file. There is no `--offline` flag yet; a
missing Git cache causes a clear "not cached; run sync/lock" error rather than
an implicit network fetch during `check`/`run`.
`run`, `call`, `check` and `inspect` never fetch and never write the lock. With
declared dependencies they require a lock. They resolve each `(parent instance,
alias)` edge in the lock; missing entries, digest/source drift and root-manifest
drift are errors. A materialized env or Git cache directory is trusted only
after its file-set digest and cache marker verify.
## 5. `init`
@@ -262,13 +315,13 @@ inconsistency to fix).
|---|---|
| Git dependency resolution (pinned rev, clone/fetch/checkout) | Implemented for exact revisions; no floating branches, submodules or dependency scripts. |
| Registry / package publishing / SemVer resolution | Not implemented. |
| Transitive dependency graph and conflict resolution | Transitive `@alias` imports resolve from the dependency's own manifest; the lock remains flat and a full conflict solver is not implemented. |
| Transitive dependency graph and conflict resolution | The lock records the full transitive closure with per-instance edges; two versions of one package can coexist. A general SemVer conflict solver is not implemented. |
| `tree`, `update`, `vendor`, `package` commands | Not implemented. |
| `--offline`, `--locked` on `lock` | Not implemented; missing cache fails instead of fetching during check/run. |
| Environment materialization (`.marqdo/env`, `cache`) | Implemented: `sync` writes `.marqdo/env` atomically and `lock` populates the Git cache. Kernels/sessions are not materialized. |
| Environment materialization (`.marqdo/env`, `cache`) | Implemented: `sync` materializes the full locked closure into `.marqdo/env` atomically; `lock`/`sync` populate a verified Git cache. Kernels/sessions are not materialized. |
| Dependency signatures / trusted publishers / supply-chain scanning | Not implemented. |
| Multiple/nested project boundary diagnostics | Not implemented; nearest `marqdo.yaml` wins. |
| Lock file migration between `lock_version`s | v1 is read and migrated; writers emit v2. |
| Lock file migration between `lock_version`s | Only v3 is read; v1/v2 are rejected with a relock instruction. `lock` regenerates the graph. |
| Plugin installation / plugin dependency management | Not implemented; `plugins:` in the manifest is declarative only. |
The lock/package format is deliberately small and deterministic so these can