Posted on by RESERVE

RESERVE v1.2.0: Introducing Workflows

One of the recurring goals in RESERVE development has been making sophisticated economic analysis easier to create, understand, and repeat.

As the project has grown, users have increasingly combined data retrieval, transformation, analysis, and visualization commands into pipelines. These pipelines are one of the CLI’s greatest strengths, but they also introduce a practical challenge: a useful analysis often needs to be reconstructed each time it is performed. For agentic users of RESERVE, that translates to avoidable token consumption.

RESERVE 1.2.0 introduces a foundation for solving that problem.

The release adds workflows, a content-first system for creating, documenting, validating, and sharing reusable economic analyses.

A workflow can describe the purpose of an analysis, the economic concepts it covers, the inputs it requires, and the RESERVE pipeline used to perform it. Static workflows can represent fixed analyses with no runtime inputs, while dynamic workflows can accept ordered values such as a start date, end date, country, series, or comparison period.

Version 1.2.0 does not attempt to solve every part of workflow distribution and execution. Instead, it establishes the document format, command model, filesystem layout, validation rules, and safety boundaries upon which the broader workflow ecosystem can be built.

Introducing the Workflow Command

The new workflow command family provides the tools needed to author and inspect reusable analyses:

reserve workflow create
reserve workflow validate
reserve workflow list
reserve workflow show
reserve workflow edit
reserve workflow remove
reserve workflow contract
reserve workflow render

The command model follows RESERVE’s noun-verb convention. Workflow is the object being managed, while commands such as create, validate, and render describe the action being performed.

A new collection can be created with:

reserve workflow create personal/economic-growth

A workflow can then be added to that collection:

reserve workflow create personal/economic-growth/gdp-summary

RESERVE creates a collection-oriented directory structure:

~/.reserve/workflows/
  personal/
    economic-growth/
      collection.yaml
      README.md
      workflows/
        gdp-summary.yaml

The collection README is a normal repository artifact. It can explain the purpose of the collection, document its workflows, and travel with the collection when it is distributed through Git or another repository service. RESERVE scaffolds the initial README but never overwrites existing documentation.

Static and Dynamic Workflows

Not every analysis requires user input.

A static workflow can define a fixed pipeline that is rendered the same way every time. This is useful for established dashboards, recurring reports, classroom demonstrations, or analyses tied to a specific series and period.

Dynamic workflows add an ordered runtime contract.

For example, a GDP summary workflow might declare two inputs:

contract:
  - label: start date
    format: YYYY-MM-DD
    sample: 2020-01-01
    description: First date in the analysis period.

  - label: end date
    format: YYYY-MM-DD
    sample: 2024-12-31
    description: Final date in the analysis period.

The workflow pipeline refers to these inputs positionally:

pipeline:
  - reserve obs get GDP --start @1 --end @2 --format jsonl
  - reserve analyze summary

The first supplied value replaces @1, the second replaces @2, and the pattern can continue through @X.

Users and AI agents can inspect the required inputs before rendering the workflow:

reserve workflow contract gdp-summary

RESERVE displays the label, expected format, sample value, and description for each input:

personal/economic-growth/gdp-summary contract:
  @1 = start date
    format: YYYY-MM-DD
    sample: 2020-01-01
    description: First date in the analysis period.
  @2 = end date
    format: YYYY-MM-DD
    sample: 2024-12-31
    description: Final date in the analysis period.

Zero-input workflows are supported as a first-class use case. A workflow only needs a contract when its pipeline contains runtime slots.

Safe Rendering Instead of Execution

An important design decision in RESERVE 1.2.0 is that workflows do not execute pipeline content.

A workflow is rendered with:

reserve workflow render gdp-summary 2020-01-01 2024-12-31

RESERVE validates the workflow, binds the supplied values, and prints one copy-ready command:

reserve obs get GDP --start '2020-01-01' --end '2024-12-31' --format jsonl | reserve analyze summary

It does not invoke Bash, start another shell, or execute the rendered pipeline.

This boundary is intentional.

Shell execution introduces significant security and cross-platform questions, especially when workflow definitions may eventually come from public, educational, community, or private repositories. Version 1.2.0 keeps the operator or calling agent in control. The rendered command can be reviewed, copied, modified, audited, or executed through an environment chosen by the user.

A future release may introduce explicit rendering targets or controlled execution semantics. Those capabilities may only be added after their portability, trust, and security models are clearly defined.

Validation as a First-Class Feature

Because workflows are intended to become portable artifacts, validation must be more rigorous than simply checking whether a YAML file can be opened.

The new validator checks workflow structure, runtime contracts, pipeline placeholders, and collection-aware references:

reserve workflow validate personal/economic-growth/gdp-summary

Version 1.2.0 also adds several production safeguards:

  • Unknown YAML fields are rejected instead of being silently ignored.
  • Multiple YAML documents in one workflow file are rejected.
  • Runtime slots must match the declared contract.
  • Repository-style paths cannot traverse outside the configured workflow root.
  • Symlinks cannot be used to escape the workflow namespace.
  • A workflow’s reserve_version requirement is checked against the running CLI.
  • Rendering fails when required runtime values are missing or incompatible.

These rules help authors catch mistakes before publishing a collection and give users greater confidence when inspecting workflows obtained from another source.

A Repository-Aware Foundation

Workflows are organized using a three-part name:

repository/collection/workflow

For example:

personal/economic-growth/gdp-summary

Each part has a distinct purpose.

The repository identifies the source or trust boundary. The collection groups related analyses. The workflow identifies the individual analytical method.

Version 1.2.0 begins with local filesystem storage and uses personal as the default repository for user-authored workflows. The architecture also anticipates additional repository types:

  • official for workflows maintained and distributed by the RESERVE project
  • community for collections curated by organizations or subject-matter communities
  • education for universities, schools, instructors, and home-school networks
  • private for internal organizational analysis

Remote search, installation, synchronization, signing, and trust policies are not part of this foundational release. However, establishing repository-aware names now means those capabilities can be added later without redesigning the workflow identity model.

A university could eventually distribute a collection through GitHub. A research group could maintain an internal Git repository. A home-school network could publish a shared economics curriculum. RESERVE’s local commands can remain consistent regardless of how those collections are distributed.

Moving Beyond Snippets

Earlier versions included an exploratory feature called snippet.

Snippets helped test the idea that RESERVE pipelines could be saved and reused, but they did not provide the metadata, validation, contracts, collection structure, or repository model needed for a durable ecosystem.

Version 1.2.0 removes the experimental snippet feature and replaces it with workflows.

Because snippets were introduced as a silent exploratory feature and had not been promoted for general use, this was the right point to make a clean transition. Workflows now provide the foundation on which future sharing and distribution capabilities will be built.

Built with Go 1.27

RESERVE 1.2.0 also moves source builds to Go 1.27.

For a data-oriented CLI, the move to Go 1.27 is especially relevant. The release introduces the new encoding/json/v2 implementation, with the established encoding/json API now backed by the newer engine while preserving compatibility. The Go team reports significantly faster JSON unmarshalling, an important improvement for software that regularly processes API responses and JSONL observation streams.

Because RESERVE relies heavily on JSON responses from the FRED® API, we ran our own benchmarks against representative observation data. The results were striking.

Simply compiling RESERVE with the Go 1.27 toolchain produced approximately three times the JSON unmarshalling throughput and reduced unmarshalling time by about 68 percent.

Go 1.27 JSON improvements

Go 1.27 also introduces size-specialized allocation routines that can reduce the cost of small allocations. In our benchmarks, allocations fell by approximately 80 percent when processing large FRED observation payloads.

These are workload-specific benchmark results rather than a claim that every RESERVE command will run three times faster. They do, however, demonstrate a meaningful improvement in one of the CLI’s most important data-processing paths.

Go 1.27 also strengthens the development toolchain by checking for accidental use of standard-library features newer than the version declared by a module.

Together, these improvements provide a faster and stronger runtime foundation without changing how users interact with RESERVE. Prebuilt binaries remain self-contained, so users installing a RESERVE release do not need to install or upgrade Go separately. Go 1.27 or later is required only when building RESERVE from source, and no workflow or command compatibility changes are required.

More details are available in the official Go 1.27 release notes.

A Foundation for What Comes Next

RESERVE 1.2.0 is intentionally a foundational release.

It establishes:

  • A stable workflow YAML format
  • Static and dynamic workflow contracts
  • Repository and collection namespaces
  • Strict validation and version compatibility
  • Safe, non-executing pipeline rendering
  • Collection-level documentation
  • Local creation, discovery, inspection, editing, and removal
  • A clear path toward future workflow distribution

The next phase will be shaped by real workflow authors and real collections.

That means building analyses, documenting them, testing the contract model, determining which metadata proves useful, and learning how individuals, educators, researchers, and organizations want to distribute their work.

RESERVE began as a tool for retrieving economic data from the command line. It has steadily evolved into a composable environment for transforming, analyzing, and visualizing that data.

With version 1.2.0, those commands can now become durable analytical methods.

Create the workflow once. Validate it. Document it. Render it whenever the question returns.