Skip to content
DocumentationThe local development loop
On this page

Page resources

Open Markdownllms.txtView source

Last updated

The local development loop

The inner loop runs one exact root locally, watches it, and reports readiness honestly, while keeping disposable developer state and local authority separate from release evidence. It is a foreground tooling session, not a hidden plan, deployment, or alias for a framework command.

one dev follows one exact Build

one dev requires an exact immutable realized Build reference and exactly one application root in the selected project. It selects the machine-local binding's provider and profile supplying one.developer.interface.development.session#Process@1, validates that claim and its exact runtime artifact, and only then invokes the versioned development- session process protocol.

No development path invokes a language compiler or constructs a projection privately. Every generated package or executable the session consumes comes from the supplied Build report and is revalidated against its current root, semantic revision, A-IR declaration, content identity, and projection receipt.

The current profiles are:

  • next_typescript_node_http — a production API entry plus a distinct product-owned development entry. The session starts the API child first, accepts readiness only through the application-owned readiness scenario at the fixed loopback endpoint, and starts Next only after that receipt exists. Next's mutable output stays under .one/cache/dev/<root>/next. The adapter enters Next's ordinary development lifecycle through a receipted configuration bridge; it does not edit next.config, invoke a package script, or infer a shell command.
  • one.rust#ServerHtmlApplication@1 — a manifestless Cargo projection compiled from the checked root, with a fixed /health readiness response and only the fixed loopback ONE_SERVER_HTML_ADDRESS binding derived from --port.

Aggregate readiness means every child is ready. An early failure prevents or terminates its sibling, and foreground cancellation performs bounded quiescence, process-tree termination, and reaping for the whole session.

Each run retains child and aggregate request, readiness, and terminal evidence beneath .one/dev/sessions/<session-id> and per-root exclusion beneath .one/dev/roots. These records explicitly carry no Build or production authority. one shell cannot nest this live session, and there is no general one exec surface.

The editor loop

Editor integration is a thin client over one lsp and the same lifecycle commands; it is never another project model or source of semantic truth. See Editors and language tooling.

  • There is one lossless parser, and every completion, hover, diagnostic, format, token, reference, and definition result is bound to the exact open source revision, nearest one.one, selected root, and exact one.lock.
  • Malformed or incomplete source remains the current authored state and is shown as such. A previous valid normalized value is never displayed as if it described newer invalid bytes.
  • Structured form, table, graph, and diagram views are disposable projections. When current source cannot be represented faithfully, the projection becomes read-only and the lossless source view remains available.
  • When a body's using profile or its tooling is unavailable, generic tooling preserves the raw body byte-for-byte and returns typed unsupported rather than guessing syntax.
  • Navigation and definition resolution work from the exact snapshot offline, following authored names into canonical owner contracts and virtual documents under .one/vfs/.

Source transactions

Every structured or semantic edit is a source transaction:

  • it proposes a bounded patch set against the exact revision of every affected source;
  • it shows both the authored-text and applicable normalized-owner change;
  • it reparses every complete affected bounded input through the one owned parser and reruns the exact owner checks the action requires;
  • it rejects stale, overlapping, or escaping bases; and
  • it commits the sources atomically and undoably only when every base revision is still current.

Concurrent views synchronize through committed source revisions. They never share a hidden mutable semantic model, rebase a stale edit, write trusted IR, or mutate a later-stage record. See Use source transactions.

Automation uses the same typed operations

Headless and automated development compose the same operations rather than a shell bypass:

Console
one agent setup
one agent check
one agent run
one agent resume
one tui
one mcp

one tui opens the native workspace; one mcp projects the typed automation service over the current MCP revision. Neither invents authority, effect, or evidence. See Agents and automation and the One TUI.

The separate human host lane

one shell is deliberately separate. Its host-program lane resolves and spawns ordinary host programs under ambient human filesystem and process authority. It is unreceipted, unavailable to agents, MCP, automation, and nested live interfaces, and produces no One semantic, Build, deployment, or History evidence. There is no general one exec. See One Shell.

The daemon is not current

The local daemon is not current: one daemon does not exist. The accelerator described in Local daemon is illustrative end-product syntax for a desired optional service, not an available command. Local correctness never depends on it.

Keep local state disposable

Everything under .one/cache, .one/build work, .one/dev, and similar reconstructible partitions is disposable developer state. Development readiness, simulation, and fixture data never become Build, release, hosted, or production evidence. Production follows the same contracts through exact planning, Build, apply, and inspection—see Plan, build, and apply and One Web for a worked standalone root.

Next: read Editors and language tooling or Agents and automation.

Normative owner & evidence

The normative owner is systems/developer-interface/AGENTS.md for one dev, the editor, shell, TUI, agent, and MCP surfaces. systems/build/AGENTS.md owns the artifacts and receipts a development session consumes. The repository composition law is in AGENTS.md.

Demonstrated today: the one dev foreground session for the next_typescript_node_http and one.rust#ServerHtmlApplication@1 profiles; the API-first then Next readiness sequence; the manifestless Cargo projection and fixed /health readiness; session evidence under .one/dev/; one lsp and the editor tooling loop; source transactions; and the one agent, one tui, one mcp, and one shell surfaces.

Illustrative or deferred: one daemon and the local-daemon interface it would expose. No development command replaces planning, Build, apply, or release evidence.