GPT Review — Pack 23 Long-term Text-as-Code Edit Model

Date: 2026-05-06
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Context: User clarified that Information Unit must support long-term text-as-code, multi-agent concurrent edits, parent/child slices, and Git-like review/merge workflow.

Verdict

The user is correct: Pack 23 must not be designed as a simple direct “edit current slice” function only.

The next design must use proven IT patterns:

• Git-style branch / patch / review / merge concepts;
• optimistic concurrency;
• immutable versions;
• explicit change proposals;
• reviewer/merge authority;
• parent-child units for process/workflow decomposition;
• canonical merge as the only operation that mutates current anchors.

Correct framing

Do not think of Pack 23 as only:

fn_iu_edit(address, new_body) updates current version.

Think of it as:

A canonical text-as-code edit workflow where multiple Agents can propose changes to the same Information Unit, each proposal becomes a candidate version/change-set, and a reviewer/merger chooses what becomes current.

Core model to design

Layer 1 — Immutable version store

unit_version remains append-only. New work creates new version candidates, not destructive overwrite.

Layer 2 — Change proposal / patch layer

A multi-agent edit should create a proposal, equivalent to a Git branch/PR:

• target IU;
• base version sequence/hash;
• proposed title/body;
• author/agent;
• reason;
• status: draft/proposed/reviewed/accepted/rejected/superseded/merged;
• diff/patch metadata if available.

This can later become a new table such as unit_change_proposal, or reuse existing structures if runtime schema already has something close. Do not invent DDL until inspection.

Layer 3 — Merge / publish operation

Only a canonical merge function updates the current anchor:

• validates base still matches current or performs conflict classification;
• inserts merged unit_version if accepted;
• updates IU anchor/current pointer;
• verifies invariants;
• returns merge result.

Layer 4 — Review workflow

A reviewer Agent can compare proposals, run lint/tests, request changes, then merge one or synthesize a final merged version.

Layer 5 — Parent/child slice hierarchy

Miếng mẹ / miếng con must be part of the schema/design:

• parent document/process IU;
• child step/section IU;
• ordering/reordering;
• contains/belongs_to edges;
• edit of child should not rewrite whole parent;
• parent render assembles children.

Naming recommendation

Avoid calling the first operation only fn_iu_edit if that encourages direct current mutation.

Design should compare these functions:

1. fn_iu_propose_edit(...) — create candidate change/proposal.
2. fn_iu_merge_edit(...) — accept proposal and update current anchor.
3. fn_iu_edit_plan(...) — dry-run for proposed edit / conflict check.
4. Optional later: fn_iu_revert(...), fn_iu_compare(...), fn_iu_split(...), fn_iu_move(...).

A direct fn_iu_edit(...) may exist as a convenience wrapper, but it should probably mean “propose + merge only when no conflict and policy allows,” not bypass review semantics.

Immediate correction to prior Pack 23 directive

The previous directive was too narrow when it framed Pack 23 as fn_iu_edit body/title edit only.

Revised Pack 23-P1 should be a design note for:

IU Text-as-Code Edit / Proposal / Merge Model

not simply a function design.

Directive to Opus

Create a new design note or revise the pending design path:

knowledge/dev/laws/dieu44-trien-khai/design/23-p1-iu-text-as-code-edit-merge-design.md

Do not implement runtime yet.

Required structure

§1. Text-as-code principles to reuse from industry

Cover:

• immutable commit/version history;
• branch/proposal model;
• pull request/review/merge;
• optimistic concurrency;
• diff/patch;
• merge conflict detection;
• revert;
• CI/lint/test gates;
• ownership/approval;
• release/build/render.

§2. Current Incomex primitives already available

Map to current system:

• information_unit;
• unit_version;
• fn_iu_create / fn_iu_create_plan;
• gateway guard;
• canonical address;
• birth registry;
• universal_edges or equivalent;
• dot_config policy keys;
• review/report workflow.

§3. Missing primitives for multi-agent edit

At minimum:

• change proposal / branch object;
• diff/patch metadata;
• merge function;
• conflict detection;
• review status;
• parent-child edge/order model;
• test/lint linkage;
• revert or rollback operation.

§4. Parent/child IU model

Design how parent/child slices work:

• document/process parent;
• section/step child;
• ordering;
• contains/belongs_to edges;
• render assembly;
• child edit without parent rewrite;
• parent version policy when child changes.

§5. Multi-agent concurrent workflow

Example scenario:

• 3 Agents propose edits to same IU from same base version;
• each creates proposal/candidate version;
• reviewer Agent compares diffs;
• one proposal accepted, or reviewer synthesizes final merge;
• losers become rejected/superseded;
• history preserved.

§6. Function set options

Compare:

A. Direct fn_iu_edit only.
B. fn_iu_propose_edit + fn_iu_merge_edit.
C. Proposal table + version candidates + merge.
D. External Git-like engine with PG as canonical state.

Recommend the most standard/minimal path.

Preliminary GPT recommendation: B/C hybrid — PG-native proposal/merge model, minimal first.

§7. Gateway marker strategy

Revisit marker design:

• create function marker;
• propose function marker;
• merge function marker;
• allow-list or generic canonical writer marker.

Recommend no lying marker values. Prefer allow-list or generic marker, designed explicitly.

§8. Schema evidence needed before implementation

List read-only inspection needs:

• current columns and constraints;
• whether a proposal/change table already exists;
• edge table capabilities for parent-child;
• version_seq constraints;
• content_hash strategy;
• audit fields;
• permission/guard behavior.

§9. Minimal production slice workflow

Define minimum usable v1:

• create IU;
• propose edit;
• review proposal;
• merge proposal;
• read/render current;
• inspect history;
• reject/supersede losing proposals.

§10. What not to do yet

Do not implement:

• full three-way merge engine;
• vector outbox;
• Directus UI;
• role separation;
• detector;
• package/release builder;
• semantic lint suite.

Design hooks for them, but defer implementation.

Hard boundaries

• No runtime mutation.
• No DDL/DML.
• No function/trigger changes.
• No vector mutation.
• No cleanup.
• No Pack 2C.

Expected Opus response

Opus should create the design note and stop for GPT/User review.

Do not write execution prompt yet.

Summary

The correct next step is not a simple edit function. It is a minimal Git-like proposal/merge model for Information Units. This lets multiple Agents work concurrently without overwriting each other and aligns Incomex with proven IT text-as-code patterns.