The lock#

Every One project has exactly one checked-in lock: one.lock. The project entry point selects it explicitly (lock ./one.lock), and nothing else is lock authority. There is no .one/lock, no .one/locks, and no directory of lock fragments. A partition materialized under .one/ is a disposable local view, never the reviewed lock.

.one/ holds machine-local working state. Portable meaning lives in the explicitly selected *.one sources, and one.lock is portable reviewed input that travels with them. A machine can regenerate every .one/ partition from the selected source and the accepted lock; it cannot regenerate the lock from local state.

One atomic root#

one.lock resolves mutable selections into exact owner-qualified package, semantic, implementation, mapping, language-tool, and catalog revisions as one atomic root. Resolving or accepting any one partition rewrites the whole lock consistently. The exact partitions are:

Visibility in a partition is inert. A recorded package does not activate an implementation, select a runtime provider, include a compiler toolchain, or grant authority.

What the lock does not do#

The lock does not:

• activate an implementation item or make it Build-reachable;
• select a runtime provider or physical topology;
• issue a capability, approval, grant, or runtime token; or
• contain runtime secret material.

Application source bytes and implementation-body digests live in source, analysis, selection, and Build receipts, not in the lock. Secrets remain symbolic requirements and references; secret values never enter one.one, one.lock, generated source, artifacts, or plans.

Three distinct locks#

Three content-addressed records are commonly called "the lock". They own different stages and are never substitutes for one another:

The dependency lock is reviewed input to checking and planning. It is not a provider choice, a Build report, a deployment plan, or a grant.

Lock lifecycle#

Proposals and acceptance are separate:

one sync --output one.lock.proposed
one check

one sync --output writes the complete exact lock proposal to a separate file. one check continues to use the accepted one.lock. one update proposes newer compatible selections against an exact registry observation. Checks, builds, tests, editors, and language servers never mutate the accepted lock as a side effect. A typo offers reviewable candidates and never downloads a similarly named package silently.

Checking a project whose required lock entry is absent returns the exact missing dependency and may emit a reviewable lock proposal without writing it. Deliberate re-resolution also uses this path; it never edits the lock in place.

To accept a reviewed whole-graph dependency update, provide the complete proposed project entry source, proposed lock, and owner-produced dependency comparison together:

one sync \
  --proposed-source one.one.proposed \
  --proposed-lock one.lock.proposed \
  --dependency-comparison dependency-comparison.json

All three files must describe the same exact reviewed update. The transaction validates the proposed pair and exact dependency comparison, then commits source and lock atomically. Automation should treat the output of one sync and one update as proposals and commit them only through this path. The resulting exact selections remain subject to end-to-end supply-chain governance. See CI and release automation and dependencies and toolchains.

Planned lock syntax#

End-product plan, not current. The single .one text representation is planned in plans/documents.md. That plan makes the lock a standard one.lock@1 selection-posture .one domain with references by nominal identity, reusing the same lexer, parser, Rowan tree, diagnostics, formatter, and comment handling as authored source. This is not the current lock wire.

one 1

semantic one.lock
    domain one.lock@1
    # End-product plan (plans/documents.md). Not the current lock wire.

Until that planned form lands, the accepted lock remains the current locked encoding and is consumed only through Developer Interface lock resolution and its exact proposal and acceptance commands.

Foreign ecosystem files#

Foreign ecosystem files keep their own names and formats. Generated or adopted Cargo.toml, Cargo.lock, package.json, and pyproject.toml files are disposable tool inputs described by dependencies and toolchains, not a second lock. After a project adopts the One-native path, source and one.lock become the only mutable dependency control plane, and the imported manifest does not remain a parallel authority.

Normative owner & evidence#

Developer Interface owns one.one, one.lock, lock resolution, and the proposal/acceptance commands. The three-lock separation is owned by Developer Interface, Planning, and Build as described in their contracts.

• Developer Interface
• Planning
• Build
• Contracts

Executable evidence for the current lock wire is the owning package tests under systems/developer-interface/tooling/one-project and the Developer Interface CLI lock and package tests. The planned .one lock syntax has no current implementation evidence; it is an end-product plan only.