Adopt an existing project#

One can start a new system or place an existing application under the same canonical lifecycle. Adoption is a reviewed conversion, not a permanent bridge between two mutable control planes.

Establish the project boundary#

Run one init from the directory that will own the project. It creates or adopts the bounded one.one entry point, explicit application sources, and initial exact one.lock:

cd existing-application
one init . --dry-run --offline --proposal-lock-output proposed.one.lock
one init . --offline
one check --offline

Review proposed.one.lock before the second command. The dry run is the review boundary. It reports every acquired package, language profile, toolchain, provider claim, source closure, trust record, and unresolved choice before the lock is accepted. one check remains read-only and never repairs or advances the lock implicitly.

Reviewing the proposed lock#

The dry run writes a complete candidate lock; it does not install it. Review the proposal as one atomic decision rather than a diff to hand-merge, and treat an unexplained entry as a blocker:

• every acquired semantic package, its owner normalizer, and exact content revision;
• the separate implementation-language partition of source-language packages, profiles, frontend contracts, and exact parser, analyzer, and formatter artifacts;
• every pinned toolchain revision;
• each provider claim, admission receipt, and trust record;
• every selected root, source path, and dependency edge; and
• every unresolved or ambiguous choice, with the source range that produced it.

one check --offline remains read-only and never repairs a proposal. The second one init commits the lock only when the reviewed proposal is still current. The resolved shape, partitions, and drift behavior are owned by the lock reference; the exact edges are explained by dependencies and toolchains and project and workspace.

Import ecosystem inputs once#

An existing Cargo.toml, package.json, pyproject.toml, deployment manifest, or provider resource can be acquired as an exact adoption input. One retains its original bytes, source, parser or adapter revision, identity candidates, ambiguities, and loss report. You review the mapping before it establishes any One-owned meaning.

After acceptance, portable dependencies and toolchains live in the selected .one sources and exact one.lock. Resolver adapters may construct private, receipted Cargo, npm, PyPI, or peer workspaces for upstream tools, but the old manifest does not remain a second mutable project-control path.

Application source code does not need to be rewritten into .one. Keep Rust, TypeScript, Python, and other bodies in their own language when that is the selected implementation profile; the .one implementation item associates the exact source artifact with the contract it claims to realize.

What adoption rewrites and what it leaves alone#

Adoption changes the portable project control plane; it does not confiscate the project. Name each item explicitly before accepting the conversion.

Adoption rewrites:

• the selected .one semantic sources and the exact one.lock;
• portable dependency and toolchain declarations that upstream tools consume through receipted private workspaces;
• root, component, and provider-selection intent that Planning consumes; and
• machine-local bindings, which move to the machine-local execution selection beneath .one/.

Adoption leaves alone:

• implementation bodies, which stay Rust, TypeScript, Python, or another selected profile unless you deliberately port one;
• provider configuration, which remains with the provider that owns it;
• existing data, retention, and running infrastructure until a reviewed transition moves them; and
• application-owned behavior such as validation, presentation, and domain policy.

After acceptance the old manifest does not remain a second mutable project-control path.

Adoption variants#

Adoption is one lifecycle over several common starting shapes. Each variant ends at the same explicit sources, lock, and cutover conditions.

Cargo, npm, and PyPI monorepos#

Adopt the repository that owns the workspace boundary, not each member as a separate project. Portable dependencies and toolchains lower into .one sources and one.lock; resolver adapters may materialize private, receipted Cargo, npm, or PyPI workspaces for upstream tools. Member packages keep their own build identity, but the old workspace manifest stops acting as a mutable control plane. Review every edge with dependencies and toolchains.

Existing CI and release tooling#

Do not delete pipelines during adoption. First reproduce the required behavior through the ordinary check -> test -> invoke -> plan -> build -> apply -> inspect path, then replace hand-maintained workflow YAML with a receipted typed projection. The projection invokes the same fixed commands and carries no hidden authority; see CI and release automation.

Existing provider and deployment manifests#

Treat Compose files, Kubernetes manifests, Helm values, Terraform state, and similar inputs as adoption inputs, not as desired state. One retains their bytes, parser or adapter revision, candidate identities, ambiguities, and loss report for review. After acceptance the selected providers own their configuration and One owns the typed requirement and plan; a subsequent change plans the migration rather than editing the old manifest in place.

Existing data and running infrastructure#

Data and live infrastructure are adopted by observation, not by declaration. Adoption records exact external identity, ownership posture, observed shape and baseline, credential or workload authority, retention and deletion obligations, and recovery evidence. Resemblance in name is not adoption, and adoption grants no mutation authority.

Adopt running infrastructure deliberately#

Discovering a similarly named database, queue, cluster, or deployment is not adoption. A reviewed infrastructure adoption verifies:

• exact external identity and ownership posture;
• observed shape and the baseline from which drift will be measured;
• credentials or workload authority without treating them as project source;
• current data, retention, transfer, and deletion obligations;
• recovery evidence and the effect boundary; and
• the explicit policy for later drift.

Adoption records current fact; it does not itself issue mutation authority. The first change still follows check -> test -> invoke -> plan -> build -> apply -> inspect with an immutable plan and ordinary grants.

Cut over without a hidden compatibility lane#

Before calling the adoption complete, make the selected .one source and one.lock the only portable project control plane, move machine-local bindings into the machine-local execution selection beneath .one/, leave provider configuration with its provider, and remove obsolete generated or handwritten configuration only after the exact new lifecycle reproduces the required behavior.

Cutover conditions#

Adoption is complete only when all of the following hold:

• the reviewed .one sources and one.lock reproduce the required behavior through the ordinary lifecycle;
• the selected .one files and exact one.lock are the only portable project control plane;
• machine-local bindings live in the machine-local execution selection beneath .one/ and provider configuration stays with its provider;
• the old manifests, generated files, and handwritten configuration are removed once their portable content has moved, with no compatibility reader or parallel old/new lane retained; and
• a real change has been planned and applied from the adopted state, with its evidence still resolvable by opaque reference.

Executable evidence#

Developer Interface owns the current adoption path. one-project commits an initial lock atomically and verifies an identical retry; one-cli proves initialization fails closed without an installed standard distribution:

cargo test -p one-project --lib initial_adoption_commits_lock_and_verifies_identical_retry
cargo test -p one-cli --lib init_without_an_installed_distribution_is_atomic

These checks exercise lock adoption and initialization atomicity, not the illustrative infrastructure-adoption narrative above.

Next: understand source and meaning, then author the product.