docs: add metadata field to context compaction event contracts

[colombod]

Summary

Contract-only change to CONTEXT_CONTRACT.md. Adds an optional metadata: dict | null property bag to all context compaction event payloads and documents the previously undocumented context:compaction event.

No code changes — this establishes the contract for future implementation in context manager modules.

What this PR does

1. Adds metadata field to compaction event examples — the code samples for context:pre_compact and context:post_compact now include a metadata dict showing phase-appropriate exemplars that future implementers can use as copy-paste targets:

   • pre_compact: {"strategy": "sliding_window", "trigger": "token_limit", "budget": 195000} — reports why compaction is happening and under what constraints
   • post_compact: {"budget_remaining": 97500, "storage_quota_pct": 0.42} — reports what is left after compaction, including persistence-aware info like remaining storage quota

2. Documents context:compaction with a concrete example — this event already exists as a constant in amplifier_core/events.py (line 41: CONTEXT_COMPACTION = "context:compaction") but was missing from the contract doc. This PR adds it to the "Standard events to emit" list along with a full payload example showing before/after stats and metadata with compaction trigger reason and strategy (e.g., "compaction_trigger": "topic_drift", "strategy": "semantic_pruning").

3. Adds metadata property bag explanation — describes the metadata field as an extensible property bag for implementation-specific data (compaction strategy, trigger reason, remaining budget, storage quota). Consumers that do not need metadata ignore it; set to null when no implementation-specific data is available.

4. Updates validation checklist — the "Recommended" checklist now mentions the metadata field.

Motivation

Context compaction event payloads currently have no extensibility mechanism. Different context manager implementations (in-memory, persistent, quota-aware) will want to surface implementation-specific data without changing the top-level event shape. An optional metadata property bag is the lightest-weight way to enable this.

Current state of implementations

• amplifier-module-context-simple currently emits only context:compaction (not pre_compact/post_compact) with a flat stats dict and no metadata field.
• amplifier-module-context-persistent inherits from context-simple and emits no additional events.
• Aligning these implementations with this contract will follow in separate PRs.

Backward compatibility

Contract change only. The metadata field is optional (dict | null, defaults to null), so existing context managers remain compliant without modification.

[bkrabach]

Thanks for the contribution — adding metadata as an extensibility point on context events is the right call and aligns with how we use metadata across the ecosystem as a property bag for experimentation and convention.

Two items to address:

1. Example should show the populated case (required)

The current example shows "metadata": None — contract docs are copy-paste targets. Show an exemplar instead, e.g.:

"metadata": {"strategy": "sliding_window", "trigger": "token_limit"}

The explanatory text below can note that it's None when no implementation-specific data is available.

2. context:compaction documentation (positive)

Good catch — context:compaction exists as a constant in events.py but wasn't documented in this contract. Worth noting in the PR description that you're documenting an existing-but-unimplemented event.

[colombod]

Addressed both items:

1. Populated examples — Updated the code samples to show phase-appropriate metadata instead of None:

• pre_compact: {"strategy": "sliding_window", "trigger": "token_limit", "budget": 195000} — why compaction is happening
• post_compact: {"budget_remaining": 97500, "storage_quota_pct": 0.42} — what is left after compaction, including persistence-aware info like storage quota

The explanatory text below still notes that metadata is null when no implementation-specific data is available.

2. context:compaction documentation — Updated the PR description to clarify that context:compaction already exists as a constant in events.py but was missing from the contract doc. Also added a "Current state of implementations" section noting that neither context-simple nor context-persistent implements the metadata field yet — this contract is forward-looking, with implementation PRs to follow.