docs(learn): document causal persistence contract

[cursor]

🧠 Noēsis Pull Request

Overview

Documents the current learning-event and learn.jsonl persistence contracts, including typed causal-link failures and accurate public enum/API behavior.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

The learning runtime requires persisted proposal records to carry caused_by, but the public docs showed a stale inline event payload, an inaccurate artifact example, and a nonexistent LearnStatus.PENDING value. This left adapter authors without a reliable way to join learning records to the canonical event trace or handle orphan-write failures.

Technical Details

• Updates docs/reference/events.mdx with the runtime artifact-reference payload and legacy compatibility constraint.
• Updates docs/explanation/artifacts.mdx with the learn/1.0 record shape, causal join example, and empty-log behavior.
• Updates docs/reference/python-api.mdx with current LearnStatus values, LearnProposal fields, persist_episode_learning(...), and MissingCausalLinkError handling.
• Covers noesis/runtime/learning.py, noesis/domain/learning/{errors,model}.py, noesis/learn.py, and noesis/trace/events.py.

Validation

Required

• All tests pass locally (pytest and uv are unavailable in this runner)
• Schema examples parse and documented API behavior passes direct Python smoke checks

Situational

• Docs links pass (npx --yes mintlify@latest broken-links)
• Markdown fence balance and git diff --check pass

Observability & Safety

Documentation-only. Clarifies that callers must pass an existing event ID and that an empty causal link fails before learn.jsonl is created or appended.