# Sykli 0.6.2 Contract Cleanup

This note summarizes the SDK pipeline contract cleanup from Phase 1 through
Phase 2C. The goal of this work was to make Sykli's emitted pipeline JSON a
clear execution contract for agents and tooling, rather than a loose SDK
serialization artifact.

## What changed

### Canonical schema

Sykli now has a canonical JSON Schema for SDK-emitted pipeline documents:

- `schemas/sykli-pipeline.schema.json`
- `docs/sdk-schema.md`

The schema defines the supported top-level fields, task fields, review-node
fields, and compatibility limits for the current contract.

### Conformance fixtures validate against the schema

The conformance JSON fixtures are now validated against
`schemas/sykli-pipeline.schema.json` by:

- `scripts/validate-conformance-schema.py`
- `tests/conformance/run.sh`

This makes the schema a guardrail for future SDK and fixture changes.

### `version` is the wire-format/schema version

The top-level `version` field is documented as the pipeline wire-format/schema
version.

Current behavior remains permissive: SDKs emit `version`, and the schema allows
the known values, but the engine does not yet enforce version-aware parsing.
The intended future behavior is for engines to accept supported versions and
reject unknown future versions unless an explicit compatibility mode is enabled.

Today:

- `version: "1"` means the baseline task graph format.
- `version: "2"` means the resource-aware format, including resources, mounts,
  caches, containers, and related execution-environment metadata.

### `target` removed from canonical SDK output

The `target` field was removed from the canonical SDK-emitted contract.

`target` had no execution semantics: SDKs emitted it, but the engine ignored it
and the executor did not honor it. Keeping it in canonical output made users and
agents likely to infer behavior that did not exist.

SDK builder methods are retained as deprecated/no-op compatibility shims where
needed, but canonical SDK JSON must not emit `target`. Execution requirements
should be expressed through concrete fields such as `container`, `resources`,
`mounts`, `k8s`, `services`, `workdir`, and `env`.

### TypeScript `K8sOptions` narrowed

The TypeScript SDK `K8sOptions` type was narrowed to the shape the SDK actually
emits. This removes drift between TypeScript declarations and the canonical
pipeline JSON contract. Advanced Kubernetes fields should use `k8sRaw(...)`;
the TypeScript SDK accepts either a JSON string or a structured object and
serializes it into the canonical `k8s.raw` field.

### Python conformance interpreter detection fixed

The conformance harness now lets `SYKLI_CONFORMANCE_PYTHON` participate in
Python interpreter detection and prefers Python 3.12 or newer. If no valid
interpreter exists, Python conformance cases still skip instead of failing for
local environments that cannot run them.

### Experimental review nodes across SDKs

All SDKs now support experimental review nodes with a dedicated review builder
or DSL form. Review nodes are graph nodes for review, reasoning, and check
primitives. They are not shell-command tasks.

Canonical review-node shape:

```json
{
  "name": "review-code",
  "kind": "review",
  "primitive": "lint",
  "agent": "claude",
  "context": ["src/**/*.go"],
  "depends_on": ["test"],
  "deterministic": true
}
```

Required fields:

- `name`
- `kind: "review"`
- `primitive`

Optional fields:

- `agent`
- `context`
- `depends_on`
- `inputs`, where already supported naturally by an SDK
- `deterministic`

Review nodes are non-executable. The schema rejects task execution fields on
review nodes:

- `command`
- `outputs`
- `gate`
- `container`
- `services`
- `k8s`
- `mounts`
- `retry`
- `timeout`

Review outputs are not canonical yet and were intentionally not designed in
this cleanup.

## Compatibility notes

- Existing engines may continue to ignore incoming non-canonical fields such as
  historical `target` for compatibility, but SDK-emitted canonical JSON should
  not include them.
- `version` is currently advisory for the engine. Future version-aware parsing
  should reject unknown future versions rather than silently reinterpreting them
  as older formats.
- Review-node support is experimental. SDKs should expose dedicated review
  builders rather than raw `kind` setters.

## Validation commands

```bash
python3 -c "import json; json.load(open('schemas/sykli-pipeline.schema.json'))"
python3 scripts/validate-conformance-schema.py
tests/conformance/run.sh
```
