Make entries.updated nullable — NULL on insert, set only on update

[cmeans]

Summary

• entries.updated is now NULL on insert and only set when an entry is actually updated — same semantic fix applied to users.updated in PR Add JWT auth middleware, RLS policies, and CLI commands #91
• All sort and filter queries use COALESCE(updated, created) so never-updated entries sort/filter by creation time
• Alembic migration backfills NULL where updated = created (entries that were never truly updated)

QA

Prerequisites

• pip install -e ".[dev]"
• Deploy to test instance on alternate port (AWARENESS_PORT=8421)

Manual tests (via MCP tools)

1. • New entry has null updated

   remember(source="test", tags=["qa"], description="nullable test")
   

   Then:

   get_knowledge(tags=["qa"], hint="nullable test", limit=1)
   

   Expected: entry returned with "updated": null

2. • Updated entry gets updated timestamp
     Using the entry ID from step 1:

   update_entry(entry_id="<id>", description="nullable test — edited")
   

   Expected: response includes "updated": "<timestamp>", not null

3. • Verify updated entry shows timestamp in knowledge query

   get_knowledge(tags=["qa"], hint="nullable test", limit=1)
   

   Expected: entry now has "updated": "<timestamp>" (non-null)

4. • Status entries work correctly (staleness detection)

   report_status(source="qa-test", tags=["qa"], data={"description": "test status", "ttl_sec": 5})
   

   Wait 10 seconds, then:

   get_briefing()
   

   Expected: briefing shows qa-test as stale with a last_report timestamp

5. • Since filter includes never-updated entries

   get_knowledge(tags=["qa"], since="2020-01-01T00:00:00Z", limit=5)
   

   Expected: entries from steps 1-3 appear (COALESCE ensures never-updated entries aren't excluded)

6. • Sort order correct for mixed updated/null entries
     Create a second entry:

   remember(source="test", tags=["qa"], description="second entry")
   

   Then:

   get_knowledge(tags=["qa"], limit=5)
   

   Expected: most recently created/updated entries appear first; never-updated entries sort by created time

7. • Cleanup

   delete_entry(entry_id="<id1>")
   delete_entry(entry_id="<id2>")
   

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Review — PR #92: Make entries.updated nullable

Summary

Clean semantic fix — `entries.updated` is now NULL on insert, set only on actual updates. Mirrors the `users.updated` fix from PR #91. All queries use `COALESCE(updated, created)` for sort/filter consistency.

Code Review

Migration (`h3c4d5e6f7g8`)

• Drops NOT NULL on `entries.updated`
• Backfills: `UPDATE entries SET updated = NULL WHERE updated = created` — correct for existing data
• Clean downgrade: restores from COALESCE + re-adds NOT NULL
• Revision chain correct: depends on `g2b3c4d5e6f7`

Schema (`schema.py`)

• `updated: datetime | None = None` — nullable with default
• `to_dict()` and `to_list_dict()`: `to_iso(self.updated) if self.updated else None`
• `from_dict()`: uses `ensure_dt_optional` for updated
• `age_sec`: `ref = self.updated or self.created` — correct fallback

DDL (`create_tables.sql`)

• `updated TIMESTAMPTZ` — nullable, no default

PostgresStore

• Default ORDER BY: `COALESCE(updated, created) DESC` in `_query_entries()`
• All `since`/`until` filters: `COALESCE(updated, created) >= %s`
• `updated=now` removed from all Entry constructors (upsert_status, upsert_alert, upsert_preference)
• SQL files updated: `get_entries_without_embeddings.sql`, `get_stale_embeddings.sql`

Tools (`tools.py`)

• `updated=now` removed from learn_pattern, remember, suppress_alert, add_context, remind
• `update_entry` response: `to_iso(result.updated) if result.updated else None`

Collator/Prompts

• `last_report`: `to_iso(status.updated or status.created)` — correct fallback for display

Server

• `_do_embed` dummy Entry: `updated=None`

Observations

1. `seed-demo.sql` still explicitly sets `updated` in INSERT column lists. New seed entries will have `updated = created` rather than NULL. Not a blocker — seed data predates this change — but could be aligned in a follow-up.

CI Gate Check

Check	Conclusion
lint	✅ SUCCESS
typecheck	✅ SUCCESS
test (3.10)	✅ SUCCESS
test (3.11)	✅ SUCCESS
test (3.12)	✅ SUCCESS
codecov/patch	✅ SUCCESS

Zero non-SUCCESS/non-SKIPPED checks.

Test Results

Check	Result
pytest (455 tests)	✅ 455/455 pass
ruff (src/, alembic/)	✅ Clean
mypy	✅ Clean
CI	✅ All green
Manual #1: New entry has null updated	✅ SQL: `updated IS NULL = true`
Manual #2: update_entry sets timestamp	✅ `updated` set to non-null after update, MCP returns timestamp
Manual #3: Updated entry shows in knowledge	✅ `has_updated = true`, description changed
Manual #4: Status staleness detection	✅ `age_sec` uses `COALESCE(updated, created)`, TTL-expired entry detected
Manual #5: Since filter with COALESCE	✅ Never-updated entries included in since-filtered queries
Manual #6: Sort order with mixed NULL/non-NULL	✅ `COALESCE(updated, created) DESC` sorts correctly

Verdict

Zero findings (1 observation about seed-demo.sql). All CI green. All manual tests pass. Ready for QA Signoff.

[cmeans]

Adding Ready for QA Signoff — entries.updated nullable change verified across migration, schema, DDL, all queries (COALESCE), tools, collator, prompts. CI fully green (codecov SUCCESS), 455/455 pytest, 6/6 manual tests. One observation: seed-demo.sql still sets updated explicitly.

[cmeans]

LGTM