fix(recall): stamp injected memories with age, provenance grade, and stale flag

[cdeust]

Summary

The harness-comparison rev.2 A/B measured the ai-architect stack (Harness B) serving facts "2–4 months stale with no age signal": every recalled memory entered the model's context as bare text, so a months-old fact and a fresh one were indistinguishable (e.g. it served "PostgreSQL default" when the live default is SQLite, with no way for the reader to tell the claim was old). The store already tracks the freshness — created_at, the source_attribution provenance grade, and is_stale — but the injection formatter discarded all three. This threads them through the primary UserPromptSubmit recall path and renders them as a compact per-memory suffix.

Before → after (rendered injection line):

- PostgreSQL is the default store (decision)
- PostgreSQL is the default store (decision)  ·  3mo ago  ·  src=verified  ·  ⚠stale

Addresses cdeust/fleet-watch#110 (freshness seams) for the primary recall path. It does not fully close #110: the parallel formatters (session_start banner, recall_helpers.inject_triggered_memories) take the same shared/freshness.py helper as a follow-up, and #110 also covers post-commit re-verify + provenance-first seeding.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Audit-finding closure (partial — cdeust/fleet-watch#110, primary recall path only)

Test plan

Authoring environment has no numpy/psycopg/pytest, so the full suite runs in CI. What was verified locally:

• New pure tests — tests_py/shared/test_freshness.py: age buckets (just-now → years), ISO-8601 + naive-datetime coercion, unknown/absent-field omission, grade+stale composition.

• New formatter tests — two cases in tests_py/hooks/test_hook_receipts_unit.py: the suffix renders when fields are present; a bare memory renders identically to before (no ·), so existing budget/parity tests are unaffected.

• Direct execution (bypassing pytest): imported shared.freshness and auto_recall._format_injection and exercised both the freshness and bare-memory cases — output matches the tests above.

• Lint: ruff check + ruff format --check clean on all four files.

• All existing tests pass — deferred to CI (suite not runnable in authoring env).

• New tests added for new behavior.

• Mutation survival check: dropping any of the three fields, rendering the suffix unconditionally (would break bare-memory sites), or not counting the suffix toward the injection budget (would break the receipt-parity invariant) are all caught.

• Manual verification of the injected-context output change (shown above).

Audit notes

• Engineering review: self-review only — verified layer direction (shared/ imports stdlib only), budget/parity invariant preserved (suffix counts toward _MAX_INJECTION_CHARS, so the receipt still mirrors exactly what is printed), and no behavior change for memories lacking the fields. No multi-agent audit cycle was run in this environment.
• Genius review: not run here.
• Outstanding deferred findings: parallel formatters (session_start, recall_helpers) still bare — follow-up under cdeust/fleet-watch#110.

Coding-standards compliance

• §2.2 Layer dependency direction preserved (shared/freshness.py imports stdlib only).
• §3.2 No untyped-boundary any.
• §4.1 No file > 500 lines (freshness.py is 81).
• §4.2 No function > 50 lines.
• §4.4 No function with > 4 parameters.
• §7 Local reasoning preserved.
• §8 Numeric constants annotated — the time-unit boundaries carry a # source: note (calendar/SI definitions; 30-day/365-day display convention).
• §9 No dead code / untracked TODOs.

Breaking changes

None. Memories without created_at/source_attribution/is_stale render exactly as before; _format_injection gains an optional now parameter (defaults to wall clock) used only to make tests deterministic.

Screenshots / logs

Injected block for a stale memory:

**Cortex context:**
- PostgreSQL is the default store (decision)  ·  3mo ago  ·  src=verified  ·  ⚠stale

Reviewer checklist

• CHANGELOG.md updated — not touched; flagging for reviewer preference.
• No secrets / credentials / PII in the diff.
• CI passes on the latest commit — pending.

---

Generated by Claude Code

[cdeust]

Scope update: this now covers both context-injection surfaces, not just the primary recall path.

• 487e033 — refactor to keep _format_injection under the method-size gate (CI caught it; fixed).
• 688fc11 — extends the same shared/freshness.py stamping to the SessionStart banner (_build_context): anchors, team decisions, and hot memories now carry age · provenance grade · stale marker, on both the PG fetches and the SQLite path (_partition_banner_rows).

So the injection-side of fleet-watch#110 is now complete here. Remaining #110 seams (post-commit re-verify / content-hashing of file-derived memories so is_stale actually fires on source change, and provenance-first seeding) are separate follow-up PRs — the display shipped here is only as useful as the staleness flag being set, which is the next change.

Verified locally: ruff + the craftsmanship gate clean; a stale anchor renders · 4mo ago · src=verified · ⚠stale; memories without the fields render unchanged. Full pytest runs in CI.

---

Generated by Claude Code