plan-ads.md

Implement DeltaWire v1 as a standalone Go CLI.

Do not stop after proposing another plan. After the mandatory grounding phase, implement the complete v1, run every required validation, and return the evidence report described at the end.

Only stop before implementation when:

• the current repository is not appropriate
• required tooling is unavailable
• a verified repository fact contradicts this specification
• a required dependency cannot be verified
• continuing would require inventing an API, format, result, or benchmark claim

Do not commit, push, tag, publish a release, or create a remote repository.

1. Product definition

Working name:

DeltaWire

Command:

deltawire

Public value statement:

Generate large, verified test and eval datasets from compact declarative plans.

DeltaWire is a repository-local deterministic data materializer.

The intended workflow is:

human or coding agent
    ↓
compact DeltaWire generation plan
    ↓
deterministic expansion
    ↓
record-schema validation
    ↓
dataset assertions
    ↓
managed JSON or NDJSON output
    ↓
reproducibility receipt and CI check

The coding agent should write the compact plan.

The coding agent should not generate the expanded dataset itself when DeltaWire can deterministically derive it.

2. ZCA implementation boundary

This shipped system requires two slices.

Slice 1 — Local value

Compile a compact, versioned generation plan into a canonical JSON or NDJSON dataset.

The v1 generation primitives are:

• static defaults
• schema-once tuple rows
• Cartesian matrices
• integer ranges
• base-record variants
• deterministic string interpolation
• JSON Pointer set and omit operations

Slice 2 — Reliability boundary

Ensure that generated data is:

• deterministic
• schema-valid
• assertion-valid
• bounded in size
• protected from path traversal
• protected from accidental overwrite
• reproducible from committed plans
• checkable in CI
• attributable to exact plan, schema, and output hashes

Do not build beyond these two slices.

3. Explicit non-goals

DeltaWire v1 is not:

• an LLM API proxy
• a prompt router
• a model gateway
• a benchmark runner
• an eval scorer
• an arbitrary scripting engine
• a random-data generator
• a fuzzing framework
• a database
• a general template language
• a JSON compression proxy
• a semantic-delta protocol for source code
• a Boatstack dependency
• an Intelligence Flow dependency
• a tokenizer implementation
• a CSV or Parquet generator
• a YAML-based tool

Do not add:

• model SDKs
• model calls
• embeddings
• judge calls
• HTTP clients
• runtime network access
• shell execution
• plugin execution
• JavaScript
• Python
• Lua
• CEL
• JSONata
• jq
• arbitrary expressions
• environment-variable interpolation
• wall-clock-generated values
• unseeded randomness
• timestamps in deterministic state
• UUID generation
• remote schema references

The initial claim is not “DeltaWire saves X% of model tokens.”

The initial verified claim is:

DeltaWire can deterministically materialize and verify a full dataset from
a smaller declarative representation.

Model-specific token savings remain an evaluation question.

4. Mandatory repository grounding

Before writing code, run and record:

pwd
git status --short
git rev-parse --show-toplevel
git rev-parse HEAD
git branch --show-current
git remote -v
go version
go env GOVERSION
find . -maxdepth 3 -type f | sort | sed -n '1,240p'

Repository rules:

1. The intended repository basename is deltawire.

2. If the current repository is an unrelated project such as Boatstack or intelligence-flow, stop. Do not place DeltaWire inside it.

3. If this is an existing DeltaWire repository with at least one commit:

   create or use branch:
   feat/deltawire-v1
   

   Prefer a dedicated worktree:

   ../deltawire-worktrees/v1
   

   Do not overwrite an existing branch or worktree.

4. If this is a new empty Git repository:

   remain in place
   use branch feat/deltawire-v1
   do not create a commit
   

5. If this directory is not a Git repository:

   confirm that the directory basename is deltawire
   git init -b feat/deltawire-v1
   do not create a commit
   

6. Record verified facts in:

   docs/00-grounding.md
   

Use the table:

Claim | Evidence | Verification command

Do not copy assumptions from this prompt into the grounding document.

5. Language and dependency rules

Use Go.

Use the installed stable Go version only.

If go version reports a development or release-candidate build, stop and report it.

Use the Go standard library for:

• CLI parsing
• JSON parsing
• canonical output
• hashing
• file operations
• embedded initialization templates
• tests

Do not use a CLI framework.

One third-party runtime dependency is permitted:

• an established JSON Schema Draft 2020-12 validator

Before choosing it:

1. Verify the actual module path.

2. Verify that the module exists.

3. Verify that the selected version exists.

4. Verify that it supports record validation against Draft 2020-12.

5. Pin an actual version in go.mod.

6. Record the dependency and license in:

   THIRD_PARTY_NOTICES.md
   

Do not invent a module version.

Do not permit the schema library to fetch remote resources.

DeltaWire v1 permits:

• one local schema document
• internal fragment references beginning with #

DeltaWire v1 rejects:

• http:// references
• https:// references
• file:// references
• absolute schema references
• relative references to another file

Use a custom loader or pre-validation to guarantee that no schema validation path performs network I/O.

Do not add any other third-party runtime module without stopping and explaining why it is essential.

6. Repository layout

Create approximately this structure:

.
├── cmd/
│   └── deltawire/
│       └── main.go
├── internal/
│   ├── cli/
│   ├── config/
│   ├── plan/
│   ├── engine/
│   ├── schema/
│   ├── store/
│   └── report/
├── assets/
│   └── init/
│       ├── config.json
│       ├── INSTRUCTIONS.md
│       └── deltawire-plan.schema.json
├── schemas/
│   └── deltawire-plan.schema.json
├── examples/
│   └── auth-eval/
│       ├── auth-case.schema.json
│       └── auth-eval.dw.json
├── docs/
│   ├── 00-grounding.md
│   ├── architecture.md
│   ├── plan-format.md
│   ├── verification.md
│   ├── plan-integration.md
│   ├── claims.md
│   └── research-next.md
├── scripts/
│   ├── validate.sh
│   ├── check-determinism.sh
│   └── check-runtime-boundary.sh
├── .github/
│   └── workflows/
│       └── ci.yml
├── README.md
├── go.mod
├── go.sum
└── THIRD_PARTY_NOTICES.md

Adjust package-file decomposition when required, but preserve these architectural boundaries:

• plan parses and validates plan documents
• engine performs pure deterministic expansion
• schema wraps record-schema validation
• store owns repository paths, managed outputs, state, and atomic writes
• report produces deterministic JSON and Markdown reports
• cli owns command parsing and presentation
• cmd/deltawire contains only process entry-point wiring

Do not create a public Go SDK in v1.

Keep implementation packages under internal/.

7. Repository installation model

DeltaWire consists of:

1. A standalone CLI binary installed on the developer machine.
2. A repository-local .deltawire/ directory created by deltawire init.

Development installation:

go install ./cmd/deltawire

Repository installation:

deltawire init --repo .

deltawire init must create:

.deltawire/
  config.json
  INSTRUCTIONS.md
  state.json
  plans/
  schemas/

It must not:

• modify root AGENTS.md
• modify CLAUDE.md
• modify Cursor rules
• modify Gemini configuration
• modify CI configuration
• modify .gitignore
• render an example unless --example is explicitly supplied
• overwrite an existing modified file

Use go:embed for initialization assets.

Support:

deltawire init --repo .
deltawire init --repo . --dry-run
deltawire init --repo . --example

init must be idempotent.

A second identical invocation must produce no file changes.

If an initialization file exists and differs from the embedded version, refuse to overwrite it and report the exact path.

Do not provide an automatic force flag for initialization in v1.

8. Repository configuration

Use this versioned configuration shape:

{
  "version": "deltawire.config.v1",
  "plans_dir": ".deltawire/plans",
  "schemas_dir": ".deltawire/schemas",
  "state_file": ".deltawire/state.json",
  "limits": {
    "max_plan_bytes": 1048576,
    "max_schema_bytes": 1048576,
    "max_records": 100000,
    "max_output_bytes": 104857600
  }
}

Configuration requirements:

• strict JSON
• reject unknown fields
• reject duplicate object keys
• reject unsupported versions
• all paths are repository-root relative
• absolute paths are invalid
• path traversal is invalid
• symlink escape from the repository is invalid
• output paths under .git/ are invalid
• generated dataset paths under .deltawire/ are invalid
• state_file is the only managed output permitted under .deltawire/

Do not interpolate environment variables.

9. Generation-plan format

Generation plans use:

*.dw.json

Schema version:

deltawire.plan.v1

All paths in plans are repository-root relative.

Use this exact conceptual shape:

{
  "version": "deltawire.plan.v1",
  "id": "auth-eval",
  "description": "Authorization evaluation cases",
  "record_schema": ".deltawire/schemas/auth-case.schema.json",
  "output": {
    "path": "evals/generated/auth-cases.ndjson",
    "format": "ndjson",
    "pretty": false
  },
  "defaults": {
    "suite": "auth",
    "expected": "deny"
  },
  "sets": {
    "non_admin_roles": ["guest", "member"],
    "routes": ["billing", "admin"]
  },
  "generators": [
    {
      "kind": "matrix",
      "name": "non-admin routes",
      "dimensions": [
        {
          "name": "role",
          "set": "non_admin_roles"
        },
        {
          "name": "route",
          "set": "routes"
        }
      ],
      "record": {
        "id": "auth/${role}/${route}",
        "input": {
          "role": "${role}",
          "route": "/${route}"
        }
      }
    },
    {
      "kind": "rows",
      "name": "admin routes",
      "columns": [
        "/id",
        "/input/role",
        "/input/route",
        "/expected"
      ],
      "rows": [
        [
          "auth/admin/billing",
          "admin",
          "/billing",
          "allow"
        ],
        [
          "auth/admin/admin",
          "admin",
          "/admin",
          "allow"
        ]
      ]
    },
    {
      "kind": "variants",
      "name": "missing-role edge cases",
      "base": {
        "id": "auth/role/base",
        "input": {
          "role": "guest",
          "route": "/admin"
        }
      },
      "variants": [
        {
          "name": "empty",
          "set": {
            "/id": "auth/role/empty",
            "/input/role": ""
          }
        },
        {
          "name": "null",
          "set": {
            "/id": "auth/role/null",
            "/input/role": null
          }
        },
        {
          "name": "omitted",
          "set": {
            "/id": "auth/role/omitted"
          },
          "omit": [
            "/input/role"
          ]
        }
      ]
    }
  ],
  "assertions": {
    "count": 9,
    "unique": [
      "/id"
    ],
    "coverage": [
      {
        "path": "/expected",
        "values": [
          "allow",
          "deny"
        ]
      }
    ]
  }
}

Create and maintain:

schemas/deltawire-plan.schema.json

The installed copy must be:

.deltawire/schemas/deltawire-plan.schema.json

The Go parser remains authoritative.

The JSON Schema exists for:

• editor support
• external validation
• documentation
• fixture testing

Tests must prove that the JSON Schema and Go parser accept all valid examples and reject representative invalid examples.

10. Strict JSON parsing

Plan and configuration parsing must:

• use JSON numbers without silently converting all numbers to float64
• reject unknown fields
• reject duplicate object keys
• reject trailing non-whitespace data
• reject unsupported version strings
• return stable error codes with JSON Pointer or field-path locations
• never panic on user input

Standard DisallowUnknownFields is not enough because it does not reject duplicate keys.

Add an explicit duplicate-key detection pass.

Do not normalize malformed input into a valid plan.

11. Plan semantics

11.1 Defaults

defaults must be a JSON object.

Defaults are applied before generator-specific records.

Deep-merge rules:

• object + object: recursively merge
• scalar overrides scalar
• array replaces array
• null replaces the existing value
• generator data overrides defaults
• variant patches override defaults and base
• omission occurs after all merges

Defaults must not contain interpolation placeholders.

11.2 Sets

sets is a collection of named ordered scalar arrays.

Permitted set values:

• string
• JSON number
• boolean
• null

Objects and arrays are not permitted as set entries in v1.

Set names must be unique.

11.3 Matrix generator

A matrix generator has:

• kind: matrix
• unique name
• ordered dimensions
• one record template

Each dimension must define exactly one source:

• values
• set
• range

Inline values:

{
  "name": "role",
  "values": ["guest", "member"]
}

Named set:

{
  "name": "role",
  "set": "roles"
}

Integer range:

{
  "name": "index",
  "range": {
    "start": 0,
    "end_exclusive": 100,
    "step": 1
  }
}

Range rules:

• integers only
• step cannot be zero
• direction must agree with start and end
• overflow must be detected
• count must be computable before generation

Dimension names must match:

[A-Za-z_][A-Za-z0-9_]*

Dimension names must be unique within a generator.

Every dimension must be referenced by the record template.

Iteration order:

• generators remain in plan order
• dimensions remain in declared order
• values remain in declared order
• the last dimension changes fastest

Do not sort declared values.

11.4 Interpolation

Only matrix-record templates support interpolation.

Syntax:

${dimension_name}

Rules:

1. If the complete JSON string is exactly one placeholder:

   "${index}"
   

   preserve the original scalar type.

2. If a placeholder appears inside a larger string:

   "case-${index}"
   

   convert string, JSON number, or boolean to deterministic text.

3. Embedded null, object, or array values are invalid.

4. Unknown placeholders are errors.

5. Unclosed placeholders are errors.

6. Environment variables are never consulted.

7. Functions and expressions are not supported.

8. Interpolation is recursive through objects and arrays.

11.5 Rows generator

A rows generator has:

• kind: rows
• unique name
• ordered JSON Pointer columns
• ordered row arrays

Example:

{
  "kind": "rows",
  "name": "explicit cases",
  "columns": [
    "/id",
    "/input/value",
    "/expected"
  ],
  "rows": [
    ["empty", "", "reject"],
    ["null", null, "reject"]
  ]
}

Rules:

• columns use RFC 6901 JSON Pointer syntax
• columns must be unique
• every row length must exactly match column count
• v1 permits object-path creation
• v1 does not permit setting array indexes through row columns
• conflicting parent and child columns are invalid
• defaults are applied first
• row values are applied second
• row order is preserved

11.6 Variants generator

A variants generator has:

• kind: variants
• unique name
• one base JSON object
• ordered variants

Each variant has:

• unique name within the generator
• optional set
• optional omit

set keys are RFC 6901 JSON Pointers.

omit values are RFC 6901 JSON Pointers.

Rules:

• defaults are applied
• base is deep-merged
• set operations are applied
• omit operations are applied last
• set and omit cannot target the same pointer
• omission of a nonexistent path is an error
• v1 patch operations may target object properties
• v1 patch operations may not mutate array indexes
• variant order is preserved

11.7 Generator identity

Generator names must be unique inside one plan.

Plan IDs must be unique across all discovered plans.

Output paths must be unique across all discovered plans.

Do not silently merge outputs from multiple plans.

12. Output formats

Support only:

json
ndjson

JSON

JSON output is one array of generated records.

When pretty=false:

• canonical compact JSON
• exactly one trailing newline

When pretty=true:

• deterministic two-space indentation
• exactly one trailing newline

NDJSON

• one canonical compact JSON object per line
• records must be JSON objects
• exactly one newline after every record
• no array wrapper

Canonical output rules:

• object keys sorted deterministically
• strings encoded consistently
• JSON numbers preserved without float conversion where possible
• no insignificant nondeterminism
• no timestamps
• no runtime-specific map ordering
• no platform-specific line endings

The same plan, schema, configuration, and binary semantics must produce byte-identical output.

13. Record-schema validation

record_schema describes one generated record.

Every record must be validated before it is committed to output.

The schema:

• must be strict JSON
• must remain inside the repository
• must remain below the configured schema byte limit
• must not contain remote or external-file references
• may use internal fragment references beginning with #

Record generation fails on the first schema-invalid record.

The error must include:

• plan ID
• generator name
• zero-based generator record index
• schema failure location
• concise reason

Do not write or modify the target output when any record fails validation.

14. Assertions

Assertions are evaluated across the complete generated dataset.

V1 supports:

Count

{
  "count": 100
}

count is required.

It acts as a fanout contract.

A plan whose projected count differs from the asserted count must fail before writing output.

Unique

{
  "unique": ["/id"]
}

Rules:

• JSON Pointer must resolve on every record
• resolved value must be scalar
• canonical scalar value is used for comparison
• duplicate value reports both record indexes

Coverage

{
  "coverage": [
    {
      "path": "/expected",
      "values": ["allow", "deny"]
    }
  ]
}

Rules:

• path must resolve to a scalar
• every declared value must appear at least once
• extra observed values are permitted
• missing required values fail generation

Do not add arbitrary predicates in v1.

15. Expansion limits

Before generating:

• calculate projected record count
• detect integer overflow
• reject count above max_records
• reject count different from assertions.count

During generation:

• count output bytes
• stop before exceeding max_output_bytes
• delete temporary output
• leave existing output and state unchanged

Plan and schema files must be checked against configured byte limits before parsing.

Do not add a command-line flag that silently bypasses limits.

Users can explicitly edit repository configuration and commit the changed limits.

16. Pure engine boundary

The internal/engine package must be deterministic and side-effect free.

Inputs:

• validated plan
• compiled record validator
• generation limits
• record callback

Outputs:

• generated records through callback
• deterministic statistics
• assertion result
• structured errors

The engine package must not:

• read files
• write files
• access the network
• execute commands
• read environment variables
• use time
• use randomness
• depend on CLI packages
• depend on store packages

The same inputs must yield the same record sequence and statistics.

17. Repository path safety

All user-controlled paths must be resolved against the selected repository root.

Reject:

• absolute paths
• .. traversal outside the repository
• output paths under .git
• dataset outputs under .deltawire
• symlink escapes
• paths whose nearest existing parent resolves outside the repository
• output paths that collide with config, state, plan, or schema files

Test on the current platform using temporary directories.

Implement path logic so it remains portable across Windows, macOS, and Linux.

Do not rely on string-prefix comparison alone.

18. Managed-output safety

DeltaWire owns only outputs recorded in:

.deltawire/state.json

State schema:

{
  "version": "deltawire.state.v1",
  "entries": [
    {
      "plan_id": "auth-eval",
      "plan_path": ".deltawire/plans/auth-eval.dw.json",
      "schema_path": ".deltawire/schemas/auth-case.schema.json",
      "output_path": "evals/generated/auth-cases.ndjson",
      "plan_sha256": "...",
      "schema_sha256": "...",
      "output_sha256": "...",
      "record_count": 9,
      "plan_source_bytes": 1234,
      "schema_source_bytes": 567,
      "output_bytes": 8901
    }
  ]
}

State rules:

• no timestamps
• no absolute paths
• entries sorted by plan path
• SHA-256 lowercase hex
• plan hash uses canonical semantic plan representation
• schema hash uses canonical JSON representation
• output hash uses exact generated bytes
• source byte counts use actual source-file lengths

Render behavior:

1. If output does not exist:

   • generation may proceed

2. If output exists and no state entry owns it:

   • refuse to overwrite
   • return unmanaged-output error

3. If output exists and its current hash differs from recorded output hash:

   • refuse to overwrite
   • return modified-managed-output error

4. If output exists and matches recorded output hash:

   • safe regeneration is permitted

Support:

deltawire render <plan>
deltawire render <plan> --dry-run
deltawire render <plan> --force

--force requirements:

• explicit user invocation only
• never used by init
• never used by check
• never suggested in agent instructions
• cannot bypass path safety
• cannot bypass schema validation
• cannot bypass assertions
• cannot bypass size limits
• prints which existing managed or unmanaged output would be replaced

Agents must be instructed not to use --force without explicit human approval.

19. Atomic generation

Generation must use a temporary file in the target directory.

Required sequence:

1. Parse and validate config.
2. Parse and validate plan.
3. Resolve and validate paths.
4. Calculate projected count.
5. Compile record schema.
6. Stream records into a temporary output.
7. Validate every record.
8. Track assertions.
9. Enforce output byte limit.
10. Finalize assertions.
11. Flush and close temporary output.
12. Calculate output hash.
13. Prepare deterministic new state.
14. Replace target output atomically.
15. Replace state atomically.

If any step before target replacement fails:

• delete temporary files
• leave current output unchanged
• leave state unchanged

If output replacement succeeds but state replacement fails:

• attempt to restore the previous output
• report the state-write failure
• document that deltawire check detects any interrupted state transition

Do not write partial final output.

20. CLI commands

Implement:

deltawire init
deltawire validate
deltawire render
deltawire check
deltawire inspect
deltawire doctor
deltawire version

All commands support:

--repo <path>

Default repository path:

current working directory

validate

deltawire validate <plan>
deltawire validate --all

Behavior:

• no repository mutation
• validate plan syntax
• validate plan semantics
• compile record schema
• generate to a discard sink
• validate every record
• evaluate assertions
• report projected record and byte statistics

render

deltawire render <plan>
deltawire render --all
deltawire render <plan> --dry-run
deltawire render <plan> --force

Behavior:

• perform complete validation
• enforce managed-output rules
• write output and state only after success

--all discovers:

<plans_dir>/**/*.dw.json

Discovery order must be lexicographically sorted by repository-relative path.

Before writing any output in --all mode:

• load all plans
• validate unique plan IDs
• validate unique output paths
• preflight all counts and paths

Do not partially render the first plans and then discover a collision later.

check

deltawire check <plan>
deltawire check --all

Behavior:

• no repository mutation
• deterministically regenerate to a hash/count sink
• compare semantic plan hash
• compare schema hash
• compare exact output hash
• compare record count
• compare state entry
• report missing output
• report stale output
• report modified output
• report stale state
• report unmanaged collision

This is the CI command.

Do not trust state without regenerating.

inspect

deltawire inspect <plan>
deltawire inspect <plan> --format json
deltawire inspect <plan> --format markdown

Default format:

human-readable text

The deterministic JSON report includes:

• plan ID
• plan path
• schema path
• output path
• output format
• projected record count
• assertion summary
• plan source bytes
• schema source bytes
• projected output bytes
• plan-only byte amplification numerator and denominator
• cold byte amplification numerator and denominator
• generation primitives used
• exact validate command
• exact render command
• exact check command

Do not store floating-point ratios in state.

Display ratios only in reports.

Definitions:

plan_only_wire_amplification =
    output_bytes / plan_source_bytes

cold_wire_amplification =
    output_bytes / (plan_source_bytes + schema_source_bytes)

Label these as byte-level representation measurements.

Do not call them model-token savings.

Markdown format must produce a plan-ready block:

### DeltaWire generation contract

- Plan: `.deltawire/plans/auth-eval.dw.json`
- Record schema: `.deltawire/schemas/auth-case.schema.json`
- Output: `evals/generated/auth-cases.ndjson`
- Projected records: `9`
- Assertions: exact count, unique `/id`, coverage `/expected`
- Generate: `deltawire render .deltawire/plans/auth-eval.dw.json`
- Verify: `deltawire check .deltawire/plans/auth-eval.dw.json`

This is the generic integration surface for:

• Boatstack plans
• coding-agent plans
• benchmark plans
• eval plans
• CI documentation

Do not parse or modify arbitrary Markdown plans in v1.

doctor

deltawire doctor

Validate:

• repository root
• configuration
• plans directory
• schemas directory
• state schema
• duplicate plan IDs
• duplicate output paths
• state paths remain inside repository
• managed outputs exist or are reported missing
• no remote schema references
• embedded initialization assets are available

No writes.

No network.

version

Print:

• semantic binary version or dev
• Go runtime version
• supported config version
• supported plan version
• supported state version

No timestamp.

21. Exit codes and stable errors

Use stable error codes in stderr.

At minimum:

DW_USAGE
DW_CONFIG_INVALID
DW_PLAN_INVALID
DW_SCHEMA_INVALID
DW_ASSERTION_FAILED
DW_OUTPUT_DRIFT
DW_OUTPUT_UNMANAGED
DW_OUTPUT_MODIFIED
DW_PATH_ESCAPE
DW_LIMIT_EXCEEDED
DW_STATE_INVALID
DW_INTERNAL

Process exit codes:

0  success
1  internal failure
2  usage or configuration failure
3  plan, schema, or assertion failure
4  output/state drift or overwrite refusal
5  path or resource-limit violation

Tests must assert both stable error code and process exit code.

Do not expose Go stack traces for user input errors.

22. Portable agent instructions

deltawire init must create:

.deltawire/INSTRUCTIONS.md

Use content equivalent to:

# DeltaWire repository instructions

Use DeltaWire for repetitive generated test, fixture, benchmark, or evaluation
data.

Do not manually generate or edit a managed output when the data can be derived
from a DeltaWire plan.

Workflow:

1. Create or edit a `.deltawire/plans/*.dw.json` generation plan.
2. Keep the record schema under `.deltawire/schemas/`.
3. Run `deltawire validate <plan>`.
4. Run `deltawire inspect <plan> --format markdown` when preparing a coding plan.
5. Run `deltawire render <plan>`.
6. Run `deltawire check <plan>` before claiming completion.

Never use `deltawire render --force` without explicit human approval.

Do not claim model-token savings from byte-amplification measurements.

Generated data is complete only when:

- record-schema validation passes
- dataset assertions pass
- the output hash matches repository state
- `deltawire check` exits successfully

Do not generate agent-vendor-specific adapters in v1.

23. Example record schema

Create:

examples/auth-eval/auth-case.schema.json

Use a strict Draft 2020-12 schema equivalent to:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "auth-case",
  "type": "object",
  "required": [
    "id",
    "suite",
    "input",
    "expected"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "suite": {
      "const": "auth"
    },
    "input": {
      "type": "object",
      "required": [
        "route"
      ],
      "properties": {
        "role": {
          "type": [
            "string",
            "null"
          ]
        },
        "route": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "expected": {
      "enum": [
        "allow",
        "deny"
      ]
    }
  },
  "additionalProperties": false
}

The $schema URI identifies the dialect and must not be fetched.

The $id is an identifier and must not be fetched.

Test that external $ref values are rejected.

24. Example generation plan

Create:

examples/auth-eval/auth-eval.dw.json

Use the nine-record example defined earlier in this specification.

Also ensure:

• the example validates
• render output is deterministic
• count is exactly 9
• /id is unique
• /expected covers allow and deny
• omitted role remains valid
• null role remains valid
• empty role remains valid

Do not claim that the example is a benchmark.

It is a deterministic fixture.

25. Initialization example

When:

deltawire init --example

create the example as repository-local files:

.deltawire/schemas/auth-case.schema.json
.deltawire/plans/auth-eval.dw.json

Set the example output to:

testdata/generated/auth-cases.ndjson

Do not render it automatically.

Print:

deltawire validate .deltawire/plans/auth-eval.dw.json
deltawire inspect .deltawire/plans/auth-eval.dw.json --format markdown
deltawire render .deltawire/plans/auth-eval.dw.json
deltawire check .deltawire/plans/auth-eval.dw.json

26. Required unit tests

Add comprehensive tests for:

Strict parsing

• valid config
• unknown config field rejected
• duplicate config key rejected
• unsupported config version rejected
• valid plan
• unknown plan field rejected
• duplicate plan key rejected
• trailing JSON rejected
• unsupported plan version rejected
• numeric values preserve intended representation

Matrix generation

• inline values
• named sets
• integer range
• dimension order
• Cartesian count
• last dimension changes fastest
• exact-placeholder type preservation
• embedded-placeholder string conversion
• unknown placeholder rejected
• unclosed placeholder rejected
• unused dimension rejected
• zero range step rejected
• inconsistent range direction rejected
• range overflow rejected
• projected-count overflow rejected

Rows generation

• valid rows
• row order
• defaults applied
• exact row width required
• duplicate columns rejected
• invalid JSON Pointer rejected
• parent/child column collision rejected
• array-index mutation rejected

Variants generation

• defaults then base then set then omit
• variant order
• duplicate variant name rejected
• set/omit collision rejected
• missing omit path rejected
• invalid pointer rejected
• array-index mutation rejected

Merge behavior

• recursive object merge
• array replacement
• scalar replacement
• null replacement

Assertions

• exact count
• count mismatch before write
• unique success
• duplicate unique value reports both indexes
• missing unique path
• non-scalar unique value rejected
• coverage success
• missing coverage value
• missing coverage path

Schema validation

• valid record
• invalid record
• error includes plan ID
• error includes generator name
• error includes record index
• internal fragment reference works
• HTTP reference rejected
• HTTPS reference rejected
• file reference rejected
• relative external-file reference rejected

Canonical output

• JSON compact
• JSON pretty
• NDJSON
• stable key ordering
• stable newline behavior
• stable JSON number behavior
• repeated execution produces identical bytes

Limits

• plan byte limit
• schema byte limit
• record count limit
• output byte limit
• temporary file removed on failure
• existing output unchanged on failure

Repository paths

• valid nested output
• absolute output rejected
• traversal rejected
• .git output rejected
• .deltawire dataset output rejected
• existing symlink escape rejected
• new-file parent symlink escape rejected
• output collision rejected

Managed outputs

• new output accepted
• unmanaged existing output refused
• matching managed output replaced
• modified managed output refused
• force is explicit
• force does not bypass validation
• force does not bypass paths
• state entries sorted
• state contains no timestamp
• state uses repository-relative paths

Init

• first initialization
• second initialization is idempotent
• dry-run writes nothing
• modified embedded file is not overwritten
• example created only with --example

CLI

• every command help surface
• required exit-code mapping
• stable error codes
• validate performs no writes
• check performs no writes
• inspect Markdown is deterministic
• doctor performs no writes
• version contains no timestamp

27. Required integration tests

Create temporary Git repositories and exercise the real compiled CLI.

Integration 1 — clean lifecycle

1. Initialize repository.
2. Initialize DeltaWire with example.
3. Validate example.
4. Inspect Markdown contract.
5. Render example.
6. Check example.
7. Record output SHA-256.
8. Render again.
9. Record output SHA-256 again.
10. Assert identical hashes.
11. Assert second check succeeds.

Integration 2 — output drift

1. Render example.
2. Manually modify generated output.
3. Run check.
4. Assert DW_OUTPUT_DRIFT or DW_OUTPUT_MODIFIED.
5. Run normal render.
6. Assert overwrite is refused.
7. Assert modified file remains unchanged.

Do not use --force in this integration.

Integration 3 — unmanaged output

1. Create the intended output manually before first render.
2. Run render.
3. Assert DW_OUTPUT_UNMANAGED.
4. Assert the file remains unchanged.

Integration 4 — invalid record

1. Modify the plan so one record violates the schema.
2. Render.
3. Assert failure.
4. Assert existing output and state remain byte-identical.

Integration 5 — stale plan

1. Render.
2. Change plan semantics.
3. Run check.
4. Assert drift.
5. Render.
6. Run check.
7. Assert success.

Integration 6 — path escape

1. Create symlink from a path inside the repository to a directory outside.
2. Target output through the symlink.
3. Assert render fails.
4. Assert no external file is created.

Skip only when the current platform cannot create symlinks, and report the skip explicitly.

Integration 7 — all-plan preflight

1. Create two valid plans with the same output path.
2. Run render --all.
3. Assert failure before any output is written.

Integration 8 — process determinism

Run the same inspect and render operations in separate processes.

Assert:

• identical inspect JSON
• identical inspect Markdown
• identical generated output
• identical state entry

28. Determinism validation

Add:

scripts/check-determinism.sh

It must:

1. Create two independent temporary repositories.
2. Initialize the same DeltaWire example in both.
3. Render both.
4. Compare:
   • output files
   • state files
   • inspect JSON
   • inspect Markdown
5. Use cmp.
6. Fail on any difference.

Also run:

go test -count=20 ./...

Do not seed output with temporary paths.

Do not include absolute repository paths in deterministic reports or state.

29. Runtime-boundary validation

Add:

scripts/check-runtime-boundary.sh

Use Go tooling plus source inspection.

Assert that project-owned runtime packages do not directly import:

net
net/http
net/rpc
os/exec
plugin
math/rand
crypto/rand

Assert that engine packages do not directly import:

os
io/fs
path/filepath
time
runtime
internal/cli
internal/store

It is acceptable for CLI/store packages to use filesystem packages.

Reject source references to:

• OpenAI
• Anthropic
• Gemini model SDKs
• model inference endpoints
• embedding clients
• shell command execution

Do not simply grep dependency names and claim proof.

Use:

go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...

and test the actual package boundaries.

Also test that remote $ref values are rejected before schema compilation.

30. Validation script

Create:

scripts/validate.sh

It must use:

set -euo pipefail

It must print every command before running it.

Run, in order:

1. gofmt verification
2. go mod tidy verification
3. go test ./...
4. go test -race ./...
5. go test -count=20 ./...
6. go vet ./...
7. runtime-boundary check
8. determinism check
9. build static binary
10. run example lifecycle
11. git diff --check

Suggested build:

mkdir -p dist
CGO_ENABLED=0 go build -trimpath -o dist/deltawire ./cmd/deltawire

Do not suppress failures.

Do not use:

|| true

Do not automatically rewrite golden files.

The validation script must clean generated temporary files.

The final repository may ignore:

dist/

31. CI

Add a minimal GitHub Actions workflow using official GitHub actions.

Required checks:

• Linux: full validation script
• macOS: go test and build
• Windows: go test and build
• static builds for:
  • linux amd64
  • linux arm64
  • darwin amd64
  • darwin arm64
  • windows amd64

Do not add an automated release workflow in v1.

Do not reference a GitHub release that does not exist.

The currently verified installation path is:

go install ./cmd/deltawire

A public binary installer remains future work.

32. Documentation

README.md

Lead with user value:

# DeltaWire

Generate large, verified test and eval datasets from compact declarative plans.

Instead of asking a coding agent to emit hundreds or thousands of repetitive
records, define the decisions, dimensions, defaults, and edge cases once.
DeltaWire materializes the complete JSON or NDJSON dataset, validates every
record, checks dataset-level invariants, and records reproducible hashes.

The agent defines the data.
DeltaWire performs the repetition.
Your tests and evals consume ordinary files.

Include:

• installation
• repository initialization
• minimal example
• commands
• plan integration
• safety behavior
• current claim status
• explicit non-goals

Do not describe DeltaWire as universal LLM compression.

docs/architecture.md

Document:

compact generation plan
        ↓
strict parser
        ↓
preflight count and path checks
        ↓
deterministic record stream
        ↓
record-schema verifier
        ↓
dataset assertions
        ↓
atomic managed output
        ↓
reproducibility state

Explain the two slices:

• generation
• reliability boundary

docs/plan-format.md

Document every field and exact semantic rule.

Include matrix, rows, ranges, variants, interpolation, defaults, assertions, and path resolution.

docs/verification.md

Document:

• schema validation
• assertions
• deterministic hashing
• managed outputs
• check behavior
• size limits
• atomic writes
• path safety

docs/plan-integration.md

Explain how any coding plan can include:

deltawire inspect <plan> --format markdown

Provide a generic plan section.

Do not couple it to Boatstack.

Include a Boatstack-compatible example only as ordinary Markdown, not as code or a dependency.

docs/claims.md

Use:

Verified

• deterministic plan expansion
• JSON and NDJSON materialization
• per-record schema validation
• count, uniqueness, and coverage assertions
• managed-output protection
• deterministic state and hashes
• repository installation through deltawire init
• no model call in DeltaWire runtime
• no runtime network requirement

Observed

• fixture-specific byte amplification from compact plans to generated output

Make clear that this is a byte-level property of fixtures.

Being evaluated

• model-token savings
• prompt-token amortization
• retry-rate effects
• performance across model tokenizers
• eval-quality improvements
• benchmark-development speed
• broader semantic-delta use cases

docs/research-next.md

Future work only:

• exact tokenizer adapters
• schema-once model grammars
• source-span references
• dictionary coding
• columnar model-facing formats
• semantic deltas
• deterministic code patch materialization
• paired model experiments
• agent integration adapters

Do not implement these in v1.

33. Byte-amplification report

The example and inspect command may report:

plan_source_bytes
schema_source_bytes
output_bytes

And derive:

plan-only byte amplification
cold byte amplification

The report must say:

Byte amplification measures representation expansion.
It does not establish tokenizer-specific savings.

Do not present fixture results as general product performance.

Do not add an approximate “characters divided by four” token estimate.

34. Claim discipline

Public and implementation claims must use these levels:

Verified

Supported by tests or deterministic inspection.

Observed

Seen in a named example or fixture, without generalization.

Being evaluated

Not yet established.

Forbidden claims:

• saves 50% of tokens
• universally reduces LLM cost
• improves benchmark quality
• improves eval quality
• works with every schema
• replaces fuzzing
• replaces synthetic-data systems
• zero compute
• compression without tradeoffs

Allowed statement:

DeltaWire makes it possible to measure whether compact generation plans
reduce model output while preserving exact generated data.

35. Prohibited shortcuts

Do not:

• let the agent generate the expanded golden dataset and hardcode it
• implement examples without using the real engine
• make tests pass by weakening schema validation
• treat JSON parser success as record correctness
• use unordered map iteration for record order
• silently coerce invalid values
• silently drop duplicate IDs
• silently skip invalid records
• continue after assertion failure
• write output before all validation succeeds
• overwrite unmanaged files
• use absolute paths in state
• add timestamps to state
• add random IDs
• use network schema loading
• use external processes for generation
• create a plugin system
• implement arbitrary expressions
• add a model API
• add token-savings benchmark numbers
• add a public installer that points to nonexistent releases
• modify unrelated repositories
• commit or push

36. Required final validation

Run:

./scripts/validate.sh

Then run manually:

go install ./cmd/deltawire

Create a fresh temporary repository and run:

deltawire init --repo . --example
deltawire validate --repo . .deltawire/plans/auth-eval.dw.json
deltawire inspect --repo . .deltawire/plans/auth-eval.dw.json --format markdown
deltawire render --repo . .deltawire/plans/auth-eval.dw.json
deltawire check --repo . .deltawire/plans/auth-eval.dw.json
deltawire doctor --repo .

Record all exit codes.

Run:

go list -m all
go mod graph
git diff --check
git status --short
git diff --stat

Do not state that validation passed unless all required commands actually exited successfully.

37. Required final response

Return exactly these sections.

Grounded repository facts

Include:

• repository root
• branch
• starting commit or empty-repository state
• Go version
• dependency selected
• commands used to verify the dependency

Implementation summary

Describe what was built without marketing language.

Files changed

List exact paths.

Plan format implemented

List:

• defaults
• sets
• matrix
• ranges
• rows
• variants
• interpolation
• assertions
• output formats

Reliability boundaries

List:

• strict parsing
• duplicate-key rejection
• record-schema validation
• assertions
• path safety
• size limits
• managed-output protection
• atomic writes
• deterministic hashes

Validation evidence

Provide a table:

Requirement | Exact command or test | Exit code | Result

Include actual output excerpts.

Do not write only “all tests pass.”

Determinism evidence

Include:

• output hash from run one
• output hash from run two
• state hash from run one
• state hash from run two
• cmp result

Managed-output evidence

Name the tests proving:

• unmanaged files are preserved
• modified managed outputs are preserved
• invalid generation leaves previous output unchanged
• force does not bypass validation

Path-safety evidence

Name the traversal and symlink tests.

Dependency evidence

Paste:

go list -m all

Explain the JSON Schema dependency and why it is present.

Runtime-boundary evidence

Show that DeltaWire contains:

• no model client
• no runtime network path
• no shell execution path
• no randomness in generation
• no wall-clock data in state

Example report

Paste the output of:

deltawire inspect ... --format markdown

Include byte measurements, clearly labeled as fixture-specific.

Claim status

Verified: list verified v1 properties

Observed: list fixture-only observations

Being evaluated: model-token savings retry effects benchmark-development speed eval-development speed cross-model behavior

Git status

Paste:

git status --short
git diff --stat

Explicit exclusions

State:

No model call was added.
No benchmark was run.
No token-savings claim was made.
No CSV, Parquet, YAML, or arbitrary scripting was added.
No Boatstack dependency was added.
No release or remote repository was created.
No commit or push was performed.