Skip to main content
A semantic operation is a described change rather than an edited file. You hand cordango apply a list of operations and it rewrites the affected source files.
This is the preferred path for structural change, and the path an agent should use.

​
Scope is required

--scope names the one aggregate the change may touch. An operation naming anything outside the scope is refused, and no file is written. A rejected attempt costs nothing and needs no cleanup, which is what makes it safe to let an agent try.

​
The operations

upsert_entity, upsert_field, remove
Upserts, deliberately. An operation that describes the state a thing should be in can be applied twice without a different result, which matters when the thing applying it is retrying.

​
Ask what an operation may say

The operation vocabulary is a different question from the App Definition’s, and for a while it was the one nobody could ask. An agent worked it out by submitting deliberately invalid operations and reading the rejections. The schemas existed the whole time; nothing exposed them.
An operation and a file spell some things differently. A reference’s target is target in an operation and targetEntity in a file; a trigger is on against trigger. cordango vocabulary lists every pair. See the schema.

​
The file

note is for the human reading the diff later.

​
See it before you do it

Prints which files a change would write or delete, and writes nothing.

​
Then check

cordango apply writes to the working tree. It does not stage, does not commit, and does not validate on your behalf. A person reads the diff and decides.

​
Why not just edit the file

For a one-line change, do edit the file. Operations earn their place in three situations: Scope enforcement. The guarantee that a change cannot touch anything outside one aggregate is worth having when the thing making the change is a model. Refusal is free. A rejected operation set leaves the tree exactly as it was. There is no half-applied state to clean up. They describe intent. upsert_field on ticket is a reviewable statement about what was meant. A YAML diff shows what changed but not why it was one change.