P3D Pack 1 Phase 5C1 — Species/Mapping + QT-001 Backfill — rev5 DISPATCH CANDIDATE

Date: 2026-05-11 | rev5: 2026-05-11 (add missing status/depth/parent_ref concepts) Author: Opus 4.7 Status: rev5 DISPATCH CANDIDATE — NOT YET APPROVED until GPT final review + User GO Probe: reports/p3d-pack1-phase5c1a-species-schema-parent-probe-report.md GPT species lock: reviews/gpt-review-p3d-pack1-phase5c1a-probe-pass-lock-species-identity-2026-05-11.md GPT rev4 directive: directives/gpt-directive-opus-p3d-pack1-phase5c1-rev4-final-hardening-2026-05-11.md Scope: QT-005 species + mapping + QT-001 backfill only Out of scope: TAC migration, IU/UV rows, DIEU-35, universal_edges, unit_version mapping, DDL, function patch DB: VPS PostgreSQL (postgres container, db=directus, schema=public)

0. SCOPE BLOCK (GPT-LOCKED species identity)

target_collection   = 'information_unit'
species_code        = 'information_unit_atom'
entity_code         = 'SPE-IUA'
display_name        = 'Đơn vị Thông tin'
composition_level   = 'atom'
management_mode     = 'observed'          # MUST override DB default 'governed'
dot_origin          = 'DOT:QT-005-P3D-PACK1-5C1'
prefix              = 'IUA'
description         = 'Loài cho collection information_unit dưới chiến lược D3 hybrid; IU là atomic text unit, hierarchy lưu metadata/edges hậu pilot.'

mapping_collection  = 'information_unit'
mapping_species     = 'information_unit_atom'

write_table_species = 'entity_species'
write_table_mapping = 'species_collection_map'
write_table_birth   = 'birth_registry'
read_table_colreg   = 'collection_registry'

Agent reads ALL values from §0. Agent MUST NOT invent, modify, or substitute any value.

1. ERROR HANDLING POLICY

ON_ERROR_STOP = 1
- Any failed gate, assertion, or unexpected result → immediate ROLLBACK + report.
- No retry with modified SQL.
- No improvisation.
- No continue after failed gate.
- Report must include: failed_gate_id, expected, actual, query used.
- After ROLLBACK: verify pre-state restored (§8.C).

1B. MANDATORY EXECUTION LOG

Before any DB action, open VPS log:

log_path = /opt/incomex/logs/p3d-pack1-phase5c1-<timestamp>.log

Log captures (append as execution proceeds):

[INIT]       timestamp, prompt rev5, agent version
[INTROSPECT] schema results summary
[RESOLVE]    concept resolution results
[PRECOMMIT]  backfill target capture (entity_codes, birth_ids, count)
[TXN_START]  BEGIN timestamp
[LOCK]       advisory lock acquired (true/false)
[INSERT_SP]  captured_species_id
[INSERT_MAP] captured_mapping_id
[BACKFILL]   affected_count, birth_id list
[TXN_END]    COMMIT or ROLLBACK + reason
[KB_UPLOAD]  report upload status (success/failed)
[KEYS]       committed_rollback_keys

If VPS log cannot be opened → ABORT before any DB action.

Rollback reference fallback

KB success + VPS log has keys  → rollback_reference = 'both'
KB failed  + VPS log has keys  → rollback_reference = 'vps_log' (PARTIAL_LOGGED)
KB success + VPS log missing   → rollback_reference = 'kb'
Neither has keys               → CRITICAL FAILURE → immediate GPT/User alert

2. PRE-TRANSACTION PHASE (read-only)

2.1 Schema introspection (4 tables)

-- entity_species
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema='public' AND table_name='entity_species'
ORDER BY ordinal_position;

-- species_collection_map
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema='public' AND table_name='species_collection_map'
ORDER BY ordinal_position;

-- birth_registry
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema='public' AND table_name='birth_registry'
ORDER BY ordinal_position;

-- collection_registry (for G0-4/G0-5)
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema='public' AND table_name='collection_registry'
ORDER BY ordinal_position;

2.2 Concept resolution

Verify these columns exist live (from probe — re-confirm):

Table	Concept	Expected column
entity_species	PK	id
entity_species	identifier	species_code
entity_species	entity_code	code
entity_species	display	display_name
entity_species	composition	composition_level
entity_species	management	management_mode
entity_species	dot_origin	_dot_origin
entity_species	prefix	prefix
entity_species	description	description
entity_species	status	status
entity_species	depth	depth
entity_species	parent_ref	parent_id
species_collection_map	PK	id
species_collection_map	collection_key	collection_name
species_collection_map	species_ref	species_code
species_collection_map	primary_flag	is_primary
birth_registry	PK	id
birth_registry	collection_key	collection_name
birth_registry	species_ref	species_code
birth_registry	composition	composition_level
birth_registry	entity_key	entity_code
collection_registry	collection_key	collection_name
collection_registry	governance_role	governance_role

If any expected column absent → ABORT. Report discrepancy.

2.3 Fill policy validation

For each NOT NULL column without default in entity_species:

Must be in §4.2 INSERT column set or have known safe default.
Unexpected NOT NULL column → ABORT.

2.4 Resolve expected defaults from introspection

status_default     = column_default for resolved <status col>       (probe: 'active')
depth_default      = column_default for resolved <depth col>        (probe: 1)
mgmt_mode_default  = column_default for resolved <management col>   (probe: 'governed')
is_primary_default = column_default for resolved <primary_flag col> (probe: true)

Store for §4 verification. Do NOT hardcode — use introspected values.

2.5 Pre-transaction checks (informational — repeated inside transaction)

G0-1  'SPE-IUA' does NOT exist in entity_species.<entity_code col>
G0-2  'information_unit_atom' does NOT exist in entity_species.<identifier col>
G0-3  0 rows in species_collection_map WHERE <collection_key col> = 'information_unit'
G0-4  'information_unit' exists in collection_registry.<collection_key col>
G0-5  collection_registry.<governance_role col> = 'observed' WHERE <collection_key col> = 'information_unit'

All column references use §2.2 resolved names. If any G0 fails → ABORT.

3. BACKFILL TARGET CAPTURE (read-only — before transaction)

3.1 SELECT targets

SELECT <entity_key col>, <PK col> AS birth_id
FROM birth_registry
WHERE <collection_key col> = 'information_unit'
  AND <species_ref col> IS NULL
ORDER BY <PK col>;

→ precommit_target_capture = [{entity_code, birth_id}, ...]
→ precommit_target_count = count

3.2 Persist precommit capture

Write to KB + VPS log BEFORE transaction.
NOTE: PRECOMMIT — diagnostic only if rolled back.

4. TRANSACTION

BEGIN;

4.0 Advisory lock (non-blocking)

SELECT pg_try_advisory_xact_lock(hashtext('p3d_pack1_phase5c1_information_unit_species_mapping_backfill')) AS lock_acquired;

If lock_acquired = false:

ROLLBACK;
status = BLOCKED_LOCK_BUSY
→ No retry. No wait. Report. Return to GPT/User.

4.1 Stale-sensitive rechecks INSIDE transaction

T-G1  SELECT count(*) FROM entity_species WHERE <entity_code col> = 'SPE-IUA';           → ASSERT = 0
T-G2  SELECT count(*) FROM entity_species WHERE <identifier col> = 'information_unit_atom'; → ASSERT = 0
T-G3  SELECT count(*) FROM species_collection_map WHERE <collection_key col> = 'information_unit'; → ASSERT = 0
T-G4  SELECT count(*) FROM birth_registry WHERE <collection_key col> = 'information_unit' AND <species_ref col> IS NULL;
      → ASSERT = precommit_target_count (if different → ROLLBACK, targets changed)

4.2 INSERT species

INSERT INTO entity_species (
  <entity_code col>, <identifier col>, <display col>, <composition col>,
  <management col>, <dot_origin col>, <prefix col>, <description col>
)
VALUES (
  'SPE-IUA', 'information_unit_atom', 'Đơn vị Thông tin', 'atom',
  'observed', 'DOT:QT-005-P3D-PACK1-5C1', 'IUA',
  'Loài cho collection information_unit dưới chiến lược D3 hybrid; IU là atomic text unit, hierarchy lưu metadata/edges hậu pilot.'
)
RETURNING <PK col> AS captured_species_id;

4.3 Verify species

SELECT <identifier col>, <entity_code col>, <management col>, <composition col>,
       <status col>, <depth col>, <parent_ref col>
FROM entity_species WHERE <PK col> = captured_species_id;

ASSERT <identifier col>  = 'information_unit_atom'
ASSERT <entity_code col> = 'SPE-IUA'
ASSERT <management col>  = 'observed'        ← CRITICAL: must NOT equal mgmt_mode_default
ASSERT <composition col> = 'atom'
ASSERT <status col>      = status_default    (from §2.4 introspection)
ASSERT <depth col>       = depth_default     (from §2.4 introspection)
ASSERT <parent_ref col>  IS NULL

4.4 INSERT mapping

INSERT INTO species_collection_map (<species_ref col>, <collection_key col>)
VALUES ('information_unit_atom', 'information_unit')
RETURNING <PK col> AS captured_mapping_id;

4.5 Verify mapping

ASSERT <species_ref col>    = 'information_unit_atom'
ASSERT <collection_key col> = 'information_unit'
ASSERT <primary_flag col>   = is_primary_default    (from §2.4)

4.6 UPDATE backfill (captured keys ONLY)

UPDATE birth_registry
SET <species_ref col> = 'information_unit_atom',
    <composition col> = 'atom'
WHERE <PK col> = ANY (<precommit birth_id list>);

→ affected_count = ROW_COUNT
→ ASSERT affected_count = precommit_target_count

4.7 Verify backfill

SELECT <entity_key col>, <species_ref col>, <composition col>
FROM birth_registry WHERE <PK col> = ANY (<precommit birth_id list>);

→ ASSERT every row: species_ref = 'information_unit_atom', composition = 'atom'

4.8 Verify zero NULL remaining

SELECT count(*) FROM birth_registry
WHERE <collection_key col> = 'information_unit' AND <species_ref col> IS NULL;
→ ASSERT = 0

4.9 COMMIT

COMMIT;

5. POST-COMMIT: Persist committed rollback keys

committed_rollback_keys = {
  species_id:       captured_species_id,
  mapping_id:       captured_mapping_id,
  backfill_birth_ids: <precommit birth_id list>
}

Write to KB + VPS log.

6. POST-COMMIT: Final verification (read-only)

FV-1  entity_species WHERE <identifier col> = 'information_unit_atom'   → count = 1
FV-2  species_collection_map WHERE <collection_key col> = 'information_unit' AND <primary_flag col> = true → count = 1
FV-3  birth_registry WHERE <collection_key col> = 'information_unit' AND <species_ref col> IS NULL → count = 0
FV-4  birth_registry WHERE <collection_key col> = 'information_unit' AND <species_ref col> = 'information_unit_atom' → report count

If FV-1..3 fail → post-COMMIT rollback (§8.B).

7. REPORT

Save to: knowledge/dev/laws/dieu44-trien-khai/reports/p3d-pack1-phase5c1-species-mapping-backfill-report.md

phase5c1_status                       = PASS | PARTIAL | ROLLED_BACK | BLOCKED | BLOCKED_LOCK_BUSY
transaction_outcome                   = COMMITTED | ROLLED_BACK | NOT_STARTED
schema_introspection                  = PASS | FAIL
concept_resolution                    = PASS | FAIL
fill_policy_validation                = PASS | FAIL
pre_transaction_checks                = PASS | FAIL
in_transaction_checks                 = PASS | FAIL
advisory_lock_acquired                = true | false
advisory_lock_key                     = p3d_pack1_phase5c1_information_unit_species_mapping_backfill
step_species_created                  = COMMITTED | ROLLED_BACK | NOT_RUN
step_species_management_verified      = observed | governed_TRAP | NOT_CHECKED
step_mapping_seeded                   = COMMITTED | ROLLED_BACK | NOT_RUN
step_backfill_executed                = COMMITTED | ROLLED_BACK | NOT_RUN
precommit_target_count                = <live>
backfill_affected_count               = <live>
remaining_null_species                = 0 | <N>
captured_species_id                   = <id>
captured_mapping_id                   = <id>
captured_backfill_ids                 = <list>
committed_rollback_keys_persisted     = true | false
precommit_captures_persisted          = true | false
execution_log_path                    = <path>
execution_log_contains_committed_keys = true | false
kb_report_upload_status               = success | failed
rollback_reference_available          = both | kb | vps_log | none
no_iu_uv_rows_created                = true
no_tac_rows_modified                  = true
failed_gate_id                        = <gate id> | none
post_commit_verification              = PASS | FAIL
phase5c2_unblocked                    = true | false

8. ROLLBACK

8.A In-transaction

Failed gate inside §4 → ROLLBACK;. Pre-state restored.

8.B Post-COMMIT (FV failure or GPT/User reject)

BEGIN;
UPDATE birth_registry SET <species_ref col> = NULL, <composition col> = NULL
  WHERE <PK col> = ANY (<committed backfill_birth_ids>);
DELETE FROM species_collection_map WHERE <PK col> = <committed mapping_id>;
DELETE FROM entity_species WHERE <PK col> = <committed species_id>;
COMMIT;

8.C Post-rollback verification

PRV-1  entity_species WHERE <identifier col> = 'information_unit_atom' → count = 0
PRV-2  species_collection_map WHERE <collection_key col> = 'information_unit' → count = 0
PRV-3  birth_registry WHERE <collection_key col> = 'information_unit' AND <species_ref col> = 'information_unit_atom' → count = 0

8.D Capture persistence: KB + VPS log. No new DB table.

9. HARD BOUNDARIES

No TAC migration. No IU/UV row creation. No DIEU-35. No unit_version mapping. No DDL. No function/trigger patch. No nested Agent. No retry. No improvisation.

10. RÀNG BUỘC LUẬT

Điều 0-G, Điều 29, QT-001, QT-005, §0-AU, §FIX_GỐC