After Richard Brautigan's poem, and with a nod to Dario Amodei's essay on AI's potential.

Abstract​

Autonomous systems are becoming more capable — and less legible.

Machine learning systems can now perceive, classify, predict, and optimize across domains once considered uniquely human. But as capability increases, interpretability often decreases. In safety-critical environments, this creates an asymmetry: systems can act faster than humans can understand why they acted.

This article introduces Trait Machines, a compositional behavioral specification model designed to make autonomous system behavior explicitly readable, auditable, and constrainable — without discarding the benefits of machine learning.

Trait Machines combine:

1. Explicit state-machine semantics
2. Deterministic constraint guards
3. Flat compositional behavioral traits
4. Machine learning operating inside defined safety envelopes

The central property is simple but consequential:

The specification is the system.

The same artifact defines behavior, validates composition, and generates runtime execution logic.

I. The Problem We Quietly Accepted​

Modern autonomy is built on a tradeoff we rarely say out loud:

The more capable a system becomes, the harder it is to explain what it is doing.

For years, this was acceptable. Systems were narrow, contained, and supervised.

But autonomy is moving into physical spaces: Hospitals. Roads. Homes. Factories. Classrooms.

In these environments, performance is not enough. Behavior must be understandable while it is happening — not reconstructed afterward.

Today, when autonomous systems fail, we often:

• Retrain models
• Add data
• Tune thresholds
• Hope the failure does not recur

This is not root-cause reasoning. It is statistical recovery.

Trait Machines are an attempt to shift failure handling back toward deterministic explanation.

II. Design Goals​

Trait Machines were designed around five requirements:

Behavioral Legibility​

Behavior must be inspectable as structured logic.

Composable Semantics​

Systems must be built from independently testable behavioral units.

Deterministic Safety Enforcement​

All actions must pass explicit guards before execution.

Specification–Runtime Equivalence​

Behavioral definitions must generate runtime behavior directly.

Learning Compatibility​

Machine learning must remain usable — but bounded.

III. The Trait Machine Model​

A Trait Machine is a constrained state machine built from five elements:

This is not new theory. State machines are decades old. The difference is how they are used, composed, and exposed.

Traits as Capability Contracts​

Traits define observable behavior units.

They can:

• Add capabilities
• Add restrictions
• Coordinate behavior

Safety is not a separate layer. It is expressed using the same language as capability.

Example: Safety Trait​

# Example 1 — Safety Trait: ObstacleStop

trait ObstacleStop -> Robot

@interaction

initial: patrolling

patrolling -- OBSTACLE_DETECTED --> stopped
when (< @payload.distance 0.5)
do (set motors "off")
   (emit STOPPED { reason: "obstacle too close" })

stopped -- CLEAR --> patrolling
do (set motors "on")

This is intentionally small.

Small systems are readable. Readable systems are debuggable. Debuggable systems are trustworthy.

IV. Composition at the Entity Level​

# Example 2 — Entity With Composed Traits

orbital InspectionUnit

entity InspectionRobot [runtime]

position : string
scanResult : string

trait Movement -> InspectionRobot
trait Rotation -> InspectionRobot
trait Scanning -> InspectionRobot
trait ZoneEnforcement -> InspectionRobot

Composition is flat.

You can inspect a system’s behavioral surface without tracing execution trees or diagrams. That is not just a developer convenience — it is an auditability property.

V. Learning Inside Constraints​

Trait Machines do not replace machine learning. They constrain it.

Execution model:

1. Model proposes action
2. System computes validation signals
3. Trait guards evaluate
4. Valid actions execute

Example: Constraining Learned Navigation​

# Example 3 — Constrained ML Navigation

trait LearnedNavigation -> Robot

@interaction

initial: idle

idle -- NAVIGATE_TO --> navigating
when (and
      (= @payload.isCollisionFree true)
      (= @payload.speedWithinLimit true)
      (= @payload.avoidsRestricted true))
do (set currentPath @payload.proposedPath)

idle -- NAVIGATE_TO --> idle
when (not (and
           (= @payload.isCollisionFree true)
           (= @payload.speedWithinLimit true)
           (= @payload.avoidsRestricted true)))
do (emit PATH_REJECTED)

The model learns. The boundaries remain explicit.

Learning becomes search inside safety, not across it.

VI. Runtime Legibility​

Trait systems produce structured execution traces.

14:03:22 State: patrolling
14:03:22 Event: OBSTACLE_DETECTED { distance: 0.3m, type: "person" }
14:03:22 Guard: (< @entity.distance 0.5) → TRUE
14:03:22 Transition: patrolling --> stopping
14:03:22 Effect: (stop motors)
14:03:22 Effect: (emit STOPPED { reason: "person detected at 0.3m" })

Every decision is reconstructable as logic, not inference.

Example: Healthcare Safety Guard​

# Example 5 — Healthcare Safety Guard

when (and
      (<= @payload.appliedForce @entity.forceTolerance)
      (= @payload.verbalConfirmation true)
      (= @entity.emergencyStopAccessible true))

This is not philosophical AI safety. This is operational safety engineering.

VII. Static Validation​

Compile-time validation can detect:

• Unreachable states
• Unhandled events
• Invalid bindings
• Deadlocks
• Cross-trait communication gaps

This shifts failures from runtime to build time.

VIII. Real-Time Constraints​

Guards must be:

1. Deterministic
2. Bounded cost
3. Independent of global system size

This enables static worst-case timing certification.

Learning Feedback Loop​

Guard rejections become structured training data:

PATH_REJECTED → reason: restricted zone violation

Constraints become part of the learning signal.

IX. Human Readability Scope​

Not "anyone instantly."

But:

• Inspectable by safety reviewers
• Understandable by domain experts
• Auditable by regulators
• Teachable in education

The goal is reducing the distance between specification and intent.

X. Limitations​

Trait Machines do not:

• Solve alignment
• Replace ML
• Remove human specification risk
• Replace robotics stacks

They provide a behavioral specification and constraint layer.

XI. Claimed Contributions​

Specification = Runtime​

One artifact defines behavior and execution.

Constraint–Capability Symmetry​

Safety and ability share representation.

Audience Expansion​

Specification readable outside formal methods specialists.

Canonical Representation​

Readable notation compiles to JSON.

{
  "from": "idle",
  "event": "NAVIGATE_TO",
  "to": "navigating",
  "guard": ["and",
    ["=", "@payload.isCollisionFree", true],
    ["=", "@payload.speedWithinLimit", true],
    ["=", "@payload.avoidsRestricted", true]
  ],
  "effects": [
    ["set", "@entity.currentPath", "@payload.proposedPath"]
  ]
}

Human-readable and machine-optimizable are equivalent views of the same system.

XII. Strategic Implication​

As machines move into physical environments, behavior transparency becomes infrastructure, not documentation.

Explicit behavioral systems enable:

• Deterministic auditing
• Faster incident diagnosis
• Regulatory verification
• Cross-domain comprehension

XIII. Conclusion​

Trait Machines propose a simple shift:

• Learning provides adaptability.
• Traits provide boundaries.
• Specification provides execution.
• Behavior remains readable.

The claim is not that this makes systems perfect.

The claim is narrower, and more practical:

Systems that act in human environments should be understandable by humans while they act.

Not eventually. Not after analysis. While they run.

Vsi gradijo RAG sisteme z vektorskimi DB. Mi smo našemu AI dali strukturiran pomnilniški sistem, ki dejansko razume kontekst.

Problem RAG​

Retrieval-Augmented Generation (RAG) je standardni pristop za dajanje AI agentom spomina:

1. Sprejmi uporabniško poizvedbo: "Kako sem nazadnje obdelal avtentikacijo?"
2. Generiraj embedding vektor
3. Poišči v vektorski bazi podatkov za podobne vektorje
4. Vstavi top-K rezultate v prompt
5. Generiraj odgovor

Problem? Vektorska podobnost ≠ kontekstualna relevantnost.

Kdaj RAG odpove​

Scenarij 1: Časovni kontekst

• Uporabnik: "Na kaj sem delal v torek?"
• Vektorska DB: Najde dokumente o "delu" in "torkovih sestankih"
• Realnost: Uporabnik želi njihovo specifično sejo izpred 5 dni

Scenarij 2: Ujemanje vzorcev

• Uporabnik: "Pokaži mi vse sezname pogledov, ki sem jih zgradil"
• Vektorska DB: Najde dokumente, ki vsebujejo "seznam" in "pogled"
• Realnost: Uporabnik želi entity-table patterne, uporabljene v sejah

Scenarij 3: Kavzalno sklepanje

• Uporabnik: "Zakaj je moja avtentikacija spodletela?"
• Vektorska DB: Najde dokumente o avtentikaciji
• Realnost: Uporabnik potrebuje verigo napaka → popravek → uspeh

Vektorsko iskanje najde podobno besedilo. Ne razume česa dejansko sprašujete.

Alternativa orbitalnega spomina​

Namesto vektorskih embeddingov Almadarjev AI uporablja strukturiran orbitalni spomin:

• Entitete: Uporabniki, seje, projekti, patterni
• Relationships: Seja pripada uporabniku, uporablja patterne
• Časovni sled: Kdaj se je zgodilo, v kakšnem vrstnem redu
• Semantični kontekst: Kakšni so bili cilji, rezultati, nauki

To ni iskanje podobnosti. To je razumevanje strukture.

Prednosti​

1. Časovni pomnilnik: "Kaj sem delal v torek?" → natančen odgovor
2. Pattern razpoznavanje: "Pokaži mi sezname" → vsi entity-table patterni
3. Kavzalne verige: "Zakaj je spodletelo?" → sled napake do rešitve

Vector DB išče besedilo. Orbitalni spomin razume pomen.

Ste že odprli modal in ga niste mogli zapreti? To je prekinjen krog. Mi smo to naredili nemogoče za gradnjo.

Problem zataknjenega uporabnika​

Uporabljate aplikacijo. Kliknete "Odpri nastavitve." Pojavi se modal. Kliknete gumb X. Nič se ne zgodi. Pritisnete Escape. Nič. Kliknete zunaj modala. Še vedno nič.

Zataknili ste se.

To se zgodi, ker:

1. Modal se je odprl preko internega stanja (setIsOpen(true))
2. Gumb za zaprtje sproži setIsOpen(false)
3. Ampak če je napaka, se stanje ne posodobi
4. Ali še huje — gumb za zaprtje ni bil nikoli povezan

V Almadarju je to arhitekturno nemogoče.

Načelo zaprtega kroga​

Vsaka interakcija z UI mora zaključiti poln krog nazaj do state machine.

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│   Uporabniški klik ──► Event Bus ──► State Machine ──► Posodobitev UI │
│       ▲                                              │         │
│       └──────────────────────────────────────────────┘         │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Brez bližnjic. Brez neposrednih mutacij stanja. Vsaka akcija teče skozi krog.

Kako deluje v Almadarju​

1. Uporabnik sproži dogodek​

Ko kliknete gumb:

// ❌ NE to:
onClick={() => setIsModalOpen(false)}

// ✅ To:
onClick={() => eventBus.emit('UI:CLOSE')}

Komponenta ne ve, kaj se zgodi potem. Samo emitira.

2. Event Bus usmeri do State Machine​

Event bus prejme UI:CLOSE in ga usmeri do state machine aktivnega traita.

3. State Machine obdela​

{
  "from": "modalOpen",
  "to": "browsing",
  "event": "CLOSE",
  "effects": [
    ["render-ui", "modal", null],
    ["render-ui", "main", { "type": "page-header", ... }]
  ]
}

State machine:

1. Preide iz modalOpen v browsing
2. Počisti modal slot
3. Renderira glavno vsebino

4. UI se posodobi​

Komponenta se ponovno renderira glede na novo stanje. Modal izgine, ker je tako rekla state machine.

Zakaj to preprečuje zataknjena stanja​

1. Dogodki morajo imeti prehode​

Če definirate gumb z dogodkom:

{
  "type": "page-header",
  "actions": [{ "label": "Odpri", "event": "OPEN_MODAL" }]
}

Validator zahteva ujemajoč prehod:

{
  "from": "browsing",
  "to": "modalOpen",
  "event": "OPEN_MODAL"
  // ✅ Obstaja zahtevan prehod
}

Če pozabite:

✗ Napaka: CIRCUIT_ORPHAN_EVENT
  Akcija 'Odpri' emitira dogodek 'OPEN_MODAL', ki nima handlerja za prehod

2. Overlay sloti morajo imeti izhode​

Če renderirate v modal ali drawer, validator zahteva izhod:

{
  "from": "browsing",
  "to": "modalOpen",
  "event": "OPEN_MODAL",
  "effects": [
    ["render-ui", "modal", { "type": "form-section", ... }]
  ]
}

Mora imeti:

{
  "from": "modalOpen",
  "to": "browsing",
  "event": "CLOSE"
  // ✅ Zahtevan izhodni prehod
}

Če pozabite:

✗ Napaka: CIRCUIT_NO_OVERLAY_EXIT
  Stanje 'modalOpen' renderira v slot 'modal' ampak nima izhodnega prehoda.
  Uporabniki se bodo zataknili v ta overlay.

3. Slot Wrappers obdelujejo Escape Hatches​

Tudi če pozabite gumb za zaprtje, vas slot wrapper reši:

// ModalSlot.tsx (avto-generirani wrapper)
const handleClose = () => {
  eventBus.emit('UI:CLOSE');
  eventBus.emit('UI:CANCEL');
};

return (
  <Modal 
    isOpen={Boolean(children)} 
    onClose={handleClose}  // Escape tipka, klik overlaya, gumb X
  >
    {children}
  </Modal>
);

Wrapper emitira dogodek. State machine ga obdela. Krog se zaključi.

Primerjava iz resničnega sveta: Semaforji​

Semaforji sledijo zaprtemu krogu:

Rdeča ──(timer)──► Zelena ──(timer)──► Rumena ──(timer)──► Rdeča

Ni "skoči iz Rdeče v Zeleno takoj" ali "zataknjen na Rumeni." Krog je zaprt — vsako stanje ima definirane prehode.

Zdaj si predstavljajte pokvarjen semafor:

• Zataknjen na Rdeči → prometni zastoj
• Zataknjen na Zeleni → nesreče
• Naključni prehodi → kaos

Almadarjev validator je kot prometni inženir, ki preveri:

• ✅ Vsaka luč ima prehode
• ✅ Ni nemogočih stanj
• ✅ Emergency načini definirani

Primer: Modal, ki se ne more pokvariti​

Tukaj je implementacija modala, v katerega je nemogoče zatakniti:

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "modalOpen" }
  ],
  "events": [
    { "key": "OPEN_MODAL", "name": "Odpri Modal" },
    { "key": "CLOSE", "name": "Zapri" },
    { "key": "SAVE", "name": "Shrani" }
  ],
  "transitions": [
    {
      "from": "browsing",
      "to": "browsing",
      "event": "INIT",
      "effects": [
        ["render-ui", "main", {
          "type": "page-header",
          "title": "Naloge",
          "actions": [{ "label": "Nova naloga", "event": "OPEN_MODAL" }]
        }]
      ]
    },
    {
      "from": "browsing",
      "to": "modalOpen",
      "event": "OPEN_MODAL",
      "effects": [
        ["render-ui", "modal", {
          "type": "form-section",
          "entity": "Task",
          "fields": ["title", "status"],
          "submitEvent": "SAVE",
          "cancelEvent": "CLOSE"
        }]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "CLOSE",
      "effects": [
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "SAVE",
      "effects": [
        ["persist", "create", "Task", "@payload.data"],
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    }
  ]
}

Trije načini za izhod iz modala:

1. Klik "Prekliči" → sproži CLOSE dogodek
2. Klik "Shrani" → sproži SAVE dogodek
3. Pritisni Escape ali klikni overlay → ModalSlot emitira UI:CLOSE

Vsi trije preidejo nazaj v browsing in počistijo modal.

Hierarhija slotov​

Različni sloti imajo različne zahteve za vračanje:

Zakaj ta arhitektura pomembna​

Za uporabnike​

• ✅ Nikoli se ne zataknejo v modalih
• ✅ Konsistentno vedênje čez aplikacije
• ✅ Predvidljivi UI vzorci

Za razvijalce​

• ✅ Napake ujete ob compile time
• ✅ Brez ročnega povezovanja close handlerjev
• ✅ Spremembe stanja so sledljive

Za ekipe​

• ✅ Schema = dokumentacija
• ✅ Enostavno pregledovanje state flows
• ✅ Hitrejši onboarding

Poskusite: Zgradite nepokvarljiv Modal​

Ustvarite modal-demo.orb:

{
  "name": "ModalDemo",
  "orbitals": [{
    "name": "Demo",
    "entity": { "name": "Item", "fields": [{ "name": "name", "type": "string" }] },
    "traits": [{
      "name": "DemoTrait",
      "linkedEntity": "Item",
      "stateMachine": {
        "states": [
          { "name": "main", "isInitial": true },
          { "name": "modalOpen" }
        ],
        "events": [
          { "key": "INIT", "name": "Inicializiraj" },
          { "key": "OPEN", "name": "Odpri" },
          { "key": "CLOSE", "name": "Zapri" }
        ],
        "transitions": [
          {
            "from": "main",
            "to": "main",
            "event": "INIT",
            "effects": [
              ["render-ui", "main", {
                "type": "page-header",
                "title": "Demo",
                "actions": [{ "label": "Odpri Modal", "event": "OPEN" }]
              }]
            ]
          },
          {
            "from": "main",
            "to": "modalOpen",
            "event": "OPEN",
            "effects": [
              ["render-ui", "modal", { "type": "page-header", "title": "Jaz sem Modal!" }]
            ]
          },
          {
            "from": "modalOpen",
            "to": "main",
            "event": "CLOSE",
            "effects": [
              ["render-ui", "modal", null],
              ["emit", "INIT"]
            ]
          }
        ]
      }
    }],
    "pages": [{ "name": "DemoPage", "path": "/", "traits": [{ "ref": "DemoTrait" }] }]
  }]
}

Prevedite in preizkusite:

orbital validate modal-demo.orb  # Ne bo uspelo brez CLOSE prehoda
orbital compile modal-demo.orb --shell typescript

Poskusite odstraniti CLOSE prehod in ponovno validirati. Compiler vam ne bo dovolil ustvariti prekinjenega kroga.

Spoznanje​

Vzorec zaprtega kroga ni samo dobra ideja — je vsiljen s strani compilerja.

V Almadarju:

• Vsaka UI akcija emitira dogodek
• Vsak dogodek ima prehod
• Vsak overlay ima izhod
• Uporabniki se nikoli ne zataknejo

Ker najboljši način za preprečevanje napak ni testiranje — je narediti, da so nemogoče za zapisati.

Več o state machines v Almadarju.

Almadar compiler izvaja 50+ validacijskih pravil čez 12 modulov, preden generira eno samo vrstico kode. Ujame zataknjene modale, osirotele dogodke, nedosegljiva stanja in prekinjene kroge — napake, ki bi normalno preživele vse do produkcije.

Tukaj je kaj ujame in kako.

Zakaj Validacija > Testiranje​

Testiranje vam pove: "Ta specifični scenarij deluje."

Validacija vam pove: "Noben scenarij ne more pokvariti."

Testi so vzorci. Validacija je dokaz. Almadar compiler ne preverja, ali vaša aplikacija deluje v primerih, ki ste jih testirali. Preverja, ali vaša aplikacija lahko sploh pokvari.

12 Validacijskih Modulov​

Compiler izvaja validatorje v zaporedju, vsak se osredotoča na drugo skrb:

Schema → Entity → Trait → Effect → RenderUI → Slot →
S-Expression → Binding → Service → CrossOrbital → Icon → ClosedCircuit

Prehodimo najzanimivejše.

1. Entity Validator​

Ujame težave modela podatkov, preden postanejo runtime napake.

Podvojena imena polj:

Error: ORB_E_DUPLICATE_FIELD
  Entity 'Task' ima podvojeno ime polja 'status'.
  Vsako ime polja mora biti unikatno znotraj entity.

Neveljavni cilji relacij:

Error: ORB_E_INVALID_RELATION
  Polje 'assigneeId' referencira entity 'User' ampak entity
  z imenom 'User' ne obstaja v tej shemi.
  Razpoložljivi entities: Task, Project, Comment

Rezervirana imena polj:

Error: ORB_E_RESERVED_FIELD
  Ime polja 'id' je rezervirano in samodejno generirano.
  Odstranite to polje iz definicije entity.

2. Trait Validator​

Zagotavlja, da so state machines dobro oblikovane.

Ni začetnega stanja:

Error: ORB_T_NO_INITIAL_STATE
  Trait 'TaskInteraction' nima začetnega stanja.
  Dodajte 'isInitial: true' točno enemu stanju.

Nedosegljiva stanja:

Error: ORB_T_UNREACHABLE_STATE
  Stanje 'Archived' v traitu 'TaskInteraction' nima prihajajočih
  prehodov. Nikoli ga ni mogoče doseči.
  Bodisi dodajte prehod v to stanje ali ga odstranite.

To je subtilno. Definirate stanje, ampak pozabite ustvariti prehod v njega. Brez validatorja stanje obstaja v vaši shemi, ampak vanj ni mogoče vstopiti — mrtva koda v vašem state machineu.

Podvojeni prehodi:

Error: ORB_T_DUPLICATE_TRANSITION
  Trait 'TaskInteraction' ima dva prehoda iz 'Browsing'
  ob dogodku 'EDIT'. State machines morajo biti deterministični.

3. Closed Circuit Validator​

Dragulj krona. Zagotavlja, da vsaka interakcija uporabnika zaključi poln krog.

Zataknjeni overlayi:

Error: CIRCUIT_NO_OVERLAY_EXIT
  Stanje 'EditModal' renderira v 'modal' slot ampak nima izhodnega
  prehoda. Uporabniki se bodo zataknili v ta overlay.

  Fix: Dodajte prehod iz 'EditModal' z dogodkom 'CANCEL' ali 'CLOSE'
  ki vključuje effect: ["render-ui", "modal", null]

To je napaka "modal, ki se ne more zapreti". V tradicionalnih aplikacijah jo najdete, ko jo uporabnik prijavi. V Almadarju jo najdete, preden koda obstaja.

Osiroteli dogodki:

Error: CIRCUIT_ORPHAN_EVENT
  Akcija 'Delete' v stanju 'Viewing' emitira dogodek 'DELETE'
  ki nima handlerja za prehod v trenutnem stanju.

  Gumb se bo renderiral ampak klik nanj ne bo storil ničesar.

Definirali ste gumb z dogodkom, ampak noben prehod ne obravnava tega dogodka v trenutnem stanju. Gumb bi se renderiral, uporabnik bi kliknil nanj, in nič se ne bi zgodilo. Validator to ujame ob compile time.

Manjkajoč main slot:

Error: CIRCUIT_NO_MAIN_RENDER
  Stanje 'Browsing' nima render-ui effecta, ki cilja na 'main' slot.
  Stran bo prazna ob vstopu v to stanje.

Definirali ste stanje, ampak pozabili renderirati karkoli v glavni UI slot. Uporabniki bi videli prazno stran.

4. S-Expression Validator​

Preverja, da so vaši logični izrazi dobro oblikovani.

Neznani operatorji:

Error: ORB_S_UNKNOWN_OPERATOR
  Neznan operator 'equals' v guard izrazu.
  Ali ste mislili '='?
  Razpoložljivi primerjalni operatorji: =, !=, >, >=, <, <=

Napačna arnost:

Error: ORB_S_WRONG_ARITY
  Operator 'and' pričakuje 2+ argumentov, dobil 1.
  Izraz: ["and", ["=", "@entity.status", "active"]]

  'and' z enim argumentom je vedno enak temu argumentu.
  Ali ste mislili dodati še en pogoj?

Neskladnost tipov:

Error: ORB_S_TYPE_MISMATCH
  Operator '>' pričakuje numerične argumente.
  Dobljeno: "@entity.name" (string) > 10 (number)

  Primerjate string s številom. To bo vedno
  ovrednoteno kot false.

5. Binding Validator​

Zagotavlja, da vse reference na podatke kažejo na prava polja.

Neznana korenska vezava:

Error: ORB_B_UNKNOWN_ROOT
  Neznana korenska vezava '@result' v izrazu.
  Veljavni koreni: @entity, @payload, @state, @now, @config, @user

Neznano polje entity:

Error: ORB_B_UNKNOWN_FIELD
  Vezava '@entity.staus' referencira polje 'staus', ki ne
  obstaja na entity 'Task'.
  Ali ste mislili 'status'?
  Razpoložljiva polja: title, description, status, priority

Detekcija tipkarske napake s predlogi. @entity.staus → "Ali ste mislili status?"

6. Cross-Orbital Validator​

Zagotavlja, da je komunikacija dogodkov med orbitali popolna.

Emit brez listenerja:

Error: ORB_X_ORPHAN_EMIT
  Trait 'OrderTrait' emitira 'ORDER_COMPLETED' ampak noben trait
  nima ujemajoče 'listens' deklaracije.

  Vsak emitiran dogodek mora imeti vsaj enega poslušalca.
  Bodisi dodajte poslušalca ali odstranite emisijo.

To preprečuje "fire and forget" dogodke — emisije, ki gredo nikamor. V mikroservisni arhitekturi bi to bilo sporočilo objavljeno na queue brez consumerja. V Almadarju compiler to ujame.

Dvo-prepustna arhitektura​

Nekatere validacije zahtevajo naprej reference. Entity A referencira Entity B, ampak B je definiran po A. Enoprepustni validator bi to zavrnil.

Almadar compiler uporablja dvo-prepustni pristop:

Prehod 1: Zbiranje

• Zberi vsa imena entity, imena trait, imena stanj, imena dogodkov
• Zgradi tabelo simbolov vsega, kar obstaja

Prehod 2: Validacija

• Preveri vse reference proti tabeli simbolov
• Zaženi vseh 12 validacijskih modulov
• Poročaj o napakah s kontekstom in predlogi

To pomeni, da lahko definirate orbitable v katerem koli vrstnem redu. Compiler ugotovi graf odvisnosti.

Kakovost napak: Razlika med "Napaka" in "Pomočjo"​

Primerjajte tipično napako compilerja:

Error: unexpected token at line 47, column 12

Z Almadar validacijsko napako:

Error: CIRCUIT_NO_OVERLAY_EXIT

  Stanje 'EditModal' renderira v 'modal' slot ampak nima izhodnega prehoda.
  Uporabniki se bodo zataknili v ta overlay.

  Lokacija: orbitals[0].traits[0].stateMachine.states[2]
  Shema: task-app.orb

  Fix: Dodajte prehod iz 'EditModal' z dogodkom 'CANCEL' ali 'CLOSE'
  ki vključuje effect: ["render-ui", "modal", null]

  Primer:
    {
      "from": "EditModal",
      "to": "Browsing",
      "event": "CANCEL",
      "effects": [["render-ui", "modal", null]]
    }

Vsaka napaka vključuje:

• Kodo napake — iskalno, dokumentabilno
• Berljiv opis — kaj je narobe
• Vpliv — zakaj je pomembno (uporabniki se bodo zataknili)
• Lokacijo — točno kje v shemi
• Fix — kako to rešiti
• Primer — copy-paste rešitev

Zgrajeno v Rustu: Zakaj je to pomembno​

Compiler je napisan v Rustu. To nam daje:

Izčrpno pattern matching: Ko dodamo nov tip effecta, Rust compiler prisili, da ga obravnavamo v vsakem validatorju. Ne moremo pozabiti primera — ne bo se prevedlo.

Memory safety brez GC: Validator si izposodi shemo brez kopiranja. Za 5.000-vrstično shemo to prihrani pomemben pomnilnik in čas.

Hitrost kompilacije: Polna validacija velike sheme traja <50ms. Feedback dobite hitreje, kot se lahko vaš editor osveži.

Brezstrahna sočasnost: Validacijski moduli lahko tečejo vzporedno brez tekmovanj za podatke. Rustov tipni sistem to zagotavlja ob compile time.

Česa ne validiramo (še)​

Validator ni vseveden. Trenutno ne preverja:

• Semantične pravilnosti guardov — Vé, da je [">=", "@entity.amount", 0] sintaktično veljaven, ampak ne, ali je poslovna logika pravilna
• Performančnih implikacij — State machine s 1.000 stanji je veljaven, ampak potencialno počasen
• UI estetike — Dve tabeli, ki renderirata v isti slot, sta veljavni, ampak verjetno grdi

To so področja za prihodnje izboljšave. Ampak 50+ pravil, ki jih imamo danes, ujame veliko večino napak, ki preživijo v produkcijo v tradicionalnih aplikacijah.

Spoznanje​

Najboljša napaka je tista, ki nikoli ne obstaja.

Almadarjev compiler ne preverja samo sintakse. Preverja vzročnost (zaprte kroge), popolnost (ni osirotelih dogodkov), dosegljivost (ni mrtvih stanj), pravilnost (type-safe izrazi) in konsistenco (ujemanje cross-orbital dogodkov).

50+ pravil. 12 modulov. <50ms.

To ni compiler. To je code reviewer, ki nikoli ne spi, nikoli ne zamudi primera in nikoli ne odobri pokvarjene kode.

Raziščite compiler dokumentacijo za več.

To ni samo mehanika igre. Je vzorec programske arhitekture, ki reši razpravo med mikroservisi in monoliti.

Problem kompozicije​

Programska arhitektura je ujeta med dvema slabima možnostima:

Monolit: Vse v eni kodebazi. Enostavno za gradnjo, nemogoče za skaliranje. Vsaka sprememba tvega pokvariti nekaj nepovezanega.

Mikroservisi: Vse v svojem servisu. Enostavno za skaliranje, nemogoče za koordinacijo. Vsaka funkcija zahteva orkestracijo 5 servisov, 3 message queue in molitev.

Oba pristopa obravnavata vedênje kot lokacijski problem: kje živi koda?

Pravo vprašanje je: kako se vedênje komponira?

Lekcije iz oblikovanja iger​

V Iram, dungeon-crawling action RPG zgrajen na Almadar, igralčev lik definira katera Orbitals opremi:

Vsak Orbital je samostojen state machine. Defend ne ve o Mend. Pathfind ne ve o Fabricate.

Ampak ko ju opremite skupaj, se pojavi emergentno vedênje.

Resonance: Kompozicija ustvarja emergenco​

Ko so združljivi Orbitals opremljeni hkrati, ustvarijo Resonance — sinergijske efekte, ki jih noben Orbital ne definira sam:

{
  "resonance": [
    {
      "requires": ["Defend", "Mend"],
      "effect": "Shield regeneration rate increased by 1.5x",
      "multiplier": { "shieldRegen": 1.5 }
    },
    {
      "requires": ["Disrupt", "Fabricate"],
      "effect": "Traps apply disruption debuffs",
      "multiplier": { "trapDamage": 1.3 }
    },
    {
      "requires": ["Archive", "Command"],
      "effect": "Allies receive enemy weakness intel",
      "multiplier": { "allyDamage": 1.2 }
    }
  ]
}

Ključno spoznanje: noben Orbital se ne spremeni. Defend nima kode za "deluj bolje z Mend." Resonance je lastnost kombinacije, ne posameznikov.

To je točno tako, kot bi morala delovati kompozicija programske opreme.

Vzorec: Orbital Composition​

V Almadarju Orbitals komunicirajo preko dogodkov. Vsak Orbital deklarira kaj emitira in kaj posluša:

{
  "name": "DefendOrbital",
  "traits": [{
    "name": "ShieldTrait",
    "emits": ["SHIELD_ACTIVATED", "SHIELD_DEPLETED"],
    "stateMachine": {
      "states": [
        { "name": "Ready", "isInitial": true },
        { "name": "Active" },
        { "name": "Cooldown" }
      ],
      "transitions": [
        {
          "from": "Ready",
          "to": "Active",
          "event": "ACTIVATE_SHIELD",
          "effects": [
            ["set", "@entity.shieldHp", "@entity.maxShieldHp"],
            ["emit", "SHIELD_ACTIVATED"]
          ]
        },
        {
          "from": "Active",
          "to": "Cooldown",
          "event": "SHIELD_BROKEN",
          "effects": [
            ["set", "@entity.shieldHp", 0],
            ["emit", "SHIELD_DEPLETED"]
          ]
        }
      ]
    }
  }]
}

{
  "name": "MendOrbital",
  "traits": [{
    "name": "HealTrait",
    "listens": [
      { "event": "SHIELD_DEPLETED", "triggers": "EMERGENCY_HEAL" }
    ],
    "stateMachine": {
      "transitions": [
        {
          "from": "Idle",
          "to": "Healing",
          "event": "EMERGENCY_HEAL",
          "effects": [
            ["set", "@entity.hp", ["+", "@entity.hp", ["*", "@entity.maxHp", 0.2]]]
          ]
        }
      ]
    }
  }]
}

Defend emitira SHIELD_DEPLETED. Mend ga posluša. Ko se ščit razbije, se healing sproži samodejno. Noben Orbital ne referencira drugega po imenu. Komunicirata preko event busa.

To je:

• Ohlapno povezano — Defend deluje brez Mend
• Kompozabilno — Dodaj Mend in novo vedênje se pojavi
• Preverljivo — Compiler preveri, da ima vsak emit svoj listen
• Odkrivljivo — Preberi event deklaracije za razumevanje interakcij

Implikacije programske arhitekture​

Ta vzorec se neposredno prenese v poslovno programsko opremo:

E-Commerce: Obdelava naročil​

OrderOrbital         PaymentOrbital         InventoryOrbital
    │                     │                      │
    ├─ emits:             ├─ listens:            ├─ listens:
    │  ORDER_PLACED       │  ORDER_PLACED        │  PAYMENT_CONFIRMED
    │                     │  → PROCESS_PAYMENT   │  → RESERVE_STOCK
    │                     │                      │
    │                     ├─ emits:              ├─ emits:
    │                     │  PAYMENT_CONFIRMED   │  STOCK_RESERVED
    │                     │  PAYMENT_FAILED      │  OUT_OF_STOCK

Trije Orbitali. Vsak samostojen. Kompozicija preko dogodkov. Compiler preveri, da je graf dogodkov popoln — nobeno sporočilo ne ostane neobdelano.

Primerjajte s mikroservisno različico:

• Trije servisi, tri deploymenti, tri baze
• Message queue (Kafka/RabbitMQ) za povezavo
• Dead letter queues za neuspešna sporočila
• Saga patterns za distribuirane transakcije
• Monitoring in alerting za vsak servis

Almadar različica se prevede v en deployment z isto event-driven arhitekturo, ampak brez infrastrukturnega overheada.

Timsko sodelovanje: Vzporeden razvoj​

Ker Orbitals komunicirajo samo preko dogodkov, lahko ekipe delajo vzporedno:

• Ekipa A gradi Order Orbital
• Ekipa B gradi Payment Orbital
• Ekipa C gradi Inventory Orbital

Soglasje o event kontraktih:

{
  "event": "ORDER_PLACED",
  "payload": {
    "orderId": "string",
    "items": "array",
    "total": "number"
  }
}

Nato gradijo neodvisno. Compiler preveri, da se kontrakti ujemajo, ko so Orbitali komponirani.

Standardna knjižnica: Vnaprej zgrajena vedênja​

Almadar vključuje 11 standardnih knjižničnih vedênj, ki se zaskočijo v vsak projekt:

Uvozite jih v kateri koli Orbital:

{
  "uses": [{ "from": "std/Pagination", "as": "Paginate" }],
  "traits": [
    { "ref": "Paginate.traits.PaginationTrait" },
    { "ref": "TaskInteraction" }
  ]
}

Vaš seznam Taskov zdaj ima paginacijo. Ni kode napisane. Samo komponirano.

Zakaj igre to dobro obvladajo​

Igre so vedno razumele kompozicijo. RPG lik je kompozicija:

• Class (Warrior, Mage, Rogue)
• Equipment (Sword, Shield, Staff)
• Skills (Fireball, Heal, Sneak)
• Buffs/Debuffs (Poisoned, Blessed, Hasted)

Vsaka je samostojno vedênje. Skupaj ustvarijo unikatnega lika z emergentnimi sposobnostmi.

Poslovna programska oprema bi morala delovati enako:

• Račun je kompozicija CRUD + Approval + PDF Generation + Email Notification
• Uporabnik je kompozicija Authentication + Profile + Preferences + Activity Log
• Dashboard je kompozicija Charts + Filters + Real-time Updates + Export

Vsako vedênje je Orbital. Kompozicija preko dogodkov. Compiler zagotavlja, da je ožičenje pravilno.

Spoznanje​

Razprava mikroservisi vs monolit postavlja napačno vprašanje. Vprašanje ni, kje vedênje živi. Je, kako se vedênje komponira.

Orbitali vam dajejo:

• Samostojne enote (kot mikroservisi) — vsak Orbital ima svoj state machine
• Enostavno kompozicijo (kot monolit) — uvozi, komponiraj, prevedi
• Preverjeno ožičenje (kot nobeden) — compiler preveri vsako event povezavo
• Emergentno vedênje (kot igre) — resonance efekti iz združljivih kombinacij

Naslednjič, ko oblikujete sistem, ne začnite z "koliko servisov?" Začnite z "katera vedênja potrebujem in kako se komponirajo?"

Več o cross-orbital dogodkih in standardni knjižnici.

Past zastavic boolean​

Tukaj je znan vzorec:

function UserProfile() {
  const [isLoading, setIsLoading] = useState(false);
  const [isError, setIsError] = useState(false);
  const [isEditing, setIsEditing] = useState(false);
  const [isSaving, setIsSaving] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');
  
  const handleSave = async () => {
    setIsSaving(true);
    setIsError(false);
    try {
      await saveUser(user);
      setIsEditing(false);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSaving(false);
    }
  };
  
  // Katere kombinacije so veljavne?
  // isLoading=true, isError=true? 
  // isEditing=true, isSaving=true?
  // Kdo ve!
}

To ustvarja 2^n možnih stanj (32 kombinacij za 5 booleanov). Večina je neveljavnih ali nesmiselnih.

State Machine alternativa​

Kaj če eksplicitno definirate veljavna stanja?

{
  "states": [
    { "name": "idle", "isInitial": true },
    { "name": "loading" },
    { "name": "editing" },
    { "name": "saving" },
    { "name": "error" }
  ],
  "events": ["FETCH", "EDIT", "SAVE", "SUCCESS", "ERROR", "CANCEL"],
  "transitions": [
    { "from": "idle", "to": "loading", "event": "FETCH" },
    { "from": "loading", "to": "idle", "event": "SUCCESS" },
    { "from": "loading", "to": "error", "event": "ERROR" },
    { "from": "idle", "to": "editing", "event": "EDIT" },
    { "from": "editing", "to": "saving", "event": "SAVE" },
    { "from": "saving", "to": "idle", "event": "SUCCESS" },
    { "from": "saving", "to": "error", "event": "ERROR" },
    { "from": "editing", "to": "idle", "event": "CANCEL" },
    { "from": "error", "to": "idle", "event": "CANCEL" }
  ]
}

Zdaj je natančno 5 stanj in 9 veljavnih prehodov. Ni nemogočih kombinacij.

Vizualizacija razlike​

Zastavice boolean: Špageti stanja​

         isLoading=true
        /             \
isError=true?      isEditing=true?
      /                 \
     ?                   ?

Vsaka kombinacija je možna. Napake nastanejo iz neveljavnih stanj, ki jih niste upoštevali.

State Machine: Usmerjen graf​

                    ┌─────────┐
         ┌─────────►│  idle   │◄────────┐
         │          └────┬────┘         │
         │               │              │
    ERROR│          FETCH│         SUCCESS
         │               ▼              │
    ┌────┴───┐      ┌─────────┐        │
    │ error  │      │ loading │        │
    └───┬────┘      └────┬────┘        │
        ▲                │             │
        │           SUCCESS            │
        │                │             │
        │                ▼             │
        │           ┌─────────┐        │
        └───────────┤ editing ├────────┘
                    └────┬────┘
                         │ SAVE
                         ▼
                    ┌─────────┐
         ┌─────────│ saving  │─────────┐
         │         └─────────┘         │
    ERROR│                              │SUCCESS
         │                              │
         └──────────────────────────────┘

Vsaka pot je eksplicitna. Neveljavni prehodi ne obstajajo.

Primer iz resničnega sveta: Pošiljanje forme​

Boolean način​

function ContactForm() {
  const [formData, setFormData] = useState({});
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);
  const [isError, setIsError] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');
  
  const submit = async () => {
    setIsSubmitting(true);
    setIsError(false);
    setIsSuccess(false);
    
    try {
      await api.submit(formData);
      setIsSuccess(true);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSubmitting(false);
    }
  };
  
  // Napaka: Kaj če sta isSuccess in isError oba true?
  // Napaka: Lahko ponovno pošljem med isSubmitting?
  // Napaka: Kaj počisti isSuccess?
}

State Machine način​

{
  "states": [
    { "name": "editing", "isInitial": true },
    { "name": "validating" },
    { "name": "submitting" },
    { "name": "success", "isTerminal": true },
    { "name": "error" }
  ],
  "events": ["SUBMIT", "VALIDATED", "SUCCESS", "FAILURE", "RETRY", "EDIT"],
  "transitions": [
    {
      "from": "editing",
      "to": "validating",
      "event": "SUBMIT",
      "effects": [["validate", "@entity"]]
    },
    {
      "from": "validating",
      "to": "submitting",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", true],
      "effects": [["call-service", "submitForm", "@entity"]]
    },
    {
      "from": "validating",
      "to": "editing",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", false],
      "effects": [["set", "@state.errors", "@validation.errors"]]
    },
    {
      "from": "submitting",
      "to": "success",
      "event": "SUCCESS",
      "effects": [["render-ui", "main", { "type": "success-state" }]]
    },
    {
      "from": "submitting",
      "to": "error",
      "event": "FAILURE",
      "effects": [["set", "@state.error", "@payload.message"]]
    },
    {
      "from": "error",
      "to": "editing",
      "event": "RETRY"
    }
  ]
}

Prednosti:

• ✅ Ni pošiljanja medtem ko že pošiljaš
• ✅ Validacija se zgodi v svojem stanju
• ✅ Napaka in uspeh sta medsebojno izključujoča
• ✅ Jasne poti za ponovni poskus

Zakaj razvijalci izogibajo State Machines​

Mit 1: "Preveč kompleksni so"​

Realnost: Zastavice boolean izgledajo enostavne, dokler jih ni 5+. Potem postane interakcijska matrika nepredstavljiva.

Mit 2: "Samo za igre so"​

Realnost: Igralni razvijalci uporabljajo FSM, ker delujejo. UI je kot igra: uporabniške akcije sprožijo spremembe stanja.

Mit 3: "Težko jih je spreminjati"​

Realnost: Spreminjanje state machine pomeni dodajanje stanja ali prehoda. Spreminjanje zastavic boolean pomeni lovljenje skozi useEffect verige.

Kdaj uporabiti State Machines​

Almadar to olajša​

V Almadarju ne implementirate state machine — ga deklarirate:

{
  "traits": [{
    "name": "TaskManager",
    "linkedEntity": "Task",
    "stateMachine": {
      "states": [
        { "name": "browsing", "isInitial": true },
        { "name": "creating" },
        { "name": "editing" },
        { "name": "deleting" }
      ],
      "events": ["INIT", "CREATE", "EDIT", "DELETE", "SAVE", "CANCEL"],
      "transitions": [
        {
          "from": "browsing",
          "to": "browsing",
          "event": "INIT",
          "effects": [
            ["render-ui", "main", { "type": "entity-table", "entity": "Task" }]
          ]
        },
        {
          "from": "browsing",
          "to": "creating",
          "event": "CREATE",
          "effects": [
            ["render-ui", "modal", { "type": "form-section", ... }]
          ]
        },
        {
          "from": "creating",
          "to": "browsing",
          "event": "SAVE",
          "effects": [
            ["persist", "create", "Task", "@payload.data"],
            ["render-ui", "modal", null],
            ["emit", "INIT"]
          ]
        },
        {
          "from": "creating",
          "to": "browsing",
          "event": "CANCEL",
          "effects": [["render-ui", "modal", null]]
        }
      ]
    }
  }]
}

Compiler generira:

• State machine runtime
• TypeScript tipe
• Event handlerje
• UI vezave

Vi samo definirate logiko.

Primerjava iz resničnega sveta: Semaforji (spet)​

Semaforji so kanonični state machine:

Rdeča → Zelena → Rumena → Rdeča

Predstavljajte si, če bi semaforji uporabljali zastavice boolean:

const [isRed, setIsRed] = useState(true);
const [isGreen, setIsGreen] = useState(false);
const [isYellow, setIsYellow] = useState(false);

// Napaka: Vsi bi lahko bili true!
// Napaka: Vsi bi lahko bili false!
// Napaka: Zelena bi lahko šla neposredno v Rdečo!

Prometni inženirji uporabljajo state machine, ker od življenja je odvisno predvidljivo stanje.

Vaši uporabniki si zaslužijo enako.

Poskusite: Pretvorite boolean zmešnjavo​

Vzemite to komponento polno booleanov:

function Checkout() {
  const [isCartOpen, setIsCartOpen] = useState(false);
  const [isCheckingOut, setIsCheckingOut] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
  const [isComplete, setIsComplete] = useState(false);
  const [hasError, setHasError] = useState(false);
  // ... nočna mora useEffect
}

In pretvorite v Almadar schema:

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "cartOpen" },
    { "name": "checkoutForm" },
    { "name": "processing" },
    { "name": "complete", "isTerminal": true },
    { "name": "error" }
  ],
  "events": ["VIEW_CART", "CHECKOUT", "SUBMIT", "SUCCESS", "FAILURE", "CLOSE", "RETRY"]
  // ... transitions
}

State machine različica ima 6 eksplicitnih stanj namesto 32 možnih boolean kombinacij.

Spoznanje​

Končni avtomati stanja niso akademske vaje — so praktična orodja za upravljanje kompleksnosti.

• 2-3 booleani: Verjetno v redu
• 4+ booleani: Razmislite o state machine
• Asinhrone poteki: Definitivno uporabite state machine
• Večkoraki UI: State machine ali nič

Almadar naredi state machine privzete, ne izjeme. Ker si vaši uporabniki zaslužijo predvidljivo programsko opremo.

Pripravljeni poskusiti? Zgradite svoj prvi state machine.

Avtorizacijska zmešnjava​

Večina aplikacij obravnava dovoljenja tako:

// V komponenti
function ApproveButton({ order }) {
  const { user } = useAuth();
  
  const canApprove = 
    user.roleLevel >= 5 && 
    !order.isFlagged && 
    order.amount > 0;
  
  return (
    <button disabled={!canApprove} onClick={handleApprove}>
      Odobri
    </button>
  );
}

// V API poti
app.post('/api/orders/:id/approve', async (req, res) => {
  const { user } = req;
  const order = await Order.findById(req.params.id);
  
  // Ista logika, podvojena!
  if (user.roleLevel < 5) {
    return res.status(403).json({ error: 'Nezadostna dovoljenja' });
  }
  if (order.isFlagged) {
    return res.status(400).json({ error: 'Naročilo je označeno' });
  }
  if (order.amount <= 0) {
    return res.status(400).json({ error: 'Neveljaven znesek' });
  }
  
  // ... dejanska logika odobritve
});

Problemi:

• ❌ Logika podvojena v frontendu in backendu
• ❌ Težko vzdrževati sinhronizirano
• ❌ Raztresena po datotekah
• ❌ Ni enega vira resnice

Guards: Deklarativna avtorizacija​

V Almadarju so guards del state machine:

{
  "from": "pending",
  "to": "approved",
  "event": "APPROVE",
  "guard": ["and",
    [">=", "@user.roleLevel", 5],
    ["not", "@entity.isFlagged"],
    [">", "@entity.amount", 0]
  ],
  "effects": [
    ["set", "@entity.status", "approved"],
    ["set", "@entity.approvedAt", "@now"],
    ["persist", "update", "Order", "@entity.id", "@entity"]
  ]
}

Guard je deklarativen, serializabilen in vsiljen povsod.

Kako Guards delujejo​

1. Definiraj Guard​

{
  "guard": ["operator", "operand1", "operand2", ...]
}

2. Ovrednoten ob času prehoda​

Ko se prejme dogodek APPROVE:

1. Guard izraz se ovrednoti
2. Če je true: prehod se izvede
3. Če je false: prehod je blokiran, opcijsko sporočilo o napaki

3. Uporabljen povsod​

Isti guard se uporablja za:

• ✅ UI (gumb onemogočen, če guard ne uspe)
• ✅ State machine (prehod blokiran)
• ✅ Generiran API (zahtevek zavrnjen)
• ✅ Audit logi (odločitev o avtorizaciji zabeležena)

Primeri Guardov​

Enostavna primerjava​

{
  "guard": ["=", "@entity.ownerId", "@user.id"]
}
// Samo lastnik lahko izvede to akcijo

Na podlagi vlog​

{
  "guard": [">=", "@user.roleLevel", 5]
}
// Zahtevana stopnja admin (5+)

Večfaktorski​

{
  "guard": ["and",
    ["or",
      [">=", "@user.roleLevel", 5],
      ["=", "@user.department", "finance"]
    ],
    ["not", "@entity.isLocked"],
    ["<", "@entity.amount", 10000]
  ]
}
// (Admin ALI Finance) IN Ni zaklenjeno IN Znesek < 10k

Časovni​

{
  "guard": ["<", 
    ["-", "@now", "@entity.createdAt"], 
    86400000
  ]
}
// Akcija dovoljena samo v 24 urah po ustvarjanju

Članstvo v arrayu​

{
  "guard": ["contains", "@user.permissions", "orders:approve"]
}
// Uporabnik mora imeti izrecno dovoljenje

Kompleksen primer: Approval Workflow​

{
  "traits": [{
    "name": "OrderApproval",
    "linkedEntity": "Order",
    "stateMachine": {
      "states": [
        { "name": "draft", "isInitial": true },
        { "name": "pending_review" },
        { "name": "approved" },
        { "name": "rejected" },
        { "name": "escalated" }
      ],
      "events": ["SUBMIT", "APPROVE", "REJECT", "ESCALATE", "RETURN"],
      "transitions": [
        {
          "from": "draft",
          "to": "pending_review",
          "event": "SUBMIT",
          "guard": ["and",
            [">", "@entity.amount", 0],
            ["not", ["is-empty", "@entity.description"]]
          ]
        },
        {
          "from": "pending_review",
          "to": "approved",
          "event": "APPROVE",
          "guard": ["and",
            [">=", "@user.roleLevel", 5],
            ["not", "@entity.isFlagged"],
            ["or",
              ["<", "@entity.amount", 5000],
              ["and",
                [">=", "@user.roleLevel", 7],
                ["<", "@entity.amount", 50000]
              ]
            ]
          ]
        },
        {
          "from": "pending_review",
          "to": "escalated",
          "event": "ESCALATE",
          "guard": [">=", "@user.roleLevel", 5]
        },
        {
          "from": "pending_review",
          "to": "rejected",
          "event": "REJECT",
          "guard": [">=", "@user.roleLevel", 5]
        },
        {
          "from": "escalated",
          "to": "approved",
          "event": "APPROVE",
          "guard": [">=", "@user.roleLevel", 9]
        }
      ]
    }
  }]
}

To kodira celotno matriko odobritev:

• Vsakdo lahko pošlje (če je veljavno)
• Stopnja 5+ lahko odobri do 5K
• Stopnja 7+ lahko odobri do 50K
• Stopnja 9+ lahko odobri karkoli
• Eskalirana naročila potrebujejo stopnjo 9+

Primerjava iz resničnega sveta: Letališka varnost​

Letališka varnost je state machine z guards:

Check-in ──(ima karto?)──► Bag Drop ──(teža < 23kg?)──► Varnost
                                                    
Varnost ──(brez tekočin?)──► Sken ──(brez orožja?)──► Gate
                                              
Gate ──(boarding pass veljaven?)──► Boarding ──(prosto mesto?)──► Sedež

Vsak prehod ima guard. Če ne uspe:

• Ni karte? → Ni možen check-in
• Pretežka prtljaga? → Plačaj dodatno ali prepakiraj
• Tekočine v torbi? → Vrzi stran

Guardi so eksplicitni, nedvoumni in konsistentno uporabljeni.

Guards v primerjavi s tradicionalno avtorizacijo​

Poskusite: Zgradite sistem dovoljenj​

Ustvarite approval-workflow.orb:

{
  "name": "ApprovalWorkflow",
  "orbitals": [{
    "name": "DocumentApproval",
    "entity": {
      "name": "Document",
      "fields": [
        { "name": "title", "type": "string", "required": true },
        { "name": "content", "type": "string", "required": true },
        { "name": "status", "type": "enum", "values": ["draft", "pending", "approved", "rejected"] },
        { "name": "authorId", "type": "string", "required": true },
        { "name": "isConfidential", "type": "boolean", "default": false }
      ]
    },
    "traits": [{
      "name": "DocumentWorkflow",
      "linkedEntity": "Document",
      "stateMachine": {
        "states": [
          { "name": "draft", "isInitial": true },
          { "name": "pending" },
          { "name": "approved" },
          { "name": "rejected" }
        ],
        "events": ["SUBMIT", "APPROVE", "REJECT", "EDIT"],
        "transitions": [
          {
            "from": "draft",
            "to": "pending",
            "event": "SUBMIT",
            "guard": ["=", "@entity.authorId", "@user.id"]
          },
          {
            "from": "pending",
            "to": "approved",
            "event": "APPROVE",
            "guard": ["and",
              [">=", "@user.roleLevel", 5],
              ["or",
                ["not", "@entity.isConfidential"],
                [">=", "@user.roleLevel", 7]
              ]
            ]
          },
          {
            "from": "pending",
            "to": "rejected",
            "event": "REJECT",
            "guard": [">=", "@user.roleLevel", 5]
          },
          {
            "from": "rejected",
            "to": "draft",
            "event": "EDIT",
            "guard": ["=", "@entity.authorId", "@user.id"]
          }
        ]
      }
    }],
    "pages": [{ "name": "DocumentsPage", "path": "/documents" }]
  }]
}