# Experience model and compatibility

Each experience is a human-readable JSON document in `.reliora/experiences`. Stored records keep schema version `1`; Stage 2 adds optional/defaulted fields rather than forcing a global rewrite.

## Draft fields

| Field | Meaning |
| --- | --- |
| `title` | Specific, recognizable lesson name |
| `task` | Work being performed |
| `projectContext` | Relevant project and technology context |
| `tags` | Retrieval vocabulary |
| `problems` | Observed symptoms or failures |
| `failedAttempts` | Attempt/reason pairs; may be empty |
| `solution` | Applied solution |
| `whyItWorked` | Causal explanation |
| `applicability` | Boundaries for reuse |
| `warnings` | Risks and caveats; may be empty |
| `verification` | Reproducible evidence |
| `confidence` | `low`, `medium`, or `high` |
| `derivedFrom` | Optional project-local IDs deliberately refined or combined |
| `appliedExperiences` | Optional project-local IDs that materially guided the solution |

Unknown fields are rejected. Text and collection sizes are bounded. IDs must be UUIDs. Lineage cannot contain duplicates, cross-list duplicates, self references, or missing project-local targets.

## Stored fields

Reliora adds `schemaVersion`, `id`, `projectId`, `createdAt`, `updatedAt`, and `feedback`. The stable external reference is:

```text
reliora://project/<projectId>/experience/<id>
```

The locator is logical and portable; it never exposes a local filesystem path.

## Feedback

The compatible summary counters are:

```json
{
  "successes": 0,
  "failures": 0,
  "partialUses": 0,
  "notApplicableUses": 0,
  "outdatedUses": 0,
  "lastUsedAt": null,
  "events": []
}
```

Each new event has `schemaVersion: 1`, an outcome, optional impact, optional notes, and a timestamp. Event history is capped at 100 entries and notes at 500 characters. Applied outcomes (`success`, `partial`, `failure`) update `lastUsedAt`; consideration/staleness outcomes do not claim the lesson was applied.

## Part 1 compatibility

Part 1 records containing only `successes`, `failures`, and `lastUsedAt` load without modification. In memory they receive zero values for new counters, an empty event history, and empty lineage arrays. A file is rewritten only when that specific experience receives feedback; there is no eager whole-library migration.

Legacy feedback commands remain valid:

```sh
reliora feedback <id> --success
reliora feedback <id> --failure
```

Legacy JSON response fields such as `storageId`, the nested complete `experience`, `successfulUses`, and `failedUses` are retained while Stage 2 adds locators, match data, lineage, and extended counters.