dtcs 0.12.0

# Getting Started

Install the tools and validate a contract. Prefer `pip install` when you want a fast first success; `cargo install` compiles from source and often takes longer than a few minutes.

## Prerequisites

- **Python 3.9+** (for PyPI) **or** **Rust 1.75+** (for `cargo install` / building from source)
- A terminal with `curl` (or any way to save a YAML file)

## 1. Install

```bash
pip install dtcs
# or: cargo install dtcs
```

Verify:

```bash
dtcs version
```

Expected:

```text
dtcs 0.12.0
spec 2.0.0
```

## 2. Get a minimal contract (no git clone)

PyPI and crates.io installs do **not** include the repo `examples/` directory. Download the sample:

```bash
curl -fsSL https://raw.githubusercontent.com/eddiethedean/dtcs/main/examples/minimal.dtcs.yaml \
  -o contract.dtcs.yaml
```

Or create `contract.dtcs.yaml` with this content (prefer `dtcsVersion: "2.0.0"`; `"1.0.0"` remains accepted):

```yaml
dtcsVersion: "2.0.0"
id: "demo.minimal"
name: "Minimal Demo"
version: "0.1.0"

metadata:
  description: "Smallest valid DTCS contract for install checks"
  classification: internal
  governance:
    owner: "docs"
    steward: "docs"
  provenance:
    author: "docs"
    createdAt: "2026-01-01T00:00:00Z"

inputs:
  - id: "people"
    schema:
      fields:
        - name: "person_id"
          type: "string"
          nullable: false
        - name: "display_name"
          type: "string"
          nullable: false

outputs:
  - id: "people_normalized"
    schema:
      fields:
        - name: "normalized_id"
          type: "string"
          nullable: false
        - name: "normalized_name"
          type: "string"
          nullable: false

semanticActions:
  - id: "lower_display_name"
    action: "dtcs:lowercase"
    target: "people.display_name"

lineage:
  mappings:
    - output: "people_normalized"
      inputs: ["people"]
      operation: "dtcs:derive"
      flow: derived
```

## 3. Validate (success milestone)

```bash
dtcs validate contract.dtcs.yaml
echo $?
```

Expected:

```text
valid
```

Exit code `0` means no error-severity diagnostics. If validation fails:

```bash
dtcs diagnostics contract.dtcs.yaml
```

Add `--json` for machine-readable output (see [json-output.md](json-output.md)).

**You are done with the first success path (validate).** Optional: run a tiny contract with sample rows without cloning (below), or continue with the table.

## 4. Run without cloning (optional)

Create `hello.dtcs.yaml`:

```yaml
dtcsVersion: "2.0.0"
id: "demo.hello"
name: "Hello Run"
version: "0.1.0"

metadata:
  description: "Minimal contract that executes with the reference runtime"
  classification: internal
  governance:
    owner: "docs"
    steward: "docs"
  provenance:
    author: "docs"
    createdAt: "2026-01-01T00:00:00Z"

inputs:
  - id: "people"
    schema:
      fields:
        - name: "name"
          type: "string"
          nullable: false

outputs:
  - id: "people_out"
    schema:
      fields:
        - name: "name"
          type: "string"
          nullable: false

semanticActions:
  - id: "lower_name"
    action: "dtcs:lowercase"
    target: "people.name"

lineage:
  mappings:
    - output: "people_out"
      inputs: ["people"]
```

Create `hello.input.json`:

```json
{
  "people": [
    { "name": "Ada" },
    { "name": "Grace" }
  ]
}
```

```bash
dtcs validate hello.dtcs.yaml
dtcs run hello.dtcs.yaml --input hello.input.json --json
```

Expected JSON includes lowercased names under `people_out` (for example `"ada"`, `"grace"`). A warning about the shared field name `name` is harmless. This is an in-memory teaching runtime, not a warehouse executor — see [limits.md](limits.md).

## Next steps

| Goal | Document / action |
|------|-------------------|
| Mental model (COM → validate → plan → run) | [concepts.md](concepts.md) |
| Versions (crate / Spec / `dtcsVersion`) | [versioning.md](versioning.md) |
| Author richer contracts | [writing-contracts.md](writing-contracts.md) |
| Sample pipeline (clone or download) | [`customer_pipeline.dtcs.yaml`](https://github.com/eddiethedean/dtcs/blob/main/examples/customer_pipeline.dtcs.yaml) |
| More recipes | [cookbook.md](cookbook.md) |
| Upgrade to 0.12 / Spec 2.0 | [migration-0.12.md](migration-0.12.md) |
| CLI flags and exit codes | [cli-guide.md](cli-guide.md) |
| CI gates | [ci-integration.md](ci-integration.md) |
| Common problems | [troubleshooting.md](troubleshooting.md) · [faq.md](faq.md) |

### Explore the full CLI (requires a local checkout)

```bash
git clone https://github.com/eddiethedean/dtcs.git
cd dtcs

dtcs validate examples/customer_pipeline.dtcs.yaml
dtcs analyze examples/customer_pipeline.dtcs.yaml
dtcs plan examples/customer_pipeline.dtcs.yaml
dtcs run examples/customer_pipeline.dtcs.yaml \
  --input tests/fixtures/runtime/customer_pipeline_input.json
dtcs compat examples/analysis/backward_old.yaml examples/analysis/backward_new.yaml
dtcs registry resolve dtcs:lowercase
```

Expected for a valid pipeline contract:

```text
valid
```

### Use from Python

```python
import dtcs
import urllib.request

url = "https://raw.githubusercontent.com/eddiethedean/dtcs/main/examples/minimal.dtcs.yaml"
content = urllib.request.urlopen(url).read()
report = dtcs.parse_and_validate(content)
assert dtcs.is_valid(report)
print(dtcs.__version__, dtcs.SPEC_VERSION)
```

Contract dicts use **camelCase** keys (`dtcsVersion`, `semanticActions`, …). See [Python API](../api/python.md).

## Develop from source

```bash
git clone https://github.com/eddiethedean/dtcs.git
cd dtcs
python -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin develop --no-default-features --features python --locked
pytest python/tests -v
```

See [CONTRIBUTING.md](https://github.com/eddiethedean/dtcs/blob/main/CONTRIBUTING.md#contributor-quickstart).