Environment lock · Basecamp

What basecamp.lock owns

Native project files remain authoritative for their ecosystem. Basecamp does not copy or reinterpret their package graph. It records input digests and locks the wider environment: runtime, platform, tools, native inputs, sources, and materialization rules.

Cargo.toml
Cargo.lock
rust-toolchain.toml
.cargo/config.toml
        ↓
Basecamp resolver
        ↓
basecamp.lock
        ↓
runtime + packages + tools + native inputs

Cargo.lock stays in the project

Cargo.lock is generated and maintained by Cargo. If it does not exist, Basecamp materializes the requested Rust toolchain and invokes that toolchain's cargo generate-lockfile. The file is written to the project root.

basecamp.lock stores only the SHA-256 digest of Cargo.lock. If Cargo.lock later changes,basecamp sync stops and asks for basecamp update.

What the lock contains

{
  "schema": 1,
  "environment_id": "sha256 identity",
  "stack": "rust",
  "host": "aarch64-apple-darwin",
  "target": "aarch64-apple-darwin",
  "runtime": {
    "name": "rust",
    "version": "1.98.1"
  },
  "inputs": [
    {
      "kind": "cargo-lock",
      "path": "Cargo.lock",
      "digest": "sha256:..."
    }
  ],
  "layers": [
    {
      "kind": "toolchain",
      "name": "rust",
      "source": {
        "type": "url",
        "url": "https://static.rust-lang.org/...",
        "sha256": "sha256:..."
      }
    },
    {
      "kind": "packages",
      "name": "cargo",
      "source": {
        "type": "registry",
        "ecosystem": "cargo",
        "lock_digest": "sha256:..."
      }
    }
  ]
}

Platform scope in 0.5

The current Rust lock is host-specific: host and target must match the machine running basecamp sync. Basecamp detects mismatches in sync/status/doctor instead of attempting to execute a foreign toolchain or silently omitting target std layers.

Lock lifecycle

Command	Lock behavior
`basecamp init`	Create the first lock when the project has not been initialized.
`basecamp sync`	Strictly reproduce the existing lock. Never rewrite it.
`basecamp update`	Re-detect the project and write a new lock, then synchronize it.
`basecamp bundle pack`	Export the lock plus the already materialized layers.

Commit it

Commit basecamp.lock alongside native ecosystem lockfiles. Ignore.basecamp/, which is machine-local activation state.