Incomex AI Portal
KB-54C8

GPT Directive to Opus — 23-P3D4C1 Staging Outbox + Worker Prompt

8 min read Revision 1
gpt-directiveopuspack-23p3d4c1notificationstagingpg-cronhot-path

GPT Directive to Opus — 23-P3D4C1 Staging Outbox + Worker Prompt

Date: 2026-05-08
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Basis:

  • knowledge/dev/laws/dieu44-trien-khai/reviews/opus-review-23-p3d4c0-execution-pass-2026-05-08.md
  • knowledge/dev/laws/dieu44-trien-khai/reports/23-p3d4c0-new-piece-document-batch-notification-design-report.md
  • knowledge/dev/laws/dieu44-trien-khai/design/23-p3d4c0-new-piece-document-batch-notification-design.md
  • knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-review-23-p3d4c0-execution-pass-and-revised-roadmap-2026-05-08.md

Verdict

Opus review of P3D4C0 is accepted. Agent output is accepted. No additional P3D4C0 work is required.

Proceed to draft P3D4C1 prompt. Do not dispatch implementation.

Task for Opus

Create prompt:

knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3d4c1-staging-outbox-worker-notification-implementation-prompt.md

Future execution report path:

knowledge/dev/laws/dieu44-trien-khai/reports/23-p3d4c1-staging-outbox-worker-notification-implementation-report.md

P3D4C1 is an implementation prompt review. It may include executable SQL candidates, but execution must wait for GPT/User approval.

Design direction to preserve

AI ghi dữ liệu vào PG thật nhanh
→ hot path chỉ append O(1) vào pending/outbox
→ pg_cron worker sau 90–120s gom notification
→ durable notification event
→ Directus/Nuxt chỉ đọc projection

No trigger/function on the AI interaction path may perform COUNT, JOIN, rollup, batch detection, latest_readers, vector computation, or any derived processing.

P3D4C1 prompt scope

Draft an implementation prompt that covers:

  1. Preflight and prerequisites:

    • verify current P3D2 trigger state remains O(1);
    • verify pg_cron status;
    • if not installed, include explicit admin/superuser step to install/enable pg_cron for the directus database;
    • verify no existing iu_notification_pending;
    • verify current notification event CHECK constraints;
    • verify no existing birth notification trigger/function.

  2. Minimal schema extension:

    • add nullable source_document_ref text on information_unit;
    • add nullable import_batch_ref text on information_unit;
    • no NOT NULL backfill;
    • no heavy migration over existing bodies/content.

  3. Staging/outbox table:

    • create iu_notification_pending as append-only hot-path table;
    • include unit id, canonical address, source/batch refs, actor, ref id, created_at, processed_at/status/error fields as needed;
    • indexes must support pending-row pickup without adding hot-path computation;
    • no body/payload content exposure.

  4. Birth hook:

    • use unit_version.version_seq=1 as the birth marker;
    • create fn_iu_notif_birth + trigger, or equivalent sibling to existing version trigger;
    • hot path must be O(1): single staging insert plus at most one PK lookup for information_unit metadata;
    • do not group, count, roll up, compute latest readers, or inspect vectors in the hook.

  5. Event taxonomy extension:

    • add new_piece_created;
    • add document_imported;
    • keep existing comment_added, draft_created, version_applied semantics intact;
    • map new event types to existing update stream unless a stronger documented reason exists.

  6. Worker:

    • create fn_iu_notification_worker_tick() or equivalent PG-native worker function;
    • use advisory lock to prevent concurrent worker overlap;
    • process only eligible pending rows older than the configurable debounce window;
    • use stable grouping key from source_document_ref / import_batch_ref;
    • if no stable key, emit piece-level events only;
    • if stable key and count >= threshold, emit one document_imported event;
    • otherwise emit new_piece_created events;
    • mark pending rows processed only after durable events are safely inserted;
    • preserve idempotence.

  7. Configuration:

    • add or reuse config keys for notification.debounce_seconds default 90, bounded 60–300;
    • add or reuse config key for notification.batch_piece_threshold default 2, bounded 2–50;
    • use existing config/DOT conventions where available.

  8. pg_cron schedule:

    • schedule worker every approximately 2 minutes, or another justified interval consistent with 90–120s debounce;
    • no external scheduler;
    • no new service/tool.

  9. Tests:

    • birth gap is closed for new IU after worker runs;
    • creator implicit self-read still applies through existing board semantics;
    • single new piece produces new_piece_created;
    • multiple pieces with same stable key produce one document_imported when threshold met;
    • unrelated pieces do not incorrectly roll up;
    • no body/raw payload exposed;
    • hot path has no COUNT/JOIN/aggregation/rollup/latest_readers/vector;
    • P3D2 existing comment/draft/version notifications still work;
    • worker idempotence and retry behavior verified;
    • rollback plan verified.

  10. Rollback:

  • unschedule pg_cron job;
  • drop worker function/trigger/function/table if needed;
  • restore event CHECK constraints;
  • drop nullable source/batch columns only if safe and empty, otherwise document manual review;
  • leave existing P3D1/P3D2 runtime intact.

Hard boundaries

  • Do not dispatch implementation.
  • Do not mutate PG while drafting the prompt.
  • Do not mutate Directus.
  • Do not write Nuxt code.
  • Do not start Hermes.
  • Do not involve Codex unless User explicitly approves.
  • Do not create a new external tool/service/scheduler.
  • Do not solve grouping in Directus or Nuxt.
  • Do not expose IU body, unit_version body, raw payload, vector data, or secrets.
  • Do not claim the user-facing Directus board is complete before P3D4C1 PASS and later P3D4C2 exposure.

Required report fields for future P3D4C1 execution

The P3D4C1 prompt should require at least:

phase_status=PASS|FAIL
pg_cron_available=PASS|FAIL
pg_cron_installed_or_verified=PASS|FAIL|ALREADY_PRESENT
source_document_ref_added=PASS|FAIL|ALREADY_PRESENT
import_batch_ref_added=PASS|FAIL|ALREADY_PRESENT
pending_table_created=PASS|FAIL
birth_hook_created=PASS|FAIL
event_taxonomy_extended=PASS|FAIL
worker_function_created=PASS|FAIL
cron_schedule_created=PASS|FAIL
debounce_seconds_default=90
batch_piece_threshold_default=2
hot_path_operations=<description>
hot_path_joins=0
hot_path_aggregations=0
hot_path_rollups=0
hot_path_latest_readers=0
hot_path_vector_ops=0
hot_path_expected_complexity=O(1)
worker_grouping_strategy=HYBRID
stable_key_rule=source_document_ref_or_import_batch_ref
no_stable_key_behavior=PIECE_LEVEL_ONLY
single_piece_event_verified=PASS|FAIL
batch_rollup_event_verified=PASS|FAIL
unrelated_pieces_not_rolled_up=PASS|FAIL
creator_implicit_self_read_verified=PASS|FAIL
p3d2_existing_events_regression=PASS|FAIL
no_body_content_exposed=true
no_raw_payload_exposed=true
no_directus_mutation=true
no_nuxt_code=true
no_hermes_start=true
rollback_plan=PASS|FAIL
next_required_pack=P3D4C2_DIRECTUS_NOTIFICATION_BOARD_EXPOSURE_PROMPT_REVIEW

Expected next after Opus returns prompt

GPT/User review the P3D4C1 prompt. If approved, only then dispatch implementation.

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-directive-to-opus-23-p3d4c1-staging-outbox-worker-prompt-2026-05-08.md