# Toon — TODO

## Priority legend
- **P0** blocker · **P1** important · **P2** nice-to-have · **P3** idea

---

## ACCORE-TOON-T-D1R7: Tabular array mode (CSV-style headered lists)
**Priority:** P2 · **Type:** Feature (opt-in) · **Origin:** 2026-04-24 LLM-accuracy proposal

Emit arrays of homogeneous flat objects with a single column header instead of repeating property names on every element:

```
OrderItems: OrderItem[] = [
  [Id, Quantity, ProductName]
  [120, 10, "Blueberries"]
  [121, 5, "Oranges"]
]
```

Activation conditions (all must hold):
- Every element's runtime type equals the declared element type (no polymorphism).
- All element properties are primitives/strings (no nested objects).
- `OmitDefaultValues = false` (otherwise empty columns are ambiguous), or a separate empty-cell encoding chosen.

When any condition fails → fall back to the current named syntax.

Rationale: the CSV pattern is heavily represented in LLM training data; a single header avoids per-row key repetition. Estimated 30-50% token savings on arrays with 50+ rows. Must remain OFF in `Verbose` preset for debug clarity.

## ACCORE-TOON-T-G5M3: Schema-derived type elision in `@data`
**Priority:** P2 · **Type:** Feature · **Origin:** 2026-04-24 LLM-accuracy proposal

Omit type names on `@data` list elements when:
1. The containing property's declared type is a concrete class (not interface/abstract).
2. The collection is non-polymorphic at runtime.
3. The element is not the `@data` root.

```
// Currently
GenericAttributes = [
  GenericAttributeDto { Id = 99, Key = "NetWeight" }
]

// Proposed (when conditions hold)
GenericAttributes = [
  { Id = 99, Key = "NetWeight" }
]
```

Must stay explicit in `Verbose` mode and in polymorphic collections (type name is the discriminator). The main design tension: this slightly erodes the "explicit is better" principle — schema drift in a long conversation could cause silent misinterpretation. Pair with ACCORE-TOON-T-S6B9 to mitigate.

## ACCORE-TOON-T-J8N6: Schema-declared default values
**Priority:** P2 · **Type:** Feature · **Origin:** 2026-04-24 LLM-accuracy proposal

Currently `OmitDefaultValues = true` removes fields equal to `default(T)`, but the LLM must guess what the default is. Extend `@types` with explicit per-property defaults so absence becomes unambiguous:

```
@types {
  Product:
    Stock: int32
      description: "Available inventory"
      default-value: 0
      constraints: "required, non-negative"
}
```

Implementation: during `@types` emission, detect the property's `default(T)` value and emit `default-value: ...` when `OmitDefaultValues = true`. `@data` omission then carries documented semantics ("use the schema default"), not implicit guessing.

Deserializer impact: N/A — no deserializer yet (see ACCORE-TOON-T-F3X1).

## ACCORE-TOON-T-V2T4: Reference-handling preset audit
**Priority:** P3 · **Type:** Configuration review · **Origin:** 2026-04-24 LLM-accuracy proposal

The `@N` / `@ref:N` syntax exists and works (see `TOON_FORMAT.md#reference-syntax`). Audit whether the presets activate it aggressively enough:

- `Default` preset inherits `ReferenceHandling` from the base `AcSerializerOptions` default — verify the default is `OnlyId` or `All`, not `None`, for IId-bearing entity graphs.
- `Compact` explicitly sets `None` — intentional (token-minimal) but may duplicate shared objects.
- Document explicitly which preset to choose when the object graph has repeated entities.

Deliverable: a "When to choose which ReferenceHandling mode" section in `TOON_OPTIONS.md` with concrete examples.

## ACCORE-TOON-T-S6B9: Schema hash in `@meta`
**Priority:** P3 · **Type:** Feature (defense-in-depth for ACCORE-TOON-T-G5M3, ACCORE-TOON-T-J8N6) · **Origin:** 2026-04-24

After ACCORE-TOON-T-G5M3 and ACCORE-TOON-T-J8N6 ship, `@data` payloads rely more heavily on a specific `@types` schema. In multi-turn conversations, the LLM's cached schema may drift out of sync with the sender's.

Emit a compact schema fingerprint in `@meta`:

```
@meta {
  version = "1.0"
  schema-hash = "a3f9b2"
  types = [...]
}
```

The prompt template instructs the LLM: *"only use cached schema when the `schema-hash` matches; otherwise request the full schema again."* Cost: ~20-30 tokens per payload. Benefit: silent schema drift becomes detectable.

## ACCORE-TOON-T-F3X1: Deserialization support
**Priority:** P3 · **Type:** Feature (major) · **Origin:** 2026-04-24 during docs migration

Toon is currently **serialize-only** — there is no `AcToonDeserializer`. An LLM can produce Toon-formatted responses, but the framework cannot parse them back into C# objects.

Decision needed before implementation:
- Is Toon deserialization in-scope? (Primary goal is LLM accuracy — deserialization is mostly useful for LLM-generated outputs.)
- Or is `AcBinary`/`AcJson` the intended deserialization path, with Toon strictly a presentation format for LLM inputs?

If in-scope, the parser must handle: `@meta`/`@types`/`@data` sections, reference resolution (`@N` / `@ref:N`), multi-line strings, numeric enum values (requires `@types` for name mapping), tabular arrays (if ACCORE-TOON-T-D1R7 lands), polymorphic collections.

## ACCORE-TOON-T-M9Q2: Validate benchmark claims before re-adding to docs
**Priority:** P3 · **Type:** Doc correctness · **Origin:** 2026-04-24 during `ToonExtendedInfo.txt` removal

The original `ToonExtendedInfo.txt` (deleted during migration) claimed:
- First-time Full mode: ~85% of JSON speed.
- Subsequent DataOnly: ~95% of JSON speed.
- With attributes: ~90% of JSON speed.

No benchmark harness was found in `AyCode.Core.Tests` or `AyCode.Benchmark` backing these numbers. Either:
- (a) Run real benchmarks and replace with measured values in `TOON_OPTIONS.md`.
- (b) Drop the claims entirely — marketing filler without provenance is worse than no claim.

## ACCORE-TOON-T-W8B5: Adopt `MaxDepthBehavior` dispatch in Toon
**Priority:** P2 · **Type:** Feature parity · **Related:** `TOON_ISSUES.md#accore-toon-i-s4q9`

The base `AcSerializerOptions.MaxDepthBehavior` enum (`Truncate` / `Throw` / `Disable`) is honored by `AcBinarySerializer` but silently ignored by `AcToonSerializer`. Bring Toon to parity:

- **`Truncate`** — current Toon behavior (emit `null` at `depth > MaxDepth`); rename comment / wire the existing path through the dispatch.
- **`Throw`** — throw `InvalidOperationException` with type name + position in the output (offer matches Binary's diagnostic surface).
- **`Disable`** — skip the depth check entirely (max perf when graph is known cycle-free).

Implementation site: `AcToonSerializer.DataSection.cs` (depth-check fire-point) + `AcToonSerializer.MetaWriter.cs` (the `@types` walk also recurses; verify whether it should honor the same dispatch).

Acceptance:
- All three modes produce the documented output.
- A test exercises each variant on a cyclic graph without `ReferenceHandling`.
- Update `TOON_OPTIONS.md` `MaxDepthBehavior` row and `TOON_IMPLEMENTATION.md` reference-scanning paragraph to drop the "not honored" caveats; close `TOON_ISSUES.md#accore-toon-i-s4q9`.

## TODO entry template

```
## TODO-NN: Short title
**Priority:** P0 / P1 / P2 / P3 · **Type:** Bug fix / Feature / Cleanup / Docs · **Related:** `TOON_ISSUES.md#issue-NN` (if applicable)

Description of what and why, including the trigger (user request, audit finding, incident).

Options / sub-tasks / acceptance criteria.
```
