Skip to content

V0.md

Latest commit

 

History

History
237 lines (160 loc) · 6.01 KB

V0.md

File metadata and controls

237 lines (160 loc) · 6.01 KB

V0 Scope

Purpose

This document defines the first buildable slice of the Axiom family.

The goal of v0 is not to complete the whole architecture. The goal is to build the cornerstone well enough that the rest of the system can stand on it.

That cornerstone is SDA.

V0 Goal

V0 is:

  • a serious SDA library
  • a serious sda CLI
  • a testable implementation of the current SDA specification

The point of v0 is to make SDA immediately useful on its own and make it strong enough to serve as the workhorse for everything that comes later.

That means users should be able to:

  1. ingest JSON
  2. transform it with SDA
  3. validate shapes and assumptions
  4. normalize ambiguous structures
  5. emit useful structured output

In practical terms, sda should be useful as a shell tool in the same problem space as jq, but with stronger semantics around absence, duplicates, carriers, and failures.

Why SDA Is V0

SDA is the right v0 for four reasons:

  1. it is the best-specified part of the project
  2. it is the semantic cornerstone of everything else
  3. it is useful even if the rest of the system does not exist yet
  4. every later tool depends on it as the transformation engine

Axiom, Enrichment, and Shaping are important, but they are downstream of SDA.

What Ships In V0

V0 should include only the minimum pieces needed to make SDA a real product.

1. Full SDA library

Required:

  • parser
  • AST
  • evaluator
  • JSON input/output bridge
  • stable failures
  • conformance-oriented tests

The library is the core asset. The CLI is one delivery surface over it.

2. sda CLI

Required:

  • sda eval
  • sda check
  • JSON in
  • JSON out
  • stdin/stdout-first behavior
  • stable exit/failure behavior

The sda CLI should be useful immediately in shell, ETL, and fixture-driven test workflows.

3. Enough SDA coverage to be real

V0 should aim for the current SDA core, not a tiny demo subset.

At minimum this means strong support for:

  • Null, Bool, Num, Str
  • Seq, Set, Bag, Map, Prod, BagKV
  • selectors and eliminators
  • Opt and Res
  • let
  • function calls
  • comprehensions needed by the spec
  • normalization operations
  • stable error codes and messages

If v0 cheats too much here, the rest of the architecture will stand on sand.

4. Shell-friendly workflows

V0 should prove that sda works well as a standalone Unix-style tool.

Example use cases:

  • JSON cleanup and normalization
  • fixture transformation in tests
  • ETL extraction stages
  • contract validation
  • duplicate-aware and absence-aware data reshaping

5. Fixture-driven tests

V0 must include replayable tests and examples.

This should include:

  • simple unit-style semantic tests
  • conformance-style tests derived from the spec
  • at least one realistic JSON transformation example

What Does Not Ship In V0

V0 does not ship the rest of the architecture as full products.

Deferred tools

  • axiom workflow runtime
  • standalone enr CLI
  • standalone shape CLI

Those are v1+ concerns built on top of the SDA workhorse.

What Is Explicitly Deferred

These items are valuable, but they should not block v0.

Deferred language work

  • full Enrichment language grammar
  • full Shaping language grammar
  • rich Axiom workflow syntax
  • macros or metaprogramming
  • user-defined functions beyond what is necessary
  • non-essential surface extensions

Deferred runtime work

  • HTTP CRUD runtime
  • file orchestration runtime
  • retries and caching policy
  • concurrency and fan-out
  • streaming
  • binary codecs and PIC support
  • multiple serialization formats beyond JSON

Deferred tooling

  • formatter beyond what sda needs
  • package manager
  • manifest system
  • editor plugins
  • debugger UI
  • explain plans beyond what sda needs

V0 Command Surface

The intended v0 command surface is:

sda eval -f extract.sda < event.json
sda check -f extract.sda
sda fmt -f extract.sda

Optional if it helps testing:

  • sda explain
  • sda trace

V0 Product Shape

The intended v0 user experience is:

JSON input
  -> SDA program
  -> JSON output

With semantics strong enough to outperform ad hoc JSON tooling in correctness-sensitive cases.

Example Value Proposition

sda should be usable immediately for work such as:

  • extracting stable records from messy event payloads
  • distinguishing missing fields from explicit null
  • handling duplicate keys honestly with BagKV
  • normalizing data before tests or ETL
  • acting as a better-specified alternative to jq for structured-data transformation

Non-Goals For V0

V0 is not trying to prove:

  • that all four languages need full syntax immediately
  • that Axiom must replace shell scripts on day one
  • that the whole architecture must be implemented at once
  • that binary data support is ready
  • that enrichment and shaping are fully separate products yet

V0 is trying to prove one thing:

A well-specified structured-data algebra can stand on its own as a useful library and tool, and can support the rest of the architecture later.

Success Criteria

V0 is successful if all of the following are true:

  1. a user can transform real JSON data with sda from the shell
  2. the SDA library is solid enough to embed from another host
  3. failures are stable enough to write tests against
  4. the semantics match the current SDA spec closely enough for conformance-style testing
  5. users can already get value from SDA before Axiom exists

If those are true, v1 can safely decide:

  • how Axiom should orchestrate effects around SDA
  • whether enr deserves its own language
  • whether shape deserves its own language
  • how small or large the Axiom glue syntax should be

Recommended Build Order

The implementation order for v0 should be:

  1. align the SDA spec and conformance expectations
  2. implement the SDA parser, AST, and evaluator
  3. implement JSON input/output bridging
  4. implement sda eval and sda check
  5. add fixture-driven and conformance-style tests
  6. refine the CLI for shell and ETL usability

That order keeps the project grounded in the strongest and most reusable part of the system.