# Project and workspace

Every One application begins at one canonical scope entry point: `one.one`.
That file selects authored sources and the exact lock; it is not itself an
application semantic source.

## The project entry point

`one.one` is a bounded `.one` source unit containing exactly one semantic item
using the built-in `one.project@1` domain. It contains exactly one `project` or
`workspace` declaration and no implementation item.

A project declaration lowers to the owner-qualified `one.project/v1` value. It
selects:

- the project identity;
- every explicit application `.one` source;
- root-wide external dependency and toolchain constraints; and
- the exact `one.lock`.

Those selected application sources and their explicit semantic dependencies
supply the contracts, system declarations, roots, implementation claims, and
root-scoped selections. The entry point establishes scope without becoming
application meaning.

The entry point cannot select itself in `sources`. Adapter configuration,
provider inputs, language package manifests, and build-system files cannot
substitute for this scope.

## The exact lock

`one.lock` resolves mutable selections to exact owner-qualified package,
semantic, implementation, mapping, language-tool, and catalog revisions needed
by the selected roots. A lock is reviewed input to checking and planning. It is
not a provider choice, Build report, deployment plan, or grant.

Package operations propose source and lock changes as one transaction. Merely
installing a package or adding a workspace member does not activate it.

`one sync` resolves semantic packages, Cargo/npm/PyPI or peer dependency
demands, tools, provenance, and qualifications into that one atomic lock.
`one update` proposes a newer solution against an exact catalog observation.
Checks, tests, builds, editors, and language servers never mutate it
implicitly. See [dependencies and toolchains](/one/reference/dependencies-toolchains).

## Workspaces aggregate without merging

A workspace declaration lists existing project roots. It supports selection,
batch checking, testing, and authority-free planning while every project keeps
its own sources, lock, semantic graph, root closure, Build evidence, authority,
and operational history.

Commands run at a project path select that project with workspace context.
Commands at a workspace root either operate on the declared batch or require an
exact `project/root` selection. Exact authority-bearing work remains per-root.

Affected-root optimization compares owner-derived closures and prior accepted
reports. Git status, timestamps, changed paths, or package membership cannot
prove that a root is unaffected.

## Execution configuration is machine-local

Machine, credential, local provider, model, tool, and protected-store bindings
remain in their owned execution configuration. Provider-specific configuration
remains provider-owned. These values can enter plans and evidence by exact
revision without becoming portable project meaning.

Secrets remain symbolic requirements and references. Secret values never enter
`one.one`, `one.lock`, generated source, artifacts, or plans.

## Put configuration at its owner

| Configuration | Canonical location |
| --- | --- |
| Portable application meaning and policy | Explicitly selected application `.one` source |
| Root-wide dependency and toolchain constraints | The `one.project@1` declaration in `one.one` |
| Reviewed provider-selection intent | Planning-owned explicitly selected `.one` source |
| Provider-owned portable settings | The selected provider domain's `.one` source |
| Machine paths, ports, processes, local tools, and protected bindings | `.one/execution.toml` or owner-qualified local state |
| Secret bytes | The selected secret provider only |
| Shell presentation and interaction preferences | Explicit machine-local One Shell preferences |

A source item may reference another owner's exact configuration contract but
does not absorb its meaning. Configuration is typed: unknown, duplicate,
misplaced, or inapplicable fields fail before execution. Environment variables
and command fragments are not a fallback untyped configuration channel.

## Discovery is deterministic

The Developer Interface finds the nearest valid declared project or containing
workspace under bounded path rules. A path within a workspace but outside every
listed project is rejected. Symlinks, environment variables, hidden manifests,
or repository heuristics cannot silently change scope.

## Example

Illustrative canonical scope contains one project declaration and no
implementation item:

```one
one 1

semantic parcelhub.one
    domain one.project@1
    project ParcelHub@1
        source ./one/parcelhub.one
        lock ./one.lock
```

Follow [Manage workspaces, packages, and source transactions](/one/examples/workspace-source-transactions).

Canonical owner:
[Developer Interface](https://github.com/muijf/one/blob/main/systems/developer-interface/AGENTS.md).