Incomex AI Portal
KB-494B rev 2

23-P3D4C0 — New Piece + Document Batch Notification Design Prompt (rev2)

9 min read Revision 2
p3d4c0promptnotificationbirthbatchdebouncedesignpg-nativehot-pathrev2

23-P3D4C0 — New Piece + Document Batch Notification Design Prompt (rev2)

Date: 2026-05-08 Status: PROMPT rev2 — chờ GPT/User final review. CHƯA dispatch. Report: knowledge/dev/laws/dieu44-trien-khai/reports/23-p3d4c0-new-piece-document-batch-notification-design-report.md Scope: Design/inventory only. NO implementation. NO mutation. Rev1→Rev2: Hot path O(1), staging+pg_cron preferred, 3-layer separation, stable grouping key, batch threshold, performance budget, P3D2 trigger review, hook options, Directus pause.

Hard Boundaries

  • ❌ KHÔNG implement — design only
  • ❌ KHÔNG mutate PG
  • ❌ KHÔNG mutate Directus config
  • ❌ KHÔNG code Nuxt
  • ❌ KHÔNG start Hermes
  • ❌ KHÔNG dispatch Codex
  • ❌ KHÔNG viết tool mới — PG-native only
  • ❌ KHÔNG external scheduler — pg_cron only
  • ❌ KHÔNG heavy trigger logic (no COUNT, JOIN, aggregation, rollup on write path)
  • ❌ KHÔNG tight polling loops
  • ❌ KHÔNG per-event immediate aggregation
  • ❌ KHÔNG sync notification computation trên AI interaction path
  • ❌ KHÔNG claim board complete nếu birth/batch gap chưa resolved/disclosed
  • ✅ KB document create only
  • ✅ PG read-only inventory

Kiến trúc bắt buộc — Hot Path O(1)

Hot path rule: Triggers/functions trên IU creation/edit/comment CHỈ ĐƯỢC làm O(1) append vào staging/outbox nhẹ.

CẤM trên hot path:

  • Aggregation (COUNT, SUM, GROUP BY)
  • Batch detection
  • JOIN
  • JSON build nặng
  • latest_readers calculation
  • Rollup

Derived work (grouping, debounce, rollup, count, latest_readers) → làm sau bởi pg_cron worker.

Architecture mặc định:

AI ghi miếng → PG (fast)
  → trigger O(1) append vào iu_notification_pending (staging)
  → KHÔNG tính toán gì thêm
  
pg_cron worker (mỗi 90-120s)
  → đọc pending
  → gom batch theo stable key
  → tạo durable events trong iu_notification_event
  → xóa/mark processed pending
  
Directus/Nuxt → đọc iu_notification_event + view

Nếu Agent đề xuất kiến trúc khác → phải justify rõ tại sao staging+pg_cron không phù hợp.

LISTEN/NOTIFY: optional signal, KHÔNG phải main design Phase 1.

3 Lớp Dữ Liệu (agent phải tách rõ)

Lớp Table Vai trò Computation
Staging iu_notification_pending (hoặc equivalent) Append-only, O(1), hot path KHÔNG
Durable events iu_notification_event (đã có) Processed notifications pg_cron worker tạo
Directus view v_iu_notification_board (future) Read projection View/query time

Design phải ghi rõ computation nào nằm ở lớp nào. KHÔNG trộn.

Grouping — Stable Key Required

Rule: No grouping by timing alone. Debounce 90-120s không đủ kết luận "cùng tài liệu."

Grouping PHẢI dùng stable key nếu có:

  • source_document_id / source_document_ref
  • import_batch_id / import_batch_ref
  • parent_document_id
  • canonical_address root/prefix
  • ingestion job id
  • explicit batch token

Nếu chưa có key:

  • Recommend thêm minimal source_document_ref hoặc import_batch_ref
  • Hoặc piece-level events with gap disclosed
  • Hoặc defer batch rollup

Batch threshold (configurable):

  • count >= threshold (default >=2) cùng stable key → document-level rollup event
  • count = 1 → piece-level event
  • 1 miếng thêm sau vào tài liệu cũ → piece-level event
  • Không hardcode threshold

Step 0: Mandatory Pre-Read

  1. knowledge/dev/laws/constitution.md
  2. knowledge/dev/laws/law-07-assembly-first.md
  3. knowledge/dev/ssot/data-connection-law.md
  4. knowledge/dev/laws/dieu44-trien-khai/design/23-p3d4b-directus-dot-notification-readonly-exposure-package-review.md
  5. knowledge/dev/laws/dieu44-trien-khai/reports/23-p3d2-notification-triggers-report.md — review trigger hot-path
  6. knowledge/dev/laws/dieu44-trien-khai/context-packs/iu-agent-front-door-context.md

Step 1: 8 Design Questions (PG read-only inventory)

Q1. Birth identification

Bảng/cột nào xác định new IU birth? (information_unit, unit_version.version_seq=1, birth triggers, created_by, source metadata)

Q2. Source document / import batch

Có identifier nào? (canonical_address convention, parent/child, source_ref, batch_id, import_job_id, publication tables). Nếu NOT_FOUND → recommend minimal addition.

Q3. Phân biệt 3 scenarios

  • 1 miếng mới thêm vào tài liệu cũ
  • Nhiều miếng mới cùng lúc từ 1 tài liệu mới
  • Nhiều miếng mới không liên quan riêng lẻ

Q4. Event taxonomy

Candidate: new_piece_created, document_sliced_created/document_imported, comment_added, draft_created, version_applied.

Q5. Debounce mechanism (PG-native)

Đánh giá: pg_cron + staging table (preferred), LISTEN/NOTIFY (optional), advisory locks. Debounce window configurable (PG config table), default 90-120s.

Q6. Anti-spam / grouping

Rule: N miếng + stable key → 1 document notification. 1 miếng đơn → 1 piece notification. Creator implicit self-read mọi level.

Q7. New piece hook — chọn ít xâm lấn nhất

Options (KHÔNG nhảy thẳng birth trigger):

  • Hook vào fn_iu_save / creation function
  • Trigger on information_unit INSERT (nếu nhẹ, O(1))
  • Trigger on unit_version WHERE version_seq=1
  • Pending/outbox append từ creation gateway Chọn hook nhanh nhất, ít xâm lấn nhất, đúng luật.

Q8. P3D2 trigger hot-path review

Inventory P3D2 triggers hiện tại: trg_aa_iu_notif_comment, trg_aa_iu_notif_draft, trg_aa_iu_notif_version.

  • Có đang làm heavy work không? (JOIN, COUNT, aggregation)
  • Nếu heavy → recommend later refactor, KHÔNG mutate trong P3D4C0
  • Report: p3d2_trigger_hot_path_review, p3d2_trigger_heavy_work_found

Step 2: Output — Design Note

Path: knowledge/dev/laws/dieu44-trien-khai/design/23-p3d4c0-new-piece-document-batch-notification-design.md

A. PG inventory evidence (8 questions)

B. Hot path architecture (3 layers)

C. Debounce + grouping mechanism

D. Event taxonomy proposal

E. Hook recommendation

F. P3D2 trigger review

G. Future observability design (pending count, processed count, duration, errors, quiet period, rollback)

H. Recommendation — chọn 1:

Option Mô tả
EXTEND_RUNTIME_BEFORE_DIRECTUS_EXPOSURE Stable key có hoặc minimal addition an toàn
DESIGN_STAGING_OUTBOX_FIRST Birth/batch cần pending table + worker design trước
EXPOSE_CURRENT_RUNTIME_WITH_GAP_DISCLOSED User chấp nhận thiếu new-piece visibility
DEFER_BIRTH_BATCH_UNTIL_SOURCE_SCHEMA_READY Source schema chưa có, defer

I. Directus exposure status

p3d4c_directus_exposure_status=PAUSE_UNTIL_BIRTH_BATCH_DESIGN|ALLOW_GAP_AWARE_CURRENT_RUNTIME|DEFER

Verification

phase_status=PASS|FAIL
birth_notification_gap=CONFIRMED|NOT_CONFIRMED
batch_grouping_required=true
source_document_identifier=FOUND|NOT_FOUND|UNCLEAR
import_batch_identifier=FOUND|NOT_FOUND|UNCLEAR
debounce_mechanism_recommended=PG_CRON_STAGING|LISTEN_NOTIFY|OTHER
debounce_window_configurable=true
batch_piece_threshold_configurable=true
recommended_event_taxonomy=<list>
recommended_grouping_strategy=PIECE_ONLY|DOCUMENT_ROLLUP|HYBRID|DEFERRED
recommended_hook=FN_IU_SAVE|IU_INSERT_TRIGGER|UV_SEQ1_TRIGGER|CREATION_GATEWAY|OTHER
creator_implicit_self_read_applies=true
hot_path_operations=<description>
hot_path_joins=0
hot_path_aggregations=0
hot_path_expected_complexity=O(1)
derived_processing_window_seconds=90_120
expected_ai_pg_latency_impact=LOW
p3d2_trigger_hot_path_review=PASS|FAIL|LIMITED
p3d2_trigger_heavy_work_found=true|false
p3d4c_directus_exposure_status=PAUSE_UNTIL_BIRTH_BATCH_DESIGN|ALLOW_GAP_AWARE|DEFER
no_pg_mutation=true
no_directus_mutation=true
no_nuxt_code=true
no_new_tool_created=true
no_external_scheduler=true
no_heavy_trigger_logic=true
next_required_pack=<based on recommendation>

Key Principles

  1. Hot path O(1). Trigger chỉ append nhẹ. KHÔNG tính toán trên write path.
  2. Staging → Worker → Durable. 3 lớp tách rõ.
  3. Debounce 90-120s. pg_cron, configurable, PG-native.
  4. Stable key, not timing. Grouping bằng source ID, không bằng thời gian.
  5. 1 tài liệu mới = 1 notification. Batch threshold configurable.
  6. Creator implicit self-read. Mọi level.
  7. PG-native only. Không tool mới, không external scheduler.
  8. Design only. P3D4C0 không implement.

P3D4C0 rev2 | Design only | Hot path O(1) | Staging+debounce | CHƯA dispatch | Chờ GPT/User final review

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3d4c0-new-piece-document-batch-notification-design-prompt.md