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.

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#

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 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.

Canonical owner: Developer Interface.