Author: RESERVE

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

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

reserve workflow create personal/economic-growth

A workflow can then be added to that collection:

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

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

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

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

The original design goals of RESERVE were straightforward: provide intuitive access to the FRED® API while extending that foundation with pipelines, transformations, and analysis capabilities in a single command-line environment.

As the platform has evolved, another design goal has emerged. RESERVE is no longer focused solely on executing commands; it is increasingly focused on helping users capture, repeat, and share economic data workflows.

Economic analysis is rarely a single command invocation. It is often a sequence of retrieval, transformation, filtering, summarization, and visualization steps that users repeat over time.

Version 1.1.7 introduces the first foundation for treating those workflows as reusable assets.

Introducing Snippet Libraries

The headline feature of this release is a new snippet command family:

reserve snippet set
reserve snippet list
reserve snippet get
reserve snippet run
reserve snippet delete

reserve snippet set
reserve snippet list
reserve snippet get
reserve snippet run
reserve snippet delete

Snippets provide a mechanism for storing and reusing commonly executed command sequences.

Rather than maintaining shell history entries, personal notes, or external documentation, users can begin building a catalog of repeatable RESERVE workflows directly within the platform.

Importantly, snippets are backed by a filesystem-based library model rather than a temporary or session-oriented implementation.

This establishes a foundation that can scale beyond simple local convenience.

Today’s snippets may be personal workflow shortcuts.

Tomorrow they could become shared libraries, team standards, educational examples, or domain-specific analysis recipes.

Version 1.1.7 is intentionally a soft launch of that capability.

The goal is to establish the foundation before expanding the ecosystem around it.

Reproducibility Matters

Reusable workflows are only valuable if they produce consistent results.

A significant portion of this release focuses on strengthening the reliability of RESERVE’s batch-processing infrastructure through deterministic concurrency testing.

Batch observation and series retrieval now have dedicated testing coverage for:

• Concurrency limits
• Ordering guarantees
• Warning behavior
• Fallback paths

Previous test approaches relied on timing assumptions and sleep-based coordination.

The new test framework uses deterministic synchronization mechanisms that make behavior reproducible and easier to validate.

Most users will never see these changes directly.

But they contribute to something important:

Confidence that the same workflow behaves the same way every time it runs.

Preserving Attribution Through Pipelines

Another important improvement in v1.1.7 addresses metadata fidelity.

Recent releases have emphasized citations, provenance, and source attribution as first-class concerns within RESERVE.

This release extends that philosophy into transformation workflows.

Pipeline transformation commands now preserve citation metadata from upstream JSONL inputs, ensuring source attribution remains attached to data as it moves through transformations and resampling operations.

The principle is simple.

Transforming data should not erase information about where that data came from.

As workflows become more sophisticated, preserving provenance becomes increasingly important.

Small Improvements Matter

Not every enhancement in a release needs to be architectural.

Version 1.1.7 also improves ASCII chart rendering by standardizing numeric value labels to fixed two-decimal formatting.

Values such as:

59.00

59.00

now align consistently within chart output.

This is a small visual refinement, but one that improves readability when scanning larger datasets.

Polish accumulates over time.

And often the most frequently used features benefit the most from incremental improvements.

Building Beyond Individual Commands

The broader theme of v1.1.7 is not snippets themselves.

It is the idea that economic analysis consists of workflows rather than isolated commands.

• Users retrieve data.
• Transform it.
• Compare it.
• Visualize it.
• Share the process.
• Repeat it.

The new snippet library begins creating a place where those processes can be captured, reused, and eventually shared.

That makes this release more than a quality-of-life improvement.

It represents an early step toward a larger vision for RESERVE: not just a collection of economic data commands, but a platform for building repeatable economic data workflows.