Browse documentation
The shared development workflow
Create, inspect, edit, verify, test and watch applications and libraries through one development loop.
Applications and libraries should use the same everyday loop: create a project, inspect its code, make a change, check it, test it and see the result in a running application. Reusable code stays in its library; a consumer application supplies the entry points, tests and local routes.
Much of this workflow is implemented in the current development build. The walkthrough below uses the existing library commands. Work remains on consistent project setup and guidance across applications, libraries and workspaces, and on exercising and measuring the loop on larger ecosystem libraries. There is no committed completion date.
“Shared workflow” means common tools and feedback. It does not yet mean one compiler profile or automatic migration of saved state.
Create a project
With a runtime binary that records its source commit on your PATH, create a library and its example consumer in an absent or empty directory:
effectful new ./pricing --kind library --name pricing
See the library tutorial for runtime setup and the generated example. The main files are:
Path under pricing/ |
Purpose |
|---|---|
library.toml |
Identifies the library, its consumers and the runtime source version |
packages/pricing/src/lib.rs |
Reusable implementation |
consumers/example/src/lib.rs |
Application entry points that call the library |
consumers/example/tests/ |
Scripted cases checking results and effect traces |
consumers/example/serve.toml |
Local development routes |
| Root Cargo workspace | Editor support and optional native Rust tooling |
oracle/ |
Separate native tests of the same library source |
The equivalent starting command for a unit-based application is effectful new ./my-app. Today, these commands create different project formats; their supported Rust constructs and runtime integrations still differ.
Inspect before editing
A person can read the source in an editor. An AI agent can also query checked definitions and their relationships:
effectful code find ./pricing/consumers/example \
--query scale --format json
The returned definition ID and snapshot can be used with code context, code show and code dependents to inspect the body, its context and checked callers. See code and evidence for the complete commands.
These queries take the consumer crate directory, not the library-project root. The consumer determines which application and dependencies are being inspected. The source snapshot makes it possible to detect a changed revision between queries.
A list of callers helps identify the impact of an edit. It does not establish that those callers have passed tests.
Edit, verify and test
Change a function in packages/pricing/src/lib.rs, then run:
effectful verify ./pricing
effectful test ./pricing
verify checks the declared consumers, builds their managed representation, archives the captured inputs and verifies reconstruction. It runs no test cases. test executes the declared cases through the managed runtime. Valid source can therefore pass verification while producing a failing test result.
These commands do not invoke Cargo, rustc or dependency downloads for each supported edit. Septa still parses, checks and lowers code internally; “zero build” refers to avoiding a native application build in that loop.
The test command checks the consumers declared in library.toml. To investigate one case:
effectful test ./pricing --consumer example --case scaled
That result covers the selected case. Run the complete declared suite to check the rest of the project.
Reuse relevant test results
Keep a feedback cache outside the project:
feedback_dir=$(mktemp -d)
effectful test ./pricing --cache "$feedback_dir" --explain-reuse
Reuse the same cache directory on subsequent invocations. Eligible unchanged cases can reuse their previous results; changed or ineligible cases execute again. The output explains reuse separately from fresh execution.
This caches test outcomes, not all compilation work. Source is checked and verification still occurs. A reused failure remains a failure. See code identity and test reuse.
Keep a consumer running while you edit
Start the example consumer with a separate state directory:
watch_work=$(mktemp -d)
effectful serve --app ./pricing --consumer example \
--state "$watch_work/state" --watch
The command prints a local listener address. Use the requests in the watch guide to see the current result.
For each candidate edit, the runtime checks the captured source and its tests before activation. A failed test or incompatible route change leaves the previous accepted version serving. An accepted change is selected for new executions; retained executions keep the code that started them.
This lets an agent edit a library while a person exercises its consumer. The watch result states whether the edit was accepted or refused.
The current listener is local development tooling. Its entry-based activation does not automatically migrate graph actors or arbitrary saved state. A library still owns no listener or deployment of its own; the consumer supplies those boundaries.
Review evidence for the change
Record fresh results for a consumer with a new receipt filename:
evidence_dir=$(mktemp -d)
effectful graph test ./pricing/consumers/example \
--no-cache --evidence "$evidence_dir/run-001.json" --format json
After another edit, check whether that receipt still applies:
effectful code evidence ./pricing/consumers/example \
--receipt "$evidence_dir/run-001.json" --format json
The second command checks applicability without rerunning tests. A relevant edit can make the result stale. Read both the outcome and applicability: an applicable failed result is still a failure.
Evidence creation currently uses the consumer-level graph test command. The shared project-level test command does not yet expose every consumer-level option. These tests use scripted inputs and effect answers; they do not validate a live provider or deployment. See test evidence.
For an AI-authored change, the review can include the changed source, checked dependencies and effects, the tests that ran, results reused from earlier executions, and any compatibility work still required.
Keep native checks and deployment explicit
The generated oracle/ project tests the same library as ordinary Rust. After installing the toolchain described in the generated README, its separate check is:
cd pricing/oracle
cargo test
This uses Cargo and has its own build. Native adapters and runtime changes also need their own checks. A passing managed test suite does not establish native behavior, live-service behavior or deployment readiness.
What is still being unified?
The implemented steps already let a library use the same main verbs as an application: new, verify, test and serve --watch. The remaining work should make the starting point and guidance consistent too:
- Choose what to create: an application, a reusable library with an executable consumer, or a workspace containing both. The exact workspace command and layout still need to be settled.
- Find the code immediately: generated projects should identify the implementation, application entry points, tests and host adapters, with a short source map and exact first commands.
- Give agents the same instructions: project guidance should record the runtime/profile version and explain the supported edit and test loop. Native checks remain a separate step.
- Use the installed runtime in development and CI: ordinary checks should not require rebuilding the runtime repository. Creation should work offline and refuse to overwrite an existing project.
- Exercise the workflow on larger libraries: the graph database adoption work includes its own expected test results, separate native checks and measured edit-to-result times.
The intended experience is that extracting code into a library, or adding another consumer, keeps the same development loop. Some pieces above already exist in the library scaffold; the remaining work is to make them consistent across the supported project types and demonstrate them on real projects.
Some details remain specific to the project format: code-query targets, evidence commands, available source constructs and supported effect adapters. A shared command does not remove those limits.
There is no adopted plan for a single crate-based authoring model, complete language-feature parity or automatic conversion of existing projects. Use the current format comparison when selecting a project today.