Structive/AGENTS.md

Structive Codex Instructions

Mandatory skill usage

• Use $structive-development before editing Structive Core, Extension metadata, runtime access, synchronization, tests, CMake, install/export, or public documentation.
• Do not use Git commands or modify repository history.

Project purpose

Structive augments ordinary C++ structs with explicit property schema, intrinsic capability, attributes, constraints, optional managed synchronization, and a runtime adapter boundary. It does not replace the native object model.

Read docs/DESIGN.zh-CN.md (or docs/DESIGN.md) before changing architecture, and docs/CORE_GUIDE.zh-CN.md for the concrete API.

Non-negotiable architecture rules

• Enhance native C++ structs; do not introduce a second object model such as mandatory Property<T> storage wrappers.
• Registration is explicit. Members not present in the Schema are ordinary C++ state.
• Intrinsic readable/writable capability describes structure, not authorization or user permission.
• Raw C++ access and managed access are intentionally different contracts.
• Stored intrinsic read-only properties must remain outside mutable lock topology and keep the zero-lock managed-read fast path.
• Static facts should fail or optimize at compile time through constexpr, concepts, requires, and static_assert.
• Runtime access is for dynamic adapters, not the primary C++ business API.
• Runtime write is a copy-input boundary. Property::writable and Property::runtime_copy_writable have different meanings; move-only typed writes must remain possible when the accessor supports them.
• Validation remains explicit; do not hide validation, events, persistence, transactions, or rollback inside ordinary write().
• Synchronization protects mutable consistency only. It is not visibility, authorization, persistence, or transaction policy.
• Core has one Attribute protocol. New domains define Extension-owned categories instead of adding domain enums/branches to Core.
• Extension dependency direction is Extension -> Core; Core must never include or interpret Presentation/Adminive/other extension semantics.

Coding style

• C++ uses K&R brace style.
• Do not add meaningless blank lines.
• Keep comments adjacent to the code they explain.
• Preserve existing public function signatures and semantic meaning when modifying implementations.
• Replaced implementations are deleted; do not add compatibility wrappers unless the design explicitly requires them.
• Avoid repeated defensive checks in internal layers when the invariant is already established by the outer/schema boundary.
• CMake paths are relative to the owning CMake file through CMAKE_CURRENT_LIST_DIR; do not build paths from a parent project's source directory.
• Do not introduce random build/output path names.
• If PowerShell is needed, use PowerShell 7 through pwsh.

Core versus Extension ownership

Core owns:

Property identity/key
Accessor/intrinsic capability
Object_Schema / Type_Descriptor
Attribute protocol
Constraint / explicit validation helpers
Synchronization plan and resolved lock topology
Property_Object managed typed access
Dynamic runtime structural access

Extensions own domain interpretation such as presentation labels, descriptions, groups, order, persistence hints, RPC names, or documentation metadata.

Do not move Adminive concepts such as editable, Form, Collection, AMIS, HTTP, CRUD, or Resource_Transaction into Structive.

Tests and verification

• Positive runtime/compile-time behavior belongs in Core/Extension tests.
• A rule whose contract is “this must not compile” belongs in the compile-fail matrix rather than a runtime test.
• Every public header must independently compile.
• Changes to install/export behavior require the standalone install consumer.
• Synchronization changes require focused concurrency tests and TSan when available.
• Run Debug and Release tests for substantive Core changes because many guarantees are compile-time/template-sensitive.
• Do not claim a sanitizer/compiler matrix passed unless it was actually executed.

Standalone commands from the Structive directory:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DSTRUCTIVE_BUILD_TESTS=ON -DSTRUCTIVE_INSTALL=ON
cmake --build build
ctest --test-dir build --output-on-failure

When Structive is edited inside Adminive, also run the relevant Adminive tests because Adminive is an important consumer of the public Structive contract.

Review priorities

1. Native-object-model preservation.
2. Intrinsic capability versus external policy boundary.
3. Compile-time/schema invariant correctness.
4. Read-only zero-lock guarantee.
5. Lock ordering/group/override correctness and reference lifetime.
6. Runtime adapter result semantics, including copy-write support.
7. Extension-to-Core dependency direction.
8. Public-header independence, compile-fail matrix, install consumer, and Adminive consumer compatibility.