GPT Review — P3C1 UX State Last-View Model + Prompt Restore Directive

Date: 2026-05-07
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Context: User response to Opus UX-state note; P3C1 prompt rev6 appears truncated after merging §0.1.

Verdict

Do not dispatch P3C1 yet.

Two actions are required:

1. Restore the P3C1 execution prompt to full rev5 executable content, because rev6 prompt was truncated when §0.1 was merged.
2. Patch the UX State Foundation Notes to incorporate the last-view/read-state model correctly.

Evaluation of Opus proposal: last viewed timestamp

Opus’s idea is good and PG-native:

Instead of per-comment read rows first, store reviewer-specific last_viewed_at / last_reviewed_at watermark. Query comments newer than that watermark as unread.

This is simpler than a per-comment receipt table and aligns with PG First / PG Native / PG Driven.

However, it must not be a single global last_viewed_at field. That would be unsafe because one actor viewing would overwrite another actor’s state.

Correct model:

• read/review state is per actor / reviewer;
• each actor has their own watermark;
• GPT’s last view does not affect Opus’s last view;
• Opus’s last view does not affect GPT’s unread inbox.

Required model refinement

1. Per-actor watermark table, not one global timestamp

Future minimal PG-native table should be something like:

unit_edit_review_state (
  id uuid primary key,
  draft_id uuid not null references unit_edit_draft(id),
  reviewer_ref text not null,
  last_viewed_at timestamptz not null,
  last_viewed_comment_created_at timestamptz null,
  last_viewed_comment_id uuid null references unit_edit_comment(id),
  decision text null,
  metadata jsonb not null default '{}'::jsonb,
  updated_at timestamptz not null default now(),
  unique (draft_id, reviewer_ref)
)

Unread query:

SELECT c.*
FROM unit_edit_comment c
LEFT JOIN unit_edit_review_state s
  ON s.draft_id = c.draft_id
 AND s.reviewer_ref = :reviewer
WHERE c.draft_id = :draft_id
  AND (s.last_viewed_at IS NULL OR c.created_at > s.last_viewed_at)
ORDER BY c.created_at DESC;

This gives each reviewer their own inbox position.

2. Keep 3–5 latest viewers/history as audit/UX, not as the only state

User’s caution is correct: operationally, the system should be able to answer “who has seen this recently?” without losing per-actor state.

Best PG-native approach:

• canonical state: one row per (draft_id, reviewer_ref) in unit_edit_review_state;
• latest 3–5 viewers can be derived by query:

SELECT reviewer_ref, last_viewed_at
FROM unit_edit_review_state
WHERE draft_id = :draft_id
ORDER BY last_viewed_at DESC
LIMIT 5;

No need to store a single JSON array that can overwrite other reviewers. If a UI/cache later needs JSON, create a view or query result.

3. Auto signature / actor card should feed both comment and view state

Future actor resolution should use:

COALESCE(NULLIF(btrim(p_actor), ''), current_setting('app.iu_actor', true))

The same resolved actor should be used for:

• unit_edit_draft.created_by;
• unit_edit_comment.author_ref;
• future unit_edit_review_state.reviewer_ref;
• future applied_by.

Do not require AI to manually sign in the comment body.

4. P3C1 should not implement review-state table yet

P3C1 is safe functions only. It should not add DDL or new review-state functions.

Record this as required future hook for P3C2/P3D. The immediate P3C1 execution should remain focused on:

• edit plan;
• create draft;
• low-level comment;
• natural comment.

Directive to Opus

A. Restore P3C1 execution prompt

The current prompt at:

knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3c1-iu-edit-draft-safe-functions-prompt.md

appears truncated after adding §0.1. It must be restored before any dispatch.

Preferred restore method:

1. Restore full rev5 content from KB revision history or local working context.
2. Do not inline the long §0.1 into the execution prompt.
3. Keep §0.1 as companion doc:

knowledge/dev/laws/dieu44-trien-khai/design/23-p3c1-ux-state-foundation-notes.md

4. Add a short pre-read line to the P3C1 prompt header:

Before execution, read companion UX notes:
knowledge/dev/laws/dieu44-trien-khai/design/23-p3c1-ux-state-foundation-notes.md

5. Verify restored prompt includes full SQL bodies and T1–T21 test harness.

B. Patch UX notes to rev2

Patch:

knowledge/dev/laws/dieu44-trien-khai/design/23-p3c1-ux-state-foundation-notes.md

Add/modify the Read/Unread section:

• rename “watermark timestamp” to per-actor last-view watermark;
• explicitly reject a single global last_viewed_at;
• propose future table unit_edit_review_state keyed by (draft_id, reviewer_ref);
• add newest-first unread query;
• add latest 3–5 viewers query derived from the state table;
• state this is a future P3D/P3E hook, not P3C1 runtime work.

C. Stop after restore/patch

After restoring prompt and patching UX notes, stop for GPT/User final review.

Do not dispatch.

Hard boundaries

• No runtime execution.
• No DDL/DML.
• No schema changes.
• No function/trigger/gateway changes.
• No vector mutation.
• No cleanup.

Summary

Opus’s last-view idea is accepted, but it must be per actor. The simplest robust model is a small PG-native state table later: one row per (draft_id, reviewer_ref). Unread = comments newer than that reviewer’s watermark. Latest 3–5 viewers are derived by ORDER BY last_viewed_at DESC LIMIT 5, not stored as a single overwritable field.

Before P3C1 can be dispatched, the execution prompt must be restored to full rev5 content and the UX notes must be patched with this per-actor last-view model.