DEV Community: canonical

Why Attractor Guided Engineering Cannot Be Demoted to an AI Agent Skill

canonical — Mon, 01 Jun 2026 07:05:49 +0000

Agent Skill is already one of the most widely accepted practices in AI Agent engineering: encapsulating repeatable tasks into capability packages that are discoverable, callable, and injectable into context.

This is certainly valuable. Diagnosing bugs can be a skill. Reviewing code can be a skill. Generating slides can be a skill. Converting files can be a skill. Skills let an Agent enter a proven way of working faster, and they allow teams to distill experience into reusable work specifications.

But as the saying goes: “If all you have is a hammer, everything looks like a nail.” The same is true for skills: as soon as people find a useful practice, their first instinct is often “wrap it into a reusable skill.”

Attractor Guided Engineering (AGE) points out that if every AI engineering practice is turned into a skill, we lose sight of the most critical question in AI-dominated software engineering: how does the system remain controlled and convergent under continuous perturbation?

Skills solve the problem of capability invocation. AGE solves the problem of how domain structure is preserved during the long-term evolution of a repository, and how trajectory drift is suppressed.

This also explains why AGE cannot be demoted to a skill: making skills the primary vehicle for AGE practices would collapse repository-level convergence mechanisms into one-shot invocation capabilities, defeating the purpose of AGE.

1. The Essence of a Skill is a Semantic-Level Hash Map

When many people think of skills, they first see the file form: SKILL.md, description, trigger words, supporting files, scripts, templates.

But these are just the shell. Where a skill really works is that the Agent runtime organizes them into a semantic-level lookup table:

task intent -> matched skill -> procedure bundle

In other words, the Agent does not gain capability simply because a file is named SKILL.md; it gains capability because the current task intent can be matched in the skill description space to a loadable work specification.

The hash here is not a string hash. The key is not a fixed string but a combination of task intent, contextual clues, trigger words, and descriptions; the value is not a single file but a collection of instructions, scripts, templates, and examples that can be injected into the context.

This structure is ideally suited to answering one question:

I need to do this kind of task — which set of practices should I load?

Therefore, skills are very suitable for encapsulating local capabilities: diagnosing bugs, reviewing diffs, calling tools, generating reports, executing checklists. Their organizing axis is invocation intent, mapping “what to do” to “which capability package to load.”

2. The Information Format Is Not the Key

Since the real mechanism of a skill is semantic matching, we must not fetishize the file format of a skill.

For an intelligent agent, the format in which information is written is not essential. AI can read Markdown, and it can also read XML and other formats. Database models, API models, and the like can be fully expressed in DSLs (domain-specific languages).

AGENTS.md and docs/index.md can perfectly serve as information routers and can even do better: through file links, we can provide hierarchical routing by domain structure. The AI can first read a compact entry point and then, as the task requires, progressively open more specific owner docs, model files, tests, and source code.

Therefore, the question is not “has this piece of knowledge been written as a skill?”

The question is: after the information changes form, does the original structure still exist?

A key capability of intelligence is the ability to freely transform information across forms. If the structure remains, knowledge written as Markdown, XML, tests, DSL/schema, or source code anchors can all be used by the AI. If the structure is lost, wrapping it in the most exquisite skill only makes the fragments—after the structure is lost—easier to invoke.

3. Why Dynamical Systems Care About Preserving Structure

Dynamical systems in mathematics and physics provide a useful intuition: the variables describing a system can change, but the key structures governing the system’s evolution must not be casually discarded.

Imagine a pendulum clock. You can describe it with angle and angular velocity, or with position and velocity, or with energy and phase. The form of expression can change, but the key structure of the pendulum cannot be lost: how position and velocity are coupled, how energy changes, how damping dissipates energy, where external forces enter.

If an algorithm only pursues “the next position looks roughly right” without preserving these structures, it might make only small errors at each step, yet over the long term it makes the pendulum swing higher and higher for no reason, or stop suddenly. The local output looks similar, but the long-term system is no longer the original system.

Consider an electrical circuit. You can describe it with node voltages, or with branch currents, or treat the energy stored in capacitors and inductors as state variables. The variable form can change, but some structures must not be lost: charge conservation, the coupling relationships between voltage and current, energy storage and dissipation in components, where the external power source injects energy.

If an algorithm only pursues voltage values at a few sampling points that look close, without preserving these structures, the long-term simulation may spontaneously generate energy, or turn a system that should dissipate into one that oscillates endlessly. The local curve resembles the truth, but the physical meaning of the system is already wrong.

This is what it means to preserve structure:

The form of expression can change, but key constraints, coupling relationships, and conservation/dissipation structures must not be lost.

A controlled system converges over the long term not because each step seems reasonable, but because these structures are preserved through repeated transformations and perturbations.

4. The State Space Is Not the Source Code Space

If we observe software engineering through the lens of dynamical systems, a repository is no longer a static folder but a system that is repeatedly perturbed. Every requirements clarification, plan generation, code modification, test addition, review, and log update pushes the repository to a new state.

Traditional software engineering rests on an implicit assumption: the human brain can serve as the long-term implicit integrator of system truth. Source code, requirements, architectural trade-offs, historical bugs, and unwritten context can ultimately be fully understood by a few core engineers who decide the direction of evolution.

After deep participation of AI, this underlying assumption is shaken. AI can generate at high frequency, modify at large amplitude, and spread across modules, while each session lacks a sustained sense of direction. The expansive force that AI introduces into the state space far exceeds the information processing capacity of a few humans. At this point, unless we forcibly slow AI down to a rhythm that humans can continuously integrate, the source of truth in the system's evolution can no longer be the memory inside someone's head. What the next session can re-read is not the complete intent in the author’s mind, but the code, diffs, logs, tests, docs, models, and audit evidence in the repository.

The history of nop-chaos-flux has already recorded this kind of drift multiple times. Workstream 8 of docs/plans/436-deep-audit-2026-05-24-full-remediation-plan.md fixed an active-doc drift: the documentation described component:open/close/toggle, component:refresh, the old package split, old source anchors, and an outdated component inventory as current facts, while the live repo was no longer like that. docs/logs/2026/05-26.md recorded a proof drift: the E2E tests still asserted that the spreadsheet's 30 row headers were mounted simultaneously, while the live spreadsheet shell had already been virtualized, so the correct proof could only assert that visible row headers were mounted. Code, documentation, and tests might each be locally reasonable, but the owner/proof/precedence relationships among them had already drifted.

Thus, the basic premise of AGE is:

Repository = Source of Truth
Chat = Transient work surface

Under this premise, the core question is not:

Did the Agent invoke the right skill this time?

but:

After many Agent perturbations, does the repository still converge in a controlled manner along the domain structure?

The basic picture of AGE is:

State space -> Attractor -> Trajectory -> Control

The state space here is not the “source code state space.” Source code answers what the current implementation is, but it cannot alone answer where the system should converge, why a certain design is valid, which behavior has been proven, why a certain deviation was accepted, and from where the AI should recover context next time.

AGE is concerned with the state of the entire repository engineering reality: source code, tests, owner docs, requirements, plans, logs, bug notes, schemas, XML models, database models, XDSL, AGENTS.md, docs/index.md, CI configuration, and audit evidence together constitute a state.

These are not several separable materials, but the distribution of the same set of semantic commitments across different carriers. Code has authority over implementation facts; owner docs have authority over convergence direction; tests have authority over proven behavior; logs/bug notes have authority over the evolution trajectory; plans/audits have authority over whether the current cycle of changes is closed. What AGE must maintain is the relationships among these authorities, not the sanctification of any single file format.

A Skill occupies a different position. AGE organizes the repository itself; skills are external capabilities or control inputs that act upon the repository.

External capabilities can change the system, but they cannot replace the internal structure of the system. A bug-diagnosis skill can be used in many repositories, many domains, many bug types. Its organizing logic is general task capability, not the topology of domain concepts inside a specific repository.

What truly needs to be preserved inside the repository are the relationships among source code, documentation, tests, models, plans, logs, and audit evidence — relationships such as owner, proof, precedence, and freshness. Skills can help modify these things, but they cannot replace the relationships themselves.

At this point, we realize that the skill’s semantic hash is insufficient to solve the problem. What a skill stores is:

task intent -> capability package

What AGE needs to preserve is:

domain concept -> semantic commitment -> implementation location -> proof evidence -> audit/memory -> subsequent obligations

These two structures are not the same. A skill can tell an Agent how to review, but it cannot automatically know which owner doc holds the current semantic fact. A skill can tell an Agent how to write tests, but it cannot automatically know which domain commitment this test protects. A skill can tell an Agent how to update documentation, but it cannot automatically determine whether a piece of information should go into an owner doc, a bug note, a log, a lesson, a reference, or a skill.

These judgments are not invocation capabilities; they are the semantic authority structure of the repository.

5. Why `age-skill` Is a Wrong Abstraction

Turning AGE into an age-skill is superficially tempting: take AGE’s rules, procedures, checklists, and document templates and write them into a callable capability package. When the Agent needs AGE, it loads this skill.

But this places AGE at exactly the wrong level. A skill is a capability package that is matched and loaded after a task occurs; AGE should be the repository structure that already exists before the task begins. It determines how the task is understood, where information is read from, whose voice prevails in a conflict, and how closure is proved after completion.

AGE cannot wait to appear only after a certain skill is selected. It should already be embodied in:

The operational boundary of AGENTS.md
The routing structure of docs/index.md
The fact ownership of owner docs
The conflict rules of source-of-truth precedence
The obligation declarations of plans
The proof relations of tests
The closure gates of audits
The trajectory memory of logs, bug notes, and lessons
The action constraints of freshness/autonomy

If these relationships exist only inside an age-skill, they are not repository structure but merely the content of a procedure bundle. Whenever the Agent does not match this skill, or the skill conflicts with the live repo, AGE becomes ineffective.

Making age-skill an always-on or global skill does not solve this problem either. At best, it can prescribe “read these owner docs first, check precedence this way, do a closure audit like that.” But the real owner, proof, precedence, and freshness relationships must still exist among the repository’s files, tests, logs, plans, and audit evidence.

So the problem is not whether age-skill is loaded every time; the problem is that a skill is still a capability package imposed on the repository from the outside. AGE must become the underlying topology of the repository itself. As long as owner, proof, precedence, and freshness are not internalized as repository state, AGE is demoted to an external operating method rather than an intrinsic convergence structure.

6. The Missing Concepts That AGE Supplies

Under the image of controlled convergence and structure preservation, what AGE supplies is not a new checklist, but a set of first-class system concepts that skill-ification practices lack.

1. Attractor

To what structure should the system return in the long run? This cannot be decided by any single skill. It needs to be carried by owner docs, architectural baselines, domain design, and source-of-truth precedence. Without an attractor, a skill can only tell the Agent how to do things; it cannot tell the repository where it should converge.

2. Trajectory

Completing a single task does not mean the system direction is correct. Logs, bug notes, lessons, plans, and audit records record how the repository arrived at its current state step by step. Without trajectory memory, the AI starts anew from a local cross-section each time, making it hard to judge whether the system is converging or drifting.

3. Semantic Authority

When a skill, plan, code, test, and documentation disagree, whose voice prevails? AGE requires owner, routing, and precedence, rather than letting the currently invoked skill adjudicate on the fly. Semantic authority is not part of the execution steps; it is the internal order of the repository’s state space.

4. Proof Relation

It is not enough for tests to “have coverage.” Tests must declare which semantic commitment they protect. Audit is not a checklist, either, but an examination of whether commitments have disappeared, weakened, or migrated to non-authoritative carriers. Proof relation makes verification not just about passing commands, but about returning to domain commitments.

5. Freshness / Autonomy

Documentation is not eternally trustworthy just because it was written. Whether a document is fresh affects whether the AI can act on it, how far it can go autonomously, and when it must stop and ask a human. Freshness/autonomy turns “can we trust this, can we do this automatically” into a visible state of the repository, rather than an ad-hoc judgment inside a single session.

6. Structure-Preserving Document Routing

AGENTS.md can provide the AI with a compact operational entry point, and docs/index.md can provide complete routing. The purpose of both is not to cram all knowledge into a single file, but to let the AI progressively open the right information according to the task’s needs. Information disclosure can be layered, but the domain structure must not be fragmented.

These concepts together form the semantic authority topology of AGE.

7. AGE Can Use Skills, But Cannot Become a Skill

AGE is not opposed to skills. Skills are excellent execution scaffolds.

But within AGE, skills can only be method nodes; they cannot be the source of truth, nor can they be AGE itself.

The correct order is:

First, find the route via AGENTS.md / docs/index.md
Then, read the domain or architectural owner doc
Then, read the active requirement / plan / audit evidence
Finally, select the appropriate skill as the execution method

Not:

First, select a skill, then let the skill decide fact ownership

For example, a bug diagnosis skill can tell the Agent how to reproduce and locate a problem. But which domain concept the root cause belongs to, which owner doc needs updating, which test proves the fix, and which category of regression the bug note will constrain in the future — all of these must be decided by returning to the semantic topology of AGE.

A good skill accelerates execution. Bad skill-ification replaces domain structure with execution methods.

8. Judgment Criteria

To judge whether a set of AI engineering practices is over-skill-ified, ask:

Does it organize knowledge primarily by operational verbs, or by domain concepts and architectural ownership?
Are its links mainly execution resource references, or owner / invariant / proof / precedence / freshness relationships?
After information is transformed between skills, plans, code, tests, docs, and logs, can the domain structure still be recovered?
If all skills are deleted, does the repository still know what is correct, who owns it, and how to prove it?

If the answers are negative, skills have already taken on attractor responsibilities they should not bear.

The ultimate distinction can be compressed into a single sentence:

Skill packages capabilities by invocation.
AGE preserves domain structure across transformations.

Skills make the Agent better at doing things. AGE ensures that after the Agent does things repeatedly, the repository still converges in a controlled manner along the domain structure.

AGE Application Development Template

Beyond Harness Engineering: Understanding Attractor-Guided Engineering through Nonlinear Dynamical System Control

canonical — Fri, 29 May 2026 15:17:19 +0000

This article is aimed at readers who are already familiar with Harness Engineering but not yet familiar with Attractor-Guided Engineering (AGE).

Harness Engineering focuses on how to constrain, verify, and audit AI-generated outputs; AGE asks further: what long-term structure should these control mechanisms eventually pull the repository trajectories back to?

For a detailed introduction to AGE, see my previous article: Attractor Before Harness: A Methodology for AI-Scale Development. This article focuses on a methodological analogy: using the language of nonlinear dynamical system control—in particular the structure-preserving terminology of port-Hamiltonian systems (PHS) and the target-manifold image of Immersion and Invariance—to explain some structures that already exist in AGE but have not yet been fully named: how semantic commitments are conserved, how change obligations are transformed, how document topology preserves structure, and how AI sessions recover the same system reality in a repository across time.

1. Why This Analogy Is Needed

AGE already has a core language:

State space → attractor → trajectory → control

This basic AGE vocabulary precisely captures a core problem in AI-scale development: when AI perturbs the repository at high frequency and amplitude with no persistent memory, how do we describe whether the system is still converging to a stable structure over the long term?

More precisely, AGE examines AI-driven software engineering through the mental image of a dynamical system. A single AI task can be seen as one perturbation and correction on the repository trajectory; a single input-output is only a local cross-section of that trajectory. The repository is a state space that evolves over time; AI, humans, CI, audits, and documentation updates all change the trajectory; owner docs define the attractor the system should repeatedly return to; plans, tests, audits, and logs provide local calibration mechanisms.

Nonlinear dynamical system control is the theoretical branch that systematically studies “states, trajectories, stability, manifolds, feedback, observation, and structure preservation.” PHS (port-Hamiltonian systems) is a representative example of the structure-preserving approach. It decomposes a complex system into four structural classes: the Hamiltonian records how much energy is stored in the system; the interconnection matrix records how energy is transferred losslessly among internal variables; damping records irreversible losses such as resistance or friction; ports record the boundaries where the system exchanges energy with the external world. The key role of PHS modeling is to classify the coupling terms in the equations by function: some coupling terms only move energy internally, some represent true dissipation, and some come from external ports. Once these structures are distinguished, control design knows which terms should be preserved and which should be compensated or suppressed.

This article does not try to equate AGE with PHS, but rather borrows the representative vocabulary of PHS to further identify conserved quantities, phase variables, interconnection topology, dissipation mechanisms, and port boundaries in AGE.

Terminology conventions used in this article:

AGE: Attractor-Guided Engineering. The core hierarchy is “state space → attractor → trajectory → control.”
Harness Engineering: the engineering practice of building execution scaffolding around AI generation, such as guardrails, verification, review, audit, and diagnostics.
PHS: port-Hamiltonian systems, the representative language of the structure-preserving approach in nonlinear dynamical system control, describing complex systems using an energy function, interconnection, dissipation, and ports.
Hamiltonian: the system’s stored energy function, describing how much energy the system currently holds.
Immersion and Invariance: a method that handles nonlinear control, observation, and adaptation problems by constructing a target invariant manifold.
owner docs: long-term documents that hold the ultimate interpretive authority for certain categories of facts in the repository, such as architecture baselines, feature designs, or component contracts.
closure audit: an audit that re-checks the closure evidence along requirements, owner docs, code, tests, and logs before a task is considered complete.

Compared with PHS, the basic language of AGE still has an underexplored layer:

Between repeated inputs, plans, implementations, verifications, audits, and logs, what exactly is being preserved, transformed, routed, and dissipated?

If we answer in ordinary process language, it is easy to fall back into a linear pipeline:

input → requirement → design → plan → code → test → log

This image misleads the reader. Real development does not simply read the output of the previous stage and generate the next artifact. When writing and reviewing code, the AI typically needs to reference simultaneously: the current requirement, owner docs, live code, tests, a known-good baseline, bugs, logs, the plan, audit results, external contracts, and the reading routes given by the document index and architecture hierarchy.

In other words, AGE is more like a multi-port coupled system; the unidirectional cascade pipeline only describes a local projection of it.

The inspiration from nonlinear control lies exactly here: complex coupling terms are not necessarily noise; many coupling terms are themselves the way the system preserves structure. In motor control, the d-q coordinates—direct-axis and quadrature-axis coordinates that rotate with the rotor—are commonly used; under these coordinates, certain speed-dependent, skew-symmetric cross-coupling terms can represent lossless flow of energy between different coordinates. Similarly, in AGE the cross-references among requirements, architecture, plans, code, tests, and logs bear the topological function of keeping semantic commitments recoverable across different carriers—not just document redundancy.

2. The Structure-Preserving Language of PHS

The basic starting point of PHS is to view a physical system as a combination of “energy storage, interconnection, dissipation, and port exchange.” A common finite-dimensional form can be written as:

dx/dt = (J(x) − R(x)) ∇H(x) + G(x) u
y = G(x)ᵀ ∇H(x)

This formula shows how several core symbols are organized:

H measures the energy currently stored in the system;
J only moves energy; it neither creates nor destroys energy;
R dissipates the system’s internal energy;
u is the port input, y is the port output; the pair forms the port power yᵀu;
G describes how the ports couple to the internal state.

We can borrow this vocabulary to express three methodological principles from nonlinear control:

First find quantities that tend to be conserved, then judge which errors need to be eliminated.
Distinguish lossless routing from true dissipation; do not mistake “information moved” for “the system converged.”
View “transport, dissipation, and external injection/extraction” separately, and avoid flattening all coupling into a linear task chain.

3. The Feedback-Linearization–Style Software Engineering Fallacy

In control theory, exact feedback linearization attempts to cancel nonlinear terms using coordinate transformations and feedback so that the system behaves as a linear object. This works in some systems, but it can also be highly dependent on exact parameters and destroy the system’s original energy structure.

There is a similar impulse in software engineering: to make things easier for the AI, flatten all knowledge into a single unified artifact—a spec, a change request, a task list, an issue, a pull request description, or some master plan document.

This practice appears to reduce complexity, but it is actually performing an engineering version of “linearization”:

Context in raw input is flattened into requirement entries;
The long-term structure of owner docs is flattened into this iteration’s task description;
Architecture precedence is flattened into a checklist;
Historical judgments in logs, bugs, and analysis are flattened into “known items”;
Tests and audits are flattened into “completed proof.”

Locally, this makes it easier for the AI to execute. Over the long term, it destroys the semantic topology of the repository. After different types of facts are squeezed into the same coordinate system, the AI no longer knows which material answers “what is,” which material answers “where we should converge,” and which material is only “why we did it that way at the time.”

AGE can use specs and checklists, but it should not forcibly compress all knowledge into the same execution form. docs/architecture/, docs/components/, docs/plans/, docs/logs/, docs/bugs/, docs/analysis/ need to retain distinct responsibilities, because they are different energy ports and different state coordinates within the same repository system.

4. Semantic Commitment as the Energy Storage Function of AGE

In PHS, the Hamiltonian is the system’s stored energy function, answering “how much energy does the system currently hold.” When applied to AGE, we can regard the semantic commitments that must be recovered, preserved, and used to constrain future evolution across sessions as the repository system’s “stored energy”:

H_repo = total amount of semantic commitment in the repository that remains valid
         and must be recoverable across sessions to constrain future evolution.

Here “semantic commitment” means facts, contracts, and judgments that the system has accepted and that should not be casually lost; file word count or number of document entries is not equivalent to semantic commitment. For example:

A certain user-visible behavior must exist;
A certain schema field has a definite meaning;
A certain package dependency direction must not be reversed;
A certain renderer contract needs to be stable;
The root cause of a certain historical bug must not be reintroduced;
A certain audit finding has been falsified and should no longer drive corrective action;
A certain owner doc defines the current specification baseline, not a future aspiration.

These commitments can be roughly decomposed as:

H_repo = H_intent + H_requirement + H_owner + H_contract + H_behavior + H_proof + H_memory

These components correspond to:

Component	Meaning	Typical carriers
Hintent	Genuine intent brought by external input	User requests, PM explanations, external material
Hrequirement	Requirement commitments that the current slice must fulfill	requirement, plan goals
Howner	Long-term stable structural commitments	architecture docs, component design docs
Hcontract	Contracts that can be relied upon externally or downstream	schema, API, public types, renderer contracts
Hbehavior	Actual running behavior in the live repo	code, examples, playground
Hproof	Re-examinable proof	tests, verification, audit evidence
Hmemory	Trajectory judgments that should not be forgotten in the future	logs, bugs, retrospectives, analysis

An implementation changes the carrier shape of a commitment: the same semantic commitment transforms from “a change obligation not yet fulfilled” into “a stable, recoverable fact in code, tests, owner docs, and logs.”

Hrepo describes only the commitments that have been accepted by the system and need to be retained and recovered. It excludes free uncertainty that has not yet been clarified, assigned, or verified. The latter is recorded separately as:

F_repo = free semantic uncertainty in the repository not yet bound
         to a stable commitment, owner, or proof.

Therefore, Frepo is not a component of Hrepo. It is more like unbound energy floating around the semantic commitments: when requirements are not yet clear, owners not yet determined, tests not yet proven, audits not yet closed—the commitment has emerged but has not yet settled into a stable repository structure.

5. Energy Redistribution Is About Authority Weight, Not File Count

Each folder should not be naively viewed as a separate energy bin. After a requirement is turned into code, the requirement file does not disappear; after an owner doc is updated, the input file still exists. What truly changes is the active authority of the same semantic commitment across different carriers—the redistribution of interpretive power, constraining power, and proving power.

For example, a commitment initially appears in raw input:

"Hidden form fields should not participate in submission."

After it enters the requirement, the raw input is still retained, but the direct interpretive authority for the current implementation transfers to the requirement. After it enters an architecture owner doc, long-term baseline interpretive authority transfers to the owner doc. After it enters code and tests, behavioral execution and proving authority transfer to implementation and verification. After it enters a bug note or log, historical judgment becomes a recoverable memory for future sessions.

Therefore, a more accurate statement is:

Files are not conserved.
The effective weight of semantic commitments is redistributed among multiple carriers.

Within a closed slice, unless an explicit human decision changes the scope, Hrepo should not increase or decrease out of nowhere. What truly should decrease is Frepo—the free semantic uncertainty that has not yet been bound, assigned, or verified.

The goal of AGE can be written as:

preserve H_repo while reducing F_repo.

Requirement clarification, owner-doc alignment, tests, verification, and closure audits bind commitments from a free, vague, driftable state into a stable, recoverable, provable form.

In PHS, R dissipates physical energy H; in AGE, Hrepo represents the total semantic commitment that should be preserved as much as possible, and should not be treated as an object of dissipation. Later, the term R-flow will refer to reducing Frepo—that is, reducing the free uncertainty generated when the same semantic commitment is not yet bound, assigned, or verified.

6. q and p: Stable State Representation and Change Obligation Representation

If we view Hrepo as a scalar defined on some phase space, that phase space requires at least two classes of conjugate variables.

It can be written as:

H_repo(q, p).

Here I borrow the notation q and p to represent two complementary semantic dimensions in AGE, not to treat them as physical position and momentum.

q is the stable state representation:

q_i = the current form in which a certain semantic commitment exists
      within the stable structure of the repository.

It answers: what the system is now.

p is the change obligation representation:

p_i = the directional pressure that a certain semantic commitment exerts
      on future evolution.

It answers: why the system needs to move next, and in which direction.

A simple example explains why the q/p duality is still needed even in one-dimensional cases. Suppose the semantic commitment is:

c = "administrators can export CSV (comma-separated value) files."

When the code currently has no CSV export, two completely different situations can exist:

Situation	qc	pc	AI's expected action
CSV explicitly out of scope	currently unsupported	no change obligation	should not implement
CSV is the top-priority active requirement	currently unsupported	strong change obligation	should implement per plan

Looking only at q, both are “currently unsupported.” But p is completely different.

Conversely, if the current code supports CSV but an owner doc decides to remove it, qc remains “currently supported” while pc becomes a reverse change obligation. Without p, the AI cannot distinguish “stable existence” from “should be deleted but not yet deleted.”

In the AGE documentation system, q is primarily carried by these materials:

Current baselines in docs/architecture/;
Component contracts in docs/components/*/design.md;
Live code and exported types;
Passing tests and examples;
Schema, public contracts, runtime behavior.

p is primarily carried by these materials:

Active plan;
Backlog or audit findings;
Failing test;
Bug report;
Open question;
Stale-doc conflict;
Closure gate;
Human decision pending.

This is only a tendency of responsibility, not a fixed directory mapping. The same file may simultaneously carry both q and p. A requirement describes both the target state and the implementation obligation; a plan records both the current baseline and the closure pressure; a bug note records both historical facts and imposes constraints on future changes.

7. Development Is Converting Legitimate p into Stable q

A correct implementation in AGE converts legitimate change obligations into stable state commitments. “Completing the task” is only the surface narrative; what really matters is whether this change has entered a recoverable, provable repository structure.

Again take CSV export as an example.

In the table below, T(p) denotes the total tension or pressure of change obligations—not a new physical energy, but a marker for “why the system still needs to evolve.”

Before implementation:

Component	State
Hrequirement	high, requirement carries "CSV support needed"
Howner	low or needs update, owner doc hasn't absorbed the capability
Hbehavior	low, code not yet implemented
Hproof	low, no tests or verification
T(p)	high, plan/backlog holds change pressure

After implementation:

Component	State
Hrequirement	still present, but unclosed obligation decreases
Howner	increases if it becomes a stable capability
Hbehavior	increases, code carries behavior
Hproof	increases, tests and verification carry evidence
Hmemory	increases, log/audit records closure
T(p)	decreases, change obligation released

In engineering language, this is:

active requirement / plan pressure
→ owner baseline / code behavior / proof / memory

The commitment did not disappear; it only transformed from “an obligation to be fulfilled in the future” into “a stable fact the current system already supports.”

This also explains why a closure audit should not merely look at checkboxes. - [x] only indicates that the executor claims something is done. The real question is: has this p been transformed into stable q, or has it merely been moved from plan to summary, from summary to log, from log to the next round of follow-ups?

8. J-flow and R-flow: Routing Is Not Dissipation

In PHS, J represents the lossless interconnection structure, and R represents dissipation. AGE likewise needs to distinguish two completely different classes of actions.

J-flow and R-flow here are engineering labels created in this article by borrowing cybernetic language; they are not standard control-theory terms.

J-flow is the transport and transformation of semantic commitments along the correct topology.

Examples:

Raw input is recorded in docs/input/;
Requirements are synthesized into a requirement;
Stable rules enter an owner doc;
A plan references owner docs and the live baseline;
Traceable links are established among code/test/log/audit.

These actions themselves do not necessarily reduce uncertainty. They mainly let commitments flow along the correct topology and avoid being stuffed into wrong positions.

R-flow is what truly reduces Frepo:

A human explicitly cuts scope;
A requirement writes testable acceptance criteria;
An owner doc absorbs a stable baseline;
Automated tests prove behavior;
Focused verification exercises real paths;
An independent closure audit overthrows or confirms a completion narrative;
A bug note records a non-obvious root cause, reducing the risk of future drift.

This distinction is critical. A great deal of seemingly diligent documentation work is actually only J-flow:

Moving ambiguity from input to discussion;
Writing an undecided design into a plan;
Writing a plan summary into a log;
Turning preliminary audit findings directly into a backlog;
Writing “should test” as a closure gate, but never truly executing it.

These may be necessary steps, but they mainly change the location of free semantic energy without truly eliminating it. The real danger is mistaking J-flow for R-flow—mistaking “information moved” for “the system converged.”

9. Park Transformation: From Chat Coordinates to Repo Coordinates

From the nonlinear control perspective, the significance of the Park transformation is that it converts the rotational couplings hidden in time-varying three-phase coordinates into d-q coordinates, where power relationships and interconnection structure are easier to identify.

A similar move exists in AGE. The raw chat, PM materials, and discussions in a long context constitute a time-varying, strongly coupled, implicit coordinate system. Requirements, architecture, execution, proof, history, and assumptions are all mixed together. In this coordinate system, the AI can easily mistake exploration for baseline, plans for facts, and historical judgments for current contracts.

The docs/ system performs the function of transforming this mixed semantic field into more stable repo coordinates:

Coordinate	Responsibility
`docs/architecture/`	Current canonical architecture and owner precedence
`docs/components/`	Component-level contracts and schema semantics
`docs/plans/`	How this round of work will close
`docs/logs/`	What happened and short-term context
`docs/bugs/`	Non-obvious defects and regression risks
`docs/analysis/`	Exploration, comparison, rejected directions
`docs/testing/`	Manual or exploratory proof
live code/tests	Current implementation facts and executable evidence

This step is more like a coordinate transformation: it turns a hidden semantic interconnection structure into a routable, auditable, recoverable topology. Document classification is only the external form of this coordinate transformation.

One could say:

AGE's document system resembles a Park-style re-coordinatization:
it expresses the time-varying, implicit, strongly coupled semantic quantities
in chat into more stable, routable, auditable responsibility coordinates
in the repository. This process is not lossless transformation; it is a
structured transcription that includes interpretation, assignment, and
evidence binding.

10. Space, Time, and Conservation

If we continue unfolding the energy-function language, “space” and “time” in AGE can also receive a clearer explanation.

Here space refers to the semantic responsibility space, not the filesystem path itself:

space = the set of positions where a commitment can be placed,
        interpreted, constrained, and proven.

It can also be called:

space ≃ semantic ownership topology.

For example, the same commitment “should hidden form fields participate in submission” might simultaneously reside in:

docs/architecture/form-validation.md;
docs/architecture/data-domain-owner.md;
runtime code;
validation tests;
a historical bug note;
plan closure evidence.

These positions are more like coordinate axes; together they define the spatial distribution of this commitment in the repository, rather than forming a before-and-after sequence of stages.

Here time refers to the discrete evolution sequence of the repository state, not the natural calendar:

time = sequence of repository state transitions across sessions.

A plan closure, an audit overturn, a commit, a full-green baseline, an owner-doc update—these are all events in AGE time.

AI does not have human continuous memory. Therefore, AGE time is not psychological time but externalized, recoverable repository time. If a decision exists only in chat and never enters the repository, it barely existed in AGE time at all.

From this, we can define two important homogeneities.

Temporal homogeneity: When the same repository state is re-read on different dates, in different AI sessions, and in different context windows, the same set of effective commitments and execution rules should be recovered.

This is the deep meaning of file-in/file-out:

temporal homogeneity = session translation invariance.

If the AI knows today that a feature is out of scope, but tomorrow in a different session does not know it because it was only written in chat, then temporal homogeneity is broken and Hrepo suffers a semantic leak.

Spatial homogeneity: The same type of semantic commitment, no matter in which local feature it appears, should follow the same ownership, routing, and proof rules.

For example, a permission commitment should not bypass the permission owner doc just because it appears inside a CSV export button; schema authoring semantics should not bypass compiler/runtime contracts just because they appear in an example; a complex host capability should not leak directly into the core scope just because the current implementation makes it convenient.

AGE space is not a uniform Euclidean space but a responsibility space with topology and curvature:

Protected areas are high-curvature zones; entering them requires a change in trajectory;
Owner docs are centers of a potential field; nearby changes will be pulled back toward the baseline;
Stale docs are coordinate singularities and should not be taken at face value;
External integrations are open ports that may inject or extract commitments;
Audits are observation surfaces, not sources of fact.

Therefore, AGE does not require all spatial points to be homogeneous. It requires homogeneity within the same type of responsibility region, and that cross-region transitions obey clear topology.

11. Immersion and Invariance: From Attractor to Target Manifold

The core idea of Immersion and Invariance is to first construct a target manifold, rather than estimating all unknown parameters accurately. Immersion means embedding the desired low-dimensional target dynamics into the original system’s state space so that the target behavior becomes a set of state relationships the system can reach. Invariance means that once the trajectory lands on this set of relationships, the system evolution will not take it off the manifold. The task of the controller or observer is to make the trajectory converge to this manifold and maintain self-consistent evolution on it.

The relationship to the attractor concept can be understood this way: the attractor answers “what structure the system should converge to in the long term,” while Immersion and Invariance answers “when unknown parameters and local unobservability exist, how to construct a convergent, maintainable target manifold.” The former defines the long-term structure; the latter gives a control-design image for making the trajectory enter and stay near that structure.

In AI development there are also massive “parameters” that can never be fully known:

The product manager’s complete true intent;
Future user behavior;
The full boundaries of external systems;
All the historical reasons in legacy code;
What the next AI session will misunderstand;
The real evolutionary pressure on a certain abstraction six months later.

Traditional approaches easily fall into two extremes: either try to clarify all unknowns before acting, or swallow all unknowns and code directly.

AGE is closer to the Immersion and Invariance compromise:

Do not require knowing all parameters; only require that the current slice
be embedded into, and converge to, a closable invariant manifold.

Corresponding to AGE, owner docs define the long-term attractor; the current plan’s goals, non-goals, accepted assumptions, verification gates, and closure audit define the local target manifold for this slice. A slice does not have to resolve all unknowns, but it needs to state which local manifold it is embedded into, and why it will not escape this manifold after completion.

This manifold is jointly defined by the following materials:

goals;
non-goals;
owner-doc invariants;
accepted assumptions;
blocking assumptions;
verification gates;
closure audit;
live code baseline.

What a plan should really spell out is:

This slice is permitted to ignore X because X is orthogonal to this closure.
This slice needs to resolve Y because Y changes current contracts or
user-visible behavior.

This does not give a green light to vague requirements. On the contrary, it demands the classification of uncertainty: which unknowns can remain unknown, and which must be eliminated first through human decisions or owner-doc alignment.

12. Structure-Preserving Observer: Audit Is Not Another Narrative Source

The key inspiration from structure-preserving PHS observer design is: an observer can preserve the system’s original structure rather than constructing a separate estimator disconnected from the system topology.

AGE’s audit should be the same. A good closure audit re-observes the system state along the same set of owner-doc precedence, live code, tests, logs, and plan gates; the implementer’s completion narrative is merely material to be verified.

This is also why a closure audit in AGE should not merely ask “is the task done,” but should ask:

Has the live behavior truly landed;
Does the owner doc still describe the current baseline;
Do the tests protect the commitment rather than an accidental implementation;
Are the plan’s Goals/Non-Goals still honest;
Does the closure evidence exist in the repository, not just in a summary;
Have in-scope defects been downgraded to vague follow-ups;
Has J-flow been misreported as R-flow.

If an audit does not preserve structure, it becomes another high-density narrative source. It may create new findings, new backlogs, a new sense of completion, without actually reducing Frepo.

Thus, the audit in AGE should resemble a structure-preserving observer: it re-estimates the system state according to the existing fact topology, and calibrates its estimation with live repo evidence; it does not create a separate fact topology.

13. Implications for AGE Practice

The value of this nonlinear control analogy for AGE practice lies in pointing out several directly improvable methodological points. New terminology is meaningful only when it helps distinguish real engineering actions.

1. Plans Should Explicitly Write the Reference Set

Writing and reviewing code both require materials beyond the previous-stage file. A plan can more explicitly require listing the reference constellation for this slice:

## Reference Set

- Context / routing:
- Active owner docs:
- Live code routes:
- Tests / verification baseline:
- Logs / bugs / known regressions:
- External contracts:
- Plan / audit evidence:

This can prevent the AI from treating the plan as the sole source of truth.

2. Plans Should Explicitly Write the Commitment Phase State

Current plans already emphasize baseline, goals, non-goals, and closure gates. The nonlinear control perspective further asks to spell out q/p:

## Commitment Phase State

- Stable state now (`q`):
- Active change pressure (`p`):
- Target stable state after closure:
- Proof that `p` was converted into stable `q`:
- Remaining pressure and why it is non-blocking:

This can distinguish “the behavior currently does not exist because it is stably unnecessary” from “the behavior currently does not exist but needs to be implemented.”

3. Closure Audit Should Check Semantic Conservation

One more question can be added:

Did any in-scope commitment disappear, weaken, or move to a non-authoritative artifact?

This is more accurate than “were the documents updated.” What we truly need to avoid is commitments leaking during transformation.

4. Owner Docs Should Write Stable Commitments

For important owner docs, structures like the following can be gradually added:

## Stable Commitments

## Allowed Variation

## Drift / Leakage Signals

## Correction Path

This makes owner docs more like structural equations than instruction manuals.

5. Audit Prompts Should Distinguish J-flow and R-flow

During an audit, one should ask:

Which changes merely routed commitments between artifacts?
Which changes actually reduced free semantic uncertainty through
decision, proof, or owner-doc alignment?

This avoids mistaking “more documents were written” for “the system has become more convergent.”

14. Conclusion: The Nonlinear Dynamical System Control Image of AGE

If AGE is reinterpreted under the lens of nonlinear dynamical system control, it can be seen as a structure-preserving AI engineering control system. PHS provides the representative vocabulary of energy, interconnection, dissipation, and ports; Immersion and Invariance supplements the image of a target manifold, unknown parameters, and trajectory convergence.

This image can be summarized as:

Hrepo is the total semantic commitment that should be conserved across sessions;
q is the stable state representation of commitment;
p is the change obligation representation of commitment;
Development is the conversion of legitimate p into stable q;
J-flow is responsible for routing commitments along the correct ownership topology;
R-flow is responsible for reducing free semantic energy that is unbound, unverified, and unassigned;
The docs system is a Park transformation from chat coordinates to repo coordinates;
File-in/file-out maintains temporal homogeneity, i.e., session translation invariance;
Owner docs, plans, tests, audits, and logs together form a multi-port coupled convergence mechanism.

The core judgment is:

The disorder in AI development is not just noise; it is often semantic energy that has not yet been correctly coordinatized. The next step for AGE is to more clearly model how these semantic commitments are injected, routed, stored, transformed, proven, and conserved, rather than simply piling on more processes.

Therefore, AGE can be understood as:

A nonlinear dynamical system control image for software engineering under high-speed AI perturbation: use owner docs to define the attractor, use plans to embed the current slice into a local target manifold, use routing to preserve structure, use verification/audit to reduce free semantic energy, and use logs/bugs to preserve the trajectory memory across time.

Appendix: PHS Mathematical Background

PHS is a structured modeling framework developed by van der Schaft, Maschke, and others around the 1990s around nonlinear systems, generalized bond graphs, and port interconnections, and is closely intertwined with the passivity-based control and energy shaping work of Ortega and others. Its difference from ordinary state-space models lies in putting the energy function and interconnection topology first. Mechanical systems, electrical circuits, motors, power networks, and fluid networks can all be viewed under this perspective as combinations of energy-storage elements, dissipative elements, and port interconnections.

Interconnection and Damping Assignment Passivity-Based Control further applies this approach to control design: the controller does not simply cancel nonlinearities, but reconfigures the closed-loop system’s interconnection structure and damping distribution so that the closed-loop energy function has the desired shape. Structure-preserving observers, PHS network stability, and passive interconnection of microgrids all inherit the same judgment: preserving structure is often more robust than flattening it.

A common form of finite-dimensional PHS is:

dx/dt = (J(x) − R(x)) ∇H(x) + G(x) u
y = G(x)ᵀ ∇H(x)

where:

Symbol	Meaning
x	System state, e.g., mechanical position/momentum, circuit flux linkage/charge
H(x)	Total energy function of the system
∇H(x)	Gradient of energy with respect to state, also often called co-energy variables; under specific port choices can correspond to conjugate quantities like force, voltage, current
J(x)	Skew-symmetric interconnection matrix, satisfying J(x)ᵀ = −J(x), represents lossless energy routing
R(x)	Positive semidefinite dissipation matrix, satisfying R(x) = R(x)ᵀ ≽ 0, represents dissipation such as resistance, friction
G(x)	How external ports couple into the system
u	Port input, e.g., applied voltage, external force
y	Port output, usually paired with u to form input power yᵀu

Taking the derivative of H along system trajectories:

dH/dt = (∇H)ᵀ ẋ = (∇H)ᵀ J ∇H − (∇H)ᵀ R ∇H + (∇H)ᵀ G u.

Since J is skew-symmetric, for any vector a we have aᵀ J a = 0. Therefore:

dH/dt = − (∇H)ᵀ R ∇H + yᵀ u.

If there is no dissipation and no external input, i.e., R = 0 and u = 0, then dH/dt = 0—energy is conserved. If u = 0 but R ≽ 0, then dH/dt ≤ 0—the system energy is non-increasing. This is the fundamental reason why passivity-based control and energy shaping can work.

Integrating the above from 0 to t gives the passivity inequality:

H(x(t)) − H(x(0)) ≤ ∫₀ᵗ y(τ)ᵀ u(τ) dτ.

It expresses that the increase in stored energy will not exceed the total energy injected through the external ports. The system can store energy, release energy, and dissipate energy, but cannot create energy out of nothing.

This inequality explains why PHS is particularly suitable for network systems. If two passive systems are interconnected in a power-conserving way, for example:

u₁ = −y₂, u₂ = y₁,

then the sum of the two port powers is:

y₁ᵀ u₁ + y₂ᵀ u₂ = y₁ᵀ (−y₂) + y₂ᵀ y₁ = 0.

The interconnection itself neither injects nor dissipates energy; it only moves energy between the two subsystems. Therefore, lossless interconnection of passive systems remains passive. This property is key to extending PHS from single motors, robot arms, and circuits to microgrids, networked systems, and large-scale physical systems modeling.

The minimal canonical Hamiltonian system can be written as:

x = (q, p),

[ dq/dt ]   [ 0  I ] [ ∂H/∂q ]
[ dp/dt ] = [ −I 0 ] [ ∂H/∂p ].

Here q is a position-like variable, p is a momentum-like variable, and the matrix in the middle is the most basic symplectic structure. Its role is not to dissipate energy, but to let energy reciprocally convert between “positional potential energy” and “momentum kinetic energy.”

If dissipation and ports are added, we obtain a more general form:

[ dq/dt ]   [ 0  I ] [ ∂H/∂q ]
[ dp/dt ] = [ −I 0 ] [ ∂H/∂p ] − damping terms + port input terms.

The reason the Park transformation is important in electric motors is that it converts the time-varying rotational relationships in stationary three-phase coordinates into d-q coordinates, making speed-dependent cross-couplings easier to identify as part of the interconnection structure. From the energy perspective, such a cross-term is not an ordinary disturbance, but a structural channel through which energy flows among the d-axis, q-axis, and mechanical momentum.

This fact can be seen from a two-dimensional skew-symmetric matrix:

S = [ 0  −1 ]
    [ 1   0 ],  Sᵀ = −S.

For any 2D vector z, we have zᵀ S z = 0. If a local dynamic contains a term ω S z, it will cause the two components of z to rotate mutually and exchange energy forms, but it will not change the quadratic energy ½ zᵀ z:

d/dt (½ zᵀ z) = zᵀ ż = zᵀ (ω S z) = ω zᵀ S z = 0.

This is why the PHS perspective cautions against the intuition to “cancel all cross-coupling terms.” Some cross-terms are not errors, but the manifestation of system topology in local coordinates.

AGE Application Development Template

Attractor Before Harness: A Methodology for Large-Scale AI Development

canonical — Thu, 21 May 2026 12:08:33 +0000

In systems where AI deeply participates in development, the first-principles question is not "how to constrain AI's behavior," but "what long-term structure the system should converge to."

Only after this direction is clearly defined can mechanisms like harness, guardrail, verification, audit, and closure truly have meaning. Otherwise, they are merely efficiently solidifying a wrong baseline.

This claim is inevitable because AI collaboration pushes "trajectory convergence"—a problem long treated as an add-on in software engineering methodology—to a position where it must be explicitly modeled.

1. Why Harness Is the First Thing People Think of When Discussing AI Engineering

In current discussions about AI-assisted development, the most common terms are:

guardrail
verification
review
feedback loop
agent harness

This set of intuitions assumes a single premise by default:

The correct direction of the system is already known.

Given that premise, the problems naturally become:

How to limit deviations
How to expose failures as early as possible
How to make reviews stricter
How to prevent agents from going rogue

This language suffices for small tasks. For a script, a CRUD page, or a local bug fix, you usually already know "what a correct result looks like"; the remaining work is mainly about execution and verification.

But what truly makes large systems difficult is often not "how to prevent crossing the line," but "which path is the right long-term structure in the first place."

To answer this question, we must first recognize one thing: all current harness-type mechanisms rest on an implicit premise—the evaluation unit is primarily state, and trajectory convergence relies on the developer's tacit sense of direction as a backstop. AI collaboration removes precisely this backstop.

2. The Backstop That Has Been Removed

Open any mainstream engineering methodology—TDD, DDD, Clean Architecture, Agile, Code Review culture—and their first-class evaluation targets are almost always state:

Evaluate "whether this PR is correct," not "whether the cumulative direction of the last 100 PRs is correct."
Evaluate "whether the current architecture is clean," not "whether the architecture is being continuously pushed toward a stable form during evolution."
Evaluate "whether tests cover the current behavior," not "whether the test suite itself has been corroded by implementation details."

Traditional methodologies are not entirely without trajectory awareness—refactoring, technical debt, code smells, evolutionary architecture, and Lehman's laws of software evolution all touch on trajectory. But these concepts exist in the methodology as corrective mechanisms and diagnostic vocabulary, not as fundamental objects. When a theory must continuously introduce negative concepts like "debt," "fragility," and "corrosion" to retroactively acknowledge trajectory problems, it reveals that its foundational category set lacks a positive trajectory object.

This state-centric paradigm has worked for so long because human engineers themselves act as a perturbation source with low frequency and stable directional sense. A person writes a few hundred lines of code per day; each perturbation is small in magnitude, and a continuous sense of direction is maintained in the mind. State-level quality assurance combined with the programmer's implicit directional sense ensures that the trajectory does not drift.

AI collaboration removes this backstop. AI is not a faster programmer; it is a structurally different perturbation source:

High frequency: A single session can generate hundreds of lines of code spanning multiple modules in minutes.
High magnitude: Each generation can introduce cross-boundary structural changes.
No persistent directional sense: Each session is independent, with no implicit architectural judgment carried across sessions.
Highly reasonable locally: Interfaces, types, tests, and documentation can be produced simultaneously, and each piece passes inspection when viewed in isolation.

The last point is crucial. In AI collaboration, all state-level checks can pass while the system as a whole drifts continuously.

Plan 76 of nop-chaos-flux is a typical example. An attempt to remove the local state mirror in array-editor / key-value immediately caused 11 test failures. But what was exposed was not a specific bug, but a deeper fact: the tests themselves had become tightly coupled to the timing of the old implementation. From a state perspective, every incremental change had passed review and CI; from a trajectory perspective, the test suite had unconsciously drifted into a position where it could no longer support structural evolution.

Traditional theory has a symptom name for this—"test fragility"—but a symptom name is a cross-sectional diagnosis. It does not name the process by which 100 legitimate commits accumulate into fragility. Trajectory problems are process problems, and process problems require a process language.

Thus, the issue is not that AI makes old problems worse, but that AI pushes trajectory problems from an occasional repair target to a high-frequency, first-class citizen. For these problems to enter the methodology's field of view, engineering methodology must adopt "trajectory" as a fundamental category.

3. Dynamical Systems Language: Making Trajectory Problems Explicit

In mathematics and physics, a dynamical system refers to a system whose state evolves continuously over time, with each next state depending on the current state. What we care about is not just whether it is correct at a single moment, but what kind of trajectory it traces out over time.

Translated to large-scale AI development, this language corresponds to four mutually defining fundamental objects:

State Space: All possible implementation states the system can evolve into under current constraints.
Attractor: The stable structure to which the system is repeatedly pulled back during long-term evolution.
Trajectory: The actual evolutionary path left behind after each round of generation, verification, and correction.
Control: The various mechanisms that continuously influence the trajectory through local signals.

The repository, under existing constraints, has a set of all possible combinations of code, documentation, and tests it could evolve into—this constitutes the state space. The continuous actions of humans, AI, review, CI, and documentation updates constitute the evolution rules. The interaction of these two forms the live repo history, which is the trajectory. The attractor is the stable structure to which the system is repeatedly pulled back during long-term iteration.

One point must be made clear: this language is not a "more elegant way of saying things," but the foundational language of a new ontology. The four concepts—state space, attractor, trajectory, control—define one another; if one is missing, the other three cannot be rigorously expressed. Attempting to translate these concepts into the language of the old ontology (architecture, constraints, goals, process) inevitably incurs information loss—this is the root of misreadings like "Isn't Attractor Guided Engineering just Harness?"

The relationship among the four objects is:

State Space → Attractor → Trajectory → Control

This is not a rhetorical ordering; it is a logical dependency. Without defining the state space, there is no talk of an attractor; without defining the attractor, one cannot judge whether the trajectory is drifting; without trajectory judgment, control has no target.

The "before" here refers to logical priority: in execution, attractor and harness co-evolve in a closed loop, but the attractor can be conceptually defined independently of the harness, while the harness cannot be conceptually defined independently of the attractor (to correct deviation, toward what?). This asymmetry corresponds to the relationship between final cause and efficient cause in dynamical systems—acknowledging co-evolution does not weaken the "before" claim. Final cause and efficient cause act together in physical systems as well, but the final cause remains the logical prerequisite for the efficient cause.

4. What Exactly Is an Attractor

Take the well-known Lorenz attractor as an example. It is implicitly defined by differential equations. It is not a checklist that enumerates all correct trajectories in advance, nor is it a simple boundary. Within the attractor, local trajectories are highly complex and appear nearly chaotic in the short term, yet the whole does not fly apart randomly; it is always pulled back into the same type of geometric shape.

Lorenz attractor: Local trajectories are highly complex, yet the whole is still constrained by a stable structure. Chaos does not equal randomness; local unpredictability does not mean the whole is out of control.

An engineering attractor works the same way. It is more like an "equation-defined manifold" than "a list of all legal points enumerated one by one." The equation does not write out every point on the manifold in advance; it only stipulates which relations must hold. Points satisfying these relations naturally fall within the same structure.

Key difference from traditional architecture concepts: DDD and Clean Architecture also emphasize long-term structure, but they treat that long-term structure as a target state—the methodology's job is to "reach X." A trajectory ontology treats the long-term structure as an attractor—the methodology's job is to "return to the vicinity of X no matter how far you are pushed away." The second perspective addresses stability under perturbation. This is exactly the core problem in AI collaboration scenarios, and exactly the problem for which traditional methodologies lack first-class conceptual tools.

To prevent conceptual drift, an attractor in engineering can be strictly divided into three layers:

Structural layer (the attractor itself): A small number of high-order invariants, such as how responsibilities are divided, how boundaries are established, and which structural relationships cannot be violated.
Carrier layer (the engineering carrier of the attractor): Externalizing these invariants into versionable, auditable documents.
Implementation layer (the instantaneous projection of the attractor): The parts of the current code that actually embody these invariants.

The attractor is not the document; the document is the carrier of the attractor. The attractor is not the code; the code is an instantaneous projection of the attractor.

This layering is important because it resolves a common confusion: "When architecture docs and code conflict, which one do we follow?" The answer is not "which one is more authoritative," but "what question are you asking?" If you are asking about current implementation behavior, the code is authoritative. If you are asking where the system should converge, the docs are authoritative. If you are asking why a certain path was abandoned, logs/bugs/analysis are authoritative. Each layer is authoritative only for its corresponding question.

5. The Repository Begins to Bear the System's Truth, Making Harness Infrastructure

Once AI deeply participates, the repository is no longer merely an external projection of human cognition; it begins to become the sole carrier of the system's truth. No one person fully grasps all the design details in the system, and no one can answer questions about the system's design without consulting the project source code. What the next session can re-read is not the full intent in the author's mind, but the code, diffs, logs, tests, and documentation.

This has a direct engineering consequence:

Generation and acceptance must be genuinely separated.

Generation actions can be completed at high speed by AI within the same context, but acceptance can no longer rely on that generative context itself. You must return to the external evidence in the repository and re-evaluate:

Whether the behavior was truly implemented.
What the current baseline actually is.
Which materials are authoritative.
Whether this "completion" is just a feeling of completion.

It is precisely because the repository begins to bear the system's truth that generation and evaluation must be separated; and it is precisely because generation and evaluation are separated that the harness is upgraded from a "safer engineering habit" to necessary infrastructure.

In traditional collaboration, harness is optional discipline; in AI collaboration, harness is the necessary condition for making trajectory judgment possible. The reason is this: while AI generates code, it also generates all the materials for judging whether that code is correct—types, tests, documentation, completion summaries are all produced together by the same context based on the same understanding. If that understanding is skewed, all "verification evidence" will be skewed consistently in the same direction, not contradicting each other, yet entirely wrong as a whole. This self-verification trap is naturally weakened in human collaboration—CI rules, reviewers, spec documents are all independent external standards maintained by different cognitive subjects. AI collaboration breaks this independence, so we must use engineering means—fresh sessions, independent audits, returning to live repo forensics—to artificially reconstruct the separation of generation and acceptance.

Under repo-truth conditions:

test / lint / audit functions more like measurement.
owner doc / plan / closure functions more like constraints.
logs / bugs / discussions functions more like trajectory records and externalized memory.

6. Three Most Common Ontological Confusions

First, mistaking the attractor for a boundary.

Boundaries answer "what cannot be done," and violating them causes an error immediately. Attractors answer "where the system should converge in the long run." A single violation may not cause an error, but persistent deviation causes structural decay. Boundaries define forbidden zones; attractors define stability zones. Confusing the two downgrades the attractor to a stricter guardrail, missing its core capability of handling "stability under perturbation."

Second, mistaking the attractor for a stronger guardrail.

Guardrails operate at the execution layer (checked for each action), while attractors operate at the direction layer (whether the accumulation of multiple actions trends toward it). Understanding it as stricter governance, denser constraints, or stronger auditing still reduces the primary problem to the control layer. The root of this reduction is the failure to recognize that the two belong to different levels.

Third, mistaking the attractor for another way of saying "control target."

The phrase control target seems very close, but it assumes that a control framework is already in place. Under a trajectory ontology, the attractor's role is to provide the final cause for control—it is prior to control, not within it. If the attractor is not defined first, so-called control has no target, and mechanisms like harness, guardrail, verification, and audit have no unified meaning.

7. In the nop-chaos-flux Repository, the Attractor Is First and Foremost `docs/architecture/`

If the attractor remains only at an abstract level, it has no real engineering significance. For nop-chaos-flux, what first bears the attractor is the owner-doc system with precedence within docs/architecture/.

In this repository, the engineering landing point is clear: the specification definitions under docs/architecture/ come first, followed by convergence mechanisms like plan, verification, audit, and logs.

Within docs/architecture/, this "equation layer" also has a clear precedence:

docs/architecture/README.md is responsible for explaining the architecture hierarchy and reading order.
flux-design-principles.md handles the direction layer, explaining design intent and stable principles.
frontend-programming-model.md handles the top-level specification layer, defining primitive identity, macro boundaries, and hard invariants.
flux-core.md handles the current codebase-wide baseline.
Narrower architecture docs define local contracts within their respective topics.

In nop-chaos-flux, the structural layer of the attractor is not an abstract "correct architecture," but is defined by a small number of high-value invariants: the closed set of seven primitives, the compile-first pipeline, the Template/Instance separation, Data/Capability orthogonality, the unified renderer/hook contract, and the dependency direction flux-core → flux-formula → flux-compiler → flux-action-core → flux-runtime → flux-react.

These are not parallel pieces of governance material; they are structural equations fixed by owner docs. The value of architecture lies not in describing everything, but in making wrong structures unable to continue existing legitimately.

It is precisely for this reason that many truly important convergence actions in this repository end up manifesting as "a certain old structure being excluded from the legitimate state space."

The final removal of CompiledSchemaNode is a typical example. It was not merely a refactoring cleanup; it demonstrated that once the new baseline of template/instance separation was established, the old intermediate structure, though still functional, no longer belonged to the correct structure and was thus excluded.

Similarly, the three-way split of flux-compiler / flux-action-core / flux-runtime is not simply a matter of "extracting two more packages," but a case where the attractor became more precise: the system was not just "able to run," but was further converged into a more stable responsibility structure.

8. What Is Harness

If the attractor solves "what is the direction," then harness solves:

How to continuously measure, correct, and update the system's trajectory through local signals.

The term "harness" here does not mean the narrow testing harness, but a broader execution scaffold. It typically includes: context routing, separation of implementation and acceptance, planning and closure conditions, verification mechanisms, audit mechanisms, diagnostic tools, and externalized memory.

In this repository, at least five layers of harness can be seen:

1. Routing Harness

docs/index.md and docs/architecture/README.md determine: what to read first for a given problem, what is the current baseline, and what is merely analysis, plan, or history.

2. Plan Harness

docs/plans/ addresses "how this round of expansion closes," not "what the system is."

Fields like current baseline, goals / non-goals, exit criteria, validation checklist, and closure audit evidence define how a local trajectory can be effectively closed.

After Plan 145's closure/audit, the newly confirmed follow-ups were broken out into Plan 146. Plan 143's closure assumptions were repeatedly overturned by fresh audits until the live repo truly crossed the line and closure was allowed. Plans here are not a to-do list, but a local convergence mechanism—they don't just list "what needs to be done now," but stipulate where this round of expansion must close, what exit criteria must be met, and what independent evidence closure requires.

3. Verification Harness

lint, check, typecheck, build, test push high-frequency, clear, automatable deviation detection to the machine layer ahead of time.

4. Audit Harness

Not all deviations can be caught by automated rules. Higher-level semantic drift, structural bias, false completion, and problems that are locally self-consistent but globally distorted still require independent auditing.

Auditing itself is also a closed loop: discover deviation points, filter out conflicts and false problems, and return to the live repo for confirmation. The focus of high-quality auditing is not to pile up more problems, but to eliminate invalid problems as quickly as possible.

In this repository, one of the most critical harness rules is: never let the same context serve as both implementer and completion judge. Completion must be re-evaluated against the live repo by a fresh session or independent audit. The reason the closures of Plan 143 and Plan 145 carry weight is precisely because "completion" is not self-reported by the implementer, but comes from an independent convergence judgment.

5. Memory Harness

docs/logs/, docs/bugs/, docs/discussions/ constitute cross-session externalized memory.

This layer is especially important because for AI, "why that understanding is invalid" is itself part of the system's memory. It is often insufficient to retain only the final conclusion; you must also retain:

Which premise has been falsified
Which path has been proven to diverge
Which terminological translation degrades the problem
Which "completed" judgment was later overturned by the live repo

Without this memory harness, the system loses a portion of its historical trajectory information each time.

True closed-loop is not "define the attractor once, then execute harness forever," but "define attractor → expand → correct → update attractor → expand again." The three-way split of flux-compiler / flux-action-core / flux-runtime is an example of the attractor being refined by practice before continuing expansion.

9. Why a New Attractor Is Usually Not Evolved by AI on Its Own

Even with harness in place, you cannot expect AI to slowly evolve a new attractor on its own through high-speed iteration.

At least under the training distribution and biases of current mainstream models, this generally cannot be expected to happen naturally.

To be more specific:

Current mainstream AI excels at high-speed expansion and convergence around an existing attractor.
However, it typically falls back to the average solution it has seen.
Truly novel conceptual decompositions, boundary redefinitions, and architectural languages still require a human to propose first.

The responsibility for defining a new attractor cannot be silently outsourced to AI.

In large-scale framework development, the division of labor between humans and AI cannot be simplified to "AI writes code, humans do review." The more realistic division is:

Humans define new attractors.
AI performs high-speed expansion around the defined attractor.
Harness continuously pulls the trajectory back on track.

Concepts like the separation of ActionScope and Data Scope, or lexical scoping—concepts that genuinely change the system's structural language—cannot grow by letting AI freely sample average solutions. They are new attractors that must be proposed first; only then can AI perform large-scale expansion on the new baseline.

A limitation must be acknowledged: this means the effectiveness of this methodology depends on the presence of people within the team capable of defining attractors. This is not a weakness of the methodology, but a fact it correctly identifies—architectural judgment is a scarce resource. In traditional collaboration, this judgment could partially reside in the architect's mind, transmitted through oral tradition and code review. AI has no cross-session memory; any architectural judgment not explicitly externalized does not exist for AI. The engineering contribution of this methodology is precisely to externalize this scarce resource into a versionable, auditable, inheritable repository structure so that it does not have to leave with the individual. However, if no one on the team can make such judgments at all, the methodology cannot generate them out of thin air.

10. Conclusion

The truly difficult part of large-scale AI development is not getting AI to write more code, but ensuring the system continues to converge toward the correct structure during high-speed expansion.

This convergence problem has no positive object in traditional methodologies where state is the first-class citizen—it can only be indirectly acknowledged through negative terms like "debt," "fragility," and "corrosion." For the convergence problem to become a first-class citizen object that can be expressed, discussed, and engineered, the methodology must incorporate trajectory into its foundational categories.

Whoever proposes a new attractor defines the structural baseline for the system's subsequent evolution.

Compressing this methodology to its core, only one line remains:

State Space → Attractor → Trajectory → Control.

This is not a more complex engineering process; it is a more fundamental engineering conceptual structure. Only with a structure defining where the system should converge in the long run can there be a judgment of whether the trajectory has deviated; only with a judgment of trajectory deviation can the subsequent harness, guardrail, verification, audit, and closure have a unified meaning.

In the age of AI, what is truly scarce is not more agents that can write code, but people who can first answer the question, "Where should the system converge?"

nop-chaos-flux is open source:

From Spec-Driven Development to Attractor-Guided Engineering

canonical — Thu, 21 May 2026 11:52:48 +0000

nop-chaos-flux is a low-code runtime framework built on React 19, Zustand 5, and Vite 8. It is inspired by Baidu AMIS but independently implemented from scratch based on innovative design principles. It includes a JSON Schema compiler and runtime, as well as design tools such as a report designer and Flow Designer.

The initial version of this project was completed by a single programmer in two months, developed entirely through AI automation. Unlike typical AI-assisted development, as features were continuously added, the project did not suffer from quality degradation. Instead, module boundaries became clearer, document categorization more stable, testing and auditing increasingly captured real issues, and code quality continuously improved.

I recently gave some internal sharing sessions and named this practice Attractor-Guided Engineering (AGE). Later, during code reviews, I found that many people did not truly understand it. Some operated in a way close to casual vibe coding, while others adopted a spec-driven development style similar to OpenSpec, leaning overall toward task-driven, feature-by-feature development. As the workload accumulated, inconsistencies in the code steadily built up, and deviations from the architectural design became the norm.

This article analyzes the differences between AGE and spec-driven development, and what ordinary business projects can learn from the large-scale AI engineering practices of nop-chaos-flux.

Core Hierarchy

At the heart of AGE lies the following conceptual hierarchy:

State Space → Attractor → Trajectory → Control

State Space: All possible implementation states the system can evolve into under current constraints.
Attractor: The stable structure to which the system is repeatedly pulled back during long-term evolution.
Trajectory: The actual evolutionary path preserved after each round of generation, verification, and correction.
Control: Various mechanisms that continuously influence the trajectory through local signals.

All possible combinations of code, documentation, and tests that the repository could evolve into under existing constraints constitute the state space. The continuous actions of humans, AI, review, CI, and document updates form the evolutionary rules. The live repo history created by the superposition of the two is the trajectory. The attractor is the stable structure to which the system is repeatedly pulled back over long-term iteration.

Large-scale AI development is essentially a controlled convergence problem for a dynamical system. AI expands the state space extremely fast. The key is not to add guardrails everywhere, but to first figure out: what structure should the system be pulled back to over the long term?

An attractor is not a fully written-out end point, not a roadmap, and not a "scope of permitted activity." It is a structure implicitly defined by a small set of high-order constraints: local implementations can vary, but the whole will be pulled back to the same type of form by these relationships.

In nop-chaos-flux, what first defines the attractor is not the plan, lint, test, audit, or any single spec file, but the architecture docs with precedence under docs/architecture/. In the following text, these architecture docs with owner and precedence are referred to as owner docs.

docs/architecture/README.md explicitly states: docs/architecture/ is the current final-state architecture baseline, flux-design-principles.md is the governing-principles anchor, frontend-programming-model.md holds the top-level primitives and core-boundary precedence, and other normative docs hold local precedence within their respective topics.

These documents do not enumerate all correct implementations. They define a stable structure like an equation: what primitives exist, which dependency directions are legal, which owner boundaries must not be broken, and which old patterns no longer belong to the correct state space. They first define the cluster of states that can sustainably exist, so that subsequent implementation, testing, planning, and auditing have a reference.

Plan, verification, audit, logs, bugs, testing all come later. They are not the attractor itself, but the harness that keeps the system trajectory continuously close to the attractor.

Flux/AGE is not centered on spec evolution, but on attractor definition and trajectory convergence.

Real Development History

"Architecture docs define the attractor" might sound like ordinary document governance at first, but the difference becomes clear if you carefully examine the actual development records in docs/logs/.

For example, docs/plans/371-deep-audit-2026-05-19-owner-routing-plan.md is a typical entry point. It does not directly change the code, but converges the 64 retained findings from the 2026-05-19 deep audit into an owner-routing baseline. Each finding has a unique owner bucket, priority, successor plan, and owner-doc obligation. No ownerless items, no multiply-owned items, no silent downgrade to vague follow-ups.

Its role is to first freeze how a round of deviations should be resolved, after which the subsequent execution plans close the local trajectory to concrete outcomes. docs/plans/382-deep-audit-2026-05-19-table-and-crud-owner-state-and-event-contract-plan.md resolves the table/CRUD owner state and event payload: Current Baseline declares the live status of explicit empty-array owner state and event payload, execution items fix the empty-array fallback, focused tests prove the result, docs/components/table/design.md and docs/components/crud/design.md synchronize the owner contract, and finally repo-wide pnpm typecheck, pnpm build, pnpm lint, pnpm test all pass, with the independent closure audit ses_1bd9ed593ffeVpkho4lb4wPR6p recording Verdict: acceptable.

docs/plans/388-deep-audit-2026-05-19-form-tree-widget-accessibility-plan.md demonstrates another type of closure: visible node roving focus, ArrowUp/ArrowDown/Home/End navigation, loading aria-busy/aria-describedby for input-tree and tree-select all have focused proof, but the plan explicitly rules No owner-doc update required. This shows that a plan is not just a to-do list; it is also responsible for judging whether this change modifies the owner-doc baseline.

docs/plans/400-deep-audit-2026-05-19-test-harness-reliability-plan.md and docs/bugs/62-e2e-shared-websocket-error-suppression-fix.md demonstrate the role of memory harness. The problem was not a business function failure, but that the E2E shared fixture's filter scope was too broad, filtering out real transport/runtime failures as well. The fix not only changes the code, but also adds tests/e2e/fixtures-hard-gate.spec.ts to prove it now fails, and records a rule in the bug note: if future tests genuinely expect a WebSocket failure, a per-test allowance must be used, and fixture-wide suppression must not be restored.

docs/logs/2026/05-19.md and docs/logs/2026/05-20.md are not mere daily logs. They record the focused proof of each closure slice, owner-doc rulings, repo-wide gates, independent audits, and full-green baselines.

These materials form a real chain: owner docs define the long-term structure, audits discover deviations, plans route and freeze ownership, focused proof demonstrates local results, owner-doc rulings decide whether to update, logs/bugs/testing preserve cross-session memory, and closure audits re-judge completion status from the live repo.

This is the harness in AGE. The goal is not to make each task appear more complete, but to make the system trajectory continuously return to the vicinity of the attractor.

Where OpenSpec's Structure Excels

OpenSpec is a representative spec-driven development framework that structures a category of work well:

openspec/specs/ stores the behavioral specifications of current capabilities.
openspec/changes/ stores proposed changes, including proposal.md (why change, what changes, impact), design.md (technical design when necessary), and tasks.md (implementation checklist).
changes/<name>/specs/ records spec deltas using ADDED/MODIFIED/REMOVED/RENAMED.
Archive applies the deltas back to the main specs through fixed rules.

This mechanism lowers the cost of updating specifications. OpenSpec does not require the AI to freely understand the entire requirement and then arbitrarily modify documents each time. Instead, it uses fixed sections, requirement header matching, and delta application to merge structured changes back into the main specs. This approach is well-suited for scenarios where behavioral specifications are clear and need to be parseable, archivable, and re-writable.

Where OpenSpec Is Limited

OpenSpec's spec format (Requirement, Scenario, SHALL/MUST, delta sections) is tool-parseable friendly, but is not flexible enough as a way to organize general project knowledge.

A lot of repository knowledge does not naturally grow into requirement/scenario form:

Architecture hierarchy and precedence.
History of terminology misunderstandings.
External research materials (PPT, discussion records).
Analysis conclusions from a source code audit.
Phenomena discovered through manual testing.
The elimination path of a complex bug.
Why a plan cannot be closed.

If everything must first be translated into a spec/change to gain an official place, the conversion cost is high, and the original context is also lost. External documents, discussion records, analysis reports, and bug retrospectives could directly become repository memory. Forcing them into requirement/scenario format tends to flatten the information.

In terms of execution verification, the two reflect different tool philosophies. OpenSpec's tasks.md is a checklist; /opsx:verify is an optional agent verification skill (requires manually enabling expanded workflows). archive checks task status and prompts about risks, but can still proceed after user confirmation—strict closure is left to the team's own conventions.

Flux plan, on the other hand, bakes independent closure audit in as a required step: you must start from the current baseline, write clear Goals, Non-Goals, execution items (each annotated with Fix/Decision/Proof), and Closure Gates; before marking completed, an independent sub-agent or independent reviewer must go back to the live repo and perform a closure audit. docs/plans/361-slot-contract-host-manifest-and-owner-doc-closure-plan.md puts together the current baseline, the finding ownership matrix, execution phases, closure gates, the deferred items that have been ruled on, and independent review evidence. This is not a checklist, but an execution contract that strictly defines closure conditions and requires independent audit. It emphasizes not what was done, but to what standard something counts as truly landed.

Why Spec-Driven Easily Becomes Task-Oriented

The default structure of spec-driven development easily pulls the attention of both humans and AI back to "how to complete this change."

A change typically has a proposal, design, tasks, and delta specs. This is much better than verbal requirements, but it is naturally organized around one change: why change, what to change, how to do it, which checklist items are done. Over time, spec-driven development can easily become a more formal task dispatch system.

This task orientation has a hidden risk: specs are updated, tasks are checked, archive is done, and both AI and humans get a strong sense of completion. But whether the system is truly closer to the long-term structure is not proven by the change itself. It must be verified by looking back at the architecture docs, the live repo, tests, logs, and independent audits.

If one tries to long-term maintain specs to the level of precision in Flux, the cost is usually higher. What Flux maintains is not a single specification tree, but a set of repository memories with different responsibilities: architecture docs define the attractor, plans define local trajectory closure, logs record evolution, bugs preserve complex defect diagnosis, testing preserves manual findings, analysis preserves research judgments, and audit is responsible for looking back at the live repo. Cramming all of this into a spec/change structure incurs continuous conversion cost.

Spec-driven can serve as a local harness within AGE to manage behavioral spec evolution. But it should not replace architecture docs, nor should it replace the separate repository memories of plan closure, logs, bugs, testing, and audit.

What If You Just Need to Look Up an Owner Doc?

This reveals a fundamental difference between the two approaches.

If, in Flux, you simply want to check the current owner contract of the renderer runtime, you can directly route from docs/index.md to docs/architecture/renderer-runtime.md and the relevant references. You do not need to create a change, do not need a proposal, do not need tasks, and do not need to rewrite the question into a spec delta.

If it's just research, it might go into docs/analysis/. If it's just a discovery from manual testing, it goes into docs/testing/ first. If it's a complex bug, it goes into docs/bugs/. If it's an execution closure, then a plan is written. A stable baseline change then goes back to the owner doc.

Flux's document organization is free but not arbitrary. Free means: it does not force all knowledge to first enter the same artifact workflow. Constraint means: each type of material has a clear responsibility and cannot arbitrarily compete for factual status.

OpenSpec's organization is more structured. It is good at putting proposed behavioral changes into a change package and then writing spec deltas back to main specs. But general repository knowledge routing is not the main problem it aims to solve by default.

Tasks Are Not Plans

OpenSpec's tasks.md does not correspond to Flux's plans.

tasks.md at most corresponds to the execution checklist fragment inside a Flux plan, or the todo list of the current session. It can help AI avoid missing steps, but it does not answer these questions:

What is the current live repo baseline?
What is explicitly not being done this time?
What evidence can prove it is truly complete?
Which defects cannot be downgraded to follow-ups?
Who independently verifies the completion status?

The value of a Flux plan is not in "having more tasks," but in it being a closure contract for a local trajectory.

So tasks are necessary for AI, but tasks are not the source of truth. - [x] only indicates that the executor claims an item is complete. The real proof must return to the current code, tests, owner docs, and independent review.

Sources of Change Go Beyond Spec Changes

OpenSpec's path is very clear: organize behavioral spec evolution around specs and changes.

Flux's sources of change are broader:

New requirements raised by users.
Architectural drift discovered by reading source code.
Owner boundary problems discovered by audits.
Interaction problems exposed by testing issues.
Historical regression risks recorded in bug notes.
Design judgments derived from external research or analysis.
A plan closure audit overturning a previous judgment of "completed."

These sources should not all be transformed into spec deltas first. They can first land in analysis, testing, bugs, logs, plans, or directly update architecture docs. Whether they ultimately need to become a behavioral contract depends on whether they are part of the long-term baseline.

This is the significance of Flux's organizational freedom in documentation. Information from different sources first stops at different positions, rather than being shoved entirely into a single spec evolution channel.

Why Files-In, Files-Out Matters

I have emphasized many times in sharing sessions that a best practice for AI-driven development is files-in, files-out. This is not just documentation fastidiousness—the attractor and the harness need a physical carrier.

Files-in: do not leave input only in the chat window. Even if the content is messy, first write it to a requirements file, analysis file, or plan file, and then @ this file in OpenCode.

Files-out: do not end with output just printed in the window. Important conclusions, analyses, plans, test records, bug diagnoses, and architectural constraints are all written into docs/, categorized by responsibility:

Architecture rules → docs/architecture/
Change closures → docs/plans/
Execution trajectory → docs/logs/
Manual testing findings → docs/testing/
Complex defect diagnosis → docs/bugs/
Research judgments → docs/analysis/

The point is not "write more documents." Once output is categorized and persisted, it enters the repository memory. The chat window is temporary context; files are the repository memory.

Code Is the Current Implementation Fact, Not the Only Fact

Code is the source of truth for the current implementation. Types and tests protect the current behavior. The architecture owner docs with precedence define the attractor—the structure the system should converge to over the long term. Logs, bugs, analysis, and testing record the trajectory and externalize memory.

These do not conflict. Conflicts arise in two situations:

When documents start regurgitating implementation details that easily rot.
When the completed state of a document is taken as proof that the code is already correct.

OpenSpec's behavior-first boundary actually avoids the first problem to some extent: behavioral specs should write verifiable behavior, not internal implementation details. Flux further emphasizes the second problem: even if the document describes the correct behavior, it cannot replace the verification of the current repository. True closure must return to code, tests, owner docs, logs, and audit evidence.

The Real Difference

What OpenSpec solves: how to use structured specs/changes/delta/archive to organize the update of behavioral specifications, focusing on the evolution flow of specs.

What AGE solves: when AI rapidly expands the state space, how the system first defines an attractor, and then uses harnesses such as plan, verification, audit, logs, bugs, analysis, and testing to make the trajectory continuously converge.

The two tools solve problems at different levels. OpenSpec's strength is the structured specification workflow. Flux/AGE's strength is using architecture owner docs with precedence to define the attractor, and then using free but responsibility-bounded document routing and a strict closure harness to make the repository converge over the long term.

Moving from spec-driven development to Attractor-Guided Engineering is not moving from "writing specs" back to "not writing specs," but moving from "organizing changes into spec updates" toward "defining where the system should converge over the long term, and making every round of AI generation continuously pulled back by this structure."

What Ordinary Projects Can Directly Adopt

There is no need to copy the full governance of Flux.

First, files-in, files-out. Write input into a file first before @-ing it to AI; output goes into docs/, not left only in the chat window. This step takes just a few minutes, but it gives AI traceable repository memory instead of relying on conversational context.

Second, write an architecture document for the core business that defines the business attractor. Do not write a code guide. Instead, write down the sources of truth, state transitions, ownership boundaries, and common misunderstandings.

Third, write lightweight plans for complex changes. Include the current baseline, goals, what is not being done, an execution checklist, proof items, and closure conditions. Before completion, have an independent session or independent reviewer re-verify.

Fourth, turn recurring problems into repository memory. Manual issues go into testing, complex bugs go into bugs, research conclusions go into analysis, and high-frequency errors go into audit scripts.

Specification updates are a necessary layer. System convergence still needs an attractor.

nop-chaos-flux is open source:

NOP Chaos Flux Architecture Evolution: Rewriting from AMIS to a Modern Low-Code Runtime

canonical — Tue, 19 May 2026 12:57:52 +0000

This article is based on the development logs under docs/logs/2026/ (2026-03-20 to 2026-05-03), sorting out the architectural decisions, module splits, performance optimizations, and platform evolution of the entire framework from zero to maturity. Each phase includes key code paths and document links for traceability.

This article is a collation of historical evolution and implementation trajectory, not a current normative owner doc. For judgments involving current primitive boundaries, action execution model, resource publishing contracts, template instantiation, or package boundaries, the current owner docs and live code pointed to by docs/architecture/README.md shall prevail.

The "key path" filenames appearing in the text are recorded according to the repository state at that time; some paths may have been moved, split, or deleted today and should not be used as current entry indexes.

Preface: Source of Design Ideas

The core design ideas of Flux were not discovered gradually during implementation, but were established as early as the AMIS theory research phase. The two articles under nop-entropy/docs/theory/amis/ — Why Baidu AMIS Framework is an Excellent Design and Revisiting Baidu AMIS Framework and Declarative Programming — laid the theoretical foundation for the entire project:

Env environment abstraction: AMIS's env object virtualizes all I/O operations, making output = AmisPage(Input) possible. Flux's RendererEnv is a modern implementation of this idea.
Api and value/function duality: The Api object is a Ref encapsulation of remote async calls, essentially an asynchronous upgrade of computed. Flux's Resource (data-source) primitive directly inherits this idea.
Data chain = lexical scope: AMIS's data chain is essentially lexical scope lookup at the DSL level. Flux's ScopeRef chain structure is a compile-time enhancement of this model.
xui:import action modularization: The xui:import attribute introduced by the Nop platform for AMIS injects external function libraries into the action system by lexical scope. Flux's xui:imports + ActionScope is a complete compile-time implementation of this mechanism.
Declarative first: From imperative DOM manipulation to reactive data binding to compiled artifact execution — each step increases the proportion of declarativeness. Flux's compile-first principle is the endpoint of this evolution.

Therefore, the architectural evolution of Flux is not "discovering principles during design" but "systematically implementing established principles on a modern technology stack (React 19, Zustand, TypeScript 6.0)". The evolution history records split decisions, performance breakthrough bottlenecks, and contract refinements on the implementation path, not swings in design direction.

The Most Fundamental Shift: From Runtime Interpretation to Compile-Time Execution

The above principles answer "what to design"; the most fundamental implementation shift throughout the evolution is "how to execute":

AMIS is essentially a runtime interpreter — takes a JSON schema, reads and executes it on the fly. Data chain is looked up at runtime, actions are dispatched at runtime, validation is triggered at runtime, field visibility is judged at runtime. All design principles operate at the runtime level.

Flux inserts a compilation phase between DSL and runtime, moving forward various categories of AMIS runtime behavior into compiled artifacts:

AMIS Runtime Behavior	Flux Compiled Artifact
Runtime type judgment of values	`CompiledValueNode` five static node types
Runtime traversal of schema structure	`TemplateNode` immutable graph (compile once, instantiate multiple times)
Runtime resolution of actions	`CompiledActionProgram` / `CompiledActionNode` IR
Runtime wiring of host contracts	`CapabilityProjectionManifest` compile-time visible and verifiable
Runtime exposure of schema problems	Compile-time diagnostics (unknown attributes, contract shape validation)

This shift was not completed at once but runs through the entire evolution process as the main thread: from value compilation (03-25) to template instantiation (04-07) to action pre-compilation (04-20) to compiler package extraction (04-21) — each step is a milestone on the same path of "moving runtime judgment forward to compile time". The final three-layer split of flux-compiler / flux-action-core / flux-runtime is the physical form of this shift: the compiler is responsible for producing immutable artifacts, and the runtime only consumes and instantiates them.

Phase 1: Core Concept Establishment and Package Structure Setup
Phase 2: Flow Designer from Proof of Concept to Production-Grade
Phase 3: Renaming, Styling System, and Component Migration
Phase 4: Complex Renderers and Architecture Audit
Phase 5: Code Audit and Quality Convergence
Phase 6: Runtime Architecture Convergence and Performance Optimization
Phase 7: Frontend Programming Model Finalization and In-depth Design
Phase 8: Template Instantiation and Node Identity System
Phase 9: Deep Audit, Performance Optimization, and Architecture Convergence
Phase 10: Compiler Independence and Package Boundary Hardening
Phase 11: Comprehensive Quality Convergence and Host Maturity
Key Principles of Architectural Evolution
Appendix: Timeline Overview

1. Phase 1: Core Concept Establishment and Package Structure Setup

Time: 2026-03-20 ~ 2026-03-23

On 03-20, systematic bug analysis and first-round fixes of the early Flux runtime were completed (dual-state desynchronization, concurrent submit race, validation coverage, etc.). On the same day, @nop-chaos/amis-debugger (later renamed nop-debugger) was created, positioned from the start as an AI-first structured diagnostic tool.

1.1 Action Scope and Import Semantics

docs/architecture/action-scope-and-imports.md established one of the most core conceptual layers of Flux:

ScopeRef is a pure data scope, only carrying data reads/writes.
ActionScope is a capability scope, carrying namespaced actions and imported library capabilities.
xui:import is declarative import semantics (order-independent, repeatable, deduplicated by normalized key), not execution order semantics.

The dispatch path is fixed as: built-in → component:<method> → namespaced action.

1.2 Flow Designer Package Creation

The two packages @nop-chaos/flow-designer-core and @nop-chaos/flow-designer-renderers were created in this phase. Core contains the pure graph runtime (GraphDocument, GraphNode, GraphEdge, DesignerConfig), and Renderers contains renderer definitions for designer-page, designer-field, designer-canvas, designer-palette.

1.3 Collaborative Documentation System

The complexity of Flow Designer gave birth to a layered documentation system:

docs/architecture/flow-designer/design.md — target architecture
docs/architecture/flow-designer/runtime-snapshot.md — current implementation snapshot
docs/architecture/flow-designer/collaboration.md — runtime collaboration boundaries
docs/architecture/flow-designer/canvas-adapters.md — canvas adapter boundaries

Key decision: Split documentation into "target state" and "snapshot state" to avoid confusion between target architecture and current implementation.

Key paths: packages/flux-runtime/src/action-runtime.ts, packages/flow-designer-core/src/core.ts, docs/architecture/action-scope-and-imports.md

2. Phase 2: Flow Designer from Proof of Concept to Production-Grade

Time: 2026-03-23 ~ 2026-03-27

2.1 Canvas Bridge Pattern

Introduced the DesignerCardCanvasBridge contract, abstracting canvas interactions (select, delete, move, connect, reconnect, viewport sync) as bridge callbacks, allowing the card canvas and XYFlow canvas to share the same command adapter.

Renderer UI Events → Bridge Callbacks → Command Adapter → Core Mutations

Key decision: Replacing the canvas renderer does not require reintroducing direct graph mutation paths. All mutations go through the shared command adapter.

2.2 Command Adapter

designer-command-adapter.ts introduced a target-side command normalization layer, providing a unified result shape of ok/snapshot/data/error/reason. Both Provider and canvas bridge dispatch commands through this surface, avoiding fragmented semantic rejection logic.

2.3 Schema-Driven Designer

Flow Designer completed the migration from hardcoded React components to JSON configuration-driven. Node/edge rendering is defined through the body: SchemaInput field, allowing complex node appearances to be composed using AMIS schemas such as flex, container, tpl, icon. classAliases and themeStyles enable theme customizability.

2.4 Production-Grade Visual Alignment

Completed visual alignment with the flow-editor-static.html prototype, unifying node two-line semantics, selection states, palette icon chips, quick action buttons, edge/label tokens, minimap anchor positions, etc.

Key paths: packages/flow-designer-renderers/src/canvas-bridge.tsx, packages/flow-designer-renderers/src/designer-command-adapter.ts, apps/playground/src/schemas/workflow-designer-schema.json

3. Phase 3: Renaming, Styling System, and Component Migration

Time: 2026-03-25 ~ 2026-03-29

3.1 AMIS → Flux Renaming

Comprehensively migrated package references and documentation from the AMIS namespace to the Flux namespace:

amis-schema → flux-core
amis-runtime → flux-runtime
amis-react → flux-react
amis-debugger → nop-debugger
Window global variables renamed from __NOP_AMIS_* to __NOP_FLUX_*

3.2 flux-core Modular Split

packages/flux-core/src/index.ts (1183 lines) was split into a modular structure:

types.ts (687 lines) — all type definitions
validation-model.ts (174 lines) — validation model functions
utils/object.ts — object utilities
utils/path.ts — path utilities
utils/schema.ts — schema utilities
constants.ts — constants

3.3 Styling System Established

docs/architecture/styling-system.md established a TailwindCSS-first styling solution:

Semantic attributes (direction, gap, align) as syntactic sugar for Tailwind classes
classAliases mechanism for reusable Tailwind class definitions, supporting nested alias expansion and scope inheritance
Layout renderers only emit marker classes (nop-container, nop-flex), marker classes carry no visual styling
Spacing explicitly declared in schema via stack-*/hstack-* aliases

3.4 shadcn/ui Migration

Created @nop-chaos/ui package, based on the shadcn/ui component library pattern (class-variance-authority + tailwind-merge + lucide-react), migrating the underlying layer from radix-ui to base-ui:

Button, Input as first migrated components
Gradually covering the full component set: Textarea, Checkbox, Switch, RadioGroup, Select, Dialog, Tabs, Table, Card, etc.
First batch of renderers (Button, Input, Form) migrated to @nop-chaos/ui, subsequent renderers follow in batches

3.5 RendererComponentProps Contract

Established the RendererComponentProps pattern that all renderers must follow:

Data Source	Provides	Purpose
`props.props`	Compiled runtime values	Schema-driven values
`props.meta`	Compiled metadata	Control state
`props.regions`	Pre-compiled child render handles	Render child fragments
`props.events`	Runtime event handlers	Event binding
`props.helpers`	Stable runtime helpers	dispatch, evaluate

3.6 FieldFrame and Renderer Wrapping Contract

The FieldFrame component was introduced into the flux-react layer to uniformly handle form label/error/hint wrapping. The RendererDefinition.wrap flag lets NodeRenderer automatically add labels and error displays for renderers that need field wrapping.

3.7 Report Designer and Spreadsheet Migration

Migrated four packages from nop-chaos-next into the workspace (completed 03-25):

@nop-chaos/spreadsheet-core / spreadsheet-renderers
@nop-chaos/report-designer-core / report-designer-renderers

Integrated workspace configuration (tsconfig references, path aliases, Vite aliases), fixed runtime/test issues, ensured all tests pass.

3.8 testid and Architecture Consistency

On 03-29, added the testid field to BaseSchema, propagated through the compilation→parsing pipeline, all production renderers apply data-testid to the root element. On the same day, completed an architecture consistency audit, discovering issues such as implicit layout injection by renderers, validation trigger semantic drift, theme token naming drift, etc., and established a two-phase fix strategy.

Key paths: packages/ui/src/, docs/architecture/styling-system.md, packages/flux-react/src/field-frame.tsx, packages/spreadsheet-renderers/src/, packages/report-designer-renderers/src/

4. Phase 4: Complex Renderers and Architecture Audit

Time: 2026-03-28 ~ 2026-03-31

4.1 Full shadcn/ui Migration

On 03-28, completed the full migration of the shadcn/ui component library. The @nop-chaos/ui package expanded to cover the full suite of components including Inputs/fields, Overlay, Layout/feedback, etc. Flow Designer, form renderers, code editor, etc., fully switched to shadcn/ui components.

4.2 Code Editor Package

On 03-30, @nop-chaos/flux-code-editor was created based on CodeMirror 6, unifying the expression editor and SQL editor. Features include: support for 8 languages, expression/SQL completion, expression validation, friendly name tagging, template mode, fullscreen toggle, light/dark themes. Subsequently on 03-31, SQL enhancements (formatting, snippet templates, variable panel, SQL execution result preview) were completed.

4.3 Condition Builder

On 03-30, a complete condition-builder renderer was implemented in flux-renderers-form, supporting embedded/selector mode, AND/OR/NOT logic, field search, grouping, unique fields, nested groups, custom operators.

4.4 Word Editor Package

On 03-31, @nop-chaos/word-editor-core (framework-agnostic bridge layer with zero React dependencies + Store) and @nop-chaos/word-editor-renderers (EditorCanvas, RibbonToolbar, FontControls, WordEditorPage) were created. Integrated @hufe921/canvas-editor as the canvas rendering engine, with template expressions stored as hyperlinks. On the same day, completed Phase 1 basic editor integration and Phase 1~4 toolbar controls.

4.5 Architecture Audit

On 03-31, conducted a comprehensive audit of core packages (flux-core, flux-runtime, flux-react, flux-formula, 3 renderer packages), analyzing approximately 32,000 lines of non-test source code. Findings: flux-core's design is correct (it is a base package containing shared pure utilities, not a pure types package), form-runtime has been decomposed into 10 sub-modules, and the dependency flow is clean.

Key paths: packages/ui/src/, packages/flux-code-editor/src/, packages/word-editor-core/src/

5. Phase 5: Code Audit and Quality Convergence

Time: 2026-04-01 ~ 2026-04-03

5.1 Code Audit Fix Plan (Plan #25)

Executed 14 fixes covering 8 packages:

Build hygiene: Removed stale tsconfig include paths, created scripts/verify-no-src-artifacts.mjs CI guard
Logical correctness: Fixed Flow Designer allowMultiEdge logic error, unified executeApiObject() request pipeline
Defensive fixes: Wrapped NodeRenderer with React.memo, added boundary protection for evaluateArray/evaluateObject
Performance optimizations: API cache LRU eviction, Proxy cache WeakMap

5.2 Comprehensive Code Overhaul (Plan #27)

Executed comprehensive code overhaul including:

Render phase remains side-effect free
Form path state relatedPaths fix
Extracted shared hook for form field controller
Dynamic renderer API payload validation
Changed root component registry from module-level mutable state to instance-level state
Added change detection to ScopeRef.merge() method

5.3 Data Source Redesign

DataSourceSchema removed the body region, instead injecting data into the current scope. If dataPath is set, the response is written to scope[dataPath]; otherwise, the response is merged as a plain object into the current scope.

5.4 useOwnScopeSelector Dual Hooks and Full Adoption of @nop-chaos/ui

On 04-03, flux-react exposed useOwnScopeSelector() in parallel with the lexical useScopeSelector(). Report Designer shell renderers migrated to the own-scope hook, consuming only fragment host data. On the same day, completed adoption migration of word-editor-renderers, report-designer-renderers, spreadsheet-renderers to @nop-chaos/ui.

5.5 Dependency and Lint Upgrades

From 04-02 to 04-03, the workspace upgraded to eslint-plugin-react-hooks recommended-latest strict rule set (later deepened on 04-16 to React 19 strict lint baseline), completed Lucide React patch fixes, and cleaned up all build artifact leaks in src/ directories.

Key paths: packages/flux-runtime/src/request-runtime.ts, packages/flux-renderers-data/src/data-source-renderer.tsx, scripts/verify-no-src-artifacts.mjs

6. Phase 6: Runtime Architecture Convergence and Performance Optimization

Time: 2026-04-04 ~ 2026-04-06

6.1 Formily Comparative Analysis and Performance Direction

Completed a detailed comparison with 10+ low-code platforms (AMIS, Formily, LowCode Engine, Appsmith, ToolJet, Retool, etc.). Core findings:

The reactivity model is the most critical shortcoming: The current Pull Model triggers evaluation of O(number of nodes × number of expressions) on parent scope changes, whereas Formily's Push Model is O(number of dependents)
Flux's AOT compilation, orthogonal scope design, and field metadata-driven compilation are unique architectural advantages
Decision: Maintain Flux's compile-first general-purpose platform baseline, allowing only thin local capability extensions in the form subdomain

6.2 Dependency Tracking and Change Path Notification

Implemented ScopeChange dependency tracking baseline:

ScopeStore carries ScopeChange (set of changed paths)
Formula leaf evaluation refreshes dependency set after each successful run
NodeRenderer subscriptions gate metadata/property recomputation through dependency path intersection
Later evolved into lexical root binding model: dependency tracking converges to lexical roots like user, row, record

6.3 Source Registry and Reaction Runtime

Source Registry (source-registry.ts): RendererRuntime exposes registerDataSource(...), sources are bucketed by ScopeRef.id, the data-source renderer is only responsible for registration/release lifecycle
Reaction Runtime (reaction-runtime.ts): ReactionSchema supports watch, when, immediate, debounce, once, reaction execution async scheduling occurs after writes stabilize
Self-cascade protection: Queued reaction triggers merge change paths by pending turn, self-cascading reactions hard-stop after a limited number of times

6.4 Action Control Flow Extensions

The action system added when/parallel/timeout/retry:

when: Precondition check, returns structured skip result if false
parallel: Promise.all parallel execution
timeout: Structured timeout result, cancelable request-like actions participate in actual cancellation
retry: Retry strategy with fixed attempts/fixed delay

6.5 Complex Renderer State Ownership

On 04-05, the Table renderer introduced a local/controlled two-level state ownership model, extended to three levels on 04-06 with the addition of scope mode:

local (default) — internal renderer state
controlled — external schema/runtime driven
scope (added 04-06) — reads/writes reactive state directly from the current rendering scope

6.6 Frontend Programming Model Documentation

docs/architecture/frontend-programming-model.md was established as the top-level architecture baseline document, defining Flux's seven core primitives (at that time the first primitive was still called Base Tree, officially renamed to Template on 04-21). The seven primitives are: Template (formerly Base Tree), ScopeRef, Value, Resource, Reaction, Capability, Host Projection.

6.7 WorkbenchShell Extraction

On 04-04, extracted the shared WorkbenchShell React component from various designers into packages/flux-react/src/workbench/. The page renderers of Flow Designer and Report Designer migrated from handwritten three-column layouts to the unified WorkbenchShell. Shell is purely presentational, carrying no Flux scope or domain knowledge.

Key paths: packages/flux-runtime/src/source-registry.ts, packages/flux-runtime/src/reaction-runtime.ts, packages/flux-runtime/src/action-runtime.ts, packages/flux-react/src/workbench/workbench-shell.tsx, docs/architecture/frontend-programming-model.md

7. Phase 7: Frontend Programming Model Finalization and In-depth Design

Time: 2026-04-06 ~ 2026-04-11

Note: This phase had parallel work with Phase 8 (Template Instantiation), with overlapping dates.

7.1 Programming Model Evolution Discussions

After multiple rounds of in-depth discussions (8 rounds of discussion recorded in docs/discussions/2026-04-06-programming-model-optimality-critique.md), finally established:

Keep the seven primitives closed, do not introduce an alternative primitive system
Understand data-source as "registering a named dynamic value into scope"
name as the sole normalized publication path, mergeToScope: true as the only special publication mode
Action semantics (when + then + onError + parallel) already form a DAG at execution time
Distinguish between "progressive authoring surface" and "DAG execution semantics"

7.2 Action/API Convergence Construction

Renamed declarative request from ApiObject to ApiSchema
type: 'source' as an action-based anonymous value consumption form
data-source as the named/dispatch extension of source
Standardized built-in action naming to camelCase (openDialog, showToast)

7.3 Validation System In-depth Design

On 04-11, completed a unified validation design (docs/analysis/2026-04-11-flux-validation-unified-design.md), covering:

modelGeneration counter to track validation model replacements
Async run identity quintuple (ownerId, modelGeneration, path, ruleId, runGeneration)
Two lifecycle paths: owner-compatible model refresh vs. owner boundary change
State retention rules: always reset materialized caches and async runs

7.4 Form Linkage and Hidden Field Policy

On 04-11, fully implemented the HiddenFieldPolicy contract (Plan 67): clearValueWhenHidden, validatePath skipping, notifyFieldHidden, 21 new tests.
Constraint-based declarative linkage (xui:linkage) compiled into existing node metadata/properties and validation flow.
Field presentation snapshot (effectiveDisabled/effectiveRequired).

7.5 Owner Status Model

On 04-09, unified loading/pending/status as owner-specific read-only summaries:

Internal form expressions standardized to $form binding
Cross-form observers standardized to explicit statusPath
Surface owners (dialog/drawer) expose external read-only status via statusPath

7.6 Component Documentation System and xui:imports Expression Projection

On 04-07, established the docs/components/ component documentation system, each component directory carries design.md + example.json, distinguishing registered renderers from planned renderers. Component naming standardized to Flux native vocabulary rather than AMIS legacy names.

On the same day, completed xui:imports expression projection; import aliases can now be used in expressions as $alias.method(...), sharing the same import namespace provider mapping as the existing namespace:method action dispatch.

Key paths: docs/architecture/frontend-programming-model.md, docs/architecture/api-data-source.md, docs/architecture/action-scope-and-imports.md

8. Phase 8: Template Instantiation and Node Identity System

Time: 2026-04-07 ~ 2026-04-08

8.1 Template Instantiation Architecture

docs/architecture/template-instantiation-and-node-identity.md established the architecture of "compile the template once, instantiate it multiple times at runtime":

cid is strictly a mount-time active node bridge ID
Structure resolution belongs to the runtime-owned resolver
Canonical runtime address as NodeLocator = runtimeId + templateGraphId + templateNodeId + instancePath

8.2 Repeated Instance Identity Propagation

Table row child rendering (cell, buttons, expanded) passes in [{ repeatedTemplateId: 'table.row', instanceKey: rowKey }], row child debug locator data can now see the real instancePath.

8.3 NodeRenderer Compatibility Migration

Through Plan 40, gradually migrated CompiledSchemaNode dependencies to NodeInstance/templateNode:

NodeFrameWrapper consumes templateNode + explicit renderer wrap metadata
RendererComponentProps and useCurrentNodeMeta() mirror templateNode + optional locator
Fragment/dialog ownership seams migrated to active-node-first fallback

8.4 Compiler-Integrated Diagnostics

Plan 41 implemented compiler-integrated schema diagnostics:

flux-core exposes a formal schema diagnostic contract
CompileSchemaOptions carries diagnostic/validation policy
RendererDefinition can contribute schemaValidator
Form and table renderers contributed renderer-owned schema validator checks

8.5 BEM Migration Completed

All internal __ markers cleaned up, field framework, code editor, spreadsheet/report designer, workbench areas migrated to data-slot/data-*.

Key paths: docs/architecture/template-instantiation-and-node-identity.md, packages/flux-react/src/node-instance.ts, packages/flux-runtime/src/node-resolver.ts

9. Phase 9: Deep Audit, Performance Optimization, and Architecture Convergence

Time: 2026-04-12 ~ 2026-04-20

Note: This phase was the highest-density convergence period of the entire project, with code changes, document audits, performance optimizations, and architectural decisions densely interwoven.

9.1 Architecture Document Consistency Audit and Governance System Maturation

On 04-12, completed the first full-scope architecture document consistency audit, checking all files under docs/architecture/ for consistency with code and with each other. Discovered cross-document conflicts (Final Execution Schema wording, node identity model, xui:imports boundaries, style contract drift, etc.), established a repair strategy sharded by document family.

This phase also marked the formal maturation of Flux's unique development governance method:

First write owner doc (target state architecture document)
Then write execution plan
Write daily log after execution
Finally use an independent sub-audit to confirm closure

Many subsequent Plans (73~121) followed this method.

9.2 Plan 82: Architecture Contract Implementation Convergence

Plan 82 was the core convergence plan from 04-12 to 04-14, covering multiple parallel contract alignment threads:

xui:imports node lifecycle tightening (Phase 5): The creation of ActionScope for import declaration nodes and namespace registration began to separate from renderer policies; module loading deduplication and scope namespace lifecycle initially became independent. The final import-owned boundary was finalized in Plan 133 on 04-23 (see Phase 10, 10.3)
Surface family extraction (Phase 5): dialog/drawer state extracted from page.store into independent SurfaceStore, SurfaceRuntime became the unified owner for dialog/drawer/surface
Value adaptation contract convergence (Phase 6): detail-field, detail-view, object-field, array-field, variant-field gradually aligned to shared value-adaptation helper and unified scope model
Architecture narrowing decision: After multiple rounds of implementation attempts, the architecture documentation clearly positioned object-field, array-field, variant-field as inline live-edit controls (editing directly writes to parent form), only detail-field/detail-view retain staged owner semantics (confirm/cancel boundaries)

9.3 ScopeRef Read-Write Separation and Per-Path Subscription

From 04-14 to 04-15, performed a major refactoring of ScopeRef's core APIs:

read() → readVisible() + materializeVisible() (Plan 89): readVisible() uses the prototype chain to provide a lazy lexical view; materializeVisible() is called only at explicit flattening boundaries (formula broad-access, debugger dump, request includeScope: '*')
Per-path fine-grained subscription (Plan 90): FormStore added a subscribeToPath(path) mechanism; keystrokes on field A no longer wake subscribers of field B, achieving O(1) field-level invalidation
Host Projection scope base (Plan 87): RendererRuntime.createHostProjectionScope(...) moved the read-only/write-protection boundary of host projection from React hooks into a shared runtime contract

9.4 Performance Optimization Series (Plans 100~110)

On 04-16, executed an entire performance optimization plan series, from audit to per-package implementation:

Playground loading and bundle boundaries (Plan 102)
Flux React hot path fixes (Plan 103): NodeRenderer useSyncExternalStore selector stabilization, ClassAliasesContext broadcast debouncing
Formula runtime hot path (Plan 104)
Spreadsheet performance and virtualization (Plan 105): setCells() batch operations, grid virtualization (binary search for visible range), requestAnimationFrame batch selection/fill/zoom
Runtime and form invalidation performance (Plan 106): parallel field validation, computeScopeState caching, publishStatus skip unchanged updates
Collection renderer scalability (Plan 107): table viewport-driven virtualization (threshold 50 rows, overscan 10), row scope cache changed from full clone to in-place mutation + generation counter
Form field consumer performance (Plan 108): useBoundFieldValue() uses UNUSED_VALUE sentinel selector to avoid inactive subscriptions
Flow Designer performance hygiene (Plan 109): node synchronization reduced from O(n²) to O(n)
API request and cache hygiene (Plan 110): source refresh O(1) name indexing, polling changed from setInterval to setTimeout chain

9.5 @nop-chaos/flux-renderers-form-advanced Split

On 04-16, split 11 advanced renderers from flux-renderers-form (~15,800 lines) into the new @nop-chaos/flux-renderers-form-advanced package: condition-builder, variant-field, detail-view, detail-field, object-field, array-field, array-editor, tag-list, key-value, etc. flux-renderers-form was reduced to ~3,000 lines. Dependency direction confirmed as form-advanced → form → basic (no cycles).

9.6 Capability Projection Manifest

On 04-16, introduced the Capability Projection Manifest architecture (Plan 112), upgrading host protocols from runtime wiring conventions to compile-time visible and verifiable static contracts:

HostCapabilityProjectionManifest declares host projection fields and namespaced capability methods
RendererDefinition.hostContract lets renderer definitions carry host contract metadata
Flow Designer as the first pilot, declaring 30 designer:* methods
Compiler-integrated diagnostics: validateActionShape() can now validate host action parameter shapes

9.7 @nop-chaos/flux-i18n Internationalization Package

On 04-17, created the @nop-chaos/flux-i18n package, based on i18next and react-i18next, supporting zh-CN (default) and en-US. All translation keys use the flux. prefix. Subsequently migrated hardcoded strings from packages like condition-builder, report-designer, code-editor, form-advanced to t() calls, upgrading the ESLint i18next/no-literal-string rule from warn to error, ensuring that new hardcoded strings cause build failures.

9.8 ValueAdapter Unified Protocol

On 04-20, docs/architecture/value-adaptation-and-detail-field.md established ValueAdapter as the canonical shared protocol (Plan 121):

Simple fields use declarative adapters: stringAdapter(), booleanStringAdapter(), array adapters
Composite owners (object-field, variant-field) uniformly connect to actionAdapter() for transformInAction / transformOutAction
Staged helpers of detail-field/detail-view internally delegate to actionAdapter(), keeping the public API unchanged
ValueAdapter becomes the standard access method for new value-oriented fields, replacing JSX local type conversions

9.9 CompiledSchemaNode Complete Elimination

On 04-16, the compilation pipeline no longer passes through the CompiledSchemaNode intermediate layer, directly generating TemplateNode from SchemaInput. CompiledSchemaMeta and CompiledNodeRuntimeState were demoted to type aliases. This cleanup simplified the compilation pipeline and eliminated an indirection layer that no longer held value after the template/instance separation landed.

9.10 Renderers Contract Unified Static Metadata

On 04-20 (Plan 117), added unified static contract fields to RendererDefinition: rendererClass, rendererTraits, propContracts, eventContracts, componentCapabilityContracts, scopeExportContracts. propContracts immediately participates in compiler unknown attribute checking; the remaining fields are reserved for tooling (Inspector, online editor). button, form, crud, designer-page served as the first pilots.

9.11 Action Pre-compilation and Async Governance

On 04-20 (Plans 119~120), pushed the action system into the compile phase:

CompiledActionProgram IR: compileAction() compiles ActionSchema to CompiledActionProgram/CompiledActionNode; the runtime executor no longer mixes raw schema execution paths internally
Async governance convergence: Shared async-governance.ts base unified the run identity, stale publish gating, and debug diagnostics for three categories of async runtime owners: data-source, reaction, and async validation

9.12 Documentation Governance and Deep Audits

From 04-12 to 04-19, multiple rounds of deep audits were produced (12 audit dimensions covering API surface, state ownership, reactivity precision, async safety, validation consistency, renderer contracts, style compliance, field slot modeling, lifecycle, etc.). After each audit, only true defects still reproducible in the current code were fixed, avoiding over-fixing.

Key paths: packages/flux-core/src/value-adapter.ts, packages/flux-runtime/src/async-governance.ts, packages/flux-runtime/src/action-compiler.ts, packages/flux-i18n/src/, packages/flux-renderers-form-advanced/

10. Phase 10: Compiler Independence and Package Boundary Hardening

Time: 2026-04-21 ~ 2026-04-25

10.1 Compiler Package Extraction

Extracted the @nop-chaos/flux-compiler package from flux-runtime:

Schema compilation/validation
Action pre-compilation
Compilation symbol table
Diagnostics and validation lowering
flux-runtime briefly retained a compatibility re-export layer (removed in Plan 124 on 04-22; runtime side no longer holds any compiler code)

10.2 Action Core Package Extraction

On 04-22, further extracted the @nop-chaos/flux-action-core package from flux-runtime, with ActionRuntimeAdapter becoming the unified action invocation boundary. By this step, Flux completed a three-layer split:

flux-compiler responsible for "turning schema into executable artifacts"
flux-action-core responsible for "action dispatching, control flow, and unified invocation exit"
flux-runtime responsible for "connecting compiled artifacts with the host environment and holding lifecycle"

10.3 Import Boundary Semantic Convergence

On 04-23, the creation of ActionScope for xui:imports was separated from renderer policy into import-owned boundary semantics (Plan 133). Module loading deduplication and scope namespace registration operate independently; import lifecycle and compile-time diagnostics participate in the compilation pipeline, completing the second phase of the ActionScope / xui:imports model proposed in late March.

On the same day, Plan 132 eliminated runtime fallback reads of raw Schema objects — DataSource and Reaction fully migrated to compiled data; the runtime no longer holds uncompiled schemas. This is a direct manifestation of the compile-forward mainline.

10.4 Base Tree → Template Renaming

On 04-21, the first primitive of the programming model was renamed from Base Tree to Template, emphasizing its nature as a compile-time immutable program definition. SchemaCompiler produces an immutable TemplateNode graph; the runtime only consumes and instantiates.

10.5 Data Domain Owner Architecture

On 04-22, the Data Domain Owner concept was formally elevated to an architecture baseline document (docs/architecture/data-domain-owner.md). object-field, array-field, variant-field aligned to the Data Domain Owner baseline — composite fields become explicit data domain owners, with clear value adaptation, validation coordination, and sub-scope lifecycle. This complements the staged owner semantics of detail-field/detail-view: two ownership models (inline live-edit vs. staged confirm/cancel boundaries) cover all composite field paradigms.

10.6 DingFlow Tree Mode

Introduced a structured process tree contract: nodes can have branch groups, branches implicitly merge, continuation flow enters the downstream child of the owner node. In tree mode, free connections, free reconnections, and manual node dragging are disabled.

10.7 CRUD Contract Finalization and Shared Context Menu

The design and implementation of CRUD spanned multiple phases: component contract document completed on 04-12 (docs/components/crud/design.md), entered implementation around 04-17, and completed interaction and contract finalization on 04-24 ~ 04-25:

CRUD selection summary and refresh behavior stabilized
Spreadsheet shared context menu baseline (copy, cut, paste, clear, insert/delete rows/columns)
Double-click fill handle uses adjacent data region for auto-fill down

On 04-25, Plan 139 removed the DataSourceSchema.api field; all remote calls are uniformly dispatched via { action: 'ajax', args: ... }. ApiSchema is explicitly defined as a transport contract used internally by the ajax action; author side no longer directly touches independent API definitions — the convergence from independent execution paths to unified action dispatch is completed here.

Key paths: packages/flux-compiler/src/, packages/flux-action-core/src/, docs/architecture/flux-runtime-module-boundaries.md, docs/architecture/capability-projection-manifest.md

11. Phase 11: Comprehensive Quality Convergence and Host Maturity

Time: 2026-04-25 ~ 2026-05-03

Note: This phase was the second high-density convergence period after Phase 9 (04-12~04-20), but the focus shifted from "architecture contract alignment" to "comprehensive quality convergence" — performance audit, test institutionalization, adversarial security review, validation owner boundary precision, host tooling engineering. If Phase 9 answered "is the architecture right?", Phase 11 answered "is the implementation robust enough".

11a. Performance Audit and Hot Path Optimization (04-26)

Conducted in-depth performance audits on four hot paths: runtime, form, spreadsheet, report-designer:

Eliminated JSON.stringify full-value comparisons: Form valuesPath publication used JSON.stringify for change detection, incurring significant serialization overhead in high-field-count forms. Replaced with path-aware structural comparison.
Spreadsheet batch writes: Batch operations like paste/cut changed from per-cell full Map cloning to setCells() batch interface, eliminating O(n) immutable clone overhead.
Condition-builder recursive structural equality: Condition builder used JSON.stringify for value comparison; replaced with recursive structural equality function, avoiding stringification overhead and key-order sensitivity.
Path-aware form value subscription: useCurrentFormState added an optional { path: name } parameter; field-level subscribers are woken only when the specified path changes, eliminating cascading re-renders of unrelated fields.
Full adoption in advanced form renderers: Path-aware subscription extended to all advanced form renderers including object-field, array-field, detail-field, variant-field, array-editor, key-value, etc.

11b. Test Coverage Institutionalization and Deep Audit (04-26 ~ 04-27)

Plan 143: Coverage threshold institutionalization

Enforced 80% Vitest coverage thresholds in all core package configurations. Systematically closed coverage gaps in the following packages:

flux-runtime, flux-react, flux-renderers-data
flux-renderers-form, flux-renderers-form-advanced, flux-renderers-basic
flux-formula

First 18-dimensional deep audit (04-27)

Full-dimensional audit covering 24 packages, discovering 1 P0, 16 P1, 28 P2, 36 P3 issues. Audit dimensions included:

Architecture consistency, state ownership, async safety, reactivity precision
Host contracts, test quality, accessibility, security
Performance, boundary clarity, dependency direction, API surface stability
Documentation synchronization, type safety, error handling, internationalization, observability, extensibility

11c. Renderer Contract and Host Projection Convergence (04-26 ~ 04-30)

Plan 145: runtime/react/renderer hot spot boundary convergence

Extracted shared helper functions, established projected-owner scope base, CRUD owner bridging, Flow Designer page-shell/adapter split. Cross-package dependencies in renderer hot paths converged to explicit contracts.

Plan 146: Domain-host projection and lexical convergence

Word Editor real-time save vs. auto-save timing semantics clarified
Report Designer standardized selection vocabulary
Host projection interfaces of various domain designers aligned to a unified baseline

Plan 144: Execution boundary diagnostics and host contract tooling

Diagnostic information carries source location, supporting precise jumping from runtime errors to schema definition locations
Host contract manifest tooling, supporting automated contract checking

Plan 150: xui:actions — Schema-local named action chains

Introduced the xui:actions attribute, allowing declaration of named action chains on schema nodes:

__xui_actions__ synthetic namespace carries schema-local action definitions
Lexical inheritance: child nodes inherit xui:actions from the parent scope, sharing the same namespace resolution mechanism as xui:imports
Action chains support when/then/onError control flow

11d. Adversarial Review and Security Hardening (05-01 ~ 05-02)

Conducted an adversarial review of the entire codebase (24 packages), covering compiler-runtime contract consistency, reaction cascade depth, scope dangerous key filtering, formula parser/evaluator depth limits, form validation resilience, accessibility.

Key fixes:

$Date symbol table fix: Completed from 7 methods to 14 methods, covering all date operations
booleanStringAdapter("false") fix: Boolean("false") pitfall — the string "false" is truthy in JavaScript; adapter must explicitly parse
Action compilation depth limit: MAX_ACTION_COMPILE_DEPTH=128 to prevent malicious nested action chains from causing compile stack overflow
Scope snapshot sanitization: sanitizeSnapshot() blocks prototype pollution keys like __proto__, constructor, prototype
Formula parser depth limit: MAX_PARSER_DEPTH=256, MAX_EVAL_DEPTH=256 to prevent deeply nested expression attacks

11e. Validation Owner Boundary Convergence (04-30 ~ 05-03)

The validation owner boundary underwent three stages of precision refinement, finally forming a clear ownership hierarchy:

Plan 157: validation owner boundary

formId becomes a true targeting carrier, no longer just an identifier
submitWhenHidden semantics removed — submission behavior of hidden fields is uniformly controlled by the owner
Registration identity maintains path-singleton: registrations on the same path are automatically replaced, no duplication

Plan 163: core boundary

flux-core completely removes React type dependencies, becoming a pure TypeScript package
flux-react owns the reactComponent convenience path
Surface runtime creates an independent validation owner for each surface, achieving validation isolation

Plan 168: validation owner convergence

formId resolution path unified
validateOn: 'change' no longer gates on touched — validation on change, orthogonal to touched state
Summary-gate enforcement during submission: collect all validation summaries on submit, block until all pass

Plan 174: Strict Validation Mode

Schema authors can enable strict compilation mode, causing the compiler to report unknown attributes. This mechanism fills the last piece of schema validation: from "compiler ignores unknown attributes" to "unknown attributes are compile errors in strict mode".

Final Validation Owner Hierarchy:

Owner Level	Coverage	Typical Scenario
form	All fields within the form	Main form submission
page-root	Page-level validation	Page-level linkage constraints
surface	Independent validation domain within dialog/drawer	Popup form independent submission
detail-child	Sub-validation domain within staged owner	Detail row edit confirm/cancel boundary

11f. Host Tooling and Engineering (04-30)

Turborepo introduction

Turborepo as the workspace task runner, enabling parallel execution of build/typecheck/test/lint. The task dependency graph is automatically topologically sorted by Turborepo, eliminating manual orchestration scripts.

Repository-level audit toolchain

dependency-cruiser: Dependency direction validation, preventing circular dependencies and illegal cross-layer references
knip: Dead code detection, identifying unused exports, types, and dependencies
Stryker: Mutation testing pilot, validating the effectiveness of test suites
Semgrep: Static security scanning, detecting known unsafe patterns

Bundle analysis

Support for pnpm analyze via rollup-plugin-visualizer, visualizing bundle composition of each package, helping identify size regressions and unexpected dependencies.

Key paths: packages/flux-runtime/src/form-runtime.ts, packages/spreadsheet-core/src/, packages/flux-formula/src/, packages/flux-core/src/, docs/plans/143-*, docs/plans/145-*, docs/plans/157-*, docs/plans/163-*, docs/plans/168-*

12. Key Principles of Architectural Evolution

Looking across the evolution history from 2026-03-20 to 2026-05-03, the following principles repeatedly appear in key decisions:

12.1 Compile First

Flux always does as much work as possible at compile time: value classification, expression compilation, action pre-compilation, schema diagnostics. The runtime only executes compiled artifacts and makes no additional judgments. This principle runs from the five node types of CompiledValueNode through the TemplateNode/NodeInstance separation.

12.2 Data and Capability Separation

ScopeRef purely carries data, ActionScope purely carries capabilities; they are orthogonally separated. This decision avoids turning ScopeRef into a general-purpose method registry, keeping the scope model simple.

12.3 Renderer Contract Consistency

All renderers follow the unified RendererComponentProps pattern, with data coming from props.props/props.meta/props.regions/props.events/props.helpers, and do not directly access stores. This ensures renderer replaceability and testability.

12.4 Marker Classes Carry No Styling

Layout renderers only emit semantic marker classes (nop-container, nop-flex); marker classes carry no visual styling. All spacing/direction/padding is explicitly declared via classAliases or semantic attributes in the schema. This avoids implicit layout and style drift.

12.5 Domain Bridge Pattern

Complex designers (Flow Designer, Report Designer, Spreadsheet) are integrated via the DomainBridge pattern: core packages provide pure logic runtime, renderer packages provide React integration, and the canvas is decoupled via bridge callbacks. This allows canvas implementations to be replaced without affecting core logic.

12.6 Documentation as Architecture

From the layered documentation system of Flow Designer to multiple rounds of discussion on the frontend programming model, the Flux project always uses documentation as the carrier of architectural decisions. The separation of target state and snapshot state, and the separation of discussion records from normative documents, ensure the sustainable maintenance of architectural knowledge.

12.7 AI-First Observability

The debugger was designed as AI-first from the start: structured automation APIs, diagnostic reports, session export, interaction tracing. Subsequent dependency tracking change paths, source/reaction registry snapshots, and node locator identity all follow the "machine-readable over human-readable" observability design.

12.8 Design First, Implementation Approximates

Flux's core design ideas (Env environment abstraction, Api/Resource as asynchronous reactive values, lexical scope data chain, xui:imports action modularization, declarative first) were established as early as the AMIS theory research phase. The architectural evolution records not the discovery of design directions, but the gradual approximation of implementation precision to design principles — from runtime interpretation to compile-time staticization, from implicit conventions to explicit contracts, from monolithic to layered package boundaries.

12.9 Host Boundary Testing Ground

Flow Designer is the first testing ground for Flux to validate host protocols. What Flux learned from Flow Designer is not "how to make a flowchart editor", but that complex controls must access the runtime via host boundaries, namespaced actions, bridge snapshots, and configuration-driven approaches. The same unified runtime later successfully accommodated two vastly different complex host paradigms: structured process tree (DingFlow) and Excel-native workbench (Spreadsheet/Report Designer).

12.10 Implementation-Driven Convergence

Although design ideas were established early, the implementation path was not achieved overnight. Flux's architecture gradually became precise through continuous implementation, failure, regression, splitting, renaming, rewriting documentation, and then being forced to converge by sub-audits. Each step of implementation advancement was accompanied by clear documentation and regression test coverage, ensuring traceability of implementation decisions.

12.11 Audit Rule Extraction Forms Long-Term Governance Loop

From the deep audits of Phase 9 to the 18-dimensional audit of Phase 11, the Flux project continuously distilled audit findings into reusable governance rules: coverage thresholds (Plan 143), compilation depth limits, scope snapshot sanitization, strict validation mode. The output of each audit is not just fixes, but the extraction of new rules. These rules are written into code (threshold configs, compiler checks) rather than documentation, forming an automated governance loop.

12.12 Adversarial Review Complements Deep Audit

Deep audits discover problems from architectural dimensions (state ownership, dependency direction, contract consistency); adversarial reviews expose vulnerabilities from an attacker's perspective (prototype pollution, deep nesting, truthy traps). The two complement each other: deep audits ensure "architecture is correct", adversarial reviews ensure "attacks do not succeed". Phase 11 institutionalized both as standard processes before release.

12.13 Reactive Subscription Precision is an Architectural Concern

From per-path subscription (Plan 90) in Phase 9 to path-aware useCurrentFormState in Phase 11, subscription precision has always been an architectural concern, not a local optimization. The wake-up scope of React re-renders directly determines the responsiveness performance of forms, tables, and designers. Flux's answer is progressive precision from full-value comparison → dependency path intersection → path-aware precise subscription; each step is an architectural decision, not an implementation detail.

12.14 Validation Owner Hierarchy

The ownership of the validation system is not a binary "has/has not", but a hierarchical model: form (form domain) → page-root (page domain) → surface (popup domain) → detail-child (staged sub-domain). Each layer has an independent lifecycle, submission gating, and validation summary. This hierarchy was the result of three Plans (157 → 163 → 168) gradually converging in Phase 11, evolving from implicit "form owns all validation" to an explicit four-layer ownership model.

13. Appendix: Timeline Overview

Phase	Date	Key Events
Phase 1	03-20 ~ 03-23	Bug #1~#5 analysis and fixes, debugger birth, ActionScope/Import semantics established, Flow Designer packages created, canvas bridge initial implementation
Phase 2	03-23 ~ 03-27	Canvas bridge, command adapter, schema-driven designer, production-grade visual alignment
Phase 3	03-25 ~ 03-29	AMIS→Flux renaming, flux-core split, styling system, shadcn/ui migration, FieldFrame, Report/Spreadsheet migration, testid
Phase 4	03-28 ~ 03-31	Full shadcn/ui migration, Code Editor, Condition Builder, Word Editor, architecture audit
Phase 5	04-01 ~ 04-03	Code audit fixes, comprehensive overhaul, data source redesign, dual-hook design, full @nop-chaos/ui adoption
Phase 6	04-04 ~ 04-06	Formily comparison, dependency tracking, source registry, reaction runtime, action control flow, WorkbenchShell, table state ownership, programming model doc
Phase 7	04-06 ~ 04-11	Programming model finalization, Action/API convergence, Owner Status, component documentation system, imports expression projection, validation design, HiddenFieldPolicy
Phase 8	04-07 ~ 04-08	Template instantiation, repeated instance identity, NodeRenderer migration, compiler diagnostics, BEM cleanup
Phase 9	04-12 ~ 04-20	Deep audit, architecture doc consistency, Plan 82 contract convergence, ScopeRef read-write separation, per-path subscription, performance optimization series (Plans 100~110), form-advanced split, Capability Projection Manifest, flux-i18n, ValueAdapter unified protocol, CompiledSchemaNode elimination, action pre-compilation IR, async governance convergence
Phase 10	04-21 ~ 04-25	Compiler package extraction, action core package extraction, Import Boundary convergence, Base Tree→Template, DingFlow tree mode, CRUD, shared context menu
Phase 11	04-25 ~ 05-03	Performance audit and hot path optimization, test coverage institutionalization (Plan 143), 18-dimensional deep audit, renderer contract convergence (Plans 145/146/144), xui:actions (Plan 150), adversarial security review and hardening, validation owner four-layer boundary convergence (Plans 157/163/168), Strict Validation Mode (Plan 174), Turborepo engineering

Conclusion

The architectural evolution of NOP Chaos Flux is a process of systematically implementing established design ideas on a modern technology stack. The core designs — Env environment abstraction, Api/Resource as asynchronous reactive values, lexical scope data chain, xui:imports action modularization, declarative first — were established as early as the AMIS theory research phase (see c:/can/nop/nop-entropy/docs/theory/amis/). What Flux did was not to invent these principles, but to solve the structural limitations of AMIS at the schema layer (parallel field explosion) and runtime layer (MST tight coupling), and to implement these principles in a compile-first, type-safe, package-boundary-clear manner.

The strongest mainline throughout the evolution is from runtime interpretation to compile-time execution: value classification, template instantiation, action pre-compilation, host contract staticization, compiler package extraction — each step is a milestone on the same path of moving runtime judgment forward to compile time. But this mainline is not the only one. Running in parallel and equally important are two others: the ownership convergence of owner / validation / surface (from implicit dual-state to explicit staged owner, finally converging to the four-layer validation owner of form / page-root / surface / detail-child), and the boundary explicitization of host contract / import boundary / capability manifest (from runtime wiring conventions to compile-time visible contracts). The final three-layer split of flux-compiler / flux-action-core / flux-runtime is the physical form of the compile-forward mainline. Phase 11 built on the three-layer split to complete comprehensive quality convergence: performance hot path optimization, 80% coverage institutionalization, adversarial security review, validation owner boundary precision, host tooling engineering — a leap from "architecture correct" to "implementation robust".

The resulting architecture — DSL-first + compilation/execution separation + orthogonal scopes + template instantiation + domain bridging + compile-time host contracts + layered validation owner + automated quality governance — provides a clear modern runtime reference for declarative frontend low-code DSLs.

nop-chaos-flux is open source:

Design Principles of nop-chaos-flux, a Next-Generation Low-Code Rendering Framework

canonical — Tue, 19 May 2026 12:38:06 +0000

Introduction

nop-chaos-flux is the rendering layer of the Nop platform—a low‑code runtime driven by declarative DSLs, designed to render and execute application pages described by Schema in the browser. Its DSL surface syntax resembles that of Baidu AMIS, but achieves conceptual unification (e.g., eliminating the xxxOn suffix family). Its internal compilation model, runtime architecture, and expression engine have all been redesigned.

Most low‑code platforms treat the Schema as the runtime input configuration. The runtime then simultaneously carries authoring‑time structures, domain semantics, and scheduling logic. Every new capability adds another set of primitives, a new global provider, another authoritative Schema channel, and the core keeps bloating.

Flux starts from a different path: elevating the DSL from a runtime input format to an independent, first‑class structural layer.

1. DSL First

The DSL is not an input format fed to the runtime; it is a first‑class artifact of the platform: an independent, operable structural layer. Before ever entering the runtime, it already possesses its own lifecycle, transformation space, and organization rules.

Many systems have a DSL, but it is only used as a runtime input format—there is no independent structural manipulation. Flux does not see it that way. Flux’s DSL is a structural layer that can be edited, composed, trimmed, and transformed even outside the runtime:

Operation	Meaning
Edit	Source location retention, aliases, editor metadata, round‑trip fidelity
Merge / Inherit	`x:extends` inheritance, override expansion, fragment composition
Trim	Permission trimming, feature flag trimming, profile assembly
Transform	i18n string replacement, static default expansion
Meta‑programming	Express variations through structural conventions (not by growing runtime interfaces)

DSL transformations are layered: permission trimming, i18n replacement, and default expansion each operate independently. Removing authoring‑time metadata must not change runtime behavior.

2. Authoring–Execution Separation

Even when adopting a DSL‑first approach, many systems still maintain only one model, forcing the runtime to directly carry authoring‑time structures. Flux deliberately does not do this. Instead, it places the Authoring Model and the Execution Model on opposite sides of a pre‑compilation boundary.

The point of this principle is not “having two models” per se, but acknowledging that the two sides have different optimisation goals: authoring time serves understanding, editing, composition, and fidelity; execution time serves conceptual simplification, reduced runtime overhead, and stable execution semantics.

Two‑sided optimisation goals

Aspect	Authoring Model	Execution Model
Optimisation goal	Understandability, domain expressiveness, editing fidelity	Performance, unified internal concepts, minimal runtime overhead
Structural form	Retains source location, aliases, editor metadata, domain‑specific edit structures	Final assembled Execution Schema, no redundancy
Correctness	Round‑trip fidelity, author intent never lost	Behavioural equivalence, deterministic execution
Replaceability	Many editors/designers/collaborative engines can produce the same DSL	The same Final Execution Schema can execute on different runtime hosts

Significance of the boundary

The pre‑compilation boundary means more than “do some optimisation early”. It ensures that structural problems that should never land on the runtime surface are resolved at the structural layer:

Compile‑time structural decisions — type resolution, renderer binding, default expansion are done during the loading phase; runtime overhead is zero.
Compile‑time policy trimming — permission nodes, feature flag branches are removed before entering the runtime; the runtime never sees them.
Compile‑time action DAG assembly — then / onError / parallel are assembled at compile time into a cycle‑free execution graph; no graph discovery or cycle detection at runtime.
Unified Value IR — All forms of Value (literal/expression/template/array/object) are compiled into a unified IR; evaluation is unified at runtime.

If a problem can be solved at the structural transformation layer, it must never be dragged onto the runtime surface.

3. Reactive Data‑Driven

Flux’s core execution model is reactive and declarative. The author does not need to explicitly build imperative linkage logic: whenever a dynamic value reads a path from the scope via a field path, name, or ${expr}, it automatically falls into the dependency graph and will be re‑evaluated when the dependency changes.

Basic rhythm: evaluate → collect dependencies → propagate changes → targeted re‑evaluation / invalidation → republish.

Dependency tracking is a built‑in design semantic of the Value primitive. Dependencies are automatically collected during evaluation, not declared statically beforehand. Value, Resource, and Reaction all use this mechanism, but with different consequences: Value is re‑evaluated, Resource is marked dirty and refreshed, a Reaction may trigger a Capability.

The current implementation uses React and useSyncExternalStore to interface with the rendering host, but the principle itself is not tied to any UI framework.

Read/Write and Effect Separation

Read: Value / Resource published values / Host Projection snapshots are all read‑only via ScopeRef.
Write: User edits, FormRuntime.setValue, ScopeRef.update, Resource publication—these modify owner‑owned data and belong to the data owner side; they will publish store/scope changes, but that is not equivalent to triggering an action.
Command / Effect: Schema‑authored commands (API calls, setValue action, submission, navigation, host commands, etc.) are dispatched only through Capability.
Change → Effect: Data changes do not directly trigger actions; they must pass through a Reaction or a Semantic Lifecycle Entry.

Rendering Host Interfacing

The Store layer runs the reactive logic self‑consistently; React is merely a rendering host that subscribes to Store snapshots.

Settled Update Turn is a runtime‑store concept, not a React useEffect ordering concept.
React concurrent mode can interrupt, replay, and discard renders; Flux does not constrain such scheduling behaviour—it only defines when the store settles an update turn and when a stable snapshot is published.
The rendering host consumes the published results; it does not directly hold reactive protocol objects.

4. Gradual Evolution

Complex capabilities in Flux should not be obtained by continually inventing new primitives; they should grow naturally from simpler existing forms. This principle constrains two things at the same time:

The author‑visible DSL naturally extends from simple forms to complex forms without frequent mental model switches.
Complex capabilities inside the runtime should be composed from existing primitives (derived system) as much as possible, instead of expanding the primitive set under pressure.

DSL‑level evolution: natural growth from simple forms

Concept	Simple form	→	Complex form
Value	literal → expression → anonymous source	→	named `data-source` (Resource)
Action	single‑step dispatch	→	`when` guard → `then`/`onError` branches → `parallel` fan‑out → compilable to DAG execution graph
Structure	`visible` (display level)	→	`when` (lifecycle activation) → `loop` (collection expansion) → `dynamic-renderer` (remote assembly)
Host write	semantic command	→	generic patch‑style `applyPatch`

Value evolution

The same property chooses the appropriate form based on complexity. How the consumer reads the value stays the same: ${countries} remains uniform from literal to data‑source.

// literal
{ "options": ["draft", "published", "archived"] }

// expression
{ "options": "${role === 'admin' ? adminOptions : userOptions}" }

// source: field‑level anonymous request, not published to scope
{ "options": {
  "type": "source",
  "action": "ajax",
  "args": { "url": "/api/countries", "params": { "region": "${form.region}" } }
}}

// data-source: named Resource with producer lifecycle & scheduling policy
{ "type": "data-source", "name": "countries",
  "action": "ajax",
  "args": { "url": "/api/countries" },
  "interval": 3000,
  "stopWhen": "${countries.complete}" }

Action evolution

The compiler recursively assembles nested schemas into a CompiledActionNode DAG (flux-compiler/action-compiler.ts). The runtime simply traverses edges to execute; no graph discovery or cycle detection is needed.

// single-step dispatch
{ "action": "setValue", "args": { "path": "name", "value": "test" } }

// when guard: skip if condition not met, result marked skipped
{ "action": "setValue", "when": "${isEnabled}",
  "args": { "path": "name", "value": "test" } }

// then/onError branches: different paths based on ActionResult triage
{ "action": "ajax", "args": { "url": "/api/users" },
  "then":     { "action": "showToast", "args": { "message": "Save successful" } },
  "onError":  { "action": "showToast", "args": { "message": "${error.message}" } } }

// parallel fan-out + onSettled aggregation
{ "action": "parallel",
  "parallel": [
    { "action": "ajax", "args": { "url": "/api/notify/email" } },
    { "action": "ajax", "args": { "url": "/api/notify/sms" } }
  ],
  "onSettled": { "action": "showToast", "args": { "message": "Notifications complete" } } }

// form submission: submitAction owned by the form node; button is only a thin component:submit trigger
{ "type": "form", "id": "profile-form",
  "submitAction": {
    "action": "ajax", "args": { "url": "/api/profile", "method": "post" } },
  "onSubmitSuccess": { "action": "closeSurface" },
  "onSubmitError":   { "action": "showToast", "args": { "message": "${error.message}" } } }

Branch contexts (result / error / prevResult) are automatically injected into the evaluation environment during dispatching (flux-action-core/action-core.ts createBranchEvaluationBindings).

Structure evolution

visible and when are not synonyms: fields hidden by visible still participate in validation; subtrees with when=false are entirely inactive and do not participate in the lifecycle.

// visible: display‑level toggle, node still exists
{ "type": "input-text", "name": "adminCode", "visible": "${role === 'admin'}" }

// when: lifecycle activation, affects existence and subtree validation
{ "type": "fragment", "when": "${showSummary}",
  "body": [{ "type": "text", "text": "Summary content" }] }

// loop: collection expansion, each iteration gets its own repeated‑item scope
{ "type": "loop", "items": "${users}", "itemName": "user", "indexName": "idx",
  "body": [{ "type": "text", "text": "${idx + 1}. ${user.name}" }],
  "empty": [{ "type": "text", "text": "No data" }] }

// dynamic-renderer: runtime remote assembly, decides which fragment to render
// Note: it is not a second Resource facet — data‑source produces named values, dynamic‑renderer assembles fragments
{ "type": "dynamic-renderer",
  "loadAction": { "action": "ajax", "args": { "url": "/api/schema/${componentType}" } },
  "body": { "type": "text", "text": "Loading..." } }

5. Lexical Ownership

This principle is an organisational constraint for Principle 3. Data, capabilities, resources, reactions, and runtime sidecars belong to the lexical scope or subtree boundary; they are not held by a global runtime mega‑object.

Three resolution mechanisms

Data lookup (ScopeRef), action lookup (ActionScope), and instance location (ComponentHandleRegistry) are architecturally separate resolution mechanisms, each with its own scoping rules.

Lexical shadowing

Child scopes override parent publications through natural lexical shadowing, not global overrides. Bindings with the same name can independently exist in different lexical scopes:

// page scope has items
{
  "type": "page",
  "data": { "items": ["a", "b"] },
  "body": [
    // dialog child scope also has items, shadows parent
    {
      "type": "dialog",
      "data": { "items": ["x", "y"] },
      "body": [{ "type": "text", "text": "${items}" }],
    }, // → ["x", "y"]
  ],
}

Resource publication ownership

Within the same owning scope, the same binding target should not be long‑term co‑occupied by two simultaneously active publishing producers. This constraint applies to authoritative publication (continuous publication by a Resource), not ordinary writes:

// compliant: two forms write to the same path at different times
{ "type": "dialog", "body": [
  { "type": "form", "id": "createForm",
    "onSubmitSuccess": { "action": "setValue", "args": { "path": "result", "value": "${result}" } } },
  { "type": "form", "id": "editForm",
    "onSubmitSuccess": { "action": "setValue", "args": { "path": "result", "value": "${result}" } } }
]}

// violation: two data‑sources simultaneously claim to publish "status"
{ "type": "page", "body": [
  { "type": "data-source", "name": "status", "action": "ajax", "args": { "url": "/api/a" } },
  { "type": "data-source", "name": "status", "action": "ajax", "args": { "url": "/api/b" } }
]}

Runtime sidecars (Resource state, Reaction state, caches, diagnostics) follow lexical ownership, but they must not become methods or mutable protocol objects attached to a ScopeRef. The Scope hosts the data environment; it does not carry bridges, controllers, handles, or other command‑like objects.

6. Domain Isolation & Abstraction

The Flux core maintains a small, stable abstraction layer. Its goal is not to absorb all frontend domain semantics, but to provide a sufficiently stable execution kernel that allows different domains to grow outside the core.

The litmus test for this principle is not “can the core directly describe all complex systems?” but “can the core provide a stable embedding surface for complex systems without pushing domain complexity back into the core vocabulary?”

Isolation contract

Interactions between domain systems (Flow Designer, Report Designer, Spreadsheet Editor, collaborative engines, CRDT/OT, etc.) and the Flux core are narrowed down to:

Direction	Mechanism	Meaning
Core → Domain (read)	Host Projection	Read‑only snapshot projection, host‑driven refresh
Domain → Core (write)	Capability	Namespaced command dispatch (e.g., `designer:*`)
Instance location	ComponentHandleRegistry	Explicit target component instance method invocation
Host‑private	DomainBridge	`getSnapshot/subscribe/dispatch`, does NOT enter Schema‑visible Scope

Why the core stays stable

Graph algorithms, layout, collision detection, collaboration protocols, CRDT/OT, local‑first sync, gesture loops—these are all important, but they are domain systems and should not become core primitives. From Flux’s perspective, they are just production strategies behind a Resource, host snapshots behind a Host Projection, or command systems behind a Capability.
New domains plug in by declaring a host type + projection fields + capability namespace, without needing to introduce new global provider families, environment registries, or new authoritative Schema channels.
Cross‑domain generic write pattern for editable hosts: read Host Projection → write Capability (structured patch DTO) → DomainBridge host‑private.

Business semantics ownership

Business pipelines (form submission, dialog confirmation, page entry) belong to the node that owns that lifecycle boundary, not to the UI trigger. Concrete examples are given in Section 4 (Semantic Lifecycle Entry). This is a concrete manifestation of lexical ownership and domain isolation.

Summary

#	Principle	One‑liner
1	DSL First	The DSL is a first‑class structural layer independent of the runtime: editable, composable, and transformable before execution.
2	Authoring–Execution Separation	Authoring and execution serve different optimisation goals; they should be separated by a pre‑compilation boundary, not mixed in the runtime.
3	Reactive Data‑Driven	The Value primitive has built‑in dependency tracking, read/write separation, and side effects are funnelled through Capability.
4	Gradual Evolution	Complexity should grow naturally from simple DSL forms and existing primitives, not by expanding the primitive set under pressure.
5	Lexical Ownership	Data, capabilities, resources, reactions, and their sidecars belong to lexical/subtree boundaries, not to a global runtime mega‑object.
6	Domain Isolation & Abstraction	The core provides a small, stable execution kernel; domain complexity stays outside the core and embeds through a narrow contract.

nop-chaos-flux is open source:

Nop Chaos Flux: The Next-Generation Low-Code Rendering Engine After Baidu AMIS

canonical — Wed, 06 May 2026 09:42:15 +0000

1. Introduction — Why Another Low-Code Framework?

Baidu AMIS is an outstanding design. It is powerful, well-documented, widely used in various enterprise applications, and has a profound influence in the low‑code rendering space. However, AMIS has a long development history — through continuous iteration, its internal implementation has gradually become bloated and complex, and conceptual consistency is suboptimal in many places. Specifically, several issues stand out:

Inconsistent expression rules at the schema layer. Although AMIS automatically handles boolean expressions with the xxxOn suffix and template expressions with the xxxExpr suffix via a generic regex in getExprProperties, it does not generally support template interpolation on plain string properties (e.g., label: "Hello ${name}"), nor expressions inside deeply nested objects. At the same time, static and dynamic values use different field names in the schema: disabled / disabledOn, options / source. Whether a property supports expressions, and which syntax it uses, lacks uniform rules.

Over‑responsibility of the store at runtime, mixing data and behavior. AMIS's MST store acts as both a data container (data field) and a carrier for data operations (updateData, changeValue), API calls (fetchData, saveRemote), dialog management (openDialog, closeDialog) — behavior methods are attached directly to the store. Moreover, the store's data field itself is a scope object built on the prototype chain (Object.create(superProps)), where data inheritance is implicit in the object structure, interweaving reactive updates with variable lookup.

System environment dependencies passed layer by layer through props. All system‑level objects in AMIS — store, env, data, render functions — must be passed down through React props. The props interfaces of renderers grow increasingly bloated; even intermediate layers that do not use these objects must forward them, increasing coupling between components and making renderer interfaces heavy.

Previously, due to the enormous workload, I wrote only a few articles outlining thoughts on improving AMIS's design, never intending to rebuild a better low‑code runtime from scratch (see Why Baidu AMIS Framework is an Excellent Design and Revisiting Baidu AMIS Framework and Declarative Programming). But with the support of AI, a single architect can now directly implement a complex framework. Therefore, starting in April 2026, I designed and implemented the Flux architecture. Flux is a complete rewrite of AMIS, but the goal is not to change the technology stack — it is to address the structural limitations of AMIS at the schema and runtime layers.

Flux is the rendering layer of the Nop platform, not a standalone framework. The Nop platform, based on reversible computing principles, provides a series of structural transformation capabilities before the schema reaches the renderer — i18n substitution, permission pruning, module decomposition and inheritance, compile‑time metaprogramming. These concerns are addressed at the JSON structure level, without relying on any frontend framework runtime mechanisms. Section 10 of this article details these platform‑level capabilities. The rendering framework layer and the platform layer each fulfill their own responsibilities; this layering is an intentional architectural decision: problems that can be solved at the structural transformation layer are not carried into the rendering runtime.

At the same time, Flux is designed with the assumption that the primary way schemas are produced is shifting from human handwriting to AI generation. This premise influences several design decisions — notably the explicitness of the styling system and tolerance for schema redundancy. For AI, explicit and predictable interfaces are friendlier than implicit conventions; for humans, reviewing and locally modifying an explicitly declared schema is also more reliable than understanding implicit defaults. Of course, this does not mean the framework is unusable for human‑authored schemas — it merely tips the design trade‑off toward determinism.

2. Core Philosophy — Unified Value Semantics

The most fundamental difference between Flux and AMIS lies in how values are expressed.

AMIS's approach: a property can be either a static value or an expression. To distinguish the two, AMIS introduces a family of parallel fields in the base schema (amis-core/src/schema.ts). Every property that needs dynamic control is split into two: a static field and an expression variant with an On suffix — disabled / disabledOn, visible / visibleOn, hidden / hiddenOn, static / staticOn. At the form item level there is required / requiredOn, and in some renderers (like Table/CRUD) there are expression variants like classNameExpr.

This split creates difficulties when extending. The number of fields doubles, and schema authors have to remember which properties use the static form and which use the expression form. Worse, the two are mutually exclusive — writing disabled: true and disabledOn together is not allowed, but the framework does not enforce this. It all relies on conventions and documentation.

AMIS's parallel fields elevate the semantic difference inside a value — "this is static" vs. "this is dynamic" — to the structural level of the object, expressing that difference through distinct field names. This approach externalizes a judgment that should belong to the value as an object structure, forcing structural changes when extension is needed.

Flux's approach unifies under a single field name, letting the compiler distinguish the type of value.

disabled is just disabled. It can be a static boolean true, an expression ${$form.submitting}, or a template string containing an expression "${name} is disabled". How to distinguish these forms? Let the compiler decide, rather than having schema authors memorize various suffixes. This judgment is confined to the expression of the value and does not need to be elevated to the object structure level.

The type system behind this is as follows:

type CompiledValueNode<T> =
  | { kind: 'static-node'; value: T }
  | { kind: 'expression-node'; source: string; compiled: CompiledExpression<T> }
  | { kind: 'template-node'; source: string; compiled: CompiledStringTemplate<T> }
  | { kind: 'array-node'; items: CompiledValueNode[] }
  | { kind: 'object-node'; keys: string[]; entries: Record<string, CompiledValueNode> };

At compile time, the compiler analyzes each field's value, determines which kind of node it is, and wraps the result into CompiledRuntimeValue at runtime — static nodes are directly wrapped as StaticRuntimeValue (zero‑cost return), dynamic nodes are wrapped as DynamicRuntimeValue (carrying evaluation closure and state tracking). CompiledValueNode at compile time is a pure data tree; CompiledRuntimeValue at runtime is an executable wrapper:

type CompiledRuntimeValue<T> =
  | { kind: 'static'; isStatic: true; node: StaticValueNode<T>; value: T }
  | {
      kind: 'dynamic';
      isStatic: false;
      node: DynamicValueNode<T>;
      createState(): RuntimeValueState<T>;
      exec(context, env, state): ValueEvaluationResult<T>;
    };

The compiler analyzes each field's value at compile time, determines which kind of node it is, and generates the corresponding compiled result. At runtime, only the compiled result is executed — no further determination is needed. Expression compilation also performs automatic optimization: if the expression's value is constant (e.g., "${1 + 2}" is optimized to the static value 3), it directly returns a static value without incurring dynamic evaluation overhead. Therefore, even if written as an expression, the compiler automatically eliminates dynamic evaluation cost when the result is constant. To output a literal $ symbol in a template string, use ${'$'} for escaping.

By limiting the semantic difference of "a value can be static or dynamic" to the value level via the five node types of CompiledValueNode, three benefits are achieved:

Simpler schema: the number of fields is halved; schema authors do not need to memorize xxxOn rules; disabled is just disabled.
Unambiguous composition and inheritance: each field name is unique; there is no priority conflict when both disabled and disabledOn appear; semantics remain clear when overriding layer by layer.
Compile‑time classification paves the way for later optimizations: static-node takes the zero‑cost fast path; expression-node and object-node independently track references, providing the structural prerequisite for full‑value tree compilation (Section 3).

This design also provides a structural foundation for type safety: each node has an explicit type tag, allowing TypeScript to provide effective type checking on most call paths — the implementation keeps a small number of type assertions for practicality; type safety is layered rather than absolute.

This distinction is not merely syntactic convenience; it sinks the semantic difference of values from the object structure down to the value level. What schema authors see is what exists at runtime, with no cognitive gap.

3. Full‑Value Tree Compilation — Static Fast Path and Dynamic Reuse

An important feature enabled by unified value semantics is that we can compile the entire schema value tree, not just the expressions inside it.

Traditional frameworks typically compile only expressions, using static values directly at runtime. Flux compiles the entire value tree structure.

Consider a static configuration object:

{
  "type": "button",
  "label": "Submit",
  "disabled": false,
  "className": "btn-primary"
}

In a traditional framework, this object must be parsed and passed on every render. In Flux, when the schema is first passed to the renderer, the compiler triggers a one‑time JIT compilation — it recognizes this as a purely static node, generates the corresponding compiled result, and caches it. Every subsequent runtime access to this compiled result directly returns a reference to the original object, without any further decision making.

For an object containing dynamic parts:

{
  "type": "button",
  "label": "Submit",
  "disabled": "${$form.submitting}",
  "className": "${$form.submitting ? 'btn-disabled' : 'btn-primary'}"
}

The compiler compiles this object into an object-node, where each expression field has its own evaluation state. At runtime, each field tracks its previous computed result independently; finally, the assembled object is compared with the previous result using shallowEqual — if none of the field references have changed, the previously computed object reference is returned directly without creating a new object.

RuntimeValueState maintains the previously computed value for each node; the reusedReference flag in ValueEvaluationResult tells the caller whether an old reference was reused. This mechanism works most stably for object structures defined by the schema (object-node): each field's expression is tracked separately; as long as the references of field values do not change, the outer object's reference does not change either.

This design has a significant impact on React performance. React's re‑rendering is based on reference equality; stable object references allow child components to skip unnecessary renders.

4. Scope Chain — Explicit Lexical Interface and Lazy Merging

In low‑code frameworks, scope is a core concept. Components need to access various contextual information such as form data, page parameters, and environment variables.

AMIS builds the scope chain via createObject (amis-core/src/utils/object.ts), which is implemented using JavaScript's prototype chain: child scopes are created via Object.create(parentScope), variable lookup travels upward along the prototype chain, and same‑named variables automatically shadow those in parent scopes. This mechanism is not inherently crude, but its problem lies in implicitness — everything is implemented through the JS engine's internal prototype chain, with no explicit interface contracts, and no way to accurately distinguish between "read only the current layer" and "read the entire chain" without understanding the internal implementation.

Flux adopts an explicit ScopeRef lexical lookup chain:

interface ScopeRef {
  id: string;
  path: string;
  parent?: ScopeRef;
  value: Record<string, any>;
  get(path: string): unknown;
  has(path: string): boolean;
  readOwn(): Record<string, any>;
  readVisible(): Record<string, any>;
  materializeVisible(): Record<string, any>;
}

Each scope is linked via a parent pointer, forming a chain structure. When looking up a variable, the get(path) method walks up the chain until it finds the corresponding value or reaches the root.

This design has several key advantages:

Explicit interface semantics: readOwn() returns only the current layer's data; readVisible() returns the lexically visible view; materializeVisible() explicitly expands when a plain object is truly needed. The underlying implementation may use the prototype chain to optimize readVisible() performance, but the interface semantics are independent of the implicit behavior of the JS prototype chain — the boundaries between these operations are immediately clear, without needing to understand internal details.
Lazy expansion: only when a complete plain object is truly required does materializeVisible() execute; most of the time access goes through get() or readVisible() to access individual variables, avoiding unnecessary object construction.
Testability: ScopeRef is an ordinary interface that can be constructed and tested independently, without relying on the implicit behavior of the JS prototype chain.
Traceability: the id and path fields allow scopes to be precisely located during debugging and logging.

The usage pattern is also clear: scope.get(path) is the fast path for high‑frequency operations; scope.readVisible() is suitable for obtaining the lexically visible view; scope.materializeVisible() is the low‑frequency fallback for plain‑object needs.

5. Data, Actions, Components — Three Trees, Three Origins

Flux splits the runtime into three independent tree structures.

Starting from the fundamental structure of object‑oriented GUI systems, a complete GUI runtime essentially contains three orthogonal dimensions: ComponentTree (the organization of components on the interface), StateTree (the distribution and flow of data and state), and ActionTree (the operations that can be performed and their naming/resolution rules). Although these three dimensions collaborate within the same UI, they have fundamentally different growth patterns and lifecycles. Traditional object‑oriented design mixes them into a single tree, which is the root of complexity.

In Flux, these three conceptual dimensions correspond to concrete runtime carriers: StateTree ≈ ScopeRef (lexical data visibility chain), ActionTree ≈ ActionScope (namespace action resolution chain), ComponentTree ≈ compiled Template structure (immutable component tree description). ComponentHandleRegistry is a separate instance‑level location layer responsible for looking up component handles by id/name; it supports the resolution of instance‑targeted actions like component:<method>.

This divide‑and‑conquer approach stems from a fundamental observation about object‑oriented GUI systems: the core essence of OO technology in the GUI domain lies in the organizational relationship between ComponentTree, StateTree, and ActionTree — components form the static structure, data flows in the state tree, and events bubble along the action tree. Flux formalizes this observation into three independent runtime structures, each with explicit lexical lookup semantics.

Particularly noteworthy is the isomorphism between lexical scoping and event bubbling: if we stipulate that event names passed upward are exactly function names, then the event bubbling process can be seen as a function name resolution process in the lexical scope. xui:imports creates different lexical scopes at different levels; action resolution always starts from the nearest scope and, if not found, looks up to the parent scope — exactly the same as variable resolution rules in programming languages. The separation of the three trees is not for its own sake, but because they have fundamentally different growth patterns and lifecycles; forcibly unifying them would only introduce unnecessary coupling.

In traditional low‑code frameworks like AMIS, data and behavior are mixed in the same scope object. Need to access data? Take it from the scope. Need to invoke an action? Also take it from the scope. This design is convenient for simple scenarios, but it masks an essential difference: the composition sources of data and behavior are fundamentally different.

Data is structural. Data flows in naturally as the component tree renders — when a form component mounts, its field values enter the scope; when a data-source component receives a response, the result is written into the scope. The growth of the data scope is strictly bound to the rendering process of the component tree — it is passive and follows the structure.

Behavior is declaratively imported. Through xui:imports, a container can import capabilities from external libraries — demo-lib, spreadsheet-lib. These libraries have no relation to the position of the current component in the tree; they are loaded asynchronously and have their own initialization and destruction lifecycles. The source of behavior lies outside the component tree.

If data and behavior are placed in the same tree, fundamental lifecycle conflicts arise: the data scope follows the mounting/unmounting of components; libraries loaded via xui:imports may need asynchronous initialization, reference counting to manage multiple imports, and independent teardown when unmounted. These requirements cannot be uniformly managed by the same mechanism.

Therefore, Flux splits the runtime into three independent trees:

ScopeRef handles the data layer: values, variables, form state, and other pure data information. get(path) walks up the chain to look up a variable name; readOwn() reads only the current layer; readVisible() returns the lexically visible view — the semantics of the three operations are directly expressed by the interface names, rather than reliant on implementation details.

ActionScope handles action capabilities, i.e., executable operations. Actions are organized by namespaces — designer:addNode, spreadsheet:setCellValue — namespaces are dynamically registered via xui:imports, completely isolated from the data scope, so adding or removing actions does not affect variable lookup. The action resolution order in the action dispatcher has a clear priority: first built‑in platform actions (setValue, ajax, dialog), then component‑targeted actions (component:submit, component:validate), and finally namespace actions (designer:export, spreadsheet:mergeRange). This hierarchy ensures both flexibility and sensible defaults.

ComponentHandleRegistry handles the location and access of component instances. id is a stable and unique anchor within a page; name is a local logical name suitable for reuse within different local boundaries — but if duplicated within the same resolution boundary, an explicit ambiguity error is triggered. Schema authors use component:<method> together with componentId or componentName to specify the target component; the runtime may perform internal index optimizations for statically resolvable targets to reduce common lookup costs.

These three trees share the same design intuition: chain lexical lookup. ScopeRef.get(path) resolves variable names; ActionScope.resolve('demo:open') looks up the demo namespace along the chain (just like lexical scope resolution of function names in programming languages); ComponentHandleRegistry.resolve(target) locates component handles. Each tree maintains its own independent lifecycle semantics, but the lookup logic inside each tree follows the same upward‑chain principle, preserving overall design consistency.

This "three‑tree separation" design continues the separation‑of‑concerns thinking from classic architectures like MVC, but grounds it as a self‑consistent implementation scheme for the low‑code domain.

5.1 xui:actions — Schema‑Local Named Action Chains

The separation of the three trees makes the origin of actions clear and controllable, but a recurring issue remains in practice: how can reusable action sequences be expressed in a schema?

In previous implementations, if multiple schema nodes needed to execute the same action sequence (e.g., a set of ajax calls with fixed parameters), the only options were to define those actions at a higher‑level node and reference them by name, or to duplicate the definitions on each node. The former moves action definitions far from their usage sites; the latter creates redundancy.

xui:actions solves this problem. Schema nodes can now declare named action chains via xui:actions:

{
  "type": "container",
  "xui:actions": {
    "myAction": [
      { "action": "ajax", "args": { "url": "/api/submit" } },
      { "action": "notify", "args": { "message": "Submitted successfully" } }
    ]
  },
  "body": [
    {
      "type": "button",
      "onClick": {
        "action": "myAction"
      }
    }
  ]
}

At compile time, action chains declared in xui:actions are compiled and stored on the template node. At runtime, they are accessible via ActionScope — a synthetic namespace driven by the compilation results, not requiring an explicit import via xui:imports.

Lexical inheritance is the key design feature: when the requested action name is not found at the current level, the namespace provider falls back upward to the parent scope. This means child nodes automatically inherit named actions defined by parent nodes, without needing to redeclare them. This behavior is exactly consistent with the lexical lookup model of the data scope — although the origin of actions differs from data, the lookup semantics follow the same design intuition.

The action resolution order thus expands to:

Built‑in platform actions (setValue, ajax, dialog, etc.)
Component‑targeted actions (component:submit, component:validate)
Named actions (local action chains defined by xui:actions)
Namespace actions (external libraries imported via xui:imports)
Resolution failure: error reported if none of the above match

With the addition of xui:actions, "named actions" become first‑class citizens in the resolution chain, standing alongside built‑in actions and namespace actions. Each layer has its own origin and priority. This resolves the previous practical pain point: reusable action sequences can be defined locally, inherited lexically, and no longer require a binary choice between global definitions and per‑node duplication.

6. xui:imports — Declarative Capability Import

xui:imports is a direct manifestation of the separation between behavior and data. It addresses a very practical problem: schema authors cannot write import statements; schemas may be dynamically loaded from the server. How can a schema fragment declare the external capabilities it depends on without causing global pollution?

In traditional frameworks, third‑party capabilities are usually introduced through global registration. The problem is that global registration easily leads to conflicts and offers no control over scope.

Flux draws inspiration from ES module imports and introduces the xui:imports declaration:

{
  "type": "container",
  "xui:imports": [{ "from": "demo-lib", "as": "demo" }],
  "body": [
    {
      "type": "button",
      "onClick": {
        "action": "demo:open",
        "args": { "id": "${id}" }
      }
    }
  ]
}

from specifies the library to import; as specifies the namespace prefix after import. The imported library is registered into the ActionScope of the current container, becoming an action namespace available to that container and its descendants. Complex hosts such as Flow Designer, Report Designer, and Spreadsheet also follow the same lexical boundary discipline: each host page establishes its own local ActionScope, and then registers the host namespace within that boundary.

xui:imports has several key characteristics:

Declarative: dependencies are explicitly declared in the schema, without requiring code‑side registration.
Lexical visibility: child containers see imports from parent containers, but sibling containers do not see each other's imports — this is intuitive and avoids naming conflicts.
Idempotency and automatic deduplication: when the same library is imported at multiple levels, module loading is deduplicated by a normalized import key; registration on the scope side follows the container's lifecycle. The current implementation already has frame‑level reference counting and release paths — repeated installation increments refCount, and on release the import stack is popped and the corresponding registration is cleaned up.
Security: the from value is resolved by the host‑provided env.importLoader; the framework itself does not perform any URL resolution or script loading. The security boundary is clearly defined: the framework is responsible for managing lexical visibility and lifecycle (registration and teardown) of imports; the host decides which libraries can be loaded and how. It is recommended that hosts implement a whitelist mechanism, allowing only pre‑registered trusted library identifiers rather than accepting arbitrary URLs. In the current implementation, if the host does not provide an importLoader, imports are not silently ignored but enter an explicit failure state, exposing the wiring error via env.notify('error', ...) and monitor diagnostics; subsequent calls to that namespace return a failure result. Namespace isolation ensures that imported libraries cannot override built‑in platform actions (setValue, ajax, etc.); namespace actions always have lower resolution priority than built‑in actions.

This also explains why ActionScope must be separate from ScopeRef: library loading is asynchronous and has its own registration, reference counting, and teardown semantics, which are fundamentally incompatible with the synchronous, structural growth pattern of the data scope.

7. Data Fetching and Dynamic Schema — Splitting the Service

In AMIS, Service is a "do‑everything" component: it simultaneously takes on two responsibilities — fetching data via api (store.fetchData) and dynamically loading a Schema via schemaApi (store.fetchSchema). These two paths share the same component instance and the same store, tightly coupling their lifecycles. If you want to load both a schema and data, and even add polling, properties like initFetch, initFetchSchema, interval, stopAutoRefreshWhen must be combined, making the intent of the schema fuzzy.

Moreover, the way AMIS merges API request data with the scope is implicit — internally, it uses createObject to merge the current data scope into request parameters, making it difficult for users to precisely control which data is sent to the server. Schema authors must understand these implicit behaviors to use them correctly.

From a computational model perspective, api and schemaApi are two fundamentally different computation patterns. api is essentially a reactive asynchronous computation: it establishes a mapping from "state → remote value", retriggering the request when the state changes — it is an asynchronous version of computed. The input is the current state in the scope; the output is a remote value that updates as the state changes. schemaApi, on the other hand, is a one‑time structure initialization: it fires when the component first mounts, and the result is a description of the render tree, used to decide "what to render", not "what data to show". Mixing the two in the same component couples lifecycles and conflates computational semantics.

Flux splits these two responsibilities into separate renderers. Remote calls uniformly enter the runtime via action dispatch:

{
  "type": "container",
  "body": [
    {
      "type": "data-source",
      "action": "ajax",
      "args": {
        "url": "/api/user/${userId}",
        "includeScope": ["userId"]
      },
      "name": "user",
      "interval": 3000,
      "stopWhen": "${user.loaded}"
    },
    {
      "type": "text",
      "text": "Hello, ${user.name}"
    }
  ]
}

data-source is dedicated to declarative data fetching. It is a side‑effect node that does not directly render UI: it fetches data via the action mechanism, publishes the result into the current scope under name, and optionally polls via interval + stopWhen. It returns null, so loading, empty, or error states are handled by sibling nodes in the same scope or by the host notification mechanism.

{
  "type": "dynamic-renderer",
  "loadAction": {
    "action": "ajax",
    "args": { "url": "/api/schema/${pageId}" }
  },
  "body": {
    "type": "text",
    "text": "Loading..."
  }
}

dynamic-renderer is dedicated to dynamic schema loading. It declares the loading action via loadAction (unified with the action mechanism used by data-source), obtains the remote schema, and renders it — focusing solely on the "what to render" concern.

This split brings several benefits. First, concerns are clearer: each component does one thing, making intent easier to understand. Second, lifecycles are independent — polling in data-source does not affect schema loading in dynamic-renderer. Finally, the semantics of the request description object become more precise: includeScope explicitly declares which lexical scope variables are injected into the request; params clearly distinguishes URL query parameters; the actual execution path is uniformly converged to the ajax action and the runtime request preparation flow.

8. Field Metadata Driven — Compiler Makes Decisions, Not Renderers

A title field might be a string "Hello", or a rendering fragment {"type": "text", "text": "Hello ${name}"}, or even an event handler. A renderer would have to determine the field type each time and dispatch logic accordingly — error‑prone and performance‑impacting.

Flux's approach: let renderers define field metadata, and let the compiler perform normalization during compilation.

Field metadata includes the kind of field: meta, prop, region, value-or-region, event, ignored, etc. The most interesting is value-or-region, which allows the same field name to be compiled differently depending on the input type:

{
  "type": "card",
  "title": "Simple Title"
}

Here title is a string, compiled and passed directly to the renderer as props.title.

{
  "type": "card",
  "title": {
    "type": "text",
    "text": "${name} - ${status}"
  }
}

Here title is a schema fragment. Compiled and placed into regions.title, the renderer will render the content of this fragment.

The renderer's code becomes extremely simple, requiring no manual decisions:

const titleContent = props.regions.title?.render() ?? props.props.title;

The compiler has already moved the complex decision logic forward, keeping the renderer simple — it only consumes the compiled output.

9. Styling System — Configurable Explicit Styles

Hardcoding styles in renderers (e.g., a container adding gap‑4 by default) makes it hard for schema authors to adjust because they cannot see the default values; providing no styling at all forces every usage scenario to repeat configuration.

Flux's styling system draws from shadcn/ui's design philosophy, dividing styling responsibilities into two layers: visual defaults at the component library layer and structural arrangement at the renderer layer. The underlying UI components (shadcn/ui based on Base UI) come with sensible visual defaults — borders, rounded corners, focus rings, spacing — so that a {"type": "input-text"} renders as a consistently styled input without any additional class names. The renderer layer does not inject extra visual preferences on top of the component library's defaults; className in the schema is used for layout customization and visual tailoring, not for providing basic appearance.

The core principle is: the renderer layer does not inject default visual styles unrelated to the schema's intent. The basic visual appearance of primitive components is provided by shadcn/ui; the renderer is only responsible for translating structural semantics (flex direction, alignment, etc.). This means that when you look at the schema for a component, the className you see is a declaration of layout and customization, not a repetition of basic appearance. Components like nop-container and nop-flex are only responsible for structural semantics and do not carry fixed visual styles. When a renderer maps semantic attributes like direction, align to utility classes like flex, items-center, this is a direct translation of the schema's intent, not an implicit preference introduced outside the schema.

This approach has several practical benefits:

Full controllability: all renderer‑layer styles are explicitly visible in the schema; there is no confusion like "where did this spacing come from?"
Unambiguous overrides: because the renderer does not inject implicit styles, any custom class names take effect directly, without needing !important to fight framework defaults.
Project‑level reusability: the same Tailwind configuration can be shared across pages, ensuring visual consistency.
AI‑friendly: an explicit, predictable style interface is more beneficial for AI generation scenarios — the AI does not need to "know" what styles the renderer internally injects; the generated result is WYSIWYG.

When the same set of Tailwind class names appears repeatedly in multiple places, classAliases provides an abstraction for reuse:

{
  "classAliases": {
    "card": "bg-white rounded-lg shadow-md p-4",
    "card-hover": "hover:shadow-lg hover:border-blue-300",
    "btn-primary": "bg-blue-500 text-white hover:bg-blue-600"
  }
}

In components, these aliases are referenced directly:

{
  "type": "card",
  "className": "card card-hover",
  "body": [
    {
      "type": "button",
      "className": "btn-primary",
      "label": "Submit"
    }
  ]
}

classAliases is a naming abstraction on top of Tailwind — it does not change the principle of "explicitly declared styles". The schema still writes className: "card card-hover"; no style is silently injected by the renderer. It solves the problem of repetitive writing, rather than introducing implicit behavior.

The scope inheritance mechanism is also natural: child components can override aliases of the same name from parent components. For example, if a different card style is needed in a specific region, it can be redefined in that region's classAliases without affecting other places.

10. Layered Responsibilities — What the Renderer Does Not Need to Know

A common design tendency in low‑code frameworks is to stuff every concern into the rendering layer: i18n using the t('key') function, permissions using conditional rendering like v-if="hasPermission", modularization using global registration. This blurs the responsibility boundary of the rendering framework and leads to growing internal complexity.

Flux adopts a different strategy: explicitly divide which concerns belong to the rendering framework, which belong to the platform layer, and which belong to the component library layer.

Nop Platform Layer (structural transformation)
  → i18n text substitution (@i18n: prefix, pure JSON operations)
  → permission pruning (xui:roles / xui:permissions, delete nodes without permission)
  → module decomposition and merging (x:extends / x:gen-extends)
  → compile‑time metaprogramming (XPL template language)
  → XML/JSON bidirectional conversion
         ↓ outputs processed, clean JSON
Flux Rendering Framework Layer
  → unified value compilation, scope management, action dispatch, rendering coordination
         ↓
shadcn/ui / Radix UI Component Layer
  → component‑level visual defaults
  → component‑level accessibility support (ARIA roles, focus management, keyboard navigation)

The core principle of this layering is: each layer solves only its own problems and does not leak responsibilities to adjacent layers.

10.1 Internationalization (i18n) — Structural Transformation at the Platform Layer

i18n is handled at the platform layer via JSON structural transformation, without involving any frontend framework runtime mechanisms. The Nop platform provides two complementary syntaxes:

Inline value approach — compact, suitable for new schemas:

{
  "label": "@i18n:common.batchDelete|Batch delete"
}

The @i18n: prefix identifies the internationalization key to replace; the text after | serves as both a fallback and provides readability — even without looking up an i18n dictionary, one can understand what the schema is saying.

Companion property approach — non‑invasive to the original value, suitable for retrofitting i18n into existing schemas:

{
  "label": "Batch Delete",
  "@i18n:label": "common.batchDelete"
}

Add a corresponding @i18n:key property for each key that needs internationalization; the original value is not modified.

After processing, @i18n: markers no longer exist in the JSON; what the rendering framework sees is the final text for the current locale. This means that even if the rendering layer is replaced — Flux, AMIS, or even native React — i18n continues to work.

10.2 Permission Control — Structural Pruning over Runtime Hiding

Permission control is also handled at the platform layer. The Nop platform defines permission‑related properties such as xui:roles and xui:permissions. Upon receiving the JSON page data, it automatically verifies whether the permission conditions are satisfied and deletes all nodes that do not meet the permission requirements. This processing takes place on the JSON structure, without involving any frontend‑framework‑specific knowledge.

This is safer than runtime conditional hiding: sensitive structures never leave the server. The rendering framework never sees content that the user is not authorized to access, eliminating the risk of "the component is hidden in the DOM but the data has already reached the client".

10.3 Schema Modularization — Decomposition and Merging via Reversible Computing

The Nop platform implements a generic decomposition and merging mechanism for JSON and XML based on reversible computing theory. It can decompose a very large JSON file into multiple small files according to generic rules, effectively supplementing low‑code schemas with module organization syntax.

The two most commonly used syntaxes are: x:extends for inheriting an external file, and x:gen-extends for dynamically generating an inheritable JSON object:

x:gen-extends: |
  <web:GenPage view="NopAuthDept.view.xml" page="main"
               xpl:lib="/nop/web/xlib/web.xlib" />

body:
  name: crud-grid
  actions:
    - type: button
      id: test-button
      label: 'Test'
      onClick:
        action: dialog
        args:
          'x:extends': test.page.yaml
          title: 'Test Dialog'

The above example means: first dynamically generate a CRUD page based on the configuration of NopAuthDept.view.xml, then add a Test button to the batch action button area. The dialog popped up by the button reuses the existing test.page.yaml file; the title property overrides the inherited content from x:extends, setting the dialog title to Test Dialog.

x:extends acts as a generic operator on tree structures, similar to object‑oriented inheritance. This directly solves the modularization difficulty of "one big JSON file per large page" that plagues most low‑code frameworks.

x:gen-extends further allows dynamic generation of the inherited structure at compile time using the XPL template language, enabling compile‑time metaprogramming. For any external file in JSON format, simply replace the ordinary loading function with a call to the Nop platform's ResourceLoader, and the decomposition/merging operations defined by reversible computing are automatically available.

These capabilities are completed before the JSON reaches the renderer; Flux does not need — and should not — embed a module system.

10.4 Bidirectional Conversion between XML and JSON

When writing and reading manually, the XML format has certain advantages over JSON, especially when integrating with external template engines for dynamic generation. The Nop platform adds an XML syntax representation for low‑code schemas, implementing bidirectional conversion between XML and JSON based on a few simple rules:

The type property corresponds to the tag name.
Simple‑type properties correspond to XML attributes.
Complex‑type properties correspond to XML child nodes.
For list types, mark the node with j:list=true.
The body property is specially recognized and does not need explicit j:list.

For example, the following JSON:

{
  "type": "operation",
  "label": "Operation",
  "buttons": [
    {
      "label": "Details",
      "type": "button",
      "level": "link",
      "onClick": {
        "action": "openDialog",
        "args": {
          "title": "View Details",
          "body": {
            "type": "form",
            "body": [
              {
                "type": "input-text",
                "name": "browser",
                "label": "Browser"
              }
            ]
          }
        }
      }
    }
  ]
}

Corresponds to the XML format:

<operation label="Operation">
  <buttons j:list="true">
    <button label="Details" level="link">
      <onClick action="openDialog">
        <args title="View Details">
          <body>
            <input-text name="browser" label="Browser" />
          </body>
        </args>
      </onClick>
    </button>
  </buttons>
</operation>

The XPL template language in the Nop platform provides many simplifications for dynamically generating XML:

<button xpl:if="xxx" label="${'$'}{grade}" icon="${icon}">
</button>

xpl:if is a conditional expression; the entire node is generated only if it returns true. During generation, if any XML attribute value is null, it is automatically omitted from the final output — leveraging this null attribute filtering mechanism, one can concisely control which attributes are generated.

Schemas converted to XML become very close to ordinary HTML or Vue templates, greatly improving the experience of manual writing and reading.

10.5 Accessibility (a11y) — Responsibility of the Component Library Layer

Accessibility is handled by the underlying component library. shadcn/ui is built on Base UI, which provides complete WAI‑ARIA support:

Dialog: automatic focus trapping, Escape to close, focus restoration.
Select / Combobox: full ARIA roles, arrow key navigation.
Menu: roving tabindex, aria‑expanded state management.
Form controls: automatic association between labels and inputs, aria‑describedby for error messages.

The responsibility of the Flux renderer is not to break these existing accessibility capabilities — pass through aria‑* attributes, do not replace semantic elements with div, do not swallow keyboard events. This is about "not doing wrong things" rather than "actively doing things".

10.6 GraphQL Simplification

GraphQL always requires specifying the list of fields to return. However, for a low‑code platform, which fields exist in a form can be derived from the model. The Nop platform supports directly calling a GraphQL backend via REST‑style configuration:

{
  "url": "/r/NopAuthUser__get",
  "data": { "id": "${id}" },
  "gql:selection": "xxx,yyy"
}

gql:selection automatically generates the GraphQL field selection set based on the current form's field definitions, reducing the amount of information schema authors need to manually maintain.

10.7 Summary

This layering allows Flux to maintain a smaller responsibility scope and a simpler internal structure. The rendering framework is a pure schema interpreter; it does not need to know about i18n, permissions, or modularity — those concerns have already been resolved before it sees the JSON. a11y is guaranteed by the component library layer; the renderer only needs to ensure it does not break existing accessibility capabilities. The responsibility boundary of each layer is explicit: problems that can be solved at the structural transformation layer are not carried into the runtime; problems that can be solved at the component library layer are not re‑implemented in the renderer.

11. Technology Stack and Layered Architecture

Flux uses React 19, TypeScript 6.0 strict mode, Zustand 5, Vite 8, TailwindCSS 4, pnpm workspace. The choice of Zustand vanilla stores has a clear architectural motivation: the store is decoupled from the React lifecycle, can be created, updated, and subscribed to independently, and is not tied to the component tree — this directly addresses the tight coupling between the store tree and the component tree in AMIS's MST architecture.

The entire project adopts a layered architecture with clear dependencies between packages:

flux-core (type definitions, contracts, pure utilities)
  → flux-formula (expression compiler, evaluator)
    → flux-compiler (schema compilation, diagnostics, template graph construction)
      → flux-action-core (action compilation and dispatch semantics)
        → flux-runtime (stores, lifecycle, runtime bridging)
          → flux-react (React hooks, rendering layer)
            → flux-renderers-* / designer / editor
              → apps/playground

flux-core
  → flux-i18n
    → flux-react / @nop-chaos/ui

Each layer has clear responsibilities; upper layers depend on lower layers, not vice versa. The dependency direction is one‑way, and package boundaries are clean.

The React integration approach is also carefully designed: explicit at the boundaries, implicit in the middle.

Renderer props contain renderer‑local data: schema, node, props, meta, regions, events.
Hooks provide access to runtime state: useRendererRuntime, useScopeSelector, useCurrentForm.

This division makes component interfaces clearer — which data comes from props and which is obtained via hooks is immediately obvious.

12. Host Contract — RendererEnv

The host contract is not an invention of Flux. AMIS already designed RendererEnv: renderers do not call fetch() directly, but call env.fetcher(); they do not manipulate routing directly, but call env.jumpTo(). The core insight of this pattern is: a low‑code framework is essentially an interpreter, and its "system calls" should be implemented by the host, not hardcoded by the framework. The framework only specifies the interface; the concrete implementation is left to the host — this allows the same framework to be embedded into different host environments, leaving the choice of HTTP library and routing library on the host side.

Flux makes two improvements on this foundation.

The first is the introduction of env.importLoader. xui:imports is a new capability introduced by Flux; AMIS has no corresponding mechanism, so naturally AMIS's RendererEnv does not have this interface. importLoader takes over the library loading logic for xui:imports declarations — which module identifier to load, how to cache, how to handle loading failures — all these decisions are fully controlled by the host, while the framework is only responsible for calling it at the right time and managing lexical visibility, registration, and release. The security boundary is thus established: the framework is responsible for executing declarations in the schema that have entered the runtime boundary; the loading and execution of external libraries are completely controlled by the host via importLoader.

The second improvement is the clarification of the minimal required interface. Flux's RendererEnv reduces the interface to two required fields — fetcher (network requests) and notify (message notifications) — all other capabilities (navigate, confirm, functions, filters, importLoader, monitor) are optional. Importantly, the fetcher no longer receives an author‑facing ApiSchema, but an ExecutableApiRequest after runtime request preparation; that is, the evaluation of request expressions, includeScope merging, params normalization, and adaptor application occur before fetcher, so the host sees the final executable request.

Together, these two improvements allow Flux's host contract to be summarized by a formula:

output = FluxPage(schema, env)

schema is a declaration describing "what to render"; env is the execution environment provided by the host; FluxPage is the interpreter. As long as RendererEnv is implemented, Flux can be embedded into any host framework without making any assumptions about the host's routing library, request library, or module system. This is the direction of abstraction that AMIS established, and Flux follows it more thoroughly.

13. Performance Design Principles

In Flux, performance is an architectural decision, not a post‑facto optimization. Flux's performance design follows several prioritized principles:

Preserve the static fast path: access to static values should be zero‑cost, directly returning object references.
Preserve dynamic reference reuse: if the result of a dynamic computation has not changed, return the same object reference.
Avoid constructing merged objects in hot paths: prefer scope.get() over scope.materializeVisible().
Keep selector subscriptions precise: subscribe only to the data that is truly needed.
Apply debouncing or cancellation to high‑frequency actions.

useScopeSelector(selector, equalityFn) is an important tool. It allows selective access to data in the scope instead of subscribing to the entire scope. This avoids cascading re‑renders.

The splitting of React contexts is also critical. Different contexts — runtime, scope, action‑scope, component‑registry, node‑meta, form, page — have different change frequencies. Splitting them reduces unnecessary re‑renders.

These designs are framework‑level general guarantees, not dependent on specific scenarios.

14. Error Handling and Developer Experience

Compilation phase: Under the current baseline, failures in compiling expressions and templates are no longer treated as a default "silent degradation" path; compilation/evaluation errors should be understood and handled as potentially throwing exceptions. Structural issues like unknown renderer types should also be explicitly exposed by the compiler or runtime, rather than relying on implicit fallbacks.

Expression evaluation: Errors during runtime expression evaluation propagate upwards. The error tolerance boundary lies at the host side or in React's ErrorBoundary, not inside the framework.

Dynamic schema loading: When the loadAction request of dynamic-renderer fails, an inline error message is rendered (Error: {message}); the body region is rendered as placeholder content before the schema loading completes. Retrying requires changing the loadAction dependencies to trigger re‑mounting.

Development tools: nop-debugger currently provides a floating debug panel to view timelines for compile, render, action, api, notify, error events, along with a network view and node inspection capabilities based on data-cid. With component handles and form stores, it can already show some component state and form state snapshots. The namespace chain of ActionScope and the complete internal index of ComponentHandleRegistry are not yet exposed as stable debug UI; the expression evaluation panel also remains disabled. Dynamic nodes (expression-node, template-node) retain the source field after compilation, allowing tracing back to the original expression text during debugging; static nodes have no source field.

Strict validation mode: Schema authors can enable strictValidation: true on SchemaRenderer to activate strict compilation mode. In strict mode, the compiler performs stricter checks on schema properties: for renderers with a closed‑prop model, unknown schema properties are reported as errors; for open renderers, unknown properties are reported as warnings. This distinction ensures strictness without affecting renderer types that are designed to accept arbitrary properties.

The practical value of strict mode lies in forward‑compatibility safety: when a renderer's schema contract changes (e.g., a property is renamed or removed), strict mode immediately catches residual old properties instead of silently ignoring them. This immediate feedback avoids subtle issues where "the schema looks correct but the behavior is not as expected". Strict mode can also be toggled at runtime via the debugger, allowing real‑time schema validation without redeployment.

15. Validation Owner Hierarchy

Flux's validation system is organized around a hierarchical Owner structure, where each Owner manages a set of validation contracts with independent lifecycles.

Form owner: the primary validation Owner within a form scope, responsible for managing form‑level field validation. When a renderer detects type: "form", it automatically creates a Form owner and takes over the validation lifecycle of all fields under it.

Page‑root owner: SchemaRenderer creates a validation Owner at the page root level, responsible for handling validation of top‑level fields that do not belong to any form. This ensures that even without an explicit form wrapper, top‑level fields still receive validation support.

Surface owner: a separate validation Owner created by a hosted dialog or drawer surface, providing scoped validation for the content carried by the surface. The lifecycle of a Surface owner is bound to the opening/closing of the surface; when closed, all validation states under it are automatically destroyed.

Detail‑child owner: child validation contracts created by detail‑field / detail‑view, attached to a parent Owner, supporting staged editing and draft validation. Child owners can validate independently without affecting the validation state of the parent Owner; only when submitting are the validation results merged into the parent.

Each Owner has explicit lifecycle stages: bootstrapping → active → refreshing → disposed. The bootstrapping stage completes field registration and mounting of initial validation rules; the active stage accepts user interactions and real‑time validation; the refreshing stage handles synchronization of validation state due to scope data refreshes; the disposed stage cleans up all validation resources.

The formId mechanism makes cross‑form operations possible: actions like setValue / setValues / submitForm can precisely specify the target form via formId, and explicitly fail when formId does not match — avoiding the subtle issue of actions being mistakenly sent to the wrong form.

16. Summary — Design Philosophy

Looking back over the entire Flux design, several consistent core principles can be seen:

Unified semantics over parallel field families. The semantic difference inside a value is determined at the value level, not elevated to object structure; one field, multiple forms, compiler decides, unique field name ensures unambiguous composition.
Compile once, static optimization, dynamic reuse. A one‑time JIT compilation is triggered when the schema loads; at runtime, the benefits of static analysis and dynamic reuse are both enjoyed.
Lexical scope chain, explicit interface, lazy merging. get() is the fast path; readVisible() provides the visible view; materializeVisible() is the low‑frequency fallback; interface semantics are clear and testable.
GUI three‑tree orthogonal separation. ComponentTree, StateTree, ActionTree are independent, sharing the design intuition of lexical lookup but maintaining their own lifecycle semantics.
Declarative import and lexical visibility. ES‑module‑style imports, in‑scope capability visibility, independent lifecycle management (idempotent loading + reference counting + release).
Field‑metadata‑driven compilation; renderers do not guess. The compiler handles complex logic up front; renderers consume normalized output.
Single responsibility, clear computational semantics. data-source is a runtime‑owned value‑producing node; loadAction is a one‑time structure initialization; remote calls uniformly enter the runtime via action dispatch, while the request description object is only responsible for the transport contract.
Configurable explicit styles. The renderer layer does not inject default visual styles unrelated to the schema's intent; basic component visual appearance is provided by shadcn/ui; layout and customization are explicitly declared in the schema via Tailwind utility classes and classAliases, balancing predictability and reusability.
Carry forward and improve the host contract. RendererEnv is the direction of abstraction established by AMIS; Flux builds on it by introducing env.importLoader to support xui:imports and narrowing the fetcher to the final executable request boundary, making the framework a pure schema runtime.
Layered resolution, no cross‑boundary handling. i18n, permissions, modularization are solved at the platform layer via JSON structural transformation; a11y is solved at the component library layer via Radix UI; the rendering framework layer only handles its own concerns — compilation, scoping, actions, rendering coordination. The responsibility boundary of each layer is explicit: problems that can be solved at the structural transformation layer are not carried into the runtime; problems that can be solved at the component library layer are not re‑implemented in the renderer.
Performance designed into the architecture up front. Not post‑facto patching, but a design constraint from the first line of code.

These principles have dependencies among them: unified value semantics enables full‑value tree compilation; value‑level determination makes field composition unambiguous; the three‑tree orthogonal separation allows the asynchronous lifecycle of xui:imports to be managed independently; the computational semantic separation of data-source and dynamic-renderer provides a more solid theoretical foundation for splitting the Service; RendererEnv gives the outermost layer of the layered architecture a clear host integration boundary. Flux does not need to be a do‑everything framework; it only needs to get the rendering layer right, leaving the rest to the platform layer and the component library layer, each fulfilling its own role.

nop-chaos-flux is open source:

The Essence of DDD: The Practice Guide from Philosophy to Mathematics to Engineering

canonical — Sat, 21 Feb 2026 11:48:35 +0000

Introduction: From Theory to Practice

In the first half of this article, the Theory Guide, we explored the philosophical background and mathematical principles of DDD, introducing (Generalized) Reversible Computation as its technical core. We recognized that DDD's effectiveness lies in its ability to guide us in building computational models that are closer to the essence of the domain, while Reversible Computation provides the mathematical foundation for system construction and evolution.

The value of theory must be validated through practice. In this guide, we will focus on the concrete implementation of these ideas, highlighting how the Nop Platform applies Reversible Computation theory to real-world DDD practice. We will see how, through a systematic engineering approach, DDD's strategic and tactical designs can be effectively implemented in code and architecture, thereby lowering the barrier to entry and enhancing the maintainability and evolutionary capabilities of systems.

The (Generalized) Reversible Computation theory mentioned in this text is not the same as the concept of Reversible Computing in physics. It does not refer to the reverse execution of computational instructions but rather to an extended understanding of the concept of "reversibility" at the level of software construction. See Reversible Computation: The Next-Generation Software Construction Theory and Generalized Reversible Computation: Naming and Explaining a Software Construction Paradigm.

The Nop Platform is an open-source reference implementation of (Generalized) Reversible Computation theory. Nop is a recursive acronym for "Nop is not Programming."

Chapter 9: Closing the Engineering Loop of DDD — The Reversible Computation Practice of the Nop Platform

Introduction: From Theory to an Executable Engineering System

In the preceding chapters, we constructed a cognitive framework for software design and evolution from the abstract heights of philosophy and mathematics. Its core is built upon the four pillars of "Space," "Time," "Coordinate System," and "Delta." However, no matter how grand a theory is, it will ultimately become a castle in the air if it cannot be translated into a rigorous, executable, and governable engineering system.

Now, we must answer the final and most crucial question: How is this theory implemented?

The Nop Platform was created to answer this very question. It does not simply provide a set of auxiliary tools for DDD; instead, it thoroughly integrates DDD's strategic and tactical patterns into the unified engineering paradigm of "Reversible Computation + DSL Atlas + Delta." Its ultimate goal is to transform DDD from an "art for masters," dependent on team experience and individual enlightenment, into an "engineering science" that is orchestratable, verifiable, and evolvable.

9.1 Institutionalizing Strategic Design: Boundary-First, Language as Coordinate System

Strategic design is the essence of DDD. The Nop Platform ensures that the strategic blueprint can be accurately and losslessly mapped into the code structure through a series of hard engineering mechanisms.

9.1.1 Physicalizing the Bounded Context: From `Modular Directories` to a `DSL Atlas`

In the Nop Platform, a Bounded Context is no longer a vague logical concept; it is precisely physicalized in engineering terms as:

An independent module root directory (e.g., /nop/iam for the Identity and Access Management context).
Within this directory, a set of DSLs specific to this context form a "DSL Atlas." This atlas may include:
- Data Models: app.orm.xlsx or *.orm.xml
- API and Metadata Models: *.xmeta
- View Models: *.view.xml
- Rule Models: *.rule.xml
- Workflow Models: *.wf.xml
- ...and so on.

These DSLs, constrained by a unified XDef meta-model, ensure that the Ubiquitous Language is no longer a vocabulary floating in wikis or meeting minutes, but a living, parsable, verifiable, and code-generation-driving domain coordinate system.

All these DSLs can be freely converted between Excel and XML/JSON formats through configuration (no coding required). This allows many models to be expressed directly in the familiar Excel format, enabling business analysts to participate directly in the modeling process. The resulting Excel file is both an intuitive requirements document and a precise model that can be automatically parsed to drive code generation, eliminating the disconnect between documentation and code from the source.

9.1.2 Engineering Context Mapping: `Events`, `Services`, and `Transformation DSLs`

In the Nop Platform, the collaboration mechanisms between Bounded Contexts are concretized into the following executable engineering elements, with unified abstract interfaces:

Asynchronous Event Communication: Cross-context collaboration prioritizes Domain Events for loose coupling. The platform provides a unified abstract interface IMessageService for one-way messaging and includes a default implementation based on mechanisms like the SysEvent table, which integrates with database transactions to ensure reliable event publication.

// Unified one-way message abstraction
interface IMessageService extends IMessageSender, IMessageReceiver {
    CompletionStage<Void> sendAsync(String topic, 
          Object message, MessageSendOptions options);
    IMessageSubscription subscribe(String topic, 
          IMessageConsumer listener, MessageSubscribeOptions options);
}

Service Call Integration: For request-response bidirectional communication, the platform provides a unified abstraction through the IRpcService interface. NopRPC, its core implementation, offers a Feign-like strongly-typed client calling experience in about 3000 lines of code. It supports creating proxy interfaces via runtime reflection or compile-time code generation, transparently mapping local method calls to remote IRpcService calls.

// Unified two-way RPC abstraction
interface IRpcService {
    CompletionStage<ApiResponse<?>> callAsync(String serviceMethod, 
          ApiRequest<?> request, ICancelToken cancelToken);
}

// Standardized response wrapper for easy error handling and cross-protocol adaptation
class ApiResponse<T> {
    Map<String, Object> headers;
    int status; // For adapting command-line return codes
    String code;
    String msg;
    T data;
}

The platform also provides adapters like MessageRpcClient/MessageRpcServer to achieve flexible conversion of communication patterns: the core mechanism is request-response correlation based on message IDs. The client generates a unique ID for each request, sends it to a request topic, and waits for a response with the corresponding ID on a response topic. The server subscribes to the request topic, processes the request, and sends the result (or error) along with the ID to the response topic.

Similarly, the capabilities of IRpcService can be used to simulate a one-way IMessageService interface over a two-way RPC channel. This bidirectional adaptation capability demonstrates the flexibility and symmetry of the communication abstraction layer.

Distributed Transaction Coordination: For business scenarios requiring strong consistency, the platform supports TCC (Try-Confirm-Cancel) and Saga patterns for distributed transactions through the NopTcc component. Transaction boundaries and compensation logic are defined via annotations or tcc configurations in the XBiz model, coordinating business operations across multiple services to ensure eventual consistency.
DSL-izing and Dynamic Evolution of the Anti-Corruption Layer (ACL): When model transformation is needed, the Anti-Corruption Layer is no longer scattered throughout the business code. The Nop Platform recommends using the Xpl template language or a dedicated transformation DSL to perform model translation during load-time or compile-time, ensuring the runtime domain core remains unpolluted by external models.
- Powerful Record Mapping: The platform includes a dedicated record-mapping DSL for mapping between two complex objects. It supports conditional mapping, many-to-one/one-to-many transformations, dictionary lookups, and other advanced features, greatly simplifying model transformation logic.
- Multi-format Codec and Batch Processing: The record model itself supports encoding and parsing of binary and text formats, which can be automatically used for parsing and generating TCP messages, data files, etc. Combined with the NopBatch model, it's easy to implement multi-machine, multi-threaded, chunked parallel data processing, providing powerful support for high-performance data integration and ETL scenarios.
- Dynamically Evolving Anti-Corruption Logic: The logic of the anti-corruption layer can also be dynamically evolved through the Delta customization mechanism, ensuring that integration logic can adapt to changes in external systems without modifying the core domain model.

The decay of architecture essentially stems from the system being continuously eroded by random, accidental requirements, leading to an increase in system entropy. Various architectural methods are essentially trying to prevent this entropy increase, but the law of entropy in physics states that this is an unavoidable fate for any system. However, if we change our perspective, even if we cannot completely stop entropy from increasing, we can try to control where it occurs. By isolating random and accidental requirements into independent Delta increments, the overall integrity of the core architecture is decoupled from ever-changing demands, thereby achieving long-term stability and systematically slowing down the process of decay.

9.1.3 Guardrails for Hexagonal Architecture: Descriptive Contracts Derived from `BizModel` and `XMeta`

After clarifying the collaboration mechanisms between contexts, we turn to architectural governance within a context. The core design principle of the Nop Platform is minimal information expression: business descriptions should only contain core domain concepts (What), while delaying or omitting specific technical implementation details (How). This descriptive approach naturally possesses framework-neutrality (independent of any specific runtime), providing an ideal engineering foundation for implementing Hexagonal Architecture.

Technology-Neutral Port Definitions: The service ports provided by a context are represented in code as plain Java classes based on @BizModel (or equivalent XBiz DSL models). Annotations like @BizMutation/@BizQuery only declare business semantics, without containing any HTTP paths, methods, or other protocol-specific information. This ensures the purity of the domain model and its potential for multi-protocol adaptation (e.g., GraphQL, gRPC) from the source.
Contracts Uniquely Derived from Models: The complete contract for a port is uniquely derived from the XMeta model as the Single Source of Truth (SSOT). This model defines data structures, validation rules, and permissions in a purely descriptive manner, and automatically generates:
- GraphQL Schema and OpenAPI documentation
- Runtime input validation logic
- Front-end page skeletons and form rules This ensures source-of-truth consistency from the model to various contract forms.
Supplementing Implementation Details via Delta: Based on Reversible Computation theory, the platform allows for the non-invasive addition of protocol-specific details through the Delta mechanism. For example, a custom URL path can be specified in XMeta via the rest:path extension attribute. This supplementary information is optional and localized, achieving a unification of minimal expression and full customization.
Configurable Replacement of Adapters: All interactions with external infrastructure (databases, message queues, etc.) are handled through Adapters/Drivers. These adapters are where framework dependencies are concentrated and can be replaced via Nop's IoC container in the _delta directory through configuration, without modifying the core code. This ensures the isolation of the domain core from external technical implementations at the architectural level.

Closing the Theoretical Loop: From Minimal Expression to Framework Neutrality

The Nop Platform's DSL models are a minimal, descriptive representation of business information. They capture the most stable and essential business structures, becoming the standard intermediate representation for free transformation between different technical frameworks.

The Inner Logic of Minimal Information Expression: It means describing only the goal (What) while omitting execution details (How). If multiple frameworks all achieve true minimal expression, their information content will inevitably converge toward uniqueness. This uniqueness guarantees that a reversible, equivalent transformation must exist between the different framework representations. By inserting a formal transformation layer into the architecture and combining it with the principle of minimal expression, framework neutrality is naturally achieved.

This purely POJO-based, minimal information expression brings a direct engineering advantage: Nop Platform's API service functions can always be unit-tested in a pure fashion. Because its input parameters and return objects are plain Java objects, testing does not require simulating complex web containers or framework contexts. One can simply construct POJO inputs and validate POJO outputs, which greatly reduces testing costs and, in turn, proves the purity and framework-neutrality of its architecture.

9.2 Platformizing Tactical Design: Built-in Patterns and Emergent Robustness

The Nop Platform internalizes the complex tactical patterns of DDD into standard platform capabilities, allowing developers to naturally follow best practices without conscious effort.

9.2.1 Aggregates, Entities, and Value Objects: Unified by `NopORM` and `XMeta`

The Nop Platform provides a unified, efficient, and domain-aligned design foundation for DDD tactical modeling through its NopORM engine and XMeta metadata model. Its implementation retains the core value of these patterns while avoiding some of the rigid designs of traditional ORMs (like JPA), reflecting the "progressive" and "delta-based" philosophy guided by Reversible Computation theory.

Entity Generation and Extension: The Generation Gap Pattern
Entities in the Nop Platform are directly generated from the ORM model and adopt the classic Generation Gap Pattern. Each entity is generated in two parts: a base class maintained by tools (e.g., _NopAuthUser) and a subclass that developers can freely extend (e.g., NopAuthUser). This pattern perfectly separates mechanical code from business code, ensuring that developer-added business methods are safely preserved when code is regenerated after model changes. Since NopORM entities naturally support one-to-one and one-to-many associations and can directly map rich object graphs, the entity itself often naturally assumes the role of an aggregate root in many scenarios, eliminating the need for extra abstraction layers. Domain logic can operate directly on the association graph centered on the entity, and developers only need to add auxiliary domain methods to the entity (e.g., order.calculateTotalAmount()).
Pragmatic Handling of Associations: Re-examining "Many-to-Many"
NopORM was intentionally designed without built-in support for many-to-many associations. This decision stems from an insight into the nature of relational databases—they do not directly support many-to-many relationships but implement them through an intermediate table. NopORM encourages developers to explicitly define the intermediate entity (e.g., OrderLine), thereby preserving maximum flexibility and extensibility in the model. At the same time, to provide convenience at the domain layer, the platform supports the automatic generation of helper methods on entities that simulate many-to-many associations through a marker during code generation. For example, the order.getProducts() method can internally access the order.getOrderLines() collection and then retrieve the Product associated with each OrderLine to compose the return value. This allows developers to program in a natural object-oriented way at the domain layer while maintaining precise mapping and control of relationships at the persistence layer.
Entities with Built-in Deltas: OrmEntity and State Tracking
Unlike JPA's transparent lazy loading and implicit dirty checking, NopORM provides an active OrmEntity base implementation. This base class accurately tracks all changed properties through a dirtyProps set and automatically records the values before and after modification. This means every OrmEntity instance has a built-in "delta" representation of its own state changes. This mechanism offers two core advantages:

1.  **High-Performance Delta Updates**: When saving an entity, `NopORM` can generate and execute SQL only for the changed fields, rather than updating the entire object.
2.  **Safe Domain Data Merging**: Using the `OrmEntityCopier` tool, complex JSON data from the front end (which can be seen as a data delta `Δ`) can be safely and efficiently merged into the current aggregate root object. This achieves an effect similar to `aggregateRoot.merge(Δ)`, which is crucial for handling concurrent updates and command merging.

The Essence and Implementation of Value Objects: OrmComponent
The essence of a Value Object is not just its immutability, but more importantly, that it encapsulates a cohesive set of business rules and invariants. NopORM implements this encapsulation through the IOrmComponent interface, which is similar in role to JPA's @Embeddable components. However, Nop's design philosophy is progressive and view-based, in stark contrast to JPA's rigid "either-or" choice:
- JPA's Rigidity: A field is either a native field or encapsulated in a Component; you must choose one.
- NopORM's Flexibility: It always generates native get/set methods for every database field, ensuring the most basic access capability. At the same time, OrmComponent is designed as a computable, non-invasive "view" built on top of the entity's fields.
This "view" model brings unprecedented flexibility:

1.  **A single field can be reused by multiple Components**: For example, a `latitude/longitude` field can belong to both a `Geolocation` Component and a `RegionBoundary` Component.
2.  **Robust handling of nulls**: When a Component is composed of multiple fields, a `null` value in one of them **does not cause the entire Component object to be `null`**. The Component always exists, and its internal methods can robustly handle partially missing data, avoiding the potential null pointer traps found in JPA.
3.  **Explicit lifecycle control**: The `IOrmComponent` interface defines methods like `flushToEntity` and `reset`, making the timing of data synchronization between the Component and its owning entity controllable and explicit. This is particularly useful for handling complex derived logic and temporary computed states.

Therefore, in NopORM, a Value Object is seen more as a **carrier of domain rules** and a **consistent view of data**, rather than a simple data container. Its immutability is not a mandatory requirement but is determined by the needs of the invariants it encapsulates.

Dynamic Extension of Entity Models: Built-in Extension Fields Mechanism
To cope with frequent changes in business models and avoid the real-world challenge of frequent database table modifications, the Nop Platform has a built-in, comprehensive Extension Fields mechanism in NopORM. By simply adding a use-ext-field tag to an entity in the Excel data model, you can dynamically add any number of extension fields to the entity without modifying the DDL. These fields are stored uniformly in a dedicated extension table (e.g., nop_sys_ext_field) and, through the ORM engine, provide an access experience at the entity object level that is indistinguishable from native fields. Whether in Java code, EQL queries, or GraphQL interfaces, extension fields can be used, filtered, and sorted just like regular fields. This mechanism provides a standardized solution for resolving customization conflicts in productized software.
Seamless Data Flow and Validation from Port to Entity
The Nop Platform builds an automated, metadata-driven data pipeline from external ports to internal domain entities. The core of this lies in a multi-layered, customizable meta-model system:

1.  **ORM Model (`EntityModel`)**: An `OrmEntity` can directly access its `EntityModel`, which contains complete reflection information at the ORM layer. This is the metadata foundation that supports **persistence concerns** like multi-tenancy, logical deletion, and field encryption.
2.  **XMeta Model**: The **data contract and validation rules** for external ports (like GraphQL, RPC) are defined by the `XMeta` metadata model. `XMeta` can be automatically generated from the ORM entity model (e.g., generating `_NopAuthUser.xmeta`) and also follows the **Generation Gap Pattern**—developers can customize, override, or extend the auto-generated rules in the non-underscored `NopAuthUser.xmeta` file.
3.  **End-to-End Data Processing**: Data from the front end is first validated and transformed by the `ObjMetaBasedValidator`, which is based on `XMeta`. Configurations in `XMeta` like `mapToProp`, `getter`, and `setter` enable declarative implementation of needs like **front-end/back-end property name mapping**, **data format conversion**, and **complex logic computation**. The `validatedData` obtained after validation and transformation is finally merged into the domain entity object using the efficient `OrmEntityCopier` tool. This mechanism ensures the **security, correctness, and semantic consistency** of data as it crosses system boundaries, while liberating developers from tedious data glue code.

Domain-Driven Invariant Abstraction: domain and Metaprogramming
The Nop Platform further deepens the "domain-driven" concept by introducing the concept of data domains (domain) at the field level. This is similar to a Domain in PowerDesigner and serves as an abstraction for field-level business semantics and invariants. For example, a field can be assigned a domain like currency or createTime.

This simple configuration triggers a wide range of cascading semantic effects across the platform, perfectly embodying Nop's design philosophy of "few assumptions, general mechanisms":

1.  **Persistence Behavior**: A field marked as `createTime` will **automatically** be set to the current time when the entity is saved, without any manual coding.
2.  **Front-end Control Binding**: Front-end tag libraries like `control.xlib` will automatically recognize the `domain` configuration and look for a corresponding dedicated control (e.g., `<editor-currency>`), achieving **automatic mapping from domain semantics to UI implementation**.
3.  **Interface Model Generation**: Even more powerfully, through metaprogramming rules defined in `meta-prop.xlib`, a `domain` can **dynamically generate or correct property definitions in XMeta**. For example, for a domain marked as a comma-separated list, the platform will automatically apply transformation rules to convert a `String` type to `List<String>` at the interface level and automatically inject serialization (`transformOut`) and deserialization (`transformIn`) logic.

<!-- Metaprogramming rule example: dynamically generate List<String> schema and transformation logic for the csv-list domain -->
<domain-csv-list outputMode="node">
  <attr name="propNode"/>
  <source>
      <prop name="${propNode.getAttr('name')}">
          <schema type="List<String>"/>
          <transformIn>return value?.$toCsvListString();</transformIn>
          <transformOut>return value?.$toCsvList();</transformOut>
      </prop>
  </source>
</domain-csv-list>

The introduction of these rules is not hard-coded into the platform. Instead, they are dynamically implemented through metaprogramming segments like x:post-extends in XMeta files, which call general metaprogramming directives like <meta-gen:GenPropFromDomain/>. The Nop Platform has very few built-in assumptions; a large number of features and rules are introduced and composed on-demand through general, reversible metaprogramming mechanisms like x:gen-extends and x:post-extends. This allows the platform's core to remain extremely concise while possessing nearly limitless semantic extension capabilities.

9.2.2 Transparent Services and Repositories: NopTaskFlow Orchestration and the Generic `EntityDao`

The Nop Platform internalizes DDD's complex tactical patterns into standard platform capabilities, with the transparent design of Repositories and Services being particularly prominent. Through the unified IEntityDao interface, powerful QueryBean capabilities, and the NopTaskFlow logic orchestration engine, developers can naturally follow best practices without conscious effort.

Unified Repository Abstraction: The Complete `IEntityDao` Interface

In NopORM, repositories are completely transparent. Through the unified DaoProvider, developers can obtain a strongly-typed IEntityDao<T> interface (e.g., IEntityDao<NopAuthUser>). Although each entity has a corresponding Dao interface, business logic typically only uses the Dao interface of the aggregate root, which naturally reinforces the DDD concept of aggregate boundaries.

IEntityDao provides a very complete set of CRUD operations, eliminating the need to derive custom repositories:

// Query by equality
User example = new User();
example.setStatus(10);
IEntityDao<User> dao = daoProvider.daoFor(User.class);
List<User> userList = dao.findAllByExample(example);
List<User> pageList = dao.findPageByExample(example, List.of(orderBy(PROP_NAME_status,true)), 0,100);
User user = dao.findFirstByExample(example);
long count = dao.countByExample(example);
dao.saveEntity(newEntity);

Powerful `QueryBean`: Standardized Encapsulation for Complex Queries

QueryBean provides rich query condition encapsulation, supporting various query scenarios from simple to complex:

1. Complex Condition Queries

// Similar to MyBatisPlus's LambdaQueryWrapper
QueryBean query = new QueryBean();
query.addFilter(eq(PROP_NAME_username, "Zhang San"))
    .addFilter(and(
        or(
            between(PROP_NAME_age, 18, 30),
            eq(PROP_NAME_gender, 1)
        )))
    .addOrderField(PROP_NAME_createTime, true)
    .offset(100)
    .limit(20);

List<User> userList = dao.findPageByQuery(query);
User user = dao.findFirstByQuery(query);

2. Embedded Subqueries

query.addFilter(SQL.begin("o.id in (select y.xx from tbl y where y.id=?)", 3)
   .end().asFilter());

3. Automatic Join Queries

// Composite properties are automatically expanded into join queries
query.addFilter(eq("product.productType.name", "abc"));

4. Unified Filter Model

Filter provides a standard way to express complex conditional logic, reusable across multiple scenarios:

In Java code, built via the FilterBeans utility class
In XML/Xpl templates, using syntax like <eq name="status" value="1" />
Automatically converted to SQL statements or Java Predicates
Visually editable in the front-end via a Condition control
Used uniformly in rule engines, data permissions, etc.

Unified SQL Management: The `sql-lib` Mechanism Surpassing MyBatis

Using the Nop Platform's built-in infrastructure, the sql-lib model can be implemented in less than 1000 lines of code. It centrally manages all complex SQL/EQL/DQL statements, offering capabilities more powerful than MyBatis:

DQL is a multi-dimensional data query language for OLAP invented by the report vendor Ruqian, allowing business users to perform complex cross-table data analysis with simple syntax. See Say Goodbye to Wide Tables, Achieve a New Generation of BI with DQL - Qian Academy

1. Unified Management of Multiple Query Languages

<sql-lib>
  <sqls>
    <sql name="nativeSql">...</sql>
    <eql name="entityQuery">...</eql>
    <query name="dqlQuery">...</query>
  </sqls>
</sql-lib>

2. Delta Customization Support
Customize SQL statements without modifying base product code, using delta files:

<sql-lib x:extends="super">
  <sqls>
    <eql name="yyy">...</eql> <!-- Overrides the base definition -->
  </sqls>
</sql-lib>

3. Powerful XPL Template Language
Compared to MyBatis's limited tags, XPL provides full programming capabilities and tag abstraction:

<sql name="complexQuery">
  <source>
    select <my:CustomFields/>
    from MyEntity o
    where <my:AuthFilter/>
    <c:if test="${!_.isEmpty(status)}">
      and o.status = ${status}
    </c:if>
  </source>
</sql>

4. Macro Tag Metaprogramming
Simplify SQL writing through compile-time macro transformations:

<sql:filter>and o.classId = :myVar</sql:filter>
<!-- Expands at compile-time to -->
<c:if test="${!_.isEmpty(myVar)}">
  and o.classId = ${myVar}
</c:if>

5. Secure SQL Output Mode
Automatic SQL injection prevention and intelligent parameter handling:

id in (${ids}) <!-- Automatically expands to id in (?,?,?) -->
name = ${name}  <!-- Automatically parameterized -->

6. Strongly-Typed Mapper Interfaces

@SqlLibMapper("/app/mall/sql/LitemallGoods.sql-lib.xml")
public interface LitemallGoodsMapper {
    void syncCartProduct(@Name("product") LitemallGoodsProduct product);
}

Service Logic Orchestration: NopTaskFlow's Fine-Grained Flow Control

NopTaskFlow is the Nop Platform's built-in logic orchestration engine. It adopts the design principle of minimal information expression and can support both heavyweight distributed service orchestration and lightweight, fine-grained logic orchestration at the function level within a service.

Advantages Over Microservice Orchestration Engines:

Direct Local Function Calls: No REST call serialization overhead, supports passing complex domain object references.
Local Environment Integration: Supports executing multiple steps within the same database transaction or OrmSession.
Lightweight Execution: Can run in a lightweight mode with no third-party dependencies and no persistence.
Asynchrony and State Recovery: Built-in support for asynchronous processing, timeout retries, and breakpoint resumption.

Seamless Integration of Service Functions and TaskFlow:

In the xbiz model, a service function can be delegated to a TaskFlow with minimal configuration:

<biz x:extends="/nop/biz/lib/common.xbiz">
  <actions>
    <mutation name="callTask" task:name="test/DemoTask"/>
  </actions>
</biz>

Through compile-time metaprogramming, the platform automatically infers the input and output parameter types and implementation code for the service function from the TaskFlow model, achieving responsive derivation: when the TaskFlow model is modified, the dependent service function definition is automatically updated.

TaskFlow Example: Order Discount Rules

version: 1
steps:
  - type: xpl
    name: book_discount_1
    when: "order.getOriginalPrice() < 100"
    source: |
      order.setRealPrice(order.getOriginalPrice());
      logInfo("No discount");
  - type: xpl
    name: book_discount_4
    when: "order.getOriginalPrice() >= 300"
    source: |
      order.setRealPrice(order.getOriginalPrice() - 100);
      logInfo("Discount of 100");
  - type: xpl
    name: book_discount_2
    when: "order.getOriginalPrice() >= 100 && order.getOriginalPrice() < 200"
    source: |
      order.setRealPrice(order.getOriginalPrice() - 20);
      logInfo("Discount of 20");
outputs:
  - name: realPrice
    source: order.realPrice

Rule Engine Integration: NopRule for Professional Decision Handling

For complex business rules, the Nop Platform also provides a dedicated rule engine, NopRule, which integrates seamlessly with TaskFlow:

<steps>
  <xpl name="calcDiscount">
    <source>
      <rule:Execute ruleModelPath="/nop/demo/rule/discount.rule.xlsx"
                    inputs="${{order}}" xpl:return="outputs"/>
      <c:script>
        order.setRealPrice(order.originalPrice - outputs.discount);
      </c:script>
    </source>
  </xpl>
</steps>

NopRule supports decision tables and decision trees, which can be configured visually via Excel (or edited online), making it especially suitable for managing complex business rules.

Clear Division of Labor in the Service Layer

Through the collaboration of the above components, the Nop Platform achieves a clear division of labor in the service layer:

Repository Layer: Unified abstraction by IEntityDao, providing powerful data access.
Domain Logic: Complex business rules handled by NopRule, process orchestration managed by NopTaskFlow.
Application Service: Hosted by the XBiz model, responsible for use case orchestration and transaction management.
Query Abstraction: All data queries managed uniformly through QueryBean and sql-lib.
CRUD Automation: The platform automatically handles templated CRUD operations, allowing developers to focus on business logic.

9.2.3 Natural Emergence of Event-Driven Architecture: Platform-wide Observability and Declarative Event Weaving

Event-driven architecture is the soul of DDD, but traditional implementations often rely on developers manually publishing events in their code. This "deliberate" approach can easily lead to omissions and clutter domain code with technical concerns. The Nop Platform takes a different path: through system-wide model definitions and a unified delta syntax, it transforms the system into a "naturally observable" organism. This allows event listening and triggering to become a side effect that can be seamlessly woven in at any level in a declarative manner, letting an event-driven architecture "emerge" naturally from the platform.

Cross-Context Events: Reliable Event Bus and the `Outbox` Pattern

For loosely coupled integration between Bounded Contexts, the platform provides a standardized asynchronous event communication abstraction, IMessageService, with a built-in default implementation, SysDaoMessageService, based on mechanisms like the SysEvent table. This implementation is tightly integrated with database transactions, ensuring that domain events are published atomically within the same database transaction as the business operation, providing a reliable engineering foundation for eventual consistency.

System-wide Observability: A Standardized Coordinate System for Event Triggering

As a thoroughly model-driven architecture, the Nop Platform defines DSL models with clear lifecycles at every level of the system. These models naturally standardize event trigger points, providing a unified "observation coordinate system" for declarative event listening:

Service Layer Observation Points: In the XBiz model, which hosts application services, developers can use the observe section to declaratively configure listeners that trigger before or after a service function executes. These listeners can respond to events on a global EventBus, implementing cross-cutting concerns decoupled from business logic.
```

<observe from="MyBizObj" event="createOrder">
<source>
    
</source>
</observe>
```
Persistence Layer Observation Points: The NopORM engine, through the IOrmInterceptor interface, provides extremely fine-grained, entity-level lifecycle events (e.g., pre-save, post-save, pre-update, post-delete). More importantly, the platform's XplOrmInterceptorFactoryBean mechanism allows developers to define "database trigger"-style interception logic for specific entities using the Xpl template language, simply by configuring a /_moduleId/orm/app.orm-interceptor.xml file, without writing any Java code.
```
<interceptor>
<entity name="io.nop.auth.dao.entity.NopAuthUser">
    <post-save id="syncToEs">
        
    </post-save>
</entity>
</interceptor>
```
Process Layer Observation Points: When business logic is finely orchestrated using the NopTaskFlow engine, the event mechanism becomes even more flexible. Developers can either directly insert observation steps to trigger events at any point in the process or use the Step's decorator mechanism (which acts similarly to Java annotations) to non-invasively attach event-triggering side-effect logic to a step.

Declarative Event Weaving: Metaprogramming Injection Based on `Delta`

The most advanced manifestation of the Nop Platform's event-driven capabilities lies in its unified delta-based customization ability. All DSL models follow the XLang delta syntax, supporting metaprogramming extensions through x:gen-extends and x:post-extends. This means that event listening logic itself can exist outside the base model and be "injected" into existing models during a later customization phase via a Delta file.

For example, a standard product module might not initially include audit logging functionality. However, when deploying for a specific client, we can use a _delta customization file to "apply a delta" to key service methods or entity persistence operations, declaratively adding the logic to trigger audit events. This approach achieves complete decoupling and on-demand composition of event concerns, making system observability a dynamically evolving feature rather than a fixed, static design.

Closing the Theoretical Loop: From "Deliberate Design" to "Natural Emergence"

In the Nop Platform, event-driven is no longer just a tactical pattern in DDD; it is elevated to a system-level first principle that permeates the entire architecture. Through:

Standardized observation points (the lifecycles of models at every layer),
A unified listening mechanism (Observe section, OrmInterceptor, TaskFlow Decorator),
Delta-based weaving capabilities (metaprogramming injection),

event listening becomes a "pluggable" capability that can be declared after the fact, precisely targeted, and non-invasively attached. Developers can make the system "grow" event-driven nerve endings without modifying core business logic. This is a profound embodiment of Reversible Computation theory at the architectural level: using a delta (Δ) to superimpose new behavior (⊕) onto an already generated base system (F(X)), ultimately allowing complex event-response capabilities to naturally emerge from the platform.

9.2.4 Queries and Read Models: The Automation of `GraphQL` and `DataLoader`

A long-standing dilemma in traditional API design is whether to create complex interfaces that lead to "over-fetching" or multiple simple interfaces that cause "under-fetching" and numerous network requests.

GraphQL as a Composable Information Algebra System

NopGraphQL fundamentally reinterprets GraphQL, elevating it from a mere API protocol to a universal engine for information decomposition, composition, and dispatch.

GraphQL is essentially REST with a standardized, composable @selection parameter.

For example:

query {
  NopAuthDept__findAll {
    name, status, children { name, status }
  }
}

is equivalent to:

/r/NopAuthDept__findAll?@selection=name,status,children{name,status}

This means GraphQL is a natural superset of REST: when @selection is not provided, the system degrades to traditional REST behavior. This mathematically proves that REST is a special case of GraphQL in select-all mode.

Two-Phase Execution Model: Built-in Separation of Read/Write Concerns

NopGraphQL employs a two-phase execution model, naturally achieving an architectural separation of read and write operations, which aligns with the principles of CQRS:

Phase One: Core Business Execution (within a transaction)
- Automatically starts and commits a database transaction for @BizMutation.
- Executes the main service function to complete the state change.
- The transaction is committed immediately, releasing the database connection in the shortest possible time.
Phase Two: Result Processing (read-only)
- Invokes @BizLoader on-demand based on the client's FieldSelection.
- The ORM Session is forced into read-only mode to prevent state pollution.
- Performs field-level permission checks and data masking.

CQRS Connection: Through @BizLoader and the XMeta model, the system can define data structures and loading logic specifically for query scenarios. This forms a natural separation of responsibilities from the write model, which primarily focuses on state changes and business rules. The read side can freely compose data across aggregates, define computed fields, and apply performance optimization strategies without being constrained by the write model's transaction boundaries or function signatures.

DataLoader Automation: Solving the N+1 Query Problem

Achieve orthogonal decomposition of knowledge through the @BizLoader mechanism:

// Core query
@BizQuery
public NopAuthUser getUser(@Name("id") String id) {
    return userDao.findById(id);
}

// Associated loader
@BizLoader
public List<String> roles(@ContextSource NopAuthUser user) {
    return roleDao.findRolesByUserId(user.getId());
}

When a client queries { user(id:"123") { id, name, roles } }, the engine automatically:

Calls getUser to fetch the core object.
Discovers the need for the roles field and matches it to the roles loader.
Merges and batches queries through the DataLoader mechanism, solving the N+1 problem at its root.

Performance Optimization: Early Information Use and Execution Pruning

Avoid unnecessary computations in phase one by checking the field selection:

@BizQuery
public Order getOrder(@Name("id") String id, FieldSelection selection) {
    Order order = orderDao.getById(id);

    // Perform expensive calculation only when the client needs it
    if (selection.hasField("salesAnalysis")) {
        order.setSalesAnalysis(analysisService.calculateAnalysis(order));
    }

    return order;
}

The Dual Unity of Aggregate Roots and GraphQL

The Nop Platform reinterprets the meaning of an Aggregate Root:

An Aggregate Root is an information construction operation: It builds a unified, highly cohesive "conceptual map."
GraphQL is an information deconstruction operation: It dynamically trims the required data through FieldSelection.

This dual unity of "aggregation" and "selection" ensures both the expressive power of the model and the efficiency of the runtime, allowing the front-end and back-end to evolve independently with clear contracts.

Security Assurance: Field-Level Permission Control

Field-level security is built into the XMeta model.
Field-level ACLs and data masking policies pre-prune permissions during the query plan generation phase.
Unauthorized access and side-channel information leaks are prevented at the source.

Theoretical Value

The innovation of NopGraphQL lies in elevating APIs from a "collection of endpoints" to a "composable information algebra system." Business logic is written once and can be automatically adapted by the engine to multiple protocols like GraphQL, REST, and gRPC, creating a truly living information space.

9.2.5 Eradicating Stubborn Problems: Solving `N+1` and `Database Deadlocks` at the Source

In traditional DDD practice, the inherent conflict between object-oriented navigational queries and database transaction mechanisms often leads to the stubborn performance and concurrency problems of N+1 queries and database deadlocks. The Nop Platform addresses these issues with targeted mitigation and avoidance through the systematic design of its NopORM engine.

Farewell to N+1: Declarative Batch Loading The batchLoadProps function provided by IEntityDao allows developers to preload all necessary associated properties with a single batch query after fetching a list of entities. A simple declaration is all it takes to solve the N+1 problem without breaking the encapsulation of the aggregate.

List<MyEntity> list = dao.findAll();
// Preload multi-level associations with a single batch query
dao.batchLoadProps(list, Arrays.asList("parent", "children", "parent.parent"));

Its internal mechanism is similar to GraphQL's `DataLoader` but is deeply optimized for the association graph characteristics of ORM entities. Compared to the dilemma in JPA—where using entity navigation is most natural, but performance bottlenecks force invasive rewrites of business code—NopORM's **descriptive batch loading** provides a **performance optimization path decoupled from business logic**.

This mechanism also broadens the applicability of aggregate roots. For scenarios like batch processing that require loading large amounts of data, developers do not need to abandon the object-oriented programming model. Simply executing `batchLoad` after loading each chunk is enough to efficiently assemble the complete object graph. More importantly, in higher-level frameworks like `NopGraphQL` and `SqlManager`, batch loading can be automatically analyzed and executed based on the client's Field Selection, achieving **performance optimization that is transparent and imperceptible** to the developer.

Systematically Avoiding Deadlocks: Globally Ordered Write Operations
NopORM abandons JPA's auto-flush mode, which is prone to causing chaos. Write operations like dao.save(entity) only register the entity's state with the current OrmSession and do not immediately generate SQL. All actual database write operations are deferred until just before the transaction commits, to be executed in a single, unified flush operation.

During this process, NopORM globally sorts all pending INSERT, UPDATE, and DELETE operations based on table dependencies and entity primary keys. This mechanism ensures that in any concurrent scenario, the order in which multiple transactions acquire database locks is deterministic and consistent, thus greatly reducing the probability of deadlocks at a system level. The tricky concurrency problem of deadlocks is no longer solely reliant on developers following fragile best practices to avoid; it is largely "designed away" through architectural design.

Addendum: OrmSession as a LoadingCache

In essence, an OrmSession can be viewed as a LoadingCache specifically designed for ORM. When associated data is accessed through object navigation, if the target entity is not yet loaded, the Session automatically calls the corresponding Persister to load it from the database. With NopORM, we can achieve data source transparency: developers can manually "inject" entity objects obtained through any means (e.g., remote API calls, message queues, file parsing) into the Session using the attach method. Once managed by the Session, these objects are indistinguishable from entities loaded from the database; all mechanisms for association access, state tracking, and persistence based on object navigation will work correctly. This ensures that when the data source changes, the core domain model code requires no modification, truly achieving data-source-agnostic domain programming.

interface IOrmSession{
    // ...

    /**
     * Attaches an entity from outside the session to the session.
     *
     * @param entity
     */
    void attach(IOrmEntity entity, boolean cascade);

    /**
     * Assumes all data is in memory, directly finds collection elements in the session,
     * and assembles them into a collection object.
     *
     * @param collectionName
     */
    void assembleAllCollectionInMemory(String collectionName);

    void assembleCollectionInMemory(Collection<? extends IOrmEntity> coll);
}

Architectural Panorama: A Unified Technical Core and Platformized Capabilities

Through the detailed analysis above, we have seen how the Nop Platform internalizes DDD's tactical patterns into standard platform capabilities. The following diagram provides a panoramic view of how these capabilities work together around a unified technical core to form a complete tactical design support system:

This architecture reflects the following core design principles:

Domain Model at the Center: BizObject and ORM form a unified domain object model, hosting the core business logic.
Multi-Engine Platform Integration:
- The GraphQL engine provides flexible query capabilities, automatically optimizing N+1 problems.
- The Workflow and StateMachine engines drive complex business processes.
- BizModel achieves organic composition of business logic through a "dispatch-extend" mechanism.
Transparent Data Access Enhancement: The ORM layer has built-in enterprise-grade features like lazy loading, batch loading, extension fields, and distributed transactions.
Orthogonal Security Architecture: Data permissions and operation permissions are treated as separate concerns, injected into business processes through standard interfaces.
Diverse Integration Support: Native support for integration patterns like MessageQueue, RPC, and BatchFile.

This design allows developers to naturally achieve a robust and evolvable system architecture without consciously following DDD patterns—this is the engineering embodiment of "emergent robustness."

9.3 Programmable Evolution: The "Trinity" Paradigm of Reversible Computation

Reversible Computation provides a solid mathematical and engineering foundation for the implementation and long-term evolution of DDD models through the unified paradigm Y = F(X) ⊕ Δ.

9.3.1 The Unified Evolution Formula: `Effective Model = Generator<Base Model> ⊕ Δ(Delta)`

In the Nop Platform, the construction of any model follows this formula. Whether it's a data model, a UI model, or a process model, its final effective form is composed of a base model (often generated from an upstream model) and one or more Delta packages.

A Profound Mathematical Insight: Full Content is a Special Case of a Delta

This design is rooted in a profound mathematical principle: a full representation is just a special case of a delta (A = 0 + A). In any system with a unit element, the full representation is equivalent to "the unit element + itself." For example, in software construction, the "do nothing" null operation is the unit element, and any operation can be seen as a delta on top of that null operation. This seemingly simple cognitive shift is actually a paradigm shift from "action-oriented thinking" to "noun-oriented thinking" and is the key breakthrough in treating delta as a first-class concept. It completely unifies "building from scratch" and "customizing modifications" mathematically, providing unprecedented flexibility for software evolution.

The Engineering Value of Isomorphic Design

The direct engineering manifestation of this principle is isomorphic design: the format for expressing a delta is identical to that of the full model, eliminating the need for a special format for deltas. Compare JSON Patch with the Nop Platform's implementation:

// JSON Patch (Heterogeneous design, special format)
[
  {"op": "add", "path": "/columns/-", "value": {"name": "newColumn"}},
  {"op": "remove", "path": "/columns/2"}
]

// Nop Platform (Isomorphic design, unified format)
{
  "columns": [
    {"name": "newColumn", "type": "string"},
    {"name": "column2", "x:override": "remove"}
  ]
}

JSON Patch uses a completely different syntax and relies on unstable array indices. The Nop Platform's delta maintains the same structure as the full model, using only a few extension attributes like x:override to express the intent of the change and relying on stable semantic identifiers (like name) to locate elements. This isomorphic design is consistent throughout the platform: from modified data submitted by the front-end to change records in the back-end database, all use a unified delta representation.

A Breakthrough Insight: The Scope of a Delta Can Cover Any Granularity

Recognizing that "full content is a special case of a delta" also shatters a common misconception: that deltas must be small, local changes. In reality, the scope of a delta can cover any granularity—from modifying a single field to refactoring an entire module, and even building a brand new system, all can be expressed through deltas. In a mathematical context with inverse elements, a delta can even express the reverse operation of "from the current system to an empty state." This understanding liberates the mindset of software evolution, providing a unified theoretical framework for system refactoring and customization.

Built-in Delta Support in DSLs: All DSLs Follow a Unified Decomposition and Merge Mechanism

All DSLs in the Nop Platform natively support decomposition and merging, implementing complex model management through the standardized XLang Delta syntax:

<!-- Inherit a base model via x:extends -->
<meta x:extends="_NopAuthUser.xmeta" x:schema="/nop/schema/xmeta.xdef"
      xmlns:x="/nop/schema/xdsl.xdef">

    <!-- Dynamically generate model content via metaprogramming -->
    <x:post-extends>
        <biz-gen:GenDictLabelFields xpl:lib="/nop/core/xlib/biz-gen.xlib"/>
    </x:post-extends>
</meta>

Key mechanisms include:

x:extends: Inherits from an existing model file.
x:gen-extends/x:post-extends: Built-in metaprogramming mechanism, implementing the Generator part of Reversible Computation.
x:override: Specifies the node merge strategy (merge, replace, remove, etc.).
Extension Attribute Support: All DSL model objects support arbitrary extension attributes without modifying the platform's built-in meta-models.

9.3.2 The Deterministic Construction Phase: `S-N-V` (Structure Merge - Normalization - Validation) Loading

The construction process for all DSL models in the Nop Platform is decomposed into three deterministic phases: S (Structure Merge) → N (Normalization) → V (Validation). This layered principle, through clever "process decomposition" and "separation of concerns," solves the core challenges in designing a universal merge algorithm.

The Fundamental Insight: Retreating to Structural Unification

Similar to how relational databases solve data consistency issues by retreating to a non-redundant, standardized table structure, the Nop Platform achieves unified delta processing by retreating to a standardized XDSL structural layer. That is, delta merging is not performed at the level of parsed, strongly-typed object models, but at a lower-level, standardized tree structure (XNode).

Relational Model Theory	Reversible Computation Theory
Schema Definition	XDefinition Meta-model Specification
Non-redundant Tabular Data	Non-redundant Tree-like Information Structure: XDSL
On-the-fly computation on standardized data structures: SQL	Compile-time computation on a generic XNode data structure: XLang

This "one step back" design allows:

Decoupling of merge algorithms from business semantics: A single universal algorithm can handle the merging of all DSLs.
Deterministic merge results: The same input will always produce the same output structure.
Support for unified cross-domain processing: DSLs from different business domains use the same merge mechanism.

"Virtual Time" and Deferred Validation

The S-N-V principle introduces a philosophy of "Virtual Time," which boldly allows a model to exist in a temporary, semantically inconsistent intermediate state during its construction. Before the final validation occurs, the system tolerates the model's "imperfections," thereby completely decoupling the generic "structural arrangement" from the complex "meaning check."

Three-Phase Decomposition

S - Structure Merge: Generic Tree Structure Operations
This phase operates only at the structural layer, executing domain-agnostic, universal algorithms. It mechanically merges the XNode tree based on meta-directives like x:override, ensuring the merge process satisfies the associative law. The output may be an intermediate model that does not yet satisfy semantic constraints.
N - Normalization: Domain-Specific Semantic Processing
On the basis of the merged structure, domain-specific semantic corrections are performed. This is analogous to view computation in relational databases and includes:
- Parsing and applying default values
- Computing derived properties
- Expanding shorthand syntax
- Automatically resolving benign semantic conflicts
V - Validation: Final Legality Check

After all structural semantics have stabilized, a final, global validation is performed to ensure the output is a completely legal model.

Engineering Value: Determinism from Structural Unification

// Unified model loading process: Structure Layer => Object Layer
modelPath => XDSL => [S-N-V processing] => DslModel

This structure-layer-based unified processing ensures:

Algorithmic Generality: The S phase uses one set of algorithms for all models, with O(1) complexity.
Semantic Extensibility: The N/V phases are attached as pluggable rules to specific domains.
High Runtime Performance: All complex transformations are completed at load-time.
Online Dynamic Updates: Supports runtime model hot-swapping through a virtual file system.

Dynamic Delta-based Updates

How can we ensure runtime state consistency when a DSL model is updated with a delta? To answer this, we can look at the solution provided by microservices architecture.

Microservices can achieve dynamic rolling updates because of their so-called stateless design. The traditional object-oriented approach encapsulates functions and the data they process into objects, leading to a tangled mess of functions and data—a spaghetti-like structure that is difficult to break down and, consequently, difficult to update partially. Ideally, we want a layered structure, like a mille-feuille pastry, where layers can be added or removed at will.

The essence of stateless design is the decoupling of processing logic from the runtime state space. The "pure air" of static logic rises, and the "turbid air" of dynamic runtime state sinks. This dynamic state data is pushed out of the static logic structure, with some becoming parameters passed between functions and some becoming persistent data stored in shared storage. This way, the microservice's runtime structure itself no longer explicitly contains state data, so its dynamic updates are not entangled with state space data migration, becoming a problem that can be solved independently.

When accessing a microservice, we first go to a service registry, dynamically look up the service instance by name, and then send it input parameters. The service instance then automatically loads persistent state data based on these parameters. In the abstract language of functional programming, the process of a microservice corresponds to:

  serviceName => Service => input => state => Result

Similarly, in the Nop Platform, the processing of all models follows the same logical structure:

  modelPath => XDSL => DslModel => arguments => scope => Result

Like microservices, the dynamic updating of a DSL model can be independent of the structural migration of the state space.

9.3.3 The Fractal Software Production Line: `XORM` → `XMeta` → `XView` → `XPage`

The Nop Platform decomposes the process from data to page into a multi-stage fractal software production line. Each transformation step on this line strictly follows the evolution formula of Reversible Computation:

XMeta = Generator<XORM> ⊕ Δ_meta
XView = Generator<XMeta> ⊕ Δ_view
XPage = Generator<XView> ⊕ Δ_page

The Essence of Fractal: Infinitely Recursive Decomposition

The core of this fractal design is its self-similarity: each component can be further decomposed into a combination of finer-grained generators and deltas. Not only does the final product follow this pattern, but the generators and deltas themselves also follow the same structure:

Generator<X> = Generator<Generator<X>> ⊕ Δ_generator
Δ_meta = Generator<Δ_base> ⊕ Δ_custom

This means:

Generators can be constructed in layers: A base generator can be customized with a delta to create a more specialized generator.
Deltas can be defined recursively: A delta itself can be composed from more fundamental deltas via a generator.
Unity at every granularity: From the finest-grained field definition to a complete page layout, everything follows the same construction pattern.

Complete Independence at Every Level

Based on this fractal characteristic, each level possesses complete, independent capabilities:

XMeta Level: Can be entirely generated from XORM, written manually from scratch, or built from zero using Generator<Empty> ⊕ Δ_meta.
XView Level: The generator itself can be Generator<XMeta>, or it can be Generator<Empty> plus a complete Δ_view.
Arbitrary Combination: Any level can selectively use information from the level below or be developed completely independently.

This infinitely recursive fractal design completely solves the rigid constraints of traditional MDA (either fully automatic or fully manual), achieving a truly flexible software production line. Developers can intervene at any granularity and any level, using the delta mechanism to achieve all kinds of customization needs, from minor tweaks to fundamental refactoring, while the entire system maintains a unified mathematical structure and predictable behavior.

9.3.4 Full-Stack Delta Customization: The Path of Evolution Without Changing a Single Line of Base Code

In the Nop Platform, the Reversible Computation concept of delta customization is systematically realized through the core technology of a Delta File System. This mechanism turns the ideal of deep customization "without changing a single line of base code" into an engineering reality, fundamentally changing the software delivery and evolution model.

The Delta File System: The Cornerstone of System-Level Customization

The Nop Platform's virtual file system provides capabilities similar to UnionFS in Docker technology, implementing system-level resource customization through layered overlays:

/_vfs/_delta/default/a.xml will automatically override /_vfs/a.xml.
All code loaded via ResourceComponentManager.loadComponentModel("/a.xml") will actually read /_vfs/_delta/default/a.xml after the delta layer is enabled.
Multiple delta layers can be supported by configuring nop.core.vfs.delta-layer-ids, enabling more complex customization strategies.
Model records in the database (e.g., wf:MyWf/1.0) can also be mapped to virtual file paths, bringing dynamically created models under the management of the delta mechanism.

Full-Stack Customization Example: Seamless Overlays from Data Model to Front-end UI

In the _delta directory, by using delta files with the same names as the base models, any layer of the system can be non-invasively modified:

Data Model Delta: In orm/app.orm.xml, use x:override="remove" to delete fields from the base product, or directly add new business entities.
Business Logic Delta: Through an xbiz/app.xbiz file, declaratively add new business methods to the base entity's CRUD services or override existing logic.
IoC Configuration Delta: Override beans/app.beans.xml, using x:extends="super" to append new beans, modify the properties of existing beans, or even replace an entire bean's implementation class.
Front-end UI Delta: In pages/MyEntity/MyEntity.view.xml, add new action buttons to a base list page or modify the layout of a form through delta merging.
Engine Capability Delta: All engine models (rules, reports, workflows) are XDSLs, and extension nodes can be injected or existing definitions modified via the Delta mechanism.

Paradigm Shift: From "1 Core + N Forks" to "1 Base + N Deltas"

The delta mechanism of Reversible Computation brings about a fundamental paradigm shift, upgrading the software construction and delivery model from the traditional branching model to a delta-stacking model:

Traditional Model (1 Core + N Forks): Based on a core version, multiple independent branches (Forks) are created to meet the needs of different customers or markets. This leads to an exponential increase in maintenance costs, makes it difficult to synchronize features between branches, and ultimately results in merge hell.
Reversible Computation Model (1 Base + N Deltas): Based on a unified base product, the final system is generated by stacking multiple independent, composable delta packages (Δ). The unified formula is:
Effective System = Base ⊕ Δ_Industry ⊕ Δ_Region ⊕ Δ_Customer

The Sustainability of Customization and Evolution

This full-stack, delta-based customization method ensures the sustainability of software evolution:

The base product can be upgraded independently: Delta customizations are physically isolated from the base code. Bug fixes and feature enhancements to the base product can be released independently, and custom projects can safely merge these changes by updating their dependency versions.
Customization logic can be accumulated and reused: Customization logic for specific industries or customers can be packaged as independent Delta modules and reused in different projects.
Customization conflicts can be visually traced: Thanks to the metadata preserved by XNode during the merge process, the origin of every custom element can be precisely traced. When conflicts occur between multiple Delta modules, they can be quickly located and resolved.

Through this systematic delta customization mechanism, the Nop Platform achieves the ideal goal of "retaining the efficiency of automation without losing the flexibility of customization," providing a solid technical foundation for the long-term evolution of complex business systems.

Platformized Multi-tenancy: The Tenant as a Coordinate Dimension

This full-stack delta customization mechanism provides an exceptionally elegant, platform-level solution for the complex requirement of multi-tenancy. In the Nop Platform, multi-tenancy is not a "special case" that requires special coding but a natural consequence of its core architecture. Based on the idea that "extensibility is dimension extension," a Tenant is treated as an independent dimension in the system's coordinate space.

When the system needs to load any resource (like an ORM model, a business process, or a UI page), its core model loader (Loader) automatically adds a tenantId dimension, extending the loading function from Model = Loader(resourcePath) to Model = Loader(resourcePath ⊗ tenantId). This is analogous to extending a single-variable function in mathematics to a function acting on a tensor product space.

This abstraction is seamlessly implemented in engineering terms through the platform's Delta File System: when the Loader loads a.xml, it automatically considers the "current tenant ID" as a dimension, prioritizing searching and merging from the tenant-specific delta layer (e.g., /_delta/tenantA/a.xml).

Therefore, whether implementing simple data isolation (by customizing the NopORM model under a tenant delta layer to automatically add a tenant ID filter to all queries) or implementing complex tenant-specific business logic (by customizing NopTaskFlow or NopRule models), everything is accomplished under the unified delta paradigm of Y = F(X) ⊕ Δ. Multi-tenancy is no longer a collection of scattered if-else statements but a universal, predictable system behavior that emerges from the platform's first principles.

9.4 Contract-First: From "Living Documents" to "Living Systems"

The Nop Platform elevates the DDD principles of "Ubiquitous Language" and "Model-Driven" to a truly automated, contract-first software production line.

9.4.1 Contract is Model, Model is Contract: An Automated Production Pipeline Starting with `Excel`

In Nop, Contract-First is implemented in its most thorough form. All key designs, such as data models and API interfaces, are clearly defined in an Excel model during the requirements phase. This model is no longer a static document but an "executable contract," the single source of truth that drives all subsequent automated processes. Once the "contract" is established, the platform can automatically generate database DDL, back-end entities and services, API documentation, and even front-end page skeletons.

AI-Enhanced Model Generation

The Nop Platform's DSL-driven architecture is naturally suited for AI-assisted development. By interacting with large AI models, one can directly generate DSLs like orm.xml and xmeta, which can then be automatically converted to Excel format using the platform's built-in converters:

AI Generation => orm.xml => Automatic Conversion => Excel Model

9.4.2 Reversible Transformation of Multiple Representations: Lossless Conversion and Delta Merging of Excel, XML, JSON

Reversible Computation theory states that information has multiple representations that are mutually convertible. The Nop Platform engineers this: any model naturally has multiple forms, such as Excel, XML, JSON, and YAML, and can be automatically converted back and forth. A technical person can enjoy the syntax checking of XML in an IDE, while a business person can review and even edit the same model in the familiar environment of Excel.

More importantly, these representations are also delta-based. A business person can define only the changes in an app-delta.orm.xlsx file, and then, using command-line tools, safely merge multiple Delta models with the base model.

# XML → XLSX
java -jar nop-cli.jar convert app.orm.xml  -o app.orm.xlsx

# XLSX + Delta XLSX → XML
java -jar nop-cli.jar convert app.orm.xlsx app-delta.orm.xlsx -o app.orm.xml

9.4.3 Unified Governance and Quality Assurance: Full-Link `Traceability` and `Snapshot Testing`

The Nop Platform provides powerful governance capabilities for this complex automated system:

Full-Link Traceability: Thanks to the rich metadata preserved by XNode during the merge process, any final result in the system (like a button on a page) can be _dumped with a single command to precisely trace its complete "generation history": in which base file and on which line it was originally defined, and which delta files modified it.
Contract is Test: Through JunitAutoTestCase and the @EnableSnapshot annotation, the platform can automatically record service call requests, responses, and all observable side effects as a "snapshot." Subsequent test runs automatically compare against this snapshot, achieving "contract as test." This can dramatically reduce the cost of creating and maintaining automated tests.
Complete Observability and Deterministic Side Effects: Reversible Computation theory posits that a well-designed system should have complete observability. The key criterion for this is that all side effects (such as database state changes, message queue sends, cache updates, file system operations, external API calls, etc.) should be observable.

The complete behavior of a software system can be abstracted as:
```
Complete System Behavior = Input + Output + Side Effects
```
Traditional unit tests often focus only on inputs and outputs, ignoring various side effects, which leads to:
- Non-deterministic test results
- Fragility due to environmental dependencies
- Difficult-to-reproduce intermittent issues
The Nop Platform, through its systematic observation mechanisms, can capture and record all key side-effect data. When we supplement the input/output dataset with this observed side-effect data, we get the complete information set of the system's behavior:
```
Deterministic Test Case = Input + Output + Observed Side Effects
```
This complete observability eliminates all unknown side-effect influences, restoring a test case that was once disturbed by its environment into a purely deterministic function. This fundamentally overcomes the problem of test fragility caused by incomplete information.

Based on this principle, the Nop Platform implements reliable record-and-replay unit testing:
- Recording Phase: The system completely records input parameters, return values, and all observable side effects (including database change logs, message sending records, cache operations, etc.).
- Replay Phase: By replaying the same input, the test verifies the complete consistency of the output and all side effects.
- Environment Isolation: The test does not depend on a real external environment; all side effects are replayed in a controlled, simulated environment.
This testing method is particularly suitable for verifying complex systems after multiple Delta layers have been applied, ensuring that customizations do not break original business logic and providing a solid guarantee for the reliable evolution of the system.

From an architectural perspective, complete observability provides a solid technical foundation for event-driven architecture. As mentioned earlier, through system-wide standardized observation points, the system can automatically trigger events at the precise moment of a state change, making declarative event weaving possible and thus achieving a complete decoupling of business logic from cross-cutting concerns.

This also inversely proposes an important criterion for judging architectural design: is the system's observability sufficient to enable automated record-and-replay testing, transforming complex business logic processing into a deterministic pure function?

Chapter 10: The Final Paradigm Revolution — From "Applying DDD" to "Emergent DDD"

Introduction: The "No-Move Is the Best Move" State of Architecture

At this point, we have detailed from an engineering perspective how the Nop Platform solidifies DDD's strategic and tactical patterns into a rigorous, executable, and closed-loop system. However, to truly understand the change that the Nop Platform brings, we must answer a deeper question: what is the fundamental difference between it and other frameworks that attempt to standardize DDD?

The answer lies in a profound paradigm revolution: from consciously "Applying DDD" to unconsciously "Emergent DDD."

This transformation is akin to the paradigm shift in physics from Newtonian mechanics to relativity. Newtonian mechanics relies on detailed force analysis, requiring us to precisely calculate every action and reaction—just as traditional DDD practice demands that developers constantly maintain design vigilance, consciously partitioning boundaries, defining entities, and building aggregates. It is an "architectural design" based on external rules and active effort.

But Einstein's relativity showed that spacetime itself is curved by mass and energy, and the motion of objects is simply them following the shortest path (a geodesic) in this curved spacetime. It no longer focuses on isolated "forces" but describes the intrinsic geometric properties of spacetime itself. Similarly, the ultimate goal of the Nop Platform is not to provide a more refined set of "DDD design tools," but to shape a "curved space" through its meta-model system and delta-merge mechanism, a space where domain models can grow naturally. In this "space," defined by Reversible Computation theory, the organization of code, the partitioning of boundaries, and the evolution of models spontaneously tend toward the form that best fits the essence of the domain.

Just as the highest level of martial arts is "the best move is no move," the ideal endpoint of DDD practice may well be to "forget DDD" itself. When the construction space of the system inherently contains all the evolutionary possibilities of domain models, the deliberate "application" of specific design patterns is no longer necessary. Structures that are true to the domain's essence will emerge naturally within it.

10.1 From Application-Layer Abstractions to First-Principle Support

A fine example of traditional DDD architecture is the Explicit Architecture proposed by Herberto Graca. See Explicit Architecture (01): Fusing DDD, Onion Architecture, Clean Architecture, CQRS.... The Nop Platform aims to achieve similar technical goals, but through a different path.

Most frameworks that attempt to engineer DDD are essentially providing fixed abstractions at the application layer. They offer a series of base classes or interfaces like AggregateRootBase, AbstractRepository, and DomainEvent. Developers must consciously inherit from and implement them, as if they were building an application with a set of "DDD building blocks." The intention is good, but it still requires the developer to first be a competent DDD thinker and then "translate" that thinking into calls to the framework's specific APIs.

The Nop Platform takes a radically different path. It does not provide fixed DDD patterns at the application layer but instead provides the first principles at the underlying level of software construction that support the natural emergence of these patterns.

10.1.1 The Internalization of Patterns: A Comparison with the Evolution of the `Singleton` Pattern and `DI` Frameworks

This is like the history of modern high-level languages and frameworks:

Once upon a time, developers had to manually implement the "Singleton Pattern" and constantly be wary of concurrency pitfalls like double-checked locking. But with the advent of modern Dependency Injection (DI) frameworks (like Spring or NopIoC), a developer simply declares a component's scope (@Singleton), and the "singleton" becomes a natural result; we no longer need to care about its complex underlying implementation. Similarly, we once had to manually implement the "Observer Pattern," but today's reactive programming frameworks allow us to simply declare data streams and transformation relationships, and the complex event propagation and subscription management are made transparent by the framework.

The Nop Platform elevates this idea of "pattern internalization" to the level of the entire DDD system.

10.1.2 The Protocol-Neutral BizModel: Dissolving the Redundant `Controller/Service/DTO` Layers

In traditional layered architectures (like Controller-Service-DAO), concepts like Controller, Service, and DTO form explicit, mandatory layers. This leads to a large amount of glue code and "translation loss": domain objects need to be converted and encapsulated at each layer, and the rich domain objects returned by a Service are "flattened" or converted into specialized DTOs in the Controller layer to adapt to front-end requirements or hide internal details.

The Nop Platform, through its unified NopGraphQL engine and protocol-neutral BizModel, completely dissolves these redundant boundaries.

A BizModel is a pure expression of business logic, independent of any external interface protocol. A developer simply uses @BizModel and @BizMutation/@BizQuery annotations on a plain Java class (POJO) to define the core business logic. This method directly returns domain entities, aggregate roots, or other complex domain objects.

The key to achieving protocol neutrality lies in its minimalist interface signature. Unlike many traditional MVC frameworks that allow or even encourage exposing runtime-specific objects like HttpServletRequest or WebContext in Controller methods, NopGraphQL service function input parameters are strictly limited to pure POJOs (or primitive types), and an optional FieldSelection (to sense client query needs). It does not need, and cannot access, any runtime objects specific to the HTTP protocol or any other transport protocol.

This design brings fundamental benefits:

Automatic Decoupling: Business logic is decoupled from any specific interface protocol (like HTTP, gRPC, or message queues) at its source. The same BizModel can be exposed as GraphQL, REST, RPC, and other endpoints without any modification.
Purity and Testability: Since it does not depend on any web container or framework context, the service function can be unit-tested in a pure fashion. Testing simply involves constructing POJO inputs and validating POJO outputs, drastically reducing the complexity and cost of testing.
Clear Intent: The function signature clearly expresses the business input and output, with no "noise" related to technical implementation, making the domain logic the absolute core.

So, with such a pure interface, how are complex interface adaptation needs met? The fundamental reason is that the NopGraphQL engine provides a powerful, standardized "post-processing pipeline" that replaces the hand-written, scattered glue code of traditional architectures.

When a BizModel's service function returns a result, the engine's subsequent processing is far from simple JSON serialization. This substantial post-processing layer automatically executes a series of complex and critical logic:

On-Demand Loading and N+1 Optimization: The engine parses the client's FieldSelection, automatically identifies associated properties that need to be lazy-loaded, and uses the DataLoader mechanism for batch loading, solving the N+1 query problem at its root.
Field-Level Post-Processing: Based on configurations like transformOut and getter defined in the XMeta meta-model, it performs complex transformations, calculations, and formatting on field values. This allows the interface to return computed fields or derived fields that do not directly exist on the entity model.
Field-Level Security Control: It automatically applies data permission checks and data masking policies at the field level. Based on the current user's permissions, it dynamically decides which fields can be returned (field pruning) and how sensitive fields (like phone numbers, ID cards) should be returned (field masking).
Multi-Protocol Adaptation: The same BizModel can be simultaneously exposed as GraphQL, REST, gRPC, and other protocols. The post-processing pipeline will appropriately wrap the response according to the protocol's characteristics.

Therefore, the return value of a BizModel does not need to be a DTO specially prepared and "pre-processed" for a specific interface. It only needs to return the most natural and richest domain object. All the adaptation, trimming, security, and optimization work for the interface is handled uniformly and declaratively by the engine's post-processing pipeline. The BizModel becomes a protocol-neutral domain core, and the NopGraphQL engine acts as the single, powerful universal adapter, completely eliminating tedious DTOs and manual glue code.

10.1.3 Separating the CRUD Subspace: From the `Repository` Pattern to `IEntityDao` and "Complement Space" Programming

A widely held view in the DDD community is that "simple CRUD systems are not suitable for DDD." This reflects the powerlessness of the Repository pattern when faced with large amounts of templated CRUD code. The traditional approach requires defining a dedicated Repository interface for each aggregate root, which leads to an inherent contradiction: CRUD operations themselves form a highly unified mathematical subspace with a complete set of operations, yet they are artificially segregated by different object types.

The Nop Platform proposes a solution derived from mathematical thinking: separate the CRUD subspace. Since CRUD operations (Create, Read, Update, Delete) have a unified structure and a complete set of operations, they should be addressed with a unified, generic solution.

1. A Unified Entity Space and Descriptive Persistence

In NopORM, we no longer need to define a separate Repository for each entity. The platform provides a generic IEntityDao<T> interface, which serves as a complete tool applicable to all entity types. More importantly, NopORM reinterprets persistence operations:

The traditional Repository.save carries an imperative execution semantic; calling it means immediately or scheduled execution of a database operation.
In NopORM, session.save is essentially descriptive: It merely registers the entity object with the current OrmSession, a unified entity space, for management. The entity is brought under the Session's jurisdiction, its state changes are tracked (via the built-in dirtyProps delta), but the actual database operations are deferred until the transaction commits, to be handled uniformly.

The direct benefit of this descriptive management is that the composition of operations has mathematical determinism. For example, saving an entity and then immediately deleting it will result in these two operations canceling each other out during the final flush, producing no database calls. This reflects the "delta stacking" idea in Reversible Computation: (+Δ) ⊕ (-Δ) = 0.

2. Subspace Decomposition: Long-Wave Background and Short-Wave Foreground

We can understand this design using an analogy from wavelet analysis in signal processing:

CRUD operations are like the long-wave background of a signal. They change slowly, have a uniform structure, and can be perfectly predicted and automated.
Unique domain logic is like the short-wave foreground of a signal. It carries the main information content, changing rapidly and unpredictably.

The traditional Repository pattern attempts to decompose the entire signal using the same "basis" (i.e., one Repository per aggregate root), which causes the background noise (CRUD template code) to interfere with the foreground information (domain logic). Nop Platform's approach is to perform an orthogonal subspace decomposition:

CRUD Subspace: Handled automatically by the generic IEntityDao and the built-in CrudBizModel. This subspace chooses a set of "standard orthogonal bases" (create, delete, update, find, paginate, etc.), providing a unified and complete solution for all entity types.
Domain Logic Complement Space: This is where the truly valuable, non-standard, and unique business logic resides. Developers are refocused here, in the XBiz model or domain services, to concentrate on writing that unique business logic.

This can be expressed with an elegant Reversible Computation formula:

Complete Domain Behavior = Generator<CRUD Subspace> ⊕ Δ(Domain Complement Space)

Conclusion: Developers do not need to have all their business classes inherit from interfaces like CrudRepository. IEntityDao is used as a complete tool to solve the uniform CRUD background problem. The developer's core job is to work in the XBiz "delta (Δ)" model, within the domain complement space, focusing on implementing the unique logic that truly defines the core business value, thereby being completely liberated from boilerplate CRUD code.

10.2 From "Deployment Decision" to "Compositional Freedom"

DDD emphasizes that a microservice is a deployment decision, while a Bounded Context is a logical boundary. The Nop Platform brings this philosophy to its ultimate practice through its modularization mechanism.

10.2.1 Module as Bounded Context: A Physical Carrier with an Independent `DSL Atlas`

In Nop, a module is the physical carrier of a Bounded Context. Each module has its own independent ORM model, permission model, business service model (BizModel), and a whole set of other models, forming its own "DSL Atlas." They are self-contained and have their own "intrinsic coordinate system."

10.2.2 Composition as Architecture: Free Switching Between `Modular Monolith` and `Microservices`

Nop's IoC container has powerful capabilities for automatic module discovery and assembly, which brings unprecedented architectural flexibility:

When you package your application and include multiple module dependencies, they run in the same process, automatically forming a high-performance "modular monolith."
When you package only one module, it independently becomes a "microservice" application.

10.2.3 Location-Transparent Communication: Automatic Adaptation Between `Local Calls` and `Remote RPC`

Interaction between modules always occurs through defined API interfaces (ports). The underlying Nop framework automatically handles the communication details: if the called module is in the same process, it's an efficient local method call; if the called module is remote, it automatically switches to an RPC call.

This means that architectural evolution—from monolith to microservices—is no longer a painful, major refactoring effort, but merely a matter of changing the application's packaging composition.

10.3 From "Data-Centric" to "Information Flow Inversion"

The design philosophy of the Nop Platform also triggers a fundamental shift in how business logic is implemented.

10.3.1 Refocusing the Aggregate Root: From "Write Boundary" to "Information Access Center"

In traditional DDD, the primary responsibility of an Aggregate Root is established as the write boundary for "consistency" and "transactions." This design has its merits in a monolithic architecture, often manifesting as a black-box command method (e.g., order.confirm()) that is internally responsible for synchronously and atomically transitioning the aggregate from one consistent state to another.

However, this pattern reveals its limitations in microservices architectures and complex business scenarios:

Stateless, service-oriented architectures reduce the need for strong in-memory consistency: Domain objects are temporarily reconstructed from persisted data that is already consistent. A brief inconsistency within a process is not observable externally. The key guarantee lies at the commit threshold—ensuring that the final persisted delta change (Δ) satisfies database constraints and business rules.
Black-box methods are not conducive to orchestrating and understanding complex logic: Encapsulating a complex business operation involving multiple entities and invariants within a single method on the aggregate root turns that method into a large, difficult-to-test and maintain "God function." More importantly, the very concept of using a single function to guarantee all invariants is inappropriate. A business consistency constraint (invariant) typically involves only a few objects and properties within the aggregate, which could have been described and validated independently.

The Nop Platform, through its NopTaskFlow orchestration engine, provides a more expressive "gray-box" modeling approach. The function that modifies a business entity does not have to be a black-box method on the aggregate root. A service function (or a large business action) can be decomposed into multiple clearly defined Steps, each responsible for handling a local state transition or validating a specific invariant. This decomposition makes the process of guaranteeing complex consistency transparent, traceable, and easily composable.

To understand this shift, we need to re-examine the essence of a domain model. A domain model is expressed through a domain language, and the aggregate root is the most direct and cheapest carrier for implementing that domain language. The so-called ubiquitous language first provides a vocabulary (class names, method names, property names), and the aggregate root then defines the feasible organization of these words. The aggregate root provides a stable "base space" (data structure and associations), while domain services represent the "dynamics" (business behavior) that occur in this base space. This clear separation of roles can be seen as an improvement on traditional DDD after absorbing ideas from functional programming.

Based on this understanding, the Nop Platform fundamentally reinterprets and refocuses the responsibilities of the aggregate root:

The core value of an aggregate root lies in defining a stable "domain structure space" (base space) and ensuring "optimal information accessibility."

This structure space is composed of the following elements, which remain highly stable throughout the product's lifecycle, across deployments for different customers, and through various customizations:

Core data structures: The entity and its key properties.
Rich intrinsic associations: Stable relationships between entities (one-to-one, one-to-many, etc.).
Fixed computed properties: A small number of derived calculations that are independent of specific business logic and are purely determined by the entity's own properties (e.g., totalPrice = unitPrice × quantity).

The primary responsibility of the aggregate root shifts from maintaining a "write boundary" and providing "black-box consistency methods" back to building a logically unified, richly associated, and freely navigable object graph. This object graph becomes the information access center for the entire Bounded Context, providing the most natural and complete source of information for various read-side needs (like condition checks in the NopRule engine, data extraction for reporting engines, data sources for complex queries) and for the steps of write-side processes.

Under this model, the consistency guarantee for write operations is moved up, decomposed, and "platformized":

Transaction Boundaries: Defined by service methods (i.e., Actions in @BizModel).
Consistency Constraints: Guaranteed step-by-step by process steps and ultimately validated by database constraints, forming a multi-layered safety net.

This refocusing brings a fundamental advantage: the aggregate root no longer sacrifices its structural clarity and evolutionary flexibility to accommodate an outdated consistency encapsulation model. It returns to its essence as a rich "information source," while complex state transition logic is elegantly implemented through orchestratable process steps. This clear separation of structure (base space) and behavior (dynamics) is the architectural cornerstone that supports the deep customization and long-term evolution of productized software.

10.3.2 Decoupling Business Logic: From "Pushing Data (DTOs)" to "Pulling Information (Expression Language - EL)"

In the traditional approach, each business function (like a rule or a report) requires its own carefully prepared parameters (DTOs). When the logic is slightly adjusted, it often requires modifying multiple function signatures along the call chain. The essence of this pattern is: we are always writing code for a specific requirement, so we need to prepare and push dedicated data for each requirement.

The Nop Platform, by establishing the aggregate root as a stable "information center," achieves an inversion of information flow. The key lies in a philosophical shift:

In Nop's design, the domain model expressed by the aggregate root is not tailored for specific business requirements but exists as an objective, directly usable, universal information source. It provides a unified, semantically rich information space where various business logics can freely explore and retrieve the information they need.

Based on this design:

From "Push" to "Pull": When the rule engine (NopRule) or report engine executes, what is passed in is the entire aggregate root object or object graph. The engine internally uses expressions (like order.customer.address.city) to actively pull the required information from this rich, universal information source.
Localized Changes: When the logic of a report or rule needs to be adjusted (e.g., changing from basing it on the customer's address to the shipping address), we do not need to modify any caller's code. Because what is passed in is always that complete, objective information source, we only need to modify the local data-fetching expression within the report/rule model itself. This "pull" model greatly enhances the system's decoupling and evolutionary capabilities.

This inversion of information flow completely decouples business logic from the method of data supply. Business components no longer depend on the outside world to prepare data in a specific structure; instead, they declaratively extract what they need from a unified information space. This significantly reduces the coupling between components, making the system much more flexible in responding to business changes.

Chapter 11: Case Study — The Reversible Computation Transformation of a Large Bank's Core System

The value of theory lies in guiding practice. To prove that Reversible Computation is not an "ivory tower" theory tied exclusively to the Nop Platform but a universal, implementable technical philosophy, we examine the transformation of a large bank's core system. This project, without fully adopting the Nop Platform, systematically introduced the core ideas of Reversible Computation into a standard technology stack of SpringBoot + MyBatis + SpringMVC + GraphQL Java, and achieved remarkable results.

11.1 Lightweight Implementation of Core Principles: `Loader as Generator`

The Reversible Computation formula, App = Generator<DSL> ⊕ Δ, hinges on treating the superposition of "generation" and "delta" as a unified construction process. In the bank project, this idea was realized through the lightweight principle of "Loader as Generator."

Load-Time Implementation of Delta Merging: The project team developed a Delta Aware model loader to replace standard JSON/XML parsers. When this loader reads a base model file (e.g., cms.beans.xml, User.mapper.xml), it automatically finds and merges the corresponding file in the delta directory (e.g., /_delta/default/beans/cms.beans.xml). This means the merge logic of Generator<DSL> ⊕ Δ is encapsulated within the loader, making it completely transparent to the runtime engines. What Spring's IoC container and MyBatis see is the final, merged model.
Separation of Compile-Time and Run-Time: Drawing inspiration from Nop Platform's nop-cli tool, they moved some complex model transformations (like Excel to JSON conversion, x:gen-extends expansion, and xdef meta-model validation) to the Maven packaging phase. The runtime engine did not need to be aware of these concepts, keeping the technology stack pure and high-performing. This perfectly illustrates the profound value of separating the "construction phase" from the "run-time phase" in Reversible Computation theory.

11.2 Handling Major Model Changes: The Power of Delta Customization

During the project implementation, the system underwent major model change requirements, which fully validated the resilience of the Reversible Computation architecture:

External System Integration and Table Structure Changes: Key configuration tables and account tables were required to reuse content from external systems, involving destructive changes like table naming conventions and field reductions.
Zero-Code-Change Data Layer Adaptation: Through Delta customization, without modifying the core system's code, the database mapping relationships in MyBatis's mapper.xml were changed solely through delta data model definitions. After merging the Delta models, the system automatically generated a data access layer that conformed to the new specifications.
Mixed Data Source Support: When fetching business objects (BOs), the system could transparently combine multiple data sources:
- Some information was fetched from the local database.
- Other information was fetched from remote APIs.
- All data was managed uniformly in a DataCache, forming a complete domain object view.

11.3 Elastic Extension of Process Orchestration

Based on the Reversible Computation process orchestration mechanism, the system achieved flexible extension of business logic:

Automatically Generated Calling Skeletons: The system automatically generated the basic calling structure for process orchestration based on the API model.
Delta Customization of Processes: Non-invasive modifications were made to the process orchestration definitions through delta files.
Pre and Post Adapters: Pre-adapter steps were added for request data transformation (like dictionary mapping), and post-transformation steps handled response data.
Distributed Transaction Support: At the end of the process, changes in the DataCache were automatically synchronized to remote systems via API calls.

Key Outcome: Despite major changes to the business model, the core business processing code remained almost entirely unchanged (some processing steps were added, and parameters of existing steps were adjusted), fully demonstrating the stability of the delta-stacking architecture in the face of business changes.

11.4 Purifying the Domain Model: Modifying MyBatis to Enable "Aggregate Root Programming"

The core of DDD tactical design is object-oriented programming centered on the Aggregate Root. However, in traditional MyBatis practice, developers often get bogged down in "anemic models" and a proliferation of DAO calls. This project made a key modification to MyBatis to support a domain programming model similar to JPA.

Introducing a DataCache Context: They created a DataCache component, similar to the OrmSession in NopORM. Within the lifecycle of a business operation (typically corresponding to a GraphQL request or a Service method), it acts as a cache and change tracker for entity objects.
State Management and Dirty Checking: State properties (like _state) and a dirty properties set (_dirtyProps) were introduced to the entity objects. When an entity property is modified, it is automatically marked as "dirty."
A Revolution in Programming Model: After this transformation, the way back-end business logic was written changed fundamentally:

// 1. Get the aggregate root from the Manager (Application Service) entry point
IAccountBo accountBo = accountManager.getAccountBo(accountId);
Account account = accountBo.getAccount();

// 2. Pure object programming: Navigate within the aggregate root to execute business logic
ICustomerBo customerBo = accountBo.getCustomerBo();
IAccountBo foreignCurrencyBo = accountBo.getForeignCurrencyBo(currencyCode);

// ... Complex business logic, all accomplished through object method calls ...

// 3. Declare the intent to save
dataCache.save(account);

// 4. At the transaction boundary (e.g., at the end of @Transactional), DataCache automatically flushes.
// At this point, based on dirty checking, it generates and executes SQL only for the changed fields and handles associated objects.

The Core Value of This Transformation: It established a strict programming discipline—absolutely avoid direct use of DAOs in business logic code. When writing business logic, developers only need to, and can only, program against the pure domain concept of the aggregate root. All data access is done through object navigation.

This "Aggregate Root Programming" model brought significant advantages:

Clear Code Intent: Business logic revolves entirely around domain concepts, no longer cluttered with database access details.
Decoupling from Persistence Implementation: Business code does not depend on specific DAO implementations, facilitating testing and architectural evolution.
Transparent Performance Optimization: The DataCache's dirty checking mechanism automatically avoids unnecessary SQL execution while ensuring data consistency.
Clear Architectural Constraints: DAOs are used only at the application service entry point to fetch aggregate roots; within the business logic layer, work is done entirely on the object model.

11.5 Unification and Automation of the Service Layer: Enhancing GraphQL Java

At the service layer, the project chose GraphQL as the unified API gateway and enhanced the standard GraphQL Java library.

RESTful Mapping: To facilitate calls from traditional front-ends, a REST-style mapping layer was provided for GraphQL Java, allowing complex GraphQL queries to be invoked via simple HTTP POST requests.
Automation of Standard CRUD: Based on the Reversible Computation idea of "generation," they developed a set of code generators that could automatically generate GraphQL Schema and corresponding CRUD Resolver implementations from the data model (metadata). This drastically reduced repetitive coding for simple entities, allowing the team to focus on complex business rules.

11.6 Delta-based Configuration for the Front-end: Modular Governance of AMIS JSON

The front-end used the low-code platform AMIS, but its JSON configurations tended to become bloated as the business grew. The project team applied the delta-based thinking of Reversible Computation to manage front-end configurations.

Delta JSON Loader: A generic Delta JSON loader was developed, capable of recognizing extension markers like x:extends in the JSON configuration.
Decomposition and Merging of Configurations:
- Vertical Decomposition: A large page JSON was split into multiple sub-files by UI components (like tables, forms, dialogs).
- Horizontal Generation and Customization: First, basic view skeletons like _form_view.json were automatically generated from the back-end model (e.g., XMeta). Then, developers could create a hand-written form_view.json file to correct, override, and extend the auto-generated content using the x:extends mechanism.

11.7 Lessons from the Case Study: Thought Over Form

The successful transformation of this bank's core system provides us with crucial insights:

Reversible Computation is an architectural philosophy, not a specific product: Its core principles—delta stacking, generative programming, and the separation of construction and run-time—can permeate different technology stacks. The Nop Platform is a complete and self-consistent implementation of this philosophy, but you can also extract its essence to empower your existing systems.
A Path of Gradual Evolution: Enterprises do not need to undergo "shock therapy" by replacing their entire technology stack. They can start by focusing on individual dimensions, such as delta-based management of configuration files or purification of the domain layer, to gradually enjoy the improvements in maintainability and evolvability that the theory brings.
It Solves Fundamental Pain Points: Whether it's the customization of back-end configurations, the anemia of domain models, or the bloating of front-end configurations, these are all fundamental challenges in software engineering. Reversible Computation provides a unified mental model and a tool paradigm to systematically address these challenges.

This case study eloquently demonstrates that the laws of software construction revealed by Reversible Computation theory are being, and will inevitably be, validated and adopted by a wider range of engineering practices, regardless of their specific form of implementation.

Conclusion: The End of DDD Is to "Forget DDD"

What the Nop Platform has initiated is a quiet revolution. It doesn't give you a more complex DDD toolbox; instead, it provides a simpler, more powerful "physics" of software.

In this physics, DDD is not a discipline to be learned, but a destination that is naturally reached. When you use a set of construction tools derived from first principles, you no longer need to constantly constrain yourself with the rules and patterns of design. Your energy will shift completely from the technical problem of "how to build correctly" to the fundamental question of "what the business being built actually is."

Developers need only focus on using DSLs to sketch the blueprint of the business, and a robust, evolvable, and clearly bounded system will emerge as naturally as the stars move in their orbits. This, perhaps, is the most ideal future for DDD in the realm of engineering.

The Essence of DDD: A Complete Guide from Philosophy to Mathematics to Engineering Practice—The Theory Part

canonical — Tue, 03 Feb 2026 13:07:27 +0000

The prevalence of microservices has sparked a renaissance for Domain-Driven Design (DDD). However, a profound debate persists in the industry about whether, and how, its best practices can or should be standardized into a unified technical framework. In the process of implementing DDD, many design meetings are filled with pointless arguments over technical details, with no one able to convince the others.

So, what exactly are the advantages of DDD? Is it about better adapting to the object-oriented ecosystem? Or is it about aligning the team's mental model and clearly mapping managerial resistance into the technical world, thereby bridging the chasm between technology and business? Or perhaps, does it possess a certain technical inevitability that can be proven at a mathematical level? This article, combining the theory of (Generalized) Reversible Computation and the technical implementation of the open-source low-code platform, Nop Platform, will dissect the technical core of DDD.

The (Generalized) Reversible Computation theory mentioned in this article is not the same as the concept of Reversible Computing in physics. It does not refer to the reverse execution of computational instructions but rather to an expanded understanding of the concept of "reversibility" at the level of software construction. See Reversible Computation: The Next-Generation Software Construction Theory and Generalized Reversible Computation: Naming and Interpretation of a Software Construction Paradigm.

The Nop Platform is an open-source reference implementation of the (Generalized) Reversible Computation theory. Nop is a recursive acronym for "Nop is not Programming."

I. The Standard Understanding of DDD: Strategic and Tactical Design

If we were to ask a large AI model: Do you understand DDD? Do you know why it works?

GPT-5 would likely provide the following standard answer:

Yes, I do. Domain-Driven Design (DDD) is both a mindset and a set of practices used in complex business domains to closely align software design with domain knowledge, enabling the faster and more stable delivery of evolvable systems.

What It Is (A Two-Layered Perspective)

Strategic Design: Mapping the Business Landscape, Defining Boundaries, and Team Collaboration

Domain/Subdomain: Decompose business capabilities (Core, Supporting, Generic).
Bounded Context: Use a consistent model and terminology within a clear boundary. Contexts communicate through integration patterns (e.g., Anti-Corruption Layer).
Ubiquitous Language: Business and technical teams share a common language to avoid "translation loss."

Tactical Design: How to Model and Implement within a Boundary

Entity/Value Object, Aggregate & Aggregate Root: Define invariants and transaction consistency boundaries.
Domain Service, Domain Event, Repository, Factory, Specification, etc.
Ports & Adapters (Hexagonal Architecture): Isolate the domain from infrastructure.

Why It Works (The Underlying Mechanisms)

Reduces Cognitive and Communication Overhead: The Ubiquitous Language and collaborative modeling make implicit rules explicit, reducing the "paraphrasing layer" between requirements and code.
Manages Complexity: Bounded Contexts break down large problems into smaller, "high cohesion, low coupling" problems. Aggregates localize strong consistency constraints.
Ensures Business Correctness: Invariants are embedded in the model (rather than scattered in controllers/SQL/validators), making "invalid states unrepresentable."
Promotes Evolution: Clear boundaries and inward-facing dependencies facilitate refactoring and replacement. Domain events and eventual consistency enable looser coupling for cross-boundary collaboration.
Socio-Technical Alignment: Leverages Conway's Law by aligning team boundaries with Bounded Contexts, reducing cross-team friction.
Focuses Resources: Classifying subdomains into Core, Supporting, and Generic helps concentrate modeling and engineering efforts on the "differentiating value" of the core domain.

When It's a Good Fit

For long-term, evolvable projects with complex business rules and changing concepts (e.g., e-commerce orders, financial risk control, supply chain planning).
When multiple teams are collaborating, system boundaries are unclear, and integration is complex.
When strict control over invariants and consistency is required.

When It's Not a Good Fit

For small, short-lived projects that are primarily CRUD-based with simple rules; a simpler architecture is more efficient in these cases.

How to Get Started (Practical Advice)

Discovery & Alignment
- Use Domain Interviews, Event Storming, and Domain Storytelling to map out processes and events.
- Partition subdomains and assess their value (distinguish Core/Supporting/Generic), aligning them with team boundaries.
Drawing Boundaries & Integration
- Define Bounded Contexts and Context Maps (Shared Kernel, Published Language, Anti-Corruption Layer, etc.).
Modeling & Implementation
- Use invariants to define Aggregates; favor small aggregates. Use events or process orchestration (Saga/Process Manager) for eventual consistency across aggregates.
- Prioritize Value Objects (immutable, easy to test); use Entities only when an identity is truly needed.
- Application Services orchestrate use cases, Domain Services contain cross-aggregate domain logic, and Repositories are only responsible for persisting Aggregate Roots.
- Use Ports & Adapters to isolate external systems and infrastructure.
Iteration
- Evolve the model as understanding deepens; refactor frequently. Measure change costs and defect rates to validate if boundaries are appropriate.

A Simplified Example (E-commerce)

Bounded Contexts: Catalog, Pricing, Ordering, Payment, Shipping.
Ordering Context Aggregate: Order (Invariants: total amount = sum of line items; state transitions are restricted; an order cannot be paid for twice).
Cross-Context: An OrderPlaced event notifies the Inventory and Shipping contexts. After successful payment, a PaymentConfirmed event is published, and the order status is updated asynchronously. An Anti-Corruption Layer (ACL) adapts different models between boundaries to avoid shared database coupling.

Common Pitfalls

Using only "tactical patterns" (Entity/Repository) without strategic design, resulting in a Big Ball of Mud.
Treating DDD as a "microservices silver bullet": Microservices are a deployment decision, while DDD is a modeling and collaboration method. DDD can be implemented first within a modular monolith.
Over-enforcing consistency: Forcing invariants that span multiple contexts into a single transaction, leading to high coupling and performance/availability issues.
Failing to implement the language: Using business terms in meetings but switching to technical jargon in the code, breaking the Ubiquitous Language.

One-Sentence Summary

DDD is effective because it uses clear business boundaries, a shared language, and explicit invariants to directly reflect the knowledge structure of a complex business in the code and team collaboration, thereby reducing complexity, increasing correctness, and supporting continuous evolution.

------------End of GPT-5's creation---------

II. The First Principle of DDD: Discovering and Expressing the Inherent Laws of the Domain

As a mature software engineering methodology, DDD is inevitably a comprehensive socio-technical system involving management, technology, and external environmental constraints.

The reason DDD is often difficult to "perfectly implement" is precisely that it attempts to solve real-world problems entangled with various non-technical factors. For instance, when we collaborate with an external team with varying technical skills, high communication costs, and even conflicting interests, these human and organizational issues of interest and coordination (so-called "office politics") directly influence the system's interface design, module division, and even technology choices. This fully demonstrates that many of DDD's design decisions are often rooted in human factors, communication games, and inter-organizational interest coordination.

However, is this the whole truth of DDD? If we temporarily strip away its socio-technical shell and focus purely on the technical domain, do the patterns advocated by DDD still exhibit some form of technical superiority? In other words, why is a pattern like "Aggregate Root" technically better at controlling state transitions than an arbitrary combination of objects? Why is the division of "Bounded Contexts" better at reducing coupling than a monolithic model?

If DDD can indeed solve technical problems widely and effectively, there must be an underlying essential reason at a mathematical level—a manifestation of some objective law that is independent of people and environment.

The starting point of this objective law can be boiled down to one core insight: business logic is, in essence, technology-agnostic. It is a pure information description of concepts, rules, and processes within a domain. Therefore, the most stable and time-resistant software structure is one that can use, and only use, the concepts from the business domain to express business logic. The "and only use" here is key; it means maximizing the avoidance of "technical noise"—those accidental factors originating from specific implementation technologies like databases, message queues, and web frameworks.

Once we can achieve this, we obtain a description built entirely on the domain's inherent structure. By shedding the accidental nature of technical implementations, this description gains long-term stability. More importantly, because it directly reflects the laws of the domain itself, it appears conceptually purer and more elegant.

The domain possesses an inherent regularity, which is the core reason why a domain model can endure through business development cycles and provide lasting value. Imagine if a domain had no inherent laws. In that case, writing code directly for specific business scenarios would suffice. Why bother extracting a stable domain model that can adapt to various business developments? Why is this "intermediate layer" necessary? This is like in software product line engineering, where the reason we extract core assets and variability mechanisms is precisely that we believe there are stable, abstractable, and reusable structures behind a series of similar products. The value of a domain model lies precisely in its ability to capture the stable, essential, and inherently regular parts of the domain problem space.

We can often observe that a business log table designed by a business expert with no knowledge of distributed systems to ensure process correctness is strikingly similar in structure to a Saga log or event sourcing table designed by a distributed systems expert to ensure data consistency.
This is because they are facing the same fundamentally constrained problem: "how to ensure overall correctness in a multi-step, unreliable process." It is the inherent structure of the problem itself that often leads its solutions to converge on similar structures.

From this perspective, DDD's tactical patterns (Aggregate, Entity, Value Object, Domain Service, etc.) are no longer just "best practices" but a series of tools and constraints we've invented to build a technology-neutral, pure expression system for business logic. DDD is technically effective because it guides us to discover and construct a structurally more refined "computational model" that is closer to the essence of the domain problem, rather than scattering business logic haphazardly and accidentally across various corners tightly coupled with technical implementation.

This is also the most fundamental reason why the "Ubiquitous Language" is so important. It is not just to make the team's communication "smoother" or to improve daily interactions, but to ensure that the business logic in the code accurately maps the domain's inherent laws using the problem's own language, avoiding contamination by implementation details. When we insist on using domain concepts instead of technical concepts to express business logic, we are actually ensuring that the code maps the stable structure of the domain, not the accidental features of a specific technology stack. Only a domain model built this way can remain stable and continue to provide value through business evolution and technological change.

III. The Art of Decomposition: Vertical Slicing and Horizontal Layering

Having understood that the goal of DDD is to capture the inherent laws of a domain, a subsequent question arises: How do we systematically construct this "computational model" that reflects the domain's laws? A powerful mental framework is to view software design essentially as a process of "divide and conquer" over a complex problem space, a process that can be reduced to two fundamental dimensions of decomposition: vertical and horizontal.

Vertical Decomposition: The Natural Emergence of Object-Orientation

If we want to decompose a complex design space, the most direct goal is to minimize the coupling between the resulting parts. The ideal situation is for the decomposed parts to be able to evolve completely independently and in parallel.

First-Level Decomposition and Object Naming: To achieve this isolation, the primary task is to find the dimension that "slices the system most cleanly" (the primary decomposition dimension). The choice of this dimension directly corresponds to which core components we conceptualize the system into. When we assign names to these components—such as "Order," "Customer," "Inventory"—we are, in fact, performing object decomposition. This is the most fundamental means of abstraction because it directly corresponds to our cognitive division of core entities in the problem domain. A proper object decomposition has the highest internal cohesion and the weakest inter-component associations.
Second-Level Decomposition and Internal Structure: After identifying the core objects, we naturally need to describe the internal composition of each object. At this point, the second-level decomposed parts cannot be completely unrelated (otherwise, they should have been independent first-level objects). These "somewhat related yet somewhat different" structures are precisely what define an object's internal characteristics and behaviors. In the programming world, they are naturally named properties (data) and methods (functions). This is not a coincidence but a consequence of data and functions being the most basic building blocks of the programming universe.

Therefore, vertical decomposition is a process that naturally leads to object-oriented abstraction. By identifying the core concepts in the domain and their internal constitution, it encapsulates the system's complexity into a series of modular units with clear boundaries and well-defined responsibilities.

Engineering Implementation of Vertical Decomposition: From Conceptual Splitting to Addressable Domain Coordinates

"The nameless is the beginning of heaven and earth. The named is the mother of all things."

The essence of vertical decomposition is to introduce structural asymmetry into an initially homogeneous and egalitarian space of functions and data by identifying "intrinsic relatedness," thereby allowing higher-level concepts (objects) to "naturally emerge."

The earliest programming languages consisted of the 0s and 1s of binary machine language, represented by punched paper tapes. Assembly language "gave aliases" to instructions and addresses, opening the door to a symbolic world. High-level languages like C/Pascal went a step further, supporting custom type names for complex data structures and creating local variable names through local scopes. Object-orientation achieved the next conceptual leap by naming all related data and functions and introducing relative names through the this pointer: the specific meaning of this.fly() is no longer absolute but is determined relative to the object entity pointed to by this.

Looking from the outside in, the first thing we see is the conceptual splitting brought about by vertical decomposition. Taking the Nop Platform as an example, the REST link format for frontend access to the backend is determined by first principles to be /r/{bizObjName}__{bizAction} (e.g., /r/NopAuthUser__findPage). This intuitively splits a complete backend service into multiple independent semantic subspaces based on core domain concepts (like User, Order).

Object names define the split boundaries: NopAuthUser is the product of this split, acting as a coordinate that defines the boundary of a highly cohesive domain concept.

Splitting gives rise to internal aggregation: Within this boundary, the system automatically aggregates all technical implementations of this concept:

NopAuthUser.xbiz - Defines business logic
NopAuthUser.xmeta - Defines metadata model
NopAuthUser.view.xml - Defines the view outline

Recursive evolution of splitting: This splitting process can be applied recursively to achieve fine-grained, delta-based governance. For example: /r/NopAuthUser_admin__active_findPage

Further vertical splitting: NopAuthUser_admin is split again from the generic user concept, forming a specialized version for the administrator role. It can have its own custom business logic (NopAuthUser_admin.xbiz) and UI model, while selectively inheriting the generic user's definition (using x:extends). This perfectly embodies the evolutionary design from a single generic model to a "core model + multiple delta variants."
Horizontal refinement: active_findPage refines the behavior. Its basic logic is the same as findPage, but it additionally specifies the active query condition.

In the Nop Platform, the URL is a direct manifestation of this conceptual splitting, transforming abstract vertical slicing into a stable, addressable engineering contract.

Horizontal Decomposition: The Inevitability of Layered Architecture

Complementing vertical decomposition, which focuses on "what different things constitute the system," horizontal decomposition focuses on "which steps in the process of handling any one thing are fundamentally different." Its goal is to separate concerns, allowing technical logic of different natures to change and be reused independently.

The Natural Separation of Input, Processing, and Output: The most basic horizontal decomposition is to view any process as three stages: "Input -> Processing -> Output." We immediately realize that the same core "Processing" logic can be adapted to different "Input" sources and "Output" destinations. To reuse the core logic and isolate changes, separating these three stages into independent layers becomes a necessary choice.
Three-Tier Architecture: The classic Presentation Layer, Business Logic Layer, and Data Persistence Layer three-tier architecture is a direct embodiment of this horizontal decomposition thinking. It separates the input (Web requests) and output (database operations), which are strongly tied to technical details, from the core business processing logic.

Unifying the Two: A Matrix to Govern Complexity

In a real software system, vertical and horizontal decomposition are not mutually exclusive choices but are simultaneously at play, interwoven to form a design matrix.

Vertical decomposition defines the system's "static structure": It answers, "What are the core objects in the system?" (What it is)
Horizontal decomposition defines the system's "dynamic flow": It answers, "How does a request for each use case travel through the layers, interact with these objects, and complete its task?" (How it works)

An elegant architecture is one that makes clear, consistent cuts along both of these dimensions. It is at the intersection of this vertical and horizontal grid that we can precisely locate the responsibility of each piece of code, thus systematically building a system structure that is stable, flexible, and faithfully reflects the inherent laws of the domain.

IV. Bounded Context: The Revolution of Discovering "Space"

Before the advent of DDD, the world of software design was like the world of physics before Newton's classical mechanics.

1. The Pre-DDD Era: An Infinite, Homogeneous "Absolute Space"

In classical object and layered design, the entire software system was treated as a single, infinite, homogeneous "absolute space."

Unified and Infinite: All objects, regardless of their business domain, existed in the same global namespace and semantic field. In theory, any object could directly or indirectly interact with any other object. This is like all celestial bodies floating in the same boundless ether.
Homogeneous: The space itself had no properties. We only focused on the "objects" (entities) within the space and their interactions (method calls), ignoring the possibility that the "space" itself might have properties and boundaries. Space was merely a passive, transparent background container.
The Focus of Design: Consequently, all design complexity was concentrated on how to manage and organize the "objects" in this space. We invented design patterns, componentization, and other methods to try to bring order to the tangled web of object relationships. But we never considered that the problem might lie with the "space" itself.

2. The DDD Revolution: Discovering "Relative Space"—The Bounded Context

The paradigm shift introduced by DDD is, at a cognitive level, analogous to the shift in physics from Newton's absolute spacetime to Einstein's theory of relativity. Einstein showed that space is not a passive background but a dynamic entity that can be curved by mass and has its own properties.

Similarly, through the Bounded Context, DDD reveals to us that:

The software design space is not unified, but is composed of multiple heterogeneous, bounded "relative spaces."
Each "space" (Bounded Context) has its own unique "physical laws"—this is the Ubiquitous Language. In the "Order space," a "Product" follows one set of rules; in the "Inventory space," the "Product" follows a completely different set of rules.
"Space" defines the meaning of "objects": The true meaning and behavior of an object (like a "Product") are determined by the "space" (Bounded Context) it resides in. Talking about an object without its context is meaningless.

Therefore, the core contribution of the Bounded Context is that it allows us to "see" the space itself for the first time. We no longer take space for granted as a transparent background, but rather treat it as a first-class citizen of design. (Previously, we only saw the foreground and ignored the background.)

3. The Paradigm Shift in Design Brought by "Space"

Once we discover the existence of "space," the entire design paradigm undergoes a fundamental transformation:

From "Objects First, Then Relationships" to "Space First, Then Objects":
- Old Paradigm: We first design a large number of objects and then rack our brains to sort out the relationships between them.
- New Paradigm (DDD Strategic Design): The first thing we must do is partition the space (identify Bounded Contexts). This is a strategic, macroscopic decision. Only after the space is defined can we safely and unambiguously design and evolve the objects (Aggregates, Entities) that belong to that space. Slicing happens within the space.
From "Internal Tidying" to "Boundary Isolation" for Complexity Governance:
- Old Paradigm: Faced with complexity, we try to arrange the furniture more neatly within the same large room.
- New Paradigm: We build walls directly, partitioning one large room into several functionally independent small rooms. Each small room can be simple internally, and interactions between rooms occur through well-defined doors (Anti-Corruption Layers, Open Host Services). Complexity is effectively isolated and controlled by the boundaries.

V. Hexagonal Architecture: Boundaries and Isolation

The "space revolution" in the vertical dimension solves the problem of macroscopic semantic boundaries. Within a single Bounded Context, the evolution of horizontal architecture is dedicated to protecting the purity of the domain model, marked by the evolution from Three-Tier Architecture to Hexagonal Architecture.

Contributions and Limitations of Three-Tier Architecture
The classic three-tier architecture (Presentation, Business Logic, Data Persistence) is a successful application of horizontal decomposition. By separating concerns, it isolates tasks of different natures—user interaction, core logic, and data persistence—theoretically allowing the business logic layer to exist independently of specific data sources and user interfaces.

However, in practice, the "Business Logic Layer" often becomes a vague container. Technical implementation details (like transaction management, database connections, remote calls) can easily leak in and become entangled with core domain rules. More critically, it implies a certain "top-down" hierarchical concept and fails to clearly and symmetrically express a core design intent: to protect the domain core from any external technical influence.
Hexagonal Architecture: A Clear Inside and Outside

The Hexagonal Architecture (also known as Ports and Adapters) is a thorough implementation and sublimation of the three-tier concept. It performs a fundamental conceptual refactoring:

*   **From "Up/Down" to "Inside/Outside"**: It abandons the hierarchically suggestive "upper-layer/lower-layer" concept and explicitly divides the system into an **Inside (Domain Model)** and an **Outside (Technical Implementations & the World)**.
*   **Ports and Adapters**:
    *   The **Inside** declares what functionality it needs or can provide through **Ports**—a set of abstract interfaces.
    *   The **Outside** connects concrete implementations (like web controllers, database repositories) to these ports via **Adapters**.

The essence of Hexagonal Architecture is to transform "technical layering" into "boundary division between the business core and technical implementations." It places the core domain model at the center of the architecture, isolated by a protective ring of ports and adapters. **The domain model is thus no longer "dependent" on any specific technology; it merely defines contracts (ports), and the outside world adapts to it.** This perfectly achieves the goal mentioned earlier of "building a technology-neutral expression system for business logic."

This architectural evolution can be compared to how biological cells achieve a separation of "boundary and interior" through the cell membrane. The cell membrane (Ports and Adapters), acting as a selective boundary, strictly controls the exchange of matter and information between the inside and outside. Its fundamental purpose is to create a protected internal environment, allowing the internal structures to be decoupled from the complexity of the external environment, thereby gaining the ability to evolve and adapt independently. It is through this mechanism that the highly complex and precise chemical reactions (core business logic) within the cytoplasm and nucleus (Domain Model) can proceed stably and efficiently, free from the disorderly interference of the external environment. Bounded Context and Hexagonal Architecture, working together, achieve a similar "cellularization" encapsulation in software systems.

A Convergence of Vertical and Horizontal to Build a Cognitive Mirror

At this point, we can see a clear evolutionary path:

Vertically, DDD completes a paradigm revolution from "organizing objects" to "partitioning space" through Bounded Contexts, solving the problem of macroscopic semantic boundaries.
Horizontally, architectural styles have refined the concept from "separating concerns" to "protecting the core" through Hexagonal Architecture, solving the problem of microscopic technical dependencies.

When the two are combined, we get a powerful architectural paradigm: a system is composed of multiple Bounded Contexts (vertical semantic spaces), and each Bounded Context, in turn, uses a Hexagonal Architecture (horizontal technical boundaries) to organize its internal structure.

This marks an evolution in our design thinking from simple "slicing" and "layering" to the thoughtful design and governance of "boundaries." By drawing clear, robust boundaries in these vertical and horizontal dimensions, we finally construct a software system that can truly map the inherent laws of the domain, possessing both resilience and evolvability—a precise cognitive mirror of domain knowledge in the digital world.

VI. Entity and Domain Event: Evolution in the Time Dimension

Through vertical and horizontal decomposition, we have shaped the spatial structure of a software system. However, a model that truly reflects the laws of a domain must not only depict its static snapshot at a given moment but also describe its dynamic evolution over time. DDD opens up our understanding of the system's behavioral time dimension through two core constructs: Entity and Domain Event.

Entity: Continuity of Identity Through Time

In DDD's tactical patterns, an Entity is defined as an object determined by its identity, not its attribute values. This definition, though seemingly simple, contains a profound philosophical insight: it captures those things in the domain that need to maintain identity as time passes.

Identity: The Anchor Across Time
An "Order" may constantly change its state (amount, shipping address, logistics information) from creation to payment to delivery, but we always consider it the same order. The identity (like an order number) is the "anchor" that allows this order to maintain its selfhood in the stream of time. It answers a fundamental question: "In the full set of state changes, what is immutable and used to track the thing itself?"
The Finiteness of State
An entity's state transitions are not arbitrary. The Aggregate Root pattern imposes a boundary, specifying which states an entity can "control" (those within its aggregate), and ensures the legitimacy of state transitions by guarding invariants. This makes the entity's lifecycle, though long, follow a predictable and constrained path.

An Entity, in essence, is a model for things in the domain that are stateful, have a lifecycle, and need to be continuously tracked over time.

Command and Notice: The Philosophical Distinction Between Intent and Fact

At the source that drives an entity's state evolution, we must make a fundamental distinction: Command versus Notice, which is the divide between intent and fact (To-Do list vs. operation log).

Command: Intent Laden with Uncertainty (Points to the future, the start of a process)
A Command is an imperative sentence expressing the intent for the system to perform an action, such as PlaceOrder or ConfirmPayment. The outcome of a command is not predetermined; it depends on the system's current state and external environment when the command is received. Therefore, executing the same command multiple times may produce different results due to different timing and contexts. This uncertainty is a direct reflection of business rule complexity and the non-deterministic nature of the real world.
Notice: Event as a Confirmed Fact (Points to the past, the end of a process)
A Notice (often represented as a Domain Event in DDD) is a declarative sentence recording a fact that has already occurred and cannot be changed, such as OrderPlaced or PaymentConfirmed. It is an assertion about the outcome of a state transition and contains no execution logic itself. Processing the same notice multiple times should yield a deterministic and idempotent result, because it describes the past, and the past cannot be changed.

[A Note from a Design Perspective]
This distinction clarifies a potential misunderstanding in the classic Command Pattern when applied to business modeling. The "command" recorded in that pattern, to enable safe Redo/Undo, must have its inherent uncertainty eliminated. It essentially records a deterministic change function on the state space. This is closer to what we call an "event" in Event Sourcing—a confirmed, safely replayable factual notice. The true business "command," on the other hand, precedes this deterministic change function; it is the input that triggers the computation and contains the seeds of uncertainty itself.

From a Single Timeline to Parallel Universes: A New Picture of the Time Dimension

The traditional modeling perspective is a "top-down view," where we observe the final state of an entity at a specific point in time. Domain events and technologies like CDC (Change Data Capture) shift our perspective to a "side view"—we begin to focus on the timeline constituted by state transitions itself.

Timeline as a First-Class Citizen and State Deltas
When we take a side view, the entity's current state is no longer the sole focus. The timeline of its complete lifecycle, composed of domain events, becomes equally, if not more, fundamental. The current state is merely a cross-section of this timeline at the "present" moment. More importantly, we can understand this relationship with a concise mathematical formula:
NewState = Action(OldState, Event) = OldState ⊕ Event
Here, the Event can be precisely understood as a Delta in the state space, and the ⊕ operation represents the deterministic evolution function that applies this delta to the old state to produce the new state. This formula clearly reveals the essence of an event as a "state increment."
The Possibility of Multi-Verse Evolution
This mathematical perspective provides a theoretical basis for "multi-verse" evolution. Since the system's evolution is driven by a stream of events, starting from the same initial state S0 and applying different event sequences [E1, E2, ...] through the continuous application of the ⊕ operation will give rise to different timeline branches. This is akin to the "parallel universes" discussed by physicists.
Event Sourcing technology is the engineering practice of this idea: it uses the event stream [E1, E2, ..., En] as the single source of truth for the system's state. The current state is simply the result of calculating S0 ⊕ E1 ⊕ E2 ⊕ ... ⊕ En. This allows us to precisely reconstruct the entity's state at any point in history by replaying the event stream, and even to simulate different "what if..." scenarios by injecting different event sequences.
Infinite Event Streams and System Resilience
Infinitely long, replayable message queues (like Apache Kafka) provide the infrastructure for this multi-timeline picture. They allow domain events, as deterministic deltas, to serve as a permanent, shared communication medium. Different Bounded Contexts (and even different derived systems) can independently consume and process events from the stream at their own pace and with their own logic, building their own state universes based on the same S0 and ⊕ function, thereby achieving unprecedented system decoupling and evolutionary resilience.

Conclusion: Building a System That is Traceable and Sim-ulatable in the Time Domain

By combining the lifecycle of an Entity, the uncertainty of a Command, and the determinism of an Event as a state delta, we construct a model within the software system that is traceable and even sim-ulatable in the time domain.

Entity provides the subject for tracking changes over time.
Command is the intent input, laden with uncertainty, that drives change.
Event (Δ) is the state delta that records confirmed changes, constituting the timeline and driving deterministic state evolution via the ⊕ operation.

This "Command-Event-Entity" triangle, supplemented by the State ⊕ Event mathematical model and the shift from a "state top-down view" to a "timeline side view," makes the system's dynamic behavior thoroughly explicit and mathematical. It transforms business logic from a black box hidden behind method calls into a series of observable, traceable, and even simulatable causal chains. It is on this time dimension that the systems we build with DDD truly gain the insight and evolutionary capability to cope with the complexity and uncertainty of the real business world.

An Entity corresponds to a timeline with its own intrinsic activity. Any operation on it means that different timelines will become entangled, creating complex histories and hard-to-manage side effects. A Value Object, on the other hand, is an immutable snapshot of a fact at a point in time. It has no timeline of its own and can therefore be safely embedded in any timeline as a universal descriptor. This is why one should use Value Objects wherever possible, to avoid the "entanglement" cost brought about by unnecessary entity-fication.

Epilogue: The Price of Irreversible Time—The Real-World Dilemma of Traditional Design

However, in most traditional software designs, this systematic consideration of the time dimension is severely lacking. Systems typically only maintain the "current state" of an entity, discarding the complete evolutionary history. This design leads to the irreversibility of time—when the business needs to "roll back" (e.g., for refunds or interest recalculations), the reverse logic, lacking precise historical events, can only be based on speculation and estimation, which is essentially an imprecise approximation (a reversal based on assumptions, not facts).

This technical information deficit ultimately forces the business to compromise, creating various "imperfect but feasible" solutions. This starkly contrasts with the value of an event-centric model that preserves the complete timeline. It requires us to confront the need for time symmetry from the very beginning of the design process, ensuring the system retains enough information to not only evolve forward but also to perform precise "reversals" when necessary.

This is not just a technical implementation upgrade, but a fundamental shift in design philosophy: from caring only about "what it is now," to also caring about "how it became now" and "how to get back to the past."

VII. Mathematical Insights: Language as a Coordinate System

We have established the cognitive framework for Domain-Driven Design (DDD) to master complexity through the philosophical concepts of "boundary" and "time." Traditional DDD stops here—it provides powerful analytical thinking and a series of patterns, but it essentially remains at the level of qualitative cognition. Can we, however, transform this methodological philosophy into a rigorous, computable, and executable software construction system? The answer lies hidden in a pure mathematical examination of "extensibility" and "system evolution."

1. The Mathematical Axioms of Extensibility

Let's abstract the process of software evolution into a mathematical formula. Suppose a system evolves from an initial state X to a new state Y. If we consider X as a set composed of parts A, B, and C, then the evolved Y might become a set of A', B', and a new part D. This process can be expressed as:

X = A + B + C, Y = A' + B' + D

Here, A' and B' are modifications of A and B, which we can represent as A' = A + dA and B' = B + dB. Substituting this into the equation, we get:

Y = (A + dA) + (B + dB) + D

To establish a clear mathematical relationship between the evolved Y and the original X, we introduce the concept of a "Delta," defining Y = X + Delta. Through simple algebraic manipulation, we can reveal the specific composition of Delta:

Delta = Y - X
Delta = (A + dA + B + dB + D) - (A + B + C)
Delta = dA + dB + D - C

This is a heuristic derivation. The mathematical definition of a Delta in reversible computation theory is more complex, and general Deltas do not necessarily satisfy the commutative law.

This seemingly simple formula reveals two indispensable mathematical axioms for achieving true extensibility:

A Delta Must Include Both "Addition" and "Subtraction": Delta not only contains the new part D and modifications dA, dB (which can be seen as additions), but it must also contain an inverse element -C, i.e., the ability to delete an original part. Any extension mechanism that only supports "addition" (like most plugin systems) is mathematically incomplete.
A Delta Must Be Separable and Relocatable: To achieve separation of concerns, we want to consolidate all changes (dA, dB, D, -C) into an independent Delta package, managed separately from the base system X. When this Delta needs to be applied, the system must be able to know precisely that dA should act on A and -C should remove C.

This second axiom leads directly to an inevitable conclusion: there must exist a precise, unambiguous positioning system within the system, such that any part that can be modified can be uniquely "referenced."

2. The Coordinate System: From Positioning to Addressing

The formal mathematical name for this "positioning system" is a coordinate system. A proper coordinate system must provide us with two basic operations:

value = get(path): Get a value based on a unique coordinate (path).
set(path, value): Set (or modify/delete) a value based on a unique coordinate.

This requires that all objects in the system that need to be focused on, modified, and evolved must have a unique, stable coordinate in this coordinate system.

Looking back at our traditional extension mechanisms, we find that their essence is an attempt to construct some kind of coordinate system:

Plugins/Extension Points: These can be seen as a discrete, predefined set of coordinate points. We pre-dig several "holes" in the system and name them—these are the coordinates. The fundamental flaw of this approach is its predictive nature—we must predict all possible extension points in advance. Too few extension points, and the architecture becomes rigid; too many, and the architecture "dissolves," losing its cohesion. We can never apply an effect at an unforeseen location without modifying the source code.

3. The Intrinsic Coordinates of Language: From General to Specific

How can we establish a coordinate system that is all-encompassing and requires no prediction? The answer lies in something we take for granted: programming languages. Because all system logic must ultimately be expressed through some language, the structure of the language itself constitutes a natural coordinate system.

However, different languages have vastly different precision and applicability in their coordinate systems:

Coordinate System of General-Purpose Languages (GPLs): Languages like Java and C# provide a two-level "class-method" coordinate system. We can locate a class, and then a method within it. AOP (Aspect-Oriented Programming) essentially utilizes this coordinate system and, by introducing mechanisms like Annotations, "refines" it to some extent, adding more "coordinate points." But it still cannot delve inside a method, nor can it stably reference an anonymous inner class or a lambda expression. This is a general-purpose, but coarse-grained, coordinate system. When a minor business change occurs, the "structural mismatch" of the coordinate system often leads to scattered, non-local changes across many source files.
Intrinsic Coordinate System of a Domain-Specific Language (DSL): Physics tells us that the most natural coordinate system for describing circular motion is polar coordinates, not Cartesian coordinates. This polar coordinate system is "intrinsic" to the geometric properties of the problem itself. It leverages the inherent constraint that the radius r is constant, thus simplifying the description of a trajectory that would otherwise require two variables (x, y) to one that requires only one variable, θ (angle), achieving dimensionality reduction of the problem. Similarly, the most natural way to describe a business domain is with a custom-built Domain-Specific Language (DSL). Every node and attribute in the Abstract Syntax Tree (AST) of this DSL can be precisely located by its unique path (e.g., XPath). This constitutes a fine-grained, stable, intrinsic coordinate system tailored for the domain problem.

[Analogy: The Method of Moving Frames in Differential Geometry]

This idea can be compared to the Method of Moving Frames in differential geometry. While a moving trajectory can be described in an external coordinate system, what is more profound is that the trajectory itself naturally generates an intrinsic coordinate system attached to it, one that best reflects its internal geometric properties. For example, for a curve in three-dimensional space, its "moving frame" at each point consists of three mutually orthogonal unit vectors:

Tangent vector (T): Points in the direction the curve is moving.

Normal vector (N): Points in the direction the curve is bending.

Binormal vector (B): Is perpendicular to both the tangent and normal vectors, describing the direction the curve is "twisting" out of its current plane.

These three vectors are completely determined by the curve's own local geometry (velocity, acceleration), not by a fixed external coordinate system. Similarly, business logic is described in a DSL, and the structure of this DSL itself provides the most natural intrinsic coordinate system for describing changes to the business logic (i.e., the Delta).

The core contribution of language paradigms like XLang is to ensure, through mechanisms like the XDef metamodel, that every syntax node in any defined DSL automatically receives a stable domain coordinate.

4. The Macroscopic Puzzle and a Field-Theoretic Worldview

So far, we have found an intrinsic coordinate system for a single domain. But a complex enterprise system often involves multiple domains (e.g., orders, inventory, payments). Trying to describe all domains with a single, monolithic DSL is like trying to accurately map the streets of every city with a single flat world map—it's both impossible and unnecessary.

In modern mathematics, the breakthrough of differential manifold theory was the realization that describing a complex curved space (like the surface of the Earth) cannot rely on a single coordinate system. Instead, one must introduce an "Atlas" composed of multiple local coordinate systems (maps). Each map is responsible for describing only a small region, and the maps are smoothly "glued" together by "transition functions." This idea can be heuristically mapped to software architecture:

A complex system should be described by a "DSL forest" or a "DSL Atlas." Each DSL (e.g., orm.xml, workflow.xml, view.xml) is a "local map," responsible for describing the intrinsic structure of a Bounded Context.
A foundational framework like the Nop Platform, in turn, has the core responsibility of providing the universal "glue"—the common Delta computation mechanism (like x-extends). This allows us to apply a unified, coordinate-based Delta package across different DSL "maps," thereby achieving global, consistent system evolution.

With the introduction of a coordinate system, our worldview undergoes a fundamental shift. It is no longer about the interaction of discrete objects but moves towards a Field Theory worldview. A "field" is a space where a ubiquitous coordinate system exists, and a physical quantity can be defined at every point in that coordinate system. Our focus is no longer on isolated objects, but on objects immersed in the field, and the properties of the field itself.

5. A Revolution in Worldview: From Particles to Waves, From Assembly to Superposition

Ultimately, mastering this ideology based on coordinate systems and deltas will bring about a profound revolution in worldview. This can be compared to the wave-particle duality revealed by quantum physics.

Traditional Worldview: Particle View
- Basic Unit: The world is made of discrete, bounded "objects," "components," and "modules." These are the fundamental "particles" of the software world.
- Construction Method: Through Invasive Assembly. We rigidly connect these "particles" through invocation, inheritance, composition, etc., to build larger aggregates.
- Focus: The internal state and behavior of individual objects. We think: "What is this object? What can it do?"
New Worldview: Wave View
- Basic Unit: The world is composed of a continuous pattern (the coordinate system/field) as the background, and the perturbations (the deltas/Δ) that act upon it.
- Construction Method: Through Non-Invasive Superposition. Different "waves" (delta packages Delta) interfere and superimpose within the same "field" (base structure X), collectively shaping the final complex form Y that we observe.
- Focus: How the background coordinate system evolves, and how the changes (Δ) themselves are combined, transmitted, and interact. We think: "In which coordinate system did what change occur?"

This cognitive revolution is the most valuable gift that (Generalized) Reversible Computation offers us. It leads us from an ontology of "being" to an evolution theory of "becoming." Our understanding of software shifts from static, isolated "entities" to dynamic, interconnected "processes." Once we complete this worldview transformation, we will be able to master the eternal and ubiquitous force in the software world—change—with unprecedented clarity, elegance, and power.

6. A Paradigm Shift in the Principle of Reuse: From "Decomposition-Reassembly" to "Whole-Transformation"

The establishment of the coordinate system and delta model directly triggers a paradigm shift in "reuse." The core of this shift is transforming the cost of change from being "related to the overall complexity of the system" to being "related only to the size of the change itself."

Old Paradigm: "Decomposition-Reassembly" Reuse Based on "Sameness"
Traditional reuse is "modification-based reuse." When a system evolves from X to Y, we must "open up" the internals of X, identify the same parts for reuse, and then modify, replace, and reassemble the remaining parts. In this process, the cost of change is directly related to the overall complexity of the base system X.
New Paradigm: "Whole-Transformation" Reuse Based on "Relatedness"
Reversible computation's reuse is "superposition-based reuse." We treat the entire X as a black-box whole, untouched, and independently create a delta Delta that describes all changes. Finally, we obtain the new system through Y = X + Delta. X is never "opened" or "modified." The cost of change is related only to the complexity of the delta Delta and is completely decoupled from the size and complexity of X.

This is like the difference between "genetic surgery" and "wearing equipment":

Traditional reuse is "genetic surgery": The cost and risk of the surgery are strongly correlated with the complexity of the organism itself.

Reversible computation is "wearing equipment": All costs and risks lie in making the "equipment" (Delta), regardless of whether the organism is a mouse or an elephant.

The ultimate insight of this paradigm shift lies in the fundamental leap of the reuse principle: from Reuse of Sameness to Reuse of Relatedness. We are no longer limited to reusing the same parts in a "part-whole" relationship but can establish a transformation relationship via a Delta between any two related systems X and Y. This makes it possible to "inherit an entire software product just like inheriting a class," perfectly solving the core conflict between "productization and deep customization" in the enterprise software domain.

A Note on the Real-World Form of "Domain Languages"

It is important to note that in the vast majority of DDD practices, the so-called "Ubiquitous Language" or "Domain Language" is far from reaching the rigor of a complete formal language (with precisely defined syntax and semantics). More often, it manifests as a domain vocabulary agreed upon through negotiation, relying on the team's experience and conventions to constrain the combinatorial relationships between these concepts.

The manifestation of this constrained relationship in code is precisely the encapsulation and association mechanisms of object-oriented programming: specific methods can only belong to specific classes (defining "what can be done"), and specific classes can only be associated in specific ways (defining "who is related to whom"). This is, in effect, simulating a constrained context-free grammar—class names and associations form the syntax, while method implementations provide the semantics. Many successful internal DSLs today follow this path: they do not create a new language from scratch but cleverly leverage the class system of a host language (like Java or C#) to build a restricted subset of expressions that is morphologically closer to the domain problem, often using methods like the Fluent Interface.

Therefore, the real-world significance of the "Language as a Coordinate System" insight is that it pushes us to engineer the implicit, vague rules of vocabulary combination into a finite but precise set of explicit specifications. A superior domain DSL is the ultimate embodiment of this process—it strives to upgrade the "coordinate system" of domain expression from an experience-dependent "rough sketch" to a machine-parsable "engineering blueprint."

Wittgenstein famously said, "The limits of my language mean the limits of my world." The (Generalized) Reversible Computation theory further interprets this as: A language is a coordinate system, and from a coordinate system, a delta naturally arises.

VIII. Reversible Computation: Making Evolution Programmable

After "seeing space" with Bounded Contexts and "seeing time" with event timelines, we are just one step away from truly bringing software into a state of sustainable order: seeing the shape of "change" itself and making it orchestratable. The insight of Reversible Computation lies precisely here—it does not treat change as an accidental side effect but reifies change itself, making it data-driven and composable (demoting it from a verb to a noun). It attempts to establish a unified "evolutionary dynamics" for system construction and growth with an extremely simple yet infinitely recursive formula: Y = F(X) ⊕ Δ.

1. The Universal Pattern of Evolution: From a Perturbation Model to a Construction Paradigm

Any computation can be abstractly described as Result = Function(Data). When a system evolves, both the Function and the Data can change: NewFunction = BaseFunction + ΔFunction, and NewData = BaseData + ΔData. The interaction of these underlying changes ultimately leads to a change in the Result.

Traditional approaches get bogged down in analyzing these complex interactions. The revolutionary assertion of Reversible Computation is that regardless of how complex the underlying changes are, their net effect on the final result can always be encapsulated into a single, structured 'Total Delta'.

This means we can describe evolution with a universal perturbation model:

NewResult = BaseFunction(BaseData) + TotalDelta

This formula describes the necessary structure of any evolving system; it is a mathematical necessity. Consider this: if we view the output result as binary data, we can always define a delta between any two pieces of data in binary space using an XOR operation. However, such a raw bitstream-level delta has no business value; it is difficult to understand intuitively and cannot be efficiently composed or maintained.

The real breakthrough is to apply the delta to a structured space. The key here can be compared to the success of Docker container technology:

The delta backup mechanism of virtual machine images is like operating in binary space—feasible but cumbersome.
The App = DockerBuild<Dockerfile> overlay-fs BaseImage paradigm, however, by establishing a Delta within the structured filesystem namespace, achieves lightweight reuse and flexible composition of image layers, thus completely liberating productivity.

Reversible Computation theory elevates this idea to a higher dimension of software construction, implementing the universal computation pattern Y = F(X) ⊕ Δ as a very specific, executable technical formula:

App = Delta x-extends Generator<DSL>

This paradigm precisely decomposes the software construction process into three independently evolvable First-class Citizens:

DSL (Domain-Specific Language): As a precise "Domain Coordinate System"
It defines the problem's description space. A well-structured DSL provides a stable, addressable location for every semantic unit in the system. This is the structural prerequisite for Delta to perform precise addressing and application, and for x-extends to achieve reversible merging.
Generator: As a "Model Transformer" and "Truth Unfolder"
At compile-time, it is responsible for executing multi-stage transformations from abstract to concrete (model-to-model, model-to-code). More profoundly, like the derivation process of a mathematical theorem, it automatically unfolds a highly condensed "kernel truth" (the DSL model) into a complete, runnable base application.
Delta: As a composable "Evolution Unit"
It is an independent, reversible, and non-invasive unit of change. Delta encapsulates all changes, including structured deletion, and its merge operation satisfies the associative law, meaning multiple Deltas can be pre-composed into an independently distributable and versionable "feature pack" or "patch."

Finally, these three first-class citizens are deterministically combined via the x-extends operator. x-extends is an algebraic upgrade to the traditional extends. It is no longer simple property overriding but a reversible, deterministic merge of a first-class citizen Delta within a well-defined structural space. Because its operation is deterministic, the concept of "merge conflicts" found in traditional version control (like Git) does not exist.

In this way, Reversible Computation elevates the trickiest problems in software engineering—"customization," "reuse," and "evolution"—from the realm of external tools or design patterns to the core semantic level of the language itself, providing them with a native, unified, and mathematically sound solution.

It must be emphasized that the formula App = Delta x-extends Generator<DSL> in Reversible Computation theory is not a metaphorical illustration but a technical path that can be rigorously defined mathematically and strictly implemented in engineering. The Nop Platform systematically implements this programming paradigm through XLang, a fourth-generation programming language with a built-in concept of deltas. For details, see Why XLang is an Innovative Programming Language?.

2. The Fractal Construction of Software: Longitudes and Latitudes

To truly understand the essence of Reversible Computation as a "system construction theory," we must grasp the most profound characteristic of the invariant Y = F(X) ⊕ Δ: its recursivity. It is not just a formula but a fractal self-similarity principle that is recursively applied throughout the software world.

This self-similarity is manifested in several fundamental dimensions of software architecture: the vertical "longitudes" (cross-layer), the horizontal "latitudes" (cross-domain), the flow of time (version evolution), and the "meta-level" of the construction system itself. Together, they weave a complete, evolvable "DSL Atlas."

2.1 Vertical Longitudes: The Multi-Stage Software Production Line

The vertical "longitudes" depict a multi-stage software production line, which solves a core dilemma of traditional Model-Driven Architecture (MDA). In traditional MDA, if the reasoning chain is too long (e.g., directly generating final UI code from a highly abstract business model), it leads to overly complex source model definitions and allows information from different abstraction levels to mix chaotically, ultimately becoming difficult to maintain and extend.

Reversible Computation provides a standardized technical path for this, decomposing a one-off, complex model transformation into a series of controllable, clear steps:

Decompose the Reasoning Pipeline: First, a complex A => C transformation is broken down into smaller, more focused steps, such as A => B => C. This makes each stage's responsibility singular and simplifies the model definitions.
Deltify Each Step: This is the most critical innovation. In each transformation step, the upstream model (e.g., A) does not directly generate the final downstream model (B). Instead, it generates a "draft" or "base" model, conventionally named with a leading underscore (e.g., _B). The final B is then obtained by applying a Delta package to customize and extend this draft. This process can be precisely described as:
B = Δ_B ⊕ _B
where _B = Generator<A>.
Allow Information Passthrough: Every stage (Generator) in the production line follows the "principle of tolerance." It only processes information it can understand. For unrecognized extension attributes or metadata from upstream, it will temporarily store and "pass them through" to the downstream unmodified. This ensures that customized information injected at any stage of the production line is not lost.

Taking the built-in model-driven production line of NopPlatform as an example, it clearly decomposes the process from data to page into four main model stages:

XORM: Storage layer model
XMeta: Interface layer model
XView: Framework-agnostic frontend logical view
XPage: Final page model bound to a specific frontend framework

This production line is a perfect embodiment of the technical path described above, where each step can be clearly described by the formula of reversible computation:

XMeta = Δ_meta ⊕ Generator<XORM>
XView = Δ_view ⊕ Generator<XMeta>
XPage = Δ_page ⊕ Generator<XView>

In this way, Reversible Computation completely resolves the dilemma of MDA. It allows us to no longer pursue perfect coverage of all details during modeling. We can concentrate on building core model generators (Generator) that handle 80% of common scenarios, while the remaining 20% of special requirements can be precisely and elegantly injected at any stage of the production line via Delta.

2.2 Horizontal Latitudes: Parallel Projection of DSL Feature Vectors

The horizontal "latitudes" depict a landscape of a DSL feature vector space. In an "Atlas" composed of multiple DSLs, whether it's a UI model, a data model, or a business logic model, they all follow the exact same superpositional evolution rule.

A cross-domain business requirement (e.g., "add a VIP user level") can be precisely decomposed into a set of "isomorphic" deltas {Δ_ui, Δ_data, Δ_logic, ...} acting on different DSL models. Due to the universality of the superposition operator ⊕ (i.e., x-extends), these deltas can be applied uniformly and deterministically within their respective domains. This constitutes a precise feature vector decomposition:

App = [DSL1, DSL2, ..., Δ_residual]

The Δ_residual here ensures the completeness of the decomposition: it represents the "residual" that cannot be perfectly captured by the existing DSL system or requires special coordination. Furthermore, when we treat all known DSLs and their rules as "background knowledge" and strip them away, the remaining content represented by Δ_residual can itself be considered a logically complete whole with its own syntax and semantics, understandable independently of the aforementioned background. This makes the entire vector decomposition mathematically precise and lossless.

2.3 Time Recursion: The Self-Similarity of Version Evolution

In addition to spatial decomposition along longitudes and latitudes, the recursivity of Y = F(X) ⊕ Δ is also reflected in the time dimension. Any entity in the system (be it the entire product or a Delta package) can itself be seen as the result of superimposing an evolution delta onto its earlier version (the base). This forms an infinitely extending evolutionary chain:

Product_V3 = Δ_v3 x-extends Product_V2
And Product_V2 itself is Δ_v2 x-extends Product_V1

Furthermore, each element in the formula (X, F, Δ) can itself be decomposed again. For example, a complex feature delta Δ_feature can be composed of its base version Δ_base and a patch for it Δ_patch: Δ_feature = Δ_patch x-extends Δ_base.

This makes "change" itself a manageable, versionable, and evolvable core asset.

In the engineering implementation of the Nop Platform, this temporal recursion is perfectly embodied through the built-in Delta customization mechanism: developers can make delta-based modifications to existing data models, business logic, and even UI interfaces simply by adding a file with the same name in a specific Delta directory, without modifying a single line of the base product's source code. See How to Achieve Customized Development Without Modifying the Base Product's Source Code.

2.4 Meta-Recursion: The Bootstrapping of the Construction System Itself

This is the most disruptive aspect of Reversible Computation: the toolchain, rules, and platform used to construct the software themselves follow the exact same invariant for their evolution.

Evolution of DSL Definitions (Metamodels): MyDSL_v2 = Δ_meta x-extends MyDSL_v1
Evolution of Build Tools: Compiler_Pro = Δ_feature x-extends Compiler_Base
Even the Evolution of Merge Rules Themselves: MergeRule_New = Δ_rule x-extends MergeRule_Old

The entire software world—from the final product to intermediate models, to the construction system itself—becomes a vast, self-similar delta structural space connected by the ⊕ operator. In this "fractal space," entities at any level and any granularity share the same construction and evolution philosophy. This achieves a true "one law to rule them all," elevating software engineering from a "cottage industry" of repeatedly inventing extension mechanisms for different domains and layers to a unified, self-consistent new era of industrialization. In this new era, the tools we use to build software, and the software we build, follow the same laws of growth.

Figure: A schematic of a delta-oriented architecture based on Reversible Computation, showing the complete stack from the infrastructure layer, through the core engine layer, to the business application layer, with a consistent delta customization mechanism running through all layers. The architecture itself also follows the meta-recursive principle Y = F(X) ⊕ Δ—components at every layer can be customized and extended via deltas, including the construction rules of the architecture itself.

3. The Unified Engineering Cornerstones

To make the grand fractal structure described above achievable in engineering, all DSLs must share an intrinsically unified "physical law." Reversible Computation provides three unified engineering cornerstones for this.

Unified Intermediate Representation (IR): XNode
All DSLs are represented in memory as an enhanced, XML-like tree structure (XNode). It uses a mechanism similar to XML namespaces to achieve "localized metadata," meaning each node and attribute can carry its own metadata (like source file, merge history, etc.) without polluting the business data itself. Based on this structure, we can build a universal, coordinate-based delta merging algorithm whose runtime cost is proportional only to the size of the change, not the size of the overall model.
Unified Metamodel Definition: XDef
XDef is a DSL for defining DSLs. Unlike traditional metamodel technologies (like EMF/Ecore), XDef itself is fully integrated into the delta-superposition evolutionary system. We can customize and extend the language's own syntax rules through deltas, just as we customize business models, providing unprecedented flexibility for language evolution.
Unified Full-Link Traceability: _dump
Thanks to the rich metadata carried and preserved by XNode during the merge process, any final result in the system (e.g., the color of a button on a page) can be precisely traced back to its origin. We can one-click _dump its complete "generation history": in which line of which base file it was originally defined, which modifications from which delta files it underwent, and how it ultimately reached its current state. This capability provides irreplaceable convenience for debugging and understanding complex customized systems.

Through these three cornerstones, Reversible Computation ensures that every "map" in the "DSL Atlas" uses the same paper, the same drafting standards, and the same coordinate positioning mechanism, thus making unified, recursive evolutionary programming possible.

For a detailed introduction to the theory of Reversible Computation, you can refer to my other articles.

Making Evolution Programmable: XLang and the Structured Paradigm of Reversible Computation

XDef: An Evolution-Oriented Metamodel and Its Construction Philosophy

To Be Continued

The above is the first half of this article, where we explored DDD from multiple perspectives, including its philosophical underpinnings, mathematical principles, and theoretical framework. We covered the essence of DDD as "discovering and expressing the inherent laws of the domain," analyzed methods for managing complexity through "vertical and horizontal decomposition," and introduced the cognitive shift from "absolute space" to "relative space." Leveraging (Generalized) Reversible Computation theory and the mathematical perspective of "language as a coordinate system," we have provided a possible theoretical foundation for the engineering of DDD.

The value of theory must ultimately be tested by practice. in the second half of this article, we will turn to the engineering practice level, focusing on how the Nop Platform, based on the theories above, specifically implements DDD's various patterns through the engineering paradigm of Reversible Computation. We will also explore a key question: How can a system design that aligns with DDD principles be made to "emerge" naturally through the support of an underlying technology platform, thereby lowering the barrier to practice, rather than relying entirely on the personal experience and discipline of the designer?

Preview of the Second Half:

Chapter 9: The Engineering Closure of DDD—Reversible Computation in Practice on the Nop Platform

9.1 Institutionalizing Strategic Design: Boundary-First, Language as a Coordinate System
- 9.1.1 Physicalization of Bounded Contexts: From Modular Directories to a DSL Atlas
- 9.1.2 Engineering Context Maps: Events, APIs, and Transformation DSLs
- 9.1.3 Guardrails of Hexagonal Architecture: Declarative Contracts Derived from BizModel and XMeta Models
9.2 Platformizing Tactical Design: Built-in Patterns and Emergent Robustness
- 9.2.1 Aggregates, Entities, and Value Objects: Unified in NopORM and XMeta
- 9.2.2 Transparent Services and Repositories: NopTaskFlow Orchestration and a Generic EntityDao
- 9.2.3 The Natural Emergence of Event-Driven Architecture: A Platform-level Outbox and Synchronous Events
- 9.2.4 Queries and Read Models: Automation with GraphQL and DataLoader
- 9.2.5 Eradicating Stubborn Problems: Solving N+1 and Database Deadlocks at the Root
9.3 Programmable Evolution: The "Trinity" Paradigm of Reversible Computation
- 9.3.1 The Unified Evolution Formula: EffectiveModel = Δ(Delta) ⊕ Generator<BaseModel>
- 9.3.2 The Deterministic Construction Phase: S-N-V (Structure-Merge, Normalize, Validate) Loading
- 9.3.3 The Fractal Software Production Line: XORM → XMeta → XView → XPage
- 9.3.4 Full-Stack Delta Customization Example: The Path of Evolution Without Changing a Single Line of Base Code
9.4 Contract-First: From "Living Documents" to "Living Systems"
- 9.4.1 Contract is Model, Model is Contract: The Automated Production Pipeline Starting from Excel
- 9.4.2 Reversible Transformation of Multiple Representations: Lossless Conversion and Delta Merging of Excel, XML, and JSON
- 9.4.3 Unified Governance and Quality Assurance: Full-Link Traceability and Snapshot Testing

Chapter 10: The Final Paradigm Revolution—From "Applying DDD" to "Emergent DDD"

10.1 From Application-Layer Abstraction to First-Principle Support
- 10.1.1 Internalization of Patterns: A Comparison with the Evolution of the Singleton Pattern and DI Frameworks
- 10.1.2 The Protocol-Neutral BizModel: Eliminating the Redundant Controller/Service/DTO Layers
- 10.1.3 Separation of the CRUD Subspace: From the Repository Pattern to IEntityDao and "Complementary Space" Programming
10.2 From "Deployment Decision" to "Compositional Freedom"
- 10.2.1 Module as Bounded Context: The Physical Carrier with an Independent DSL Atlas
- 10.2.2 Composition as Architecture: The Free Switching Between Modular Monolith and Microservices
- 10.2.3 Location-Transparent Communication: Automatic Adaptation Between Local Calls and Remote RPC
10.3 From "Data-Centric" to "Information Flow Inversion"
- 10.3.1 Refocusing the Aggregate Root: From "Write Boundary" to "Information Access Center"
- 10.3.2 Decoupling Business Logic: From "Pushing Data (DTO)" to "Pulling Information (EL)"

Chapter 11: Case Study—The Reversible Computation Transformation of a Large Bank's Core System

11.1 Lightweight Implementation of Core Principles: Loader as Generator
11.2 Dealing with Major Model Changes: The Power of Delta Customization
11.3 The Elastic Extension of Process Orchestration
11.4 Purifying the Domain Model: Modifying MyBatis to Achieve "Aggregate Root Programming"
11.5 Unification and Automation of the Service Layer: Enhancing GraphQL-Java
11.6 Delta-based Configuration for the Frontend: Modular Governance of AMIS JSON
11.7 Lessons from the Case: Substance Over Form

Third Round of Q&A on the XLang Language

canonical — Sun, 01 Feb 2026 11:47:43 +0000

1. Is XLang a framework or a programming language?

XLang is not a traditional programming language, but if you ask DeepSeek, DeepSeek would answer:

XLang combines the high abstraction of fourth-generation languages with the theoretical innovations of fifth-generation languages. Its core positioning is a “meta-language supporting Reversible Computation,” which boosts development efficiency through low-code and domain-specific syntax while redefining the underlying rules of program construction via structural space theory and Delta operations. Therefore, XLang can be regarded as an evolutionary form of a fourth-generation language—call it a “Fourth-Generation+ Language”—achieving a unique balance between low-code and theoretical innovation.

Mainstream programming languages today are so-called third-generation programming languages (3GL), which typically use a main function as the program’s entry point. Fundamentally, the language design is about writing that executable main function, and the compiler translates the execution logic written in the programming language into instructions executable by a hardware model. Fourth-generation programming languages (4GL), however, began to emphasize descriptiveness, simplifying development through highly abstract declarative syntax and graphical programming tools. In other words, the core of 4GL is “non-procedural,” emphasizing higher-level abstraction rather than adaptation to lower-level hardware models.

With the rise of LLVM, hardware-level optimization is essentially a separate concern, and different programming languages can share a common compilation backend. This does not constitute an essential requirement of a programming language. I expect new languages like Moonbit to offer a very compact, lightweight toolchain. As long as XScript’s AST is translated to Moonbit’s AST, the rest is handled automatically.
XLang includes a sub-language XScript, whose syntax deliberately adopts a subset of JavaScript plus minor extensions, and the type system mimics a simplified Java-like type system. This ensures lossless translation at the AST level to all mainstream programming languages.

Although the Nop platform is a complete low-code platform built on the XLang language, this does not mean that XLang itself is a framework. While XLang currently runs on the JVM and relies on certain helper libraries and implementation classes provided by the underlying Java language, it does not depend on Java. The entire content of XLang can be ported to other programming languages such as Lisp or Rust. When writing business code, you can use only the XLang language without touching the underlying Java language.

2. The fundamental reason a Turing machine achieves Turing completeness is that a Turing machine can be viewed as a virtual machine that can simulate all other automatic computing machines.

For this statement, those with formal training may object: Turing completeness is defined via the Turing machine, so “a Turing machine is Turing-complete” is a conclusion by definition. My view is: if you get entangled in the mathematical definition and say Turing completeness is defined via the Turing machine, that’s fine; but this is merely due to a historical contingency.

Conceptually, Turing completeness and NP-completeness are similar classifications in computation. The computational complexities of every NP-complete problem are comparable; solving any one of them allows you to solve all NP-complete problems. Yet we do not define NP-completeness as “knapsack-completeness.”

Similarly, Turing completeness is an abstract computational capability. All computing machines are equivalent at this capability boundary; no particular machine has a more special capability. By historical accident, this capability was named Turing completeness. Turing completeness can be defined as a computing system’s ability to execute any computable function; it could just as well have been named Lambda Calculus completeness.

In physics, all concepts are independent of any particular problem or choice of reference frame. If one insists that Turing completeness is defined via the Turing machine, that is merely a concrete manifestation of using a specific idealized model to describe an abstract computational capability. What we care about is not the concrete form, but the universal capability itself.

3. Is the development goal of XLang to replace general-purpose languages like Java?

XLang’s development goal is not to replace mainstream languages such as C++ or Java; in fact, they should be complementary.

<c:script lang="groovy">
  Groovy syntax can be used here
</c:script>

XLang uses XML syntax. When execution logic needs to be expressed, it employs the Xpl template language, a sub-language that is Turing-complete. Within it, you can embed XScript via the <c:script> tag. If lang="groovy" is specified, you can implement the script in Groovy. Similarly, you can integrate virtually any other language.

Existing programming languages already address a large problem space effectively; there is often no need to invent new syntax for expressing procedural computation logic—reusing existing language syntax or even language runtimes will suffice.
XLang focuses on areas not effectively handled by existing languages. By introducing the concepts of Delta and Reversible Computation, XLang can solve many problems that require the computing pattern F(X)+Delta to be handled effectively. In other words, the problem space XLang addresses is largely non-overlapping with that of existing languages. However, this does not mean XLang is a DSL; its syntax and semantics are general-purpose and not tied to any specific business domain. Ultimately, in usage, XLang can cooperate with any third-generation programming language: the XScript part can be replaced with any other third-generation programming language.

If we regard TypeScript as an extension of JavaScript, TypeScript = JavaScript + JSX + TypeSystem, then XLang can also be viewed as an extension of JavaScript, XLang = XScript + Xpl + XDef + MetaProgramming + DeltaProgramming. Xpl is an XML-form template language, similar in purpose to JSX.
The distinctive parts here are DeltaProgramming and MetaProgramming. XLang does not strongly depend on JavaScript syntax; the XScript sub-language can be replaced by any other third-generation programming language.

Some misunderstand XLang’s capabilities because it adopts an XML syntactic form and thus fail to associate it with a conventional programming language. But if you think carefully, TypeScript embeds XML-like JSX syntax inside JavaScript, and JavaScript code blocks can be embedded inside JSX. It is a bona fide programming language. Conversely, embedding JavaScript syntax inside XML format is equivalent to what TypeScript does, isn’t it?

XLang’s outermost entry point is not a simple main function; rather, it is a variety of DSLs with diverse structures and semantics, and even visual models.

4. Can XLang build its own ecosystem?

Certainly. But the content in XLang’s ecosystem is not the usual generic functionality that every new language seems destined to re-implement, such as JSON parsers or HTTP clients. XLang is typically used with a host language (e.g., Java), allowing direct reuse of functionality implemented in the host, at most with a wrapper over standard interfaces. This is similar to how TypeScript directly reuses the underlying JavaScript host ecosystem.
Future directions include cross-language code reuse across multiple syntactic forms, e.g., all based on WASM bytecode, or via GraalVM’s polyglot interop mechanisms.

What should be shared within XLang’s ecosystem are primarily XDef meta-model definitions for various DSLs, as well as code generators and meta-programming structural transformations written in the Xpl template language.

To reiterate, XLang’s primary use is to rapidly develop and extend domain-specific languages, realizing the so-called Language Oriented Programming paradigm. Business development is essentially independent of any specific programming language—akin to physical facts being independent of coordinate systems. A general-purpose language is like a general Euclidean coordinate system; locally, we can adopt more efficient specialized coordinate systems, i.e., DSLs. As technology advances, descriptive programming and imperative programming can be better integrated, and the descriptive subspace occupied by DSLs can grow larger. Multiple DSLs can be seamlessly bonded via G<DSL1> + G<DSL2> +Delta; the concept of Delta must be added to break the limitation that a DSL applies only to a single domain.

5. Are there intuitive examples showing how XLang is used?

You can refer to the following articles:

Detailed syntax can be found in the Nop platform documentation XLang Language

In most cases we do not develop business applications directly with XLang. Instead, we first use XLang to define a DSL, and then develop the actual business using that DSL. XLang defines DSL structure via the XDef meta-model language; the Nop platform’s nop-xdefs module collects all meta-model files of already-defined DSLs.
When developing your own DSL, you generally do not have to start from scratch. You can compose these existing XDef meta-model definitions directly—for example, reuse the variable definition model var-define.xdef via xdef:ref in a rules model.

<rule>
  <input name="!var-name" xdef:ref="schema/var-define.xdef" xdef:name="RuleInputDefineModel"
         computed="!boolean=false" mandatory="!boolean=false" xdef:unique-attr="name"/>
  ...
</rule>

In fact, XLang’s concrete merge algorithm is very simple—essentially akin to the virtual DOM diff algorithms in React and Vue, only simpler. XLang stipulates that elements in a list have unique identifiers such as name or id, thereby ensuring stable XPath that can serve as domain coordinates. During diff and merge computation, items are merged directly by coordinates.

Syntactically, XLang is essentially ordinary XML augmented with a small set of special annotations such as x:schema, x:extends, and x:override. The underlying language engine understands these annotations and performs Delta merge after parsing. x:schema imports the XDef meta-model; via XDef we can define the types of nodes and attributes in XML. If an attribute’s type is specified as xpl, that attribute is parsed using the Xpl template language.

<task x:schema="/nop/schema/xdef.xdef">
  <steps xdef:body-type="list" xdef:key-attr="name">
    <xpl name="!string">
      <source xdef:value="xpl" />
    </xpl>
  </steps>
</task>

The meta-model above defines the structure of task.xml. It states that steps are a set of step definitions, each step has type xpl, and it has a source attribute, which is parsed using the Xpl template language.

An example of a concrete task.xml:

<task x:schema="/nop/schema/task.xdef">
  <steps>
    <xpl name="test">
      <source>
        logInfo("hello world");
      </source>
    </xpl>
  </steps>
</task>

Note that the structure of the task.xdef meta-model and the task.xml model file it describes are essentially identical. task.xdef is like an XML template with annotations indicating the types of the template’s attributes. The concrete task.xml is the result of filling the template’s attributes and child nodes with specific values.

x:schema="/nop/schema/xdef.xdef" on the root of the meta-model indicates that task.xdef is a meta-model definition file whose structure is constrained by xdef.xdef. Meanwhile, x:schema="/nop/schema/task.xdef on the root of task.xml indicates that task.xml is a model file whose structure is constrained by task.xdef.
If you look at the definition of xdef.xdef, you will find its x:schema also points to xdef.xdef. In other words, model structure is defined by the XDef meta-model, and the XDef meta-model itself is defined using the XDef meta-model.

Here is one community member’s understanding:

I finally fully grasped your principle of Delta-based merging today. XLang is a set of standard attribute definitions used to add, delete, or modify node definitions. Delta-based merging is the process of merging a main file with a Delta, and the merge rules are defined by the XLang language specification. After merging, you get a new DSL description (which can be XML, JSON, or any tree structure). You then hand this new DSL to an execution engine; how it parses and handles the DSL is the execution engine’s responsibility.

XLang defines DSLs and automatically implements DSL decomposition, merging, and Delta customization. In principle, once you obtain the merged DSL, it is no longer tied to XLang; the execution engine can use any other technology to parse XML/YAML for subsequent processing. If you use the Nop platform deeply, the execution engine can leverage the XDef meta-model to automatically parse the DSL, and executable code segments can directly reuse the Xpl template language.

6. How does XLang define Delta at the language level? (not a formula)

XLang defines XDSL via the XDef meta-model; every syntactic element in an XDSL has a unique, stable domain coordinate. Business is expressed in XDSL, effectively projecting business into the coordinate system defined by XDSL. A Delta can be defined at any point in this coordinate system. Furthermore, Deltas that arise at many coordinates can be factored out and recognized and managed conceptually as one large Delta—an integrated change pattern that becomes an independent cognitive entity.

XLang can be viewed as a meta-language. It does not directly express Deltas; it first defines a DSL, and then defines language-level Deltas within that DSL. At a more abstract level, all sub-languages in XLang are defined via the XDef meta-model language, and XDef itself is defined via XDef as well. Consequently, all its sub-languages automatically inherit the concept of language-level Deltas.

Many find this difficult to grasp because they do not realize the meta-level nature here. It is not directly about “A solves problem X,” but rather solving it at a higher meta-level through a logical ladder, then projecting it down to the next level where it manifests concretely.

Further explanations on the article "Why XLang is an innovative programming language"

canonical — Sun, 18 Jan 2026 12:30:33 +0000

The XLang language is a key foundational technology underpinning the next-generation open-source low-code Nop platform. Traditional programming languages that support generic metaprogramming correspond structurally to the construction formula Map = Map extends Map<Map>, whereas XLang effectively extends this to Tree = Tree x-extends Tree<Tree>. That is, Map is generalized to Tree, and the extends operation between Map structures is generalized to the x-extends operation on Tree structures—particularly, x-extends adds reverse-deletion semantics.

XLang is innovative because it creates a new program-structure space in which the computing paradigm proposed by Reversible Computation, Y = F(X) + Delta, can be implemented with ease. This conceptual innovation departs from the inertia of traditional computer-science thinking, so some classically trained practitioners may experience additional cognitive friction when trying to understand it.

Previously, I published two articles explaining the design principles of XLang on my WeChat official account: Why is XLang an innovative programming language? and Q&A on "Why XLang is an innovative programming language". A friend commented on Zhihu:

Having patiently read through your two masterpieces, I must say claiming I completely understood them would be dishonest—but understanding just a little is more confusing than not understanding at all: What is XLang actually for? Is it a super registry-style data structure? How do you realize the grand goals you mention (or that I suppose)? Are functions first-class citizens in your language?

Such confusion is common. Fundamentally, it stems from the fact that the theoretical basis of XLang comes from mathematics and physics; therefore, students trained only in computer science tend to map XLang’s concepts to the familiar notions of CS, often causing psychological discomfort. One cannot easily understand what one has not yet understood, and what one has already accepted is often subconsciously regarded as self-evident. Cognitions that deviate from existing understanding tend to be ignored or resisted. In this article, I will provide more targeted explanations. If you have questions, feel free to discuss in the comments.

I. What is XLang for?

XLang’s primary purpose is rapid development and extension of domain-specific languages (DSLs), enabling the so-called Language Oriented Programming paradigm. This paradigm was not invented by me; it has existed in computer science for many years. See, for example, the 1994 paper [PDF] Language-Oriented Programming | Semantic Scholar.

We typically implement business logic using general-purpose programming languages, while Language Oriented Programming emphasizes DSLs (Domain Specific Languages). When developing business features, one first develops a DSL dedicated to that business domain, then uses this DSL to express the logic. JetBrains, the company behind the IntelliJ IDEA IDE, has a related product: MPS (Meta Programming System).

Using XLang to develop a new DSL is extremely simple—so simple that you only need to add an XDef metamodel definition file, and you immediately get a new DSL. The Nop platform provides a general IntelliJ IDEA plugin that automatically reads XDef metamodels to implement syntax hints, link navigation, breakpoints, etc., for custom DSLs, with type inference to follow. The Nop platform’s infrastructure automatically generates model class definitions from XDef metamodel files, implements parsers and validators, and automatically generates visual editors.

DSLs defined with XLang do not need special consideration for extensibility (nor special syntax for it), and they also do not need to worry about how multiple DSLs can be seamlessly integrated for combined use. The Nop platform’s underlying infrastructure implements all of this uniformly. Within DSL files, built-in syntax like x:extends and x:gen-extends automatically enable model decomposition/merging and compile-time metaprogramming.

Extending an existing DSL’s syntax is also very simple: just add an XDef metamodel file that inherits from the existing XDef metamodel file.

All software products developed using XLang-defined DSLs automatically support the so-called Delta customization mechanism. That is, without modifying any existing source code, you can add Delta files under the Delta directory to modify or delete existing logic, and of course also add new logic.

These capabilities provided by XLang are innovative in ways no previous programming language has had. They are crucial for the Nop platform to solve coarse-grained, system-level software reuse. In other words, the most challenging customization problems in the ToB market can be essentially improved under the Nop platform’s technical architecture—especially, the architecture of the base product will not be affected by custom development.

A core banking application developed with XLang can, without any modification to the base product’s source code, be customized across the entire stack—from data model to business logic to front-end display—simply by adding Delta files under the Delta directory.
A low-code platform developed with XLang can, without modifying its own code, customize all visual designers’ UI and editing features via the same Delta customization approach, and even customize the model objects being edited.

II. Is XLang a super registry-style data structure?

Understanding XLang as a registry is like understanding Lisp as a linked list: related, but not the point.

When using existing programming languages to build abstractions, we typically define discrete extension points, which can be managed by a registry-like structure. This idea is deeply entrenched. For example, Huawei’s TinyEngine low-code engine emphasized in its 2.0 design that “the registry mechanism makes it easy to replace components, APIs, etc., enabling flexible plug-and-play and customization.” See Introduction to TinyEngine low-code engine 2.0 new features.

For an existing implementation like ABC, if we want to turn it into an extensible abstraction, the most common approach is variable extraction, e.g., A{X:B}C. Replace B with a variable X, then use a variable-mapping Map (essentially a registry) to assign a concrete value to X. To reduce configuration, we can also specify a default value B and proclaim this as a design principle—convention over configuration. This approach is like digging holes where changes might be needed, and then filling the holes differently depending on requirements.

This can also be explained as adding a layer of indirection: any problem that can’t be solved can be addressed by adding one extra pointer hop; if that still doesn’t solve it, add another layer.

If only a few places might need extension, digging a few holes is easy. But what if we don’t know in advance where changes are needed, and many places might change? If we dig holes everywhere, the original architecture becomes hollow—what meaning does it have left? Digging holes adds cost, affects runtime performance, and increases cognitive complexity. Some pre-dug holes may never be used, and some may even obstruct truly needed extensions. For example, after turning ABC into {X}{Y}C, the actual requirement might be neither replacing X nor Y, but part of Y and part of C. What then?

Each extension point can be viewed as a degree of freedom of the extension space. As extension points increase, the degrees of freedom of the extension space increase. When the degrees of freedom of the extension space grow without bound, can we establish an appropriate abstraction method? Traditional software construction theory answers no. In current theory, we rely on prior prediction to preset extension points, and cannot add or modify extension points post hoc without changing the original system’s code—nor can we remove extension points without code changes.

XLang’s solution to the problem of unlimited extension freedoms is to borrow a concept from physics: coordinate systems. Essentially, it shifts from a rigid-body mechanics worldview to a field-theoretic worldview. In high school we learned Newtonian physics, a branch of classical mechanics rooted in rigid-body mechanics, which is fully mechanistic: a rigid body’s motion is described by a small set of parameters—center-of-mass coordinates, size, shape, orientation. Internal structure is unobservable and irrelevant. Rigid bodies interact via direct contact, and shapes must match precisely to form a seamless whole (compare the software component black-box model). Even in classical mechanics, slightly more advanced perspectives switch to Lagrangian or Hamiltonian formulations, whose spirit is the field-theoretic worldview. A field is a ubiquitous coordinate system with a physical quantity defined at every point. The field has infinite degrees of freedom, yet through the coordinate system it is definable, measurable, and analyzable; we can precisely measure local changes at each coordinate point. In the same spirit, Reversible Computation’s basic setup is first to establish a sufficiently fine and general domain-description coordinate system in which we can point-and-act and act-and-point (coordinate uniqueness).

In Reversible Computation theory, a coordinate system assigns a unique coordinate to every value involved in the system.

value = get(path);
set(path, value);

Formally, implementing a coordinate system looks like a registry. But a coordinate system is an abstract concept with many forms. For example, a file system can be viewed as a coordinate system, where coordinates are file paths; each path corresponds to a file, and each file has a unique path (ignoring links, or considering canonical paths only). Generally, we don’t regard a file system as a registry, let alone a DSL as a registry.

How is the coordinate system implemented in XLang? The answer is simple: each DSL automatically defines a coordinate system. This may sound subtle, but if you’ve studied the moving frame method in differential geometry, it becomes intuitive. Typically we define motion within a selected coordinate system, but the moving frame method uses the motion’s intrinsic properties to automatically define an intrinsic coordinate system attached to the trajectory—meaning motion happens within a coordinate system and simultaneously induces a coordinate system. Similarly, business logic is expressed using a DSL, and the DSL’s abstract syntax tree (AST) and its node attributes automatically form a coordinate system. Concretely, every attribute on the AST has a unique XPath, e.g., /task/steps[@name=a]/@name indicates the name attribute of step a. Because any logic must be expressed by a programming language, there can be no case where the coordinate system doesn’t cover it; all business necessarily occurs in the coordinate space defined by this coordinate system.

Any programming language can be parsed into an AST whose nodes and attributes have unique XPaths. Therefore, any programming language defines an intrinsic coordinate system. The problem is that, at the business level, coordinates in general-purpose languages are unstable. For example, if you add a field at the data-model level, expressing it in a general-purpose language may require editing many places by hand. But if you use a model-driven architecture, a data-model DSL may require modifying only a single place, from which the other changes are inferred automatically. We can say that adding a field induces only a local perturbation in the coordinate system defined by the data model. If you’ve studied Dirac’s delta function, we can formally express it as $ Field*\delta(x-x_0)$.

DSLs defined by XLang differ from general Tree structures by introducing an additional convention: all list elements must have an attribute that can serve as a unique identifier, e.g., name, id, etc. If the business domain lacks such an attribute, XLang provides a built-in x:id. With this rule, each Tree node in the DSL gains a stable coordinate that will not drift due to inserting or deleting nodes. This approach is intuitive and natural. In frontend frameworks like React and Vue, the virtual DOM diff algorithm requires list structures to have a key attribute to ensure diff stability.

DeepSeek’s comment: This constraint aligns with the naming philosophy in computer science—just like DNS decouples IP addresses via domain names, and UUID decouples storage location via unique identifiers, XLang enforces unique identity to separate a tree node’s logical identity from its physical position, enabling a paradigm shift from “fragile positional coupling” to “stable identity abstraction.”

III. How does XLang achieve its ambitious goals?

The overall technical roadmap of Reversible Computation is embodied in the following core formula:

App = Delta x-extends Generator<DSL>

XLang’s unique approach is essentially repeated applications of the formula above—continuously decomposing the problem space horizontally and vertically, projecting it into many DSL subspaces, and then using Delta to glue these subspaces back together. If you’ve studied differential manifolds, the intrinsic logic here becomes easy to grasp. For details, see How does Nop overcome the limitation that DSLs apply only to specific domains?

For example, XLang provides a standardized technical route for reuse based on dynamic similarity.

Traditional reuse leverages stable sameness and struggles to utilize dynamic similarity.

With embedded metaprogramming and code generation, you can establish an inference pipeline between any structures A and C.
Decompose the inference pipeline into multiple steps: A => B => C
Further delta-ize the inference pipeline: A => _B => B => _C => C

Each stage allows buffering and pass-through of extension information not needed in that step.
Specifically, Nop’s built-in model-driven production line can be decomposed into four primary models:

XORM: storage-layer domain model
XMeta: GraphQL interface-layer domain model; can directly generate GraphQL type definitions
XView: business-layer understanding of frontend logic, using a small set of UI elements (forms, tables, buttons), independent of frontend frameworks
XPage: page model targeting a specific frontend framework

When deriving models, we only derive a candidate result (generally stored in model files prefixed with underscores), then choose to extend the candidate model, adding manual fixes and Delta inference relying on additional information (stored in models without underscore prefixes). Every step in the inference chain is optional: you can start from any step directly or discard all information inferred in prior steps entirely. For example, you can create an xview model manually without requiring it to have specific xmeta support; you can even create a page.yaml file directly and write JSON code per the AMIS component spec—the AMIS framework’s capabilities are not constrained by the inference pipeline. Through a deep-decomposition pattern akin to deep learning, we can fully unleash the power of model-driven development, while introducing extra information via Delta when necessary, so the final product’s capabilities aren’t bounded by the expressive power of the models. This frees us from chasing coverage of every detailed requirement during modeling; we focus on the most core, general needs.

XORM = Generator<ExcelModel> + Delta
XMeta = Generator<XORM> + Delta
XView = Generator<XMeta> + Delta
XPage = Generator<XView> + Delta

Mapped to the concepts of traditional computer science, XLang offers a form of multi-stage compilation. Traditionally, the rules of compile-time execution are hard-coded into the compiler, and the compilation process is a one-step black box. XLang, by contrast, opens up the compile-time space via compile-time metaprogramming, allowing domain-specific structural construction rules in a Turing-complete compile-time space, and then complements them with the Delta concept to form multi-stage layered inference.

The Delta concept emphasized by XLang has some counterparts in traditional languages—e.g., GraphQL’s schema definition language supports type deltas via the extend type syntax. But XLang’s fundamental innovation is that it provides a unified, general Delta definition and Delta operations mechanism, avoiding redundant definitions in every DSL subspace. Combined with the XDef metamodel, this ensures intrinsic consistency across all DSL subspaces and enables seamless gluing.

Why can only XLang offer unified Delta definition and operations? Because it implements Delta operations at the structural layer rather than at the object layer! On this point, DeepSeek AI generated a fun analogy:

Structure-level operations: directly modifying the “design blueprint”

Traditional approach: Code is like a built house; to change the window you must break walls (change source code) or hang curtains (AOP proxy).
XLang approach: Modify the architectural blueprint (XNode tree structure) directly, then rebuild from the blueprint. For example:
Original blueprint: Main gate position = (10,20)
Delta blueprint: Main gate position = (15,20)
The system automatically generates a new blueprint without worrying about how the wall is laid.
Technical core: XLang defines Delta at the structure layer (analogous to CAD blueprints), not at the object layer (already built house) where you patch things.

Reversible Computation emphasizes that, before transforming information into business objects, there exists a unified structural expression layer where many common operations can be done directly. There is no need to push processing to the object layer. At the object layer, each object has a different type and thus different handling rules.
Just as the diversity of architectural works rests on unified engineering mechanics, at the structural layer, many things that differ at the business layer are essentially the same, obeying the same structural construction rules and amenable to the same tools and methods.

DeepSeek AI’s comment: Differential manifold theory uses the framework of “local linearization + global smooth gluing” to convert complex geometric objects into computable structures. Abstracted into XLang, this becomes the engineering paradigm of “DSL subspaces + Delta gluing,” allowing software to retain the simplicity of modular development while achieving global consistency via mathematically rigorous Delta operations.

IV. Are functions first-class citizens in XLang?

In program spaces, the most basic units are values and functions, and functional programming even claims that everything is a function; all values and their operations (e.g., +, −, ×, ÷) can be simulated by functions. In modern languages, the importance of functions has continually increased and culminates in treating functions as first-class citizens that can participate in various operations and structural constructions without being forced to belong to a class. However, XLang’s conceptual framework differs significantly from existing languages; it doesn’t care about the traditional dichotomy of values and functions. In XLang, only Delta is truly a first-class citizen: A = 0 + A; a full value is a special case of Delta. Whether functions are first-class is secondary.

If you’ve studied band theory in solid-state physics, this logic is easy to grasp. In solid-state physics, the fundamental building blocks are electrons, ions, and their interactions. Yet the first-class citizen in band theory is neither electrons nor ions, but phonons. Phonons are quantized lattice vibrations—quasiparticles describing collective oscillations of atoms or ions in a crystal. Put simply, a phonon is a collective motion mode that we can treat as an independent individual at the conceptual level, much like a particle. Similarly, Delta is a basic construction unit composed of myriad tiny disturbances whose aggregate is definable and manageable at a macroscopic level. It can be tiny—down to an attribute, a function, or an execution step inside a function; it can be large—across multiple objects as an AOP aspect; it can be even larger—a layered slice across the whole system.

DeepSeek AI’s explanation: A phonon is a quantized energy packet of lattice vibration; it does not directly correspond to any physical particle, but describes the dynamic pattern of atomic collective motion. Just as Delta in XLang is the basic carrier of system evolution, phonons are not static units of matter but the basic language of internal dynamic interactions. When macroscopic properties (e.g., thermal conduction, electrical conductivity) need describing, physicists do not track each atom’s displacement but use phonon excitation and annihilation to characterize state transitions. Building a theory via dynamic deltas rather than static entities mirrors XLang’s design philosophy in computer science.

A function’s granularity is not the smallest composable granularity in XLang. Structures below functions, once given domain coordinates, also belong to XLang’s structural operations space.

Because all sufficiently powerful languages are Turing-complete, their concepts can be transformed into one another. For example, Delta can be understood as a function: A = f(0) = 0 + A; any Delta can be seen as a function executed on the identity element! Generators in Reversible Computation also correspond logically to function mappings in mathematics. In this sense, saying functions are first-class citizens in XLang is fine. However, this understanding is purely mathematical; when reflected in concrete language implementations, subtle differences arise.

First, while functions in programming languages satisfy associativity—combining f and g yields a new function h—composing f and g does not automatically produce a simplified implementation (only the compiler, through optimizations we don’t see, opens function boundaries to simplify the composite). Delta differs: combining Delta1 and Delta2 automatically triggers a merge operation, yielding a simplified Delta3.

Second, a mathematical function may not correspond to a simple function implemented in a programming language at the concrete level. For example, a Generator may correspond to a complex code-generation tool or a sophisticated metaprogramming plugin.

Computer science’s understanding of software-construction structure space remains rudimentary. The construction patterns of the physical world are rich and complex, whereas software structure seems to only have functions, values, and simple composition rules. I believe intelligent software development in the AI era must be built upon a new theory of software construction.

Conclusion

Linus Torvalds, king of hackers, said: talk is cheap, show me the code. XLang is not just a theoretical design; it is a key supporting technology of the open-source low-code Nop platform. Any questions about XLang can be answered by reading the implementation.

gitee: https://gitee.com/canonical-entropy/nop-entropy
gitcode: https://gitcode.com/canonical-entropy/nop-entropy
github: https://github.com/entropy-cloud/nop-entropy

Documentation: https://nop-platform.github.io/projects/nop-entropy/docs-en/dev-guide/xlang/

Thanks to “Blue Book of Domestic Programming Languages 2024” for including XLang.

Appendix

Below are DeepSeek AI-generated explanations of related mathematical and physical concepts.

A. What is the Moving Frame Method?

The Moving Frame Method (also called the moving frame) is a powerful tool in differential geometry for studying the geometric properties of curves, surfaces, and higher-dimensional manifolds. Its core idea is to dynamically construct coordinate systems from the local characteristics of the geometric object itself, thus freeing us from reliance on a fixed global coordinate system. French mathematician Élie Cartan systematized this method in the early 20th century. It is widely used in geometry, physics, and engineering.

1. Core idea

Traditional geometric analysis typically relies on fixed global coordinate systems (e.g., Cartesian), while the moving frame adheres to the geometric object, dynamically adjusting as the object moves or deforms. Such a coordinate system is called a moving frame, with characteristics including:

Intrinsic: the frame is defined directly from the object’s local differential properties (e.g., tangent, normal, curvature).
Dynamic: the frame automatically updates as the object extends or deforms.
Adaptive: the frame’s dimension matches that of the object (e.g., 1D frame for curves, 2D for surfaces).

2. Key steps (taking a space curve as an example)

For a smooth curve in three-dimensional space, the classic process is:

(1) Frame construction

Tangent vector (T): the unit vector along the curve’s tangent, given by normalized parameter derivative: $\mathbf{T}(s) = \frac{d\mathbf{r}}{ds}$ (s is arc-length).
Normal vector (N): the unit vector pointing toward the curve’s bending direction, given by normalized derivative of T: $\mathbf{N}(s) = \frac{d\mathbf{T}/ds}{|d\mathbf{T}/ds|}$.
Binormal (B): a unit vector orthogonal to T and N, defined by the cross product: $\mathbf{B}(s) = \mathbf{T} \times \mathbf{N}$.

These three vectors form the Frenet frame ${ \mathbf{T}, \mathbf{N}, \mathbf{B} }$ at every point along the curve, fully determined by the curve’s own geometry.

(2) Structural equations (Frenet–Serret formulas)

The frame’s differential change is characterized by curvature ($\kappa$) and torsion ($\tau$):

$$
\begin{cases}
\frac{d\mathbf{T}}{ds} = \kappa \mathbf{N} \
\frac{d\mathbf{N}}{ds} = -\kappa \mathbf{T} + \tau \mathbf{B} \
\frac{d\mathbf{B}}{ds} = -\tau \mathbf{N}
\end{cases}
$$

These equations show that the curve’s geometry is completely encoded by local changes of the frame (curvature and torsion), without depending on any external coordinate system.

3. Comparison with fixed coordinate systems

Characteristic	Fixed coordinate system	Moving frame method
Dependency	Depends on external frame	Defined entirely by the object’s intrinsic properties
Adaptivity	Does not change with the object	Dynamically attached; updates with deformation
Information density	Requires global coordinate parametrization	Only needs local invariants (e.g., curvature, torsion)
Application	Simple geometric analysis	Complex manifolds, fiber bundles, gauge theory

4. Extensions and deeper significance

The moving frame applies not only to curves but also to surfaces and high-dimensional manifolds:

Surface frames: use tangent plane basis vectors ($\mathbf{e}_1, \mathbf{e}_2$) and normal vector ($\mathbf{n}$), described via the first and second fundamental forms.
Cartan connection: in fiber-bundle theory, moving frames combine with connections to describe rules for parallel transport of vector fields along a manifold.
Gauge theories: physical gauge field theories (e.g., general relativity, Yang–Mills) extend the moving frame idea to higher-dimensional spaces.

5. Applications

Computer graphics: surface deformation, animation skeleton binding (e.g., skinning).
Robot kinematics: dynamic adjustment of local coordinate systems in manipulator trajectory planning.
General relativity: local descriptions of spacetime curvature (frame-dragging effects).
Materials science: local strain analysis in crystal dislocations and continuum mechanics.

6. Philosophical insight

The essence of the moving frame method is to replace externally imposed coordinate systems with coordinate systems defined by the object’s intrinsic properties. This resonates with “background independence” in modern physics (e.g., general relativity) and with the design philosophy of DSLs in computer science—defining the descriptive framework via the object’s own structure rather than external abstraction. It builds a profound bridge between mathematics and engineering.

B. What is differential manifold theory?

Differential manifold theory studies how “spaces that look flat locally but may be curved globally” can be decomposed, measured, and computed. (For example: the Earth’s surface is a sphere globally, but each city map looks flat.)

Core ideas explained step by step

1. What is a manifold?

Imagine studying a “weird-shaped object,” e.g.:

The surface of a balloon (2-sphere)
The surface of a donut (torus)
A crumpled sheet of paper

A manifold is defined as: such objects look locally like a flat plane (or Euclidean space), but globally may be curved or knotted.

Example:
Standing on Earth, the ground underfoot feels flat (locally planar), but the entire Earth is spherical (globally curved).

2. How to describe a manifold—using an “atlas”

Suppose you want to map the entire Earth. One sheet cannot cover the whole sphere, so you:

Draw multiple local maps: Beijing, Shanghai, New York… Each map covers only a small region.
Mark overlaps: the edges of Beijing and Shanghai maps overlap (e.g., Hebei Province).
Define transformation rules: in the overlap, how Beijing’s “Tianjin” coordinates convert to Shanghai’s coordinates.

This is the core method of manifolds:

Each local map = coordinate chart (describes a small portion of the manifold)
All maps together = atlas (covers the entire manifold)
Conversion rules = transition functions (ensuring seamless stitching between maps)

3. Why “smooth”—the differential structure

Manifolds should be “map-stitchable,” but we also need to do calculus on them (e.g., compute velocity, acceleration). For that we require:

Smooth transition functions: adjacent chart conversions must be smoothly varying—no abrupt jumps or kinks. (e.g., coordinate conversions between Beijing and Shanghai maps in overlapping regions must be continuous and differentiable)

Real-world analogy:
When tiling a mosaic, not only must tile edges align, but color gradients must transition naturally—this is the smoothness requirement.

4. “Direction” and “change” on a manifold—tangent space

On a plane, direction can be represented by arrows (east, north). On a curved manifold, how do we define direction?

Tangent space: at every point on the manifold, define a “virtual flat plane” to represent directions at that point. (e.g., standing at a point on Earth, the tangent space is the “imaginary flat plane” under your feet)

Practical meaning:

Calculate a car’s driving direction on Earth’s surface → use arrows in the tangent space.
Compute a satellite’s trajectory → use the tangent space of a four-dimensional spacetime manifold.

5. Why is manifold theory important?

The physical world is inherently curved:
In Einstein’s general relativity, spacetime is a four-dimensional manifold, and gravity is the manifestation of spacetime curvature.
Complex systems in engineering:
Robot joint motion ranges, social-network connectivity, software modular architectures—all can be abstracted as manifolds.

Differential manifolds vs. software engineering (XLang’s DSL + Delta)

Manifold	Software system	Correspondence
Local maps (charts)	Modular code (DSL subspaces)	Local simplification; hides complexity
Transition functions	Inter-module adaptation (Delta)	Ensures cooperation between modules
Smoothness requirement	Interface compatibility; conflict-free changes	Changes must transition smoothly; avoid system breakage
Tangent-space direction	Local impact analysis of code changes	Predict how one change affects other modules

Real-world analogy: a city traffic system

Manifold = entire city’s road network (Globally complex, but each intersection’s surroundings can be mapped on a plane)
Chart = each neighborhood’s map
Transition function = connection rules at neighborhood boundaries
Smoothness = gentle slopes; vehicles can drive smoothly
Tangent space = direction signs at a particular intersection

Summary

Differential manifold theory teaches us:

Divide and conquer: break complex spaces into many simple locals (as with modular code).
Define rules: specify how locals connect (like inter-module interface agreements).
Maintain smoothness: ensure global changes are coherent (like upgrades that don’t break existing functionality).

This thinking guides the construction of flexible, maintainable complex systems—in both the physical and digital worlds.

C. What is a phonon?

A phonon is a key concept in condensed matter physics—a quasiparticle describing the quantization of lattice vibration energy in a crystal. We can understand it on several levels:

I. Physical essence

Quantization of collective vibration
When atoms/ions in a crystal perform collective oscillations near equilibrium positions (like masses connected by springs), these vibrations are discretized into energy packets under quantum mechanics; each packet is a phonon.
Mathematical description: via canonical coordinate transformations, the 3N-dimensional vibrations of N atoms are simplified to 3N independent harmonic oscillators, and each oscillator’s energy quantum is a phonon.
Quasiparticle properties

Not a real particle—an abstract of collective motion
Carries specific energy and momentum: $E = \hbar\omega$ ($\omega$ is the vibrational frequency)
Obeys Bose–Einstein statistics; can be excited and annihilated

II. Core characteristics

Characteristic	Manifestation
Nonlocality	Describes cooperative vibrations across the lattice; cannot be localized to a single atom
Quantized propagation	Vibrational energy propagates in discrete quantities (phonon number)
Mode diversity	Includes multiple modes, e.g., longitudinal (acoustic branch) and transverse (optical branch)
Interactions	Phonon–phonon scattering affects heat conduction; phonon–electron interactions lead to phenomena such as superconductivity

III. Analogy with XLang’s Delta

graph LR
    A[Crystal system] --> B[Phonon]
    C[Software system] --> D[Delta]

    B --> E[Describes dynamic vibration]
    D --> E
    B --> F[Non-entity primitive]
    D --> F
    B --> G[Explains macro behavior via composition]
    D --> G

Dynamics first Just as physicists describe thermal conduction using phonons rather than individual atomic displacements, XLang uses Delta (Δ) rather than complete states to describe system evolution. For example:

   # Traditional way
   system.temperature = 300K  # directly set the absolute value

   # Delta way
   system += Δ_temperature(+50K)  # record the change process

Principle of compositionality

Phonons: the superposition of different vibrational modes forms actual lattice dynamics

Delta: the combination of multiple incremental modifications constitutes the final system state

 // Phonon composition example
 thermal_conductivity = phonon_mode1 ⊕ phonon_mode2

 // Delta composition example
 final_system = base_system + Δ_security + Δ_logging

IV. Practical application domains

Materials science

Explain heat conduction: phonon mean free path determines thermal conductivity
Predict phase transitions: softening of the phonon spectrum indicates structural instability

Condensed matter theory

Superconductivity mechanism: electron–phonon coupling forms Cooper pairs (BCS theory)
Topological states: theoretical studies of the phonon Hall effect

Engineering

Thermoelectric materials: phonon engineering to reduce lattice thermal conductivity
Quantum computing: phonons as quantum information carriers (e.g., ion-trap systems)

This method of simplifying complex systems into basic excitations (phonon/Delta) reflects a shift in human cognition—from static entities to dynamic relations. Just as phonons revolutionized our understanding of solids, the Delta concept is reshaping the construction philosophy of software engineering.

Q&A on "Why XLang Is an Innovative Programming Language"

canonical — Mon, 12 Jan 2026 15:20:56 +0000

In my previous article Why XLang Is an Innovative Programming Language, I introduced the design philosophy of XLang and explained that XLang is innovative because it creates a new program structure space where it is convenient to implement the computation paradigm proposed by Reversible Computation theory: Y = F(X) + Delta. This article provides further explanations addressing feedback and questions.

1. How can Delta computation be compressed to compile-time execution based on XLang?

To implement property inheritance, UIOTOS made a lot of special designs and introduced a significant amount of code related to property inheritance in its runtime engine. However, based on the XLang language, Delta computation can be completely compressed to compile-time; the runtime engine only needs to understand ordinary component structures and does not need any knowledge of Delta decomposition or merging.

UIOTOS is a no-code platform for the IoT domain. It introduces a container component that can embed an existing page and then use a property mechanism to override properties of objects within the page. This achieves flexible customization of the page content without reimplementing the page.

{
  type: "container",
  baseUrl: "a.page.json",
  overrideProps: {
    "form/title": "sss",
    "actions/0/label": "vvv"
  }
}

The general approach is as shown above: essentially, the page object is brought in via baseUrl, and then multiple inherited properties are used to override content within the page object. With a syntax similar to JsonPath, you can modify any nested content within the page object, so it differs from conventional component frameworks where you call a component and pass parameters to it.

UIOTOS writes considerable code in the frontend runtime framework specifically for property inheritance and needs to introduce a special container control. A limitation of the UIOTOS approach is that it can only override property values in existing pages and cannot change the structure of the inherited page. Another low-code platform uses a similar approach without introducing a special container component; it allows Delta customization for any component. Concretely, it introduces a special overwrite property within the component.

{
  "component": "MyComponent",
  "version" : "1.0",
  "properties": {
     "a": 1, // Set component property directly
   },
   "overwrite": [
    "Here we record the visual editor’s edit actions on the component"
 ]
}

The basic operation pattern is: after dragging a component in the editor, if some details need adjustment, you can enter a component customization mode to fine-tune the component in the visual designer. The adjustment steps are automatically recorded as overwrite and saved in the page file. This approach can arbitrarily adjust component structure and is more adaptable than UIOTOS’s approach. However, recording operation actions is verbose, and multiple actions are hard to compress into a concise final result (i.e., it does not leverage the associative law for simplification).

According to Reversible Computation theory, A = 0 + A; full content is a special case of Delta. We can define full content and Delta in a unified form, so the Delta of a Delta is also just another normal Delta, enabling more complex logical reasoning. Using action-based overwrite to represent a Delta is not suitable.

Regardless of which approach is used above, the editor and frontend runtime framework both need to incorporate handling code related to the Delta concept. However, if XLang is used as the underlying model expression language, Delta computation can be completely compressed to compile-time; the runtime engine only needs to understand ordinary component structures with no knowledge of Delta decomposition or merging. The specific method uses x:extends for component inheritance.

<component x:schema="component.xdef">
  <import from="comp:MyComponent/1.0.0"/>

  <component name="MyComponentEx" x:extends="comp:MyComponent/1.0.0">
    <props>
      <prop name="a" x:override="remove"/>
      <prop name="b"/>
    </props>

    <template x:override="merge">
      Only show the Delta-corrected portion here

      <form x:extends="a.form.xml">
        <actions>
          <action name="ss" x:id="ss"/>
        </actions>
      </form>
    </template>
  </component>

  <template>
    <MyComponent/>
    <MyComponentEx/>
  </template>
</component>

If no customization is needed, you can import the component directly. If customization is needed, enable local component definitions and use x:extends to inherit existing components. XLang defines a Delta merge algorithm between Tree structures. Through the unified DslNodeLoader, the algorithm is automatically executed when loading model files. Pseudocode is as follows:

 function loadDeltaModel(path){
    rootNode = VirtualFileSystem.loadXml(path);
    for each node with x:extends attribute  // Recursively traverse rootNode and its children
        baseNode = loadDeltaNode(node.removeAttr('x:extends'));
        genNodes = processGenExtends(node);

        for each genNode in genNodes
            baseNode = new DeltaMerger().merge(baseNode, genNode);
        node = new DeltaMerger().merge(baseNode,node);

    processPostExtends(node);
    return node;
 }

DslNodeLoader.loadDeltaModel("comp:MyComponent/1.0.0") returns an XNode representing the final merged node, which no longer contains any attributes or child nodes in the x namespace.

Loader can be regarded as a kind of just-in-time compiler; the structural transformation performed while loading model files can be considered part of the compilation process.

Delta operations defined at the structural layer rather than the object layer

Wittgenstein said that the limits of my language mean the limits of my world. Reversible Computation theory further interprets this as: a programming language defines a software structural space, and various reuse mechanisms that produce new structures from existing ones are transformation rules within this structural space.

A truly practical DSL must consider extensibility and needs to embed decomposition, merging, and reuse mechanisms. However, most DSL designers habitually introduce these structural operations at the semantic object layer, which results in ad hoc designs lacking generality and internal consistency.

XLang offers a standardized approach that once and for all solves extensibility for all DSLs. A DSL engine only needs to consider minimal runtime concerns. XLang operates entirely at compile time (model parsing and loading); there is no XLang-specific content at runtime. The key is that XLang performs Delta merging at the structural layer beneath objects—the XNode layer—akin to S-expressions in Lisp, which themselves have no semantics. Detaching from semantics is precisely what gives Delta merging its generality.

For example, Spring’s beans.xml can be regarded as a DSL in the component assembly domain. Spring 1.0 introduced the parent attribute to implement a kind of inheritance, and the import syntax for complex file decomposition and reuse. Spring 2.0 introduced custom elements to simplify configuration of complex structured beans. Spring Boot introduced the @ConditionalOnProperty annotation, allowing bean activation to be controlled via configuration switches. To implement these features, Spring’s core had to include specific handling code.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:myns="http://www.example.com/schema/myns"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.example.com/schema/myns
           http://www.example.com/schema/myns/myns.xsd">

    <import resource="classpath:config/services.beans.xml"/>

    <!-- Parent Bean -->
    <bean id="parentBean" class="com.example.ParentClass">
        <property name="commonProperty" value="commonValue"/>
    </bean>

    <!-- Child Bean inheriting from the parent -->
    <bean id="childBean" parent="parentBean">
        <property name="extProp" value="extValue"/>
    </bean>

     <!-- Configure a Bean using a custom namespace -->
    <myns:customBean id="customBean" customProperty="customValue"/>
</beans>

@Component
@ConditionalOnProperty(name = "mycomponent.enabled", havingValue = "true", matchIfMissing = false)
public class MyComponent {

    public MyComponent() {
        System.out.println("MyComponent is initialized!");
    }

    public void doSomething() {
        System.out.println("MyComponent is doing something!");
    }
}

With XLang, none of these features need to be implemented within the framework itself.

<beans x:extends="config/base.beans.ml">
   <x:gen-extends>
     <c:include src="config/services.beans.xml" />

     <beans>
        <myns:customBean id="customBean" customProperty="customValue"
                      xpl:lib="/example/myns.xlib" />
     </beans>
   </x:gen-extends>

   <bean id="parentBean" class="com.example.ParentClass">
        <property name="commonProperty" value="commonValue"/>
   </bean>

   <bean id="childBean" x:prototype="parentBean">
        <property name="extProp" value="extValue"/>
   </bean>

   <bean id="myComponent" class="com.example.MyComponent"
         feature:on="mycomponent.enabled">
       <property name="propA" ref="xxx" feature:on="mycomponent.xxx.enabled" />
   </bean>
</beans>

First, notice that without any additional extensibility mechanisms, bean definitions in Spring 1.0 already constitute a complete component assembly model. That is, any bean that can be assembled via get/set methods and constructors can be declaratively defined using the beans.xml DSL. Mathematically, we can say Spring 1.0 defines a complete set of assembly operations.
XLang’s approach is to introduce a set of Delta operations atop the existing DSL, but the result of these Delta operations is to reduce DSL + Delta back to the original DSL structure. Interestingly, the custom namespace approach introduced in Spring 2.0 cannot be reduced back to the 1.0 syntax. In other words, beans configured with Spring 2.0 syntax are not guaranteed to be configurable using Spring 1.0 syntax, even though Spring 1.0 provides a complete operation set. Spring 2.0’s custom namespaces, such as <myns:customBean>, trigger a NamespaceHandler in Java whose execution logic can be arbitrarily complex and may implicitly introduce order dependencies (declaration order could affect assembly results), thereby undermining Spring 1.0’s POJO declarative assembly design.
x:extends can inherit existing DSL files, similar in function to Spring 1.0’s import syntax.
x:gen-extends executes the Xpl template language to dynamically generate bean definitions. The Xpl built-in c:include can include external XNode nodes, again replacing Spring 1.0’s import syntax.
The Xpl custom tag capability used within x:gen-extends can emulate Spring 2.0’s custom namespace mechanism. However, Xpl tags perform code generation: no matter how complex the tag function’s logic is, as long as it produces the desired bean configuration definitions, that is sufficient. For example, the <myns:customBean> above might actually generate multiple bean definitions. What matters at runtime is the generated result of the tag function. x:gen-extends itself executes at compile time.

 <myns:customBean id="customBean" customProperty="customValue"
                      xpl:lib="/example/myns.xlib" />

Actually expands into the following two bean definitions:

<bean id="customBean" class="com.example.CustomBean">
    <property name="customProperty" value="customValue" />
    <property name="otherProperty" ref="otherBean" />
</bean>

<bean id="otherBean" class="com.example.OtherBean" />

In XLang, sibling nodes at the same level can specify inheritance via the x:prototype attribute. This replaces the parent attribute’s role in Spring 1.0 syntax. Meanwhile, when nodes are merged in XLang, x:override can precisely control the merging logic: whether to overwrite, merge, or delete, etc. Importantly, XLang’s mechanism applies to any node—e.g., you can also specify x:prototype on a property to inherit another property’s configuration. In contrast, Spring’s parent attribute can only be used for bean definition inheritance.
In XLang, every node can use feature switches like feature:on and feature:off to control conditional loading. When a feature switch does not match, the corresponding node is automatically removed and never enters runtime. This replaces Spring Boot’s conditional beans. Likewise, feature switches can be used on any node; for example, you can control whether to configure a particular <property>. In Spring Boot, conditional switches only control bean creation; there is no declarative mechanism for conditionally configuring a property.

In summary, the Spring framework embeds many mechanisms to enhance extensibility, each specifically written for the component assembly domain and for the Spring framework itself. If you migrate to another runtime engine, these mechanisms all need to be re-implemented. For example, the Quarkus framework also supports bean assembly definitions and has to implement all these extensions on its own. Even after Spring implements them, frameworks like Hibernate cannot leverage these mechanisms for their own extensions.

The key for XLang is that, after parsing XML or JSON into XNodes, it performs Delta operations at the XNode layer, rather than converting XNodes into strongly-typed BeanDefinitions and then doing Delta operations. Therefore, these capabilities can automatically apply to other DSLs, such as MyBatis mapper files, Hibernate hbm files, and more.

Similar extensibility issues exist in many domains. For instance, Facebook’s GraphQL protocol introduced type extension syntax:

type User {
  id: ID!
  name: String!
  email: String!
}

extend type User {
  age: Int
  email: String @deprecated(reason: "Use 'contactEmail' instead")
  contactEmail: String!
}

In the graphql-java implementation, GraphQL definitions are first parsed into TypeDefinition and TypeExtensionDefinition, and type merging is implemented at the object layer.

Within XLang’s technology stack, the NopGraphQL framework defines types using the XMeta metadata model, so it can directly use XLang’s built-in Delta mechanisms at the XNode layer to implement extensions, without designing a separate TypeExtension syntax. At runtime in NopGraphQL, there is no need to understand any type extension concept. For the runtime framework, a type is just a type—there is no “type + type extension”.

Loader as Generator

Within XLang’s technology stack, the Loader abstraction has a special status. Since all content related to Reversible Computation is, in principle, implemented within the Loader abstraction, integrating XLang into third-party frameworks is very simple: directly replace the DSL’s Loader with XLang’s Delta Loader.

A generic model loader can be seen as having the following type definition:

Loader :: Path -> Model

For a general design, we must recognize that coding is not only for current needs; it must also consider future changes and the system’s evolution across space and time. In other words, programming does not target a single, current world but all possible worlds. Formally, we can introduce a Possible operator to describe this:

Loader :: Possible Path -> Possible Model
Possible Path = deltaPath + stdPath

stdPath refers to the standard path corresponding to the model file, while deltaPath refers to the path used for Delta customization of an existing model file. For example, in a base product we have a built-in business workflow main.wf.xml. When customizing for Customer A, we need a different workflow but do not want to modify the base product’s code. In this case, we can add a Delta model file /_delta/a/main.wf.xml, which represents Customer A’s customized main.wf.xml. The Loader will automatically recognize the existence of this file and use it, without any changes to existing business code.

If we only want to fine-tune the original model rather than completely replace it, we can use x:extends inheritance. The execution logic of XLang’s DeltaLoader is described mathematically by:

Loader<Possible Path> = Loader<deltaPath + stdPath>
                      = Loader<deltaPath> x-extends Loader<stdPath>
                      = DeltaModel x-extends Model
                      = Possible Model

It is important to emphasize that the Loader abstraction has very broad application scenarios. Many functionalities related to extensibility can be pushed down to the Loader layer for unified implementation. For example, multi-tenant customization can be handled by a Loader that recognizes tenant parameters. For further details, see Designing Low-Code Platforms Through Tensor Product.

2. How to understand the analogy between Delta superposition and waves in XLang?

In the physical world, there is another way of construction: waves. Waves are continuously existing patterns that construct the world through interference and superposition. XLang’s distinctiveness lies in its support for continuous constructive superposition via Delta operations.

Traditionally, after constructing X, any modification must change X itself. In contrast, with a superpositional approach, you can obtain a new Y without directly changing X by adding an extra Delta.

X = A + B + C
Y = A + B + D
  = X + (-C + D)
  = X + Delta

In traditional software engineering, even if incremental development is achievable, many specialized extension points are often needed, and not all modifications can be done via Delta-style customization. In particular, traditional incremental approaches generally imply adding new features and rarely include a design for reducing existing features. Delta customization allows us to achieve reduction by addition.

Systems developed with XLang require no extra work to automatically support Delta customization. This drastically reduces the development cost of productized software products. For example, after packaging a banking core system into a JAR, there is no need to modify the base product’s code. All user-specific customizations and secondary development can be stored separately as Deltas. By switching Deltas, multiple different customized versions can be realized. The same mechanism can be used for multi-tenant customization.

Delta customization enables precise customization down to individual properties. Traditional software engineering offers only a few pre-defined extension points and finds it difficult to support fine-grained customization everywhere. For example, if you only want to define a single property of a button, you often have to add a new component or page. All business-level concepts of interest can be customized individually—this is a manifestation of continuity.

3. Can XLang be introduced into already developed standard systems?

XLang is an innovative technology. Can it be applied to existing systems? This way, when customization needs arise, one can express the Delta using XLang and then generate a customized version based on the standard system plus the Delta.

First, it must be clear that Deltas need to be expressed within a Delta-ized structural space. Traditional software uses general-purpose languages, and its structural space is defined by such languages. General-purpose languages like Java and C# are very limited in expressing Deltas and cannot achieve fine-grained Delta definitions.

In object-oriented languages, the only Delta mechanism that can be directly leveraged is inheritance. The Nop platform uses a “sandwich” architecture, with code generation following the pattern:

class NopAuthUser extends _NopAuthUser{

    // You can add extra methods here, inheriting code generated from the base class.
}

class _NopAuthUser extends OrmEntity{
}

That is, code-generated classes inherit from system-built base classes to automatically obtain built-in properties and methods, while an outermost class inherits from the generated class to isolate hand-written code from auto-generated code. During code generation, we follow this rule: files with an underscore prefix and all files under the _gen directory are automatically overwritten; other files are only created if they do not exist. Thus, when the model changes, you can regenerate without losing manual changes, enabling model-driven incremental development.

Although more Delta support cannot be obtained directly from object-oriented languages, more Delta mechanisms can be constructed at the architectural level. The most basic approach is to introduce XLang wherever XML/JSON/YAML configuration or model files are used.

In the example above, Chain is a model object that can be defined via a JSON file, and it can be parsed and loaded using the Chain.parseByUrl function. If refactoring with XLang, you can replace Chain.parseByUrl with ResourceComponentManager.loadComponentModel(path) and then move the JSON file to the resources/_vfs directory. In this JSON, you can use XLang’s Delta syntax such as x:extends, x:post-extends, and x:override.

The Nop platform provides a nop-spring-delta module that adds Delta customization support for Spring’s beans.xml and MyBatis’s mapper.xml files. You can place these XML files under resources/_vfs. The specific approach is as follows:

@Service
@ConditionalOnProperty(name = "nop.spring.delta.mybatis.enabled", matchIfMissing = true)
public class NopMybatisSessionFactoryCustomizer implements SqlSessionFactoryBeanCustomizer {
    @Override
    public void customize(SqlSessionFactoryBean factoryBean) {

        List<IResource> resources = ModuleManager.instance().findModuleResources(false, "/mapper", ".mapper.xml");

        if (!resources.isEmpty()) {
            List<Resource> locations = new ArrayList<>(resources.size());
            for (IResource resource : resources) {
                // Ignore auto-generated mapper files; they can only serve as base classes
                if (resource.getName().startsWith("_"))
                    continue;

                XDslExtendResult result = DslNodeLoader.INSTANCE.loadFromResource(resource);
                XNode node = result.getNode();
                node.removeAttr("xmlns:x");

                String xml = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n" +
                        "<!DOCTYPE mapper\n" +
                        "        PUBLIC \"-//mybatis.org//DTD Mapper 3.0//EN\"\n" +
                        "        \"http://mybatis.org/dtd/mybatis-3-mapper.dtd\">\n" + node.xml();
                locations.add(new ByteArrayResource(xml.getBytes(StandardCharsets.UTF_8), resource.getPath()));
            }
            factoryBean.addMapperLocations(locations.toArray(new Resource[0]));
        }
    }
}

ModuleManager.instance().findModuleResources(false, "/mapper", ".mapper.xml") searches for mapper.xml files under each module’s mapper directory. This process automatically considers files under Delta directories. If a file with the same name exists under _vfs/_delta/{deltaId}/, the Delta version will be selected automatically. The Nop platform’s built-in VirtualFileSystem is similar to Docker’s layered filesystem: a file in an upper layer overrides the same-named file in a lower layer. Each Delta directory forms an independent layer, and multiple Delta layers can be specified via nop.core.vfs.delta-layer-ids.
When loading XML files through XLang’s DslNodeLoader, the x:schema attribute on the root node is used to read the corresponding XDef meta-model, and Delta merging is performed according to the meta-model specification.
After merging, you obtain an XNode, which can be converted to an XML DOM node; here we serialize it to XML and feed it into MyBatis’s factory bean. MyBatis itself requires no modifications; we simply add a new way for it to obtain mapper files.

4. Does XLang’s Delta computation and mechanism introduce extra performance overhead while improving extensibility and customization?

Primarily, XLang performs DSL Delta merging and Delta customization at model load time via the unified ResourceComponentManager.loadComponentModel function, implementing model caching and model compilation dependency tracking (automatically invalidating model caches when dependent files change).

During development, technologies like lazy loading, just-in-time compilation, and parallel loading can reduce system initialization time.

For releases, you can use Maven packaging to execute merges at compile time, generating the merged model files under the _delta directory and marking the model root node with x:validated="true". At runtime, the system will prioritize loading the model files under _delta (which are already the final merged results). Since they are marked as validated, the merge process is automatically skipped, so even complex Delta merges will not impact runtime performance.

5. Is XLang essentially a set of annotations that the underlying engine understands and, after parsing, performs Delta merging?

You can think of it as introducing new Delta operation syntax rules on top of general XNode nodes (akin to a general AST), i.e., the x:extends, x:override annotations you mentioned.

If we package these annotations and the parsing engine into a general XML input/output system, can we achieve Delta-ization of everything? Regardless of whether it’s program logic, workflows, forms, or any other content, as long as it can be defined in XML, it can be Delta-merged; after merging, pass it to the execution engine, and how to parse that DSL is up to the engine and unrelated to XLang.
Yes, but this understanding is partial and contains misunderstandings. For example, it ties the concept to XML specifically, whereas XLang is fundamentally agnostic to concrete forms; it is about operations on general Tree structures.
So is XLang a standard set of attributes to describe additions, deletions, or modifications of node definitions, where Delta merging combines a main file and a delta according to XLang’s defined rules, producing a new DSL description (XML, JSON, or any tree structure), and then the execution engine takes over to parse it independently of XLang?
Broadly yes. But you also need to understand the roles of x:gen-extends and x:post-extends, and ultimately recognize the complete computation pattern: App = Delta x-extends Generator<DSL>.

6. Does XLang’s model pose challenges for secondary development and an ISV ecosystem? If debugging bugs without access to others’ Deltas, how can we diagnose where a logic changed the data?

First, all model files are managed under the unified _vfs virtual file directory and all have XDef meta-model definitions. Generally, you only need to inspect the meta-model definition to understand the DSL’s specific syntax structure, and the IntelliJ IDEA plugin provides syntax hints and supports breakpoints, etc.

At system startup, all Delta merge results are output to the dump directory, where you can see the final merged result of each model file and the origin of each property and node. To further trace the merge process, mark the root node with x:dump="true".
For detailed debugging methods, see debug.md

DEV Community: canonical

Why Attractor Guided Engineering Cannot Be Demoted to an AI Agent Skill

1. The Essence of a Skill is a Semantic-Level Hash Map

2. The Information Format Is Not the Key

3. Why Dynamical Systems Care About Preserving Structure

4. The State Space Is Not the Source Code Space

5. Why age-skill Is a Wrong Abstraction

6. The Missing Concepts That AGE Supplies

1. Attractor

2. Trajectory

3. Semantic Authority

4. Proof Relation

5. Freshness / Autonomy

6. Structure-Preserving Document Routing

7. AGE Can Use Skills, But Cannot Become a Skill

8. Judgment Criteria

AGE Application Development Template

Beyond Harness Engineering: Understanding Attractor-Guided Engineering through Nonlinear Dynamical System Control

1. Why This Analogy Is Needed

2. The Structure-Preserving Language of PHS

3. The Feedback-Linearization–Style Software Engineering Fallacy

4. Semantic Commitment as the Energy Storage Function of AGE

5. Energy Redistribution Is About Authority Weight, Not File Count

6. q and p: Stable State Representation and Change Obligation Representation

7. Development Is Converting Legitimate p into Stable q

8. J-flow and R-flow: Routing Is Not Dissipation

9. Park Transformation: From Chat Coordinates to Repo Coordinates

10. Space, Time, and Conservation

11. Immersion and Invariance: From Attractor to Target Manifold

12. Structure-Preserving Observer: Audit Is Not Another Narrative Source

13. Implications for AGE Practice

1. Plans Should Explicitly Write the Reference Set

2. Plans Should Explicitly Write the Commitment Phase State

3. Closure Audit Should Check Semantic Conservation

4. Owner Docs Should Write Stable Commitments

5. Audit Prompts Should Distinguish J-flow and R-flow

14. Conclusion: The Nonlinear Dynamical System Control Image of AGE

Appendix: PHS Mathematical Background

AGE Application Development Template

Attractor Before Harness: A Methodology for Large-Scale AI Development

1. Why Harness Is the First Thing People Think of When Discussing AI Engineering

2. The Backstop That Has Been Removed

3. Dynamical Systems Language: Making Trajectory Problems Explicit

4. What Exactly Is an Attractor

5. The Repository Begins to Bear the System's Truth, Making Harness Infrastructure

6. Three Most Common Ontological Confusions

7. In the nop-chaos-flux Repository, the Attractor Is First and Foremost docs/architecture/

8. What Is Harness

1. Routing Harness

2. Plan Harness

3. Verification Harness

4. Audit Harness

5. Memory Harness

9. Why a New Attractor Is Usually Not Evolved by AI on Its Own

10. Conclusion

From Spec-Driven Development to Attractor-Guided Engineering

Core Hierarchy

Real Development History

Where OpenSpec's Structure Excels

Where OpenSpec Is Limited

Why Spec-Driven Easily Becomes Task-Oriented

What If You Just Need to Look Up an Owner Doc?

Tasks Are Not Plans

Sources of Change Go Beyond Spec Changes

Why Files-In, Files-Out Matters

Code Is the Current Implementation Fact, Not the Only Fact

The Real Difference

What Ordinary Projects Can Directly Adopt

NOP Chaos Flux Architecture Evolution: Rewriting from AMIS to a Modern Low-Code Runtime

Preface: Source of Design Ideas

The Most Fundamental Shift: From Runtime Interpretation to Compile-Time Execution

Table of Contents

1. Phase 1: Core Concept Establishment and Package Structure Setup

1.1 Action Scope and Import Semantics

1.2 Flow Designer Package Creation

1.3 Collaborative Documentation System

2. Phase 2: Flow Designer from Proof of Concept to Production-Grade

2.1 Canvas Bridge Pattern

2.2 Command Adapter

2.3 Schema-Driven Designer

5. Why `age-skill` Is a Wrong Abstraction

7. In the nop-chaos-flux Repository, the Attractor Is First and Foremost `docs/architecture/`