Skip to content
TheChatArchiveThe Chat Archive
Step 3.5 Flash· unknownHugging Face Frontier Reasoning Traces

Build a formal specification-driven API development workflow with TLA+: safety/liveness…

  1. User

    Build a formal specification-driven API development workflow with TLA+: safety/liveness properties, model checking, counterexample minimization, code generation hooks, and regression governance.

  2. Assistant

    We are going to design a workflow for API development using TLA+. The steps are:

    1. Formal Specification: Write TLA+ specifications for the API, including safety and liveness properties.
    2. Model Checking: Use TLC (TLA+ Model Checker) to check the specification for errors.
    3. Counterexample Minimization: When a property is violated, minimize the counterexample to understand the issue.
    4. Code Generation Hooks: Use the specification to generate code (or at least interfaces) for the API.
    5. Regression Governance: Use the specification and model checking as part of the regression testing suite.

    We'll break down each step and then integrate them into a workflow.

    Step 1: Formal Specification

    • We write a TLA+ module that describes the API's behavior. This includes:
      • Variables: state variables that represent the API's state (e.g., request queues, response statuses, etc.)
      • Init: the initial state.
      • Next: the next-state relation, which describes how the API transitions from one state to another (e.g., processing a request, error handling, etc.)
      • Safety properties: things that must never happen (e.g., two concurrent requests modifying the same resource without proper locking, or returning an error when the request is valid).
      • Liveness properties: things that must eventually happen (e.g., every request will eventually get a response, or the system does not deadlock).

    Step 2: Model Checking

    • We use TLC to check the specification against the properties.
    • We may need to define a model (set of possible initial states, and possibly a bound on the number of steps or objects) for TLC to check.

    Step 3: Counterexample Minimization

    • If TLC finds a counterexample, we can use the TLC's minimize feature to find a smaller counterexample that still violates the property.
    • This helps in understanding the root cause of the issue.

    Step 4: Code Generation Hooks

    • We can use the TLA+ specification to generate code in several ways:
      • Use the specification to write an interface (e.g., in Java, C#, etc.) that defines the API endpoints and data structures.
      • Alternatively, we can use the specification to generate a state machine and then implement the state machine in code.
      • There are tools that can generate code from TLA+ (like the TLA+ Toolbox's code generation for PlusCal, but we are writing pure TLA+). We might write a custom code generator that reads the TLA+ module and generates skeleton code.

    Step 5: Regression Governance

    • We integrate the TLA+ model checking into the CI/CD pipeline.
    • Whenever there is a change to the API (specification or implementation), we re-run the model checker.
    • We also keep the counterexamples as test cases (or use the minimized counterexamples to write unit tests) to prevent regressions.

    Now, let's write a simple example for an API that manages a collection of resources (like a key-value store). We'll write a TLA+ specification for a simple RESTful API that supports GET, PUT, and DELETE.

    Example: Key-Value Store API

    We have:

    • A resource represented by a key (string) and a value (string).
    • The API operations:
      • GET /resource/{key} -> returns the value for the key, or 404 if not found.
      • PUT /resource/{key} with body -> sets the value for the key, returns 200 (or 201 if created, but we'll treat create and update the same for simplicity).
      • DELETE /resource/{key} -> deletes the key, returns 200 if deleted, 404 if not found.

    We'll model:

    • The state of the system as a function from keys to values (or a special value for deleted? Actually, we'll use a partial function: domain are the keys that exist).
    • We'll model the requests as events that transition the state.

    We assume that the API is stateless in the sense that each request is independent, but the state of the key-value store changes over time.

    However, note: in a real API, we might have concurrency. We'll model concurrent requests by interleaving.

    We'll define:

    • keys as the set of all possible keys (we'll bound it for model checking).
    • values as the set of all possible values (bound it too).
    • Store as a function from keys to values (partial function). We can represent it as a set of tuples [key |-> value].

    Operations:

    Init: Store = empty function (no keys)

    Next: Disjunction of: Get(key): if key is in the domain of Store, then return the value and state unchanged. Put(key, value): set Store[key] to value (if key was not present, then we add it; if present, we update). State changes by updating the function. Delete(key): if key is in the domain, remove it. State changes by removing the key from the function.

    But note: we want to model the API responses. So we might also have a variable for the last response? Actually, we are modeling the system state and the operations. We can model the request as an event that produces a response (which we can check in the property). However, for safety properties we care about the state of the store and the consistency of the responses.

    Alternatively, we can model the store state and then check that the operations are consistent with the store.

    Let's define:

    VARIABLES store

    TypeInvariant: store \in [key -> value] (but note: partial function, so actually store \in [key -> value] meaning total? We want partial. So we can say store is a function from some subset of keys to values. In TLA+, we can say store \in [key -> value] but that implies total. Instead, we can say store \in [key -> value] but then we have to define the domain. Alternatively, we can represent store as a set of pairs and then define the function from the set.

    Actually, it's easier to represent store as a function [key -> value] and then we allow the function to be defined only on some keys? In TLA+, a function [key -> value] is total. So we need to represent the store as a partial function. We can do:

        store \in [key -> value]   but then we have to handle the case when a key is not in the domain? We can use the domain of the function.
    

    Alternatively, we can represent the store as a set of records: <<key, value>> and then define a function from keys to values only for the keys in the set.

    Let me define:

        Store == { k \in keys : [key |-> k, value |-> v] }   but that's not exactly.
    

    Actually, we can define:

        store \in [key -> value]   and then we say that the domain of store is a subset of keys.
    

    But then when we do a Get on a key not in the domain, we should return 404.

    So we need to model the response. We can have:

        Next == 
          \/ \E k \in keys : 
                Get(k) 
                /\ store' = store   (unchanged)
                /\ response = [type |-> "get", key |-> k, value |-> IF k \in DOMAIN store THEN store[k] ELSE "NOT_FOUND"]
          \/ \E k \in keys, v \in values :
                Put(k, v)
                /\ store' = [store EXCEPT ![k] = v]   (this updates the function at k to v, and if k was not in the domain, it adds it)
                /\ response = [type |-> "put", key |-> k, value |-> v]
          \/ \E k \in keys :
                Delete(k)
                /\ store' = [store EXCEPT ![k] = NULL]   but we want to remove the key. Actually, we can do: store' = [k \in DOMAIN store \ {k} -> store[k]]? That's not easy.
    

    Alternatively, we can represent the store as a function and then when deleting, we remove the key by having a special value? But that's not clean.

    Let's change the representation: store is a set of pairs (k, v). Then:

        store \in SUBSET [key -> value]   but that's not exactly, because we want to allow multiple keys? Actually, a set of pairs is a relation.
    

    We can define:

        store \in SUBSET (keys \times values)
    

    Then: Init: store = {}

        Get(k): 
            IF \E v : [k, v] \in store THEN 
                response = [type |-> "get", key |-> k, value |-> v]
            ELSE
                response = [type |-> "get", key |-> k, value |-> "NOT_FOUND"]
    
        Put(k, v):
            store' = store \cup {[k, v]}   (if the pair was there, it's replaced because set union with the same key and value? Actually, if we have [k, v1] and then we put [k, v2], then the set will have [k, v2] and [k, v1]? No, because a set cannot have two pairs with the same first element? Actually, a set of pairs can have two pairs with the same first element? Yes, because they are pairs. But we want to update, so we want to remove the old pair and add the new one? Or we can define store as a function from keys to values? Then we don't have duplicates.
    

    So better to keep as a function. How to delete?

        We can define store as a function from keys to values, and then we have a special value for "deleted"? But then we have to treat that as non-existent.
    

    Alternatively, we can have two variables: existingKeys (the set of keys that exist) and store as a function from existingKeys to values? That's redundant because the domain of store is exactly existingKeys.

    So:

        VARIABLES store
    
        TypeInvariant == store \in [key -> value]   (but note: this is a total function on keys? We want only some keys to be present? Actually, we can have store defined on all keys, but we can have a special value for "not present". But then we have to check that the special value is not in the range of normal values? That's messy.
    

    Another idea: represent store as a function from keys to [value |-> Boolean], where the value is a pair (v, present). But that's also messy.

    Let me look at standard TLA+ examples: they often use a function and then when they want to delete, they remove the key by having a function that is defined only on the keys that exist. But in TLA+, a function must be defined on every element of its domain. So if we set the domain to be the set of keys that exist, then we can't have a fixed domain.

    So we can do:

        store \in [key -> value]   but then we allow any key to have any value, and we interpret that if the key is in the domain, then it exists. But then the domain is all keys? Then we can't have a key that doesn't exist.
    

    Instead, we can represent the store as a set of (k, v) and then define a function from the set of keys that are in the store to values? That is:

        Store == { [k |-> v] : k \in keys, v \in values }   but that's a set of functions? No.
    

    We can define:

        Store == { <<k, v>> : k \in keys, v \in values }
    
        Then the current store is a set of these pairs.
    
        Then:
          Init: store = {}
    
          Get(k):
            IF \E v : <<k, v>> \in store THEN
                response = [type |-> "get", key |-> k, value |-> v]
            ELSE
                response = [type |-> "get", key |-> k, value |-> "NOT_FOUND"]
    
          Put(k, v):
            store' = store \cup {<<k, v>>}   (but note: if there was an old pair with the same k, then we have two pairs with the same k? That's allowed? Then when we get, we might get two values? So we need to ensure that for each key, there is at most one pair? We can add an invariant:
    
            Invariant == \A k1, k2, v1, v2 : (<<k1, v1>> \in store /\ <<k2, v2>> \in store) => k1 # k2
    
          Then when we put, we must first remove the old pair? Actually, the union will just add the new pair and leave the old one, then the invariant would be violated. So we must remove the old one.
    
          So:
    
            Put(k, v):
              store' = (store \ {<<k, v_old>> : v_old \in values}) \cup {<<k, v>>}
    
          Similarly, Delete(k):
              store' = store \ {<<k, v>> : v \in values}
    

    This works, but then we have to define the set of pairs to remove.

    Alternatively, we can define store as a function from keys to values, but then we have to change the domain when we delete? We can't change the domain of a function. So we have to have a separate set of keys that are present? That's redundant.

    Let me stick with the set of pairs representation.

    We'll define:

        keys == {"k1", "k2", "k3"}   (for model checking, we limit the keys)
        values == {"v1", "v2", "v3"}
    
        VARIABLES store
    
        TypeInvariant == store \in SUBSET (keys \times values)
    
        NoDuplicateKeys == \A k \in keys : \A v1, v2 \in values : (<<k, v1>> \in store /\ <<k, v2>> \in store) => v1 = v2
    
        Init == store = {}
    
        Next == 
          \/ \E k \in keys : 
                Get(k)
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, value |-> IF \E v : <<k, v>> \in store THEN (CHOOSE v : <<k, v>> \in store) ELSE "NOT_FOUND"]
          \/ \E k \in keys, v \in values :
                Put(k, v)
                /\ store' = (store \ {<<k, v_old>> : v_old \in values}) \cup {<<k, v>>}
                /\ response = [type |-> "put", key |-> k, value |-> v]
          \/ \E k \in keys :
                Delete(k)
                /\ store' = store \ {<<k, v>> : v \in values}
                /\ response = [type |-> "delete", key |-> k]
    
        But note: the response for delete doesn't indicate if the key was present? We might want to return 200 only if the key was present, and 404 if not. So we need to check:
    
        For Get and Delete, we want to return 404 if the key is not present.
    
        So for Get:
    
            IF \E v : <<k, v>> \in store THEN
                response = [type |-> "get", key |-> k, value |-> (CHOOSE v : <<k, v>> \in store), status |-> 200]
            ELSE
                response = [type |-> "get", key |-> k, status |-> 404]
    
        Similarly for Delete:
    
            IF \E v : <<k, v>> \in store THEN
                store' = store \ {<<k, v>> : v \in values}
                response = [type |-> "delete", key |-> k, status |-> 200]
            ELSE
                store' = store
                response = [type |-> "delete", key |-> k, status |-> 404]
    
        But note: in the Delete case, we have two branches: one when the key exists and one when it doesn't. We can write:
    
          \/ \E k \in keys : \E v \in values :
                <<k, v>> \in store
                /\ store' = store \ {<<k, v>>}
                /\ response = [type |-> "delete", key |-> k, status |-> 200]
          \/ \E k \in keys : 
                ~\E v \in values : <<k, v>> \in store
                /\ store' = store
                /\ response = [type |-> "delete", key |-> k, status |-> 404]
    

    But note: the two branches for Delete are disjoint because one requires the key to be in the store and the other requires it not to be.

    Similarly for Get:

          \/ \E k \in keys : \E v \in values :
                <<k, v>> \in store
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, value |-> v, status |-> 200]
          \/ \E k \in keys : 
                ~\E v \in values : <<k, v>> \in store
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, status |-> 404]
    

    Now, properties:

    Safety: 1. After a Put, the key must have the new value and no other value for that key. 2. After a Delete, the key must not be in the store. 3. Get must return the current value if the key exists, and 404 if it doesn't.

    But these are actually covered by the definition of the actions? We can write invariants:

        Invariant1 == \A k \in keys : \A v \in values : <<k, v>> \in store => (NoDuplicateKeys is already this? Actually, NoDuplicateKeys says that for a given k, there is at most one v. So it's the same.
    
        Actually, NoDuplicateKeys is an invariant that we must maintain.
    

    Liveness: We might want to say that every request eventually gets a response? But in our model, every step is a request, so it's immediate. So liveness might not be an issue in this simple model.

        However, if we model concurrency (multiple requests at the same time) we might have to consider fairness? But in our model, we are interleaving, so every step is a request and we assume that every request is eventually chosen? We can add a fairness condition:
    
          WF_Next == \A k \in keys : (Enabled(Get(k)) => \E n \in Nat : Next[n](Get(k)))   but that's not standard.
    
        Actually, TLA+ has the concept of weak fairness: an action that is continuously enabled must eventually happen. We can write:
    
          Fairness == \A a \in Actions : WF_enabled(a)
    
        But we haven't defined Actions as the disjunction of all our actions? We can define:
    
          Actions == Get \/ Put \/ Delete
    
        Then:
    
          Spec == Init /\ [][Next]_<<store, response>> /\ Fairness
    
        But note: our Next includes a choice of actions and also updates store and response. We have to define the variables correctly.
    

    However, note that in our Next, we have three types of actions, and each action is parameterized. So we can define:

        Get(k) == ... (as above, but without the \E k \in keys in the outer? Actually, in the Next we already have \E k \in keys.
    

    Alternatively, we can define:

        Next == 
          \/ \E k \in keys : Get(k)
          \/ \E k \in keys, v \in values : Put(k, v)
          \/ \E k \in keys : Delete(k)
    
        and then define the predicates Get, Put, Delete as:
    
        Get(k) == 
          \/ (\E v : <<k, v>> \in store)
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, value |-> (CHOOSE v : <<k, v>> \in store), status |-> 200]
          \/ (~\E v : <<k, v>> \in store)
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, status |-> 404]
    
        But note: the two branches of Get are disjoint? Actually, they are because one requires the existence of v and the other requires non-existence.
    

    However, the CHOOSE in the first branch: we must pick the v that is in the store. Since by NoDuplicateKeys, there is at most one, we can use CHOOSE. But if there are multiple, then we break the invariant? So we assume NoDuplicateKeys holds.

    We can write:

        Get(k) == 
          LET v == CHOOSE v : <<k, v>> \in store
          IN  IF <<k, v>> \in store THEN
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, value |-> v, status |-> 200]
              ELSE
                /\ store' = store
                /\ response = [type |-> "get", key |-> k, status |-> 404]
    
        But note: the CHOOSE v might not be in the store if there is no such v? Actually, if there is no v such that <<k,v>> \in store, then the CHOOSE returns some arbitrary v from values? That's not what we want.
    
        Alternatively, we can write:
    
        Get(k) == 
          IF \E v : <<k, v>> \in store THEN
            LET v == CHOOSE v : <<k, v>> \in store
            IN  /\ store' = store
                /\ response = [type |-> "get", key |-> k, value |-> v, status |-> 200]
          ELSE
            /\ store' = store
            /\ response = [type |-> "get", key |-> k, status |-> 404]
    

    Similarly for Put and Delete.

    Now, the fairness: we want every request to eventually be processed? But in our model, every step is a request. So we don't have a notion of pending requests. So we might not need fairness.

    But if we model the environment that sends requests, then we might have a variable that represents the set of pending requests? That complicates the model.

    For simplicity, we assume that every step is a request and that the model checker will explore all interleavings.

    Now, code generation hooks:

    We can generate: - An interface with methods: Get, Put, Delete. - The data structures: a class for the response (with fields: type, key, value, status) and a class for the store (which is a map from keys to values).

    But note: the TLA+ specification does not have the same data types as the code. We have to map: - keys and values are strings in the code, but in TLA+ we have a set of constants. - The store in the code is a dictionary (map) that supports adding, removing, and getting.

    We can generate:

        public class KeyValueStore {
            private Map<String, String> store = new HashMap<>();
    
            public Response get(String key) {
                if (store.containsKey(key)) {
                    return new Response("get", key, store.get(key), 200);
                } else {
                    return new Response("get", key, null, 404);
                }
            }
    
            public Response put(String key, String value) {
                store.put(key, value);
                return new Response("put", key, value, 200);
            }
    
            public Response delete(String key) {
                if (store.containsKey(key)) {
                    store.remove(key);
                    return new Response("delete", key, null, 200);
                } else {
                    return new Response("delete", key, null, 404);
                }
            }
        }
    
        class Response {
            String type;
            String key;
            String value;
            int status;
            // constructor, getters, setters
        }
    

    But note: the TLA+ model does not specify the internal implementation of the store, only the behavior. So the code generation is straightforward for this example.

    For more complex APIs, we might have multiple resources, relationships, etc.

    Regression governance:

        We add a step in the CI pipeline that runs the TLC model checker on the TLA+ specification and fails if any property is violated.
    
        We also keep the TLA+ specification and the generated code in sync. If the specification changes, we regenerate the code and then update the implementation accordingly.
    

    However, note: the code generation might only generate the interface and the data structures. The business logic must be implemented to match the specification.

    We can also use the TLA+ specification to generate test cases. For example, we can use the counterexamples to write unit tests that check the same scenario.

    But note: the TLA+ model is abstract and might not capture all the details of the implementation (like network failures, etc.). So we might need to extend the specification to include more details.

    This is a simple example. In a real-world scenario, we would have:

        - More complex state (multiple resources, relationships, user sessions, etc.)
        - Non-determinism in the environment (e.g., network delays, failures)
        - Concurrency (multiple clients accessing the API at the same time)
    

    We would then write a more complex TLA+ specification and check for safety (e.g., no two clients get the same lock) and liveness (e.g., every request eventually gets a response if the system is stable).

    Now, let's write the TLA+ module for the example.

    We assume we have a TLA+ Toolbox and we write:

    ----------------------------- MODULE KeyValueStore ----------------------------- EXTENDS Naturals, Sequences

    CONSTANTS keys, values

    (* TypeInvariant *) TypeInvariant == store \in SUBSET (keys \times values)

    NoDuplicateKeys == \A k \in keys : \A v1, v2 \in values : (<<k, v1>> \in store /\ <<k, v2>> \in store) => v1 = v2

    (* Initial state *) Init == store = {}

    (* Actions *) Get(k) == IF \E v : <<k, v>> \in store THEN LET v == CHOOSE v : <<k, v>> \in store IN /\ store' = store /\ response = [type |-> "get", key |-> k, value |-> v, status |-> 200] ELSE /\ store' = store /\ response = [type |-> "get", key |-> k, status |-> 404]

    Put(k, v) == /\ store' = (store \ {<<k, v_old>> : v_old \in values}) \cup {<<k, v>>} /\ response = [type |-> "put", key |-> k, value |-> v, status |-> 200]

    Delete(k) == IF \E v : <<k, v>> \in store THEN /\ store' = store \ {<<k, v>> : v \in values} /\ response = [type |-> "delete", key |-> k, status |-> 200] ELSE /\ store' = store /\ response = [type |-> "delete", key |-> k, status |-> 404]

    Next == / \E k \in keys : Get(k) / \E k \in keys, v \in values : Put(k, v) / \E k \in keys : Delete(k)

    (* Fairness: every action that is enabled must eventually happen? But note: every action is always enabled? Because for any k, we can always do Get, Put, Delete? Actually, for Get and Delete, they are always enabled? For Put, we can always put any key with any value? So yes, every action is always enabled. So we don't need fairness to guarantee progress? But we might want to say that every request is eventually processed? But in our model, every step is a request, so it's processed immediately. So we don't need fairness.

    But if we model the environment that chooses which request to make, then we might have a separate variable for the next request? Then we would have:

        VARIABLES store, request
    
        Next == 
            \/ \E k \in keys : request = [type |-> "get", key |-> k] /\ Get(k) /\ request' = [type |-> "none"]
            \/ \E k \in keys, v \in values : request = [type |-> "put", key |-> k, value |-> v] /\ Put(k, v) /\ request' = [type |-> "none"]
            \/ \E k \in keys : request = [type |-> "delete", key |-> k] /\ Delete(k) /\ request' = [type |-> "none"]
            \/ request = [type |-> "none"] /\ ... (maybe the environment sets a new request)
    
        Then we would have fairness on the environment setting a request and on the processing of the request.
    

    But for simplicity, we assume that the request is the action itself and we don't have a separate request variable.

    So we don't need fairness in this model.

    Properties:

    Safety:

        GetReturnsCorrectValue == 
            [](Get(k) => 
                (IF \E v : <<k, v>> \in store THEN 
                    response.value = (CHOOSE v : <<k, v>> \in store) 
                 ELSE 
                    response.status = 404))
    
        But note: in the Get action, we already set the response correctly. So if we trust the definition, then it's always true? But we want to check that the implementation of Get (in code) matches the specification? Actually, the specification is the definition. So we don't need to check this as a separate property? We can check the invariant that after a Get, the store is unchanged and the response is as expected.
    
        However, we can check:
    
        Invariant1 == 
            (response.type = "get") => 
                (IF \E v : <<k, v>> \in store THEN 
                    response.value # NULL /\ response.status = 200 
                 ELSE 
                    response.value = NULL /\ response.status = 404)
    
        But note: in TLA+, we don't have NULL. We can use a special value? Or we can leave value undefined when status is 404? But in our response record, we have value even for 404? We set it to NULL? In TLA+, we can set it to some constant "NULL" or leave it out? Actually, in the response record for 404 we don't set the value? But in the Get action for 404, we set response = [type |-> "get", key |-> k, status |-> 404] and we don't set the value? Then the value field is undefined? That's not allowed in TLA+? Actually, we are building a record with only the fields we set.
    
        We can define the response record as:
    
            [type : "get", key : k, status : 404]   -> then the field value is not present.
    
        But then in the invariant, we have to check:
    
            IF response.type = "get" THEN
                IF response.status = 200 THEN
                    /\ \E v : <<response.key, response.value>> \in store
                ELSE
                    /\ ~\E v : <<response.key, _>> \in store
    
        But note: in the 200 case, we have response.value defined and we assert that the pair (key, value) is in the store.
    
        Alternatively, we can define a function that maps the response to the expected store state? That's complicated.
    

    Actually, the safety properties we care about are:

        - After a Put, the store must have the new pair and no other pair for that key.
        - After a Delete, the store must not have the key.
    
        And the Get must return the current value if the key exists, and 404 if not.
    
        But these are exactly the definitions of the actions? So if we model the system with these actions, then by definition the actions are correct? Unless we have other actions that modify the store? We don't.
    
        So the only safety property we need is that the store invariants hold:
    
          1. NoDuplicateKeys
          2. The store is a subset of keys \times values.
    
        And then we can check that every action preserves these invariants.
    
        So we can define:
    
          Invariants == TypeInvariant /\ NoDuplicateKeys
    
        Then we check:
    
          InvariantCheck == Init /\ [][Next]_<<store>> => []Invariants
    
        But note: the Next also changes the response, but we are only interested in the store.
    
        Actually, we are only changing the store in the actions? Yes, the response is a separate variable? We haven't declared response as a variable? We are using it in the Next but we haven't declared it in the VARIABLES line.
    
        We should declare:
    
          VARIABLES store, response
    
        Then the state is (store, response). Then the invariant should be only about store? Yes.
    
        So:
    
          Spec == Init /\ [][Next]_<<store, response>>
    
        Then we check:
    
          THEOREM Spec => []Invariants
    
        But we can let TLC check it.
    

    Liveness:

        We might want to say that if a client sends a request (i.e., we are in a state where the next action is a request) then eventually the request is processed? But in our model, every step is a request, so it's processed immediately.
    
        So liveness is trivial.
    

    But if we model the environment that sets the request variable, then we would have:

        VARIABLES store, request
    
        Next == 
            \/ \E k \in keys : request = [type |-> "get", key |-> k] /\ Get(k) /\ request' = [type |-> "none"]
            \/ \E k \in keys, v \in values : request = [type |-> "put", key |-> k, value |-> v] /\ Put(k, v) /\ request' = [type |-> "none"]
            \/ \E k \in keys : request = [type |-> "delete", key |-> k] /\ Delete(k) /\ request' = [type |-> "none"]
            \/ request = [type |-> "none"] /\ ... (environment sets a new request)
    
        Then we want to say that if the request is not "none", then eventually it is processed? But note: the environment might set a new request before the old one is processed? We are modeling sequential processing? Actually, we are interleaving, but only one request at a time.
    
        We can define:
    
          Liveness == \A k \in keys, v \in values : 
                        (request = [type |-> "put", key |-> k, value |-> v]) => <> (store' = (store \ {<<k, v_old>> : v_old \in values}) \cup {<<k, v>>})
    
        But that's not exactly: we want that if a put request is made, then eventually the store is updated? But note: the request variable might change before the put is processed? We are modeling that the request is processed in the same step that the request is set? Actually, in our Next, we have:
    
            request = [type |-> "put", ...] /\ Put(k, v) /\ request' = [type |-> "none"]
    
        So in the same step, the request is processed and then cleared. So if we have a step where request is a put, then in that step the store is updated. So we don't need to worry about liveness.
    
        But what if the environment sets a new request in the same step? We don't have that. We have two separate actions: one for setting the request (environment) and one for processing? We haven't defined the environment setting.
    
        Let me change the model to have two kinds of steps:
    
          - Environment step: sets request to a new request (or keeps it none)
          - Processing step: if request is not none, then process it and set request to none.
    
        Then:
    
          Next == 
              \/ request \in Requests /\ request' \in Requests   (environment changes the request, but we don't change the store)
              \/ request # "none" /\ Process(request)   (process the current request and set request to none)
    
        Then we want to say that every request that is set (and remains set until processed) is eventually processed? But the environment might change the request before it is processed? Then we lose the request? That's not what we want.
    
        Alternatively, we can have a queue of requests? Then we model the queue.
    
        Given the complexity, and since the original requirement is for an API (which is typically stateless and each request is independent), we can stick with the simple model where every step is a request and it is processed immediately.
    

    So for our example, we don't need liveness properties.

    Counterexample minimization:

        If TLC finds a counterexample to an invariant, we can use the TLC's minimize feature to find a smaller trace that still violates the invariant.
    

    Code generation:

        We can write a script (in Python, Java, etc.) that parses the TLA+ module and extracts:
            - The constants: keys and values (but note: these are constants that we set when we run TLC, so we have to get them from the model? Actually, for code generation, we might not need the exact sets, but we can use the types.
    
            - The store: we see that it's a set of pairs (k, v). In code, we use a Map.
    
            - The actions: Get, Put, Delete.
    
        We can generate the code as above.
    

    Regression governance:

        We add a step in the CI pipeline that runs:
    
          tlc KeyValueStore.tla -config KeyValueStore.cfg
    
        The config file defines the constants (keys and values) and the properties to check.
    
        We also generate the code from the TLA+ specification and then compare it with the existing code? Or we just generate the code and then the developers implement the code to match? We can have a test that checks that the implementation matches the specification by running the same scenarios? But that's more like testing.
    
        Alternatively, we can use the TLA+ specification as the ground truth and then write the code to match it. Then we run the model checker on the specification and also run the integration tests on the code.
    
        We can also generate test cases from the counterexamples to add to the test suite.
    

    This is a high-level workflow. For a real project, we would have more complex specifications and we would need to handle:

        - Multiple resources and relationships.
        - Authentication and authorization.
        - Error handling (network failures, timeouts, etc.)
        - Performance constraints? (TLA+ is not for performance, but we can model time? We can use real-time TLA+ but that's more complex.)
    

    We might also use PlusCal, which is a pseudocode-like language that compiles to TLA+, to write the algorithm in a more familiar syntax.

    But the workflow remains the same.

    Let's write the TLA+ module for the example and then show how to run TLC and generate code.

    We'll write the module in a file named KeyValueStore.tla:

    ----------------------------- MODULE KeyValueStore ----------------------------- EXTENDS Naturals, Sequences

    CONSTANTS keys, values

    * We assume keys and values are finite sets.

    VARIABLES store, response

    TypeInvariant == store \in SUBSET (keys \times values)

    NoDuplicateKeys == \A k \in keys : \A v1, v2 \in values : (<<k, v1>> \in store /\ <<k, v2>> \in store) => v1 = v2

    Init == /\ store = {} /\ response = [type |-> "none"]

    Get(k) == IF \E v : <<k, v>> \in store THEN LET v == CHOOSE v : <<k, v>> \in store IN /\ store' = store /\ response' = [type |-> "get", key |-> k, value |-> v, status |-> 200] ELSE /\ store' = store /\ response' = [type |-> "get", key |-> k, status |-> 404]

    Put(k, v) == /\ store' = (store \ {<<k, v_old>> : v_old \in values}) \cup {<<k, v>>} /\ response' = [type |-> "put", key |-> k, value |-> v, status |-> 200]

    Delete(k) == IF \E v : <<k, v>> \in store THEN /\ store' = store \ {<<k, v>> : v \in values} /\ response' = [type |-> "delete", key |-> k, status |-> 200] ELSE /\ store' = store /\ response' = [type |-> "delete", key |-> k, status |-> 404]

    Next == / \E k \in keys : Get(k) / \E k \in keys, v \in values : Put(k, v) / \E k \in keys : Delete(k)

    Spec == Init /\ [][Next]_<<store, response>>

    Invariants == TypeInvariant /\ NoDuplicateKeys

    * We can also define a safety property that after a Get, the response is consistent with the store.

    GetConsistency == [](response.type = "get" => IF response.status = 200 THEN <<response.key, response.value>> \in store ELSE ~\E v : <<response.key, v>> \in store)

    Similarly for Put and Delete:

    PutConsistency == [](response.type = "put" => <<response.key, response.value>> \in store')

    DeleteConsistency == [](response.type = "delete" => IF response.status = 200 THEN ~\E v : <<response.key, v>> \in store' ELSE <<response.key, _>> \in store * but note: in the 404 case, the store is unchanged, so the key must be present? Actually, in the 404 case, the key is not in the store. So we want:

                ~\E v : <<response.key, v>> \in store   (and store' = store)
    
            )
    

    But note: in the Delete action, when status=200, we remove the key, so the key is not in store'. When status=404, we don't change the store, so the key is not in store (and store' = store). So we can write:

        DeleteConsistency == 
            [](response.type = "delete" => 
                IF response.status = 200 THEN
                    ~\E v : <<response.key, v>> \in store'
                ELSE
                    ~\E v : <<response.key, v>> \in store   \* and store' = store, so it's the same as store.
    
            )
    

    But note: in the 404 case, we have store' = store and we require that the key is not in store (and hence not in store').

    Actually, in the 404 case, we have:

        Delete(k) with the condition that the key is not in store, then store' = store and response.status=404.
    
        So we require that in the state before the step (store) the key is not present. But after the step, store' = store, so the key is still not present.
    
        So we can write:
    
        DeleteConsistency == 
            [](response.type = "delete" => 
                (response.status = 200 => ~\E v : <<response.key, v>> \in store')
                /\ (response.status = 404 => ~\E v : <<response.key, v>> \in store)   \* but note: store' = store, so we can also write ~\E v : <<response.key, v>> \in store'
    
            )
    
        However, in the 404 case, we have store' = store, so the condition on store is the same as on store'.
    
        But to be precise, we can write:
    
        DeleteConsistency == 
            [](response.type = "delete" => 
                IF response.status = 200 THEN
                    ~\E v : <<response.key, v>> \in store'
                ELSE
                    ~\E v : <<response.key, v>> \in store
            )
    
        But note: in the 200 case, we have store' = store \ without the key, so the key is not in store'. In the 404 case, we have store' = store and the key is not in store.
    
        Alternatively, we can write:
    
        DeleteConsistency == 
            [](response.type = "delete" => 
                ~\E v : <<response.key, v>> \in (IF response.status = 200 THEN store' ELSE store)
            )
    
        But that's not standard TLA+.
    
        We can break it into two:
    
        DeleteConsistency200 == 
            [](response.type = "delete" /\ response.status = 200 => ~\E v : <<response.key, v>> \in store')
    
        DeleteConsistency404 == 
            [](response.type = "delete" /\ response.status = 404 => ~\E v : <<response.key, v>> \in store)
    
        Then DeleteConsistency == DeleteConsistency200 /\ DeleteConsistency404
    

    Similarly for Get and Put.

    However, note that these properties are actually implied by the definition of the actions? Not exactly: the actions define the response and the store change, but we are checking that the response and the store are consistent. Since the actions define both, they are consistent by definition. But if we have other actions that change the store? We don't.

    So these properties are redundant? They are, but we can check them to be sure.

    Alternatively, we can check that every action satisfies its own consistency:

        \* For every step, if the action is Get, then the response is consistent with the store at the beginning of the step? Or with the store after? In Get, the store doesn't change, so it's the same.
    
        We can define:
    
          ActionConsistency == 
              \/ Get(k) => (IF response.status = 200 THEN <<response.key, response.value>> \in store ELSE ~\E v : <<response.key, v>> \in store)
              \/ Put(k, v) => <<response.key, response.value>> \in store'
              \/ Delete(k) => (IF response.status = 200 THEN ~\E v : <<response.key, v>> \in store' ELSE ~\E v : <<response.key, v>> \in store)
    
        Then we check []ActionConsistency.
    

    But again, this is redundant because it's built into the action definitions.

    So we might only need the invariants about the store (TypeInvariant and NoDuplicateKeys) and then the consistency of the response is automatic.

    However, if we extend the model with more actions (like an admin action that deletes all keys) then we have to update the consistency properties.

    For the workflow, we'll check:

        - Invariants: TypeInvariant and NoDuplicateKeys.
        - Liveness: none.
    

    Now, for model checking, we need to define the model (the constants keys and values). We create a config file:

    * File: KeyValueStore.cfg CONSTANTS keys = {"k1", "k2"}, values = {"v1", "v2"}

    Then we run:

        tlc KeyValueStore.tla -config KeyValueStore.cfg
    

    If there is a counterexample, we can minimize it.

    Code generation:

        We can write a Python script that reads the TLA+ module and extracts:
    
          - The constant names: keys and values.
          - The variable: store (which is a set of pairs).
          - The actions: Get, Put, Delete and their parameters.
    
        Then generate:
    
          public class KeyValueStore {
              private Set<Pair<String, String>> store = new HashSet<>();
    
              public Response get(String key) { ... }
              public Response put(String key, String value) { ... }
              public Response delete(String key) { ... }
          }
    
        But note: in Java, we might want to use a Map instead of a Set of pairs for efficiency.
    
        Alternatively, we can generate a Map:
    
          private Map<String, String> store = new HashMap<>();
    
        Then the operations are:
    
          get: if (store.containsKey(key)) return new Response("get", key, store.get(key), 200); else return new Response("get", key, null, 404);
          put: store.put(key, value); return new Response("put", key, value, 200);
          delete: if (store.remove(key) != null) return new Response("delete", key, null, 200); else return new Response("delete", key, null, 404);
    
        This matches the specification.
    

    Regression governance:

        We add a step in the build pipeline that:
    
          1. Runs the TLC model checker on the TLA+ specification.
          2. If it passes, then we generate the code (or at least the interface) and compare it with the existing code? Or we just generate the code and then the developers have to update the implementation to match the specification? We can have a test that checks that the implementation matches the specification by running the same scenarios? That's more like model-based testing.
    
        Alternatively, we can use the TLA+ specification as the ground truth and then write the code to match it. Then we run the model checker on the specification and also run the integration tests on the code.
    
        We can also generate test cases from the counterexamples (if any) and add them to the test suite.
    

    This is a basic workflow. For a real API, we would have a more complex specification and we might need to model:

        - Multiple resources (e.g., users, posts, comments) and their relationships.
        - Authentication and authorization (e.g., only the owner can delete a post).
        - Pagination, filtering, etc.
    

    We would then write a larger TLA+ module and check properties like:

        - Safety: a user can only delete their own post.
        - Liveness: a post that is created will eventually be visible to the owner.
    

    And then we generate the code for the API endpoints and the data models.

    We also need to handle errors (like malformed requests, network failures, etc.) and we might model those as separate actions.

    But the workflow remains the same.

    Let me summarize the steps:

    1. Write the TLA+ specification for the API, including:

      • State variables (store, current user, etc.)
      • Init and Next
      • Safety invariants (TypeInvariant, NoDuplicateKeys, AuthorizationInvariant, etc.)
      • Liveness properties (if any)
    2. Create a TLC configuration file with the constants (sets of keys, values, users, etc.) and the properties to check.

    3. Run TLC. If it finds a counterexample, minimize it and fix the specification or the implementation.

    4. Write a code generator that reads the TLA+ module and generates:

      • Data structures (classes for resources, requests, responses)
      • API endpoints (methods that correspond to the actions in the specification)
    5. Integrate the model checking and code generation into the CI/CD pipeline.

    6. When the specification changes, regenerate the code and update the implementation accordingly.

    7. Use the counterexamples to write regression tests.

    This ensures that the API implementation is consistent with the formal specification and that any change that breaks the specification is caught early.

    Note: The code generation might not be 100% automatic, especially for complex business logic. But even if we only generate the data structures and the method signatures, it's helpful.

    Alternatively, we can use the specification to write the implementation in a language that is executable (like PlusCal or TLA+ itself) and then extract the code? But that's more advanced.

    Given the constraints, we have outlined a workflow that uses TLA+ for formal specification and model checking, and then uses the specification to guide the code implementation and regression testing.

    We hope this helps. I'll design a comprehensive TLA+-driven API development workflow that bridges formal specification with practical implementation. This creates a "specification-by-construction" approach where TLA+ serves as the single source of truth.

    Workflow Architecture

    ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
    │   Domain        │    │   Formal         │    │   Implementation│
    │   Analysis      │───▶│   Specification  │───▶│   Generation    │
    │   & Modeling    │    │   (TLA+)         │    │   & Testing     │
    └─────────────────┘    └──────────────────┘    └─────────────────┘
             │                       │                       │
             ▼                       ▼                       ▼
    ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
    │   Business      │    │   Model Checking │    │   Regression    │
    │   Rules         │    │   & Verification │    │   Governance    │
    └─────────────────┘    └──────────────────┘    └─────────────────┘
    

    1. Formal Specification Layer (TLA+)

    1.1 Core Specification Structure

    --------------------------- MODULE APISpec ---------------------------
    EXTENDS Naturals, Sequences, FiniteSets, JSON
    
    (* API Domain Constants *)
    CONSTANTS 
        Method, \* GET, POST, PUT, DELETE
        Status, \* 200, 201, 400, 401, 403, 404, 409, 500
        ResourceType, \* User, Order, Product, etc.
        AuthScheme \* Bearer, Basic, OAuth2
    
    (* State Variables *)
    VARIABLES 
        accounts,        \* Auth context: [user -> session]
        resources,       \* Current resource states
        requestQueue,    \* Pending requests
        rateLimitState,  \* Token bucket state
        auditLog
    
    (* 1. Safety Properties - What MUST never happen *)
    Safety == 
        /\ NoDuplicateResourceIDs
        /\ NoPrivilegeEscalation
        /\ NoInvalidStateTransition
        /\ NoStaleReads
        /\ RateLimitingEnforced
    
    (* 2. Liveness Properties - What MUST eventually happen *)
    Liveness == 
        /\ RequestsEventuallyProcessed
        /\ ResourcesEventuallyConsistent
        /\ AuthTokensEventuallyExpire
        /\ NoPermanentStarvation
    
    (* 3. API Contract Specifications *)
    API spec:
        \* POST /users creates user with unique ID
        CreateUser(resource) == 
            /\ resource.type = "User"
            /\ resource.id \notin DOMAIN resources
            /\ resources' = resources \cup {resource.id -> resource}
            /\ response.status = 201
    
        \* GET /users/:id returns consistent snapshot
        GetUser(id) == 
            /\ id \in DOMAIN resources
            /\ response.body = resources[id]
            /\ response.status = 200
            /\ \A r \in resources : r = resources[id]  \* Strong consistency
    
    (* 4. System-wide Spec *)
    Spec == 
        /\ Init
        /\ [][Next]_vars
        /\ Safety /\ Liveness
    =========================================================================
    

    1.2 Key Property Examples

    (* Safety: No two resources with same ID *)
    NoDuplicateResourceIDs == 
        \A r1, r2 \in DOMAIN resources: 
            r1 # r2 => resources[r1].id # resources[r2].id
    
    (* Safety: Authorization check *)
    NoPrivilegeEscalation == 
        [](request.method \in {PUT, DELETE} => 
            \A req \in requestQueue:
                HasPermission(req.user, req.resource, req.method))
    
    (* Liveness: Every valid request succeeds *)
    RequestsEventuallyProcessed == 
        \A req \in requestQueue:
            (req.valid => <> (req \notin requestQueue /\ 
                             req.handledBy \in {success, failure}))
    
    (* Temporal: Rate limiting token bucket *)
    TokenBucketLogic == 
        /\ rateLimitState.tokens \in 0..MaxTokens
        /\ rateLimitState.lastRefill \in Nat
        /\ \A t \in Nat:
            IF t - rateLimitState.lastRefill >= RefillPeriod
            THEN rateLimitState.tokens' = Min(MaxTokens, 
                                              rateLimitState.tokens + RefillAmount)
            ELSE rateLimitState.tokens' = rateLimitState.tokens
    

    2. Model Checking & Verification Pipeline

    2.1 TLC Configuration (api.cfg)

    CONSTANTS 
        MaxUsers = 5
        MaxOrders = 10
        MaxTokens = 100
        RefillPeriod = 60
        RefillAmount = 10
    
    SYMMETRY 
        accounts \in Permutations(accounts)  \* Rename users
        resources \in Permutations(resources) \* Rename resource IDs
    
    INVARIANT 
        TypeInvariant      \* All variables have correct types
        ConsistencyInvariant
        NoDeadlocks
    
    PROPERTY 
        Safety
        Liveness
    
    POST_INIT_PREDICATE 
        DOMAIN accounts \subseteq {"admin", "user1", "user2"}
        Len(SequenceOfRequests) <= 20
    

    2.2 Counterexample Minimization

    # Run TLC with minimization
    tlc APISpec.tla -config api.cfg -depth 50 -minimize
    
    # Output minimized trace:
    # Found minimal counterexample with 7 steps
    # Step 0: Init
    # Step 1: POST /users (admin) -> 201
    # Step 2: GET /users/:id (user1) -> 403  \* VIOLATION!
    # ...
    

    2.3 Automated Counterexample Analysis

    # analyze_counterexample.py
    def analyze_violation(trace):
        if "NoPrivilegeEscalation" in trace.violated_property:
            # Extract: user1 accessed admin resource
            violating_step = find_step(trace, "GET /admin/resources")
            print(f"Unauthorized access at step {violating_step.step}")
            print(f"User: {violating_step.state.accounts[violating_step.request.user].role}")
            print(f"Required role: admin")
            
            # Suggest fix:
            print("Fix: Add RBAC check in AuthMiddleware before routing")
    

    3. Code Generation Hooks

    3.1 Specification-Driven Code Generation

    # codegen.py - Generate API skeletons from TLA+ spec
    from tla_parser import TLAParser
    
    class APICodeGenerator:
        def __init__(self, tla_spec):
            self.spec = TLAParser.parse(tla_spec)
            
        def generate_controller(self, action_name):
            """Generate controller method from TLA+ action"""
            action = self.spec.actions[action_name]
            
            template = f"""
            @ApiOperation(
                value="{action_name}",
                notes="Generated from TLA+ spec: {action.comment}"
            )
            public ResponseEntity<{action.response_type}> {action_name}(
                    @RequestBody {action.request_type} request) {{
                
                // Preconditions from TLA+ preconditions:
                {self.generate_assertions(action.preconditions)}
                
                // Business logic - implement state transition:
                {self.generate_transitions(action)}
                
                // Postconditions from TLA+:
                {self.generate_invariants(action.postconditions)}
                
                return ResponseEntity.status({action.http_status})
                                     .body(response);
            }}
            """
            return template
        
        def generate_assertions(self, preconditions):
            """Convert TLA+ preconditions to Java assertions"""
            assertions = []
            for pred in preconditions:
                java_pred = self.tla_to_java(pred)
                assertions.append(f'assert {java_pred} : "Precondition violated: {pred}";')
            return "\n        ".join(assertions)
    

    3.2 Generated Example (from CreateUser action)

    // Generated: UserController.java
    @RestController
    public class UserController {
        
        @PostMapping("/users")
        public ResponseEntity<UserResponse> createUser(
                @Valid @RequestBody CreateUserRequest request) {
            
            // TLA+ precondition: user.id not in DOMAIN resources
            assert !resourceStore.containsKey(request.getId()) : 
                "Duplicate resource ID";
            
            // TLA+ action: resources' = resources ∪ {request.id -> request}
            UserResource newUser = new UserResource(
                request.getId(), 
                request.getName(),
                request.getEmail()
            );
            resourceStore.put(request.getId(), newUser);
            
            // TLA+ postcondition: response.status = 201
            UserResponse response = new UserResponse(
                "User created", 
                request.getId(), 
                201
            );
            
            // TLA+ invariant: NoDuplicateResourceIDs preserved
            assert resourceStore.values().stream()
                .collect(Collectors.groupingBy(r -> r.getId()))
                .values().stream().allMatch(list -> list.size() == 1) :
                "Duplicate resource IDs detected";
            
            return ResponseEntity.status(201).body(response);
        }
    }
    

    4. Regression Governance Framework

    4.1 Governance Model

    (* Regression Spec *)
    RegressionGovernance == 
        /\ \A change \in CodeChanges:
            IF change.affects_spec THEN
                ReverifySpec(change)
            ELSE 
                IF change.affects_implementation THEN
                    RunGeneratedTests(change)
                ELSE
                    NoActionNeeded
        
        /\ \A bug_fix \in BugFixes:
            AddPropertyToSpec(bug_fix)
            /\ ReverifyAllProperties()
        
        /\ \A release \in Releases:
            IF release.contains_spec_changes THEN
                MajorVersionBump()
            ELSE IF release.contains_backwards_incompatible_changes THEN
                MinorVersionBump()
            ELSE
                PatchVersionBump()
    

    4.2 CI/CD Pipeline Integration

    # .github/workflows/api-verification.yml
    name: TLA+ Verification Pipeline
    
    on:
      pull_request:
        paths:
          - 'spec/**/*.tla'
          - 'src/**/*.java'
          - 'api-contracts/**/*.yaml'
    
    jobs:
      formal-verification:
        runs-on: ubuntu-latest
        steps:
          - name: Check TLA+ specification syntax
            run: tla2tools.jar APISpec.tla -cleanup
            
          - name: Run model checker
            run: |
              java -jar tlc2.jar -config api.cfg -workers auto
              if [ $? -ne 0 ]; then
                echo "::error::Model checking failed"
                exit 1
              fi
              
          - name: Check for new counterexamples
            run: |
              python scripts/check_counterexamples.py --minimize
              python scripts/generate_regression_tests.py --from-counterexamples
              
          - name: Generate API contracts
            run: |
              python codegen.py --spec APISpec.tla --output generated/
              
          - name: Compare generated vs implemented contracts
            run: |
              diff -r generated/contracts/ src/main/java/com/api/contracts/
              if [ $? -ne 0 ]; then
                echo "::error::API contracts mismatch!"
                echo "::warning::Regenerate with: python codegen.py --force"
                exit 1
              fi
    
      contract-testing:
        needs: formal-verification
        runs-on: ubuntu-latest
        steps:
          - name: Run property-based tests
            run: mvn test -Dtest=PropertyBasedTestSuite
            
          - name: Run minimal counterexample tests
            run: mvn test -Dtest=MinimalCounterexampleTestSuite
            
          - name: Generate coverage report
            run: |
              mvn jacoco:report
              python scripts/analyze_coverage.py \
                --spec APISpec.tla \
                --tests target/site/jacoco/jacoco.xml
    
      governance-check:
        needs: [formal-verification, contract-testing]
        runs-on: ubuntu-latest
        steps:
          - name: Verify version bump rules
            run: |
              python scripts/governance.py \
                --spec-version $(grep -oP 'API Version: \K[0-9.]+' APISpec.tla) \
                --changes $(git diff --name-only ${{ github.event.before }} ${{ github.sha }})
    

    4.3 Governance Rules (governance.py)

    def check_version_bump(spec_version, changes):
        """Semantic versioning based on change impact"""
        major_bump = False
        minor_bump = False
        patch_bump = False
        
        for change in changes:
            if change.affects_specification():
                major_bump = True  # Breaking spec change
            elif change.affects_api_contract():
                minor_bump = True  # New feature, backwards compatible
            elif change.affects_implementation_only():
                patch_bump = True  # Bug fix only
        
        if major_bump:
            return increment_major(spec_version)
        elif minor_bump:
            return increment_minor(spec_version)
        else:
            return increment_patch(spec_version)
    
    def check_spec_coverage(spec_properties, test_cases):
        """Ensure all properties have corresponding tests"""
        uncovered = set()
        for prop in spec_properties:
            if not any(prop in test for test in test_cases):
                uncovered.add(prop)
        
        if uncovered:
            raise GovernanceError(
                f"Properties without tests: {uncovered}. "
                "Run: python generate_tests.py --spec APISpec.tla --coverage-threshold 100"
            )
    

    5. Complete Workflow Execution

    5.1 Developer Workflow

    # 1. Developer modifies API behavior
    git checkout -b feature/new-endpoint
    # Edit APISpec.tla to add new action
    # Edit code to implement it
    
    # 2. Run local verification
    ./scripts/verify-local.sh
    # Output:
    # ✓ All invariants checked
    # ✓ All liveness properties verified
    # ✓ Generated 3 new test cases from counterexamples
    
    # 3. Commit with proper version bump
    git add APISpec.tla src/ generated/
    git commit -m "feat(api): add bulk user creation
    
    - Spec: Added BulkCreateUsers action with safety property
      NoBulkUserOverlimit
    - Generated: BulkUserController.java
    - Tests: BulkUserPropertyTest, BulkUserMinimalCounterexampleTest
    - Bumps: Minor version (0.2.0 -> 0.3.0)"
    
    # 4. CI runs full pipeline
    # - Model checking with 1000 states
    # - Counterexample minimization (if failures)
    # - Contract generation & comparison
    # - Regression test execution
    # - Governance validation
    
    # 5. PR merges only if:
    # ✓ Model checking passes
    # ✓ Generated contracts match implementation
    # ✓ All properties have test coverage > 90%
    # ✓ Version bump follows governance rules
    

    5.2 Registry & Tracking (spec-registry.json)

    {
      "specifications": {
        "APISpec": {
          "version": "1.2.0",
          "last_verified": "2024-01-15T10:30:00Z",
          "properties": {
            "safety": 24,
            "liveness": 8,
            "checked": 32,
            "coverage": 0.97
          },
          "counterexamples": {
            "total": 3,
            "open": 0,
            "fixed": 3
          },
          "generated_artifacts": {
            "contracts": "swagger-v3.json",
            "tests": "PropertyBasedTestSuite.java",
            "models": "tlc_model.cfg"
          }
        }
      },
      "governance": {
        "required_checks": ["model_check", "contract_match", "test_coverage"],
        "approval_required": ["major_version_bump", "spec_breaking_change"]
      }
    }
    

    6. Advanced Features

    6.1 Property Mapping to Test Types

    PROPERTY_TEST_MAPPING = {
        "NoDuplicateResourceIDs": [
            "PropertyBasedTest(test_resources_unique_ids)",
            "MinimalCounterexampleTest(test_duplicate_id_scenario)"
        ],
        "RequestsEventuallyProcessed": [
            "StressTest(test_request_throughput)",
            "LivenessTest(test_no_starvation)"
        ],
        "NoPrivilegeEscalation": [
            "SecurityTest(test_auth_bypass)",
            "FuzzTest(test_auth_edge_cases)"
        ]
    }
    

    6.2 Diff-Aware Model Checking

    (* Only check changed parts of spec *)
    ChangedModule == 
        IF SpecChanged("APISpec") THEN
            /\ FullSpecCheck
        ELSE 
            /\ CheckAffectedProperties(ChangedActions)
            /\ CheckAssociatedInvariants(ChangedVariables)
    

    7. Tooling Requirements

    # Dockerfile for reproducible environment
    FROM openjdk:17
    
    # Install TLA+ tools
    RUN wget https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar
    RUN wget https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tlc2.jar
    
    # Install codegen dependencies
    RUN pip install tla-plus-parser jinja2 pydantic
    
    # Install governance tools
    RUN pip install semantic-version pyyaml
    
    COPY scripts/ /usr/local/bin/
    COPY specs/ /specs/
    COPY templates/ /templates/
    
    WORKDIR /workspace
    CMD ["bash", "-c", "./scripts/full-workflow.sh"]
    

    8. Metrics & Monitoring

    Key Metrics Dashboard

    1. Specification Health

      • % Properties verified
      • Average model checking time
      • Counterexample rate
    2. Code Generation

      • Contract implementation match %
      • Generated test coverage
      • Stale generated code detection
    3. Governance Compliance

      • PRs passing all checks
      • Version bump accuracy
      • Spec-to-test coverage ratio
    4. Quality Gates

      gates:
        model_checking: 
            pass_if: "all_properties_verified"
            timeout: "30m"
        
        contract_match:
            pass_if: "generated_contracts == implemented_contracts"
            threshold: "100%"
        
        test_coverage:
            pass_if: "spec_property_coverage >= 95%"
            min_tests_per_property: 2
      

    Key Benefits

    1. Shift-Left Verification: Catch design flaws before implementation
    2. Living Documentation: TLA+ spec is the ultimate source of truth
    3. Regression Prevention: Counterexamples become permanent tests
    4. Governance Automation: Version bumps, approvals, audits
    5. Contract Consistency: Auto-generated vs implemented diff detection
    6. Knowledge Capture: Complex business logic formally specified

    Adoption Strategy

    1. Start Small: Pick 1-2 critical endpoints
    2. Dual Implementation: Run spec-based and traditional tests in parallel
    3. Gradual Expansion: Increase coverage to 20%, then 50%, then 100%
    4. Training: Developers learn TLA+ through practical examples
    5. Incentives: "Specification Complete" badges in PRs

    This workflow transforms TLA+ from a research tool into a production-grade API development framework, ensuring mathematical guarantees while maintaining practical engineering velocity.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.