# The lock

Every One project has exactly one checked-in lock: `one.lock`. The
[project entry point](/one/reference/project) 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:

| Partition | Records |
| --- | --- |
| Semantics | Semantic packages, owners, normalizer and compatibility revisions, explicit imports, and declared mapping and stage-contribution dependency revisions |
| Implementation languages | Only explicitly referenced implementation profiles; exactly one `SourceLanguageDefinition` per profile; parser/analyzer/formatter contracts; admitted tooling plus Providers-owned trust receipts; and exact external implementation source/package dependencies needed for analysis |
| External dependencies | Resolved ecosystem packages, checksums, signatures, provenance, features/extras, targets, and consumer/transitive edges |
| Tools | Exact external tool and toolchain selections with their revisions and qualifications |
| Projections | Exact projection-profile selections and their build inputs |
| Provider catalogs | Exact provider-catalog and admission snapshot selections |
| Per-root source closures | The exact selected source closure for each declared root |

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:

| Lock | Owner and stage | What it commits |
| --- | --- | --- |
| `one.lock` | Developer Interface dependency resolution | Exact resolved dependency packages in the typed partitions above |
| Selection lock | Planning | Exact per-root mapping and contribution activation, the implementation candidate and analysis receipt, and provider, topology, and physical choices over one S-IR and the root-reachable projections of `one.lock` |
| Build lock | Build | Exact selected logical implementation bodies and external source/package dependencies, compiler/toolchain packages, language/package dependencies, tools, actions, targets, and artifacts; each generated projection contributes its exact Contracts-owned `ProjectionLockEntry` and, after realization, its `ProjectionReceipt` |

```mermaid
flowchart LR
  S["accepted *.one source"] --> L["one.lock<br/>dependency resolution"]
  L --> P["Planning selection lock"]
  P --> B["Build lock"]
  B --> A["A-IR actions and artifacts"]
  A --> R["ProjectionReceipt"]
```

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:

```console
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:

```console
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](/one/platform/supply-chain) governance. See
[CI and release automation](/one/guides/ci-automation) and
[dependencies and toolchains](/one/reference/dependencies-toolchains).

## Planned lock syntax

> **End-product plan, not current.** The single `.one` text representation is
> planned in [`plans/documents.md`](https://github.com/muijf/one/blob/main/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
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](/one/reference/dependencies-toolchains), not a second lock. After a
project [adopts the One-native path](/one/start/adopt-project), 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](https://github.com/muijf/one/blob/main/systems/developer-interface/AGENTS.md)
- [Planning](https://github.com/muijf/one/blob/main/systems/planning/AGENTS.md)
- [Build](https://github.com/muijf/one/blob/main/systems/build/AGENTS.md)
- [Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md)

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.